@mentra/miniapp 0.3.0-beta.0

package/README.md

@@ -0,0 +1,259 @@
+# @mentra/miniapp
+
+SDK for building MentraOS local miniapps — static web apps that run inside the MentraOS phone app's WebView and talk to smart glasses via a typed session API.
+
+> Developing this SDK or running the in-repo example from a fresh clone? Start at the **[SDK developer guide](../../../sdk/README.md)** (setup, build loop, doc map).
+> Per-module deep dives (return shapes, events, error codes): **[`sdk/docs/`](../../../sdk/docs/README.md)**.
+> Companion package: **[`@mentra/miniapp-cli`](../../../sdk/miniapp-cli/README.md)** — `mentra-miniapp` CLI (`dev`, `release`, `pack`, `manifest`, `permission`, `hardware`, `schema`). Per-command docs live there.
+> Scaffolder: `bunx create-mentra-miniapp my-app`.
+> Reference miniapp: [`sdk/example-miniapp/`](../../../sdk/example-miniapp).
+> High-level walkthrough: [`agents/miniapp-sdk-overview.md`](../../../agents/miniapp-sdk-overview.md).
+
+## Install
+
+```bash
+bun add @mentra/miniapp
+# or
+npm install @mentra/miniapp
+```
+
+`react` is an optional peer dependency — only required if you use `@mentra/miniapp/react`.
+
+## Entry points
+
+| Specifier                  | Contents                                                                                          |
+| -------------------------- | ------------------------------------------------------------------------------------------------- |
+| `@mentra/miniapp`          | `MiniappSession`, `NotConnectedError`, transports, manifest-types re-exports, module type exports |
+| `@mentra/miniapp/react`    | React hooks + `<MentraProvider>` + `<MiniappHeader>`                                              |
+| `@mentra/miniapp/protocol` | `MiniappRequestType`, `MiniappResponseType`, `MiniappStreamType`, `MiniappErrorCode`              |
+
+## Quick start
+
+```ts
+import {MiniappSession} from "@mentra/miniapp"
+
+const session = new MiniappSession()
+await session.connect() // sends CONNECT, resolves on CONNECT_ACK
+
+// render() replaces the whole frame; stable ids update in place, render([]) clears.
+const box = {x: 0, y: 0, w: 576, h: 288} // raw device px — see session.capabilities.display
+session.display.render([{type: "text", id: "hello", box, text: "hello"}])
+const unsub = session.transcription.on((d) => session.display.render([{type: "text", id: "hello", box, text: d.text}]))
+// later: unsub()
+```
+
+React:
+
+```tsx
+import {MentraProvider, useSession, useConnected} from "@mentra/miniapp/react"
+
+function App() {
+  const session = useSession() // shared session, auto-connects
+  const ready = useConnected()
+  // ...
+}
+
+// root:
+;<MentraProvider>
+  <App />
+</MentraProvider>
+```
+
+## Session
+
+`MiniappSession` is the only object you construct. It owns the transport, the request/response correlation map, the pre-ready outbound queue, the keepalive PONG, and the cached visibility / capabilities / color-scheme / permissions state.
+
+### Lifecycle
+
+```ts
+const session = new MiniappSession(options?)
+await session.connect()       // idempotent; same Promise on repeat calls
+session.isConnected()
+session.disconnect()
+```
+
+`MiniappSessionOptions`:
+
+- `packageName?: string` — overrides auto-detection from `window.MentraOS`
+- `connectTimeoutMs?: number` — defaults to 10s
+- transport-selection options from `createTransport` (`mode`, `transport`, `localSocket`)
+
+### Lifecycle events
+
+```ts
+const off = session.on("ready", () => {})
+session.off("ready", handler)
+```
+
+| Event          | Signature                                     |
+| -------------- | --------------------------------------------- |
+| `ready`        | `() => void` — fires after CONNECT_ACK        |
+| `disconnect`   | `(reason: string) => void`                    |
+| `error`        | `(err: Error) => void`                        |
+| `visibility`   | `("foreground" \| "background") => void`      |
+| `capabilities` | `(caps: GlassesCapabilities \| null) => void` |
+| `colorScheme`  | `("light" \| "dark") => void`                 |
+| `permissions`  | `(perms: PermissionRecord) => void`           |
+| `speakerState` | `(event: SpeakerStateEvent) => void`          |
+
+Convenience wrappers: `onVisibilityChange`, `onCapabilitiesChange`, `onColorSchemeChange`. Each `on(...)` call also returns an unsubscribe function.
+
+### Cached state
+
+`session.userId`, `session.packageName`, `session.capabilities`, `session.visibility`, `session.colorScheme`, `session.ready` — populated from `CONNECT_ACK` and kept in sync via the lifecycle events above.
+
+## Modules
+
+All event subscribers return an `UnsubscribeFn`. Subscriptions are ref-counted: the SDK sends `SUBSCRIBE` when a stream's active state or routing metadata changes.
+
+| Module                        | Methods                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `session.display`             | `render(elements, opts?)` — scene API: diffed frames, stable-id in-place updates, `render([])` clears                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `session.speaker`             | `play({audioUrl})`, `speak(text, options?)`, `createStream({sampleRate?, volume?})` for bounded 16-bit PCM output, `stop()`, `onStateChange(handler)`                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `session.mic`                 | `onAudioChunk(handler)`, `onVoiceActivity(handler)`, `stop()`, `hasPermission`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `session.transcription`       | `on(handler, {forceLocal?})`, `forLanguage(lang \| [langs], handler, {forceLocal?})`, `configure({languageHints, vocabulary, diarization})`, `stop()`, `hasPermission`                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `session.translation`         | `forLanguagePair(from, to, handler)`, `stop()`, `hasPermission`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `session.input`               | `onButtonPress(handler)`, `onTouch(handler \| gesture, handler \| gestures, handler)`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `session.location`            | `onUpdate(handler)`, `hasPermission`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `session.imu`                 | `onHeadPosition(handler)`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `session.glasses`             | `onBattery(handler)`, `onConnection(handler)`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `session.phone.notifications` | `on(handler)`, `onDismissed(handler)`, `stop()`, `hasPermission`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `session.phone.calendar`      | `listEvents({startsAt, endsAt, limit?})`, `hasPermission`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `session.phone`               | `onBattery(handler)`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `session.system`              | `share(opts)`, `openUrl(url)`, `copyToClipboard(text)`, `download(opts)`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `session.camera`              | `takePhoto({size?, mode?, compress?, sound?, saveToGallery?})`, `setFov({fov, roiPosition?} \| {preset})`, `hasPermission`                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `session.led`                 | `turnOn({color?, ontime?, offtime?, count?})`, `turnOff()`, `blink(color, ontime, offtime, count)`, `solid(color, duration)` — resolve after the glasses acknowledge the RGB command                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `session.permissions`         | `has(type)`, `getAll()`, `onUpdate(handler)`, `onPermissionError(handler)`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `session.storage`             | `get(key)`, `set(key, value)`, `delete(key)`, `list()` — strings only, scoped to `(userId, packageName)`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `session.stream`              | `startUnmanaged({streamUrl, video?, audio?, sound?})`, `startManaged({restreamDestinations?, video?, audio?, sound?, ingest?})`, `stop(streamId?)` — stream video input fields are `width`, `height`, `bitrate`, and `fps`; resolved status reports effective frame rate as `resolvedConfig.video.fps`. Start resolves with `{streamId, status, resolvedConfig?}` after glasses report the publisher is streaming; managed starts also return playback URLs; `ingest` selects `"srt"` for HLS/recording or `"whip"` for low-latency WebRTC; stop is idempotent for an already-stopped stream |
+| `session.dashboard`           | `setContent(mode, content)` — **noop in v1**, prints a one-time `console.warn`. Cloud DashboardManager owns rendering.                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+
+`session.events` is **internal**. It exposes `subscribe(rawStreamType, handler)` only as a forward-compat escape hatch for new event types not yet wrapped on a domain module — prefer the typed module surface.
+
+### Camera FOV
+
+`await session.camera.setFov({fov, roiPosition})` applies a temporary, miniapp-owned FOV/ROI override and resolves with `CameraFovResult` after the ASG client reports the setting was applied following the camera restart cooldown. The host restores the previous live miniapp override—or the persistent 102-degree centered base—when this miniapp closes. `roiPosition` accepts `"center"`, `"bottom"`, or `"top"` and defaults to `"center"`. You can also call `setFov({preset: "narrow" | "standard" | "wide"})`; presets map to 82, 102, and 118 degrees with center ROI. The call requires `CAMERA` in `miniapp.json` and rejects with `MiniappRequestError` if the host or glasses cannot apply it.
+
+### Camera Photos
+
+`await session.camera.takePhoto(...)` resolves only after the photo is delivered through the phone/cloud upload path. The result includes `{requestId, photoUrl, mimeType, size}`. Glasses-side or phone-relay failures such as `CAMERA_BUSY`, `BATTERY_LOW`, storage errors, or fallback upload failures reject before upload polling completes; intermediate `photo_status` progress and request acceptance alone do not resolve the miniapp photo promise.
+
+### Transcription language convention
+
+Transcription/translation streams use a colon-suffixed wire format: `transcription:en-US`, `translation:en-US:fr-FR`. `session.transcription.on(handler)` subscribes to `transcription:auto` (cloud auto-detects). The detected language is in the payload. A handler on `transcription:auto` receives any `transcription:<lang>` event — wildcard fan-out — so "give me transcripts in whatever language" works without manual wiring. Use `session.transcription.forLanguage(lang | [langs], handler)` to pin specific languages. Pass `{forceLocal: true}` as the final argument to either method to require on-device transcription and suppress cloud results for that subscription. Routing is per listener, so a default listener on the same stream can continue receiving cloud transcription.
+
+### Permissions semantics
+
+`session.permissions.has("microphone")` returns whether the manifest declared the permission. Same semantics as cloud SDK v3. **It does NOT report OS-level grant state** — even when `has(...)` returns `true` the user can have denied the OS prompt and your subscriptions will silently receive no events. OS-grant tracking and `request(...)` are deferred and will land additively on the same module.
+
+`PermissionType` is the lowercase canonical union: `"location" | "microphone" | "camera" | "notifications" | "calendar"`. Manifest UPPER_CASE names map onto these (`BACKGROUND_LOCATION` → `location`; `READ_NOTIFICATIONS`, `POST_NOTIFICATIONS` → `notifications`).
+
+## React bindings — `@mentra/miniapp/react`
+
+All hooks share a single session per app, created on first `useSession()` call.
+
+| Hook                      | Returns                                                                                    |
+| ------------------------- | ------------------------------------------------------------------------------------------ |
+| `useSession()`            | Shared `MiniappSession`. Auto-calls `connect()` once.                                      |
+| `useConnected()`          | `boolean` — flips on `ready` / `disconnect`                                                |
+| `useCapabilities()`       | The current glasses capability profile, or `null`                                          |
+| `useVisibility()`         | `"foreground" \| "background"`                                                             |
+| `useColorScheme()`        | `"light" \| "dark"` (host theme)                                                           |
+| `useSafeArea()`           | `{insets, capsuleMenu}` — pixel insets + bounding rect of the host's floating capsule menu |
+| `useCapsuleHeaderStyle()` | Pre-computed CSS for a header row that aligns with the capsule menu                        |
+
+Components:
+
+- `<MentraProvider>` — root provider. Keeps `<html class="dark">` in sync with the host color scheme during render (no FOUC).
+- `<MiniappHeader title="…" left={…} right={…} onBack={…} />` — drop-in header that respects the safe area and leaves room for the capsule menu.
+
+## Manifest — `miniapp.json`
+
+```json
+{
+  "packageName": "com.mentra.example",
+  "version": "1.0.0",
+  "name": "Live Captions",
+  "description": "…",
+  "icon": "icon.png",
+  "permissions": [{"type": "MICROPHONE", "description": "…"}],
+  "hardwareRequirements": [
+    {"type": "DISPLAY", "level": "REQUIRED"},
+    {"type": "MICROPHONE", "level": "REQUIRED"}
+  ]
+}
+```
+
+- `permissions[].type` ∈ `MICROPHONE | CAMERA | CALENDAR | LOCATION | BACKGROUND_LOCATION | READ_NOTIFICATIONS | POST_NOTIFICATIONS`
+- `hardwareRequirements[].type` ∈ `CAMERA | DISPLAY | MICROPHONE | SPEAKER | IMU | BUTTON | LIGHT | WIFI`, `level` ∈ `REQUIRED | OPTIONAL`
+
+The CLI validates the manifest on every `dev`, `release`, and `pack`. Run `mentra-miniapp schema print` for the canonical JSON Schema.
+
+## CLI
+
+The author-facing CLI lives in a sibling package: **[`@mentra/miniapp-cli`](../../../sdk/miniapp-cli/README.md)** (binary: `mentra-miniapp`). Full per-command docs there. Quick map:
+
+| Command                                                        | Purpose                                                      |
+| -------------------------------------------------------------- | ------------------------------------------------------------ |
+| `mentra-miniapp dev`                                           | Hot-reload dev server + QR sideload onto a phone over LAN    |
+| `mentra-miniapp release`                                       | Build, pack, and serve a QR to install on a phone            |
+| `mentra-miniapp pack`                                          | Validate manifest and zip `dist/` into `<pkg>-<version>.zip` |
+| `mentra-miniapp manifest`                                      | Interactive top-level wizard for `miniapp.json`              |
+| `mentra-miniapp permission list \| add \| remove [TYPE]`       | Object-verb manifest edits for permissions                   |
+| `mentra-miniapp hardware list \| add \| remove [TYPE] [LEVEL]` | Object-verb manifest edits for hardware requirements         |
+| `mentra-miniapp schema print`                                  | Print the canonical `miniapp.json` JSON Schema               |
+
+See [the CLI README](../../../sdk/miniapp-cli/README.md) for flags, semantics, and the `miniapp://` URL schemes the QR codes encode.
+
+## Host-injected globals — `window.MentraOS`
+
+The MentraOS app injects this before content loads. Authors generally use the React hooks instead, but the raw shape is:
+
+```ts
+{
+  packageName, platform, capabilities,
+  miniappLocal, miniappDeveloperMode,
+  safeAreaInsets: {top, bottom, left, right},
+  capsuleMenu: {top, right, bottom, left, width, height},
+  colorScheme: "light" | "dark"
+}
+```
+
+Use `getMentraOSGlobals()` (exported from the package) to read it with the right TypeScript types.
+
+## Transports
+
+Auto-selected by `createTransport(options)`:
+
+- **`PostMessageTransport`** — used inside the MentraOS WebView. `window.ReactNativeWebView.postMessage` outbound, `window` `message` listener inbound.
+- **`LocalSocketTransport`** — fallback for laptop browsers. Default endpoint `ws://127.0.0.1:8765`. The in-laptop-browser dev story is currently broken; see the overview doc for status.
+
+Both are exported for advanced uses (forced transport, tests). `MockTransport` is also exported for unit tests.
+
+## Wire protocol
+
+Every message is a `{payload, requestId?}` envelope, JSON over the chosen transport. `requestId` correlates request ↔ response for methods that return a value. Constants live in `@mentra/miniapp/protocol`:
+
+- `MiniappRequestType` — `CONNECT`, `SUBSCRIBE`, etc.
+- `MiniappResponseType` — `CONNECT_ACK`, `EVENT`, `REQUEST_RESULT`, `PERMISSIONS_UPDATE`, …
+- `MiniappStreamType` — typed names for stream identifiers
+- `MiniappErrorCode` — `NOT_CONNECTED`, `PERMISSION_NOT_DECLARED`, …
+
+Full enum listings in [`src/protocol.ts`](./src/protocol.ts).
+
+## Controller pattern (recommended)
+
+Smart-glasses miniapps are **always-on services**. The webview is a UI on top of a continuously-running session. If you tie subscriptions to React component lifecycle, closing or navigating away from a page also stops the glasses behavior — wrong shape for glasses.
+
+**Rule:** user-facing glasses logic lives in a session-scoped controller, instantiated once at module init. React pages read controller-driven state via a store (Zustand recommended) and call imperative methods on the controller for user-triggered actions. They do **not** subscribe to `session.*` directly.
+
+See [`sdk/example-miniapp/src/controller/GlassesController.ts`](../../../sdk/example-miniapp/src/background/controllers/GlassesController.ts) for a worked reference.
+
+**Tester pages exception:** `pages/tester/*` are diagnostic surfaces — by design they inline-subscribe to `session.*` and tear down on unmount. This is the only place where that pattern is acceptable.
+
+## File map
+
+- Runtime: [`src/{session,protocol,envelope,globals}.ts`](./src/), [`src/modules/`](./src/modules/), [`src/transport/`](./src/transport/), [`src/react/`](./src/react/)
+- CLI: [`../miniapp-cli/src/`](../../../sdk/miniapp-cli/src/)
+- Scaffolder: [`../create-mentra-miniapp/`](../../../sdk/create-mentra-miniapp/)
+- Reference miniapp: [`../example-miniapp/`](../../../sdk/example-miniapp/)

