@glassly/miniapp 0.3.0-dev.1

package/src/protocol.ts

@@ -0,0 +1,475 @@
+/**
+ * @fileoverview Wire protocol for @glassly/miniapp.
+ *
+ * Fresh miniapp-naming enum values. No legacy tpa_/app_/applet_ prefixes.
+ * These values are the contract between @glassly/miniapp (running in a WebView)
+ * and LocalMiniappRuntime (running on the phone).
+ *
+ * IMPORTANT: This file has NO runtime dependency on @glassly/sdk. The cloud SDK's
+ * wire protocol enums live in @glassly/sdk/types/message-types.ts and are used
+ * for cloud↔app communication, not phone↔miniapp.
+ */
+
+// ============================================================================
+// Miniapp → phone (request, via bridge envelope)
+// ============================================================================
+
+export enum MiniappRequestType {
+  /** Handshake: miniapp announces itself and asks phone to bind the session. */
+  CONNECT = "miniapp_connect",
+
+  /** Request a fresh miniapp-scoped backend auth token. */
+  AUTH_REFRESH = "miniapp_auth_refresh",
+
+  /** Update the set of streams the miniapp is subscribed to. */
+  SUBSCRIBE = "miniapp_subscribe",
+
+  /**
+   * Push a legacy display layout to the glasses. The SDK no longer emits this
+   * (render()/RENDER replaced it); hosts keep accepting it from bundles packed
+   * with older SDKs and from cloud-shaped layouts.
+   */
+  DISPLAY = "miniapp_display",
+
+  /** Render a whole scene of positioned elements (replace-the-frame). */
+  RENDER = "miniapp_render",
+
+  /**
+   * Feed the device's firmware-rendered navigation UI (capability
+   * `hasNativeNavigation`): structured turn-by-turn card fields and
+   * pre-rendered map bitmaps. Only accepted while a trip is active.
+   */
+  NATIVE_NAV = "miniapp_native_nav",
+
+  /** Play an arbitrary audio URL through the phone's audio playback service. */
+  PLAY_AUDIO = "miniapp_play_audio",
+
+  /** Stop any audio playback this miniapp initiated. */
+  STOP_AUDIO = "miniapp_stop_audio",
+
+  /** Speak text via cloud TTS — phone constructs the URL. */
+  SPEAK = "miniapp_speak",
+
+  /**
+   * Live PCM output stream to the phone's audio playback service
+   * (speaker.createStream). OPEN provisions a native chunk player; WRITE
+   * appends base64 PCM (replies with {bufferedMs} for backpressure); CLOSE
+   * drains and finishes; ABORT drops immediately.
+   */
+  SPEAKER_STREAM_OPEN = "miniapp_speaker_stream_open",
+  SPEAKER_STREAM_WRITE = "miniapp_speaker_stream_write",
+  SPEAKER_STREAM_CLOSE = "miniapp_speaker_stream_close",
+  SPEAKER_STREAM_ABORT = "miniapp_speaker_stream_abort",
+
+  /** Control the glasses RGB LED. */
+  RGB_LED = "miniapp_rgb_led",
+
+  /** One-shot location poll. */
+  LOCATION_POLL = "miniapp_location_poll",
+
+  /** Read a bounded snapshot of phone calendar events. */
+  CALENDAR_LIST_EVENTS = "miniapp_calendar_list_events",
+
+  /** Start a turn-by-turn navigation trip. Android only. */
+  NAVIGATION_START = "miniapp_navigation_start",
+  /** Stop the active navigation trip (if any). */
+  NAVIGATION_STOP = "miniapp_navigation_stop",
+  /** Dev-only: nudge the simulator off-route to test rerouting. Android sim only. */
+  NAVIGATION_DEVIATE = "miniapp_navigation_deviate",
+  /** Dev-only: lock simulated locations to the wrong sidewalk for pivot-trigger testing. */
+  NAVIGATION_SET_WRONG_SIDEWALK = "miniapp_navigation_set_wrong_sidewalk",
+  /** Dev-only: take over the simulator and walk a polyline with crossings stripped. */
+  NAVIGATION_SET_SKIP_CROSSINGS = "miniapp_navigation_set_skip_crossings",
+  /** Snapshot of the active trip (or null). Lets a miniapp opening mid-trip hydrate. */
+  NAVIGATION_GET_STATE = "miniapp_navigation_get_state",
+  /** Compute a route without starting a trip. Replaces hand-rolled Directions calls. */
+  NAVIGATION_COMPUTE_ROUTE = "miniapp_navigation_compute_route",
+  /** Reverse-geocode a coordinate to a short road name + full formatted
+   *  address. `road` backs the engine's fallback for pivots whose Routes-API
+   *  instruction didn't include a parseable road; `address` backs UI labels for
+   *  dropped pins / POI taps. Resolved in the v2 cloud maps service (Mapbox
+   *  today) via the host bridge — the miniapp never holds a maps token. */
+  NAVIGATION_REVERSE_GEOCODE = "miniapp_navigation_reverse_geocode",
+  /** Type-ahead place search (autocomplete). Resolved in the v2 cloud maps
+   *  service (Mapbox Search Box today) via the host bridge — the miniapp never
+   *  holds a maps token. Pairs with NAVIGATION_PLACE_DETAILS via a sessionToken. */
+  NAVIGATION_PLACE_AUTOCOMPLETE = "miniapp_navigation_place_autocomplete",
+  /** Resolve an autocomplete suggestion (placeId + sessionToken) to coordinates,
+   *  in the v2 cloud maps service via the host bridge. */
+  NAVIGATION_PLACE_DETAILS = "miniapp_navigation_place_details",
+  /** Request nav permission up-front so start() doesn't have to (no dialog under Mapbox). */
+  NAVIGATION_REQUEST_PERMISSION = "miniapp_navigation_request_permission",
+
+  /**
+   * Read a user-supplied provider API key (Settings > API Keys) by provider
+   * name. Requires the API_KEYS manifest permission; the host only serves an
+   * allowlisted provider set (see KeysModule) — notably the Soniox key is
+   * excluded. Keys are device-local; the value never transits any server.
+   */
+  KEYS_GET = "miniapp_keys_get",
+
+  /**
+   * Run one LLM completion turn through the platform. Requires the AI manifest
+   * permission. The host routes to the cloud LLM service, which picks the
+   * provider and pays with the platform key — or with the user's own key when
+   * they've saved one for that provider (Settings > API Keys), in which case
+   * the call isn't metered against their plan.
+   *
+   * Single-shot or a client-side tool loop: when the model wants a tool run,
+   * the result comes back with stopReason "tool_use" and the calls to execute;
+   * append the answers and call again. The `webSearch` flag grants the
+   * provider's own server-side search tool; other provider server-side tools
+   * (Anthropic code_execution / Files API) and streaming are deliberately not
+   * exposed — see cloud-v2/packages/protocol/src/llm.ts.
+   */
+  AI_COMPLETE = "miniapp_ai_complete",
+  AI_GENERATE = "miniapp_ai_generate",
+
+  /** Phone-local simple storage. */
+  STORAGE_GET = "miniapp_storage_get",
+  STORAGE_SET = "miniapp_storage_set",
+  STORAGE_DELETE = "miniapp_storage_delete",
+  STORAGE_LIST = "miniapp_storage_list",
+  STORAGE_CLEAR = "miniapp_storage_clear",
+  STORAGE_HAS = "miniapp_storage_has",
+  STORAGE_GET_ALL = "miniapp_storage_get_all",
+  STORAGE_SET_MULTIPLE = "miniapp_storage_set_multiple",
+  STORAGE_FLUSH = "miniapp_storage_flush",
+
+  /**
+   * Shared user-level memory timeline (transcript lines + notes + hourly
+   * summaries), stored host-side and scoped to the USER — not to this
+   * miniapp's storage namespace. Requires the MEMORY manifest permission.
+   * The user manages the same timeline in Settings > Memory.
+   */
+  MEMORY_APPEND_LINE = "miniapp_memory_append_line",
+  MEMORY_ADD_NOTE = "miniapp_memory_add_note",
+  MEMORY_REMOVE_ENTRY = "miniapp_memory_remove_entry",
+  MEMORY_REMOVE_SCOPE = "miniapp_memory_remove_scope",
+  MEMORY_SESSION_LIST = "miniapp_memory_session_list",
+  MEMORY_QUERY = "miniapp_memory_query",
+  MEMORY_WINDOW = "miniapp_memory_window",
+  MEMORY_EXPORT_TEXT = "miniapp_memory_export_text",
+  MEMORY_SUMMARY_ADD = "miniapp_memory_summary_add",
+  MEMORY_SUMMARY_LIST = "miniapp_memory_summary_list",
+  MEMORY_PENDING_SUMMARY_HOUR = "miniapp_memory_pending_summary_hour",
+  MEMORY_CLEAR = "miniapp_memory_clear",
+
+  /**
+   * Resolve an enrolled-speaker id (`spk_…` from TranscriptionData.speakerId)
+   * to the user's display name for that speaker. Requires the SPEAKERS
+   * manifest permission — names are on-device PII and only cross into a
+   * miniapp through this explicit, user-visible gate.
+   */
+  SPEAKERS_RESOLVE_NAME = "miniapp_speakers_resolve_name",
+
+  /** Write camera FOV settings. */
+  CAMERA_FOV = "miniapp_camera_fov",
+
+  /** Pre-warm the glasses camera so the next takePhoto() is near-instant. */
+  CAMERA_WARM_UP = "miniapp_camera_warm_up",
+
+  /**
+   * Enable/disable raw accelerometer (IMU) streaming on the glasses. The
+   * accel stream also auto-enables on subscribe; this is an explicit override
+   * for callers who want to control the sensor directly. G2 only today.
+   */
+  IMU_SET_ENABLED = "miniapp_imu_set_enabled",
+
+  /** Explicitly enable/disable glasses-side VAD (GX8002). Mirrors the app's mic settings toggle. */
+  MIC_SET_VAD_ENABLED = "miniapp_mic_set_vad_enabled",
+  /** Explicitly enable/disable the center-mic loudness gate ("Barrier"). */
+  MIC_SET_LOUDNESS_GATE_ENABLED = "miniapp_mic_set_loudness_gate_enabled",
+
+  /**
+   * Enable or disable Wi-Fi ADB (wireless debugging) on Mentra Live.
+   * SYSTEM-only — host rejects with NOT_PERMITTED for non-system callers.
+   */
+  SET_WIFI_ADB_STATE = "miniapp_set_wifi_adb_state",
+
+  /** Share content via the OS share sheet. */
+  SHARE = "miniapp_share",
+  /** Open a URL in the system browser. */
+  OPEN_URL = "miniapp_open_url",
+  /** Copy text to the system clipboard. */
+  COPY_CLIPBOARD = "miniapp_copy_clipboard",
+  /** Download a file (triggers OS share sheet for save location). */
+  DOWNLOAD = "miniapp_download",
+  /**
+   * Open a phone-camera QR scanner overlay. Host must not unmount the miniapp
+   * (clearing foreground fires UI_CLOSE and can hang up live sessions).
+   */
+  SCAN_QR = "miniapp_scan_qr",
+
+  /**
+   * Phone-local persistent binary blob storage, scoped to (userId, packageName).
+   * Unlike STORAGE_* (small string KV in MMKV), blobs are arbitrary bytes written
+   * to the phone filesystem. Large payloads are moved in chunks (BLOB_WRITE /
+   * BLOB_READ) so a single bridge message never carries a multi-MB string.
+   */
+  BLOB_CREATE = "miniapp_blob_create",
+  BLOB_WRITE = "miniapp_blob_write",
+  BLOB_COMMIT = "miniapp_blob_commit",
+  BLOB_ABORT = "miniapp_blob_abort",
+  BLOB_GET = "miniapp_blob_get",
+  BLOB_LIST = "miniapp_blob_list",
+  BLOB_DELETE = "miniapp_blob_delete",
+  BLOB_CLEAR = "miniapp_blob_clear",
+  BLOB_USAGE = "miniapp_blob_usage",
+  BLOB_OPEN_READ = "miniapp_blob_open_read",
+  BLOB_READ = "miniapp_blob_read",
+  BLOB_CLOSE_READ = "miniapp_blob_close_read",
+  /** Download a URL straight into a blob, host-side (no bytes cross the bridge). */
+  BLOB_SET_FROM_URL = "miniapp_blob_set_from_url",
+  /** Open the OS file picker and import the chosen file into a blob, host-side. */
+  BLOB_IMPORT = "miniapp_blob_import",
+  /** Share a stored blob from disk via the OS share sheet (no bytes cross the bridge). */
+  BLOB_SHARE = "miniapp_blob_share",
+
+  /** Phone → miniapp liveness probe. Miniapp SDK auto-replies with PONG. */
+  PING = "miniapp_ping",
+
+  /**
+   * Apply transcription configuration (language hints, vocabulary, diarization).
+   * Phone forwards to the cloud STT layer. Fire-and-forget; cached client-side
+   * so future reconnect logic can re-send.
+   */
+  TRANSCRIPTION_CONFIG = "miniapp_transcription_config",
+
+  // ----- Deferred in v1 -----
+
+  /** Dashboard content update. Noop in v1. */
+  DASHBOARD_CONTENT_UPDATE = "miniapp_dashboard_content_update",
+
+  /** Bring the glasses' native dashboard (OS idle screen) to the foreground. */
+  SHOW_NATIVE_DASHBOARD = "miniapp_show_native_dashboard",
+
+  // ----- Photos, streaming -----
+  PHOTO = "miniapp_photo",
+  VIDEO_RECORDING_START = "miniapp_video_recording_start",
+  VIDEO_RECORDING_STOP = "miniapp_video_recording_stop",
+  STREAM_START = "miniapp_stream_start",
+  STREAM_STOP = "miniapp_stream_stop",
+  MANAGED_STREAM_START = "miniapp_managed_stream_start",
+  MANAGED_STREAM_STOP = "miniapp_managed_stream_stop",
+
+  /** Ask the host to open the glasses Wi-Fi setup flow (mirrors the cloud SDK's requestWifiSetup). */
+  REQUEST_WIFI_SETUP = "miniapp_request_wifi_setup",
+
+  // ----- Inter-miniapp interop -----
+  // Lifecycle control (MINIAPPS_*) stays SYSTEM-only; the action layer
+  // (ACTIONS_LIST / ACTION_INVOKE) is open to every miniapp, gated per-action
+  // by the target's manifest `visibility`.
+  /** List installed miniapps (compatibility-filtered, with declared actions). SYSTEM-only. */
+  MINIAPPS_LIST = "miniapp_apps_list",
+  /** Start another miniapp (user-tap semantics). SYSTEM-only. */
+  MINIAPPS_START = "miniapp_apps_start",
+  /** Stop another miniapp. SYSTEM-only. */
+  MINIAPPS_STOP = "miniapp_apps_stop",
+  /** Stop the CALLING miniapp itself. One-shot (no reply) and NOT system-gated. */
+  MINIAPPS_STOP_SELF = "miniapp_apps_stop_self",
+  /** List every action the caller may invoke across installed miniapps (MCP tools/list analog). */
+  ACTIONS_LIST = "miniapp_actions_list",
+  /** Invoke a declared action on another miniapp; headless-wakes it if stopped. */
+  ACTION_INVOKE = "miniapp_action_invoke",
+  /** Target → host: the result of a delivered ACTION_CALL, correlated by callId. */
+  ACTION_RESULT = "miniapp_action_result",
+  /** Ask the host to stop THIS miniapp (self-close; e.g. after finishing a one-shot action). */
+  SYSTEM_EXIT = "miniapp_system_exit",
+}
+
+// ============================================================================
+// Phone → miniapp (response or push)
+// ============================================================================
+
+export enum MiniappResponseType {
+  /** Response to CONNECT carrying userId, packageName, capabilities. */
+  CONNECT_ACK = "miniapp_connect_ack",
+
+  /** Push: a streamed event for a subscribed stream. */
+  EVENT = "miniapp_event",
+
+  /** Response to any request that needs a result (matched by requestId). */
+  REQUEST_RESULT = "miniapp_request_result",
+
+  /** Push: glasses capabilities changed. */
+  CAPABILITIES_UPDATE = "miniapp_capabilities_update",
+
+  /** Push: miniapp's foreground/background state changed. */
+  VISIBILITY_CHANGE = "miniapp_visibility_change",
+
+  /** Push: host color scheme (light/dark) changed. */
+  COLOR_SCHEME_CHANGE = "miniapp_color_scheme_change",
+
+  /**
+   * Push: speaker playback state transitioned. Per-miniapp; the runtime sends
+   * to the owning miniapp only. Carries {state, errorCode?, errorMessage?,
+   * durationMs?}. See SpeakerModule.onStateChange().
+   */
+  SPEAKER_STATE = "miniapp_speaker_state",
+
+  /**
+   * Push: manifest-declared permissions changed (e.g. dev miniapp re-scanned
+   * with updated manifest). Carries a full PermissionRecord. SDK caches it
+   * and fires session.permissions.onUpdate handlers.
+   */
+  PERMISSIONS_UPDATE = "miniapp_permissions_update",
+
+  /**
+   * Push: miniapp-scoped backend auth token changed. Carries a token minted for
+   * this packageName only; it is never a Core or runtime access token.
+   */
+  AUTH_UPDATE = "miniapp_auth_update",
+
+  /** Reply to PING. SDK auto-handles this; developers never see it. */
+  PONG = "miniapp_pong",
+
+  /**
+   * Host → target: deliver an action call (from another miniapp's
+   * session.actions.invoke) to this miniapp's session.actions.handle handler.
+   * Carries {callId, actionId, params, callerPackageName}. The SDK runs the
+   * handler and replies with an ACTION_RESULT request keyed by callId.
+   */
+  ACTION_CALL = "miniapp_action_call",
+
+  /**
+   * Push: phone is about to tear down the miniapp's session. Gives the SDK
+   * a brief window (~50ms grace on the phone side) to fire one last
+   * `sendOneShot` before the transport closes — used to flush final
+   * cleanup like `display.render([])`. Synchronous handlers only.
+   */
+  WILL_DISCONNECT = "miniapp_will_disconnect",
+
+  /** Async error not tied to a specific request. */
+  ERROR = "miniapp_error",
+}
+
+// ============================================================================
+// Stream types a miniapp can subscribe to
+// ============================================================================
+
+export enum MiniappStreamType {
+  // Hardware / input events
+  BUTTON_PRESS = "button_press",
+  TOUCH_EVENT = "touch_event",
+  HEAD_POSITION = "head_position",
+  /**
+   * Raw accelerometer reading from the glasses IMU — `{x, y, z}` in g, plus a
+   * timestamp. G2 only today. A richer combined IMU stream (accel + gyro +
+   * magnetometer) is future work; this is the single-sensor precursor.
+   */
+  ACCEL_DATA = "accel_data",
+
+  // Status
+  GLASSES_BATTERY = "glasses_battery",
+  PHONE_BATTERY = "phone_battery",
+  GLASSES_CONNECTION = "glasses_connection",
+  /** Glasses Wi-Fi state (connected/ssid). Glasses with Wi-Fi only; needed for streaming. */
+  GLASSES_WIFI = "glasses_wifi",
+
+  // Speech / audio (cloud or local)
+  TRANSCRIPTION = "transcription", // language variant: "transcription:en-US"
+  TRANSLATION = "translation", // language variant: "translation:en-US"
+  AUDIO_CHUNK = "audio_chunk",
+  VAD = "vad",
+
+  // Phone sensors
+  LOCATION_UPDATE = "location_update",
+  /** Compass heading in degrees (0=N, 90=E). */
+  HEADING_UPDATE = "heading_update",
+  /** Turn-by-turn navigation event (maneuver / rerouting / arrived / error). */
+  NAVIGATION_UPDATE = "navigation_update",
+  /** Active navigation route polyline — full path, fired once per route build. */
+  NAVIGATION_ROUTE = "navigation_route",
+  PHONE_NOTIFICATION = "phone_notification",
+  /**
+   * A previously-posted notification was dismissed by the user.
+   *
+   * Android-only today. iOS does not expose dismiss callbacks to apps
+   * (Apple privacy restriction); subscribing on iOS succeeds but no events
+   * fire. See agents/miniapp-speaker-state-and-notif-dismissed-plan.md.
+   */
+  PHONE_NOTIFICATION_DISMISSED = "phone_notification_dismissed",
+  // Photos, streaming
+  PHOTO_TAKEN = "photo_taken",
+  STREAM_STATUS = "stream_status",
+}
+
+// ============================================================================
+// Error codes
+// ============================================================================
+
+export enum MiniappErrorCode {
+  /** Request arguments failed host-side validation. */
+  INVALID_ARGUMENT = "INVALID_ARGUMENT",
+
+  /** The miniapp subscribed to a stream whose required permission wasn't in its manifest. */
+  PERMISSION_NOT_DECLARED = "PERMISSION_NOT_DECLARED",
+
+  /** The required phone OS permission is not currently granted. */
+  PERMISSION_DENIED = "PERMISSION_DENIED",
+
+  /** Request routed to a method that isn't supported yet. */
+  NOT_IMPLEMENTED = "NOT_IMPLEMENTED",
+
+  /** Request timed out or the session was torn down before it could complete. */
+  REQUEST_ABORTED = "REQUEST_ABORTED",
+
+  /** Phone-side code path threw. Check `message`. */
+  INTERNAL = "INTERNAL",
+
+  /**
+   * The account's free-tier allowance for this feature (e.g. monthly AI
+   * credit) is used up. Not retryable this period; the user can upgrade or
+   * the miniapp can fall back to a non-cloud path.
+   */
+  QUOTA_EXCEEDED = "QUOTA_EXCEEDED",
+
+  /** Cloud TTS returned a non-2xx for a SPEAK request. */
+  TTS_TEXT_TOO_LONG = "TTS_TEXT_TOO_LONG",
+  TTS_INVALID_VOICE = "TTS_INVALID_VOICE",
+  TTS_UPSTREAM_ERROR = "TTS_UPSTREAM_ERROR",
+
+  /** `speak({forceLocal: true})` but the on-device offline TTS model isn't downloaded/ready. */
+  TTS_LOCAL_UNAVAILABLE = "TTS_LOCAL_UNAVAILABLE",
+
+  /** Not connected / pre-ACK and transport closed. */
+  NOT_CONNECTED = "NOT_CONNECTED",
+
+  // ----- Inter-miniapp interop -----
+  /**
+   * Caller is not a system app — SYSTEM-only APIs (interop list/start/stop/invoke,
+   * setWifiAdbState) reject with this code.
+   */
+  NOT_PERMITTED = "NOT_PERMITTED",
+  /** Target miniapp is not installed. */
+  APP_NOT_FOUND = "APP_NOT_FOUND",
+  /** Target miniapp is incompatible with the connected glasses. */
+  APP_NOT_COMPATIBLE = "APP_NOT_COMPATIBLE",
+  /** Target miniapp does not declare the requested action. */
+  ACTION_NOT_FOUND = "ACTION_NOT_FOUND",
+  /** Target connected but never registered a handler for the action (within the buffer window). */
+  NO_ACTION_HANDLER = "NO_ACTION_HANDLER",
+  /** Target failed to wake / complete its CONNECT handshake for an invoke. */
+  WAKE_FAILED = "WAKE_FAILED",
+  /** Action handler did not return within the caller's timeout. */
+  ACTION_TIMEOUT = "ACTION_TIMEOUT",
+  /** Action params or result exceeded the 256 KB size cap. */
+  PAYLOAD_TOO_LARGE = "PAYLOAD_TOO_LARGE",
+
+  // ----- Blob storage / recorder -----
+  /** No blob with the given id in this miniapp's namespace. */
+  BLOB_NOT_FOUND = "BLOB_NOT_FOUND",
+  /** Writing this blob would exceed the per-app blob quota. */
+  BLOB_QUOTA_EXCEEDED = "BLOB_QUOTA_EXCEEDED",
+  /** Blob is larger than the requested in-memory read can hold. */
+  BLOB_TOO_LARGE = "BLOB_TOO_LARGE",
+  /** Write/read handle is unknown, already settled, or belongs to another app. */
+  BLOB_HANDLE_INVALID = "BLOB_HANDLE_INVALID",
+  /** Filesystem write failed (out of disk, permissions, etc.). */
+  BLOB_WRITE_FAILED = "BLOB_WRITE_FAILED",
+  /** `blob.setFromUrl` could not download the URL (network / non-2xx). */
+  BLOB_DOWNLOAD_FAILED = "BLOB_DOWNLOAD_FAILED",
+  /** `blob.importFile` failed (not the user cancelling — that resolves to null). */
+  BLOB_IMPORT_FAILED = "BLOB_IMPORT_FAILED",
+}

