@mentra/engine 0.1.0-beta.0

package/README.md

@@ -0,0 +1,79 @@
+# @mentra/engine
+
+Mentra Engine — the on-device miniapp library.
+
+## Installation
+
+```sh
+npm install @mentra/engine
+```
+
+> **Peer packages:** the engine's `@mentra/*` peer dependencies (`crust`,
+> `cloud-client`, `cloud-protocol`, `miniapp`) must be available to your
+> package manager. Until every peer is published to npm, consume the engine
+> from this monorepo's workspace (as the example OEM app does).
+
+> **Module format:** the published entry points target **React Native /
+> Metro** consumers (the `react-native` exports condition). Loading
+> `@mentra/engine` from plain Node (`require`/ESM) is not supported at 0.1.x —
+> the `default` condition's build output is ESM with extensionless imports and
+> will not resolve under Node's loader.
+
+## Entry points
+
+The package exposes three entry points (declared in `package.json` `exports`,
+with the `react-native` condition pointing at `src/` so Metro, tsc and jest
+resolve live TypeScript source):
+
+- **`@mentra/engine`** (main, `src/index.ts`) — the OEM-facing surface: the
+  `engine` namespace (`configure`/`start`/`stop` + typed domain facades),
+  contract/read-model types, and pure helpers host UI renders with
+  (`decideReconnect`, `deriveDisplayState`, the `useApps`-style hooks,
+  OTA policy constants, hardware capability tables, `BgTimer`). Judgment rule:
+  read models, commands, pure functions and types are main; anything that
+  mutates runtime state or exposes a store/service is not.
+- **`@mentra/engine/internal`** (`src/internal.ts`) — the migration-era
+  runtime surface: raw zustand stores (`useCoreStore`, `useSettingsStore`,
+  `useAppStatusStore`, …) and service singletons (`appRegistry`, `restComms`,
+  `cloudClientService`, the gallery cluster, the miniapp engine, …). The
+  host's `@/stores/*` shims re-export from here. New host code should use
+  `engine.*` instead; `scripts/check-mobile-runtime-boundary.sh` counts every
+  `/internal` import in `mobile/src` (report-only) as the burn-down metric.
+- **`@mentra/engine/devtools`** (`src/devtools.ts`) — debug-only singletons
+  (`miniappRunningRegistry`, `devServerBridge`) for the internal dev screens.
+
+See `cloud-v2/docs/issues/020-glasses-status-boundary/integration-review.md`
+§D for the burn-down plan.
+
+This module owns the pieces of miniapp logic and handling that aren't tied to
+the rest of the manager app: the WebView message bus, the in-memory running
+registry, and the JS globals that we inject into every miniapp WebView.
+
+The goal is for all miniapp logic to live here over time. Today the move is
+incremental — only the self-contained services have moved. Cross-cutting
+services (LocalMiniappRuntime, MantleManager, Composer install pipeline) still
+live under `mobile/src/` because they reach back into the manager's stores and
+sockets.
+
+## Public surface
+
+```ts
+import {engine, decideDevLaunchRoute} from "@mentra/engine"
+import {webviewBridge, buildMiniappGlobalsScript} from "@mentra/engine/internal"
+import {miniappRunningRegistry} from "@mentra/engine/devtools"
+```
+
+- `webviewBridge` — registers per-package WebView message handlers so any
+  service can `postMessage` JSON into a specific miniapp.
+- `miniappRunningRegistry` — session-scoped set of currently-mounted local
+  miniapp packageNames (foreground + background).
+- `buildMiniappGlobalsScript` — builds the `window.MentraOS` injection script
+  (and CSS variables / console-tap shim) used by every miniapp WebView.
+- `decideDevLaunchRoute` — pre-flight a dev URL's `miniapp.json` to decide
+  whether to mount live or take the user to the offline screen.
+
+## Imports
+
+Inside `mobile/modules/engine/src/`, use **relative paths** (`./services/...`,
+`../utils/...`). The mobile app's `@/*` alias is not configured here — there
+is no build-time path rewriter for this module.