package/dist/background/index.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @mentra/miniapp/background — background-side SDK entry point.
+ *
+ * Imported from a miniapp's `src/background/index.ts` to access the
+ * per-miniapp `MiniappSession` and its typed `session.*` module
+ * wrappers. This is the **always-running JSContext side** of a two-layer
+ * miniapp.
+ *
+ * What's NOT in this entry point:
+ *   - `mentra` WebView global (UI-only — import from `@mentra/miniapp/ui`).
+ *   - `MentraProvider` / React hooks (UI-only).
+ *   - Any DOM-bound API. The JSContext has no DOM.
+ *
+ * Importing the wrong sub-path is caught at compile time by the
+ * separate type-roots on each `exports` entry.
+ */
+export { MiniappSession, type MiniappSessionOptions } from "../session";
+export { registerMiniapp, type MiniappInitHandler } from "./register";
+export type { TranscriptionData, TranslationData, ButtonPressData, AudioChunkData, VadData, BatteryData, ConnectionData, WifiData, HeadPositionData, AccelData, LocationData, PhoneNotificationData, NotificationDismissedData, HeadingData, TouchData, UnsubscribeFn, } from "../modules/events";
+export type { CalendarEvent, CalendarListOptions, CalendarListResult } from "../modules/phone";
+export { MiniappRequestType, MiniappResponseType, MiniappStreamType, MiniappErrorCode } from "../protocol";
+export type { ActionContext, ActionHandler, InvokeOptions } from "../modules/actions";
+export type { DisplayManager } from "../modules/display";
+export type { CameraFovPreset, CameraFovRequest, CameraFovResult, CameraModule, CameraRoiPosition, SetCameraFovOptions, } from "../modules/camera";
+export type { CloudClientAudioTransport, CloudClientConnectionStatus, CloudClientStatus, CloudModule, } from "../modules/cloud";
+export type { DashboardAPI } from "../modules/dashboard";
+export type { GlassesModule } from "../modules/glasses";
+export type { HeadingModule } from "../modules/heading";
+export type { ImuModule } from "../modules/imu";
+export type { InputModule } from "../modules/input";
+export type { LedModule } from "../modules/led";
+export type { LocationModule } from "../modules/location";
+export type { MicModule } from "../modules/mic";
+export type { NavigationModule } from "../modules/navigation";
+export type { PermissionsModule } from "../modules/permissions";
+export type { PhoneModule } from "../modules/phone";
+export type { SimpleStorage } from "../modules/storage";
+export { BlobModule, BlobWriter, BlobReader, BLOB_WRITE_CHUNK_BYTES, BLOB_READ_ALL_MAX_BYTES } from "../modules/blob";
+export type { BlobMeta, BlobSetOptions, BlobSetFromUrlOptions, BlobImportOptions } from "../modules/blob";
+export { bytesToBase64, base64ToBytes } from "../modules/base64";
+export type { SpeakerModule } from "../modules/speaker";
+export type { StreamModule } from "../modules/stream";
+export type { SystemModule } from "../modules/system";
+export type { TranscriptionModule } from "../modules/transcription";
+export type { TranslationModule } from "../modules/translation";
+export type { UIModule, UIChannelHandler, UIUnsubscribe } from "../modules/ui";
+export type { Rpc, IsRpc, RpcReq, RpcRes, RpcRequestOptions, RpcHandlerContext } from "../modules/ui";
+export { MentraRpcError, MentraRpcTimeoutError } from "../modules/ui";
+export type { LedColor, LedControlOptions } from "../modules/led";
+export type { ViewType, DisplayBreakMode, RenderBox, RenderElement, RenderOptions, RenderRectStyle, RenderResult, RenderTextStyle, } from "../modules/display";
+export type { DashboardMode } from "../modules/dashboard";
+export type { PlayAudioOptions, SpeakOptions, SpeakResult, SpeakerState, SpeakerStateEvent } from "../modules/speaker";
+export type { ShareOptions, ShareResult, DownloadOptions, DownloadResult } from "../modules/system";
+export type { TranscriptionConfig, TranscriptionOptions } from "../modules/transcription";
+export type { PermissionErrorEvent } from "../modules/permissions";
+export type { AuthUpdatePayload, MiniappVisibility, PermissionType, PermissionRecord, GlassesCapabilities, ConnectAckPayload, MiniappAuthState, MiniappRequestError, } from "../session";
+export type { AuthFetchOptions, AuthModule } from "../modules/auth";
+export type { MiniappColorScheme } from "../globals";
+export type { LatLng, TravelMode, ManeuverKind, RouteAvoidances, NavManeuver, NavOffRoute, NavRerouting, NavArrived, NavError, NavUpdate, NavRoute, PivotOptions, Pivot, PivotEvent, NavStep, NavigationDev, StartNavigationOptions, NavState, NavPermissionResult, ComputeRouteOptions, ComputedRouteStep, ComputedRoute, ComputeRouteResult, } from "../modules/navigation";
+//# sourceMappingURL=index.d.ts.map

