@glassly/engine 0.1.0-dev.1 → 0.1.0-dev.27

package/src/services/CustomDashboardService.ts

@@ -0,0 +1,575 @@
+/**
+ * Scene API dashboard for G2 custom firmware.
+ *
+ * G2.swift marks the published firmware version after it detects the CFW
+ * capability advertisement. The service retains a dashboard frame, owns
+ * dashboard gestures while head-up is active, and leaves every other device
+ * on its native behavior.
+ *
+ * The dashboard is composed of user-orderable widgets (clock, calendar, apps
+ * button, notifications button) stacked vertically on the CFW scene canvas.
+ * The apps button switches to a second, dashboard-rendered app menu view.
+ */
+import {File} from "expo-file-system"
+
+import {BluetoothSdk} from "@glassly/bluetooth-sdk"
+import type {CalendarEvent} from "@glassly/miniapp"
+
+import {useAppStatusStore} from "../stores/apps"
+import {useGlassesStore} from "../stores/glasses"
+import {SETTINGS, useSettingsStore} from "../stores/settings"
+import type {ClientApp} from "../types/applet"
+import type {SceneElementInput} from "../utils/display/scene"
+import {BgTimer} from "../utils/timers"
+import {
+  appMenuActions,
+  dashboardActions,
+  formatDashboardClock,
+  isCustomDashboardEligible,
+  normalizeDashboardWidgets,
+  orderedDashboardApps,
+  type CustomDashboardClockStyle,
+  type DashboardWidgetSetting,
+  type MenuAppSetting,
+} from "./CustomDashboardModel"
+import {isGlassesConnected} from "./GlassesReadiness"
+import {listPhoneCalendarEvents} from "./PhoneCalendarService"
+import sceneRenderer from "./SceneRenderer"
+
+const DASHBOARD_APP_ID = "system.custom-dashboard"
+const CLOCK_REFRESH_MS = 30_000
+const CALENDAR_REFRESH_MS = 5 * 60_000
+
+// CFW blits the stock compositor's 576×288 canvas; used when the firmware has
+// not reported scene capabilities yet.
+const FALLBACK_CANVAS = {width: 576, height: 288}
+const MARGIN_X = 16
+const MARGIN_TOP = 10
+const WIDGET_GAP = 10
+/** Row height for the glasses' builtin 20px font engine. */
+const LINE_H = 24
+const BUTTON_H = 34
+/** App-menu icon grid: 4 per page (G2 firmware image-container pool). */
+const APPS_PER_PAGE = 4
+const APP_CELL = 72
+const APP_CELL_GAP = 16
+const APP_ICON_INSET = 4
+const APP_ICON = APP_CELL - APP_ICON_INSET * 2
+
+function eventLine(event: CalendarEvent): string {
+  const when = event.allDay
+    ? "All day"
+    : new Intl.DateTimeFormat(undefined, {hour: "numeric", minute: "2-digit"}).format(new Date(event.startsAt))
+  return `${when}  ${event.title}`
+}
+
+class CustomDashboardService {
+  private started = false
+  private open = false
+  private view: "main" | "apps" = "main"
+  private mainIndex = 0
+  private appsIndex = 0
+  private calendarAvailable = false
+  /** packageName → base64 icon bytes, or null when the icon can't be loaded (monogram fallback). */
+  private iconCache = new Map<string, string | null>()
+  private iconLoads = new Set<string>()
+  private calendarEvents: CalendarEvent[] = []
+  private unsubs: Array<() => void> = []
+  private clockTimer: number | null = null
+  private calendarTimer: number | null = null
+  /** Last observed eligibility, for transition detection. */
+  private eligible = false
+
+  start(): void {
+    if (this.started) return
+    this.started = true
+    this.unsubs.push(
+      useGlassesStore.subscribe(
+        (state) => `${state.connection.state}:${state.deviceModel}:${state.firmwareVersion}`,
+        () => {
+          if (!this.syncEligibility()) return
+          void this.refreshCalendarAndRender()
+        },
+      ),
+      // Selector: only dashboard-relevant settings retrigger a refresh. The
+      // whole-store form fired a calendar query on every settings write.
+      useSettingsStore.subscribe(
+        (state) =>
+          JSON.stringify([
+            state.getSetting(SETTINGS.custom_dashboard_enabled.key),
+            state.getSetting(SETTINGS.custom_dashboard_widgets.key),
+            state.getSetting(SETTINGS.custom_dashboard_clock_style.key),
+            state.getSetting(SETTINGS.custom_dashboard_clock_show_date.key),
+            state.getSetting(SETTINGS.twelve_hour_time.key),
+            state.getSetting(SETTINGS.custom_dashboard_calendar_event_count.key),
+            state.getSetting(SETTINGS.custom_dashboard_calendar_days_ahead.key),
+            state.getSetting(SETTINGS.menu_apps.key),
+          ]),
+        () => {
+          if (!this.syncEligibility()) return
+          void this.refreshCalendarAndRender()
+        },
+      ),
+      useAppStatusStore.subscribe(() => {
+        if (this.isEligible()) this.render()
+      }),
+    )
+    this.clockTimer = BgTimer.setInterval(() => {
+      if (this.isEligible()) this.render()
+    }, CLOCK_REFRESH_MS)
+    this.calendarTimer = BgTimer.setInterval(() => {
+      if (this.isEligible()) void this.refreshCalendarAndRender()
+    }, CALENDAR_REFRESH_MS)
+    this.eligible = this.isEligible()
+    if (this.eligible) {
+      this.ensureContextualDashboard()
+      void this.refreshCalendarAndRender()
+    }
+  }
+
+  /**
+   * Track eligible⇄ineligible transitions from any trigger (setting toggle,
+   * connect/disconnect, firmware change). Entering enables the contextual
+   * dashboard once — not on every settings write, so a user's manual
+   * contextual-dashboard choice is no longer ratcheted back. Leaving closes
+   * the dashboard, blanks the glasses view, and drops the retained scene so a
+   * stale frame can't be replayed after the feature was turned off.
+   */
+  private syncEligibility(): boolean {
+    const eligible = this.isEligible()
+    if (eligible === this.eligible) return eligible
+    this.eligible = eligible
+    if (eligible) {
+      this.ensureContextualDashboard()
+    } else {
+      this.open = false
+      this.resetNavigation()
+      sceneRenderer.emitScene(DASHBOARD_APP_ID, "dashboard", [])
+      sceneRenderer.clearApp(DASHBOARD_APP_ID)
+    }
+    return eligible
+  }
+
+  stop(): void {
+    for (const unsub of this.unsubs) unsub()
+    this.unsubs = []
+    if (this.clockTimer !== null) BgTimer.clearInterval(this.clockTimer)
+    if (this.calendarTimer !== null) BgTimer.clearInterval(this.calendarTimer)
+    this.clockTimer = null
+    this.calendarTimer = null
+    this.open = false
+    this.eligible = false
+    this.resetNavigation()
+    this.started = false
+    sceneRenderer.clearApp(DASHBOARD_APP_ID)
+  }
+
+  isEligible(): boolean {
+    if (useSettingsStore.getState().getSetting(SETTINGS.custom_dashboard_enabled.key) === false) return false
+    const state = useGlassesStore.getState()
+    return (
+      isGlassesConnected(state.connection) &&
+      isCustomDashboardEligible({
+        model: state.deviceModel,
+        firmwareVersion: state.firmwareVersion,
+      })
+    )
+  }
+
+  get isOpen(): boolean {
+    return this.open
+  }
+
+  setHeadUp(up: boolean): void {
+    if (!this.isEligible()) {
+      this.open = false
+      return
+    }
+    if (up && !this.open) this.resetNavigation()
+    this.open = up
+    if (up) void this.refreshCalendarAndRender()
+  }
+
+  /** Toggle the custom dashboard for an eligible device. */
+  toggle(): boolean {
+    if (!this.isEligible()) return false
+    this.open = !this.open
+    if (this.open) {
+      this.resetNavigation()
+      void this.refreshCalendarAndRender()
+    }
+    void Promise.resolve(BluetoothSdk.toggleHeadUp()).catch((error) => {
+      this.open = !this.open
+      console.error("CustomDashboard: toggleHeadUp failed", error)
+    })
+    return true
+  }
+
+  /** Returns true when an open custom dashboard consumed the gesture. */
+  handleGesture(gestureName: string): boolean {
+    if (!this.open || !this.isEligible()) return false
+    if (gestureName === "double_tap") {
+      // In the app menu a double tap backs out to the top of the dashboard
+      // (there is no Back row); on the main view it closes the dashboard.
+      if (this.view === "apps") {
+        this.resetNavigation()
+        this.render()
+        return true
+      }
+      return this.toggle()
+    }
+    if (this.view === "apps") return this.handleAppMenuGesture(gestureName)
+    return this.handleMainGesture(gestureName)
+  }
+
+  private resetNavigation(): void {
+    this.view = "main"
+    this.mainIndex = 0
+    this.appsIndex = 0
+  }
+
+  private handleMainGesture(gestureName: string): boolean {
+    const actions = dashboardActions(this.widgets())
+    if (this.mainIndex >= actions.length) this.mainIndex = Math.max(0, actions.length - 1)
+    if (gestureName === "swipe_down" || gestureName === "swipe_up") {
+      if (actions.length === 0) return true
+      const delta = gestureName === "swipe_down" ? 1 : -1
+      this.mainIndex = (this.mainIndex + delta + actions.length) % actions.length
+      this.render()
+      return true
+    }
+    if (gestureName === "single_tap") {
+      const action = actions[this.mainIndex]
+      if (action?.kind === "apps-menu") {
+        this.view = "apps"
+        this.appsIndex = 0
+        this.render()
+      } else if (action?.kind === "notifications") {
+        void this.openNotificationsPanel()
+      }
+      return true
+    }
+    return false
+  }
+
+  private handleAppMenuGesture(gestureName: string): boolean {
+    const rows = appMenuActions(this.menuApps())
+    if (this.appsIndex >= rows.length) this.appsIndex = Math.max(0, rows.length - 1)
+    if (gestureName === "swipe_down" || gestureName === "swipe_up") {
+      const delta = gestureName === "swipe_down" ? 1 : -1
+      this.appsIndex = (this.appsIndex + delta + rows.length) % rows.length
+      this.render()
+      return true
+    }
+    if (gestureName === "single_tap") {
+      const row = rows[this.appsIndex]
+      if (row?.kind === "app") {
+        void this.toggleApp(row.packageName)
+      }
+      return true
+    }
+    return false
+  }
+
+  private menuApps(): ClientApp[] {
+    const menu = useSettingsStore.getState().getSetting(SETTINGS.menu_apps.key) as MenuAppSetting[] | null
+    return orderedDashboardApps(menu, useAppStatusStore.getState().apps)
+  }
+
+  private widgets(): DashboardWidgetSetting[] {
+    return normalizeDashboardWidgets(useSettingsStore.getState().getSetting(SETTINGS.custom_dashboard_widgets.key))
+  }
+
+  private async close(): Promise<void> {
+    if (!this.open) return
+    this.open = false
+    await Promise.resolve(BluetoothSdk.toggleHeadUp()).catch((error) => {
+      console.error("CustomDashboard: close failed", error)
+    })
+  }
+
+  private async openNotificationsPanel(): Promise<void> {
+    await this.close()
+    await BluetoothSdk.showNativeNotificationPanel().catch((error) => {
+      console.error("CustomDashboard: notification panel failed", error)
+    })
+  }
+
+  private async toggleApp(packageName: string): Promise<void> {
+    await this.close()
+    const app = useAppStatusStore.getState().apps.find((candidate) => candidate.packageName === packageName)
+    if (!app) return
+    if (app.running) {
+      await useAppStatusStore.getState().stop(app.packageName)
+    } else {
+      await useAppStatusStore.getState().start(app, {skipNavigation: true})
+    }
+  }
+
+  private calendarWidgetEnabled(): boolean {
+    return this.widgets().some((widget) => widget.id === "calendar" && widget.enabled)
+  }
+
+  private ensureContextualDashboard(): void {
+    const settings = useSettingsStore.getState()
+    if (settings.getSetting(SETTINGS.contextual_dashboard.key) !== true) {
+      // DeviceManager selects its retained dashboard Scene only while this is
+      // enabled. Custom firmware eligibility makes that dashboard automatic.
+      void settings.setSetting(SETTINGS.contextual_dashboard.key, true, false)
+    }
+  }
+
+  private async refreshCalendarAndRender(): Promise<void> {
+    if (!this.calendarWidgetEnabled()) {
+      this.calendarAvailable = false
+      this.calendarEvents = []
+      this.render()
+      return
+    }
+    const settings = useSettingsStore.getState()
+    const count = Number(settings.getSetting(SETTINGS.custom_dashboard_calendar_event_count.key) ?? 2)
+    const days = Number(settings.getSetting(SETTINGS.custom_dashboard_calendar_days_ahead.key) ?? 3)
+    const startsAt = new Date()
+    const endsAt = new Date(startsAt.getTime() + Math.max(1, days) * 24 * 60 * 60 * 1000)
+    try {
+      const result = await listPhoneCalendarEvents({startsAt, endsAt, limit: Math.max(1, Math.min(3, count))})
+      this.calendarAvailable = true
+      this.calendarEvents = result.events
+    } catch {
+      // Permission is requested from the Custom Dashboard settings screen;
+      // without access the widget silently stays off the glasses.
+      this.calendarAvailable = false
+      this.calendarEvents = []
+    }
+    this.render()
+  }
+
+  private canvas(): {width: number; height: number} {
+    const {sceneCanvasWidth, sceneCanvasHeight} = useGlassesStore.getState()
+    if (sceneCanvasWidth && sceneCanvasWidth > 0 && sceneCanvasHeight && sceneCanvasHeight > 0) {
+      return {width: sceneCanvasWidth, height: sceneCanvasHeight}
+    }
+    return FALLBACK_CANVAS
+  }
+
+  private render(): void {
+    if (!this.isEligible()) return
+    const elements = this.view === "apps" ? this.appMenuElements() : this.mainElements()
+    sceneRenderer.emitScene(DASHBOARD_APP_ID, "dashboard", elements)
+  }
+
+  private mainElements(): SceneElementInput[] {
+    const canvas = this.canvas()
+    const settings = useSettingsStore.getState()
+    const widgets = this.widgets().filter((widget) => widget.enabled)
+    const actions = dashboardActions(widgets)
+    if (this.mainIndex >= actions.length) this.mainIndex = Math.max(0, actions.length - 1)
+    const selected = actions[this.mainIndex]
+
+    const clockStyle =
+      (settings.getSetting(SETTINGS.custom_dashboard_clock_style.key) as CustomDashboardClockStyle) === "large"
+        ? "large"
+        : "compact"
+    const calendarEnabled = widgets.some((widget) => widget.id === "calendar")
+    // Calendar lives in the right half; everything else stacks in the left
+    // half (full width when the calendar widget is off).
+    const halfW = Math.floor(canvas.width / 2) - MARGIN_X - Math.floor(WIDGET_GAP / 2)
+    const width = calendarEnabled ? halfW : canvas.width - MARGIN_X * 2
+    const rightX = Math.floor(canvas.width / 2) + Math.floor(WIDGET_GAP / 2)
+
+    const elements: SceneElementInput[] = []
+    let y = MARGIN_TOP
+    for (const widget of widgets) {
+      if (widget.id === "clock") {
+        const fontSize = clockStyle === "large" ? 48 : 32
+        const clock = formatDashboardClock(new Date(), {
+          twelveHour: settings.getSetting(SETTINGS.twelve_hour_time.key) === true,
+          showDate: settings.getSetting(SETTINGS.custom_dashboard_clock_show_date.key) !== false,
+        })
+        elements.push({
+          type: "text",
+          id: "clock",
+          box: {x: MARGIN_X, y, w: width, h: fontSize + 6},
+          text: clock.time,
+          style: {font: "mono", fontSize, breakMode: "strict-word"},
+        })
+        y += fontSize + 6
+        if (clock.date) {
+          elements.push({
+            type: "text",
+            id: "clock-date",
+            box: {x: MARGIN_X, y, w: width, h: LINE_H},
+            text: clock.date,
+            style: {font: "builtin", breakMode: "strict-word"},
+          })
+          y += LINE_H
+        }
+        y += WIDGET_GAP
+      } else if (widget.id === "calendar") {
+        // Right half, top-aligned, independent of the left stack. A missing
+        // calendar (permission not granted, fetch failed) shows a hint
+        // instead of silently vanishing.
+        const lines = this.calendarAvailable
+          ? [
+              "Calendar",
+              ...(this.calendarEvents.length
+                ? this.calendarEvents.slice(0, 3).map(eventLine)
+                : ["No upcoming events"]),
+            ]
+          : ["Calendar", "No access"]
+        elements.push({
+          type: "text",
+          id: "calendar",
+          box: {x: rightX, y: MARGIN_TOP, w: halfW, h: lines.length * LINE_H},
+          text: lines.join("\n"),
+          style: {font: "builtin", breakMode: "strict-word", overflow: "ellipsis"},
+        })
+      } else if (widget.id === "apps") {
+        const isSelected = selected?.kind === "apps-menu"
+        elements.push({
+          type: "text",
+          id: "apps-button",
+          box: {x: MARGIN_X, y, w: width, h: BUTTON_H},
+          text: "Apps",
+          style: {font: "builtin", border: isSelected ? 2 : 0, radius: 8},
+        })
+        y += BUTTON_H + WIDGET_GAP
+      } else if (widget.id === "notifications") {
+        const isSelected = selected?.kind === "notifications"
+        elements.push({
+          type: "text",
+          id: "notifications",
+          box: {x: MARGIN_X, y, w: width, h: BUTTON_H},
+          text: "Notifications",
+          style: {font: "builtin", border: isSelected ? 2 : 0, radius: 8},
+        })
+        y += BUTTON_H + WIDGET_GAP
+      }
+    }
+    return elements
+  }
+
+  /**
+   * Resolve a miniapp icon to base64 for the glasses. Local/bundled miniapps
+   * carry a file:// icon.png; store apps an https URL; the offline system
+   * tiles a bundler asset id (unsupported here — monogram fallback). Loads
+   * are async and cached; a finished load repaints the open app menu.
+   */
+  private loadIcon(app: ClientApp): void {
+    if (this.iconCache.has(app.packageName) || this.iconLoads.has(app.packageName)) return
+    const url = typeof app.logoUrl === "string" ? app.logoUrl : ""
+    if (!/^(file|https?):/.test(url)) {
+      this.iconCache.set(app.packageName, null)
+      return
+    }
+    this.iconLoads.add(app.packageName)
+    void (async () => {
+      try {
+        let base64: string
+        if (url.startsWith("file:")) {
+          base64 = await new File(url).base64()
+        } else {
+          const response = await fetch(url)
+          const blob = await response.blob()
+          base64 = await new Promise<string>((resolve, reject) => {
+            const reader = new FileReader()
+            reader.onload = () => resolve(String(reader.result).split(",")[1] ?? "")
+            reader.onerror = () => reject(reader.error)
+            reader.readAsDataURL(blob)
+          })
+        }
+        this.iconCache.set(app.packageName, base64 || null)
+      } catch {
+        this.iconCache.set(app.packageName, null)
+      } finally {
+        this.iconLoads.delete(app.packageName)
+        if (this.open && this.view === "apps") this.render()
+      }
+    })()
+  }
+
+  private appMenuElements(): SceneElementInput[] {
+    const canvas = this.canvas()
+    const width = canvas.width - MARGIN_X * 2
+    const apps = this.menuApps()
+    const rows = appMenuActions(apps)
+    if (this.appsIndex >= rows.length) this.appsIndex = Math.max(0, rows.length - 1)
+
+    const elements: SceneElementInput[] = [
+      {
+        type: "text",
+        id: "apps-title",
+        box: {x: MARGIN_X, y: MARGIN_TOP, w: width, h: LINE_H},
+        text: "Apps",
+        style: {font: "builtin"},
+      },
+    ]
+    const listTop = MARGIN_TOP + LINE_H + 16
+    if (apps.length === 0) {
+      elements.push({
+        type: "text",
+        id: "apps-empty",
+        box: {x: MARGIN_X, y: listTop, w: width, h: LINE_H},
+        text: "No apps in Glasses Menu",
+        style: {font: "builtin"},
+      })
+      return elements
+    }
+
+    // Icon grid, paged: the G2 firmware image-container pool is 4, so at most
+    // four icon images may be on a page. Selection is the bordered cell.
+    const perPage = APPS_PER_PAGE
+    const pageStart = Math.floor(this.appsIndex / perPage) * perPage
+    const page = apps.slice(pageStart, pageStart + perPage)
+    const totalW = page.length * APP_CELL + (page.length - 1) * APP_CELL_GAP
+    const startX = Math.max(MARGIN_X, Math.round((canvas.width - totalW) / 2))
+    page.forEach((app, column) => {
+      const x = startX + column * (APP_CELL + APP_CELL_GAP)
+      const selected = pageStart + column === this.appsIndex
+      const icon = this.iconCache.get(app.packageName)
+      if (icon === undefined) this.loadIcon(app)
+      if (icon) {
+        elements.push({
+          type: "image",
+          id: `app-icon:${app.packageName}`,
+          box: {x: x + APP_ICON_INSET, y: listTop + APP_ICON_INSET, w: APP_ICON, h: APP_ICON},
+          data: icon,
+        })
+      } else {
+        // Monogram fallback for icons that can't load (bundler-asset tiles).
+        elements.push({
+          type: "text",
+          id: `app-icon:${app.packageName}`,
+          box: {x: x + APP_ICON_INSET, y: listTop + APP_ICON_INSET, w: APP_ICON, h: APP_ICON},
+          text: (app.name.trim()[0] ?? "?").toUpperCase(),
+          style: {font: "mono", fontSize: 40},
+        })
+      }
+      if (selected) {
+        elements.push({
+          type: "rect",
+          id: "apps-selection",
+          box: {x, y: listTop, w: APP_CELL, h: APP_CELL},
+          style: {border: 2, radius: 8},
+        })
+      }
+    })
+
+    // Grayscale mini icons are ambiguous on their own: caption the selection.
+    const selectedApp = apps[this.appsIndex]
+    if (selectedApp) {
+      elements.push({
+        type: "text",
+        id: "apps-selected-name",
+        box: {x: MARGIN_X, y: listTop + APP_CELL + 12, w: width, h: LINE_H},
+        text: `${selectedApp.name}${selectedApp.running ? "  ●" : ""}`,
+        style: {font: "builtin", breakMode: "strict-word", overflow: "ellipsis"},
+      })
+    }
+    return elements
+  }
+}
+
+const customDashboardService = new CustomDashboardService()
+export default customDashboardService
+export {CustomDashboardService}

