@mentra/engine 0.1.0-beta.0

package/src/services/CloudTranscriptE2EMetrics.ts

@@ -0,0 +1,27 @@
+import type {TranscriptionData} from "@mentra/cloud-protocol"
+
+import {buildE2EMetric, logE2EMetricPayload} from "../utils/e2eMetrics"
+
+export function buildCloudV2TranscriptMetric(data: TranscriptionData): Record<string, unknown> {
+  return buildE2EMetric("cloud_v2_transcript", {
+    text: data.text,
+    state: data.isFinal ? "final" : "interim",
+    is_final: data.isFinal,
+    resolved_language: data.resolvedLanguage,
+    language_detected: data.languageDetected,
+    utterance_id: data.utteranceId,
+    speaker_id: data.speakerId,
+    start_ms: data.startMs,
+    end_ms: data.endMs,
+    duration_ms: data.durationMs,
+    provider: data.provider,
+    confidence: data.confidence,
+    timestamp_ms: data.timestamp,
+    token_count: data.tokens.length,
+    subscription: data.subscription,
+  })
+}
+
+export function logCloudV2TranscriptMetric(data: TranscriptionData): void {
+  logE2EMetricPayload(buildCloudV2TranscriptMetric(data), "cloud_v2_transcript")
+}

package/src/services/ConnectionCoordinator.ts

@@ -0,0 +1,65 @@
+/**
+ * ConnectionCoordinator — the connection *decisions* that were duplicated across
+ * the reconnect effect and the connect/disconnect buttons.
+ *
+ * Pure logic: callers gather the inputs from their stores and perform the IO
+ * (permission prompts, bluetooth calls, navigation) themselves. Centralizing the
+ * decisions keeps the "when do we (re)connect / cancel / go to pairing" rules in
+ * one tested place instead of re-deriving them in home.tsx, DeviceStatus, the
+ * reconnect effect, and the connect buttons.
+ *
+ */
+export interface ReconnectDecisionInput {
+  /** The reconnect_on_app_foreground setting. */
+  reconnectOnForeground: boolean
+  /** The default_wearable setting (model id), if any. */
+  defaultWearable: string | null | undefined
+  /** True when defaultWearable is the simulated device. */
+  isSimulated: boolean
+  /** True when the glasses BLE link is already connected. */
+  connected: boolean
+  /** True while the native link layer is mid scan / connect / bond. */
+  nativeLinkBusy: boolean
+  /** True when the SDK holds an actual default device (connectDefault target). */
+  hasDefaultDevice: boolean
+  /** True when a scan is already in progress. */
+  searching: boolean
+}
+
+/**
+ * "skip" means do not connect — the caller returns `result` (preserving the
+ * original true/false contract of attemptReconnect). "connect" means proceed to
+ * the permission check + connectDefault().
+ */
+export type ReconnectDecision = {kind: "skip"; result: boolean} | {kind: "connect"}
+
+export function decideReconnect(input: ReconnectDecisionInput): ReconnectDecision {
+  // Reconnect-on-foreground disabled: treat as a no-op success.
+  if (!input.reconnectOnForeground) return {kind: "skip", result: true}
+  // No real wearable paired (or the simulated device): nothing to reconnect to.
+  if (!input.defaultWearable || input.isSimulated) return {kind: "skip", result: false}
+  // Model chosen but never actually paired (or the native default was cleared):
+  // connectDefault() would throw — skip quietly; pairing is a user-driven flow.
+  // (Safe to trust at cold start now: hasDefaultDevice reads are gated on the
+  // device-store hydration completing, and callers fail open on rejection.)
+  if (!input.hasDefaultDevice) return {kind: "skip", result: false}
+  // Already connected, or a scan/connect/bond is already in flight: starting a
+  // second connectDefault() on top of the busy link layer would collide with it
+  // (same busy rule as decideConnectButtonAction).
+  if (input.connected || input.searching || input.nativeLinkBusy) return {kind: "skip", result: true}
+  return {kind: "connect"}
+}
+
+export type ConnectButtonAction = "cancel" | "pair" | "connect"
+
+/**
+ * What a connect/disconnect button should do when tapped:
+ * - "cancel"  — a scan/connect is in flight; the tap cancels it (disconnect)
+ * - "pair"    — no device is paired yet; the tap goes to the pairing flow
+ * - "connect" — a device is paired and idle; the tap connects to it
+ */
+export function decideConnectButtonAction(input: {hasDefaultWearable: boolean; busy: boolean}): ConnectButtonAction {
+  if (input.busy) return "cancel"
+  if (!input.hasDefaultWearable) return "pair"
+  return "connect"
+}

