@mentra/engine 0.1.0-beta.0

package/src/facades/glasses.ts

@@ -0,0 +1,206 @@
+/**
+ * glasses facade — the core `engine.glasses.*` surface: connection actions (over
+ * the bluetooth-sdk passthrough), a curated status/info read-model (projected from
+ * the engine-owned glasses store), capabilities (from the model table), and the
+ * discrete input events. The `wifi` sub-facade is nested here.
+ *
+ * Read-models project the raw glasses store into the stable shape OEM UIs consume,
+ * so the device store's field layout doesn't leak into every screen.
+ */
+// Internal btsdk surface — connectSimulated/reconnect/controller live on the full
+// surface, not the public entry. Relative path (the alias doesn't resolve in engine's
+// standalone build); jest moduleNameMapper + tsconfig both resolve it.
+import BluetoothSdk from "@mentra/bluetooth-sdk/internal"
+import type {ButtonPressEvent, TouchEvent} from "@mentra/bluetooth-sdk/internal"
+import {useGlassesStore} from "../stores/glasses"
+import {useSettingsStore, SETTINGS} from "../stores/settings"
+import {hasDefaultDevice} from "../services/DeviceStoreHydration"
+import {projectPairingIdentity} from "../services/PairingIdentity"
+import {isGlassesConnected, isGlassesReady} from "../services/GlassesReadiness"
+import {pushAllBluetoothSettings} from "../services/GlassesSettingsSync"
+import {getModelCapabilities, type DeviceTypes} from "../types"
+import {glassesWifi} from "./glassesWifi"
+import {glassesSettings} from "./glassesSettings"
+
+function projectStatus() {
+  const s = useGlassesStore.getState()
+  return {
+    state: s.connection.state,
+    fullyBooted: isGlassesReady(s.connection),
+    battery: s.batteryLevel,
+    charging: s.charging,
+    case: {battery: s.caseBatteryLevel, charging: s.caseCharging, open: s.caseOpen, removed: s.caseRemoved},
+    signal: s.signalStrength,
+    micEnabled: s.micEnabled,
+    vadEnabled: s.voiceActivityDetectionEnabled,
+    btClassic: s.bluetoothClassicConnected,
+  }
+}
+
+function projectControllerStatus() {
+  const s = useGlassesStore.getState()
+  return {
+    connected: s.controllerConnected,
+    fullyBooted: s.controllerFullyBooted,
+    battery: s.controllerBatteryLevel,
+    signal: s.controllerSignalStrength,
+  }
+}
+
+function projectInfo() {
+  const s = useGlassesStore.getState()
+  return {
+    model: s.deviceModel,
+    style: s.style,
+    color: s.color,
+    bluetoothName: s.bluetoothName,
+    firmwareVersion: s.firmwareVersion,
+    mtkFirmware: s.mtkFirmwareVersion,
+    besFirmware: s.besFirmwareVersion,
+    appVersion: s.appVersion,
+    androidVersion: s.androidVersion,
+    serialNumber: s.serialNumber,
+    buildNumber: s.buildNumber,
+    btMac: s.bluetoothMacAddress,
+    leftMac: s.leftMacAddress,
+    rightMac: s.rightMacAddress,
+    // Copy: the snapshot must not hand callers a mutable reference into the store.
+    wifi: {...s.wifi},
+  }
+}
+
+export type GlassesStatusSnapshot = ReturnType<typeof projectStatus>
+export type ControllerStatusSnapshot = ReturnType<typeof projectControllerStatus>
+export type GlassesInfoSnapshot = ReturnType<typeof projectInfo>
+
+export const glasses = {
+  // --- connection (bluetooth-sdk passthrough) ---
+  /**
+   * Reconnect the default wearable. Seeds the phone's current device settings to
+   * native first, so they're primed before the connect handshake replays them to
+   * the glasses (this used to be a host-side step before `connectDefault`).
+   */
+  connectDefault: async (): Promise<void> => {
+    await pushAllBluetoothSettings()
+    return BluetoothSdk.connectDefault()
+  },
+  disconnect: (): Promise<void> => BluetoothSdk.disconnect(),
+  forget: (): Promise<void> => BluetoothSdk.forget(),
+  /** Connect to a specific (discovered) device. */
+  connect: async (...args: Parameters<typeof BluetoothSdk.connect>): Promise<void> => {
+    await pushAllBluetoothSettings()
+    return BluetoothSdk.connect(...args)
+  },
+  /** Connect the built-in simulated glasses (dev/testing). */
+  connectSimulated: (): Promise<void> => BluetoothSdk.connectSimulated(),
+  /** Set a device as the `connectDefault()` target. */
+  setDefault: (...args: Parameters<typeof BluetoothSdk.setDefaultDevice>) => BluetoothSdk.setDefaultDevice(...args),
+  /**
+   * Reconnect to the saved default glasses. Resolves `false` when there's nothing to
+   * reconnect to (no default paired) or the connect attempt fails (e.g. BLE powered
+   * off), `true` when already connected or after kicking off the connect. Never
+   * rejects — the boolean contract holds. The host gates connectivity/permissions
+   * (its UI) before calling.
+   */
+  reconnect: async (): Promise<boolean> => {
+    const defaultWearable = useSettingsStore.getState().getSetting(SETTINGS.default_wearable.key)
+    if (!defaultWearable) return false
+    if (isGlassesConnected(useGlassesStore.getState().connection)) return true
+    try {
+      await pushAllBluetoothSettings()
+      await BluetoothSdk.connectDefault()
+    } catch (error) {
+      console.warn("engine.glasses.reconnect failed:", error)
+      return false
+    }
+    return true
+  },
+  /** True when no glasses has ever been paired NOR selected (the pairing-identity
+   * lifecycle is in its `none` state) — e.g. to route a first-run host into the
+   * pairing/onboarding flow. A pending selection is not "first" — the host should
+   * offer finish-pairing (see `engine.pairing.identity()`). */
+  isFirstPairing: (): boolean => projectPairingIdentity().kind === "none",
+  /**
+   * True when the SDK has an actual default DEVICE to reconnect to. Distinct from
+   * `default_wearable` (a model string that a pending or orphaned selection can
+   * hold without any paired device): connectDefault() throws without a device, so
+   * hosts should route to the pairing flow when this is false.
+   *
+   * Hydration-aware: awaits the device-store seed internally, so a cold-start
+   * read can't see a false "absent" for genuinely-paired users. Rejects if
+   * hydration failed — callers guarding destructive or routing decisions must
+   * fail open (treat as "has a device").
+   */
+  hasDefaultDevice: (): Promise<boolean> => hasDefaultDevice(),
+
+  // --- read-model (projected from the engine-owned glasses store) ---
+  status: (): GlassesStatusSnapshot => projectStatus(),
+  onStatus: (cb: (status: GlassesStatusSnapshot) => void): (() => void) => {
+    // Dedupe: the glasses store updates on many fields; only fire when the
+    // projected status snapshot actually changes.
+    let last = JSON.stringify(projectStatus())
+    return useGlassesStore.subscribe(() => {
+      const snap = projectStatus()
+      const key = JSON.stringify(snap)
+      if (key === last) return
+      last = key
+      cb(snap)
+    })
+  },
+  info: (): GlassesInfoSnapshot => projectInfo(),
+  onInfo: (cb: (info: GlassesInfoSnapshot) => void): (() => void) => {
+    let last = JSON.stringify(projectInfo())
+    return useGlassesStore.subscribe(() => {
+      const snap = projectInfo()
+      const key = JSON.stringify(snap)
+      if (key === last) return
+      last = key
+      cb(snap)
+    })
+  },
+  capabilities: () => getModelCapabilities(useGlassesStore.getState().deviceModel as DeviceTypes),
+  /** Ask the glasses to report fresh firmware/version info (updates the store). */
+  requestVersionInfo: () => BluetoothSdk.requestVersionInfo(),
+
+  // --- discrete input events (passthrough listeners) ---
+  onButtonPress: (cb: (event: ButtonPressEvent) => void): (() => void) => {
+    const sub = BluetoothSdk.addListener("button_press", cb)
+    return () => sub.remove()
+  },
+  onTouchGesture: (cb: (event: TouchEvent) => void): (() => void) => {
+    const sub = BluetoothSdk.addListener("touch_event", cb)
+    return () => sub.remove()
+  },
+
+  // --- ring controller (optional input device) ---
+  controller: {
+    connectDefault: (): Promise<void> => BluetoothSdk.connectDefaultController(),
+    disconnect: (): Promise<void> => BluetoothSdk.disconnectController(),
+    forget: (): Promise<void> => BluetoothSdk.forgetController(),
+    status: (): ControllerStatusSnapshot => projectControllerStatus(),
+    onStatus: (cb: (status: ControllerStatusSnapshot) => void): (() => void) => {
+      let last = JSON.stringify(projectControllerStatus())
+      return useGlassesStore.subscribe(() => {
+        const snap = projectControllerStatus()
+        const key = JSON.stringify(snap)
+        if (key === last) return
+        last = key
+        cb(snap)
+      })
+    },
+  },
+
+  // --- audio (glasses media-volume + own-app playback hint) ---
+  audio: {
+    /** Read the glasses' current media volume. */
+    getMediaVolume: () => BluetoothSdk.getGlassesMediaVolume(),
+    /** Set the glasses' media volume. */
+    setMediaVolume: (level: number) => BluetoothSdk.setGlassesMediaVolume(level),
+    /** Tell native whether THIS app is currently playing audio (for ducking). */
+    setOwnAppPlaying: (playing: boolean): Promise<void> => BluetoothSdk.setOwnAppAudioPlaying(playing),
+  },
+
+  // --- sub-facades ---
+  wifi: glassesWifi,
+  settings: glassesSettings,
+}

