@mentra/miniapp 0.3.0-dev.0

package/src/sub-path-types.test-d.ts

@@ -0,0 +1,49 @@
+/**
+ * Compile-time test for the two-layer SDK split.
+ *
+ * The package exports two sub-paths with distinct type-roots:
+ *   - `@mentra/miniapp/background` exposes `MiniappSession` + module
+ *     types; it does NOT declare the `mentra` global.
+ *   - `@mentra/miniapp/ui` exposes the `MentraUiGlobal` / `MentraTyped`
+ *     types + React adapters. It deliberately does NOT declare a
+ *     `var mentra` on `globalThis` — that would lock every consumer
+ *     into the SDK's default `Record<string, unknown>` channel shape
+ *     and break per-miniapp `Channels` registries via TS's `var`
+ *     declaration-merging rules. Each miniapp declares its own typed
+ *     `var mentra: MentraTyped<MyChannels>` in `shared/channels.ts`.
+ *
+ * Wrong-layer imports should be caught at compile time. This file is
+ * type-only (`.test-d.ts`) — no runtime assertions. `bun typecheck` /
+ * `bun x tsc -p tsconfig.json` is the executor.
+ *
+ * NOTE: this file lives inside `src/` so it ships with the package and
+ * downstream consumers' typechecks would also catch a regression. The
+ * `@ts-expect-error` lines fail the build if the named symbol *does*
+ * become reachable on the wrong path, which is the contract we want.
+ */
+
+// ----- @mentra/miniapp/background ---------------------------------------
+import type {MiniappSession} from "./background/index"
+
+// ✅ MiniappSession is reachable from the background entry.
+const _bg: MiniappSession | undefined = undefined
+void _bg
+
+// ----- @mentra/miniapp/ui -----------------------------------------------
+import type {MentraUiGlobal, MentraTyped} from "./ui/index"
+
+// ✅ MentraUiGlobal is reachable from the ui entry.
+const _ui: MentraUiGlobal | undefined = undefined
+void _ui
+
+// ✅ MentraTyped<TChannels> is the canonical way to type the global.
+//    Consumers do `declare global { var mentra: MentraTyped<Channels> }`
+//    inside their own code; the SDK no longer ships the declaration.
+export type _Typed = MentraTyped<{foo: number}>
+
+// ----- compile-time guardrails ------------------------------------------
+// (TypeScript doesn't ship a `// @ts-expect-no-error` mirror, so we just
+// rely on the named imports above failing if the corresponding files
+// disappear. The asymmetric exports are enforced by package.json's
+// `exports` map at consumer time; this file proves the source files
+// expose what they should.)

package/src/transport/auto.ts

