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

package/src/services/HotspotOtaTransport.ts

@@ -0,0 +1,185 @@
+import BluetoothSdk, {isEnabledHotspotStatus} from "@mentra/bluetooth-sdk"
+import {otaServer} from "@mentra/bluetooth-sdk/ota-transport"
+// 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 type {OtaCheckCurrentGlassesResult} from "./OtaUpdateCheckService"
+import {
+  cleanupArtifacts,
+  OtaArtifactError,
+  planArtifacts,
+  prepareArtifacts,
+  rewriteManifestForLocalServer,
+  type OtaArtifactDownloadProgress,
+  type PreparedOtaArtifact,
+} from "./OtaArtifactDownloader"
+import {disableHotspotWithRetry} from "./HotspotShutdown"
+import {localNetworkTransport} from "./asg/localNetworkTransport"
+
+export type HotspotOtaPhase = "idle" | "downloading" | "starting_hotspot" | "joining_hotspot" | "serving"
+
+export type HotspotOtaProgress = {
+  phase: HotspotOtaPhase
+  artifact?: OtaArtifactDownloadProgress
+}
+
+export type HotspotOtaErrorCode =
+  | "hotspot_wifi_permission_denied"
+  | "hotspot_start_failed"
+  | "hotspot_join_failed"
+  | "hotspot_server_failed"
+
+export class HotspotOtaTransportError extends Error {
+  constructor(
+    public readonly code: HotspotOtaErrorCode,
+    message: string,
+  ) {
+    super(message)
+    this.name = "HotspotOtaTransportError"
+  }
+}
+
+/** Owns the single phone-side endpoint and network lease for one hotspot OTA attempt. */
+class HotspotOtaTransport {
+  private active = false
+  private prepared: PreparedOtaArtifact[] = []
+  private hotspotRequested = false
+  private localNetworkConnected = false
+  private serverStarted = false
+  private teardownPromise: Promise<void> | null = null
+
+  async prepare(
+    checkResult: OtaCheckCurrentGlassesResult,
+    onProgress?: (progress: HotspotOtaProgress) => void,
+  ): Promise<string> {
+    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: HotspotOtaPhase = "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 otaServer.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 otaServer.start("{}", artifactPaths, localAddress)
+      this.serverStarted = true
+      const manifest = rewriteManifestForLocalServer(checkResult.manifestBody, this.prepared, server.baseUrl)
+      const published = await otaServer.start(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. */
+  private async ensureAndroidWifiPermission(): Promise<void> {
+    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",
+      )
+    }
+  }
+
+  private downloadIosArtifact = async (
+    entry: {url: string},
+    destination: string,
+    onProgress?: (bytesWritten: number, contentLength: number) => void,
+  ): Promise<{statusCode: number}> => {
+    const subscription = otaServer.onArtifactDownloadProgress((event) => {
+      if (event.destination === destination) onProgress?.(event.bytesWritten, event.contentLength)
+    })
+    try {
+      return await otaServer.downloadArtifact(entry.url, destination)
+    } finally {
+      subscription.remove()
+    }
+  }
+
+  async teardown(): Promise<void> {
+    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 otaServer.stop().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()

package/src/services/HotspotShutdown.ts

@@ -0,0 +1,41 @@
+type HotspotState = {state: "disabled" | "enabled"}
+
+type HotspotShutdownOptions = {
+  attempts?: number
+  initialDelayMs?: number
+  retryDelayMs?: number
+  sleep?: (delayMs: number) => Promise<void>
+}
+
+const sleep = (delayMs: number) => new Promise<void>((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: () => Promise<HotspotState>,
+  options: HotspotShutdownOptions = {},
+): Promise<boolean> {
+  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
+}

package/src/services/LocalDisplayManager.ts

@@ -2,9 +2,8 @@
  * LocalDisplayManager
  *
  * Phone-side arbiter for display requests originating from LOCAL miniapps
- * (the @mentra/miniapp SDK). Mirrors the user-facing behavior of the cloud
- * DisplayManager (cloud/packages/cloud/src/services/layout/DisplayManager6.1.ts)
- * for the features that matter on the phone:
+ * (the @mentra/miniapp SDK). Preserves the retired cloud display manager's
+ * user-facing behavior for the features that matter on the phone:
  *
  *   - boot message ("Starting <AppName>…") with a bounded window
  *   - durationMs auto-clear
@@ -98,6 +97,12 @@ 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: DisplayPayload): boolean {
+  if (payload.scene) return payload.scene.length === 0
+  return payload.layout?.layoutType === "clear_view"
+}
+
 // =============================================================================
 // LocalDisplayManager
 // =============================================================================
@@ -144,14 +149,20 @@ class LocalDisplayManager {
   public onMount(packageName: string, displayName: string): void {
     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:
@@ -163,7 +174,7 @@ class LocalDisplayManager {
     })
 
     const timerId = BgTimer.setTimeout(() => {
-      this.endBoot(/* triggeredByFirstDisplay */ false)
+      this.endBoot()
     }, BOOT_DURATION_MS)
 
     this.bootingApp = {
@@ -195,15 +206,39 @@ class LocalDisplayManager {
     }
   }
 
+  /** Report-safe ownership snapshot for incident diagnostics. */
+  public getDiagnosticSnapshot(): Record<string, unknown> {
+    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.
    */
   public onUnmount(packageName: string): void {
     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)
@@ -216,10 +251,17 @@ class LocalDisplayManager {
       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
@@ -263,7 +305,7 @@ 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
     }
@@ -271,6 +313,16 @@ class LocalDisplayManager {
     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.
+   */
+  public dismiss(packageName: string): void {
+    this.handleExpiry(packageName)
+  }
+
   // ===========================================================================
   // Internals — arbitration
   // ===========================================================================
@@ -283,6 +335,16 @@ class LocalDisplayManager {
       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) {
@@ -339,6 +401,33 @@ 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.
+   */
+  private handleAppClear(packageName: string, resolve?: DisplayRequestResolver): void {
+    // 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
   // ===========================================================================
@@ -523,7 +612,7 @@ class LocalDisplayManager {
     this.bootingApp = null
   }
 
-  private endBoot(triggeredByFirstDisplay: boolean): void {
+  private endBoot(): void {
     if (!this.bootingApp) return
     const preBoot = this.bootingApp.preBoot
     BgTimer.clearTimeout(this.bootingApp.timerId)
@@ -543,17 +632,18 @@ class LocalDisplayManager {
       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 {
         this.sendClear()