@glassly/engine 0.1.0-dev.0

package/src/facades/maps.ts

@@ -0,0 +1,13 @@
+/**
+ * maps facade — `engine.maps.mapbox`: the user-supplied Mapbox access token
+ * (Settings > Keys). Thin passthrough over MapboxTokenService, same shape as
+ * `engine.speech.sonioxDirect` so the Keys screen treats providers uniformly.
+ */
+import {validateMapboxApiKey} from "../services/MapboxTokenService"
+
+export const maps = {
+  mapbox: {
+    /** Probe a token against the Mapbox Tokens API without saving it. */
+    validateKey: (...args: Parameters<typeof validateMapboxApiKey>) => validateMapboxApiKey(...args),
+  },
+}

package/src/facades/memory.ts

@@ -0,0 +1,46 @@
+/**
+ * memory facade — `engine.memory`: the user's shared phone-local memory
+ * timeline (Settings > Memory). Host UI manages the note entries and can
+ * purge everything; the full timeline surface (lines, sessions, summaries)
+ * is what miniapps reach through session.memory with the MEMORY permission.
+ */
+import type {MemoryEntry, MemorySession} from "@glassly/miniapp"
+
+import type {MemoryStats} from "../services/MemoryStore"
+import {EXTENDED_RETENTION, STANDARD_RETENTION} from "../services/MemoryStore"
+import {isMemoryRetentionExtended, memoryStore, setMemoryRetentionExtended} from "../services/memoryStoreInstance"
+
+export const memory = {
+  /** All note entries, newest first. */
+  notes: (): Promise<MemoryEntry[]> => memoryStore.notes(),
+  /**
+   * Add a manual note ("ui" source). Pass `at` inside a past hour to append
+   * to that session. Resolves null on duplicate/empty.
+   */
+  addNote: (text: string, at?: number): Promise<MemoryEntry | null> =>
+    memoryStore.addNote(text, "ui", at ?? Date.now()),
+  /** Rewrite a note's text. Resolves false when the id isn't a note. */
+  updateNote: (id: string, text: string): Promise<boolean> => memoryStore.updateNote(id, text),
+  /** Delete one entry (note or line) by id. */
+  removeEntry: (id: string): Promise<boolean> => memoryStore.removeEntry(id),
+  /** All sessions (hours with entries + summary), newest first (history browser). */
+  sessions: (): Promise<MemorySession[]> => memoryStore.sessionList(),
+  /** Delete every entry (and summary) in an hour, or a whole day of hours. */
+  removeScope: (scope: "session" | "day", at: number): Promise<void> => memoryStore.removeScope(scope, at),
+  /** Counts for the Settings screen (entries, lines, notes, summaries). */
+  stats: (): Promise<MemoryStats> => memoryStore.stats(),
+  /** Drop the entire timeline: every entry and every summary. */
+  clearAll: (): Promise<void> => memoryStore.clear(),
+  /** Subscribe to store mutations (from miniapps or Settings). */
+  onChanged: (listener: () => void): (() => void) => memoryStore.onChanged(listener),
+  /** Whether the extended (Plus/Pro) retention window is active. */
+  retentionExtended: (): boolean => isMemoryRetentionExtended(),
+  /** Retention window in days for the given (or current) tier, for UI copy. */
+  retentionDays: (extended?: boolean): number =>
+    Math.round(
+      ((extended ?? isMemoryRetentionExtended()) ? EXTENDED_RETENTION : STANDARD_RETENTION).maxAgeMs /
+        (24 * 60 * 60 * 1000),
+    ),
+  /** Flip retention on subscription change. Host app (RevenueCat sync) only. */
+  setRetentionExtended: (extended: boolean): void => setMemoryRetentionExtended(extended),
+}

package/src/facades/miniapps.ts