package/src/facades/glassesSettings.ts

@@ -0,0 +1,56 @@
+/**
+ * glasses.settings facade — `engine.glasses.settings`: the keyed DEVICE-settings
+ * surface (brightness, head-up angle, dashboard, camera/button, sensing, …). These
+ * are the settings the engine store auto-syncs to the glasses over the bluetooth-sdk
+ * (`BLUETOOTH_SETTING_KEYS`), so `set()` both persists and pushes to the device.
+ *
+ * Distinct from `engine.settings` (user/app prefs): this is scoped to the
+ * hardware-facing keys, minus the internal sync keys (auth/token) that aren't
+ * user-tunable device settings.
+ */
+import {useSettingsStore, SETTINGS, BLUETOOTH_SETTING_KEYS} from "../stores/settings"
+
+// Keys carried on BLUETOOTH_SETTING_KEYS for the device handshake that are NOT
+// user-tunable settings — auth, device/controller IDENTITY (set by pairing), and
+// internal RUNTIME flags. Kept out of the OEM-facing `available()` surface.
+const INTERNAL_KEYS = new Set<string>([
+  // auth
+  SETTINGS.core_token.key,
+  SETTINGS.auth_email.key,
+  // glasses + controller identity (managed by pairing, not the user)
+  SETTINGS.pending_wearable.key,
+  SETTINGS.default_wearable.key,
+  SETTINGS.device_name.key,
+  SETTINGS.device_address.key,
+  SETTINGS.pending_controller.key,
+  SETTINGS.default_controller.key,
+  SETTINGS.controller_device_name.key,
+  SETTINGS.controller_address.key,
+  // internal runtime flags
+  SETTINGS.local_stt_fallback_active.key,
+])
+const DEVICE_KEYS = BLUETOOTH_SETTING_KEYS.filter((k) => !INTERNAL_KEYS.has(k))
+
+// Copy: object/array-valued settings must not hand callers a mutable reference
+// into the store (mutations would bypass persistence + Bluetooth sync).
+function copySettingValue<T>(value: T): T {
+  if (Array.isArray(value)) return [...value] as T
+  if (value && typeof value === "object") return {...(value as object)} as T
+  return value
+}
+
+export const glassesSettings = {
+  /** Read a device setting by key (object/array values are shallow copies). */
+  get: <T = unknown>(key: string): T | undefined =>
+    copySettingValue(useSettingsStore.getState().getSetting(key) as T | undefined),
+  /** Write a device setting — persists and auto-syncs to the connected glasses. */
+  set: <T = unknown>(key: string, value: T) => useSettingsStore.getState().setSetting(key, value),
+  /** Subscribe to changes for one device-setting key; returns an unsubscribe. */
+  onChanged: <T = unknown>(key: string, cb: (value: T | undefined) => void): (() => void) =>
+    useSettingsStore.subscribe((s) => s.getSetting(key) as T | undefined, cb),
+  /** The schema descriptor for a key (type, default, options…), or undefined. */
+  descriptor: (key: string) => SETTINGS[key],
+  /** The device-setting keys synced to the glasses (excludes internal sync keys). */
+  // Copy: callers must not be able to mutate the module-level key list.
+  available: (): string[] => [...DEVICE_KEYS],
+}