package/dist/background/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/background/index.ts"],"names":[],"mappings":"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"}

package/dist/background/index.js

@@ -0,0 +1,25 @@
+/**
+ * @mentra/miniapp/background — background-side SDK entry point.
+ *
+ * Imported from a miniapp's `src/background/index.ts` to access the
+ * per-miniapp `MiniappSession` and its typed `session.*` module
+ * wrappers. This is the **always-running JSContext side** of a two-layer
+ * miniapp.
+ *
+ * What's NOT in this entry point:
+ *   - `mentra` WebView global (UI-only — import from `@mentra/miniapp/ui`).
+ *   - `MentraProvider` / React hooks (UI-only).
+ *   - Any DOM-bound API. The JSContext has no DOM.
+ *
+ * Importing the wrong sub-path is caught at compile time by the
+ * separate type-roots on each `exports` entry.
+ */
+export { MiniappSession } from "../session";
+export { registerMiniapp } from "./register";
+// Public envelope + protocol types so authors can write strongly-typed
+// glue when they need to fall back to session.sendOneShot / sendRequest.
+export { MiniappRequestType, MiniappResponseType, MiniappStreamType, MiniappErrorCode } from "../protocol";
+export { BlobModule, BlobWriter, BlobReader, BLOB_WRITE_CHUNK_BYTES, BLOB_READ_ALL_MAX_BYTES } from "../modules/blob";
+export { bytesToBase64, base64ToBytes } from "../modules/base64";
+export { MentraRpcError, MentraRpcTimeoutError } from "../modules/ui";
+//# sourceMappingURL=index.js.map

