@mentra/engine 0.1.0-beta.0

package/src/facades/reports.ts

@@ -0,0 +1,185 @@
+/**
+ * reports facade — `engine.reports`: user/system report submission over the
+ * Cloud V2 core client.
+ *
+ * Host/OEM code owns UI and wording. Engine owns MentraOS mechanics: context
+ * collection, recent phone logs, Cloud V2 calls, local automatic throttling,
+ * screenshots, and notifying connected glasses.
+ */
+import BluetoothSdk from "@mentra/bluetooth-sdk/internal"
+import type {
+  ReportAttachmentInput,
+  ReportContext,
+  ReportStatus,
+  SubmitReportInput,
+} from "@mentra/cloud-client"
+import {useGlassesStore} from "../stores/glasses"
+import {isGlassesConnected} from "../services/GlassesReadiness"
+import {cloudClientService} from "../services/CloudClientService"
+import {collectDiagnosticContext} from "../utils/diagnosticContext"
+import {logBuffer} from "../utils/devLogging"
+
+export type {
+  ReportAttachmentInput,
+  ReportContext,
+  ReportDetails,
+  ReportStatus,
+  ReportTrigger,
+} from "@mentra/cloud-client"
+
+export type EngineSubmitReportInput =
+  | (Omit<Extract<SubmitReportInput, {kind: "bug"}>, "context"> & {
+      context?: Partial<ReportContext>
+      screenshots?: ReportAttachmentInput[]
+    })
+  | (Omit<Extract<SubmitReportInput, {kind: "feedback"}>, "context"> & {
+      context?: Partial<ReportContext>
+    })
+
+export type EngineSubmitAutomaticReportInput = Omit<Extract<SubmitReportInput, {kind: "automatic"}>, "context"> & {
+  context?: Partial<ReportContext>
+  screenshots?: ReportAttachmentInput[]
+  throttleKey?: string
+  throttleWindowMs?: number
+}
+
+type InternalSubmitReportInput = EngineSubmitReportInput | EngineSubmitAutomaticReportInput
+
+export type ReportSubmitResult =
+  | {status: "submitted"; reportId: string; reportStatus: ReportStatus}
+  | {status: "skipped"; reason: "throttled_within_window"}
+  | {status: "failed"; error: string}
+
+const DEFAULT_AUTOMATIC_REPORT_THROTTLE_MS = 90_000
+const automaticReportThrottleRegistry = new Map<string, number>()
+
+function automaticThrottleShouldSkip(key: string, nowMs: number, windowMs: number): boolean {
+  const previous = automaticReportThrottleRegistry.get(key)
+  if (previous !== undefined && nowMs - previous < windowMs) {
+    return true
+  }
+  pruneAutomaticThrottleRegistry(nowMs, windowMs)
+  return false
+}
+
+function markAutomaticThrottleSuccess(key: string, nowMs: number, windowMs: number): void {
+  automaticReportThrottleRegistry.set(key, nowMs)
+  pruneAutomaticThrottleRegistry(nowMs, windowMs)
+}
+
+function pruneAutomaticThrottleRegistry(nowMs: number, windowMs: number): void {
+  for (const [entryKey, entryTime] of automaticReportThrottleRegistry) {
+    if (nowMs - entryTime > windowMs * 3) {
+      automaticReportThrottleRegistry.delete(entryKey)
+    }
+  }
+}
+
+function notifyGlasses(reportId: string, apiBaseUrl?: string | null): void {
+  if (!isGlassesConnected(useGlassesStore.getState().connection)) return
+  void (async () => {
+    try {
+      await cloudClientService.syncCoreTokenToBluetooth()
+      await BluetoothSdk.sendIncidentId(reportId, apiBaseUrl ?? cloudClientService.getCoreUrl())
+    } catch (error) {
+      console.warn("reports.submit: notify glasses failed:", error instanceof Error ? error.message : error)
+    }
+  })()
+}
+
+async function submitReportInternal(input: InternalSubmitReportInput): Promise<ReportSubmitResult> {
+  const throttle =
+    input.kind === "automatic" && input.throttleKey
+      ? {
+          key: input.throttleKey,
+          windowMs: input.throttleWindowMs ?? DEFAULT_AUTOMATIC_REPORT_THROTTLE_MS,
+        }
+      : null
+
+  if (input.kind === "automatic" && input.throttleKey) {
+    const shouldSkip = automaticThrottleShouldSkip(
+      input.throttleKey,
+      Date.now(),
+      throttle?.windowMs ?? DEFAULT_AUTOMATIC_REPORT_THROTTLE_MS,
+    )
+    if (shouldSkip) return {status: "skipped", reason: "throttled_within_window"}
+  }
+
+  const context = await collectDiagnosticContext(input.context)
+  let reportId: string
+  let reportStatus: ReportStatus
+  let artifactsComplete = true
+  try {
+    const res =
+      input.kind === "feedback"
+        ? await cloudClientService.core.reports.submit({
+            kind: "feedback",
+            feedback: input.feedback,
+            context,
+          })
+        : input.kind === "bug"
+          ? await cloudClientService.core.reports.submit({
+              kind: "bug",
+              trigger: input.trigger,
+              report: input.report,
+              context,
+            })
+          : await cloudClientService.core.reports.submit({
+              kind: "automatic",
+              trigger: input.trigger,
+              report: input.report,
+              context,
+            })
+    reportId = res.reportId
+    reportStatus = res.status
+  } catch (error) {
+    return {status: "failed", error: error instanceof Error ? error.message : String(error)}
+  }
+
+  if (input.kind !== "feedback") {
+    const logs = logBuffer.getRecentLogs()
+    if (logs.length > 0) {
+      try {
+        await cloudClientService.core.reports.addLogs(reportId, "phone", logs)
+      } catch (error) {
+        artifactsComplete = false
+        console.warn("reports.submit: add phone logs failed:", error instanceof Error ? error.message : error)
+      }
+    }
+
+    notifyGlasses(reportId, cloudClientService.getCoreUrl())
+
+    if (input.screenshots && input.screenshots.length > 0) {
+      try {
+        await cloudClientService.core.reports.addScreenshots(reportId, input.screenshots)
+      } catch (error) {
+        artifactsComplete = false
+        console.warn("reports.submit: add screenshots failed:", error instanceof Error ? error.message : error)
+      }
+    }
+
+    try {
+      const completed = await cloudClientService.core.reports.complete(reportId)
+      reportStatus = completed.status
+    } catch (error) {
+      artifactsComplete = false
+      console.warn("reports.submit: complete report failed:", error instanceof Error ? error.message : error)
+    }
+  }
+
+  if (throttle && artifactsComplete) {
+    markAutomaticThrottleSuccess(throttle.key, Date.now(), throttle.windowMs)
+  }
+
+  return {status: "submitted", reportId, reportStatus}
+}
+
+export const reports = {
+  submit(input: EngineSubmitReportInput): Promise<ReportSubmitResult> {
+    return submitReportInternal(input)
+  },
+}
+
+export function submitAutomaticReport(input: EngineSubmitAutomaticReportInput): Promise<ReportSubmitResult> {
+  return submitReportInternal(input)
+}

