@glassly/engine 0.1.0-dev.99 → 0.2.8-dev.445

package/src/services/LocalMiniappRuntime.ts

@@ -9,7 +9,10 @@
  * management (connect/disconnect/ping).
  */
 
+import {mirrorService} from "./MirrorService"
 import {AppState, Linking} from "react-native"
+import {logBuffer} from "../utils/devLogging"
+import {collectDisplayDiagnostics} from "./DisplayDiagnostics"
 import Share from "react-native-share"
 import * as Battery from "expo-battery"
 import * as Clipboard from "expo-clipboard"
@@ -26,7 +29,7 @@ import {
   parseEnvelope,
   serializeEnvelope,
 } from "@glassly/miniapp"
-import type {MiniappEnvelope} from "@glassly/miniapp"
+import type {MiniappEnvelope, MiniappLaunchSource, MiniappPreferences} from "@glassly/miniapp"
 
 import {DeviceTypes, type Capabilities} from "../types"
 import {getEffectiveCapabilities} from "./effectiveCapabilities"
@@ -52,10 +55,34 @@ import {normalizeAiTier, resolveAiTier} from "./AiTierResolution"
 import type {AiTier, AiTierProvider, SavedLlmKeys} from "./AiTierResolution"
 import {HttpError} from "@glassly/cloud-client"
 import localDisplayManager from "./LocalDisplayManager"
-import {claimsGesture} from "./gestureClaims"
+import {
+  dropGestureClaims,
+  emptyGestureClaims,
+  gestureClaimant,
+  hasGestureClaim,
+  setGestureClaims,
+  type GestureClaimChange,
+  type GestureClaimState,
+} from "./gestureClaims"
+import overlayPages from "./pages/OverlayPages"
+import dashboardOpenTrace from "./debug/DashboardOpenTrace"
+import {isAppForegrounded, isPhoneActive, onAppForegroundChange, onPhoneActivityChange} from "./PhoneActivity"
+import {installedNotificationApps} from "./PhoneNotificationsSync"
+import {
+  DERIVED_SETTINGS_KEYS,
+  SETTINGS_BRIDGE_KEYS,
+  isDerivedSettingsKey,
+  ringBatteryFrom,
+  selectSettingsBridgeKeys,
+  validateSettingsSet,
+  type DerivedSettingsKey,
+} from "./settingsBridge"
+import {addOverlayApp, displayViewsFor, isOverlayApp, removeOverlayApp, setOverlayViewer} from "./pages/overlayApps"
+import {pagesEligible} from "./pages/pageEligibility"
 import nativeNavigationService from "./NativeNavigationService"
 import type {DisplayPayload} from "./LocalDisplayManager"
 import headingService from "./HeadingService"
+import glassesSensorService from "./GlassesSensorService"
 import localSttFallbackCoordinator from "./LocalSttFallbackCoordinator"
 import speakerLabelResolver from "./SpeakerLabelResolver"
 import micStateCoordinator from "./MicStateCoordinator"
