@mentra/engine 0.1.0-beta.0 → 0.1.0-dev.1

package/build/services/HotspotOtaTransport.js

@@ -0,0 +1,146 @@
+import BluetoothSdk, { isEnabledHotspotStatus, MentraOtaServer } from "@mentra/bluetooth-sdk/internal";
+// One coordinator selects the native Android or iOS staging implementation at runtime.
+// eslint-disable-next-line react-native/split-platform-components
+import { PermissionsAndroid, Platform } from "react-native";
+import { cleanupArtifacts, OtaArtifactError, planArtifacts, prepareArtifacts, rewriteManifestForLocalServer, } from "./OtaArtifactDownloader";
+import { disableHotspotWithRetry } from "./HotspotShutdown";
+import { localNetworkTransport } from "./asg/localNetworkTransport";
+export class HotspotOtaTransportError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "HotspotOtaTransportError";
+    }
+}
+/** Owns the single phone-side endpoint and network lease for one hotspot OTA attempt. */
+class HotspotOtaTransport {
+    active = false;
+    prepared = [];
+    hotspotRequested = false;
+    localNetworkConnected = false;
+    serverStarted = false;
+    teardownPromise = null;
+    async prepare(checkResult, onProgress) {
+        if (this.teardownPromise)
+            await this.teardownPromise;
+        if (this.active) {
+            throw new Error("A hotspot OTA transport is already active");
+        }
+        if (!checkResult.manifestBody) {
+            throw new Error("The selected OTA check has no manifest body");
+        }
+        let phase = "downloading";
+        try {
+            await this.ensureAndroidWifiPermission();
+            onProgress?.({ phase: "downloading" });
+            this.prepared = await prepareArtifacts(planArtifacts(checkResult), (artifact) => onProgress?.({ phase: "downloading", artifact }), Platform.OS === "ios" ? this.downloadIosArtifact : undefined);
+            phase = "starting_hotspot";
+            onProgress?.({ phase: "starting_hotspot" });
+            this.hotspotRequested = true;
+            const hotspot = await BluetoothSdk.setHotspotState(true);
+            if (!isEnabledHotspotStatus(hotspot)) {
+                throw new HotspotOtaTransportError("hotspot_start_failed", "Mentra Live did not return hotspot credentials");
+            }
+            phase = "joining_hotspot";
+            onProgress?.({ phase: "joining_hotspot" });
+            const scopedAddress = await localNetworkTransport.connect(hotspot.ssid, hotspot.password);
+            this.localNetworkConnected = true;
+            let localAddress = scopedAddress;
+            if (Platform.OS === "ios") {
+                try {
+                    localAddress = await MentraOtaServer.waitForWifiAddress(hotspot.localIp, 15_000);
+                }
+                catch (error) {
+                    throw new HotspotOtaTransportError("hotspot_join_failed", error instanceof Error ? error.message : String(error));
+                }
+            }
+            const artifactPaths = Object.fromEntries(this.prepared.map((artifact) => [artifact.sha256, artifact.filePath]));
+            // Start exactly one native listener to learn its selected port, then atomically replace
+            // the placeholder with the immutable rewritten manifest before ota_start is sent.
+            const server = await MentraOtaServer.startOtaServer("{}", artifactPaths, localAddress);
+            this.serverStarted = true;
+            const manifest = rewriteManifestForLocalServer(checkResult.manifestBody, this.prepared, server.baseUrl);
+            const published = await MentraOtaServer.startOtaServer(manifest, artifactPaths, server.host);
+            if (published.manifestUrl !== server.manifestUrl) {
+                throw new Error("Local OTA server endpoint changed while publishing the manifest");
+            }
+            this.active = true;
+            onProgress?.({ phase: "serving" });
+            return published.manifestUrl;
+        }
+        catch (error) {
+            const joined = this.localNetworkConnected;
+            await this.teardown();
+            if (error instanceof OtaArtifactError || error instanceof HotspotOtaTransportError) {
+                throw error;
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            if (phase === "starting_hotspot") {
+                throw new HotspotOtaTransportError("hotspot_start_failed", message);
+            }
+            if (phase === "joining_hotspot" && !joined) {
+                throw new HotspotOtaTransportError("hotspot_join_failed", message);
+            }
+            throw new HotspotOtaTransportError("hotspot_server_failed", message);
+        }
+    }
+    /** Android 13+ requires the nearby-WiFi runtime grant before WifiNetworkSpecifier is usable. */
+    async ensureAndroidWifiPermission() {
+        if (Platform.OS !== "android")
+            return;
+        const permission = PermissionsAndroid.PERMISSIONS.NEARBY_WIFI_DEVICES;
+        if (await PermissionsAndroid.check(permission))
+            return;
+        const result = await PermissionsAndroid.request(permission);
+        if (result !== PermissionsAndroid.RESULTS.GRANTED) {
+            throw new HotspotOtaTransportError("hotspot_wifi_permission_denied", "Nearby devices permission is required to connect to the glasses hotspot");
+        }
+    }
+    downloadIosArtifact = async (entry, destination, onProgress) => {
+        const subscription = MentraOtaServer.addListener("artifactDownloadProgress", (event) => {
+            if (event.destination === destination)
+                onProgress?.(event.bytesWritten, event.contentLength);
+        });
+        try {
+            return await MentraOtaServer.downloadArtifact(entry.url, destination);
+        }
+        finally {
+            subscription.remove();
+        }
+    };
+    async teardown() {
+        if (this.teardownPromise)
+            return this.teardownPromise;
+        this.teardownPromise = (async () => {
+            if (this.hotspotRequested) {
+                const hotspotStopped = await disableHotspotWithRetry(() => BluetoothSdk.setHotspotState(false), {
+                    // A completed APK step has just replaced ASG. Let the new command path
+                    // settle before asking it to tear down the SystemUI-owned access point.
+                    initialDelayMs: this.serverStarted ? 750 : 0,
+                });
+                if (!hotspotStopped) {
+                    console.warn("[OTA_PROGRESS] glasses hotspot shutdown was not confirmed after bounded retries");
+                }
+            }
+            if (this.serverStarted)
+                await MentraOtaServer.stopOtaServer().catch(() => { });
+            if (this.localNetworkConnected)
+                await localNetworkTransport.disconnect().catch(() => { });
+            await cleanupArtifacts().catch(() => { });
+            this.prepared = [];
+            this.active = false;
+            this.serverStarted = false;
+            this.localNetworkConnected = false;
+            this.hotspotRequested = false;
+        })();
+        try {
+            await this.teardownPromise;
+        }
+        finally {
+            this.teardownPromise = null;
+        }
+    }
+}
+export const hotspotOtaTransport = new HotspotOtaTransport();
+//# sourceMappingURL=HotspotOtaTransport.js.map

package/build/services/HotspotOtaTransport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HotspotOtaTransport.js","sourceRoot":"","sources":["../../src/services/HotspotOtaTransport.ts"],"names":[],"mappings":"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","sourcesContent":["import BluetoothSdk, {isEnabledHotspotStatus, MentraOtaServer} from \"@mentra/bluetooth-sdk/internal\"\n// One coordinator selects the native Android or iOS staging implementation at runtime.\n// eslint-disable-next-line react-native/split-platform-components\nimport {PermissionsAndroid, Platform} from \"react-native\"\nimport type {OtaCheckCurrentGlassesResult} from \"./OtaUpdateCheckService\"\nimport {\n  cleanupArtifacts,\n  OtaArtifactError,\n  planArtifacts,\n  prepareArtifacts,\n  rewriteManifestForLocalServer,\n  type OtaArtifactDownloadProgress,\n  type PreparedOtaArtifact,\n} from \"./OtaArtifactDownloader\"\nimport {disableHotspotWithRetry} from \"./HotspotShutdown\"\nimport {localNetworkTransport} from \"./asg/localNetworkTransport\"\n\nexport type HotspotOtaPhase = \"idle\" | \"downloading\" | \"starting_hotspot\" | \"joining_hotspot\" | \"serving\"\n\nexport type HotspotOtaProgress = {\n  phase: HotspotOtaPhase\n  artifact?: OtaArtifactDownloadProgress\n}\n\nexport type HotspotOtaErrorCode =\n  | \"hotspot_wifi_permission_denied\"\n  | \"hotspot_start_failed\"\n  | \"hotspot_join_failed\"\n  | \"hotspot_server_failed\"\n\nexport class HotspotOtaTransportError extends Error {\n  constructor(\n    public readonly code: HotspotOtaErrorCode,\n    message: string,\n  ) {\n    super(message)\n    this.name = \"HotspotOtaTransportError\"\n  }\n}\n\n/** Owns the single phone-side endpoint and network lease for one hotspot OTA attempt. */\nclass HotspotOtaTransport {\n  private active = false\n  private prepared: PreparedOtaArtifact[] = []\n  private hotspotRequested = false\n  private localNetworkConnected = false\n  private serverStarted = false\n  private teardownPromise: Promise<void> | null = null\n\n  async prepare(\n    checkResult: OtaCheckCurrentGlassesResult,\n    onProgress?: (progress: HotspotOtaProgress) => void,\n  ): Promise<string> {\n    if (this.teardownPromise) await this.teardownPromise\n    if (this.active) {\n      throw new Error(\"A hotspot OTA transport is already active\")\n    }\n    if (!checkResult.manifestBody) {\n      throw new Error(\"The selected OTA check has no manifest body\")\n    }\n\n    let phase: HotspotOtaPhase = \"downloading\"\n    try {\n      await this.ensureAndroidWifiPermission()\n      onProgress?.({phase: \"downloading\"})\n      this.prepared = await prepareArtifacts(\n        planArtifacts(checkResult),\n        (artifact) => onProgress?.({phase: \"downloading\", artifact}),\n        Platform.OS === \"ios\" ? this.downloadIosArtifact : undefined,\n      )\n\n      phase = \"starting_hotspot\"\n      onProgress?.({phase: \"starting_hotspot\"})\n      this.hotspotRequested = true\n      const hotspot = await BluetoothSdk.setHotspotState(true)\n      if (!isEnabledHotspotStatus(hotspot)) {\n        throw new HotspotOtaTransportError(\"hotspot_start_failed\", \"Mentra Live did not return hotspot credentials\")\n      }\n      phase = \"joining_hotspot\"\n      onProgress?.({phase: \"joining_hotspot\"})\n      const scopedAddress = await localNetworkTransport.connect(hotspot.ssid, hotspot.password)\n      this.localNetworkConnected = true\n      let localAddress = scopedAddress\n      if (Platform.OS === \"ios\") {\n        try {\n          localAddress = await MentraOtaServer.waitForWifiAddress(hotspot.localIp, 15_000)\n        } catch (error) {\n          throw new HotspotOtaTransportError(\n            \"hotspot_join_failed\",\n            error instanceof Error ? error.message : String(error),\n          )\n        }\n      }\n      const artifactPaths = Object.fromEntries(this.prepared.map((artifact) => [artifact.sha256, artifact.filePath]))\n      // Start exactly one native listener to learn its selected port, then atomically replace\n      // the placeholder with the immutable rewritten manifest before ota_start is sent.\n      const server = await MentraOtaServer.startOtaServer(\"{}\", artifactPaths, localAddress)\n      this.serverStarted = true\n      const manifest = rewriteManifestForLocalServer(checkResult.manifestBody, this.prepared, server.baseUrl)\n      const published = await MentraOtaServer.startOtaServer(manifest, artifactPaths, server.host)\n      if (published.manifestUrl !== server.manifestUrl) {\n        throw new Error(\"Local OTA server endpoint changed while publishing the manifest\")\n      }\n      this.active = true\n      onProgress?.({phase: \"serving\"})\n      return published.manifestUrl\n    } catch (error) {\n      const joined = this.localNetworkConnected\n      await this.teardown()\n      if (error instanceof OtaArtifactError || error instanceof HotspotOtaTransportError) {\n        throw error\n      }\n      const message = error instanceof Error ? error.message : String(error)\n      if (phase === \"starting_hotspot\") {\n        throw new HotspotOtaTransportError(\"hotspot_start_failed\", message)\n      }\n      if (phase === \"joining_hotspot\" && !joined) {\n        throw new HotspotOtaTransportError(\"hotspot_join_failed\", message)\n      }\n      throw new HotspotOtaTransportError(\"hotspot_server_failed\", message)\n    }\n  }\n\n  /** Android 13+ requires the nearby-WiFi runtime grant before WifiNetworkSpecifier is usable. */\n  private async ensureAndroidWifiPermission(): Promise<void> {\n    if (Platform.OS !== \"android\") return\n\n    const permission = PermissionsAndroid.PERMISSIONS.NEARBY_WIFI_DEVICES\n    if (await PermissionsAndroid.check(permission)) return\n    const result = await PermissionsAndroid.request(permission)\n    if (result !== PermissionsAndroid.RESULTS.GRANTED) {\n      throw new HotspotOtaTransportError(\n        \"hotspot_wifi_permission_denied\",\n        \"Nearby devices permission is required to connect to the glasses hotspot\",\n      )\n    }\n  }\n\n  private downloadIosArtifact = async (\n    entry: {url: string},\n    destination: string,\n    onProgress?: (bytesWritten: number, contentLength: number) => void,\n  ): Promise<{statusCode: number}> => {\n    const subscription = MentraOtaServer.addListener(\"artifactDownloadProgress\", (event) => {\n      if (event.destination === destination) onProgress?.(event.bytesWritten, event.contentLength)\n    })\n    try {\n      return await MentraOtaServer.downloadArtifact(entry.url, destination)\n    } finally {\n      subscription.remove()\n    }\n  }\n\n  async teardown(): Promise<void> {\n    if (this.teardownPromise) return this.teardownPromise\n    this.teardownPromise = (async () => {\n      if (this.hotspotRequested) {\n        const hotspotStopped = await disableHotspotWithRetry(() => BluetoothSdk.setHotspotState(false), {\n          // A completed APK step has just replaced ASG. Let the new command path\n          // settle before asking it to tear down the SystemUI-owned access point.\n          initialDelayMs: this.serverStarted ? 750 : 0,\n        })\n        if (!hotspotStopped) {\n          console.warn(\"[OTA_PROGRESS] glasses hotspot shutdown was not confirmed after bounded retries\")\n        }\n      }\n      if (this.serverStarted) await MentraOtaServer.stopOtaServer().catch(() => {})\n      if (this.localNetworkConnected) await localNetworkTransport.disconnect().catch(() => {})\n      await cleanupArtifacts().catch(() => {})\n      this.prepared = []\n      this.active = false\n      this.serverStarted = false\n      this.localNetworkConnected = false\n      this.hotspotRequested = false\n    })()\n    try {\n      await this.teardownPromise\n    } finally {\n      this.teardownPromise = null\n    }\n  }\n}\n\nexport const hotspotOtaTransport = new HotspotOtaTransport()\n"]}