package/src/facades/session.ts

@@ -0,0 +1,55 @@
+/**
+ * session facade — `engine.session`: the cloud-v2 live-session surface engine
+ * now owns (keystone #5). Exposes the connection status read-model (status +
+ * audio transport, projected from the engine-owned cloud-status store) and the
+ * liveness flag.
+ *
+ */
+import {cloudClientService} from "../services/CloudClientService"
+import {useCloudClientStatusStore} from "../stores/cloudClientStatus"
+import {useConnectionStore} from "../stores/connection"
+import type {WebSocketStatus} from "../stores/connection"
+import type {CloudClientStatusSnapshot} from "../runtime/config"
+
+function project(): CloudClientStatusSnapshot {
+  const s = useCloudClientStatusStore.getState()
+  return {status: s.status, audioTransport: s.audioTransport}
+}
+
+export const session = {
+  /** Current cloud live-session status (connection state + audio transport). */
+  status: (): CloudClientStatusSnapshot => project(),
+  /** Subscribe to cloud session-status changes; returns an unsubscribe. */
+  onStatus: (cb: (status: CloudClientStatusSnapshot) => void): (() => void) => {
+    // Dedupe: fire only when the projected {status, audioTransport} changes.
+    let last = JSON.stringify(project())
+    return useCloudClientStatusStore.subscribe(() => {
+      const snap = project()
+      const key = JSON.stringify(snap)
+      if (key === last) return
+      last = key
+      cb(snap)
+    })
+  },
+  /** Whether the live-session handshake has completed. */
+  isConnected: (): boolean => cloudClientService.isConnected(),
+
+  /**
+   * Legacy Cloud-V1 websocket status. The socket's writer (the host
+   * WebSocketManager) was deleted in the Cloud V1 ripout, so this now always
+   * reports the store's initial DISCONNECTED; the host connection banners
+   * render `status()` (the cloud-v2 runtime) instead. Kept, with the backing
+   * connection store, for the engine-side legacy-surface removal (issue #3392).
+   */
+  legacyWebsocketStatus: (): WebSocketStatus => useConnectionStore.getState().status,
+  /** Subscribe to legacy websocket status changes; fires only when it changes. Returns an unsubscribe. */
+  onLegacyWebsocketStatus: (cb: (status: WebSocketStatus) => void): (() => void) => {
+    let last = useConnectionStore.getState().status
+    return useConnectionStore.subscribe((state) => {
+      if (state.status === last) return
+      last = state.status
+      cb(state.status)
+    })
+  },
+
+}

