@glassly/miniapp 0.1.0-dev.98 → 0.2.8-dev.444

package/src/protocol.ts

@@ -25,9 +25,9 @@ export enum MiniappRequestType {
   SUBSCRIBE = "miniapp_subscribe",
 
   /**
-   * Declare the touch gestures this miniapp is handling itself, suppressing
-   * the host's default behavior for them (e.g. double_tap opens the
-   * dashboard) while the app is foreground on the glasses.
+   * 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",
 
@@ -41,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
@@ -77,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). */
@@ -182,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",
@@ -199,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",
@@ -302,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",
 
@@ -359,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 +
@@ -382,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"

package/src/react/useColorScheme.ts

@@ -3,9 +3,8 @@
  * color scheme.
  *
  * WebView-side hook: reads `window.Glassly.colorScheme`, injected by the host
- * before the miniapp's content loads. Like `useSafeArea`, this is read once at
- * mount — the host doesn't push color-scheme changes to the WebView at runtime;
- * flipping the phone's theme forces a reload.
+ * before the miniapp's content loads, and follows the host's
+ * `glassly:color-scheme-change` events while the WebView remains mounted.
  *
  * IMPORTANT: this hook must NOT construct a `MiniappSession`. `MiniappSession`
  * is the *background* (JSContext) API; inside a UI WebView its transport falls
@@ -14,13 +13,23 @@
  * read host-injected globals instead (see `useSafeArea`).
  */
 
-import {useState} from "react"
+import {useEffect, useState} from "react"
 
-import {getGlasslyGlobals, type MiniappColorScheme} from "../globals"
+import {getHostGlobals, type MiniappColorScheme} from "../globals"
+
+const readScheme = (): MiniappColorScheme => (getHostGlobals().colorScheme === "dark" ? "dark" : "light")
 
 export function useColorScheme(): MiniappColorScheme {
-  const [scheme] = useState<MiniappColorScheme>(() => {
-    return getGlasslyGlobals().colorScheme === "dark" ? "dark" : "light"
-  })
+  const [scheme, setScheme] = useState<MiniappColorScheme>(readScheme)
+
+  useEffect(() => {
+    if (typeof window === "undefined") return
+    const update = () => setScheme(readScheme())
+    window.addEventListener("glassly:color-scheme-change", update)
+    // Catch an update delivered between the initial render and subscription.
+    update()
+    return () => window.removeEventListener("glassly:color-scheme-change", update)
+  }, [])
+
   return scheme
 }

package/src/react/useRpc.ts

@@ -19,7 +19,7 @@ import type {RpcReq, RpcRes, RpcRequestOptions} from "../modules/ui"
 type RequestFn = (channel: string, payload: unknown, options?: RpcRequestOptions) => Promise<unknown>
 
 /** Walk to the global `glassly.request` (typed). */
-function getGlasslyRequest(): RequestFn {
+function getHostRequest(): RequestFn {
   const m = (globalThis as unknown as {glassly?: {request?: RequestFn}}).glassly
   if (!m || typeof m.request !== "function") {
     throw new Error(
@@ -89,7 +89,7 @@ export function useRpc<TChannels extends object, C extends keyof TChannels & str
       const signals: AbortSignal[] = [ctrl.signal, mountRef.current!.signal]
       if (options?.signal) signals.push(options.signal)
       const signal = mergeSignals(signals)
-      return getGlasslyRequest()(channel, payload, {signal, timeout: options?.timeout}) as Promise<RpcRes<TChannels[C]>>
+      return getHostRequest()(channel, payload, {signal, timeout: options?.timeout}) as Promise<RpcRes<TChannels[C]>>
     },
     [channel],
   ) as RpcCallable<TChannels, C>

package/src/react/useSafeArea.ts

@@ -9,7 +9,7 @@
 
 import {useState} from "react"
 
-import {getGlasslyGlobals, type MiniappCapsuleMenuRect, type MiniappSafeAreaInsets} from "../globals"
+import {getHostGlobals, type MiniappCapsuleMenuRect, type MiniappSafeAreaInsets} from "../globals"
 
 const EMPTY_INSETS: MiniappSafeAreaInsets = {top: 0, bottom: 0, left: 0, right: 0}
 
@@ -26,7 +26,7 @@ export interface UseSafeAreaResult {
 
 export function useSafeArea(): UseSafeAreaResult {
   const [result] = useState<UseSafeAreaResult>(() => {
-    const globals = getGlasslyGlobals()
+    const globals = getHostGlobals()
     return {
       insets: globals.safeAreaInsets ?? EMPTY_INSETS,
       capsuleMenu: globals.capsuleMenu ?? null,

package/src/session.ts

@@ -15,7 +15,7 @@
 import {EventEmitter} from "eventemitter3"
 
 import {makeRequestId, MiniappEnvelope, parseEnvelope, serializeEnvelope} from "./envelope"
-import {getGlasslyGlobals, MiniappColorScheme} from "./globals"
+import {getHostGlobals, MiniappColorScheme} from "./globals"
 import {MiniappErrorCode, MiniappRequestType, MiniappResponseType} from "./protocol"
 import {createTransport, CreateTransportOptions} from "./transport/auto"
 import {Transport} from "./transport/types"
@@ -26,15 +26,17 @@ import {DashboardAPI} from "./modules/dashboard"
 import {DisplayManager} from "./modules/display"
 import {EventManager, type TranscriptionEventRoute, type UnsubscribeFn} from "./modules/events"
 import {GlassesModule} from "./modules/glasses"
-import {HeadingModule} from "./modules/heading"
 import {AiModule} from "./modules/ai"
 import {ImuModule} from "./modules/imu"
+import {CompassModule} from "./modules/compass"
+import {LightSensorModule} from "./modules/lightSensor"
 import {InputModule} from "./modules/input"
 import {KeysModule} from "./modules/keys"
 import {LedModule} from "./modules/led"
 import {LocationModule} from "./modules/location"
 import {MemoryModule} from "./modules/memory"
 import {SpeakersModule} from "./modules/speakers"
+import {MirrorModule} from "./modules/mirror"
 import {MicModule} from "./modules/mic"
 import {NavigationModule} from "./modules/navigation"
 import {PermissionsModule} from "./modules/permissions"
@@ -42,6 +44,7 @@ import {PhoneModule} from "./modules/phone"
 import {TranscriptionModule} from "./modules/transcription"
 import {TranslationModule} from "./modules/translation"
 import {UIModuleImpl, type UIModule} from "./modules/ui"
+import {SettingsModule} from "./modules/settings"
 import {SimpleStorage} from "./modules/storage"
 import {SpeakerModule} from "./modules/speaker"
 import {StreamModule} from "./modules/stream"
@@ -70,9 +73,23 @@ export interface DisplayCapabilities {
   maxImageElements?: number
   /** Per-image dimension cap (box-level), when the device has one. */
   maxImagePx?: {width: number; height: number}
+  /** Shape element types the device draws ("rect", "circle", "line", …). */
   shapes?: string[]
+  /** True ⇒ element `transition`s animate on the device. */
+  animation?: boolean
+  /** Geometric and SVG rotations, including duration-based transitions. */
+  rotation?: boolean
+  /** Per-element stereo `depth` (a lens disparity) is honored; otherwise elements draw flat. */
+  depth?: boolean
   intensityLevels?: number
+
   partialUpdate?: boolean
+  /**
+   * The views this app may draw right now. "main" always; "dashboard" only
+   * for the running app whose manifest type is "system_dashboard", while the
+   * connected glasses can show the overlay slot (see display.showView).
+   */
+  views?: Array<"main" | "dashboard">
   /** Legacy capability fields (resolution, isColor, maxTextLines, …) ride along. */
   [key: string]: unknown
 }
@@ -87,6 +104,8 @@ export interface GlassesCapabilities {
 }
 
 export type MiniappVisibility = "foreground" | "background"
+/** Where the user started this session from: the phone app or the glasses menu. */
+export type MiniappLaunchSource = "phone" | "glasses"
 
 export interface MiniappSessionOptions extends CreateTransportOptions {
   /** Override auto-detected packageName. Normally provided via window.Glassly. */
@@ -95,13 +114,30 @@ export interface MiniappSessionOptions extends CreateTransportOptions {
   connectTimeoutMs?: number
 }
 
+/** Distance/temperature unit family. Mirrors the host's "Use Metric System" toggle. */
+export type MiniappUnitSystem = "metric" | "imperial"
+
+/**
+ * Host user preferences a miniapp should follow by default (Settings >
+ * Appearance). Sent in CONNECT_ACK and pushed on change. Miniapps may still
+ * offer their own override on top.
+ */
+export interface MiniappPreferences {
+  unitSystem: MiniappUnitSystem
+  /** True for 12-hour (AM/PM) clocks, false for 24-hour. */
+  twelveHourTime: boolean
+}
+
 export interface ConnectAckPayload {
   type: MiniappResponseType.CONNECT_ACK
   userId: string
   packageName: string
   capabilities: GlassesCapabilities | null
+  /** Absent on runtimes older than the preferences surface. */
+  preferences?: MiniappPreferences
   visibility?: MiniappVisibility
   colorScheme?: MiniappColorScheme
+  launchSource?: MiniappLaunchSource
   /**
    * Manifest-declared permission record. Mirrors cloud SDK v3's PermissionRecord:
    * `{location, microphone, camera, notifications, calendar, apiKeys}` —
@@ -114,7 +150,7 @@ export interface ConnectAckPayload {
 }
 
 export interface MiniappAuthState {
-  glasslyUserId: string
+  userId: string
   oemId?: string
   token: string
   expiresAt: number
@@ -143,6 +179,7 @@ export type PermissionType =
   | "memory"
   | "ai"
   | "speakers"
+  | "displayMirror"
 export type PermissionRecord = Record<PermissionType, boolean>
 
 const ALL_PERMISSION_TYPES: readonly PermissionType[] = [
@@ -155,6 +192,7 @@ const ALL_PERMISSION_TYPES: readonly PermissionType[] = [
   "memory",
   "ai",
   "speakers",
+  "displayMirror",
 ] as const
 
 export class NotConnectedError extends Error {
@@ -224,6 +262,7 @@ type SessionEmitterEvents = {
   disconnect: (reason: string) => void
   visibility: (v: MiniappVisibility) => void
   capabilities: (cap: GlassesCapabilities | null) => void
+  preferences: (prefs: MiniappPreferences) => void
   colorScheme: (scheme: MiniappColorScheme) => void
   permissions: (perms: PermissionRecord) => void
   speakerState: (event: import("./modules/speaker").SpeakerStateEvent) => void
@@ -236,6 +275,7 @@ type SessionEmitterEvents = {
 
 export class MiniappSession<TChannels extends object = any> {
   public readonly auth: AuthModule
+  public readonly mirror: MirrorModule
   public readonly display: DisplayManager
   /**
    * Internal subscription registry + escape hatch.
@@ -251,8 +291,9 @@ export class MiniappSession<TChannels extends object = any> {
   public readonly cloud: CloudModule
   public readonly dashboard: DashboardAPI
   public readonly glasses: GlassesModule
-  public readonly heading: HeadingModule
   public readonly imu: ImuModule
+  public readonly lightSensor: LightSensorModule
+  public readonly compass: CompassModule
   public readonly input: InputModule
   /**
    * User-supplied provider API keys (Settings > API Keys). Requires the
@@ -286,6 +327,11 @@ export class MiniappSession<TChannels extends object = any> {
   public readonly navigation: NavigationModule
   public readonly permissions: PermissionsModule
   public readonly phone: PhoneModule
+  /**
+   * The engine's settings store behind an allowlist. SYSTEM-only — calls
+   * reject with NOT_PERMITTED unless this miniapp is a system app.
+   */
+  public readonly settings: SettingsModule
   public readonly storage: SimpleStorage
   /**
    * Phone-local persistent BINARY storage (`session.blob`) — the binary
@@ -318,9 +364,13 @@ export class MiniappSession<TChannels extends object = any> {
 
   /** Phone-declared glasses capabilities. Null until CONNECT_ACK arrives. */
   public capabilities: GlassesCapabilities | null = null
+  /** Host user preferences. Null until CONNECT_ACK arrives (or on runtimes that don't send them). */
+  public preferences: MiniappPreferences | null = null
   public userId = ""
   public packageName = ""
   public visibility: MiniappVisibility = "foreground"
+  /** Where the user started this session from. Null until CONNECT_ACK arrives. */
+  public launchSource: MiniappLaunchSource | null = null
   /** Host color scheme. Seeded from window.Glassly, updated via session events. */
   public colorScheme: MiniappColorScheme = "light"
 
@@ -359,13 +409,14 @@ export class MiniappSession<TChannels extends object = any> {
     memory: false,
     ai: false,
     speakers: false,
+    displayMirror: false,
   }
 
   constructor(options: MiniappSessionOptions = {}) {
     this.transport = createTransport(options)
     this.connectTimeoutMs = options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS
 
-    const injected = getGlasslyGlobals()
+    const injected = getHostGlobals()
     this.packageName = options.packageName ?? injected.packageName ?? ""
     if (injected.colorScheme === "light" || injected.colorScheme === "dark") {
       this.colorScheme = injected.colorScheme
@@ -377,10 +428,12 @@ export class MiniappSession<TChannels extends object = any> {
     this.camera = new CameraModule(this)
     this.cloud = new CloudModule(this)
     this.dashboard = new DashboardAPI(this)
+    this.mirror = new MirrorModule(this)
     this.display = new DisplayManager(this)
     this.glasses = new GlassesModule(this)
-    this.heading = new HeadingModule(this)
     this.imu = new ImuModule(this)
+    this.lightSensor = new LightSensorModule(this)
+    this.compass = new CompassModule(this)
     this.input = new InputModule(this)
     this.ai = new AiModule(this)
     this.keys = new KeysModule(this)
@@ -392,6 +445,7 @@ export class MiniappSession<TChannels extends object = any> {
     this.navigation = new NavigationModule(this)
     this.permissions = new PermissionsModule(this)
     this.phone = new PhoneModule(this)
+    this.settings = new SettingsModule(this)
     this.storage = new SimpleStorage(this)
     this.blob = new BlobModule(this)
     this.stream = new StreamModule(this)
@@ -646,6 +700,10 @@ export class MiniappSession<TChannels extends object = any> {
     return this.on("capabilities", handler)
   }
 
+  onPreferencesChange(handler: (prefs: MiniappPreferences) => void): () => void {
+    return this.on("preferences", handler)
+  }
+
   onColorSchemeChange(handler: (scheme: MiniappColorScheme) => void): () => void {
     return this.on("colorScheme", handler)
   }
@@ -691,13 +749,15 @@ export class MiniappSession<TChannels extends object = any> {
         this.userId = ack.userId ?? ""
         if (ack.packageName) this.packageName = ack.packageName
         this.capabilities = ack.capabilities ?? null
+        if (ack.preferences) this.preferences = ack.preferences
         if (ack.visibility) this.visibility = ack.visibility
+        if (ack.launchSource) this.launchSource = ack.launchSource
         if (ack.colorScheme === "light" || ack.colorScheme === "dark") {
           this.colorScheme = ack.colorScheme
         }
         if (ack.auth) {
           this.applyAuth(ack.auth)
-          if (!this.userId) this.userId = ack.auth.glasslyUserId
+          if (!this.userId) this.userId = ack.auth.userId
         }
         // Populate the manifest-declared permission cache. Older runtimes
         // that don't send `permissions` leave the all-false default in place
@@ -714,7 +774,7 @@ export class MiniappSession<TChannels extends object = any> {
         const next = (payload as unknown as AuthUpdatePayload).auth
         if (next) {
           this.applyAuth(next)
-          if (!this.userId) this.userId = next.glasslyUserId
+          if (!this.userId) this.userId = next.userId
         }
         return
       }
@@ -785,6 +845,14 @@ export class MiniappSession<TChannels extends object = any> {
         return
       }
 
+      case MiniappResponseType.PREFERENCES_UPDATE: {
+        const prefs = payload.preferences as MiniappPreferences | undefined
+        if (!prefs) return
+        this.preferences = prefs
+        this.emitter.emit("preferences", prefs)
+        return
+      }
+
       case MiniappResponseType.VISIBILITY_CHANGE: {
         const next = payload.visibility as MiniappVisibility | undefined
         if (next === "foreground" || next === "background") {
@@ -956,6 +1024,8 @@ function manifestKeyToCanonical(manifestKey: string): PermissionType | null {
       return "memory"
     case "AI":
       return "ai"
+    case "DISPLAY_MIRROR":
+      return "displayMirror"
     case "SPEAKERS":
       return "speakers"
     default:

package/src/transport/auto.ts

@@ -24,12 +24,12 @@ export interface CreateTransportOptions {
  *
  * 1. **DispatchTransport** — when running in a per-miniapp JSContext
  *    (no DOM, but `__dispatch` is installed on `globalThis` by the
- *    GlasslyJS runtime). This is the production path.
+ *    JSRuntime runtime). This is the production path.
  * 2. **PostMessageTransport** — inside a Glassly WebView
  *    (`window.ReactNativeWebView` defined). This is the existing UI
  *    layer path and the only transport miniapp UI bundles need.
  * 3. **MockTransport** — explicit opt-in via `?glassly=mock` or
- *    `localStorage.GLASSLY_MOCK=1`. Useful for Storybook / unit tests.
+ *    `localStorage.MINIAPP_MOCK=1`. Useful for Storybook / unit tests.
  * 4. **LocalSocketWithMockFallback** — external browser, races a
  *    `ws://127.0.0.1` LocalSocketTransport open against a 500ms timeout
  *    and falls back to MockTransport so the page doesn't hang.

package/src/transport/dispatch.ts

@@ -1,7 +1,7 @@
 /**
  * @fileoverview DispatchTransport — Transport implementation that rides
  * the native `__dispatch(iface, method, argsJson)` bridge exposed by the
- * GlasslyJS runtime (per-miniapp JSContext on iOS-JSC, Zipline/QuickJS
+ * JSRuntime runtime (per-miniapp JSContext on iOS-JSC, Zipline/QuickJS
  * context on Android).
  *
  * The existing `MiniappSession` (session.ts) is transport-agnostic — it

package/src/transport/mock.ts

@@ -4,7 +4,7 @@
  * Activates when:
  *   - `window.ReactNativeWebView` is undefined (not in Glassly WebView), AND
  *   - The first LocalSocketTransport connection attempt fails fast, OR
- *   - The author opts in via `?glassly=mock` query param / `localStorage.GLASSLY_MOCK = "1"`.
+ *   - The author opts in via `?glassly=mock` query param / `localStorage.MINIAPP_MOCK = "1"`.
  *
  * Behaviors:
  *   - On `open()`: synthesize a CONNECT_ACK envelope so `session.connect()` resolves.
@@ -12,20 +12,32 @@
  *     auto-reply with synthetic results for any request that needs one.
  *   - Does NOT emit any glasses events. Subscribing succeeds silently.
  *
- * This is the Stage-1 stopgap from `agents/miniapp-quick-fixes-spec.md` #6.
+ * This is the Stage-1 stopgap from `notes/archive/agents/miniapp-quick-fixes-spec.md` #6.
  * The full simulator (event injection, glasses-display preview, hardware bridge)
- * is Stage 2 — see `agents/miniapp-browser-testing-simulator-spec.md`.
+ * is Stage 2 — see `notes/archive/agents/miniapp-browser-testing-simulator-spec.md`.
  */
 
 import {parseEnvelope, serializeEnvelope, type MiniappEnvelope} from "../envelope"
-import {MiniappRequestType, MiniappResponseType} from "../protocol"
+import {MiniappRequestType, MiniappResponseType, MiniappStreamType} from "../protocol"
 import type {Transport, TransportDisconnectHandler, TransportMessageHandler} from "./types"
 
+const mockMirror = () => ({
+  revision: 0,
+  updatedAt: 0,
+  connected: false,
+  model: null,
+  canvas: null,
+  view: null,
+  appId: null,
+  content: {kind: "unavailable", reason: "mock-host"},
+  glyphWidths: {},
+})
+
 const LOG_PREFIX = "[mock-transport]"
 
 /**
  * Returns true if the current environment requested the mock transport
- * explicitly. Checks `?glassly=mock` query param and `localStorage.GLASSLY_MOCK`.
+ * explicitly. Checks `?glassly=mock` query param and `localStorage.MINIAPP_MOCK`.
  */
 export function isMockExplicitlyRequested(): boolean {
   if (typeof window === "undefined") return false
@@ -38,7 +50,7 @@ export function isMockExplicitlyRequested(): boolean {
     // ignore
   }
   try {
-    if (typeof localStorage !== "undefined" && localStorage.getItem("GLASSLY_MOCK") === "1") {
+    if (typeof localStorage !== "undefined" && localStorage.getItem("MINIAPP_MOCK") === "1") {
       return true
     }
   } catch {
@@ -105,6 +117,19 @@ export class MockTransport implements Transport {
         return
 
       case MiniappRequestType.SUBSCRIBE:
+        if (Array.isArray(payload.subscriptions) && payload.subscriptions.includes(MiniappStreamType.MIRROR_UPDATE)) {
+          queueMicrotask(() =>
+            this.messageHandler?.(
+              serializeEnvelope({
+                payload: {
+                  type: MiniappResponseType.EVENT,
+                  streamType: MiniappStreamType.MIRROR_UPDATE,
+                  data: mockMirror(),
+                },
+              }),
+            ),
+          )
+        }
         // Subscribe is fire-and-forget; no response expected. Stage 1 emits no
         // events. Future Stage 2 simulator can synthesize events here.
         return
@@ -149,7 +174,7 @@ export class MockTransport implements Transport {
       visibility: "foreground",
       colorScheme: "light",
       auth: {
-        glasslyUserId: this.userId,
+        userId: this.userId,
         oemId: "mock",
         token: this.authToken,
         expiresAt: Date.now() + 60 * 60 * 1000,
@@ -195,10 +220,10 @@ function syntheticDataFor(requestId: string, requestType: string, requestPayload
         requestPayload.preset === "narrow"
           ? 82
           : requestPayload.preset === "wide"
-            ? 118
-            : requestPayload.preset === "standard"
-              ? 102
-              : undefined
+          ? 118
+          : requestPayload.preset === "standard"
+          ? 102
+          : undefined
       const fov = typeof requestPayload.fov === "number" ? requestPayload.fov : (presetFov ?? 102)
       const roi = requestPayload.roiPosition
       const roiPosition = roi === "bottom" ? "bottom" : roi === "top" ? "top" : "center"
@@ -221,6 +246,9 @@ function syntheticDataFor(requestId: string, requestType: string, requestPayload
     case MiniappRequestType.RGB_LED:
       return {type: "rgb_led_control_response", state: "success", requestId}
 
+    case MiniappRequestType.MIRROR_GET:
+      return mockMirror()
+
     case MiniappRequestType.LOCATION_POLL:
       // San Francisco fallback — using 0,0 puts dev sessions in the
       // Atlantic, which makes maps/navigation unusable in the WebView.
@@ -246,6 +274,9 @@ function syntheticDataFor(requestId: string, requestType: string, requestPayload
     case MiniappRequestType.SET_WIFI_ADB_STATE:
       return {ok: true}
 
+    case MiniappRequestType.DISPLAY_DIAGNOSTICS:
+      return {enabled: false, generatedAt: Date.now(), records: []}
+
     case MiniappRequestType.SCAN_QR:
       return {cancelled: true}