package/dist/background/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/background/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAC,cAAc,EAA6B,MAAM,YAAY,CAAA;AACrE,OAAO,EAAC,eAAe,EAA0B,MAAM,YAAY,CAAA;AAwBnE,uEAAuE;AACvE,yEAAyE;AACzE,OAAO,EAAC,kBAAkB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,gBAAgB,EAAC,MAAM,aAAa,CAAA;AAoCxG,OAAO,EAAC,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,sBAAsB,EAAE,uBAAuB,EAAC,MAAM,iBAAiB,CAAA;AAEnH,OAAO,EAAC,aAAa,EAAE,aAAa,EAAC,MAAM,mBAAmB,CAAA;AAQ9D,OAAO,EAAC,cAAc,EAAE,qBAAqB,EAAC,MAAM,eAAe,CAAA"}

package/dist/background/register.d.ts

@@ -0,0 +1,38 @@
+/**
+ * registerMiniapp — entry hook for the background JSContext.
+ *
+ * The MentraJS host loads the polyfill (which installs __dispatch /
+ * __deliver / timers / fetch / etc.), then evaluates the miniapp's
+ * background bundle. After both scripts have evaluated successfully,
+ * the host delivers a single `{kind: "init", sessionId}` envelope.
+ * The polyfill turns that into a call to `__mentraInitCallback(sessionId)`.
+ *
+ * This module wires that callback to:
+ *   1. Construct a `MiniappSession` (DispatchTransport picks itself
+ *      automatically because `__dispatch` is on globalThis).
+ *   2. Call the user-supplied handler synchronously so subscriptions
+ *      are registered before any host events fan out.
+ *   3. Call `session.connect()` so the host receives CONNECT and the
+ *      first CONNECT_ACK populates `userId`, `capabilities`, etc.
+ *
+ * The handler runs once per spawn. If the host kills + respawns the
+ * JSContext (crash recovery, dev reload), the polyfill + bundle are
+ * re-evaluated and the handler fires again with a fresh session.
+ */
+import { MiniappSession, type MiniappSessionOptions } from "../session";
+export type MiniappInitHandler = (session: MiniappSession) => void | Promise<void>;
+/**
+ * Register the miniapp's startup handler. Call once at the top level of
+ * `src/background/index.ts`. Top-level side effects are fine, but the
+ * vast majority of setup should live inside the handler so it can run
+ * with a connected session.
+ *
+ * @example
+ *   registerMiniapp((session) => {
+ *     session.transcription.on((tx) => {
+ *       session.display.render([{type: "text", id: "tx", box, text: tx.text}])
+ *     })
+ *   })
+ */
+export declare function registerMiniapp(handler: MiniappInitHandler, options?: MiniappSessionOptions): void;
+//# sourceMappingURL=register.d.ts.map