package/src/facades/settings.ts

@@ -0,0 +1,57 @@
+/**
+ * settings facade — `engine.settings`: the typed keyed user-settings surface over
+ * the engine-owned settings store. This is the (A) OEM contract; the raw store at
+ * `engine.stores.settings` is the Mentra-app escape hatch.
+ *
+ * Keys + their schema live in `SETTINGS` (theme, devMode, metric/twelveHourTime,
+ * notifications, onboarding flags, …); `descriptor(key)`/`keys()` expose them.
+ */
+import {useSettingsStore, SETTINGS} from "../stores/settings"
+
+// Copy: object/array-valued settings must not hand callers a mutable reference
+// into the store (mutations would silently corrupt store state, bypassing set()).
+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 settings = {
+  /** Read a setting by key (the current value, or its default; object/array values
+   * are shallow copies). */
+  get: <T = unknown>(key: string): T | undefined =>
+    copySettingValue(useSettingsStore.getState().getSetting(key) as T | undefined),
+  /**
+   * Write a setting. `syncToServer` (default true) also pushes the change to the
+   * backend; pass false for device-local-only writes.
+   */
+  set: <T = unknown>(key: string, value: T, syncToServer = true) =>
+    useSettingsStore.getState().setSetting(key, value, syncToServer),
+  /** Subscribe to changes for one 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],
+  /** All known setting keys. */
+  keys: (): string[] => Object.keys(SETTINGS),
+  /**
+   * Reset every setting to its default on THIS device only (no server sync) —
+   * the logout path. Server-side settings are untouched.
+   */
+  resetAllLocal: (): void => useSettingsStore.getState().resetAllSettingsLocally(),
+  /**
+   * Hydrate the settings store from device storage — the host-boot step (fire
+   * once at app start, before UI reads settings). Single-flighted internally.
+   */
+  loadAll: () => useSettingsStore.getState().loadAllSettings(),
+  /**
+   * Every EXPLICITLY-SET setting (shallow copy; keys never written are absent —
+   * use get() for default-resolved reads). The data-export surface.
+   */
+  getAll: (): Record<string, unknown> => ({...useSettingsStore.getState().settings}),
+  /**
+   * Bulk device-local write without server sync — seeding the store from a
+   * backend settings payload.
+   */
+  setManyLocal: (values: Record<string, unknown>) => useSettingsStore.getState().setManyLocally(values),
+}

