@glassly/miniapp 0.1.0-dev.26

package/src/modules/imu.ts

@@ -0,0 +1,44 @@
+/**
+ * @fileoverview ImuModule — head position + motion events.
+ *
+ * Glasses' inertial measurement unit. Exposes head-up/down position and a
+ * raw accelerometer stream (`onAccel`). Gyroscope / magnetometer / fused
+ * orientation are future work — when added they'll surface as a combined IMU
+ * event rather than extending this single-sensor accel stream.
+ */
+
+import {MiniappRequestType, MiniappStreamType} from "../protocol"
+import {MiniappSession} from "../session"
+import type {AccelData, HeadPositionData, UnsubscribeFn} from "./events"
+
+export class ImuModule {
+  constructor(private readonly session: MiniappSession) {}
+
+  onHeadPosition(handler: (data: HeadPositionData) => void): UnsubscribeFn {
+    return this.session._subscribe(MiniappStreamType.HEAD_POSITION, handler as (data: unknown) => void)
+  }
+
+  /**
+   * Subscribe to raw accelerometer readings (`{x, y, z}` in g) from the
+   * glasses IMU. G2 only today; on glasses without an exposed IMU stream the
+   * subscription succeeds but no events fire.
+   */
+  onAccel(handler: (data: AccelData) => void): UnsubscribeFn {
+    return this.session._subscribe(MiniappStreamType.ACCEL_DATA, handler as (data: unknown) => void)
+  }
+
+  /**
+   * Explicitly enable or disable raw accelerometer streaming on the glasses.
+   *
+   * Subscribing via `onAccel` already auto-enables the sensor and unsubscribing
+   * disables it, so most callers don't need this. Use it when you want to drive
+   * the IMU directly — e.g. a diagnostic toggle. G2 only today; a no-op on
+   * glasses without an exposed IMU stream.
+   */
+  setEnabled(enabled: boolean): Promise<void> {
+    return this.session.sendRequest<void>({
+      type: MiniappRequestType.IMU_SET_ENABLED,
+      enabled,
+    })
+  }
+}

package/src/modules/input.ts

@@ -0,0 +1,87 @@
+/**
+ * @fileoverview InputModule — physical control events on the glasses.
+ *
+ * Combines button + touch surfaces. Future input modes (gesture, voice
+ * command, eye tracking) will extend this module rather than spawning new
+ * top-level modules.
+ *
+ * Touch overloads:
+ *
+ *   session.input.onTouch(handler)
+ *   session.input.onTouch("single_tap", handler)
+ *   session.input.onTouch(["swipe_up", "swipe_down"], handler)
+ *
+ * Per-gesture filtering rides on `touch_event:<gesture>` stream variants
+ * the phone runtime fans out alongside the bare `touch_event` stream.
+ */
+
+import {MiniappRequestType, MiniappStreamType} from "../protocol"
+import {MiniappSession} from "../session"
+import type {ButtonPressData, TouchData, UnsubscribeFn} from "./events"
+
+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.
+   *
+   * 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.
+   *
+   *   session.input.setClaimedGestures(["double_tap"]) // in-app back gesture
+   *   session.input.setClaimedGestures([])             // back to system default
+   */
+  setClaimedGestures(gestures: string[]): Promise<void> {
+    return this.session
+      .sendRequest<void>({type: MiniappRequestType.CLAIM_GESTURES, gestures})
+      .then(() => undefined)
+  }
+
+  onButtonPress(handler: (data: ButtonPressData) => void): UnsubscribeFn {
+    return this.session._subscribe(MiniappStreamType.BUTTON_PRESS, handler as (data: unknown) => void)
+  }
+
+  /**
+   * Subscribe to touch events.
+   *
+   *   onTouch(handler)                — all touch events
+   *   onTouch("single_tap", handler)  — only single taps
+   *   onTouch(["a","b"], handler)     — multiple gestures, single subscription
+   */
+  onTouch(handler: (data: TouchData) => void): UnsubscribeFn
+  onTouch(gesture: string, handler: (data: TouchData) => void): UnsubscribeFn
+  onTouch(gestures: string[], handler: (data: TouchData) => void): UnsubscribeFn
+  onTouch(
+    gestureOrHandler: string | string[] | ((data: TouchData) => void),
+    maybeHandler?: (data: TouchData) => void,
+  ): UnsubscribeFn {
+    // Plain handler — subscribe to all touches.
+    if (typeof gestureOrHandler === "function") {
+      return this.session._subscribe(MiniappStreamType.TOUCH_EVENT, gestureOrHandler as (data: unknown) => void)
+    }
+
+    const handler = maybeHandler!
+    const gestures = Array.isArray(gestureOrHandler) ? gestureOrHandler : [gestureOrHandler]
+    if (gestures.length === 0) return () => {}
+
+    const unsubs: UnsubscribeFn[] = []
+    for (const g of gestures) {
+      unsubs.push(this.session._subscribe(`${MiniappStreamType.TOUCH_EVENT}:${g}`, handler as (data: unknown) => void))
+    }
+    return () => {
+      for (const u of unsubs) {
+        try {
+          u()
+        } catch {
+          /* ignore */
+        }
+      }
+    }
+  }
+}

