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

package/README.md

@@ -1,13 +1,13 @@
 # @glassly/miniapp
 
-SDK for building Glassly local miniapps — static web apps that run inside the Glassly phone app's WebView and talk to smart glasses via a typed session API.
+SDK for building Glassly local miniapps: static web apps that run inside the Glassly 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: **[`@glassly/miniapp-cli`](../../../sdk/miniapp-cli/README.md)** — `glassly-miniapp` CLI (`dev`, `release`, `pack`, `manifest`, `permission`, `hardware`, `schema`). Per-command docs live there.
-> Scaffolder: `bunx create-miniapp my-app`.
+> Companion package: **[`@glassly/miniapp-cli`](../../../sdk/miniapp-cli/README.md)**, the `glassly-miniapp` CLI (`dev`, `release`, `pack`, `manifest`, `permission`, `hardware`, `schema`). Per-command docs live there.
+> Scaffolder: `bunx @glassly/create-miniapp my-app`.
 > Reference miniapp: [`miniapps/example-miniapp/`](../../../miniapps/example-miniapp).
-> High-level walkthrough: [`agents/miniapp-sdk-overview.md`](../../../agents/miniapp-sdk-overview.md).
+> High-level walkthrough: [`notes/miniapp-sdk-overview.md`](../../../notes/miniapp-sdk-overview.md).
 
 ## Install
 
@@ -17,17 +17,19 @@ bun add @glassly/miniapp
 npm install @glassly/miniapp
 ```
 
-`react` is an optional peer dependency — only required if you use `@glassly/miniapp/react`.
+`react` is an optional peer dependency, required only if you use `@glassly/miniapp/react`.
 
 ## Entry points
 
 | Specifier                    | Contents                                                                                          |
 | ---------------------------- | ------------------------------------------------------------------------------------------------- |
 | `@glassly/miniapp`            | `MiniappSession`, `NotConnectedError`, transports, manifest-types re-exports, module type exports |
-| `@glassly/miniapp/background` | `MiniappSession`, `registerMiniapp` — the always-on session layer (see two-layer note below)      |
+| `@glassly/miniapp/background` | `MiniappSession`, `registerMiniapp`, the always-on session layer (see two-layer note below)      |
 | `@glassly/miniapp/ui`         | The WebView-side `glassly` channel bridge + React adapters (`<MiniappProvider>`, `<MiniappHeader>`, hooks) |
 | `@glassly/miniapp/react`      | React hooks + `<MiniappProvider>` + `<MiniappHeader>` (also re-exported from `/ui`)                |
 | `@glassly/miniapp/protocol`   | `MiniappRequestType`, `MiniappResponseType`, `MiniappStreamType`, `MiniappErrorCode`              |
+| `@glassly/miniapp/hardware`   | `HardwareType`, `HardwareRequirementLevel`, `HardwareRequirement` (manifest hardware-requirement types) |
+| `@glassly/miniapp/known-apps` | `KNOWN_APPS`, `knownApp`, `knownAppName`, `appGlyph` (notification app names and card glyphs by bundle id / package name) |
 
 > **Two layers.** Miniapps split into an always-on **background** layer that
 > owns the `MiniappSession` (`@glassly/miniapp/background`, entered via
@@ -47,14 +49,14 @@ import {registerMiniapp} from "@glassly/miniapp/background"
 // before invoking your handler.
 registerMiniapp((session) => {
   // 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
+  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()
 })
 ```
 
-UI layer (WebView React app — no session here):
+UI layer (WebView React app, no session here):
 
 ```tsx
 import {MiniappProvider, useConnected} from "@glassly/miniapp/ui"
@@ -73,6 +75,34 @@ function App() {
 
 ## Session
 
+### Shared display primitives
+
+Import `TextMeasurer`, `TextWrapper`, display profiles, and pixel-art helpers
+from `@glassly/miniapp/display`. These pure TypeScript primitives share the
+host's implementation and work in either miniapp layer. See the
+[display primitives reference](../../../sdk/docs/display-primitives.md).
+
+### Opt-in display helpers
+
+Both the main and `/background` entry points export:
+
+- `monoTextRows({id, text, box, fontSize})`: stable-ID row elements for G2 CFW
+  fixed-pitch grids. Uses its 2px text inset and rounded 1.2× line pitch.
+  Unsupported Unicode falls back per row instead of rasterizing the entire
+  grid. Check positioned-text and element budgets first; this does not make
+  stock firmware support dense mono grids. Submit all rows in each scene,
+  including blank rows, so deletions clear correctly.
+- `LatestRenderScheduler(() => intervalMs)`: `request(async () => { ... })`
+  runs one callback at a time, keeping only the latest pending callback.
+  Construct the scene inside the callback and await `display.render()`;
+  report failures there. Call `clearPending()` when changing views and
+  `dispose()` on shutdown. It cannot cancel native work already submitted,
+  does not change global FPS/transport settings, and must never be used to
+  discard input bytes or other non-replaceable events.
+
+These are optional producer-side helpers, not an automatic native Unicode
+renderer change or BLE message pipelining.
+
 `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
