@mentra/engine 0.1.0-beta.0

package/package.json

@@ -0,0 +1,120 @@
+{
+  "name": "@mentra/engine",
+  "version": "0.1.0-beta.0",
+  "description": "Mentra Engine — miniapp registry, WebView bridge, and miniapp store",
+  "main": "build/index.js",
+  "react-native": "src/index.ts",
+  "types": "build/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/index.d.ts",
+      "react-native": "./src/index.ts",
+      "default": "./build/index.js"
+    },
+    "./internal": {
+      "types": "./build/internal.d.ts",
+      "react-native": "./src/internal.ts",
+      "default": "./build/internal.js"
+    },
+    "./devtools": {
+      "types": "./build/devtools.d.ts",
+      "react-native": "./src/devtools.ts",
+      "default": "./build/devtools.js"
+    },
+    "./build/*": null,
+    "./src/*": null,
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "build",
+    "README.md",
+    "src",
+    "!src/**/__tests__",
+    "!src/**/*.test.ts"
+  ],
+  "scripts": {
+    "build": "expo-module build",
+    "clean": "expo-module clean",
+    "lint": "expo-module lint",
+    "test": "bun test src",
+    "build:module": "expo-module prepare",
+    "prepublishOnly": "expo-module prepublishOnly",
+    "expo-module": "expo-module"
+  },
+  "keywords": [
+    "react-native",
+    "expo",
+    "engine",
+    "Engine",
+    "miniapp"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mentra-Community/MentraOS.git",
+    "directory": "mobile/modules/engine"
+  },
+  "bugs": {
+    "url": "https://github.com/Mentra-Community/MentraOS/issues"
+  },
+  "author": "Mentra Community",
+  "license": "MIT",
+  "homepage": "https://github.com/Mentra-Community/MentraOS/tree/dev/mobile/modules/engine#readme",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "buffer": "^6.0.3",
+    "events": "^3.3.0",
+    "semver": "^7.7.4",
+    "typesafe-ts": "^1.7.1"
+  },
+  "devDependencies": {
+    "@mentra/bluetooth-sdk": "workspace:*",
+    "@mentra/cloud-client": "workspace:*",
+    "@mentra/cloud-protocol": "workspace:*",
+    "@mentra/miniapp": "workspace:*",
+    "@types/semver": "^7.7.1",
+    "expo-module-scripts": "^55.0.2",
+    "expo-modules-core": "55.0.25",
+    "react-native-nitro-modules": "^0.31.10",
+    "typescript": "~5.9.2"
+  },
+  "peerDependencies": {
+    "expo": "*",
+    "expo-modules-core": "*",
+    "react": "*",
+    "react-native": "*",
+    "react-native-udp": "*",
+    "@types/react": "*",
+    "react-native-mmkv": "*",
+    "react-native-nitro-bg-timer": "*",
+    "react-native-nitro-modules": "*",
+    "react-native-reanimated": "*",
+    "expo-file-system": "*",
+    "react-native-zip-archive": "*",
+    "zustand": "*",
+    "expo-battery": "*",
+    "expo-audio": "*",
+    "expo-clipboard": "*",
+    "expo-calendar": "*",
+    "expo-constants": "*",
+    "expo-location": "*",
+    "expo-task-manager": "*",
+    "expo-notifications": "*",
+    "react-native-share": "*",
+    "react-native-localize": "*",
+    "react-native-ble-manager": "*",
+    "react-native-permissions": "*",
+    "react-native-wifi-reborn": "*",
+    "@react-native-community/netinfo": "*",
+    "@dr.pogodin/react-native-fs": "*",
+    "@craftzdog/react-native-buffer": "*",
+    "axios": "*",
+    "@mentra/bluetooth-sdk": "*",
+    "@mentra/crust": "^0.1.0-beta.0",
+    "@mentra/cloud-client": "^0.1.0-beta.0",
+    "@mentra/miniapp": "^0.3.0-beta.0",
+    "@mentra/cloud-protocol": "^0.1.0-beta.0"
+  }
+}

package/src/devtools.ts