package/src/facades/glassesWifi.ts

@@ -0,0 +1,68 @@
+/**
+ * glasses.wifi facade — the first typed engine facade over the bluetooth-sdk
+ * passthrough, and the reference pattern the rest of the (A) host API copies.
+ *
+ * A facade wraps the raw `@mentra/bluetooth-sdk` surface into a small, typed,
+ * device-agnostic API (the `doX()` action shape here; `getX()`/`onX()` read-models
+ * come with domains that own their state). The host UI calls `engine.glasses.wifi.*`
+ * instead of importing bluetooth-sdk directly — that's the native-import boundary
+ * the engine is built around.
+ *
+ * `connect()` propagates bluetooth-sdk's coded errors unchanged so callers keep
+ * their existing error mapping. The `status()`/`onStatus()` read-model reads the
+ * glasses-state store engine now owns (wifi status is derived there from the
+ * device's connection info).
+ */
+import BluetoothSdk from "@mentra/bluetooth-sdk"
+import type {WifiSearchResult, WifiStatus} from "@mentra/bluetooth-sdk"
+import {useGlassesStore} from "../stores/glasses"
+
+export type {WifiSearchResult, WifiStatus}
+
+export const glassesWifi = {
+  /** Scan for nearby wifi networks. Request/response — resolves with the results. */
+  scan(): Promise<WifiSearchResult[]> {
+    return BluetoothSdk.requestWifiScan()
+  },
+
+  /**
+   * Subscribe to streamed scan results: the glasses report networks one by one
+   * while a scan runs, so callers can render them as they arrive instead of
+   * waiting for the final `scan()` result. Returns an unsubscribe.
+   */
+  onScanResult(cb: (networks: WifiSearchResult[]) => void): () => void {
+    const sub = BluetoothSdk.addListener("wifi_scan_result", (event) => {
+      cb(event.networks)
+    })
+    return () => sub.remove()
+  },
+
+  /**
+   * Send wifi credentials to the glasses. Resolves on success; rejects with the
+   * bluetooth-sdk coded error (`bluetooth_powered_off`, `request_timeout`, …) on
+   * failure, propagated unchanged for the caller to map.
+   */
+  async connect(ssid: string, password: string): Promise<void> {
+    await BluetoothSdk.sendWifiCredentials(ssid, password)
+  },
+
+  /** Forget a saved network on the glasses. */
+  async forget(ssid: string): Promise<void> {
+    await BluetoothSdk.forgetWifiNetwork(ssid)
+  },
+
+  /** The glasses' current wifi connection status (snapshot). */
+  status(): WifiStatus {
+    // Copy: the snapshot must not hand callers a mutable reference into the store.
+    return {...useGlassesStore.getState().wifi}
+  },
+
+  /** Subscribe to wifi-status changes (current, previous); returns an unsubscribe. */
+  onStatus(cb: (status: WifiStatus, previous: WifiStatus) => void): () => void {
+    // Copy: like status(), never publish the store's live wifi objects to listeners.
+    return useGlassesStore.subscribe(
+      (s) => s.wifi,
+      (wifi, previous) => cb({...wifi}, {...previous}),
+    )
+  },
+}

