@mentra/engine 0.1.0-beta.0

package/src/services/GlassesReadiness.ts

@@ -0,0 +1,103 @@
+/**
+ * GlassesReadiness — the canonical connection predicates plus a wait-for-booted
+ * primitive.
+ *
+ * The predicates ("connected / booted / busy") are the single app-facing home
+ * for connection readiness: the app, the Connection coordinator, and the
+ * Pairing coordinator all read them through engine rather than re-deriving the
+ * same checks in three places. They are defined here over the btsdk
+ * `GlassesConnectionStatus` type through the public Bluetooth SDK package
+ * boundary.
+ *
+ * waitForGlassesReady is the new primitive those coordinators build on:
+ * "resolve once the glasses report fully booted, or false on timeout". It is
+ * host-store-agnostic — callers inject a snapshot getter + a subscribe fn — so
+ * it is unit-testable without a live device.
+ */
+import {
+  isBusyGlassesConnectionStatus,
+  isConnectedGlassesConnectionStatus,
+  isReadyGlassesConnectionStatus,
+  type GlassesConnectionStatus,
+} from "@mentra/bluetooth-sdk/types"
+
+import {BgTimer} from "../utils/timers"
+
+export type {GlassesConnectionStatus}
+
+/** True when the BLE link is established (regardless of boot state). */
+export function isGlassesConnected(connection: GlassesConnectionStatus): boolean {
+  return isConnectedGlassesConnectionStatus(connection)
+}
+
+/** True when connected AND the glasses OS has finished booting. */
+export function isGlassesReady(connection: GlassesConnectionStatus): boolean {
+  return isReadyGlassesConnectionStatus(connection)
+}
+
+/** True while the native link layer is mid scan / connect / bond. */
+export function isGlassesLinkLayerBusy(connection: GlassesConnectionStatus): boolean {
+  return isBusyGlassesConnectionStatus(connection)
+}
+
+export interface WaitForGlassesReadyOptions {
+  /** Current connection snapshot. */
+  getConnection: () => GlassesConnectionStatus
+  /** Subscribe to connection changes; returns an unsubscribe fn. */
+  subscribe: (listener: (connection: GlassesConnectionStatus) => void) => () => void
+  /** Resolve false after this many ms if still not ready. Default 35s — the pairing boot budget. */
+  timeoutMs?: number
+  /** Abort the wait early (e.g. the screen unmounted). Tears down the subscription + timer; resolves false. */
+  signal?: AbortSignal
+}
+
+/**
+ * Resolves true once the glasses report fully booted, false on timeout, or
+ * false if the optional signal aborts. Resolves immediately when already ready.
+ * Always tears down its subscription, timer, and abort listener before resolving.
+ */
+export function waitForGlassesReady(options: WaitForGlassesReadyOptions): Promise<boolean> {
+  const {getConnection, subscribe, timeoutMs = 35_000, signal} = options
+  return new Promise<boolean>((resolve) => {
+    if (signal?.aborted) {
+      resolve(false)
+      return
+    }
+    if (isGlassesReady(getConnection())) {
+      resolve(true)
+      return
+    }
+
+    let settled = false
+    let timer: number | null = null
+    let unsubscribe: (() => void) | null = null
+    let onAbort: (() => void) | null = null
+
+    const finish = (value: boolean) => {
+      if (settled) return
+      settled = true
+      if (unsubscribe) unsubscribe()
+      if (timer !== null) BgTimer.clearTimeout(timer)
+      if (onAbort && signal) signal.removeEventListener("abort", onAbort)
+      resolve(value)
+    }
+
+    if (signal) {
+      onAbort = () => finish(false)
+      signal.addEventListener("abort", onAbort)
+    }
+
+    unsubscribe = subscribe((connection) => {
+      if (isGlassesReady(connection)) finish(true)
+    })
+
+    if (settled) {
+      // subscribe() notified synchronously with a ready state, so finish() ran
+      // before unsubscribe was assigned and couldn't tear the subscription down.
+      // Do it now (and don't arm a timer).
+      unsubscribe()
+    } else {
+      timer = BgTimer.setTimeout(() => finish(isGlassesReady(getConnection())), timeoutMs)
+    }
+  })
+}

