@glassly/miniapp 0.1.0-dev.26

package/src/modules/blob.ts

@@ -0,0 +1,341 @@
+/**
+ * @fileoverview BlobModule — phone-local persistent BINARY storage, keyed and
+ * scoped to (userId, packageName). The binary sibling of `session.storage`:
+ * where storage holds small strings, blob holds arbitrary bytes (PDFs, EPUBs,
+ * audio, video, model files, caches) as files on the phone.
+ *
+ * It deliberately mirrors `session.storage`'s shape — `set` / `get` / `delete` /
+ * `keys` / `has` / `clear` — so it's instantly familiar, plus the things files
+ * (and not strings) need:
+ *   - `setFromUrl(key, url)` — the host downloads a URL straight to disk
+ *     (like the web Cache API's `cache.add`, iOS `URLSession` download task, or
+ *     Android `DownloadManager`). Bytes never cross the bridge.
+ *   - `importFile()` — opens the OS file picker and stores the chosen file.
+ *     Bytes never cross the bridge.
+ *   - `share(key)` — hands the file to the OS share sheet.
+ *   - `createWriteStream` / `createReadStream` — for streaming huge payloads
+ *     (named like Node's `fs.createWriteStream`).
+ *
+ * BACKGROUND-ONLY. Binary doesn't belong in the WebView. A blob's `uri` is a
+ * `file://` path in the app's private storage — fine for `session.speaker.play`,
+ * `blob.share`, or another host capability, but a WebView generally can't load
+ * it directly (route rendering through a host viewer for now).
+ *
+ * Transfer model: the bridge moves JSON strings through a per-miniapp JS engine
+ * (JSC/QuickJS) with a watchdog, so in-JS writes/reads are CHUNKED (≤ ~1 MB raw
+ * per call). Prefer `setFromUrl` / `importFile` when you can — they keep the
+ * bytes entirely host-side.
+ */
+
+import {MiniappRequestType} from "../protocol"
+import {MiniappSession} from "../session"
+import {base64ToBytes, bytesToBase64, toUint8Array} from "./base64"
+
+/** Metadata for one stored blob. `uri` is a `file://` path. */
+export interface BlobMeta {
+  /** The key it's stored under (caller-chosen). */
+  key: string
+  /** Optional display/file name (e.g. the original filename for an import). */
+  name?: string
+  /** MIME type, e.g. "application/pdf". */
+  mimeType: string
+  /** Size on disk in bytes. */
+  bytes: number
+  /** Epoch ms first written. */
+  createdAt: number
+  /** Epoch ms last written. */
+  updatedAt: number
+  /** Content md5 (lowercase hex), computed host-side (skipped for very large blobs). */
+  md5?: string
+  /** `file://` URI. Feed to `session.speaker.play`, `blob.share`, etc. */
+  uri: string
+  /** App-defined metadata persisted with the blob. */
+  meta?: Record<string, string | number | boolean>
+}
+
+export interface BlobSetOptions {
+  /** Default "application/octet-stream". */
+  mimeType?: string
+  name?: string
+  meta?: Record<string, string | number | boolean>
+}
+
+export interface BlobSetFromUrlOptions extends BlobSetOptions {
+  /** Request headers (e.g. an Authorization token) for the download. */
+  headers?: Record<string, string>
+}
+
+export interface BlobImportOptions {
+  /** Key to store under. Default: a generated key. */
+  key?: string
+  /** Restrict the picker to a MIME type, e.g. "application/pdf". */
+  mimeType?: string
+  meta?: Record<string, string | number | boolean>
+}
+
+/** Raw bytes per chunked write. ~1 MB raw → ~1.34 MB base64, under the watchdog. */
+export const BLOB_WRITE_CHUNK_BYTES = 1024 * 1024
+const BLOB_WRITE_CHUNK_B64 = Math.floor(BLOB_WRITE_CHUNK_BYTES / 3) * 4
+/** Max bytes `bytes()` will buffer before throwing — read large blobs as a stream. */
+export const BLOB_READ_ALL_MAX_BYTES = 32 * 1024 * 1024
+
+/**
+ * Streaming writer (`fs.createWriteStream`-like). Call `write`/`writeBase64` as
+ * many times as you like (each is auto-split into bridge-safe chunks), then
+ * `close()` to publish, or `abort()` to discard the partial blob.
+ */
+export class BlobWriter {
+  private settled = false
+
+  constructor(
+    private readonly session: MiniappSession,
+    readonly key: string,
+  ) {}
+
+  /** Append raw bytes. Auto-chunked. */
+  async write(chunk: Uint8Array | ArrayBuffer): Promise<void> {
+    this.assertOpen()
+    const bytes = toUint8Array(chunk)
+    for (let off = 0; off < bytes.length; off += BLOB_WRITE_CHUNK_BYTES) {
+      await this.send(bytesToBase64(bytes.subarray(off, off + BLOB_WRITE_CHUNK_BYTES)))
+    }
+  }
+
+  /** Append already-base64-encoded bytes (e.g. straight from `mic.onAudioChunk`). */
+  async writeBase64(b64: string): Promise<void> {
+    this.assertOpen()
+    // Slice on 4-char boundaries so each chunk is whole base64 groups.
+    for (let off = 0; off < b64.length; off += BLOB_WRITE_CHUNK_B64) {
+      await this.send(b64.slice(off, off + BLOB_WRITE_CHUNK_B64))
+    }
+  }
+
+  /**
+   * Overwrite bytes at a fixed offset within the not-yet-closed blob (a seek
+   * write). Must stay within already-written bytes; does not grow the blob.
+   * Advanced — used e.g. to patch a container header on finalize.
+   */
+  async writeAt(offset: number, chunk: Uint8Array | ArrayBuffer): Promise<void> {
+    this.assertOpen()
+    await this.session.sendRequest<{bytesWritten: number}>({
+      type: MiniappRequestType.BLOB_WRITE,
+      key: this.key,
+      offset,
+      base64: bytesToBase64(toUint8Array(chunk)),
+    })
+  }
+
+  /** Finalize and return the blob's metadata. Optional `meta` merges into the record. */
+  async close(meta?: Record<string, string | number | boolean>): Promise<BlobMeta> {
+    this.assertOpen()
+    this.settled = true
+    return this.session.sendRequest<BlobMeta>({type: MiniappRequestType.BLOB_COMMIT, key: this.key, meta})
+  }
+
+  /** Discard the partial blob. Idempotent. */
+  async abort(): Promise<void> {
+    if (this.settled) return
+    this.settled = true
+    await this.session.sendRequest<void>({type: MiniappRequestType.BLOB_ABORT, key: this.key})
+  }
+
+  private assertOpen(): void {
+    if (this.settled) throw new Error("BlobWriter is already closed/aborted")
+  }
+
+  private send(base64: string): Promise<{bytesWritten: number}> {
+    return this.session.sendRequest<{bytesWritten: number}>({
+      type: MiniappRequestType.BLOB_WRITE,
+      key: this.key,
+      base64,
+    })
+  }
+}
+
+/** Streaming reader (`fs.createReadStream`-like). */
+export class BlobReader {
+  private closed = false
+
+  constructor(
+    private readonly session: MiniappSession,
+    readonly handle: string,
+    readonly meta: BlobMeta,
+  ) {}
+
+  /** Read up to `maxBytes` (default one chunk). `done` is true at end of file. */
+  async read(maxBytes = BLOB_WRITE_CHUNK_BYTES): Promise<{bytes: Uint8Array; done: boolean}> {
+    if (this.closed) throw new Error("BlobReader is closed")
+    const res = await this.session.sendRequest<{base64: string; done: boolean}>({
+      type: MiniappRequestType.BLOB_READ,
+      handle: this.handle,
+      maxBytes,
+    })
+    return {bytes: base64ToBytes(res?.base64 ?? ""), done: !!res?.done}
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) return
+    this.closed = true
+    await this.session.sendRequest<void>({type: MiniappRequestType.BLOB_CLOSE_READ, handle: this.handle})
+  }
+}
+
+export class BlobModule {
+  constructor(private readonly session: MiniappSession) {}
+
+  // ── write ────────────────────────────────────────────────────────────────
+
+  /** Store bytes under `key`. `data` may be a Uint8Array/ArrayBuffer or a base64 string. */
+  async set(key: string, data: Uint8Array | ArrayBuffer | string, opts: BlobSetOptions = {}): Promise<BlobMeta> {
+    const writer = await this.createWriteStream(key, opts)
+    try {
+      if (typeof data === "string") await writer.writeBase64(data)
+      else await writer.write(data)
+      return await writer.close()
+    } catch (err) {
+      await writer.abort().catch(() => {})
+      throw err
+    }
+  }
+
+  /**
+   * Download `url` straight into a blob under `key`, host-side. The bytes never
+   * cross the bridge (like the web Cache API's `cache.add`). `opts.headers` lets
+   * you pass auth. Resolves to the stored blob's metadata.
+   */
+  setFromUrl(key: string, url: string, opts: BlobSetFromUrlOptions = {}): Promise<BlobMeta> {
+    return this.session.sendRequest<BlobMeta>({
+      type: MiniappRequestType.BLOB_SET_FROM_URL,
+      key,
+      url,
+      mimeType: opts.mimeType,
+      name: opts.name,
+      headers: opts.headers,
+      meta: opts.meta,
+    })
+  }
+
+  /**
+   * Open the OS file picker and store the chosen file as a blob, host-side.
+   * Resolves to the blob's metadata, or `null` if the user cancelled.
+   */
+  importFile(opts: BlobImportOptions = {}): Promise<BlobMeta | null> {
+    return this.session.sendRequest<BlobMeta | null>({
+      type: MiniappRequestType.BLOB_IMPORT,
+      key: opts.key,
+      mimeType: opts.mimeType,
+      meta: opts.meta,
+    })
+  }
+
+  /** Open a streaming writer for `key` (for large/streamed payloads). */
+  async createWriteStream(key: string, opts: BlobSetOptions = {}): Promise<BlobWriter> {
+    const res = await this.session.sendRequest<{key: string}>({
+      type: MiniappRequestType.BLOB_CREATE,
+      key,
+      mimeType: opts.mimeType,
+      name: opts.name,
+      meta: opts.meta,
+    })
+    return new BlobWriter(this.session, res.key)
+  }
+
+  // ── read ─────────────────────────────────────────────────────────────────
+
+  /** Metadata (incl. the `file://` uri) for `key`, or null if absent. */
+  get(key: string): Promise<BlobMeta | null> {
+    return this.session.sendRequest<BlobMeta | null>({type: MiniappRequestType.BLOB_GET, key})
+  }
+
+  /** Alias of `get` — the file-stat verb. */
+  stat(key: string): Promise<BlobMeta | null> {
+    return this.get(key)
+  }
+
+  /** True iff a blob is stored under `key`. */
+  async has(key: string): Promise<boolean> {
+    return (await this.get(key)) !== null
+  }
+
+  /** Every key this miniapp has stored, newest first. */
+  async keys(): Promise<string[]> {
+    return (await this.list()).map((m) => m.key)
+  }
+
+  /** Every blob this miniapp owns, newest first. */
+  async list(): Promise<BlobMeta[]> {
+    const res = await this.session.sendRequest<{blobs: BlobMeta[]}>({type: MiniappRequestType.BLOB_LIST})
+    return res?.blobs ?? []
+  }
+
+  /** Open a streaming reader. Prefer `get(key).uri` when you just need to play/share it. */
+  async createReadStream(key: string): Promise<BlobReader> {
+    const res = await this.session.sendRequest<{handle: string; meta: BlobMeta}>({
+      type: MiniappRequestType.BLOB_OPEN_READ,
+      key,
+    })
+    return new BlobReader(this.session, res.handle, res.meta)
+  }
+
+  /** Read a whole blob into memory as bytes, or null if absent. Throws past the cap — stream big ones. */
+  async bytes(key: string): Promise<Uint8Array | null> {
+    let reader: BlobReader
+    try {
+      reader = await this.createReadStream(key)
+    } catch {
+      return null
+    }
+    const parts: Uint8Array[] = []
+    let total = 0
+    try {
+      for (;;) {
+        const {bytes, done} = await reader.read()
+        if (bytes.length) {
+          total += bytes.length
+          if (total > BLOB_READ_ALL_MAX_BYTES) {
+            throw new Error(`Blob "${key}" exceeds the in-memory read cap — stream it with createReadStream()`)
+          }
+          parts.push(bytes)
+        }
+        if (done) break
+      }
+    } finally {
+      await reader.close().catch(() => {})
+    }
+    const out = new Uint8Array(total)
+    let at = 0
+    for (const p of parts) {
+      out.set(p, at)
+      at += p.length
+    }
+    return out
+  }
+
+  // ── manage ───────────────────────────────────────────────────────────────
+
+  /** Per-app usage + the quota ceiling, in bytes. */
+  usage(): Promise<{bytes: number; count: number; quotaBytes: number}> {
+    return this.session.sendRequest<{bytes: number; count: number; quotaBytes: number}>({
+      type: MiniappRequestType.BLOB_USAGE,
+    })
+  }
+
+  /** Delete the blob under `key`. No-op if absent. */
+  async delete(key: string): Promise<void> {
+    await this.session.sendRequest<void>({type: MiniappRequestType.BLOB_DELETE, key})
+  }
+
+  /** Delete every blob this miniapp owns. */
+  async clear(): Promise<void> {
+    await this.session.sendRequest<void>({type: MiniappRequestType.BLOB_CLEAR})
+  }
+
+  /** Share the blob via the OS share sheet (host shares from disk — no bytes cross the bridge). */
+  async share(key: string): Promise<{success: boolean; cancelled?: boolean}> {
+    const res = await this.session.sendRequest<{success: boolean; cancelled?: boolean}>({
+      type: MiniappRequestType.BLOB_SHARE,
+      key,
+    })
+    return res ?? {success: false}
+  }
+}