package/src/facades/speech.ts

@@ -0,0 +1,38 @@
+/**
+ * speech facade — `engine.speech.{stt,tts}`: on-device STT/TTS model management,
+ * wrapping the in-engine model managers. Thin passthrough (args forwarded with
+ * exact types via Parameters<>), so the facade never drifts from the managers.
+ * STT additionally exposes the auto-download status stream (the TTS path has none).
+ */
+import BluetoothSdk from "@mentra/bluetooth-sdk/internal"
+import sttModelManager from "../services/STTModelManager"
+import ttsModelManager from "../services/TTSModelManager"
+import offlineSpeechModelService from "../services/OfflineSpeechModelService"
+
+export const speech = {
+  /** Restart the glasses' on-device transcriber (e.g. after switching STT language). */
+  restartTranscriber: (): Promise<void> => BluetoothSdk.restartTranscriber(),
+  stt: {
+    currentLanguage: () => sttModelManager.getCurrentLanguage(),
+    languages: () => sttModelManager.getAvailableLanguages(),
+    languageInfo: () => sttModelManager.getAllLanguageInfo(),
+    download: (...args: Parameters<typeof sttModelManager.downloadModel>) => sttModelManager.downloadModel(...args),
+    activate: (code: string) => sttModelManager.setCurrentLanguage(code),
+    cancelDownload: () => sttModelManager.cancelDownload(),
+    deleteModel: (...args: Parameters<typeof sttModelManager.deleteModel>) => sttModelManager.deleteModel(...args),
+    /** Current auto-download status of the offline STT model. */
+    status: () => offlineSpeechModelService.getStatus(),
+    /** Subscribe to auto-download status changes; returns an unsubscribe. */
+    onStatusChanged: (...args: Parameters<typeof offlineSpeechModelService.subscribe>) =>
+      offlineSpeechModelService.subscribe(...args),
+  },
+  tts: {
+    currentLanguage: () => ttsModelManager.getCurrentLanguage(),
+    languages: () => ttsModelManager.getAvailableLanguages(),
+    languageInfo: () => ttsModelManager.getAllLanguageInfo(),
+    download: (...args: Parameters<typeof ttsModelManager.downloadModel>) => ttsModelManager.downloadModel(...args),
+    activate: (code: string) => ttsModelManager.setCurrentLanguage(code),
+    cancelDownload: () => ttsModelManager.cancelDownload(),
+    deleteModel: (...args: Parameters<typeof ttsModelManager.deleteModel>) => ttsModelManager.deleteModel(...args),
+  },
+}

package/src/index.ts