package/dist/background/register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../src/background/register.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAC,cAAc,EAAE,KAAK,qBAAqB,EAAC,MAAM,YAAY,CAAA;AAErE,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;AAYlF;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,kBAAkB,EAAE,OAAO,GAAE,qBAA0B,GAAG,IAAI,CAmCtG"}

package/dist/background/register.js

@@ -0,0 +1,75 @@
+/**
+ * registerMiniapp — entry hook for the background JSContext.
+ *
+ * The MentraJS host loads the polyfill (which installs __dispatch /
+ * __deliver / timers / fetch / etc.), then evaluates the miniapp's
+ * background bundle. After both scripts have evaluated successfully,
+ * the host delivers a single `{kind: "init", sessionId}` envelope.
+ * The polyfill turns that into a call to `__mentraInitCallback(sessionId)`.
+ *
+ * This module wires that callback to:
+ *   1. Construct a `MiniappSession` (DispatchTransport picks itself
+ *      automatically because `__dispatch` is on globalThis).
+ *   2. Call the user-supplied handler synchronously so subscriptions
+ *      are registered before any host events fan out.
+ *   3. Call `session.connect()` so the host receives CONNECT and the
+ *      first CONNECT_ACK populates `userId`, `capabilities`, etc.
+ *
+ * The handler runs once per spawn. If the host kills + respawns the
+ * JSContext (crash recovery, dev reload), the polyfill + bundle are
+ * re-evaluated and the handler fires again with a fresh session.
+ */
+import { MiniappSession } from "../session";
+/**
+ * Register the miniapp's startup handler. Call once at the top level of
+ * `src/background/index.ts`. Top-level side effects are fine, but the
+ * vast majority of setup should live inside the handler so it can run
+ * with a connected session.
+ *
+ * @example
+ *   registerMiniapp((session) => {
+ *     session.transcription.on((tx) => {
+ *       session.display.render([{type: "text", id: "tx", box, text: tx.text}])
+ *     })
+ *   })
+ */
+export function registerMiniapp(handler, options = {}) {
+    const g = globalThis;
+    g.__mentraInitCallback = (_sessionId) => {
+        const session = new MiniappSession(options);
+        // Fire the user handler first so any session.* subscriptions get
+        // registered before the CONNECT_ACK fan-out lands.
+        try {
+            const result = handler(session);
+            if (result && typeof result.then === "function") {
+                ;
+                result.catch((err) => {
+                    // eslint-disable-next-line no-console
+                    console.error("[mentra-miniapp] registerMiniapp handler rejected:", err);
+                });
+            }
+        }
+        catch (err) {
+            // eslint-disable-next-line no-console
+            console.error("[mentra-miniapp] registerMiniapp handler threw:", err);
+        }
+        session.connect().catch((err) => {
+            // eslint-disable-next-line no-console
+            console.error("[mentra-miniapp] session.connect() rejected:", err);
+            // Surface to the host's crash controller as a structured uncaught
+            // error so the existing backoff + crashloop machinery handles it.
+            // Repeated connect failures eventually flip the miniapp to
+            // CRASHLOOP_DISABLED, which the host turns into a user-facing
+            // alert + automatic incident report.
+            try {
+                const message = err instanceof Error ? err.message : String(err);
+                const stack = err instanceof Error && err.stack ? err.stack : "";
+                g.__hostError?.(JSON.stringify({ message: `session.connect() failed: ${message}`, stack }));
+            }
+            catch {
+                /* host bridge missing in tests — ignore */
+            }
+        });
+    };
+}
+//# sourceMappingURL=register.js.map

