@mentra/miniapp 0.3.0-dev.0

package/dist/modules/mic.js

@@ -0,0 +1,67 @@
+/**
+ * @fileoverview MicModule — low-level audio input subscriptions.
+ *
+ * Mirrors cloud SDK v3's MicManager naming. Houses raw audio chunks + VAD;
+ * transcription and translation hoisted to top-level (`session.transcription`
+ * / `session.translation`) in the v3-alignment round so authors don't have to
+ * mentally model "transcription is a microphone thing" — it's just a
+ * top-level domain. This module was called `MicrophoneModule` /
+ * `session.microphone` before that round.
+ *
+ * Audio *output* (TTS, file playback) lives on `session.speaker`.
+ *
+ * MICROPHONE permission must be declared in miniapp.json for any of these
+ * subscriptions to succeed; the phone runtime rejects with
+ * PERMISSION_NOT_DECLARED otherwise.
+ */
+import { MiniappStreamType } from "../protocol";
+export class MicModule {
+    constructor(session) {
+        this.session = session;
+        /** All active unsubscribe functions for stop() to tear down at once. */
+        this.unsubs = new Set();
+    }
+    /**
+     * Subscribe to voice activity detection (VAD) events. `data.status` is
+     * `true` while the user is speaking, `false` when silent.
+     */
+    onVoiceActivity(handler) {
+        return this.track(this.session._subscribe(MiniappStreamType.VAD, handler));
+    }
+    /**
+     * Subscribe to raw audio chunks. Format depends on the phone's mic mode
+     * (PCM or LC3, base64-encoded).
+     */
+    onAudioChunk(handler) {
+        return this.track(this.session._subscribe(MiniappStreamType.AUDIO_CHUNK, handler));
+    }
+    /**
+     * Tear down every subscription this module owns. Useful when a component
+     * is unmounting and wants to free everything at once without tracking
+     * individual unsubscribe functions.
+     */
+    stop() {
+        for (const u of this.unsubs) {
+            try {
+                u();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        this.unsubs.clear();
+    }
+    /** True iff `MICROPHONE` is declared in the miniapp's manifest. */
+    get hasPermission() {
+        return this.session._hasManifestPermission("MICROPHONE");
+    }
+    // ------------------------------------------------------------------------
+    track(unsub) {
+        this.unsubs.add(unsub);
+        return () => {
+            this.unsubs.delete(unsub);
+            unsub();
+        };
+    }
+}
+//# sourceMappingURL=mic.js.map

package/dist/modules/mic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mic.js","sourceRoot":"","sources":["../../src/modules/mic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAC,iBAAiB,EAAC,MAAM,aAAa,CAAA;AAI7C,MAAM,OAAO,SAAS;IAIpB,YAA6B,OAAuB;QAAvB,YAAO,GAAP,OAAO,CAAgB;QAHpD,wEAAwE;QACvD,WAAM,GAAG,IAAI,GAAG,EAAiB,CAAA;IAEK,CAAC;IAExD;;;OAGG;IACH,eAAe,CAAC,OAAgC;QAC9C,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,iBAAiB,CAAC,GAAG,EAAE,OAAkC,CAAC,CAAC,CAAA;IACvG,CAAC;IAED;;;OAGG;IACH,YAAY,CAAC,OAAuC;QAClD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,iBAAiB,CAAC,WAAW,EAAE,OAAkC,CAAC,CAAC,CAAA;IAC/G,CAAC;IAED;;;;OAIG;IACH,IAAI;QACF,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAC5B,IAAI,CAAC;gBACH,CAAC,EAAE,CAAA;YACL,CAAC;YAAC,MAAM,CAAC;gBACP,YAAY;YACd,CAAC;QACH,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAA;IACrB,CAAC;IAED,mEAAmE;IACnE,IAAI,aAAa;QACf,OAAO,IAAI,CAAC,OAAO,CAAC,sBAAsB,CAAC,YAAY,CAAC,CAAA;IAC1D,CAAC;IAED,2EAA2E;IAEnE,KAAK,CAAC,KAAoB;QAChC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;QACtB,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;YACzB,KAAK,EAAE,CAAA;QACT,CAAC,CAAA;IACH,CAAC;CACF"}

package/dist/modules/miniapps.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @fileoverview MiniappsModule — `session.miniapps`.
+ *
+ * Discover and control the lifecycle of OTHER miniapps: list, start, stop.
+ * SYSTEM-only — every call rejects with NOT_PERMITTED unless the caller is a
+ * system app (Mentra AI is the first consumer). The action *capability* layer
+ * (invoke / handle) lives on `session.actions`, not here — these three are
+ * operations on the app as a whole, not on a declared action.
+ */
+import { MiniappSession } from "../session";
+/** A declared action surfaced by {@link MiniappsModule.list}. */
+export interface MiniappActionInfo {
+    id: string;
+    description: string;
+    /**
+     * JSON-Schema input descriptor (the MCP-compatible subset). Maps verbatim
+     * to an MCP tool `inputSchema`. Undefined for actions that take no params.
+     */
+    parameters?: Record<string, unknown>;
+}
+/**
+ * Hardware compatibility for a listed miniapp. Structurally mirrors the host's
+ * `CompatibilityResult` so the runtime can pass it straight through.
+ */
+export interface MiniappCompatibility {
+    isCompatible: boolean;
+    missingRequired: Array<{
+        type: string;
+        level?: string;
+    }>;
+    missingOptional: Array<{
+        type: string;
+        level?: string;
+    }>;
+    warnings: string[];
+}
+/** One installed miniapp, as surfaced to a system caller. */
+export interface MiniappInfo {
+    packageName: string;
+    name: string;
+    description?: string;
+    version: string;
+    running: boolean;
+    compatibility: MiniappCompatibility;
+    /** Declared actions (empty if the miniapp declares none). */
+    actions: MiniappActionInfo[];
+}
+export interface ListMiniappsOptions {
+    /** Include incompatible miniapps too (default false — compatible-only). */
+    includeIncompatible?: boolean;
+}
+export declare class MiniappsModule {
+    private readonly session;
+    constructor(session: MiniappSession);
+    /**
+     * List installed miniapps. Compatible-only by default; pass
+     * `{includeIncompatible: true}` to include the rest (each carries a
+     * `compatibility` result with the missing hardware). SYSTEM-only.
+     */
+    list(opts?: ListMiniappsOptions): Promise<MiniappInfo[]>;
+    /**
+     * Start another miniapp in the **background** — spawns its background JS
+     * context without changing the user's phone navigation or foregrounding
+     * anything. The app reports as running and can handle actions / drive the
+     * glasses immediately; its WebView only mounts if the user later opens it.
+     * SYSTEM-only.
+     */
+    start(packageName: string): Promise<void>;
+    /** Stop another miniapp. SYSTEM-only. */
+    stop(packageName: string): Promise<void>;
+}
+//# sourceMappingURL=miniapps.d.ts.map

package/dist/modules/miniapps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"miniapps.d.ts","sourceRoot":"","sources":["../../src/modules/miniapps.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAC,cAAc,EAAC,MAAM,YAAY,CAAA;AAEzC,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAA;IACV,WAAW,EAAE,MAAM,CAAA;IACnB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACrC;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,OAAO,CAAA;IACrB,eAAe,EAAE,KAAK,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAC,CAAC,CAAA;IACtD,eAAe,EAAE,KAAK,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAC,CAAC,CAAA;IACtD,QAAQ,EAAE,MAAM,EAAE,CAAA;CACnB;AAED,6DAA6D;AAC7D,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,OAAO,CAAA;IAChB,aAAa,EAAE,oBAAoB,CAAA;IACnC,6DAA6D;IAC7D,OAAO,EAAE,iBAAiB,EAAE,CAAA;CAC7B;AAED,MAAM,WAAW,mBAAmB;IAClC,2EAA2E;IAC3E,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAC9B;AAED,qBAAa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,cAAc;IAEpD;;;;OAIG;IACG,IAAI,CAAC,IAAI,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAQ9D;;;;;;OAMG;IACG,KAAK,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO/C,yCAAyC;IACnC,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAM/C"}

package/dist/modules/miniapps.js

@@ -0,0 +1,48 @@
+/**
+ * @fileoverview MiniappsModule — `session.miniapps`.
+ *
+ * Discover and control the lifecycle of OTHER miniapps: list, start, stop.
+ * SYSTEM-only — every call rejects with NOT_PERMITTED unless the caller is a
+ * system app (Mentra AI is the first consumer). The action *capability* layer
+ * (invoke / handle) lives on `session.actions`, not here — these three are
+ * operations on the app as a whole, not on a declared action.
+ */
+import { MiniappRequestType } from "../protocol";
+export class MiniappsModule {
+    constructor(session) {
+        this.session = session;
+    }
+    /**
+     * List installed miniapps. Compatible-only by default; pass
+     * `{includeIncompatible: true}` to include the rest (each carries a
+     * `compatibility` result with the missing hardware). SYSTEM-only.
+     */
+    async list(opts) {
+        const result = await this.session.sendRequest({
+            type: MiniappRequestType.MINIAPPS_LIST,
+            includeIncompatible: opts?.includeIncompatible ?? false,
+        });
+        return result ?? [];
+    }
+    /**
+     * Start another miniapp in the **background** — spawns its background JS
+     * context without changing the user's phone navigation or foregrounding
+     * anything. The app reports as running and can handle actions / drive the
+     * glasses immediately; its WebView only mounts if the user later opens it.
+     * SYSTEM-only.
+     */
+    async start(packageName) {
+        await this.session.sendRequest({
+            type: MiniappRequestType.MINIAPPS_START,
+            packageName,
+        });
+    }
+    /** Stop another miniapp. SYSTEM-only. */
+    async stop(packageName) {
+        await this.session.sendRequest({
+            type: MiniappRequestType.MINIAPPS_STOP,
+            packageName,
+        });
+    }
+}
+//# sourceMappingURL=miniapps.js.map

package/dist/modules/miniapps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"miniapps.js","sourceRoot":"","sources":["../../src/modules/miniapps.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAC,kBAAkB,EAAC,MAAM,aAAa,CAAA;AA0C9C,MAAM,OAAO,cAAc;IACzB,YAA6B,OAAuB;QAAvB,YAAO,GAAP,OAAO,CAAgB;IAAG,CAAC;IAExD;;;;OAIG;IACH,KAAK,CAAC,IAAI,CAAC,IAA0B;QACnC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAgB;YAC3D,IAAI,EAAE,kBAAkB,CAAC,aAAa;YACtC,mBAAmB,EAAE,IAAI,EAAE,mBAAmB,IAAI,KAAK;SACxD,CAAC,CAAA;QACF,OAAO,MAAM,IAAI,EAAE,CAAA;IACrB,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,KAAK,CAAC,WAAmB;QAC7B,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAO;YACnC,IAAI,EAAE,kBAAkB,CAAC,cAAc;YACvC,WAAW;SACZ,CAAC,CAAA;IACJ,CAAC;IAED,yCAAyC;IACzC,KAAK,CAAC,IAAI,CAAC,WAAmB;QAC5B,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAO;YACnC,IAAI,EAAE,kBAAkB,CAAC,aAAa;YACtC,WAAW;SACZ,CAAC,CAAA;IACJ,CAAC;CACF"}

package/dist/modules/navigation.d.ts

@@ -0,0 +1,326 @@
+/**
+ * NavigationModule — turn-by-turn navigation for miniapps. A thin pass-through over the bridge;
+ * the phone-side daemon owns the trip lifecycle.
+ *
+ * Works on iOS and Android (both back it with the Mapbox Navigation SDK). Every Promise
+ * resolves with an `{ok, error?}` shape; nothing throws, so check `result.ok`.
+ */
+import { MiniappSession } from "../session";
+import type { UnsubscribeFn } from "./events";
+export type LatLng = {
+    lat: number;
+    lng: number;
+};
+export type TravelMode = "walking" | "driving" | "cycling" | "two_wheeler";
+/**
+ * Categorical maneuver vocabulary. Most values come from the Google Nav SDK + Routes API;
+ * "CROSS_STREET" is SDK-synthesized when the pivot engine detects a crosswalk leg.
+ */
+export type ManeuverKind = "STRAIGHT" | "CONTINUE" | "SLIGHT_LEFT" | "SLIGHT_RIGHT" | "TURN_LEFT" | "TURN_RIGHT" | "SHARP_LEFT" | "SHARP_RIGHT" | "U_TURN" | "NAME_CHANGE" | "DEPART" | "ARRIVE" | "CROSS_STREET";
+/** Routing preferences. All flags default to false. */
+export type RouteAvoidances = {
+    highways?: boolean;
+    tolls?: boolean;
+    ferries?: boolean;
+};
+export type NavManeuver = {
+    kind: "maneuver";
+    maneuverType: ManeuverKind;
+    /** Meters to the maneuver. -1 if unknown. */
+    distanceMeters: number;
+    /** Road the user is currently on. Null when unnamed or pre-first-update. */
+    fromRoad?: string | null;
+    /** Legacy "next road" field. Prefer `nextStepRoad` for new UIs. */
+    toRoad?: string | null;
+    /** Road the user will be on AFTER the maneuver. Use as the "next street" label. */
+    nextStepRoad?: string | null;
+    /** Total meters to the destination. -1 if unknown. */
+    distanceToDestinationMeters?: number;
+    /** Remaining travel time in seconds. -1 if unknown. */
+    timeToDestinationSeconds?: number;
+    /** Current speed in m/s. Null if unavailable. */
+    currentSpeedMps?: number | null;
+    /** Speed limit in m/s. Null if unknown / not regulated. */
+    speedLimitMps?: number | null;
+    /** Route bearing at the user's position, 0–360. Null if unknown. */
+    routeHeadingDeg?: number | null;
+    /** Host engine's verbatim instruction (e.g. "Turn left onto Waller St"). Render as-is. */
+    instruction?: string | null;
+};
+export type NavOffRoute = {
+    kind: "off_route";
+    /** Approximate perpendicular distance from the route, in meters. */
+    offRouteDistanceMeters: number;
+};
+export type NavRerouting = {
+    kind: "rerouting";
+};
+export type NavArrived = {
+    kind: "arrived";
+};
+export type NavError = {
+    kind: "error";
+    message: string;
+};
+export type NavUpdate = NavManeuver | NavOffRoute | NavRerouting | NavArrived | NavError;
+export type NavRoute = {
+    points: LatLng[];
+    totalDistanceMeters?: number;
+    totalDurationSeconds?: number;
+    /** Ordered navigable segments. Omitted by older hosts that don't supply step metadata. */
+    steps?: NavStep[];
+};
+/** Pivot-detection tuning. Omitted fields use mode-aware defaults. */
+export type PivotOptions = {
+    /** "Turning now" radius. Defaults: walking 7, cycling 15, driving 40. */
+    radiusMeters?: number;
+    /** "Approaching" radius. Defaults: walking 100, cycling 300, driving 800. */
+    approachThresholdMeters?: number;
+};
+/** A real turn along the route, derived once per route build (re-derived on reroute). */
+export type Pivot = {
+    /** 0-based ordinal; invalidated when `onRoute` fires again. */
+    index: number;
+    lat: number;
+    lng: number;
+    direction: "left" | "right";
+    /** Road approaching the pivot. Null when the engine has no name. */
+    fromRoad: string | null;
+    /** Road exiting the pivot. Same null semantics. */
+    toRoad: string | null;
+    maneuver: ManeuverKind;
+    /** Meters from trip start to this pivot, along the route. */
+    distanceAlongRouteMeters: number;
+    /** "Turning now" radius for this pivot, in meters. */
+    radiusMeters: number;
+};
+/** Each pivot fires `approaching` → `entered` → `exited` (once each), then the cursor advances. */
+export type PivotEvent = {
+    kind: "approaching";
+    pivot: Pivot;
+    distanceMeters: number;
+} | {
+    kind: "entered";
+    pivot: Pivot;
+} | {
+    kind: "exited";
+    pivot: Pivot;
+};
+/** One route leg: a stretch of road ending in a maneuver. */
+export type NavStep = {
+    /** Coordinate where this step begins (== end of the previous step). */
+    lat: number;
+    lng: number;
+    /** Index into `NavRoute.points[]` where this step starts. */
+    routeIndex: number;
+    /** Road traversed during this step. Null when unnamed. */
+    road?: string | null;
+    /** Maneuver performed at the END of this step. */
+    maneuver: ManeuverKind;
+    distanceMeters: number;
+};
+/** One type-ahead place suggestion from `placeAutocomplete`. */
+export type NavPlaceSuggestion = {
+    /** Opaque id to feed into `placeDetails`. */
+    placeId: string;
+    /** Primary line, e.g. "Blue Bottle Coffee". */
+    mainText: string;
+    /** Secondary line, e.g. "66 Mint St, San Francisco". Empty when none. */
+    secondaryText: string;
+};
+/** A place resolved from a suggestion via `placeDetails` — has coordinates to route to. */
+export type NavPlaceDetails = {
+    placeId: string;
+    name: string;
+    address: string;
+    lat: number;
+    lng: number;
+};
+export type NavigationDev = {
+    deviate(offsetMeters?: number): void;
+    setWrongSidewalkOffset(enabled: boolean): void;
+    setSkipCrossings(enabled: boolean): void;
+};
+export type StartNavigationOptions = {
+    /** Single-destination shorthand. Rewritten to `stops: [{lat, lng}]`. */
+    lat?: number;
+    lng?: number;
+    /** Ordered stops; last is the final destination. Must have ≥1 entry. */
+    stops?: LatLng[];
+    /** Defaults to "driving". */
+    mode?: TravelMode;
+    avoid?: RouteAvoidances;
+    /** Dev/testing only — fake walking the route at speedMultiplier×. */
+    simulate?: boolean;
+    speedMultiplier?: number;
+    /** Override the default pivot-detection knobs for this trip. */
+    pivots?: PivotOptions;
+    /** Reroute once the user is this many meters past a missed pivot. Omit / 0 to use host defaults. */
+    missedTurnRerouteMeters?: number;
+};
+/** Snapshot of the active trip, shaped like the streaming events so mid-trip opens render the same. */
+export type NavState = {
+    active: boolean;
+    mode?: TravelMode;
+    stops?: LatLng[];
+    /** Index of the stop currently being navigated to (0 = first). */
+    currentStopIndex?: number;
+    route?: NavRoute;
+    maneuver?: NavManeuver;
+    distanceToDestinationMeters?: number;
+    timeToDestinationSeconds?: number;
+    currentSpeedMps?: number | null;
+    speedLimitMps?: number | null;
+};
+export type NavPermissionResult = {
+    /** True if the request reached the host. False e.g. when LOCATION isn't declared in the manifest. */
+    ok: boolean;
+    /** True if the user accepted the Nav SDK T&Cs (always true on platforms without a T&C gate). */
+    accepted: boolean;
+    error?: string;
+};
+/** Standalone route compute — does NOT start a trip. */
+export type ComputeRouteOptions = {
+    origin: LatLng;
+    /** ≥1 entry; last is the final destination. */
+    stops: LatLng[];
+    /** Defaults to "driving". */
+    mode?: TravelMode;
+    avoid?: RouteAvoidances;
+    /** Up to N alternate routes (engine-permitting). Default 1. */
+    alternatives?: number;
+};
+/** One step of a previewed route, available BEFORE `start()`. Maneuver ENDS the segment. */
+export type ComputedRouteStep = {
+    lat: number;
+    lng: number;
+    endLat: number;
+    endLng: number;
+    distanceMeters: number;
+    maneuver?: ManeuverKind;
+    /** Full instruction from the Routes API (e.g. "Turn left onto Fell St"). */
+    instruction?: string;
+    /** Resolved road name. Prefer this over parsing `instruction`. Null when none found. */
+    road?: string | null;
+};
+export type ComputedRoute = {
+    points: LatLng[];
+    totalDistanceMeters: number;
+    totalDurationSeconds: number;
+    summary?: string;
+    steps?: ComputedRouteStep[];
+};
+export type ComputeRouteResult = {
+    ok: boolean;
+    error?: string;
+    /** Primary route first, alternates after. */
+    routes?: ComputedRoute[];
+};
+export declare class NavigationModule {
+    private readonly session;
+    private _pivots;
+    /** Subscriptions owned while a trip is active. Released on stop(). */
+    private _tripUnsubs;
+    /** Trip params captured at start() so reroutes can re-issue computeRoute. */
+    private _tripStops;
+    private _tripMode;
+    private _tripAvoid;
+    /** Bumps per request so a stale reply from before a newer reroute is ignored. */
+    private _computeRouteSeq;
+    /** Latest GPS position, used as the origin for reroute computeRoute calls. */
+    private _lastUserPosition;
+    constructor(session: MiniappSession);
+    /** True iff `LOCATION` is declared in the miniapp's manifest. */
+    get hasPermission(): boolean;
+    /**
+     * Trigger the Nav SDK Terms & Conditions dialog up front, before the user hits "start".
+     * Idempotent. Resolves `{ok: false, accepted: false, error}` when LOCATION isn't declared.
+     */
+    requestPermission(): Promise<NavPermissionResult>;
+    /**
+     * Start a navigation session. Pass `{lat, lng}` or `{stops: [...]}`. `{ok: true}` means the
+     * daemon accepted the request, not that a route was built — listen via `onUpdate(...)`.
+     */
+    start(opts: StartNavigationOptions): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    /** Stop the active session (no-op if none). Fire-and-forget; also detaches pivot tracking. */
+    stop(): void;
+    /** Dev-only simulator helpers for testing trips. `deviate` works on both platforms;
+     *  a few helpers are Android-only and return `{ok: false}` on iOS. */
+    get dev(): NavigationDev;
+    /** Subscribe to live trip events (maneuver / off_route / rerouting / arrived / error). */
+    onUpdate(handler: (update: NavUpdate) => void): UnsubscribeFn;
+    /** Subscribe to the route polyline. Fires once per route build (initial + reroute), full path. */
+    onRoute(handler: (route: NavRoute) => void): UnsubscribeFn;
+    /** Snapshot of the active trip, or `null` when none is running. Use on mount to hydrate state. */
+    getState(): Promise<NavState | null>;
+    /** Compute a route without starting a trip. Primary route first, alternates after. */
+    computeRoute(opts: ComputeRouteOptions): Promise<ComputeRouteResult>;
+    /**
+     * Reverse-geocode a coordinate into a short road name (`road`) and a full
+     * formatted street address (`address`, e.g. "369 Hayes Street, San Francisco,
+     * California 94102"). `road` backs the pivot engine's fallback; `address`
+     * backs UI labels for dropped pins / POI taps. Each is null when none of that
+     * kind is found near the coordinate; `ok: false` is an actual failure.
+     *
+     * Resolved entirely in the v2 cloud maps service (provider-abstracted, Mapbox
+     * today) via the host bridge — the miniapp never holds a maps token or calls a
+     * provider directly.
+     */
+    reverseGeocodeRoad(coord: LatLng): Promise<{
+        ok: boolean;
+        road?: string | null;
+        address?: string | null;
+        error?: string;
+    }>;
+    /**
+     * Type-ahead place search. Returns lightweight suggestions for `query`,
+     * optionally biased toward `near`. Resolved in the v2 cloud maps service
+     * (Mapbox Search Box today) via the host bridge — no maps token in the
+     * miniapp. `sessionToken` should be a stable per-search-box-opening string,
+     * reused on the following `placeDetails` call, then rotated after a pick, so
+     * the keystrokes + the final retrieve bill as one search session.
+     *
+     * Does NOT require LOCATION permission — it's a text search; `near` is only a
+     * ranking bias. Resolves `{ok, suggestions}`; `ok: false` is an actual failure.
+     */
+    placeAutocomplete(opts: {
+        query: string;
+        near?: LatLng;
+        sessionToken: string;
+    }): Promise<{
+        ok: boolean;
+        suggestions?: NavPlaceSuggestion[];
+        error?: string;
+    }>;
+    /**
+     * Resolve a suggestion's `placeId` (from `placeAutocomplete`) to a full place
+     * with coordinates. Pass the SAME `sessionToken` used for the autocomplete so
+     * the provider closes the billing session. Resolved in the v2 cloud maps
+     * service via the host bridge. Resolves `{ok, place}`; `ok: false` is a
+     * failure (including an unresolvable id).
+     */
+    placeDetails(opts: {
+        placeId: string;
+        sessionToken: string;
+    }): Promise<{
+        ok: boolean;
+        place?: NavPlaceDetails;
+        error?: string;
+    }>;
+    /** Subscribe to pivot events. Each pivot fires once per kind; passed pivots aren't re-evaluated. */
+    onPivot(handler: (event: PivotEvent) => void): UnsubscribeFn;
+    /** Full pivot list for the active route. Empty before the first `onRoute`. */
+    getPivots(): Pivot[];
+    /** The pivot the user is currently inside (between `entered` and `exited`), or `null`. */
+    getActivePivot(): Pivot | null;
+    /** The next pivot ahead, or `null` once every pivot has been passed. */
+    getUpcomingPivot(): Pivot | null;
+    private _attachPivotTrackingForTrip;
+    /** computeRoute for the current trip, using the latest position (or route start) as origin. */
+    private _issueComputeRouteForTrip;
+    private _detachPivotTracking;
+}
+//# sourceMappingURL=navigation.d.ts.map

package/dist/modules/navigation.d.ts.map

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