package/src/modules/keys.ts

@@ -0,0 +1,46 @@
+/**
+ * @fileoverview KeysModule — read user-supplied provider API keys.
+ *
+ * Users can enter their own provider API keys in the Glassly App
+ * (Settings > API Keys). A miniapp that declares the API_KEYS permission in
+ * miniapp.json can read the providers in {@link ApiKeyProvider}; the phone
+ * runtime rejects with PERMISSION_NOT_DECLARED otherwise.
+ *
+ * The provider set is an explicit host-side allowlist — asking for anything
+ * else (e.g. the Soniox transcription key, which is deliberately not exposed
+ * to miniapps) rejects with INVALID_ARGUMENT. Keys are device-local settings:
+ * the value travels only across the local bridge, never through any server.
+ */
+
+import {MiniappRequestType} from "../protocol"
+import {MiniappSession} from "../session"
+
+/** Providers whose user-supplied keys miniapps may read. */
+export type ApiKeyProvider = "anthropic" | "gemini" | "openai" | "elevenlabs" | "mapbox"
+
+interface KeysGetResult {
+  key: string | null
+}
+
+export class KeysModule {
+  constructor(private readonly session: MiniappSession) {}
+
+  /** True iff `API_KEYS` is declared in the miniapp's manifest. */
+  get hasPermission(): boolean {
+    return this.session._hasManifestPermission("API_KEYS")
+  }
+
+  /**
+   * Fetch the user's API key for a provider. Resolves with the key, or null
+   * when the user hasn't saved one for that provider. Values are not cached —
+   * re-fetch (e.g. on retry after a 401 from the provider) to pick up a key
+   * the user edited in Settings while the miniapp was running.
+   */
+  async get(provider: ApiKeyProvider): Promise<string | null> {
+    const result = await this.session.sendRequest<KeysGetResult>({
+      type: MiniappRequestType.KEYS_GET,
+      provider,
+    })
+    return result?.key ?? null
+  }
+}

package/src/modules/languages.ts