@@ -86,9 +116,9 @@ session.disconnect()
 
 `MiniappSessionOptions`:
 
-- `packageName?: string` — overrides auto-detection from `window.Glassly`
-- `connectTimeoutMs?: number` — defaults to 10s
-- transport-selection options from `createTransport` (`mode`, `transport`, `localSocket`)
+- `packageName?: string`: overrides auto-detection from `window.Glassly`
+- `connectTimeoutMs?: number`: defaults to 10s
+- transport-selection options from `createTransport` (`transport`, `localSocketUrl`)
 
 ### Lifecycle events
 
@@ -99,52 +129,81 @@ 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.
+| `ready`            | `() => void`, fires after CONNECT_ACK                                          |
+| `beforeDisconnect` | `(reason: string) => void`, last chance to send one final one-shot             |
+| `disconnect`       | `(reason: string) => void`                                                     |
+| `error`            | `(err: Error) => void`                                                         |
+| `visibility`       | `("foreground" \| "background") => void`                                       |
+| `capabilities`     | `(caps: GlassesCapabilities \| null) => void`                                  |
+| `preferences`      | `(prefs: MiniappPreferences) => void`                                          |
+| `colorScheme`      | `("light" \| "dark") => void`                                                  |
+| `permissions`      | `(perms: PermissionRecord) => void`                                            |
+| `speakerState`     | `(event: SpeakerStateEvent) => void`                                           |
+| `auth`             | `(auth: MiniappAuthState) => void`                                             |
+
+Convenience wrappers: `onVisibilityChange`, `onCapabilitiesChange`, `onPreferencesChange`, `onColorSchemeChange`, `onBeforeDisconnect`. 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.
+`session.userId`, `session.packageName`, `session.capabilities`, `session.preferences`, `session.visibility`, `session.colorScheme`, `session.launchSource`, `session.ready` are populated from `CONNECT_ACK` and kept in sync via the lifecycle events above.
+
+`session.preferences` is `{unitSystem: "metric" | "imperial", twelveHourTime: boolean}`, mirroring the host's Settings > Appearance toggles. Follow it for distances, temperatures and clock formatting unless your miniapp offers its own override. It is `null` on runtimes that predate the preferences surface, so fall back rather than assuming a value.
+
+`session.launchSource` is `"phone"` or `"glasses"` — where the user started this session from — and `null` until `CONNECT_ACK` arrives, or on runtimes that don't send it.
+
+```ts
+const twelveHour = session.preferences?.twelveHourTime ?? true
+session.onPreferencesChange((prefs) => rerender(prefs))
+
+if (session.launchSource === "glasses") openGlassesFirstView()
+```
 
 ## 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?, transferMethod?, compress?, sound?, saveToGallery?, zsl?, mfnr?, timeoutMs?, ...})`, `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.