package/src/react/MiniappHeader.tsx

@@ -0,0 +1,114 @@
+/**
+ * @fileoverview MiniappHeader — drop-in header component that aligns with
+ * the host's floating capsule menu.
+ *
+ * The header has three slots: `left`, `title`, and `right`. Content auto-
+ * respects the safe area and leaves room for the capsule menu on the far
+ * top-right. Typical usage:
+ *
+ *   <MiniappHeader
+ *     title="My Miniapp"
+ *     left={<BackButton onClick={goBack} />}
+ *     right={<Badge>Connected</Badge>}
+ *   />
+ *
+ * If `title` is a string it renders as a semantic <h1>. Pass a ReactNode if
+ * you need custom styling. The component itself is unstyled beyond the
+ * layout — use `className` or `style` for theming.
+ */
+
+import type {CSSProperties, ReactNode} from "react"
+
+import {useCapsuleHeaderStyle, type UseCapsuleHeaderStyleOptions} from "./useCapsuleHeaderStyle"
+
+export interface MiniappHeaderProps extends UseCapsuleHeaderStyleOptions {
+  /** Title — string renders as <h1>; pass a node for custom markup. */
+  title?: ReactNode
+  /** Left slot, typically a back button or logo. Overrides onBack if both set. */
+  left?: ReactNode
+  /**
+   * Shortcut: when provided, renders a back chevron in the left slot that
+   * calls this handler. Ignored if `left` is explicitly set.
+   */
+  onBack?: () => void
+  /** Right slot, typically a badge or action buttons. Sits to the left of the capsule. */
+  right?: ReactNode
+  /** Custom className applied to the header element. */
+  className?: string
+  /** Inline style overrides merged over the computed layout style. */
+  style?: CSSProperties
+  /**
+   * When true, adds a 8px spacer <div> below the header so your next
+   * content doesn't sit flush against it. Default true.
+   */
+  bottomSpacer?: boolean
+}
+
+function BackChevron({onBack}: {onBack: () => void}): ReactNode {
+  return (
+    <button
+      type="button"
+      onClick={onBack}
+      aria-label="Back"
+      style={{
+        display: "inline-flex",
+        alignItems: "center",
+        justifyContent: "center",
+        width: 32,
+        height: 32,
+        marginLeft: -8,
+        padding: 0,
+        border: "none",
+        background: "transparent",
+        color: "inherit",
+        cursor: "pointer",
+        borderRadius: 8,
+      }}>
+      <svg width="22" height="22" viewBox="0 0 24 24" fill="none" aria-hidden="true">
+        <path d="M15 18l-6-6 6-6" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" />
+      </svg>
+    </button>
+  )
+}
+
+export function MiniappHeader({
+  title,
+  left,
+  onBack,
+  right,
+  className,
+  style,
+  bottomSpacer = true,
+  ...styleOptions
+}: MiniappHeaderProps): ReactNode {
+  const computedStyle = useCapsuleHeaderStyle(styleOptions)
+  const resolvedLeft = left ?? (onBack ? <BackChevron onBack={onBack} /> : null)
+
+  return (
+    <>
+      <header className={className} style={{...computedStyle, ...style}}>
+        <div style={{display: "flex", alignItems: "center", gap: 10, minWidth: 0, flex: 1}}>
+          {resolvedLeft}
+          {typeof title === "string" ? (
+            <h1
+              style={{
+                fontSize: 18,
+                fontWeight: 600,
+                lineHeight: 1,
+                margin: 0,
+                whiteSpace: "nowrap",
+                overflow: "hidden",
+                textOverflow: "ellipsis",
+              }}>
+              {title}
+            </h1>
+          ) : (
+            title
+          )}
+        </div>
+        {right ? <div style={{display: "flex", alignItems: "center", gap: 8, flexShrink: 0}}>{right}</div> : null}
+      </header>
+      {bottomSpacer ? <div style={{height: 8, flexShrink: 0}} /> : null}
+    </>
+  )
+}

