@glassly/engine 0.1.0-dev.99 → 0.2.8-dev.445

package/src/services/GlassesKeyboardInput.ts

@@ -0,0 +1,306 @@
+import type {KeyboardKeyEvent} from "@glassly/bluetooth-sdk"
+
+import localMiniappRuntime from "./LocalMiniappRuntime"
+import {BgTimer} from "../utils/timers"
+
+/**
+ * Keyboard event as miniapps receive it on the `keyboard_event` stream. The
+ * shape mirrors the DOM: `key` is the logical key (layout applied, US only for
+ * now), `code` the physical key, `text` the printable character the press
+ * produces (down/repeat only), `repeat` a synthesized auto-repeat of a held key.
+ */
+export interface KeyboardEventPayload {
+  phase: "down" | "up"
+  key: string
+  code: string
+  modifiers: {shift: boolean; ctrl: boolean; alt: boolean; meta: boolean}
+  text?: string
+  repeat: boolean
+  timestamp: number
+}
+
+interface Timers {
+  setTimeout: (callback: () => void, delayMs: number) => number
+  clearTimeout: (id: number) => void
+}
+
+export interface KeyboardInputOptions {
+  forward: (payload: KeyboardEventPayload) => void
+  timers?: Timers
+  now?: () => number
+  /** Typematic delay before the first repeat and the interval between repeats. */
+  repeatDelayMs?: number
+  repeatIntervalMs?: number
+}
+
+const REPEAT_DELAY_MS = 400
+const REPEAT_INTERVAL_MS = 50
+
+/** [unshifted, shifted] for US layout punctuation on the keyboard page. */
+const PUNCTUATION: Record<number, [string, string, string]> = {
+  45: ["-", "_", "Minus"],
+  46: ["=", "+", "Equal"],
+  47: ["[", "{", "BracketLeft"],
+  48: ["]", "}", "BracketRight"],
+  49: ["\\", "|", "Backslash"],
+  50: ["#", "~", "IntlHash"],
+  51: [";", ":", "Semicolon"],
+  52: ["'", '"', "Quote"],
+  53: ["`", "~", "Backquote"],
+  54: [",", "<", "Comma"],
+  55: [".", ">", "Period"],
+  56: ["/", "?", "Slash"],
+  100: ["\\", "|", "IntlBackslash"],
+}
+
+const SHIFTED_DIGITS = "!@#$%^&*()"
+const DIGITS = "1234567890"
+
+const NAMED: Record<number, [string, string]> = {
+  40: ["Enter", "Enter"],
+  41: ["Escape", "Escape"],
+  42: ["Backspace", "Backspace"],
+  43: ["Tab", "Tab"],
+  57: ["CapsLock", "CapsLock"],
+  70: ["PrintScreen", "PrintScreen"],
+  71: ["ScrollLock", "ScrollLock"],
+  72: ["Pause", "Pause"],
+  73: ["Insert", "Insert"],
+  74: ["Home", "Home"],
+  75: ["PageUp", "PageUp"],
+  76: ["Delete", "Delete"],
+  77: ["End", "End"],
+  78: ["PageDown", "PageDown"],
+  79: ["ArrowRight", "ArrowRight"],
+  80: ["ArrowLeft", "ArrowLeft"],
+  81: ["ArrowDown", "ArrowDown"],
+  82: ["ArrowUp", "ArrowUp"],
+  83: ["NumLock", "NumLock"],
+  88: ["Enter", "NumpadEnter"],
+  101: ["ContextMenu", "ContextMenu"],
+  102: ["Power", "Power"],
+  224: ["Control", "ControlLeft"],
+  225: ["Shift", "ShiftLeft"],
+  226: ["Alt", "AltLeft"],
+  227: ["Meta", "MetaLeft"],
+  228: ["Control", "ControlRight"],
+  229: ["Shift", "ShiftRight"],
+  230: ["Alt", "AltRight"],
+  231: ["Meta", "MetaRight"],
+}
+
+const NUMPAD: Record<number, [string, string]> = {
+  84: ["/", "NumpadDivide"],
+  85: ["*", "NumpadMultiply"],
+  86: ["-", "NumpadSubtract"],
+  87: ["+", "NumpadAdd"],
+  99: [".", "NumpadDecimal"],
+  103: ["=", "NumpadEqual"],
+}
+
+const CONSUMER: Record<number, string> = {
+  0xe9: "AudioVolumeUp",
+  0xea: "AudioVolumeDown",
+  0xe2: "AudioVolumeMute",
+  0xcd: "MediaPlayPause",
+  0xb0: "MediaPlay",
+  0xb1: "MediaPause",
+  0xb5: "MediaTrackNext",
+  0xb6: "MediaTrackPrevious",
+  0xb7: "MediaStop",
+  0x6f: "BrightnessUp",
+  0x70: "BrightnessDown",
+  0x221: "BrowserSearch",
+  0x223: "BrowserHome",
+  0x224: "BrowserBack",
+  0x225: "BrowserForward",
+  0x18a: "LaunchMail",
+  0x192: "LaunchApplication2",
+  0x194: "LaunchApplication1",
+}
+
+interface Translated {
+  key: string
+  code: string
+  text?: string
+}
+
+/**
+ * Map one HID usage to DOM-style key/code/text under the US layout. Exported
+ * for tests; `shift` is the effective shift (Shift XOR CapsLock for letters).
+ */
+export function translateUsage(page: number, usage: number, shift: boolean, capsLock: boolean): Translated {
+  if (page === 7) {
+    if (usage >= 4 && usage <= 29) {
+      const lower = String.fromCharCode(97 + usage - 4)
+      const upper = shift !== capsLock
+      const key = upper ? lower.toUpperCase() : lower
+      return {key, code: `Key${lower.toUpperCase()}`, text: key}
+    }
+    if (usage >= 30 && usage <= 39) {
+      const index = usage - 30
+      const key = shift ? SHIFTED_DIGITS[index]! : DIGITS[index]!
+      return {key, code: `Digit${DIGITS[index]}`, text: key}
+    }
+    if (usage === 44) return {key: " ", code: "Space", text: " "}
+    const punctuation = PUNCTUATION[usage]
+    if (punctuation) {
+      const key = shift ? punctuation[1] : punctuation[0]
+      return {key, code: punctuation[2], text: key}
+    }
+    if (usage >= 58 && usage <= 69) return {key: `F${usage - 57}`, code: `F${usage - 57}`}
+    if (usage >= 104 && usage <= 115) return {key: `F${usage - 91}`, code: `F${usage - 91}`}
+    if (usage >= 89 && usage <= 97) {
+      const digit = String(usage - 88)
+      return {key: digit, code: `Numpad${digit}`, text: digit}
+    }
+    if (usage === 98) return {key: "0", code: "Numpad0", text: "0"}
+    const numpad = NUMPAD[usage]
+    if (numpad) return {key: numpad[0], code: numpad[1], text: numpad[0]}
+    const named = NAMED[usage]
+    if (named) return {key: named[0], code: named[1]}
+    return {key: "Unidentified", code: `Usage${usage.toString(16).padStart(2, "0")}`}
+  }
+  if (page === 12) {
+    const name = CONSUMER[usage]
+    return name ? {key: name, code: name} : {key: "Unidentified", code: `Consumer${usage.toString(16)}`}
+  }
+  return {key: "Unidentified", code: `Page${page.toString(16)}Usage${usage.toString(16)}`}
+}
+
+const MODIFIER_USAGES = new Set([224, 225, 226, 227, 228, 229, 230, 231])
+
+/**
+ * Turns the native bridge's raw HID transitions into layout-translated
+ * keyboard events and synthesizes typematic auto-repeat, which BLE HID
+ * keyboards never send (the report just stays asserted). Modifier state is
+ * derived from the same stream, so a lost release (the bridge emits an `up`
+ * for every gap) always clears it.
+ */
+export class GlassesKeyboardInput {
+  private readonly forward: (payload: KeyboardEventPayload) => void
+  private readonly timers: Timers
+  private readonly now: () => number
+  private readonly repeatDelayMs: number
+  private readonly repeatIntervalMs: number
+  private held = new Map<string, {page: number; usage: number}>()
+  private modifiers = {shift: false, ctrl: false, alt: false, meta: false}
+  private capsLock = false
+  private repeatTimer: number | null = null
+  private repeating: {page: number; usage: number} | null = null
+
+  constructor(options: KeyboardInputOptions) {
+    this.forward = options.forward
+    this.timers = options.timers ?? {
+      setTimeout: (callback, delay) => BgTimer.setTimeout(callback, delay),
+      clearTimeout: (id) => BgTimer.clearTimeout(id),
+    }
+    this.now = options.now ?? (() => Date.now())
+    this.repeatDelayMs = options.repeatDelayMs ?? REPEAT_DELAY_MS
+    this.repeatIntervalMs = options.repeatIntervalMs ?? REPEAT_INTERVAL_MS
+  }
+
+  /** One raw transition from the `keyboard_key` native event. */
+  handle(event: KeyboardKeyEvent): void {
+    const id = `${event.page}:${event.usage}`
+    if (event.down) {
+      if (this.held.has(id)) return // duplicate report; the firmware already de-duplicates
+      this.held.set(id, {page: event.page, usage: event.usage})
+      this.applyModifier(event.page, event.usage, true)
+      if (event.page === 7 && event.usage === 57) this.capsLock = !this.capsLock
+      this.emit("down", event.page, event.usage, false, event.timestamp)
+      if (!(event.page === 7 && MODIFIER_USAGES.has(event.usage))) this.startRepeat(event.page, event.usage)
+    } else {
+      if (!this.held.delete(id)) return
+      this.applyModifier(event.page, event.usage, false)
+      if (this.repeating?.page === event.page && this.repeating.usage === event.usage) this.stopRepeat()
+      this.emit("up", event.page, event.usage, false, event.timestamp)
+    }
+  }
+
+  /** Link lost or keyboard dropped: forget everything without emitting. */
+  reset(): void {
+    this.stopRepeat()
+    this.held.clear()
+    this.modifiers = {shift: false, ctrl: false, alt: false, meta: false}
+    this.capsLock = false
+  }
+
+  private applyModifier(page: number, usage: number, down: boolean): void {
+    if (page !== 7) return
+    switch (usage) {
+      case 224:
+      case 228:
+        this.modifiers.ctrl = down || this.otherHeld(usage === 224 ? 228 : 224)
+        break
+      case 225:
+      case 229:
+        this.modifiers.shift = down || this.otherHeld(usage === 225 ? 229 : 225)
+        break
+      case 226:
+      case 230:
+        this.modifiers.alt = down || this.otherHeld(usage === 226 ? 230 : 226)
+        break
+      case 227:
+      case 231:
+        this.modifiers.meta = down || this.otherHeld(usage === 227 ? 231 : 227)
+        break
+    }
+  }
+
+  private otherHeld(usage: number): boolean {
+    return this.held.has(`7:${usage}`)
+  }
+
+  private emit(phase: "down" | "up", page: number, usage: number, repeat: boolean, timestamp: number): void {
+    const translated = translateUsage(page, usage, this.modifiers.shift, this.capsLock)
+    const payload: KeyboardEventPayload = {
+      phase,
+      key: translated.key,
+      code: translated.code,
+      modifiers: {...this.modifiers},
+      repeat,
+      timestamp,
+    }
+    // Text only for plain presses: Ctrl/Alt/Meta chords are commands, not typing.
+    if (
+      phase === "down" &&
+      translated.text !== undefined &&
+      !this.modifiers.ctrl &&
+      !this.modifiers.alt &&
+      !this.modifiers.meta
+    ) {
+      payload.text = translated.text
+    }
+    this.forward(payload)
+  }
+
+  private startRepeat(page: number, usage: number): void {
+    this.stopRepeat()
+    this.repeating = {page, usage}
+    this.repeatTimer = this.timers.setTimeout(() => this.repeatTick(), this.repeatDelayMs)
+  }
+
+  private repeatTick(): void {
+    const key = this.repeating
+    if (!key || !this.held.has(`${key.page}:${key.usage}`)) {
+      this.stopRepeat()
+      return
+    }
+    this.emit("down", key.page, key.usage, true, this.now())
+    this.repeatTimer = this.timers.setTimeout(() => this.repeatTick(), this.repeatIntervalMs)
+  }
+
+  private stopRepeat(): void {
+    if (this.repeatTimer !== null) this.timers.clearTimeout(this.repeatTimer)
+    this.repeatTimer = null
+    this.repeating = null
+  }
+}
+
+/** Engine singleton: fans translated events out to subscribed miniapps. */
+const glassesKeyboardInput = new GlassesKeyboardInput({
+  forward: (payload) => localMiniappRuntime.forwardEvent("keyboard_event", payload),
+})
+
+export default glassesKeyboardInput