package/src/services/DeviceEventRouter.ts

@@ -20,7 +20,9 @@ import BluetoothSdk from "@glassly/bluetooth-sdk/internal"
 import {shallow} from "zustand/shallow"
 
 import localMiniappRuntime from "./LocalMiniappRuntime"
+import localDisplayManager from "./LocalDisplayManager"
 import localSttFallbackCoordinator from "./LocalSttFallbackCoordinator"
+import {MiniappExitGesture} from "./MiniappExitGesture"
 import nativeNavigationService from "./NativeNavigationService"
 import speakerLabelResolver from "./SpeakerLabelResolver"
 import {phonePhotoCoordinator} from "./PhonePhotoCoordinator"
@@ -31,10 +33,23 @@ import {SETTINGS, useSettingsStore} from "../stores/settings"
 import {useAppStatusStore} from "../stores/apps"
 import {retirePendingSelectionOnPromotion} from "./PairingIdentity"
 import GlobalEventEmitter from "../utils/GlobalEventEmitter"
+import {BgTimer} from "../utils/timers"
 import {asgCameraApi} from "./asg/asgCameraApi"
+import customDashboardService from "./CustomDashboardService"
+import gestureDotsService from "./GestureDotsService"
 
 let subs: Array<{remove: () => void}> = []
 
