@mentra/engine 3.2.0-dev.255 → 3.2.0-dev.261

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/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

package/src/services/slimStreamStatus.ts

@@ -11,7 +11,10 @@ import type {StreamStatusEvent} from "@mentra/bluetooth-sdk/internal"
  */
 export const ENABLE_PIPELINE_FPS_TELEMETRY = false
 
-/** Fields forwarded to cloud / miniapps after the first resolvedConfig ack. */
+/**
+ * Select stream-status fields for local miniapps. Include resolvedConfig only
+ * when requested by the caller; include stats only when FPS telemetry is enabled.
+ */
 export function slimStreamStatusEvent(
   event: StreamStatusEvent,
   options: {includeResolvedConfig?: boolean; enableFpsTelemetry?: boolean} = {},

package/src/stores/apps.ts

@@ -381,8 +381,8 @@ export const useAppStatusStore = create<AppStatusState>((set, get) => ({
     // side effect of LocalMiniappView mounting on foreground; pulling it here
     // lets start() actually run the app even when nothing foregrounds it (e.g.
     // a system app launching another miniapp via session.miniapps). Idempotent
-    // with the view's own ensureRunning; a no-op for native offline built-ins
-    // and cloud apps (no JS bundle).
+    // with the view's own ensureRunning; skipped for native offline built-ins
+    // (no JS bundle).
     if (app.local) {
       try {
         await miniappLauncher.ensureRunning(packageName)

package/src/utils/miniappGlobals.ts

@@ -1,11 +1,9 @@
 /**
  * miniappGlobals — shared builder for the window.MentraOS globals injected
- * into every miniapp WebView (both cloud and local).
+ * into miniapp WebViews in the Mentra App on the phone.
  *
- * Authors should be able to use one API in their miniapp code regardless of
- * whether it's hosted in the cloud or on-device. So both injection paths
- * (webview.tsx for cloud miniapps, MiniappHost.tsx for local miniapps) funnel
- * through this util.
+ * Miniapps run locally. This util gives their WebView UI a consistent API
+ * for host capabilities, safe-area insets, and capsule-menu geometry.
  */
 
 import {Dimensions, Platform} from "react-native"