package/src/services/GlassesSensorService.ts

@@ -0,0 +1,233 @@
+import BluetoothSdk from "@glassly/bluetooth-sdk/internal"
+import {MiniappErrorCode} from "@glassly/miniapp/protocol"
+import {BgTimer} from "../utils/timers"
+
+type Sensor = "light" | "compass"
+type Operation = "query" | "start" | "stop"
+type Options = Record<string, number>
+type Control = (sensor: Sensor, operation: Operation, options: Options) => Promise<boolean>
+type Owner = {app: string; options: Options}
+
+const RANGES: Record<Sensor, Record<string, [number, number]>> = {
+  light: {intervalMs: [100, 5000], minDelta: [0, 65535], heartbeatMs: [0, 65535]},
+  compass: {intervalMs: [50, 2000], minChangeDegrees: [0, 359]},
+}
+const COMPASS_DEFAULTS: Options = {intervalMs: 1000, minChangeDegrees: 5}
+const COMPASS_RETRY_MS = [2000, 4000, 8000]
+
+function fail(code: MiniappErrorCode, message: string): never {
+  throw Object.assign(new Error(message), {code})
+}
+
+function sameOptions(a: Options | null, b: Options | null): boolean {
+  if (!a || !b) return a === b
+  const keys = new Set([...Object.keys(a), ...Object.keys(b)])
+  for (const key of keys) if (a[key] !== b[key]) return false
+  return true
+}
+
+/**
+ * Light: explicit, miniapp-scoped ownership. A subscriber alone never changes auto brightness.
+ * Compass: demand-driven. It runs while any miniapp is subscribed; `start(options)` only
+ * records that miniapp's override and everyone is served the smallest interval and
+ * threshold requested. Native navigation temporarily borrows both; its stock configuration wins.
+ */
+export class GlassesSensorService {
+  private lightOwner: Owner | null = null
+  private compassSubscribers = new Set<string>()
+  private compassOverrides = new Map<string, Options>()
+  /** Options the firmware currently runs; null while stopped. */
+  private compassApplied: Options | null = null
+  private compassRetry: number | null = null
+  private compassRetryAttempt = 0
+  private pending: Promise<unknown> = Promise.resolve()
+  private navigationActive = false
+  private generation = 0
+
+  constructor(private readonly control: Control) {}
+
+  private serial<T>(work: () => Promise<T>): Promise<T> {
+    const next = this.pending.then(work)
+    this.pending = next.catch(() => {})
+    return next
+  }
+
+  private validate(payload: Record<string, unknown>): {sensor: Sensor; operation: Operation; options: Options} {
+    const sensor = payload.sensor
+    const operation = payload.operation
+    if (sensor !== "light" && sensor !== "compass") fail(MiniappErrorCode.INVALID_ARGUMENT, "Unknown sensor")
+    if (operation !== "start" && operation !== "stop" && !(sensor === "light" && operation === "query")) {
+      fail(MiniappErrorCode.INVALID_ARGUMENT, "Unknown sensor operation")
+    }
+    const raw = payload.options ?? {}
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+      fail(MiniappErrorCode.INVALID_ARGUMENT, "Invalid sensor options")
+    const ranges = RANGES[sensor]
+    const options: Options = {}
+    for (const [key, value] of Object.entries(raw)) {
+      const range = Object.prototype.hasOwnProperty.call(ranges, key) ? ranges[key] : undefined
+      if (!range || typeof value !== "number" || !Number.isInteger(value) || value < range[0] || value > range[1]) {
+        fail(MiniappErrorCode.INVALID_ARGUMENT, `Invalid ${key}`)
+      }
+      options[key] = value
+    }
+    return {sensor, operation, options}
+  }
+
+  request(app: string, payload: Record<string, unknown>): Promise<void> {
+    const generation = this.generation
+    return this.serial(async () => {
+      if (generation !== this.generation) fail(MiniappErrorCode.NOT_CONNECTED, "Glasses disconnected")
+      const {sensor, operation, options} = this.validate(payload)
+      if (sensor === "compass") {
+        if (operation === "start") this.compassOverrides.set(app, options)
+        else this.compassOverrides.delete(app)
+        if (this.navigationActive) return
+        await this.applyCompass(generation, true)
+        return
+      }
+      const owner = this.lightOwner
+      if (operation !== "query" && owner && owner.app !== app) {
+        fail(MiniappErrorCode.INVALID_ARGUMENT, "This sensor is controlled by another miniapp")
+      }
+      if (operation === "stop" && !owner) return
+      if (this.navigationActive) {
+        if (operation === "stop") {
+          this.lightOwner = null
+          return
+        }
+        fail(MiniappErrorCode.INVALID_ARGUMENT, "Native navigation currently owns the glasses sensors")
+      }
+      // Keep cleanup ownership even after an ambiguous transport failure: the firmware
+      // may have applied the command before its ACK was lost.
+      if (operation === "start") this.lightOwner = {app, options}
+      if (!(await this.control("light", operation, options))) this.commandFailed()
+      if (generation !== this.generation) fail(MiniappErrorCode.NOT_CONNECTED, "Glasses disconnected")
+      if (operation === "stop") this.lightOwner = null
+    })
+  }
+
+  private commandFailed(): never {
+    fail(
+      MiniappErrorCode.INTERNAL,
+      "Sensor command failed: connect G2 custom firmware and keep its miniapp display active",
+    )
+  }
+
+  /** Miniapps currently subscribed to the glasses compass stream. Replaces the previous set. */
+  setCompassSubscribers(apps: Iterable<string>): Promise<void> {
+    const generation = this.generation
+    return this.serial(async () => {
+      this.compassSubscribers = new Set(apps)
+      if (generation !== this.generation || this.navigationActive) return
+      await this.applyCompass(generation, false)
+    })
+  }
+
+  private compassDemand(): Options | null {
+    if (this.compassSubscribers.size === 0 && this.compassOverrides.size === 0) return null
+    const requests = [...this.compassOverrides.values()].map((o) => ({...COMPASS_DEFAULTS, ...o}))
+    for (const app of this.compassSubscribers) if (!this.compassOverrides.has(app)) requests.push(COMPASS_DEFAULTS)
+    const demand: Options = {}
+    for (const key of Object.keys(COMPASS_DEFAULTS)) demand[key] = Math.min(...requests.map((r) => r[key]))
+    return demand
+  }
+
+  /**
+   * Bring the firmware in line with current demand. Explicit requests surface failures;
+   * subscription-driven applies stay silent (stock firmware, no CFW carrier yet) and retry
+   * a few times so a compass subscribed before firmware classification still starts.
+   */
+  private async applyCompass(generation: number, explicit: boolean): Promise<void> {
+    this.clearCompassRetry()
+    const demand = this.compassDemand()
+    if (sameOptions(demand, this.compassApplied)) return
+    if (!demand) {
+      const ok = await this.control("compass", "stop", {})
+      if (generation === this.generation) this.compassApplied = null
+      if (!ok && explicit) this.commandFailed()
+      return
+    }
+    const ok = await this.control("compass", "start", demand)
+    if (generation !== this.generation) {
+      if (explicit) fail(MiniappErrorCode.NOT_CONNECTED, "Glasses disconnected")
+      return
+    }
+    if (ok) {
+      this.compassApplied = demand
+      this.compassRetryAttempt = 0
+      return
+    }
+    if (explicit) this.commandFailed()
+    const delay = COMPASS_RETRY_MS[this.compassRetryAttempt]
+    if (delay === undefined) return
+    this.compassRetryAttempt++
+    this.compassRetry = BgTimer.setTimeout(() => {
+      this.compassRetry = null
+      void this.resync()
+    }, delay)
+  }
+
+  private clearCompassRetry(): void {
+    if (this.compassRetry != null) BgTimer.clearTimeout(this.compassRetry)
+    this.compassRetry = null
+  }
+
+  /** Re-apply compass demand after the glasses connect or their firmware is classified. */
+  resync(): Promise<void> {
+    const generation = this.generation
+    return this.serial(async () => {
+      if (generation !== this.generation || this.navigationActive) return
+      await this.applyCompass(generation, false).catch(() => {})
+    })
+  }
+
+  release(app: string): Promise<void> {
+    const generation = this.generation
+    return this.serial(async () => {
+      if (generation !== this.generation) return
+      const hadSubscription = this.compassSubscribers.delete(app)
+      const hadOverride = this.compassOverrides.delete(app)
+      const hadCompass = hadSubscription || hadOverride
+      if (this.lightOwner?.app === app) {
+        if (!this.navigationActive) await this.control("light", "stop", {}).catch(() => false)
+        this.lightOwner = null
+      }
+      if (hadCompass && !this.navigationActive) await this.applyCompass(generation, false).catch(() => {})
+    })
+  }
+
+  setNavigationActive(active: boolean): Promise<void> {
+    const generation = this.generation
+    return this.serial(async () => {
+      if (generation !== this.generation) return
+      if (this.navigationActive === active) return
+      this.navigationActive = active
+      this.clearCompassRetry()
+      if (active) {
+        if (this.lightOwner) await this.control("light", "stop", {}).catch(() => false)
+        if (this.compassApplied) await this.control("compass", "stop", {}).catch(() => false)
+        this.compassApplied = null
+        return
+      }
+      if (this.lightOwner) await this.control("light", "start", this.lightOwner.options).catch(() => false)
+      this.compassRetryAttempt = 0
+      await this.applyCompass(generation, false).catch(() => {})
+    })
+  }
+
+  /** Never replay requests from an old miniapp connection onto a new pair of glasses. */
+  disconnected(): void {
+    this.generation++
+    this.clearCompassRetry()
+    this.compassRetryAttempt = 0
+    this.lightOwner = null
+    this.compassApplied = null
+    this.navigationActive = false
+  }
+}
+
+const glassesSensorService = new GlassesSensorService((sensor, operation, options) =>
+  BluetoothSdk.glassesSensorControl(sensor, operation, options),
+)
+export default glassesSensorService