package/src/react/MiniappProvider.tsx

@@ -0,0 +1,50 @@
+/**
+ * @fileoverview MiniappProvider — optional root provider for miniapp apps.
+ *
+ * Opt-in conveniences that would otherwise require boilerplate in every
+ * miniapp. Currently:
+ *   - Keeps `<html class="dark">` in sync with the host's color scheme so the
+ *     shared theme CSS switches automatically.
+ *
+ * Usage:
+ *   createRoot(root).render(
+ *     <MiniappProvider>
+ *       <App />
+ *     </MiniappProvider>
+ *   )
+ *
+ * Each convenience is controllable via props so miniapps that manage these
+ * things themselves can opt out without forking the provider.
+ */
+
+import {type ReactNode} from "react"
+
+import {useColorScheme} from "./useColorScheme"
+
+export interface MiniappProviderProps {
+  children: ReactNode
+  /**
+   * Toggle `document.documentElement.classList` "dark" to match the host's
+   * current color scheme. The toggle runs synchronously during render so
+   * children paint with the correct class on first mount — no flash.
+   *
+   * Default: true. Set to false if your app owns the `dark` class itself
+   * (e.g. you integrate a theming library like next-themes).
+   */
+  syncColorScheme?: boolean
+}
+
+export function MiniappProvider({children, syncColorScheme = true}: MiniappProviderProps) {
+  const scheme = useColorScheme()
+
+  // Runs during render — before children paint, before effects fire.
+  if (syncColorScheme && typeof document !== "undefined") {
+    const el = document.documentElement
+    const shouldBeDark = scheme === "dark"
+    if (el.classList.contains("dark") !== shouldBeDark) {
+      el.classList.toggle("dark", shouldBeDark)
+    }
+  }
+
+  return <>{children}</>
+}

