@mentra/engine 0.1.0-dev.0 → 3.1.0-beta.100

package/README.md

@@ -21,7 +21,8 @@ npm install @mentra/engine
 
 ## Entry points
 
-The package exposes three entry points (declared in `package.json` `exports`,
+The package exposes its Engine entry points and a supported Bluetooth SDK
+facade (declared in `package.json` `exports`,
 with the `react-native` condition pointing at `src/` so Metro, tsc and jest
 resolve live TypeScript source):
 
@@ -32,15 +33,15 @@ resolve live TypeScript source):
   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.
+- **`@mentra/engine/ota`** (`src/react/index.ts`) — the complete Mentra Live OTA
+  controller plus its stock full-screen renderer. `useMentraLiveOta` owns the
+  check, hotspot or Wi-Fi install, APK/MTK/BES progress, reboot, retry, and final
+  verification behavior. `MentraLiveOtaFlow` renders that same public hook.
+- **`@mentra/engine/bluetooth-sdk`** (`src/bluetooth-sdk/index.ts`) — the
+  complete public Bluetooth SDK surface, re-exported without a wrapper so it
+  has the same singleton identity as `@mentra/bluetooth-sdk`. The supported
+  SDK `react`, `types`, `photo-receiver`, `ota-transport`, and `debug` subpaths are mirrored
+  below this path. The SDK's `internal` entrypoint is deliberately not exposed.
 
 See `cloud-v2/docs/issues/020-glasses-status-boundary/integration-review.md`
 §D for the burn-down plan.
@@ -59,21 +60,75 @@ sockets.
 
 ```ts
 import {engine, decideDevLaunchRoute} from "@mentra/engine"
-import {webviewBridge, buildMiniappGlobalsScript} from "@mentra/engine/internal"
-import {miniappRunningRegistry} from "@mentra/engine/devtools"
+import BluetoothSdk from "@mentra/engine/bluetooth-sdk"
 ```
 
