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

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 dashboardCoordinator from "./DashboardCoordinator"
+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 (dashboardCoordinator.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 (dashboardCoordinator.toggleCustom()) 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) {
@@ -198,9 +238,7 @@ export function startDeviceEventRouter(): void {
             })
           }
         } else {
-          void Promise.resolve(BluetoothSdk.toggleHeadUp()).catch((err) => {
-            console.error("DeviceEventRouter: toggleHeadUp failed:", err)
-          })
+          dashboardCoordinator.toggleLegacy()
         }
       }
     }),
@@ -219,6 +257,7 @@ export function startDeviceEventRouter(): void {
   // Head position — translate native {up:boolean} → SDK {position:"up"|"down"}.
   subs.push(
     BluetoothSdk.addListener("head_up", (event) => {
+      dashboardCoordinator.setHeadUp(event.up)
       localMiniappRuntime.forwardEvent("head_up", {position: event.up ? "up" : "down", timestamp: Date.now()})
     }),
   )
@@ -263,4 +302,5 @@ export function startDeviceEventRouter(): void {
 export function stopDeviceEventRouter(): void {
   for (const sub of subs) sub.remove()
   subs = []
+  miniappExitGesture.reset()
 }

package/src/services/DisplayProcessor.ts

@@ -2,15 +2,15 @@
  * DisplayProcessor
  *
  * Processes display events with pixel-accurate text wrapping using the same
- * display-utils library as the cloud. This ensures the mobile preview matches
- * exactly what is shown on the glasses.
+ * Engine display utilities. This ensures the mobile preview matches exactly
+ * what is shown on the glasses.
  *
  * Key responsibilities:
  * 1. Intercept display events before sending to native SGC
  * 2. Wrap text using the correct device profile (G1, etc.)
  * 3. Ensure GlassesDisplayMirror shows exactly what glasses will show
  *
- * @see cloud/issues/026-mobile-display-processor for design docs
+ * @see notes/miniapp-display-api-redesign.md for the current display design
  */
 
 import {

package/src/services/GestureDotsService.ts

@@ -0,0 +1,164 @@
+/**
+ * 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), a bullseye while a CFW tap-then-hold is held. 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
+  /**
+   * The CFW's tap_then_hold fired during this press (discrete recognition
+   * event; the tap_end that follows on release is what clears it).
+   */
+  private holdRecognized = 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.holdRecognized = 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
+      if (!held) this.holdRecognized = false
+      this.render()
+      return
+    }
+    // CFW tap-then-hold (the stock Menu gesture): swap the steady dot for the
+    // bullseye until release. Recognition arrives mid-press, but set held too
+    // in case the tap_start edge was missed — the release edge still clears.
+    if (gestureName === "tap_then_hold") {
+      this.held = true
+      this.holdRecognized = true
+      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 ? (this.holdRecognized ? "hold" : "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 = []