@mentra/engine 0.1.0-beta.0

package/build/services/LocalMiniappRuntime.js

@@ -0,0 +1,3695 @@
+/**
+ * LocalMiniappRuntime
+ *
+ * Singleton service that bridges local miniapps (running in WebViews) with
+ * phone capabilities: display, audio, storage, sensors, LED, etc.
+ *
+ * Each miniapp communicates via the @mentra/miniapp envelope protocol.
+ * This runtime handles request dispatch, stream fan-out, and lifecycle
+ * management (connect/disconnect/ping).
+ */
+import { Linking } from "react-native";
+import Share from "react-native-share";
+import * as Battery from "expo-battery";
+import * as Clipboard from "expo-clipboard";
+import { File, Paths } from "expo-file-system";
+import * as Location from "expo-location";
+import BluetoothSdk from "@mentra/bluetooth-sdk";
+import { MiniappErrorCode, MiniappRequestType, MiniappResponseType, MiniappStreamType, CLOUD_STATUS_STREAM, parseEnvelope, serializeEnvelope, } from "@mentra/miniapp";
+import { DeviceTypes, getModelCapabilities } from "../types";
+import { storage as mmkvStorage } from "../utils/storage/storage";
+import { BgTimer } from "../utils/timers";
+import devServerBridge from "./DevServerBridge";
+import { islandNotifications } from "./NotificationsEmitter";
+import { isGlassesConnected } from "./GlassesReadiness";
+import audioPlaybackService from "./AudioPlaybackService";
+import { phoneLocationService } from "./PhoneLocationService";
+import { useGlassesStore } from "../stores/glasses";
+import { useSettingsStore } from "../stores/settings";
+import localDisplayManager from "./LocalDisplayManager";
+import headingService from "./HeadingService";
+import localSttFallbackCoordinator from "./LocalSttFallbackCoordinator";
+import micStateCoordinator from "./MicStateCoordinator";
+import { BlobStore } from "./BlobStore";
+import { CloudAudioSubscriptionSync } from "./CloudAudioSubscriptionSync";
+import { phoneCameraFovCoordinator } from "./PhoneCameraFovCoordinator";
+import { phonePhotoCoordinator } from "./PhonePhotoCoordinator";
+import { phoneStreamCoordinator } from "./PhoneStreamCoordinator";
+import { phoneVideoCoordinator } from "./PhoneVideoCoordinator";
+import { runSentenceTtsPipeline } from "./SentenceTtsPipeline";
+import { summarizeTranscriptionRoutes, transcriptionDeliveryRoute } from "./TranscriptionRouting";
+import { cloudClientService } from "./CloudClientService";
+import { miniappLauncher } from "./MiniappLauncher";
+import { ISLAND_SETTINGS_KEYS, } from "../runtime/config";
+import { getAnalytics, getUiSeams } from "../runtime/bootstrap";
+import { normalizeStreamAudioConfig, normalizeStreamVideoConfig } from "../runtime/streamConfig";
+import ttsModelManager from "./TTSModelManager";
+import { NavigationHandlers } from "./NavigationHandlers";
+import { useAppStatusStore } from "../stores/apps";
+import { getDevAppAttestation, getDevAppSourcePackage } from "./AppRegistry";
+import { listPhoneCalendarEvents, PhoneCalendarError } from "./PhoneCalendarService";
+/**
+ * Strictness ordering for `location_stream` rate values. Higher index =
+ * higher accuracy and higher power cost. The aggregate tier applied to
+ * the OS is the max of every connected miniapp's requested rate;
+ * miniapps that didn't ask for `location_stream` contribute nothing.
+ *
+ * If a miniapp passes a value we don't recognize, we treat it like the
+ * weakest known rate ("passive") rather than blanket-overwriting an
+ * active stronger request from another app.
+ */
+const LOCATION_RATE_PRIORITY = ["off", "passive", "low", "high", "realtime"];
+function locationRateRank(rate) {
+    if (!rate)
+        return -1;
+    const i = LOCATION_RATE_PRIORITY.indexOf(rate);
+    return i >= 0 ? i : LOCATION_RATE_PRIORITY.indexOf("passive");
+}
+function withTimeout(promise, timeoutMs) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const done = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            BgTimer.clearTimeout(timer);
+            resolve(value);
+        };
+        const timer = BgTimer.setTimeout(() => done(null), timeoutMs);
+        promise.then((value) => done(value), () => done(null));
+    });
+}
+const LOG_TAG = "LOCAL_MINIAPP";
+const SYSTEM_MINIAPP_PACKAGES = new Set([
+    "com.mentra.camera",
+    "com.mentra.gallery",
+    "com.mentra.settings",
+    "com.mentra.simulated",
+    "com.mentra.mirror",
+    "com.mentra.ai",
+    "cloud.augmentos.notify",
+    "com.mentra.feedback",
+    "com.mentra.miniappdev",
+]);
+const PING_INTERVAL_MS = 5_000;
+const MINIAPP_AUTH_REFRESH_HEADROOM_MS = 5 * 60 * 1000;
+const MINIAPP_AUTH_REFRESH_MIN_DELAY_MS = 5_000;
+// Backoff bounds for re-minting the INITIAL miniapp token after a failed mint
+// (e.g. the cloud client had not finished its first-boot Core token exchange
+// when the miniapp connected). Exponential from base, capped, so a transient
+// not-yet-connected client self-heals within seconds instead of needing a full
+// manual Cloud V2 reconnect.
+const MINIAPP_AUTH_RETRY_BASE_MS = 1_000;
+const MINIAPP_AUTH_RETRY_MAX_MS = 15_000;
+const FOREGROUND_LIVENESS_PROBE_TIMEOUT_MS = 2_500;
+const REQUEST_WIFI_SETUP_TYPE = "miniapp_request_wifi_setup";
+// Unregister after this many missed pongs. Generous on purpose: a busy
+// context (heavy interim translation traffic) or OS scheduling while idle can
+// delay pongs well past one interval, and killing a healthy-but-busy script
+// drops its subscriptions (releasing the mic). With the liveness-timeout
+// respawn path wired (MentraJSRouter.start), a genuinely dead context still
+// comes back automatically — this threshold only bounds how long that takes.
+const PING_TIMEOUT_THRESHOLD = 6; // ~30s
+const TRANSCRIPT_TIMING_TELEMETRY = globalThis.__DEV__ === true;
+const RGB_LED_ACTIONS = new Set(["on", "off"]);
+const RGB_LED_COLORS = new Set(["red", "green", "blue", "orange", "white"]);
+const CAMERA_FOV_MIN = 62;
+const CAMERA_FOV_MAX = 118;
+const CAMERA_FOV_DEFAULT = 102;
+const CAMERA_FOV_PRESETS = { narrow: 82, standard: CAMERA_FOV_DEFAULT, wide: 118 };
+const CAMERA_ROI_POSITION_BY_NAME = { center: "center", bottom: "bottom", top: "top" };
+// =============================================================================
+// Declared-permission record helper (for CONNECT_ACK / PERMISSIONS_UPDATE)
+// =============================================================================
+/**
+ * Map from manifest permission types (uppercase, snake-y) to the lowercase
+ * canonical permission keys the SDK exposes via session.permissions. Mirrors
+ * cloud SDK v3's PermissionType union.
+ *
+ * BACKGROUND_LOCATION + POST_NOTIFICATIONS aren't in v3's surface; they map
+ * onto the same canonical keys (location / notifications) since the SDK's
+ * `has()` is "do I have *any* form of this permission declared".
+ */
+const PERMISSION_TYPE_TO_CANONICAL = {
+    MICROPHONE: "microphone",
+    CAMERA: "camera",
+    LOCATION: "location",
+    BACKGROUND_LOCATION: "location",
+    READ_NOTIFICATIONS: "notifications",
+    POST_NOTIFICATIONS: "notifications",
+    CALENDAR: "calendar",
+};
+function normalizeRgbLedAction(value) {
+    return typeof value === "string" && RGB_LED_ACTIONS.has(value) ? value : "off";
+}
+function normalizeRgbLedColor(value) {
+    return typeof value === "string" && RGB_LED_COLORS.has(value) ? value : null;
+}
+function normalizeCameraFovPayload(payload) {
+    if (typeof payload.preset === "string") {
+        const preset = payload.preset in CAMERA_FOV_PRESETS ? payload.preset : "standard";
+        return { preset };
+    }
+    const rawFov = typeof payload.fov === "number" && Number.isFinite(payload.fov) ? payload.fov : CAMERA_FOV_DEFAULT;
+    return {
+        fov: Math.min(CAMERA_FOV_MAX, Math.max(CAMERA_FOV_MIN, rawFov)),
+        roiPosition: normalizeCameraRoiPosition(payload.roiPosition ?? payload.roi_position),
+    };
+}
+function normalizeCameraRoiPosition(value) {
+    if (typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 2) {
+        return value === 1 ? "bottom" : value === 2 ? "top" : "center";
+    }
+    if (typeof value === "string") {
+        return CAMERA_ROI_POSITION_BY_NAME[value] ?? "center";
+    }
+    return "center";
+}
+const ALL_CANONICAL_PERMISSIONS = ["location", "microphone", "camera", "notifications", "calendar"];
+/**
+ * Build the {location, microphone, camera, notifications, calendar} record the
+ * SDK's session.permissions module reads from. Missing types are false.
+ */
+function computeDeclaredPermissionRecord(manifest) {
+    const record = {};
+    for (const k of ALL_CANONICAL_PERMISSIONS)
+        record[k] = false;
+    for (const perm of manifest?.permissions ?? []) {
+        const canonical = PERMISSION_TYPE_TO_CANONICAL[perm.type?.toUpperCase()];
+        if (canonical)
+            record[canonical] = true;
+    }
+    return record;
+}
+// =============================================================================
+// PERMISSION_NOT_DECLARED warnings — per-session dedup
+// =============================================================================
+//
+// When a miniapp tries to subscribe / call something whose required permission
+// isn't declared in miniapp.json, the runtime rejects with
+// PERMISSION_NOT_DECLARED. The error reaches the SDK but most authors don't
+// subscribe to session.on("error", ...), so it's silent in practice.
+//
+// To make the failure discoverable for developers running the MentraOS app
+// from source, log a clear, copy-pasteable message in the phone console that
+// names the offending permission, the offending stream/op, and the JSON
+// snippet to add to miniapp.json. Once-per-session per (packageName, permission)
+// to avoid spam from a tight retry loop.
+//
+// Production users running the App Store build of MentraOS won't see these
+// (they don't watch Metro/adb logcat). For them, the WebView console bridge
+// (#5 of the quick-fixes round) ships the structured error to the miniapp
+// itself, and the miniapp's own console.warn flows to the dev terminal.
+const warnedPermission = new Set(); // key: `${packageName}::${permission}`
+function logPermissionNotDeclared(packageName, permission, context, manifestSnippet) {
+    const key = `${packageName}::${permission}`;
+    if (warnedPermission.has(key))
+        return;
+    warnedPermission.add(key);
+    console.warn(`${LOG_TAG}: ${packageName} attempted ${context}, but permission ${permission} is not declared in miniapp.json.\n` +
+        `Add this to the "permissions" array:\n  ${manifestSnippet}`);
+}
+/** Reset the per-session dedup; called when a miniapp unregisters so a fresh launch warns again. */
+function resetPermissionWarnings(packageName) {
+    for (const key of warnedPermission) {
+        if (key.startsWith(`${packageName}::`))
+            warnedPermission.delete(key);
+    }
+}
+// =============================================================================
+// LocalMiniappRuntime
+// =============================================================================
+class LocalMiniappRuntime {
+    static instance = null;
+    /** Connected miniapps keyed by packageName. */
+    connectedApps = new Map();
+    /**
+     * Packages that have completed their CONNECT handshake (sent
+     * `miniapp_connect`, got `CONNECT_ACK`). Distinct from `connectedApps`,
+     * which is populated at spawn/registration time — handshake is later.
+     * Drives {@link waitForConnect}.
+     */
+    handshookApps = new Set();
+    /** Pending {@link waitForConnect} resolvers, keyed by packageName. */
+    connectWaiters = new Map();
+    /** Ref-counted stream subscriptions: stream → set of packageNames. */
+    streamSubscribers = new Map();
+    /** Guards one-time wiring of the cloud transcript/translation fan-out. */
+    cloudResultsWired = false;
+    cloudStatusWired = false;
+    cloudAudioSubscriptionSync = new CloudAudioSubscriptionSync();
+    /** Ping interval handle. */
+    pingIntervalId = null;
+    foregroundProbeTimers = new Map();
+    /**
+     * Notified when a miniapp is unregistered for missing liveness pings.
+     * MentraJSRouter wires this into its crash-respawn machinery so a
+     * silently-stalled background script is restarted (with crash-loop
+     * protection) instead of staying dead — a dead background drops its
+     * subscriptions, which releases the mic while the webview still looks
+     * alive.
+     */
+    onLivenessTimeout = null;
+    /** Pending cloud requests: requestId → packageName that originated the request. */
+    pendingCloudRequests = new Map();
+    speechRuns = new Map();
+    // Browser fallback token auth — HMAC-signed blob with a phone-local
+    // secret. Both issuer and verifier are the same process, so the
+    // secret never leaves the device.
+    localSecret = `miniapp_${Date.now()}_${Math.random().toString(36).slice(2, 14)}`;
+    usedTokens = new Set();
+    constructor() { }
+    /**
+     * Generate an HMAC-signed local session token for browser fallback auth.
+     * Token format: base64(JSON({userId, packageName, exp})).base64(HMAC-SHA256(payload, secret))
+     * Single-use, 5-minute TTL.
+     */
+    generateLocalToken(userId, packageName) {
+        const payload = JSON.stringify({
+            userId,
+            packageName,
+            exp: Date.now() + 5 * 60 * 1000, // 5 min TTL
+            nonce: Math.random().toString(36).slice(2, 10),
+        });
+        const payloadB64 = btoa(payload);
+        const sig = this.hmacSign(payload);
+        return `${payloadB64}.${sig}`;
+    }
+    /**
+     * Validate and consume a local session token. Single-use.
+     */
+    validateLocalToken(token) {
+        const parts = token.split(".");
+        if (parts.length !== 2)
+            return null;
+        const [payloadB64, sig] = parts;
+        // Check single-use
+        if (this.usedTokens.has(token))
+            return null;
+        // Verify signature
+        let payload;
+        try {
+            payload = atob(payloadB64);
+        }
+        catch {
+            return null;
+        }
+        if (this.hmacSign(payload) !== sig)
+            return null;
+        // Parse and check expiry
+        let parsed;
+        try {
+            parsed = JSON.parse(payload);
+        }
+        catch {
+            return null;
+        }
+        if (Date.now() > parsed.exp)
+            return null;
+        // Mark as used
+        this.usedTokens.add(token);
+        // Prune old used tokens periodically (keep set from growing unbounded)
+        if (this.usedTokens.size > 1000) {
+            this.usedTokens.clear();
+        }
+        return { userId: parsed.userId, packageName: parsed.packageName };
+    }
+    /**
+     * Simple HMAC-SHA256 using Web Crypto API (available in React Native).
+     * Returns base64url-encoded signature.
+     * Falls back to a simpler hash if crypto.subtle is not available.
+     */
+    hmacSign(payload) {
+        // Synchronous HMAC using a simple hash — Web Crypto's subtle.sign is async
+        // which doesn't fit cleanly here. For phone-local single-process auth,
+        // a keyed hash is sufficient.
+        let hash = 0;
+        const key = this.localSecret;
+        const input = key + payload + key;
+        for (let i = 0; i < input.length; i++) {
+            const ch = input.charCodeAt(i);
+            hash = ((hash << 5) - hash + ch) | 0;
+        }
+        // Mix in more bytes for collision resistance
+        let hash2 = 0x811c9dc5; // FNV offset basis
+        for (let i = 0; i < input.length; i++) {
+            hash2 ^= input.charCodeAt(i);
+            hash2 = Math.imul(hash2, 0x01000193); // FNV prime
+        }
+        return btoa(String(hash >>> 0) + "." + String(hash2 >>> 0));
+    }
+    static getInstance() {
+        if (!LocalMiniappRuntime.instance) {
+            LocalMiniappRuntime.instance = new LocalMiniappRuntime();
+        }
+        return LocalMiniappRuntime.instance;
+    }
+    initialized = false;
+    /**
+     * Initialize the runtime. Called from MantleManager.init().
+     * Idempotent — safe to call multiple times.
+     */
+    initialize() {
+        if (this.initialized)
+            return;
+        this.initialized = true;
+        console.log(`${LOG_TAG}: initialize()`);
+        this.ensurePingLoop();
+    }
+    /**
+     * Handle an incoming cloud message forwarded by SocketComms
+     * (phone_stream_status, phone_managed_stream_status).
+     *
+     * Routes the response back to the originating miniapp via the requestId
+     * that was stored when the miniapp first made the request.
+     */
+    handleCloudMessage(msg) {
+        const requestId = msg.requestId;
+        const msgType = msg.type;
+        console.log(`${LOG_TAG}: Cloud message: ${msgType}, requestId=${requestId ?? "none"}`);
+        if (!requestId) {
+            console.warn(`${LOG_TAG}: Cloud message ${msgType} has no requestId, cannot route`);
+            return;
+        }
+        const pending = this.pendingCloudRequests.get(requestId);
+        if (!pending) {
+            console.warn(`${LOG_TAG}: No pending request for requestId=${requestId}`);
+            return;
+        }
+        this.pendingCloudRequests.delete(requestId);
+        switch (msgType) {
+            case "phone_stream_status": {
+                // Unreachable for phone-orchestrated streams (the coordinator owns
+                // their lifecycle and never registers a pending cloud request).
+                // Retained as a safety net for any legacy registration path.
+                this.sendToMiniapp(pending.packageName, {
+                    type: MiniappResponseType.EVENT,
+                    streamType: "stream_status",
+                    data: {
+                        streamId: msg.streamId,
+                        status: msg.status,
+                        errorDetails: msg.errorDetails,
+                    },
+                });
+                // Re-register for ongoing status updates (streams send multiple status messages)
+                this.pendingCloudRequests.set(requestId, pending);
+                break;
+            }
+            case "phone_managed_stream_status": {
+                if (msg.status === "connected" || msg.status === "active") {
+                    // Managed stream is ready — send back the playback URLs as the request result
+                    this.sendResult(pending.packageName, pending.envelopeRequestId, true, {
+                        streamId: msg.streamId,
+                        hlsUrl: msg.hlsUrl,
+                        dashUrl: msg.dashUrl,
+                        webrtcUrl: msg.webrtcUrl,
+                    });
+                }
+                // Forward all statuses as events too
+                this.sendToMiniapp(pending.packageName, {
+                    type: MiniappResponseType.EVENT,
+                    streamType: "stream_status",
+                    data: {
+                        streamId: msg.streamId,
+                        status: msg.status,
+                        hlsUrl: msg.hlsUrl,
+                        dashUrl: msg.dashUrl,
+                        webrtcUrl: msg.webrtcUrl,
+                    },
+                });
+                // Re-register for ongoing updates
+                this.pendingCloudRequests.set(requestId, pending);
+                break;
+            }
+            default:
+                console.warn(`${LOG_TAG}: Unknown cloud message type: ${msgType}`);
+        }
+    }
+    /**
+     * Register a pending cloud request so we can route the response back.
+     */
+    registerPendingCloudRequest(requestId, packageName, envelopeRequestId) {
+        this.pendingCloudRequests.set(requestId, { packageName, envelopeRequestId });
+    }
+    // ===========================================================================
+    // App registration
+    // ===========================================================================
+    registerApp(packageName, sendFn, installedManifest) {
+        console.log(`${LOG_TAG}: registerApp(${packageName})`);
+        this.clearForegroundProbe(packageName);
+        // Fresh spawn → fresh handshake. Clear any prior handshake flag so
+        // waitForConnect() blocks until this context's own CONNECT arrives.
+        this.handshookApps.delete(packageName);
+        // If the app is already registered (e.g. QR scanned again for same package),
+        // tear down its old subscriptions first so streamSubscribers doesn't keep
+        // dangling references. The WebView will re-subscribe after its CONNECT.
+        if (this.connectedApps.has(packageName)) {
+            const existing = this.connectedApps.get(packageName);
+            this.cancelSpeech(packageName);
+            // A crash respawn replaces the ConnectedMiniapp without going through
+            // unregisterApp(). Abort the old incarnation's native PCM player before
+            // its only stream id is lost. Target the exact stream rather than using
+            // stopForApp(), whose async playback cleanup could race with audio the
+            // replacement app starts after it connects.
+            const existingSpeakerStreamId = existing.activeSpeakerStreamId;
+            if (existingSpeakerStreamId) {
+                existing.activeSpeakerStreamId = undefined;
+                void audioPlaybackService.abortStream(existingSpeakerStreamId).catch((error) => {
+                    console.warn(`${LOG_TAG}: failed to abort speaker stream while replacing ${packageName}`, error);
+                });
+            }
+            if (existing.authRefreshTimerId !== null) {
+                BgTimer.clearTimeout(existing.authRefreshTimerId);
+                existing.authRefreshTimerId = null;
+            }
+            if (existing.authRetryTimerId !== null) {
+                BgTimer.clearTimeout(existing.authRetryTimerId);
+                existing.authRetryTimerId = null;
+            }
+            for (const stream of existing.subscriptions) {
+                const subs = this.streamSubscribers.get(stream);
+                if (subs) {
+                    subs.delete(packageName);
+                    if (subs.size === 0)
+                        this.streamSubscribers.delete(stream);
+                }
+            }
+            this.recomputeMicRequirements();
+            this.updateCloudSubscriptions();
+        }
+        this.connectedApps.set(packageName, {
+            subscriptions: new Set(),
+            forceLocalTranscriptionStreams: new Set(),
+            cloudTranscriptionStreams: new Set(),
+            sendMessage: sendFn,
+            lastPongAt: Date.now(),
+            installedManifest,
+            authRefreshTimerId: null,
+            authRetryTimerId: null,
+            authDelivered: false,
+            speakerState: "idle",
+            requestedLocationRate: null,
+        });
+        // If we just clobbered an existing entry, its requestedLocationRate is
+        // now gone — recompute so the aggregate doesn't include a stale rate.
+        // The WebView will re-SUBSCRIBE shortly and the rate will reappear.
+        this.recomputeLocationTier();
+        this.ensureCloudStatusWired();
+        this.ensurePingLoop();
+        // Show the system boot message ("Starting <name>…") on the glasses for the
+        // bounded boot window, mirroring the cloud DisplayManager boot screen. The
+        // window ends early once this app pushes its first display (see
+        // LocalDisplayManager.request), or after ~1.5s. Fires once per spawn —
+        // including a crash-respawn, since each spawn is a fresh "app is starting".
+        localDisplayManager.onMount(packageName, installedManifest?.name ?? packageName);
+    }
+    /**
+     * Resolve once `packageName` has completed its CONNECT handshake. If it has
+     * already connected, resolves immediately. Rejects if the timeout elapses
+     * first, or if the app is unregistered while waiting.
+     *
+     * Used by the launcher's `ensureConnected` (and thus the action broker) so a
+     * just-spawned target is known to be live before anything is delivered to it.
+     */
+    waitForConnect(packageName, timeoutMs) {
+        if (this.handshookApps.has(packageName))
+            return Promise.resolve();
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const waiter = (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                this.connectWaiters.get(packageName)?.delete(waiter);
+                if (err)
+                    reject(err);
+                else
+                    resolve();
+            };
+            const timer = setTimeout(() => {
+                waiter(new Error(`waitForConnect: ${packageName} did not connect within ${timeoutMs}ms`));
+            }, timeoutMs);
+            let set = this.connectWaiters.get(packageName);
+            if (!set) {
+                set = new Set();
+                this.connectWaiters.set(packageName, set);
+            }
+            set.add(waiter);
+        });
+    }
+    /** Resolve/reject all pending {@link waitForConnect} waiters for a package. */
+    flushConnectWaiters(packageName, err) {
+        const waiters = this.connectWaiters.get(packageName);
+        if (!waiters)
+            return;
+        this.connectWaiters.delete(packageName);
+        for (const w of waiters)
+            w(err);
+    }
+    /**
+     * Invalidate the CONNECT handshake for a package whose native context is
+     * being replaced WITHOUT going through register/unregister — i.e. a crash
+     * respawn. Without this, {@link waitForConnect} would treat the dead/
+     * not-yet-initialized context as connected and deliver to it. Pending waiters
+     * are failed so a wake mid-respawn retries rather than hanging.
+     */
+    resetHandshake(packageName) {
+        this.handshookApps.delete(packageName);
+        this.flushConnectWaiters(packageName, new Error(`${packageName} respawning`));
+    }
+    /**
+     * Attach (or update) the installedManifest for an already-registered app.
+     * Used when the manifest is fetched asynchronously (dev miniapps) after the
+     * miniapp has already CONNECTed — preserves existing subscriptions.
+     */
+    setInstalledManifest(packageName, installedManifest) {
+        const app = this.connectedApps.get(packageName);
+        if (!app)
+            return;
+        app.installedManifest = installedManifest;
+        // Push declared-permission record to the SDK so session.permissions stays
+        // in sync. Sent regardless of CONNECT_ACK timing — covers the dev-miniapp
+        // case where the manifest is fetched async after the miniapp CONNECTs.
+        this.sendToMiniapp(packageName, {
+            type: MiniappResponseType.PERMISSIONS_UPDATE,
+            permissions: computeDeclaredPermissionRecord(installedManifest),
+        });
+    }
+    /**
+     * Graceful version of {@link unregisterApp}: notify the miniapp via
+     * `WILL_DISCONNECT`, wait ~50ms so its `beforeDisconnect` handlers can
+     * fire one last `sendOneShot` (e.g. `display.clear()`), then run the
+     * normal teardown. Use this for any disconnect path where the socket
+     * is still open. For ungraceful paths (transport already closed),
+     * call {@link unregisterApp} directly — the heads-up would be
+     * undeliverable anyway.
+     */
+    async gracefullyUnregisterApp(packageName, reason = "unregistering") {
+        const app = this.connectedApps.get(packageName);
+        if (!app)
+            return;
+        console.log(`${LOG_TAG}: gracefullyUnregisterApp(${packageName}) — sending WILL_DISCONNECT`);
+        this.sendToMiniapp(packageName, {
+            type: MiniappResponseType.WILL_DISCONNECT,
+            reason,
+        });
+        // 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));
+        this.unregisterApp(packageName);
+    }
+    unregisterApp(packageName) {
+        console.log(`${LOG_TAG}: unregisterApp(${packageName})`);
+        this.clearForegroundProbe(packageName);
+        this.clearMiniappAuthRefresh(packageName);
+        this.clearMiniappAuthDeliveryRetry(packageName);
+        // Drop the handshake flag and fail any in-flight waitForConnect() callers
+        // (e.g. a wake that's mid-handshake when the app is torn down). Done before
+        // the early-return so it runs even if the connectedApps entry is already gone.
+        this.handshookApps.delete(packageName);
+        this.flushConnectWaiters(packageName, new Error(`${packageName} unregistered before connect`));
+        // 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
+        // finish closing the sensor before FOV reconciliation begins. Continue to FOV cleanup even if
+        // warm-up cancellation fails; phone ownership remains retryable until the ASG lease TTL.
+        void phonePhotoCoordinator
+            .stopWarmUpForApp(packageName)
+            .catch((error) => {
+            console.warn(`${LOG_TAG}: failed to stop camera warm-up for ${packageName} on unregister`, error);
+        })
+            .then(() => phoneCameraFovCoordinator.releaseForApp(packageName))
+            .catch((error) => {
+            console.warn(`${LOG_TAG}: failed to release camera FOV override for ${packageName} on unregister`, error);
+        });
+        const app = this.connectedApps.get(packageName);
+        if (!app)
+            return;
+        // Remove from all stream subscriber sets
+        for (const stream of app.subscriptions) {
+            const subs = this.streamSubscribers.get(stream);
+            if (subs) {
+                subs.delete(packageName);
+                if (subs.size === 0) {
+                    this.streamSubscribers.delete(stream);
+                }
+            }
+        }
+        // Reset per-session warning dedup so a relaunch surfaces issues again.
+        resetPermissionWarnings(packageName);
+        // Cancel lookahead/in-flight synthesis before stopping the current file so
+        // an interrupted sentence cannot advance and reclaim playback.
+        this.cancelSpeech(packageName);
+        // Stop audio for this app
+        audioPlaybackService.stopForApp(packageName);
+        // Tear down this app's blob state: abort in-flight uploads + close readers
+        // so a crashed/closed miniapp doesn't leak partial files or file handles.
+        this.blobStore.onAppGone(packageName);
+        // Release phone-owned camera streams. If a miniapp closes/crashes without
+        // sending STREAM_STOP, the host coordinator must drop its subscriber/owner
+        // so glasses publishing and managed Cloudflare inputs do not leak.
+        void phoneStreamCoordinator.stop(packageName).catch((error) => {
+            console.warn(`${LOG_TAG}: failed to stop stream for ${packageName} on unregister`, error);
+        });
+        // Stop any phone-owned video recordings for this app. A miniapp that
+        // closes/crashes mid-recording loses its recordingId, so without this the
+        // glasses keep recording until the max-recording timeout or thermal shutdown.
+        void phoneVideoCoordinator.stopForApp(packageName).catch((error) => {
+            console.warn(`${LOG_TAG}: failed to stop video recording for ${packageName} on unregister`, error);
+        });
+        // Detach the per-app nav event forwarder but leave the native nav session
+        // running. The user may have just closed the mini-app UI and will reopen
+        // it; stopping the session here would kill an active trip mid-route.
+        // Navigation is only stopped when the mini-app explicitly calls
+        // navigation.stop() or when the trip arrives/errors naturally.
+        // (See NavigationHandlers — activeNavApps stays populated so a reconnect
+        // can reattach listeners and resume.)
+        this.navigationHandlers.onDisconnect(packageName);
+        // Recompute heading subscription — if this app was the last subscriber,
+        // the sensor will stop.
+        this.recomputeHeadingSubscription();
+        // Same for the IMU/accelerometer stream.
+        this.recomputeImuSubscription();
+        // 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
+        // in `recomputeLocationTier` is over connectedApps — clearing the
+        // field is enough.
+        app.requestedLocationRate = null;
+        this.recomputeLocationTier();
+        // Clean up any pending cloud requests from this app
+        for (const [reqId, pending] of this.pendingCloudRequests) {
+            if (pending.packageName === packageName) {
+                this.pendingCloudRequests.delete(reqId);
+            }
+        }
+        // Release any display real estate this app held — if it owned the
+        // current on-glasses frame, this clears the glasses (or restores the
+        // core app's saved frame).
+        localDisplayManager.onUnmount(packageName);
+        this.connectedApps.delete(packageName);
+        this.recomputeMicRequirements();
+        this.updateCloudSubscriptions();
+        if (this.connectedApps.size === 0) {
+            this.stopPingLoop();
+        }
+    }
+    // ===========================================================================
+    // Inbound message handling
+    // ===========================================================================
+    handleRawMessage(packageName, raw) {
+        const envelope = parseEnvelope(raw);
+        if (!envelope) {
+            // Not a miniapp envelope — ignore (could be legacy bridge message)
+            return;
+        }
+        const payload = envelope.payload;
+        const requestType = payload.type;
+        const requestId = envelope.requestId;
+        if (!requestType) {
+            console.warn(`${LOG_TAG}: Envelope from ${packageName} missing payload.type`);
+            return;
+        }
+        // ANY inbound message proves the context is alive — a busy background
+        // script streaming DISPLAY/storage traffic shouldn't be killed by the
+        // liveness watchdog just because its PONG replies queue behind real work.
+        this.handlePong(packageName);
+        // Console-tap forwarding. The miniapp's console.log/warn/etc is wrapped
+        // (via injected shim from miniappGlobals.ts) to post a `dev_log`
+        // envelope. We fan out to two destinations:
+        //   1. DevServerBridge — forwards to the laptop's `mentra-miniapp dev`
+        //      terminal. No-op when there's no sidecar (installed miniapps).
+        //   2. React Native console — surfaces the log in Metro / Xcode console
+        //      / adb logcat so installed-miniapp errors are still inspectable
+        //      when there's no laptop to forward to.
+        if (requestType === "dev_log") {
+            const level = payload.level ?? "log";
+            const args = Array.isArray(payload.args) ? payload.args : [];
+            const timestamp = payload.timestamp ?? Date.now();
+            // Source is "ui" because the single-bundle WebView console-tap
+            // shim in miniappGlobals.ts is the only thing that posts
+            // `dev_log`; the two-layer path uses a separate envelope
+            // (`{type:"log", source}`) routed by MentraUIRouter.
+            devServerBridge.forwardLog(packageName, level, args, timestamp, "ui");
+            const tag = `[MINIAPP ${packageName}]`;
+            const fn = console[level] ?? console.log;
+            try {
+                fn(tag, ...args);
+            }
+            catch {
+                console.log(tag, ...args);
+            }
+            return;
+        }
+        // Dispatch
+        switch (requestType) {
+            case MiniappRequestType.CONNECT:
+                void this.handleConnect(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.AUTH_REFRESH:
+                void this.handleAuthRefresh(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.SUBSCRIBE:
+                this.handleSubscribe(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.DISPLAY:
+                this.handleDisplay(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.RENDER:
+                this.handleRender(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.PLAY_AUDIO:
+                this.handlePlayAudio(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.STOP_AUDIO:
+                this.handleStopAudio(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.SPEAK:
+                this.handleSpeak(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.SPEAKER_STREAM_OPEN:
+                void this.handleSpeakerStreamOpen(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.SPEAKER_STREAM_WRITE:
+                void this.handleSpeakerStreamWrite(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.SPEAKER_STREAM_CLOSE:
+                void this.handleSpeakerStreamClose(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.SPEAKER_STREAM_ABORT:
+                void this.handleSpeakerStreamAbort(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.RGB_LED:
+                void this.handleRgbLed(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.LOCATION_POLL:
+                this.handleLocationPoll(packageName, requestId);
+                break;
+            case MiniappRequestType.CALENDAR_LIST_EVENTS:
+                void this.handleCalendarListEvents(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.NAVIGATION_START:
+                this.navigationHandlers.handleStart(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.NAVIGATION_STOP:
+                this.navigationHandlers.handleStop(packageName, requestId);
+                break;
+            case MiniappRequestType.NAVIGATION_DEVIATE:
+                this.navigationHandlers.handleDeviate(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.NAVIGATION_SET_WRONG_SIDEWALK:
+                this.navigationHandlers.handleSetWrongSidewalk(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.NAVIGATION_SET_SKIP_CROSSINGS:
+                this.navigationHandlers.handleSetSkipCrossings(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.NAVIGATION_GET_STATE:
+                this.navigationHandlers.handleGetState(packageName, requestId);
+                break;
+            case MiniappRequestType.NAVIGATION_COMPUTE_ROUTE:
+                this.navigationHandlers.handleComputeRoute(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.NAVIGATION_REVERSE_GEOCODE:
+                this.navigationHandlers.handleReverseGeocode(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.NAVIGATION_PLACE_AUTOCOMPLETE:
+                this.navigationHandlers.handlePlaceAutocomplete(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.NAVIGATION_PLACE_DETAILS:
+                this.navigationHandlers.handlePlaceDetails(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.NAVIGATION_REQUEST_PERMISSION:
+                this.navigationHandlers.handleRequestPermission(packageName, requestId);
+                break;
+            case MiniappRequestType.STORAGE_GET:
+                this.handleStorageGet(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.STORAGE_SET:
+                this.handleStorageSet(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.STORAGE_DELETE:
+                this.handleStorageDelete(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.STORAGE_LIST:
+                this.handleStorageList(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.STORAGE_CLEAR:
+                this.handleStorageClear(packageName, requestId);
+                break;
+            case MiniappRequestType.STORAGE_HAS:
+                this.handleStorageHas(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.STORAGE_GET_ALL:
+                this.handleStorageGetAll(packageName, requestId);
+                break;
+            case MiniappRequestType.STORAGE_SET_MULTIPLE:
+                this.handleStorageSetMultiple(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.STORAGE_FLUSH:
+                // No-op today — MMKV writes through synchronously. Reserved so
+                // a future debounced backend can honor "flush before I quit"
+                // calls without breaking the API.
+                this.sendResult(packageName, requestId, true);
+                break;
+            case MiniappRequestType.CAMERA_FOV:
+                void this.handleCameraFov(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.IMU_SET_ENABLED:
+                this.handleImuSetEnabled(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.PING:
+                // SDK should handle this itself; reply PONG just in case
+                this.sendToMiniapp(packageName, { type: MiniappResponseType.PONG }, requestId);
+                break;
+            case MiniappResponseType.PONG: {
+                // Liveness already touched above for every inbound message; the
+                // PONG carries no other action.
+                break;
+            }
+            case MiniappRequestType.SHARE:
+                this.handleShare(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.OPEN_URL:
+                this.handleOpenUrl(packageName, payload);
+                break;
+            case MiniappRequestType.COPY_CLIPBOARD:
+                this.handleCopyClipboard(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.DOWNLOAD:
+                this.handleDownload(packageName, payload, requestId);
+                break;
+            // Persistent binary blob storage (session.blob)
+            case MiniappRequestType.BLOB_CREATE:
+                this.blobStore.handleCreate(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.BLOB_WRITE:
+                this.blobStore.handleWrite(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.BLOB_COMMIT:
+                this.blobStore.handleCommit(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.BLOB_ABORT:
+                this.blobStore.handleAbort(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.BLOB_SET_FROM_URL:
+                void this.blobStore.handleSetFromUrl(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.BLOB_IMPORT:
+                void this.blobStore.handleImport(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.BLOB_GET:
+                this.blobStore.handleGet(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.BLOB_LIST:
+                this.blobStore.handleList(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.BLOB_USAGE:
+                this.blobStore.handleUsage(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.BLOB_DELETE:
+                this.blobStore.handleDelete(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.BLOB_CLEAR:
+                this.blobStore.handleClear(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.BLOB_OPEN_READ:
+                this.blobStore.handleOpenRead(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.BLOB_READ:
+                this.blobStore.handleRead(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.BLOB_CLOSE_READ:
+                this.blobStore.handleCloseRead(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.BLOB_SHARE:
+                void this.blobStore.handleShare(packageName, payload, requestId);
+                break;
+            // Cloud-coordinated features
+            case MiniappRequestType.PHOTO:
+                void this.handlePhoto(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.CAMERA_WARM_UP:
+                void this.handleCameraWarmUp(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.VIDEO_RECORDING_START:
+                void this.handleVideoRecordingStart(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.VIDEO_RECORDING_STOP:
+                void this.handleVideoRecordingStop(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.STREAM_START:
+                void this.handleStreamStart(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.STREAM_STOP:
+                void this.handleStreamStop(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.MANAGED_STREAM_START:
+                void this.handleManagedStreamStart(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.MANAGED_STREAM_STOP:
+                void this.handleManagedStreamStop(packageName, payload, requestId);
+                break;
+            case REQUEST_WIFI_SETUP_TYPE:
+                void this.handleRequestWifiSetup(packageName, payload, requestId);
+                break;
+            // Inter-miniapp interop (SYSTEM apps only)
+            case MiniappRequestType.MINIAPPS_LIST:
+                this.handleMiniappsList(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.MINIAPPS_START:
+                void this.handleMiniappsStart(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.MINIAPPS_STOP:
+                void this.handleMiniappsStop(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.ACTION_INVOKE:
+                void this.handleActionInvoke(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.ACTION_RESULT:
+                this.handleActionResult(packageName, payload);
+                break;
+            // Deferred in v1
+            case MiniappRequestType.DASHBOARD_CONTENT_UPDATE:
+                this.sendResult(packageName, requestId, false, undefined, {
+                    code: MiniappErrorCode.NOT_IMPLEMENTED,
+                    message: "Dashboard API is deferred in v1",
+                });
+                break;
+            default:
+                console.warn(`${LOG_TAG}: Unknown request type from ${packageName}: ${requestType}`);
+                break;
+        }
+    }
+    // ===========================================================================
+    // Request handlers
+    // ===========================================================================
+    async handleConnect(packageName, _payload, requestId) {
+        console.log(`${LOG_TAG}: CONNECT from ${packageName}`);
+        // Register if not already
+        const existing = this.connectedApps.get(packageName);
+        if (!existing) {
+            console.warn(`${LOG_TAG}: CONNECT from unregistered app ${packageName}, ignoring`);
+            return;
+        }
+        // Update lastPongAt so it doesn't time out right away
+        existing.lastPongAt = Date.now();
+        // Read current glasses capabilities from the settings store
+        const defaultWearable = useSettingsStore.getState().getSetting(ISLAND_SETTINGS_KEYS.defaultWearable);
+        const capabilities = getModelCapabilities(defaultWearable || DeviceTypes.NONE);
+        // 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
+        // to false; this is manifest-declaration tracking only — OS-grant state
+        // is intentionally not modeled here.
+        const declaredPermissions = computeDeclaredPermissionRecord(existing.installedManifest);
+        // Fresh handshake → clear any auth state from a prior context so a stale
+        // retry timer can't fire against this new connection and so the retry loop
+        // below re-arms from scratch.
+        existing.authDelivered = false;
+        this.clearMiniappAuthDeliveryRetry(packageName);
+        const authPromise = this.requestMiniappAuth(packageName);
+        const initialAuth = await withTimeout(authPromise, 1_500);
+        const userId = initialAuth?.mentraUserId ?? "";
+        if (initialAuth) {
+            existing.authDelivered = true;
+            this.scheduleMiniappAuthRefresh(packageName, initialAuth);
+        }
+        this.sendToMiniapp(packageName, {
+            type: MiniappResponseType.CONNECT_ACK,
+            userId,
+            packageName,
+            capabilities,
+            permissions: declaredPermissions,
+            ...(initialAuth ? { auth: initialAuth } : {}),
+        }, requestId);
+        if (!initialAuth) {
+            // The mint timed out or (more importantly) REJECTED — the latter happens
+            // when the cloud client hasn't finished its first-boot Core token exchange
+            // yet, which is exactly the case when a dev miniapp is scanned/launched
+            // right after app start. CONNECT_ACK already went out without auth; keep
+            // trying to mint (and re-drive on cloud-connect) so the app authenticates
+            // to its backend on its own, instead of staying dead until a full manual
+            // Cloud V2 reconnect re-runs the whole handshake.
+            this.deliverInitialMiniappAuth(packageName, authPromise, 0);
+        }
+        this.sendCloudStatusToMiniapp(packageName);
+        // Handshake complete — unblock any launcher.waitForConnect() callers.
+        this.handshookApps.add(packageName);
+        this.flushConnectWaiters(packageName);
+    }
+    async requestMiniappAuth(packageName, opts) {
+        const authPackageName = getDevAppSourcePackage(packageName) ?? packageName;
+        const devAttestation = getDevAppAttestation(packageName) ?? undefined;
+        return cloudClientService.getMiniappAuthToken(authPackageName, {
+            ...opts,
+            ...(devAttestation ? { devAttestation } : {}),
+        });
+    }
+    async handleAuthRefresh(packageName, payload, requestId) {
+        try {
+            const auth = await this.refreshMiniappAuth(packageName, this.authRefreshOptions(payload));
+            if (!auth) {
+                this.sendResult(packageName, requestId, false, undefined, {
+                    code: MiniappErrorCode.NOT_CONNECTED,
+                    message: "Miniapp auth is not configured",
+                });
+                return;
+            }
+            this.sendResult(packageName, requestId, true, { auth });
+        }
+        catch (err) {
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: MiniappErrorCode.INTERNAL,
+                message: err?.message ?? "Miniapp auth refresh failed",
+            });
+        }
+    }
+    async refreshMiniappAuth(packageName, opts) {
+        const auth = await this.requestMiniappAuth(packageName, opts);
+        if (!auth)
+            return null;
+        this.scheduleMiniappAuthRefresh(packageName, auth);
+        this.sendToMiniapp(packageName, {
+            type: MiniappResponseType.AUTH_UPDATE,
+            auth,
+        });
+        return auth;
+    }
+    authRefreshOptions(payload) {
+        const minTtlMs = Number(payload.minTtlMs);
+        if (!Number.isFinite(minTtlMs) || minTtlMs <= 0)
+            return undefined;
+        return { minTtlMs };
+    }
+    scheduleMiniappAuthRefresh(packageName, auth) {
+        const app = this.connectedApps.get(packageName);
+        if (!app)
+            return;
+        this.clearMiniappAuthRefresh(packageName);
+        const refreshAt = auth.expiresAt - MINIAPP_AUTH_REFRESH_HEADROOM_MS;
+        const delay = Math.max(MINIAPP_AUTH_REFRESH_MIN_DELAY_MS, refreshAt - Date.now());
+        app.authRefreshTimerId = BgTimer.setTimeout(() => {
+            const current = this.connectedApps.get(packageName);
+            if (!current)
+                return;
+            current.authRefreshTimerId = null;
+            void this.refreshMiniappAuth(packageName).catch((err) => {
+                console.warn(`${LOG_TAG}: miniapp auth refresh failed for ${packageName}: ${err?.message ?? err}`);
+            });
+        }, delay);
+    }
+    clearMiniappAuthRefresh(packageName) {
+        const app = this.connectedApps.get(packageName);
+        if (!app || app.authRefreshTimerId === null)
+            return;
+        const timerId = app.authRefreshTimerId;
+        BgTimer.clearTimeout(timerId);
+        app.authRefreshTimerId = null;
+    }
+    /**
+     * Deliver the miniapp's FIRST auth token, retrying until it lands. Called from
+     * {@link handleConnect} when the initial mint didn't resolve in the CONNECT_ACK
+     * window. `inFlight` lets attempt 0 reuse the mint the handshake already
+     * started (avoids a redundant duplicate request); later attempts mint fresh.
+     *
+     * A `null` result means auth is fundamentally unavailable (no miniappAuth hook)
+     * — permanent, so we do NOT retry. A REJECTION means a transient failure
+     * (typically the cloud client isn't connection-ready yet) — retry with backoff.
+     * Either way we bail if the app has since disconnected or already got a token
+     * (e.g. via {@link redriveMiniappAuthDelivery} on cloud-connect).
+     */
+    deliverInitialMiniappAuth(packageName, inFlight, attempt) {
+        const app = this.connectedApps.get(packageName);
+        if (!app || app.authDelivered)
+            return;
+        const mint = inFlight ?? this.requestMiniappAuth(packageName);
+        void mint
+            .then((auth) => {
+            const current = this.connectedApps.get(packageName);
+            if (!current || current.authDelivered)
+                return;
+            if (!auth)
+                return; // no auth hook — permanent, don't spin
+            current.authDelivered = true;
+            this.clearMiniappAuthDeliveryRetry(packageName);
+            this.scheduleMiniappAuthRefresh(packageName, auth);
+            this.sendToMiniapp(packageName, { type: MiniappResponseType.AUTH_UPDATE, auth });
+        })
+            .catch((err) => {
+            console.warn(`${LOG_TAG}: miniapp auth mint failed for ${packageName} (attempt ${attempt}): ${err?.message ?? err}`);
+            this.scheduleInitialMiniappAuthRetry(packageName, attempt);
+        });
+    }
+    scheduleInitialMiniappAuthRetry(packageName, attempt) {
+        const app = this.connectedApps.get(packageName);
+        if (!app || app.authDelivered)
+            return;
+        this.clearMiniappAuthDeliveryRetry(packageName);
+        const delay = Math.min(MINIAPP_AUTH_RETRY_MAX_MS, MINIAPP_AUTH_RETRY_BASE_MS * 2 ** attempt);
+        app.authRetryTimerId = BgTimer.setTimeout(() => {
+            const current = this.connectedApps.get(packageName);
+            if (!current)
+                return;
+            current.authRetryTimerId = null;
+            this.deliverInitialMiniappAuth(packageName, undefined, attempt + 1);
+        }, delay);
+    }
+    clearMiniappAuthDeliveryRetry(packageName) {
+        const app = this.connectedApps.get(packageName);
+        if (!app || app.authRetryTimerId === null)
+            return;
+        BgTimer.clearTimeout(app.authRetryTimerId);
+        app.authRetryTimerId = null;
+    }
+    /**
+     * When the cloud client (re)connects, immediately re-attempt the initial mint
+     * for any handshook app still missing its token, instead of waiting out the
+     * backoff. This is what turns "scan a dev app before the cloud is ready" from
+     * "dead until you manually reconnect Cloud V2" into "authenticates on its own
+     * the instant the connection comes up".
+     */
+    redriveMiniappAuthDelivery() {
+        for (const [packageName, app] of this.connectedApps) {
+            if (app.authDelivered)
+                continue;
+            // Only apps that finished their CONNECT handshake are in the mint-retry
+            // state; skip anything still mid-handshake (handleConnect owns that).
+            if (!this.handshookApps.has(packageName))
+                continue;
+            this.clearMiniappAuthDeliveryRetry(packageName);
+            this.deliverInitialMiniappAuth(packageName, undefined, 0);
+        }
+    }
+    handleSubscribe(packageName, payload, requestId) {
+        const app = this.connectedApps.get(packageName);
+        if (!app)
+            return;
+        const rawStreams = (payload.subscriptions ?? payload.streams);
+        // Normalize: objects like {stream: "location_stream", rate: "realtime"} → extract stream name
+        // "location_stream" is the rate-bearing alias for "location_update".
+        // The strictest rate wins when multiple `location_stream` entries appear
+        // in one SUBSCRIBE — the same rule we apply across apps.
+        let requestedLocationRate = null;
+        const forceLocalTranscriptionStreams = new Set();
+        const cloudTranscriptionStreams = new Set();
+        const streams = rawStreams?.map((s) => {
+            if (typeof s === "object" && s !== null) {
+                if (s.stream === "location_stream") {
+                    if (s.rate && locationRateRank(s.rate) > locationRateRank(requestedLocationRate)) {
+                        requestedLocationRate = s.rate;
+                    }
+                    return "location_update";
+                }
+                if (s.forceLocal === true && s.stream.startsWith("transcription:")) {
+                    forceLocalTranscriptionStreams.add(s.stream);
+                }
+                if (s.stream.startsWith("transcription:") && (s.forceLocal !== true || s.includeCloud === true)) {
+                    cloudTranscriptionStreams.add(s.stream);
+                }
+                return s.stream;
+            }
+            if (s.startsWith("transcription:"))
+                cloudTranscriptionStreams.add(s);
+            return s;
+        });
+        if (!Array.isArray(streams)) {
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: MiniappErrorCode.INTERNAL,
+                message: "subscribe requires a subscriptions array",
+            });
+            return;
+        }
+        console.log(`${LOG_TAG}: SUBSCRIBE from ${packageName}: [${streams.join(", ")}]`);
+        // Gate each stream on the permission type its data requires. The manifest
+        // must declare the permission (miniapp.json -> permissions) or we reject
+        // the whole subscribe with PERMISSION_NOT_DECLARED.
+        const declaredTypes = new Set((app.installedManifest?.permissions ?? []).map((p) => p.type?.toUpperCase()));
+        const permissionForStream = (s) => {
+            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 === "phone_notification")
+                return "READ_NOTIFICATIONS";
+            if (s === "phone_notification_dismissed")
+                return "READ_NOTIFICATIONS";
+            return null;
+        };
+        for (const stream of streams) {
+            const required = permissionForStream(stream);
+            if (required && !declaredTypes.has(required)) {
+                logPermissionNotDeclared(packageName, required, `to subscribe to "${stream}"`, `{"type": "${required}"}`);
+                this.sendResult(packageName, requestId, false, undefined, {
+                    code: MiniappErrorCode.PERMISSION_NOT_DECLARED,
+                    message: `${required} permission not declared in miniapp.json (required for "${stream}"). Add {"type": "${required}"} to the "permissions" array.`,
+                    // Extra context fields read by the SDK so authors that subscribe
+                    // to session.on("error") can format their own messages.
+                    permission: required,
+                    subscription: stream,
+                });
+                return;
+            }
+        }
+        // Remove old subscriptions for this app
+        for (const oldStream of app.subscriptions) {
+            const subs = this.streamSubscribers.get(oldStream);
+            if (subs) {
+                subs.delete(packageName);
+                if (subs.size === 0) {
+                    this.streamSubscribers.delete(oldStream);
+                }
+            }
+        }
+        // Add new 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)));
+        for (const stream of streams) {
+            let subs = this.streamSubscribers.get(stream);
+            if (!subs) {
+                subs = new Set();
+                this.streamSubscribers.set(stream, subs);
+            }
+            subs.add(packageName);
+        }
+        this.recomputeMicRequirements();
+        this.updateCloudSubscriptions();
+        this.recomputeHeadingSubscription();
+        this.recomputeImuSubscription();
+        // 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.
+        app.requestedLocationRate = requestedLocationRate;
+        this.recomputeLocationTier();
+        this.sendResult(packageName, requestId, true);
+        // Fire initial snapshot values for stateful streams so miniapps don't have
+        // to wait for the first change event.
+        this.emitInitialSnapshots(packageName, streams);
+    }
+    async handleCalendarListEvents(packageName, payload, requestId) {
+        const app = this.connectedApps.get(packageName);
+        const declared = app?.installedManifest?.permissions?.some((permission) => permission.type?.toUpperCase() === "CALENDAR");
+        if (!declared) {
+            logPermissionNotDeclared(packageName, "CALENDAR", "to list calendar events", '{"type": "CALENDAR"}');
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: MiniappErrorCode.PERMISSION_NOT_DECLARED,
+                message: 'CALENDAR permission not declared in miniapp.json. Add {"type": "CALENDAR"} to the permissions array.',
+                permission: "CALENDAR",
+            });
+            return;
+        }
+        try {
+            const result = await listPhoneCalendarEvents(payload);
+            this.sendResult(packageName, requestId, true, result);
+        }
+        catch (error) {
+            const known = error instanceof PhoneCalendarError;
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: known ? error.code : MiniappErrorCode.INTERNAL,
+                message: error instanceof Error ? error.message : "Failed to read phone calendar events",
+            });
+        }
+    }
+    /**
+     * For state-bearing streams (battery, connection), deliver the current value
+     * immediately on subscribe. Other streams (button press, transcription, etc.)
+     * are pure event streams with no "current value" to snapshot.
+     */
+    emitInitialSnapshots(packageName, streams) {
+        // Read the engine glasses store directly (was a host glassesStatus hook).
+        const gs = useGlassesStore.getState();
+        const glassesState = {
+            connected: isGlassesConnected(gs.connection),
+            deviceModel: gs.deviceModel,
+            batteryLevel: gs.batteryLevel,
+            charging: gs.charging,
+        };
+        const isSimulated = (glassesState.deviceModel || "").toLowerCase().includes("simulated");
+        for (const stream of streams) {
+            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) {
+                    void this.emitPhoneBatteryAs(packageName, "glasses_battery");
+                }
+                else if (typeof glassesState.batteryLevel === "number" && glassesState.batteryLevel >= 0) {
+                    this.sendToMiniapp(packageName, {
+                        type: MiniappResponseType.EVENT,
+                        streamType: "glasses_battery",
+                        data: {
+                            level: glassesState.batteryLevel,
+                            charging: !!glassesState.charging,
+                            timestamp: Date.now(),
+                        },
+                    });
+                }
+            }
+            else if (stream === "phone_battery") {
+                void this.emitPhoneBatteryAs(packageName, "phone_battery");
+            }
+            else if (stream === "glasses_connection") {
+                this.sendToMiniapp(packageName, {
+                    type: MiniappResponseType.EVENT,
+                    streamType: "glasses_connection",
+                    data: glassesState,
+                });
+            }
+            else if (stream === "glasses_wifi") {
+                // Snapshot the current glasses Wi-Fi state on subscribe (like battery).
+                // Read the canonical nested `wifi: {state, ssid}` from the STORE state
+                // (`glassesState` is the narrowed 4-field projection and has no `wifi`;
+                // the pre-engine host hook spread the full store, so read gs directly —
+                // NOT the legacy flat wifiConnected). Effective connectivity requires the
+                // glasses connected AND on Wi-Fi — mirrors the host's store-derived
+                // forward, so an already-disconnected device reports `connected: false`
+                // rather than silently emitting nothing. Always emits so onWifi gets an
+                // initial value.
+                const wifi = gs.wifi.state === "connected" ? gs.wifi : null;
+                const connected = glassesState.connected === true && wifi !== null;
+                this.sendToMiniapp(packageName, {
+                    type: MiniappResponseType.EVENT,
+                    streamType: "glasses_wifi",
+                    data: {
+                        connected,
+                        ssid: connected ? wifi?.ssid : undefined,
+                        localIp: connected ? wifi?.localIp : undefined,
+                        timestamp: Date.now(),
+                    },
+                });
+            }
+            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.
+                const headUp = gs.headUp;
+                if (typeof headUp === "boolean") {
+                    this.sendToMiniapp(packageName, {
+                        type: MiniappResponseType.EVENT,
+                        streamType: "head_position",
+                        data: {
+                            position: headUp ? "up" : "down",
+                            timestamp: Date.now(),
+                        },
+                    });
+                }
+            }
+        }
+    }
+    /**
+     * Read the phone's battery state right now and emit it as the given stream.
+     * Used for both phone_battery snapshot on subscribe, and as a stand-in for
+     * glasses_battery when connected to Simulated Glasses.
+     */
+    async emitPhoneBatteryAs(packageName, streamType) {
+        try {
+            const level = await Battery.getBatteryLevelAsync();
+            const state = await Battery.getBatteryStateAsync();
+            const charging = state === Battery.BatteryState.CHARGING || state === Battery.BatteryState.FULL;
+            this.sendToMiniapp(packageName, {
+                type: MiniappResponseType.EVENT,
+                streamType,
+                data: {
+                    level: Math.round(level * 100),
+                    charging,
+                    timestamp: Date.now(),
+                },
+            });
+        }
+        catch (err) {
+            console.log(`${LOG_TAG}: phone battery snapshot failed`, err);
+        }
+    }
+    handleDisplay(packageName, payload, requestId) {
+        try {
+            // Zombie-frame gate: a dying miniapp's last in-flight frame can arrive
+            // AFTER onUnmount cleared its display — repainting a dead app's UI (and
+            // poisoning the next boot's pre-boot restore snapshot). Killed mid-route
+            // nav reproduced this reliably; its 3s re-push raced the teardown.
+            if (!this.connectedApps.has(packageName)) {
+                console.log(`${LOG_TAG}: dropping display from unmounted app ${packageName}`);
+                return;
+            }
+            if (!payload.layout || typeof payload.layout !== "object") {
+                this.sendResult(packageName, requestId, false, undefined, {
+                    code: MiniappErrorCode.INTERNAL,
+                    message: "display request missing layout object",
+                });
+                return;
+            }
+            // Hand off to LocalDisplayManager — it owns boot/throttle/arbitration/
+            // expiry + the native BluetoothSdk.displayEvent call + useDisplayStore.
+            localDisplayManager.request(packageName, {
+                view: payload.view ?? "main",
+                layout: payload.layout,
+                durationMs: payload.durationMs,
+            });
+            this.sendResult(packageName, requestId, true);
+        }
+        catch (err) {
+            console.error(`${LOG_TAG}: display error:`, err);
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: MiniappErrorCode.INTERNAL,
+                message: err instanceof Error ? err.message : "Display error",
+            });
+        }
+    }
+    /**
+     * Scene render (session.display.render()). Same arbitration as DISPLAY, but
+     * the payload is a whole frame of positioned elements and the caller may be
+     * awaiting the outcome: LocalDisplayManager guarantees the resolver fires
+     * exactly once (displayed/blocked, with degraded/dropped reporting), and that
+     * becomes the REQUEST_RESULT data.
+     */
+    handleRender(packageName, payload, requestId) {
+        try {
+            // Zombie-frame gate — see handleDisplay.
+            if (!this.connectedApps.has(packageName)) {
+                this.sendResult(packageName, requestId, true, { status: "blocked", reason: "app stopped" });
+                return;
+            }
+            if (!Array.isArray(payload.elements)) {
+                this.sendResult(packageName, requestId, false, undefined, {
+                    code: MiniappErrorCode.INTERNAL,
+                    message: "render request missing elements array",
+                });
+                return;
+            }
+            localDisplayManager.request(packageName, {
+                view: payload.view ?? "main",
+                scene: payload.elements,
+                durationMs: payload.durationMs,
+            }, (result) => this.sendResult(packageName, requestId, true, result));
+        }
+        catch (err) {
+            console.error(`${LOG_TAG}: render error:`, err);
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: MiniappErrorCode.INTERNAL,
+                message: err instanceof Error ? err.message : "Render error",
+            });
+        }
+    }
+    handlePlayAudio(packageName, payload, requestId) {
+        const audioUrl = (payload.audioUrl ?? payload.url);
+        if (!audioUrl) {
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: MiniappErrorCode.INTERNAL,
+                message: "play_audio requires an audioUrl",
+            });
+            return;
+        }
+        const audioRequestId = requestId || `local_${Date.now()}`;
+        const volume = typeof payload.volume === "number" ? payload.volume : 1.0;
+        const stopOtherAudio = payload.stopOtherAudio !== false;
+        this.cancelSpeech(packageName);
+        this.setSpeakerState(packageName, "loading");
+        audioPlaybackService.play({ requestId: audioRequestId, audioUrl, appId: packageName, volume, stopOtherAudio }, (_respId, success, error, duration) => {
+            if (success) {
+                this.setSpeakerState(packageName, "stopped", { durationMs: duration ?? undefined });
+            }
+            else {
+                this.setSpeakerState(packageName, "error", {
+                    errorCode: MiniappErrorCode.INTERNAL,
+                    errorMessage: error ?? "play failed",
+                    durationMs: duration ?? undefined,
+                });
+            }
+            this.sendResult(packageName, requestId, success, { duration }, error
+                ? {
+                    code: MiniappErrorCode.INTERNAL,
+                    message: error,
+                }
+                : undefined);
+        });
+        // Optimistic "started playing" transition. The audio service doesn't
+        // have a "playback actually started" callback today; cloud SDK v3 has
+        // the same constraint and uses optimistic timing. Microtask so the
+        // initial "loading" envelope flushes first.
+        queueMicrotask(() => this.setSpeakerState(packageName, "playing"));
+    }
+    handleStopAudio(packageName, _payload, requestId) {
+        this.cancelSpeech(packageName);
+        audioPlaybackService.stopForApp(packageName);
+        this.setSpeakerState(packageName, "stopped");
+        this.sendResult(packageName, requestId, true);
+    }
+    // ── speaker.createStream (live PCM output) ────────────────────────────────
+    /** Valid PCM sample rates for speaker streams. Mirrors the SDK contract. */
+    static SPEAKER_STREAM_SAMPLE_RATES = new Set([16000, 24000, 48000]);
+    static SPEAKER_STREAM_MAX_BASE64_CHARS = Math.ceil((256 * 1024) / 3) * 4;
+    speakerStreamCounter = 0;
+    async handleSpeakerStreamOpen(packageName, payload, requestId) {
+        const app = this.connectedApps.get(packageName);
+        if (!app)
+            return;
+        // One stream per miniapp: opening a second closes the first.
+        const previous = app.activeSpeakerStreamId;
+        if (previous) {
+            app.activeSpeakerStreamId = undefined;
+            await audioPlaybackService.abortStream(previous).catch((error) => {
+                console.warn(`${LOG_TAG}: failed to abort previous speaker stream for ${packageName}`, error);
+            });
+        }
+        const sampleRate = typeof payload.sampleRate === "number" ? payload.sampleRate : 16000;
+        if (!LocalMiniappRuntime.SPEAKER_STREAM_SAMPLE_RATES.has(sampleRate)) {
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: MiniappErrorCode.INVALID_ARGUMENT,
+                message: `unsupported sampleRate ${sampleRate} (use 16000, 24000, or 48000)`,
+            });
+            return;
+        }
+        const channels = typeof payload.channels === "number" ? payload.channels : 1;
+        if (channels !== 1) {
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: MiniappErrorCode.INVALID_ARGUMENT,
+                message: "speaker streams currently support mono PCM only",
+            });
+            return;
+        }
+        const volume = typeof payload.volume === "number" ? payload.volume : 1;
+        if (!Number.isFinite(volume) || volume < 0 || volume > 1) {
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: MiniappErrorCode.INVALID_ARGUMENT,
+                message: "speaker stream volume must be between 0 and 1",
+            });
+            return;
+        }
+        const streamId = `spkstream_${Date.now()}_${++this.speakerStreamCounter}`;
+        this.setSpeakerState(packageName, "loading");
+        try {
+            await audioPlaybackService.openStream({
+                streamId,
+                appId: packageName,
+                sampleRate,
+                channels,
+                volume,
+                stopOtherAudio: payload.stopOtherAudio !== false,
+                onEnded: (endedId, success, error, durationMs) => {
+                    const current = this.connectedApps.get(packageName);
+                    // Ignore completion from an app incarnation replaced by a crash
+                    // respawn. Its abort may finish after the new app has registered and
+                    // must not overwrite that app's speaker state.
+                    if (current !== app)
+                        return;
+                    if (current.activeSpeakerStreamId === endedId)
+                        current.activeSpeakerStreamId = undefined;
+                    if (success) {
+                        this.setSpeakerState(packageName, "stopped", { durationMs: durationMs ?? undefined });
+                    }
+                    else {
+                        this.setSpeakerState(packageName, "error", {
+                            errorCode: MiniappErrorCode.INTERNAL,
+                            errorMessage: error ?? "speaker stream failed",
+                            durationMs: durationMs ?? undefined,
+                        });
+                    }
+                },
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.setSpeakerState(packageName, "error", {
+                errorCode: MiniappErrorCode.INTERNAL,
+                errorMessage: message,
+            });
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: MiniappErrorCode.INTERNAL,
+                message,
+            });
+            return;
+        }
+        // The native open can outlive a miniapp disconnect. Its ordinary teardown
+        // ran while no StreamState existed yet, so close this late result here
+        // instead of leaving an orphan AudioTrack/AVAudioEngine session.
+        if (this.connectedApps.get(packageName) !== app) {
+            await audioPlaybackService.abortStream(streamId);
+            return;
+        }
+        app.activeSpeakerStreamId = streamId;
+        // Optimistic "playing", same as play(): the chunk player starts as soon
+        // as the first write lands. Microtask so "loading" flushes first.
+        queueMicrotask(() => this.setSpeakerState(packageName, "playing"));
+        this.sendResult(packageName, requestId, true, { streamId });
+    }
+    /** Resolve + validate a stream id from a payload against the app's active stream. */
+    activeSpeakerStream(packageName, payload) {
+        const streamId = typeof payload.streamId === "string" ? payload.streamId : undefined;
+        const app = this.connectedApps.get(packageName);
+        if (!streamId || !app || app.activeSpeakerStreamId !== streamId)
+            return null;
+        return streamId;
+    }
+    async handleSpeakerStreamWrite(packageName, payload, requestId) {
+        const streamId = this.activeSpeakerStream(packageName, payload);
+        if (!streamId) {
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: MiniappErrorCode.INTERNAL,
+                message: "speaker stream is not open",
+            });
+            return;
+        }
+        const base64 = typeof payload.base64 === "string" ? payload.base64 : "";
+        if (!base64 || base64.length % 4 !== 0) {
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: MiniappErrorCode.INVALID_ARGUMENT,
+                message: "speaker stream write requires padded base64 PCM data",
+            });
+            return;
+        }
+        if (base64.length > LocalMiniappRuntime.SPEAKER_STREAM_MAX_BASE64_CHARS) {
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: MiniappErrorCode.PAYLOAD_TOO_LARGE,
+                message: "speaker stream chunk exceeds the 256 KB raw PCM limit",
+            });
+            return;
+        }
+        try {
+            const result = await audioPlaybackService.writeStreamChunk(streamId, base64);
+            this.sendResult(packageName, requestId, true, result);
+        }
+        catch (error) {
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: MiniappErrorCode.INTERNAL,
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    async handleSpeakerStreamClose(packageName, payload, requestId) {
+        const streamId = this.activeSpeakerStream(packageName, payload);
+        if (!streamId) {
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: MiniappErrorCode.INTERNAL,
+                message: "speaker stream is not open",
+            });
+            return;
+        }
+        try {
+            // Resolves once the buffered audio has drained; onEnded delivers the
+            // terminal SPEAKER_STATE ("stopped").
+            const result = await audioPlaybackService.closeStream(streamId);
+            this.sendResult(packageName, requestId, true, result);
+        }
+        catch (error) {
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: MiniappErrorCode.INTERNAL,
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    async handleSpeakerStreamAbort(packageName, payload, requestId) {
+        const streamId = this.activeSpeakerStream(packageName, payload);
+        if (!streamId) {
+            // Aborting an already-gone stream is fine — abort() is idempotent.
+            this.sendResult(packageName, requestId, true);
+            return;
+        }
+        try {
+            await audioPlaybackService.abortStream(streamId);
+            this.sendResult(packageName, requestId, true);
+        }
+        catch (error) {
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: MiniappErrorCode.INTERNAL,
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    async handleSpeak(packageName, payload, requestId) {
+        const rawText = payload.text;
+        const sentences = typeof rawText === "string"
+            ? [rawText.trim()].filter(Boolean)
+            : Array.isArray(rawText)
+                ? rawText.filter((sentence) => typeof sentence === "string").map((sentence) => sentence.trim()).filter(Boolean)
+                : [];
+        if (sentences.length === 0) {
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: MiniappErrorCode.INTERNAL,
+                message: "speak requires text or a non-empty sentence list",
+            });
+            return;
+        }
+        const cloudText = sentences.join(" ");
+        const voice = (payload.voice_id ?? payload.voice) || "default";
+        const audioRequestId = requestId || `tts_${Date.now()}`;
+        const volume = typeof payload.volume === "number" ? payload.volume : 1.0;
+        const stopOtherAudio = payload.stopOtherAudio !== false;
+        const voiceSettings = payload.voice_settings && typeof payload.voice_settings === "object"
+            ? payload.voice_settings
+            : undefined;
+        const speed = typeof voiceSettings?.speed === "number" ? voiceSettings.speed : undefined;
+        const run = { id: audioRequestId, cancelled: false };
+        this.cancelSpeech(packageName);
+        this.speechRuns.set(packageName, run);
+        this.setSpeakerState(packageName, "loading");
+        let terminalSent = false;
+        const sendPlaybackResult = (success, error, duration, fallbackErrorMessage, completed = success, errorCode = MiniappErrorCode.TTS_UPSTREAM_ERROR) => {
+            if (terminalSent)
+                return;
+            terminalSent = true;
+            // A superseded run still owns its bridge request, but it no longer owns
+            // the package's shared speaker state.
+            const ownsSpeakerState = this.speechRuns.get(packageName) === run;
+            if (ownsSpeakerState)
+                this.speechRuns.delete(packageName);
+            if (ownsSpeakerState) {
+                if (success) {
+                    this.setSpeakerState(packageName, "stopped", { durationMs: duration ?? undefined });
+                }
+                else {
+                    this.setSpeakerState(packageName, "error", {
+                        errorCode,
+                        errorMessage: error ?? fallbackErrorMessage,
+                        durationMs: duration ?? undefined,
+                    });
+                }
+            }
+            this.sendResult(packageName, requestId, success, { completed, duration }, error
+                ? {
+                    code: errorCode,
+                    message: error,
+                }
+                : undefined);
+        };
+        run.onCancelled = () => sendPlaybackResult(true, null, null, "tts playback stopped", false);
+        try {
+            const voiceExplicit = payload.voice_id !== undefined || payload.voice !== undefined;
+            const offlineSupportsVoice = !voiceExplicit || voice === "default" || ttsModelManager.getAvailableLanguages().some((l) => l.code === voice);
+            const modelId = typeof payload.model_id === "string" ? payload.model_id : undefined;
+            const forceLocal = payload.forceLocal === true;
+            const cloudConnected = cloudClientService.isConnected();
+            console.log(`${LOG_TAG}: TTS decision for ${packageName}: cloudConnected=${cloudConnected}, runtimeTts=yes, offlineVoice=${offlineSupportsVoice}, forceLocal=${forceLocal}`);
+            const playOfflineTts = async (reason) => {
+                if (run.cancelled)
+                    return true;
+                if (!offlineSupportsVoice || !(await ttsModelManager.isModelAvailable())) {
+                    return false;
+                }
+                if (run.cancelled)
+                    return true;
+                const languageCode = ttsModelManager.getAvailableLanguages().some((l) => l.code === voice) ? voice : undefined;
+                const offlineSentences = sentences;
+                if (offlineSentences.length > 1) {
+                    let firstSentence;
+                    try {
+                        firstSentence = await ttsModelManager.synthesizeToFile(offlineSentences[0], { languageCode, speed });
+                    }
+                    catch (offlineErr) {
+                        if (run.cancelled)
+                            return true;
+                        console.warn(`${LOG_TAG}: offline sentence TTS synthesize failed${reason ? ` after ${reason}` : ""}:`, offlineErr);
+                        return false;
+                    }
+                    if (run.cancelled) {
+                        await Promise.resolve(firstSentence.cleanup?.());
+                        return true;
+                    }
+                    void runSentenceTtsPipeline({
+                        sentences: offlineSentences,
+                        firstAudio: firstSentence,
+                        run,
+                        synthesize: (sentence) => ttsModelManager.synthesizeToFile(sentence, { languageCode, speed }),
+                        play: (audio, index) => new Promise((resolve) => {
+                            const sentenceRequestId = `${audioRequestId}_sentence_${index}`;
+                            run.playbackRequestId = sentenceRequestId;
+                            audioPlaybackService.play({
+                                requestId: sentenceRequestId,
+                                audioUrl: audio.audioUrl,
+                                appId: packageName,
+                                volume,
+                                stopOtherAudio,
+                                suppressCloudUplink: true,
+                            }, (_responseId, success, error, duration, completionReason) => {
+                                if (run.playbackRequestId === sentenceRequestId)
+                                    run.playbackRequestId = undefined;
+                                resolve({ success, completed: completionReason === "completed", error, duration });
+                            });
+                        }),
+                        onCleanupError: (cleanupError) => {
+                            console.warn(`${LOG_TAG}: sentence TTS cleanup failed`, cleanupError);
+                        },
+                    }).then(({ success, completed, error, duration }) => {
+                        sendPlaybackResult(success, error, duration, "offline sentence tts playback failed", completed);
+                    }, (pipelineError) => {
+                        const message = pipelineError instanceof Error ? pipelineError.message : String(pipelineError);
+                        sendPlaybackResult(false, message, null, "offline sentence tts playback failed", false);
+                    });
+                    queueMicrotask(() => {
+                        if (this.speechRuns.get(packageName) === run)
+                            this.setSpeakerState(packageName, "playing");
+                    });
+                    return true;
+                }
+                let offlineGenerated;
+                try {
+                    offlineGenerated = await ttsModelManager.synthesizeToFile(offlineSentences[0], { languageCode, speed });
+                }
+                catch (offlineErr) {
+                    if (run.cancelled)
+                        return true;
+                    console.warn(`${LOG_TAG}: offline TTS synthesize failed${reason ? ` after ${reason}` : ""}:`, offlineErr);
+                    return false;
+                }
+                const generated = offlineGenerated;
+                if (run.cancelled) {
+                    await Promise.resolve(generated.cleanup?.());
+                    return true;
+                }
+                run.playbackRequestId = audioRequestId;
+                audioPlaybackService.play({
+                    requestId: audioRequestId,
+                    audioUrl: generated.audioUrl,
+                    appId: packageName,
+                    volume,
+                    stopOtherAudio,
+                    suppressCloudUplink: true,
+                }, (_respId, success, error, duration, completionReason) => {
+                    if (run.playbackRequestId === audioRequestId)
+                        run.playbackRequestId = undefined;
+                    void Promise.resolve(generated.cleanup?.()).catch((cleanupError) => {
+                        console.warn(`${LOG_TAG}: offline TTS cleanup failed`, cleanupError);
+                    });
+                    sendPlaybackResult(success, error, duration, "offline tts playback failed", completionReason === "completed");
+                });
+                queueMicrotask(() => {
+                    if (this.speechRuns.get(packageName) === run)
+                        this.setSpeakerState(packageName, "playing");
+                });
+                return true;
+            };
+            const playCloudTts = async (fallbackToOffline) => {
+                if (run.cancelled)
+                    return true;
+                let source;
+                try {
+                    source = await cloudClientService.tts.speak(cloudText, {
+                        ...(voiceExplicit && voice !== "default" ? { voice_id: voice } : {}),
+                        ...(modelId ? { model_id: modelId } : {}),
+                        ...(voiceSettings ? { voice_settings: voiceSettings } : {}),
+                    });
+                }
+                catch (cloudErr) {
+                    if (run.cancelled)
+                        return true;
+                    const error = cloudErr instanceof Error ? cloudErr.message : String(cloudErr);
+                    console.warn(`${LOG_TAG}: cloud TTS source failed: ${error}`);
+                    if (fallbackToOffline && (await playOfflineTts("cloud tts source failed"))) {
+                        return true;
+                    }
+                    sendPlaybackResult(false, error, null, "tts failed");
+                    return true;
+                }
+                if (run.cancelled)
+                    return true;
+                run.playbackRequestId = audioRequestId;
+                await Promise.resolve(audioPlaybackService.play({
+                    requestId: audioRequestId,
+                    audioUrl: source.audioUrl,
+                    appId: packageName,
+                    volume,
+                    stopOtherAudio,
+                    suppressCloudUplink: true,
+                }, (_respId, success, error, duration, completionReason) => {
+                    if (run.playbackRequestId === audioRequestId)
+                        run.playbackRequestId = undefined;
+                    if (!success && fallbackToOffline) {
+                        void playOfflineTts("cloud tts playback failed").then((started) => {
+                            if (!started) {
+                                sendPlaybackResult(false, error, duration, "tts failed");
+                            }
+                        });
+                        return;
+                    }
+                    sendPlaybackResult(success, error, duration, "tts failed", completionReason === "completed");
+                }));
+                queueMicrotask(() => {
+                    if (this.speechRuns.get(packageName) === run)
+                        this.setSpeakerState(packageName, "playing");
+                });
+                return true;
+            };
+            if (forceLocal) {
+                if (await playOfflineTts()) {
+                    return;
+                }
+                if (run.cancelled)
+                    return;
+                const message = "tts unavailable: forceLocal requested but offline TTS model is not available";
+                sendPlaybackResult(false, message, null, message, false, MiniappErrorCode.TTS_LOCAL_UNAVAILABLE);
+                return;
+            }
+            if (cloudConnected && (await playCloudTts(true))) {
+                return;
+            }
+            // Offline is the disconnected-cloud fallback. If the model is not
+            // available, preserve the old behavior by trying cloud as a last resort.
+            if (await playOfflineTts(cloudConnected ? undefined : "cloud disconnected")) {
+                return;
+            }
+            if (await playCloudTts(false)) {
+                return;
+            }
+            const message = "tts unavailable: no cloud TTS URL or offline TTS model";
+            sendPlaybackResult(false, message, null, message, false);
+        }
+        catch (err) {
+            console.error(`${LOG_TAG}: speak error:`, err);
+            const message = err instanceof Error ? err.message : "TTS error";
+            sendPlaybackResult(false, message, null, "TTS error", false);
+        }
+    }
+    cancelSpeech(packageName) {
+        const run = this.speechRuns.get(packageName);
+        if (!run)
+            return;
+        run.cancelled = true;
+        this.speechRuns.delete(packageName);
+        if (run.playbackRequestId)
+            audioPlaybackService.cancelPlayback(run.playbackRequestId);
+        run.onCancelled?.();
+    }
+    async handleRgbLed(packageName, payload, requestId) {
+        const coerceNumber = (value, fallback) => {
+            const coerced = Number(value);
+            return Number.isFinite(coerced) ? coerced : fallback;
+        };
+        const ledRequestId = requestId || `led_${Date.now()}`;
+        const action = normalizeRgbLedAction(payload.action);
+        const color = normalizeRgbLedColor(payload.color);
+        try {
+            const result = await BluetoothSdk.rgbLedControl(ledRequestId, packageName, action, color, coerceNumber(payload.ontime, 1000), coerceNumber(payload.offtime, 0), coerceNumber(payload.count, 1));
+            this.sendResult(packageName, requestId, true, result);
+        }
+        catch (err) {
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: err.code || MiniappErrorCode.INTERNAL,
+                message: err instanceof Error ? err.message : "RGB LED command failed",
+            });
+        }
+    }
+    async handleLocationPoll(packageName, requestId) {
+        try {
+            const { status } = await Location.requestForegroundPermissionsAsync();
+            if (status !== "granted") {
+                this.sendResult(packageName, requestId, false, undefined, {
+                    code: MiniappErrorCode.PERMISSION_NOT_DECLARED,
+                    message: "Location permission not granted",
+                });
+                return;
+            }
+            // Try the OS cache first — usually instant — and only fall back to
+            // a fresh fix if the cache is empty. Use Low accuracy on the fresh
+            // path so we get a cell/wifi-tower fix in ~1s instead of waiting
+            // for full GPS warm-up.
+            const cached = await Location.getLastKnownPositionAsync({ maxAge: 60_000 });
+            const location = cached ?? (await Location.getCurrentPositionAsync({ accuracy: Location.Accuracy.Low }));
+            this.sendResult(packageName, requestId, true, {
+                lat: location.coords.latitude,
+                lng: location.coords.longitude,
+                accuracy: location.coords.accuracy ?? undefined,
+                timestamp: location.timestamp,
+            });
+        }
+        catch (err) {
+            console.error(`${LOG_TAG}: location poll error:`, err);
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: MiniappErrorCode.INTERNAL,
+                message: err instanceof Error ? err.message : "Location error",
+            });
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Navigation
+    // ---------------------------------------------------------------------------
+    /**
+     * All navigation handlers + their state live in NavigationHandlers. The
+     * dispatcher's NAVIGATION_* cases delegate here; the rest of the runtime
+     * cross-cuts navigation through {@link NavigationHandlers.onDisconnect}
+     * (mini-app disconnect) and {@link NavigationHandlers.isTripActive}
+     * (location-stream gating during a trip).
+     */
+    navigationHandlers = new NavigationHandlers((packageName, envelope) => this.sendToMiniapp(packageName, envelope), (packageName, requestId, ok, result, error) => this.sendResult(packageName, requestId, ok, result, error));
+    /**
+     * `session.blob` — persistent, per-app binary storage. Like NavigationHandlers,
+     * the BLOB_* dispatcher cases delegate here. It's a generic byte store; audio
+     * recording lives entirely in the miniapp (mic.onAudioChunk → chunked
+     * BLOB_WRITE), so nothing audio-specific runs in the host.
+     */
+    blobStore = new BlobStore({
+        sendResult: (packageName, requestId, ok, result, error) => this.sendResult(packageName, requestId, ok, result, error),
+        getUserId: () => useSettingsStore.getState().getSetting(ISLAND_SETTINGS_KEYS.coreToken) || "anonymous",
+    });
+    /**
+     * Heading is a sensor stream — start the native compass when any mini
+     * app is subscribed to "heading_update", stop it when none are.
+     */
+    headingUnsub = null;
+    recomputeHeadingSubscription() {
+        const wantsHeading = this.streamSubscribers.has(MiniappStreamType.HEADING_UPDATE);
+        if (wantsHeading && !this.headingUnsub) {
+            // Heading sensor lives in engine (HeadingService) — subscribe directly.
+            this.headingUnsub = headingService.addListener((degrees) => {
+                this.forwardEvent(MiniappStreamType.HEADING_UPDATE, { degrees });
+            });
+        }
+        else if (!wantsHeading && this.headingUnsub) {
+            this.headingUnsub();
+            this.headingUnsub = null;
+        }
+    }
+    /**
+     * Accelerometer is a sensor stream — enable the glasses IMU when any mini
+     * app is subscribed to "accel_data", disable it when none are. Mirrors the
+     * heading pattern. Only G2 streams IMU today; on other devices the native
+     * call is a no-op so this is harmless.
+     */
+    imuEnabled = false;
+    recomputeImuSubscription() {
+        const wantsImu = this.streamSubscribers.has(MiniappStreamType.ACCEL_DATA);
+        if (wantsImu === this.imuEnabled)
+            return;
+        this.imuEnabled = wantsImu;
+        void BluetoothSdk.setImuEnabled(wantsImu);
+    }
+    /**
+     * Last rate we asked the host for. Lets us skip the cross-process call
+     * when nothing actually changed (most SUBSCRIBE / unregister churn
+     * leaves the aggregate unchanged) and tracks state for the no-active-
+     * subscribers → tell host to back off case.
+     */
+    lastAppliedLocationRate = null;
+    /**
+     * Recompute the aggregate location tier across every connected
+     * miniapp and push the result to the host. The aggregate is the
+     * STRICTEST rate any single app has requested — see
+     * {@link LOCATION_RATE_PRIORITY} — because the GPS sample rate is a
+     * shared OS-level setting that we can't bias per-app.
+     *
+     * Called after every SUBSCRIBE and every unregister so that when a
+     * realtime-requesting app goes away the tier falls back down. If no
+     * connected app is asking for a location rate, we tell the host
+     * "off" so it can drop GPS power.
+     */
+    recomputeLocationTier() {
+        let bestRank = -1;
+        for (const app of this.connectedApps.values()) {
+            const r = app.requestedLocationRate;
+            if (!r)
+                continue;
+            const rank = locationRateRank(r);
+            if (rank > bestRank) {
+                bestRank = rank;
+            }
+        }
+        // When no app is asking, downgrade to "off". Without this we'd
+        // leak the last-known-strictest rate forever (the original bug).
+        const next = bestRank >= 0 ? LOCATION_RATE_PRIORITY[bestRank] : "off";
+        if (next === this.lastAppliedLocationRate)
+            return;
+        this.lastAppliedLocationRate = next;
+        console.log(`[LOCATION] aggregate tier → ${next}`);
+        void phoneLocationService.setLocationTier(next);
+    }
+    // ---------------------------------------------------------------------------
+    // Storage helpers
+    // ---------------------------------------------------------------------------
+    getStorageKeyPrefix(packageName) {
+        const userId = useSettingsStore.getState().getSetting(ISLAND_SETTINGS_KEYS.coreToken) || "anonymous";
+        return `mentraos_localstorage_${userId}_${packageName}_`;
+    }
+    async handleStorageGet(packageName, payload, requestId) {
+        try {
+            const key = payload.key;
+            if (!key) {
+                this.sendResult(packageName, requestId, false, undefined, {
+                    code: MiniappErrorCode.INTERNAL,
+                    message: "storage_get requires a key",
+                });
+                return;
+            }
+            const fullKey = this.getStorageKeyPrefix(packageName) + key;
+            const result = mmkvStorage.load(fullKey);
+            this.sendResult(packageName, requestId, true, { key, value: result.is_ok() ? result.value : null });
+        }
+        catch (err) {
+            console.error(`${LOG_TAG}: storage_get error:`, err);
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: MiniappErrorCode.INTERNAL,
+                message: err instanceof Error ? err.message : "Storage error",
+            });
+        }
+    }
+    async handleStorageSet(packageName, payload, requestId) {
+        try {
+            const key = payload.key;
+            if (!key) {
+                this.sendResult(packageName, requestId, false, undefined, {
+                    code: MiniappErrorCode.INTERNAL,
+                    message: "storage_set requires a key",
+                });
+                return;
+            }
+            const fullKey = this.getStorageKeyPrefix(packageName) + key;
+            mmkvStorage.save(fullKey, payload.value ?? null);
+            this.sendResult(packageName, requestId, true);
+        }
+        catch (err) {
+            console.error(`${LOG_TAG}: storage_set error:`, err);
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: MiniappErrorCode.INTERNAL,
+                message: err instanceof Error ? err.message : "Storage error",
+            });
+        }
+    }
+    async handleStorageDelete(packageName, payload, requestId) {
+        try {
+            const key = payload.key;
+            if (!key) {
+                this.sendResult(packageName, requestId, false, undefined, {
+                    code: MiniappErrorCode.INTERNAL,
+                    message: "storage_delete requires a key",
+                });
+                return;
+            }
+            const fullKey = this.getStorageKeyPrefix(packageName) + key;
+            mmkvStorage.remove(fullKey);
+            this.sendResult(packageName, requestId, true);
+        }
+        catch (err) {
+            console.error(`${LOG_TAG}: storage_delete error:`, err);
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: MiniappErrorCode.INTERNAL,
+                message: err instanceof Error ? err.message : "Storage error",
+            });
+        }
+    }
+    async handleStorageList(packageName, _payload, requestId) {
+        try {
+            const prefix = this.getStorageKeyPrefix(packageName);
+            const allKeys = mmkvStorage.getAllKeys();
+            const keys = allKeys.filter((k) => k.startsWith(prefix)).map((k) => k.slice(prefix.length));
+            this.sendResult(packageName, requestId, true, { keys });
+        }
+        catch (err) {
+            console.error(`${LOG_TAG}: storage_list error:`, err);
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: MiniappErrorCode.INTERNAL,
+                message: err instanceof Error ? err.message : "Storage error",
+            });
+        }
+    }
+    async handleStorageClear(packageName, requestId) {
+        try {
+            const prefix = this.getStorageKeyPrefix(packageName);
+            const allKeys = mmkvStorage.getAllKeys();
+            for (const k of allKeys) {
+                if (k.startsWith(prefix))
+                    mmkvStorage.remove(k);
+            }
+            this.sendResult(packageName, requestId, true);
+        }
+        catch (err) {
+            console.error(`${LOG_TAG}: storage_clear error:`, err);
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: MiniappErrorCode.INTERNAL,
+                message: err instanceof Error ? err.message : "Storage error",
+            });
+        }
+    }
+    async handleStorageHas(packageName, payload, requestId) {
+        try {
+            const key = payload.key;
+            if (!key) {
+                this.sendResult(packageName, requestId, false, undefined, {
+                    code: MiniappErrorCode.INTERNAL,
+                    message: "storage_has requires a key",
+                });
+                return;
+            }
+            const fullKey = this.getStorageKeyPrefix(packageName) + key;
+            const result = mmkvStorage.load(fullKey);
+            this.sendResult(packageName, requestId, true, { has: result.is_ok() });
+        }
+        catch (err) {
+            console.error(`${LOG_TAG}: storage_has error:`, err);
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: MiniappErrorCode.INTERNAL,
+                message: err instanceof Error ? err.message : "Storage error",
+            });
+        }
+    }
+    async handleStorageGetAll(packageName, requestId) {
+        try {
+            const prefix = this.getStorageKeyPrefix(packageName);
+            const allKeys = mmkvStorage.getAllKeys();
+            const values = {};
+            for (const k of allKeys) {
+                if (!k.startsWith(prefix))
+                    continue;
+                const r = mmkvStorage.load(k);
+                if (r.is_ok()) {
+                    const v = r.value;
+                    values[k.slice(prefix.length)] = typeof v === "string" ? v : String(v ?? "");
+                }
+            }
+            this.sendResult(packageName, requestId, true, { values });
+        }
+        catch (err) {
+            console.error(`${LOG_TAG}: storage_get_all error:`, err);
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: MiniappErrorCode.INTERNAL,
+                message: err instanceof Error ? err.message : "Storage error",
+            });
+        }
+    }
+    async handleStorageSetMultiple(packageName, payload, requestId) {
+        try {
+            const values = payload.values;
+            if (!values || typeof values !== "object") {
+                this.sendResult(packageName, requestId, false, undefined, {
+                    code: MiniappErrorCode.INTERNAL,
+                    message: "storage_set_multiple requires a values object",
+                });
+                return;
+            }
+            const prefix = this.getStorageKeyPrefix(packageName);
+            for (const [key, value] of Object.entries(values)) {
+                mmkvStorage.save(prefix + key, value ?? null);
+            }
+            this.sendResult(packageName, requestId, true);
+        }
+        catch (err) {
+            console.error(`${LOG_TAG}: storage_set_multiple error:`, err);
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: MiniappErrorCode.INTERNAL,
+                message: err instanceof Error ? err.message : "Storage error",
+            });
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Camera FOV
+    // ---------------------------------------------------------------------------
+    async handleCameraFov(packageName, payload, requestId) {
+        const app = this.connectedApps.get(packageName);
+        const hasCameraPermission = app?.installedManifest?.permissions?.some((p) => p.type === "CAMERA");
+        if (!hasCameraPermission) {
+            logPermissionNotDeclared(packageName, "CAMERA", "to set camera FOV", `{"type": "CAMERA"}`);
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: MiniappErrorCode.PERMISSION_NOT_DECLARED,
+                message: `CAMERA permission not declared in miniapp.json. Add {"type": "CAMERA"} to the "permissions" array.`,
+                permission: "CAMERA",
+                operation: MiniappRequestType.CAMERA_FOV,
+            });
+            return;
+        }
+        try {
+            const request = normalizeCameraFovPayload(payload);
+            const description = "preset" in request ? `preset=${request.preset}` : `fov=${request.fov} roi=${request.roiPosition ?? "center"}`;
+            console.log(`${LOG_TAG}: camera_fov_set ${description}`);
+            const result = await phoneCameraFovCoordinator.setOverride(packageName, request);
+            this.sendResult(packageName, requestId, true, result);
+        }
+        catch (err) {
+            console.error(`${LOG_TAG}: camera_fov error:`, err);
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: err.code || MiniappErrorCode.INTERNAL,
+                message: err instanceof Error ? err.message : "Camera FOV error",
+            });
+        }
+    }
+    /**
+     * Explicit IMU enable/disable from a miniapp (session.imu.setEnabled).
+     *
+     * The accel stream already auto-toggles the native IMU on subscribe (see
+     * {@link recomputeImuSubscription}); this is a direct override. We sync
+     * `this.imuEnabled` to the requested state so a subsequent subscription
+     * recompute with the same aggregate doesn't issue a redundant native call.
+     * Note that a later subscribe/unsubscribe that changes the aggregate will
+     * still re-derive the sensor state from subscriptions.
+     */
+    handleImuSetEnabled(packageName, payload, requestId) {
+        try {
+            const enabled = !!payload.enabled;
+            console.log(`${LOG_TAG}: imu_set_enabled ${enabled} (by ${packageName})`);
+            this.imuEnabled = enabled;
+            void BluetoothSdk.setImuEnabled(enabled);
+            this.sendResult(packageName, requestId, true);
+        }
+        catch (err) {
+            console.error(`${LOG_TAG}: imu_set_enabled error:`, err);
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: MiniappErrorCode.INTERNAL,
+                message: err instanceof Error ? err.message : "IMU set-enabled error",
+            });
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // System utilities (share, open URL, clipboard, download)
+    // ---------------------------------------------------------------------------
+    async handleShare(packageName, payload, requestId) {
+        const { text, title, base64, mimeType, filename, url } = payload;
+        try {
+            if (base64) {
+                // File share via base64 — write to temp file then share
+                const tempFile = new File(Paths.cache, filename || "shared_file");
+                tempFile.write(base64, { encoding: "base64" });
+                await Share.open({
+                    url: tempFile.uri,
+                    type: mimeType || "application/octet-stream",
+                    filename: filename,
+                    title: title,
+                });
+            }
+            else if (url) {
+                await Share.open({ url, title, message: text });
+            }
+            else {
+                await Share.open({ message: text || "", title });
+            }
+            this.sendResult(packageName, requestId, true, { success: true });
+        }
+        catch (error) {
+            // react-native-share throws when user dismisses the share sheet
+            if (error?.message?.includes("User did not share")) {
+                this.sendResult(packageName, requestId, true, { success: false, cancelled: true });
+            }
+            else {
+                console.error(`${LOG_TAG}: share error:`, error);
+                this.sendResult(packageName, requestId, true, { success: false });
+            }
+        }
+    }
+    async handleOpenUrl(packageName, payload) {
+        const url = payload.url;
+        if (!url || typeof url !== "string") {
+            console.warn(`${LOG_TAG}: open_url missing url`);
+            return;
+        }
+        // Block dangerous schemes
+        if (url.startsWith("javascript:") || url.startsWith("file:")) {
+            console.warn(`${LOG_TAG}: open_url blocked dangerous scheme: ${url}`);
+            return;
+        }
+        try {
+            await Linking.openURL(url);
+        }
+        catch (error) {
+            console.error(`${LOG_TAG}: open_url error:`, error);
+        }
+    }
+    async handleCopyClipboard(packageName, payload, requestId) {
+        const text = payload.text;
+        if (typeof text !== "string") {
+            console.warn(`${LOG_TAG}: copy_clipboard missing text`);
+            return;
+        }
+        try {
+            await Clipboard.setStringAsync(text);
+            this.sendResult(packageName, requestId, true);
+        }
+        catch (error) {
+            console.error(`${LOG_TAG}: clipboard error:`, error);
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: MiniappErrorCode.INTERNAL,
+                message: error?.message || "Clipboard error",
+            });
+        }
+    }
+    async handleDownload(packageName, payload, requestId) {
+        const { base64, url, mimeType, filename } = payload;
+        const name = filename || "download";
+        try {
+            let file;
+            if (base64) {
+                file = new File(Paths.cache, name);
+                file.write(base64, { encoding: "base64" });
+            }
+            else if (url) {
+                file = await File.downloadFileAsync(url, new File(Paths.cache, name), { idempotent: true });
+            }
+            else {
+                console.warn(`${LOG_TAG}: download missing base64 or url`);
+                return;
+            }
+            // Open share sheet so user can choose where to save
+            await Share.open({
+                url: file.uri,
+                type: mimeType || "application/octet-stream",
+                filename: name,
+            });
+            this.sendResult(packageName, requestId, true, { success: true });
+        }
+        catch (error) {
+            if (error?.message?.includes("User did not share")) {
+                this.sendResult(packageName, requestId, true, { success: true, cancelled: true });
+            }
+            else {
+                console.error(`${LOG_TAG}: download error:`, error);
+                this.sendResult(packageName, requestId, true, { success: false });
+            }
+        }
+    }
+    // ===========================================================================
+    // Photo + streaming handlers (cloud-coordinated)
+    // ===========================================================================
+    async handlePhoto(packageName, payload, requestId) {
+        // Manifest CAMERA permission gate.
+        const app = this.connectedApps.get(packageName);
+        const hasCameraPermission = app?.installedManifest?.permissions?.some((p) => p.type === "CAMERA");
+        if (!hasCameraPermission) {
+            logPermissionNotDeclared(packageName, "CAMERA", "to take a photo", `{"type": "CAMERA"}`);
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: MiniappErrorCode.PERMISSION_NOT_DECLARED,
+                message: `CAMERA permission not declared in miniapp.json. Add {"type": "CAMERA"} to the "permissions" array.`,
+                permission: "CAMERA",
+                operation: MiniappRequestType.PHOTO,
+            });
+            return;
+        }
+        try {
+            const result = await phonePhotoCoordinator.takePhoto(packageName, {
+                size: payload.size,
+                mode: payload.mode,
+                transferMethod: payload.transferMethod,
+                compress: payload.compress,
+                sound: payload.sound,
+                saveToGallery: payload.saveToGallery,
+                exposureTimeNs: payload.exposureTimeNs,
+                iso: payload.iso,
+                aeExposureDivisor: payload.aeExposureDivisor,
+                isoCap: payload.isoCap,
+                noiseReduction: payload.noiseReduction,
+                edgeEnhancement: payload.edgeEnhancement,
+                mfnr: payload.mfnr,
+                zsl: payload.zsl,
+                ispDigitalGain: payload.ispDigitalGain,
+                ispAnalogGain: payload.ispAnalogGain,
+            });
+            this.sendResult(packageName, requestId, true, result);
+        }
+        catch (err) {
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: err.code || MiniappErrorCode.INTERNAL,
+                message: err instanceof Error ? err.message : "Photo request failed",
+                stage: err.stage,
+                transport: err.transport,
+            });
+        }
+    }
+    async handleCameraWarmUp(packageName, payload, requestId) {
+        // Manifest CAMERA permission gate (same as photo).
+        const app = this.connectedApps.get(packageName);
+        const hasCameraPermission = app?.installedManifest?.permissions?.some((p) => p.type === "CAMERA");
+        if (!hasCameraPermission) {
+            logPermissionNotDeclared(packageName, "CAMERA", "to warm up the camera", `{"type": "CAMERA"}`);
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: MiniappErrorCode.PERMISSION_NOT_DECLARED,
+                message: `CAMERA permission not declared in miniapp.json. Add {"type": "CAMERA"} to the "permissions" array.`,
+                permission: "CAMERA",
+                operation: MiniappRequestType.CAMERA_WARM_UP,
+            });
+            return;
+        }
+        try {
+            await phonePhotoCoordinator.warmUpCamera(packageName, {
+                size: payload.size,
+                mode: payload.mode,
+                exposureTimeNs: payload.exposureTimeNs,
+                durationMs: payload.durationMs,
+            });
+            this.sendResult(packageName, requestId, true);
+        }
+        catch (err) {
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: err.code || MiniappErrorCode.INTERNAL,
+                message: err instanceof Error ? err.message : "Camera warm-up failed",
+                stage: err.stage,
+                transport: err.transport,
+            });
+        }
+    }
+    async handleVideoRecordingStart(packageName, payload, requestId) {
+        // Manifest CAMERA permission gate (same as photo).
+        const app = this.connectedApps.get(packageName);
+        const hasCameraPermission = app?.installedManifest?.permissions?.some((p) => p.type === "CAMERA");
+        if (!hasCameraPermission) {
+            logPermissionNotDeclared(packageName, "CAMERA", "to record video", `{"type": "CAMERA"}`);
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: MiniappErrorCode.PERMISSION_NOT_DECLARED,
+                message: `CAMERA permission not declared in miniapp.json. Add {"type": "CAMERA"} to the "permissions" array.`,
+                permission: "CAMERA",
+                operation: MiniappRequestType.VIDEO_RECORDING_START,
+            });
+            return;
+        }
+        try {
+            const result = await phoneVideoCoordinator.startRecording(packageName, {
+                width: payload.width,
+                height: payload.height,
+                fps: payload.fps,
+                sound: payload.sound,
+                save: payload.save,
+            });
+            this.sendResult(packageName, requestId, true, result);
+        }
+        catch (err) {
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: err.code || MiniappErrorCode.INTERNAL,
+                message: err instanceof Error ? err.message : "Video recording start failed",
+            });
+        }
+    }
+    async handleVideoRecordingStop(packageName, payload, requestId) {
+        try {
+            await phoneVideoCoordinator.stopRecording(packageName, payload.recordingId, {
+                uploadUrl: payload.uploadUrl,
+                uploadAuthToken: payload.uploadAuthToken,
+            });
+            this.sendResult(packageName, requestId, true);
+        }
+        catch (err) {
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: err.code || MiniappErrorCode.INTERNAL,
+                message: err instanceof Error ? err.message : "Video recording stop failed",
+            });
+        }
+    }
+    /**
+     * Stream handlers — dispatched to the engine PhoneStreamCoordinator. For managed
+     * streams the coordinator additionally calls the v2 client REST route to
+     * provision Cloudflare. Cloud-SDK apps (third-party developers) use a
+     * separate cloud-side path that does not pass through here.
+     */
+    async handleStreamStart(packageName, payload, requestId) {
+        const streaming = phoneStreamCoordinator;
+        if (!streaming) {
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: MiniappErrorCode.NOT_IMPLEMENTED,
+                message: "Streaming is not configured on this host",
+            });
+            return;
+        }
+        try {
+            const result = await streaming.startUnmanaged(packageName, {
+                streamUrl: payload.streamUrl,
+                video: normalizeStreamVideoConfig(payload.video),
+                audio: normalizeStreamAudioConfig(payload.audio),
+                sound: payload.sound,
+            });
+            this.sendResult(packageName, requestId, true, result);
+        }
+        catch (err) {
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: err.code || MiniappErrorCode.INTERNAL,
+                message: err instanceof Error ? err.message : "Stream start failed",
+                stage: err.stage,
+                transport: err.transport,
+            });
+        }
+    }
+    async handleStreamStop(packageName, payload, requestId) {
+        const streaming = phoneStreamCoordinator;
+        if (!streaming) {
+            // No adapter wired — treat as already-stopped.
+            this.sendResult(packageName, requestId, true);
+            return;
+        }
+        try {
+            await streaming.stop(packageName, payload.streamId);
+            this.sendResult(packageName, requestId, true);
+        }
+        catch (err) {
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: err.code || MiniappErrorCode.INTERNAL,
+                message: err instanceof Error ? err.message : "Stream stop failed",
+                stage: err.stage,
+                transport: err.transport,
+            });
+        }
+    }
+    async handleManagedStreamStart(packageName, payload, requestId) {
+        const streaming = phoneStreamCoordinator;
+        if (!streaming) {
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: MiniappErrorCode.NOT_IMPLEMENTED,
+                message: "Streaming is not configured on this host",
+            });
+            return;
+        }
+        try {
+            const result = await streaming.startManaged(packageName, {
+                restreamDestinations: payload.restreamDestinations,
+                video: normalizeStreamVideoConfig(payload.video),
+                audio: normalizeStreamAudioConfig(payload.audio),
+                sound: payload.sound,
+                ingest: payload.ingest,
+            });
+            this.sendResult(packageName, requestId, true, result);
+        }
+        catch (err) {
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: err.code || MiniappErrorCode.INTERNAL,
+                message: err instanceof Error ? err.message : "Managed stream start failed",
+                stage: err.stage,
+                transport: err.transport,
+            });
+        }
+    }
+    async handleManagedStreamStop(packageName, payload, requestId) {
+        return this.handleStreamStop(packageName, payload, requestId);
+    }
+    /**
+     * session.glasses.requestWifiSetup — open the phone's glasses Wi-Fi setup
+     * flow. The host owns the actual UI via the `engine.configure({ui})` seam;
+     * this just forwards the request and reports success/failure.
+     */
+    async handleRequestWifiSetup(packageName, payload, requestId) {
+        const requestWifiSetup = getUiSeams().requestWifiSetup;
+        if (!requestWifiSetup) {
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: MiniappErrorCode.NOT_IMPLEMENTED,
+                message: "Wi-Fi setup is not configured on this host",
+            });
+            return;
+        }
+        try {
+            await requestWifiSetup(payload.reason);
+            this.sendResult(packageName, requestId, true);
+        }
+        catch (err) {
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: err.code || MiniappErrorCode.INTERNAL,
+                message: err instanceof Error ? err.message : "Wi-Fi setup failed",
+            });
+        }
+    }
+    /**
+     * Wire the PhoneStreamCoordinator's status callback so coordinator-emitted
+     * updates become `EVENT { streamType: "stream_status" }` envelopes on the
+     * subscribing miniapp(s).
+     */
+    wireStreamingStatusFanout() {
+        const streaming = phoneStreamCoordinator;
+        if (!streaming)
+            return;
+        streaming.setStatusSubscriber((packageName, update) => {
+            this.sendToMiniapp(packageName, {
+                type: MiniappResponseType.EVENT,
+                streamType: "stream_status",
+                data: {
+                    streamId: update.streamId,
+                    status: update.status,
+                    source: update.source,
+                    ...(update.data || {}),
+                },
+            });
+        });
+    }
+    // ===========================================================================
+    // Public subscribe helper
+    // ===========================================================================
+    /**
+     * Standalone subscribe — lets external code subscribe a registered miniapp to
+     * streams without going through the envelope protocol.
+     *
+     * Returns `{ok: true}` on success, or `{ok: false, error}` on failure.
+     */
+    subscribe(packageName, streams) {
+        const app = this.connectedApps.get(packageName);
+        if (!app) {
+            return { ok: false, error: `App ${packageName} is not registered` };
+        }
+        if (!Array.isArray(streams)) {
+            return { ok: false, error: "streams must be an array" };
+        }
+        console.log(`${LOG_TAG}: subscribe(${packageName}, [${streams.join(", ")}])`);
+        // Check microphone permission for mic-requiring streams
+        const micStreams = ["transcription", "translation", "audio_chunk", "vad"];
+        const needsMic = streams.some((s) => micStreams.some((m) => s.startsWith(m) || s === m));
+        if (needsMic) {
+            const hasMicPermission = app.installedManifest?.permissions?.some((p) => p.type === "MICROPHONE");
+            if (!hasMicPermission) {
+                return { ok: false, error: "MICROPHONE permission not declared in miniapp.json" };
+            }
+        }
+        // Remove old subscriptions for this app
+        for (const oldStream of app.subscriptions) {
+            const subs = this.streamSubscribers.get(oldStream);
+            if (subs) {
+                subs.delete(packageName);
+                if (subs.size === 0) {
+                    this.streamSubscribers.delete(oldStream);
+                }
+            }
+        }
+        // Add new subscriptions
+        app.subscriptions = new Set(streams);
+        app.forceLocalTranscriptionStreams.clear();
+        app.cloudTranscriptionStreams = new Set(streams.filter((stream) => stream.startsWith("transcription:")));
+        for (const stream of streams) {
+            let subs = this.streamSubscribers.get(stream);
+            if (!subs) {
+                subs = new Set();
+                this.streamSubscribers.set(stream, subs);
+            }
+            subs.add(packageName);
+        }
+        this.recomputeMicRequirements();
+        this.updateCloudSubscriptions();
+        return { ok: true };
+    }
+    // ===========================================================================
+    // Mic requirements
+    // ===========================================================================
+    recomputeMicRequirements() {
+        let anyPcm = false;
+        let anyLc3 = false;
+        for (const [stream, subscribers] of this.streamSubscribers) {
+            if (subscribers.size === 0)
+                continue;
+            if (stream === "audio_chunk")
+                anyPcm = true;
+            if (stream.startsWith("transcription:") || stream.startsWith("translation:") || stream === "vad")
+                anyLc3 = true;
+        }
+        micStateCoordinator.setLocalRequirements({ pcm: anyPcm, lc3: anyLc3 });
+    }
+    /**
+     * Recompute the aggregated v2 cloud subscription list across all local miniapps.
+     *
+     * Cloud-dependent streams (transcription:*, translation:*) only flow if the
+     * v2 runtime knows the phone wants them. Local-only streams (button_press, etc.)
+     * are NOT sent — they come from the Bluetooth SDK, not from cloud.
+     */
+    updateCloudSubscriptions() {
+        const cloudStreams = new Set();
+        let transcriptionLang = null;
+        let forceLocalTranscriptionLang = null;
+        let hasForceLocalTranscription = false;
+        for (const [stream, subscribers] of this.streamSubscribers) {
+            if (subscribers.size === 0)
+                continue;
+            // Only transcription / translation need cloud delivery. Location and
+            // notifications are sourced natively on the phone — no cloud hop.
+            if (stream.startsWith("translation:")) {
+                cloudStreams.add(stream);
+            }
+            if (stream.startsWith("transcription:")) {
+                const language = stream.substring("transcription:".length);
+                if (transcriptionLang === null)
+                    transcriptionLang = language;
+                const routes = summarizeTranscriptionRoutes(subscribers, (packageName) => this.appTranscriptionRoutesForSubscription(packageName, stream));
+                if (routes.hasForceLocalSubscriber) {
+                    hasForceLocalTranscription = true;
+                    if (forceLocalTranscriptionLang === null)
+                        forceLocalTranscriptionLang = language;
+                }
+                if (routes.hasCloudSubscriber)
+                    cloudStreams.add(stream);
+            }
+        }
+        localSttFallbackCoordinator.onSubscriptionChange(transcriptionLang !== null, forceLocalTranscriptionLang ?? transcriptionLang, hasForceLocalTranscription);
+        // Mirror the same set as typed AudioSubscription[] and push it to the cloud
+        // runtime.
+        this.ensureCloudResultsWired();
+        const subs = this.buildCloudAudioSubscriptions(cloudStreams);
+        const nextKey = this.audioSubscriptionKey(subs);
+        if (!this.cloudAudioSubscriptionSync.begin(nextKey))
+            return;
+        console.log(`${LOG_TAG}: updateCloudSubscriptions streams=[${Array.from(cloudStreams).join(", ")}] cloudSubs=${subs.length}`);
+        cloudClientService
+            .setSubscriptions(subs)
+            .then(() => {
+            this.cloudAudioSubscriptionSync.succeeded(nextKey);
+        })
+            .catch((err) => {
+            // Best-effort: the cloud may not be connected yet. Keep failed writes
+            // retryable; otherwise a reconnect that recomputes the same desired
+            // transcription set gets deduped and local captions never recover.
+            this.cloudAudioSubscriptionSync.failed(nextKey);
+            console.warn(`${LOG_TAG}: cloud setSubscriptions failed: ${err?.message ?? err}`);
+        });
+    }
+    /**
+     * Build the cloud `AudioSubscription[]` from the miniapp cloud-stream key set.
+     *
+     * Stream keys: `transcription:<lang>` (lang may be `auto`, `en-US`, …) and
+     * `translation:<source>:<target>` (3 colon-parts; source/target may be `*`
+     * or `auto` wildcards, target may also be `*`). The cloud protocol requires a
+     * concrete `target: string` for translation, so wildcard-target translation
+     * keys (`translation:<source>:*`, `translation:*:*`, `translation:auto`) have
+     * no cloud equivalent and are skipped. Wildcard/`auto` SOURCE maps to
+     * `{mode: "auto"}`.
+     */
+    buildCloudAudioSubscriptions(cloudStreams) {
+        const subs = [];
+        const langSource = (code) => code === "auto" || code === "*" ? { mode: "auto" } : { mode: "specific", code };
+        for (const stream of cloudStreams) {
+            if (stream.startsWith("transcription:")) {
+                const lang = stream.substring("transcription:".length);
+                subs.push({ kind: "transcription", language: langSource(lang) });
+            }
+            else if (stream.startsWith("translation:")) {
+                const parts = stream.split(":");
+                // Only `translation:<source>:<target>` maps cleanly; a concrete target
+                // is required by the cloud schema.
+                if (parts.length === 3) {
+                    const [, source, target] = parts;
+                    if (target === "*")
+                        continue;
+                    subs.push({ kind: "translation", source: langSource(source), target });
+                }
+            }
+        }
+        return subs;
+    }
+    audioSubscriptionKey(subs) {
+        return JSON.stringify(subs
+            .map((sub) => {
+            if (sub.kind === "transcription") {
+                return {
+                    kind: sub.kind,
+                    language: sub.language,
+                };
+            }
+            return {
+                kind: sub.kind,
+                source: sub.source,
+                target: sub.target,
+            };
+        })
+            .sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b))));
+    }
+    /**
+     * Wire the cloud's transcription/translation results into the existing
+     * miniapp fan-out exactly once. Maps each cloud result back to the
+     * cloud-to-app data shape `forwardEvent` already forwards, keyed on the
+     * `transcription:<lang>` / `translation:<source>:<target>` stream strings, so
+     * subscribed miniapps receive identical envelopes.
+     */
+    ensureCloudResultsWired() {
+        if (this.cloudResultsWired)
+            return;
+        this.cloudResultsWired = true;
+        cloudClientService.onTranscript((d) => {
+            const receivedAt = Date.now();
+            if (TRANSCRIPT_TIMING_TELEMETRY) {
+                console.log(`${LOG_TAG}: transcript cloud_recv t=${receivedAt} final=${d.isFinal} lang=${d.resolvedLanguage} text="${d.text.slice(0, 48)}"`);
+            }
+            this.forwardEvent(`transcription:${d.resolvedLanguage}`, {
+                type: "transcription",
+                text: d.text,
+                isFinal: d.isFinal,
+                utteranceId: d.utteranceId,
+                transcribeLanguage: d.resolvedLanguage,
+                detectedLanguage: d.languageDetected ? d.resolvedLanguage : undefined,
+                startTime: d.startMs,
+                endTime: d.endMs,
+                speakerId: d.speakerId,
+                duration: d.durationMs,
+                provider: d.provider,
+                confidence: d.confidence,
+                __hostReceivedAt: receivedAt,
+            }, "cloud");
+        });
+        cloudClientService.onTranslation((d) => {
+            this.forwardEvent(`translation:${d.source.language}:${d.target.language}`, {
+                type: "translation",
+                text: d.text,
+                originalText: d.originalText,
+                isFinal: d.isFinal,
+                utteranceId: d.utteranceId,
+                startTime: d.startMs,
+                endTime: d.endMs,
+                speakerId: d.speakerId,
+                duration: d.durationMs,
+                transcribeLanguage: d.source.language,
+                translateLanguage: d.target.language,
+                didTranslate: true,
+                provider: d.provider,
+                confidence: d.confidence,
+            });
+        });
+    }
+    ensureCloudStatusWired() {
+        if (this.cloudStatusWired)
+            return;
+        this.cloudStatusWired = true;
+        cloudClientService.onStatusChanged((status) => {
+            if (status.status === "connected") {
+                this.updateCloudSubscriptions();
+                // A miniapp that connected before the cloud client was ready never got
+                // its auth token; now that we're connected, mint it without waiting for
+                // the retry backoff (or a full manual reconnect).
+                this.redriveMiniappAuthDelivery();
+            }
+            this.broadcastCloudStatus();
+        });
+        useSettingsStore.subscribe((s) => s.getSetting(ISLAND_SETTINGS_KEYS.localSttFallbackActive), () => {
+            this.broadcastCloudStatus();
+        });
+    }
+    currentCloudStatus() {
+        const base = cloudClientService.getStatus();
+        const fallbackActive = useSettingsStore.getState().getSetting(ISLAND_SETTINGS_KEYS.localSttFallbackActive) ===
+            true;
+        return {
+            status: base.status,
+            audioTransport: fallbackActive ? "offline" : base.audioTransport,
+        };
+    }
+    broadcastCloudStatus() {
+        const status = this.currentCloudStatus();
+        for (const packageName of this.connectedApps.keys()) {
+            this.sendCloudStatusToMiniapp(packageName, status);
+        }
+    }
+    sendCloudStatusToMiniapp(packageName, status = this.currentCloudStatus()) {
+        this.sendToMiniapp(packageName, {
+            type: MiniappResponseType.EVENT,
+            streamType: CLOUD_STATUS_STREAM,
+            data: status,
+        });
+    }
+    // ===========================================================================
+    // Stream fan-out
+    // ===========================================================================
+    /**
+     * Forward a streamed event to all miniapps subscribed to the given stream.
+     *
+     * Event name translation:
+     * - Cloud sends "head_up" → miniapp protocol uses "head_position" (HEAD_POSITION)
+     * - Cloud sends "VAD" (uppercase) → miniapp protocol uses "vad" (lowercase)
+     */
+    forwardEvent(streamType, data, transcriptionSource) {
+        // Translate cloud event names to miniapp protocol stream types
+        const normalizedStream = this.normalizeStreamType(streamType);
+        // Collect all subscribers: exact match, plus wildcard matches for streams
+        // that carry a language tag. A miniapp subscribed to "transcription:auto"
+        // should receive any "transcription:<lang>" event (the detected language
+        // is conveyed in the event data, not the stream key).
+        //
+        // Translation streams support cloud v3's wildcard patterns. Incoming
+        // events are keyed `translation:<source>:<target>` and we match against
+        // any of:
+        //   translation:*:*             — all-pairs (TranslationModule.on)
+        //   translation:*:<target>      — any-source → target (TranslationModule.to)
+        //   translation:<source>:*      — source → any-target (rare)
+        //   translation:<source>:<target> — exact (TranslationModule.fromTo)
+        //   translation:auto            — back-compat alias for *:*
+        const matchedSubs = new Set();
+        const exact = this.streamSubscribers.get(normalizedStream);
+        if (exact)
+            for (const p of exact)
+                matchedSubs.add(p);
+        if (normalizedStream.startsWith("transcription:")) {
+            const autoSubs = this.streamSubscribers.get("transcription:auto");
+            if (autoSubs)
+                for (const p of autoSubs)
+                    matchedSubs.add(p);
+        }
+        else if (normalizedStream.startsWith("translation:")) {
+            // translation:<source>:<target> — match each wildcard variant.
+            const parts = normalizedStream.split(":");
+            // parts[0] = "translation", parts[1] = source, parts[2] = target
+            if (parts.length === 3) {
+                const [, source, target] = parts;
+                const patterns = [
+                    "translation:auto", // legacy alias for *:*
+                    "translation:*:*", // cloud v3 "all pairs"
+                    `translation:*:${target}`, // cloud v3 "to <target>"
+                    `translation:${source}:*`, // cloud v3 "from <source>"
+                ];
+                for (const pat of patterns) {
+                    const subs = this.streamSubscribers.get(pat);
+                    if (subs)
+                        for (const p of subs)
+                            matchedSubs.add(p);
+                }
+            }
+            else {
+                // Malformed stream key — still honor the legacy auto alias.
+                const autoSubs = this.streamSubscribers.get("translation:auto");
+                if (autoSubs)
+                    for (const p of autoSubs)
+                        matchedSubs.add(p);
+            }
+        }
+        // Touch event per-gesture fan-out. SDK-side dispatch is keyed on the
+        // exact streamType, so per-gesture subscribers (`touch_event:single_tap`,
+        // etc.) need their own EVENT envelope with the gesture-tagged streamType.
+        // The bare `touch_event` stream above still catches `onTouch(handler)`.
+        let perGestureStream = null;
+        let outboundData = data;
+        if (normalizedStream === MiniappStreamType.TOUCH_EVENT) {
+            // The Bluetooth SDK delivers the gesture under `gestureName` (single_tap /
+            // double_tap / triple_tap / long_press / swipe_up / swipe_down). Surface it
+            // to miniapps as `TouchData.kind` and tag a per-gesture stream so
+            // onTouch("single_tap", ...) routes correctly.
+            const touch = data;
+            const gesture = touch?.gestureName ?? touch?.kind;
+            if (typeof gesture === "string" && gesture.length > 0) {
+                outboundData = { ...touch, kind: gesture };
+                perGestureStream = `${MiniappStreamType.TOUCH_EVENT}:${gesture}`;
+            }
+        }
+        if (normalizedStream.startsWith("transcription:")) {
+            // const known = Array.from(this.streamSubscribers.keys())
+            // console.log(
+            //   `${LOG_TAG}: forwardEvent(${streamType} → ${normalizedStream}) matched=${matchedSubs.size} known=[${known.join(", ")}]`,
+            // )
+        }
+        if (matchedSubs.size === 0 && !perGestureStream)
+            return;
+        for (const packageName of matchedSubs) {
+            let transcriptionRoute;
+            if (normalizedStream.startsWith("transcription:") && transcriptionSource) {
+                const routes = this.appTranscriptionRoutesForEvent(packageName, normalizedStream);
+                transcriptionRoute =
+                    transcriptionDeliveryRoute(transcriptionSource, routes, cloudClientService.isConnected()) ?? undefined;
+                if (!transcriptionRoute)
+                    continue;
+            }
+            if (TRANSCRIPT_TIMING_TELEMETRY && normalizedStream.startsWith("transcription:")) {
+                const transcript = data;
+                const now = Date.now();
+                console.log(`${LOG_TAG}: transcript fanout t=${now} app=${packageName} final=${!!transcript?.isFinal} hostDelta=${transcript?.__hostReceivedAt ? now - transcript.__hostReceivedAt : -1}ms text="${(transcript?.text ?? "").slice(0, 48)}"`);
+            }
+            // While a nav trip is active the Nav SDK's road-snapped fixes are
+            // already being forwarded via addLocationListener (see NAV_START handler).
+            // Suppress the raw background-GPS forward for that miniapp so the two
+            // streams don't interleave and cause the position to jump back to the
+            // real-phone location during simulation.
+            if (normalizedStream === MiniappStreamType.LOCATION_UPDATE && this.navigationHandlers.isTripActive(packageName)) {
+                continue;
+            }
+            this.sendToMiniapp(packageName, {
+                type: MiniappResponseType.EVENT,
+                streamType: normalizedStream,
+                data: outboundData,
+                ...(transcriptionRoute ? { transcriptionRoute } : {}),
+            });
+        }
+        // Send a separate envelope to per-gesture subscribers tagged with the
+        // gesture-specific streamType so SDK-side dispatch routes correctly.
+        if (perGestureStream) {
+            const gestureSubs = this.streamSubscribers.get(perGestureStream);
+            if (gestureSubs) {
+                for (const packageName of gestureSubs) {
+                    this.sendToMiniapp(packageName, {
+                        type: MiniappResponseType.EVENT,
+                        streamType: perGestureStream,
+                        data: outboundData,
+                    });
+                }
+            }
+        }
+    }
+    appTranscriptionRoutesForSubscription(packageName, stream) {
+        const app = this.connectedApps.get(packageName);
+        return {
+            cloud: app?.cloudTranscriptionStreams.has(stream) === true,
+            forceLocal: app?.forceLocalTranscriptionStreams.has(stream) === true,
+        };
+    }
+    appTranscriptionRoutesForEvent(packageName, stream) {
+        const app = this.connectedApps.get(packageName);
+        const autoStream = `${MiniappStreamType.TRANSCRIPTION}:auto`;
+        return {
+            cloud: app?.cloudTranscriptionStreams.has(stream) === true || app?.cloudTranscriptionStreams.has(autoStream) === true,
+            forceLocal: app?.forceLocalTranscriptionStreams.has(stream) === true ||
+                app?.forceLocalTranscriptionStreams.has(autoStream) === true,
+        };
+    }
+    /**
+     * Translate cloud event names to miniapp stream type values.
+     */
+    normalizeStreamType(cloudEventName) {
+        // Cloud / Bluetooth SDK → miniapp protocol translations.
+        // Bluetooth SDK event names don't always match the miniapp wire values.
+        switch (cloudEventName) {
+            case "head_up":
+                return MiniappStreamType.HEAD_POSITION; // head_up → head_position
+            case "accel_event":
+                return MiniappStreamType.ACCEL_DATA; // accel_event (native) → accel_data
+            case "VAD":
+                return MiniappStreamType.VAD; // VAD (uppercase) → vad (lowercase)
+            case "glasses_battery_update":
+                return MiniappStreamType.GLASSES_BATTERY; // glasses_battery_update → glasses_battery
+            case "glasses_connection_state":
+                return MiniappStreamType.GLASSES_CONNECTION; // glasses_connection_state → glasses_connection
+            default:
+                // Preserve case for typed streams like "transcription:en-US" / "translation:en-US:fr-FR"
+                // whose language tags are case-sensitive (BCP-47). Lowercase only plain names.
+                if (cloudEventName.includes(":"))
+                    return cloudEventName;
+                return cloudEventName.toLowerCase();
+        }
+    }
+    // ===========================================================================
+    // Outbound helpers
+    // ===========================================================================
+    /**
+     * Send a payload to a connected miniapp, wrapped in an envelope.
+     */
+    /**
+     * Push a speaker-state transition to the owning miniapp. Idempotent: if
+     * the new state matches the cached one (and isn't an error), no envelope
+     * is sent. Error events are always sent — they're transient and the SDK
+     * settles back to a non-error state immediately after.
+     */
+    setSpeakerState(packageName, next, extra) {
+        const app = this.connectedApps.get(packageName);
+        if (!app)
+            return;
+        if (app.speakerState === next && next !== "error")
+            return;
+        app.speakerState = next === "error" ? "error" : next;
+        this.sendToMiniapp(packageName, {
+            type: MiniappResponseType.SPEAKER_STATE,
+            state: next,
+            ...(extra?.errorCode !== undefined ? { errorCode: extra.errorCode } : {}),
+            ...(extra?.errorMessage !== undefined ? { errorMessage: extra.errorMessage } : {}),
+            ...(extra?.durationMs !== undefined ? { durationMs: extra.durationMs } : {}),
+        });
+        // After an error event, immediately transition to "stopped" so the
+        // SDK's isPlaying getter reads false and a new play()/speak() call
+        // starts cleanly from idle/stopped.
+        if (next === "error") {
+            app.speakerState = "stopped";
+            this.sendToMiniapp(packageName, {
+                type: MiniappResponseType.SPEAKER_STATE,
+                state: "stopped",
+            });
+        }
+    }
+    sendToMiniapp(packageName, payload, requestId) {
+        const app = this.connectedApps.get(packageName);
+        if (!app) {
+            console.warn(`${LOG_TAG}: sendToMiniapp — ${packageName} not connected`);
+            return;
+        }
+        const envelope = {
+            payload,
+            requestId,
+        };
+        const serialized = serializeEnvelope(envelope);
+        if (payload?.streamType?.toString().startsWith("transcription")) {
+            // console.log(
+            //   `${LOG_TAG}: sendToMiniapp → ${packageName} streamType=${(payload as Record<string, unknown>).streamType}`,
+            // )
+        }
+        try {
+            app.sendMessage(serialized);
+        }
+        catch (err) {
+            console.error(`${LOG_TAG}: sendToMiniapp error for ${packageName}:`, err);
+        }
+    }
+    /**
+     * Send a REQUEST_RESULT response.
+     */
+    // ===========================================================================
+    // Inter-miniapp interop (session.miniapps + session.actions.invoke)
+    // ===========================================================================
+    /** Max serialized size of an action call's params / result (256 KB). */
+    static ACTION_PAYLOAD_CAP = 256 * 1024;
+    /** Outstanding action invocations, keyed by host-generated callId. */
+    actionCalls = new Map();
+    actionCallSeq = 0;
+    interopApps() {
+        return useAppStatusStore.getState().apps;
+    }
+    isSystemPackage(packageName) {
+        if (SYSTEM_MINIAPP_PACKAGES.has(packageName))
+            return true;
+        return this.interopApps().find((app) => app.packageName === packageName)?.isMiniappDev === true;
+    }
+    async startInteropApp(packageName) {
+        const app = this.interopApps().find((a) => a.packageName === packageName);
+        if (!app)
+            return false;
+        if (app.local) {
+            await miniappLauncher.ensureConnected(packageName);
+            return true;
+        }
+        return useAppStatusStore.getState().start(app, { skipNavigation: true });
+    }
+    stopInteropApp(packageName) {
+        return useAppStatusStore.getState().stop(packageName);
+    }
+    wakeInteropApp(packageName) {
+        return miniappLauncher.ensureConnected(packageName);
+    }
+    /** Emit an interop audit event (best-effort — never let telemetry break a call). */
+    auditInterop(event) {
+        try {
+            getAnalytics()?.("miniapp_interop", {
+                caller: event.caller,
+                op: event.op,
+                target: event.target ?? "",
+                actionId: event.actionId ?? "",
+                ok: event.ok,
+                errorCode: event.errorCode ?? "",
+            });
+        }
+        catch {
+            /* telemetry must never break an interop call */
+        }
+    }
+    /** Reject the request with NOT_PERMITTED unless the caller is a system app. */
+    requireSystemCaller(packageName, requestId, op, target) {
+        if (this.isSystemPackage(packageName))
+            return true;
+        this.auditInterop({ caller: packageName, op, target, ok: false, errorCode: MiniappErrorCode.NOT_PERMITTED });
+        this.sendResult(packageName, requestId, false, undefined, {
+            code: MiniappErrorCode.NOT_PERMITTED,
+            message: "Inter-miniapp APIs are restricted to system apps",
+        });
+        return false;
+    }
+    /** Project a host ClientApp into the SDK's MiniappInfo shape (JSON over the wire). */
+    buildMiniappInfo(app) {
+        const compatibility = app.compatibility ?? {
+            isCompatible: true,
+            missingRequired: [],
+            missingOptional: [],
+            warnings: [],
+        };
+        return {
+            packageName: app.packageName,
+            name: app.name,
+            version: app.version ?? "",
+            running: app.running,
+            compatibility,
+            actions: app.actions ?? [],
+        };
+    }
+    handleMiniappsList(packageName, payload, requestId) {
+        if (!this.requireSystemCaller(packageName, requestId, "list"))
+            return;
+        const includeIncompatible = payload.includeIncompatible === true;
+        const infos = this.interopApps()
+            .filter((a) => a.packageName &&
+            a.packageName !== packageName &&
+            !a.packageName.includes("@empty") &&
+            (includeIncompatible || a.compatibility?.isCompatible !== false))
+            .map((a) => this.buildMiniappInfo(a));
+        this.sendResult(packageName, requestId, true, infos);
+        this.auditInterop({ caller: packageName, op: "list", ok: true });
+    }
+    async handleMiniappsStart(packageName, payload, requestId) {
+        const target = payload.packageName;
+        if (!this.requireSystemCaller(packageName, requestId, "start", target))
+            return;
+        const app = target ? this.interopApps().find((a) => a.packageName === target) : undefined;
+        if (!target || !app) {
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: MiniappErrorCode.APP_NOT_FOUND,
+                message: `Miniapp not found: ${target ?? "(missing packageName)"}`,
+            });
+            this.auditInterop({
+                caller: packageName,
+                op: "start",
+                target,
+                ok: false,
+                errorCode: MiniappErrorCode.APP_NOT_FOUND,
+            });
+            return;
+        }
+        // Pre-flight the hardware gate so the caller gets a precise reason rather
+        // than a generic rejection (start()'s own gate would otherwise alert + abort).
+        if (app.compatibility && app.compatibility.isCompatible === false) {
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: MiniappErrorCode.APP_NOT_COMPATIBLE,
+                message: `${target} is not compatible with the connected glasses`,
+            });
+            islandNotifications.emit({
+                kind: "version_incompatible",
+                packageName: target,
+                reason: `${target} is not compatible with the connected glasses`,
+                metadata: { missingRequired: app.compatibility.missingRequired ?? [], via: "miniapps.start" },
+                timestamp: Date.now(),
+            });
+            this.auditInterop({
+                caller: packageName,
+                op: "start",
+                target,
+                ok: false,
+                errorCode: MiniappErrorCode.APP_NOT_COMPATIBLE,
+            });
+            return;
+        }
+        try {
+            // startInteropApp resolves to false when the app-store gate rejected the
+            // launch or the background context failed to spawn — don't report success.
+            const started = await this.startInteropApp(target);
+            if (started) {
+                this.sendResult(packageName, requestId, true);
+                this.auditInterop({ caller: packageName, op: "start", target, ok: true });
+            }
+            else {
+                this.sendResult(packageName, requestId, false, undefined, {
+                    code: MiniappErrorCode.INTERNAL,
+                    message: `start of ${target} was rejected by the host (gated or failed to spawn)`,
+                });
+                this.auditInterop({
+                    caller: packageName,
+                    op: "start",
+                    target,
+                    ok: false,
+                    errorCode: MiniappErrorCode.INTERNAL,
+                });
+            }
+        }
+        catch (e) {
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: MiniappErrorCode.INTERNAL,
+                message: e?.message ?? "start failed",
+            });
+            this.auditInterop({
+                caller: packageName,
+                op: "start",
+                target,
+                ok: false,
+                errorCode: MiniappErrorCode.INTERNAL,
+            });
+        }
+    }
+    async handleMiniappsStop(packageName, payload, requestId) {
+        const target = payload.packageName;
+        if (!this.requireSystemCaller(packageName, requestId, "stop", target))
+            return;
+        if (!target) {
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: MiniappErrorCode.APP_NOT_FOUND,
+                message: "stop requires a packageName",
+            });
+            return;
+        }
+        try {
+            await this.stopInteropApp(target);
+            this.sendResult(packageName, requestId, true);
+            this.auditInterop({ caller: packageName, op: "stop", target, ok: true });
+        }
+        catch (e) {
+            this.sendResult(packageName, requestId, false, undefined, {
+                code: MiniappErrorCode.INTERNAL,
+                message: e?.message ?? "stop failed",
+            });
+        }
+    }
+    /** True iff `value` serializes larger than the action payload cap. */
+    actionPayloadTooLarge(value) {
+        try {
+            return JSON.stringify(value ?? null).length > LocalMiniappRuntime.ACTION_PAYLOAD_CAP;
+        }
+        catch {
+            // Unserializable — let it through; the transport's own serialize handles it.
+            return false;
+        }
+    }
+    /**
+     * session.actions.invoke → wake the target headlessly, deliver an ACTION_CALL,
+     * and correlate its ACTION_RESULT back to the caller's pending request.
+     */
+    async handleActionInvoke(callerPackageName, payload, requestId) {
+        const targetForGate = payload.targetPackageName;
+        if (!this.requireSystemCaller(callerPackageName, requestId, "invoke", targetForGate))
+            return;
+        const target = payload.targetPackageName;
+        const actionId = payload.actionId;
+        const params = payload.params ?? {};
+        // Floor the timeout at 6s so the host never rejects with ACTION_TIMEOUT before
+        // the target SDK's handler-registration window closes. A freshly-woken miniapp
+        // buffers an undelivered ACTION_CALL for HANDLER_WAIT_MS (5s in @mentra/miniapp's
+        // actions module) waiting for session.actions.handle; a shorter host timeout
+        // could fire while the target is still registering, then the action would run
+        // with no caller left to receive its result. 6s = that 5s buffer + 1s for the
+        // ACTION_RESULT/NO_ACTION_HANDLER reply to travel back. Keep these in sync.
+        const timeoutMs = Math.min(Math.max(Number(payload.timeoutMs) || 30_000, 6_000), 120_000);
+        if (this.actionPayloadTooLarge(params)) {
+            this.sendResult(callerPackageName, requestId, false, undefined, {
+                code: MiniappErrorCode.PAYLOAD_TOO_LARGE,
+                message: "action params exceeded the 256 KB cap",
+            });
+            return;
+        }
+        const app = target ? this.interopApps().find((a) => a.packageName === target) : undefined;
+        if (!target || !app) {
+            this.sendResult(callerPackageName, requestId, false, undefined, {
+                code: MiniappErrorCode.APP_NOT_FOUND,
+                message: `Miniapp not found: ${target ?? "(missing targetPackageName)"}`,
+            });
+            return;
+        }
+        if (!actionId) {
+            this.sendResult(callerPackageName, requestId, false, undefined, {
+                code: MiniappErrorCode.ACTION_NOT_FOUND,
+                message: "invoke requires an actionId",
+            });
+            return;
+        }
+        if (app.compatibility && app.compatibility.isCompatible === false) {
+            this.sendResult(callerPackageName, requestId, false, undefined, {
+                code: MiniappErrorCode.APP_NOT_COMPATIBLE,
+                message: `${target} is not compatible with the connected glasses`,
+            });
+            islandNotifications.emit({
+                kind: "version_incompatible",
+                packageName: target,
+                reason: `${target} is not compatible with the connected glasses`,
+                metadata: { missingRequired: app.compatibility.missingRequired ?? [], via: "miniapps.invoke" },
+                timestamp: Date.now(),
+            });
+            return;
+        }
+        // Declared-action gate — only once the host populates app.actions (Phase 2);
+        // until then app.actions is undefined and we fall through to NO_ACTION_HANDLER.
+        if (!(app.actions ?? []).some((a) => a.id === actionId)) {
+            this.sendResult(callerPackageName, requestId, false, undefined, {
+                code: MiniappErrorCode.ACTION_NOT_FOUND,
+                message: `${target} does not declare action "${actionId}"`,
+            });
+            return;
+        }
+        // Headless wake + wait for CONNECT (idempotent / fast if already connected).
+        try {
+            await this.wakeInteropApp(target);
+        }
+        catch (e) {
+            this.sendResult(callerPackageName, requestId, false, undefined, {
+                code: MiniappErrorCode.WAKE_FAILED,
+                message: e?.message ?? `failed to wake ${target}`,
+            });
+            return;
+        }
+        // The wake waited for CONNECT, but the target could have dropped in the gap
+        // before delivery — fail fast rather than arming a timer for a call that
+        // sendToMiniapp would silently drop (the caller would otherwise wait the
+        // full invoke timeout for an ACTION_CALL that was never delivered).
+        if (!this.connectedApps.has(target)) {
+            this.sendResult(callerPackageName, requestId, false, undefined, {
+                code: MiniappErrorCode.WAKE_FAILED,
+                message: `${target} disconnected before the action could be delivered`,
+            });
+            this.auditInterop({
+                caller: callerPackageName,
+                op: "invoke",
+                target,
+                actionId,
+                ok: false,
+                errorCode: MiniappErrorCode.WAKE_FAILED,
+            });
+            return;
+        }
+        // Deliver the call and arm the handler timeout; ACTION_RESULT resolves it.
+        const callId = `act-${Date.now().toString(36)}-${this.actionCallSeq++}`;
+        const timer = BgTimer.setTimeout(() => {
+            this.actionCalls.delete(callId);
+            this.sendResult(callerPackageName, requestId, false, undefined, {
+                code: MiniappErrorCode.ACTION_TIMEOUT,
+                message: `action "${actionId}" timed out after ${timeoutMs}ms`,
+            });
+        }, timeoutMs);
+        this.actionCalls.set(callId, { callerPackageName, targetPackageName: target, callerRequestId: requestId, timer });
+        this.sendToMiniapp(target, {
+            type: MiniappResponseType.ACTION_CALL,
+            callId,
+            actionId,
+            params,
+            callerPackageName,
+        });
+        this.auditInterop({ caller: callerPackageName, op: "invoke", target, actionId, ok: true });
+    }
+    /** Target → host: forward an ACTION_RESULT back to the caller's pending invoke. */
+    handleActionResult(targetPackageName, payload) {
+        const callId = payload.callId;
+        if (!callId)
+            return;
+        const pending = this.actionCalls.get(callId);
+        if (!pending)
+            return;
+        // Only the invoked target may resolve this call. callIds are guessable
+        // (timestamp + seq), so a different connected miniapp must not be able to
+        // spoof a result/error for someone else's invoke.
+        if (pending.targetPackageName !== targetPackageName)
+            return;
+        this.actionCalls.delete(callId);
+        BgTimer.clearTimeout(pending.timer);
+        if (payload.ok === true) {
+            const result = payload.result;
+            if (this.actionPayloadTooLarge(result)) {
+                this.sendResult(pending.callerPackageName, pending.callerRequestId, false, undefined, {
+                    code: MiniappErrorCode.PAYLOAD_TOO_LARGE,
+                    message: "action result exceeded the 256 KB cap",
+                });
+                return;
+            }
+            this.sendResult(pending.callerPackageName, pending.callerRequestId, true, result ?? null);
+        }
+        else {
+            const error = payload.error ?? {
+                code: MiniappErrorCode.INTERNAL,
+                message: "action handler error",
+            };
+            this.sendResult(pending.callerPackageName, pending.callerRequestId, false, undefined, error);
+        }
+    }
+    sendResult(packageName, requestId, ok, data, error) {
+        if (!requestId)
+            return;
+        this.sendToMiniapp(packageName, {
+            type: MiniappResponseType.REQUEST_RESULT,
+            requestId,
+            ok,
+            ...(data !== undefined ? { data } : {}),
+            ...(error ? { error } : {}),
+        }, requestId);
+    }
+    /**
+     * Send a VISIBILITY_CHANGE push to a miniapp.
+     */
+    sendVisibilityChange(packageName, visibility) {
+        this.sendToMiniapp(packageName, {
+            type: MiniappResponseType.VISIBILITY_CHANGE,
+            visibility,
+        });
+    }
+    /**
+     * Fast foreground liveness check used when a local miniapp UI is opened or
+     * resumed. The normal watchdog intentionally waits ~30s to avoid killing a
+     * healthy-but-busy background script. When the user is actively looking at a
+     * WebView, a stale JSContext reads as "cloud offline" / no captions, so probe
+     * immediately and reuse the crash-respawn path if no message comes back.
+     */
+    probeForegroundLiveness(packageName, reason = "foreground-open", timeoutMs = FOREGROUND_LIVENESS_PROBE_TIMEOUT_MS) {
+        const app = this.connectedApps.get(packageName);
+        if (!app)
+            return;
+        this.clearForegroundProbe(packageName);
+        const probeStartedAt = Date.now();
+        this.sendToMiniapp(packageName, {
+            type: MiniappRequestType.PING,
+        });
+        const timerId = BgTimer.setTimeout(() => {
+            this.foregroundProbeTimers.delete(packageName);
+            const current = this.connectedApps.get(packageName);
+            if (!current)
+                return;
+            if (current.lastPongAt >= probeStartedAt)
+                return;
+            console.warn(`${LOG_TAG}: ${packageName} failed foreground liveness probe (${reason}), respawning`);
+            this.unregisterApp(packageName);
+            this.onLivenessTimeout?.(packageName);
+        }, timeoutMs);
+        this.foregroundProbeTimers.set(packageName, timerId);
+    }
+    // ===========================================================================
+    // Ping / pong liveness
+    // ===========================================================================
+    ensurePingLoop() {
+        if (this.pingIntervalId !== null)
+            return;
+        this.pingIntervalId = BgTimer.setInterval(() => {
+            this.doPingRound();
+        }, PING_INTERVAL_MS);
+    }
+    stopPingLoop() {
+        if (this.pingIntervalId !== null) {
+            BgTimer.clearInterval(this.pingIntervalId);
+            this.pingIntervalId = null;
+        }
+    }
+    doPingRound() {
+        const now = Date.now();
+        const staleThreshold = PING_INTERVAL_MS * PING_TIMEOUT_THRESHOLD;
+        const toRemove = [];
+        for (const [packageName, app] of this.connectedApps) {
+            if (now - app.lastPongAt > staleThreshold) {
+                console.warn(`${LOG_TAG}: ${packageName} missed ${PING_TIMEOUT_THRESHOLD} pings, unregistering`);
+                toRemove.push(packageName);
+                continue;
+            }
+            // Send PING — SDK auto-replies with PONG
+            this.sendToMiniapp(packageName, {
+                type: MiniappRequestType.PING,
+            });
+        }
+        for (const pkg of toRemove) {
+            this.unregisterApp(pkg);
+            // Hand the package to the router's respawn machinery — a missed-pings
+            // death is treated like a crash so the background script comes back.
+            this.onLivenessTimeout?.(pkg);
+        }
+    }
+    /**
+     * Called when a PONG is received from a miniapp (or any message, really).
+     * Updates lastPongAt to keep the app alive.
+     */
+    handlePong(packageName) {
+        const app = this.connectedApps.get(packageName);
+        if (app) {
+            app.lastPongAt = Date.now();
+            this.clearForegroundProbe(packageName);
+        }
+    }
+    clearForegroundProbe(packageName) {
+        const timerId = this.foregroundProbeTimers.get(packageName);
+        if (timerId == null)
+            return;
+        BgTimer.clearTimeout(timerId);
+        this.foregroundProbeTimers.delete(packageName);
+    }
+    // ===========================================================================
+    // Lifecycle
+    // ===========================================================================
+    cleanup() {
+        console.log(`${LOG_TAG}: cleanup()`);
+        this.stopPingLoop();
+        // Copy keys since unregisterApp mutates the map
+        const packageNames = [...this.connectedApps.keys()];
+        for (const pkg of packageNames) {
+            this.unregisterApp(pkg);
+        }
+        // Belt-and-suspenders: clear any remaining state
+        this.pendingCloudRequests.clear();
+        this.streamSubscribers.clear();
+        this.connectedApps.clear();
+        for (const timerId of this.foregroundProbeTimers.values()) {
+            BgTimer.clearTimeout(timerId);
+        }
+        this.foregroundProbeTimers.clear();
+        LocalMiniappRuntime.instance = null;
+    }
+    /**
+     * Number of currently connected miniapps (for diagnostics).
+     */
+    get connectedAppCount() {
+        return this.connectedApps.size;
+    }
+}
+const localMiniappRuntime = LocalMiniappRuntime.getInstance();
+export default localMiniappRuntime;
+//# sourceMappingURL=LocalMiniappRuntime.js.map