@glassly/miniapp 0.3.0-dev.2 → 0.3.0-dev.462

package/src/mirror/geometry.ts

@@ -0,0 +1,128 @@
+export const SHAPE_TYPES = new Set(["rect", "circle", "arc", "pie", "line", "triangle", "quad", "bezier", "svg"])
+
+/** The mirror consumes processed frames; it does not own native scene state. */
+export interface MirrorSceneElement {
+  id?: string
+  type?: string
+  box?: {x?: number; y?: number; w?: number; h?: number}
+  points?: readonly {x: number; y: number}[]
+  style?: {
+    color?: number
+    width?: number
+    border?: number
+    radius?: number
+    fill?: boolean
+    font?: string
+    fontSize?: number
+  }
+  startDeg?: number
+  endDeg?: number
+  rotation?: number
+  pivot?: {x: number; y: number}
+  pathScale?: number
+  d?: string
+  fillRule?: string
+  text?: string
+  data?: string
+  change?: string
+  transition?: {durationMs: number; easing?: string}
+}
+
+/** Tweenable state of one scene element, in canvas pixels. */
+export interface SceneGeometry {
+  x: number
+  y: number
+  w: number
+  h: number
+  /** Ink intensity derived from the gray level (0..15 → 0..1). */
+  level: number
+  /** Stroke width in canvas px; 0 = no outline. */
+  stroke: number
+  radius: number
+  /** Flat x0, y0, x1, y1, … for point shapes. */
+  points: number[]
+  startDeg: number
+  endDeg: number
+  rotation: number
+  pivotX: number
+  pivotY: number
+  pathScale: number
+}
+
+/** Gray level 0..15 → normalized ink intensity. */
+export function levelOpacity(color: unknown): number {
+  const level = Number(color)
+  return Number.isFinite(level) ? Math.max(0, Math.min(15, level)) / 15 : 1
+}
+
+export function sceneGeometry(element: MirrorSceneElement): SceneGeometry {
+  const box = element?.box ?? {}
+  const style = element?.style ?? {}
+  const type = element?.type
+  const stroke =
+    type !== "rect" && SHAPE_TYPES.has(type ?? "")
+      ? Number(style.width) || Number(style.border) || 1
+      : Number(style.border) || (type === "rect" && style.fill !== true ? 1 : 0)
+  const points: number[] = Array.isArray(element?.points)
+    ? element.points.flatMap((p) => [Number(p?.x) || 0, Number(p?.y) || 0])
+    : []
+  return {
+    x: Number(box.x) || 0,
+    y: Number(box.y) || 0,
+    w: Math.max(0, Number(box.w) || 0),
+    h: Math.max(0, Number(box.h) || 0),
+    level: levelOpacity(style.color),
+    stroke,
+    radius: Number(style.radius) || 0,
+    points,
+    startDeg: Number(element?.startDeg) || 0,
+    endDeg: Number(element?.endDeg) || 0,
+    rotation: Number(element?.rotation) || 0,
+    pivotX: Number(element?.pivot?.x ?? Number(box.x || 0) + Number(box.w || 0) / 2),
+    pivotY: Number(element?.pivot?.y ?? Number(box.y || 0) + Number(box.h || 0) / 2),
+    pathScale: Number(element?.pathScale ?? 256) / 256,
+  }
+}
+
+export function geometryEqual(a: SceneGeometry, b: SceneGeometry): boolean {
+  return (
+    a.x === b.x &&
+    a.y === b.y &&
+    a.w === b.w &&
+    a.h === b.h &&
+    a.level === b.level &&
+    a.stroke === b.stroke &&
+    a.radius === b.radius &&
+    a.startDeg === b.startDeg &&
+    a.endDeg === b.endDeg &&
+    a.pathScale === b.pathScale &&
+    a.points.length === b.points.length &&
+    a.points.every((p, i) => p === b.points[i])
+  )
+}
+
+/** Linear blend of two geometries at eased progress `t` (0..1). */
+export function tweenAt(from: SceneGeometry, to: SceneGeometry, t: number): SceneGeometry {
+  "worklet"
+  if (t >= 1) return to
+  if (t <= 0) return from
+  const mix = (a: number, b: number) => a + (b - a) * t
+  const points = from.points.length === to.points.length ? to.points.map((p, i) => mix(from.points[i], p)) : to.points
+  return {
+    x: mix(from.x, to.x),
+    y: mix(from.y, to.y),
+    w: mix(from.w, to.w),
+    h: mix(from.h, to.h),
+    level: mix(from.level, to.level),
+    stroke: mix(from.stroke, to.stroke),
+    radius: mix(from.radius, to.radius),
+    points,
+    startDeg: mix(from.startDeg, to.startDeg),
+    endDeg: mix(from.endDeg, to.endDeg),
+    rotation: mix(from.rotation, to.rotation),
+    // Firmware changes the fixed pivot immediately when a rotation retargets.
+    pivotX: to.pivotX,
+    pivotY: to.pivotY,
+    pathScale: mix(from.pathScale, to.pathScale),
+  }
+}