@@ -158,6 +185,8 @@ interface ConnectedMiniapp {
    * see {@link LOCATION_RATE_PRIORITY}.
    */
   requestedLocationRate: string | null
+  /** Who started the app; echoed in CONNECT_ACK. */
+  launchSource?: MiniappLaunchSource
 }
 
 interface SpeechRun {
@@ -222,9 +251,12 @@ const SYSTEM_MINIAPP_PACKAGES = new Set([
   "com.glassly.simulated",
   "com.glassly.mirror",
   "com.glassly.ai",
-  "cloud.augmentos.notify",
   "com.glassly.feedback",
   "com.glassly.miniappdev",
+  // The dashboard: the settings bridge and the miniapp list/start/stop are its side menu and settings page.
+  "com.glassly.dashboard",
+  // The notifications viewer: the settings bridge and the notification app list are its settings page.
+  "com.glassly.notifications",
 ])
 const PING_INTERVAL_MS = 5_000
 // Min gap between "transcription limit reached" notices on the glasses. A
@@ -304,6 +336,7 @@ const PERMISSION_TYPE_TO_CANONICAL: Record<string, string> = {
   LOCATION: "location",
   BACKGROUND_LOCATION: "location",
   READ_NOTIFICATIONS: "notifications",
+  DISPLAY_MIRROR: "displayMirror",
   POST_NOTIFICATIONS: "notifications",
   CALENDAR: "calendar",
   API_KEYS: "apiKeys",
@@ -423,6 +456,7 @@ const ALL_CANONICAL_PERMISSIONS = [
   "memory",
   "ai",
   "speakers",
+  "displayMirror",
 ] as const
 
 /**
@@ -540,8 +574,8 @@ class LocalMiniappRuntime {
 
   /** Connected miniapps keyed by packageName. */
   private connectedApps: Map<string, ConnectedMiniapp> = new Map()
-  /** Per-app claimed gestures (CLAIM_GESTURES) — see foregroundClaimsGesture. */
-  private gestureClaims: Map<string, Set<string>> = new Map()
+  /** Claimed gestures (CLAIM_GESTURES): a stack per gesture, the most recent claimer holding it. */
+  private gestureClaims: GestureClaimState = emptyGestureClaims()
 
   /**
    * Packages that have completed their CONNECT handshake (sent
@@ -564,6 +598,10 @@ class LocalMiniappRuntime {
   private cloudResultsWired = false
   private cloudStatusWired = false
   private capabilitiesWired = false
+  private preferencesWired = false
+  private settingsBridgeWired = false
+  /** Last derived read-only values pushed on the settings stream, for change detection. */
+  private derivedSettings = new Map<DerivedSettingsKey, string>()
   private cloudAudioSubscriptionSync = new CloudAudioSubscriptionSync()
 
   /**
@@ -692,6 +730,22 @@ class LocalMiniappRuntime {
       }
     }
 
+    if (this.streamSubscribers.has(MiniappStreamType.MIRROR_UPDATE)) {
+      if (!this.mirrorUnsubscribe)
+        this.mirrorUnsubscribe = mirrorService.subscribe((snapshot) => {
+          for (const pkg of this.streamSubscribers.get(MiniappStreamType.MIRROR_UPDATE) ?? []) {
+            if (this.hasMirrorPermission(pkg))
+              this.sendToMiniapp(pkg, {
+                type: MiniappResponseType.EVENT,
+                streamType: MiniappStreamType.MIRROR_UPDATE,
+                data: snapshot,
+              })
+          }
+        })
+    } else {
+      this.mirrorUnsubscribe?.()
+      this.mirrorUnsubscribe = null
+    }
     this.publishTranscriptionDebugSubscribers()
   }
 
@@ -802,6 +856,15 @@ class LocalMiniappRuntime {
     return LocalMiniappRuntime.instance
   }
 
+  private mirrorUnsubscribe: (() => void) | null = null
+
+  private hasMirrorPermission(packageName: string): boolean {
+    return (
+      this.connectedApps.get(packageName)?.installedManifest?.permissions?.some((p) => p.type === "DISPLAY_MIRROR") ===
+      true
+    )
+  }
+
   private initialized = false
 
   /**
@@ -813,6 +876,17 @@ class LocalMiniappRuntime {
     this.initialized = true
     console.log(`${LOG_TAG}: initialize()`)
     this.ensurePingLoop()
+    mirrorService.initialize()
+    // The overlay apps' pages relay through the runtime: the slot going to
+    // and from an app arrives as its display_view events.
+    overlayPages.setSink({
+      send: (packageName, event) =>
+        this.sendToMiniapp(packageName, {
+          type: MiniappResponseType.EVENT,
+          streamType: MiniappStreamType.DISPLAY_VIEW,
+          data: event,
+        }),
+    })
   }
 
   /**
@@ -907,6 +981,7 @@ class LocalMiniappRuntime {
     packageName: string,
     sendFn: (raw: string) => void,
     installedManifest?: InstalledMiniappManifest,
+    launchSource?: MiniappLaunchSource,
   ): void {
     console.log(`${LOG_TAG}: registerApp(${packageName})`)
     this.clearForegroundProbe(packageName)
@@ -918,6 +993,9 @@ class LocalMiniappRuntime {
     // dangling references. The WebView will re-subscribe after its CONNECT.
     if (this.connectedApps.has(packageName)) {
       const existing = this.connectedApps.get(packageName)!
+      void glassesSensorService.release(packageName).catch((error) => {
+        console.warn(`${LOG_TAG}: sensor cleanup failed on respawn for ${packageName}`, error)
+      })
       this.cancelSpeech(packageName)
       // A crash respawn replaces the ConnectedMiniapp without going through
       // unregisterApp(). Abort the old incarnation's native PCM player before
@@ -956,6 +1034,7 @@ class LocalMiniappRuntime {
       authDelivered: false,
       speakerState: "idle",
       requestedLocationRate: null,
+      launchSource,
     })
     // If we just clobbered an existing entry, its requestedLocationRate is
     // now gone — recompute so the aggregate doesn't include a stale rate.
@@ -963,6 +1042,8 @@ class LocalMiniappRuntime {
     this.recomputeLocationTier()
     this.ensureCloudStatusWired()
     this.ensureCapabilitiesWired()
+    this.ensurePreferencesWired()
+    this.ensureSettingsBridgeWired()
     this.ensurePingLoop()
 
     // Show the system boot message ("Starting <name>…") on the glasses for the
@@ -988,12 +1069,12 @@ class LocalMiniappRuntime {
       const waiter = (err?: Error) => {
         if (settled) return
         settled = true
-        clearTimeout(timer)
+        BgTimer.clearTimeout(timer)
         this.connectWaiters.get(packageName)?.delete(waiter)
         if (err) reject(err)
         else resolve()
       }
-      const timer = setTimeout(() => {
+      const timer = BgTimer.setTimeout(() => {
         waiter(new Error(`waitForConnect: ${packageName} did not connect within ${timeoutMs}ms`))
       }, timeoutMs)
       let set = this.connectWaiters.get(packageName)
@@ -1065,7 +1146,7 @@ class LocalMiniappRuntime {
     // 50 ms: imperceptible to the user, plenty of time for the SDK's
     // synchronous `beforeDisconnect` handlers to flush a final
     // sendOneShot through the still-open transport.
-    await new Promise<void>((resolve) => setTimeout(resolve, 50))
+    await new Promise<void>((resolve) => BgTimer.setTimeout(resolve, 50))
     this.unregisterApp(packageName)
   }
 
@@ -1083,6 +1164,14 @@ class LocalMiniappRuntime {
     // Drop this app's transcription hints; the cloud subscription rebuild
     // below (via replaceStreamSubscribers) re-derives the hint union without it.
     this.transcriptionHintsByApp.delete(packageName)
+    // An overlay app is going: release the slot if it holds it, and drop the
+    // dashboard view from its capabilities record.
+    if (isOverlayApp(packageName)) {
+      overlayPages.remove(packageName)
+      removeOverlayApp(packageName)
+    }
+    // Its gesture claims go back to whoever claimed them before.
+    this.applyGestureClaimChanges(dropGestureClaims(this.gestureClaims, packageName))
 
     // Warm-up is a request-owned camera lease. Cancel it even if the app record was already
     // removed so a close racing the camera-open promise cannot leave the sensor running.
@@ -1150,11 +1239,16 @@ class LocalMiniappRuntime {
       this.navigationHandlers.onDisconnect(packageName)
     }
 
+    void glassesSensorService.release(packageName).catch((error) => {
+      console.warn(`${LOG_TAG}: sensor cleanup failed for ${packageName}`, error)
+    })
+
     // Recompute heading subscription — if this app was the last subscriber,
     // the sensor will stop.
     this.recomputeHeadingSubscription()
-    // Same for the IMU/accelerometer stream.
+    // Same for the IMU/accelerometer and glasses compass streams.
     this.recomputeImuSubscription()
+    this.recomputeCompassSubscription()
 
     // Drop this app's location-tier request before recomputing so the
     // aggregate falls back down if it was the strictest. Done before
@@ -1176,7 +1270,6 @@ class LocalMiniappRuntime {
     // core app's saved frame).
     localDisplayManager.onUnmount(packageName)
 
-    this.gestureClaims.delete(packageName)
     this.connectedApps.delete(packageName)
     this.recomputeMicRequirements()
     if (releasedMicGateOverride) {
@@ -1261,9 +1354,30 @@ class LocalMiniappRuntime {
       case MiniappRequestType.DISPLAY:
         this.handleDisplay(packageName, payload, requestId)
         break
+      case MiniappRequestType.MIRROR_GET:
+        if (!this.hasMirrorPermission(packageName)) {
+          this.sendResult(packageName, requestId, false, undefined, {
+            code: MiniappErrorCode.PERMISSION_NOT_DECLARED,
+            message: "DISPLAY_MIRROR permission not declared in miniapp.json",
+            permission: "DISPLAY_MIRROR",
+          })
+        } else this.sendResult(packageName, requestId, true, mirrorService.current())
+        break
       case MiniappRequestType.RENDER:
         this.handleRender(packageName, payload, requestId)
         break
+      case MiniappRequestType.SHOW_VIEW:
+        this.handleShowView(packageName, payload, requestId)
+        break
+      case MiniappRequestType.SETTINGS_GET:
+        this.handleSettingsGet(packageName, payload, requestId)
+        break
+      case MiniappRequestType.SETTINGS_SET:
+        void this.handleSettingsSet(packageName, payload, requestId)
+        break
+      case MiniappRequestType.NOTIFICATION_APPS_LIST:
+        void this.handleNotificationAppsList(packageName, requestId)
+        break
       case MiniappRequestType.NATIVE_NAV:
         this.handleNativeNav(packageName, payload, requestId)
         break
@@ -1395,6 +1509,23 @@ class LocalMiniappRuntime {
       case MiniappRequestType.SET_WIFI_ADB_STATE:
         void this.handleSetWifiAdbState(packageName, payload, requestId)
         break
+      case MiniappRequestType.GLASSES_SENSOR_CONTROL:
+        if (!this.connectedApps.has(packageName)) {
+          this.sendResult(packageName, requestId, false, undefined, {
+            code: MiniappErrorCode.NOT_CONNECTED,
+            message: "Miniapp disconnected",
+          })
+          break
+        }
+        void glassesSensorService.request(packageName, payload).then(
+          () => this.sendResult(packageName, requestId, true),
+          (error: unknown) =>
+            this.sendResult(packageName, requestId, false, undefined, {
+              code: (error as {code?: string}).code || MiniappErrorCode.INTERNAL,
+              message: error instanceof Error ? error.message : "Sensor control failed",
+            }),
+        )
+        break
       case MiniappRequestType.IMU_SET_ENABLED:
         this.handleImuSetEnabled(packageName, payload, requestId)
         break
@@ -1420,6 +1551,15 @@ class LocalMiniappRuntime {
       case MiniappRequestType.OPEN_URL:
         this.handleOpenUrl(packageName, payload)
         break
+      case MiniappRequestType.DISPLAY_DIAGNOSTICS: {
+        const enabled = useSettingsStore.getState().getSetting(SETTINGS.debug_console.key) === true
+        this.sendResult(packageName, requestId, true, {
+          enabled,
+          generatedAt: Date.now(),
+          records: enabled ? collectDisplayDiagnostics(logBuffer.getRecentLogs()) : [],
+        })
+        break
+      }
       case MiniappRequestType.COPY_CLIPBOARD:
         this.handleCopyClipboard(packageName, payload, requestId)
         break
@@ -1609,7 +1749,10 @@ class LocalMiniappRuntime {
     existing.lastPongAt = Date.now()
     existing.unansweredPingRounds = 0
 
-    const capabilities = this.currentCapabilities()
+    // A system_dashboard app may take the overlay slot: its capabilities
+    // carry the dashboard view from the start.
+    if (existing.installedManifest?.type === "system_dashboard") addOverlayApp(packageName)
+    const capabilities = this.capabilitiesFor(packageName)
 
     // Build the declared-permission record for the SDK's session.permissions
     // module. Lower-cased to match v3's PermissionType union (microphone,
@@ -1624,7 +1767,7 @@ class LocalMiniappRuntime {
     this.clearMiniappAuthDeliveryRetry(packageName)
     const authPromise = this.requestMiniappAuth(packageName)
     const initialAuth = await withTimeout(authPromise, 1_500)
-    const userId = initialAuth?.glasslyUserId ?? ""
+    const userId = initialAuth?.userId ?? ""
     if (initialAuth) {
       existing.authDelivered = true
       this.scheduleMiniappAuthRefresh(packageName, initialAuth)
@@ -1637,7 +1780,10 @@ class LocalMiniappRuntime {
         userId,
         packageName,
         capabilities,
+        preferences: this.currentPreferences(),
+        visibility: this.currentVisibility(),
         permissions: declaredPermissions,
+        ...(existing.launchSource ? {launchSource: existing.launchSource} : {}),
         ...(initialAuth ? {auth: initialAuth} : {}),
       },
       requestId,
@@ -1867,11 +2013,10 @@ class LocalMiniappRuntime {
 
   /**
    * CLAIM_GESTURES (session.input.setClaimedGestures): the app declares which
-   * touch gestures it handles itself, replacing its previous claim set.
-   * Claims suppress the host's default behavior for those gestures (today:
-   * double_tap → dashboard/head-up in DeviceEventRouter) but ONLY while the
-   * claiming app is the one in front of the user — see
-   * {@link foregroundClaimsGesture}. Cleared on app stop.
+   * touch gestures it handles itself, replacing its previous claim set. The
+   * most recent claimer of a gesture holds it and gets it alone; releasing
+   * hands it back to the previous claimer, and both hear the change on the
+   * gesture_claim stream. Cleared on app stop.
    */
   private handleClaimGestures(packageName: string, payload: Record<string, unknown>, requestId?: string): void {
     if (!this.connectedApps.has(packageName)) {
@@ -1880,19 +2025,39 @@ class LocalMiniappRuntime {
     }
     const raw = payload.gestures
     const gestures = Array.isArray(raw) ? raw.filter((g): g is string => typeof g === "string") : []
-    if (gestures.length === 0) this.gestureClaims.delete(packageName)
-    else this.gestureClaims.set(packageName, new Set(gestures))
+    if (payload.scope !== undefined && (typeof payload.scope !== "string" || payload.scope.length === 0)) {
+      this.sendResult(packageName, requestId, false, undefined, {
+        code: MiniappErrorCode.INVALID_ARGUMENT,
+        message: "Gesture claim scope must be a nonempty string",
+      })
+      return
+    }
+    this.applyGestureClaimChanges(
+      setGestureClaims(this.gestureClaims, packageName, gestures, payload.scope as string | undefined),
+    )
     this.sendResult(packageName, requestId, true)
   }
 
-  /** True iff the miniapp in front of the user has claimed `gesture`. */
-  public foregroundClaimsGesture(gesture: string): boolean {
-    return claimsGesture(
-      this.gestureClaims,
-      gesture,
-      localDisplayManager.getGestureOwner(),
-      useAppStatusStore.getState().foregroundedPackage,
-    )
+  private applyGestureClaimChanges(result: {state: GestureClaimState; changes: GestureClaimChange[]}): void {
+    this.gestureClaims = result.state
+    for (const change of result.changes) {
+      this.forwardEvent(
+        MiniappStreamType.GESTURE_CLAIM,
+        {gesture: change.gesture, held: change.held},
+        undefined,
+        change.packageName,
+      )
+    }
+  }
+
+  /** The app holding `gesture` (the most recent claimer), or null when it is unclaimed. */
+  public gestureClaimant(gesture: string): string | null {
+    return gestureClaimant(this.gestureClaims, gesture)
+  }
+
+  /** Has this app registered the gesture, even if a later claimant currently receives it? */
+  public hasGestureClaim(packageName: string, gesture: string): boolean {
+    return hasGestureClaim(this.gestureClaims, packageName, gesture)
   }
 
   private handleSubscribe(packageName: string, payload: Record<string, unknown>, requestId?: string): void {
@@ -1944,9 +2109,10 @@ class LocalMiniappRuntime {
     const declaredTypes = new Set((app.installedManifest?.permissions ?? []).map((p) => p.type?.toUpperCase()))
 
     const permissionForStream = (s: string): string | null => {
+      if (s === MiniappStreamType.MIRROR_UPDATE) return "DISPLAY_MIRROR"
       if (s === "audio_chunk" || s === "vad") return "MICROPHONE"
       if (s.startsWith("transcription") || s.startsWith("translation")) return "MICROPHONE"
-      if (s === "location_update") return "LOCATION"
+      if (s === "location_update" || s === "heading_update") return "LOCATION"
       if (s === "phone_notification") return "READ_NOTIFICATIONS"
       if (s === "phone_notification_dismissed") return "READ_NOTIFICATIONS"
       return null
@@ -1968,6 +2134,15 @@ class LocalMiniappRuntime {
       }
     }
 
+    // The settings stream carries the wearer's settings: system apps only.
+    if (streams.includes(MiniappStreamType.SETTINGS_CHANGED) && !this.isSystemPackage(packageName)) {
+      this.sendResult(packageName, requestId, false, undefined, {
+        code: MiniappErrorCode.NOT_PERMITTED,
+        message: "The settings stream is restricted to system apps",
+      })
+      return
+    }
+
     // Add new subscriptions
     const previousSubscriptions = app.subscriptions
     app.subscriptions = new Set(streams)
@@ -1978,11 +2153,16 @@ class LocalMiniappRuntime {
       [...cloudTranscriptionStreams].filter((stream) => app.subscriptions.has(stream)),
     )
     this.replaceStreamSubscribers(packageName, previousSubscriptions, app.subscriptions)
+    // An overlay app that listens to phone notifications presents them on the glasses.
+    if (isOverlayApp(packageName)) {
+      setOverlayViewer(packageName, app.subscriptions.has(MiniappStreamType.PHONE_NOTIFICATION))
+    }
 
     this.recomputeMicRequirements()
     this.updateCloudSubscriptions()
     this.recomputeHeadingSubscription()
     this.recomputeImuSubscription()
+    this.recomputeCompassSubscription()
     // Persist this app's requested rate (or clear it if SUBSCRIBE didn't
     // include `location_stream` this time), then ask the host for the
     // strictest rate across all connected apps.
@@ -2043,7 +2223,13 @@ class LocalMiniappRuntime {
     const isSimulated = (glassesState.deviceModel || "").toLowerCase().includes("simulated")
 
     for (const stream of streams) {
-      if (stream === "glasses_battery") {
+      if (stream === MiniappStreamType.MIRROR_UPDATE && this.hasMirrorPermission(packageName)) {
+        this.sendToMiniapp(packageName, {
+          type: MiniappResponseType.EVENT,
+          streamType: MiniappStreamType.MIRROR_UPDATE,
+          data: mirrorService.current(),
+        })
+      } else if (stream === "glasses_battery") {
         // Simulated glasses have no real battery; mirror the phone's battery
         // so miniapps see a sensible value during development.
         if (isSimulated) {
@@ -2089,6 +2275,15 @@ class LocalMiniappRuntime {
             timestamp: Date.now(),
           },
         })
+      } else if (stream === MiniappStreamType.SETTINGS_CHANGED) {
+        // Replay every bridged key so a mirror can be built from the stream alone.
+        for (const key of selectSettingsBridgeKeys(undefined)) {
+          this.sendToMiniapp(packageName, {
+            type: MiniappResponseType.EVENT,
+            streamType: MiniappStreamType.SETTINGS_CHANGED,
+            data: {key, value: this.settingsBridgeValue(key)},
+          })
+        }
       } else if (stream === "head_position") {
         // The glasses store has no headUp field (same on the pre-engine host
         // hook), so this stays a no-emit until head state lands in the store.
@@ -2191,6 +2386,16 @@ class LocalMiniappRuntime {
         })
         return
       }
+      // The dashboard view is the overlay apps' alone; anyone else's frame
+      // is dropped, reported rather than silently lost.
+      if (payload.view === "dashboard" && !isOverlayApp(packageName)) {
+        this.sendResult(packageName, requestId, true, {
+          status: "displayed",
+          presented: false,
+          reason: "not the dashboard app",
+        })
+        return
+      }
 
       localDisplayManager.request(
         packageName,
@@ -2210,6 +2415,174 @@ class LocalMiniappRuntime {
     }
   }
 
+  /**
+   * display.showView: the designated dashboard app takes or releases the
+   * overlay slot. Refused (NOT_PERMITTED) for any other app; "unsupported"
+   * while the glasses cannot show the dashboard view. Idempotent either way;
+   * the slot's state comes back to the app as a display_view change.
+   */
+  private handleShowView(packageName: string, payload: Record<string, unknown>, requestId?: string): void {
+    if (!this.connectedApps.has(packageName)) {
+      this.sendResult(packageName, requestId, true, {status: "unsupported", reason: "app stopped"})
+      return
+    }
+    const view = payload.view
+    if (view !== "main" && view !== "dashboard") {
+      this.sendResult(packageName, requestId, false, undefined, {
+        code: MiniappErrorCode.INVALID_ARGUMENT,
+        message: 'showView takes "main" or "dashboard"',
+      })
+      return
+    }
+    if (!isOverlayApp(packageName)) {
+      this.sendResult(packageName, requestId, false, undefined, {
+        code: MiniappErrorCode.NOT_PERMITTED,
+        message: "The dashboard view belongs to system_dashboard apps",
+      })
+      return
+    }
+    if (view === "main") {
+      overlayPages.hide(packageName)
+      this.sendResult(packageName, requestId, true, {status: "shown"})
+      return
+    }
+    if (!pagesEligible()) {
+      this.sendResult(packageName, requestId, true, {
+        status: "unsupported",
+        reason: "glasses cannot show the dashboard",
+      })
+      return
+    }
+    dashboardOpenTrace.showViewRequested(packageName)
+    const shown = overlayPages.show(packageName)
+    if (shown) dashboardOpenTrace.slotGranted()
+    this.sendResult(
+      packageName,
+      requestId,
+      true,
+      shown ? {status: "shown"} : {status: "unsupported", reason: "the overlay slot was refused"},
+    )
+  }
+
+  // ---------------------------------------------------------------------------
+  // Settings bridge (session.settings) — system apps only
+  // ---------------------------------------------------------------------------
+
+  private requireSystemForSettings(packageName: string, requestId: string | undefined): boolean {
+    if (this.isSystemPackage(packageName)) return true
+    this.sendResult(packageName, requestId, false, undefined, {
+      code: MiniappErrorCode.NOT_PERMITTED,
+      message: "The settings bridge is restricted to system apps",
+    })
+    return false
+  }
+
+  /** A bridged key's current value: the store's, or the engine's for a derived key. */
+  private settingsBridgeValue(key: string): unknown {
+    if (isDerivedSettingsKey(key)) return this.derivedSettingValue(key)
+    return useSettingsStore.getState().getSetting(key) ?? null
+  }
+
+  private derivedSettingValue(key: DerivedSettingsKey): unknown {
+    switch (key) {
+      case "phone_active":
+        return isPhoneActive()
+      case "foreground_app_on_screen":
+        return localDisplayManager.foregroundAppOnScreen()
+      case "ring_battery":
+        return ringBatteryFrom(useGlassesStore.getState())
+    }
+  }
+
+  private handleSettingsGet(packageName: string, payload: Record<string, unknown>, requestId?: string): void {
+    if (!this.requireSystemForSettings(packageName, requestId)) return
+    const values: Record<string, unknown> = {}
+    for (const key of selectSettingsBridgeKeys(payload.keys)) values[key] = this.settingsBridgeValue(key)
+    this.sendResult(packageName, requestId, true, {values})
+  }
+
+  private async handleSettingsSet(
+    packageName: string,
+    payload: Record<string, unknown>,
+    requestId?: string,
+  ): Promise<void> {
+    if (!this.requireSystemForSettings(packageName, requestId)) return
+    const validated = validateSettingsSet(payload)
+    if (!validated.ok) {
+      this.sendResult(packageName, requestId, false, undefined, {code: validated.code, message: validated.message})
+      return
+    }
+    // Through the store, so persistence, server sync and the Bluetooth sync
+    // of glasses settings behave as if a phone screen wrote it.
+    const result = await useSettingsStore.getState().setSetting(validated.key, validated.value)
+    if (result.is_error()) {
+      this.sendResult(packageName, requestId, false, undefined, {
+        code: MiniappErrorCode.INTERNAL,
+        message: result.error.message,
+      })
+      return
+    }
+    this.sendResult(packageName, requestId, true)
+  }
+
+  private async handleNotificationAppsList(packageName: string, requestId?: string): Promise<void> {
+    if (!this.requireSystemForSettings(packageName, requestId)) return
+    try {
+      this.sendResult(packageName, requestId, true, await installedNotificationApps())
+    } catch (err) {
+      this.sendResult(packageName, requestId, false, undefined, {
+        code: MiniappErrorCode.INTERNAL,
+        message: err instanceof Error ? err.message : "Failed to list notification apps",
+      })
+    }
+  }
+
+  /**
+   * Push bridged settings as they change: stored keys from the store, the
+   * derived keys whenever their inputs move (phone activity, the display,
+   * the apps store, the ring). Subscribers are system apps only (gated at
+   * SUBSCRIBE), so this is a no-op fan-out for everyone else.
+   */
+  private ensureSettingsBridgeWired(): void {
+    if (this.settingsBridgeWired) return
+    this.settingsBridgeWired = true
+    const storedKeys = Object.keys(SETTINGS_BRIDGE_KEYS)
+    const emit = (key: string, value: unknown) => this.forwardEvent(MiniappStreamType.SETTINGS_CHANGED, {key, value})
+    useSettingsStore.subscribe(
+      (s) => storedKeys.map((key) => JSON.stringify(s.getSetting(key) ?? null)),
+      (next, previous) => {
+        storedKeys.forEach((key, i) => {
+          if (next[i] !== previous[i]) emit(key, this.settingsBridgeValue(key))
+        })
+      },
+      {equalityFn: (a, b) => a.length === b.length && a.every((value, i) => value === b[i])},
+    )
+    const pushDerived = () => {
+      for (const key of DERIVED_SETTINGS_KEYS) {
+        const value = this.derivedSettingValue(key)
+        const encoded = JSON.stringify(value ?? null)
+        if (this.derivedSettings.get(key) === encoded) continue
+        this.derivedSettings.set(key, encoded)
+        emit(key, value)
+      }
+    }
+    for (const key of DERIVED_SETTINGS_KEYS) {
+      this.derivedSettings.set(key, JSON.stringify(this.derivedSettingValue(key) ?? null))
+    }
+    onPhoneActivityChange(pushDerived)
+    // App foreground/background drives VISIBILITY_CHANGE. Background execution
+    // limits (timer coalescing, BLE credit polling) follow the app's own
+    // foreground bit, not `isPhoneActive()` — which counts an unlocked phone as
+    // active even while the app is suspended behind it.
+    onAppForegroundChange((foregrounded) => this.broadcastVisibility(foregrounded))
+    localDisplayManager.onActiveDisplayChange(pushDerived)
+    useAppStatusStore.subscribe(pushDerived)
+    useGlassesStore.subscribe(
+      (s) => `${s.ringConnected}:${s.ringBatteryLevel}:${s.controllerConnected}:${s.controllerBatteryLevel}`,
+      pushDerived,
+    )
+  }
+
   /**
    * Native nav UI feed (display.sendNativeNav*). Gated on the device's nav
    * mode being active (trip-scoped); the miniapp's first pushes can race the
@@ -2223,6 +2596,7 @@ class LocalMiniappRuntime {
         return
       }
       const sent = nativeNavigationService.handleMiniappRequest(payload)
+      if (sent) mirrorService.invalidate("firmware-navigation")
       this.sendResult(packageName, requestId, true, {
         status: sent ? "sent" : "unsupported",
         ...(sent ? {} : {reason: "native navigation unavailable"}),
@@ -2252,6 +2626,7 @@ class LocalMiniappRuntime {
         this.sendResult(packageName, requestId, true, {status: "unsupported", reason: "no glasses connected"})
         return
       }
+      mirrorService.invalidate("firmware-dashboard")
       void Promise.resolve(BluetoothSdk.showDashboard()).catch((err) => {
         console.error(`${LOG_TAG}: showDashboard failed:`, err)
       })
@@ -2923,13 +3298,13 @@ class LocalMiniappRuntime {
   private readonly blobStore = new BlobStore({
     sendResult: (packageName, requestId, ok, result, error) =>
       this.sendResult(packageName, requestId, ok, result, error),
-    getUserId: () => cloudClientService.getGlasslyUserId(),
+    getUserId: () => cloudClientService.getUserId(),
   })
   private readonly blobRequestQueues = new Map<string, Promise<void>>()
 
   private readonly simpleStorage = new LocalMiniappStorage({
     backend: localMiniappStorageBackend,
-    getUserId: () => cloudClientService.resolveGlasslyUserId(),
+    getUserId: () => cloudClientService.resolveUserId(),
   })
 
   /**
@@ -2946,7 +3321,7 @@ class LocalMiniappRuntime {
     const previous = this.blobRequestQueues.get(packageName) ?? Promise.resolve()
     const queued = previous.then(async () => {
       try {
-        await cloudClientService.resolveGlasslyUserId()
+        await cloudClientService.resolveUserId()
       } catch (err) {
         console.error(`${LOG_TAG}: blob identity error:`, err)
         this.sendResult(packageName, requestId, false, undefined, {
@@ -2988,7 +3363,7 @@ class LocalMiniappRuntime {
   }
 
   /**
-   * Heading is a sensor stream — start the native compass when any mini
+   * Phone heading is a sensor stream — start the phone compass when any mini
    * app is subscribed to "heading_update", stop it when none are.
    */
   private headingUnsub: (() => void) | null = null
@@ -3019,6 +3394,18 @@ class LocalMiniappRuntime {
     void BluetoothSdk.setImuEnabled(wantsImu)
   }
 
+  /**
+   * Glasses compass is demand-driven: GlassesSensorService runs it while any
+   * miniapp is subscribed to "glasses_compass" (custom firmware), serving the
+   * tightest sampling any subscriber asked for via session.compass.start().
+   */
+  private recomputeCompassSubscription(): void {
+    const subscribers = this.streamSubscribers.get(MiniappStreamType.GLASSES_COMPASS) ?? new Set<string>()
+    void glassesSensorService.setCompassSubscribers(subscribers).catch((error) => {
+      console.warn(`${LOG_TAG}: compass subscription update failed`, error)
+    })
+  }
+
   /**
    * Last rate we asked the host for. Lets us skip the cross-process call
    * when nothing actually changed (most SUBSCRIBE / unregister churn
@@ -3767,7 +4154,7 @@ class LocalMiniappRuntime {
         })
       }
 
-      await new Promise((resolve) => setTimeout(resolve, GENERATE_JOB_POLL_MS))
+      await new Promise<void>((resolve) => BgTimer.setTimeout(resolve, GENERATE_JOB_POLL_MS))
     }
   }
 
@@ -3935,11 +4322,7 @@ class LocalMiniappRuntime {
    * session.system.scanQr — host camera overlay. Must not clear miniapp
    * foreground; the host seam is responsible for presenting a Modal on top.
    */
-  private async handleScanQr(
-    packageName: string,
-    payload: Record<string, unknown>,
-    requestId?: string,
-  ): Promise<void> {
+  private async handleScanQr(packageName: string, payload: Record<string, unknown>, requestId?: string): Promise<void> {
     try {
       const result = await invokeScanQrSeam(getUiSeams().scanQr, payload)
       this.sendResult(packageName, requestId, true, result)
@@ -4403,6 +4786,10 @@ class LocalMiniappRuntime {
       }
     }
 
+    if (streams.includes(MiniappStreamType.MIRROR_UPDATE) && !this.hasMirrorPermission(packageName)) {
+      return {ok: false, error: "DISPLAY_MIRROR permission not declared"}
+    }
+
     // Add new subscriptions
     const previousSubscriptions = app.subscriptions
     app.subscriptions = new Set(streams)
@@ -4799,12 +5186,55 @@ class LocalMiniappRuntime {
   private ensureCapabilitiesWired(): void {
     if (this.capabilitiesWired) return
     this.capabilitiesWired = true
+    const broadcast = () => this.broadcastCapabilities()
+    // Connection, model and firmware also decide the dashboard view's eligibility.
     useGlassesStore.subscribe(
-      (s) => `${s.sceneCanvasWidth ?? 0}x${s.sceneCanvasHeight ?? 0}`,
+      (s) =>
+        `${s.sceneCanvasWidth ?? 0}x${s.sceneCanvasHeight ?? 0}:${s.sceneVector === true}:${s.firmwareVersion}:${s.connection.state}:${s.deviceModel}`,
+      broadcast,
+    )
+    // The debug knob flips hasNativeNavigation on custom firmware.
+    useSettingsStore.subscribe((s) => s.getSetting(SETTINGS.cfw_native_navigation.key), broadcast)
+    // The dashboard master switch flips the dashboard view.
+    useSettingsStore.subscribe((s) => s.getSetting(SETTINGS.custom_dashboard_enabled.key), broadcast)
+  }
+
+  /** Capabilities as `packageName` sees them: the model profile plus the views this app may draw. */
+  private capabilitiesFor(packageName: string): Capabilities {
+    const capabilities = this.currentCapabilities()
+    if (!capabilities.display) return capabilities
+    const views = displayViewsFor(packageName, pagesEligible())
+    return {...capabilities, display: {...capabilities.display, views}}
+  }
+
+  private broadcastCapabilities(): void {
+    for (const packageName of this.handshookApps) {
+      this.sendToMiniapp(packageName, {
+        type: MiniappResponseType.CAPABILITIES_UPDATE,
+        capabilities: this.capabilitiesFor(packageName),
+      })
+    }
+  }
+
+  /** Host user preferences miniapps follow by default (Settings > Appearance). */
+  private currentPreferences(): MiniappPreferences {
+    const settings = useSettingsStore.getState()
+    return {
+      unitSystem: settings.getSetting(SETTINGS.metric_system.key) === true ? "metric" : "imperial",
+      twelveHourTime: settings.getSetting(SETTINGS.twelve_hour_time.key) === true,
+    }
+  }
+
+  private ensurePreferencesWired(): void {
+    if (this.preferencesWired) return
+    this.preferencesWired = true
+    useSettingsStore.subscribe(
+      (s) =>
+        `${s.getSetting(SETTINGS.metric_system.key) === true}:${s.getSetting(SETTINGS.twelve_hour_time.key) === true}`,
       () => {
-        const capabilities = this.currentCapabilities()
+        const preferences = this.currentPreferences()
         for (const packageName of this.handshookApps) {
-          this.sendToMiniapp(packageName, {type: MiniappResponseType.CAPABILITIES_UPDATE, capabilities})
+          this.sendToMiniapp(packageName, {type: MiniappResponseType.PREFERENCES_UPDATE, preferences})
         }
       },
     )
@@ -4850,7 +5280,13 @@ class LocalMiniappRuntime {
    * - Cloud sends "head_up" → miniapp protocol uses "head_position" (HEAD_POSITION)
    * - Cloud sends "VAD" (uppercase) → miniapp protocol uses "vad" (lowercase)
    */
-  public forwardEvent(streamType: string, data: unknown, transcriptionSource?: TranscriptionEventSource): void {
+  public forwardEvent(
+    streamType: string,
+    data: unknown,
+    transcriptionSource?: TranscriptionEventSource,
+    /** Deliver to this subscriber alone (the designated dashboard app's gestures while it shows). */
+    only?: string,
+  ): void {
     // Local sherpa results enter the runtime only through here (DeviceEventRouter's
     // local_transcription listener); cloud/direct are marked at their onTranscript
     // wiring, which never passes "local".
@@ -4958,6 +5394,7 @@ class LocalMiniappRuntime {
     if (matchedSubs.size === 0 && !perGestureStream) return
 
     for (const packageName of matchedSubs) {
+      if (only !== undefined && packageName !== only) continue
       let transcriptionRoute: "default" | "forceLocal" | "all" | undefined
       if (normalizedStream.startsWith("transcription:") && transcriptionSource) {
         const routes = this.appTranscriptionRoutesForEvent(packageName, normalizedStream)
@@ -4996,6 +5433,7 @@ class LocalMiniappRuntime {
       const gestureSubs = this.streamSubscribers.get(perGestureStream)
       if (gestureSubs) {
         for (const packageName of gestureSubs) {
+          if (only !== undefined && packageName !== only) continue
           this.sendToMiniapp(packageName, {
             type: MiniappResponseType.EVENT,
             streamType: perGestureStream,
@@ -5260,6 +5698,7 @@ class LocalMiniappRuntime {
       name: app.name,
       version: app.version ?? "",
       running: app.running,
+      hidden: app.hidden === true,
       compatibility,
       actions: app.actions ?? [],
     }
@@ -5636,6 +6075,24 @@ class LocalMiniappRuntime {
     })
   }
 
+  /**
+   * Push the app's foreground state to every connected miniapp. Miniapps that
+   * pace their own work (streaming a scene, polling a sensor) need to know when
+   * the host process is backgrounded, because that is when iOS coalesces their
+   * timers and the BLE writer falls back to credit polling.
+   */
+  private broadcastVisibility(foregrounded: boolean): void {
+    const visibility = foregrounded ? "foreground" : "background"
+    for (const packageName of this.connectedApps.keys()) {
+      this.sendVisibilityChange(packageName, visibility)
+    }
+  }
+
+  /** Foreground state a miniapp is given at CONNECT_ACK, before any transition fires. */
+  public currentVisibility(): "foreground" | "background" {
+    return isAppForegrounded() ? "foreground" : "background"
+  }
+
   /**
    * Fast foreground liveness check used when a local miniapp UI is opened or
    * resumed. The normal watchdog intentionally waits ~30s to avoid killing a