@mentra/miniapp 0.3.0-beta.0

package/dist/react/useCapsuleHeaderStyle.js

@@ -0,0 +1,36 @@
+/**
+ * @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 { useSafeArea } from "./useSafeArea";
+export function useCapsuleHeaderStyle(options = {}) {
+    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,
+    };
+}
+//# sourceMappingURL=useCapsuleHeaderStyle.js.map

package/dist/react/useCapsuleHeaderStyle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCapsuleHeaderStyle.js","sourceRoot":"","sources":["../../src/react/useCapsuleHeaderStyle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,EAAC,WAAW,EAAC,MAAM,eAAe,CAAA;AAazC,MAAM,UAAU,qBAAqB,CACnC,UAAwC,EAAE;IAE1C,MAAM,EAAC,WAAW,GAAG,EAAE,EAAE,QAAQ,GAAG,EAAE,EAAE,cAAc,GAAG,EAAE,EAAE,iBAAiB,GAAG,EAAE,EAAC,GAAG,OAAO,CAAA;IAC9F,MAAM,EAAC,MAAM,EAAE,WAAW,EAAC,GAAG,WAAW,EAAE,CAAA;IAE3C,MAAM,MAAM,GAAG,WAAW,EAAE,MAAM,IAAI,cAAc,CAAA;IACpD,MAAM,MAAM,GAAG,WAAW;QACxB,CAAC,CAAC,WAAW,CAAC,GAAG,GAAG,WAAW,CAAC,MAAM,GAAG,CAAC,GAAG,MAAM,CAAC,GAAG;QACvD,CAAC,CAAC,iBAAiB,GAAG,MAAM,GAAG,CAAC,CAAA;IAClC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,CAAC,CAAC,CAAA;IAClD,MAAM,YAAY,GAAG,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,GAAG,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAA;IAE7E,OAAO;QACL,OAAO,EAAE,MAAM;QACf,UAAU,EAAE,CAAC;QACb,UAAU,EAAE,QAAQ;QACpB,cAAc,EAAE,eAAe;QAC/B,WAAW,EAAE,WAAW;QACxB,YAAY;QACZ,SAAS;QACT,MAAM;KACP,CAAA;AACH,CAAC"}

package/dist/react/useColorScheme.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @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 { type MiniappColorScheme } from "../globals";
+export declare function useColorScheme(): MiniappColorScheme;
+//# sourceMappingURL=useColorScheme.d.ts.map

package/dist/react/useColorScheme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useColorScheme.d.ts","sourceRoot":"","sources":["../../src/react/useColorScheme.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,EAAqB,KAAK,kBAAkB,EAAC,MAAM,YAAY,CAAA;AAEtE,wBAAgB,cAAc,IAAI,kBAAkB,CAKnD"}

package/dist/react/useColorScheme.js

@@ -0,0 +1,24 @@
+/**
+ * @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 } from "../globals";
+export function useColorScheme() {
+    const [scheme] = useState(() => {
+        return getMentraOSGlobals().colorScheme === "dark" ? "dark" : "light";
+    });
+    return scheme;
+}
+//# sourceMappingURL=useColorScheme.js.map

package/dist/react/useColorScheme.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useColorScheme.js","sourceRoot":"","sources":["../../src/react/useColorScheme.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAC,QAAQ,EAAC,MAAM,OAAO,CAAA;AAE9B,OAAO,EAAC,kBAAkB,EAA0B,MAAM,YAAY,CAAA;AAEtE,MAAM,UAAU,cAAc;IAC5B,MAAM,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAqB,GAAG,EAAE;QACjD,OAAO,kBAAkB,EAAE,CAAC,WAAW,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAA;IACvE,CAAC,CAAC,CAAA;IACF,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/react/useConnected.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @fileoverview useConnected — React hook that returns true while the miniapp's
+ * UI WebView is bridged to its background JSContext.
+ *
+ * WebView-side hook. "Connected" here means the `window.mentra` bridge is open:
+ * the shim has fired `mentra.ready()` and the host has bound the WebView so
+ * `mentra.send/on/request` flow. Tracked via the shim's `onOpen` / `onClose`.
+ * `onOpen` fires its callback immediately if the bridge is already open (see
+ * the shim), so late mounts still observe the connected state.
+ *
+ * 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").
+ */
+export declare function useConnected(): boolean;
+//# sourceMappingURL=useConnected.d.ts.map

