@glassly/miniapp 0.3.0-dev.1 → 0.3.0-dev.460

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"

package/src/protocol.ts

@@ -5,9 +5,9 @@
  * These values are the contract between @glassly/miniapp (running in a WebView)
  * and LocalMiniappRuntime (running on the phone).
  *
- * IMPORTANT: This file has NO runtime dependency on @glassly/sdk. The cloud SDK's
- * wire protocol enums live in @glassly/sdk/types/message-types.ts and are used
- * for cloud↔app communication, not phone↔miniapp.
+ * IMPORTANT: This file has no runtime dependency on the retired cloud SDK.
+ * Its published wire-protocol enums are used only for compatibility with
+ * existing cloud-hosted miniapps, not for phone↔miniapp communication.
  */
 
 // ============================================================================
@@ -24,6 +24,13 @@ export enum MiniappRequestType {
   /** Update the set of streams the miniapp is subscribed to. */
   SUBSCRIBE = "miniapp_subscribe",
 
+  /**
+   * Declare the touch gestures this miniapp is handling itself. The most
+   * recent claimer of a gesture gets it alone and the host's default for it
+   * is skipped; releasing hands it back to the previous claimer.
+   */
+  CLAIM_GESTURES = "miniapp_claim_gestures",
+
   /**
    * Push a legacy display layout to the glasses. The SDK no longer emits this
    * (render()/RENDER replaced it); hosts keep accepting it from bundles packed
@@ -34,6 +41,17 @@ export enum MiniappRequestType {
   /** Render a whole scene of positioned elements (replace-the-frame). */
   RENDER = "miniapp_render",
 
+  /** Read the globally visible intended glasses canvas. DISPLAY_MIRROR permission. */
+  MIRROR_GET = "miniapp_mirror_get",
+
+  /**
+   * Ask the host for a display view (display.showView). "main" is every
+   * app's; "dashboard" is the overlay slot above the main content, granted
+   * only to the running miniapp whose manifest type is "system_dashboard"
+   * while the glasses can show it.
+   */
+  SHOW_VIEW = "miniapp_show_view",
+
   /**
    * Feed the device's firmware-rendered navigation UI (capability
    * `hasNativeNavigation`): structured turn-by-turn card fields and
@@ -70,6 +88,21 @@ export enum MiniappRequestType {
   /** Read a bounded snapshot of phone calendar events. */
   CALENDAR_LIST_EVENTS = "miniapp_calendar_list_events",
 
+  /**
+   * Apps that post phone notifications, for a notification filter UI.
+   * SYSTEM-only. Android: installed apps with icons; iOS: the seeded
+   * catalog plus apps the glasses reported.
+   */
+  NOTIFICATION_APPS_LIST = "miniapp_notification_apps_list",
+
+  /**
+   * The engine's settings store behind an allowlist (session.settings).
+   * SYSTEM-only. GET takes optional `keys` and answers `{values}`; SET
+   * takes `key` and `value` and writes through the store.
+   */
+  SETTINGS_GET = "miniapp_settings_get",
+  SETTINGS_SET = "miniapp_settings_set",
+
   /** Start a turn-by-turn navigation trip. Android only. */
   NAVIGATION_START = "miniapp_navigation_start",
   /** Stop the active navigation trip (if any). */
@@ -175,6 +208,7 @@ export enum MiniappRequestType {
    * for callers who want to control the sensor directly. G2 only today.
    */
   IMU_SET_ENABLED = "miniapp_imu_set_enabled",
+  GLASSES_SENSOR_CONTROL = "miniapp_glasses_sensor_control",
 
   /** Explicitly enable/disable glasses-side VAD (GX8002). Mirrors the app's mic settings toggle. */
   MIC_SET_VAD_ENABLED = "miniapp_mic_set_vad_enabled",
@@ -192,6 +226,7 @@ export enum MiniappRequestType {
   /** Open a URL in the system browser. */
   OPEN_URL = "miniapp_open_url",
   /** Copy text to the system clipboard. */
+  DISPLAY_DIAGNOSTICS = "miniapp_display_diagnostics",
   COPY_CLIPBOARD = "miniapp_copy_clipboard",
   /** Download a file (triggers OS share sheet for save location). */
   DOWNLOAD = "miniapp_download",
@@ -295,6 +330,9 @@ export enum MiniappResponseType {
   /** Push: glasses capabilities changed. */
   CAPABILITIES_UPDATE = "miniapp_capabilities_update",
 
+  /** Push: host user preferences (units, clock format) changed. */
+  PREFERENCES_UPDATE = "miniapp_preferences_update",
+
   /** Push: miniapp's foreground/background state changed. */
   VISIBILITY_CHANGE = "miniapp_visibility_change",
 
@@ -352,7 +390,25 @@ export enum MiniappStreamType {
   // Hardware / input events
   BUTTON_PRESS = "button_press",
   TOUCH_EVENT = "touch_event",
+  /**
+   * Physical keyboard paired to the glasses (input.onKey): DOM-style
+   * `{phase, key, code, modifiers, text?, repeat, timestamp}`. G2 Glassly CFW
+   * revision 39+ only; broadcast to every subscriber like button_press.
+   */
+  KEYBOARD_EVENT = "keyboard_event",
   HEAD_POSITION = "head_position",
+  /**
+   * The dashboard view's state (display.onViewChange): `{kind: "change",
+   * view, reason}` when the host grants or takes the overlay slot.
+   */
+  DISPLAY_VIEW = "display_view",
+  /** Initial mirror snapshot and subsequent visible display changes. */
+  MIRROR_UPDATE = "mirror_update",
+  /**
+   * A gesture claim changed hands (input.onClaimChange): `{gesture, held}`,
+   * sent to the app that gained or lost the gesture.
+   */
+  GESTURE_CLAIM = "gesture_claim",
   /**
    * Raw accelerometer reading from the glasses IMU — `{x, y, z}` in g, plus a
    * timestamp. G2 only today. A richer combined IMU stream (accel + gyro +
@@ -375,19 +431,30 @@ export enum MiniappStreamType {
 
   // Phone sensors
   LOCATION_UPDATE = "location_update",
-  /** Compass heading in degrees (0=N, 90=E). */
+  /** Phone compass heading in degrees (0=N, 90=E). */
   HEADING_UPDATE = "heading_update",
+  // Glasses sensors
+  LIGHT_SENSOR = "light_sensor",
+  /** Glasses compass heading; auto-starts on custom firmware, nav mode only on stock. */
+  GLASSES_COMPASS = "glasses_compass",
+  COMPASS_CALIBRATION = "compass_calibration",
   /** Turn-by-turn navigation event (maneuver / rerouting / arrived / error). */
   NAVIGATION_UPDATE = "navigation_update",
   /** Active navigation route polyline — full path, fired once per route build. */
   NAVIGATION_ROUTE = "navigation_route",
   PHONE_NOTIFICATION = "phone_notification",
+  /**
+   * An allowlisted engine setting changed (session.settings.onChange), as
+   * `{key, value}`. SYSTEM-only; every key's current value is replayed on
+   * subscribe.
+   */
+  SETTINGS_CHANGED = "settings_changed",
   /**
    * A previously-posted notification was dismissed by the user.
    *
    * Android-only today. iOS does not expose dismiss callbacks to apps
    * (Apple privacy restriction); subscribing on iOS succeeds but no events
-   * fire. See agents/miniapp-speaker-state-and-notif-dismissed-plan.md.
+   * fire. See notes/archive/agents/miniapp-speaker-state-and-notif-dismissed-plan.md.
    */
   PHONE_NOTIFICATION_DISMISSED = "phone_notification_dismissed",
   // Photos, streaming

package/src/react/MirrorCanvas.tsx

@@ -0,0 +1,35 @@
+import {useEffect, useRef, type CSSProperties} from "react"
+import {MirrorCanvasRenderer} from "../mirror/canvas"
+import type {MirrorSnapshot} from "../mirror/types"
+
+export interface MirrorCanvasProps {
+  frame: MirrorSnapshot | null
+  className?: string
+  style?: CSSProperties
+}
+
+/** Browser preview of intended glasses output; pass snapshots over a UI channel. */
+export function MirrorCanvas({frame, className, style}: MirrorCanvasProps) {
+  const canvas = useRef<HTMLCanvasElement>(null)
+  const renderer = useRef<MirrorCanvasRenderer | null>(null)
+  useEffect(() => {
+    if (!canvas.current) return
+    renderer.current = new MirrorCanvasRenderer(canvas.current)
+    return () => {
+      renderer.current?.dispose()
+      renderer.current = null
+    }
+  }, [])
+  useEffect(() => {
+    if (frame) renderer.current?.update(frame)
+  }, [frame])
+  return (
+    <canvas
+      ref={canvas}
+      className={className}
+      role="img"
+      aria-label="Glasses display mirror"
+      style={{display: "block", width: "100%", height: "auto", ...style}}
+    />
+  )
+}

package/src/react/index.ts

@@ -10,3 +10,6 @@ export type {MiniappHeaderProps} from "./MiniappHeader"
 export {MiniappProvider} from "./MiniappProvider"
 export type {MiniappProviderProps} from "./MiniappProvider"
 export {useRpc, type RpcCallable} from "./useRpc"
+
+export {MirrorCanvas, type MirrorCanvasProps} from "./MirrorCanvas"
+export type {MirrorSnapshot, MirrorContent, MirrorElement} from "../mirror/types"