@@ -0,0 +1,13 @@
+/**
+ * `@mentra/engine/devtools` — the devtools-only surface.
+ *
+ * Debug/diagnostic singletons consumed by the Mentra app's internal dev
+ * screens (stress test, miniapp dev-server tooling). Never import this from
+ * product UI or host services; every `/devtools` import in mobile/src is
+ * counted (report-only) by scripts/check-mobile-runtime-boundary.sh.
+ */
+
+// Which miniapps the local runtime currently has running (stress-test screen).
+export {miniappRunningRegistry} from "./services/MiniappRunningRegistry"
+// Dev-server connection bridge for live-reloading local miniapps.
+export {default as devServerBridge} from "./services/DevServerBridge"

package/src/engine.ts

@@ -0,0 +1,173 @@
+/**
+ * `engine` — the namespaced OEM-facing engine API (the "(A) host API" from the
+ * Phase-1 contract). Host UI calls `engine.<domain>.<method>()`; each domain is a
+ * typed facade over the runtime. (Exported from the `@mentra/engine` module, whose
+ * name stays `engine` in code; the public API surface is `engine`.)
+ *
+ * It grows one facade at a time. The migration-era flat store/service exports
+ * live on the `@mentra/engine/internal` entry (and the debug singletons on
+ * `@mentra/engine/devtools`); they shrink as screens move onto `engine.*`.
+ */
+import {configure, start as bootstrapStart, stop as bootstrapStop} from "./runtime/bootstrap"
+import {cloudClientService} from "./services/CloudClientService"
+import {hydrateDeviceStore, demoteOrphanedDefaultWearable} from "./services/DeviceStoreHydration"
+import {startGlassesSettingsSync, stopGlassesSettingsSync} from "./services/GlassesSettingsSync"
+import {startGlassesStatusProjection, stopGlassesStatusProjection} from "./services/GlassesStatusProjection"
+import {startOtaService, stopOtaService} from "./services/OtaService"
+import {startAudioCloudUplink, stopAudioCloudUplink} from "./services/AudioCloudUplink"
+import {startDeviceEventRouter, stopDeviceEventRouter} from "./services/DeviceEventRouter"
+import {startPhoneNotificationsSync, stopPhoneNotificationsSync} from "./services/PhoneNotificationsSync"
+import {startCaptionsTesterReportService, stopCaptionsTesterReportService} from "./services/CaptionsTesterReportService"
+import {
+  startMentraJSCrashloopReportService,
+  stopMentraJSCrashloopReportService,
+} from "./services/MentraJSCrashloopReportService"
+import {ensureMiniappEngine, stopMiniappEngine} from "./services/MiniappEngine"
+import localMiniappRuntime from "./services/LocalMiniappRuntime"
+import displayProcessor from "./services/DisplayProcessor"
+import {gallerySyncService} from "./services/asg/gallerySyncService"
+import {glasses} from "./facades/glasses"
+import {display} from "./facades/display"
+import {speech} from "./facades/speech"
+import {session} from "./facades/session"
+import {settings} from "./facades/settings"
+import {dev} from "./facades/dev"
+import {reports} from "./facades/reports"
+import {ota} from "./facades/ota"
+import {gallery} from "./facades/gallery"
+import {miniapps} from "./facades/miniapps"
+import {pairing} from "./facades/pairing"
+import {phoneNotifications} from "./facades/phoneNotifications"
+import {permissions} from "./facades/permissions"
+import {notifications} from "./facades/notifications"
+import {logBuffer} from "./utils/devLogging"
+
+export const engine = {
+  /** Front door — hand engine auth + config, then start/stop the runtime. */
+  configure,
+  /** Start the runtime: mark started + construct/connect the cloud client + begin
+   * syncing device settings to the glasses. */
+  async start() {
+    // Reports attach recent phone logs, so engine owns console interception for
+    // OEM hosts too. Idempotent; the Mentra host may start it earlier.
+    logBuffer.startConsoleInterception()
+    await bootstrapStart()
+    // Construct + connect the cloud client so the documented configure()+start()
+    // lifecycle yields a live engine.session for OEMs. Idempotent for repeated
+    // start() calls.
+    cloudClientService.init()
+    // Project native device status -> the engine stores (the inbound feed the rest
+    // of the runtime reads). Established first so the stores are live before the
+    // syncs below react to them.
+    startGlassesStatusProjection()
+    // Route the rest of the inbound device events (wifi/hotspot/gallery -> stores+bus,
+    // photo/stream -> coordinators, button/touch/accel/head -> miniapps, save_setting ->
+    // store, miniapp_selected -> launcher) so a bare OEM gets device data, not just the
+    // Mentra app's MantleManager.
+    startDeviceEventRouter()
+    // Hydration contract: the native DeviceStore is in-memory and starts empty
+    // every launch; seed it from the persisted settings BEFORE start() resolves
+    // so every post-start getDefaultDevice() read is a trustworthy two-state
+    // answer (no false "absent" for genuinely-paired users at cold start).
+    // Ordered before startGlassesSettingsSync so the settings load can't
+    // double-push through the change subscription. A failed hydration must not
+    // brick the runtime: start() continues, and the guards that consume
+    // hasDefaultDevice() see the rejection and fail open.
+    try {
+      await hydrateDeviceStore()
+      // Boot repair: a persisted default_wearable without a native default
+      // device (identity abandoned mid-pairing, or resurrected from the server
+      // before identity stopped syncing) demotes to pending_wearable so hosts
+      // render finish-pairing instead of a connect that would throw.
+      await demoteOrphanedDefaultWearable()
+    } catch (error) {
+      console.warn("engine.start: device-store hydration failed:", error instanceof Error ? error.message : error)
+    }
+    // Project the glasses' OTA events into the store for the engine.ota read surface.
+    startOtaService()
+    // Forward glasses mic_lc3 frames to the v2 cloud session so cloud transcription
+    // works for any host (not just the Mentra app's host-side MantleManager fork).
+    startAudioCloudUplink()
+    try {
+      await cloudClientService.syncCoreTokenToBluetooth()
+    } catch (error) {
+      console.warn(
+        "engine.start: initial Cloud V2 core token sync failed:",
+        error instanceof Error ? error.message : error,
+      )
+    }
+    // Push device-setting changes to the glasses for ANY host, so
+    // engine.glasses.settings.set() reaches the device (not just the Mentra app).
+    startGlassesSettingsSync()
+    // Same for phone-notification config -> the native listener (Android).
+    startPhoneNotificationsSync()
+    // Android internal/e2e: laptop captions tester can broadcast a failure intent;
+    // engine owns turning that into a Cloud V2 report.
+    startCaptionsTesterReportService()
+    // MentraJS crashloop-disabled is runtime state; engine owns filing the
+    // automatic report while hosts only render alert/telemetry side effects.
+    startMentraJSCrashloopReportService()
+    // Bring up the local-miniapp engine so a bare OEM can run MentraJS miniapps:
+    // the LocalMiniappRuntime (registry + WebView bridge), the MentraJS router
+    // (crust-bound spawn/dispatch pump + launcher wiring), the DisplayProcessor
+    // (layout arbitration over the engine stores), and the gallery-sync service.
+    // All idempotent — when the Mentra app's host bootstrap also calls these, the
+    // second call is a no-op. Host-only crashloop telemetry is attached
+    // separately by the Mentra app.
+    localMiniappRuntime.initialize()
+    ensureMiniappEngine()
+    displayProcessor.attachToRuntime()
+    gallerySyncService.initialize()
+  },
+  /** Stop the runtime: tear down the settings sync + cloud client + mark stopped.
+   * Each step is guarded so one failing teardown can't skip the rest and leak
+   * the remaining runtime services. */
+  async stop() {
+    const safely = async (label: string, step: () => unknown): Promise<void> => {
+      try {
+        await step()
+      } catch (error) {
+        console.warn(`engine.stop: ${label} failed:`, error)
+      }
+    }
+    await safely("glasses settings sync", stopGlassesSettingsSync)
+    await safely("glasses status projection", stopGlassesStatusProjection)
+    await safely("device event router", stopDeviceEventRouter)
+    await safely("ota service", stopOtaService)
+    await safely("audio cloud uplink", stopAudioCloudUplink)
+    await safely("phone notifications sync", stopPhoneNotificationsSync)
+    await safely("captions tester report service", stopCaptionsTesterReportService)
+    await safely("mentrajs crashloop report service", stopMentraJSCrashloopReportService)
+    await safely("miniapp engine", stopMiniappEngine)
+    await safely("local miniapp runtime", () => localMiniappRuntime.cleanup())
+    await safely("display processor", () => displayProcessor.detachFromRuntime())
+    await safely("gallery sync service", () => gallerySyncService.cleanup())
+    await safely("cloud client", () => cloudClientService.stop())
+    await safely("bootstrap", bootstrapStop)
+  },
+  glasses,
+  speech,
+  /** Cloud (cloud-v2) live-session status + account ops — engine owns the client. */
+  session,
+  /** Typed keyed user settings over the engine-owned settings store. */
+  settings,
+  /** Developer/debug surface (backend+cloud URL overrides, reconnect, min version). */
+  dev,
+  /** Bug-report, automatic runtime report, and feedback submission. */
+  reports,
+  /** Firmware OTA read/observe surface (updateAvailable/status + on* subscriptions). */
+  ota,
+  /** Gallery sync: status/onStatus · onNotice (host renders) · sync/cancel. */
+  gallery,
+  /** Miniapp lifecycle (the WebView bridge primitives are exported separately). */
+  miniapps,
+  /** First-time glasses discovery + pairing. */
+  pairing,
+  /** Phone→glasses notification forwarding (Android). */
+  phoneNotifications,
+  /** OS permissions (check/request/openSettings + per-miniapp requirements). */
+  permissions,
+  /** Inbound alerts engine→host (crashloop, version-incompatible, connection loss). */
+  notifications,
+  display,
+}