package/src/services/GlassesSettingsSync.ts

@@ -0,0 +1,134 @@
+/**
+ * Glasses settings sync — engine-owned. Keeps the connected glasses in sync with
+ * the phone's device settings (`BLUETOOTH_SETTING_KEYS`) over the bluetooth-sdk, so
+ * `engine.glasses.settings.set()` (and any other settings-store write) reaches the
+ * device for ANY host — not just the first-party Mentra app, where this used to live
+ * in MantleManager.
+ *
+ * Two triggers:
+ *   1. on change — push the keys that changed.
+ *   2. on (re)connect — push the FULL set, so a freshly-connected device gets the
+ *      phone's current settings (not just future changes).
+ *
+ * Started by `engine.start()`. Idempotent.
+ */
+import {shallow} from "zustand/shallow"
+
+import BluetoothSdk from "@mentra/bluetooth-sdk/internal"
+import {useSettingsStore, PAIRING_IDENTITY_KEYS} from "../stores/settings"
+import {useGlassesStore} from "../stores/glasses"
+import {createDebouncedPatchFlusher} from "../utils/debouncedPatch"
+import {isGlassesConnected} from "./GlassesReadiness"
+
+/**
+ * Change-pushes are debounced (300ms) and merged so a burst of setSetting
+ * calls becomes ONE BLE write (wire v2 keeps BLE JSON small and infrequent).
+ * The full on-connect/seed pushes stay direct — callers await their ordering.
+ */
+const flushBluetoothSettingsPatch = createDebouncedPatchFlusher<Record<string, unknown>>((patch) => {
+  // Settings can change while the glasses are disconnected — a native
+  // rejection must not surface as an unhandled promise rejection.
+  void Promise.resolve(BluetoothSdk.updateBluetoothSettings(patch)).catch((error) => {
+    console.warn("GlassesSettingsSync: updateBluetoothSettings failed:", error)
+  })
+}, 300)
+
+/**
+ * The changed-keys diff for the change-push, MINUS the pairing-identity keys.
+ * Identity is native-authoritative (promoted on pairing success, cleared on
+ * forget, echoed down via save_setting) and reaches native only through the
+ * explicit full seeds. Pushing identity from the change subscription would
+ * close a feedback loop: native echo → store setSetting → change-push →
+ * native apply → echo…, which self-sustains the moment two different values
+ * are in flight (e.g. a boot demotion crossing a native promotion) and flaps
+ * the pairing UI.
+ */
+export function diffBluetoothSettingsForPush(
+  settings: Record<string, unknown>,
+  previous: Record<string, unknown>,
+): Record<string, unknown> {
+  const changed: Record<string, unknown> = {}
+  for (const key in settings) {
+    if (PAIRING_IDENTITY_KEYS.includes(key)) continue
+    if (settings[key] !== previous[key]) changed[key] = settings[key]
+  }
+  return changed
+}
+
+/** A copy of the settings record without the pairing-identity keys. */
+export function stripPairingIdentity(settings: Record<string, unknown>): Record<string, unknown> {
+  const stripped: Record<string, unknown> = {}
+  for (const key in settings) {
+    if (PAIRING_IDENTITY_KEYS.includes(key)) continue
+    stripped[key] = settings[key]
+  }
+  return stripped
+}
+
+let unsubChange: (() => void) | null = null
+let unsubConnect: (() => void) | null = null
+
+/**
+ * Push the FULL current device-settings set — identity included — to native.
+ * This is the explicit identity SEED, for the flows where native genuinely
+ * needs the phone's persisted identity BEFORE it can act: the device-store
+ * hydration at start, the pre-connect seed (connectDefault targets the seeded
+ * identity), the post-demotion re-push, and the abandon re-seed.
+ */
+export async function pushAllBluetoothSettings(): Promise<void> {
+  // Returns the native write promise so callers can await the seed before the
+  // connect handshake replays settings to the glasses (otherwise the handshake
+  // can race ahead and replay stale native settings).
+  await BluetoothSdk.updateBluetoothSettings(useSettingsStore.getState().getBluetoothSettings())
+}
+
+/**
+ * Push the device-settings set MINUS the pairing identity. The on-connect
+ * replay uses this: while connected, NATIVE owns the identity (it promotes at
+ * device-ready and echoes down), and the JS snapshot can be mid-relay stale —
+ * on Mentra Live "connected" lands together with device-ready, and a full
+ * replay raced the promotion echoes and overwrote the just-promoted identity
+ * with pre-promotion empties (wiping the pairing it had just made).
+ */
+export async function pushDeviceSettingsOnConnect(): Promise<void> {
+  await BluetoothSdk.updateBluetoothSettings(stripPairingIdentity(useSettingsStore.getState().getBluetoothSettings()))
+}
+
+export function startGlassesSettingsSync(): void {
+  if (unsubChange || unsubConnect) return
+
+  // 1. Push only the keys that changed (matching the prior MantleManager sync).
+  // Pairing identity is excluded — see diffBluetoothSettingsForPush.
+  unsubChange = useSettingsStore.subscribe(
+    (state) => state.getBluetoothSettings(),
+    (settings: Record<string, unknown>, previous: Record<string, unknown>) => {
+      const changed = diffBluetoothSettingsForPush(settings, previous)
+      if (Object.keys(changed).length > 0) {
+        flushBluetoothSettingsPatch(changed)
+      }
+    },
+    {equalityFn: shallow},
+  )
+
+  // 2. Push the device settings whenever the glasses transition to connected —
+  // identity EXCLUDED: native owns the identity it just promoted, and a full
+  // replay here raced the promotion echoes (see pushDeviceSettingsOnConnect).
+  let wasConnected = isGlassesConnected(useGlassesStore.getState().connection)
+  unsubConnect = useGlassesStore.subscribe(() => {
+    const connected = isGlassesConnected(useGlassesStore.getState().connection)
+    if (connected && !wasConnected) {
+      // Background sync: log-and-continue if the device drops right after connect.
+      void pushDeviceSettingsOnConnect().catch((error) => {
+        console.warn("GlassesSettingsSync: on-connect settings push failed:", error)
+      })
+    }
+    wasConnected = connected
+  })
+}
+
+export function stopGlassesSettingsSync(): void {
+  unsubChange?.()
+  unsubConnect?.()
+  unsubChange = null
+  unsubConnect = null
+}

