@glassly/engine 0.1.0-dev.99 → 0.2.9-beta.448

package/build/services/LocalMiniappRuntime.js

@@ -8,7 +8,10 @@
  * This runtime handles request dispatch, stream fan-out, and lifecycle
  * 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";
@@ -33,9 +36,17 @@ import { createAnthropicProvider, createGeminiProvider, createOpenAiProvider, }
 import { normalizeAiTier, resolveAiTier } from "./AiTierResolution";
 import { HttpError } from "@glassly/cloud-client";
 import localDisplayManager from "./LocalDisplayManager";
-import { claimsGesture } from "./gestureClaims";
+import { dropGestureClaims, emptyGestureClaims, gestureClaimant, hasGestureClaim, setGestureClaims, } 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, } from "./settingsBridge";
+import { addOverlayApp, displayViewsFor, isOverlayApp, removeOverlayApp, setOverlayViewer } from "./pages/overlayApps";
+import { pagesEligible } from "./pages/pageEligibility";
 import nativeNavigationService from "./NativeNavigationService";
 import headingService from "./HeadingService";
+import glassesSensorService from "./GlassesSensorService";
 import localSttFallbackCoordinator from "./LocalSttFallbackCoordinator";
 import speakerLabelResolver from "./SpeakerLabelResolver";
 import micStateCoordinator from "./MicStateCoordinator";
@@ -117,9 +128,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
@@ -194,6 +208,7 @@ const PERMISSION_TYPE_TO_CANONICAL = {
     LOCATION: "location",
     BACKGROUND_LOCATION: "location",
     READ_NOTIFICATIONS: "notifications",
+    DISPLAY_MIRROR: "displayMirror",
     POST_NOTIFICATIONS: "notifications",
     CALENDAR: "calendar",
     API_KEYS: "apiKeys",
@@ -298,6 +313,7 @@ const ALL_CANONICAL_PERMISSIONS = [
     "memory",
     "ai",
     "speakers",
+    "displayMirror",
 ];
 /**
  * Build the {location, microphone, camera, notifications, calendar, apiKeys}
@@ -400,8 +416,8 @@ class LocalMiniappRuntime {
     llmQuotaBlocked = false;
     /** Connected miniapps keyed by packageName. */
     connectedApps = new Map();
-    /** Per-app claimed gestures (CLAIM_GESTURES) — see foregroundClaimsGesture. */
-    gestureClaims = new Map();
+    /** Claimed gestures (CLAIM_GESTURES): a stack per gesture, the most recent claimer holding it. */
+    gestureClaims = emptyGestureClaims();
     /**
      * Packages that have completed their CONNECT handshake (sent
      * `miniapp_connect`, got `CONNECT_ACK`). Distinct from `connectedApps`,
@@ -419,6 +435,10 @@ class LocalMiniappRuntime {
     cloudResultsWired = false;
     cloudStatusWired = false;
     capabilitiesWired = false;
+    preferencesWired = false;
+    settingsBridgeWired = false;
+    /** Last derived read-only values pushed on the settings stream, for change detection. */
+    derivedSettings = new Map();
     cloudAudioSubscriptionSync = new CloudAudioSubscriptionSync();
     /**
      * Per-miniapp language hints from TRANSCRIPTION_CONFIG (issue 021 WP3).
@@ -529,6 +549,23 @@ 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();
     }
     /** Mirror the live transcription/translation subscriber sets into the debug store. */
@@ -639,6 +676,11 @@ class LocalMiniappRuntime {
         }
         return LocalMiniappRuntime.instance;
     }