package/src/facades/miniapps.ts

@@ -0,0 +1,55 @@
+/**
+ * miniapps facade — `engine.miniapps`: miniapp lifecycle over the engine-owned
+ * apps store. Thin forwarding (args via Parameters<>), so the facade never drifts
+ * from the store's actions.
+ *
+ * The miniapp WebView is a HOST component (engine ships the bridge, not the view) —
+ * the bridge primitives (`buildMiniappGlobalsScript`, `buildMentraUiShim`, the
+ * MentraJS router) are exported from `@mentra/engine` directly; the host mounts a
+ * `<WebView>` wired to them. This facade is the lifecycle half.
+ */
+import {useAppStatusStore} from "../stores/apps"
+import type {ClientApp} from "../types"
+
+type AppsState = ReturnType<typeof useAppStatusStore.getState>
+
+export const miniapps = {
+  /** All installed miniapps (snapshot). */
+  // Copy: the snapshot must not hand callers a mutable reference into the store.
+  list: (): ClientApp[] => [...useAppStatusStore.getState().apps],
+  /** Subscribe to the installed-app set; fires only when it changes. Returns an unsubscribe. */
+  onChanged: (cb: (apps: ClientApp[]) => void): (() => void) => {
+    let last = JSON.stringify(useAppStatusStore.getState().apps)
+    return useAppStatusStore.subscribe(() => {
+      const apps = useAppStatusStore.getState().apps
+      const key = JSON.stringify(apps)
+      if (key === last) return
+      last = key
+      cb(apps)
+    })
+  },
+
+  /** Re-fetch the installed-app list from the backend. */
+  refresh: () => useAppStatusStore.getState().refresh(),
+  /** Start (foreground) a miniapp. */
+  start: (...args: Parameters<AppsState["start"]>) => useAppStatusStore.getState().start(...args),
+  /** Stop a miniapp. */
+  stop: (...args: Parameters<AppsState["stop"]>) => useAppStatusStore.getState().stop(...args),
+  /** Bring a running miniapp to the foreground. */
+  setForeground: (...args: Parameters<AppsState["setForeground"]>) =>
+    useAppStatusStore.getState().setForeground(...args),
+  /** Clear the current foreground miniapp. */
+  clearForeground: () => useAppStatusStore.getState().clearForeground(),
+  /** Stop all running miniapps. */
+  stopAll: () => useAppStatusStore.getState().stopAll(),
+  /** Install a miniapp from a bundle URL. */
+  install: (...args: Parameters<AppsState["install"]>) => useAppStatusStore.getState().install(...args),
+  /** Uninstall a miniapp. */
+  uninstall: (...args: Parameters<AppsState["uninstall"]>) => useAppStatusStore.getState().uninstall(...args),
+  /** Persist a miniapp's captured screenshot (the switcher/card preview). */
+  saveScreenshot: (...args: Parameters<AppsState["saveScreenshot"]>) =>
+    useAppStatusStore.getState().saveScreenshot(...args),
+  /** Hide/show a miniapp on the home surfaces. */
+  setHiddenStatus: (...args: Parameters<AppsState["setHiddenStatus"]>) =>
+    useAppStatusStore.getState().setHiddenStatus(...args),
+}