@@ -0,0 +1,62 @@
+/**
+ * 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`, `buildUiShim`, the
+ * GlasslyJS router) are exported from `@glassly/engine` directly; the host mounts a
+ * `<WebView>` wired to them. This facade is the lifecycle half.
+ */
+import {useAppStatusStore} from "../stores/apps"
+import localMiniappRuntime from "../services/LocalMiniappRuntime"
+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)
+    })
+  },
+
+  /** Miniapps actively subscribed to Mentra Live hardware-button events. */
+  buttonPressSubscribers: (): string[] => localMiniappRuntime.getButtonPressSubscribers(),
+  /** Observe the active Mentra Live hardware-button subscriber set. */
+  onButtonPressSubscribersChanged: (cb: (packageNames: string[]) => void): (() => void) =>
+    localMiniappRuntime.onButtonPressSubscribersChanged(cb),
+
+  /** 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,14 @@
+/**
+ * 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,177 @@
+/**
+ * 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 "@glassly/bluetooth-sdk/internal"
+import type {OtaProgress, OtaProgressStatus, OtaStatus, OtaUpdateInfo} from "@glassly/bluetooth-sdk/internal"
+import {isGlassesConnected, useGlassesStore} from "../stores/glasses"
+import {resolveOtaManifestUrl} from "../services/otaManifestUrl"
+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,
+    hotspotOtaVersion: s.hotspotOtaVersion ?? 0,
+    wifiConnected: s.wifi.state === "connected",
+    wifiStatusKnown: s.wifiStatusKnown,
+    manifestUrl: resolveOtaManifestUrl(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: {
+    /** Select Wi-Fi or capability-gated hotspot transport for this checked manifest. */
+    prepare: (result: OtaCheckCurrentGlassesResult) => otaInstallCoordinator.prepare(result),
+    /** 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)
+    })
+  },
+}

package/src/facades/pairing.ts

@@ -0,0 +1,329 @@
+/**
+ * pairing facade — `engine.pairing`: scan for nearby glasses + pair. Scan state
+ * (searching + results) comes from the engine core store; scan/connect go over the
+ * bluetooth-sdk; pair-failure / not-ready are the bluetooth-sdk events.
+ *
+ * (Connect-the-already-paired-default is `engine.glasses.connectDefault()`; this
+ * facade is the first-time discovery + pair flow.)
+ */
+// Internal btsdk surface — updateBluetoothSettings (the Bluetooth Classic
+// target hint) lives on the full surface, not the public entry (same reason
+// the glasses facade imports internal).
+import BluetoothSdk from "@glassly/bluetooth-sdk/internal"
+import type {ConnectOptions, Device, PairFailureEvent, GlassesNotReadyEvent} from "@glassly/bluetooth-sdk"
+import {useCoreStore} from "../stores/core"
+import {useGlassesStore} from "../stores/glasses"
+import {hasDefaultDevice} from "../services/DeviceStoreHydration"
+import {
+  markPendingSelection,
+  projectPairingIdentity,
+  subscribePairingIdentity,
+  type IdentitySnapshot,
+} from "../services/PairingIdentity"
+import {
+  isGlassesConnected,
+  isGlassesLinkLayerBusy,
+  isGlassesReady,
+  waitForGlassesReady,
+} from "../services/GlassesReadiness"
+import {
+  logAutomaticReportSubmissionStatus,
+  toAutomaticReportSubmissionStatus,
+  type AutomaticReportSubmissionStatus,
+} from "../services/AutomaticReportResult"
+import {pushAllBluetoothSettings} from "../services/GlassesSettingsSync"
+import {submitAutomaticReport} from "./reports"
+
+export type {IdentitySnapshot} from "../services/PairingIdentity"
+
+export interface PairingReadyWaitOptions {
+  deviceModel?: string
+  deviceName?: string
+  timeoutMs?: number
+  route?: string
+  signal?: AbortSignal
+}
+
+const DEFAULT_PAIRING_BOOT_TIMEOUT_MS = 35_000
+const DEFAULT_BT_CLASSIC_TIMEOUT_MS = 1_000
+const DEFAULT_PAIRING_ROUTE = "/pairing/loading"
+const LOG_TAG = "PairingTimeoutReport"
+
+function projectReadiness() {
+  const s = useGlassesStore.getState()
+  return {
+    state: s.connection.state,
+    connected: s.connection.state === "connected",
+    fullyBooted: isGlassesReady(s.connection),
+    bluetoothClassicConnected: s.bluetoothClassicConnected,
+    nativeLinkBusy: isGlassesLinkLayerBusy(s.connection),
+  }
+}
+
+export type PairingReadinessSnapshot = ReturnType<typeof projectReadiness>
+
+export async function submitPairingBootTimeoutReport(params: {
+  deviceModel?: string
+  deviceName?: string
+  showGlassesBooting: boolean
+  elapsedMs: number
+  route?: string
+}): Promise<AutomaticReportSubmissionStatus> {
+  const {deviceModel, deviceName, showGlassesBooting, elapsedMs, route = DEFAULT_PAIRING_ROUTE} = params
+  const result = await submitAutomaticReport({
+    kind: "automatic",
+    trigger: {
+      type: "automatic",
+      source: "pairing_loading",
+      reason: "glasses_connect_timeout",
+    },
+    report: {
+      expectedBehavior: `Glasses should connect successfully within ${Math.round(elapsedMs / 1000)} seconds.`,
+      actualBehavior: JSON.stringify(
+        {
+          deviceModel,
+          deviceName,
+          showGlassesBooting,
+          elapsedMs,
+          route,
+        },
+        null,
+        2,
+      ),
+      systemPriority: "medium",
+    },
+    throttleKey: `pairing_timeout|${deviceModel || "unknown"}|${deviceName || "unknown"}`,
+  })
+
+  const status = toAutomaticReportSubmissionStatus(result)
+  logAutomaticReportSubmissionStatus(LOG_TAG, status, deviceModel, deviceName)
+  return status
+}
+
+async function waitForReadyDuringPairing(options: PairingReadyWaitOptions = {}): Promise<boolean> {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_PAIRING_BOOT_TIMEOUT_MS
+  let showGlassesBooting = false
+  const notReadySub = BluetoothSdk.addListener("glasses_not_ready", () => {
+    showGlassesBooting = true
+  })
+
+  try {
+    const ready = await waitForGlassesReady({
+      getConnection: () => useGlassesStore.getState().connection,
+      subscribe: (listener) => useGlassesStore.subscribe((state) => state.connection, listener),
+      timeoutMs,
+      signal: options.signal,
+    })
+
+    if (!ready && !options.signal?.aborted) {
+      void submitPairingBootTimeoutReport({
+        deviceModel: options.deviceModel,
+        deviceName: options.deviceName,
+        showGlassesBooting,
+        elapsedMs: timeoutMs,
+        route: options.route,
+      }).catch((error) => {
+        console.error(`[${LOG_TAG}] Unexpected error:`, error)
+      })
+    }
+
+    return ready
+  } finally {
+    notReadySub.remove()
+  }
+}
+
+async function waitForBluetoothClassic(
+  options: Pick<PairingReadyWaitOptions, "timeoutMs" | "signal"> = {},
+): Promise<boolean> {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_BT_CLASSIC_TIMEOUT_MS
+  return new Promise((resolve) => {
+    if (options.signal?.aborted) {
+      resolve(false)
+      return
+    }
+
+    const initial = useGlassesStore.getState().bluetoothClassicConnected
+    if (initial) {
+      resolve(true)
+      return
+    }
+
+    let settled = false
+    let timeout: ReturnType<typeof setTimeout> | null = null
+    let unsubscribe: (() => void) | null = null
+    let onAbort: (() => void) | null = null
+
+    const finish = (value: boolean) => {
+      if (settled) return
+      settled = true
+      if (timeout) clearTimeout(timeout)
+      if (unsubscribe) unsubscribe()
+      if (onAbort && options.signal) options.signal.removeEventListener("abort", onAbort)
+      resolve(value)
+    }
+
+    if (options.signal) {
+      onAbort = () => finish(false)
+      options.signal.addEventListener("abort", onAbort)
+    }
+
+    unsubscribe = useGlassesStore.subscribe(
+      (s) => s.bluetoothClassicConnected,
+      (connected) => {
+        if (connected) finish(true)
+      },
+    )
+
+    timeout = setTimeout(() => {
+      finish(useGlassesStore.getState().bluetoothClassicConnected)
+    }, timeoutMs)
+  })
+}
+
+export const pairing = {
+  readiness: (): PairingReadinessSnapshot => projectReadiness(),
+  onReadiness: (cb: (readiness: PairingReadinessSnapshot) => void): (() => void) => {
+    let last = JSON.stringify(projectReadiness())
+    return useGlassesStore.subscribe(() => {
+      const snap = projectReadiness()
+      const key = JSON.stringify(snap)
+      if (key === last) return
+      last = key
+      cb(snap)
+    })
+  },
+
+  // --- pairing-identity lifecycle (the PairingIdentity read-model + the JS-owned
+  // identity writes; promotion to `paired` only ever happens natively) ---
+  /** The identity lifecycle snapshot: none | pending (chosen, never paired) | paired. */
+  identity: (): IdentitySnapshot => projectPairingIdentity(),
+  /** Subscribe to identity changes; fires only when the projected snapshot changes.
+   * Returns an unsubscribe. */
+  onIdentity: (cb: (identity: IdentitySnapshot) => void): (() => void) => subscribePairingIdentity(cb),
+  /** Mark the chosen model as the pending selection (the scan-entry write); the
+   * host renders it as a finish-pairing affordance until pairing succeeds. */
+  markPendingSelection: (model: string) => markPendingSelection(model),
+
+  /** Start scanning for nearby glasses. Results land on `searchResults()`/`onFound()`. */
+  scan: (...args: Parameters<typeof BluetoothSdk.startScan>) => BluetoothSdk.startScan(...args),
+  /** Whether a scan is currently in progress. */
+  scanning: (): boolean => useCoreStore.getState().searching,
+  /** Subscribe to scan-in-progress changes; fires only when it changes. Returns an unsubscribe. */
+  onScanning: (cb: (scanning: boolean) => void): (() => void) => useCoreStore.subscribe((s) => s.searching, cb),
+  /** Whether a controller scan is currently in progress. */
+  scanningController: (): boolean => useCoreStore.getState().searchingController,
+  /** Subscribe to controller-scan-in-progress changes; fires only when it changes. Returns an unsubscribe. */
+  onScanningController: (cb: (scanning: boolean) => void): (() => void) =>
+    useCoreStore.subscribe((s) => s.searchingController, cb),
+  /** Whether the phone has another Bluetooth (audio) device connected — the BT Classic pairing hint. */
+  otherBtConnected: (): boolean => useCoreStore.getState().otherBtConnected,
+  /** Subscribe to other-Bluetooth-device-connected changes; fires only when it changes. Returns an unsubscribe. */
+  onOtherBtConnected: (cb: (connected: boolean) => void): (() => void) =>
+    useCoreStore.subscribe((s) => s.otherBtConnected, cb),
+  /** The current scan results (snapshot). */
+  // Copy the array AND each entry: neither the list nor the Device objects may
+  // leak as mutable references into the store.
+  searchResults: () => useCoreStore.getState().searchResults.map((result) => ({...result})),
+  /** Subscribe to scan-result changes; fires only when they change. Returns an unsubscribe. */
+  onFound: (cb: (results: ReturnType<typeof useCoreStore.getState>["searchResults"]) => void): (() => void) => {
+    let last = JSON.stringify(useCoreStore.getState().searchResults)
+    return useCoreStore.subscribe(() => {
+      const results = useCoreStore.getState().searchResults
+      const key = JSON.stringify(results)
+      if (key === last) return
+      last = key
+      // Copy like searchResults(): listeners must not mutate shared scan state.
+      cb(results.map((result) => ({...result})))
+    })
+  },
+
+  /**
+   * Pair with (connect to) a discovered device. Two-phase identity: the connect
+   * attempt only marks the device as pending (`saveAsDefault: false` — no eager
+   * default-device write); the native layer promotes it to the default wearable
+   * when pairing actually succeeds (handleDeviceReady), so an abandoned or
+   * failed attempt can't leave a default identity with no paired device behind.
+   */
+  pair: async (device: Device, options?: ConnectOptions): Promise<void> => {
+    await pushAllBluetoothSettings()
+    return BluetoothSdk.connect(device, {...options, saveAsDefault: false})
+  },
+  /** Set a device as the default for subsequent `glasses.connectDefault()`. */
+  setDefault: (...args: Parameters<typeof BluetoothSdk.setDefaultDevice>) => BluetoothSdk.setDefaultDevice(...args),
+  /**
+   * Prime the native Bluetooth Classic audio watcher with the picked device.
+   * The iOS Mentra Live flow pairs Classic audio BEFORE any BLE connect
+   * exists, and native detects the pairing by matching the connected audio
+   * route against its device_name — which two-phase identity no longer sets
+   * at selection time. This is native-only routing state (device_name has no
+   * native→JS echo): the phone's persisted identity is untouched, and
+   * promotion still happens only at pairing success.
+   */
+  setBluetoothClassicTarget: (device: Device): Promise<void> =>
+    BluetoothSdk.updateBluetoothSettings({device_name: device.name}),
+  /**
+   * Abandon an in-flight pairing attempt (back-out, failure retry, conflict
+   * retry) without destroying an existing pairing. The decision comes from the
+   * LIVE hydrated default-device read — never from flow-entry state, because a
+   * pairing can PROMOTE while the flow is open (the glasses finish pairing
+   * even as the user backs out of the UI), and an entry snapshot would forget
+   * that brand-new pairing:
+   * - Default device exists and glasses are connected (nothing in flight — an
+   *   attempt drops the link first): stop the scan, touch nothing else.
+   * - Default device exists with an attempt in flight: cancel it, then re-seed
+   *   the native identity from the phone's persisted settings — the attempt's
+   *   connect-by-name overwrote the native device_name, so a later
+   *   connectDefault() would otherwise target the abandoned device.
+   * - No default device (genuinely unpaired attempt): also forget, clearing
+   *   the partial native pairing state.
+   * The read fails OPEN to "preserve" — a transient failure must never wipe a
+   * real pairing. The `pending_wearable` marker is deliberately left alone —
+   * the host renders it as a finish-pairing affordance.
+   */
+  abandonAttempt: async (): Promise<void> => {
+    const nativeHasDefault = await hasDefaultDevice().catch(() => true)
+    if (nativeHasDefault && isGlassesConnected(useGlassesStore.getState().connection)) {
+      // Still connected means no connect attempt is in flight (an attempt drops
+      // the existing link first): the user browsed the scan and backed out.
+      // Stop the scan and leave the live pairing untouched.
+      console.log("PairingIdentity: abandonAttempt — pairing intact and connected; stopping scan only")
+      await BluetoothSdk.stopScan()
+      return
+    }
+    await BluetoothSdk.disconnect()
+    if (projectPairingIdentity().kind === "paired") {
+      // The persisted settings describe a COMPLETE pairing: restore it to
+      // native (the attempt's connect-by-name overwrote the native
+      // device_name; and if native somehow lost its default entirely, this
+      // repairs the divergence instead of forgetting a real pairing).
+      console.log("PairingIdentity: abandonAttempt — preserving pairing; attempt cancelled, native identity re-seeded")
+      await pushAllBluetoothSettings()
+    } else if (nativeHasDefault) {
+      // Mid-relay: native promoted and its echoes are still landing — the
+      // incomplete JS snapshot must not be pushed over the fresher native
+      // identity (the on-connect replay's race). Native holds the truth.
+      console.log("PairingIdentity: abandonAttempt — preserving pairing; JS identity mid-relay, native kept as-is")
+    } else {
+      // Forgetting requires CONSENSUS: no native default AND no complete
+      // persisted pairing — a genuinely partial attempt.
+      console.log("PairingIdentity: abandonAttempt — no pairing on either layer; forgetting the partial attempt")
+      await BluetoothSdk.forget()
+    }
+  },
+
+  /** Subscribe to pairing failures; returns an unsubscribe. */
+  onPairFailure: (cb: (event: PairFailureEvent) => void): (() => void) => {
+    const sub = BluetoothSdk.addListener("pair_failure", cb)
+    return () => sub.remove()
+  },
+  /** Subscribe to glasses-not-ready events during pairing; returns an unsubscribe. */
+  onGlassesNotReady: (cb: (event: GlassesNotReadyEvent) => void): (() => void) => {
+    const sub = BluetoothSdk.addListener("glasses_not_ready", cb)
+    return () => sub.remove()
+  },
+  /** Wait for paired glasses to finish booting; engine files the timeout diagnostic. */
+  waitForReady: waitForReadyDuringPairing,
+  /** Wait briefly for Bluetooth Classic to come up after BLE pairing. */
+  waitForBluetoothClassic,
+}