-- `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.
 
+### Mentra Live OTA flow
+
+Bluetooth-only hosts can render the OTA flow without configuring or starting
+the authenticated cloud connection or miniapp runtime:
+
+```tsx
+import {MentraLiveOtaFlow} from "@mentra/engine/ota"
+;<MentraLiveOtaFlow onFinished={() => setShowOta(false)} onOpenWifiSetup={() => setShowWifiSetup(true)} />
+```
+
+The component starts only the glasses-status and OTA projections. A host that
+already called `engine.start()` should pass `initializeRuntime={false}`. Show
+the flow after a Mentra Live connects. Hosts must provide `onOpenWifiSetup`;
+the flow invokes it only for older glasses that cannot provide the OTA hotspot
+transport.
+
+Apps that need different pages can render the same controller directly:
+
+```tsx
+import {useMentraLiveOta} from "@mentra/engine/ota"
+
+const ota = useMentraLiveOta({onFinished, onOpenWifiSetup})
+// Render ota.state.screen and invoke ota.install(), retryInstall(), finish(), etc.
+```
+
+On `up_to_date`, use `ota.state.completedUpdate` to distinguish a completed
+update session from a standalone check. `releaseTransition` is optional release
+metadata and is not a completion marker.
+
+Customize presentation only. Engine must remain responsible for OTA ordering,
+hotspot staging, restart recovery, retries, and verification. The canonical
+stock and custom integration guide is
+[Update Mentra Live](https://docs.mentraglass.com/bluetooth-sdk/software-update).
+
+Released Engine packages contain a literal immutable OTA manifest URL and
+SHA-256 generated by coordinated release CI. Modern-glasses manifest selection
+is developer override, host-app release pin, then Engine release pin. It does
+not derive a URL from the Bluetooth SDK version or fall through to a
+glasses-reported or mutable production URL. An unpinned source build has OTA
+disabled unless an Expo/React Native host explicitly sets
+`EXPO_PUBLIC_ASG_OTA_VERSION_URL`; native source hosts use the Bluetooth SDK's
+debug `setOtaVersionUrl` surface. Pre-39 glasses retain their separate legacy
+path because those clients ignore the URL sent by the phone.
+
 ## 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.
+
+## Testing
+
+Run the suite with `bun run test` (from this directory). It executes
+`scripts/test.sh`, which runs **each test file in its own bun process** — do
+not replace it with a single `bun test src`.
+
+Why: bun's `mock.module` patches one process-wide module registry with live
+ESM bindings, last write wins. Several suites mock the same specifiers
+(`"@mentra/bluetooth-sdk/internal"` alone is mocked by `audioTestMocks.ts`,
+`PhonePhotoCoordinator.test.ts`, and others), so in a shared process one
+file's mock clobbers another's and suites that pass alone fail in the
+combined run. Per-file processes give every suite an isolated registry.
+
+The same rule applies when writing tests: it is fine to `mock.module` any
+specifier your suite needs, but never rely on a mock installed by a
+_different_ test file — each file must set up everything it imports.

package/build/bluetooth-sdk/debug.d.ts

@@ -0,0 +1,2 @@
+export * from "@mentra/bluetooth-sdk/debug";
+//# sourceMappingURL=debug.d.ts.map

package/build/bluetooth-sdk/debug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../../src/bluetooth-sdk/debug.ts"],"names":[],"mappings":"AAAA,cAAc,6BAA6B,CAAA"}

package/build/bluetooth-sdk/debug.js

@@ -0,0 +1,2 @@
+export * from "@mentra/bluetooth-sdk/debug";
+//# sourceMappingURL=debug.js.map

package/build/bluetooth-sdk/debug.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.js","sourceRoot":"","sources":["../../src/bluetooth-sdk/debug.ts"],"names":[],"mappings":"AAAA,cAAc,6BAA6B,CAAA","sourcesContent":["export * from \"@mentra/bluetooth-sdk/debug\"\n"]}

package/build/bluetooth-sdk/index.d.ts

@@ -0,0 +1,3 @@
+export { default } from "@mentra/bluetooth-sdk";
+export * from "@mentra/bluetooth-sdk";
+//# sourceMappingURL=index.d.ts.map

package/build/bluetooth-sdk/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bluetooth-sdk/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,OAAO,EAAC,MAAM,uBAAuB,CAAA;AAC7C,cAAc,uBAAuB,CAAA"}

package/build/bluetooth-sdk/index.js

@@ -0,0 +1,3 @@
+export { default } from "@mentra/bluetooth-sdk";
+export * from "@mentra/bluetooth-sdk";
+//# sourceMappingURL=index.js.map

package/build/bluetooth-sdk/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/bluetooth-sdk/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,OAAO,EAAC,MAAM,uBAAuB,CAAA;AAC7C,cAAc,uBAAuB,CAAA","sourcesContent":["export {default} from \"@mentra/bluetooth-sdk\"\nexport * from \"@mentra/bluetooth-sdk\"\n"]}

package/build/bluetooth-sdk/ota-transport.d.ts

@@ -0,0 +1,2 @@
+export * from "@mentra/bluetooth-sdk/ota-transport";
+//# sourceMappingURL=ota-transport.d.ts.map

package/build/bluetooth-sdk/ota-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ota-transport.d.ts","sourceRoot":"","sources":["../../src/bluetooth-sdk/ota-transport.ts"],"names":[],"mappings":"AAAA,cAAc,qCAAqC,CAAA"}

package/build/bluetooth-sdk/ota-transport.js

@@ -0,0 +1,2 @@
+export * from "@mentra/bluetooth-sdk/ota-transport";
+//# sourceMappingURL=ota-transport.js.map

package/build/bluetooth-sdk/ota-transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ota-transport.js","sourceRoot":"","sources":["../../src/bluetooth-sdk/ota-transport.ts"],"names":[],"mappings":"AAAA,cAAc,qCAAqC,CAAA","sourcesContent":["export * from \"@mentra/bluetooth-sdk/ota-transport\"\n"]}

package/build/bluetooth-sdk/photo-receiver.d.ts

@@ -0,0 +1,3 @@
+export { default } from "@mentra/bluetooth-sdk/photo-receiver";
+export * from "@mentra/bluetooth-sdk/photo-receiver";
+//# sourceMappingURL=photo-receiver.d.ts.map

package/build/bluetooth-sdk/photo-receiver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"photo-receiver.d.ts","sourceRoot":"","sources":["../../src/bluetooth-sdk/photo-receiver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,OAAO,EAAC,MAAM,sCAAsC,CAAA;AAC5D,cAAc,sCAAsC,CAAA"}

package/build/bluetooth-sdk/photo-receiver.js

@@ -0,0 +1,3 @@
+export { default } from "@mentra/bluetooth-sdk/photo-receiver";
+export * from "@mentra/bluetooth-sdk/photo-receiver";
+//# sourceMappingURL=photo-receiver.js.map

package/build/bluetooth-sdk/photo-receiver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"photo-receiver.js","sourceRoot":"","sources":["../../src/bluetooth-sdk/photo-receiver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,OAAO,EAAC,MAAM,sCAAsC,CAAA;AAC5D,cAAc,sCAAsC,CAAA","sourcesContent":["export {default} from \"@mentra/bluetooth-sdk/photo-receiver\"\nexport * from \"@mentra/bluetooth-sdk/photo-receiver\"\n"]}

package/build/bluetooth-sdk/react.d.ts

@@ -0,0 +1,2 @@
+export * from "@mentra/bluetooth-sdk/react";
+//# sourceMappingURL=react.d.ts.map

package/build/bluetooth-sdk/react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../../src/bluetooth-sdk/react.ts"],"names":[],"mappings":"AAAA,cAAc,6BAA6B,CAAA"}

package/build/bluetooth-sdk/react.js

@@ -0,0 +1,2 @@
+export * from "@mentra/bluetooth-sdk/react";
+//# sourceMappingURL=react.js.map

package/build/bluetooth-sdk/react.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.js","sourceRoot":"","sources":["../../src/bluetooth-sdk/react.ts"],"names":[],"mappings":"AAAA,cAAc,6BAA6B,CAAA","sourcesContent":["export * from \"@mentra/bluetooth-sdk/react\"\n"]}

package/build/bluetooth-sdk/types.d.ts

@@ -0,0 +1,2 @@
+export * from "@mentra/bluetooth-sdk/types";
+//# sourceMappingURL=types.d.ts.map

package/build/bluetooth-sdk/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/bluetooth-sdk/types.ts"],"names":[],"mappings":"AAAA,cAAc,6BAA6B,CAAA"}

package/build/bluetooth-sdk/types.js

@@ -0,0 +1,2 @@
+export * from "@mentra/bluetooth-sdk/types";
+//# sourceMappingURL=types.js.map

package/build/bluetooth-sdk/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/bluetooth-sdk/types.ts"],"names":[],"mappings":"AAAA,cAAc,6BAA6B,CAAA","sourcesContent":["export * from \"@mentra/bluetooth-sdk/types\"\n"]}

package/build/engine.d.ts

@@ -5,13 +5,15 @@
  * 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.*`.