@@ -0,0 +1,191 @@
+/**
+ * `@mentra/engine` — the OEM-facing main entry.
+ *
+ * The `engine` namespace (configure/start/stop + typed domain facades), the
+ * public contract/read-model types, and the pure helpers host UI legitimately
+ * renders with (decision functions, sort/order helpers, policy constants,
+ * capability tables, timers). Judgment rule: read models, commands, pure
+ * functions and types belong here; anything that mutates runtime state or
+ * exposes a raw store/service lives on `@mentra/engine/internal`
+ * (migration-era surface) or `@mentra/engine/devtools` (debug-only) instead.
+ * See cloud-v2/docs/issues/020-glasses-status-boundary/integration-review.md §D.
+ */
+
+// The namespaced OEM-facing engine API (the "(A) host API"). See ./engine.
+export {engine} from "./engine"
+export type {
+  ReportAttachmentInput,
+  ReportContext,
+  ReportDetails,
+  ReportStatus,
+  ReportTrigger,
+  ReportSubmitResult,
+  EngineSubmitReportInput,
+} from "./facades/reports"
+export type {IslandNotification, IslandNotificationKind} from "./facades/notifications"
+export type {WifiSearchResult} from "./facades/glassesWifi"
+export type {IdentitySnapshot} from "./services/PairingIdentity"
+export type {DisplayMirrorEvent} from "./facades/displayMirror"
+export type {
+  IslandConfigureOptions,
+  IslandAuth,
+  IslandConfigValues,
+  IslandAnalytics,
+  IslandUiSeams,
+  SubjectTokenType,
+} from "./runtime/bootstrap"
+
+// Settings contract: the typed key registry (schema descriptors — the same
+// surface engine.settings.descriptor()/keys() reads), the per-key React hook
+// (the hook layer, same precedent as the apps hooks below), and the pure
+// device-model key helpers. The raw useSettingsStore stays internal;
+// imperative access goes through engine.settings.
+export {SETTINGS, useSetting} from "./stores/settings"
+export {MENTRA_LIVE_SETTING_KEYS, getBluetoothSettingKeysForDevice} from "./stores/bluetoothSettingKeys"
+
+// Runtime-shared constants and contract DTOs.
+export {ISLAND_SETTINGS_KEYS} from "./runtime/config"
+export type {
+  CloudClientStatusSnapshot,
+  MiniappAuthToken,
+  InteropAuditEvent,
+  TtsSynthesisResult,
+} from "./runtime/config"
+
+// Pure readiness predicates over glasses connection state.
+export {
+  isGlassesConnected,
+  isGlassesReady,
+  isGlassesLinkLayerBusy,
+  waitForGlassesReady,
+  type GlassesConnectionStatus,
+  type WaitForGlassesReadyOptions,
+} from "./services/GlassesReadiness"
+// Pure connect/reconnect decision helpers (host UI renders the outcome).
+export {
+  decideReconnect,
+  decideConnectButtonAction,
+  type ReconnectDecision,
+  type ReconnectDecisionInput,
+  type ConnectButtonAction,
+} from "./services/ConnectionCoordinator"
+
+// OTA read-model types for host OTA UI (progress screen, error mapping,
+// progress section) — the check/install machinery itself is internal.
+export type {
+  VersionInfo,
+  MtkPatch,
+  BesFirmware,
+  VersionJson,
+  OtaCheckResult,
+  OtaCheckCurrentGlassesResult,
+  OtaCheckCurrentGlassesOptions,
+} from "./services/OtaUpdateCheckService"
+// OTA install policy (watchdog timings + failure copy) + display-state
+// derivation, consumed by the OTA screens and their tests.
+export {
+  MINIMUM_OTA_STATUS_BUILD,
+  MAX_RETRIES,
+  RETRY_INTERVAL_MS,
+  PROGRESS_TIMEOUT_MS,
+  DOWNLOAD_STUCK_TIMEOUT_MS,
+  MTK_INSTALL_TIMEOUT_MS,
+  GLOBAL_OTA_TIMEOUT_MS,
+  POST_APK_OTA_START_DELAY_MS,
+  PING_INTERVAL_MS,
+  QUERY_REPLY_TIMEOUT_MS,
+  OtaProgressMessages,
+} from "./services/otaInstallPolicy"
+export {deriveDisplayState} from "./services/otaDisplayState"
+export type {DisplayState} from "./services/otaDisplayState"
+export type {
+  OtaProgress,
+  OtaProgressStatus,
+  OtaStatus,
+  OtaUpdateInfo,
+  OtaSnapshot,
+  OtaInstallSnapshot,
+} from "./facades/ota"
+
+// Gallery read models: engine.gallery.onNotice payload types, the media
+// permission helper + display-name derivation host gallery UI uses, and the
+// glasses-camera DTO types (re-exported through the host @/types/asg shim).
+export type {GalleryNotice, GalleryNoticeCode} from "./services/asg/galleryNotices"
+export {MediaLibraryPermissions} from "./utils/permissions/MediaLibraryPermissions"
+export {deriveGalleryDisplayName} from "./utils/permissions/galleryDisplayName"
+export type {PhotoInfo, CaptureFile, CaptureGroup, GalleryResponse, ServerStatus, HealthResponse, GalleryEvent} from "./types/asg"
+
+// Bluetooth SDK event types host UI subscribes to via engine facades (the
+// BluetoothSdk singleton passthrough itself is internal).
+export type {PairFailureEvent, GlassesNotReadyEvent} from "@mentra/bluetooth-sdk/internal"
+
+// Cloud connection status enum (read model; the connection store is internal).
+export {WebSocketStatus} from "./stores/connection"
+
+// App-list hook layer + pure list helpers (the raw useAppStatusStore and
+// installAppStoreHooks wiring are internal).
+export {
+  DUMMY_APPLET,
+  saveAppsOrder,
+  getAppsOrder,
+  sortAppsByPackageNamePriority,
+  saveLastOpenTime,
+  getLastOpenTime,
+  sortAppsByLastOpenTime,
+  useApps,
+  useStart,
+  useStop,
+  useSetForeground,
+  useClearForeground,
+  useRefresh,
+  useStopAll,
+  useInstall,
+  useUninstall,
+  useActiveApps,
+  useActiveBackgroundApps,
+  useBackgroundApps,
+  useActiveForegroundApp,
+  useForegroundApp,
+  useActiveBackgroundAppsCount,
+  useLocalMiniApps,
+  type StartOptions,
+  type OrderMap,
+} from "./stores/apps"
+
+// Pure dev-miniapp launch-route decision (registration itself is internal).
+export {decideDevLaunchRoute, type DevLaunchResult, type DevManifest} from "./utils/devMiniappLaunch"
+export {HardwareCompatibility, type CompatibilityResult} from "./utils/hardware"
+export {BgTimer, throttle, debounce} from "./utils/timers"
+
+// Types (copied from @mentra/types — keep in sync with cloud/packages/types/src)
+export {
+  HardwareType,
+  HardwareRequirementLevel,
+  DeviceTypes,
+  ControllerTypes,
+  HARDWARE_CAPABILITIES,
+  getModelCapabilities,
+  simulatedGlasses,
+  evenRealitiesG1,
+  evenRealitiesG2,
+  mentraLive,
+  vuzixZ100,
+  mentraDisplay,
+} from "./types"
+export type {
+  HardwareRequirement,
+  CameraCapabilities,
+  DisplayCapabilities,
+  MicrophoneCapabilities,
+  SpeakerCapabilities,
+  IMUCapabilities,
+  ButtonCapabilities,
+  LightCapabilities,
+  PowerCapabilities,
+  Capabilities,
+  AppletType,
+  AppPermissionType,
+  AppletPermission,
+  AppletInterface,
+  ClientApp,
+} from "./types"