package/src/react/capsuleHeaderLayout.ts

@@ -0,0 +1,11 @@
+import type {MiniappCapsuleMenuRect} from "../globals"
+
+export function getCapsuleHeaderPaddingRight(
+  capsuleMenu: MiniappCapsuleMenuRect,
+  viewportWidth: number,
+  safeAreaRight: number,
+  rightGap: number,
+): number {
+  const capsuleOffsetFromContentRight = viewportWidth - capsuleMenu.left - safeAreaRight
+  return Math.max(rightGap, capsuleOffsetFromContentRight + rightGap)
+}

package/src/react/index.ts

@@ -0,0 +1,12 @@
+export {useSafeArea} from "./useSafeArea"
+export type {UseSafeAreaResult} from "./useSafeArea"
+export {useColorScheme} from "./useColorScheme"
+export {useCapabilities} from "./useCapabilities"
+export {useConnected} from "./useConnected"
+export {useCapsuleHeaderStyle} from "./useCapsuleHeaderStyle"
+export type {UseCapsuleHeaderStyleOptions} from "./useCapsuleHeaderStyle"
+export {MiniappHeader} from "./MiniappHeader"
+export type {MiniappHeaderProps} from "./MiniappHeader"
+export {MiniappProvider} from "./MiniappProvider"
+export type {MiniappProviderProps} from "./MiniappProvider"
+export {useRpc, type RpcCallable} from "./useRpc"