@glassly/bluetooth-sdk 0.1.0-dev.100

package/ios/Source/DeviceManager.swift

@@ -0,0 +1,2054 @@
+//
+//  DeviceManager.swift
+//  Glassly_Manager
+//
+//  Created by Matthew Fosse on 3/5/25.
+//
+
+import AVFoundation
+import Combine
+import CoreBluetooth
+import Foundation
+import UIKit
+#if SWIFT_PACKAGE
+    import BluetoothSDKCoreObjC
+#endif
+
+struct ViewState {
+    var topText: String
+    var bottomText: String
+    var title: String
+    var layoutType: String
+    var text: String
+    var data: String?
+    var animationData: [String: Any]?
+    // Optional container position/size - used by bitmap_view and positioned_text (G2; ignored by others)
+    var bmpX: Int32? = nil
+    var bmpY: Int32? = nil
+    var bmpWidth: Int32? = nil
+    var bmpHeight: Int32? = nil
+    // Optional positioned_text border (used by G2; ignored by others)
+    var borderWidth: Int32? = nil
+    var borderRadius: Int32? = nil
+}
+
+@MainActor
+@objc(DeviceManager) class DeviceManager: NSObject {
+    static let shared = DeviceManager()
+
+    @objc static func getInstance() -> DeviceManager {
+        return DeviceManager.shared
+    }
+
+    // MARK: - Unique (iOS)
+
+    private var cancellables = Set<AnyCancellable>()
+    var sendStateWorkItem: DispatchWorkItem?
+    let sendStateQueue = DispatchQueue(label: "sendStateQueue", qos: .userInitiated)
+
+    /**
+     * Setup Bluetooth audio pairing after BLE connection is established
+     * Attempts to automatically activate Mentra Live as the system audio device
+     * If not paired yet, prompts user to pair in Settings
+     */
+    func setupAudioPairing(deviceName _: String) {
+        // Don't configure audio session - PhoneMic.swift handles that
+        // Just check if audio session supports Bluetooth (informational only)
+        if !AudioSessionMonitor.isAudioSessionConfigured() {
+            Bridge.log(
+                "Audio: Audio session not configured for Bluetooth yet - mic system will configure it when recording"
+            )
+        }
+
+        // Extract device ID pattern to match the specific device
+        // BLE name: "MENTRA_LIVE_BLE_ABC123"
+        // BT Classic could be: "MENTRA_LIVE_BLE_ABC123" or "MENTRA_LIVE_BT_ABC123"
+        // We need to match on the unique device ID part (e.g., "ABC123")
+        let audioDevicePattern = getAudioDevicePattern()
+
+        if audioDevicePattern.isEmpty || audioDevicePattern == DeviceTypes.SIMULATED {
+            Bridge.log("Audio: Device pattern is empty or simulated, returning")
+            return
+        }
+
+        // Check if device is paired (don't activate to preserve A2DP music playback)
+        let isPaired = AudioSessionMonitor.isDevicePaired(devicePattern: audioDevicePattern)
+
+        if isPaired {
+            // Device is paired! Don't activate it - let PhoneMic.swift activate when recording starts
+            Bridge.log("Audio: Mentra Live is paired (preserving A2DP for music)")
+            glassesBluetoothClassicConnected = true
+        } else {
+            glassesBluetoothClassicConnected = false
+            // Not found in availableInputs - not paired yet
+
+            // Start monitoring for when user pairs manually
+            AudioSessionMonitor.startMonitoring(devicePattern: audioDevicePattern) {
+                [weak self] (connected: Bool, _: String?) in
+                guard let self = self else { return }
+
+                if connected {
+                    Bridge.log("Audio: Device paired and connected")
+                    // Don't activate - let PhoneMic.swift handle that when recording starts
+                    self.glassesBluetoothClassicConnected = true
+                } else {
+                    Bridge.log("Audio: Device disconnected")
+                    self.glassesBluetoothClassicConnected = false
+                }
+            }
+        }
+    }
+
+    // MARK: - End Unique
+
+    // MARK: - Properties
+
+    var coreToken: String = ""
+    var coreTokenOwner: String = ""
+    var userEmail: String = ""
+    var sgc: SGCManager?
+    var controller: ControllerManager?
+
+    // state
+    // var lastStatusObj: [String: Any] = [:]
+
+    /// settings:
+    private var defaultWearable: String {
+        get { DeviceStore.shared.get("bluetooth", "default_wearable") as? String ?? "" }
+        set { DeviceStore.shared.apply("bluetooth", "default_wearable", newValue) }
+    }
+
+    private var pendingWearable: String {
+        get { DeviceStore.shared.get("bluetooth", "pending_wearable") as? String ?? "" }
+        set { DeviceStore.shared.apply("bluetooth", "pending_wearable", newValue) }
+    }
+
+    private var pendingDeviceName: String {
+        get { DeviceStore.shared.get("bluetooth", "pending_device_name") as? String ?? "" }
+        set { DeviceStore.shared.apply("bluetooth", "pending_device_name", newValue) }
+    }
+
+    private var pendingDeviceAddress: String {
+        get { DeviceStore.shared.get("bluetooth", "pending_device_address") as? String ?? "" }
+        set { DeviceStore.shared.apply("bluetooth", "pending_device_address", newValue) }
+    }
+
+    private var deviceName: String {
+        get { DeviceStore.shared.get("bluetooth", "device_name") as? String ?? "" }
+        set { DeviceStore.shared.apply("bluetooth", "device_name", newValue) }
+    }
+
+    private var deviceAddress: String {
+        get { DeviceStore.shared.get("bluetooth", "device_address") as? String ?? "" }
+        set { DeviceStore.shared.apply("bluetooth", "device_address", newValue) }
+    }
+
+    private var defaultController: String {
+        get { DeviceStore.shared.get("bluetooth", "default_controller") as? String ?? "" }
+        set { DeviceStore.shared.apply("bluetooth", "default_controller", newValue) }
+    }
+
+    private var pendingController: String {
+        get { DeviceStore.shared.get("bluetooth", "pending_controller") as? String ?? "" }
+        set { DeviceStore.shared.apply("bluetooth", "pending_controller", newValue) }
+    }
+
+    private var controllerDeviceName: String {
+        get { DeviceStore.shared.get("bluetooth", "controller_device_name") as? String ?? "" }
+        set { DeviceStore.shared.apply("bluetooth", "controller_device_name", newValue) }
+    }
+
+    private var screenDisabled: Bool {
+        get { DeviceStore.shared.get("bluetooth", "screen_disabled") as? Bool ?? false }
+        set { DeviceStore.shared.apply("bluetooth", "screen_disabled", newValue) }
+    }
+
+    private var preferredMic: String {
+        get { DeviceStore.shared.get("bluetooth", "preferred_mic") as? String ?? "auto" }
+        set { DeviceStore.shared.apply("bluetooth", "preferred_mic", newValue) }
+    }
+
+    private var autoBrightness: Bool {
+        get { DeviceStore.shared.get("bluetooth", "auto_brightness") as? Bool ?? true }
+        set { DeviceStore.shared.apply("bluetooth", "auto_brightness", newValue) }
+    }
+
+    private var brightness: Int {
+        get { DeviceStore.shared.get("bluetooth", "brightness") as? Int ?? 50 }
+        set { DeviceStore.shared.apply("bluetooth", "brightness", newValue) }
+    }
+
+    private var headUpAngle: Int {
+        get { DeviceStore.shared.get("bluetooth", "head_up_angle") as? Int ?? 30 }
+        set { DeviceStore.shared.apply("bluetooth", "head_up_angle", newValue) }
+    }
+
+    private var sensingEnabled: Bool {
+        get { DeviceStore.shared.get("bluetooth", "sensing_enabled") as? Bool ?? true }
+        set { DeviceStore.shared.apply("bluetooth", "sensing_enabled", newValue) }
+    }
+
+    /// Phone-side VAD gating switch. Default is OFF (VAD runs) so that the
+    /// coordinator can drive per-utterance offline/online STT switching from
+    /// `vad_status` events. Set to `true` only as an emergency kill-switch.
+    private var bypassVad: Bool {
+        get { DeviceStore.shared.get("bluetooth", "bypass_vad") as? Bool ?? false }
+        set { DeviceStore.shared.apply("bluetooth", "bypass_vad", newValue) }
+    }
+
+    private var localSttFallbackActive: Bool {
+        get { DeviceStore.shared.get("bluetooth", "local_stt_fallback_active") as? Bool ?? false }
+        set { DeviceStore.shared.apply("bluetooth", "local_stt_fallback_active", newValue) }
+    }
+
+    private var shouldSendPcm: Bool {
+        get { DeviceStore.shared.get("bluetooth", "should_send_pcm") as? Bool ?? false }
+        set { DeviceStore.shared.apply("bluetooth", "should_send_pcm", newValue) }
+    }
+
+    private var shouldSendLc3: Bool {
+        get { DeviceStore.shared.get("bluetooth", "should_send_lc3") as? Bool ?? false }
+        set { DeviceStore.shared.apply("bluetooth", "should_send_lc3", newValue) }
+    }
+
+    private var shouldSendTranscript: Bool {
+        get { DeviceStore.shared.get("bluetooth", "should_send_transcript") as? Bool ?? false }
+        set { DeviceStore.shared.apply("bluetooth", "should_send_transcript", newValue) }
+    }
+
+    // state:
+
+    private var searching: Bool {
+        get { DeviceStore.shared.get("bluetooth", "searching") as? Bool ?? false }
+        set { DeviceStore.shared.apply("bluetooth", "searching", newValue) }
+    }
+
+    private var searchingController: Bool {
+        get { DeviceStore.shared.get("bluetooth", "searchingController") as? Bool ?? false }
+        set { DeviceStore.shared.apply("bluetooth", "searchingController", newValue) }
+    }
+
+    private var glassesBluetoothClassicConnected: Bool {
+        get { DeviceStore.shared.get("glasses", "bluetoothClassicConnected") as? Bool ?? false }
+        set { DeviceStore.shared.apply("glasses", "bluetoothClassicConnected", newValue) }
+    }
+
+    private var micRanking: [String] {
+        get {
+            DeviceStore.shared.get("bluetooth", "micRanking") as? [String] ?? MicMap.map["auto"]!
+        }
+        set { DeviceStore.shared.apply("bluetooth", "micRanking", newValue) }
+    }
+
+    private var shouldSendBootingMessage: Bool {
+        get { DeviceStore.shared.get("bluetooth", "shouldSendBootingMessage") as? Bool ?? true }
+        set { DeviceStore.shared.apply("bluetooth", "shouldSendBootingMessage", newValue) }
+    }
+
+    private var lastSystemTimeSyncConnectionKey = ""
+    private var pendingSystemTimeSync: DispatchWorkItem?
+    private var systemTimeSyncGeneration = 0
+
+    private var systemMicUnavailable: Bool {
+        get { DeviceStore.shared.get("bluetooth", "systemMicUnavailable") as? Bool ?? false }
+        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) }
+    }
+
+    private var currentMic: String {
+        get { DeviceStore.shared.get("bluetooth", "currentMic") as? String ?? "" }
+        set { DeviceStore.shared.apply("bluetooth", "currentMic", newValue) }
+    }
+
+    private var searchResults: [[String: Any]] {
+        get { DeviceStore.shared.get("bluetooth", "searchResults") as? [[String: Any]] ?? [] }
+        set { DeviceStore.shared.apply("bluetooth", "searchResults", newValue) }
+    }
+
+    private var wifiScanResults: [[String: Any]] {
+        get { DeviceStore.shared.get("bluetooth", "wifiScanResults") as? [[String: Any]] ?? [] }
+        set { DeviceStore.shared.apply("bluetooth", "wifiScanResults", newValue) }
+    }
+
+    private var lastLog: [String] {
+        get { DeviceStore.shared.get("bluetooth", "lastLog") as? [String] ?? [] }
+        set { DeviceStore.shared.apply("bluetooth", "lastLog", newValue) }
+    }
+
+    private var otherBtConnected: Bool {
+        get { DeviceStore.shared.get("bluetooth", "otherBtConnected") as? Bool ?? false }
+        set { DeviceStore.shared.apply("bluetooth", "otherBtConnected", newValue) }
+    }
+
+    /// LC3 Audio Encoding
+    /// Audio output format enum
+    enum AudioOutputFormat { case lc3, pcm }
+    /// Canonical LC3 config: 16kHz sample rate, 10ms frame duration
+    /// Frame size is configurable: 20 bytes (16kbps), 40 bytes (32kbps), 60 bytes (48kbps)
+    /// Persistent LC3 converter for encoding/decoding
+    var lc3Converter: PcmConverter?
+    /// Audio output format - defaults to LC3 for bandwidth savings
+    private var audioOutputFormat: AudioOutputFormat = .lc3
+    /// Last time we received an LC3 frame from the glasses (used by the mic
+    /// inactivity watchdog).
+    private var lastLc3Event: Date?
+    private var sequenceGapEvents: Int64 = 0
+    private var decodeFailures: Int64 = 0
+    private var lastLc3ReceivedAt: Int64?
+    private var lastPcmProducedAt: Int64?
+    private var lastLc3Sequence: Int?
+    private var micReinitTimer: Timer?
+
+    // STT:
+    #if !SWIFT_PACKAGE || GLASSLY_FEATURE_LOCAL_STT
+        private var transcriber: SherpaOnnxTranscriber?
+    #endif
+
+    /// Single retained display state. The JS engine owns view switching
+    /// (dashboard vs main); native just paints and repaints the last frame.
+    var viewState = ViewState(
+        topText: " ", bottomText: " ", title: " ", layoutType: "text_wall", text: ""
+    )
+
+    /// Retained SceneFrame. When it holds a scene, viewState carries a "scene"
+    /// sentinel so sendCurrentState routes here. Holding the WHOLE frame keeps
+    /// native re-dispatch coherent (nav exit re-applies a complete scene).
+    var sceneState: SceneFrame?
+
+    override init() {
+        Bridge.log("MAN: init()")
+        super.init()
+
+        // 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
+
+        // Initialize persistent LC3 converter for unified audio encoding
+        lc3Converter = PcmConverter()
+        Bridge.log("LC3 converter initialized for unified audio encoding")
+
+        DispatchQueue.main.async { [weak self] in
+            guard let self = self else { return }
+            self.micReinitTimer = Timer.scheduledTimer(
+                withTimeInterval: 10.0, repeats: true
+            ) { [weak self] _ in
+                self?.checkAndReinitGlassesMic()
+            }
+        }
+    }
+
+    // MARK: - AUX Voice Data Handling
+
+    private func convertAndSendMicLc3(_ pcmData: Data) {
+        guard let lc3Converter = lc3Converter else {
+            Bridge.log("MAN: ERROR - LC3 converter not initialized but format is LC3")
+            return
+        }
+        // Values set from the JS bridge arrive (and persist) as Double, so a
+        // force-cast to Int aborts on the mic tap thread. Coerce via NSNumber
+        // like the Android side does with `as Number`.
+        let frameSize = (DeviceStore.shared.get("bluetooth", "lc3_frame_size") as? NSNumber)?.intValue ?? 60
+        let lc3Data = lc3Converter.encode(pcmData, frameSize: frameSize) as Data
+        guard lc3Data.count > 0 else {
+            Bridge.log("MAN: ERROR - LC3 encoding returned empty data")
+            return
+        }
+        Bridge.sendMicLc3(lc3Data)
+    }
+
+    private func handleSendingPcm(_ pcmData: Data) {
+        // Bridge.log("MAN: handleSendingPcm() shouldSendPcm: \(shouldSendPcm) shouldSendLc3: \(shouldSendLc3)")
+        if shouldSendPcm {
+            Bridge.sendMicPcm(pcmData)
+        }
+        if shouldSendLc3 {
+            convertAndSendMicLc3(pcmData)
+        }
+    }
+
+    /**
+     * Handle raw LC3 audio data from glasses.
+     * Decodes the glasses LC3 to PCM, then forwards to handlePcm for processing.
+     * This matches Android behavior - glasses forward raw LC3, DeviceManager handles encoding.
+     */
+    func handleGlassesMicData(_ lc3Data: Data, _ frameSize: Int = 20, sequenceNumber: Int? = nil) {
+        recordLc3Packet(sequenceNumber: sequenceNumber)
+        guard let lc3Converter = lc3Converter else {
+            Bridge.log("MAN: LC3 converter not initialized")
+            recordMicDecodeFailure()
+            return
+        }
+
+        guard lc3Data.count > 2 else {
+            Bridge.log("MAN: Received invalid LC3 data size: \(lc3Data.count)")
+            recordMicDecodeFailure()
+            return
+        }
+
+        let pcmData = lc3Converter.decode(lc3Data, frameSize: frameSize) as Data
+        guard pcmData.count > 0 else {
+            Bridge.log("MAN: Failed to decode glasses LC3 audio")
+            recordMicDecodeFailure()
+            return
+        }
+        // Forward to handlePcm which handles SDK audio events and encoding.
+        lastPcmProducedAt = nowMs()
+        handlePcm(pcmData)
+    }
+
+    func reportGlassesAudioActivity() {
+        lastLc3Event = Date()
+        lastPcmProducedAt = nowMs()
+    }
+
+    private func micHealth() -> MicHealth {
+        MicHealth(
+            sequenceGapEvents: sequenceGapEvents,
+            decodeFailures: decodeFailures,
+            lastLc3ReceivedAt: lastLc3ReceivedAt,
+            lastPcmProducedAt: lastPcmProducedAt
+        )
+    }
+
+    func resetMicSequenceBaseline() {
+        lastLc3Sequence = nil
+    }
+
+    private func nowMs() -> Int64 {
+        Int64(Date().timeIntervalSince1970 * 1000)
+    }
+
+    private func resetMicHealth() {
+        sequenceGapEvents = 0
+        decodeFailures = 0
+        lastLc3ReceivedAt = nil
+        lastPcmProducedAt = nil
+        lastLc3Sequence = nil
+        lastLc3Event = nil
+    }
+
+    private func recordLc3Packet(sequenceNumber: Int?) {
+        let receivedAt = nowMs()
+        lastLc3ReceivedAt = receivedAt
+        lastLc3Event = Date()
+        var hasGap = false
+        if let sequenceNumber {
+            let normalized = sequenceNumber & 0xFF
+            if let previous = lastLc3Sequence {
+                let expected = (previous + 1) & 0xFF
+                if normalized != expected {
+                    hasGap = true
+                    sequenceGapEvents += 1
+                    Bridge.log("MAN: LC3 packet sequence mismatch. Expected: \(expected), Got: \(normalized)")
+                }
+            }
+            lastLc3Sequence = normalized
+        }
+        if hasGap {
+            Bridge.sendMicHealth(micHealth(), reason: "sequence_gap")
+        }
+    }
+
+    private func recordMicDecodeFailure() {
+        decodeFailures += 1
+        Bridge.sendMicHealth(micHealth(), reason: "decode_failure")
+    }
+
+    func handlePcm(_ pcmData: Data) {
+        handleSendingPcm(pcmData)
+
+        // Speaker identification / enrollment tap — no-op unless enabled.
+        SpeakerIdEngine.shared.acceptAudio(pcm16le: pcmData)
+
+        // Send PCM to local transcriber.
+        #if !SWIFT_PACKAGE || GLASSLY_FEATURE_LOCAL_STT
+            if shouldSendTranscript || localSttFallbackActive {
+                transcriber?.acceptAudio(pcm16le: pcmData)
+            }
+        #endif
+    }
+
+    func updateMicState() {
+        // go through the micRanking and find the first mic that is available:
+        var micUsed = ""
+
+        // allow the sgc to make changes to the micRanking:
+        micRanking = sgc?.sortMicRanking(list: micRanking) ?? micRanking
+        // Bridge.log("MAN: updateMicState() micRanking: \(micRanking)")
+
+        var phoneMicUnavailable = systemMicUnavailable
+
+        let appState = UIApplication.shared.applicationState
+        if appState == .background {
+            // Bridge.log("App is in background - onboard mic unavailable to start!")
+            phoneMicUnavailable = true
+        }
+
+        if micEnabled {
+            for micMode in micRanking {
+                if micMode == MicTypes.PHONE_INTERNAL || micMode == MicTypes.BLUETOOTH_CLASSIC
+                    || micMode == MicTypes.BLUETOOTH
+                {
+                    if PhoneMic.shared.isRecordingWithMode(micMode) {
+                        micUsed = micMode
+                        break
+                    }
+
+                    if phoneMicUnavailable {
+                        continue
+                    }
+
+                    // if the phone mic is not recording, start recording:
+                    let success = PhoneMic.shared.startMode(micMode)
+                    Bridge.log("MAN: starting mic mode: \(micMode) -> \(success)")
+                    if success {
+                        micUsed = micMode
+                        break
+                    }
+                }
+
+                if micMode == MicTypes.GLASSES_CUSTOM {
+                    // Bridge.log(
+                    //     "MAN: glasses custom mic found - hasMic: \(sgc?.hasMic ?? false), micEnabled: \(sgc?.micEnabled ?? false)"
+                    // )
+                    // if the glasses has a mic that's already on, mark it as used and break:
+                    if sgc?.hasMic ?? false {
+                        // enable the mic if it's not already on:
+                        if sgc?.micEnabled == false {
+                            sgc?.setMicEnabled(true)
+                            micUsed = micMode
+                            break
+                        } else {
+                            // the mic is already on, mark it as used and break:
+                            micUsed = micMode
+                            break
+                        }
+                    }
+                    // if the glasses doesn't have a mic, continue to the next mic:
+                    continue
+                }
+            }
+        }
+
+        currentMic = micUsed
+
+        // log if no mic was found:
+        if micUsed == "" && micEnabled {
+            Bridge.log("MAN: No available mic found!")
+            return
+        }
+
+        // go through and disable all mics after the first used one:
+        var allMics = micRanking
+        // add any missing mics to the list:
+        for micMode in MicMap.map["auto"]! {
+            if !allMics.contains(micMode) {
+                allMics.append(micMode)
+            }
+        }
+
+        for micMode in allMics {
+            if micMode == micUsed {
+                continue
+            }
+
+            if micMode == MicTypes.PHONE_INTERNAL || micMode == MicTypes.BLUETOOTH_CLASSIC
+                || micMode == MicTypes.BLUETOOTH
+            {
+                PhoneMic.shared.stopMode(micMode)
+            }
+
+            if micMode == MicTypes.GLASSES_CUSTOM && sgc?.hasMic == true && sgc?.micEnabled == true {
+                sgc?.setMicEnabled(false)
+            }
+        }
+    }
+
+    func setOnboardMicEnabled(_ isEnabled: Bool) {
+        Task {
+            if isEnabled {
+                // Check only; never request from Swift. The React Native UI flow
+                // owns the mic permission prompt.
+                if !(PhoneMic.shared.checkPermissions()) {
+                    Bridge.log("Microphone permissions not granted. Cannot enable microphone.")
+                    return
+                }
+
+                let success = PhoneMic.shared.startRecording()
+                if !success {
+                    // fallback to glasses mic if possible:
+                    if sgc?.hasMic ?? false {
+                        await sgc?.setMicEnabled(true)
+                    }
+                }
+            } else {
+                PhoneMic.shared.stopRecording()
+            }
+        }
+    }
+
+    // MARK: - Glasses Commands
+
+    private func playStartupSequence() {
+        Bridge.log("MAN: playStartupSequence()")
+        // Arrow frames for the animation
+        let arrowFrames = ["↑", "↗", "↑", "↖"]
+
+        let delay = 0.25 // Frame delay in seconds
+        let totalCycles = 2 // Number of animation cycles
+
+        // Variables to track animation state
+        var frameIndex = 0
+        var cycles = 0
+
+        // Create a dispatch queue for the animation
+        let animationQueue = DispatchQueue.global(qos: .userInteractive)
+
+        /// Function to display the current animation frame
+        func displayFrame() {
+            // Check if we've completed all cycles
+            if cycles >= totalCycles {
+                // End animation with final message
+                Task { await sgc?.sendTextWall("                  /// Glassly connected \\\\\\") }
+                animationQueue.asyncAfter(deadline: .now() + 1.0) {
+                    self.sgc?.clearDisplay()
+                }
+                return
+            }
+
+            // Display current animation frame
+            let frameText =
+                "                    \(arrowFrames[frameIndex]) Glassly Booting \(arrowFrames[frameIndex])"
+            Task { await sgc?.sendTextWall(frameText) }
+
+            // Move to next frame
+            frameIndex = (frameIndex + 1) % arrowFrames.count
+
+            // Count completed cycles
+            if frameIndex == 0 {
+                cycles += 1
+            }
+
+            // Schedule next frame
+            animationQueue.asyncAfter(deadline: .now() + delay) {
+                displayFrame()
+            }
+        }
+
+        // Start the animation after a short initial delay
+        animationQueue.asyncAfter(deadline: .now() + 0.35) {
+            displayFrame()
+        }
+    }
+
+    // MARK: - Auxiliary Commands
+
+    func initSGC(_ wearable: String) {
+        Bridge.log("Initializing manager for wearable: \(wearable)")
+        if sgc != nil && sgc?.type != wearable {
+            Bridge.log("MAN: Manager already initialized, cleaning up previous sgc")
+            sgc?.cleanup()
+            sgc = nil
+            resetSystemTimeSync()
+        }
+
+        if sgc != nil {
+            Bridge.log("MAN: SGC already initialized")
+            return
+        }
+        if wearable.contains(DeviceTypes.SIMULATED) {
+            sgc = Simulated()
+        } else if wearable.contains(DeviceTypes.G1) {
+            sgc = G1()
+        } else if wearable.contains(DeviceTypes.G2) {
+            sgc = G2()
+        } else if wearable.contains(DeviceTypes.LIVE) {
+            sgc = MentraLive()
+        } else if wearable.contains(DeviceTypes.NIMO) {
+            sgc = Nimo()
+        } else if wearable.contains(DeviceTypes.AR99) {
+            sgc = Ar99()
+        } else if wearable.contains(DeviceTypes.FRAME) {
+            // sgc = FrameManager()
+        }
+        #if !SWIFT_PACKAGE || GLASSLY_FEATURE_NEX
+            if sgc == nil && wearable.contains(DeviceTypes.NEX) {
+                sgc = MentraNexSGC.getInstance()
+            }
+        #endif
+        #if !SWIFT_PACKAGE || GLASSLY_FEATURE_VUZIX
+            if sgc == nil {
+                if wearable.contains(DeviceTypes.MACH1) {
+                    sgc = Mach1()
+                } else if wearable.contains(DeviceTypes.Z100) {
+                    sgc = Mach1() // Z100 uses same hardware/SDK as Mach1
+                    sgc?.type = DeviceTypes.Z100 // Override type to Z100
+                }
+            }
+        #endif
+        // update device model:
+        DeviceStore.shared.apply("glasses", "deviceModel", sgc?.type ?? "")
+    }
+
+    func initController(_ controllerModel: String) {
+        Bridge.log("MAN: Initializing controller: \(controllerModel)")
+        if controller != nil && controller?.type != controllerModel {
+            Bridge.log("MAN: Controller already initialized, cleaning up previous controller")
+            controller?.cleanup()
+            controller = nil
+        }
+
+        if controller != nil {
+            Bridge.log("MAN: Controller already initialized")
+            return
+        }
+
+        if controllerModel == ControllerTypes.R1 {
+            controller = R1()
+        }
+    }
+
+    func sendCurrentState() {
+        if screenDisabled {
+            return
+        }
+        if sgc?.navigationModeActive == true {
+            // The glasses' native nav UI owns the display. View/scene state is
+            // still retained above; the SGC triggers a repaint when nav exits.
+            return
+        }
+
+        Task {
+            let currentViewState = self.viewState
+
+            if sgc?.type.contains(DeviceTypes.SIMULATED) ?? true {
+                // dont send the event to glasses that aren't there:
+                return
+            }
+
+            var fullyBooted = sgc?.fullyBooted ?? false
+            if !fullyBooted {
+                return
+            }
+
+            // cancel any pending clear display work item:
+            sendStateWorkItem?.cancel()
+
+            let layoutType = currentViewState.layoutType
+            switch layoutType {
+            case "text_wall":
+                let text = parsePlaceholders(currentViewState.text)
+                await sgc?.sendTextWall(text)
+            case "double_text_wall":
+                let topText = parsePlaceholders(currentViewState.topText)
+                let bottomText = parsePlaceholders(currentViewState.bottomText)
+                await sgc?.sendDoubleTextWall(topText, bottomText)
+            case "reference_card":
+                let title = parsePlaceholders(currentViewState.title)
+                let text = parsePlaceholders(currentViewState.text)
+                await sgc?.sendTextWall(title + "\n\n" + text)
+            case "bitmap_view":
+                // Bridge.log("MAN: Processing bitmap_view layout")
+                guard let data = currentViewState.data else {
+                    Bridge.log("MAN: ERROR: bitmap_view missing data field")
+                    return
+                }
+                // Bridge.log("MAN: Processing bitmap_view with base64 data, length: \(data.count)")
+                await sgc?.displayBitmap(
+                    base64ImageData: data,
+                    x: currentViewState.bmpX,
+                    y: currentViewState.bmpY,
+                    width: currentViewState.bmpWidth,
+                    height: currentViewState.bmpHeight
+                )
+            case "positioned_text":
+                let text = parsePlaceholders(currentViewState.text)
+                Bridge.log(
+                    "MAN: positioned_text -> text='\(text)' rect=\(currentViewState.bmpX ?? 0),\(currentViewState.bmpY ?? 0) \(currentViewState.bmpWidth ?? 576)x\(currentViewState.bmpHeight ?? 288)"
+                )
+                await sgc?.sendPositionedText(
+                    text,
+                    x: currentViewState.bmpX ?? 0,
+                    y: currentViewState.bmpY ?? 0,
+                    width: currentViewState.bmpWidth ?? 576,
+                    height: currentViewState.bmpHeight ?? 288,
+                    borderWidth: currentViewState.borderWidth ?? 0,
+                    borderRadius: currentViewState.borderRadius ?? 0
+                )
+            case "scene":
+                if let frame = self.sceneState {
+                    await sgc?.applySceneFrame(frame)
+                }
+            case "clear_view":
+                sgc?.clearDisplay()
+            default:
+                Bridge.log("UNHANDLED LAYOUT_TYPE \(layoutType)")
+            }
+        }
+    }
+
+    // MARK: - Native navigation (glasses-rendered nav UI, e.g. G2 service 0x08)
+
+    func navigationModeStart() {
+        sgc?.enterNavigationMode()
+    }
+
+    /// Exit the native nav UI. The SGC repaints the retained view state itself
+    /// once the firmware hands the screen back (see G2.exitNavigationMode).
+    func navigationModeStop(arrived: Bool) {
+        sgc?.exitNavigationMode(arrived: arrived)
+    }
+
+    func navigationUpdateInfo(_ params: [String: Any]) {
+        sgc?.sendNavigationInfo(
+            directionIcon: (params["directionIcon"] as? NSNumber)?.int32Value ?? 0,
+            distance: params["distance"] as? String ?? "",
+            roadName: params["roadName"] as? String ?? "",
+            spendTime: params["spendTime"] as? String ?? "",
+            remainDistance: params["remainDistance"] as? String ?? "",
+            etaTime: params["etaTime"] as? String ?? "",
+            speed: params["speed"] as? String ?? ""
+        )
+    }
+
+    func navigationMiniMap(_ params: [String: Any]) {
+        guard let data = params["data"] as? String else {
+            Bridge.log("MAN: navigationMiniMap missing data field")
+            return
+        }
+        sgc?.sendNavigationMiniMap(
+            base64ImageData: data,
+            rotationDeg: (params["rotationDeg"] as? NSNumber)?.int32Value ?? 0,
+            borderEnabled: (params["border"] as? Bool) ?? true
+        )
+    }
+
+    func navigationOverviewMap(_ params: [String: Any]) {
+        guard let data = params["data"] as? String else {
+            Bridge.log("MAN: navigationOverviewMap missing data field")
+            return
+        }
+        sgc?.sendNavigationOverviewMap(base64ImageData: data)
+    }
+
+    func parsePlaceholders(_ text: String) -> String {
+        guard text.contains("$") else { return text }
+
+        let dateFormatter = DateFormatter()
+        dateFormatter.dateFormat = "M/dd, h:mm"
+        let formattedDate = dateFormatter.string(from: Date())
+
+        // 12-hour time format (with leading zeros for hours)
+        let time12Format = DateFormatter()
+        time12Format.dateFormat = "hh:mm"
+        let time12 = time12Format.string(from: Date())
+
+        // 24-hour time format
+        let time24Format = DateFormatter()
+        time24Format.dateFormat = "HH:mm"
+        let time24 = time24Format.string(from: Date())
+
+        // Current date with format MM/dd
+        let dateFormat = DateFormatter()
+        dateFormat.dateFormat = "MM/dd"
+        let currentDate = dateFormat.string(from: Date())
+
+        var placeholders: [String: String] = [:]
+        placeholders["$no_datetime$"] = formattedDate
+        placeholders["$DATE$"] = currentDate
+        placeholders["$TIME12$"] = time12
+        placeholders["$TIME24$"] = time24
+
+        if (sgc?.batteryLevel ?? -1) == -1 {
+            placeholders["$GBATT$"] = ""
+        } else {
+            placeholders["$GBATT$"] = "\(sgc!.batteryLevel)%"
+        }
+
+        // TODO: config: derive real connection status instead of hardcoding.
+        placeholders["$CONNECTION_STATUS$"] = "Connected"
+
+        var result = text
+        for (key, value) in placeholders {
+            result = result.replacingOccurrences(of: key, with: value)
+        }
+
+        return result
+    }
+
+    private func checkAndReinitGlassesMic() {
+        // Re-arm from app INTENT, not glasses STATE: a firmware page kill clears
+        // glasses/micEnabled to false while the app still wants the mic, which used to
+        // make this watchdog return early and strand the mic. micEnabled + currentMic
+        // are DeviceManager-owned intent and survive page kills. If the app wants the
+        // glasses mic on and we haven't seen an lc3 event in >5s, reinitialize it.
+        let glassesConnected = DeviceStore.shared.get("glasses", "connected") as? Bool ?? false
+        if !micEnabled || !glassesConnected {
+            return
+        }
+
+        // Intent is on but no mic was ever selected — updateMicState() ran at a moment
+        // when nothing was available (app backgrounded, glasses mid-reconnect) and set
+        // currentMic to "". Retry selection instead of staying stranded.
+        if currentMic.isEmpty {
+            Bridge.log("MAN: mic intent on but no mic selected — retrying mic selection")
+            updateMicState()
+            return
+        }
+
+        if currentMic != MicTypes.GLASSES_CUSTOM {
+            return
+        }
+
+        if sgc?.isMicSuspendedForAudio == true {
+            Bridge.log("MAN: Glasses mic intentionally suspended for phone audio; skipping mic recovery")
+            return
+        }
+
+        if PhoneAudioMonitor.getInstance().isOwnAppAudioPlaying() {
+            Bridge.log("MAN: Glassly audio is playing; skipping glasses mic recovery")
+            return
+        }
+
+        // When no frame has ever been received, treat elapsed as "forever" so we
+        // actually attempt recovery (was `?? Date()` before, which made elapsed 0 and
+        // turned the watchdog into a no-op for a mic that never started at all).
+        let timeSinceLastLc3Event = Date().timeIntervalSince(lastLc3Event ?? .distantPast)
+        if timeSinceLastLc3Event > 5 {
+            Bridge.log("MAN: No audio activity in the last 5 seconds from glasses, reinitializing glasses mic")
+            sgc?.setMicEnabled(true)
+        }
+    }
+
+    func getAudioDevicePattern() -> String {
+        let audioDevicePattern: String
+        if let idRange = deviceName.range(of: "_BLE_", options: .caseInsensitive) {
+            // Extract the ID after "_BLE_" (e.g., "ABC123")
+            audioDevicePattern = String(deviceName[idRange.upperBound...])
+        } else if let idRange = deviceName.range(of: "_BT_", options: .caseInsensitive) {
+            // Extract the ID after "_BT_"
+            audioDevicePattern = String(deviceName[idRange.upperBound...])
+        } else {
+            // Fallback: use the full device name
+            audioDevicePattern = deviceName
+        }
+        return audioDevicePattern
+    }
+
+    func checkCurrentAudioDevice() {
+        let audioDevicePattern = getAudioDevicePattern()
+        Bridge.log("MAN: checkCurrentAudioDevice: audioDevicePattern: \(audioDevicePattern)")
+
+        if audioDevicePattern.isEmpty || audioDevicePattern == DeviceTypes.SIMULATED {
+            glassesBluetoothClassicConnected = false
+            Bridge.log("MAN: Audio device pattern is empty or simulated, returning")
+            return
+        }
+
+        // check if the device disconnected:
+        let isConnected = AudioSessionMonitor.isAudioDeviceConnected(
+            devicePattern: audioDevicePattern
+        )
+
+        if !isConnected {
+            Bridge.log("MAN: Device '\(deviceName)' disconnected")
+            glassesBluetoothClassicConnected = false
+
+            let isOtherDeviceConnected = AudioSessionMonitor.isOtherAudioDeviceConnected(
+                devicePattern: audioDevicePattern
+            )
+            if isOtherDeviceConnected {
+                Bridge.log("MAN: Other device connected, returning")
+                otherBtConnected = true
+            }
+            return
+        }
+
+        let isPaired = AudioSessionMonitor.isDevicePaired(devicePattern: audioDevicePattern)
+        if isPaired {
+            let session = AVAudioSession.sharedInstance()
+            let deviceName = session.availableInputs?.first(where: {
+                $0.portName.localizedCaseInsensitiveContains(audioDevicePattern)
+            })?.portName
+            Bridge.log("MAN: Successfully detected newly paired device '\(deviceName)'")
+            glassesBluetoothClassicConnected = true
+        } else {
+            glassesBluetoothClassicConnected = false
+        }
+    }
+
+    func onRouteChange(
+        reason: AVAudioSession.RouteChangeReason, availableInputs: [AVAudioSessionPortDescription]
+    ) {
+        Bridge.log("MAN: onRouteChange: reason: \(reason)")
+        Bridge.log("MAN: onRouteChange: inputs: \(availableInputs)")
+
+        // check if our deviceName is connected:
+        // (return if deviceName is empty):
+        if deviceName.isEmpty {
+            Bridge.log("MAN: Device name is empty, returning")
+            return
+        }
+
+        // Add small delay to let iOS populate availableInputs
+        DispatchQueue.main.asyncAfter(deadline: .now() + 0.2) { [weak self] in
+            guard let self = self else { return }
+            checkCurrentAudioDevice()
+        }
+
+        updateMicState()
+    }
+
+    func onInterruption(began: Bool) {
+        Bridge.log("MAN: Interruption: \(began)")
+        systemMicUnavailable = began
+        updateMicState()
+    }
+
+    func restartTranscriber() {
+        #if !SWIFT_PACKAGE || GLASSLY_FEATURE_LOCAL_STT
+            Bridge.log("MAN: Restarting SherpaOnnxTranscriber via command")
+            transcriber?.restart()
+        #else
+            Bridge.log("MAN: Local STT is not included in this SwiftPM build")
+        #endif
+    }
+
+    // MARK: - connection state management
+
+    func handleDeviceReady() {
+        guard let sgc else {
+            Bridge.log("MAN: SGC is nil, returning")
+            return
+        }
+        Bridge.log("MAN: handleDeviceReady(): \(sgc.type)")
+        resetMicHealth()
+
+        if !pendingDeviceName.isEmpty {
+            deviceName = pendingDeviceName
+        }
+        if !pendingDeviceAddress.isEmpty {
+            deviceAddress = pendingDeviceAddress
+        }
+        clearPendingConnection()
+        defaultWearable = sgc.type
+        searching = false
+
+        let connectionKey = "\(sgc.type):\(deviceName)"
+        syncSystemTimeOnceForConnection(sgc, connectionKey: connectionKey)
+
+        // re-apply display height/depth after reconnection
+        DispatchQueue.main.asyncAfter(deadline: .now() + 2) { [weak self] in
+            // Re-read the current sgc rather than capturing the connect-time instance: the user may
+            // have disconnected or switched glasses during the 2s window, and we must not push to a
+            // stale/torn-down connection.
+            guard let sgc = self?.sgc else { return }
+            let h = DeviceStore.shared.get("bluetooth", "dashboard_height") as? Int ?? 4
+            // Fall back to the canonical default (2), matching DeviceStore, not 1.
+            let rawDepth = DeviceStore.shared.get("bluetooth", "dashboard_depth") as? Int ?? 2
+            let d = min(max(rawDepth, 1), 4)
+            sgc.setDashboardPosition(h, d)
+        }
+
+        // Show welcome message on first connect for all display glasses
+        if shouldSendBootingMessage {
+            Task {
+                // Wait until stock-vs-CFW is known: a banner drawn down the stock
+                // path with the clear routed down the CFW path never leaves the
+                // glass (the clear can't reach the stock text container).
+                await sgc.awaitFirmwareClassification()
+                await sgc.sendTextWall("// Glassly connected")
+                try? await Task.sleep(nanoseconds: 3_000_000_000)
+                sgc.clearDisplay()
+            }
+            shouldSendBootingMessage = false
+        }
+
+        // Call device-specific setup handlers
+        if defaultWearable.contains(DeviceTypes.G1) {
+            handleG1Ready()
+        } else if defaultWearable.contains(DeviceTypes.G2) {
+            // handleG2Ready()
+        } else if defaultWearable.contains(DeviceTypes.MACH1) {
+            handleMach1Ready()
+        } else if defaultWearable.contains(DeviceTypes.Z100) {
+            handleMach1Ready() // Z100 uses same initialization as Mach1
+        }
+
+        // check current audio device:
+        checkCurrentAudioDevice()
+
+        // Re-arm the mic from the stored should_send_* flags. disconnect() zeroes the
+        // micEnabled intent, but miniapp subscriptions (should_send_pcm/lc3) survive the
+        // reconnect — without this recompute the mic stays off until a subscription edge.
+        setMicState()
+
+        // save the default_wearable now that we're connected:
+        Bridge.saveSetting("default_wearable", defaultWearable)
+        Bridge.saveSetting("device_name", deviceName)
+        Bridge.saveSetting("device_address", deviceAddress)
+
+        // Restore the ring: connecting glasses tears the controller down
+        // (disconnect() nils it), so bring a paired default controller back.
+        if DeviceStore.shared.get("glasses", "controllerConnected") as? Bool != true {
+            connectDefaultController()
+        }
+        if defaultWearable.contains(DeviceTypes.AR99) {
+            let projectName = (DeviceStore.shared.get("bluetooth", "project_name") as? String)?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+            Bridge.saveSetting("project_name", projectName)
+        }
+    }
+
+    private func syncSystemTimeOnceForConnection(_ sgc: SGCManager, connectionKey: String) {
+        if sgc.type.contains(DeviceTypes.SIMULATED) {
+            return
+        }
+        if connectionKey == lastSystemTimeSyncConnectionKey {
+            return
+        }
+
+        lastSystemTimeSyncConnectionKey = connectionKey
+        pendingSystemTimeSync?.cancel()
+        systemTimeSyncGeneration += 1
+        let generation = systemTimeSyncGeneration
+        let sync = DispatchWorkItem { [weak self] in
+            guard let self,
+                  self.lastSystemTimeSyncConnectionKey == connectionKey,
+                  self.systemTimeSyncGeneration == generation
+            else {
+                return
+            }
+            self.pendingSystemTimeSync = nil
+            let timestampMs = Int64(Date().timeIntervalSince1970 * 1000)
+            Bridge.log("MAN: Syncing glasses system time once for connection: \(timestampMs)")
+            sgc.sendSetSystemTime(timestampMs)
+        }
+        pendingSystemTimeSync = sync
+        DispatchQueue.main.asyncAfter(deadline: .now() + 3, execute: sync)
+    }
+
+    private func resetSystemTimeSync() {
+        pendingSystemTimeSync?.cancel()
+        pendingSystemTimeSync = nil
+        systemTimeSyncGeneration += 1
+        lastSystemTimeSyncConnectionKey = ""
+    }
+
+    func handleControllerReady() {
+        guard let controller else {
+            Bridge.log("MAN: Controller is nil, returning")
+            return
+        }
+        Bridge.log("MAN: handleControllerReady(): \(controller.type)")
+
+        pendingController = ""
+        defaultController = controller.type
+        searching = false
+
+        // save the default_controller now that we're connected:
+        Bridge.saveSetting("default_controller", defaultController)
+        Bridge.saveSetting("controller_device_name", controllerDeviceName)
+    }
+
+    func handleControllerDisconnected() {
+        Bridge.log("MAN: Controller disconnected")
+    }
+
+    private func handleG1Ready() {
+        // G1-specific setup and configuration
+        Task {
+            // give the glasses some extra time to finish booting:
+            try? await Task.sleep(nanoseconds: 1_000_000_000)
+            await sgc?.setSilentMode(false) // turn off silent mode
+            await sgc?.getBatteryStatus()
+
+            // send loaded settings to glasses:
+            try? await Task.sleep(nanoseconds: 400_000_000)
+            sgc?.setHeadUpAngle(headUpAngle)
+            try? await Task.sleep(nanoseconds: 400_000_000)
+            sgc?.setBrightness(brightness, autoMode: autoBrightness)
+            try? await Task.sleep(nanoseconds: 400_000_000)
+            // self.g1Manager?.RN_setDashboardPosition(self.dashboardHeight, self.dashboardDepth)
+            // try? await Task.sleep(nanoseconds: 400_000_000)
+            //      playStartupSequence()
+        }
+    }
+
+    private func handleMach1Ready() {}
+
+    func handleDeviceDisconnected() {
+        Bridge.log("MAN: Device disconnected")
+        resetSystemTimeSync()
+        resetMicHealth()
+        DeviceStore.shared.apply("glasses", "headUp", false)
+        DeviceStore.shared.apply("glasses", "voiceActivityDetectionEnabled", BluetoothSdkDefaults.voiceActivityDetectionEnabled)
+        // shouldSendBootingMessage = true  // Reset for next first connect
+    }
+
+    // MARK: - Network Command handlers
+
+    func displayText(_ params: [String: Any]) {
+        guard let text = params["text"] as? String else {
+            Bridge.log("MAN: display_text missing text parameter")
+            return
+        }
+
+        Bridge.log("MAN: Displaying text: \(text)")
+        Task { await sgc?.sendTextWall(text) }
+    }
+
+    func displayEvent(_ event: [String: Any]) {
+        // 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).
+        if let sceneMap = event["scene"] as? [String: Any] {
+            handleSceneEvent(sceneMap)
+            return
+        }
+
+        guard let layout = event["layout"] as? [String: Any],
+              let layoutType = layout["layoutType"] as? String
+        else {
+            Bridge.log("MAN: displayEvent missing layout")
+            return
+        }
+
+        // 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.
+        if let prevFrame = sceneState {
+            sceneState = nil
+            if layoutType != "clear_view" {
+                let ids = prevFrame.elements.map(\.id)
+                Task { [weak self] in
+                    await self?.sgc?.clearSceneElements(ids)
+                }
+            }
+        }
+        var text = layout["text"] as? String ?? " "
+        var topText = layout["topText"] as? String ?? " "
+        var bottomText = layout["bottomText"] as? String ?? " "
+        var title = layout["title"] as? String ?? " "
+        var data = layout["data"] as? String ?? ""
+
+        // Optional bitmap_view container position/size (forwarded to the SGC; used by G2).
+        let bmpX = (layout["x"] as? NSNumber).map { $0.int32Value }
+        let bmpY = (layout["y"] as? NSNumber).map { $0.int32Value }
+        let bmpWidth = (layout["width"] as? NSNumber).map { $0.int32Value }
+        let bmpHeight = (layout["height"] as? NSNumber).map { $0.int32Value }
+        let borderWidth = (layout["borderWidth"] as? NSNumber).map { $0.int32Value }
+        let borderRadius = (layout["borderRadius"] as? NSNumber).map { $0.int32Value }
+
+        text = parsePlaceholders(text)
+        topText = parsePlaceholders(topText)
+        bottomText = parsePlaceholders(bottomText)
+        title = parsePlaceholders(title)
+
+        var newViewState = ViewState(
+            topText: topText, bottomText: bottomText, title: title, layoutType: layoutType,
+            text: text, data: data, animationData: nil,
+            bmpX: bmpX, bmpY: bmpY, bmpWidth: bmpWidth, bmpHeight: bmpHeight,
+            borderWidth: borderWidth, borderRadius: borderRadius
+        )
+
+        if layoutType == "bitmap_animation" {
+            if let frames = layout["frames"] as? [String],
+               let interval = layout["interval"] as? Double
+            {
+                let animationData: [String: Any] = [
+                    "frames": frames,
+                    "interval": interval,
+                    "repeat": layout["repeat"] as? Bool ?? true,
+                ]
+                newViewState.animationData = animationData
+                Bridge.log(
+                    "MAN: Parsed bitmap_animation with \(frames.count) frames, interval: \(interval)ms"
+                )
+            } else {
+                Bridge.log("MAN: ERROR: bitmap_animation missing frames or interval")
+            }
+        }
+
+        // positioned_text flows through the viewState slot like every other
+        // layout (matching Android): multi-element frames arrive as ONE scene
+        // event, so nothing clobbers anything.
+
+        let cS = viewState
+        let nS = newViewState
+        let currentState =
+            cS.layoutType + cS.text + cS.topText + cS.bottomText + cS.title + (cS.data ?? "")
+        let newState =
+            nS.layoutType + nS.text + nS.topText + nS.bottomText + nS.title + (nS.data ?? "")
+
+        if currentState == newState {
+            // Core.log("MAN: View state is the same, skipping update")
+            return
+        }
+
+        viewState = newViewState
+        sendCurrentState()
+    }
+
+    /// Parse + store a scene frame, then dispatch it.
+    private func handleSceneEvent(_ sceneMap: [String: Any]) {
+        guard var frame = parseSceneFrame(sceneMap) else { return }
+        let prevFrame = sceneState
+
+        if prevFrame == nil {
+            // 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).
+            let prevLegacyType = viewState.layoutType
+            if !prevLegacyType.isEmpty, prevLegacyType != "clear_view", prevLegacyType != "scene" {
+                sgc?.clearDisplay()
+            }
+        } else if let prevFrame, 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. The boot message
+            // interposes between apps in practice, so this isn't visible.
+            let ids = prevFrame.elements.map(\.id)
+            Task { [weak self] in
+                await self?.sgc?.clearSceneElements(ids)
+            }
+            frame = frame.asReplay()
+        }
+
+        // Store the REDISPATCH form: any later sendCurrentState (nav exit,
+        // screen re-enable) must repaint the whole frame - the original
+        // annotations are only valid for the first dispatch right now.
+        sceneState = frame.asReplay()
+        viewState = ViewState(
+            topText: " ", bottomText: " ", title: " ", layoutType: "scene",
+            text: " ", data: nil, animationData: nil
+        )
+
+        dispatchSceneFrame(frame)
+    }
+
+    /// Guarded scene dispatch - mirrors sendCurrentState's send conditions.
+    private func dispatchSceneFrame(_ frame: SceneFrame) {
+        if screenDisabled {
+            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 {
+            return
+        }
+        if sgc?.type.contains(DeviceTypes.SIMULATED) ?? true {
+            return
+        }
+        guard sgc?.fullyBooted == true else {
+            Bridge.log("MAN: dispatchSceneFrame(): sgc not ready")
+            return
+        }
+        Task { [weak self] in
+            await self?.sgc?.applySceneFrame(frame)
+        }
+    }
+
+    private func parseSceneFrame(_ sceneMap: [String: Any]) -> SceneFrame? {
+        guard let elementsRaw = sceneMap["elements"] as? [[String: Any]] else { return nil }
+        let elements: [SceneElement] = elementsRaw.compactMap { el in
+            guard let id = el["id"] as? String,
+                  let type = el["type"] as? String,
+                  let box = el["box"] as? [String: Any]
+            else { return nil }
+            let style = el["style"] as? [String: Any]
+            return SceneElement(
+                id: id,
+                type: type,
+                x: (box["x"] as? NSNumber)?.int32Value ?? 0,
+                y: (box["y"] as? NSNumber)?.int32Value ?? 0,
+                w: (box["w"] as? NSNumber)?.int32Value ?? 0,
+                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,
+                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
+            )
+        }
+        let canvas = sceneMap["canvas"] as? [String: Any]
+        return SceneFrame(
+            appId: sceneMap["appId"] as? String ?? "",
+            epoch: (sceneMap["sceneEpoch"] as? NSNumber)?.intValue ?? 0,
+            replay: sceneMap["replay"] as? Bool ?? false,
+            elements: elements,
+            removed: (sceneMap["removed"] as? [String]) ?? [],
+            canvasWidth: (canvas?["width"] as? NSNumber)?.int32Value ?? 0,
+            canvasHeight: (canvas?["height"] as? NSNumber)?.int32Value ?? 0
+        )
+    }
+
+    func showDashboard() {
+        sgc?.showDashboard()
+    }
+
+    func showNotificationsPanel() {
+        Task { await sgc?.showNotificationsPanel() }
+    }
+
+    func ping() {
+        sgc?.ping()
+    }
+
+    func dbg1() {
+        // sgc?.disconnectController()
+        // connectDefaultController()
+    }
+
+    func dbg2() {}
+
+    func startStream(_ message: [String: Any]) {
+        var message = message
+        Bridge.log("MAN: startStream: \(message)")
+        sgc?.startStream(message)
+    }
+
+    func stopStream() {
+        Bridge.log("MAN: stopStream")
+        sgc?.stopStream()
+    }
+
+    func keepStreamAlive(_ message: [String: Any]) {
+        Bridge.log("MAN: sendStreamKeepAlive: \(message)")
+        sgc?.sendStreamKeepAlive(message)
+    }
+
+    func requestWifiScan(scanId: String? = nil) {
+        Bridge.log("MAN: Requesting wifi scan")
+        DeviceStore.shared.apply("bluetooth", "wifiScanResults", [])
+        sgc?.requestWifiScan(scanId: scanId)
+    }
+
+    func sendIncidentId(_ incidentId: String, apiBaseUrl: String? = nil) {
+        Bridge.log("MAN: Sending incidentId to glasses for log upload: \(incidentId)")
+        sgc?.sendIncidentId(incidentId, apiBaseUrl: apiBaseUrl)
+    }
+
+    func sendWifiCredentials(_ ssid: String, _ password: String) {
+        Bridge.log("MAN: Sending wifi credentials: \(ssid) \(password)")
+        sgc?.sendWifiCredentials(ssid, password)
+    }
+
+    func forgetWifiNetwork(_ ssid: String) {
+        Bridge.log("MAN: Forgetting wifi network: \(ssid)")
+        sgc?.forgetWifiNetwork(ssid)
+    }
+
+    func setHotspotState(_ enabled: Bool) {
+        Bridge.log("MAN: 🔥 Setting glasses hotspot state: \(enabled)")
+        sgc?.sendHotspotState(enabled)
+    }
+
+    func setWifiAdbState(_ enabled: Bool) {
+        Bridge.log("MAN: 🔧 Setting glasses Wi-Fi ADB state: \(enabled)")
+        sgc?.sendWifiAdbState(enabled)
+    }
+
+    func setSystemTime(_ timestampMs: Int64) {
+        Bridge.log("MAN: Setting glasses system time: \(timestampMs)")
+        sgc?.sendSetSystemTime(timestampMs)
+    }
+
+    func queryGalleryStatus() {
+        Bridge.log("MAN: 📸 Querying gallery status from glasses")
+        sgc?.queryGalleryStatus()
+    }
+
+    /// Send OTA start command to glasses.
+    /// Called when user approves an update (onboarding or background mode).
+    /// Triggers glasses to begin download and installation.
+    func sendOtaStart(otaVersionUrl: String? = nil) {
+        Bridge.log("MAN: 📱 Sending OTA start command to glasses")
+        sgc?.sendOtaStart(otaVersionUrl: otaVersionUrl)
+    }
+
+    func sendOtaQueryStatus() {
+        Bridge.log("MAN: 📱 Sending OTA query status command to glasses")
+        (sgc as? MentraLive)?.sendOtaQueryStatus()
+    }
+
+    func startAr99OtaFromFile(_ path: String) throws -> Bool {
+        guard let ar99 = sgc as? Ar99 else {
+            throw BluetoothSdkError(code: "unsupported_device", message: "This command requires AR99 glasses.")
+        }
+        return ar99.startOtaFromFile(path)
+    }
+
+    func cancelAr99Ota() {
+        (sgc as? Ar99)?.cancelAr99Ota()
+    }
+
+    func sendAr99FactoryReset() throws {
+        guard let ar99 = sgc as? Ar99 else {
+            throw BluetoothSdkError(code: "unsupported_device", message: "This command requires AR99 glasses.")
+        }
+        ar99.sendFactoryReset()
+    }
+
+    private func liveSgc() throws -> MentraLive {
+        guard let live = sgc as? MentraLive else {
+            throw BluetoothSdkError(code: "unsupported_device", message: "This command requires Mentra Live glasses.")
+        }
+        return live
+    }
+
+    func sendGalleryMode(requestId: String, enabled: Bool) throws {
+        try liveSgc().sendGalleryMode(requestId: requestId, active: enabled)
+    }
+
+    func sendButtonPhotoSettings(requestId: String, size: String) throws {
+        try sendButtonPhotoSettings(
+            requestId: requestId,
+            settings: PhotoCaptureDefaults(size: PhotoSize(normalizedRawValue: size))
+        )
+    }
+
+    func sendButtonPhotoSettings(requestId: String, settings: PhotoCaptureDefaults) throws {
+        try liveSgc().sendButtonPhotoSettings(requestId: requestId, settings: settings)
+    }
+
+    func sendButtonVideoRecordingSettings(requestId: String, width: Int, height: Int, fps: Int) throws {
+        try liveSgc().sendButtonVideoRecordingSettings(requestId: requestId, width: width, height: height, fps: fps)
+    }
+
+    func sendButtonMaxRecordingTime(requestId: String, minutes: Int) throws {
+        try liveSgc().sendButtonMaxRecordingTime(requestId: requestId, minutes: minutes)
+    }
+
+    func sendCameraFovSetting(requestId: String, fov: Int, roiPosition: Int) throws {
+        try liveSgc().sendCameraFovSetting(requestId: requestId, fov: fov, roiPosition: roiPosition)
+    }
+
+    func sendLegacyCameraFovSetting(fov: Int, roiPosition: Int) throws {
+        let glassesConnected = DeviceStore.shared.get("glasses", "connected") as? Bool ?? false
+        guard glassesConnected else {
+            throw BluetoothSdkError(code: "not_connected", message: "Mentra Live glasses are not connected.")
+        }
+        try liveSgc().sendCameraFovSetting(requestId: nil, fov: fov, roiPosition: roiPosition)
+    }
+
+    func restoreLegacyCameraFovSetting() throws {
+        let glassesConnected = DeviceStore.shared.get("glasses", "connected") as? Bool ?? false
+        guard glassesConnected else {
+            throw BluetoothSdkError(code: "not_connected", message: "Mentra Live glasses are not connected.")
+        }
+        try liveSgc().sendCameraFovSetting()
+    }
+
+    func sendCameraFovOverride(
+        requestId: String,
+        leaseId: String,
+        fov: Int,
+        roiPosition: Int,
+        ttlMs: Int
+    ) throws {
+        try liveSgc().sendCameraFovOverride(
+            requestId: requestId,
+            leaseId: leaseId,
+            fov: fov,
+            roiPosition: roiPosition,
+            ttlMs: ttlMs
+        )
+    }
+
+    func releaseCameraFovOverride(requestId: String, leaseId: String) throws {
+        try liveSgc().releaseCameraFovOverride(requestId: requestId, leaseId: leaseId)
+    }
+
+    func sendCameraTuningConfig(requestId: String, anrOn: Bool, gainOn: Bool) throws {
+        try liveSgc().sendCameraTuningConfig(requestId: requestId, anrOn: anrOn, gainOn: gainOn)
+    }
+
+    func warmUpCamera(
+        requestId: String,
+        size: PhotoSize,
+        mode: PhotoMode = .photo,
+        exposureTimeNs: Double?,
+        durationMs: Int,
+        zsl: Bool? = nil,
+        mfnr: Bool? = nil
+    ) throws {
+        guard let live = sgc as? MentraLive else {
+            // Fail fast like other camera commands so the SDK promise rejects immediately instead
+            // of hanging until the request timeout with no camera_status.
+            throw BluetoothSdkError(
+                code: "unsupported_device", message: "This command requires Mentra Live glasses."
+            )
+        }
+        live.warmUpCamera(
+            requestId: requestId,
+            size: size,
+            mode: mode,
+            exposureTimeNs: exposureTimeNs,
+            durationMs: durationMs,
+            zsl: zsl,
+            mfnr: mfnr
+        )
+    }
+
+    func stopCameraWarmUp(requestId: String) throws {
+        try liveSgc().stopCameraWarmUp(requestId: requestId)
+    }
+
+    /// Request version info from glasses.
+    /// Glasses will respond with version_info message containing build number, firmware version, etc.
+    func requestVersionInfo() {
+        Bridge.log("MAN: 📱 Requesting version info from glasses")
+        sgc?.requestVersionInfo()
+    }
+
+    func availableG2FirmwareArtifacts() throws -> [[String: Any]] {
+        guard let g2 = sgc as? G2 else {
+            throw G2FirmwareFlashError.transport("The connected device is not a G2.")
+        }
+        return g2.availableFirmwareArtifacts()
+    }
+
+    func startG2FirmwareFlash(target: String) async throws -> [String: Any] {
+        guard let g2 = sgc as? G2 else {
+            throw G2FirmwareFlashError.transport("The connected device is not a G2.")
+        }
+        return try await g2.startFirmwareFlash(target: target)
+    }
+
+    /// Send shutdown command to glasses.
+    /// This will initiate a graceful shutdown of the device.
+    func sendShutdown() {
+        Bridge.log("MAN: 🔌 Sending shutdown command to glasses")
+        sgc?.sendShutdown()
+    }
+
+    /// Send reboot command to glasses.
+    /// This will initiate a reboot of the device.
+    func sendReboot() {
+        Bridge.log("MAN: 🔄 Sending reboot command to glasses")
+        sgc?.sendReboot()
+    }
+
+    func startVideoRecording(
+        _ requestId: String, _ save: Bool, _ sound: Bool, _ width: Int = 0, _ height: Int = 0,
+        _ fps: Int = 0, _ maxRecordingTimeMinutes: Int = 0
+    ) {
+        Bridge.log(
+            "MAN: onStartVideoRecording: requestId=\(requestId), save=\(save), sound=\(sound), resolution=\(width)x\(height)@\(fps)fps, maxRecordingTimeMinutes=\(maxRecordingTimeMinutes)"
+        )
+        sgc?.startVideoRecording(
+            requestId: requestId, save: save, sound: sound, width: width, height: height,
+            fps: fps, maxRecordingTimeMinutes: maxRecordingTimeMinutes
+        )
+    }
+
+    func queryVideoRecordingStatus(_ requestId: String) {
+        Bridge.log("MAN: Querying video recording status: requestId=\(requestId)")
+        sgc?.queryVideoRecordingStatus(requestId: requestId)
+    }
+
+    func stopVideoRecording(_ requestId: String, _ webhookUrl: String?, _ authToken: String?) {
+        Bridge.log(
+            "MAN: onStopVideoRecording: requestId=\(requestId), webhook=\((webhookUrl?.isEmpty ?? true) ? "none" : "set")"
+        )
+        sgc?.stopVideoRecording(requestId: requestId, webhookUrl: webhookUrl, authToken: authToken)
+    }
+
+    func setMicState() {
+        let willSendPcm = shouldSendPcm || shouldSendLc3
+        let willSendTranscript = shouldSendTranscript || localSttFallbackActive
+        // Speaker enrollment records through whichever mic is currently
+        // ranked active, so it holds the mic open like any other consumer.
+        micEnabled = willSendPcm || willSendTranscript || speakerEnrollmentActive
+        updateMicState()
+    }
+
+    // MARK: - Speaker identification
+
+    /// Enrollment holds the mic open (see setMicState). Set by
+    /// startSpeakerEnrollment / cleared when the session ends or is cancelled.
+    private var speakerEnrollmentActive = false
+
+    func setSpeakerIdEnabled(_ enabled: Bool) {
+        SpeakerIdEngine.shared.setIdentifyEnabled(enabled)
+    }
+
+    func setSpeakerIdModelPath(_ path: String) {
+        SpeakerIdEngine.setModelPath(path)
+    }
+
+    func setSpeakerProfiles(_ profiles: [[String: Any]]) {
+        let parsed: [SpeakerIdEngine.Profile] = profiles.compactMap { entry in
+            guard let id = entry["id"] as? String,
+                  let name = entry["name"] as? String,
+                  let base64 = entry["embedding"] as? String,
+                  let embedding = SpeakerIdEngine.embedding(fromBase64: base64)
+            else {
+                return nil
+            }
+            return SpeakerIdEngine.Profile(id: id, name: name, embedding: embedding)
+        }
+        SpeakerIdEngine.shared.setProfiles(parsed)
+    }
+
+    func startSpeakerEnrollment(targetSpeechSeconds: Double) {
+        let source = currentMic == MicTypes.GLASSES_CUSTOM ? "glasses" : "phone"
+        speakerEnrollmentActive = true
+        setMicState()
+        SpeakerIdEngine.shared.startEnrollment(targetSpeechSeconds: targetSpeechSeconds, source: source) {
+            Task { @MainActor [weak self] in
+                guard let self else { return }
+                self.speakerEnrollmentActive = false
+                self.setMicState()
+            }
+        }
+    }
+
+    func cancelSpeakerEnrollment() {
+        SpeakerIdEngine.shared.cancelEnrollment()
+        speakerEnrollmentActive = false
+        setMicState()
+    }
+
+    func rgbLedControl(
+        requestId: String,
+        packageName: String?,
+        action: String,
+        color: String?,
+        onDurationMs: Int,
+        offDurationMs: Int,
+        count: Int
+    ) {
+        sgc?.sendRgbLedControl(
+            requestId: requestId,
+            packageName: packageName,
+            action: action,
+            color: color,
+            onDurationMs: onDurationMs,
+            offDurationMs: offDurationMs,
+            count: count
+        )
+    }
+
+    /// Mentra Live only: K900 `cs_getvol` / `sr_getvol` (step volume 0-5).
+    func getGlassesMediaVolume() async throws -> [String: Any] {
+        guard let live = sgc as? MentraLive else {
+            throw NSError(
+                domain: "DeviceManager",
+                code: 100,
+                userInfo: [NSLocalizedDescriptionKey: "unsupported_device"]
+            )
+        }
+        return try await withCheckedThrowingContinuation {
+            (continuation: CheckedContinuation<[String: Any], Error>) in
+            live.getGlassesMediaVolume { result in
+                continuation.resume(with: result)
+            }
+        }
+    }
+
+    /// Mentra Live only: K900 `cs_vol` / `sr_vol`.
+    func setGlassesMediaVolume(level: Int) async throws -> [String: Any] {
+        guard let live = sgc as? MentraLive else {
+            throw NSError(
+                domain: "DeviceManager",
+                code: 100,
+                userInfo: [NSLocalizedDescriptionKey: "unsupported_device"]
+            )
+        }
+        return try await withCheckedThrowingContinuation {
+            (continuation: CheckedContinuation<[String: Any], Error>) in
+            live.setGlassesMediaVolume(level: level) { result in
+                continuation.resume(with: result)
+            }
+        }
+    }
+
+    func requestPhoto(_ request: PhotoRequest) {
+        let manualExposureNs = request.exposureTimeNs.flatMap { $0.isFinite && $0 > 0 ? $0 : nil }
+        let manualIso = manualExposureNs != nil ? request.iso.flatMap { $0 > 0 ? $0 : nil } : nil
+        let routed = PhotoRequest(
+            requestId: request.requestId,
+            size: request.size,
+            webhookUrl: request.webhookUrl,
+            authToken: request.authToken,
+            compress: request.compress,
+            save: request.save,
+            sound: request.sound,
+            exposureTimeNs: manualExposureNs,
+            iso: manualIso,
+            aeExposureDivisor: request.aeExposureDivisor,
+            isoCap: request.isoCap,
+            noiseReduction: request.noiseReduction,
+            edgeEnhancement: request.edgeEnhancement,
+            mfnr: request.mfnr,
+            zsl: request.zsl,
+            ispDigitalGain: request.ispDigitalGain,
+            ispAnalogGain: request.ispAnalogGain,
+            mode: request.mode,
+            transferMethod: request.transferMethod
+        )
+        Bridge.log(
+            "MAN: PHOTO PIPELINE [4/6] DeviceManager.requestPhoto requestId=\(routed.requestId) webhookUrl=\(routed.webhookUrl ?? "nil") size=\(routed.size.rawValue) compress=\(routed.compress?.rawValue ?? "none") save=\(routed.save) sound=\(routed.sound) exposureTimeNs=\(manualExposureNs.map { String($0) } ?? "nil") iso=\(manualIso.map { String($0) } ?? "auto") aeDivisor=\(routed.aeExposureDivisor.map { String($0) } ?? "nil") isoCap=\(routed.isoCap.map { String($0) } ?? "nil") sgc=\(sgc != nil ? String(describing: type(of: sgc!)) : "null")"
+        )
+        guard let sgc else {
+            Bridge.log(
+                "MAN: PHOTO PIPELINE - sgc is null (glasses not connected); dropping requestId=\(routed.requestId)"
+            )
+            return
+        }
+        sgc.requestPhoto(routed)
+    }
+
+    func connectDefault() {
+        if defaultWearable.isEmpty {
+            Bridge.log("MAN: No default wearable, returning")
+            return
+        }
+        let reconnectTarget =
+            if defaultWearable.contains(DeviceTypes.AR99), !deviceAddress.isEmpty {
+                deviceAddress
+            } else {
+                deviceName
+            }
+        if reconnectTarget.isEmpty {
+            Bridge.log("MAN: No reconnect target, returning")
+            return
+        }
+        initSGC(defaultWearable)
+        if let live = sgc as? MentraLive, live.isPairingYieldActive() {
+            Bridge.log("MAN: connectDefault skipped — Mentra Live pairing yield active")
+            return
+        }
+        searching = true
+        sgc?.connectById(reconnectTarget)
+        connectDefaultController()
+    }
+
+    func connectDefaultController() {
+        if defaultController.isEmpty {
+            Bridge.log("MAN: No default controller, returning")
+            return
+        }
+        if controllerDeviceName.isEmpty {
+            Bridge.log("MAN: No controller device name, returning")
+            return
+        }
+        initController(defaultController)
+        searchingController = true
+        controller?.connectById(controllerDeviceName)
+    }
+
+    func connectByName(_ dName: String) {
+        Bridge.log("MAN: Connecting to wearable: \(dName)")
+        var name = dName
+
+        // use stored device name if available:
+        if dName.isEmpty && !deviceName.isEmpty {
+            name = deviceName
+        }
+
+        if pendingWearable.isEmpty, defaultWearable.isEmpty {
+            Bridge.log("MAN: No pending or default wearable, returning")
+            return
+        }
+
+        if pendingWearable.isEmpty, !defaultWearable.isEmpty {
+            Bridge.log("MAN: No pending wearable, using default wearable: \(defaultWearable)")
+            pendingWearable = defaultWearable
+        }
+
+        // if the pending wearable is a controller, don't disconnect, use the controller manager to connect
+        if ControllerTypes.ALL.contains(pendingWearable) {
+            controller?.disconnect()
+            // connect() routes here after disconnectController() nils the
+            // controller — recreate it or connectById is a silent no-op.
+            initController(pendingWearable)
+            controller?.connectById(name)
+            return
+        }
+
+        Task {
+            disconnect(clearPendingConnection: false)
+            try? await Task.sleep(nanoseconds: 100 * 1_000_000) // 100ms
+            self.searching = true
+            self.pendingDeviceName = name
+
+            initSGC(self.pendingWearable)
+            sgc?.connectById(name)
+        }
+    }
+
+    func connectDevice(_ deviceModel: String, _ deviceName: String) {
+        Bridge.log("MAN: Connecting to device: \(deviceModel) \(deviceName)")
+        if DeviceTypes.ALL.contains(deviceModel) {
+            pendingWearable = deviceModel
+            initSGC(pendingWearable)
+            sgc?.connectById(deviceName)
+            return
+        }
+        if ControllerTypes.ALL.contains(deviceModel) {
+            pendingWearable = deviceModel
+            initController(deviceModel)
+            controller?.connectById(deviceName)
+            return
+        }
+        Bridge.log("MAN: No compatible device model, returning")
+    }
+
+    func connectSimulated() {
+        defaultWearable = DeviceTypes.SIMULATED
+        deviceName = DeviceTypes.SIMULATED
+        initSGC(defaultWearable)
+        handleDeviceReady()
+    }
+
+    func disconnect(clearPendingConnection: Bool = true) {
+        sgc?.clearDisplay() // clear the screen
+        sgc?.disconnect()
+        sgc = nil // Clear the SGC reference after disconnect
+        resetSystemTimeSync()
+        resetMicHealth()
+        searching = false
+        micEnabled = false
+        updateMicState()
+        shouldSendBootingMessage = true // Reset for next first connect
+        // clear glasses properties:
+        DeviceStore.shared.apply("glasses", "deviceModel", "")
+        // Device identifiers are session-bound. Clear them on every disconnect so a
+        // previously connected pair can never be reported for the next connection.
+        DeviceStore.shared.apply("glasses", "serialNumber", "")
+        DeviceStore.shared.apply("glasses", "bluetoothMacAddress", "")
+        DeviceStore.shared.apply("glasses", "wifiMacAddress", "")
+        DeviceStore.shared.apply("glasses", "leftMacAddress", "")
+        DeviceStore.shared.apply("glasses", "rightMacAddress", "")
+        DeviceStore.shared.apply("glasses", "macAddress", "")
+        DeviceStore.shared.apply("glasses", "fullyBooted", false)
+        DeviceStore.shared.apply("glasses", "connected", false)
+        DeviceStore.shared.apply("glasses", "connectionState", ConnTypes.DISCONNECTED)
+        DeviceStore.shared.apply("glasses", "voiceActivityDetectionEnabled", BluetoothSdkDefaults.voiceActivityDetectionEnabled)
+        // disconnect the controller as well:
+        searchingController = false
+        DeviceStore.shared.apply("glasses", "controllerConnected", false)
+        controller?.disconnect()
+        controller = nil // Clear the controller reference after disconnect
+        if clearPendingConnection {
+            self.clearPendingConnection()
+        }
+    }
+
+    private func clearPendingConnection() {
+        pendingDeviceName = ""
+        pendingDeviceAddress = ""
+        pendingWearable = ""
+    }
+
+    func disconnectController() {
+        searchingController = false
+        // disconnect the controller from the glasses if applicable:
+        sgc?.disconnectController()
+        controller?.disconnect()
+        controller = nil // Clear the controller reference after disconnect
+    }
+
+    func forget() {
+        Bridge.log("MAN: Forgetting smart glasses")
+        // Call forget first to stop timers/handlers/reconnect logic
+        sgc?.forget()
+        disconnect()
+        // Clear state
+        defaultWearable = ""
+        deviceName = ""
+        deviceAddress = ""
+        clearPendingConnection()
+        Bridge.saveSetting("default_wearable", "")
+        Bridge.saveSetting("device_name", "")
+        Bridge.saveSetting("device_address", "")
+        Bridge.saveSetting("project_name", "")
+    }
+
+    func forgetController() {
+        Bridge.log("MAN: Forgetting controller")
+        controller?.forget()
+        disconnectController()
+        // Clear state
+        defaultController = ""
+        controllerDeviceName = ""
+        Bridge.saveSetting("controller_device_name", "")
+        Bridge.saveSetting("default_controller", "")
+        DeviceStore.shared.apply("glasses", "controllerConnected", false)
+    }
+
+    func findCompatibleDevices(_ deviceModel: String) {
+        Bridge.log("MAN: Searching for compatible device names for: \(deviceModel)")
+
+        // reset the search results:
+        searchResults = []
+
+        if DeviceTypes.ALL.contains(deviceModel) {
+            pendingWearable = deviceModel
+        }
+
+        if ControllerTypes.ALL.contains(deviceModel) {
+            pendingWearable = deviceModel
+        }
+
+        if ControllerTypes.ALL.contains(deviceModel) {
+            initController(deviceModel)
+            controller?.findCompatibleDevices()
+            return
+        }
+
+        initSGC(pendingWearable)
+        sgc?.findCompatibleDevices()
+    }
+
+    func stopScan() {
+        controller?.stopScan()
+        sgc?.stopScan()
+        DeviceStore.shared.apply("bluetooth", "searching", false)
+        DeviceStore.shared.apply("bluetooth", "searchingController", false)
+    }
+
+    func cleanup() {
+        // Clean up transcriber resources
+        #if !SWIFT_PACKAGE || GLASSLY_FEATURE_LOCAL_STT
+            transcriber?.shutdown()
+            transcriber = nil
+        #endif
+
+        // Clean up LC3 converter
+        lc3Converter = nil
+
+        cancellables.removeAll()
+    }
+}