package/src/internal.ts

@@ -0,0 +1,159 @@
+/**
+ * `@mentra/engine/internal` — the migration-era runtime surface.
+ *
+ * Raw zustand stores and service singletons that the Mentra app's host-side
+ * services (and the `@/stores/*` / `@/utils/*` shims) still reach into while
+ * the typed `engine` facades grow. Everything here either mutates runtime
+ * state or exposes a store/service directly, so none of it belongs on the
+ * OEM-facing `@mentra/engine` main entry: new host code should read/act
+ * through `engine.*` instead.
+ *
+ * Every `/internal` import in mobile/src is counted (report-only) by
+ * scripts/check-mobile-runtime-boundary.sh; the burn-down plan is
+ * cloud-v2/docs/issues/020-glasses-status-boundary/integration-review.md §D.
+ * Types that only describe these internal surfaces live here with them;
+ * types host UI renders with stay on the main entry.
+ */
+
+// Miniapp runtime plumbing: WebView bridge, registry, launcher, engine.
+export {default as webviewBridge} from "./services/WebviewBridge"
+export {
+  default as appRegistry,
+  normalizeManifestPermissions,
+  normalizeManifestActions,
+  buildHardwareRequirements,
+  saveLocalAppRunningState,
+  registerDevApp,
+  unregisterDevApp,
+  getDevAppRecords,
+  getDevAppSourcePackage,
+  getDevAppAttestation,
+  DEV_APP_PACKAGE_NAME,
+  type DevAppRecord,
+} from "./services/AppRegistry"
+export {default as displayProcessor} from "./services/DisplayProcessor"
+export {default as localDisplayManager, type DisplayPayload} from "./services/LocalDisplayManager"
+export {default as localMiniappRuntime, type InstalledMiniappManifest} from "./services/LocalMiniappRuntime"
+export {miniappLauncher, type LaunchHints, type LaunchResult, type ResolvedBundle} from "./services/MiniappLauncher"
+export {
+  MentraJSRouter,
+  type MentraJSCrustBinding,
+  type OutboundMessagePayload as MentraJSOutboundMessage,
+  type RouterLogger as MentraJSRouterLogger,
+} from "./services/MentraJSRouter"
+export {buildMentraUiShim, type MentraUiShimOptions} from "./services/mentraUiShim"
+export {MentraUIRouter, type MentraUICrustBinding} from "./services/MentraUIRouter"
+export {
+  MentraJSCrashController,
+  type CrashState,
+  type CrashOutcome,
+  type CrashControllerOptions,
+} from "./services/MentraJSCrashController"
+export {ensureMiniappEngine, getMiniappEngine, type MiniappEngine} from "./services/MiniappEngine"
+export {
+  redactSecrets,
+  MentraJSLogThrottle,
+  MentraJSLogRingBuffer,
+  type ThrottleOptions,
+} from "./services/MentraJSLogPipeline"
+// WebView-injection script builders (miniapp globals + mentra-ui shim).
+export {
+  buildMiniappGlobalsScript,
+  getCapsuleMenuRect,
+  type BuildMiniappGlobalsOptions,
+  type CapsuleMenuRect,
+  type MiniappColorScheme,
+  type MiniappSafeArea,
+} from "./utils/miniappGlobals"
+
+// Speech/audio coordinators and model managers.
+export {default as localSttFallbackCoordinator} from "./services/LocalSttFallbackCoordinator"
+export {default as micStateCoordinator} from "./services/MicStateCoordinator"
+export {default as audioPlaybackService} from "./services/AudioPlaybackService"
+export {
+  default as sttModelManager,
+  STTModelManager,
+  type LanguageInfo as SttLanguageInfo,
+  type LanguageConfig as SttLanguageConfig,
+  type DownloadProgress as SttDownloadProgress,
+  type ExtractionProgress as SttExtractionProgress,
+} from "./services/STTModelManager"
+export {default as ttsModelManager, TTSModelManager} from "./services/TTSModelManager"
+export {
+  default as offlineSpeechModelService,
+  type DownloadStatus as OfflineModelDownloadStatus,
+  type DownloadStage as OfflineModelDownloadStage,
+} from "./services/OfflineSpeechModelService"
+
+export {default as navigationService} from "./services/NavigationService"
+// Phone GPS — the background location task + tier control. Importing this
+// module registers the background task, so the entry that MantleManager loads
+// must keep re-exporting it (was: the main barrel).
+export {phoneLocationService, stopPhoneLocation} from "./services/PhoneLocationService"
+// Clock-skew fix commands (BLE writes) used by OTA + gallery sync.
+export {fixGlassesClockIfSkewed, maybeFixGlassesClockFromVersionInfo} from "./services/glassesClockSync"
+// OTA manifest-URL resolution (dev-override/legacy-build/env/prod).
+export {getAsgOtaVersionUrl} from "./services/asgOtaVersionUrl"
+// Flat OTA check helpers (network + BLE state). Host usage is a tracked
+// burn-down surface (§F); the sanctioned path is engine.ota.checkForUpdates().
+export {
+  fetchVersionInfo,
+  checkVersionUpdateAvailable,
+  getLatestVersionInfo,
+  findMatchingMtkPatch,
+  checkBesUpdate,
+  checkForOtaUpdate,
+  checkCurrentGlassesForUpdate,
+} from "./services/OtaUpdateCheckService"
+
+// Gallery cluster — sync orchestrator, glasses-camera HTTP API, media/storage,
+// settings, validation and the service-to-service notice bus. Host gallery UI
+// renders engine.gallery; these are the underlying services.
+export {detectClockSkew, isSyncManifestEmpty, CLOCK_SKEW_TOLERANCE_MS} from "./services/gallerySyncClock"
+export {gallerySyncService} from "./services/asg/gallerySyncService"
+export {asgCameraApi} from "./services/asg/asgCameraApi"
+export {localStorageService} from "./services/asg/localStorageService"
+export {mediaProcessingQueue} from "./services/asg/mediaProcessingQueue"
+export {gallerySettingsService} from "./services/asg/gallerySettingsService"
+export {cameraRollExportCoordinator, type CameraRollExportSummary} from "./services/asg/cameraRollExportCoordinator"
+export {
+  INVALID_DOWNLOADED_MEDIA,
+  validateCaptureMetadataForDownload,
+  validateDownloadedMediaFile,
+} from "./services/asg/galleryMediaValidation"
+export {emitGalleryNotice, onGalleryNotice} from "./services/asg/galleryNotices"
+
+// Phone-side capture coordinators.
+export {phonePhotoCoordinator} from "./services/PhonePhotoCoordinator"
+export {phoneStreamCoordinator} from "./services/PhoneStreamCoordinator"
+
+// Raw runtime stores (re-exported via the host @/stores/* shims). Read models
+// live on the engine facades; these are the migration escape hatch.
+export {useDisplayStore, flushDisplayCoalesceForTests} from "./stores/display"
+export {useCoreStore} from "./stores/core"
+export {useConnectionStore} from "./stores/connection"
+export {useCloudClientStatusStore} from "./stores/cloudClientStatus"
+export type {RuntimeAudioTransport, RuntimeSnapshot, RuntimeStatus} from "./stores/cloudClientStatus"
+export {SETTINGS, OFFLINE_APPLETS, useSettingsStore, useSetting} from "./stores/settings"
+export {MENTRA_LIVE_SETTING_KEYS, getBluetoothSettingKeysForDevice} from "./stores/bluetoothSettingKeys"
+export {useAppStatusStore, installAppStoreHooks, type AppStoreHooks} from "./stores/apps"
+
+// Cloud client + credentials + v1 comms.
+export {cloudSecureStore} from "./utils/cloudClient/cloudSecureStore"
+export {cloudClientService} from "./services/CloudClientService"
+export {createCloudUdpSocket} from "./utils/cloudClient/RnUdpAdapter"
+
+// Log ring buffer + console interception (bug-report attachments).
+export {logBuffer, type LogEntry} from "./utils/devLogging"
+
+// Bluetooth SDK internal compatibility passthrough. Prefer an engine facade
+// when one exists; this remains an escape hatch for app-only compatibility
+// needs (its event TYPES stay on the main entry).
+export {default as BluetoothSdk} from "@mentra/bluetooth-sdk/internal"
+
+
+// Engine-owned MMKV instance + debug helper.
+export {storage, printDirectory} from "./utils/storage"
+// Process-wide event bus — one shared instance for engine services + host
+// (re-exported via the @/utils/GlobalEventEmitter shim).
+export {default as GlobalEventEmitter} from "./utils/GlobalEventEmitter"