package/build/services/HotspotShutdown.d.ts

@@ -0,0 +1,17 @@
+type HotspotState = {
+    state: "disabled" | "enabled";
+};
+type HotspotShutdownOptions = {
+    attempts?: number;
+    initialDelayMs?: number;
+    retryDelayMs?: number;
+    sleep?: (delayMs: number) => Promise<void>;
+};
+/**
+ * Disable a glasses hotspot with a bounded retry. ASG APK replacement keeps the
+ * BLE link alive through BES, but the first command after the new ASG process
+ * appears can still land while its command path is settling.
+ */
+export declare function disableHotspotWithRetry(requestDisabled: () => Promise<HotspotState>, options?: HotspotShutdownOptions): Promise<boolean>;
+export {};
+//# sourceMappingURL=HotspotShutdown.d.ts.map

package/build/services/HotspotShutdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HotspotShutdown.d.ts","sourceRoot":"","sources":["../../src/services/HotspotShutdown.ts"],"names":[],"mappings":"AAAA,KAAK,YAAY,GAAG;IAAC,KAAK,EAAE,UAAU,GAAG,SAAS,CAAA;CAAC,CAAA;AAEnD,KAAK,sBAAsB,GAAG;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3C,CAAA;AAID;;;;GAIG;AACH,wBAAsB,uBAAuB,CAC3C,eAAe,EAAE,MAAM,OAAO,CAAC,YAAY,CAAC,EAC5C,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,OAAO,CAAC,CAqBlB"}

