@glassly/engine 0.3.0-dev.462 → 0.3.0-dev.469

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glassly/engine",
-  "version": "0.3.0-dev.462",
+  "version": "0.3.0-dev.469",
   "description": "Glassly Engine — miniapp registry, WebView bridge, and miniapp store",
   "main": "build/index.js",
   "react-native": "src/index.ts",
@@ -97,17 +97,17 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@glassly/bluetooth-sdk": "0.3.0-dev.462",
-    "@glassly/cloud-client": "0.3.0-dev.462",
-    "@glassly/cloud-protocol": "0.3.0-dev.462",
-    "@glassly/crust": "0.3.0-dev.462",
-    "@glassly/miniapp": "0.3.0-dev.462",
+    "@glassly/bluetooth-sdk": "0.3.0-dev.469",
+    "@glassly/cloud-client": "0.3.0-dev.469",
+    "@glassly/cloud-protocol": "0.3.0-dev.469",
+    "@glassly/crust": "0.3.0-dev.469",
+    "@glassly/miniapp": "0.3.0-dev.469",
     "buffer": "^6.0.3",
     "events": "^3.3.0",
     "react-native-marked": "8.1.1",
     "semver": "^7.7.4",
     "typesafe-ts": "^1.7.1",
-    "@glassly/llm-providers": "0.3.0-dev.462"
+    "@glassly/llm-providers": "0.3.0-dev.469"
   },
   "devDependencies": {
     "@glassly/llm-providers": "workspace:*",

package/src/facades/miniapps.ts

@@ -10,6 +10,7 @@
  */
 import {useAppStatusStore} from "../stores/apps"
 import localMiniappRuntime from "../services/LocalMiniappRuntime"
+import {activeDashboardAmong} from "../services/pages/activeDashboard"
 import type {ClientApp} from "../types"
 
 type AppsState = ReturnType<typeof useAppStatusStore.getState>
@@ -61,4 +62,12 @@ export const miniapps = {
     useAppStatusStore.getState().setHiddenStatus(...args),
   /** Mark a miniapp Always On (starts at launch, stops only from the switcher pill), persisted for the next boot. */
   setAlwaysOn: (...args: Parameters<AppsState["setAlwaysOn"]>) => useAppStatusStore.getState().setAlwaysOn(...args),
+
+  /** Installed miniapps that can hold the dashboard role (manifest type "dashboard"). */
+  dashboards: (): ClientApp[] => useAppStatusStore.getState().apps.filter((app) => app.type === "dashboard"),
+  /** The package that holds the dashboard role, or null when no dashboard is installed. */
+  activeDashboard: (): string | null => activeDashboardAmong(useAppStatusStore.getState().apps),
+  /** Give the dashboard role to an installed dashboard; the previous holder stops and the new one starts. */
+  setActiveDashboard: (...args: Parameters<AppsState["setActiveDashboard"]>) =>
+    useAppStatusStore.getState().setActiveDashboard(...args),
 }

package/src/generated/releaseMetadata.ts

@@ -12,9 +12,9 @@ export interface EngineReleaseMetadata {
 export const ENGINE_RELEASE_METADATA: Readonly<EngineReleaseMetadata> = Object.freeze({
   "schemaVersion": 1,
   "familyBaseVersion": "0.3.0",
-  "releaseIdentity": "0.3.0-dev.462",
-  "releaseSetId": "glassly-0.3.0-dev.462",
-  "sourceCommit": "6d9eaccddb17582a14925742c5da672feeca3cee",
+  "releaseIdentity": "0.3.0-dev.469",
+  "releaseSetId": "glassly-0.3.0-dev.469",
+  "sourceCommit": "5abdf2c55c0f8f25cf402afca85f7677c753443f",
   "otaManifestUrl": null,
   "otaManifestSha256": null
 })

package/src/index.ts

@@ -182,6 +182,8 @@ export {
   useUninstall,
   useActiveApps,
   useRunningAlwaysOnApps,
+  useDashboards,
+  useActiveDashboard,
   useActiveBackgroundApps,
   useBackgroundApps,
   useActiveForegroundApp,

package/src/services/AppRegistry.ts

@@ -76,7 +76,7 @@ export function normalizeManifestPermissions(
 }
 
 function normalizeManifestType(raw: unknown): AppletType {
-  return raw === "background" || raw === "system_dashboard" || raw === "standard" ? raw : "standard"
+  return raw === "background" || raw === "dashboard" || raw === "standard" ? raw : "standard"
 }
 
 /**

package/src/services/LocalMiniappRuntime.ts

@@ -77,7 +77,19 @@ import {
   validateSettingsSet,
   type DerivedSettingsKey,
 } from "./settingsBridge"
-import {addOverlayApp, displayViewsFor, isOverlayApp, removeOverlayApp, setOverlayViewer} from "./pages/overlayApps"
+import {mayUsePermission} from "./miniappPermissions"
+import {activeDashboardAmong} from "./pages/activeDashboard"
+import {
+  activeDashboard,
+  addDashboardApp,
+  displayViewsFor,
+  isDashboardApp,
+  isOverlayApp,
+  onOverlayAppsChange,
+  removeDashboardApp,
+  setActiveDashboard,
+  setOverlayViewer,
+} from "./pages/overlayApps"
 import {pagesEligible} from "./pages/pageEligibility"
 import nativeNavigationService from "./NativeNavigationService"
 import type {DisplayPayload} from "./LocalDisplayManager"
@@ -253,9 +265,6 @@ const SYSTEM_MINIAPP_PACKAGES = new Set([
   "com.glassly.ai",
   "com.glassly.feedback",
   "com.glassly.miniappdev",
-  // The dashboard: the settings bridge and the miniapp list/start/stop are its side menu and settings
-  // page, and the notification app list is its notification settings' per-app filter.
-  "com.glassly.dashboard",
 ])
 const PING_INTERVAL_MS = 5_000
 // Min gap between "transcription limit reached" notices on the glasses. A
@@ -342,6 +351,8 @@ const PERMISSION_TYPE_TO_CANONICAL: Record<string, string> = {
   MEMORY: "memory",
   AI: "ai",
   SPEAKERS: "speakers",
+  MANAGE_MINIAPPS: "manageMiniapps",
+  PLATFORM_SETTINGS: "platformSettings",
 }
 
 /**
@@ -456,6 +467,8 @@ const ALL_CANONICAL_PERMISSIONS = [
   "ai",
   "speakers",
   "displayMirror",
+  "manageMiniapps",
+  "platformSettings",
 ] as const
 
 /**
@@ -1163,11 +1176,11 @@ class LocalMiniappRuntime {
     // Drop this app's transcription hints; the cloud subscription rebuild
     // below (via replaceStreamSubscribers) re-derives the hint union without it.
     this.transcriptionHintsByApp.delete(packageName)
-    // An overlay app is going: release the slot if it holds it, and drop the
+    // A dashboard is going: release the slot if it holds it, and drop the
     // dashboard view from its capabilities record.
-    if (isOverlayApp(packageName)) {
+    if (isDashboardApp(packageName)) {
       overlayPages.remove(packageName)
-      removeOverlayApp(packageName)
+      removeDashboardApp(packageName)
     }
     // Its gesture claims go back to whoever claimed them before.
     this.applyGestureClaimChanges(dropGestureClaims(this.gestureClaims, packageName))
@@ -1551,7 +1564,11 @@ class LocalMiniappRuntime {
         this.handleOpenUrl(packageName, payload)
         break
       case MiniappRequestType.DISPLAY_DIAGNOSTICS: {
-        const enabled = useSettingsStore.getState().getSetting(SETTINGS.debug_console.key) === true
+        // The records are parsed out of the G2PERF lines, which the SDK only logs while g2_perf_logs is on.
+        const settings = useSettingsStore.getState()
+        const enabled =
+          settings.getSetting(SETTINGS.debug_console.key) === true &&
+          settings.getSetting(SETTINGS.g2_perf_logs.key) === true
         this.sendResult(packageName, requestId, true, {
           enabled,
           generatedAt: Date.now(),
@@ -1748,9 +1765,12 @@ class LocalMiniappRuntime {
     existing.lastPongAt = Date.now()
     existing.unansweredPingRounds = 0
 
-    // A system_dashboard app may take the overlay slot: its capabilities
-    // carry the dashboard view from the start.
-    if (existing.installedManifest?.type === "system_dashboard") addOverlayApp(packageName)
+    // The dashboard that holds the role may take the overlay slot: its
+    // capabilities carry the dashboard view from the start.
+    if (existing.installedManifest?.type === "dashboard") {
+      addDashboardApp(packageName)
+      this.syncActiveDashboard()
+    }
     const capabilities = this.capabilitiesFor(packageName)
 
     // Build the declared-permission record for the SDK's session.permissions
@@ -2133,12 +2153,11 @@ class LocalMiniappRuntime {
       }
     }
 
-    // The settings stream carries the wearer's settings: system apps only.
-    if (streams.includes(MiniappStreamType.SETTINGS_CHANGED) && !this.isSystemPackage(packageName)) {
-      this.sendResult(packageName, requestId, false, undefined, {
-        code: MiniappErrorCode.NOT_PERMITTED,
-        message: "The settings stream is restricted to system apps",
-      })
+    // The settings stream carries the wearer's settings.
+    if (
+      streams.includes(MiniappStreamType.SETTINGS_CHANGED) &&
+      !this.requirePermission(packageName, requestId, "PLATFORM_SETTINGS", "to subscribe to the settings stream")
+    ) {
       return
     }
 
@@ -2152,8 +2171,9 @@ class LocalMiniappRuntime {
       [...cloudTranscriptionStreams].filter((stream) => app.subscriptions.has(stream)),
     )
     this.replaceStreamSubscribers(packageName, previousSubscriptions, app.subscriptions)
-    // An overlay app that listens to phone notifications presents them on the glasses.
-    if (isOverlayApp(packageName)) {
+    // The overlay app presents phone notifications on the glasses while it
+    // listens to them; recorded for every dashboard so the role can move.
+    if (isDashboardApp(packageName)) {
       setOverlayViewer(packageName, app.subscriptions.has(MiniappStreamType.PHONE_NOTIFICATION))
     }
 
@@ -2385,13 +2405,13 @@ class LocalMiniappRuntime {
         })
         return
       }
-      // The dashboard view is the overlay apps' alone; anyone else's frame
+      // The dashboard view is the overlay app's alone; anyone else's frame
       // is dropped, reported rather than silently lost.
       if (payload.view === "dashboard" && !isOverlayApp(packageName)) {
         this.sendResult(packageName, requestId, true, {
           status: "displayed",
           presented: false,
-          reason: "not the dashboard app",
+          reason: "not the active dashboard",
         })
         return
       }
@@ -2415,10 +2435,11 @@ class LocalMiniappRuntime {
   }
 
   /**
-   * display.showView: the designated dashboard app takes or releases the
-   * overlay slot. Refused (NOT_PERMITTED) for any other app; "unsupported"
-   * while the glasses cannot show the dashboard view. Idempotent either way;
-   * the slot's state comes back to the app as a display_view change.
+   * display.showView: the active dashboard takes or releases the overlay
+   * slot. Refused (NOT_PERMITTED) for an app that is not a dashboard;
+   * "unsupported" for a dashboard without the role and while the glasses
+   * cannot show the dashboard view. Idempotent either way; the slot's state
+   * comes back to the app as a display_view change.
    */
   private handleShowView(packageName: string, payload: Record<string, unknown>, requestId?: string): void {
     if (!this.connectedApps.has(packageName)) {
@@ -2433,13 +2454,17 @@ class LocalMiniappRuntime {
       })
       return
     }
-    if (!isOverlayApp(packageName)) {
+    if (!isDashboardApp(packageName)) {
       this.sendResult(packageName, requestId, false, undefined, {
         code: MiniappErrorCode.NOT_PERMITTED,
-        message: "The dashboard view belongs to system_dashboard apps",
+        message: 'The dashboard view belongs to miniapps of type "dashboard"',
       })
       return
     }
+    if (!isOverlayApp(packageName)) {
+      this.sendResult(packageName, requestId, true, {status: "unsupported", reason: "not the active dashboard"})
+      return
+    }
     if (view === "main") {
       overlayPages.hide(packageName)
       this.sendResult(packageName, requestId, true, {status: "shown"})
@@ -2463,19 +2488,38 @@ class LocalMiniappRuntime {
     )
   }
 
-  // ---------------------------------------------------------------------------
-  // Settings bridge (session.settings) — system apps only
-  // ---------------------------------------------------------------------------
-
-  private requireSystemForSettings(packageName: string, requestId: string | undefined): boolean {
-    if (this.isSystemPackage(packageName)) return true
+  /**
+   * Reject the request with PERMISSION_NOT_DECLARED unless the caller's
+   * manifest declares `permission`. System apps pass without declaring it.
+   */
+  private requirePermission(
+    packageName: string,
+    requestId: string | undefined,
+    permission: string,
+    context: string,
+  ): boolean {
+    const caller = {
+      system: this.isSystemPackage(packageName),
+      permissions: this.connectedApps.get(packageName)?.installedManifest?.permissions,
+    }
+    if (mayUsePermission(caller, permission)) return true
+    logPermissionNotDeclared(packageName, permission, context, `{"type": "${permission}"}`)
     this.sendResult(packageName, requestId, false, undefined, {
-      code: MiniappErrorCode.NOT_PERMITTED,
-      message: "The settings bridge is restricted to system apps",
+      code: MiniappErrorCode.PERMISSION_NOT_DECLARED,
+      message: `${permission} permission not declared in miniapp.json. Add {"type": "${permission}"} to the "permissions" array.`,
+      permission,
     })
     return false
   }
 
+  // ---------------------------------------------------------------------------
+  // Settings bridge (session.settings) — PLATFORM_SETTINGS permission
+  // ---------------------------------------------------------------------------
+
+  private requireSettingsPermission(packageName: string, requestId: string | undefined): boolean {
+    return this.requirePermission(packageName, requestId, "PLATFORM_SETTINGS", "to use the settings bridge")
+  }
+
   /** A bridged key's current value: the store's, or the engine's for a derived key. */
   private settingsBridgeValue(key: string): unknown {
     if (isDerivedSettingsKey(key)) return this.derivedSettingValue(key)
@@ -2490,11 +2534,13 @@ class LocalMiniappRuntime {
         return localDisplayManager.foregroundAppOnScreen()
       case "ring_battery":
         return ringBatteryFrom(useGlassesStore.getState())
+      case "active_dashboard":
+        return activeDashboard()
     }
   }
 
   private handleSettingsGet(packageName: string, payload: Record<string, unknown>, requestId?: string): void {
-    if (!this.requireSystemForSettings(packageName, requestId)) return
+    if (!this.requireSettingsPermission(packageName, requestId)) return
     const values: Record<string, unknown> = {}
     for (const key of selectSettingsBridgeKeys(payload.keys)) values[key] = this.settingsBridgeValue(key)
     this.sendResult(packageName, requestId, true, {values})
@@ -2505,7 +2551,7 @@ class LocalMiniappRuntime {
     payload: Record<string, unknown>,
     requestId?: string,
   ): Promise<void> {
-    if (!this.requireSystemForSettings(packageName, requestId)) return
+    if (!this.requireSettingsPermission(packageName, requestId)) return
     const validated = validateSettingsSet(payload)
     if (!validated.ok) {
       this.sendResult(packageName, requestId, false, undefined, {code: validated.code, message: validated.message})
@@ -2525,7 +2571,11 @@ class LocalMiniappRuntime {
   }
 
   private async handleNotificationAppsList(packageName: string, requestId?: string): Promise<void> {
-    if (!this.requireSystemForSettings(packageName, requestId)) return
+    if (
+      !this.requirePermission(packageName, requestId, "READ_NOTIFICATIONS", "to list the apps that post notifications")
+    ) {
+      return
+    }
     try {
       this.sendResult(packageName, requestId, true, await installedNotificationApps())
     } catch (err) {
@@ -2539,8 +2589,9 @@ class LocalMiniappRuntime {
   /**
    * Push bridged settings as they change: stored keys from the store, the
    * derived keys whenever their inputs move (phone activity, the display,
-   * the apps store, the ring). Subscribers are system apps only (gated at
-   * SUBSCRIBE), so this is a no-op fan-out for everyone else.
+   * the apps store, the ring, the dashboard role). Subscribers declared
+   * PLATFORM_SETTINGS (gated at SUBSCRIBE), so this is a no-op fan-out for
+   * everyone else.
    */
   private ensureSettingsBridgeWired(): void {
     if (this.settingsBridgeWired) return
@@ -2576,6 +2627,7 @@ class LocalMiniappRuntime {
     onAppForegroundChange((foregrounded) => this.broadcastVisibility(foregrounded))
     localDisplayManager.onActiveDisplayChange(pushDerived)
     useAppStatusStore.subscribe(pushDerived)
+    onOverlayAppsChange(pushDerived)
     useGlassesStore.subscribe(
       (s) => `${s.ringConnected}:${s.ringBatteryLevel}:${s.controllerConnected}:${s.controllerBatteryLevel}`,
       pushDerived,
@@ -5196,6 +5248,31 @@ class LocalMiniappRuntime {
     useSettingsStore.subscribe((s) => s.getSetting(SETTINGS.cfw_native_navigation.key), broadcast)
     // The dashboard master switch flips the dashboard view.
     useSettingsStore.subscribe((s) => s.getSetting(SETTINGS.custom_dashboard_enabled.key), broadcast)
+    // The wearer's choice and the installed dashboards decide who holds the role.
+    const syncRole = () => this.syncActiveDashboard()
+    useSettingsStore.subscribe((s) => s.getSetting(SETTINGS.active_dashboard.key), syncRole)
+    useAppStatusStore.subscribe(syncRole)
+    syncRole()
+  }
+
+  /**
+   * Recompute who holds the dashboard role (ADR-0009). The previous holder
+   * gives up the slot first, so it hears the view change while it is still
+   * the overlay app; then every app sees its views again.
+   */
+  private syncActiveDashboard(): void {
+    const candidates: Array<{packageName: string; type?: string}> = [...useAppStatusStore.getState().apps]
+    // A dashboard can connect at launch before the apps store has listed it.
+    for (const [packageName, app] of this.connectedApps) {
+      if (candidates.some((candidate) => candidate.packageName === packageName)) continue
+      candidates.push({packageName, type: app.installedManifest?.type})
+    }
+    const next = activeDashboardAmong(candidates)
+    const previous = activeDashboard()
+    if (next === previous) return
+    if (previous !== null) overlayPages.hide(previous, "replaced")
+    setActiveDashboard(next)
+    this.broadcastCapabilities()
   }
 
   /** Capabilities as `packageName` sees them: the model profile plus the views this app may draw. */
@@ -5668,18 +5745,20 @@ class LocalMiniappRuntime {
     }
   }
 
-  /** Reject the request with NOT_PERMITTED unless the caller is a system app. */
-  private requireSystemCaller(
+  /** Reject the request unless the caller may list, start and stop other miniapps (MANAGE_MINIAPPS). */
+  private requireMiniappsPermission(
     packageName: string,
     requestId: string | undefined,
     op: InteropAuditEvent["op"],
     target?: string,
   ): boolean {
-    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",
+    if (this.requirePermission(packageName, requestId, "MANAGE_MINIAPPS", `to ${op} miniapps`)) return true
+    this.auditInterop({
+      caller: packageName,
+      op,
+      target,
+      ok: false,
+      errorCode: MiniappErrorCode.PERMISSION_NOT_DECLARED,
     })
     return false
   }
@@ -5704,7 +5783,7 @@ class LocalMiniappRuntime {
   }
 
   private handleMiniappsList(packageName: string, payload: Record<string, unknown>, requestId?: string): void {
-    if (!this.requireSystemCaller(packageName, requestId, "list")) return
+    if (!this.requireMiniappsPermission(packageName, requestId, "list")) return
     const includeIncompatible = payload.includeIncompatible === true
     const infos = this.interopApps()
       .filter(
@@ -5725,7 +5804,7 @@ class LocalMiniappRuntime {
     requestId?: string,
   ): Promise<void> {
     const target = payload.packageName as string | undefined
-    if (!this.requireSystemCaller(packageName, requestId, "start", target)) return
+    if (!this.requireMiniappsPermission(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, {
@@ -5817,7 +5896,7 @@ class LocalMiniappRuntime {
     requestId?: string,
   ): Promise<void> {
     const target = payload.packageName as string | undefined
-    if (!this.requireSystemCaller(packageName, requestId, "stop", target)) return
+    if (!this.requireMiniappsPermission(packageName, requestId, "stop", target)) return
     if (!target) {
       this.sendResult(packageName, requestId, false, undefined, {
         code: MiniappErrorCode.APP_NOT_FOUND,

package/src/services/MiniappLauncher.ts

@@ -31,6 +31,7 @@ import {storage} from "../utils/storage/storage"
 import appRegistry, {getLocalAppRunningState, saveLocalAppRunningState} from "./AppRegistry"
 import devServerBridge from "./DevServerBridge"
 import localMiniappRuntime, {type InstalledMiniappManifest} from "./LocalMiniappRuntime"
+import {activeDashboardAmong} from "./pages/activeDashboard"
 import type {MiniappLaunchSource} from "@glassly/miniapp"
 import type {JSRouter} from "./JSRouter"
 
@@ -306,17 +307,21 @@ class MiniappLauncher {
    *
    * Always On apps (the dashboard) start whether or not they were running
    * when the app was last killed, and get a switcher card like any other app.
+   * A dashboard that does not hold the role (ADR-0009) is not started by its
+   * Always On flag.
    * Both restore paths skip apps missing required OS permissions without
    * prompting or clearing their saved running/Always On choice.
    */
   async autostartLocalMiniapps(): Promise<void> {
     const apps = await appRegistry.getInstalledMiniapps()
+    const activeDashboard = activeDashboardAmong(apps)
     for (const app of apps) {
       // Only phone-hosted miniapps have a JSContext to re-spawn. Offline
       // built-ins (`local:false, offline:true`) restore their native running
       // state elsewhere and have no bundle to launch.
       if (!app.local) continue
-      if (!app.alwaysOn && !getLocalAppRunningState(app.packageName)) continue
+      const alwaysOn = app.alwaysOn && (app.type !== "dashboard" || app.packageName === activeDashboard)
+      if (!alwaysOn && !getLocalAppRunningState(app.packageName)) continue
       if (this.isRunning(app.packageName)) continue
       try {
         const missing = await permissions.missingRequired(app.permissions ?? [])

package/src/services/miniappPermissions.ts

@@ -0,0 +1,19 @@
+/**
+ * Whether a miniapp may use an API gated on a manifest permission
+ * (miniapp.json -> permissions): `session.miniapps` needs MANAGE_MINIAPPS,
+ * `session.settings` PLATFORM_SETTINGS, the notification app list
+ * READ_NOTIFICATIONS. System apps pass without declaring it. Pure, so the
+ * runtime only does the reply.
+ */
+export interface PermissionCaller {
+  system: boolean
+  permissions?: ReadonlyArray<{type?: string}>
+}
+
+export function declaresPermission(permissions: PermissionCaller["permissions"], permission: string): boolean {
+  return (permissions ?? []).some((declared) => declared.type?.toUpperCase() === permission)
+}
+
+export function mayUsePermission(caller: PermissionCaller, permission: string): boolean {
+  return caller.system || declaresPermission(caller.permissions, permission)
+}

package/src/services/pages/OverlayPages.ts

@@ -1,11 +1,12 @@
 /**
- * The overlay apps' pages (ADR-0006): one Page per app that has taken the
- * slot, the only Page implementation the page host shows. The engine keeps
- * the slot and the eligibility watch; a page only relays: holding the slot
- * is reported to its app as a view change, and the app's frames reach the
- * slot through `renderOverlay` under its package name. Whichever app asked
- * last holds the slot; the previous one hears it was replaced. The runtime
- * supplies the sink that delivers to apps, so this module never imports it.
+ * The overlay app's page (ADR-0006, ADR-0009): one Page per dashboard that
+ * has taken the slot, the only Page implementation the page host shows. The
+ * engine keeps the slot and the eligibility watch; a page only relays:
+ * holding the slot is reported to its app as a view change, and the app's
+ * frames reach the slot through `renderOverlay` under its package name. Only
+ * the dashboard that holds the role may show; when the role moves, the
+ * previous holder hears it was replaced. The runtime supplies the sink that
+ * delivers to apps, so this module never imports it.
  */
 import pageHost, {type Page, type PageHiddenReason} from "./PageHost"
 import {isOverlayApp} from "./overlayApps"
@@ -44,10 +45,10 @@ class OverlayPages {
     return pageHost.showing === page
   }
 
-  /** Release the slot if the app holds it. */
-  hide(packageName: string): void {
+  /** Release the slot if the app holds it; "replaced" when the dashboard role moved on. */
+  hide(packageName: string, reason: PageHiddenReason = "hidden"): void {
     const page = this.pages.get(packageName)
-    if (page) pageHost.hide(page)
+    if (page) pageHost.hide(page, reason)
   }
 
   /** The app stopped: release the slot without telling it, and forget its page. */

package/src/services/pages/PageHost.ts

@@ -72,10 +72,10 @@ class PageHost {
   }
 
   /** Release the slot if `page` holds it. */
-  hide(page: Page): void {
+  hide(page: Page, reason: PageHiddenReason = "hidden"): void {
     this.enqueue(() => {
       if (this.showingPage !== page) return
-      this.release("hidden")
+      this.release(reason)
     })
   }
 

package/src/services/pages/activeDashboard.ts

@@ -0,0 +1,24 @@
+/**
+ * Who holds the dashboard role (ADR-0009): the wearer's choice when that
+ * miniapp is installed, else the default (the bundled dashboard), else the
+ * first installed dashboard by package name, else nobody. Read at decision
+ * time, never cached, so an uninstall hands the role back without anyone
+ * rewriting the setting.
+ */
+import {SETTINGS, useSettingsStore} from "../../stores/settings"
+
+export function resolveActiveDashboard(installed: readonly string[], chosen: unknown, fallback: string): string | null {
+  if (typeof chosen === "string" && installed.includes(chosen)) return chosen
+  if (installed.includes(fallback)) return fallback
+  return [...installed].sort()[0] ?? null
+}
+
+/** The active dashboard among `apps`; only miniapps whose manifest type is "dashboard" can hold the role. */
+export function activeDashboardAmong(apps: ReadonlyArray<{packageName: string; type?: string}>): string | null {
+  const installed = apps.filter((app) => app.type === "dashboard").map((app) => app.packageName)
+  return resolveActiveDashboard(
+    installed,
+    useSettingsStore.getState().getSetting(SETTINGS.active_dashboard.key),
+    SETTINGS.active_dashboard.defaultValue(),
+  )
+}