+    mirrorUnsubscribe = null;
+    hasMirrorPermission(packageName) {
+        return (this.connectedApps.get(packageName)?.installedManifest?.permissions?.some((p) => p.type === "DISPLAY_MIRROR") ===
+            true);
+    }
     initialized = false;
     /**
      * Initialize the runtime. Called from MantleManager.init().
@@ -650,6 +692,16 @@ 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,
+            }),
+        });
     }
     /**
      * Handle an incoming cloud message relayed from the v2 cloud session
@@ -729,7 +781,7 @@ class LocalMiniappRuntime {
     // ===========================================================================
     // App registration
     // ===========================================================================
-    registerApp(packageName, sendFn, installedManifest) {
+    registerApp(packageName, sendFn, installedManifest, launchSource) {
         console.log(`${LOG_TAG}: registerApp(${packageName})`);
         this.clearForegroundProbe(packageName);
         // Fresh spawn → fresh handshake. Clear any prior handshake flag so
@@ -740,6 +792,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
@@ -778,6 +833,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.
@@ -785,6 +841,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
         // bounded boot window, mirroring the cloud DisplayManager boot screen. The
@@ -810,14 +868,14 @@ class LocalMiniappRuntime {
                 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);
@@ -887,7 +945,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((resolve) => setTimeout(resolve, 50));
+        await new Promise((resolve) => BgTimer.setTimeout(resolve, 50));
         this.unregisterApp(packageName);
     }
     unregisterApp(packageName, opts) {
@@ -904,6 +962,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.
         // Keep camera teardown ordered: restoring FOV can restart the HAL, so the warm-up lease must
@@ -962,11 +1028,15 @@ class LocalMiniappRuntime {
         else {
             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
         // `connectedApps.delete` below so it doesn't matter that the iter
@@ -984,7 +1054,6 @@ class LocalMiniappRuntime {
         // current on-glasses frame, this clears the glasses (or restores the
         // core app's saved frame).
         localDisplayManager.onUnmount(packageName);
-        this.gestureClaims.delete(packageName);
         this.connectedApps.delete(packageName);
         this.recomputeMicRequirements();
         if (releasedMicGateOverride) {
@@ -1061,9 +1130,32 @@ 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;
@@ -1195,6 +1287,19 @@ 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) => this.sendResult(packageName, requestId, false, undefined, {
+                    code: error.code || MiniappErrorCode.INTERNAL,
+                    message: error instanceof Error ? error.message : "Sensor control failed",
+                }));
+                break;
             case MiniappRequestType.IMU_SET_ENABLED:
                 this.handleImuSetEnabled(packageName, payload, requestId);
                 break;
@@ -1219,6 +1324,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;
@@ -1365,7 +1479,11 @@ class LocalMiniappRuntime {
         // Update lastPongAt so it doesn't time out right away
         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,
         // camera, location, notifications, calendar). Missing permissions default
@@ -1379,7 +1497,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);
@@ -1389,7 +1507,10 @@ class LocalMiniappRuntime {
             userId,
             packageName,
             capabilities,
+            preferences: this.currentPreferences(),
+            visibility: this.currentVisibility(),
             permissions: declaredPermissions,
+            ...(existing.launchSource ? { launchSource: existing.launchSource } : {}),
             ...(initialAuth ? { auth: initialAuth } : {}),
         }, requestId);
         if (!initialAuth) {
@@ -1606,11 +1727,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.
      */
     handleClaimGestures(packageName, payload, requestId) {
         if (!this.connectedApps.has(packageName)) {
@@ -1619,15 +1739,29 @@ class LocalMiniappRuntime {
         }
         const raw = payload.gestures;
         const gestures = Array.isArray(raw) ? raw.filter((g) => 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));
         this.sendResult(packageName, requestId, true);
     }
