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

package/src/services/GestureDotsService.ts

@@ -0,0 +1,147 @@
+/**
+ * Gesture dots — a debug indicator that flashes a small glyph top-right on the
+ * glasses when a touch gesture arrives, while nothing else is on the display:
+ * a filled circle for a single tap, an arrow for a swipe, cleared after a
+ * short pulse. Extracted from the CFW dashboard service; it renders through
+ * the ordinary scene pipeline, so it works on any positioning device (stock
+ * G2 included), and is gated by the gesture_dots debug setting.
+ *
+ * The glyphs are pre-baked images (not text): the stock firmware's builtin
+ * font has no ●/↑/↓, and a single image element with a stable id and box maps
+ * to ONE re-used firmware image container — flash and idle swap its bytes
+ * (data-only update, no page rebuild) instead of creating/removing containers.
+ */
+import {SETTINGS, useSettingsStore} from "../stores/settings"
+import type {SceneElementInput} from "../utils/display/scene"
+import {BgTimer} from "../utils/timers"
+import {GESTURE_DOT_GLYPHS, GESTURE_DOT_GLYPH_SIZE, type GestureDotGlyph} from "./gestureDotGlyphs"
+import localDisplayManager from "./LocalDisplayManager"
+import sceneRenderer from "./SceneRenderer"
+
+const DOTS_APP_ID = "system.gesture-dots"
+/** How long a gesture stays on the indicator. */
+const GESTURE_FLASH_MS = 700
+const MARGIN_X = 16
+const MARGIN_TOP = 10
+
+class GestureDotsService {
+  private started = false
+  private flash: GestureDotGlyph | null = null
+  private flashTimer: number | null = null
+  /** Finger currently on the touch bar (tap_start..tap_end; the CFW forwards holds as these edges). */
+  private held = false
+  /** Whether the indicator scene currently has anything on it (needs a clear when the flash ends). */
+  private visible = false
+  private unsubs: Array<() => void> = []
+
+  start(): void {
+    if (this.started) return
+    this.started = true
+    this.unsubs.push(
+      // The indicator owns the screen only while it is empty: drop our
+      // retained state when something else takes over, and clear any
+      // leftover flash when the display empties again.
+      localDisplayManager.onActiveDisplayChange((active) => {
+        if (active) this.visible = false
+        else this.render()
+      }),
+    )
+  }
+
+  stop(): void {
+    for (const unsub of this.unsubs) unsub()
+    this.unsubs = []
+    if (this.flashTimer !== null) BgTimer.clearTimeout(this.flashTimer)
+    this.flashTimer = null
+    this.flash = null
+    this.held = false
+    this.visible = false
+    this.started = false
+    sceneRenderer.clearApp(DOTS_APP_ID)
+  }
+
+  private enabled(): boolean {
+    return useSettingsStore.getState().getSetting(SETTINGS.gesture_dots.key) === true
+  }
+
+  /**
+   * Flash a gesture on the indicator. Other gesture names are ignored. The
+   * device-event router calls this after the CFW dashboard had its chance to
+   * consume the gesture, so dashboard navigation does not flash.
+   */
+  noteGesture(gestureName: string): void {
+    if (!this.started || !this.enabled()) return
+    // Tap edges show a steady circle for as long as the finger is down (on
+    // CFW these arrive for holds: ET_LONG/ET_REL forwarded as
+    // tap_start/tap_end), with no timer — tap_end clears it.
+    if (gestureName === "tap_start" || gestureName === "tap_end") {
+      const held = gestureName === "tap_start"
+      if (this.held === held) return
+      this.held = held
+      this.render()
+      return
+    }
+    const flash: GestureDotGlyph | null =
+      gestureName === "single_tap"
+        ? "dot"
+        : gestureName === "swipe_up"
+          ? "up"
+          : gestureName === "swipe_down"
+            ? "down"
+            : null
+    if (!flash) return
+    this.flash = flash
+    if (this.flashTimer !== null) BgTimer.clearTimeout(this.flashTimer)
+    this.flashTimer = BgTimer.setTimeout(() => {
+      this.flashTimer = null
+      this.flash = null
+      this.render()
+    }, GESTURE_FLASH_MS)
+    this.render()
+  }
+
+  /**
+   * Paint or clear the indicator. Nothing is drawn while anything else is on
+   * the glasses (miniapp frame or system screen) or when no gesture was just
+   * received. The top-right anchor resolves against the device's real canvas,
+   * so no size math here.
+   *
+   * Between flashes the element STAYS in the scene with the blank glyph:
+   * removing it would tear down the firmware image container and rebuild the
+   * page on every flash (a rebuild storm on stock firmware). Only disabling
+   * the setting removes the element outright.
+   */
+  private render(): void {
+    if (!this.started) return
+    if (localDisplayManager.hasActiveDisplay()) return
+    const shown = this.flash ?? (this.held ? "dot" : null)
+    if (!this.enabled()) {
+      if (this.visible) {
+        this.visible = false
+        sceneRenderer.emitScene(DOTS_APP_ID, "main", [])
+      }
+      return
+    }
+    if (!shown && !this.visible) return
+    const elements: SceneElementInput[] = [
+      {
+        type: "image",
+        id: "gesture-dot",
+        box: {
+          x: MARGIN_X,
+          y: MARGIN_TOP,
+          w: GESTURE_DOT_GLYPH_SIZE,
+          h: GESTURE_DOT_GLYPH_SIZE,
+          anchor: "top-right",
+        },
+        data: GESTURE_DOT_GLYPHS[shown ?? "blank"],
+      },
+    ]
+    this.visible = true
+    sceneRenderer.emitScene(DOTS_APP_ID, "main", elements)
+  }
+}
+
+const gestureDotsService = new GestureDotsService()
+export default gestureDotsService
+export {GestureDotsService}

