@mentra/miniapp 0.3.0-dev.0

package/src/protocol.ts

@@ -0,0 +1,371 @@
+/**
+ * @fileoverview Wire protocol for @mentra/miniapp.
+ *
+ * Fresh miniapp-naming enum values. No legacy tpa_/app_/applet_ prefixes.
+ * These values are the contract between @mentra/miniapp (running in a WebView)
+ * and LocalMiniappRuntime (running on the phone).
+ *
+ * IMPORTANT: This file has NO runtime dependency on @mentra/sdk. The cloud SDK's
+ * wire protocol enums live in @mentra/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",
+
+  /** 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",
+
+  /** 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",
+  /** Trigger the Google Nav SDK T&C dialog up-front so start() doesn't have to. */
+  NAVIGATION_REQUEST_PERMISSION = "miniapp_navigation_request_permission",
+
+  /** 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",
+
+  /** 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",
+
+  /** 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",
+
+  /**
+   * 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",
+
+  // ----- 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 (SYSTEM apps only) -----
+  /** List installed miniapps (compatibility-filtered, with declared actions). */
+  MINIAPPS_LIST = "miniapp_apps_list",
+  /** Start another miniapp (user-tap semantics). */
+  MINIAPPS_START = "miniapp_apps_start",
+  /** Stop another miniapp. */
+  MINIAPPS_STOP = "miniapp_apps_stop",
+  /** 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",
+}
+
+// ============================================================================
+// 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). Android only. */
+  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",
+  CALENDAR_EVENT = "calendar_event",
+
+  // 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",
+
+  /** 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",
+
+  /** 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",
+
+  /** Not connected / pre-ACK and transport closed. */
+  NOT_CONNECTED = "NOT_CONNECTED",
+
+  // ----- Inter-miniapp interop -----
+  /** Caller is not a system app — interop APIs (list/start/stop/invoke) are SYSTEM-only. */
+  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/MentraProvider.tsx

@@ -0,0 +1,50 @@
+/**
+ * @fileoverview MentraProvider — 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(
+ *     <MentraProvider>
+ *       <App />
+ *     </MentraProvider>
+ *   )
+ *
+ * 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 MentraProviderProps {
+  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 MentraProvider({children, syncColorScheme = true}: MentraProviderProps) {
+  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/MiniappHeader.tsx

@@ -0,0 +1,122 @@
+/**
+ * @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/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 {MentraProvider} from "./MentraProvider"
+export type {MentraProviderProps} from "./MentraProvider"
+export {useRpc, type RpcCallable} from "./useRpc"

package/src/react/useCapabilities.ts

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview useCapabilities — React hook for the connected glasses'
+ * capability profile.
+ *
+ * The glasses `GlassesCapabilities` profile is *background-only* state: it
+ * arrives on the background `MiniappSession` (CONNECT_ACK / CAPABILITIES_UPDATE)
+ * and is never injected into the UI WebView, so there is no WebView-side source
+ * for it — this hook always returns `null`.
+ *
+ * If a UI page needs glasses capabilities, relay them from the background half
+ * over an app channel: read `session.capabilities` in a `session.ui.onOpen`
+ * handler, `session.ui.send("caps", ...)`, then read it in the UI with
+ * `mentra.on("caps", ...)`. See the example miniapp's `captions:snapshot`
+ * channel for the pattern.
+ *
+ * IMPORTANT: this hook must NOT construct a `MiniappSession`. That is the
+ * *background* (JSContext) API; inside a UI WebView its `CONNECT` never gets an
+ * ACK from the host's UI router and `session.connect()` times out
+ * ("CONNECT_ACK timeout") — the original reason this hook was rewritten.
+ *
+ * (Note: `window.MentraOS.capabilities` is a different thing — host *feature*
+ * flags like "share" / "open_url", not the glasses hardware profile.)
+ */
+
+import {type GlassesCapabilities} from "../session"
+
+export function useCapabilities(): GlassesCapabilities | null {
+  return null
+}

package/src/react/useCapsuleHeaderStyle.ts

@@ -0,0 +1,54 @@
+/**
+ * @fileoverview useCapsuleHeaderStyle — ready-to-spread React CSS props that
+ * vertically align a header row with the host's floating capsule menu.
+ *
+ * Use this when you want full control over header markup but want the
+ * alignment math done for you. If you just want a stock header, use
+ * <MiniappHeader> instead.
+ *
+ * Example:
+ *   const style = useCapsuleHeaderStyle()
+ *   <header style={style}>
+ *     <h1>Hello</h1>
+ *   </header>
+ */
+
+import type {CSSProperties} from "react"
+
+import {useSafeArea} from "./useSafeArea"
+
+export interface UseCapsuleHeaderStyleOptions {
+  /** Extra left padding beyond the safe area. Default 20px. */
+  leftPadding?: number
+  /** Extra space between the header content and the capsule menu. Default 16px. */
+  rightGap?: number
+  /** Fallback header height when no capsule menu is present. Default 32px. */
+  fallbackHeight?: number
+  /** Fallback top margin when no capsule menu is present. Default 16px. */
+  fallbackMarginTop?: number
+}
+
+export function useCapsuleHeaderStyle(
+  options: UseCapsuleHeaderStyleOptions = {},
+): CSSProperties {
+  const {leftPadding = 20, rightGap = 16, fallbackHeight = 32, fallbackMarginTop = 16} = options
+  const {insets, capsuleMenu} = useSafeArea()
+
+  const height = capsuleMenu?.height ?? fallbackHeight
+  const center = capsuleMenu
+    ? capsuleMenu.top + capsuleMenu.height / 2 - insets.top
+    : fallbackMarginTop + height / 2
+  const marginTop = Math.max(0, center - height / 2)
+  const paddingRight = capsuleMenu ? capsuleMenu.width + rightGap : leftPadding
+
+  return {
+    display: "flex",
+    flexShrink: 0,
+    alignItems: "center",
+    justifyContent: "space-between",
+    paddingLeft: leftPadding,
+    paddingRight,
+    marginTop,
+    height,
+  }
+}

package/src/react/useColorScheme.ts

@@ -0,0 +1,26 @@
+/**
+ * @fileoverview useColorScheme — React hook that returns the host's current
+ * color scheme.
+ *
+ * WebView-side hook: reads `window.MentraOS.colorScheme`, injected by the host
+ * before the miniapp's content loads. Like `useSafeArea`, this is read once at
+ * mount — the host doesn't push color-scheme changes to the WebView at runtime;
+ * flipping the phone's theme forces a reload.
+ *
+ * IMPORTANT: this hook must NOT construct a `MiniappSession`. `MiniappSession`
+ * is the *background* (JSContext) API; inside a UI WebView its transport falls
+ * back to PostMessage and its `CONNECT` never gets an ACK from the host's UI
+ * router, so `session.connect()` times out ("CONNECT_ACK timeout"). UI hooks
+ * read host-injected globals instead (see `useSafeArea`).
+ */
+
+import {useState} from "react"
+
+import {getMentraOSGlobals, type MiniappColorScheme} from "../globals"
+
+export function useColorScheme(): MiniappColorScheme {
+  const [scheme] = useState<MiniappColorScheme>(() => {
+    return getMentraOSGlobals().colorScheme === "dark" ? "dark" : "light"
+  })
+  return scheme
+}