+ * remain in a private MentraOS host package; they shrink as screens move onto
+ * `engine.*`.
  */
-import { configure } from "./runtime/bootstrap";
+import { configure, updateUiSeams } from "./runtime/bootstrap";
 export declare const engine: {
     /** Front door — hand engine auth + config, then start/stop the runtime. */
     configure: typeof configure;
+    /** Merge host-UI seams on a running runtime (scan overlay, wifi setup, …). */
+    updateUiSeams: typeof updateUiSeams;
     /** Start the runtime: mark started + construct/connect the cloud client + begin
      * syncing device settings to the glasses. */
     start(): Promise<void>;
@@ -23,7 +25,7 @@ export declare const engine: {
         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>;
+        connect: (device: import("@mentra/bluetooth-sdk").Device, options?: import("@mentra/bluetooth-sdk").ConnectOptions) => Promise<void>;
         connectSimulated: () => Promise<void>;
         setDefault: (device: import("@mentra/bluetooth-sdk").Device | null) => Promise<void>;
         reconnect: () => Promise<boolean>;
@@ -69,14 +71,14 @@ export declare const engine: {
         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>;
+            languages: () => import("./services/STTModelManager").LanguageConfig[];
+            languageInfo: () => Promise<import("./services/STTModelManager").LanguageInfo[]>;
+            download: (code?: string | undefined, onProgress?: ((progress: import("./services/STTModelManager").DownloadProgress) => void) | undefined, onExtractionProgress?: ((progress: import("./services/STTModelManager").ExtractionProgress) => 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;
+            status: () => import("./services/OfflineSpeechModelService").DownloadStatus | null;
+            onStatusChanged: (listener: (status: import("./services/OfflineSpeechModelService").DownloadStatus | null) => void) => (() => void);
         };
         tts: {
             currentLanguage: () => string;
@@ -138,27 +140,30 @@ export declare const engine: {
     };
     /** Firmware OTA read/observe surface (updateAvailable/status + on* subscriptions). */
     ota: {
-        install: (otaVersionUrl?: string | null | undefined) => Promise<import("@mentra/bluetooth-sdk").OtaStartAckEvent>;
+        initialize: () => Promise<void>;
+        install: (otaVersionUrl?: string | null) => Promise<import("@mentra/bluetooth-sdk").OtaStartAckEvent>;
         ping: () => Promise<void>;
         checkForUpdates: (options?: import(".").OtaCheckCurrentGlassesOptions) => Promise<import(".").OtaCheckCurrentGlassesResult>;
+        getReleaseChangelogs: (fromVersion?: string | null, toVersion?: string | null) => import("@mentra/bluetooth-sdk").ReleaseChangelog[];
         clearUpdateAvailable: () => void;
         clearProgress: () => void;
-        replacePendingUpdateSequence: (updates: import("@mentra/bluetooth-sdk/internal").OtaUpdateInfo["updates"]) => import("@mentra/bluetooth-sdk/internal").OtaUpdateInfo | null;
+        replacePendingUpdateSequence: (updates: import("@mentra/bluetooth-sdk").OtaUpdateInfo["updates"]) => import("@mentra/bluetooth-sdk").OtaUpdateInfo | null;
         clearBuildNumberForNextCheck: () => void;
         markMtkUpdatedThisSession: (updated: boolean) => void;
         installSession: {
+            prepare: (result: import(".").OtaCheckCurrentGlassesResult) => "wifi" | "hotspot";
             attach: () => void;
             detach: () => void;
             retry: () => void;
-            finish: () => void;
-            discard: () => void;
+            finish: () => Promise<void>;
+            discard: () => Promise<void>;
             snapshot: () => import(".").OtaInstallSnapshot;
             onSnapshot: (cb: (snapshot: import(".").OtaInstallSnapshot) => void) => (() => void);
         };
-        updateAvailable: () => import("@mentra/bluetooth-sdk/internal").OtaUpdateInfo | null;
+        updateAvailable: () => import("@mentra/bluetooth-sdk").OtaUpdateInfo | null;
         status: () => import("@mentra/bluetooth-sdk").OtaStatus | null;
         snapshot: () => import(".").OtaSnapshot;
-        onUpdateAvailable: (cb: (info: import("@mentra/bluetooth-sdk/internal").OtaUpdateInfo | null) => void) => (() => void);
+        onUpdateAvailable: (cb: (info: import("@mentra/bluetooth-sdk").OtaUpdateInfo | null) => void) => (() => void);
         onStatus: (cb: (status: import("@mentra/bluetooth-sdk").OtaStatus | null) => void) => (() => void);
         onSnapshot: (cb: (snapshot: import(".").OtaSnapshot) => void) => (() => void);
     };
@@ -178,6 +183,8 @@ export declare const engine: {
     miniapps: {
         list: () => import("./types").ClientApp[];
         onChanged: (cb: (apps: import("./types").ClientApp[]) => void) => (() => void);
+        buttonPressSubscribers: () => string[];
+        onButtonPressSubscribersChanged: (cb: (packageNames: string[]) => void) => (() => void);
         refresh: () => Promise<void>;
         start: (app: import("./types").ClientApp, opts?: import(".").StartOptions | undefined) => Promise<boolean>;
         stop: (packageName: string) => Promise<void>;
@@ -195,6 +202,8 @@ export declare const engine: {
     pairing: {
         readiness: () => import("./facades/pairing").PairingReadinessSnapshot;
         onReadiness: (cb: (readiness: import("./facades/pairing").PairingReadinessSnapshot) => void) => (() => void);
+        targetReady: (options: Pick<import("./facades/pairing").PairingReadyWaitOptions, "deviceModel" | "deviceName">) => boolean;
+        onTargetReady: (options: Pick<import("./facades/pairing").PairingReadyWaitOptions, "deviceModel" | "deviceName">, cb: (ready: boolean) => void) => (() => void);
         identity: () => import(".").IdentitySnapshot;
         onIdentity: (cb: (identity: import(".").IdentitySnapshot) => void) => (() => void);
         markPendingSelection: (model: string) => import("typesafe-ts").AsyncResult<void, Error>;
@@ -210,9 +219,13 @@ export declare const engine: {
             model: import("@mentra/bluetooth-sdk").DeviceModel;
             name: string;
             address?: string;
+            projectName?: string;
             rssi?: number;
+            pairingMode?: boolean;
+            pairingCode?: string;
+            securePairingCapable?: boolean;
         }[];
-        onFound: (cb: (results: ReturnType<() => import("./stores/core").CoreState>["searchResults"]) => void) => (() => void);
+        onFound: (cb: (results: import("@mentra/bluetooth-sdk").Device[]) => 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>;
@@ -224,8 +237,6 @@ export declare const engine: {
     };
     /** 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;

package/build/engine.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAC,SAAS,EAAkD,aAAa,EAAC,MAAM,qBAAqB,CAAA;AAmC5G,eAAO,MAAM,MAAM;IACjB,2EAA2E;;IAE3E,8EAA8E;;IAE9E;iDAC6C;;IA0E7C;;yCAEqC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IA2BrC,mFAAmF;;;;;;;;IAEnF,sEAAsE;;;;;;;;;;;;IAEtE,qFAAqF;;;gBA7FlC,CAAC;mBAAiB,CAAC;;;gBAKhD,CAAC;mBAAiB,CAAC;;;;;;;;;;;;;;;;IA0FzC,qEAAqE;;;;IAErE,sFAAsF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAEtF,6EAA6E;;;;;;;;;;;;IAE7E,iFAAiF;;;;;;;;;;;;;;;;;;;IAEjF,8CAA8C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAE9C,uDAAuD;;;;;;;;;;;;IAEvD,8EAA8E;;;;;;;IAE9E,qFAAqF;;;;;;;;;;;;;;CAGtF,CAAA"}

package/build/engine.js

@@ -5,16 +5,17 @@
  * 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.*`.
+ * remain in a private MentraOS host package; they shrink as screens move onto
+ * `engine.*`.
  */
-import { configure, start as bootstrapStart, stop as bootstrapStop } from "./runtime/bootstrap";
+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 { startSupportProfileSync, stopSupportProfileSync } from "./services/SupportProfileSync";
 import { startDeviceEventRouter, stopDeviceEventRouter } from "./services/DeviceEventRouter";
 import { startPhoneNotificationsSync, stopPhoneNotificationsSync } from "./services/PhoneNotificationsSync";
 import { startCaptionsTesterReportService, stopCaptionsTesterReportService } from "./services/CaptionsTesterReportService";
@@ -41,6 +42,8 @@ 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() {
@@ -55,7 +58,7 @@ export const engine = {
         // 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();
+        startGlassesStatusProjection((changed) => localMiniappRuntime.forwardEvent("glasses_connection_state", changed));
         // 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
@@ -91,6 +94,7 @@ export const engine = {
         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 Mentra app).
         startGlassesSettingsSync();
@@ -131,6 +135,7 @@ export const engine = {
         await safely("device event router", stopDeviceEventRouter);
         await safely("ota service", stopOtaService);
         await safely("audio cloud uplink", stopAudioCloudUplink);
+        await safely("support profile sync", stopSupportProfileSync);
         await safely("phone notifications sync", stopPhoneNotificationsSync);
         await safely("captions tester report service", stopCaptionsTesterReportService);
         await safely("mentrajs crashloop report service", stopMentraJSCrashloopReportService);

package/build/engine.js.map

@@ -1 +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"]}
+{"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 * remain in a private MentraOS host package; they shrink as screens move onto\n * `engine.*`.\n */\nimport {configure, start as bootstrapStart, stop as bootstrapStop, updateUiSeams} 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 {startSupportProfileSync, stopSupportProfileSync} from \"./services/SupportProfileSync\"\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  /** Merge host-UI seams on a running runtime (scan overlay, wifi setup, …). */\n  updateUiSeams,\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((changed) => localMiniappRuntime.forwardEvent(\"glasses_connection_state\", changed))\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    startSupportProfileSync()\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(\"support profile sync\", stopSupportProfileSync)\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

@@ -34,8 +34,9 @@ export declare const dev: {
     /**
      * 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 into the single dev slot so it appears in `engine.miniapps`
-     * and can be started. This is the OEM-host equivalent of the first-party
+     * 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.

package/build/facades/dev.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../src/facades/dev.ts"],"names":[],"mappings":"AA+DA,iBAAS,oBAAoB;;;;;;;;;;;EAkB5B;AAED,MAAM,MAAM,wBAAwB,GAAG,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAA;AAE9E,eAAO,MAAM,GAAG;IACd,+CAA+C;qBAChC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAC;IAIhD,0EAA0E;yBACrD;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAC;IAkBtD,8EAA8E;0BAC1D,IAAI;IAExB,iFAAiF;uBAChE,MAAM;IACvB;;;OAGG;2BACkB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAK5C;;;;;;;;OAQG;0BAEI,MAAM,SACJ,MAAM,KACZ,OAAO,CAAC;QAAC,EAAE,EAAE,IAAI,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,GAAG;QAAC,EAAE,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAC,CAAC;IAqCtF,qEAAqE;yBAClD,wBAAwB;IAE3C,gFAAgF;0BAC1D,CAAC,MAAM,EAAE,wBAAwB,KAAK,IAAI,KAAG,CAAC,MAAM,IAAI,CAAC;CAmBhF,CAAA"}
+{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../src/facades/dev.ts"],"names":[],"mappings":"AA+DA,iBAAS,oBAAoB;;;;;;;;;;;EAkB5B;AAED,MAAM,MAAM,wBAAwB,GAAG,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAA;AAE9E,eAAO,MAAM,GAAG;IACd,+CAA+C;qBAChC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAC;IAIhD,0EAA0E;yBACrD;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAC;IAkBtD,8EAA8E;0BAC1D,IAAI;IAExB,iFAAiF;uBAChE,MAAM;IACvB;;;OAGG;2BACkB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAK5C;;;;;;;;;OASG;0BAEI,MAAM,SACJ,MAAM,KACZ,OAAO,CAAC;QAAC,EAAE,EAAE,IAAI,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,GAAG;QAAC,EAAE,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAC,CAAC;IAyCtF,qEAAqE;yBAClD,wBAAwB;IAE3C,gFAAgF;0BAC1D,CAAC,MAAM,EAAE,wBAAwB,KAAK,IAAI,KAAG,CAAC,MAAM,IAAI,CAAC;CAmBhF,CAAA"}

package/build/facades/dev.js

@@ -116,8 +116,9 @@ export const dev = {
     /**
      * 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 into the single dev slot so it appears in `engine.miniapps`
-     * and can be started. This is the OEM-host equivalent of the first-party
+     * 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.
@@ -131,26 +132,31 @@ export const dev = {
             return { ok: false, error: "dev server unreachable, or no miniapp.json served there" };
         }
         const manifest = result.manifest;
+        const appName = name ?? manifest.name ?? "Dev Miniapp";
+        const packageName = manifest.packageName ?? DEV_APP_PACKAGE_NAME;
+        // Persist the host that answered — not the stale input IP — so home-tile
+        // relaunches skip a dead LAN address after mDNS/Metro failover.
+        const resolvedUrl = result.resolvedUrl || devUrl;
         // 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;
         try {
-            const parsed = Number(new URL(devUrl).port);
+            const parsed = Number(new URL(resolvedUrl).port);
             devPort = Number.isFinite(parsed) && parsed > 0 ? parsed + 1 : undefined;
         }
         catch {
             devPort = undefined;
         }
-        const appName = name ?? manifest.name ?? "Dev Miniapp";
-        registerDevApp({
-            // The REAL manifest package: registerDevApp preserves it as
-            // sourcePackageName (miniapp auth + dev-slot cleanup key off it) before
-            // forcing packageName to the single dev slot.
-            packageName: manifest.packageName ?? 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,
+            iconUrl: manifest.icon ? new URL(manifest.icon, `${resolvedUrl}/`).toString() : `${resolvedUrl}/icon.png`,
+            // Persist the host that answered — not the stale input IP.
+            devUrl: resolvedUrl,
             devPort,
             type: manifest.type,
             permissions: manifest.permissions,
@@ -158,7 +164,7 @@ export const dev = {
             actions: manifest.actions,
         });
         await useAppStatusStore.getState().refresh();
-        return { ok: true, packageName: DEV_APP_PACKAGE_NAME, name: appName };
+        return { ok: true, packageName, name: appName };
     },
     /** Current engine runtime status for engine-owned debug surfaces. */
     runtimeStatus: () => projectRuntimeStatus(),