@glassly/engine 0.1.0-dev.0

package/build/utils/timers/timers.js

@@ -0,0 +1,142 @@
+// BgTimer — background-safe timers for the engine.
+//
+// Everything timing-critical in the engine runs through this class: the
+// miniapp liveness watchdog, display durationMs expiries, boot windows,
+// auth-token refresh. On Android, React Native PAUSES plain JS timers while
+// the app is backgrounded, so those features only keep working in the
+// background when the native implementation (react-native-nitro-bg-timer)
+// is active.
+//
+// Who actually gets native timers:
+//   - Android, dev AND release: always attempted — dev must match production
+//     background behavior. There is no opt-in/opt-out env var. If the native
+//     module is unavailable (a dev client whose binary predates it, or a
+//     broken release binary), the failure is LOUD: a console.error with the
+//     remediation, plus a blocking dev alert. The JS-timer fallback still
+//     engages so foreground behavior keeps working, but backgrounded
+//     behavior is broken until the native rebuild — the error says exactly
+//     that. (A silent dev fallback previously cost a full debugging day of
+//     phantom "zombie miniapp" bugs; see OS-1790.)
+//   - iOS: never, dev or prod — the package is disabled pending
+//     https://github.com/tconns/react-native-nitro-bg-timer/issues/2. iOS
+//     suspends the whole process in background anyway, so background timing
+//     there is handled by native per-device queues, not JS timers.
+import { Alert, Platform } from "react-native";
+let nitroTimer;
+let nitroDisabled = false;
+let failedLoud = false;
+/**
+ * The native background timer is unavailable — say so ONCE, loudly, with the
+ * remediation. The JS-timer fallback keeps foreground behavior working, but
+ * everything timing-driven freezes while the app is backgrounded, which
+ * presents as phantom miniapp bugs (frozen captions, missed wake words,
+ * watchdog kills on resume). A quiet warning here has already cost a full
+ * debugging day; never downgrade this to console.warn.
+ */
+function failUnavailable(reason) {
+    if (failedLoud) {
+        return;
+    }
+    failedLoud = true;
+    const message = `BgTimer: native background timer unavailable (${reason}). ` +
+        "Backgrounded behavior IS BROKEN until you rebuild the Android app: run `bun android`. " +
+        "Engine timers and local miniapps (captions, wake words) freeze whenever the app is not foregrounded.";
+    console.error(message);
+    if (__DEV__) {
+        // A stale dev client may ALSO show the library's own require-time red box
+        // (bridgeless LogBox surfaces it even though we catch below) — this alert
+        // is the actionable one: it names the fix.
+        try {
+            Alert.alert("Background timers unavailable", message);
+        }
+        catch {
+            /* Alert not available (tests / headless) — the console.error stands. */
+        }
+    }
+}
+function getNitroTimer() {
+    if (nitroDisabled || Platform.OS !== "android") {
+        return null;
+    }
+    if (nitroTimer !== undefined) {
+        return nitroTimer;
+    }
+    try {
+        const { isRuntimeAlive } = require("react-native-nitro-modules");
+        if (typeof isRuntimeAlive === "function" && !isRuntimeAlive()) {
+            nitroTimer = null;
+            failUnavailable("nitro runtime is not alive");
+            return nitroTimer;
+        }
+        const { BackgroundTimer } = require("react-native-nitro-bg-timer");
+        nitroTimer =
+            BackgroundTimer &&
+                typeof BackgroundTimer.setTimeout === "function" &&
+                typeof BackgroundTimer.setInterval === "function" &&
+                typeof BackgroundTimer.clearTimeout === "function" &&
+                typeof BackgroundTimer.clearInterval === "function"
+                ? BackgroundTimer
+                : null;
+    }
+    catch {
+        nitroTimer = null;
+        nitroDisabled = true;
+    }
+    if (!nitroTimer) {
+        failUnavailable("react-native-nitro-bg-timer failed to load");
+    }
+    return nitroTimer;
+}
+function withNitro(run, fallback) {
+    const api = getNitroTimer();
+    if (!api) {
+        return fallback();
+    }
+    try {
+        return run(api);
+    }
+    catch (error) {
+        nitroDisabled = true;
+        nitroTimer = null;
+        failedLoud = false; // a mid-session failure is new information — re-announce
+        failUnavailable(`nitro timer call threw: ${String(error)}`);
+        return fallback();
+    }
+}
+export class BgTimer {
+    static setInterval(callback, delay) {
+        return withNitro((api) => api.setInterval(callback, delay), () => setInterval(callback, delay));
+    }
+    static clearInterval(intervalId) {
+        withNitro((api) => api.clearInterval(intervalId), () => clearInterval(intervalId));
+    }
+    static setTimeout(callback, delay) {
+        return withNitro((api) => api.setTimeout(callback, delay), () => setTimeout(callback, delay));
+    }
+    static clearTimeout(timeoutId) {
+        withNitro((api) => api.clearTimeout(timeoutId), () => clearTimeout(timeoutId));
+    }
+}
+export function throttle(fn, ms) {
+    let lastCalled = 0;
+    return (...args) => {
+        const now = Date.now();
+        if (now - lastCalled >= ms) {
+            lastCalled = now;
+            fn(...args);
+        }
+    };
+}
+export function debounce(fn, ms) {
+    let timeoutId = null;
+    return (...args) => {
+        if (timeoutId) {
+            BgTimer.clearTimeout(timeoutId);
+        }
+        timeoutId = BgTimer.setTimeout(() => {
+            fn(...args);
+            timeoutId = null;
+        }, ms);
+    };
+}
+//# sourceMappingURL=timers.js.map