@@ -0,0 +1,72 @@
+/**
+ * @fileoverview Language validation at the SDK boundary (issue 021, WP2).
+ *
+ * The registry itself lives in `@glassly/cloud-protocol/languages` (single
+ * source of truth shared with the cloud). This module re-exports the types so
+ * miniapps import everything from `@glassly/miniapp`, and adds the throwing
+ * validators the typed module surfaces (`transcription.*`, `translation.*`)
+ * call on every language parameter.
+ *
+ * Contract (design doc docs/issues/021-typed-language-subscriptions):
+ *   - Valid by construction: params are typed as literal unions, so TS users
+ *     get autocomplete and compile errors.
+ *   - Loud at runtime: JS users (or `any` casts) get a thrown
+ *     `MiniappValidationError` with a suggestion, never silent fallback.
+ *   - Canonical on the wire: bare codes ("fr") canonicalize to their default
+ *     tag ("fr-FR") before becoming stream keys, so the phone/cloud only ever
+ *     see registry tags.
+ */
+
+import {
+  isTranscriptionLanguage,
+  suggestTranscriptionLanguage,
+  toLanguageHint,
+  toTranscriptionLanguage,
+  SUPPORTED_LANGUAGE_HINTS,
+  SUPPORTED_TRANSCRIPTION_LANGUAGES,
+} from "@glassly/cloud-protocol/languages"
+import type {LanguageHint, TranscriptionLanguage} from "@glassly/cloud-protocol/languages"
+
+export {SUPPORTED_LANGUAGE_HINTS, SUPPORTED_TRANSCRIPTION_LANGUAGES, isTranscriptionLanguage}
+export type {LanguageHint, TranscriptionLanguage}
+
+/**
+ * Thrown synchronously by SDK methods when a parameter fails validation.
+ * Deliberately a hard throw (not a warning, not a silent default): an invalid
+ * language previously produced a subscription that silently transcribed the
+ * wrong language or silently never spoke (OS-1746).
+ */
+export class MiniappValidationError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "MiniappValidationError"
+  }
+}
+
+/**
+ * Canonicalize a subscription language or throw. Accepts registry tags
+ * ("fr-FR") and bare registry codes ("fr" -> "fr-FR").
+ */
+export function requireTranscriptionLanguage(value: string, param: string): TranscriptionLanguage {
+  const canonical = toTranscriptionLanguage(value)
+  if (canonical) return canonical
+  const suggestion = suggestTranscriptionLanguage(value)
+  throw new MiniappValidationError(
+    `${param}: unknown language ${JSON.stringify(value)}` +
+      (suggestion ? ` — did you mean ${JSON.stringify(suggestion)}?` : "") +
+      ` Supported values are BCP-47 tags from SUPPORTED_TRANSCRIPTION_LANGUAGES (e.g. "en-US", "fr-FR").`,
+  )
+}
+
+/**
+ * Normalize a language hint to the bare code the STT provider accepts, or
+ * throw. Accepts bare codes ("fr") and registry tags ("fr-FR" -> "fr").
+ */
+export function requireLanguageHint(value: string, param: string): LanguageHint {
+  const hint = toLanguageHint(value)
+  if (hint) return hint
+  throw new MiniappValidationError(
+    `${param}: unknown language hint ${JSON.stringify(value)}. ` +
+      `Hints are bare ISO 639-1 codes from SUPPORTED_LANGUAGE_HINTS (e.g. "en", "fr").`,
+  )
+}

package/src/modules/led.ts

@@ -0,0 +1,61 @@
+/**
+ * @fileoverview LedModule — glasses RGB LED control.
+ *
+ * API mirrors the cloud SDK's LED module. Colors are named strings
+ * (the phone maps them to per-device LED indices). Actions are "on" / "off".
+ */
+
+import {MiniappRequestType} from "../protocol"
+import {MiniappSession} from "../session"
+
+export type LedColor = "red" | "green" | "blue" | "orange" | "white"
+
+export type LedControlResult = {
+  type?: "rgb_led_control_response"
+  state: "success"
+  requestId: string
+}
+
+export interface LedControlOptions {
+  color?: LedColor
+  /** LED on duration in ms. */
+  ontime?: number
+  /** LED off duration in ms. */
+  offtime?: number
+  /** Number of on/off cycles. */
+  count?: number
+}
+
+export class LedModule {
+  constructor(private readonly session: MiniappSession) {}
+
+  /** Turn an LED on with the given pattern. Resolves after the glasses acknowledge the command. */
+  async turnOn(options: LedControlOptions = {}): Promise<LedControlResult> {
+    return this.session.sendRequest<LedControlResult>({
+      type: MiniappRequestType.RGB_LED,
+      action: "on",
+      color: options.color ?? "red",
+      ontime: options.ontime ?? 1000,
+      offtime: options.offtime ?? 0,
+      count: options.count ?? 1,
+    })
+  }
+
+  /** Turn all LEDs off. Resolves after the glasses acknowledge the command. */
+  async turnOff(): Promise<LedControlResult> {
+    return this.session.sendRequest<LedControlResult>({
+      type: MiniappRequestType.RGB_LED,
+      action: "off",
+    })
+  }
+
+  /** Blink pattern — repeats `count` times with ontime/offtime. */
+  async blink(color: LedColor, ontime: number, offtime: number, count: number): Promise<LedControlResult> {
+    return this.turnOn({color, ontime, offtime, count})
+  }
+
+  /** Solid LED for a fixed duration. */
+  async solid(color: LedColor, duration: number): Promise<LedControlResult> {
+    return this.turnOn({color, ontime: duration, offtime: 0, count: 1})
+  }
+}