package/src/services/GlassesStatusProjection.ts

@@ -0,0 +1,73 @@
+/**
+ * Glasses status projection — engine-owned. Subscribes to the native bluetooth-sdk
+ * status events and projects them into the engine device stores, so engine's own
+ * services (which react to those stores) work for ANY host — not just the first-party
+ * Mentra app, where this used to live in MantleManager.
+ *
+ * This is the INBOUND mirror of GlassesSettingsSync: that pushes the settings store
+ * OUT to the device; this pulls device status IN to the stores. It's the feed that
+ * the rest of the engine runtime depends on (MicStateCoordinator, the settings-sync
+ * on-connect trigger, the facade read-models all read these stores).
+ *
+ * Started by `engine.start()`. Idempotent.
+ */
+import BluetoothSdk from "@mentra/bluetooth-sdk/internal"
+import {useCoreStore} from "../stores/core"
+import {useGlassesStore} from "../stores/glasses"
+import localMiniappRuntime from "./LocalMiniappRuntime"
+
+let unsubs: Array<() => void> = []
+let projectionRunId = 0
+
+export function startGlassesStatusProjection(): void {
+  if (unsubs.length) return
+
+  const runId = ++projectionRunId
+  let bluetoothEventSeen = false
+  let glassesEventSeen = false
+
+  void BluetoothSdk.getBluetoothStatus()
+    .then((status) => {
+      if (runId !== projectionRunId || bluetoothEventSeen) return
+      useCoreStore.getState().setCoreInfo(status)
+    })
+    .catch((error) => {
+      console.warn("GlassesStatusProjection: getBluetoothStatus failed", error)
+    })
+
+  void BluetoothSdk.getGlassesStatus()
+    .then((status) => {
+      if (runId !== projectionRunId || glassesEventSeen) return
+      useGlassesStore.getState().setGlassesInfo(status)
+    })
+    .catch((error) => {
+      console.warn("GlassesStatusProjection: getGlassesStatus failed", error)
+    })
+
+  // Bluetooth-adapter status -> core store.
+  unsubs.push(
+    BluetoothSdk.onBluetoothStatus((changed) => {
+      bluetoothEventSeen = true
+      useCoreStore.getState().setCoreInfo(changed)
+    }),
+  )
+
+  // Glasses status -> glasses store (+ forward to local miniapps; clear any stale
+  // OTA-available flag on disconnect).
+  unsubs.push(
+    BluetoothSdk.onGlassesStatus((changed) => {
+      glassesEventSeen = true
+      useGlassesStore.getState().setGlassesInfo(changed)
+      localMiniappRuntime.forwardEvent("glasses_connection_state", changed)
+      if (changed.connection?.state === "disconnected") {
+        useGlassesStore.getState().setOtaUpdateAvailable(null)
+      }
+    }),
+  )
+}
+
+export function stopGlassesStatusProjection(): void {
+  projectionRunId++
+  unsubs.forEach((unsub) => unsub())
+  unsubs = []
+}