package/dist/react/useConnected.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useConnected.d.ts","sourceRoot":"","sources":["../../src/react/useConnected.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAcH,wBAAgB,YAAY,IAAI,OAAO,CAkBtC"}

package/dist/react/useConnected.js

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview useConnected — React hook that returns true while the miniapp's
+ * UI WebView is bridged to its background JSContext.
+ *
+ * WebView-side hook. "Connected" here means the `window.mentra` bridge is open:
+ * the shim has fired `mentra.ready()` and the host has bound the WebView so
+ * `mentra.send/on/request` flow. Tracked via the shim's `onOpen` / `onClose`.
+ * `onOpen` fires its callback immediately if the bridge is already open (see
+ * the shim), so late mounts still observe the connected state.
+ *
+ * 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").
+ */
+import { useEffect, useState } from "react";
+function getBridge() {
+    if (typeof window === "undefined")
+        return null;
+    return window.mentra ?? null;
+}
+export function useConnected() {
+    const [connected, setConnected] = useState(false);
+    useEffect(() => {
+        const bridge = getBridge();
+        if (!bridge)
+            return;
+        // onOpen fires immediately when the bridge is already open, so this also
+        // seeds the initial value without a separate synchronous read.
+        const offOpen = bridge.onOpen?.(() => setConnected(true));
+        const offClose = bridge.onClose?.(() => setConnected(false));
+        return () => {
+            offOpen?.();
+            offClose?.();
+        };
+    }, []);
+    return connected;
+}
+//# sourceMappingURL=useConnected.js.map

package/dist/react/useConnected.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useConnected.js","sourceRoot":"","sources":["../../src/react/useConnected.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAC,SAAS,EAAE,QAAQ,EAAC,MAAM,OAAO,CAAA;AAOzC,SAAS,SAAS;IAChB,IAAI,OAAO,MAAM,KAAK,WAAW;QAAE,OAAO,IAAI,CAAA;IAC9C,OAAQ,MAA6C,CAAC,MAAM,IAAI,IAAI,CAAA;AACtE,CAAC;AAED,MAAM,UAAU,YAAY;IAC1B,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,GAAG,QAAQ,CAAU,KAAK,CAAC,CAAA;IAE1D,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,MAAM,GAAG,SAAS,EAAE,CAAA;QAC1B,IAAI,CAAC,MAAM;YAAE,OAAM;QAEnB,yEAAyE;QACzE,+DAA+D;QAC/D,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAA;QACzD,MAAM,QAAQ,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAA;QAC5D,OAAO,GAAG,EAAE;YACV,OAAO,EAAE,EAAE,CAAA;YACX,QAAQ,EAAE,EAAE,CAAA;QACd,CAAC,CAAA;IACH,CAAC,EAAE,EAAE,CAAC,CAAA;IAEN,OAAO,SAAS,CAAA;AAClB,CAAC"}

package/dist/react/useRpc.d.ts

@@ -0,0 +1,29 @@
+/**
+ * useRpc — React hook around `mentra.request(channel, ...)`.
+ *
+ * Returns a stable callable plus an `.abort()` method. The internal
+ * AbortController is recreated per call and bound to component lifecycle:
+ *
+ *   - Calling the returned function once: abort() the previous in-flight
+ *     call (if any), then issue a fresh request. Useful for per-keystroke
+ *     autocomplete — every keystroke aborts the stale request.
+ *   - Unmount: all in-flight calls abort.
+ *   - Caller-provided `options.signal` is merged with the internal one
+ *     via `AbortSignal.any` when available; manual fan-out otherwise.
+ */
+import type { RpcReq, RpcRes, RpcRequestOptions } from "../modules/ui";
+export interface RpcCallable<TChannels extends object, C extends keyof TChannels & string> {
+    (payload: RpcReq<TChannels[C]>, options?: RpcRequestOptions): Promise<RpcRes<TChannels[C]>>;
+    /** Abort the current in-flight call (if any). No-op if nothing is pending. */
+    abort(): void;
+}
+/**
+ * Returns a stable callable for an RPC channel. The callable auto-aborts
+ * on unmount and exposes `.abort()` for cancel-previous patterns.
+ *
+ *   const autocomplete = useRpc<Channels, "places:autocomplete">("places:autocomplete")
+ *   const suggestions = await autocomplete({query: "..."})
+ *   autocomplete.abort()   // cancel the latest in-flight call
+ */
+export declare function useRpc<TChannels extends object, C extends keyof TChannels & string>(channel: C): RpcCallable<TChannels, C>;
+//# sourceMappingURL=useRpc.d.ts.map