package/src/modules/location.ts

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview LocationModule — phone location events.
+ *
+ * Exposes both a continuous `onUpdate` subscription and a one-shot
+ * `getOnce()` poll over `MiniappRequestType.LOCATION_POLL`.
+ *
+ * LOCATION permission must be declared in miniapp.json for either path to
+ * succeed; the phone runtime rejects with PERMISSION_NOT_DECLARED
+ * otherwise.
+ */
+
+import {MiniappRequestType, MiniappStreamType} from "../protocol"
+import {MiniappSession} from "../session"
+import type {LocationData, UnsubscribeFn} from "./events"
+
+export class LocationModule {
+  constructor(private readonly session: MiniappSession) {}
+
+  /** True iff `LOCATION` is declared in the miniapp's manifest. */
+  get hasPermission(): boolean {
+    return this.session._hasManifestPermission("LOCATION")
+  }
+
+  /** Subscribe to continuous location updates. */
+  onUpdate(handler: (data: LocationData) => void): UnsubscribeFn {
+    return this.session._subscribe(MiniappStreamType.LOCATION_UPDATE, handler as (data: unknown) => void)
+  }
+
+  /**
+   * Request a single location fix. Resolves with the next available
+   * reading from the phone. Useful at app load to seed UI before a
+   * continuous stream of updates begins.
+   */
+  getOnce(): Promise<LocationData> {
+    return this.session.sendRequest<LocationData>({
+      type: MiniappRequestType.LOCATION_POLL,
+    })
+  }
+}

package/src/modules/memory.ts

