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

package/src/modules/input.ts

@@ -17,36 +17,68 @@
 
 import {MiniappRequestType, MiniappStreamType} from "../protocol"
 import {MiniappSession} from "../session"
-import type {ButtonPressData, TouchData, UnsubscribeFn} from "./events"
+import type {ButtonPressData, KeyboardEventData, TouchData, UnsubscribeFn} from "./events"
+
+export interface GestureClaimChange {
+  gesture: string
+  /** True when this app now holds the gesture, false when another app took it. */
+  held: boolean
+}
 
 export class InputModule {
   constructor(private readonly session: MiniappSession) {}
 
   /**
    * Declare the gestures this miniapp is handling itself, replacing any
-   * previous claim set. While a claimed gesture arrives and this app is
-   * FOREGROUND on the glasses, the host skips its default behavior for it —
-   * today that is `double_tap`, which otherwise opens the dashboard (or
-   * toggles head-up). The events themselves still arrive via `onTouch`
-   * either way; claiming only suppresses the system default.
+   * previous claim set in the selected scope. Claims stack: the most recent app to claim a gesture
+   * holds it and receives it alone through `onTouch`, and the host skips its
+   * own default for it (a double tap otherwise leaves the visible miniapp or
+   * opens the glasses' dashboard). When the holder releases the gesture, or
+   * stops, the previous claimer holds it again; `onClaimChange` reports both
+   * sides of every handoff.
    *
-   * Pass `[]` to release every claim. Claims are cleared automatically when
-   * the miniapp stops, and are inert while the app is backgrounded — a
-   * background app never hijacks a system gesture.
+   * Pass `[]` to release that scope. Omit `scope` for the default registration.
+   * Separate scopes preserve persistent shortcuts while a temporary page claims
+   * input: releasing the page scope restores the previous receiver without
+   * re-registering the shortcuts. All scopes are cleared automatically when
+   * the miniapp stops. One exception stands above the claims: an unclaimed
+   * double tap on a miniapp whose frame is visibly on the glasses leaves that
+   * app, so claim `double_tap` yourself while you are on screen if you use it.
    *
    *   session.input.setClaimedGestures(["double_tap"]) // in-app back gesture
-   *   session.input.setClaimedGestures([])             // back to system default
+   *   session.input.setClaimedGestures([])             // hand it back
    */
-  setClaimedGestures(gestures: string[]): Promise<void> {
+  setClaimedGestures(gestures: string[], options?: {scope?: string}): Promise<void> {
     return this.session
-      .sendRequest<void>({type: MiniappRequestType.CLAIM_GESTURES, gestures})
+      .sendRequest<void>({
+        type: MiniappRequestType.CLAIM_GESTURES,
+        gestures,
+        ...(options?.scope === undefined ? {} : {scope: options.scope}),
+      })
       .then(() => undefined)
   }
 
+  /** This app gained or lost a gesture it claimed (another app claimed it, or released it back). */
+  onClaimChange(handler: (change: GestureClaimChange) => void): UnsubscribeFn {
+    return this.session._subscribe(MiniappStreamType.GESTURE_CLAIM, handler as (data: unknown) => void)
+  }
+
   onButtonPress(handler: (data: ButtonPressData) => void): UnsubscribeFn {
     return this.session._subscribe(MiniappStreamType.BUTTON_PRESS, handler as (data: unknown) => void)
   }
 
+  /**
+   * Subscribe to a physical keyboard paired to the glasses (G2 Glassly CFW
+   * revision 39+; nothing arrives on other hardware). Every subscriber
+   * receives every key, like button presses: check `phase`, use `text` to
+   * type printable characters and `key`/`modifiers` for commands.
+   *
+   *   session.input.onKey((e) => { if (e.phase === "down" && e.text) type(e.text) })
+   */
+  onKey(handler: (data: KeyboardEventData) => void): UnsubscribeFn {
+    return this.session._subscribe(MiniappStreamType.KEYBOARD_EVENT, handler as (data: unknown) => void)
+  }
+
   /**
    * Subscribe to touch events.
    *

package/src/modules/latest-render-scheduler.ts

@@ -0,0 +1,55 @@
+/**
+ * Opt-in producer pacing for any miniapp. One render promise in flight and
+ * one replaceable pending callback; no scene is built until it can be sent.
+ * This bounds SDK work, not BLE packets, and does not cancel native work.
+ */
+export class LatestRenderScheduler {
+  private pending: (() => Promise<void>) | undefined
+  private timer: ReturnType<typeof setTimeout> | undefined
+  private busy = false
+  private disposed = false
+  private nextAt = 0
+
+  constructor(private readonly intervalMs: () => number) {}
+
+  request(render: () => Promise<void>): void {
+    if (this.disposed) return
+    this.pending = render
+    this.pump()
+  }
+
+  clearPending(): void {
+    this.pending = undefined
+    if (this.timer !== undefined) clearTimeout(this.timer)
+    this.timer = undefined
+  }
+
+  dispose(): void {
+    this.disposed = true
+    this.clearPending()
+  }
+
+  private pump(): void {
+    if (this.disposed || this.busy || !this.pending || this.timer !== undefined) return
+    const delay = this.nextAt - Date.now()
+    if (delay > 0) {
+      this.timer = setTimeout(() => {
+        this.timer = undefined
+        this.pump()
+      }, delay)
+      return
+    }
+    const render = this.pending
+    this.pending = undefined
+    this.busy = true
+    this.nextAt = Date.now() + Math.max(0, this.intervalMs())
+    // Callers handle/report errors; still release the scheduler after failure.
+    void Promise.resolve()
+      .then(() => (this.disposed ? undefined : render()))
+      .catch(() => {})
+      .finally(() => {
+        this.busy = false
+        this.pump()
+      })
+  }
+}

package/src/modules/lightSensor.ts

@@ -0,0 +1,61 @@
+/** Ambient light sensor exposed by G2 custom firmware. Subscribing does not start hardware. */
+import {MiniappRequestType, MiniappStreamType} from "../protocol"
+import type {MiniappSession} from "../session"
+import type {UnsubscribeFn} from "./events"
+
+export interface LightSensorOptions {
+  /** 100..5000 ms, default 500. */
+  intervalMs?: number
+  /** Change threshold in firmware ALS units, 0..65535, default 1. */
+  minDelta?: number
+  /** Report unchanged readings every 0..65535 ms; 0 disables, default 5000. */
+  heartbeatMs?: number
+}
+export interface LightSensorData {
+  reason: "query" | "started" | "poll" | "stopped"
+  opened: boolean
+  passive: boolean
+  autoBrightness: boolean
+  readSucceeded: boolean
+  status: number
+  /** Stock calibrated ALS units (approximately tenths of lux), not a lux measurement. */
+  value: number
+  peak: number
+  targetLevel: number
+  brightness: number
+  gear: number
+  scaleQ10: number
+  /** Firmware uptime, wraps at 2^32 ms. */
+  sampleTimestampMs: number
+  /** Phone reception time, Unix milliseconds. */
+  timestamp: number
+}
+
+export class LightSensorModule {
+  constructor(private readonly session: MiniappSession) {}
+  onUpdate(handler: (data: LightSensorData) => void): UnsubscribeFn {
+    return this.session._subscribe(MiniappStreamType.LIGHT_SENSOR, handler as (data: unknown) => void)
+  }
+  /** Request the cached driver reading; delivered by onUpdate, without opening the sensor. */
+  query(): Promise<void> {
+    return this.control("query")
+  }
+  /** Passive polling temporarily suspends stock automatic brightness adjustments.
+   * Navigation pauses polling; stopping or closing the miniapp restores stock behavior.
+   * Polling also stops when the CFW display lease is released or expires.
+   */
+  start(options: LightSensorOptions = {}): Promise<void> {
+    return this.control("start", options)
+  }
+  stop(): Promise<void> {
+    return this.control("stop")
+  }
+  private control(operation: string, options: LightSensorOptions = {}): Promise<void> {
+    return this.session.sendRequest({
+      type: MiniappRequestType.GLASSES_SENSOR_CONTROL,
+      sensor: "light",
+      operation,
+      options,
+    })
+  }
+}

package/src/modules/mic.ts

@@ -11,8 +11,9 @@
  * Audio *output* (TTS, file playback) lives on `session.speaker`.
  *
  * MICROPHONE permission must be declared in miniapp.json for any of these
- * subscriptions to succeed; the phone runtime rejects with
- * PERMISSION_NOT_DECLARED otherwise.
+ * subscriptions to succeed. Otherwise the phone runtime drops them silently:
+ * SUBSCRIBE carries no requestId, so the PERMISSION_NOT_DECLARED result is
+ * discarded and handlers just never fire.
  */
 
 import {MiniappRequestType, MiniappStreamType} from "../protocol"

package/src/modules/miniapps.ts

@@ -42,6 +42,8 @@ export interface MiniappInfo {
   description?: string
   version: string
   running: boolean
+  /** The wearer keeps the app off the home grid; menus should leave it out too. Absent on older hosts. */
+  hidden?: boolean
   compatibility: MiniappCompatibility
   /** Declared actions (empty if the miniapp declares none). */
   actions: MiniappActionInfo[]

package/src/modules/mirror.ts

@@ -0,0 +1,42 @@
+import {MiniappRequestType, MiniappStreamType} from "../protocol"
+import type {MiniappSession} from "../session"
+import type {UnsubscribeFn} from "./events"
+import type {MirrorSnapshot} from "../mirror/types"
+
+/** Read the globally visible, intended glasses display. Requires DISPLAY_MIRROR. */
+export class MirrorModule {
+  private latest: MirrorSnapshot | null = null
+  private listeners = 0
+
+  constructor(private readonly session: MiniappSession) {}
+
+  get hasPermission(): boolean {
+    return this.session._hasManifestPermission("DISPLAY_MIRROR")
+  }
+
+  /** Query the host's current canvas. This is a preview, not hardware readback. */
+  getCurrent(): Promise<MirrorSnapshot> {
+    return this.session.sendRequest<MirrorSnapshot>({type: MiniappRequestType.MIRROR_GET})
+  }
+
+  /** Receive an initial snapshot and subsequent changes. Dispose when the preview closes. */
+  onUpdate(handler: (snapshot: MirrorSnapshot) => void): UnsubscribeFn {
+    this.listeners++
+    let active = true
+    const off = this.session._subscribe(MiniappStreamType.MIRROR_UPDATE, (data) => {
+      this.latest = data as MirrorSnapshot
+      handler(this.latest)
+    })
+    const cached = this.latest
+    if (cached)
+      queueMicrotask(() => {
+        if (active && this.latest === cached) handler(cached)
+      })
+    return () => {
+      if (!active) return
+      active = false
+      off()
+      if (--this.listeners === 0) this.latest = null
+    }
+  }
+}

package/src/modules/mono-text-rows.ts

@@ -0,0 +1,30 @@
+import type {RenderElement} from "./display"
+
+/**
+ * Split a fixed-pitch grid into stable row elements. On G2 CFW, unsupported
+ * Unicode then rasterizes only its row instead of the entire grid. This is
+ * opt-in: callers must check the device's text-element budget. It uses the
+ * G2 mono renderer's 2px inset and rounded 1.2x line pitch, not stock metrics.
+ * Include every returned row in each replacement scene (including blanks).
+ */
+export function monoTextRows(options: {
+  id: string
+  text: string
+  box: {x: number; y: number; w: number; h: number}
+  fontSize: number
+}): RenderElement[] {
+  const {id, text, box, fontSize} = options
+  if (![box.x, box.y, box.w, box.h, fontSize].every(Number.isFinite) || fontSize <= 0) return []
+  if (box.w <= 2 || box.h <= 2) return []
+  const pitch = Math.max(1, Math.round(fontSize * 1.2))
+  return text
+    .split("\n")
+    .slice(0, Math.ceil((box.h - 2) / pitch))
+    .map((line, index) => ({
+      type: "text",
+      id: `${id}-row-${index}`,
+      text: line,
+      box: {x: box.x, y: box.y + index * pitch, w: box.w, h: Math.min(pitch + 2, box.h - index * pitch)},
+      style: {font: "mono", fontSize},
+    }))
+}

package/src/modules/navigation.ts

@@ -342,21 +342,27 @@ export class NavigationModule {
     }
     const restRoute = restResult.routes[0]
 
-    const nativeResult = await this.session.sendRequest<{ok: boolean; error?: string}>({
-      type: MiniappRequestType.NAVIGATION_START,
-      // Keep lat/lng on the wire for hosts not yet upgraded to read `stops`.
-      lat: stops[0]?.lat,
-      lng: stops[0]?.lng,
-      stops,
-      mode,
-      avoid: opts.avoid,
-      simulate: opts.simulate ?? false,
-      speedMultiplier: opts.speedMultiplier ?? 1,
-      missedTurnRerouteMeters: opts.missedTurnRerouteMeters,
-    })
+    let nativeResult: {ok: boolean; error?: string}
+    try {
+      nativeResult = await this.session.sendRequest<{ok: boolean; error?: string}>({
+        type: MiniappRequestType.NAVIGATION_START,
+        // Keep lat/lng on the wire for hosts not yet upgraded to read `stops`.
+        lat: stops[0]?.lat,
+        lng: stops[0]?.lng,
+        stops,
+        mode,
+        avoid: opts.avoid,
+        simulate: opts.simulate ?? false,
+        speedMultiplier: opts.speedMultiplier ?? 1,
+        missedTurnRerouteMeters: opts.missedTurnRerouteMeters,
+      })
+    } catch (err) {
+      // Wire-level failure (host threw, timed out, disconnected). Honor the
+      // never-throws contract and release the pivot subscriptions.
+      return failStart(err instanceof Error ? err.message : String(err))
+    }
     if (!nativeResult.ok) {
-      this._detachPivotTracking()
-      return nativeResult
+      return failStart(nativeResult.error ?? "navigation.start: host refused the trip")
     }
 
     // Dispatch the REST route through the native route channel so subscribers see step roads now.

package/src/modules/phone.ts

@@ -5,6 +5,7 @@
  *
  *   session.phone.notifications.{on, hasPermission, stop}
  *   session.phone.calendar.{listEvents, hasPermission}
+ *   session.phone.heading.{onUpdate, hasPermission}
  *   session.phone.onBattery(...)                          // stays flat
  *
  * Imperative phone-OS calls (share, openUrl, copyToClipboard, download) live
@@ -18,7 +19,7 @@
 
 import {MiniappRequestType, MiniappStreamType} from "../protocol"
 import {MiniappSession} from "../session"
-import type {BatteryData, NotificationDismissedData, PhoneNotificationData, UnsubscribeFn} from "./events"
+import type {BatteryData, HeadingData, NotificationDismissedData, PhoneNotificationData, UnsubscribeFn} from "./events"
 
 class TrackedSubs {
   private readonly unsubs = new Set<UnsubscribeFn>()
@@ -71,6 +72,27 @@ export class PhoneNotificationsModule extends TrackedSubs {
   get hasPermission(): boolean {
     return this.session._hasManifestPermission("READ_NOTIFICATIONS")
   }
+
+  /**
+   * Apps that post phone notifications, for a per-app filter UI. Android
+   * lists installed apps with their icons (base64 PNG); iOS has no cross-app
+   * lookup, so it lists a seeded catalog plus the apps the glasses reported
+   * posting, without icons. SYSTEM-only.
+   */
+  async installedApps(): Promise<NotificationAppInfo[]> {
+    const result = await this.session.sendRequest<NotificationAppInfo[]>({
+      type: MiniappRequestType.NOTIFICATION_APPS_LIST,
+    })
+    return result ?? []
+  }
+}
+
+export interface NotificationAppInfo {
+  /** Bundle id (iOS) or package name (Android). */
+  packageName: string
+  appName: string
+  /** Base64 PNG, Android only. */
+  icon: string | null
 }
 
 export interface CalendarListOptions {
@@ -136,13 +158,30 @@ function normalizeCalendarDate(value: string | Date | undefined, field: string):
   return date.toISOString()
 }
 
+/** Phone compass (magnetometer / sensor fusion). For the glasses' own heading use `session.compass`. */
+export class PhoneHeadingModule {
+  constructor(private readonly session: MiniappSession) {}
+
+  /** True iff `LOCATION` is declared in the miniapp's manifest. */
+  get hasPermission(): boolean {
+    return this.session._hasManifestPermission("LOCATION")
+  }
+
+  /** Continuous phone heading updates; the phone compass starts on the first subscriber. */
+  onUpdate(handler: (data: HeadingData) => void): UnsubscribeFn {
+    return this.session._subscribe(MiniappStreamType.HEADING_UPDATE, handler as (data: unknown) => void)
+  }
+}
+
 export class PhoneModule {
   public readonly notifications: PhoneNotificationsModule
   public readonly calendar: PhoneCalendarModule
+  public readonly heading: PhoneHeadingModule
 
   constructor(private readonly session: MiniappSession) {
     this.notifications = new PhoneNotificationsModule(session)
     this.calendar = new PhoneCalendarModule(session)
+    this.heading = new PhoneHeadingModule(session)
   }
 
   /**

package/src/modules/settings.ts

@@ -0,0 +1,64 @@
+/**
+ * @fileoverview SettingsModule — `session.settings`, the engine's settings
+ * store behind an allowlist. SYSTEM-only: every call rejects with
+ * NOT_PERMITTED unless the caller is a system app. The dashboard miniapp is
+ * the first consumer: it reads and edits the same dashboard, notification
+ * and glasses-menu keys the phone's settings screens used to, so firmware
+ * sync and the host's notification policy keep one source of truth.
+ *
+ * Keys are the engine's setting keys (e.g. `custom_dashboard_layout`,
+ * `notifications_popups`, `menu_apps`); values are their JSON values. The
+ * host also serves a few derived read-only keys (`phone_active`,
+ * `foreground_app_on_screen`, `ring_battery`) that the engine computes
+ * rather than stores. `set` on a read-only or unknown key rejects.
+ */
+
+import {MiniappRequestType, MiniappStreamType} from "../protocol"
+import {MiniappSession} from "../session"
+import type {UnsubscribeFn} from "./events"
+
+export interface SettingsChange {
+  key: string
+  value: unknown
+}
+
+export class SettingsModule {
+  constructor(private readonly session: MiniappSession) {}
+
+  /** One allowlisted key's value; undefined when the key is unknown. SYSTEM-only. */
+  async get<T = unknown>(key: string): Promise<T | undefined> {
+    const values = await this.getAll([key])
+    return values[key] as T | undefined
+  }
+
+  /**
+   * Every allowlisted key's value, or just `keys`. Unknown keys are left out
+   * rather than rejected, so a newer miniapp on an older host still reads
+   * the keys the host knows. SYSTEM-only.
+   */
+  async getAll(keys?: string[]): Promise<Record<string, unknown>> {
+    const result = await this.session.sendRequest<{values?: Record<string, unknown>}>({
+      type: MiniappRequestType.SETTINGS_GET,
+      ...(keys ? {keys} : {}),
+    })
+    return result?.values ?? {}
+  }
+
+  /**
+   * Write a writable key through the engine's settings store: persistence,
+   * server sync and the Bluetooth sync of glasses settings behave as if a
+   * phone screen wrote it. SYSTEM-only.
+   */
+  async set(key: string, value: unknown): Promise<void> {
+    await this.session.sendRequest<void>({type: MiniappRequestType.SETTINGS_SET, key, value})
+  }
+
+  /**
+   * An allowlisted key changed (including the derived read-only keys). On
+   * subscribe the host replays every key's current value, so a mirror can
+   * be built from this stream alone. SYSTEM-only; other apps never hear it.
+   */
+  onChange(handler: (change: SettingsChange) => void): UnsubscribeFn {
+    return this.session._subscribe(MiniappStreamType.SETTINGS_CHANGED, handler as (data: unknown) => void)
+  }
+}

package/src/modules/system.ts

@@ -46,6 +46,22 @@ export interface ScanQrOptions {
 
 export type ScanQrResult = {data: string; cancelled?: false} | {cancelled: true; data?: undefined}
 
+/** Native G2 performance counters only; never display text or packet contents. */
+export interface DisplayDiagnostic {
+  v: 1
+  run: string
+  id: number
+  t: number
+  type: "sample" | "stall" | "session"
+  [key: string]: string | number | boolean
+}
+
+export interface DisplayDiagnosticsResult {
+  enabled: boolean
+  generatedAt: number
+  records: DisplayDiagnostic[]
+}
+
 export class SystemModule {
   constructor(private readonly session: MiniappSession) {}
 
@@ -66,6 +82,19 @@ export class SystemModule {
     })
   }
 
+  /**
+   * Read recent native G2 diagnostics (bounded to 180 records / 3 minutes).
+   * Requires the phone's Debug Console setting. Empty on unsupported devices;
+   * submitted bytes are not over-the-air throughput or measured display FPS.
+   * Poll no faster than once per second. Older hosts reject this request.
+   */
+  async getDisplayDiagnostics(): Promise<DisplayDiagnosticsResult> {
+    const result = await this.session.sendRequest<DisplayDiagnosticsResult>({
+      type: MiniappRequestType.DISPLAY_DIAGNOSTICS,
+    })
+    return result ?? {enabled: false, generatedAt: Date.now(), records: []}
+  }
+
   /** Copy text to the system clipboard. */
   async copyToClipboard(text: string): Promise<void> {
     await this.session.sendRequest<void>({
@@ -108,6 +137,6 @@ export class SystemModule {
       },
       {timeoutMs: 0},
     )
-    return result ?? { cancelled: true }
+    return result ?? {cancelled: true}
   }
 }

package/src/modules/transcription.ts

@@ -14,8 +14,9 @@
  * module still exposes lower-level audio chunks + VAD; this module is for
  * "give me text from speech."
  *
- * MICROPHONE permission must be declared in miniapp.json. The phone runtime
- * rejects with PERMISSION_NOT_DECLARED otherwise.
+ * MICROPHONE permission must be declared in miniapp.json. Otherwise the phone
+ * runtime drops the subscription silently: SUBSCRIBE carries no requestId, so
+ * the PERMISSION_NOT_DECLARED result is discarded and handlers just never fire.
  */
 
 import {MiniappRequestType, MiniappStreamType} from "../protocol"