package/build/services/HotspotShutdown.js

@@ -0,0 +1,29 @@
+const sleep = (delayMs) => new Promise((resolve) => setTimeout(resolve, delayMs));
+/**
+ * Disable a glasses hotspot with a bounded retry. ASG APK replacement keeps the
+ * BLE link alive through BES, but the first command after the new ASG process
+ * appears can still land while its command path is settling.
+ */
+export async function disableHotspotWithRetry(requestDisabled, options = {}) {
+    const attempts = Math.max(1, options.attempts ?? 2);
+    const initialDelayMs = Math.max(0, options.initialDelayMs ?? 0);
+    const retryDelayMs = Math.max(0, options.retryDelayMs ?? 500);
+    const wait = options.sleep ?? sleep;
+    if (initialDelayMs > 0)
+        await wait(initialDelayMs);
+    for (let attempt = 1; attempt <= attempts; attempt += 1) {
+        try {
+            const status = await requestDisabled();
+            if (status.state === "disabled")
+                return true;
+        }
+        catch {
+            // A lost command is indistinguishable from a response timeout here. Retry
+            // while the phone still owns the hotspot network and local server.
+        }
+        if (attempt < attempts && retryDelayMs > 0)
+            await wait(retryDelayMs);
+    }
+    return false;
+}
+//# sourceMappingURL=HotspotShutdown.js.map