@@ -0,0 +1,224 @@
+/**
+ * @fileoverview MemoryModule — the user's shared, phone-local memory timeline.
+ *
+ * One unified per-hour stream of what happened around the user — spoken
+ * transcript lines AND notes (manual, voice, auto) — plus the hourly summary
+ * that heads each session. The store lives on the phone (host-level,
+ * user-scoped), NOT in the per-miniapp storage namespace: every miniapp that
+ * declares the MEMORY manifest permission reads and writes the same timeline,
+ * and the user manages it in Settings > Memory.
+ *
+ * A "session" is one clock hour that has entries, derived from entry
+ * timestamps at read time — there is no stored session id.
+ *
+ * All calls require the MEMORY manifest permission; without it the host
+ * rejects with PERMISSION_NOT_DECLARED. Nothing here leaves the phone.
+ */
+
+import {MiniappRequestType} from "../protocol"
+import {MiniappSession} from "../session"
+
+export type MemoryEntryKind = "line" | "note"
+/** How a note entry originated (only meaningful when kind === "note"). */
+export type MemoryNoteSource = "voice" | "ui" | "auto"
+
+export interface MemoryEntry {
+  id: string
+  kind: MemoryEntryKind
+  text: string
+  /** Epoch ms the entry happened. */
+  at: number
+  speakerId: string | null
+  /** Enrolled-speaker display name resolved by on-device speaker ID, when known. */
+  resolvedSpeakerName?: string | null
+  language: string | null
+  /** Present for note entries. */
+  source?: MemoryNoteSource
+}
+
+export interface MemorySummary {
+  /** Epoch ms of the hour bucket start. */
+  hourStart: number
+  text: string
+  createdAt: number
+}
+
+/** One derived session: a clock hour with its entries and summary. */
+export interface MemorySession {
+  hourStart: number
+  entries: MemoryEntry[]
+  summary: string | null
+  lineCount: number
+  noteCount: number
+}
+
+export interface MemoryQuery {
+  /** Epoch ms lower bound (inclusive). Omit for "from the beginning". */
+  sinceMs?: number
+  /** Epoch ms upper bound (inclusive). Omit for "until now". */
+  untilMs?: number
+  /** Case-insensitive EXACT substring filter (codes, URLs, exact phrases). */
+  contains?: string
+  /**
+   * Fuzzy any-of terms: an entry matches when ANY term matches, and a
+   * multi-word term requires all of its words. Matching tolerates the small
+   * misspellings speech-to-text produces for names ("Korwin" matches
+   * "Corwin"). Host caps at 8 terms. Combined with `contains` as AND.
+   * Ignored by hosts that predate fuzzy search.
+   */
+  terms?: string[]
+  /** Max entries returned (host caps at 200; default 60). Newest kept. */
+  limit?: number
+}
+
+export interface MemorySearchResult {
+  /** Matches in chronological order (newest last). */
+  entries: MemoryEntry[]
+  /**
+   * Entries inside the TIME window before keyword filtering — distinguishes
+   * "keyword matched nothing" from "window empty". Undefined on hosts that
+   * predate fuzzy search.
+   */
+  windowCount?: number
+}
+
+export class MemoryModule {
+  constructor(private readonly session: MiniappSession) {}
+
+  /** True iff this miniapp's manifest declares the MEMORY permission. */
+  get hasPermission(): boolean {
+    return this.session._hasManifestPermission("MEMORY")
+  }
+
+  /** Append a spoken transcript line to the timeline. */
+  async appendLine(input: {
+    text: string
+    speakerId: string | null
+    language: string | null
+    at: number
+  }): Promise<void> {
+    await this.session.sendRequest<void>({
+      type: MiniappRequestType.MEMORY_APPEND_LINE,
+      ...input,
+    })
+  }
+
+  /**
+   * Add a note. `at` targets the hour it belongs to — omit for "now" (the
+   * current session), or pass a timestamp inside a past hour to append to
+   * that session. Notes dedupe on normalized text within the same hour;
+   * resolves null when the note was a duplicate (or empty).
+   */
+  async addNote(text: string, source: MemoryNoteSource = "ui", at?: number): Promise<MemoryEntry | null> {
+    const result = await this.session.sendRequest<{entry: MemoryEntry | null}>({
+      type: MiniappRequestType.MEMORY_ADD_NOTE,
+      text,
+      source,
+      at,
+    })
+    return result?.entry ?? null
+  }
+
+  /** Delete one entry (line or note) by id. Resolves false when unknown. */
+  async removeEntry(id: string): Promise<boolean> {
+    const result = await this.session.sendRequest<{removed: boolean}>({
+      type: MiniappRequestType.MEMORY_REMOVE_ENTRY,
+      id,
+    })
+    return !!result?.removed
+  }
+
+  /** Delete every entry (and summary) in an hour, or a whole day of hours. */
+  async removeScope(scope: "session" | "day", at: number): Promise<void> {
+    await this.session.sendRequest<void>({
+      type: MiniappRequestType.MEMORY_REMOVE_SCOPE,
+      scope,
+      at,
+    })
+  }
+
+  /** All sessions (hours with entries), newest hour first. */
+  async sessions(): Promise<MemorySession[]> {
+    const result = await this.session.sendRequest<{sessions: MemorySession[]}>({
+      type: MiniappRequestType.MEMORY_SESSION_LIST,
+    })
+    return result?.sessions ?? []
+  }
+
+  /**
+   * Query the full timeline by absolute-time window and keyword — the
+   * on-device executor shape for LLM history-search tools. Newest last, so
+   * slicing keeps the most recent matches when the limit bites.
+   */
+  async query(q: MemoryQuery = {}): Promise<MemoryEntry[]> {
+    return (await this.search(q)).entries
+  }
+
+  /**
+   * query() plus search diagnostics ({@link MemorySearchResult.windowCount}).
+   * Same wire request; prefer this from LLM history-search tools so an empty
+   * result can explain WHY it was empty instead of triggering a blind retry.
+   */
+  async search(q: MemoryQuery = {}): Promise<MemorySearchResult> {
+    const result = await this.session.sendRequest<{entries: MemoryEntry[]; windowCount?: number}>({
+      type: MiniappRequestType.MEMORY_QUERY,
+      ...q,
+    })
+    return {
+      entries: result?.entries ?? [],
+      ...(typeof result?.windowCount === "number" ? {windowCount: result.windowCount} : {}),
+    }
+  }
+
+  /** Entries in [sinceMs, untilMs), newest last. Uncapped (unlike query). */
+  async window(sinceMs: number, untilMs?: number): Promise<MemoryEntry[]> {
+    const result = await this.session.sendRequest<{entries: MemoryEntry[]}>({
+      type: MiniappRequestType.MEMORY_WINDOW,
+      sinceMs,
+      untilMs,
+    })
+    return result?.entries ?? []
+  }
+
+  /** Plain-text export of a scope, for the OS share sheet. */
+  async exportText(scope: "session" | "day" | "all", at?: number): Promise<string> {
+    const result = await this.session.sendRequest<{text: string}>({
+      type: MiniappRequestType.MEMORY_EXPORT_TEXT,
+      scope,
+      at,
+    })
+    return result?.text ?? ""
+  }
+
+  /** Upsert the summary heading an hour (keyed by hourStart). */
+  async addSummary(summary: MemorySummary): Promise<void> {
+    await this.session.sendRequest<void>({
+      type: MiniappRequestType.MEMORY_SUMMARY_ADD,
+      ...summary,
+    })
+  }
+
+  /** All hourly summaries, newest hour first. */
+  async summaries(): Promise<MemorySummary[]> {
+    const result = await this.session.sendRequest<{summaries: MemorySummary[]}>({
+      type: MiniappRequestType.MEMORY_SUMMARY_LIST,
+    })
+    return result?.summaries ?? []
+  }
+
+  /** Most recent COMPLETED hour with lines but no summary, or null. */
+  async pendingSummaryHour(nowMs?: number): Promise<number | null> {
+    const result = await this.session.sendRequest<{hourStart: number | null}>({
+      type: MiniappRequestType.MEMORY_PENDING_SUMMARY_HOUR,
+      nowMs,
+    })
+    return result?.hourStart ?? null
+  }
+
+  /** Drop the entire timeline: every entry and every summary. */
+  async clear(): Promise<void> {
+    await this.session.sendRequest<void>({
+      type: MiniappRequestType.MEMORY_CLEAR,
+    })
+  }
+}