package/build/devtools.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `@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.
+ */
+export { miniappRunningRegistry } from "./services/MiniappRunningRegistry";
+export { default as devServerBridge } from "./services/DevServerBridge";
+//# sourceMappingURL=devtools.d.ts.map

package/build/devtools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"devtools.d.ts","sourceRoot":"","sources":["../src/devtools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAC,sBAAsB,EAAC,MAAM,mCAAmC,CAAA;AAExE,OAAO,EAAC,OAAO,IAAI,eAAe,EAAC,MAAM,4BAA4B,CAAA"}

package/build/devtools.js

@@ -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";
+//# sourceMappingURL=devtools.js.map

package/build/devtools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"devtools.js","sourceRoot":"","sources":["../src/devtools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,+EAA+E;AAC/E,OAAO,EAAC,sBAAsB,EAAC,MAAM,mCAAmC,CAAA;AACxE,kEAAkE;AAClE,OAAO,EAAC,OAAO,IAAI,eAAe,EAAC,MAAM,4BAA4B,CAAA","sourcesContent":["/**\n * `@mentra/engine/devtools` — the devtools-only surface.\n *\n * Debug/diagnostic singletons consumed by the Mentra app's internal dev\n * screens (stress test, miniapp dev-server tooling). Never import this from\n * product UI or host services; every `/devtools` import in mobile/src is\n * counted (report-only) by scripts/check-mobile-runtime-boundary.sh.\n */\n\n// Which miniapps the local runtime currently has running (stress-test screen).\nexport {miniappRunningRegistry} from \"./services/MiniappRunningRegistry\"\n// Dev-server connection bridge for live-reloading local miniapps.\nexport {default as devServerBridge} from \"./services/DevServerBridge\"\n"]}

package/build/engine.d.ts

@@ -0,0 +1,261 @@
+/**
+ * `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 } from "./runtime/bootstrap";
+export declare const engine: {
+    /** Front door — hand engine auth + config, then start/stop the runtime. */
+    configure: typeof configure;
+    /** Start the runtime: mark started + construct/connect the cloud client + begin
+     * syncing device settings to the glasses. */
+    start(): Promise<void>;
+    /** 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. */
+    stop(): Promise<void>;
+    glasses: {
+        connectDefault: () => Promise<void>;
+        disconnect: () => Promise<void>;
+        forget: () => Promise<void>;
+        connect: (device: import("@mentra/bluetooth-sdk").Device, options?: import("@mentra/bluetooth-sdk").ConnectOptions | undefined) => Promise<void>;
+        connectSimulated: () => Promise<void>;
+        setDefault: (device: import("@mentra/bluetooth-sdk").Device | null) => Promise<void>;
+        reconnect: () => Promise<boolean>;
+        isFirstPairing: () => boolean;
+        hasDefaultDevice: () => Promise<boolean>;
+        status: () => import("./facades/glasses").GlassesStatusSnapshot;
+        onStatus: (cb: (status: import("./facades/glasses").GlassesStatusSnapshot) => void) => (() => void);
+        info: () => import("./facades/glasses").GlassesInfoSnapshot;
+        onInfo: (cb: (info: import("./facades/glasses").GlassesInfoSnapshot) => void) => (() => void);
+        capabilities: () => import("./types").Capabilities;
+        requestVersionInfo: () => Promise<import("@mentra/bluetooth-sdk").VersionInfoResult>;
+        onButtonPress: (cb: (event: import("@mentra/bluetooth-sdk").ButtonPressEvent) => void) => (() => void);
+        onTouchGesture: (cb: (event: import("@mentra/bluetooth-sdk").TouchEvent) => void) => (() => void);
+        controller: {
+            connectDefault: () => Promise<void>;
+            disconnect: () => Promise<void>;
+            forget: () => Promise<void>;
+            status: () => import("./facades/glasses").ControllerStatusSnapshot;
+            onStatus: (cb: (status: import("./facades/glasses").ControllerStatusSnapshot) => void) => (() => void);
+        };
+        audio: {
+            getMediaVolume: () => Promise<import("@mentra/bluetooth-sdk").GlassesMediaVolumeGetResult>;
+            setMediaVolume: (level: number) => Promise<import("@mentra/bluetooth-sdk").GlassesMediaVolumeSetResult>;
+            setOwnAppPlaying: (playing: boolean) => Promise<void>;
+        };
+        wifi: {
+            scan(): Promise<import("@mentra/bluetooth-sdk").WifiSearchResult[]>;
+            onScanResult(cb: (networks: import("@mentra/bluetooth-sdk").WifiSearchResult[]) => void): () => void;
+            connect(ssid: string, password: string): Promise<void>;
+            forget(ssid: string): Promise<void>;
+            status(): import("@mentra/bluetooth-sdk").WifiStatus;
+            onStatus(cb: (status: import("@mentra/bluetooth-sdk").WifiStatus, previous: import("@mentra/bluetooth-sdk").WifiStatus) => void): () => void;
+        };
+        settings: {
+            get: <T = unknown>(key: string) => T | undefined;
+            set: <T = unknown>(key: string, value: T) => import("typesafe-ts").AsyncResult<void, Error>;
+            onChanged: <T = unknown>(key: string, cb: (value: T | undefined) => void) => (() => void);
+            descriptor: (key: string) => import("./stores/settings").Setting;
+            available: () => string[];
+        };
+    };
+    speech: {
+        restartTranscriber: () => Promise<void>;
+        stt: {
+            currentLanguage: () => string;
+            languages: () => import("./internal").SttLanguageConfig[];
+            languageInfo: () => Promise<import("./internal").SttLanguageInfo[]>;
+            download: (code?: string | undefined, onProgress?: ((progress: import("./internal").SttDownloadProgress) => void) | undefined, onExtractionProgress?: ((progress: import("./internal").SttExtractionProgress) => void) | undefined) => Promise<void>;
+            activate: (code: string) => void;
+            cancelDownload: () => Promise<void>;
+            deleteModel: (code?: string | undefined) => Promise<void>;
+            status: () => import("./internal").OfflineModelDownloadStatus | null;
+            onStatusChanged: (listener: (status: import("./internal").OfflineModelDownloadStatus | null) => void) => () => void;
+        };
+        tts: {
+            currentLanguage: () => string;
+            languages: () => import("./services/TTSModelManager").TTSLanguageConfig[];
+            languageInfo: () => Promise<import("./services/TTSModelManager").TTSLanguageInfo[]>;
+            download: (code?: string | undefined, onProgress?: ((progress: import("./services/TTSModelManager").TTSDownloadProgress) => void) | undefined, onExtractionProgress?: ((progress: import("./services/TTSModelManager").TTSExtractionProgress) => void) | undefined) => Promise<void>;
+            activate: (code: string) => void;
+            cancelDownload: () => Promise<void>;
+            deleteModel: (_code?: string | undefined) => Promise<void>;
+        };
+    };
+    /** Cloud (cloud-v2) live-session status + account ops — engine owns the client. */
+    session: {
+        status: () => import(".").CloudClientStatusSnapshot;
+        onStatus: (cb: (status: import(".").CloudClientStatusSnapshot) => void) => (() => void);
+        isConnected: () => boolean;
+        legacyWebsocketStatus: () => import(".").WebSocketStatus;
+        onLegacyWebsocketStatus: (cb: (status: import(".").WebSocketStatus) => void) => (() => void);
+    };
+    /** Typed keyed user settings over the engine-owned settings store. */
+    settings: {
+        get: <T = unknown>(key: string) => T | undefined;
+        set: <T = unknown>(key: string, value: T, syncToServer?: boolean) => import("typesafe-ts").AsyncResult<void, Error>;
+        onChanged: <T = unknown>(key: string, cb: (value: T | undefined) => void) => (() => void);
+        descriptor: (key: string) => import("./stores/settings").Setting;
+        keys: () => string[];
+        resetAllLocal: () => void;
+        loadAll: () => import("typesafe-ts").AsyncResult<void, Error>;
+        getAll: () => Record<string, unknown>;
+        setManyLocal: (values: Record<string, unknown>) => import("typesafe-ts").AsyncResult<void, Error>;
+    };
+    /** Developer/debug surface (backend+cloud URL overrides, reconnect, min version). */
+    dev: {
+        cloudUrls: () => {
+            core?: string;
+            runtime?: string;
+        };
+        setCloudUrls: (urls: {
+            core?: string;
+            runtime?: string;
+        }) => void;
+        reconnectCloud: () => void;
+        getMemoryMB: () => number;
+        bluetoothStatus: () => Record<string, unknown>;
+        loadDevMiniapp: (url: string, name?: string) => Promise<{
+            ok: true;
+            packageName: string;
+            name: string;
+        } | {
+            ok: false;
+            error: string;
+        }>;
+        runtimeStatus: () => import("./facades/dev").DevRuntimeStatusSnapshot;
+        onRuntimeStatus: (cb: (status: import("./facades/dev").DevRuntimeStatusSnapshot) => void) => (() => void);
+    };
+    /** Bug-report, automatic runtime report, and feedback submission. */
+    reports: {
+        submit(input: import(".").EngineSubmitReportInput): Promise<import(".").ReportSubmitResult>;
+    };
+    /** Firmware OTA read/observe surface (updateAvailable/status + on* subscriptions). */
+    ota: {
+        install: (otaVersionUrl?: string | null | undefined) => Promise<import("@mentra/bluetooth-sdk").OtaStartAckEvent>;
+        ping: () => Promise<void>;
+        checkForUpdates: (options?: import(".").OtaCheckCurrentGlassesOptions) => Promise<import(".").OtaCheckCurrentGlassesResult>;
+        clearUpdateAvailable: () => void;
+        clearProgress: () => void;
+        replacePendingUpdateSequence: (updates: import("@mentra/bluetooth-sdk/internal").OtaUpdateInfo["updates"]) => import("@mentra/bluetooth-sdk/internal").OtaUpdateInfo | null;
+        clearBuildNumberForNextCheck: () => void;
+        markMtkUpdatedThisSession: (updated: boolean) => void;
+        installSession: {
+            attach: () => void;
+            detach: () => void;
+            retry: () => void;
+            finish: () => void;
+            discard: () => void;
+            snapshot: () => import(".").OtaInstallSnapshot;
+            onSnapshot: (cb: (snapshot: import(".").OtaInstallSnapshot) => void) => (() => void);
+        };
+        updateAvailable: () => import("@mentra/bluetooth-sdk/internal").OtaUpdateInfo | null;
+        status: () => import("@mentra/bluetooth-sdk").OtaStatus | null;
+        snapshot: () => import(".").OtaSnapshot;
+        onUpdateAvailable: (cb: (info: import("@mentra/bluetooth-sdk/internal").OtaUpdateInfo | null) => void) => (() => void);
+        onStatus: (cb: (status: import("@mentra/bluetooth-sdk").OtaStatus | null) => void) => (() => void);
+        onSnapshot: (cb: (snapshot: import(".").OtaSnapshot) => void) => (() => void);
+    };
+    /** Gallery sync: status/onStatus · onNotice (host renders) · sync/cancel. */
+    gallery: {
+        status: () => import("./facades/gallery").GallerySyncStatus;
+        onStatus: (cb: (status: import("./facades/gallery").GallerySyncStatus) => void) => (() => void);
+        onNotice: (cb: (notice: import(".").GalleryNotice) => void) => (() => void);
+        sync: () => Promise<void>;
+        cancel: () => Promise<void>;
+        refreshStatus: () => Promise<void>;
+        removeFilesFromQueue: (fileNames: string[]) => void;
+        clearQueue: () => void;
+        clearGlassesGalleryStatus: () => void;
+    };
+    /** Miniapp lifecycle (the WebView bridge primitives are exported separately). */
+    miniapps: {
+        list: () => import("./types").ClientApp[];
+        onChanged: (cb: (apps: import("./types").ClientApp[]) => void) => (() => void);
+        refresh: () => Promise<void>;
+        start: (app: import("./types").ClientApp, opts?: import(".").StartOptions | undefined) => Promise<boolean>;
+        stop: (packageName: string) => Promise<void>;
+        setForeground: (packageName: string) => Promise<void>;
+        clearForeground: () => void;
+        stopAll: () => import("typesafe-ts").AsyncResult<void, Error>;
+        install: (url: string, opts?: {
+            versionOverride?: string;
+        } | undefined) => import("typesafe-ts").AsyncResult<void, Error>;
+        uninstall: (packageName: string, version?: string | undefined) => import("typesafe-ts").AsyncResult<void, Error>;
+        saveScreenshot: (packageName: string, screenshot: string) => Promise<void>;
+        setHiddenStatus: (packageName: string, status: boolean) => void;
+    };
+    /** First-time glasses discovery + pairing. */
+    pairing: {
+        readiness: () => import("./facades/pairing").PairingReadinessSnapshot;
+        onReadiness: (cb: (readiness: import("./facades/pairing").PairingReadinessSnapshot) => void) => (() => void);
+        identity: () => import(".").IdentitySnapshot;
+        onIdentity: (cb: (identity: import(".").IdentitySnapshot) => void) => (() => void);
+        markPendingSelection: (model: string) => import("typesafe-ts").AsyncResult<void, Error>;
+        scan: (model: import("@mentra/bluetooth-sdk").DeviceModel) => Promise<void>;
+        scanning: () => boolean;
+        onScanning: (cb: (scanning: boolean) => void) => (() => void);
+        scanningController: () => boolean;
+        onScanningController: (cb: (scanning: boolean) => void) => (() => void);
+        otherBtConnected: () => boolean;
+        onOtherBtConnected: (cb: (connected: boolean) => void) => (() => void);
+        searchResults: () => {
+            id: string;
+            model: import("@mentra/bluetooth-sdk").DeviceModel;
+            name: string;
+            address?: string;
+            rssi?: number;
+        }[];
+        onFound: (cb: (results: ReturnType<() => import("./stores/core").CoreState>["searchResults"]) => void) => (() => void);
+        pair: (device: import("@mentra/bluetooth-sdk").Device, options?: import("@mentra/bluetooth-sdk").ConnectOptions) => Promise<void>;
+        setDefault: (device: import("@mentra/bluetooth-sdk").Device | null) => Promise<void>;
+        setBluetoothClassicTarget: (device: import("@mentra/bluetooth-sdk").Device) => Promise<void>;
+        abandonAttempt: () => Promise<void>;
+        onPairFailure: (cb: (event: import("@mentra/bluetooth-sdk").PairFailureEvent) => void) => (() => void);
+        onGlassesNotReady: (cb: (event: import("@mentra/bluetooth-sdk").GlassesNotReadyEvent) => void) => (() => void);
+        waitForReady: (options?: import("./facades/pairing").PairingReadyWaitOptions) => Promise<boolean>;
+        waitForBluetoothClassic: (options?: Pick<import("./facades/pairing").PairingReadyWaitOptions, "timeoutMs" | "signal">) => Promise<boolean>;
+    };
+    /** Phone→glasses notification forwarding (Android). */
+    phoneNotifications: {
+        enabled: () => boolean;
+        setEnabled: (enabled: boolean) => import("typesafe-ts").AsyncResult<void, Error> | undefined;
+        installedApps: () => Promise<Array<{
+            packageName: string;
+            appName: string;
+            icon: string | null;
+        }>>;
+        blocklist: () => string[];
+        setBlocklist: (packageNames: string[]) => import("typesafe-ts").AsyncResult<void, Error>;
+        hasListenerPermission: () => Promise<boolean>;
+        requestListenerPermission: () => Promise<boolean> | undefined;
+    };
+    /** OS permissions (check/request/openSettings + per-miniapp requirements). */
+    permissions: {
+        check(feature: string): Promise<boolean>;
+        request(feature: string): Promise<boolean>;
+        openSettings: () => Promise<void>;
+        requirementsForMiniapp(packageName: string): Promise<import("./types").AppletPermission[]>;
+    };
+    /** Inbound alerts engine→host (crashloop, version-incompatible, connection loss). */
+    notifications: {
+        onNotification: (cb: (notification: import(".").IslandNotification) => void) => (() => void);
+    };
+    display: {
+        mirror: {
+            current(): import(".").DisplayMirrorEvent;
+            onMirror(cb: (event: import(".").DisplayMirrorEvent) => void): () => void;
+            view(): string;
+            setView(view: "main" | "dashboard"): void;
+        };
+        text: (text: string, x?: number | undefined, y?: number | undefined, size?: number | undefined) => Promise<void>;
+        clear: () => Promise<void>;
+    };
+};
+//# sourceMappingURL=engine.d.ts.map