@@ -0,0 +1,143 @@
+/**
+ * @fileoverview Auto-detect the right Transport based on environment.
+ */
+
+import {DispatchTransport} from "./dispatch"
+import {LocalSocketTransport, LocalSocketTransportOptions} from "./local-socket"
+import {MockTransport, isMockExplicitlyRequested} from "./mock"
+import {PostMessageTransport} from "./postmessage"
+import {Transport, TransportDisconnectHandler, TransportMessageHandler} from "./types"
+
+const LOCAL_SOCKET_OPEN_TIMEOUT_MS = 500
+
+export interface CreateTransportOptions {
+  /** Force a specific transport. Skip auto-detection. */
+  transport?: Transport
+  /** For LocalSocketTransport fallback — override the ws URL. */
+  localSocketUrl?: string
+}
+
+/**
+ * Return a Transport appropriate for the current environment.
+ *
+ * Detection order (first match wins):
+ *
+ * 1. **DispatchTransport** — when running in a per-miniapp JSContext
+ *    (no DOM, but `__dispatch` is installed on `globalThis` by the
+ *    MentraJS runtime). This is the production path.
+ * 2. **PostMessageTransport** — inside a MentraOS 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 `?mentra=mock` or
+ *    `localStorage.MENTRA_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.
+ * 5. **MockTransport** — no `WebSocket` at all (some embedded contexts,
+ *    jsdom without a polyfill). Keeps the SDK from throwing.
+ *
+ * DispatchTransport is checked FIRST because the JSContext doesn't have
+ * a `window` global, so it'd otherwise fall through to LocalSocket and
+ * race a non-existent dev WebSocket — annoying and confusing in logs.
+ */
+export function createTransport(options: CreateTransportOptions = {}): Transport {
+  if (options.transport) return options.transport
+
+  // 1) JSContext background world — single check for the native bridge.
+  if (DispatchTransport.isAvailable()) {
+    return new DispatchTransport()
+  }
+
+  if (typeof window !== "undefined" && window.ReactNativeWebView) {
+    return new PostMessageTransport()
+  }
+
+  // Explicit opt-in to mock — useful for stories / framework-level testing.
+  if (isMockExplicitlyRequested()) {
+    return new MockTransport()
+  }
+
+  if (typeof WebSocket !== "undefined") {
+    const localSocketOptions: LocalSocketTransportOptions = {}
+    if (options.localSocketUrl) localSocketOptions.url = options.localSocketUrl
+    return new LocalSocketWithMockFallback(localSocketOptions)
+  }
+
+  // No WebSocket at all (some embedded contexts, jsdom without a polyfill).
+  // MockTransport keeps the SDK from throwing during construction.
+  return new MockTransport()
+}
+
+/**
+ * Internal wrapper transport: tries LocalSocketTransport first; if open() hasn't
+ * resolved within LOCAL_SOCKET_OPEN_TIMEOUT_MS, swaps in MockTransport so a
+ * miniapp opened in a regular browser tab gets a synthetic CONNECT_ACK instead
+ * of a 10-second hang while the SDK's CONNECT_ACK timeout expires.
+ *
+ * Once a delegate is selected, all subsequent calls forward to it.
+ */
+class LocalSocketWithMockFallback implements Transport {
+  private active: Transport | null = null
+  private messageHandler: TransportMessageHandler | null = null
+  private disconnectHandler: TransportDisconnectHandler | null = null
+
+  constructor(private readonly options: LocalSocketTransportOptions) {}
+
+  async open(): Promise<void> {
+    const local = new LocalSocketTransport(this.options)
+    let timedOut = false
+    const timeout = new Promise<void>((_, reject) => {
+      setTimeout(() => {
+        timedOut = true
+        reject(new Error("LocalSocketTransport open timed out"))
+      }, LOCAL_SOCKET_OPEN_TIMEOUT_MS)
+    })
+
+    try {
+      await Promise.race([local.open(), timeout])
+      // LocalSocket succeeded.
+      this.active = local
+    } catch {
+      try {
+        local.close()
+      } catch {
+        /* ignore */
+      }
+      const mock = new MockTransport()
+      await mock.open()
+      this.active = mock
+      // eslint-disable-next-line no-console
+      console.log(
+        timedOut
+          ? "[mentra-miniapp] No phone WebSocket reachable; using MockTransport so the page can render."
+          : "[mentra-miniapp] LocalSocketTransport failed; using MockTransport.",
+      )
+    }
+
+    if (this.messageHandler) this.active.onMessage(this.messageHandler)
+    if (this.disconnectHandler) this.active.onDisconnect(this.disconnectHandler)
+  }
+
+  send(raw: string): void {
+    if (!this.active) throw new Error("LocalSocketWithMockFallback: send() before open()")
+    this.active.send(raw)
+  }
+
+  onMessage(handler: TransportMessageHandler): void {
+    this.messageHandler = handler
+    this.active?.onMessage(handler)
+  }
+
+  onDisconnect(handler: TransportDisconnectHandler): void {
+    this.disconnectHandler = handler
+    this.active?.onDisconnect(handler)
+  }
+
+  close(): void {
+    this.active?.close()
+  }
+
+  isOpen(): boolean {
+    return this.active?.isOpen() === true
+  }
+}

package/src/transport/dispatch.ts