package/build/services/HotspotShutdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HotspotShutdown.js","sourceRoot":"","sources":["../../src/services/HotspotShutdown.ts"],"names":[],"mappings":"AASA,MAAM,KAAK,GAAG,CAAC,OAAe,EAAE,EAAE,CAAC,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAA;AAE/F;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,eAA4C,EAC5C,UAAkC,EAAE;IAEpC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAA;IACnD,MAAM,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,cAAc,IAAI,CAAC,CAAC,CAAA;IAC/D,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,YAAY,IAAI,GAAG,CAAC,CAAA;IAC7D,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,IAAI,KAAK,CAAA;IAEnC,IAAI,cAAc,GAAG,CAAC;QAAE,MAAM,IAAI,CAAC,cAAc,CAAC,CAAA;IAElD,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,QAAQ,EAAE,OAAO,IAAI,CAAC,EAAE,CAAC;QACxD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,eAAe,EAAE,CAAA;YACtC,IAAI,MAAM,CAAC,KAAK,KAAK,UAAU;gBAAE,OAAO,IAAI,CAAA;QAC9C,CAAC;QAAC,MAAM,CAAC;YACP,0EAA0E;YAC1E,mEAAmE;QACrE,CAAC;QAED,IAAI,OAAO,GAAG,QAAQ,IAAI,YAAY,GAAG,CAAC;YAAE,MAAM,IAAI,CAAC,YAAY,CAAC,CAAA;IACtE,CAAC;IAED,OAAO,KAAK,CAAA;AACd,CAAC","sourcesContent":["type HotspotState = {state: \"disabled\" | \"enabled\"}\n\ntype HotspotShutdownOptions = {\n  attempts?: number\n  initialDelayMs?: number\n  retryDelayMs?: number\n  sleep?: (delayMs: number) => Promise<void>\n}\n\nconst sleep = (delayMs: number) => new Promise<void>((resolve) => setTimeout(resolve, delayMs))\n\n/**\n * Disable a glasses hotspot with a bounded retry. ASG APK replacement keeps the\n * BLE link alive through BES, but the first command after the new ASG process\n * appears can still land while its command path is settling.\n */\nexport async function disableHotspotWithRetry(\n  requestDisabled: () => Promise<HotspotState>,\n  options: HotspotShutdownOptions = {},\n): Promise<boolean> {\n  const attempts = Math.max(1, options.attempts ?? 2)\n  const initialDelayMs = Math.max(0, options.initialDelayMs ?? 0)\n  const retryDelayMs = Math.max(0, options.retryDelayMs ?? 500)\n  const wait = options.sleep ?? sleep\n\n  if (initialDelayMs > 0) await wait(initialDelayMs)\n\n  for (let attempt = 1; attempt <= attempts; attempt += 1) {\n    try {\n      const status = await requestDisabled()\n      if (status.state === \"disabled\") return true\n    } catch {\n      // A lost command is indistinguishable from a response timeout here. Retry\n      // while the phone still owns the hotspot network and local server.\n    }\n\n    if (attempt < attempts && retryDelayMs > 0) await wait(retryDelayMs)\n  }\n\n  return false\n}\n"]}