package/src/facades/notifications.ts

@@ -0,0 +1,15 @@
+/**
+ * notifications facade — `engine.notifications`: inbound alerts engine→host. The
+ * OEM subscribes and renders them however it likes (modal, toast, banner). Today:
+ * miniapp crashloop; version-incompatible miniapp and persistent connection loss
+ * land as their detectors are wired into the emitter.
+ */
+import {islandNotifications, type IslandNotification} from "../services/NotificationsEmitter"
+
+export type {IslandNotification, IslandNotificationKind} from "../services/NotificationsEmitter"
+
+export const notifications = {
+  /** Subscribe to engine-raised notifications; returns an unsubscribe. */
+  onNotification: (cb: (notification: IslandNotification) => void): (() => void) =>
+    islandNotifications.subscribe(cb),
+}

package/src/facades/ota.ts

@@ -0,0 +1,174 @@
+/**
+ * ota facade — `engine.ota`: the OEM-facing OTA read/observe surface. Engine's
+ * OtaService projects the glasses' OTA BLE events into the engine store; this facade
+ * exposes the snapshot + change subscriptions the host renders its update prompt and
+ * progress UI from. No host-injected UI — the host owns all alerts/navigation/i18n.
+ *
+ * Availability checks live in engine. Install orchestration lives in engine too:
+ * `installSession` fronts the OtaInstallCoordinator state machine (WP 8B) — the host
+ * progress screen is a pure renderer over its snapshot + attach/detach/retry/finish.
+ */
+import BluetoothSdk from "@mentra/bluetooth-sdk/internal"
+import type {OtaProgress, OtaProgressStatus, OtaStatus, OtaUpdateInfo} from "@mentra/bluetooth-sdk/internal"
+import {isGlassesConnected, useGlassesStore} from "../stores/glasses"
+import {getAsgOtaVersionUrl} from "../services/asgOtaVersionUrl"
+import {otaInstallCoordinator, type OtaInstallSnapshot} from "../services/OtaInstallCoordinator"
+import {
+  checkCurrentGlassesForUpdate,
+  type OtaCheckCurrentGlassesOptions,
+  type OtaCheckCurrentGlassesResult,
+} from "../services/OtaUpdateCheckService"
+
+function projectSnapshot() {
+  const s = useGlassesStore.getState()
+  return {
+    connected: isGlassesConnected(s.connection),
+    buildNumber: s.buildNumber || null,
+    mtkFirmwareVersion: s.mtkFirmwareVersion || null,
+    besFirmwareVersion: s.besFirmwareVersion || null,
+    wifiConnected: s.wifi.state === "connected",
+    wifiStatusKnown: s.wifiStatusKnown,
+    manifestUrl: getAsgOtaVersionUrl(s.otaVersionUrl, s.buildNumber),
+    updateAvailable: s.otaUpdateAvailable,
+    status: s.otaStatus,
+    legacyProgress: s.otaProgress,
+    inProgress: s.otaInProgress,
+    mtkUpdatedThisSession: s.mtkUpdatedThisSession,
+  }
+}
+
+export type OtaSnapshot = ReturnType<typeof projectSnapshot>
+export type {
+  OtaProgress,
+  OtaProgressStatus,
+  OtaStatus,
+  OtaUpdateInfo,
+  OtaInstallSnapshot,
+  OtaCheckCurrentGlassesOptions,
+  OtaCheckCurrentGlassesResult,
+}
+
+export const ota = {
+  // --- actions ---
+  /**
+   * Start the firmware install with the resolved OTA manifest URL. Progress lands on
+   * `status()`/`onStatus()`. (The host resolves the manifest URL — dev-override/env/prod
+   * resolution stays with the OTA config; the host-side stuck/retry watchdog is its own
+   * resilience layer on top of this command.)
+   */
+  install: (...args: Parameters<typeof BluetoothSdk.startOtaUpdate>) => BluetoothSdk.startOtaUpdate(...args),
+  // Deferred: this facade entry was intended to become the engine-owned retry/check
+  // action, but BluetoothSdk.checkForOtaUpdate() only returns a boolean. Exposing it
+  // here would make callers think the rich otaUpdateAvailable read model is refreshed,
+  // while the original view still depends on the host-side manifest compare to build
+  // versionName/updates/totalSize. Keep that behavior unchanged until the whole rich
+  // availability check moves into engine.
+  // retry: () => BluetoothSdk.checkForOtaUpdate(),
+  /**
+   * Keep glasses awake while an OTA session is actively progressing.
+   * @deprecated Legacy progress route (build < 37) only — removed with WP 8D.
+   */
+  ping: () => BluetoothSdk.ping(),
+  /** Resolve and compare the current glasses against the OTA manifest, then update the OTA snapshot. */
+  checkForUpdates: (options?: OtaCheckCurrentGlassesOptions) => checkCurrentGlassesForUpdate(options),
+  /** Clear the available-update prompt state. */
+  clearUpdateAvailable: () => useGlassesStore.getState().setOtaUpdateAvailable(null),
+  /** Clear active progress/status before entering a fresh install flow. */
+  clearProgress: () => {
+    const store = useGlassesStore.getState()
+    store.setOtaProgress(null)
+    store.setOtaStatus(null)
+  },
+  /**
+   * Replace the pending update sequence after an in-flow firmware revalidation.
+   * Kept as a named OTA policy operation so host screens do not mutate the raw
+   * glasses store.
+   * @deprecated Legacy progress route (build < 37) only — removed with WP 8D.
+   */
+  replacePendingUpdateSequence: (updates: OtaUpdateInfo["updates"]): OtaUpdateInfo | null => {
+    const store = useGlassesStore.getState()
+    const current = store.otaUpdateAvailable
+    if (!current) return null
+    const next = {...current, updates}
+    store.setOtaUpdateAvailable(next)
+    return next
+  },
+  /**
+   * Clear stale build metadata before returning to the update-check screen.
+   * This forces the next version_info event through both the native observable
+   * store and the engine projection after an APK reboot.
+   * @deprecated Legacy progress route (build < 37) only — removed with WP 8D.
+   */
+  clearBuildNumberForNextCheck: () => {
+    BluetoothSdk.updateGlasses({buildNumber: ""})
+    useGlassesStore.getState().setGlassesInfo({buildNumber: ""})
+  },
+  /**
+   * Mark MTK as already applied during this app session until the glasses reboot/disconnect.
+   * @deprecated Legacy progress route (build < 37) only — removed with WP 8D.
+   */
+  markMtkUpdatedThisSession: (updated: boolean) => useGlassesStore.getState().setMtkUpdatedThisSession(updated),
+
+  /**
+   * The OTA install state machine (unified `ota_status` sessions, build >= 37).
+   * The host progress screen attaches on mount, detaches on unmount, and renders
+   * the snapshot; every watchdog/retry/reconnect rule lives in the coordinator.
+   */
+  installSession: {
+    /** Bind the machine to the mounted progress screen. Idempotent per attach/detach cycle. */
+    attach: () => otaInstallCoordinator.attach(),
+    /** Unbind on unmount: clears all timers/listeners and resets session state. */
+    detach: () => otaInstallCoordinator.detach(),
+    /** Retry after a failure: clear state and re-send ota_start (if connected). */
+    retry: () => otaInstallCoordinator.retry(),
+    /** Terminal cleanup for Continue/Done (navigation stays in the screen). */
+    finish: () => otaInstallCoordinator.finish(),
+    /** Abandon an interrupted session (super-mode skip): finish() + drop the session's status/progress. */
+    discard: () => otaInstallCoordinator.discard(),
+    /** Current install read model (displayState/errorMsg/lockout + glasses OTA data). */
+    snapshot: (): OtaInstallSnapshot => otaInstallCoordinator.snapshot(),
+    /** Subscribe to install snapshot changes (deduped on projected JSON). Returns an unsubscribe. */
+    onSnapshot: (cb: (snapshot: OtaInstallSnapshot) => void): (() => void) => otaInstallCoordinator.onSnapshot(cb),
+  },
+
+  /** Current available-update info (versionName/updates/totalSize), or null. */
+  updateAvailable: (): OtaUpdateInfo | null => useGlassesStore.getState().otaUpdateAvailable,
+  /** Current OTA install status (stepType/phase/percent/status/error), or null. */
+  status: (): OtaStatus | null => useGlassesStore.getState().otaStatus,
+  /** Current OTA read model for update prompt/progress screens. */
+  snapshot: (): OtaSnapshot => projectSnapshot(),
+
+  /** Subscribe to OTA availability changes (info or null when cleared). Returns an unsubscribe. */
+  onUpdateAvailable: (cb: (info: OtaUpdateInfo | null) => void): (() => void) => {
+    let last = useGlassesStore.getState().otaUpdateAvailable
+    return useGlassesStore.subscribe(() => {
+      const info = useGlassesStore.getState().otaUpdateAvailable
+      if (info === last) return
+      last = info
+      cb(info)
+    })
+  },
+
+  /** Subscribe to OTA install status changes. Returns an unsubscribe. */
+  onStatus: (cb: (status: OtaStatus | null) => void): (() => void) => {
+    let last = useGlassesStore.getState().otaStatus
+    return useGlassesStore.subscribe(() => {
+      const status = useGlassesStore.getState().otaStatus
+      if (status === last) return
+      last = status
+      cb(status)
+    })
+  },
+
+  /** Subscribe to OTA snapshot changes. Returns an unsubscribe. */
+  onSnapshot: (cb: (snapshot: OtaSnapshot) => void): (() => void) => {
+    let last = JSON.stringify(projectSnapshot())
+    return useGlassesStore.subscribe(() => {
+      const snap = projectSnapshot()
+      const key = JSON.stringify(snap)
+      if (key === last) return
+      last = key
+      cb(snap)
+    })
+  },
+}