package/src/mirror/index.ts

@@ -0,0 +1,2 @@
+export {MirrorCanvasRenderer} from "./canvas"
+export type {MirrorSnapshot, MirrorContent, MirrorElement} from "./types"

package/src/mirror/types.ts

@@ -0,0 +1,38 @@
+import type {
+  FrameElement,
+  SceneTextStyle,
+  SceneRectStyle,
+  SceneShapeStyle,
+  SceneStrokeStyle,
+  SceneImageStyle,
+} from "../display/scene/types"
+
+type ReadonlyValue<T> = T extends object ? {readonly [K in keyof T]: ReadonlyValue<T[K]>} : T
+
+/** Ordered, processed scene element. Coordinates are glasses canvas pixels. */
+export type MirrorElement = ReadonlyValue<
+  Omit<FrameElement, "path" | "contentHash" | "style"> & {
+    style?: SceneTextStyle & SceneRectStyle & SceneShapeStyle & SceneStrokeStyle & SceneImageStyle
+  }
+>
+
+export type MirrorContent =
+  | {readonly kind: "scene"; readonly elements: readonly MirrorElement[]; readonly epoch: number}
+  | {readonly kind: "bitmap"; readonly data: string}
+  | {readonly kind: "empty"}
+  | {readonly kind: "unavailable"; readonly reason: string}
+
+/** Serializable intended output after display arbitration; never a hardware screenshot. */
+export interface MirrorSnapshot {
+  /** Monotonic within this host runtime; useful when mixing requests and updates. */
+  readonly revision: number
+  readonly updatedAt: number
+  readonly connected: boolean
+  readonly model: string | null
+  readonly canvas: {readonly width: number; readonly height: number} | null
+  readonly view: "main" | "dashboard" | null
+  readonly appId: string | null
+  readonly content: MirrorContent
+  /** Rendered advances for the code points in this snapshot (builtin text). */
+  readonly glyphWidths: Readonly<Record<string, number>>
+}

package/src/modules/auth.ts

@@ -18,8 +18,8 @@ export class AuthModule {
     return this.session._getAuth()
   }
 