package/src/facades/dev.ts

@@ -0,0 +1,198 @@
+/**
+ * dev facade — `engine.dev`: developer/debug surface over engine-owned state.
+ * Backend/cloud URL overrides read+write the engine settings store; the cloud
+ * URL setters reconnect the engine-owned cloud client onto the new endpoints;
+ *
+ * NOTE: the dev-time endpoint *resolution* (Metro-host auto-detect, env defaults)
+ * still lives host-side in `@/services/cloudClient` during the migration; this
+ * facade manages the explicit overrides + reconnect.
+ */
+import BluetoothSdk from "@mentra/bluetooth-sdk/internal"
+import {isGlassesReady} from "../services/GlassesReadiness"
+import {useCloudClientStatusStore} from "../stores/cloudClientStatus"
+import {useConnectionStore} from "../stores/connection"
+import {useCoreStore} from "../stores/core"
+import {useGlassesStore} from "../stores/glasses"
+import {useSettingsStore, SETTINGS} from "../stores/settings"
+import {cloudClientService} from "../services/CloudClientService"
+import {getConfigValues} from "../runtime/bootstrap"
+import {decideDevLaunchRoute} from "../utils/devMiniappLaunch"
+import {registerDevApp, DEV_APP_PACKAGE_NAME, type DevAppRecord} from "../services/AppRegistry"
+import {useAppStatusStore} from "../stores/apps"
+
+type CloudUrlOverrides = {core?: string; runtime?: string}
+
+/**
+ * Reconnect the cloud client onto the current cloud-URL overrides. Explicit
+ * partial overrides merge over the boot-resolved config (which carries the
+ * host's Metro/env URL resolution); both empty clears the live override.
+ */
+function applyCloudUrlReconnect(urls: CloudUrlOverrides = currentCloudUrlOverrides()): void {
+  const resolved = resolveCloudUrlReconnectTarget(urls)
+  if (resolved === undefined) {
+    cloudClientService.reconnect(null)
+  } else if (resolved) {
+    cloudClientService.reconnect(resolved)
+  } else {
+    console.warn("engine.dev.setCloudUrls: partial cloud override missing boot-resolved sibling endpoint")
+  }
+}
+
+function currentCloudUrlOverrides(): CloudUrlOverrides {
+  const s = useSettingsStore.getState()
+  return {
+    core: trimSetting(s.getSetting(SETTINGS.cloud_core_url.key)),
+    runtime: trimSetting(s.getSetting(SETTINGS.cloud_runtime_url.key)),
+  }
+}
+
+function resolveCloudUrlReconnectTarget(urls: CloudUrlOverrides): {core: string; runtime: string} | null | undefined {
+  const core = trimSetting(urls.core)
+  const runtime = trimSetting(urls.runtime)
+  if (!core && !runtime) return undefined
+
+  const config = getConfigValues()
+  const resolvedCore = core || config.coreUrl?.trim()
+  const resolvedRuntime = runtime || config.runtimeUrl?.trim()
+  return resolvedCore && resolvedRuntime ? {core: resolvedCore, runtime: resolvedRuntime} : null
+}
+
+function trimSetting(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined
+}
+
+function projectRuntimeStatus() {
+  const core = useCoreStore.getState()
+  const glasses = useGlassesStore.getState()
+  const connection = useConnectionStore.getState()
+  const cloudClient = useCloudClientStatusStore.getState()
+  return {
+    searching: core.searching,
+    // Copy: the snapshot must not hand callers a mutable reference into the store.
+    micRanking: [...core.micRanking],
+    currentMic: core.currentMic,
+    systemMicUnavailable: core.systemMicUnavailable,
+    glassesConnected: glasses.connection.state === "connected",
+    glassesFullyBooted: isGlassesReady(glasses.connection),
+    bluetoothClassicConnected: glasses.bluetoothClassicConnected,
+    coreStatus: connection.status,
+    cloudClientStatus: cloudClient.status,
+    cloudClientAudioTransport: cloudClient.audioTransport,
+  }
+}
+
+export type DevRuntimeStatusSnapshot = ReturnType<typeof projectRuntimeStatus>
+
+export const dev = {
+  /** The cloud-v2 core/runtime URL overrides. */
+  cloudUrls: (): {core?: string; runtime?: string} => {
+    const s = useSettingsStore.getState()
+    return {core: s.getSetting(SETTINGS.cloud_core_url.key), runtime: s.getSetting(SETTINGS.cloud_runtime_url.key)}
+  },
+  /** Override the cloud-v2 URLs and reconnect the live client onto them. */
+  setCloudUrls: (urls: {core?: string; runtime?: string}) => {
+    const next = {...currentCloudUrlOverrides(), ...urls}
+    const resolved = resolveCloudUrlReconnectTarget(next)
+    if (resolved === null) {
+      console.warn("engine.dev.setCloudUrls: ignoring partial cloud override without a resolvable sibling endpoint")
+      return
+    }
+
+    const s = useSettingsStore.getState()
+    if (urls.core !== undefined) s.setSetting(SETTINGS.cloud_core_url.key, urls.core)
+    if (urls.runtime !== undefined) s.setSetting(SETTINGS.cloud_runtime_url.key, urls.runtime)
+    if (resolved === undefined) {
+      cloudClientService.reconnect(null)
+    } else {
+      cloudClientService.reconnect(resolved)
+    }
+  },
+
+  /** Tear down + rebuild the live cloud client (the dev "reconnect" button). */
+  reconnectCloud: (): void => applyCloudUrlReconnect(),
+
+  /** Current native (BLE-process) memory usage in MB — a dev/diagnostics gauge. */
+  getMemoryMB: (): number => BluetoothSdk.getMemoryMB(),
+  /**
+   * Phone-side bluetooth runtime snapshot (the core store read-model: scan/mic/
+   * search state) — the diagnostics/data-export surface. Shallow copy.
+   */
+  bluetoothStatus: (): Record<string, unknown> => {
+    const {setCoreInfo: _setCoreInfo, reset: _reset, ...state} = useCoreStore.getState()
+    return {...state}
+  },
+
+  /**
+   * Side-load a miniapp being served from a dev machine (the `mentra dev` / CLI
+   * flow) by its URL: probes `<url>/miniapp.json`, and on a reachable manifest
+   * registers it under its manifest package so it appears in `engine.miniapps`
+   * and can coexist with other dev miniapps. This is the OEM-host equivalent
+   * of the first-party
+   * developer-URL screen — the registration itself is engine-internal, so a
+   * host reaches it here rather than the internal registry. Rendering still
+   * flows through the normal display path once the miniapp is started.
+   */
+  loadDevMiniapp: async (
+    url: string,
+    name?: string,
+  ): Promise<{ok: true; packageName: string; name: string} | {ok: false; error: string}> => {
+    const devUrl = url.trim().replace(/\/+$/, "")
+    if (!devUrl) return {ok: false, error: "empty url"}
+    const result = await decideDevLaunchRoute("", devUrl)
+    if (result.decision !== "live") {
+      return {ok: false, error: "dev server unreachable, or no miniapp.json served there"}
+    }
+    const manifest = result.manifest
+    // The `mentra-miniapp dev` server puts the hot-reload/log sidecar on the
+    // user port PLUS ONE — same convention as the first-party developer-URL
+    // screen's deriveDevPort.
+    let devPort: number | undefined
+    try {
+      const parsed = Number(new URL(devUrl).port)
+      devPort = Number.isFinite(parsed) && parsed > 0 ? parsed + 1 : undefined
+    } catch {
+      devPort = undefined
+    }
+    const appName = name ?? manifest.name ?? "Dev Miniapp"
+    const packageName = (manifest.packageName as string | undefined) ?? DEV_APP_PACKAGE_NAME
+    const existing = useAppStatusStore.getState().apps.find((app) => app.packageName === packageName)
+    if (existing?.running) await useAppStatusStore.getState().stop(packageName)
+    await registerDevApp({
+      packageName,
+      name: appName,
+      iconUrl: manifest.icon ? new URL(manifest.icon, `${devUrl}/`).toString() : `${devUrl}/icon.png`,
+      devUrl,
+      devPort,
+      type: manifest.type as DevAppRecord["type"],
+      permissions: manifest.permissions as DevAppRecord["permissions"],
+      hardwareRequirements: manifest.hardwareRequirements as DevAppRecord["hardwareRequirements"],
+      actions: manifest.actions as DevAppRecord["actions"],
+    })
+    await useAppStatusStore.getState().refresh()
+    return {ok: true, packageName, name: appName}
+  },
+
+  /** Current engine runtime status for engine-owned debug surfaces. */
+  runtimeStatus: (): DevRuntimeStatusSnapshot => projectRuntimeStatus(),
+
+  /** Subscribe to the projected engine runtime status; returns an unsubscribe. */
+  onRuntimeStatus: (cb: (status: DevRuntimeStatusSnapshot) => void): (() => void) => {
+    let last = JSON.stringify(projectRuntimeStatus())
+    const notify = () => {
+      const snap = projectRuntimeStatus()
+      const key = JSON.stringify(snap)
+      if (key === last) return
+      last = key
+      cb(snap)
+    }
+    const unsubscribers = [
+      useCoreStore.subscribe(notify),
+      useGlassesStore.subscribe(notify),
+      useConnectionStore.subscribe(notify),
+      useCloudClientStatusStore.subscribe(notify),
+    ]
+    return () => {
+      unsubscribers.forEach((unsubscribe) => unsubscribe())
+    }
+  },
+}