+| Module                        | Methods                                                                                                                                                                                                                                                                                                                                            |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `session.auth`                 | `current`, `userId`, `oemId`, `getToken(opts?)`, `getAuthHeader(opts?)`, `fetch(input, init?)`, `onUpdate(handler)`; miniapp-scoped backend auth, never a Core or runtime token                                                                                                                                                                  |
+| `session.mirror` | `getCurrent()`, `onUpdate(handler)`, `hasPermission`; DISPLAY_MIRROR-gated global glasses preview; see [mirror reference](../../../sdk/docs/mirror.md) |
+| `session.display`              | `showView(view)`, `onViewChange(handler)` for overlay miniapps; `render(elements, opts?)`, scene API: diffed frames, stable-id in-place updates, `render([])` clears; `sendNativeNavInfo`/`sendNativeNavMiniMap`/`sendNativeNavOverviewMap` feed firmware-rendered navigation on devices with `hasNativeNavigation`                                                                                             |
+| `session.speaker`              | `state` (`"idle" \| "loading" \| "playing" \| "stopped" \| "error"`), `isPlaying` (true iff `state === "playing"`), `play({audioUrl})`, `speak(text, options?)`, `createStream({sampleRate?, volume?})` for bounded 16-bit PCM output, `stop()`, `onStateChange(handler)`                                                                         |
+| `session.camera`               | `takePhoto({size?, mode?, transferMethod?, compress?, sound?, saveToGallery?, zsl?, mfnr?, timeoutMs?, ...})`, `setFov({fov, roiPosition?} \| {preset})`, `warmUp(opts?)`, `startVideoRecording(opts?)`, `stopVideoRecording(recordingId, opts?)`, `hasPermission`                                                                               |
+| `session.cloud`                | `status`, `connected`, `isConnected()`, `onStatusChanged(handler)`; read-only view of the phone-owned cloud client's connection/audio-transport status                                                                                                                                                                                           |
+| `session.dashboard`            | `setContent(mode, content)` (noop in v1, prints a one-time `console.warn`); `showNativeDashboard()` brings the glasses' OS idle screen to the foreground                                                                                                                                                                                      |
+| `session.glasses`              | `onBattery(handler)`, `onConnection(handler)`, `onWifi(handler)`, `requestWifiSetup(reason?)`, `setWifiAdbState(enabled)` (SYSTEM-only)                                                                                                                                                                                                            |
+| `session.imu`                  | `onHeadPosition(handler)`, `onAccel(handler)`, `setEnabled(enabled)`                                                                                                                                                                                                                                                                                |
+| `session.compass`              | `onUpdate(handler)`, `onCalibration(handler)`, `start(options?)`, `stop()`; glasses heading in degrees, auto-starts on G2 custom firmware, stock nav mode only                                                                                                                                                                                  |
+| `session.lightSensor`          | `onUpdate(handler)`, `query()`, `start(options?)`, `stop()`; G2 custom firmware ambient light, one controlling miniapp                                                                                                                                                                                                                             |
+| `session.input`                | `setClaimedGestures(gestures, {scope?})`, `onClaimChange(handler)`, `onButtonPress(handler)`, `onTouch(handler \| gesture, handler \| gestures, handler)`                                                                                                                                                                                                                              |
+| `session.ai`                   | `complete(request)` (tier-based LLM completion, tool loop support), `generate(request, opts?)` (agentic visual generation), `prompt(text, opts?)` (single-shot text convenience), `hasPermission`                                                                                                                                                 |
+| `session.keys`                 | `get(provider)`, read a user-supplied provider API key (anthropic/gemini/openai/elevenlabs/mapbox), `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.location`             | `onUpdate(handler)`, `getOnce()`, `hasPermission`                                                                                                                                                                                                                                                                                                   |
+| `session.memory`                | `appendLine(input)`, `addNote(text, source?, at?)`, `removeEntry(id)`, `removeScope(scope, at)`, `sessions()`, `query(q?)`, `search(q?)`, `window(sinceMs, untilMs?)`, `exportText(scope, at?)`, `addSummary(summary)`, `summaries()`, `pendingSummaryHour(nowMs?)`, `clear()`, `hasPermission`; the user's shared phone-local memory timeline  |
+| `session.speakers`             | `resolveName(id)`, `hasPermission`; resolve an enrolled-speaker id to its display name                                                                                                                                                                                                                                                            |
+| `session.mic`                  | `onAudioChunk(handler)`, `onVoiceActivity(handler)`, `setVoiceActivityDetectionEnabled(enabled)`, `setLoudnessGateEnabled(enabled)`, `stop()`, `hasPermission`                                                                                                                                                                                     |
+| `session.navigation`           | `start(opts)`, `stop()`, `onUpdate(handler)`, `onRoute(handler)`, `getState()`, `computeRoute(opts)`, `reverseGeocodeRoad(...)`, `placeAutocomplete(opts)`, `placeDetails(opts)`, `onPivot(handler)`, `getPivots()`, `getActivePivot()`, `getUpcomingPivot()`, `requestPermission()`, `hasPermission`; Android-only turn-by-turn navigation      |
+| `session.permissions`          | `has(type)`, `getAll()`, `onUpdate(handler)`, `onPermissionError(handler)`                                                                                                                                                                                                                                                                          |
+| `session.phone.notifications`  | `on(handler)`, `onDismissed(handler)`, `stop()`, `hasPermission`, `installedApps()` (SYSTEM-only)                                                                                                                                                                                                                                                                                    |
+| `session.phone.calendar`       | `listEvents({startsAt, endsAt, limit?})`, `hasPermission`                                                                                                                                                                                                                                                                                           |
+| `session.phone`                | `onBattery(handler)`                                                                                                                                                                                                                                                                                                                                |
+| `session.settings` | `get(key)`, `getAll(keys?)`, `set(key, value)`, `onChange(handler)`; SYSTEM-only host settings bridge; see [settings reference](../../../sdk/docs/settings.md) |
+| `session.storage`              | `get(key)`, `set(key, value)`, `delete(key)`, `keys()`, `has(key)`, `getAll()`, `setMultiple(values)`, `clear()`, `flush()`; strings only, scoped to `(userId, packageName)`                                                                                                                                                                     |
+| `session.blob`                 | `set(key, data, opts?)`, `get(key)`, `stat(key)`, `has(key)`, `keys()`, `list()`, `setFromUrl(key, url, opts?)`, `importFile(opts?)`, `createWriteStream(key, opts?)`, `createReadStream(key)`, `bytes(key)`, `usage()`, `delete(key)`, `clear()`, `share(key)`; phone-local binary storage, chunked writes/reads                               |
+| `session.stream`               | `startStream(opts?)`, `stop(streamId?)`; managed (default, returns `hlsUrl`/`dashUrl`/`webrtcUrl` and optional `destinations` fan-out) or `direct` (publish straight to your own ingest URL, no playback URLs); `opts.ingest` selects `"srt"` (default), `"whip"`, or `"rtmp"`; video config fields are `width`, `height`, `bitrate`, `fps`     |
+| `session.system`               | `share(opts)`, `openUrl(url)`, `copyToClipboard(text)`, `download(opts)`, `scanQr(opts?)`, `exit()`, `getDisplayDiagnostics()`                                                                                                                                                                                                                     |
+| `session.transcription`        | `on(handler, {forceLocal?})`, `forLanguage(lang \| [langs], handler, {forceLocal?})`, `configure({languageHints, vocabulary, diarization})`, `stop()`, `hasPermission`                                                                                                                                                                             |
+| `session.translation`          | `on(handler)`, `to(target \| [targets], handler)`, `fromTo(source, target \| [targets], handler)`, `stop()`, `hasPermission`                                                                                                                                                                                                                       |
+| `session.ui`                   | `isOpen()`, `onOpen(handler)`, `onClose(handler)`, `send(channel, payload)`, `on(channel, handler)`, `handle(channel, handler)`; background-side message bus to the bound WebView; see [Wire protocol](#wire-protocol) and [`sdk/docs/two-layer.md`](../../../sdk/docs/two-layer.md)                                                            |
+| `session.miniapps`             | `list(opts?)`, `start(packageName)`, `stop(packageName)`, `stopSelf()`; inter-miniapp lifecycle and discovery, SYSTEM-only except `stopSelf()`                                                                                                                                                                                                      |
+| `session.actions`              | `list()`, `invoke(packageName, actionId, params?, opts?)`, `handle(actionId, handler)`; inter-miniapp action layer (MCP-tool-shaped); `list`/`invoke` open to all, gated per-action by the target's declared `visibility`                                                                                                                        |
+
+`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 118-degree full-sensor 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.
+`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 118-degree full-sensor 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
 
@@ -154,36 +213,36 @@ Pass `transferMethod: "ble"` to skip direct Wi-Fi upload and always relay the im
 
 ### 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.
+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, a 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.
+`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`).
+`PermissionType` is the lowercase canonical union: `"location" | "microphone" | "camera" | "notifications" | "calendar" | "apiKeys" | "memory" | "ai" | "speakers"`. Manifest UPPER_CASE names map onto these (`BACKGROUND_LOCATION` → `location`; `READ_NOTIFICATIONS`, `POST_NOTIFICATIONS` → `notifications`; `API_KEYS` → `apiKeys`; `MEMORY` → `memory`; `AI` → `ai`; `SPEAKERS` → `speakers`).
 