package/dist/react/useRpc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRpc.d.ts","sourceRoot":"","sources":["../../src/react/useRpc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,EAAC,MAAM,EAAE,MAAM,EAAE,iBAAiB,EAAC,MAAM,eAAe,CAAA;AAkCpE,MAAM,WAAW,WAAW,CAAC,SAAS,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,SAAS,GAAG,MAAM;IACvF,CAAC,OAAO,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAC3F,8EAA8E;IAC9E,KAAK,IAAI,IAAI,CAAA;CACd;AAED;;;;;;;GAOG;AACH,wBAAgB,MAAM,CACpB,SAAS,SAAS,MAAM,EACxB,CAAC,SAAS,MAAM,SAAS,GAAG,MAAM,EAClC,OAAO,EAAE,CAAC,GAAG,WAAW,CAAC,SAAS,EAAE,CAAC,CAAC,CAsCvC"}

package/dist/react/useRpc.js

@@ -0,0 +1,82 @@
+/**
+ * useRpc — React hook around `mentra.request(channel, ...)`.
+ *
+ * Returns a stable callable plus an `.abort()` method. The internal
+ * AbortController is recreated per call and bound to component lifecycle:
+ *
+ *   - Calling the returned function once: abort() the previous in-flight
+ *     call (if any), then issue a fresh request. Useful for per-keystroke
+ *     autocomplete — every keystroke aborts the stale request.
+ *   - Unmount: all in-flight calls abort.
+ *   - Caller-provided `options.signal` is merged with the internal one
+ *     via `AbortSignal.any` when available; manual fan-out otherwise.
+ */
+import { useCallback, useEffect, useRef } from "react";
+/** Walk to the global `mentra.request` (typed). */
+function getMentraRequest() {
+    const m = globalThis.mentra;
+    if (!m || typeof m.request !== "function") {
+        throw new Error("useRpc: window.mentra.request is not available — is this miniapp running in a UI WebView with the shim injected?");
+    }
+    return m.request;
+}
+/** AbortSignal.any polyfill — combine multiple signals into one. */
+function mergeSignals(signals) {
+    const ctor = AbortSignal;
+    if (typeof ctor.any === "function")
+        return ctor.any(signals);
+    const ctrl = new AbortController();
+    const onAbort = (sig) => {
+        if (!ctrl.signal.aborted)
+            ctrl.abort(sig.reason);
+    };
+    for (const s of signals) {
+        if (s.aborted) {
+            onAbort(s);
+            break;
+        }
+        s.addEventListener("abort", () => onAbort(s));
+    }
+    return ctrl.signal;
+}
+/**
+ * Returns a stable callable for an RPC channel. The callable auto-aborts
+ * on unmount and exposes `.abort()` for cancel-previous patterns.
+ *
+ *   const autocomplete = useRpc<Channels, "places:autocomplete">("places:autocomplete")
+ *   const suggestions = await autocomplete({query: "..."})
+ *   autocomplete.abort()   // cancel the latest in-flight call
+ */
+export function useRpc(channel) {
+    // Latest in-flight controller. Replaced on each call.
+    const currentRef = useRef(null);
+    // Mount controller — aborts every in-flight call on unmount.
+    const mountRef = useRef(null);
+    if (mountRef.current == null)
+        mountRef.current = new AbortController();
+    useEffect(() => {
+        const mount = mountRef.current;
+        return () => {
+            mount.abort();
+            currentRef.current?.abort();
+            currentRef.current = null;
+        };
+    }, []);
+    const callable = useCallback((payload, options) => {
+        // Abort any previous call for this hook.
+        currentRef.current?.abort();
+        const ctrl = new AbortController();
+        currentRef.current = ctrl;
+        const signals = [ctrl.signal, mountRef.current.signal];
+        if (options?.signal)
+            signals.push(options.signal);
+        const signal = mergeSignals(signals);
+        return getMentraRequest()(channel, payload, { signal, timeout: options?.timeout });
+    }, [channel]);
+    callable.abort = () => {
+        currentRef.current?.abort();
+        currentRef.current = null;
+    };
+    return callable;
+}
+//# sourceMappingURL=useRpc.js.map

package/dist/react/useRpc.js.map

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