package/src/modules/camera.ts

@@ -0,0 +1,258 @@
+/**
+ * @fileoverview CameraModule — glasses camera control and photo capture.
+ */
+
+import {MiniappRequestType} from "../protocol"
+import {MiniappSession} from "../session"
+
+export type CameraRoiPosition = "center" | "bottom" | "top"
+export type CameraFovPreset = "narrow" | "standard" | "wide"
+
+export type CameraFovRequest =
+  | {
+      /** Horizontal FOV, degrees. */
+      fov: number
+      /** Crop/region position: center, bottom, or top. Defaults to center. */
+      roiPosition?: CameraRoiPosition
+    }
+  | {
+      /** Named FOV preset. Presets use center ROI. */
+      preset: CameraFovPreset
+    }
+
+export type SetCameraFovOptions = CameraFovRequest
+
+export interface CameraFovResult {
+  requestId: string
+  fov: number
+  roiPosition: CameraRoiPosition
+  timestamp: number
+}
+
+export interface TakePhotoOptions {
+  size?: "low" | "medium" | "high" | "max"
+  /** Capture at maximum source quality and optimize BLE delivery for readable text. */
+  mode?: "photo" | "text"
+  /**
+   * Image delivery path. `auto` tries direct Wi-Fi upload and falls back to
+   * BLE; `direct` disables BLE fallback; `ble` always relays through the phone.
+   */
+  transferMethod?: "auto" | "direct" | "ble"
+  compress?: "none" | "low" | "medium" | "high"
+  sound?: boolean
+  saveToGallery?: boolean
+  /**
+   * Manual shutter / exposure time in nanoseconds. Omit (or pass undefined)
+   * to let the glasses auto-expose. Honored only on cameras that support
+   * manual exposure; ignored otherwise.
+   */
+  exposureTimeNs?: number
+  /** Sensor ISO for this capture only. Only used when `exposureTimeNs` enables manual exposure. */
+  iso?: number | null
+  /** After AE convergence, divide the metered exposure by this factor (scan mode). */
+  aeExposureDivisor?: number
+  /** Cap ISO after AE metering (scan mode). */
+  isoCap?: number
+  /** Request per-capture noise reduction. Sent on the wire; glasses may log `not_implemented`. */
+  noiseReduction?: boolean
+  /** Request per-capture edge enhancement. Sent on the wire; glasses may log `not_implemented`. */
+  edgeEnhancement?: boolean
+  /**
+   * ZSL buffering. Manual and scan stills force it off because fixed sensor controls take priority.
+   */
+  zsl?: boolean
+  /**
+   * MFNR still capture. Manual and scan stills force it off because fixed sensor controls take priority.
+   */
+  mfnr?: boolean
+  /** ISP digital gain hint. */
+  ispDigitalGain?: number
+  /** ISP analog gain hint. */
+  ispAnalogGain?: string
+  /**
+   * Override the SDK's default 60s request timeout for this capture only.
+   * Leave unset for a normal user-triggered capture (the full 60s ceiling is
+   * appropriate there). Callers that speculatively fire a capture and may
+   * abandon it if the result isn't needed (e.g. a short-lived non-visual
+   * assistant turn racing a capture against a ~1s latency cap) should pass a
+   * short value here so the abandoned `takePhoto()` promise settles quickly
+   * instead of sitting on the default 60s ceiling.
+   */
+  timeoutMs?: number
+}
+
+export interface PhotoTaken {
+  /** Request id that correlates ASG status, upload, and phone/cloud logs. */
+  requestId: string
+  photoUrl: string
+  mimeType: string
+  size: number
+}
+
+export interface WarmUpCameraOptions {
+  size?: "low" | "medium" | "high" | "max"
+  /** Match the upcoming capture mode so warm-up and capture share one ASG camera session. */
+  mode?: "photo" | "text"
+  exposureTimeNs?: number
+  /** Ready-state hold in milliseconds. Defaults to 15 seconds and is capped at 60 seconds. */
+  durationMs?: number
+  /** ZSL preview buffering for the warm-up session. */
+  zsl?: boolean
+  /** MFNR still capture for the warm-up session. */
+  mfnr?: boolean
+}
+
+export interface StartVideoRecordingOptions {
+  /** Video width in pixels. Omit to use the device's saved button-video default. */
+  width?: number
+  /** Video height in pixels. Omit to use the device's saved button-video default. */
+  height?: number
+  /**
+   * Frames per second. Lower frame rates keep the glasses cooler and produce
+   * smaller files — useful for long recordings where smooth motion isn't needed.
+   * Omit to use the device default.
+   */
+  fps?: number
+  /** Play start/stop capture sounds. Defaults to true. */
+  sound?: boolean
+  /** Keep the recording on the glasses after it finishes. Defaults to false. */
+  save?: boolean
+}
+
+export interface VideoRecordingStarted {
+  /** Identifier for this recording session; pass to {@link stopVideoRecording}. */
+  recordingId: string
+}
+
+export interface StopVideoRecordingOptions {
+  /**
+   * Upload the finished recording to this URL with a multipart POST (the file is
+   * the `video` part). The glasses upload it directly. Omit to keep the recording
+   * on the glasses instead.
+   */
+  uploadUrl?: string
+  /** Bearer token sent as the `Authorization` header on the upload, if your endpoint needs one. */
+  uploadAuthToken?: string
+}
+
+export class CameraModule {
+  constructor(private readonly session: MiniappSession) {}
+
+  /** True iff `CAMERA` is declared in the miniapp's manifest. */
+  get hasPermission(): boolean {
+    return this.session._hasManifestPermission("CAMERA")
+  }
+
+  /**
+   * Apply a session-owned camera FOV/ROI override on the glasses.
+   *
+   * Resolves after the ASG client reports that the setting was applied to camera
+   * hardware after the restart cooldown. The host restores the prior override or persistent base
+   * when this miniapp closes. Requires CAMERA permission declared in miniapp.json.
+   */
+  async setFov(request: CameraFovRequest): Promise<CameraFovResult> {
+    return this.session.sendRequest<CameraFovResult>({
+      type: MiniappRequestType.CAMERA_FOV,
+      ...request,
+    })
+  }
+
+  /**
+   * Take a photo via the glasses camera. Returns a URL to the captured image.
+   * Requires CAMERA permission declared in miniapp.json.
+   *
+   * The photo is uploaded to cloud storage; the returned URL is a short-TTL
+   * (~30 minute) signed download URL. If the glasses don't have a camera,
+   * the phone-side handler rejects with an error. Check
+   * `session.capabilities.hasCamera` before calling.
+   */
+  async takePhoto(options: TakePhotoOptions = {}): Promise<PhotoTaken> {
+    return this.session.sendRequest<PhotoTaken>(
+      {
+        type: MiniappRequestType.PHOTO,
+        size: options.size ?? "medium",
+        mode: options.mode ?? "photo",
+        ...(options.transferMethod !== undefined ? {transferMethod: options.transferMethod} : {}),
+        compress: options.compress ?? "none",
+        sound: options.sound ?? true,
+        saveToGallery: options.saveToGallery ?? false,
+        exposureTimeNs: options.exposureTimeNs,
+        iso: options.iso,
+        aeExposureDivisor: options.aeExposureDivisor,
+        isoCap: options.isoCap,
+        noiseReduction: options.noiseReduction,
+        edgeEnhancement: options.edgeEnhancement,
+        zsl: options.zsl,
+        mfnr: options.mfnr,
+        ispDigitalGain: options.ispDigitalGain,
+        ispAnalogGain: options.ispAnalogGain,
+      },
+      options.timeoutMs != null ? {timeoutMs: options.timeoutMs} : undefined,
+    )
+  }
+
+  /**
+   * Pre-warm the glasses camera so the next takePhoto() is near-instant.
+   * The camera stays warm for ~durationMs (default 15s, maximum 60s); call warmUp() again to
+   * extend it. Warm with the same `size` you'll capture with — a mismatched size
+   * forces the camera to reconfigure and loses the speedup. Requires CAMERA
+   * permission in miniapp.json. Resolves once the camera reports ready. The host automatically
+   * releases this miniapp's request-owned lease when the miniapp closes.
+   *
+   * Warm-ups are serialized: only one runs at a time and none may start while a
+   * photo is being captured. If the camera is busy (a capture is in flight, or
+   * another warm-up is still opening) this rejects with `camera_busy` — retry
+   * shortly, or just call takePhoto() (it works regardless, only slower). The
+   * normal warmUp() → takePhoto() sequence never hits this.
+   */
+  async warmUp(options: WarmUpCameraOptions = {}): Promise<void> {
+    await this.session.sendRequest<void>({
+      type: MiniappRequestType.CAMERA_WARM_UP,
+      size: options.size ?? "medium",
+      mode: options.mode ?? "photo",
+      exposureTimeNs: options.exposureTimeNs,
+      durationMs: options.durationMs ?? 15000,
+      zsl: options.zsl,
+      mfnr: options.mfnr,
+    })
+  }
+
+  /**
+   * Start recording video on the glasses camera. Returns a `recordingId` to pass
+   * to {@link stopVideoRecording} after the glasses report that recording
+   * started. Requires CAMERA permission declared in miniapp.json. Check
+   * `session.capabilities.hasCamera` before calling.
+   *
+   * Resolution and frame rate are optional — omit them to use the device's saved
+   * button-video settings. Lowering `fps` (e.g. to 5) keeps the glasses cooler
+   * during long recordings.
+   */
+  async startVideoRecording(options: StartVideoRecordingOptions = {}): Promise<VideoRecordingStarted> {
+    return this.session.sendRequest<VideoRecordingStarted>({
+      type: MiniappRequestType.VIDEO_RECORDING_START,
+      width: options.width,
+      height: options.height,
+      fps: options.fps,
+      sound: options.sound ?? true,
+      save: options.save ?? false,
+    })
+  }
+
+  /**
+   * Stop an in-progress video recording started with {@link startVideoRecording}.
+   *
+   * By default the recording stays on the glasses. Pass `uploadUrl` to have the
+   * glasses upload the finished clip to your own endpoint.
+   *
+   * @param recordingId The id returned from `startVideoRecording`.
+   * @param options     Optional upload destination for the finished recording.
+   */
+  async stopVideoRecording(recordingId: string, options: StopVideoRecordingOptions = {}): Promise<void> {
+    await this.session.sendRequest<void>({
+      type: MiniappRequestType.VIDEO_RECORDING_STOP,
+      recordingId,
+      uploadUrl: options.uploadUrl,
+      uploadAuthToken: options.uploadAuthToken,
+    })
+  }
+}