-## React bindings — `@glassly/miniapp/ui`
+## React bindings (`@glassly/miniapp/ui`)
 
 These UI-layer hooks run inside the WebView and read host state via the injected
-`glassly` channel bridge / `window.Glassly` globals — they do **not** own a
+`glassly` channel bridge / `window.Glassly` globals; they do not own a
 `MiniappSession` (that lives in the background layer). They are also re-exported
 from `@glassly/miniapp/react` for backwards-compat.
 
 | Hook                      | Returns                                                                                    |
 | ------------------------- | ------------------------------------------------------------------------------------------ |
-| `useConnected()`          | `boolean` — true while the `glassly` bridge is open (`onOpen` / `onClose`)                 |
-| `useCapabilities()`       | Glasses capability profile — currently always `null` on the UI side (caps arrive over a channel) |
+| `useConnected()`          | `boolean`, true while the `glassly` bridge is open (`onOpen` / `onClose`)                 |
+| `useCapabilities()`       | Glasses capability profile; currently always `null` on the UI side (caps arrive over a channel) |
 | `useColorScheme()`        | `"light" \| "dark"` (host theme)                                                           |
-| `useSafeArea()`           | `{insets, capsuleMenu}` — pixel insets + bounding rect of the host's floating capsule menu |
+| `useSafeArea()`           | `{insets, capsuleMenu}`, pixel insets and bounding rect of the host's floating capsule menu |
 | `useCapsuleHeaderStyle()` | Pre-computed CSS for a header row that aligns with the capsule menu                        |
 | `useRpc(...)`             | Typed request helper over the `glassly` channel bridge                                     |
 
 Components:
 