package/build/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAC,SAAS,EAAiD,MAAM,qBAAqB,CAAA;AAkC7F,eAAO,MAAM,MAAM;IACjB,2EAA2E;;IAE3E;iDAC6C;;IAyE7C;;yCAEqC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IA0BrC,mFAAmF;;;;;;;;IAEnF,sEAAsE;;;;;;;;;;;;IAEtE,qFAAqF;;;gBAxFtE,CAAC;mBACd,CAAH;;;gBAIe,CAAC;mBAAiB,CAAC;;;;;;;;;;;;;;;;IAqFjC,qEAAqE;;;;IAErE,sFAAsF;;;;;;;;;;;;;;;;;;;;;;;;;;IAEtF,6EAA6E;;;;;;;;;;;;IAE7E,iFAAiF;;;;;;;;;;;;;;;;;IAEjF,8CAA8C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAE9C,uDAAuD;;;;;;;;;;;;;;IAEvD,8EAA8E;;;;;;;IAE9E,qFAAqF;;;;;;;;;;;;;;CAGtF,CAAA"}

package/build/engine.js

@@ -0,0 +1,170 @@
+/**
+ * `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, step) => {
+            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,
+};
+//# sourceMappingURL=engine.js.map

package/build/engine.js.map

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

package/build/facades/dev.d.ts

@@ -0,0 +1,58 @@
+declare function projectRuntimeStatus(): {
+    searching: boolean;
+    micRanking: import("@mentra/bluetooth-sdk").MicMode[];
+    currentMic: "" | import("@mentra/bluetooth-sdk").MicMode | null;
+    systemMicUnavailable: boolean;
+    glassesConnected: boolean;
+    glassesFullyBooted: boolean;
+    bluetoothClassicConnected: boolean;
+    coreStatus: import("..").WebSocketStatus;
+    cloudClientStatus: import("@mentra/cloud-client").RuntimeStatus;
+    cloudClientAudioTransport: import("@mentra/cloud-client").RuntimeAudioTransport;
+};
+export type DevRuntimeStatusSnapshot = ReturnType<typeof projectRuntimeStatus>;
+export declare const dev: {
+    /** The cloud-v2 core/runtime URL overrides. */
+    cloudUrls: () => {
+        core?: string;
+        runtime?: string;
+    };
+    /** Override the cloud-v2 URLs and reconnect the live client onto them. */
+    setCloudUrls: (urls: {
+        core?: string;
+        runtime?: string;
+    }) => void;
+    /** Tear down + rebuild the live cloud client (the dev "reconnect" button). */
+    reconnectCloud: () => void;
+    /** Current native (BLE-process) memory usage in MB — a dev/diagnostics gauge. */
+    getMemoryMB: () => number;
+    /**
+     * 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>;
+    /**
+     * 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: (url: string, name?: string) => Promise<{
+        ok: true;
+        packageName: string;
+        name: string;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+    /** Current engine runtime status for engine-owned debug surfaces. */
+    runtimeStatus: () => DevRuntimeStatusSnapshot;
+    /** Subscribe to the projected engine runtime status; returns an unsubscribe. */
+    onRuntimeStatus: (cb: (status: DevRuntimeStatusSnapshot) => void) => (() => void);
+};
+export {};
+//# sourceMappingURL=dev.d.ts.map