package/src/modules/mic.ts

@@ -0,0 +1,103 @@
+/**
+ * @fileoverview MicModule — low-level audio input subscriptions.
+ *
+ * Mirrors cloud SDK v3's MicManager naming. Houses raw audio chunks + VAD;
+ * transcription and translation hoisted to top-level (`session.transcription`
+ * / `session.translation`) in the v3-alignment round so authors don't have to
+ * mentally model "transcription is a microphone thing" — it's just a
+ * top-level domain. This module was called `MicrophoneModule` /
+ * `session.microphone` before that round.
+ *
+ * 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.
+ */
+
+import {MiniappRequestType, MiniappStreamType} from "../protocol"
+import {MiniappSession} from "../session"
+import type {AudioChunkData, UnsubscribeFn, VadData} from "./events"
+
+export class MicModule {
+  /** All active unsubscribe functions for stop() to tear down at once. */
+  private readonly unsubs = new Set<UnsubscribeFn>()
+
+  constructor(private readonly session: MiniappSession) {}
+
+  /**
+   * Subscribe to voice activity detection (VAD) events. `data.status` is
+   * `true` while the user is speaking, `false` when silent.
+   */
+  onVoiceActivity(handler: (data: VadData) => void): UnsubscribeFn {
+    return this.track(this.session._subscribe(MiniappStreamType.VAD, handler as (data: unknown) => void))
+  }
+
+  /**
+   * Subscribe to raw audio chunks. Format depends on the phone's mic mode
+   * (PCM or LC3, base64-encoded).
+   */
+  onAudioChunk(handler: (data: AudioChunkData) => void): UnsubscribeFn {
+    return this.track(this.session._subscribe(MiniappStreamType.AUDIO_CHUNK, handler as (data: unknown) => void))
+  }
+
+  /**
+   * Temporarily override glasses-side voice activity detection (GX8002) for
+   * this miniapp's lifetime. When disabled, mic gating falls back to the
+   * loudness gate only (if it is enabled). The Glassly App's configured value
+   * is restored when this miniapp disconnects.
+   *
+   * Requires `MICROPHONE` in the miniapp manifest.
+   */
+  setVoiceActivityDetectionEnabled(enabled: boolean): Promise<void> {
+    return this.session.sendRequest<void>({
+      type: MiniappRequestType.MIC_SET_VAD_ENABLED,
+      enabled,
+    })
+  }
+
+  /**
+   * Temporarily override the center-mic loudness gate ("Barrier") for this
+   * miniapp's lifetime. It blocks quiet/self-talk audio independent of VAD.
+   * The Glassly App's configured value is restored when this miniapp disconnects.
+   *
+   * Requires `MICROPHONE` in the miniapp manifest.
+   */
+  setLoudnessGateEnabled(enabled: boolean): Promise<void> {
+    return this.session.sendRequest<void>({
+      type: MiniappRequestType.MIC_SET_LOUDNESS_GATE_ENABLED,
+      enabled,
+    })
+  }
+
+  /**
+   * Tear down every subscription this module owns. Useful when a component
+   * is unmounting and wants to free everything at once without tracking
+   * individual unsubscribe functions.
+   */
+  stop(): void {
+    for (const u of this.unsubs) {
+      try {
+        u()
+      } catch {
+        /* ignore */
+      }
+    }
+    this.unsubs.clear()
+  }
+
+  /** True iff `MICROPHONE` is declared in the miniapp's manifest. */
+  get hasPermission(): boolean {
+    return this.session._hasManifestPermission("MICROPHONE")
+  }
+
+  // ------------------------------------------------------------------------
+
+  private track(unsub: UnsubscribeFn): UnsubscribeFn {
+    this.unsubs.add(unsub)
+    return () => {
+      this.unsubs.delete(unsub)
+      unsub()
+    }
+  }
+}