@@ -0,0 +1,106 @@
+/**
+ * @fileoverview DispatchTransport — Transport implementation that rides
+ * the native `__dispatch(iface, method, argsJson)` bridge exposed by the
+ * MentraJS runtime (per-miniapp JSContext on iOS-JSC, Zipline/QuickJS
+ * context on Android).
+ *
+ * The existing `MiniappSession` (session.ts) is transport-agnostic — it
+ * serialises envelopes into JSON strings and hands them to Transport.send().
+ * The native side has historically been on the other end of a
+ * `window.ReactNativeWebView.postMessage(...)` shim (PostMessageTransport)
+ * inside a WebView. In the new architecture, background JS runs in a
+ * JSContext that has no WebView — so the wire is `__dispatch` instead.
+ *
+ * What this transport does:
+ *   - send(raw) — calls __dispatch("__bridge", "send", [raw]). The host
+ *     side `MentraJSRouter` consumes the raw string verbatim, same shape
+ *     as PostMessageTransport's wire payload.
+ *   - The polyfill bundle (`startup.ts`) wires __deliver({kind:'bridge',raw})
+ *     back into this transport's message handler so the host can push
+ *     unsolicited events (mic_pcm, transcription, button events, etc.)
+ *     into the SDK.
+ *   - open()/close() are no-ops — the JSContext is alive as long as the
+ *     host has the runtime spawned; nothing to handshake here.
+ *
+ * On Android Zipline `__dispatch` is suspending under the hood; on
+ * iOS-JSC it's a synchronous Swift block. Both shapes are JSON-string in,
+ * JSON-string out, so the JS-side surface is identical.
+ */
+
+import {Transport, TransportDisconnectHandler, TransportMessageHandler} from "./types"
+
+/**
+ * Shape of the deliver envelope used by background code to surface
+ * RN-originated transport messages back to the SDK. The polyfill bundle
+ * fans these into __mentraDeliverBridgeRaw.
+ */
+interface BridgeDeliverGlobal {
+  __mentraDeliverBridgeRaw?: (raw: string) => void
+  __dispatch?: (iface: string, method: string, argsJson: string) => string | null
+}
+
+export class DispatchTransport implements Transport {
+  private messageHandler: TransportMessageHandler | null = null
+  private disconnectHandler: TransportDisconnectHandler | null = null
+  private open_ = false
+
+  /** True iff `__dispatch` is bound on the current globalThis. */
+  static isAvailable(): boolean {
+    return typeof (globalThis as unknown as BridgeDeliverGlobal).__dispatch === "function"
+  }
+
+  async open(): Promise<void> {
+    if (!DispatchTransport.isAvailable()) {
+      throw new Error("DispatchTransport: __dispatch is not installed on globalThis")
+    }
+    // Wire up the inbound delivery hook so the polyfill's __deliver can
+    // route bridge frames here. Installed lazily so multiple transports
+    // can share the same global if a test spins up two.
+    const g = globalThis as unknown as BridgeDeliverGlobal
+    g.__mentraDeliverBridgeRaw = (raw: string) => {
+      if (this.messageHandler) this.messageHandler(raw)
+    }
+    this.open_ = true
+  }
+
+  send(raw: string): void {
+    if (!this.open_) {
+      throw new Error("DispatchTransport: send() before open()")
+    }
+    const g = globalThis as unknown as BridgeDeliverGlobal
+    if (typeof g.__dispatch !== "function") {
+      // Native bridge gone — surface as a transport-level disconnect so
+      // upstream callers don't hang on pending requests.
+      this.open_ = false
+      this.disconnectHandler?.("DispatchTransport: __dispatch disappeared")
+      return
+    }
+    // Wire format: stringify the args array as a single-element array
+    // containing the raw envelope. The router unwraps it.
+    try {
+      g.__dispatch("__bridge", "send", JSON.stringify([raw]))
+    } catch (e) {
+      this.disconnectHandler?.(`DispatchTransport: __dispatch threw: ${String(e)}`)
+    }
+  }
+
+  onMessage(handler: TransportMessageHandler): void {
+    this.messageHandler = handler
+  }
+
+  onDisconnect(handler: TransportDisconnectHandler): void {
+    this.disconnectHandler = handler
+  }
+
+  close(): void {
+    this.open_ = false
+    const g = globalThis as unknown as BridgeDeliverGlobal
+    if (g.__mentraDeliverBridgeRaw) {
+      delete g.__mentraDeliverBridgeRaw
+    }
+  }
+
+  isOpen(): boolean {
+    return this.open_
+  }
+}