package/build/services/LocalDisplayManager.d.ts

@@ -74,6 +74,8 @@ declare class LocalDisplayManager {
      * miniapp is foreground.
      */
     onCoreAppChange(packageName: string | null): void;
+    /** Report-safe ownership snapshot for incident diagnostics. */
+    getDiagnosticSnapshot(): Record<string, unknown>;
     /**
      * A local miniapp is going away. Clean up all state associated with it.
      */
@@ -88,7 +90,20 @@ declare class LocalDisplayManager {
      * the boot queue (resolved when drained or superseded).
      */
     request(packageName: string, payload: DisplayPayload, resolve?: DisplayRequestResolver): void;
+    /**
+     * End a package's temporary display early. If it currently owns the main
+     * view, release its background lock and restore the foreground miniapp's
+     * saved frame. A dismissal for a package that is no longer visible is a
+     * no-op.
+     */
+    dismiss(packageName: string): void;
     private arbitrateAndSend;
+    /**
+     * An app cleared its display ("render nothing"). Same semantics as its
+     * frame expiring: give up ownership, restore the core app's still-valid
+     * display if there is one, otherwise clear the glasses.
+     */
+    private handleAppClear;
     private sendNow;
     /**
      * Send a scene through SceneRenderer. On positioning devices this emits a

package/build/services/LocalDisplayManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LocalDisplayManager.d.ts","sourceRoot":"","sources":["../../src/services/LocalDisplayManager.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"LocalDisplayManager.d.ts","sourceRoot":"","sources":["../../src/services/LocalDisplayManager.ts"],"names":[],"mappings":"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"}

package/build/services/LocalDisplayManager.js

@@ -44,6 +44,12 @@ const BOOT_DURATION_MS = 1500;
 const BACKGROUND_LOCK_TIMEOUT_MS = 10_000;
 // Sentinel package name used as the "source" of the system boot message.
 const SYSTEM_BOOT_PKG = "system.boot";
+/** "Render nothing" — an empty scene or an explicit clear_view layout. */
+function isClearPayload(payload) {
+    if (payload.scene)
+        return payload.scene.length === 0;
+    return payload.layout?.layoutType === "clear_view";
+}
 // =============================================================================
 // LocalDisplayManager
 // =============================================================================
@@ -79,13 +85,19 @@ class LocalDisplayManager {
      */
     onMount(packageName, displayName) {
         console.log(`${LOG_TAG}: onMount(${packageName}, "${displayName}")`);
-        // Cancel any in-flight boot for a prior app.
-        this.cancelBoot();
         // Snapshot whatever's on the glasses BEFORE the boot text overwrites it.
         // registerApp fires onMount for every spawn — including a background app or
         // a crash-respawn while another app is foreground — so a boot that times out
         // without rendering must put the prior frame back rather than blank it.
-        const preBoot = this.currentDisplay;
+        // Never snapshot the boot text itself: back-to-back mounts (the autostart
+        // restore loop, crash-respawn chains) land while the previous app's
+        // "Starting X…" is still on the glasses, and endBoot would "restore" that
+        // stale, expiry-less frame permanently. Across chained boots, inherit the
+        // original pre-boot frame instead.
+        const inherited = this.bootingApp ? this.bootingApp.preBoot : this.currentDisplay;
+        const preBoot = inherited?.packageName === SYSTEM_BOOT_PKG ? null : inherited;
+        // Cancel any in-flight boot for a prior app.
+        this.cancelBoot();
         // Send the boot message directly (bypass arbitration — this is a system
         // display). Goes through sendNow so scene devices render it as a scene:
         // otherwise every app start would be a legacy→scene transition on the
@@ -95,7 +107,7 @@ class LocalDisplayManager {
             layout: { layoutType: "text_wall", text: `Starting ${displayName}…` },
         });
         const timerId = BgTimer.setTimeout(() => {
-            this.endBoot(/* triggeredByFirstDisplay */ false);
+            this.endBoot();
         }, BOOT_DURATION_MS);
         this.bootingApp = {
             packageName,
@@ -123,14 +135,38 @@ class LocalDisplayManager {
             this.coreAppDisplay = null;
         }
     }
+    /** Report-safe ownership snapshot for incident diagnostics. */
+    getDiagnosticSnapshot() {
+        return {
+            coreAppPackageName: this.coreApp,
+            currentDisplayPackageName: this.currentDisplay?.packageName ?? null,
+            backgroundLockPackageName: this.backgroundLock?.packageName ?? null,
+            bootingPackageName: this.bootingApp?.packageName ?? null,
+        };
+    }
     /**
      * A local miniapp is going away. Clean up all state associated with it.
      */
     onUnmount(packageName) {
         console.log(`${LOG_TAG}: onUnmount(${packageName})`);
-        // If this was the booting app, cancel boot.
+        // If this was the booting app, cancel boot — and don't strand its
+        // "Starting X…" text (a system frame with no expiry): put back what the
+        // boot covered, or clear.
         if (this.bootingApp?.packageName === packageName) {
+            const preBoot = this.bootingApp.preBoot;
             this.cancelBoot();
+            if (this.currentDisplay?.packageName === SYSTEM_BOOT_PKG) {
+                // The preBoot owner may have forfeited its frame during the boot
+                // window (a clear parked in the boot queue) — don't resurrect it.
+                const ownerQueued = preBoot ? this.bootQueue.get(preBoot.packageName) : undefined;
+                const preBootForfeited = ownerQueued !== undefined && isClearPayload(ownerQueued.payload);
+                if (preBoot && !preBootForfeited && (preBoot.expiresAt === null || preBoot.expiresAt > this.now())) {
+                    this.restoreDisplay(preBoot);
+                }
+                else {
+                    this.sendClear();
+                }
+            }
         }
         this.bootQueue.get(packageName)?.resolve?.({ status: "blocked", reason: "app stopped" });
         this.bootQueue.delete(packageName);
@@ -140,10 +176,17 @@ class LocalDisplayManager {
         if (this.backgroundLock?.packageName === packageName) {
             this.backgroundLock = null;
         }
-        // Clear saved core app display if the core is going away.
+        // Drop the saved core frame if the core's context is going away — the
+        // frame belongs to a dead context and must not be restored later. The
+        // coreApp POINTER itself is NOT cleared here: it is derived state owned
+        // by the apps-store reconciler. A liveness/crash respawn tears the
+        // context down (this path) without any store change — the app is still
+        // "running" — and clearing the pointer here would leave the respawned
+        // foreground app arbitrating as background until an unrelated store
+        // write happened to re-run the reconciler. Real stops release the slot
+        // via the store (running → false → reconciler → onCoreAppChange(null)).
         if (this.coreApp === packageName) {
             this.coreAppDisplay = null;
-            this.coreApp = null;
         }
         // If this app owned the current on-glasses display, clear it (and maybe
         // restore the core app's display if it still has time left).
@@ -183,12 +226,21 @@ class LocalDisplayManager {
             superseded?.resolve?.({ status: "blocked", reason: "superseded by a newer frame" });
             this.bootQueue.set(packageName, { payload, resolve });
             if (this.bootingApp.packageName === packageName) {
-                this.endBoot(/* triggeredByFirstDisplay */ true);
+                this.endBoot();
             }
             return;
         }
         this.arbitrateAndSend(packageName, payload, resolve);
     }
+    /**
+     * End a package's temporary display early. If it currently owns the main
+     * view, release its background lock and restore the foreground miniapp's
+     * saved frame. A dismissal for a package that is no longer visible is a
+     * no-op.
+     */
+    dismiss(packageName) {
+        this.handleExpiry(packageName);
+    }
     // ===========================================================================
     // Internals — arbitration
     // ===========================================================================
@@ -198,6 +250,15 @@ class LocalDisplayManager {
         if (this.backgroundLock && now > this.backgroundLock.expiresAt) {
             this.backgroundLock = null;
         }
+        // A clear ("render nothing") means "I'm done with the display" — it is a
+        // forfeit, not a frame. A background app releases its lock and the core
+        // app's still-valid display comes back; treating it as a render instead
+        // would RENEW the lock with an empty frame and blank the glasses while
+        // still blocking everyone else.
+        if (isClearPayload(payload)) {
+            this.handleAppClear(packageName, resolve);
+            return;
+        }
         const isCore = packageName === this.coreApp;
         if (isCore) {
             // Save so we can restore later.
@@ -246,6 +307,30 @@ class LocalDisplayManager {
         }
         this.sendNow(packageName, payload, resolve);
     }
+    /**
+     * An app cleared its display ("render nothing"). Same semantics as its
+     * frame expiring: give up ownership, restore the core app's still-valid
+     * display if there is one, otherwise clear the glasses.
+     */
+    handleAppClear(packageName, resolve) {
+        // Forget the app's retained scene state — its next render starts fresh.
+        sceneRenderer.clearApp(packageName);
+        if (this.backgroundLock?.packageName === packageName) {
+            this.backgroundLock = null;
+        }
+        if (this.coreApp === packageName) {
+            this.coreAppDisplay = null;
+        }
+        if (this.currentDisplay?.packageName === packageName) {
+            this.clearExpiryTimer();
+            this.currentDisplay = null;
+            this.tryRestoreCoreDisplay();
+            if (!this.currentDisplay) {
+                this.sendClear();
+            }
+        }
+        resolve?.({ status: "displayed" });
+    }
     // ===========================================================================
     // Internals — send
     // ===========================================================================
@@ -411,7 +496,7 @@ class LocalDisplayManager {
         BgTimer.clearTimeout(this.bootingApp.timerId);
         this.bootingApp = null;
     }
-    endBoot(triggeredByFirstDisplay) {
+    endBoot() {
         if (!this.bootingApp)
             return;
         const preBoot = this.bootingApp.preBoot;
@@ -430,17 +515,18 @@ class LocalDisplayManager {
                 continue;
             this.arbitrateAndSend(pkg, entry.payload, entry.resolve);
         }
-        // Boot ended on the timeout with nothing queued and no first display — the
-        // app just never rendered. Restore whatever was on the glasses before the
-        // boot text so a background app or crash-respawn can't blank a foreground
-        // app's frame (registerApp fires onMount for every spawn, and the core app
-        // isn't wired on the local path yet). If the glasses were empty before,
-        // clear the lingering "Starting …" instead — otherwise a miniapp that never
-        // renders (e.g. audio-only) would strand it.
-        if (!triggeredByFirstDisplay && queued.length === 0) {
-            // Only restore a frame that's still valid — one whose duration elapsed
-            // during the boot window should clear, not come back.
-            if (preBoot && (preBoot.expiresAt === null || preBoot.expiresAt > this.now())) {
+        // If the boot text is still on the glasses — nothing was queued, or every
+        // drained request lost arbitration — it must not strand: it's a system
+        // frame with no expiry. Restore whatever was on the glasses before the
+        // boot, else clear. Two reasons NOT to restore: the frame's duration
+        // elapsed during the boot window, or its owner FORFEITED it during the
+        // window (its final queued intent — the queue keeps last-wins per app —
+        // was a clear, which the drain above processed as a forfeit; restoring
+        // would resurrect content the clear removed).
+        if (this.currentDisplay?.packageName === SYSTEM_BOOT_PKG) {
+            const ownerEntry = preBoot ? queued.find(([pkg]) => pkg === preBoot.packageName) : undefined;
+            const preBootForfeited = ownerEntry !== undefined && isClearPayload(ownerEntry[1].payload);
+            if (preBoot && !preBootForfeited && (preBoot.expiresAt === null || preBoot.expiresAt > this.now())) {
                 this.restoreDisplay(preBoot);
             }
             else {