-  get glasslyUserId(): string | null {
-    return this.current?.glasslyUserId ?? null
+  get userId(): string | null {
+    return this.current?.userId ?? null
   }
 
   get oemId(): string | null {

package/src/modules/compass.ts

@@ -0,0 +1,69 @@
+/**
+ * Glasses compass. Subscribing starts the sensor like other glasses streams:
+ * on G2 custom firmware the raw compass API runs whenever any miniapp is
+ * subscribed; on stock firmware headings only arrive while the glasses' native
+ * navigation UI is open. Elsewhere the subscription succeeds and stays silent.
+ */
+import {MiniappRequestType, MiniappStreamType} from "../protocol"
+import type {MiniappSession} from "../session"
+import type {UnsubscribeFn} from "./events"
+
+export interface CompassOptions {
+  /** 50..2000 ms, default 1000. */
+  intervalMs?: number
+  /** Heading change threshold, 0..359 degrees, default 5. */
+  minChangeDegrees?: number
+}
+export interface CompassDiagnostics {
+  accuracy: 0 | 1 | 2 | 3 | null
+  anomalies: 0 | 1 | 2 | null
+  source: "unknown" | "grv" | "gmrv" | "rv"
+  sampleMatched: boolean
+  grvValid: boolean
+  gmrvValid: boolean
+  rvValid: boolean
+  magneticDataFresh: boolean
+  /** Firmware uptime, wraps at 2^32 ms. */
+  sampleTimestampMs: number
+}
+export interface CompassData {
+  /** Magnetic heading in degrees, 0 = north, 90 = east. Fused heading, not raw magnetometer XYZ. */
+  degrees: number
+  /** Phone reception time, Unix milliseconds. */
+  timestamp: number
+  /** Fusion quality; custom firmware only. */
+  diagnostics?: CompassDiagnostics
+}
+export interface CompassCalibrationData {
+  status: "start" | "complete"
+}
+
+export class CompassModule {
+  constructor(private readonly session: MiniappSession) {}
+  onUpdate(handler: (data: CompassData) => void): UnsubscribeFn {
+    return this.session._subscribe(MiniappStreamType.GLASSES_COMPASS, handler as (data: unknown) => void)
+  }
+  onCalibration(handler: (data: CompassCalibrationData) => void): UnsubscribeFn {
+    return this.session._subscribe(MiniappStreamType.COMPASS_CALIBRATION, handler as (data: unknown) => void)
+  }
+  /**
+   * Override the sampling this miniapp asks for. Subscribers already run with
+   * firmware defaults; the phone serves every subscriber the smallest interval
+   * and smallest change threshold requested across miniapps. Custom firmware only.
+   */
+  start(options: CompassOptions = {}): Promise<void> {
+    return this.control("start", options)
+  }
+  /** Drop this miniapp's sampling override. Live subscriptions keep the sensor running. */
+  stop(): Promise<void> {
+    return this.control("stop")
+  }
+  private control(operation: string, options: CompassOptions = {}): Promise<void> {
+    return this.session.sendRequest({
+      type: MiniappRequestType.GLASSES_SENSOR_CONTROL,
+      sensor: "compass",
+      operation,
+      options,
+    })
+  }
+}

package/src/modules/display.ts

@@ -9,8 +9,9 @@
  * from bundles packed with older SDKs.
  */
 
-import {MiniappRequestType} from "../protocol"
+import {MiniappRequestType, MiniappStreamType} from "../protocol"
 import {MiniappSession} from "../session"
+import type {UnsubscribeFn} from "./events"
 
 export type ViewType = "main" | "dashboard"
 
@@ -57,26 +58,155 @@ export interface RenderTextStyle {
    * of 1.2 × size, and NOT re-wrapped by the host — lines are taken as given.
    * For grids (terminals, tables). Devices without a phone-side rasterizer
    * (stock G2 firmware) fall back to their own proportional font.
+   *
+   * "builtin": the glasses draw the text themselves with their built-in 20 px
+   * proportional font. On the Glassly CFW G2 the default face is drawn the
+   * same way, so text updates are a few bytes each and animate like shapes;
+   * lines are clipped to the box and the render window is pinned to the
+   * middle depth level. Other devices and stock firmware use the phone's
+   * proportional face.
    */
-  font?: "default" | "mono"
+  font?: "default" | "mono" | "builtin"
   /** Font size in px for `font: "mono"`. Default 20. */
   fontSize?: number
+  /** Gray level 0..15 (15 = brightest) on devices that draw text themselves. Default 15. */
+  color?: number
 }
 
 export interface RenderRectStyle {
   border?: number
   radius?: number
+  /** Solid fill instead of an outline. */
+  fill?: boolean
+  /** Gray level 0..15 (15 = brightest). Default 15. */
+  color?: number
+}
+
+/** Closed shapes (circle, triangle, quad): an outline `border` px wide, or filled. */
+export interface RenderShapeStyle {
+  border?: number
+  fill?: boolean
+  /** Gray level 0..15 (15 = brightest). Default 15. */
+  color?: number
+}
+
+/** Open strokes (line, bezier, arc). */
+export interface RenderStrokeStyle {
+  /** Stroke width in px. Default 1. */
+  width?: number
+  /** Gray level 0..15 (15 = brightest). Default 15. */
+  color?: number
+}
+
+/** A point in raw canvas pixels (no anchoring). */
+export interface RenderPoint {
+  x: number
+  y: number
+}
+
+export type RenderEasing = "linear" | "ease" | "ease-in" | "ease-out" | "ease-in-out"
+
+/**
+ * Animate an element's geometry between renders. When an element with a
+ * stable `id` moves, resizes, or changes its points/angles/color, devices
+ * with `capabilities.display.animation` tween it on the glasses over
+ * `durationMs`; other devices jump. Content changes (new text or image
+ * pixels) always switch immediately.
+ */
+export interface RenderTransition {
+  durationMs: number
+  /** Default "ease". */
+  easing?: RenderEasing
 }
 
 /**
  * One element of a rendered scene. `id` is optional but recommended for
  * anything that updates over time: elements with a stable id update in place on
  * the glasses (no flicker); the host matches unnamed elements by geometry.
+ *
+ * Shapes beyond `rect` need `capabilities.display.shapes` to list the type;
+ * a device without it drops the element (reported via `dropped`). Circles,
+ * arcs and pies are inscribed in their box (radius = half the shorter side;
+ * angles in degrees, 0 = right, increasing clockwise). Point shapes take
+ * raw canvas coordinates and are clipped by the device; `bezier` is
+ * quadratic with 3 points or cubic with 4.
  */
-export type RenderElement =
-  | {type: "text"; id?: string; box: RenderBox; text: string; style?: RenderTextStyle}
-  | {type: "image"; id?: string; box: RenderBox; data: string}
-  | {type: "rect"; id?: string; box: RenderBox; style?: RenderRectStyle}
+export type RenderElement = (
+  | {type: "text"; id?: string; box: RenderBox; text: string; style?: RenderTextStyle; transition?: RenderTransition}
+  | {type: "image"; id?: string; box: RenderBox; data: string; transition?: RenderTransition}
+  | {type: "rect"; id?: string; box: RenderBox; style?: RenderRectStyle; transition?: RenderTransition}
+  | {type: "circle"; id?: string; box: RenderBox; style?: RenderShapeStyle; transition?: RenderTransition}
+  | {
+      type: "arc"
+      id?: string
+      box: RenderBox
+      startDeg: number
+      endDeg: number
+      style?: RenderStrokeStyle
+      transition?: RenderTransition
+    }
+  | {
+      type: "pie"
+      id?: string
+      box: RenderBox
+      startDeg: number
+      endDeg: number
+      style?: {color?: number}
+      transition?: RenderTransition
+    }
+  | {
+      type: "line"
+      id?: string
+      points: [RenderPoint, RenderPoint]
+      style?: RenderStrokeStyle
+      transition?: RenderTransition
+    }
+  | {
+      type: "triangle"
+      id?: string
+      points: [RenderPoint, RenderPoint, RenderPoint]
+      style?: RenderShapeStyle
+      transition?: RenderTransition
+    }
+  | {
+      type: "quad"
+      id?: string
+      points: [RenderPoint, RenderPoint, RenderPoint, RenderPoint]
+      style?: RenderShapeStyle
+      transition?: RenderTransition
+    }
+  | {
+      type: "bezier"
+      id?: string
+      points: [RenderPoint, RenderPoint, RenderPoint] | [RenderPoint, RenderPoint, RenderPoint, RenderPoint]
+      style?: RenderStrokeStyle
+      transition?: RenderTransition
+    }
+  | {
+      type: "svg"
+      id?: string
+      box: RenderBox
+      d: string
+      scale?: number
+      fillRule?: "nonzero" | "evenodd"
+      style?: {color?: number}
+      transition?: RenderTransition
+    }
+) & {
+  /** Clockwise degrees, unwrapped (0 to 360 makes a full turn). Geometric shapes and SVG only. */
+  rotation?: number
+  /** Fixed pivot in canvas pixels; defaults to the target box center. */
+  pivot?: RenderPoint
+  /**
+   * Stereo depth in canvas pixels, -16..16: positive floats the element in
+   * front of the rest of the frame, negative sinks it behind. Devices with
+   * `capabilities.display.depth` shift it by `depth` px on the left lens and
+   * `-depth` px on the right; others draw it flat. Elements paint in array
+   * order, so a card that should sit on top goes last AND at a positive depth.
+   * A depth change with a `transition` glides toward or away from the viewer.
+   */
+  depth?: number
+}
 
 export interface RenderOptions {
   view?: ViewType
@@ -84,6 +214,38 @@ export interface RenderOptions {
   durationMs?: number
 }
 
+// ============================================================================
+// The dashboard view — the overlay slot above the main content
+// ============================================================================
+
+/**
+ * "shown" = the requested view is showing (already showing counts).
+ * "unsupported" = the host refused: the glasses cannot show the dashboard
+ * view right now, or this app is not the designated dashboard app.
+ */
+export interface ShowViewResult {
+  status: "shown" | "unsupported"
+  reason?: string
+}
+
+/**
+ * Why the showing view changed. "shown" and "hidden" answer this app's own
+ * showView calls; "replaced" means another overlay app took the view;
+ * "ineligible" means the glasses stopped being able to show the dashboard
+ * view (disconnected, dashboard turned off); "app_stopped" is implied when
+ * the app itself stops and never arrives as an event.
+ */
+export type DisplayViewChangeReason = "shown" | "hidden" | "replaced" | "ineligible" | "app_stopped"
+
+export interface DisplayViewChange {
+  /** The view now showing. */
+  view: ViewType
+  reason: DisplayViewChangeReason
+}
+
+/** Wire shape of the display_view stream. */
+type DisplayViewEvent = {kind: "change"; view: ViewType; reason: DisplayViewChangeReason}
+
 // ============================================================================
 // Native navigation UI (capability `hasNativeNavigation`, e.g. G2)
 // ============================================================================
@@ -115,10 +277,12 @@ export interface NativeNavResult {
 }
 
 /**
- * Outcome of a render request, resolved when the host's display arbitration
- * settles it. "displayed" = accepted and sent to the device — NOT a
- * render confirmation. "blocked" = another app owns the display (or the
- * request failed); `reason` says why.
+ * Outcome of a render request. "displayed" = the host accepted the frame;
+ * on scene devices it resolves once the glasses have the frame and its
+ * transitions have finished playing (`presented`), or once the host knows
+ * the frame won't show right now (`presented: false`, `reason` says why —
+ * dashboard covering the view, screen off, nav UI up, glasses busy).
+ * "blocked" = another app owns the display (or the request failed).
  */
 export interface RenderResult {
   status: "displayed" | "blocked"
@@ -126,6 +290,13 @@ export interface RenderResult {
   degraded?: boolean
   /** Ids of elements the host dropped (budget/bounds/device limits) — dropped is never silent. */
   dropped?: string[]
+  /**
+   * The glasses showed this frame's content before the promise resolved.
+   * Absent on legacy/degrade paths, where "displayed" still just means sent.
+   */
+  presented?: boolean
+  /** A newer render() from this app landed before this one was reported; its content is on screen. */
+  superseded?: boolean
   reason?: string
 }
 
@@ -146,14 +317,21 @@ export class DisplayManager {
    * over-budget elements are dropped tail-first; both are reported via the
    * result, never silently.
    *
-   * Awaiting is OPT-IN — a plain fire-and-forget call is fine. The returned
-   * promise never rejects.
+   * Awaiting is OPT-IN — a plain fire-and-forget call is fine. Awaited, the
+   * promise resolves once the glasses have the frame and any transitions it
+   * started have finished (see `RenderResult.presented`), so `await` in a
+   * loop paces you at the real display rate. Frames that arrive faster than
+   * the host sends them are folded into the next one; each still resolves
+   * when its content is on screen. The returned promise never rejects.
    *
    * @example
    * const result = await session.display.render([
    *   {type: "text",  id: "stats", box: {x: 12, y: 9, w: 200, h: 28}, text: "863 m  11 min"},
    *   {type: "image", id: "map",   box: {x: 335, y: 14, w: 150, h: 150}, data: mapPng},
    *   {type: "rect",  box: {x: 0, y: 0, w: 500, h: 220}, style: {radius: 4}},
+   *   // Re-render with a new box and the ball glides there over 300 ms on animating devices.
+   *   {type: "circle", id: "ball", box: {x: 40, y: 100, w: 30, h: 30}, style: {fill: true},
+   *    transition: {durationMs: 300, easing: "ease-in-out"}},
    * ])
    * if (result.degraded) console.warn("dropped:", result.dropped)
    */
@@ -174,6 +352,38 @@ export class DisplayManager {
       }))
   }
 
+  /**
+   * Ask the host to show a view. `"dashboard"` takes the overlay slot above
+   * the main content: frames rendered with `{view: "dashboard"}` reach the
+   * glasses while it shows. Claim the gestures you handle there with
+   * `session.input.setClaimedGestures`. `"main"` releases the slot; the
+   * retained main content replays. Both are idempotent. Only running apps
+   * whose manifest `type` is `"system_dashboard"` may show the dashboard
+   * view, and only while `capabilities.display.views` lists it; the most
+   * recent of them to ask holds it and the previous one hears "replaced".
+   */
+  showView(view: ViewType): Promise<ShowViewResult> {
+    return this.session.sendRequest<ShowViewResult>({type: MiniappRequestType.SHOW_VIEW, view}).catch((err) => ({
+      status: "unsupported" as const,
+      reason:
+        typeof err === "object" && err !== null && "message" in err
+          ? String((err as {message: unknown}).message)
+          : String(err),
+    }))
+  }
+
+  /**
+   * The showing view changed: the host granted the dashboard view, this app
+   * released it, another overlay app took it, or the glasses stopped being
+   * able to show it. Fires only for system_dashboard apps.
+   */
+  onViewChange(handler: (change: DisplayViewChange) => void): UnsubscribeFn {
+    return this.session._subscribe(MiniappStreamType.DISPLAY_VIEW, (data) => {
+      const event = data as DisplayViewEvent | null
+      if (event?.kind === "change") handler({view: event.view, reason: event.reason})
+    })
+  }
+
   /** Update the native nav UI's turn-by-turn card. */
   sendNativeNavInfo(info: NativeNavInfo): Promise<NativeNavResult> {
     return this.sendNativeNav({action: "info", info})

package/src/modules/events.ts

@@ -106,7 +106,7 @@ export interface LocationData {
 }
 
 export interface HeadingData {
-  /** Compass heading in degrees, 0 = north, 90 = east. */
+  /** Phone compass heading in degrees, 0 = north, 90 = east. */
   degrees: number
 }
 
@@ -162,6 +162,9 @@ export interface TouchData {
    * The gesture: single_tap, double_tap, triple_tap, long_press, swipe_up, or
    * swipe_down — plus the raw press edges tap_start (finger down) and tap_end
    * (finger up), which bracket every gesture on hardware that reports them.
+   * tap_then_hold is the G2 2.2.9 tap-then-hold (Menu) gesture. touch_down is
+   * the R1 ring's finger-down, forwarded by the Glassly CFW (GLASSLYCFW/37 on
+   * G2 2.3.0.24); only the ring produces it, the temples report tap_start.
    */
   kind:
     | "single_tap"
@@ -172,9 +175,32 @@ export interface TouchData {
     | "swipe_down"
     | "tap_start"
     | "tap_end"
+    | "tap_then_hold"
+    | "touch_down"
     | string
 }
 
+/**
+ * One key transition from a physical keyboard paired to the glasses (G2
+ * Glassly CFW revision 39+). Shapes follow the DOM: `key` is the logical key
+ * under the host's layout (US for now: "a", "A", "Enter", "ArrowUp", "F5",
+ * "AudioVolumeUp", …), `code` the physical key ("KeyA", "Digit1", "Space",
+ * "ControlLeft", …). `text` is the printable character a plain press types
+ * (down and repeat only, absent for Ctrl/Alt/Meta chords and named keys).
+ * `repeat` marks the host's synthesized auto-repeat while a key stays held;
+ * every gap in the link releases held keys with matching `up` events.
+ */
+export interface KeyboardEventData {
+  phase: "down" | "up"
+  key: string
+  code: string
+  modifiers: {shift: boolean; ctrl: boolean; alt: boolean; meta: boolean}
+  text?: string
+  repeat: boolean
+  /** Phone receipt time, unix ms. */
+  timestamp: number
+}
+
 export interface AudioChunkData {
   /** PCM or LC3, base64-encoded. Format depends on phone's mic mode. */
   data: string

package/src/modules/input.ts

@@ -15,17 +15,70 @@
  * the phone runtime fans out alongside the bare `touch_event` stream.
  */
 
-import {MiniappStreamType} from "../protocol"
+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 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 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([])             // hand it back
+   */
+  setClaimedGestures(gestures: string[], options?: {scope?: string}): Promise<void> {
+    return this.session
+      .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.
    *