package/src/services/GlassesTouchInput.ts

@@ -0,0 +1,128 @@
+import {useDisplayStore} from "../stores/display"
+import {DeviceModels, type TouchEvent} from "@glassly/bluetooth-sdk"
+import BluetoothSdk from "@glassly/bluetooth-sdk/internal"
+
+import {useAppStatusStore} from "../stores/apps"
+import {useGlassesStore} from "../stores/glasses"
+import {BgTimer} from "../utils/timers"
+import dashboardOpenTrace from "./debug/DashboardOpenTrace"
+import gestureDotsService from "./GestureDotsService"
+import localDisplayManager from "./LocalDisplayManager"
+import localMiniappRuntime from "./LocalMiniappRuntime"
+import {MiniappExitGesture} from "./MiniappExitGesture"
+import nativeNavigationService from "./NativeNavigationService"
+import {isOverlayApp} from "./pages/overlayApps"
+
+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),
+})
+
+// Raw CFW ring reports include every scroll step. Rate-limit scroll actions
+// separately from press/release recognition, using native receipt timestamps
+// so a JS backlog does not collapse otherwise separate gestures.
+const RING_SCROLL_INTERVAL_MS = 100
+let lastRingScrollAt: number | null = null
+
+function shouldForwardScroll(event: TouchEvent): boolean {
+  if (
+    event.deviceModel !== DeviceModels.G2 ||
+    event.source !== 2 ||
+    (event.gestureName !== "swipe_up" && event.gestureName !== "swipe_down")
+  )
+    return true
+  const elapsed = lastRingScrollAt === null ? null : event.timestamp - lastRingScrollAt
+  if (elapsed !== null && elapsed >= 0 && elapsed < RING_SCROLL_INTERVAL_MS) return false
+  lastRingScrollAt = event.timestamp
+  return true
+}
+
+/**
+ * Route both real glasses input and phone mirror controls through the same
+ * policy. A claimed gesture goes to the app holding the claim, alone; an
+ * unclaimed one goes to every subscriber and then the engine's default. The
+ * one rule ahead of the claims: an unclaimed double tap on a miniapp whose
+ * frame is visibly on the glasses leaves that app, whoever else claimed the
+ * gesture — the dashboard's claim is for the empty screen.
+ */
+export function dispatchTouchEvent(event: TouchEvent): void {
+  const gesture = event.gestureName
+  const claimant = localMiniappRuntime.gestureClaimant(gesture)
+
+  if (gesture === "double_tap") {
+    // A visible main miniapp opts out of OS exit by registering double tap (the
+    // terminal's back-to-menu). The latest claimant still receives it. Otherwise
+    // the tap means "leave the app". The controller shows the bounded OS
+    // notice first, then uses the normal
+    // store stop path (and closes its phone overlay).
+    const visible = localDisplayManager.getVisibleMiniappPackageName()
+    if (
+      visible !== null &&
+      !localMiniappRuntime.hasGestureClaim(visible, gesture) &&
+      miniappExitGesture.tryExitVisibleMiniapp()
+    ) {
+      gestureDotsService.noteGesture(gesture, true)
+      return
+    }
+  }
+
+  if (claimant !== null) {
+    // An overlay app claims the double tap on an empty screen to open the dashboard.
+    if (gesture === "double_tap" && isOverlayApp(claimant)) dashboardOpenTrace.trigger("double-tap", event.timestamp)
+    // The press may have started before this app claimed its release edge.
+    gestureDotsService.noteGesture(gesture, true)
+    if (!shouldForwardScroll(event)) return
+    localMiniappRuntime.forwardEvent("touch_event", event, undefined, claimant)
+    return
+  }
+
+  // Gesture-dots debug indicator (any device, gated by its setting). It
+  // only paints while the screen is otherwise empty. Process even suppressed
+  // scroll repeats here so their completion still clears a held dot.
+  gestureDotsService.noteGesture(gesture)
+
+  if (!shouldForwardScroll(event)) return
+  localMiniappRuntime.forwardEvent("touch_event", event)
+
+  // Nobody claimed a double tap: the glasses' own dashboard. On eligible
+  // Glassly CFW glasses the dashboard miniapp claims it while it runs
+  // (ADR-0006); stock firmware keeps its native dashboard (ADR-0002). The
+  // modal nav UI owns the screen; showDashboard would fight it.
+  if (gesture === "double_tap" && !nativeNavigationService.isActive) {
+    useDisplayStore.getState().setDisplayEvent({layout: {layoutType: "unavailable", reason: "firmware-dashboard"}})
+    void Promise.resolve(BluetoothSdk.showDashboard()).catch((err) => {
+      console.error("DeviceEventRouter: showDashboard failed:", err)
+    })
+  }
+}
+
+export function resetTouchInput(): void {
+  miniappExitGesture.reset()
+  lastRingScrollAt = null
+}
+
+/** Phone mirror input uses the same dashboard/miniapp policy as real glasses. */
+export function sendGesture(
+  gestureName:
+    | "single_tap"
+    | "tap_start"
+    | "double_tap"
+    | "tap_end"
+    | "tap_then_hold"
+    | "touch_down"
+    | "swipe_up"
+    | "swipe_down",
+): void {
+  const model = useGlassesStore.getState().deviceModel
+  dispatchTouchEvent({
+    type: "touch_event",
+    gestureName,
+    deviceModel: Object.values(DeviceModels).find((candidate) => candidate === model) ?? DeviceModels.Simulated,
+    timestamp: Date.now(),
+  })
+}