package/src/services/HeadingService.ts

@@ -0,0 +1,98 @@
+/**
+ * HeadingService
+ *
+ * Thin singleton over the native compass stream exposed by `crust`.
+ * Works on both Android and iOS via CLLocationManager (iOS) / SensorManager (Android).
+ *
+ * Reference-counted: the underlying SensorManager subscription starts on
+ * the first listener and stops when the last one unsubscribes. Late
+ * subscribers get the most recently emitted heading replayed
+ * synchronously so the UI doesn't have to wait for the next sensor tick.
+ */
+
+import CrustModule from "@mentra/crust"
+
+const LOG_TAG = "HEADING_SERVICE"
+
+export type HeadingListener = (degrees: number) => void
+
+class HeadingService {
+  private static instance: HeadingService | null = null
+  private listeners = new Set<HeadingListener>()
+  private nativeSub: {remove: () => void} | null = null
+  private lastDegrees: number | null = null
+  private nativeStarted = false
+
+  private constructor() {}
+
+  public static getInstance(): HeadingService {
+    if (!HeadingService.instance) {
+      HeadingService.instance = new HeadingService()
+    }
+    return HeadingService.instance
+  }
+
+  public addListener(listener: HeadingListener): () => void {
+    this.listeners.add(listener)
+    if (!this.nativeStarted) {
+      this.startNative()
+    }
+    if (this.lastDegrees != null) {
+      try {
+        listener(this.lastDegrees)
+      } catch (err) {
+        console.error(`${LOG_TAG}: listener threw on replay`, err)
+      }
+    }
+    return () => {
+      this.listeners.delete(listener)
+      if (this.listeners.size === 0) {
+        this.stopNative()
+      }
+    }
+  }
+
+  private async startNative(): Promise<void> {
+    if (this.nativeStarted) return
+    this.nativeStarted = true
+    this.nativeSub = CrustModule.addListener("onHeading", (data) => {
+      const deg = Number(data.degrees)
+      if (!Number.isFinite(deg)) return
+      this.lastDegrees = deg
+      this.listeners.forEach((l) => {
+        try {
+          l(deg)
+        } catch (err) {
+          console.error(`${LOG_TAG}: listener threw`, err)
+        }
+      })
+    })
+    try {
+      const result = await CrustModule.startHeading()
+      if (!result.ok) {
+        console.warn(`${LOG_TAG}: startHeading failed — ${result.error}`)
+      } else {
+        console.log(`${LOG_TAG}: started`)
+      }
+    } catch (err) {
+      console.error(`${LOG_TAG}: startHeading threw`, err)
+    }
+  }
+
+  private async stopNative(): Promise<void> {
+    if (!this.nativeStarted) return
+    this.nativeStarted = false
+    this.nativeSub?.remove()
+    this.nativeSub = null
+    this.lastDegrees = null
+    try {
+      await CrustModule.stopHeading()
+      console.log(`${LOG_TAG}: stopped`)
+    } catch (err) {
+      console.error(`${LOG_TAG}: stopHeading threw`, err)
+    }
+  }
+}
+
+const headingService = HeadingService.getInstance()
+export default headingService