package/src/services/DevServerBridge.ts

@@ -0,0 +1,332 @@
+/**
+ * DevServerBridge — phone-side WebSocket connection to a `mentra-miniapp dev`
+ * sidecar running on a developer's laptop.
+ *
+ * Multiplexed over a single WebSocket per dev miniapp:
+ *   laptop → phone : {type: "reload"}                 → trigger WebView.reload()
+ *   phone  → laptop: {type: "log", level, args, ...}  → forwarded console calls
+ *
+ * Lifecycle: `connect(packageName, devUrl, devPort)` is called from
+ * MiniappHost.mountDev once the dev applet is mounted. `disconnect(packageName)`
+ * is called from MiniappHost.unmount. Reconnect with exponential backoff on
+ * unexpected close — the dev server is the developer's laptop and may bounce.
+ *
+ * Outgoing logs are buffered in a small ring while disconnected; flushed on
+ * reconnect. This catches early-startup logs the developer would otherwise
+ * miss when re-launching the dev server.
+ */
+
+const LOG_TAG = "DEV_SERVER_BRIDGE"
+const PROTOCOL_VERSION = "mentra-dev/1"
+const HELLO_TIMEOUT_MS = 1_000
+const BACKOFF_MIN_MS = 1_000
+const BACKOFF_MAX_MS = 30_000
+const RING_BUFFER_MAX_ENTRIES = 100
+const RING_BUFFER_MAX_BYTES = 32 * 1024
+
+type State = "idle" | "connecting" | "connected" | "disconnected" | "closed"
+
+interface BufferedLog {
+  packageName: string
+  level: string
+  args: unknown[]
+  timestamp: number
+  /** "ui" = WebView, "background" = JSContext. Stamped at capture time. */
+  source: "ui" | "background"
+  size: number
+}
+
+interface BridgeEntry {
+  state: State
+  ws: WebSocket | null
+  url: string
+  attempts: number
+  ringBuffer: BufferedLog[]
+  ringBytes: number
+  reloadHandler: ((packageName: string) => void) | null
+  reconnectTimer: ReturnType<typeof setTimeout> | null
+}
+
+class DevServerBridge {
+  private entries = new Map<string, BridgeEntry>()
+  private globalReloadHandler: ((packageName: string) => void) | null = null
+  private globalRespawnBackgroundHandler: ((packageName: string) => void) | null = null
+
+  /**
+   * Register a global reload handler. MiniappHost calls this once at boot. The
+   * bridge invokes the handler with the offending packageName whenever a
+   * reload signal is received.
+   */
+  public onReload(handler: (packageName: string) => void): void {
+    this.globalReloadHandler = handler
+  }
+
+  /**
+   * Register a global background-respawn handler. Fires when the dev
+   * server sends `{type: "respawn-bg"}` — emitted on filesystem changes
+   * under `src/background/`. The host (MentraJSRouter via the
+   * bootstrap) should kill + respawn the JSContext to pick up the
+   * change. WebView reload is separate (see `onReload`).
+   */
+  public onRespawnBackground(handler: ((packageName: string) => void) | null): void {
+    this.globalRespawnBackgroundHandler = handler
+  }
+
+  /** Clear the background-respawn handler when the miniapp engine is stopped. */
+  public clearRespawnBackgroundHandler(): void {
+    this.globalRespawnBackgroundHandler = null
+  }
+
+  /** Open (or re-open) a bridge to the given dev server. */
+  public connect(packageName: string, devHostUrl: string, devPort: number): void {
+    const url = this.buildWsUrl(devHostUrl, devPort)
+    let entry = this.entries.get(packageName)
+    if (entry) {
+      // Already have an entry; if the URL changed (e.g. LAN IP shifted), close
+      // and rebuild.
+      if (entry.url === url && (entry.state === "connecting" || entry.state === "connected")) return
+      this.teardownEntry(entry)
+    }
+    entry = {
+      state: "idle",
+      ws: null,
+      url,
+      attempts: 0,
+      ringBuffer: [],
+      ringBytes: 0,
+      reloadHandler: null,
+      reconnectTimer: null,
+    }
+    this.entries.set(packageName, entry)
+    this.openSocket(packageName, entry)
+  }
+
+  /** Close a bridge for good. Called from MiniappHost.unmount. */
+  public disconnect(packageName: string): void {
+    const entry = this.entries.get(packageName)
+    if (!entry) return
+    entry.state = "closed"
+    this.teardownEntry(entry)
+    this.entries.delete(packageName)
+  }
+
+  /**
+   * Forward a `log` envelope to the connected dev sidecar. Called from
+   * the JSContext side (`MentraJSRouter.__log` handler) AND the WebView
+   * side (`MentraUIRouter.routeFromWebView` for `type:"log"` frames).
+   *
+   * `source` distinguishes the two halves so the CLI can prefix lines
+   * `[UI]` vs `[MentraJS]`. Logs are silently dropped when no bridge
+   * exists for the package (no `mentra-miniapp dev` running) and
+   * buffered in the per-bridge ring while disconnected.
+   */
+  public forwardLog(
+    packageName: string,
+    level: string,
+    args: unknown[],
+    timestamp: number,
+    source: "ui" | "background",
+  ): void {
+    const entry = this.entries.get(packageName)
+    if (!entry) return
+    const message = JSON.stringify({type: "log", level, args, packageName, timestamp, source})
+    if (entry.state === "connected" && entry.ws) {
+      try {
+        entry.ws.send(message)
+        return
+      } catch {
+        // Fall through to buffer.
+      }
+    }
+    this.bufferLog(entry, {packageName, level, args, timestamp, source, size: message.length})
+  }
+
+  // -----------------------------------------------------------------------
+
+  private buildWsUrl(devHostUrl: string, devPort: number): string {
+    let host: string
+    try {
+      const parsed = new URL(devHostUrl)
+      host = parsed.hostname
+    } catch {
+      // devHostUrl might already be just an IP; best-effort.
+      host = devHostUrl.replace(/^https?:\/\//, "").split(":")[0].split("/")[0]
+    }
+    return `ws://${host}:${devPort}/__mentra_dev`
+  }
+
+  private openSocket(packageName: string, entry: BridgeEntry): void {
+    if (entry.state === "closed") return
+    entry.state = "connecting"
+    const ws = new WebSocket(entry.url)
+    entry.ws = ws
+
+    let helloTimer: ReturnType<typeof setTimeout> | null = null
+    let helloAcked = false
+
+    const teardown = (reason: string): void => {
+      if (helloTimer) {
+        clearTimeout(helloTimer)
+        helloTimer = null
+      }
+      try {
+        ws.close()
+      } catch {
+        /* ignore */
+      }
+      if (entry.state === "closed") return
+      entry.state = "disconnected"
+      entry.ws = null
+      entry.attempts++
+      console.log(`${LOG_TAG}: ${packageName} disconnected (${reason}); reconnect in ${this.backoffMs(entry.attempts)}ms`)
+      this.scheduleReconnect(packageName, entry)
+    }
+
+    ws.onopen = () => {
+      // Send hello; wait for hello-ack to confirm we hit the right server.
+      try {
+        ws.send(JSON.stringify({type: "hello", protocol: PROTOCOL_VERSION}))
+      } catch {
+        teardown("hello send failed")
+        return
+      }
+      helloTimer = setTimeout(() => {
+        if (!helloAcked) {
+          teardown("hello-ack timeout")
+        }
+      }, HELLO_TIMEOUT_MS)
+    }
+
+    ws.onmessage = (ev) => {
+      const data = typeof ev.data === "string" ? ev.data : null
+      if (!data) return
+      let parsed: {type?: string; protocol?: string} | null = null
+      try {
+        parsed = JSON.parse(data)
+      } catch {
+        return
+      }
+      if (!parsed) return
+
+      if (parsed.type === "hello-ack") {
+        if (parsed.protocol !== PROTOCOL_VERSION) {
+          teardown(`protocol mismatch: server sent ${parsed.protocol}, expected ${PROTOCOL_VERSION}`)
+          return
+        }
+        helloAcked = true
+        if (helloTimer) {
+          clearTimeout(helloTimer)
+          helloTimer = null
+        }
+        entry.state = "connected"
+        entry.attempts = 0
+        console.log(`${LOG_TAG}: ${packageName} connected to ${entry.url}`)
+        this.flushRingBuffer(packageName, entry)
+        return
+      }
+
+      if (parsed.type === "reload") {
+        console.log(`${LOG_TAG}: ${packageName} received reload signal`)
+        this.globalReloadHandler?.(packageName)
+        return
+      }
+
+      // Two-layer dev signal: filesystem changes under src/background/
+      // trigger a full JSContext kill + respawn (not just a WebView
+      // reload). The host's MentraJSRouter listens here.
+      if (parsed.type === "respawn-bg") {
+        console.log(`${LOG_TAG}: ${packageName} received respawn-bg signal`)
+        this.globalRespawnBackgroundHandler?.(packageName)
+        return
+      }
+    }
+
+    ws.onerror = () => {
+      // onclose follows; defer all teardown to that path so we don't double-fire.
+    }
+
+    ws.onclose = () => {
+      teardown(helloAcked ? "ws closed" : "ws closed before hello-ack")
+    }
+  }
+
+  private scheduleReconnect(packageName: string, entry: BridgeEntry): void {
+    if (entry.state === "closed") return
+    if (entry.reconnectTimer) clearTimeout(entry.reconnectTimer)
+    const delay = this.backoffMs(entry.attempts)
+    entry.reconnectTimer = setTimeout(() => {
+      entry.reconnectTimer = null
+      // Verify still alive and still in the bridge map.
+      const current = this.entries.get(packageName)
+      if (!current || current !== entry || entry.state === "closed") return
+      this.openSocket(packageName, entry)
+    }, delay)
+  }
+
+  private backoffMs(attempts: number): number {
+    const exp = Math.min(BACKOFF_MAX_MS, BACKOFF_MIN_MS * Math.pow(2, Math.max(0, attempts - 1)))
+    const jitter = exp * (0.8 + Math.random() * 0.4)
+    return Math.round(jitter)
+  }
+
+  private bufferLog(entry: BridgeEntry, log: BufferedLog): void {
+    entry.ringBuffer.push(log)
+    entry.ringBytes += log.size
+    while (
+      entry.ringBuffer.length > RING_BUFFER_MAX_ENTRIES ||
+      entry.ringBytes > RING_BUFFER_MAX_BYTES
+    ) {
+      const dropped = entry.ringBuffer.shift()
+      if (dropped) entry.ringBytes -= dropped.size
+      if (entry.ringBuffer.length === 0) {
+        entry.ringBytes = 0
+        break
+      }
+    }
+  }
+
+  private flushRingBuffer(packageName: string, entry: BridgeEntry): void {
+    if (entry.ringBuffer.length === 0) return
+    const buffered = entry.ringBuffer
+    entry.ringBuffer = []
+    entry.ringBytes = 0
+    if (!entry.ws) return
+    for (const log of buffered) {
+      try {
+        entry.ws.send(
+          JSON.stringify({
+            type: "log",
+            level: log.level,
+            args: log.args,
+            packageName: log.packageName,
+            timestamp: log.timestamp,
+            source: log.source,
+          }),
+        )
+      } catch {
+        // Re-buffer on failure and bail.
+        entry.ringBuffer.unshift(log)
+        entry.ringBytes += log.size
+        return
+      }
+    }
+  }
+
+  private teardownEntry(entry: BridgeEntry): void {
+    if (entry.reconnectTimer) {
+      clearTimeout(entry.reconnectTimer)
+      entry.reconnectTimer = null
+    }
+    if (entry.ws) {
+      try {
+        entry.ws.close()
+      } catch {
+        /* ignore */
+      }
+      entry.ws = null
+    }
+  }
+}
+
+const devServerBridge = new DevServerBridge()
+export default devServerBridge

package/src/services/DeviceEventRouter.ts

@@ -0,0 +1,238 @@
+/**
+ * Device-event router — engine-owned. Subscribes to the inbound native BLE/device
+ * events and routes them into the engine runtime: device stores, the process event
+ * bus, the photo/stream coordinators, and local miniapps (via forwardEvent).
+ *
+ * Why this exists: engine owns the stores, coordinators, miniapp runtime, and facades,
+ * but it never *subscribed to the device* for most events — the host MantleManager was
+ * still the event router the whole runtime secretly depended on. So a bare OEM that
+ * imported engine + called engine.start() got a connected runtime with almost no device
+ * data flowing in (no miniapp input, dead gallery sync, starved coordinators). This
+ * service moves those inbound bridges into engine so ANY host gets them.
+ *
+ * Scope: the engine legs only. The Cloud V1 relays that used to live beside them in
+ * MantleManager (touch→cloud, the cloud-SDK stream/photo legs, etc.) were deleted with
+ * Cloud V1 app end-of-life.
+ *
+ * Started by `engine.start()`. Idempotent.
+ */
+import BluetoothSdk from "@mentra/bluetooth-sdk/internal"
+import {shallow} from "zustand/shallow"
+
+import localMiniappRuntime from "./LocalMiniappRuntime"
+import localSttFallbackCoordinator from "./LocalSttFallbackCoordinator"
+import {phonePhotoCoordinator} from "./PhonePhotoCoordinator"
+import {phoneStreamCoordinator} from "./PhoneStreamCoordinator"
+import {isGlassesConnected} from "./GlassesReadiness"
+import {useGlassesStore} from "../stores/glasses"
+import {useSettingsStore} from "../stores/settings"
+import {useAppStatusStore} from "../stores/apps"
+import {retirePendingSelectionOnPromotion} from "./PairingIdentity"
+import GlobalEventEmitter from "../utils/GlobalEventEmitter"
+import {asgCameraApi} from "./asg/asgCameraApi"
+
+let subs: Array<{remove: () => void}> = []
+
+export function startDeviceEventRouter(): void {
+  if (subs.length) return
+
+  // --- device state → engine stores ---
+
+  // Standalone WiFi status → glasses store.
+  subs.push(
+    BluetoothSdk.addListener("wifi_status_change", (event) => {
+      const {type: _type, ...wifi} = event
+      useGlassesStore.getState().setGlassesInfo({wifi})
+    }),
+  )
+
+  // Forward glasses Wi-Fi to miniapps (session.glasses.onWifi) from the STORE — the
+  // single source of truth — so every path converges here: wifi_status_change,
+  // onGlassesStatus, and BLE disconnect. Effective connectivity requires the glasses
+  // to be connected AND on Wi-Fi, so a disconnect correctly flips `connected` false.
+  subs.push({
+    remove: useGlassesStore.subscribe(
+      (s) => {
+        const connected = isGlassesConnected(s.connection) && s.wifi.state === "connected"
+        return {
+          connected,
+          ssid: s.wifi.state === "connected" ? s.wifi.ssid : undefined,
+          localIp: s.wifi.state === "connected" ? s.wifi.localIp : undefined,
+        }
+      },
+      (wifi) => localMiniappRuntime.forwardEvent("glasses_wifi", wifi),
+      {equalityFn: shallow},
+    ),
+  })
+
+  // Incremental battery status → glasses store + local miniapps.
+  subs.push(
+    BluetoothSdk.addListener("battery_status", (event) => {
+      const state = useGlassesStore.getState()
+      state.setBatteryInfo(event.level, event.charging, state.caseBatteryLevel, state.caseCharging)
+      localMiniappRuntime.forwardEvent("glasses_battery_update", {
+        type: "glasses_battery_update",
+        level: event.level,
+        charging: event.charging,
+        timestamp: event.timestamp ?? Date.now(),
+      })
+    }),
+  )
+
+  // Hotspot status → glasses store + event bus. engine's own gallerySyncService listens
+  // on the bus for these, so without this bridge engine's gallery sync is dead.
+  subs.push(
+    BluetoothSdk.addListener("hotspot_status_change", (event) => {
+      const enabled = event.state === "enabled"
+      const ssid = enabled ? event.ssid : ""
+      const password = enabled ? event.password : ""
+      const localIp = enabled ? event.localIp : ""
+      useGlassesStore.getState().setHotspotInfo(enabled, ssid, password, localIp)
+      // Always retarget the ASG camera client: on disable (or an event with no
+      // IP) fall back to the localhost default so later calls fail fast instead
+      // of hitting the previous network's stale glasses IP.
+      asgCameraApi.setServer(localIp || "localhost", 8089)
+      GlobalEventEmitter.emit("hotspot_status_change", {enabled, ssid, password, local_ip: localIp})
+    }),
+  )
+  subs.push(
+    BluetoothSdk.addListener("hotspot_error", (event) => {
+      GlobalEventEmitter.emit("hotspot_error", {error_message: event.errorMessage, timestamp: event.timestamp})
+    }),
+  )
+
+  // Glasses gallery content counts → event bus (consumed by gallerySyncService).
+  subs.push(
+    BluetoothSdk.addListener("gallery_status", (event) => {
+      GlobalEventEmitter.emit("gallery_status", {
+        photos: event.photos,
+        videos: event.videos,
+        total: event.total,
+        has_content: event.hasContent,
+        camera_busy: event.cameraBusy,
+      })
+    }),
+  )
+
+  // Hardware-originated setting changes (user changes a setting ON the glasses) → store.
+  // The inbound complement to GlassesSettingsSync (which only pushes store→device).
+  subs.push(
+    BluetoothSdk.addListener("save_setting", async (event) => {
+      const settings = useSettingsStore.getState()
+      // Damp the relay: native re-echoes some settings unconditionally (e.g.
+      // the identity block at every handleDeviceReady) — a same-value echo
+      // must not become a store write (persistence churn + change-push noise).
+      if (settings.getSetting(event.key) !== event.value) {
+        await settings.setSetting(event.key, event.value)
+      }
+      // Two-phase identity: a promoted default retires the pending selection
+      // marker. The rule lives with PairingIdentity (a no-op for other keys).
+      await retirePendingSelectionOnPromotion(event.key, event.value)
+    }),
+  )
+
+  // --- coordinators (owns()-gated) ---
+
+  // Phone-owned photo errors settle the in-flight long-poll fast (vs. timeout).
+  // Non-owned photo responses used to forward to the Cloud V1 photo pipeline via
+  // restComms; that relay was removed with Cloud V1 app end-of-life, so they drop.
+  // Wire v2 sends a short 4-hex BLE requestId; the coordinator maps it back to
+  // the cloud requestId (resolveCloudRequestId) before ownership checks.
+  subs.push(
+    BluetoothSdk.addListener("photo_response", (event) => {
+      const cloudRequestId = event.requestId ? phonePhotoCoordinator.resolveCloudRequestId(event.requestId) : ""
+      if (cloudRequestId && phonePhotoCoordinator.owns(cloudRequestId)) {
+        if (event.state === "error") {
+          phonePhotoCoordinator.handlePhotoError(
+            event.requestId ?? cloudRequestId,
+            event.errorCode ?? "GLASSES_ERROR",
+            event.errorMessage ?? "Glasses reported an error",
+          )
+        }
+      }
+    }),
+  )
+
+  // Phone-owned stream status / keep-alive → the stream coordinator. The Cloud V1 relay
+  // for non-owned streams was removed with Cloud V1 app end-of-life.
+  subs.push(
+    BluetoothSdk.addListener("stream_status", (event) => {
+      if (event.streamId && phoneStreamCoordinator.owns(event.streamId)) {
+        phoneStreamCoordinator.handleGlassesStatus(event)
+      }
+    }),
+  )
+  subs.push(
+    BluetoothSdk.addListener("keep_alive_ack", (event) => {
+      if (event.streamId && phoneStreamCoordinator.owns(event.streamId)) {
+        phoneStreamCoordinator.handleKeepAliveAck(event)
+      }
+    }),
+  )
+
+  // --- device input → local miniapps (forwardEvent is subscriber-gated; a no-op when
+  // no miniapp listens). The v1 SocketComms cloud legs for these were removed with
+  // the Cloud V1 ripout. ---
+
+  subs.push(
+    BluetoothSdk.addListener("button_press", (event) => {
+      localMiniappRuntime.forwardEvent("button_press", event)
+    }),
+  )
+  subs.push(
+    BluetoothSdk.addListener("touch_event", (event) => {
+      localMiniappRuntime.forwardEvent("touch_event", event)
+    }),
+  )
+  // G2 IMU accelerometer — payload already matches the miniapp AccelData shape.
+  subs.push(
+    BluetoothSdk.addListener("accel_event", (event) => {
+      localMiniappRuntime.forwardEvent("accel_event", {
+        x: event.x,
+        y: event.y,
+        z: event.z,
+        timestamp: typeof event.timestamp === "number" ? event.timestamp : Date.now(),
+      })
+    }),
+  )
+  // Head position — translate native {up:boolean} → SDK {position:"up"|"down"}.
+  subs.push(
+    BluetoothSdk.addListener("head_up", (event) => {
+      localMiniappRuntime.forwardEvent("head_up", {position: event.up ? "up" : "down", timestamp: Date.now()})
+    }),
+  )
+  // On-device STT transcripts → local miniapps only while the local engine is
+  // active (cloud fallback or an explicit forceLocal subscription). The runtime
+  // filters mixed local/cloud delivery per miniapp to avoid double-delivery.
+  // forwardEvent is subscriber-gated — a no-op when no miniapp listens.
+  // (Was MantleManager.handle_local_transcription; its offline-captions display branch
+  // went away with the pseudo captions renderer.)
+  subs.push(
+    BluetoothSdk.addListener("local_transcription", (event) => {
+      if (!localSttFallbackCoordinator.isActive()) return
+      const lang = event.transcribeLanguage ?? localSttFallbackCoordinator.getActiveLanguage() ?? "en-US"
+      localMiniappRuntime.forwardEvent(`transcription:${lang}`, event, "local")
+    }),
+  )
+
+  // --- glasses swipe-menu app launcher (G2) ---
+  subs.push(
+    BluetoothSdk.addListener("miniapp_selected", (event) => {
+      const packageName = event.packageName as string
+      if (!packageName) return
+      const app = useAppStatusStore.getState().apps.find((a) => a.packageName === packageName)
+      if (!app) return
+      // Toggle: stop if running, else start.
+      if (app.running) {
+        useAppStatusStore.getState().stop(packageName)
+      } else {
+        useAppStatusStore.getState().start(app, {skipNavigation: true})
+      }
+    }),
+  )
+}
+
+export function stopDeviceEventRouter(): void {
+  for (const sub of subs) sub.remove()
+  subs = []
+}