package/dist/background/register.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.js","sourceRoot":"","sources":["../../src/background/register.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAC,cAAc,EAA6B,MAAM,YAAY,CAAA;AAcrE;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,eAAe,CAAC,OAA2B,EAAE,UAAiC,EAAE;IAC9F,MAAM,CAAC,GAAG,UAAoC,CAAA;IAC9C,CAAC,CAAC,oBAAoB,GAAG,CAAC,UAAkB,EAAE,EAAE;QAC9C,MAAM,OAAO,GAAG,IAAI,cAAc,CAAC,OAAO,CAAC,CAAA;QAC3C,iEAAiE;QACjE,mDAAmD;QACnD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;YAC/B,IAAI,MAAM,IAAI,OAAQ,MAAwB,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;gBACnE,CAAC;gBAAC,MAAwB,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;oBAChD,sCAAsC;oBACtC,OAAO,CAAC,KAAK,CAAC,oDAAoD,EAAE,GAAG,CAAC,CAAA;gBAC1E,CAAC,CAAC,CAAA;YACJ,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,sCAAsC;YACtC,OAAO,CAAC,KAAK,CAAC,iDAAiD,EAAE,GAAG,CAAC,CAAA;QACvE,CAAC;QACD,OAAO,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;YACvC,sCAAsC;YACtC,OAAO,CAAC,KAAK,CAAC,8CAA8C,EAAE,GAAG,CAAC,CAAA;YAClE,kEAAkE;YAClE,kEAAkE;YAClE,2DAA2D;YAC3D,8DAA8D;YAC9D,qCAAqC;YACrC,IAAI,CAAC;gBACH,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;gBAChE,MAAM,KAAK,GAAG,GAAG,YAAY,KAAK,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAA;gBAChE,CAAC,CAAC,WAAW,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,EAAC,OAAO,EAAE,6BAA6B,OAAO,EAAE,EAAE,KAAK,EAAC,CAAC,CAAC,CAAA;YAC3F,CAAC;YAAC,MAAM,CAAC;gBACP,2CAA2C;YAC7C,CAAC;QACH,CAAC,CAAC,CAAA;IACJ,CAAC,CAAA;AACH,CAAC"}