package/src/transport/local-socket.ts

@@ -0,0 +1,93 @@
+/**
+ * @fileoverview LocalSocket transport — browser fallback.
+ *
+ * When the miniapp runs in an external browser (Safari/Chrome, not inside the
+ * MentraOS React Native WebView), it connects to a localhost WebSocket that
+ * MentraOS exposes via MiniSockets.
+ *
+ * Default endpoint: ws://127.0.0.1:8765. Override via the `url` option for
+ * dev / testing.
+ */
+
+import {Transport, TransportDisconnectHandler, TransportMessageHandler} from "./types"
+
+export interface LocalSocketTransportOptions {
+  url?: string
+}
+
+const DEFAULT_URL = "ws://127.0.0.1:8765"
+
+export class LocalSocketTransport implements Transport {
+  private url: string
+  private ws: WebSocket | null = null
+  private messageHandler: TransportMessageHandler | null = null
+  private disconnectHandler: TransportDisconnectHandler | null = null
+
+  constructor(options: LocalSocketTransportOptions = {}) {
+    this.url = options.url ?? DEFAULT_URL
+  }
+
+  async open(): Promise<void> {
+    if (this.ws && this.ws.readyState === WebSocket.OPEN) return
+    if (typeof WebSocket === "undefined") {
+      throw new Error("LocalSocketTransport: browser WebSocket global not available")
+    }
+
+    await new Promise<void>((resolve, reject) => {
+      const ws = new WebSocket(this.url)
+      let settled = false
+      const settle = (fn: () => void) => {
+        if (settled) return
+        settled = true
+        fn()
+      }
+
+      ws.onopen = () => {
+        this.ws = ws
+        settle(() => resolve())
+      }
+      ws.onerror = (ev) => {
+        settle(() =>
+          reject(new Error(`LocalSocketTransport: failed to connect to ${this.url}: ${String(ev)}`)),
+        )
+      }
+      ws.onmessage = (ev: MessageEvent) => {
+        const data = ev.data
+        if (typeof data === "string") this.messageHandler?.(data)
+      }
+      ws.onclose = (ev) => {
+        if (this.ws === ws) this.ws = null
+        this.disconnectHandler?.(`closed: ${ev.code} ${ev.reason}`)
+      }
+    })
+  }
+
+  send(raw: string): void {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      throw new Error("LocalSocketTransport: not connected")
+    }
+    this.ws.send(raw)
+  }
+
+  onMessage(handler: TransportMessageHandler): void {
+    this.messageHandler = handler
+  }
+
+  onDisconnect(handler: TransportDisconnectHandler): void {
+    this.disconnectHandler = handler
+  }
+
+  close(): void {
+    if (!this.ws) return
+    try {
+      this.ws.close()
+    } catch {
+      // ignore
+    }
+    this.ws = null
+  }
+
+  isOpen(): boolean {
+    return !!this.ws && this.ws.readyState === WebSocket.OPEN
+  }
+}

package/src/transport/mock.ts