package/src/services/GlassesStatusProjection.ts

@@ -11,22 +11,26 @@
  *
  * Started by `engine.start()`. Idempotent.
  */
-import BluetoothSdk from "@glassly/bluetooth-sdk/internal"
+import BluetoothSdk, {type PublicGlassesStatus} from "@glassly/bluetooth-sdk"
 import {useCoreStore} from "../stores/core"
 import {useGlassesStore} from "../stores/glasses"
-import localMiniappRuntime from "./LocalMiniappRuntime"
 
 let unsubs: Array<() => void> = []
 let projectionRunId = 0
+let glassesStatusForwarder: ((status: Partial<PublicGlassesStatus>) => void) | null = null
+let hydrationPromise: Promise<void> | null = null
 
-export function startGlassesStatusProjection(): void {
-  if (unsubs.length) return
+export function startGlassesStatusProjection(
+  forwarder?: (status: Partial<PublicGlassesStatus>) => void,
+): Promise<void> {
+  if (forwarder) glassesStatusForwarder = forwarder
+  if (unsubs.length) return hydrationPromise ?? Promise.resolve()
 
   const runId = ++projectionRunId
   let bluetoothEventSeen = false
   let glassesEventSeen = false
 
-  void BluetoothSdk.getBluetoothStatus()
+  const bluetoothHydration = BluetoothSdk.getBluetoothStatus()
     .then((status) => {
       if (runId !== projectionRunId || bluetoothEventSeen) return
       useCoreStore.getState().setCoreInfo(status)
@@ -35,7 +39,7 @@ export function startGlassesStatusProjection(): void {
       console.warn("GlassesStatusProjection: getBluetoothStatus failed", error)
     })
 
-  void BluetoothSdk.getGlassesStatus()
+  const glassesHydration = BluetoothSdk.getGlassesStatus()
     .then((status) => {
       if (runId !== projectionRunId || glassesEventSeen) return
       useGlassesStore.getState().setGlassesInfo(status)
@@ -46,28 +50,33 @@ export function startGlassesStatusProjection(): void {
 
   // Bluetooth-adapter status -> core store.
   unsubs.push(
-    BluetoothSdk.onBluetoothStatus((changed) => {
+    BluetoothSdk.subscribeBluetoothStatus((changed) => {
       bluetoothEventSeen = true
       useCoreStore.getState().setCoreInfo(changed)
     }),
   )
 
-  // Glasses status -> glasses store (+ forward to local miniapps; clear any stale
-  // OTA-available flag on disconnect).
+  // Glasses status -> glasses store (+ optional full-runtime forwarding to local
+  // miniapps; clear any stale OTA-available flag on disconnect).
   unsubs.push(
-    BluetoothSdk.onGlassesStatus((changed) => {
+    BluetoothSdk.subscribeGlassesStatus((changed) => {
       glassesEventSeen = true
       useGlassesStore.getState().setGlassesInfo(changed)
-      localMiniappRuntime.forwardEvent("glasses_connection_state", changed)
+      glassesStatusForwarder?.(changed)
       if (changed.connection?.state === "disconnected") {
         useGlassesStore.getState().setOtaUpdateAvailable(null)
       }
     }),
   )
+
+  hydrationPromise = Promise.allSettled([bluetoothHydration, glassesHydration]).then(() => undefined)
+  return hydrationPromise
 }
 
 export function stopGlassesStatusProjection(): void {
   projectionRunId++
   unsubs.forEach((unsub) => unsub())
   unsubs = []
+  glassesStatusForwarder = null
+  hydrationPromise = null
 }

package/src/services/HotspotOtaTransport.ts

@@ -1,4 +1,5 @@
-import BluetoothSdk, {isEnabledHotspotStatus, OtaServer} from "@glassly/bluetooth-sdk/internal"
+import BluetoothSdk, {isEnabledHotspotStatus} from "@glassly/bluetooth-sdk"
+import {otaServer} from "@glassly/bluetooth-sdk/ota-transport"
 // One coordinator selects the native Android or iOS staging implementation at runtime.
 // eslint-disable-next-line react-native/split-platform-components
 import {PermissionsAndroid, Platform} from "react-native"
@@ -83,7 +84,7 @@ class HotspotOtaTransport {
       let localAddress = scopedAddress
       if (Platform.OS === "ios") {
         try {
-          localAddress = await OtaServer.waitForWifiAddress(hotspot.localIp, 15_000)
+          localAddress = await otaServer.waitForWifiAddress(hotspot.localIp, 15_000)
         } catch (error) {
           throw new HotspotOtaTransportError(
             "hotspot_join_failed",
@@ -94,10 +95,10 @@ class HotspotOtaTransport {
       const artifactPaths = Object.fromEntries(this.prepared.map((artifact) => [artifact.sha256, artifact.filePath]))
       // Start exactly one native listener to learn its selected port, then atomically replace
       // the placeholder with the immutable rewritten manifest before ota_start is sent.
-      const server = await OtaServer.startOtaServer("{}", artifactPaths, localAddress)
+      const server = await otaServer.start("{}", artifactPaths, localAddress)
       this.serverStarted = true
       const manifest = rewriteManifestForLocalServer(checkResult.manifestBody, this.prepared, server.baseUrl)
-      const published = await OtaServer.startOtaServer(manifest, artifactPaths, server.host)
+      const published = await otaServer.start(manifest, artifactPaths, server.host)
       if (published.manifestUrl !== server.manifestUrl) {
         throw new Error("Local OTA server endpoint changed while publishing the manifest")
       }
@@ -141,11 +142,11 @@ class HotspotOtaTransport {
     destination: string,
     onProgress?: (bytesWritten: number, contentLength: number) => void,
   ): Promise<{statusCode: number}> => {
-    const subscription = OtaServer.addListener("artifactDownloadProgress", (event) => {
+    const subscription = otaServer.onArtifactDownloadProgress((event) => {
       if (event.destination === destination) onProgress?.(event.bytesWritten, event.contentLength)
     })
     try {
-      return await OtaServer.downloadArtifact(entry.url, destination)
+      return await otaServer.downloadArtifact(entry.url, destination)
     } finally {
       subscription.remove()
     }
@@ -164,7 +165,7 @@ class HotspotOtaTransport {
           console.warn("[OTA_PROGRESS] glasses hotspot shutdown was not confirmed after bounded retries")
         }
       }
-      if (this.serverStarted) await OtaServer.stopOtaServer().catch(() => {})
+      if (this.serverStarted) await otaServer.stop().catch(() => {})
       if (this.localNetworkConnected) await localNetworkTransport.disconnect().catch(() => {})
       await cleanupArtifacts().catch(() => {})
       this.prepared = []

package/src/services/LocalDisplayManager.ts

@@ -115,12 +115,47 @@ class LocalDisplayManager {
 
   private coreApp: string | null = null
   private coreAppDisplay: ActiveDisplay | null = null
-  private currentDisplay: ActiveDisplay | null = null
+  private _currentDisplay: ActiveDisplay | null = null
   private backgroundLock: BackgroundLock | null = null
 
+  /** Fired when the display transitions between empty and occupied (any package, system screens included). */
+  private activeDisplayListeners = new Set<(active: boolean) => void>()
+
+  private get currentDisplay(): ActiveDisplay | null {
+    return this._currentDisplay
+  }
+
+  private set currentDisplay(value: ActiveDisplay | null) {
+    const wasActive = this._currentDisplay !== null
+    this._currentDisplay = value
+    const isActive = value !== null
+    if (wasActive === isActive) return
+    for (const listener of this.activeDisplayListeners) {
+      try {
+        listener(isActive)
+      } catch (error) {
+        console.error(`${LOG_TAG}: onActiveDisplayChange listener failed:`, error)
+      }
+    }
+  }
+
+  /** True while anything (miniapp or system screen) is on the glasses display. */
+  public hasActiveDisplay(): boolean {
+    return this._currentDisplay !== null
+  }
+
+  /** Subscribe to empty↔occupied display transitions. Returns an unsubscribe. */
+  public onActiveDisplayChange(listener: (active: boolean) => void): () => void {
+    this.activeDisplayListeners.add(listener)
+    return () => this.activeDisplayListeners.delete(listener)
+  }
+
   private bootingApp: BootingApp | null = null
   private bootQueue: Map<string, {payload: DisplayPayload; resolve?: DisplayRequestResolver}> = new Map()
 
+  /** Miniapp whose visible frame is temporarily covered by an OS exit notice. */
+  private exitingApp: {packageName: string; coveredDisplay: ActiveDisplay} | null = null
+
   private expiryTimerId: number | null = null
 
   /** Reconnect-replay subscription state (attachToRuntime). */
@@ -200,7 +235,7 @@ class LocalDisplayManager {
    */
   public showSystemNotice(text: string, durationMs: number = SYSTEM_NOTICE_DURATION_MS): void {
     if (!isGlassesConnected(useGlassesStore.getState().connection)) return
-    if (this.bootingApp) return
+    if (this.bootingApp || this.exitingApp) return
     console.log(`${LOG_TAG}: showSystemNotice("${text}")`)
     this.sendNow(SYSTEM_NOTICE_PKG, {
       view: "main",
@@ -228,6 +263,88 @@ class LocalDisplayManager {
     }
   }
 
+  /**
+   * The package that currently owns the glasses screen, for gesture-claim
+   * arbitration (see LocalMiniappRuntime.foregroundClaimsGesture). This is
+   * glasses ownership, not the phone's Compositor foreground: a background
+   * miniapp rendering to the glasses with the phone pocketed is the owner.
+   *
+   * The live frame's owner wins; a background app that holds the display lock
+   * but has no frame up right now (between renders) still counts. System
+   * frames (boot, notices) own nothing claimable. Returns null when the
+   * glasses are idle.
+   */
+  public getGestureOwner(): string | null {
+    const current = this.currentDisplay?.packageName ?? null
+    if (current && current !== SYSTEM_BOOT_PKG && current !== SYSTEM_NOTICE_PKG) return current
+    const lock = this.backgroundLock
+    if (lock && this.now() <= lock.expiresAt) return lock.packageName
+    return null
+  }
+
+  /**
+   * The miniapp whose frame is visibly on the glasses right now.
+   *
+   * Unlike getGestureOwner(), this deliberately does not fall back to a
+   * background display lock: a lock holder with no live frame is not visible
+   * and therefore must not be closed by the system double-tap gesture.
+   */
+  public getVisibleMiniappPackageName(): string | null {
+    const current = this.currentDisplay?.packageName ?? null
+    if (!current || current === SYSTEM_BOOT_PKG || current === SYSTEM_NOTICE_PKG) return null
+    return current
+  }
+
+  /**
+   * Cover the currently visible miniapp with a persistent system exit notice.
+   * While it is up, miniapp display traffic is held off so a streaming app
+   * cannot immediately overwrite the notice. The caller completes the normal
+   * stop flow and then calls finishMiniappExit(); onUnmount does the same as a
+   * safety net.
+   */
+  public beginMiniappExit(packageName: string, text: string): boolean {
+    if (this.exitingApp !== null) return this.exitingApp.packageName === packageName
+    const coveredDisplay = this.currentDisplay
+    if (!coveredDisplay || this.getVisibleMiniappPackageName() !== packageName) return false
+
+    console.log(`${LOG_TAG}: beginMiniappExit(${packageName})`)
+    this.exitingApp = {packageName, coveredDisplay}
+    this.clearExpiryTimer()
+    this.sendNow(SYSTEM_NOTICE_PKG, {
+      view: "main",
+      layout: {layoutType: "text_wall", text},
+    })
+    return true
+  }
+
+  /** Remove an exit notice and resume the display state normal app teardown leaves behind. */
+  public finishMiniappExit(packageName: string): void {
+    if (this.exitingApp?.packageName !== packageName) return
+    console.log(`${LOG_TAG}: finishMiniappExit(${packageName})`)
+    this.exitingApp = null
+
+    if (this.currentDisplay?.packageName !== SYSTEM_NOTICE_PKG) return
+    this.currentDisplay = null
+    this.tryRestoreCoreDisplay()
+    if (!this.currentDisplay) this.sendClear()
+  }
+
+  /** Cancel the handoff and put back the frame the exit notice covered. */
+  public cancelMiniappExit(packageName: string): void {
+    if (this.exitingApp?.packageName !== packageName) return
+    const covered = this.exitingApp.coveredDisplay
+    this.exitingApp = null
+
+    if (this.currentDisplay?.packageName !== SYSTEM_NOTICE_PKG) return
+    if (covered.expiresAt === null || covered.expiresAt > this.now()) {
+      this.restoreDisplay(covered)
+    } else {
+      this.currentDisplay = null
+      this.tryRestoreCoreDisplay()
+      if (!this.currentDisplay) this.sendClear()
+    }
+  }
+
   /** Report-safe ownership snapshot for incident diagnostics. */
   public getDiagnosticSnapshot(): Record<string, unknown> {
     return {
@@ -235,6 +352,7 @@ class LocalDisplayManager {
       currentDisplayPackageName: this.currentDisplay?.packageName ?? null,
       backgroundLockPackageName: this.backgroundLock?.packageName ?? null,
       bootingPackageName: this.bootingApp?.packageName ?? null,
+      exitingPackageName: this.exitingApp?.packageName ?? null,
     }
   }
 
@@ -297,6 +415,8 @@ class LocalDisplayManager {
         this.sendClear()
       }
     }
+
+    this.finishMiniappExit(packageName)
   }
 
   // ===========================================================================
@@ -313,6 +433,13 @@ class LocalDisplayManager {
    * the boot queue (resolved when drained or superseded).
    */
   public request(packageName: string, payload: DisplayPayload, resolve?: DisplayRequestResolver): void {
+    // Keep the OS exit notice visible for its short handoff window. Without
+    // this, streaming captions/terminal frames can replace it immediately.
+    if (this.exitingApp !== null) {
+      resolve?.({status: "blocked", reason: "a miniapp exit notice is active"})
+      return
+    }
+
     // Dashboard view: pass straight through (no throttle/arbitration). Local
     // dashboard rendering is currently a stub on the phone anyway.
     if (payload.view === "dashboard") {
@@ -785,6 +912,7 @@ class LocalDisplayManager {
     this.coreAppDisplay = null
     this.currentDisplay = null
     this.backgroundLock = null
+    this.exitingApp = null
     this.bootQueue.clear()
     this.now = () => Date.now()
     this.unsubscribeGlassesStatus?.()

package/src/services/LocalMiniappRuntime.ts

@@ -52,6 +52,7 @@ import {normalizeAiTier, resolveAiTier} from "./AiTierResolution"
 import type {AiTier, AiTierProvider, SavedLlmKeys} from "./AiTierResolution"
 import {HttpError} from "@glassly/cloud-client"
 import localDisplayManager from "./LocalDisplayManager"
+import {claimsGesture} from "./gestureClaims"
 import nativeNavigationService from "./NativeNavigationService"
 import type {DisplayPayload} from "./LocalDisplayManager"
 import headingService from "./HeadingService"
@@ -539,6 +540,8 @@ class LocalMiniappRuntime {
 
   /** Connected miniapps keyed by packageName. */
   private connectedApps: Map<string, ConnectedMiniapp> = new Map()
+  /** Per-app claimed gestures (CLAIM_GESTURES) — see foregroundClaimsGesture. */
+  private gestureClaims: Map<string, Set<string>> = new Map()
 
   /**
    * Packages that have completed their CONNECT handshake (sent
@@ -1173,6 +1176,7 @@ class LocalMiniappRuntime {
     // core app's saved frame).
     localDisplayManager.onUnmount(packageName)
 
+    this.gestureClaims.delete(packageName)
     this.connectedApps.delete(packageName)
     this.recomputeMicRequirements()
     if (releasedMicGateOverride) {
@@ -1251,6 +1255,9 @@ class LocalMiniappRuntime {
       case MiniappRequestType.SUBSCRIBE:
         this.handleSubscribe(packageName, payload, requestId)
         break
+      case MiniappRequestType.CLAIM_GESTURES:
+        this.handleClaimGestures(packageName, payload, requestId)
+        break
       case MiniappRequestType.DISPLAY:
         this.handleDisplay(packageName, payload, requestId)
         break
@@ -1858,6 +1865,36 @@ class LocalMiniappRuntime {
     this.sendResult(packageName, requestId, true, {applied: true})
   }
 
+  /**
+   * CLAIM_GESTURES (session.input.setClaimedGestures): the app declares which
+   * touch gestures it handles itself, replacing its previous claim set.
+   * Claims suppress the host's default behavior for those gestures (today:
+   * double_tap → dashboard/head-up in DeviceEventRouter) but ONLY while the
+   * claiming app is the one in front of the user — see
+   * {@link foregroundClaimsGesture}. Cleared on app stop.
+   */
+  private handleClaimGestures(packageName: string, payload: Record<string, unknown>, requestId?: string): void {
+    if (!this.connectedApps.has(packageName)) {
+      this.sendResult(packageName, requestId, true)
+      return
+    }
+    const raw = payload.gestures
+    const gestures = Array.isArray(raw) ? raw.filter((g): g is string => typeof g === "string") : []
+    if (gestures.length === 0) this.gestureClaims.delete(packageName)
+    else this.gestureClaims.set(packageName, new Set(gestures))
+    this.sendResult(packageName, requestId, true)
+  }
+
+  /** True iff the miniapp in front of the user has claimed `gesture`. */
+  public foregroundClaimsGesture(gesture: string): boolean {
+    return claimsGesture(
+      this.gestureClaims,
+      gesture,
+      localDisplayManager.getGestureOwner(),
+      useAppStatusStore.getState().foregroundedPackage,
+    )
+  }
+
   private handleSubscribe(packageName: string, payload: Record<string, unknown>, requestId?: string): void {
     const app = this.connectedApps.get(packageName)
     if (!app) return

package/src/services/MiniappExitGesture.ts

@@ -0,0 +1,76 @@
+export const MINIAPP_EXIT_NOTICE_MS = 1500
+
+interface ExitGestureApp {
+  packageName: string
+  name: string
+  running: boolean
+}
+
+interface ExitGestureState {
+  apps: ExitGestureApp[]
+  foregroundedPackage: string | null
+  clearForeground: () => void
+  stop: (packageName: string) => Promise<void>
+}
+
+export interface ExitGestureDependencies {
+  getState: () => ExitGestureState
+  getVisiblePackageName: () => string | null
+  beginExitNotice: (packageName: string, text: string) => boolean
+  finishExitNotice: (packageName: string) => void
+  cancelExitNotice: (packageName: string) => void
+  setTimeout: (callback: () => void, delay: number) => number
+  clearTimeout: (timerId: number) => void
+}
+
+/** Owns the short double-tap → exit-notice → normal-stop handoff. */
+export class MiniappExitGesture {
+  private pending: {packageName: string; timerId: number} | null = null
+
+  public constructor(private readonly deps: ExitGestureDependencies) {}
+
+  /** Returns true when the system gesture was consumed by a visible miniapp exit. */
+  public tryExitVisibleMiniapp(): boolean {
+    // Swallow repeat taps while the notice is already counting down.
+    if (this.pending) return true
+
+    const packageName = this.deps.getVisiblePackageName()
+    if (!packageName) return false
+
+    const app = this.deps.getState().apps.find((candidate) => candidate.packageName === packageName)
+    if (!app?.running) return false
+
+    const name = app.name.trim() || packageName
+    if (!this.deps.beginExitNotice(packageName, `Exiting ${name}…`)) return false
+
+    const timerId = this.deps.setTimeout(() => {
+      const state = this.deps.getState()
+      if (state.foregroundedPackage === packageName) state.clearForeground()
+
+      const stillRunning = state.apps.some((candidate) => candidate.packageName === packageName && candidate.running)
+      const stop = stillRunning ? state.stop(packageName) : Promise.resolve()
+      void stop
+        .catch((error) => {
+          console.error(`MiniappExitGesture: failed to stop ${packageName}:`, error)
+        })
+        .finally(() => {
+          if (this.pending?.packageName === packageName) this.pending = null
+          // LocalMiniappRuntime.onUnmount normally finishes the notice. This
+          // fallback also handles a failed/no-op teardown.
+          this.deps.finishExitNotice(packageName)
+        })
+    }, MINIAPP_EXIT_NOTICE_MS)
+
+    this.pending = {packageName, timerId}
+    return true
+  }
+
+  /** Cancel an in-flight handoff when the device-event router shuts down. */
+  public reset(): void {
+    if (!this.pending) return
+    const {packageName, timerId} = this.pending
+    this.pending = null
+    this.deps.clearTimeout(timerId)
+    this.deps.cancelExitNotice(packageName)
+  }
+}