package/build/utils/timers/timers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timers.js","sourceRoot":"","sources":["../../../src/utils/timers/timers.ts"],"names":[],"mappings":"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","sourcesContent":["// BgTimer — background-safe timers for the engine.\n//\n// Everything timing-critical in the engine runs through this class: the\n// miniapp liveness watchdog, display durationMs expiries, boot windows,\n// auth-token refresh. On Android, React Native PAUSES plain JS timers while\n// the app is backgrounded, so those features only keep working in the\n// background when the native implementation (react-native-nitro-bg-timer)\n// is active.\n//\n// Who actually gets native timers:\n//   - Android, dev AND release: always attempted — dev must match production\n//     background behavior. There is no opt-in/opt-out env var. If the native\n//     module is unavailable (a dev client whose binary predates it, or a\n//     broken release binary), the failure is LOUD: a console.error with the\n//     remediation, plus a blocking dev alert. The JS-timer fallback still\n//     engages so foreground behavior keeps working, but backgrounded\n//     behavior is broken until the native rebuild — the error says exactly\n//     that. (A silent dev fallback previously cost a full debugging day of\n//     phantom \"zombie miniapp\" bugs; see OS-1790.)\n//   - iOS: never, dev or prod — the package is disabled pending\n//     https://github.com/tconns/react-native-nitro-bg-timer/issues/2. iOS\n//     suspends the whole process in background anyway, so background timing\n//     there is handled by native per-device queues, not JS timers.\n\nimport {Alert, Platform} from \"react-native\"\n\ntype NitroTimerApi = {\n  setInterval: (callback: () => void, delay: number) => number\n  clearInterval: (intervalId: number) => void\n  setTimeout: (callback: () => void, delay: number) => number\n  clearTimeout: (timeoutId: number) => void\n}\n\nlet nitroTimer: NitroTimerApi | null | undefined\nlet nitroDisabled = false\nlet failedLoud = false\n\n/**\n * The native background timer is unavailable — say so ONCE, loudly, with the\n * remediation. The JS-timer fallback keeps foreground behavior working, but\n * everything timing-driven freezes while the app is backgrounded, which\n * presents as phantom miniapp bugs (frozen captions, missed wake words,\n * watchdog kills on resume). A quiet warning here has already cost a full\n * debugging day; never downgrade this to console.warn.\n */\nfunction failUnavailable(reason: string) {\n  if (failedLoud) {\n    return\n  }\n  failedLoud = true\n  const message =\n    `BgTimer: native background timer unavailable (${reason}). ` +\n    \"Backgrounded behavior IS BROKEN until you rebuild the Android app: run `bun android`. \" +\n    \"Engine timers and local miniapps (captions, wake words) freeze whenever the app is not foregrounded.\"\n  console.error(message)\n  if (__DEV__) {\n    // A stale dev client may ALSO show the library's own require-time red box\n    // (bridgeless LogBox surfaces it even though we catch below) — this alert\n    // is the actionable one: it names the fix.\n    try {\n      Alert.alert(\"Background timers unavailable\", message)\n    } catch {\n      /* Alert not available (tests / headless) — the console.error stands. */\n    }\n  }\n}\n\nfunction getNitroTimer(): NitroTimerApi | null {\n  if (nitroDisabled || Platform.OS !== \"android\") {\n    return null\n  }\n\n  if (nitroTimer !== undefined) {\n    return nitroTimer\n  }\n\n  try {\n    const {isRuntimeAlive} = require(\"react-native-nitro-modules\") as {isRuntimeAlive?: () => boolean}\n    if (typeof isRuntimeAlive === \"function\" && !isRuntimeAlive()) {\n      nitroTimer = null\n      failUnavailable(\"nitro runtime is not alive\")\n      return nitroTimer\n    }\n\n    const {BackgroundTimer} = require(\"react-native-nitro-bg-timer\") as {BackgroundTimer?: NitroTimerApi}\n    nitroTimer =\n      BackgroundTimer &&\n      typeof BackgroundTimer.setTimeout === \"function\" &&\n      typeof BackgroundTimer.setInterval === \"function\" &&\n      typeof BackgroundTimer.clearTimeout === \"function\" &&\n      typeof BackgroundTimer.clearInterval === \"function\"\n        ? BackgroundTimer\n        : null\n  } catch {\n    nitroTimer = null\n    nitroDisabled = true\n  }\n\n  if (!nitroTimer) {\n    failUnavailable(\"react-native-nitro-bg-timer failed to load\")\n  }\n  return nitroTimer\n}\n\nfunction withNitro<T>(run: (api: NitroTimerApi) => T, fallback: () => T): T {\n  const api = getNitroTimer()\n  if (!api) {\n    return fallback()\n  }\n  try {\n    return run(api)\n  } catch (error) {\n    nitroDisabled = true\n    nitroTimer = null\n    failedLoud = false // a mid-session failure is new information — re-announce\n    failUnavailable(`nitro timer call threw: ${String(error)}`)\n    return fallback()\n  }\n}\n\nexport class BgTimer {\n  static setInterval(callback: () => void, delay: number): number {\n    return withNitro(\n      (api) => api.setInterval(callback, delay),\n      () => setInterval(callback, delay) as unknown as number,\n    )\n  }\n\n  static clearInterval(intervalId: number): void {\n    withNitro(\n      (api) => api.clearInterval(intervalId),\n      () => clearInterval(intervalId),\n    )\n  }\n\n  static setTimeout(callback: () => void, delay: number): number {\n    return withNitro(\n      (api) => api.setTimeout(callback, delay),\n      () => setTimeout(callback, delay) as unknown as number,\n    )\n  }\n\n  static clearTimeout(timeoutId: number): void {\n    withNitro(\n      (api) => api.clearTimeout(timeoutId),\n      () => clearTimeout(timeoutId),\n    )\n  }\n}\n\nexport function throttle<T extends (...args: any[]) => any>(fn: T, ms: number): (...args: Parameters<T>) => void {\n  let lastCalled = 0\n\n  return (...args: Parameters<T>) => {\n    const now = Date.now()\n    if (now - lastCalled >= ms) {\n      lastCalled = now\n      fn(...args)\n    }\n  }\n}\n\nexport function debounce<T extends (...args: any[]) => any>(fn: T, ms: number): (...args: Parameters<T>) => void {\n  let timeoutId: number | null = null\n\n  return (...args: Parameters<T>) => {\n    if (timeoutId) {\n      BgTimer.clearTimeout(timeoutId)\n    }\n    timeoutId = BgTimer.setTimeout(() => {\n      fn(...args)\n      timeoutId = null\n    }, ms)\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,122 @@
+{
+  "name": "@glassly/engine",
+  "version": "0.1.0-dev.0",
+  "description": "Glassly 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": "./scripts/test.sh",
+    "build:module": "expo-module build",
+    "prepublishOnly": "expo-module prepublishOnly",
+    "expo-module": "expo-module"
+  },
+  "keywords": [
+    "react-native",
+    "expo",
+    "engine",
+    "Engine",
+    "miniapp"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tetramo-labs/glassly.git",
+    "directory": "mobile/modules/engine"
+  },
+  "bugs": {
+    "url": "https://github.com/tetramo-labs/glassly/issues"
+  },
+  "author": "Glassly Community",
+  "license": "MIT",
+  "homepage": "https://github.com/tetramo-labs/glassly/tree/dev/mobile/modules/engine#readme",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@glassly/miniapp": "workspace:*",
+    "buffer": "^6.0.3",
+    "events": "^3.3.0",
+    "semver": "^7.7.4",
+    "typesafe-ts": "^1.7.1"
+  },
+  "devDependencies": {
+    "@glassly/bluetooth-sdk": "workspace:*",
+    "@glassly/cloud-client": "workspace:*",
+    "@glassly/cloud-protocol": "workspace:*",
+    "@glassly/llm-providers": "workspace:*",
+    "@types/semver": "^7.7.1",
+    "expo-module-scripts": "^56.0.3",
+    "expo-modules-core": "57.0.7",
+    "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-device": "*",
+    "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": "*",
+    "@glassly/bluetooth-sdk": "*",
+    "@glassly/crust": "^0.1.0-dev.1",
+    "@glassly/cloud-client": "^0.1.0-dev.0",
+    "@glassly/miniapp": "^0.3.0-dev.1",
+    "@glassly/cloud-protocol": "^0.1.0-dev.0"
+  }
+}