@@ -0,0 +1,248 @@
+/**
+ * @fileoverview MockTransport — browser-tab fallback so the SDK doesn't hang.
+ *
+ * Activates when:
+ *   - `window.ReactNativeWebView` is undefined (not in MentraOS WebView), AND
+ *   - The first LocalSocketTransport connection attempt fails fast, OR
+ *   - The author opts in via `?mentra=mock` query param / `localStorage.MENTRA_MOCK = "1"`.
+ *
+ * Behaviors:
+ *   - On `open()`: synthesize a CONNECT_ACK envelope so `session.connect()` resolves.
+ *   - On `send(envelope)`: parse, log to console with `[mock-transport]` prefix,
+ *     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.
+ * The full simulator (event injection, glasses-display preview, hardware bridge)
+ * is Stage 2 — see `agents/miniapp-browser-testing-simulator-spec.md`.
+ */
+
+import {parseEnvelope, serializeEnvelope, type MiniappEnvelope} from "../envelope"
+import {MiniappRequestType, MiniappResponseType} from "../protocol"
+import type {Transport, TransportDisconnectHandler, TransportMessageHandler} from "./types"
+
+const LOG_PREFIX = "[mock-transport]"
+
+/**
+ * Returns true if the current environment requested the mock transport
+ * explicitly. Checks `?mentra=mock` query param and `localStorage.MENTRA_MOCK`.
+ */
+export function isMockExplicitlyRequested(): boolean {
+  if (typeof window === "undefined") return false
+  try {
+    if (typeof window.location !== "undefined" && window.location.search) {
+      const params = new URLSearchParams(window.location.search)
+      if (params.get("mentra") === "mock") return true
+    }
+  } catch {
+    // ignore
+  }
+  try {
+    if (typeof localStorage !== "undefined" && localStorage.getItem("MENTRA_MOCK") === "1") {
+      return true
+    }
+  } catch {
+    // localStorage may throw in some embedded contexts; ignore
+  }
+  return false
+}
+
+export interface MockTransportOptions {
+  /** Override the synthetic userId. Default "mock-user". */
+  userId?: string
+  /** Override the synthetic miniapp auth token. Default "mock-miniapp-token". */
+  authToken?: string
+  /** Override the synthetic packageName when window.MentraOS isn't set. */
+  packageName?: string
+  /** Suppress the [mock-transport] console logs. Default false. */
+  silent?: boolean
+}
+
+export class MockTransport implements Transport {
+  private messageHandler: TransportMessageHandler | null = null
+  private disconnectHandler: TransportDisconnectHandler | null = null
+  private open_ = false
+  private readonly userId: string
+  private readonly authToken: string
+  private readonly packageName: string | null
+  private readonly silent: boolean
+
+  constructor(options: MockTransportOptions = {}) {
+    this.userId = options.userId ?? "mock-user"
+    this.authToken = options.authToken ?? "mock-miniapp-token"
+    this.packageName = options.packageName ?? null
+    this.silent = options.silent === true
+  }
+
+  async open(): Promise<void> {
+    if (this.open_) return
+    this.open_ = true
+    this.log("transport opened (no real host; synthetic responses only)")
+  }
+
+  send(raw: string): void {
+    if (!this.open_) {
+      throw new Error("MockTransport: send() before open()")
+    }
+    const envelope = parseEnvelope(raw)
+    if (!envelope) {
+      this.log("dropped unparseable envelope:", raw.slice(0, 200))
+      return
+    }
+    const payload = envelope.payload as {type?: string} & Record<string, unknown>
+    const type = payload?.type
+    this.log(`recv ${type ?? "<unknown>"}${envelope.requestId ? ` (rid=${envelope.requestId})` : ""}`)
+
+    // Handle the protocol's synchronous handshake/responses.
+    switch (type) {
+      case MiniappRequestType.CONNECT:
+        this.deliverConnectAck(payload)
+        return
+
+      case MiniappRequestType.PING:
+        // Real phone sends PING. We never do — but if app code somehow does,
+        // ignore it. The SDK auto-replies to inbound PINGs, not vice versa.
+        return
+
+      case MiniappRequestType.SUBSCRIBE:
+        // Subscribe is fire-and-forget; no response expected. Stage 1 emits no
+        // events. Future Stage 2 simulator can synthesize events here.
+        return
+
+      default:
+        // Anything that has a requestId expects a REQUEST_RESULT. Reply with a
+        // synthetic empty success so app code that awaits the promise resolves.
+        if (envelope.requestId) {
+          this.deliverSyntheticResult(envelope.requestId, type ?? "<unknown>", payload)
+        }
+        return
+    }
+  }
+
+  onMessage(handler: TransportMessageHandler): void {
+    this.messageHandler = handler
+  }
+
+  onDisconnect(handler: TransportDisconnectHandler): void {
+    this.disconnectHandler = handler
+  }
+
+  close(): void {
+    if (!this.open_) return
+    this.open_ = false
+    this.disconnectHandler?.("MockTransport.close()")
+  }
+
+  isOpen(): boolean {
+    return this.open_
+  }
+
+  // ---------------------------------------------------------------------------
+
+  private deliverConnectAck(connectPayload: Record<string, unknown>): void {
+    const incomingPackage = (connectPayload.packageName as string | undefined) ?? this.packageName ?? "com.mock.app"
+    const ackPayload = {
+      type: MiniappResponseType.CONNECT_ACK,
+      userId: this.userId,
+      packageName: incomingPackage,
+      capabilities: null,
+      visibility: "foreground",
+      colorScheme: "light",
+      auth: {
+        mentraUserId: this.userId,
+        oemId: "mock",
+        token: this.authToken,
+        expiresAt: Date.now() + 60 * 60 * 1000,
+      },
+    }
+    const envelope: MiniappEnvelope = {payload: ackPayload}
+    this.log(`-> CONNECT_ACK userId=${this.userId} pkg=${incomingPackage}`)
+    // Deliver asynchronously so it doesn't fire during the same tick as send().
+    queueMicrotask(() => this.messageHandler?.(serializeEnvelope(envelope)))
+  }
+
+  private deliverSyntheticResult(
+    requestId: string,
+    requestType: string,
+    requestPayload: Record<string, unknown>,
+  ): void {
+    const data = syntheticDataFor(requestId, requestType, requestPayload)
+    const responsePayload = {
+      type: MiniappResponseType.REQUEST_RESULT,
+      ok: true,
+      data,
+    }
+    const envelope: MiniappEnvelope = {payload: responsePayload, requestId}
+    this.log(`-> REQUEST_RESULT (rid=${requestId}) synthetic ${requestType}`)
+    queueMicrotask(() => this.messageHandler?.(serializeEnvelope(envelope)))
+  }
+
+  private log(...args: unknown[]): void {
+    if (this.silent) return
+
+    console.log(LOG_PREFIX, ...args)
+  }
+}
+
+/**
+ * Synthetic payload for an unrecognized request that nonetheless awaits a
+ * REQUEST_RESULT. Returns enough shape to satisfy callers without crashing.
+ */
+function syntheticDataFor(requestId: string, requestType: string, requestPayload: Record<string, unknown>): unknown {
+  switch (requestType) {
+    case MiniappRequestType.CAMERA_FOV: {
+      const presetFov =
+        requestPayload.preset === "narrow"
+          ? 82
+          : requestPayload.preset === "wide"
+            ? 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"
+      return {
+        requestId,
+        fov,
+        roiPosition,
+        timestamp: Date.now(),
+      }
+    }
+
+    case MiniappRequestType.PHOTO:
+      // 1×1 transparent PNG so consumers that try to render don't 404.
+      return {
+        photoUrl:
+          "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkAAIAAAoAAv/lxKUAAAAASUVORK5CYII=",
+        requestId: "mock-photo",
+      }
+
+    case MiniappRequestType.RGB_LED:
+      return {type: "rgb_led_control_response", state: "success", requestId}
+
+    case MiniappRequestType.LOCATION_POLL:
+      // San Francisco fallback — using 0,0 puts dev sessions in the
+      // Atlantic, which makes maps/navigation unusable in the WebView.
+      return {lat: 37.7956, lng: -122.3933, accuracy: 0, timestamp: Date.now()}
+
+    case MiniappRequestType.STORAGE_GET:
+      return {value: null}
+
+    case MiniappRequestType.STORAGE_LIST:
+      return {keys: []}
+
+    case MiniappRequestType.SPEAK:
+      return {audioUrl: null, durationMs: 0}
+
+    case MiniappRequestType.SHARE:
+    case MiniappRequestType.OPEN_URL:
+    case MiniappRequestType.COPY_CLIPBOARD:
+    case MiniappRequestType.DOWNLOAD:
+    case MiniappRequestType.REQUEST_WIFI_SETUP:
+      return {ok: true}
+
+    default:
+      return null
+  }
+}