-- `<MiniappProvider>` — 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.
+- `<MiniappProvider>`: 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`
+## Manifest (`miniapp.json`)
 
 ```json
 {
@@ -200,8 +259,8 @@ Components:
 }
 ```
 
-- `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`
+- `permissions[].type` ∈ `MICROPHONE | CAMERA | CALENDAR | LOCATION | BACKGROUND_LOCATION | READ_NOTIFICATIONS | POST_NOTIFICATIONS | API_KEYS | MEMORY | AI | SPEAKERS`
+- `hardwareRequirements[].type` ∈ `CAMERA | DISPLAY | MICROPHONE | SPEAKER | IMU | BUTTON | LIGHT | WIFI`, `level` ∈ `REQUIRED | OPTIONAL`. (`EXIST` also exists on the wire but the phone injects it at runtime; don't declare it.)
 
 The CLI validates the manifest on every `dev`, `release`, and `pack`. Run `glassly-miniapp schema print` for the canonical JSON Schema.
 
@@ -221,9 +280,9 @@ The author-facing CLI lives in a sibling package: **[`@glassly/miniapp-cli`](../
 
 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.Glassly`
+## Host-injected globals (`window.Glassly`)
 
-The Glassly app injects this before content loads. Authors generally use the React hooks instead, but the raw shape is:
+The Glassly App injects this before content loads. Authors generally use the React hooks instead, but the raw shape is:
 
 ```ts
 {
@@ -235,37 +294,41 @@ The Glassly app injects this before content loads. Authors generally use the Rea
 }
 ```
 
-Use `getGlasslyGlobals()` (exported from the package) to read it with the right TypeScript types.
+Use `getHostGlobals()` (exported from the package) to read it with the right TypeScript types.
 
 ## Transports
 
-Auto-selected by `createTransport(options)`:
+Auto-selected by `createTransport(options)`, in this order:
+
+- `DispatchTransport`: the production path. Used when running in the per-miniapp background JSContext (no DOM, but the native bridge installs `__dispatch` on `globalThis`). Rides `__dispatch("__bridge", "send", ...)` outbound and the polyfill's `__deliverBridgeRaw` inbound.
+- `PostMessageTransport`: used inside the Glassly WebView (`window.ReactNativeWebView` defined). `window.ReactNativeWebView.postMessage` outbound, `window` `message` listener inbound.
+- `MockTransport`: explicit opt-in via `?glassly=mock` or `localStorage.MINIAPP_MOCK=1`. Synthesizes a CONNECT_ACK and REQUEST_RESULT replies so the SDK doesn't hang in a plain browser tab.
+- `LocalSocketTransport`: fallback for laptop browsers with `WebSocket` available. Default endpoint `ws://127.0.0.1:8765`. Races open() against a 500ms timeout and falls back to `MockTransport` if nothing answers.
 