package/src/modules/cloud.ts

@@ -0,0 +1,94 @@
+/**
+ * @fileoverview CloudModule — local miniapp view of the phone-owned cloud client.
+ *
+ * Miniapps do not own or configure the cloud connection. The phone owns one
+ * cloud-client instance and pushes status snapshots here so miniapps can render
+ * honest UX such as online/offline captions indicators.
+ */
+
+import {EventEmitter} from "eventemitter3"
+
+import {MiniappSession} from "../session"
+import type {UnsubscribeFn} from "./events"
+
+export type CloudClientConnectionStatus = "connected" | "connecting" | "reconnecting" | "disconnected"
+export type CloudClientAudioTransport = "udp" | "ws" | "offline" | "none"
+
+export interface CloudClientStatus {
+  status: CloudClientConnectionStatus
+  audioTransport: CloudClientAudioTransport
+}
+
+type CloudEmitterEvents = {
+  status: (status: CloudClientStatus) => void
+}
+
+export const CLOUD_STATUS_STREAM = "_cloud_status"
+
+const DEFAULT_STATUS: CloudClientStatus = {
+  status: "disconnected",
+  audioTransport: "none",
+}
+
+function normalizeCloudStatus(data: unknown): CloudClientStatus | null {
+  if (!data || typeof data !== "object") return null
+  const raw = data as Record<string, unknown>
+  const status = raw.status
+  const audioTransport = raw.audioTransport
+
+  if (status !== "connected" && status !== "connecting" && status !== "reconnecting" && status !== "disconnected") {
+    return null
+  }
+  if (
+    audioTransport !== "udp" &&
+    audioTransport !== "ws" &&
+    audioTransport !== "offline" &&
+    audioTransport !== "none"
+  ) {
+    return null
+  }
+
+  return {status, audioTransport}
+}
+
+export class CloudModule {
+  private readonly emitter = new EventEmitter<CloudEmitterEvents>()
+  private current: CloudClientStatus = {...DEFAULT_STATUS}
+
+  constructor(private readonly session: MiniappSession) {
+    this.session._subscribe(CLOUD_STATUS_STREAM, (data) => {
+      const next = normalizeCloudStatus(data)
+      if (!next) return
+      if (next.status === this.current.status && next.audioTransport === this.current.audioTransport) return
+      this.current = next
+      this.emitter.emit("status", {...this.current})
+    })
+  }
+
+  /** Latest status snapshot pushed by the phone runtime. */
+  get status(): CloudClientStatus {
+    return {...this.current}
+  }
+
+  /** True when the phone's cloud-client runtime handshake is complete. */
+  get connected(): boolean {
+    return this.current.status === "connected"
+  }
+
+  /** Method alias for callers who prefer function-style state reads. */
+  isConnected(): boolean {
+    return this.connected
+  }
+
+  /**
+   * Subscribe to cloud-client status updates. The current value is delivered
+   * immediately so UI code can hydrate without waiting for the next transition.
+   */
+  onStatusChanged(handler: (status: CloudClientStatus) => void): UnsubscribeFn {
+    handler({...this.current})
+    this.emitter.on("status", handler)
+    return () => {
+      this.emitter.off("status", handler)
+    }
+  }
+}