package/dist/dev-reload.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @fileoverview SDK-side dev-reload listener — auto-installed when the host
+ * indicates we're running in a dev miniapp.
+ *
+ * Companion to the phone-side console-tap shim (which is injected by the
+ * MentraOS app, not by the SDK). The SDK installs this listener on import so
+ * authors get live reload without any opt-in code.
+ *
+ * Mechanism:
+ *   - Phone-side `DevServerBridge` receives `{type: "reload"}` from the dev
+ *     server's WebSocket.
+ *   - Phone-side `MiniappHost` then injects a `MessageEvent` into the WebView
+ *     with payload `{type: "miniapp_dev_reload"}`.
+ *   - This listener catches that MessageEvent and calls `location.reload()`.
+ *
+ * Gated on `window.MentraOS.miniappDeveloperMode === true` so production
+ * miniapps never set up the listener. In production WebViews the host won't
+ * inject the message anyway, but belt-and-suspenders.
+ */
+export declare function installDevReloadListenerIfDevMode(): void;
+//# sourceMappingURL=dev-reload.d.ts.map

package/dist/dev-reload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-reload.d.ts","sourceRoot":"","sources":["../src/dev-reload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,wBAAgB,iCAAiC,IAAI,IAAI,CAqCxD"}

package/dist/dev-reload.js

