tempest-react-sdk 0.14.0 → 0.16.0

package/dist/tempest-react-sdk.d.ts

@@ -569,6 +569,17 @@ export declare interface BannerProps extends Omit<HTMLAttributes<HTMLDivElement>
 
 export declare type BannerVariant = "info" | "success" | "warning" | "danger";
 
+/**
+ * Initial bearing (forward azimuth) from `origin` to `destination`, in degrees
+ * clockwise from true north, normalized to `[0, 360)`. Useful for orienting a
+ * heading arrow on a trajectory.
+ *
+ * @param origin - Start coordinate.
+ * @param destination - End coordinate.
+ * @returns Bearing in degrees, `[0, 360)`.
+ */
+export declare function bearingDeg(origin: Coordinate, destination: Coordinate): number;
+
 /**
  * Fixed-bottom mobile tab bar. 3–5 items recommended. Pair with
  * `<Show below="md">` to render only on mobile.
@@ -638,6 +649,18 @@ export declare interface BottomSheetProps extends Omit<HTMLAttributes<HTMLDivEle
     children?: ReactNode;
 }
 
+/**
+ * Compute the axis-aligned bounding box that contains every point. Returns
+ * `null` for an empty list (there is nothing to bound).
+ *
+ * @param points - Coordinates to enclose.
+ * @returns The bounds, or `null` when `points` is empty.
+ */
+export declare function boundingBox(points: readonly Coordinate[]): GeoBounds | null;
+
+/** Geometric center of a bounding box. */
+export declare function boundsCenter(bounds: GeoBounds): Coordinate;
+
 export declare interface BreadcrumbItem {
     label: ReactNode;
     href?: string;
@@ -978,6 +1001,9 @@ export declare function chunk<T>(items: T[], size: number): T[][];
  */
 export declare function clamp(value: number, min: number, max: number): number;
 
+/** Clamp a latitude into the valid `[-90, 90]` range. */
+export declare function clampLatitude(latitude: number): number;
+
 declare type ClassValue = string | number | bigint | boolean | null | undefined | ClassValue[];
 
 /**
@@ -1218,6 +1244,18 @@ export { Control }
 
 export { Controller }
 
+/**
+ * WGS84 geographic coordinate. Mirrors the `Coordinate` schema from
+ * `tempest-fastapi-sdk` (`geo/schemas.py`) — `latitude` in `[-90, 90]`,
+ * `longitude` in `[-180, 180]`, serialized snake_case on the wire.
+ */
+export declare interface Coordinate {
+    /** WGS84 latitude in degrees, `[-90, 90]`. E.g. `-23.5505`. */
+    latitude: number;
+    /** WGS84 longitude in degrees, `[-180, 180]`. E.g. `-46.6333`. */
+    longitude: number;
+}
+
 /**
  * Button that copies a string to the clipboard and shows a transient "copied"
  * state for `timeout` milliseconds.
@@ -1493,6 +1531,26 @@ export declare interface CreateLoggerOptions {
  */
 export declare function createOfflineStore<TItem, TKey extends string | number = string>(config: OfflineStoreConfig<TItem>): OfflineStore<TItem, TKey>;
 
+/**
+ * Build a {@link RoutingBackend} backed by an OSRM server **you host**. OSRM
+ * only serves a driving profile, so motorcycle/bus durations are derived by
+ * scaling the car duration through {@link durationFactor} — same approach as
+ * the FastAPI SDK's `OSRMBackend`.
+ *
+ * !!! warning
+ *     This makes a network request to `baseUrl`. It is opt-in: nothing in the
+ *     SDK calls it unless you construct it and pass your own server URL. For a
+ *     zero-network estimate, use {@link estimateTravel} instead.
+ *
+ * @param options - Server URL, optional `fetch`, per-mode factors.
+ * @returns A backend whose `route()` queries OSRM.
+ *
+ * @example
+ * const backend = createOSRMBackend({ baseUrl: "https://osrm.internal" });
+ * const estimate = await backend.route(origin, destination, { mode: "car" });
+ */
+export declare function createOSRMBackend(options: OSRMBackendOptions): RoutingBackend;
+
 /**
  * Build a `206 Partial Content` response from a full one for an HTTP `Range`
  * request. Supports `bytes=start-end`, open-ended `bytes=start-` and suffix
@@ -1504,6 +1562,52 @@ export declare function createOfflineStore<TItem, TKey extends string | number =
  */
 export declare function createPartialResponse(request: Request, response: Response): Promise<Response>;
 
+/**
+ * Record a live GPS trajectory from `navigator.geolocation.watchPosition`.
+ * Framework-free — the {@link usePositionTracker} hook wraps this for React.
+ *
+ * Jitter while stationary is filtered by `minDistanceKm`; distance is
+ * accumulated across the *full* run even when `maxPoints` trims the retained
+ * array. 100% browser-side: no network, no external service.
+ *
+ * @param options - Filtering, retention and callbacks.
+ * @returns A controller with `start`/`stop`/`clear` and live getters.
+ *
+ * @example
+ * const tracker = createPositionTracker({
+ *   minDistanceKm: 0.01,
+ *   onUpdate: (pts) => console.log(pts.length, "points"),
+ * });
+ * tracker.start();
+ * // …later
+ * tracker.stop();
+ * console.log(tracker.distanceKm);
+ */
+export declare function createPositionTracker(options?: CreatePositionTrackerOptions): PositionTracker;
+
+/** Options for {@link createPositionTracker}. */
+export declare interface CreatePositionTrackerOptions {
+    /**
+     * Discard a new sample when it is closer than this (in km) to the last
+     * kept point — filters GPS jitter while standing still. Default: `0.005`
+     * (5 meters). Pass `0` to keep every sample.
+     */
+    minDistanceKm?: number;
+    /**
+     * Cap the retained trajectory to the most recent N points (older points are
+     * dropped, but their distance stays counted). Default: `Infinity`.
+     */
+    maxPoints?: number;
+    /** Forwarded to `navigator.geolocation.watchPosition`. */
+    positionOptions?: PositionOptions;
+    /** Called with the full trajectory each time a point is added. */
+    onUpdate?: (points: readonly TrackPoint[]) => void;
+    /** Called on a `GeolocationPositionError`. */
+    onError?: (error: GeolocationPositionError) => void;
+    /** Called whenever the status changes. */
+    onStatusChange?: (status: TrackerStatus) => void;
+}
+
 /**
  * Build a [[TelemetryAdapter]] backed by [`posthog-js`](https://posthog.com/docs/libraries/js).
  * The PostHog client is supplied by the caller (not bundled).
@@ -2096,6 +2200,25 @@ export declare function decodeJWT(token: string): DecodedJWT;
  */
 export declare function deepMerge<T>(target: T, source: Partial<T>): T;
 
+/**
+ * Default average car speed in km/h used to derive duration from distance.
+ * Mirrors `DEFAULT_CAR_SPEED_KMH` from `tempest-fastapi-sdk`.
+ */
+export declare const DEFAULT_CAR_SPEED_KMH = 50;
+
+/**
+ * Multiplier applied to the great-circle distance to approximate real road
+ * distance. Mirrors `DEFAULT_CIRCUITY_FACTOR` from `tempest-fastapi-sdk`.
+ */
+export declare const DEFAULT_CIRCUITY_FACTOR = 1.3;
+
+/**
+ * Per-mode multipliers applied to the car duration. Mirrors
+ * `DEFAULT_MODE_DURATION_FACTORS` from `tempest-fastapi-sdk` — motorcycles are
+ * a touch faster, buses considerably slower (stops + dedicated lanes).
+ */
+export declare const DEFAULT_MODE_DURATION_FACTORS: Record<TravelMode, number>;
+
 /**
  * Identity helper that types a declarative route tree. Use it so editors give
  * autocomplete and type-checking on every node; the array is returned as-is.
@@ -2261,6 +2384,22 @@ export declare interface DropzoneProps {
     className?: string;
 }
 
+/**
+ * Look up the duration multiplier for a travel mode, falling back to `1.0`
+ * for unknown modes. Mirrors `duration_factor` from `tempest-fastapi-sdk`.
+ *
+ * @param mode - Travel mode.
+ * @param factors - Optional override map (partial merges over the defaults).
+ * @returns The multiplier for `mode`.
+ */
+export declare function durationFactor(mode: TravelMode, factors?: Partial<Record<TravelMode, number>>): number;
+
+/**
+ * Mean Earth radius in kilometers. Same value used by `tempest-fastapi-sdk`
+ * (`geo/distance.py`) so client and server distances agree.
+ */
+export declare const EARTH_RADIUS_KM = 6371.0088;
+
 export declare interface ElementSize {
     width: number;
     height: number;
@@ -2365,6 +2504,37 @@ export declare interface ErrorTextProps extends HTMLAttributes<HTMLParagraphElem
 
 export declare function estimatePasswordStrength(value: string): PasswordStrength;
 
+/**
+ * Offline travel estimate between two coordinates. No network — distance comes
+ * from {@link haversineKm} scaled by circuity, duration from a mode-adjusted
+ * average speed. Mirrors `estimate_travel` from `tempest-fastapi-sdk`.
+ *
+ * @param origin - Start coordinate.
+ * @param destination - End coordinate.
+ * @param mode - Travel mode. Default: `"car"`.
+ * @param options - Tuning knobs (circuity, speed, per-mode factors).
+ * @returns A `"heuristic"` {@link TravelEstimate}.
+ * @throws {RangeError} If `carSpeedKmh <= 0` or `circuityFactor <= 0`.
+ *
+ * @example
+ * estimateTravel(
+ *   { latitude: -23.5505, longitude: -46.6333 },
+ *   { latitude: -23.5629, longitude: -46.6544 },
+ *   "car",
+ * ); // { mode: "car", distance_km: …, duration_minutes: …, source: "heuristic" }
+ */
+export declare function estimateTravel(origin: Coordinate, destination: Coordinate, mode?: TravelMode, options?: EstimateTravelOptions): TravelEstimate;
+
+/** Options for {@link estimateTravel}. */
+export declare interface EstimateTravelOptions {
+    /** Distance multiplier over the great-circle line. Default: `1.3`. */
+    circuityFactor?: number;
+    /** Average car speed in km/h. Default: `50`. */
+    carSpeedKmh?: number;
+    /** Per-mode duration multipliers (merged over the defaults). */
+    modeDurationFactors?: Partial<Record<TravelMode, number>>;
+}
+
 export declare interface EventStreamController {
     close: () => void;
     /** Force an immediate reconnect, resetting the retry counter. */
@@ -2386,6 +2556,18 @@ export declare interface EventStreamMessage<T> {
 
 export declare type EventStreamStatus = "idle" | "connecting" | "open" | "closed" | "error";
 
+/**
+ * Grow a bounding box outward by `ratio` of its own span on every side, with a
+ * small absolute floor so a single-point (zero-span) box still gets padding.
+ * A `ratio` of `0.1` adds 10% margin — handy so a plotted trajectory does not
+ * hug the edge of the viewport.
+ *
+ * @param bounds - The box to expand.
+ * @param ratio - Fraction of the span to add per side. Default: `0.1`.
+ * @returns A new, larger {@link GeoBounds}.
+ */
+export declare function expandBounds(bounds: GeoBounds, ratio?: number): GeoBounds;
+
 export declare interface FeatureFlagsAdapter {
     /** Synchronous lookup of a flag with a default. */
     isEnabled: (key: string, defaultValue?: boolean) => boolean;
@@ -2446,6 +2628,38 @@ export declare interface FileUploadProps {
 
 export declare type FilterPredicate<T> = (item: T, search: string) => boolean;
 
+/**
+ * Build a projection that fits `bounds` into a `width × height` viewport while
+ * preserving aspect ratio (uniform scale, centered). This is what powers the
+ * tile-free trajectory plot: project the bounds, scale to the SVG box, keep
+ * shapes undistorted.
+ *
+ * @param bounds - Geographic extent to fit.
+ * @param width - Viewport width in pixels.
+ * @param height - Viewport height in pixels.
+ * @param options - Padding tuning.
+ * @returns A {@link FittedProjection} with a `project(coord)` mapper.
+ */
+export declare function fitProjection(bounds: GeoBounds, width: number, height: number, options?: FitProjectionOptions): FittedProjection;
+
+/** Options for {@link fitProjection}. */
+export declare interface FitProjectionOptions {
+    /** Inner padding in pixels kept clear on every edge. Default: `16`. */
+    padding?: number;
+}
+
+/** A ready-to-use mapping from coordinates to viewport pixels. */
+export declare interface FittedProjection {
+    /** Project a coordinate to a pixel inside the viewport. */
+    project: (coord: Coordinate) => PixelPoint;
+    /** Uniform scale (unit-plane → pixels) actually used, after aspect fit. */
+    scale: number;
+    /** Viewport width in pixels. */
+    width: number;
+    /** Viewport height in pixels. */
+    height: number;
+}
+
 export declare type FlagValue = boolean | string | number | null;
 
 /**
@@ -2739,6 +2953,17 @@ export declare interface ForProps<T> {
  */
 export declare function generateIdempotencyKey(): string;
 
+/**
+ * Axis-aligned geographic bounding box. `min`/`max` follow the same degree
+ * ranges as {@link Coordinate}.
+ */
+export declare interface GeoBounds {
+    minLatitude: number;
+    maxLatitude: number;
+    minLongitude: number;
+    maxLongitude: number;
+}
+
 export declare interface GeolocationState {
     loading: boolean;
     error: GeolocationPositionError | null;
@@ -2880,6 +3105,22 @@ export declare interface GrowthBookLike {
 
 export { HashRouter }
 
+/**
+ * Great-circle distance between two coordinates using the haversine formula
+ * (spherical Earth). Mirrors `haversine_km` from `tempest-fastapi-sdk`.
+ *
+ * @param origin - Start coordinate.
+ * @param destination - End coordinate.
+ * @returns Distance in kilometers (`>= 0`).
+ *
+ * @example
+ * haversineKm(
+ *   { latitude: -23.5505, longitude: -46.6333 }, // São Paulo
+ *   { latitude: -22.9068, longitude: -43.1729 }, // Rio de Janeiro
+ * ); // ≈ 360.9
+ */
+export declare function haversineKm(origin: Coordinate, destination: Coordinate): number;
+
 /** Inverse of `<Show>` — hides children when the condition matches. */
 export declare function Hide({ above, below, only, children }: HideProps): ReactNode;
 
@@ -3199,6 +3440,12 @@ export declare type InterpolationValues = Record<string, string | number>;
  */
 export declare function isApiError(error: unknown): error is ApiError;
 
+/**
+ * Type guard for {@link Coordinate}: an object with finite, in-range
+ * `latitude` and `longitude`.
+ */
+export declare function isCoordinate(value: unknown): value is Coordinate;
+
 /**
  * Type guard for a {@link CursorPage} envelope.
  *
@@ -3296,6 +3543,12 @@ export declare function isShareSupported(): boolean;
  */
 export declare function isString(value: unknown): value is string;
 
+/** True when `value` is a finite latitude in `[-90, 90]`. */
+export declare function isValidLatitude(value: number): boolean;
+
+/** True when `value` is a finite longitude in `[-180, 180]`. */
+export declare function isValidLongitude(value: number): boolean;
+
 /**
  * Renders a `<kbd>` styled like a keyboard key — useful for shortcut hints.
  * Compose multiple keys by rendering siblings: `<Kbd>Ctrl</Kbd> + <Kbd>K</Kbd>`.
@@ -3558,6 +3811,21 @@ export declare interface MenubarProps extends HTMLAttributes<HTMLDivElement> {
     menus: MenubarMenu[];
 }
 
+/**
+ * Web Mercator (EPSG:3857) latitude clamp. Latitudes beyond this diverge to
+ * infinity in the projection, so tile maps cap here.
+ */
+export declare const MERCATOR_MAX_LATITUDE = 85.05112878;
+
+/**
+ * A point projected onto the unit Web Mercator plane. Both axes are in `[0, 1]`
+ * — `x` grows east, `y` grows south (screen convention).
+ */
+export declare interface MercatorPoint {
+    x: number;
+    y: number;
+}
+
 export declare type Messages = Record<string, string>;
 
 /**
@@ -3812,6 +4080,12 @@ export declare interface NavigationRailProps extends Omit<HTMLAttributes<HTMLEle
 
 export { NavLink }
 
+/**
+ * Normalize a longitude into the `[-180, 180]` range, wrapping values that
+ * cross the antimeridian (e.g. `190` → `-170`).
+ */
+export declare function normalizeLongitude(longitude: number): number;
+
 /**
  * Module-level singleton progress controller. Drive it imperatively from
  * anywhere (router transitions, fetch interceptors) and render the visual bar
@@ -4011,6 +4285,19 @@ export declare interface OpenModalOptions {
     onClose?: () => void;
 }
 
+/** Options for {@link createOSRMBackend}. */
+export declare interface OSRMBackendOptions {
+    /**
+     * Base URL of an **OSRM** HTTP server. There is no default on purpose — this
+     * SDK ships no external endpoint. Point it at a routing engine **you host**.
+     */
+    baseUrl: string;
+    /** `fetch` implementation. Default: the global `fetch`. */
+    fetch?: typeof globalThis.fetch;
+    /** Per-mode duration multipliers applied over the car profile. */
+    modeDurationFactors?: Partial<Record<TravelMode, number>>;
+}
+
 export { Outlet }
 
 /**
@@ -4113,6 +4400,15 @@ export declare type PasswordStrength = 0 | 1 | 2 | 3 | 4;
 
 export { Path }
 
+/**
+ * Total length of a trajectory: the sum of haversine distances between each
+ * consecutive pair of points. Returns `0` for an empty or single-point path.
+ *
+ * @param points - Ordered coordinates along the path.
+ * @returns Cumulative distance in kilometers.
+ */
+export declare function pathLengthKm(points: readonly Coordinate[]): number;
+
 /**
  * Extract a permission list from a JWT.
  *
@@ -4193,6 +4489,12 @@ export declare type PinInputSize = "sm" | "md" | "lg";
 
 export declare type PinInputType = "numeric" | "alphanumeric";
 
+/** A pixel coordinate inside the plotting viewport. */
+export declare interface PixelPoint {
+    x: number;
+    y: number;
+}
+
 /**
  * Convenience wrapper around a shared {@link AudioPlayer}. Use this for
  * one-off notification sounds. For more complex flows (e.g. several
@@ -4281,6 +4583,22 @@ export declare interface PortalProps {
     container?: Element | null;
 }
 
+/** Imperative controller returned by {@link createPositionTracker}. */
+export declare interface PositionTracker {
+    /** Begin watching position. No-op if already tracking. */
+    start: () => void;
+    /** Stop watching. Retains the recorded trajectory. */
+    stop: () => void;
+    /** Stop and discard the recorded trajectory. */
+    clear: () => void;
+    /** Snapshot of the recorded trajectory (newest last). */
+    readonly points: readonly TrackPoint[];
+    /** Total distance of the recorded trajectory in kilometers. */
+    readonly distanceKm: number;
+    /** Current tracker status. */
+    readonly status: TrackerStatus;
+}
+
 /**
  * Minimal subset of `posthog-js` used by the adapter. Pass either the real
  * default export (`import posthog from "posthog-js"`) or a stubbed object
@@ -4313,6 +4631,16 @@ export declare interface ProgressProps {
 
 export declare type ProgressVariant = "primary" | "success" | "warning" | "danger";
 
+/**
+ * Project a geographic coordinate onto the unit Web Mercator plane. This is the
+ * same projection tile servers use, so a self-hosted tile layer and the
+ * tile-free SVG plot line up pixel-for-pixel.
+ *
+ * @param coord - Coordinate to project.
+ * @returns `{ x, y }` in `[0, 1]`.
+ */
+export declare function projectMercator(coord: Coordinate): MercatorPoint;
+
 /**
  * Service-worker context helpers for handling `push` and `notificationclick`
  * events. Import these inside your own `sw.ts` — they expect to run in the
@@ -4700,6 +5028,21 @@ export declare type RouterKind = "browser" | "hash" | "memory";
 
 export { Routes }
 
+/**
+ * Pluggable routing backend. A backend turns two coordinates into a
+ * {@link TravelEstimate}. Mirrors the `RoutingBackend` protocol from
+ * `tempest-fastapi-sdk` so client and server share the same contract.
+ *
+ * Implement this to route against your own self-hosted engine (OSRM, Valhalla,
+ * GraphHopper). The offline {@link estimateTravel} heuristic satisfies the same
+ * shape without any network.
+ */
+export declare interface RoutingBackend {
+    route: (origin: Coordinate, destination: Coordinate, options?: {
+        mode?: TravelMode;
+    }) => Promise<TravelEstimate>;
+}
+
 /** A single runtime-caching rule, matched against each `GET` request. */
 export declare interface RuntimeRoute {
     /** A `RegExp` tested against the full URL, or a predicate over the parsed URL. */
@@ -5741,6 +6084,89 @@ export declare interface TooltipProps {
     openDelay?: number;
 }
 
+/** Convert degrees to radians. */
+export declare function toRadians(degrees: number): number;
+
+/** Lifecycle status of a {@link PositionTracker}. */
+export declare type TrackerStatus = "idle" | "tracking" | "error";
+
+/**
+ * A single sample in a recorded trajectory: a {@link Coordinate} stamped with
+ * the epoch millisecond it was captured, plus the optional accuracy radius
+ * reported by the Geolocation API.
+ */
+export declare interface TrackPoint extends Coordinate {
+    /** Capture time in epoch milliseconds (`GeolocationPosition.timestamp`). */
+    timestamp: number;
+    /** Horizontal accuracy radius in meters, if the device reported one. */
+    accuracy?: number;
+}
+
+/**
+ * Plot a GPS trajectory. By default it renders a **tile-free SVG** map (Web
+ * Mercator projection, auto-fit to the points, optional grid + scale bar) —
+ * 100% self-contained, no external tiles or paid API. Pass `tileUrl` pointing
+ * at a map server **you host** to upgrade to a real Leaflet tile layer.
+ *
+ * @example
+ * // Zero-dependency SVG plot
+ * <TrajectoryMap points={points} current={lastPoint} height={360} />
+ *
+ * @example
+ * // Real tiles from your own server (requires `leaflet` installed)
+ * <TrajectoryMap points={points} tileUrl="https://tiles.internal/{z}/{x}/{y}.png" />
+ */
+export declare function TrajectoryMap({ points, current, height, padding, showGrid, showScale, strokeColor, tileUrl, tileAttribution, label, className, style, ...rest }: TrajectoryMapProps): JSX.Element;
+
+export declare interface TrajectoryMapProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+    /** Ordered coordinates forming the trajectory. */
+    points: readonly Coordinate[];
+    /** Optional "current position" marker, drawn on top of the path. */
+    current?: Coordinate | null;
+    /** Viewport height in pixels. Default: `320`. */
+    height?: number;
+    /** Inner padding in pixels kept clear on every edge. Default: `24`. */
+    padding?: number;
+    /** Draw a light reference grid behind the path (SVG mode). Default: `true`. */
+    showGrid?: boolean;
+    /** Draw a distance scale bar (SVG mode). Default: `true`. */
+    showScale?: boolean;
+    /** Path stroke color. Default: the primary token. */
+    strokeColor?: string;
+    /**
+     * Tile URL template (`{z}/{x}/{y}`) of a map server **you host**. When set,
+     * the map upgrades to a real Leaflet tile layer (requires `leaflet` to be
+     * installed). Omit for the zero-dependency, zero-network SVG plot.
+     */
+    tileUrl?: string;
+    /** Attribution text shown over the tile layer. */
+    tileAttribution?: string;
+    /** Accessible label for the map region. Default: `"Trajetória"`. */
+    label?: string;
+}
+
+/**
+ * Estimated travel between two coordinates. Mirrors the `TravelEstimate`
+ * schema from `tempest-fastapi-sdk` (`geo/schemas.py`), snake_case preserved so
+ * a response deserializes straight into this type.
+ */
+export declare interface TravelEstimate {
+    /** Travel mode the estimate was computed for. */
+    mode: TravelMode;
+    /** Great-circle distance scaled by circuity, in kilometers (`>= 0`). */
+    distance_km: number;
+    /** Estimated duration in minutes (`>= 0`). */
+    duration_minutes: number;
+    /** How the estimate was produced. `"heuristic"` (offline) or `"osrm"`. */
+    source: "heuristic" | "osrm";
+}
+
+/**
+ * Travel mode. Mirrors the `TravelMode` string enum from `tempest-fastapi-sdk`
+ * (`geo/enums.py`) — the on-the-wire value is the raw string.
+ */
+export declare type TravelMode = "car" | "motorcycle" | "bus";
+
 /**
  * Truncate a string to `max` characters, appending `suffix` when cut.
  * Returns the original when shorter than (or equal to) `max`.
@@ -5788,6 +6214,15 @@ export declare function uniqueBy<T>(items: T[], key: (item: T) => unknown): T[];
 /** Strip any masking and return only digits. */
 export declare function unmask(value: string): string;
 
+/**
+ * Inverse of {@link projectMercator}: recover a coordinate from a unit-plane
+ * point.
+ *
+ * @param point - `{ x, y }` in `[0, 1]`.
+ * @returns The geographic coordinate.
+ */
+export declare function unprojectMercator(point: MercatorPoint): Coordinate;
+
 /**
  * Unregister all registered service workers for this origin.
  *
@@ -6597,6 +7032,49 @@ export declare interface UsePollResult<T> {
     start: () => void;
 }
 
+/**
+ * React hook wrapping {@link createPositionTracker}. Records a live GPS
+ * trajectory tied to the component lifecycle — the watch is torn down on
+ * unmount. Fully browser-side; no external service.
+ *
+ * @example
+ * const { points, distanceKm, isTracking, start, stop } = usePositionTracker({
+ *   minDistanceKm: 0.01,
+ * });
+ * return (
+ *   <>
+ *     <button onClick={isTracking ? stop : start}>{isTracking ? "Parar" : "Rastrear"}</button>
+ *     <TrajectoryMap points={points} />
+ *     <span>{distanceKm.toFixed(2)} km</span>
+ *   </>
+ * );
+ */
+export declare function usePositionTracker(options?: UsePositionTrackerOptions): UsePositionTrackerResult;
+
+export declare interface UsePositionTrackerOptions extends Omit<CreatePositionTrackerOptions, "onUpdate" | "onStatusChange"> {
+    /** Start tracking automatically on mount. Default: `false`. */
+    autoStart?: boolean;
+}
+
+export declare interface UsePositionTrackerResult {
+    /** Recorded trajectory (newest last). */
+    points: readonly TrackPoint[];
+    /** Most recent point, or `null` before the first fix. */
+    lastPoint: TrackPoint | null;
+    /** Total distance of the trajectory in kilometers. */
+    distanceKm: number;
+    /** Current tracker status. */
+    status: TrackerStatus;
+    /** True while `status === "tracking"`. */
+    isTracking: boolean;
+    /** Begin watching position. */
+    start: () => void;
+    /** Stop watching, keeping the trajectory. */
+    stop: () => void;
+    /** Stop and discard the trajectory. */
+    clear: () => void;
+}
+
 /**
  * Return the value from the previous render. `undefined` on the first render.
  *