+const miniappExitGesture = new MiniappExitGesture({
+  getState: () => useAppStatusStore.getState(),
+  getVisiblePackageName: () => localDisplayManager.getVisibleMiniappPackageName(),
+  beginExitNotice: (packageName, text) => localDisplayManager.beginMiniappExit(packageName, text),
+  finishExitNotice: (packageName) => localDisplayManager.finishMiniappExit(packageName),
+  cancelExitNotice: (packageName) => localDisplayManager.cancelMiniappExit(packageName),
+  setTimeout: (callback, delay) => BgTimer.setTimeout(callback, delay),
+  clearTimeout: (timerId) => BgTimer.clearTimeout(timerId),
+})
+
 export function startDeviceEventRouter(): void {
   if (subs.length) return
 
@@ -183,13 +198,38 @@ export function startDeviceEventRouter(): void {
   )
   subs.push(
     BluetoothSdk.addListener("touch_event", (event) => {
+      // While the custom dashboard is visible it owns its focus/navigation
+      // gestures; do not leak those into a miniapp running underneath it.
+      if (customDashboardService.handleGesture(event.gestureName)) return
+
+      // Gesture-dots debug indicator (any device, gated by its setting). It
+      // only paints while the screen is otherwise empty; the gesture still
+      // flows to miniapps below.
+      gestureDotsService.noteGesture(event.gestureName)
+
       localMiniappRuntime.forwardEvent("touch_event", event)
-      // Double-tap policy, moved out of the native G2 handlers: open the native
-      // dashboard when the setting is on, else toggle head-up. Native only
-      // reports the gesture now.
+      // Double-tap policy, moved out of the native G2 handlers: exit a visible
+      // unclaimed miniapp; otherwise open the dashboard or toggle head-up.
+      // Native only reports the gesture now.
       if (event.gestureName === "double_tap") {
-        const useNativeDashboard =
-          useSettingsStore.getState().getSetting(SETTINGS.use_native_dashboard.key) !== false
+        // A foreground miniapp that claimed double_tap (CLAIM_GESTURES) is
+        // using it as an in-app gesture (e.g. the terminal's back-to-menu) —
+        // the event was already forwarded above; skip the system default.
+        if (localMiniappRuntime.foregroundClaimsGesture("double_tap")) return
+
+        // An unclaimed double tap exits only the miniapp whose frame is visibly
+        // on the glasses. The controller shows the bounded OS notice first,
+        // then uses the normal store stop path (and closes its phone overlay).
+        // Checked before the dashboard toggle: while an app owns the screen an
+        // unclaimed double-tap always means "leave the app" — the (custom or
+        // native) dashboard is for the empty screen, and head-up still opens
+        // the custom dashboard mid-app.
+        if (miniappExitGesture.tryExitVisibleMiniapp()) return
+
+        // Eligible G2 custom firmware replaces the native dashboard.
+        if (customDashboardService.toggle()) return
+
+        const useNativeDashboard = useSettingsStore.getState().getSetting(SETTINGS.use_native_dashboard.key) !== false
         if (useNativeDashboard) {
           // The modal nav UI owns the screen; showDashboard would fight it.
           if (!nativeNavigationService.isActive) {
@@ -219,6 +259,7 @@ export function startDeviceEventRouter(): void {
   // Head position — translate native {up:boolean} → SDK {position:"up"|"down"}.
   subs.push(
     BluetoothSdk.addListener("head_up", (event) => {
+      customDashboardService.setHeadUp(event.up)
       localMiniappRuntime.forwardEvent("head_up", {position: event.up ? "up" : "down", timestamp: Date.now()})
     }),
   )
@@ -263,4 +304,5 @@ export function startDeviceEventRouter(): void {
 export function stopDeviceEventRouter(): void {
   for (const sub of subs) sub.remove()
   subs = []
+  miniappExitGesture.reset()
 }