package/dist/react/useSafeArea.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @fileoverview useSafeArea — React hook exposing the host's safe-area insets
+ * and the capsule menu rect to miniapp UIs.
+ *
+ * The host injects these via window.MentraOS before content loads. This hook
+ * reads them once at mount — they don't currently change at runtime (the host
+ * would have to force a reload to update them, e.g. on orientation change).
+ */
+import { type MiniappCapsuleMenuRect, type MiniappSafeAreaInsets } from "../globals";
+export interface UseSafeAreaResult {
+    /** Pixel insets around the WebView content. Apply as padding on your root element. */
+    insets: MiniappSafeAreaInsets;
+    /**
+     * Bounding rect of the host's floating capsule menu (top-right overlay).
+     * Null when the host doesn't render one (e.g. older builds). Use this to
+     * avoid placing clickable content underneath the menu.
+     */
+    capsuleMenu: MiniappCapsuleMenuRect | null;
+}
+export declare function useSafeArea(): UseSafeAreaResult;
+//# sourceMappingURL=useSafeArea.d.ts.map

package/dist/react/useSafeArea.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSafeArea.d.ts","sourceRoot":"","sources":["../../src/react/useSafeArea.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAEL,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC3B,MAAM,YAAY,CAAA;AAInB,MAAM,WAAW,iBAAiB;IAChC,sFAAsF;IACtF,MAAM,EAAE,qBAAqB,CAAA;IAC7B;;;;OAIG;IACH,WAAW,EAAE,sBAAsB,GAAG,IAAI,CAAA;CAC3C;AAED,wBAAgB,WAAW,IAAI,iBAAiB,CAS/C"}

package/dist/react/useSafeArea.js

@@ -0,0 +1,22 @@
+/**
+ * @fileoverview useSafeArea — React hook exposing the host's safe-area insets
+ * and the capsule menu rect to miniapp UIs.
+ *
+ * The host injects these via window.MentraOS before content loads. This hook
+ * reads them once at mount — they don't currently change at runtime (the host
+ * would have to force a reload to update them, e.g. on orientation change).
+ */
+import { useState } from "react";
+import { getMentraOSGlobals, } from "../globals";
+const EMPTY_INSETS = { top: 0, bottom: 0, left: 0, right: 0 };
+export function useSafeArea() {
+    const [result] = useState(() => {
+        const globals = getMentraOSGlobals();
+        return {
+            insets: globals.safeAreaInsets ?? EMPTY_INSETS,
+            capsuleMenu: globals.capsuleMenu ?? null,
+        };
+    });
+    return result;
+}
+//# sourceMappingURL=useSafeArea.js.map

package/dist/react/useSafeArea.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSafeArea.js","sourceRoot":"","sources":["../../src/react/useSafeArea.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAC,QAAQ,EAAC,MAAM,OAAO,CAAA;AAE9B,OAAO,EACL,kBAAkB,GAGnB,MAAM,YAAY,CAAA;AAEnB,MAAM,YAAY,GAA0B,EAAC,GAAG,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAC,CAAA;AAalF,MAAM,UAAU,WAAW;IACzB,MAAM,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAoB,GAAG,EAAE;QAChD,MAAM,OAAO,GAAG,kBAAkB,EAAE,CAAA;QACpC,OAAO;YACL,MAAM,EAAE,OAAO,CAAC,cAAc,IAAI,YAAY;YAC9C,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,IAAI;SACzC,CAAA;IACH,CAAC,CAAC,CAAA;IACF,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/session.d.ts