-    /** True iff the miniapp in front of the user has claimed `gesture`. */
-    foregroundClaimsGesture(gesture) {
-        return claimsGesture(this.gestureClaims, gesture, localDisplayManager.getGestureOwner(), useAppStatusStore.getState().foregroundedPackage);
+    applyGestureClaimChanges(result) {
+        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. */
+    gestureClaimant(gesture) {
+        return gestureClaimant(this.gestureClaims, gesture);
+    }
+    /** Has this app registered the gesture, even if a later claimant currently receives it? */
+    hasGestureClaim(packageName, gesture) {
+        return hasGestureClaim(this.gestureClaims, packageName, gesture);
     }
     handleSubscribe(packageName, payload, requestId) {
         const app = this.connectedApps.get(packageName);
@@ -1674,11 +1808,13 @@ class LocalMiniappRuntime {
         // the whole subscribe with PERMISSION_NOT_DECLARED.
         const declaredTypes = new Set((app.installedManifest?.permissions ?? []).map((p) => p.type?.toUpperCase()));
         const permissionForStream = (s) => {
+            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")
+            if (s === "location_update" || s === "heading_update")
                 return "LOCATION";
             if (s === "phone_notification")
                 return "READ_NOTIFICATIONS";
@@ -1701,16 +1837,29 @@ class LocalMiniappRuntime {
                 return;
             }
         }
+        // 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);
         app.forceLocalTranscriptionStreams = new Set([...forceLocalTranscriptionStreams].filter((stream) => app.subscriptions.has(stream)));
         app.cloudTranscriptionStreams = new Set([...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.
@@ -1761,7 +1910,14 @@ 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) {
@@ -1812,6 +1968,16 @@ class LocalMiniappRuntime {
                     },
                 });
             }
+            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.
@@ -1908,6 +2074,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, {
                 view: payload.view ?? "main",
                 scene: payload.elements,
@@ -1922,6 +2098,160 @@ 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.
+     */
+    handleShowView(packageName, payload, requestId) {
+        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
+    // ---------------------------------------------------------------------------
+    requireSystemForSettings(packageName, requestId) {
+        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. */
+    settingsBridgeValue(key) {
+        if (isDerivedSettingsKey(key))
+            return this.derivedSettingValue(key);
+        return useSettingsStore.getState().getSetting(key) ?? null;
+    }
+    derivedSettingValue(key) {
+        switch (key) {
+            case "phone_active":
+                return isPhoneActive();
+            case "foreground_app_on_screen":
+                return localDisplayManager.foregroundAppOnScreen();
+            case "ring_battery":
+                return ringBatteryFrom(useGlassesStore.getState());
+        }
+    }
+    handleSettingsGet(packageName, payload, requestId) {
+        if (!this.requireSystemForSettings(packageName, requestId))
+            return;
+        const values = {};
+        for (const key of selectSettingsBridgeKeys(payload.keys))
+            values[key] = this.settingsBridgeValue(key);
+        this.sendResult(packageName, requestId, true, { values });
+    }
+    async handleSettingsSet(packageName, payload, requestId) {
+        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);
+    }
+    async handleNotificationAppsList(packageName, requestId) {
+        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.
+     */
+    ensureSettingsBridgeWired() {
+        if (this.settingsBridgeWired)
+            return;
+        this.settingsBridgeWired = true;
+        const storedKeys = Object.keys(SETTINGS_BRIDGE_KEYS);
+        const emit = (key, value) => 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
@@ -1935,6 +2265,8 @@ 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" }),
@@ -1964,6 +2296,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);
             });
@@ -2541,12 +2874,12 @@ class LocalMiniappRuntime {
      */
     blobStore = new BlobStore({
         sendResult: (packageName, requestId, ok, result, error) => this.sendResult(packageName, requestId, ok, result, error),
-        getUserId: () => cloudClientService.getGlasslyUserId(),
+        getUserId: () => cloudClientService.getUserId(),
     });
     blobRequestQueues = new Map();
     simpleStorage = new LocalMiniappStorage({
         backend: localMiniappStorageBackend,
-        getUserId: () => cloudClientService.resolveGlasslyUserId(),
+        getUserId: () => cloudClientService.resolveUserId(),
     });
     /**
      * BlobStore's file helpers are synchronous once a user namespace is selected,
@@ -2558,7 +2891,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);
@@ -2600,7 +2933,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.
      */
     headingUnsub = null;
@@ -2631,6 +2964,17 @@ class LocalMiniappRuntime {
         this.imuEnabled = wantsImu;
         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().
+     */
+    recomputeCompassSubscription() {
+        const subscribers = this.streamSubscribers.get(MiniappStreamType.GLASSES_COMPASS) ?? new Set();
+        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
@@ -3298,7 +3642,7 @@ class LocalMiniappRuntime {
                     data: { progressToken, activity: status.activity, timestamp: Date.now() },
                 });
             }
-            await new Promise((resolve) => setTimeout(resolve, GENERATE_JOB_POLL_MS));
+            await new Promise((resolve) => BgTimer.setTimeout(resolve, GENERATE_JOB_POLL_MS));
         }
     }
     // ---------------------------------------------------------------------------
@@ -3847,6 +4191,9 @@ class LocalMiniappRuntime {
                 return { ok: false, error: "MICROPHONE permission not declared in miniapp.json" };
             }
         }
+        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);
@@ -4209,10 +4556,46 @@ class LocalMiniappRuntime {
         if (this.capabilitiesWired)
             return;
         this.capabilitiesWired = true;
-        useGlassesStore.subscribe((s) => `${s.sceneCanvasWidth ?? 0}x${s.sceneCanvasHeight ?? 0}`, () => {
-            const capabilities = this.currentCapabilities();
+        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.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. */
+    capabilitiesFor(packageName) {
+        const capabilities = this.currentCapabilities();
+        if (!capabilities.display)
+            return capabilities;
+        const views = displayViewsFor(packageName, pagesEligible());
+        return { ...capabilities, display: { ...capabilities.display, views } };
+    }
+    broadcastCapabilities() {
+        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). */
+    currentPreferences() {
+        const settings = useSettingsStore.getState();
+        return {
+            unitSystem: settings.getSetting(SETTINGS.metric_system.key) === true ? "metric" : "imperial",
+            twelveHourTime: settings.getSetting(SETTINGS.twelve_hour_time.key) === true,
+        };
+    }
+    ensurePreferencesWired() {
+        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 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 });
             }
         });
     }
@@ -4251,7 +4634,9 @@ class LocalMiniappRuntime {
      * - Cloud sends "head_up" → miniapp protocol uses "head_position" (HEAD_POSITION)
      * - Cloud sends "VAD" (uppercase) → miniapp protocol uses "vad" (lowercase)
      */
-    forwardEvent(streamType, data, transcriptionSource) {
+    forwardEvent(streamType, data, transcriptionSource, 
+    /** Deliver to this subscriber alone (the designated dashboard app's gestures while it shows). */
+    only) {
         // 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".
@@ -4364,6 +4749,8 @@ class LocalMiniappRuntime {
         if (matchedSubs.size === 0 && !perGestureStream)
             return;
         for (const packageName of matchedSubs) {
+            if (only !== undefined && packageName !== only)
+                continue;
             let transcriptionRoute;
             if (normalizedStream.startsWith("transcription:") && transcriptionSource) {
                 const routes = this.appTranscriptionRoutesForEvent(packageName, normalizedStream);
@@ -4398,6 +4785,8 @@ 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,
@@ -4624,6 +5013,7 @@ class LocalMiniappRuntime {
             name: app.name,
             version: app.version ?? "",
             running: app.running,
+            hidden: app.hidden === true,
             compatibility,
             actions: app.actions ?? [],
         };
@@ -4970,6 +5360,22 @@ class LocalMiniappRuntime {
             visibility,
         });
     }
+    /**
+     * 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.
+     */
+    broadcastVisibility(foregrounded) {
+        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. */
+    currentVisibility() {
+        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