package/src/facades/display.ts

@@ -0,0 +1,17 @@
+/**
+ * display facade — `engine.display`: the host/OEM display surface. `mirror`
+ * exposes the mirrored-view read-model; `text`/`clear` are raw passthroughs to the
+ * glasses display for dev tools and escape-hatch use (normal rendering goes through
+ * the engine DisplayProcessor / layout system, not these).
+ */
+import BluetoothSdk from "@mentra/bluetooth-sdk/internal"
+import {displayMirror} from "./displayMirror"
+
+export const display = {
+  /** Mirrored-view read-model (current/onMirror/view/setView). */
+  mirror: displayMirror,
+  /** Write raw text to the glasses display at (x, y) with a font size. */
+  text: (...args: Parameters<typeof BluetoothSdk.displayText>) => BluetoothSdk.displayText(...args),
+  /** Clear the glasses display. */
+  clear: (): Promise<void> => BluetoothSdk.clearDisplay(),
+}

package/src/facades/displayMirror.ts

@@ -0,0 +1,33 @@
+/**
+ * glasses display mirror — the typed read facade over the (now engine-owned)
+ * display store, for a phone-side preview of the glasses screen
+ * (`engine.display.mirror`). The store is fed by the display paths
+ * (LocalDisplayManager + the cloud path) via `setDisplayEvent`; this facade is the
+ * read side: `current()` (snapshot) + `onMirror(cb)` (subscribe). The raw store is
+ * also exposed as `engine.displayStore` (the Mentra-app escape hatch).
+ */
+import {useDisplayStore} from "../stores/display"
+
+export type DisplayMirrorEvent = Record<string, unknown> & {view?: string; layout?: any}
+
+export const displayMirror = {
+  /** The display event currently shown on the previewed view (snapshot). */
+  current(): DisplayMirrorEvent {
+    // Copy: the snapshot must not hand callers a mutable reference into the store.
+    return {...useDisplayStore.getState().currentEvent}
+  },
+
+  /** Subscribe to changes of the previewed display event; returns an unsubscribe. */
+  onMirror(cb: (event: DisplayMirrorEvent) => void): () => void {
+    return useDisplayStore.subscribe((s) => s.currentEvent, cb)
+  },
+
+  /** Which view is previewed — the main screen or the dashboard. */
+  view(): string {
+    return useDisplayStore.getState().view
+  },
+  /** Switch the previewed view between `"main"` and `"dashboard"`. */
+  setView(view: "main" | "dashboard"): void {
+    useDisplayStore.getState().setView(view)
+  },
+}

