@mentra/engine 3.2.0-dev.259 → 3.2.0-dev.262

package/src/services/MentraUIRouter.ts

@@ -50,14 +50,13 @@ interface BoundWebView {
 }
 
 /**
- * NOTE: the WebView ↔ host heartbeat was removed when the lifecycle
- * inversion landed. The current model is **at most one WebView at a
- * time, foreground UI with an always-on background JSContext** (same
- * shape as the cloud-WebView miniapps). User navigation closes it
- * explicitly and `onContentProcessDidTerminate` catches OS-level
- * crashes, but the host may still re-announce UI_OPEN for an already
- * mounted WebView after app resume/dev respawn so the background can
- * push a fresh authoritative snapshot.
+ * The host mounts at most one miniapp UI WebView at a time. Its background
+ * JSContext runs separately on the phone and can remain alive after UI closure.
+ * UI closure unbinds the WebView and sends UI_CLOSE; on iOS the host also exits
+ * the UI when `onContentProcessDidTerminate` reports a content-process exit.
+ * The host may re-announce UI_OPEN after app resume or background dev respawn
+ * so the background can push a fresh snapshot. This router has no WebView
+ * heartbeat timeout.
  */
 
 export class MentraUIRouter {
@@ -85,9 +84,8 @@ export class MentraUIRouter {
   }
 
   /**
-   * Called when the WebView unmounts (user navigated away or the host
-   * tore it down on heartbeat timeout). Pushes UI_CLOSE to background
-   * so handlers can flush state, then drops the binding.
+   * Called when the host tears down the WebView. Drops the binding and
+   * sends UI_CLOSE to the background so handlers can flush state.
    */
   unbindWebView(packageName: string): void {
     if (!this.bindings.has(packageName)) return
@@ -123,7 +121,6 @@ export class MentraUIRouter {
    * Recognised envelope types from the WebView shim:
    *   - {type: "ready"}                              → fire UI_OPEN
    *   - {type: "msg", seq, channel, payload}         → fire UI_MESSAGE
-   *   - {type: "heartbeat", seq}                     → silently ack
    */
   routeFromWebView(packageName: string, rawJson: string): void {
     let env: {

package/src/services/MiniappLauncher.ts

@@ -317,12 +317,9 @@ class MiniappLauncher {
   /**
    * Re-spawn local miniapps that were running when the app was last killed.
    *
-   * Cloud apps run on a remote server: the cloud persists which ones are
-   * running and resurrects them when the phone reconnects, so a host-app
-   * restart brings them back on its own. Local (phone-hosted) miniapps run in
-   * the phone's own JS engine — a host-process kill tears down their JSContext
-   * and there is no server to resurrect them, so without this they silently
-   * stay stopped on the next launch even though the user left them running.
+   * Every miniapp runs as local JavaScript in the Mentra App on the phone.
+   * A host-process kill tears down its JSContext, so without this restoration
+   * it stays stopped on the next launch even though the user left it running.
    *
    * Each local miniapp persists its running flag to disk on start/stop
    * (`saveLocalAppRunningState`, via the applet's `onStart`/`onStop`). We read
@@ -331,9 +328,9 @@ class MiniappLauncher {
    * tray/switcher project it as running, exactly as a normal start would. The
    * WebView, if any, re-attaches lazily when the user opens the app.
    *
-   * Idempotent and best-effort: skips already-spawned contexts, and clears the
-   * persisted flag for any app whose bundle can no longer be resolved
-   * (uninstalled, or dev server gone) so a dead entry doesn't retry every boot.
+   * Idempotent and best-effort: skips already-spawned contexts and clears the
+   * persisted running flag if ensureRunning fails (for example, bundle resolution,
+   * deployment policy, or context spawning) so it does not retry every boot.
    * Not compatibility-gated: a previously-running background app shouldn't be
    * dropped just because glasses are momentarily disconnected at boot — it
    * resumes when they reconnect, same as mid-session.

package/src/services/MiniappLiveness.ts

@@ -3,6 +3,24 @@ export interface MiniappPingLivenessDecision {
   unansweredPingRounds: number
 }
 
+/**
+ * SoftAP join can spend a minute in native `prepareAgent` before the glasses
+ * hotspot even turns on. The JS bundle stays alive but may miss pongs while
+ * ACS is on the native thread. Unregistering for missed pings in that window
+ * cancels the join and leaves the UI stuck on the hotspot row.
+ */
+export function shouldHoldMiniappPingLiveness(args: {
+  packageName: string
+  softapPackageName?: string | null
+  softapCancelled?: boolean
+}): boolean {
+  return Boolean(
+    args.softapPackageName &&
+      args.softapPackageName === args.packageName &&
+      !args.softapCancelled,
+  )
+}
+
 /**
  * Advance liveness by one scheduled ping round.
  *

package/src/services/PhoneLocationService.ts

@@ -1,8 +1,8 @@
 /**
  * Phone location service — engine-owned. Owns the background phone-GPS task: the
  * accuracy-tier control (`setLocationTier`), the accuracy mapping, and the
- * `expo-task-manager` background task that fans each fix to the v2 cloud
- * local miniapps (`location_update`). Cloud upload was V1 (removed).
+ * `expo-task-manager` background task that forwards the first fix in each batch
+ * to subscribed local miniapps (`location_update`). Cloud upload was V1 (removed).
  *
  * This used to be the host-injected `locationTier` runtime hook + a MantleManager
  * `TaskManager.defineTask`. It's device/OS plumbing (no UI), so it moved into engine:
@@ -21,8 +21,7 @@ import localMiniappRuntime from "./LocalMiniappRuntime"
 
 export const LOCATION_TASK_NAME = "handleLocationUpdates"
 
-// Background location task — sends each fix to the v2 cloud (RestComms) + local
-// miniapps. (The v1 SocketComms leg was already removed/commented before the move.)
+// Background location task — forwards the first fix from each non-empty batch.
 TaskManager.defineTask<{locations?: Location.LocationObject[]}>(LOCATION_TASK_NAME, async ({data, error}) => {
   if (error) {
     // OS-level failure (permission revoked, GPS unavailable, …) — log it so
@@ -36,11 +35,8 @@ TaskManager.defineTask<{locations?: Location.LocationObject[]}>(LOCATION_TASK_NA
     return
   }
   const first = locs[0]!
-  // Cloud path (relayMessageToApps) never reaches __phone__, so local miniapps rely
-  // on this direct push.
-  // Local miniapps get the update directly (the cloud relay never reaches
-  // __phone__). The Cloud V1 upload that used to run here was removed with the
-  // V1 ripout (issue #3392); a V2 location channel is separate product work.
+  // Deliver directly to local miniapps. The Cloud V1 upload that used to run
+  // here was removed with the V1 ripout (issue #3392).
   localMiniappRuntime.forwardEvent("location_update", {
     lat: first.coords.latitude,
     lng: first.coords.longitude,

package/src/services/PhoneStreamCoordinator.ts

@@ -23,8 +23,7 @@
  *
  * Important: this is the ONLY place that mints `streamId`s for phone-owned
  * streams. We use a `phone-` prefix so they're trivially distinguishable from
- * cloud-minted IDs in logs and from cloud-SDK app streams that flow through
- * the legacy path.
+ * cloud-minted managed-stream resource IDs in logs.
  *
  * BLE link loss is a SUSPENDED state, not a failure:
  *   ASG owns the ten-second phone/controller liveness deadline. The coordinator
@@ -231,9 +230,12 @@ export class PhoneStreamCoordinator {
    * A stream was torn down while the BLE link was down, so the glasses never
    * got `stopStream`. Sent on the next reconnect (if no new stream has claimed
    * the slot) so a publisher that outlived its input does not keep pushing
-   * until its own watchdog fires.
+   * until its own watchdog fires. `generation` belongs to the publisher that
+   * queued it; a later SoftAP media hop must not inherit this stop.
    */
-  private pendingBleStop: {streamId: string; hotspot?: boolean} | null = null
+  private pendingBleStop: {streamId: string; hotspot?: boolean; generation: number; discarded?: boolean} | null = null
+  /** Bumped each time an unmanaged/managed publisher claims the slot. */
+  private publisherGeneration = 0
   /**
    * Serializes state transitions (start, stop, teardown). Without it, a
    * second `start*` racing with the first can pass the `this.current === null`
@@ -364,6 +366,7 @@ export class PhoneStreamCoordinator {
       }
 
       const streamId = this.mintId("u")
+      ++this.publisherGeneration
       const entry: UnmanagedEntry = {
         kind: "unmanaged",
         streamId,
@@ -462,6 +465,7 @@ export class PhoneStreamCoordinator {
       // and joins instead of double-provisioning.
       const provision = await provisionManagedStream(opts.restreamDestinations)
       const streamId = this.mintId("m")
+      ++this.publisherGeneration
       let ingestUrl: string
       try {
         ingestUrl = pickIngestUrl(provision, opts.ingest)
@@ -514,7 +518,7 @@ export class PhoneStreamCoordinator {
             },
             () => this.linkSource.isConnected(),
             () => {
-              this.pendingBleStop = {streamId, hotspot: true}
+              this.pendingBleStop = {streamId, hotspot: true, generation: this.publisherGeneration}
               this.attachLink()
             },
           )
@@ -616,6 +620,22 @@ export class PhoneStreamCoordinator {
     })
   }
 
+  /**
+   * Drop a deferred BLE `stopStream` that belonged to a publisher that is gone.
+   *
+   * SoftAP recovery destroys generation N and rebuilds N+1. If failSuspended already
+   * tore the publisher down after `glassesGraceMs`, `stop()` is a no-op but a pending
+   * stop would still flush into the new hop on reconnect. Call this from SoftAP
+   * `stopPublishing` so the deferred command dies with its generation.
+   */
+  discardPendingBleStop(): void {
+    const pending = this.pendingBleStop
+    if (!pending) return
+    pending.discarded = true
+    this.pendingBleStop = null
+    this.detachLinkIfIdle()
+  }
+
   /**
    * Called by MantleManager when a `stream_status` event arrives from glasses
    * and the registry says it's phone-owned.
@@ -760,9 +780,10 @@ export class PhoneStreamCoordinator {
 
   private async flushPendingBleStop(): Promise<void> {
     const pending = this.pendingBleStop
-    if (!pending || this.current || !this.linkSource.isConnected()) return
+    if (!pending || pending.discarded || this.current || !this.linkSource.isConnected()) return
     console.info("[STREAM] BLE link back; sending deferred stopStream", pending)
     await BluetoothSdk.stopStream()
+    if (pending.discarded || this.pendingBleStop !== pending || this.current) return
     if (pending.hotspot) {
       const result = await BluetoothSdk.setHotspotState(false)
       if (result.state !== "disabled") throw new Error("Deferred hotspot shutdown was not confirmed")
@@ -1010,7 +1031,7 @@ export class PhoneStreamCoordinator {
     // lock for the native timeout). Defer it to the next reconnect instead.
     const linkUp = this.linkSource.isConnected()
     if (sendBleStop && !linkUp) {
-      this.pendingBleStop = {streamId: entry.streamId, hotspot: entry.kind === "managed" && !!entry.relay}
+      this.pendingBleStop = {streamId: entry.streamId, hotspot: entry.kind === "managed" && !!entry.relay, generation: this.publisherGeneration}
       console.warn("[STREAM] BLE link down during teardown; stopStream deferred", {
         streamId: entry.streamId,
         reason,