-- **`PostMessageTransport`** — used inside the Glassly 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.
+`createTransport(options)` takes `{transport?, localSocketUrl?}`. Pass `transport` to force a specific instance (tests), or `localSocketUrl` to override the LocalSocket fallback's URL.
 
-Both are exported for advanced uses (forced transport, tests). `MockTransport` is also exported for unit tests.
+All four are exported for advanced uses (forced transport, 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 `@glassly/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`, …
+- `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.
+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, the 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.
+User-facing glasses logic lives in a session-scoped controller, instantiated once in the background layer's `registerMiniapp` handler. The controller owns every `session.*` subscription and pushes state to the WebView over `session.ui.send` channels; UI pages read that pushed state (e.g. with a small `useChannel`-style hook wrapping `glassly.on`) and call back into the controller for user-triggered actions via `session.ui.handle`/`glassly.request`. Pages do not construct or subscribe to a `session.*` module directly. The background JSContext and the WebView are separate runtimes, so there is no shared in-memory store between them.
 
-See [`miniapps/example-miniapp/src/background/controllers/GlassesController.ts`](../../../miniapps/example-miniapp/src/background/controllers/GlassesController.ts) for a worked reference.
+See [`miniapps/example-miniapp/src/background/controllers/GlassesController.ts`](../../../miniapps/example-miniapp/src/background/controllers/GlassesController.ts) and [`miniapps/example-miniapp/src/ui/hooks/useChannel.ts`](../../../miniapps/example-miniapp/src/ui/hooks/useChannel.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.
+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
 
@@ -273,3 +336,85 @@ See [`miniapps/example-miniapp/src/background/controllers/GlassesController.ts`]
 - CLI: [`../miniapp-cli/src/`](../../../sdk/miniapp-cli/src/)
 - Scaffolder: [`../create-miniapp/`](../../../sdk/create-miniapp/)
 - Reference miniapp: [`miniapps/example-miniapp/`](../../../miniapps/example-miniapp/)
+
+## SVG paths and rotation
+
+G2 Glassly CFW revision 21 and Simulated Glasses support filled SVG paths and
+clockwise rotation of geometric elements. Check
+`session.capabilities.display.shapes.includes("svg")` and
+`session.capabilities.display.rotation` before using them.
+
+```ts
+const heart = {
+  type: "svg" as const,
+  id: "heart",
+  box: {x: 60, y: 60, w: 120, h: 120},
+  d: "M50 90 C-10 45 0 0 30 10 Q45 10 50 25 Q55 10 70 10 C100 0 110 45 50 90 Z",
+  scale: 1,
+  rotation: 0,
+  pivot: {x: 120, y: 120},
+}
+await session.display.render([heart])
+// Keep the id and d: the firmware reuses the path while moving and turning it.
+await session.display.render([{...heart, box: {...heart.box, x: 120}, scale: 1.5,
+  rotation: 720, transition: {durationMs: 2000, easing: "ease-in-out"}}])
+```
+
+`d` accepts absolute/relative `M L H V Q C S T Z` and implicit repetitions.
+Every contour must close with `Z`; `fillRule` is `"nonzero"` (default) or
+`"evenodd"`. This is SVG path data, not an XML document: arcs, strokes, gradients,
+CSS and SVG transform attributes must be converted before calling `render`.
+
+Path coordinates are local to `box.x/y`; `scale` uniformly scales them (0–8,
+quantized to 1/256). `box.w/h` describe layout bounds and do not stretch the path
+or clip its curves. Source coordinates must fit signed Q4 (−2048 to 2047.9375).
+
+## Depth and cards on top
+
+Every element takes an optional `depth` (−16..16 canvas px): a stereo disparity
+drawn on devices whose `session.capabilities.display.depth` is true, flat
+everywhere else. Positive floats the element in front of the frame. Elements
+still paint in array order, so a card that should sit on top of running content
+goes last in the array and at a positive depth. A `transition` animates a move
+or a depth change. This example moves a card within a G2-sized canvas:
+
+```ts
+import type {RenderElement} from "@glassly/miniapp/background"
+
+const content: RenderElement[] = [] // the rest of your scene
+const card = (x: number): RenderElement[] => [
+  {type: "rect" as const, id: "card", box: {x, y: 70, w: 300, h: 150},
+   style: {fill: true, color: 2, radius: 10}, depth: 8, transition: {durationMs: 350, easing: "ease-out"}},
+  {type: "text" as const, id: "card-title", box: {x: x + 16, y: 82, w: 268, h: 30}, text: "Incoming call",
+   style: {font: "builtin"}, depth: 8, transition: {durationMs: 350, easing: "ease-out"}},
+]
+await session.display.render([...content, ...card(20)]) // initial position
+await session.display.render([...content, ...card(252)]) // glides in, 8 px in front
+```
+
+The example miniapp's **Tester → cards + depth** suite exercises static depth,
+depth in motion, slide in/out, stacks and cache reopen.
+
+The host rejects paths exceeding 8,192 command bytes, 1,024 commands or 512
+flattened edges, and caps the scene at 4,096 path edges. Invalid/unsupported
+elements are reported in `RenderResult.dropped`.
+
+`rotation` uses unwrapped degrees (±36,000): 720 means two clockwise turns.
+`pivot` is a fixed point in canvas coordinates; it defaults to the target box's
+center. Rotation applies to rectangles, circles, lines, polygons, Béziers, arcs,
+pies and SVGs. Text and images do not rotate. Rotation duration is capped at
+65,535 ms; existing geometry tweens retain their 255-frame limit (about 8.4 s).
+Geometry and rotation run independently. Creating/replacing a path snaps;
+stable paths tween position, scale, color and rotation. Contour morphing is not
+implemented. The simulated display previews these transforms and transitions.
+
+### Glasses compass and light sensor
+
+`session.compass` is the one glasses heading API: subscribing runs the sensor
+(G2 custom firmware) or listens for the stock nav-mode heading; `start(options?)`
+/ `stop()` only set this miniapp's sampling override and the phone serves the
+tightest request across miniapps. The phone's own compass is
+`session.phone.heading`. `session.lightSensor` exposes `onUpdate`, `query`,
+`start(options?)`, and `stop` with one controlling miniapp. See
+[imu.md](../../../sdk/docs/imu.md) and [lightsensor.md](../../../sdk/docs/lightsensor.md)
+for units, options, ownership, and the example miniapp testers.

package/dist/background/index.d.ts

@@ -16,8 +16,10 @@
  */
 export { MiniappSession, type MiniappSessionOptions } from "../session";
 export { registerMiniapp, type MiniappInitHandler, type TypedMiniappSession } 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 { monoTextRows } from "../modules/mono-text-rows";
+export { LatestRenderScheduler } from "../modules/latest-render-scheduler";
+export type { TranscriptionData, TranslationData, ButtonPressData, AudioChunkData, VadData, BatteryData, ConnectionData, WifiData, HeadPositionData, AccelData, LocationData, PhoneNotificationData, NotificationDismissedData, HeadingData, TouchData, KeyboardEventData, UnsubscribeFn, } from "../modules/events";
+export type { CalendarEvent, CalendarListOptions, CalendarListResult, NotificationAppInfo } from "../modules/phone";
 export { MiniappRequestType, MiniappResponseType, MiniappStreamType, MiniappErrorCode } from "../protocol";
 export { MiniappValidationError, SUPPORTED_LANGUAGE_HINTS, SUPPORTED_TRANSCRIPTION_LANGUAGES, isTranscriptionLanguage, } from "../modules/languages";
 export type { LanguageHint, TranscriptionLanguage } from "../modules/languages";
@@ -27,9 +29,8 @@ export type { CameraFovPreset, CameraFovRequest, CameraFovResult, CameraModule,
 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 { InputModule, GestureClaimChange } from "../modules/input";
 export type { LedModule } from "../modules/led";
 export type { LocationModule } from "../modules/location";
 export type { MemoryModule, MemoryEntry, MemoryEntryKind, MemoryNoteSource, MemoryQuery, MemorySession, MemorySummary, } from "../modules/memory";
@@ -37,7 +38,8 @@ export type { SpeakersModule } from "../modules/speakers";
 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 { PhoneModule, PhoneHeadingModule } from "../modules/phone";
+export type { SettingsModule, SettingsChange } from "../modules/settings";
 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";
@@ -51,14 +53,18 @@ export type { UIModule, UIChannelHandler, UIUnsubscribe } from "../modules/ui";
 export type { Rpc, IsRpc, RpcReq, RpcRes, RpcRequestOptions, RpcHandlerContext } from "../modules/ui";
 export { RpcError, RpcTimeoutError } 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 { ViewType, DisplayBreakMode, RenderBox, RenderElement, RenderOptions, DisplayViewChange, DisplayViewChangeReason, ShowViewResult, RenderRectStyle, RenderResult, RenderTextStyle, } from "../modules/display";
 export type { DashboardMode, ShowNativeDashboardResult } from "../modules/dashboard";
 export type { PlayAudioOptions, SpeakOptions, SpeakResult, SpeakerState, SpeakerStateEvent } from "../modules/speaker";
-export type { ShareOptions, ShareResult, DownloadOptions, DownloadResult, ScanQrOptions, ScanQrResult, } from "../modules/system";
+export type { ShareOptions, ShareResult, DownloadOptions, DownloadResult, ScanQrOptions, ScanQrResult, DisplayDiagnostic, DisplayDiagnosticsResult, } 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 { AuthUpdatePayload, MiniappLaunchSource, 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, NavCancelled, NavUpdate, NavRoute, PivotOptions, Pivot, PivotEvent, NavStep, NavigationDev, StartNavigationOptions, NavState, NavPermissionResult, ComputeRouteOptions, ComputedRouteStep, ComputedRoute, ComputeRouteResult, } from "../modules/navigation";
+export type { LightSensorModule, LightSensorOptions, LightSensorData } from "../modules/lightSensor";
+export type { CompassModule, CompassOptions, CompassData, CompassDiagnostics, CompassCalibrationData, } from "../modules/compass";
+export type { MirrorModule } from "../modules/mirror";
+export type { MirrorSnapshot, MirrorContent, MirrorElement } from "../mirror/types";
 //# sourceMappingURL=index.d.ts.map

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

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

package/dist/background/index.js

@@ -16,6 +16,10 @@
  */
 export { MiniappSession } from "../session";
 export { registerMiniapp } from "./register";
+// Event / data type re-exports — these are payload shapes a miniapp's
+// background-side handlers consume from session.transcription.on, etc.
+export { monoTextRows } from "../modules/mono-text-rows";
+export { LatestRenderScheduler } from "../modules/latest-render-scheduler";
 // 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";

package/dist/background/index.js.map

@@ -1 +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,EAAoD,MAAM,YAAY,CAAA;AAwB7F,uEAAuE;AACvE,yEAAyE;AACzE,OAAO,EAAC,kBAAkB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,gBAAgB,EAAC,MAAM,aAAa,CAAA;AACxG,OAAO,EACL,sBAAsB,EACtB,wBAAwB,EACxB,iCAAiC,EACjC,uBAAuB,GACxB,MAAM,sBAAsB,CAAA;AA+C7B,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,QAAQ,EAAE,eAAe,EAAC,MAAM,eAAe,CAAA"}
+{"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,EAAoD,MAAM,YAAY,CAAA;AAE7F,sEAAsE;AACtE,uEAAuE;AACvE,OAAO,EAAC,YAAY,EAAC,MAAM,2BAA2B,CAAA;AACtD,OAAO,EAAC,qBAAqB,EAAC,MAAM,oCAAoC,CAAA;AAuBxE,uEAAuE;AACvE,yEAAyE;AACzE,OAAO,EAAC,kBAAkB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,gBAAgB,EAAC,MAAM,aAAa,CAAA;AACxG,OAAO,EACL,sBAAsB,EACtB,wBAAwB,EACxB,iCAAiC,EACjC,uBAAuB,GACxB,MAAM,sBAAsB,CAAA;AA+C7B,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,QAAQ,EAAE,eAAe,EAAC,MAAM,eAAe,CAAA"}

package/dist/background/register.d.ts

@@ -1,7 +1,7 @@
 /**
  * registerMiniapp — entry hook for the background JSContext.
  *
- * The GlasslyJS host loads the polyfill (which installs __dispatch /
+ * The JSRuntime 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.