@@ -0,0 +1,312 @@
+/**
+ * @fileoverview MiniappSession — central session object for a local miniapp.
+ *
+ * Owns the transport, the request/response correlation map, the readiness queue,
+ * the PONG auto-reply, the visibility state, and all per-module instances.
+ *
+ * Lifecycle:
+ *   const session = new MiniappSession()
+ *   await session.connect()          // sends CONNECT, resolves on CONNECT_ACK
+ *   session.display.render([...])
+ *   ...
+ *   session.disconnect()
+ */
+import { MiniappColorScheme } from "./globals";
+import { MiniappErrorCode, MiniappResponseType } from "./protocol";
+import { CreateTransportOptions } from "./transport/auto";
+import { CameraModule } from "./modules/camera";
+import { AuthModule } from "./modules/auth";
+import { CloudModule } from "./modules/cloud";
+import { DashboardAPI } from "./modules/dashboard";
+import { DisplayManager } from "./modules/display";
+import { EventManager, type UnsubscribeFn } from "./modules/events";
+import { GlassesModule } from "./modules/glasses";
+import { HeadingModule } from "./modules/heading";
+import { ImuModule } from "./modules/imu";
+import { InputModule } from "./modules/input";
+import { LedModule } from "./modules/led";
+import { LocationModule } from "./modules/location";
+import { MicModule } from "./modules/mic";
+import { NavigationModule } from "./modules/navigation";
+import { PermissionsModule } from "./modules/permissions";
+import { PhoneModule } from "./modules/phone";
+import { TranscriptionModule } from "./modules/transcription";
+import { TranslationModule } from "./modules/translation";
+import { type UIModule } from "./modules/ui";
+import { SimpleStorage } from "./modules/storage";
+import { SpeakerModule } from "./modules/speaker";
+import { StreamModule } from "./modules/stream";
+import { SystemModule } from "./modules/system";
+import { MiniappsModule } from "./modules/miniapps";
+import { ActionsModule } from "./modules/actions";
+import { BlobModule } from "./modules/blob";
+/**
+ * Typed display capabilities for the scene API. All limit fields are optional
+ * in the type because older hosts don't send them — treat absence as "unknown",
+ * not zero. Populated on the "ready" event (null in `start()`).
+ */
+export interface DisplayCapabilities {
+    /** Public drawable canvas in px — raw coordinate space for `display.render()` boxes. */
+    width?: number;
+    height?: number;
+    /** False ⇒ the device can't position elements; scenes degrade to text walls host-side. */
+    canPosition?: boolean;
+    /** Element budgets. Rects share the text pool on container-based devices. */
+    maxTextElements?: number;
+    maxImageElements?: number;
+    /** Per-image dimension cap (box-level), when the device has one. */
+    maxImagePx?: {
+        width: number;
+        height: number;
+    };
+    shapes?: string[];
+    intensityLevels?: number;
+    partialUpdate?: boolean;
+    /** Legacy capability fields (resolution, isColor, maxTextLines, …) ride along. */
+    [key: string]: unknown;
+}
+/** Minimal snapshot of the currently-connected glasses. Phone-provided. */
+export interface GlassesCapabilities {
+    /** Display block — null/absent on displayless devices (e.g. Mentra Live). */
+    display?: DisplayCapabilities | null;
+    [key: string]: unknown;
+}
+export type MiniappVisibility = "foreground" | "background";
+export interface MiniappSessionOptions extends CreateTransportOptions {
+    /** Override auto-detected packageName. Normally provided via window.MentraOS. */
+    packageName?: string;
+    /** Override the ready timeout. Default 10s. */
+    connectTimeoutMs?: number;
+}
+export interface ConnectAckPayload {
+    type: MiniappResponseType.CONNECT_ACK;
+    userId: string;
+    packageName: string;
+    capabilities: GlassesCapabilities | null;
+    visibility?: MiniappVisibility;
+    colorScheme?: MiniappColorScheme;
+    /**
+     * Manifest-declared permission record. Mirrors cloud SDK v3's PermissionRecord:
+     * `{location, microphone, camera, notifications, calendar}` — booleans
+     * indicating whether the miniapp's manifest declared each. This is
+     * declaration-only; OS-grant state is not modeled.
+     */
+    permissions?: PermissionRecord;
+    /** Miniapp-scoped backend auth. Never a Core or runtime token. */
+    auth?: MiniappAuthState;
+}
+export interface MiniappAuthState {
+    mentraUserId: string;
+    oemId?: string;
+    token: string;
+    expiresAt: number;
+}
+export interface AuthUpdatePayload {
+    type: MiniappResponseType.AUTH_UPDATE;
+    auth?: MiniappAuthState;
+}
+/**
+ * Manifest-declared permission record. v3-aligned: lowercase canonical keys.
+ * Booleans indicate whether the miniapp declared each in its manifest.json.
+ */
+export type PermissionType = "location" | "microphone" | "camera" | "notifications" | "calendar";
+export type PermissionRecord = Record<PermissionType, boolean>;
+export declare class NotConnectedError extends Error {
+    readonly code = MiniappErrorCode.NOT_CONNECTED;
+    constructor(message?: string);
+}
+export interface MiniappRequestError {
+    code: string;
+    message: string;
+}
+type SessionEmitterEvents = {
+    ready: () => void;
+    error: (error: Error) => void;
+    /**
+     * Last-chance hook before the transport closes. Fires when the phone
+     * sends WILL_DISCONNECT, or when this session calls `disconnect()`
+     * locally. Handlers run synchronously and may issue one final
+     * `sendOneShot`/`sendRequest` (e.g. `display.render([])`); async work won't complete
+     * before the socket closes.
+     */
+    beforeDisconnect: (reason: string) => void;
+    disconnect: (reason: string) => void;
+    visibility: (v: MiniappVisibility) => void;
+    capabilities: (cap: GlassesCapabilities | null) => void;
+    colorScheme: (scheme: MiniappColorScheme) => void;
+    permissions: (perms: PermissionRecord) => void;
+    speakerState: (event: import("./modules/speaker").SpeakerStateEvent) => void;
+    auth: (auth: MiniappAuthState) => void;
+};
+export declare class MiniappSession {
+    readonly auth: AuthModule;
+    readonly display: DisplayManager;
+    /**
+     * Internal subscription registry + escape hatch.
+     *
+     * Domain modules (`session.mic`, `session.input`, etc.) are the canonical
+     * surface for typed event subscriptions. `events.subscribe(...)` remains as
+     * a forward-compat escape hatch for new event types not yet wrapped on a
+     * domain module.
+     */
+    readonly events: EventManager;
+    readonly speaker: SpeakerModule;
+    readonly camera: CameraModule;
+    readonly cloud: CloudModule;
+    readonly dashboard: DashboardAPI;
+    readonly glasses: GlassesModule;
+    readonly heading: HeadingModule;
+    readonly imu: ImuModule;
+    readonly input: InputModule;
+    readonly led: LedModule;
+    readonly location: LocationModule;
+    readonly mic: MicModule;
+    readonly navigation: NavigationModule;
+    readonly permissions: PermissionsModule;
+    readonly phone: PhoneModule;
+    readonly storage: SimpleStorage;
+    /**
+     * Phone-local persistent BINARY storage (`session.blob`) — the binary
+     * counterpart to `session.storage`. Files on disk, scoped to this miniapp.
+     * Writes/reads are chunked so large payloads (e.g. captured audio fed in via
+     * `session.mic.onAudioChunk`) never cross the bridge in one message.
+     */
+    readonly blob: BlobModule;
+    readonly stream: StreamModule;
+    readonly system: SystemModule;
+    readonly transcription: TranscriptionModule;
+    readonly translation: TranslationModule;
+    /**
+     * UI message bus to the bound WebView (when one is open).
+     * Background-only API surface; mirrors the WebView's `mentra` global
+     * with inverted buffering policy (background drops when no WebView is
+     * bound; the WebView buffers until ready).
+     */
+    readonly ui: UIModule;
+    /**
+     * Inter-miniapp lifecycle + discovery (list / start / stop). SYSTEM-only —
+     * calls reject with NOT_PERMITTED unless this miniapp is a system app.
+     */
+    readonly miniapps: MiniappsModule;
+    /**
+     * Inter-miniapp action layer. `invoke` (SYSTEM-only) calls another miniapp's
+     * declared action; `handle` (open to all) exposes one of your own.
+     */
+    readonly actions: ActionsModule;
+    /** Phone-declared glasses capabilities. Null until CONNECT_ACK arrives. */
+    capabilities: GlassesCapabilities | null;
+    userId: string;
+    packageName: string;
+    visibility: MiniappVisibility;
+    /** Host color scheme. Seeded from window.MentraOS, updated via session events. */
+    colorScheme: MiniappColorScheme;
+    /** True after CONNECT_ACK. Observe with waitForReady() or the "ready" event. */
+    ready: boolean;
+    private readonly transport;
+    private readonly connectTimeoutMs;
+    private readonly emitter;
+    private authState;
+    private readonly authWaiters;
+    private authRefreshPromise;
+    /**
+     * Outbound queue for anything sent before CONNECT_ACK. Flushed in FIFO order
+     * once the phone responds with CONNECT_ACK.
+     */
+    private readonly outboundQueue;
+    private readonly pendingRequests;
+    private connectPromise;
+    private disposed;
+    /** Manifest-declared permission cache. Updated on CONNECT_ACK / PERMISSIONS_UPDATE. */
+    private _permissions;
+    constructor(options?: MiniappSessionOptions);
+    /**
+     * @internal — synchronous lookup against the cached manifest-declared
+     * permission record from CONNECT_ACK / PERMISSIONS_UPDATE. Domain modules
+     * use this to expose their `hasPermission` getters without going to the
+     * wire. Returns false until CONNECT_ACK arrives.
+     *
+     * `manifestKey` is the manifest's UPPER_CASE permission name
+     * (MICROPHONE, CAMERA, LOCATION, READ_NOTIFICATIONS, etc.). Maps to v3's
+     * lowercase canonical keys internally.
+     */
+    _hasManifestPermission(manifestKey: string): boolean;
+    /**
+     * @internal — read the current manifest-declared permission record.
+     * Powers session.permissions.getAll(). Returns a fresh shallow copy so
+     * callers can't mutate internal state.
+     */
+    _getPermissions(): PermissionRecord;
+    /** @internal — current miniapp-scoped backend auth, if the host provided one. */
+    _getAuth(): MiniappAuthState | null;
+    /**
+     * @internal — wait for a scoped miniapp token. Used by session.auth; not part
+     * of the public SDK surface because authors should never manage wire events.
+     */
+    _waitForAuth(minTtlMs: number, timeoutMs?: number): Promise<MiniappAuthState>;
+    /**
+     * @internal — subscribe to a raw stream type. Domain modules call this; it
+     * delegates to the EventManager registry. Underscore prefix signals "not
+     * part of the public SDK surface — use session.mic.onAudioChunk /
+     * session.transcription.on(...)
+     * etc. instead."
+     */
+    _subscribe(streamType: string, handler: (data: unknown) => void, options?: {
+        forceLocal?: boolean;
+    }): UnsubscribeFn;
+    /**
+     * Connect to LocalMiniappRuntime. Idempotent — calling multiple times
+     * returns the same Promise.
+     */
+    connect(): Promise<void>;
+    /** Resolves when `ready` becomes true, or rejects if connect failed. */
+    waitForReady(): Promise<void>;
+    isConnected(): boolean;
+    disconnect(): void;
+    /** Send a fire-and-forget request that does not need a response. */
+    sendOneShot(payload: object): void;
+    /**
+     * Send a request and get a Promise that resolves with the REQUEST_RESULT payload.
+     * Rejects with a MiniappRequestError if the phone returns an error result.
+     *
+     * `opts.timeoutMs` overrides the default request timeout. Pass `0` to disable
+     * it entirely for inherently long-running requests whose duration is unbounded
+     * (e.g. audio playback that resolves only when the clip finishes) — those still
+     * settle via REQUEST_RESULT or `failAllPending` on disconnect, so they can't
+     * leak. Most requests should keep the default ceiling.
+     */
+    sendRequest<TResult = unknown>(payload: object, opts?: {
+        timeoutMs?: number;
+    }): Promise<TResult>;
+    on<K extends keyof SessionEmitterEvents>(event: K, handler: SessionEmitterEvents[K]): () => void;
+    off<K extends keyof SessionEmitterEvents>(event: K, handler: SessionEmitterEvents[K]): void;
+    /**
+     * Last-chance hook before the transport closes. Fires either when the
+     * phone notifies the session of an imminent disconnect (~50ms grace
+     * window before the socket is torn down) or when this session's
+     * `disconnect()` is called locally. Use it to flush final cleanup
+     * messages — e.g. `display.render([])` — synchronously. Async work
+     * started here will not complete before the socket closes.
+     */
+    onBeforeDisconnect(handler: (reason: string) => void): () => void;
+    onVisibilityChange(handler: (v: MiniappVisibility) => void): () => void;
+    onCapabilitiesChange(handler: (cap: GlassesCapabilities | null) => void): () => void;
+    onColorSchemeChange(handler: (scheme: MiniappColorScheme) => void): () => void;
+    private enqueueOrSend;
+    private flushQueue;
+    private handleIncoming;
+    private handleTransportDisconnect;
+    private failAllPending;
+    private authHasTtl;
+    private requestAuthRefresh;
+    private applyAuth;
+    /**
+     * Update the cached permission record. Idempotent: emits "permissions"
+     * only when the record actually changed. Sanitizes incoming objects to
+     * the v3 PermissionType union.
+     */
+    private applyPermissions;
+}
+/** @internal — for the permissions module's onUpdate plumbing. */
+export declare function _allPermissionTypes(): readonly PermissionType[];
+export {};
+//# sourceMappingURL=session.d.ts.map