package/src/facades/gallery.ts

@@ -0,0 +1,69 @@
+/**
+ * gallery facade — `engine.gallery`: the OEM-facing gallery-sync surface. Engine's
+ * gallerySyncService orchestrates the sync (hotspot → wifi → HTTP fetch → process →
+ * store); this facade exposes the projected status + the structured notices the host
+ * renders its own UI from, plus the sync/cancel actions. No host-injected UI — the host
+ * owns all alerts/navigation/i18n (it renders them off `onNotice`).
+ */
+import {
+  useGallerySyncStore,
+  selectSyncProgress,
+  selectIssyncing,
+  selectGlassesGalleryStatus,
+} from "../stores/gallerySync"
+import {gallerySyncService} from "../services/asg/gallerySyncService"
+import {onGalleryNotice, type GalleryNotice} from "../services/asg/galleryNotices"
+
+function projectStatus() {
+  const s = useGallerySyncStore.getState()
+  const progress = selectSyncProgress(s)
+  return {
+    ...progress,
+    processingFiles: Array.from(progress.processingFiles),
+    processedFiles: s.processedFiles,
+    isSyncing: selectIssyncing(s),
+    isStarting: gallerySyncService.isSyncStarting(),
+    glassesGallery: selectGlassesGalleryStatus(s),
+    // Copy: the snapshot must not hand callers a mutable reference into the store
+    // (each queue item is copied too — callers must not mutate them in place).
+    queue: s.queue.map((item) => ({...item})),
+    queueLength: s.queue.length,
+    queueIndex: s.queueIndex,
+  }
+}
+
+export type GallerySyncStatus = ReturnType<typeof projectStatus>
+
+export const gallery = {
+  /** Snapshot of the current sync state + progress. */
+  status: (): GallerySyncStatus => projectStatus(),
+  /** Subscribe to sync-state changes; returns an unsubscribe. Deduped on the projected
+   * status (the gallerySync store mutates many unrelated fields during a sync), so the
+   * host only re-renders when the projection actually changes — matches the other
+   * read-model facades. */
+  onStatus: (cb: (status: GallerySyncStatus) => void): (() => void) => {
+    let last = JSON.stringify(projectStatus())
+    return useGallerySyncStore.subscribe(() => {
+      const status = projectStatus()
+      const serialized = JSON.stringify(status)
+      if (serialized === last) return
+      last = serialized
+      cb(status)
+    })
+  },
+  /** Subscribe to user-actionable notices (host renders alerts / settings deep-links). */
+  onNotice: (cb: (notice: GalleryNotice) => void): (() => void) => onGalleryNotice(cb),
+
+  /** Start a gallery sync (the host gates connectivity/permissions first). */
+  sync: (): Promise<void> => gallerySyncService.startSync(),
+  /** Cancel an in-progress sync. */
+  cancel: (): Promise<void> => gallerySyncService.cancelSync(),
+  /** Ask glasses to refresh their gallery summary counts. */
+  refreshStatus: (): Promise<void> => gallerySyncService.queryGlassesGalleryStatus(),
+  /** Remove local files from the current gallery queue after host-owned deletion UI completes. */
+  removeFilesFromQueue: (fileNames: string[]): void => useGallerySyncStore.getState().removeFilesFromQueue(fileNames),
+  /** Clear the current gallery sync queue after host-owned bulk deletion completes. */
+  clearQueue: (): void => useGallerySyncStore.getState().clearQueue(),
+  /** Clear the cached glasses gallery summary when product UI observes disconnect. */
+  clearGlassesGalleryStatus: (): void => useGallerySyncStore.getState().clearGlassesGalleryStatus(),
+}