package/src/devtools.ts

@@ -0,0 +1,13 @@
+/**
+ * `@glassly/engine/devtools` — the devtools-only surface.
+ *
+ * Debug/diagnostic singletons consumed by the Glassly 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,198 @@
+/**
+ * `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 `@glassly/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 `@glassly/engine/internal` entry (and the debug singletons on
+ * `@glassly/engine/devtools`); they shrink as screens move onto `engine.*`.
+ */
+import {configure, start as bootstrapStart, stop as bootstrapStop, updateUiSeams} 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 sonioxDirectService from "./services/soniox/SonioxDirectService"
+import {startSupportProfileSync, stopSupportProfileSync} from "./services/SupportProfileSync"
+import {startDeviceEventRouter, stopDeviceEventRouter} from "./services/DeviceEventRouter"
+import {startPhoneNotificationsSync, stopPhoneNotificationsSync} from "./services/PhoneNotificationsSync"
+import {startSpeakerIdSync, stopSpeakerIdSync} from "./services/SpeakerIdSync"
+import {startCaptionsTesterReportService, stopCaptionsTesterReportService} from "./services/CaptionsTesterReportService"
+import {startJSCrashloopReportService, stopJSCrashloopReportService} from "./services/JSCrashloopReportService"
+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 {maps} from "./facades/maps"
+import {memory} from "./facades/memory"
+import {speakers} from "./facades/speakers"
+import {providerKeys} from "./facades/providerKeys"
+import {logBuffer} from "./utils/devLogging"
+
+export const engine = {
+  /** Front door — hand engine auth + config, then start/stop the runtime. */
+  configure,
+  /** Merge host-UI seams on a running runtime (scan overlay, wifi setup, …). */
+  updateUiSeams,
+  /** 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 Glassly 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
+    // Glassly 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 Glassly app's host-side MantleManager fork).
+    startAudioCloudUplink()
+    // Phone -> Soniox direct transcription (user-supplied API key). Started
+    // after device-store hydration so the persisted key is already loaded.
+    sonioxDirectService.start()
+    try {
+      await cloudClientService.syncCoreTokenToBluetooth()
+    } catch (error) {
+      console.warn(
+        "engine.start: initial Cloud V2 core token sync failed:",
+        error instanceof Error ? error.message : error,
+      )
+    }
+    startSupportProfileSync()
+    // Push device-setting changes to the glasses for ANY host, so
+    // engine.glasses.settings.set() reaches the device (not just the Glassly app).
+    startGlassesSettingsSync()
+    // Same for phone-notification config -> the native listener (Android).
+    startPhoneNotificationsSync()
+    // On-device speaker identification: sync the enabled setting + enrolled
+    // profile centroids to the native SpeakerIdEngine, and start the resolver
+    // that annotates cloud transcripts with resolved speaker identities.
+    startSpeakerIdSync()
+    // Android internal/e2e: laptop captions tester can broadcast a failure intent;
+    // engine owns turning that into a Cloud V2 report.
+    startCaptionsTesterReportService()
+    // GlasslyJS crashloop-disabled is runtime state; engine owns filing the
+    // automatic report while hosts only render alert/telemetry side effects.
+    startJSCrashloopReportService()
+    // Bring up the local-miniapp engine so a bare OEM can run GlasslyJS miniapps:
+    // the LocalMiniappRuntime (registry + WebView bridge), the GlasslyJS 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 Glassly app's host bootstrap also calls these, the
+    // second call is a no-op. Host-only crashloop telemetry is attached
+    // separately by the Glassly 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("soniox direct service", () => sonioxDirectService.stop())
+    await safely("support profile sync", stopSupportProfileSync)
+    await safely("phone notifications sync", stopPhoneNotificationsSync)
+    await safely("speaker id sync", stopSpeakerIdSync)
+    await safely("captions tester report service", stopCaptionsTesterReportService)
+    await safely("glasslyjs crashloop report service", stopJSCrashloopReportService)
+    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.shutdown())
+    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,
+  /** Maps providers — user-supplied Mapbox access token (Settings > Keys). */
+  maps,
+  /** Shared user-scoped memory timeline (Settings > Memory + session.memory). */
+  memory,
+  /** Device-local voice profiles for on-device speaker ID (Settings > Speakers). */
+  speakers,
+  /** AI/voice provider key validation — user-supplied keys (Settings > API Keys). */
+  providerKeys,
+  display,
+}