@@ -0,0 +1,62 @@
+/**
+ * @fileoverview SDK-side dev-reload listener — auto-installed when the host
+ * indicates we're running in a dev miniapp.
+ *
+ * Companion to the phone-side console-tap shim (which is injected by the
+ * MentraOS app, not by the SDK). The SDK installs this listener on import so
+ * authors get live reload without any opt-in code.
+ *
+ * Mechanism:
+ *   - Phone-side `DevServerBridge` receives `{type: "reload"}` from the dev
+ *     server's WebSocket.
+ *   - Phone-side `MiniappHost` then injects a `MessageEvent` into the WebView
+ *     with payload `{type: "miniapp_dev_reload"}`.
+ *   - This listener catches that MessageEvent and calls `location.reload()`.
+ *
+ * Gated on `window.MentraOS.miniappDeveloperMode === true` so production
+ * miniapps never set up the listener. In production WebViews the host won't
+ * inject the message anyway, but belt-and-suspenders.
+ */
+const RELOAD_MESSAGE_TYPE = "miniapp_dev_reload";
+export function installDevReloadListenerIfDevMode() {
+    if (typeof window === "undefined")
+        return;
+    const mentra = window.MentraOS;
+    if (!mentra?.miniappDeveloperMode)
+        return;
+    // Avoid double-install if the SDK is hot-reloaded mid-session.
+    const flagKey = "__mentraDevReloadInstalled";
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    if (window[flagKey])
+        return;
+    window[flagKey] = true;
+    const handler = (ev) => {
+        const data = typeof ev.data === "string" ? ev.data : null;
+        if (!data)
+            return;
+        let parsed;
+        try {
+            parsed = JSON.parse(data);
+        }
+        catch {
+            return;
+        }
+        const env = parsed;
+        const type = env?.payload?.type;
+        if (type !== RELOAD_MESSAGE_TYPE)
+            return;
+        // eslint-disable-next-line no-console
+        console.log("[mentra-miniapp] dev reload signal received — reloading");
+        try {
+            location.reload();
+        }
+        catch {
+            // Some embedded contexts forbid reload; ignore.
+        }
+    };
+    window.addEventListener("message", handler);
+    if (typeof document !== "undefined") {
+        document.addEventListener("message", handler);
+    }
+}
+//# sourceMappingURL=dev-reload.js.map

package/dist/dev-reload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-reload.js","sourceRoot":"","sources":["../src/dev-reload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,mBAAmB,GAAG,oBAAoB,CAAA;AAEhD,MAAM,UAAU,iCAAiC;IAC/C,IAAI,OAAO,MAAM,KAAK,WAAW;QAAE,OAAM;IACzC,MAAM,MAAM,GAAI,MAAwD,CAAC,QAAQ,CAAA;IACjF,IAAI,CAAC,MAAM,EAAE,oBAAoB;QAAE,OAAM;IAEzC,+DAA+D;IAC/D,MAAM,OAAO,GAAG,4BAA4B,CAAA;IAC5C,8DAA8D;IAC9D,IAAK,MAAc,CAAC,OAAO,CAAC;QAAE,OAE7B;IAAC,MAAc,CAAC,OAAO,CAAC,GAAG,IAAI,CAAA;IAEhC,MAAM,OAAO,GAAG,CAAC,EAAgB,EAAQ,EAAE;QACzC,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAA;QACzD,IAAI,CAAC,IAAI;YAAE,OAAM;QACjB,IAAI,MAAe,CAAA;QACnB,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;QAC3B,CAAC;QAAC,MAAM,CAAC;YACP,OAAM;QACR,CAAC;QACD,MAAM,GAAG,GAAG,MAAqC,CAAA;QACjD,MAAM,IAAI,GAAG,GAAG,EAAE,OAAO,EAAE,IAAI,CAAA;QAC/B,IAAI,IAAI,KAAK,mBAAmB;YAAE,OAAM;QACxC,sCAAsC;QACtC,OAAO,CAAC,GAAG,CAAC,yDAAyD,CAAC,CAAA;QACtE,IAAI,CAAC;YACH,QAAQ,CAAC,MAAM,EAAE,CAAA;QACnB,CAAC;QAAC,MAAM,CAAC;YACP,gDAAgD;QAClD,CAAC;IACH,CAAC,CAAA;IAED,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAA;IAC3C,IAAI,OAAO,QAAQ,KAAK,WAAW,EAAE,CAAC;QACpC,QAAQ,CAAC,gBAAgB,CAAC,SAAS,EAAE,OAAmC,CAAC,CAAA;IAC3E,CAAC;AACH,CAAC"}

package/dist/envelope.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @fileoverview Bridge envelope format.
+ *
+ * Every message between @mentra/miniapp and LocalMiniappRuntime is wrapped in
+ * this envelope for request/response correlation.
+ *
+ *   { payload: {...}, requestId?: string }
+ */
+export interface MiniappEnvelope<P = unknown> {
+    payload: P;
+    /** Correlates request/response pairs. Set by the sender when it wants a reply. */
+    requestId?: string;
+}
+/** Serialize an envelope for postMessage / WebSocket transport. */
+export declare function serializeEnvelope(envelope: MiniappEnvelope): string;
+/**
+ * Parse a serialized envelope. Returns null for any malformed input — never throws.
+ * Transports should pass raw strings in and silently drop nulls.
+ */
+export declare function parseEnvelope(raw: unknown): MiniappEnvelope | null;
+/** Generate a short random requestId. Browser-native (crypto.randomUUID). */
+export declare function makeRequestId(): string;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../src/envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,OAAO;IAC1C,OAAO,EAAE,CAAC,CAAA;IACV,kFAAkF;IAClF,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,mEAAmE;AACnE,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,CAEnE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,eAAe,GAAG,IAAI,CAoBlE;AAED,6EAA6E;AAC7E,wBAAgB,aAAa,IAAI,MAAM,CAMtC"}