@wow-two-beta/ui-vue 0.0.2

package/dist/foundation/geolocation/PositionResult.d.ts

@@ -0,0 +1,74 @@
+import { Position } from './Coordinates';
+/** The message on the `Error` reported when the platform hands back a position nothing can be read out of. */
+export declare const UnreadablePositionMessage = "Geolocation reported a position with no readable coordinates.";
+/**
+ * The outcome of a position request — one-shot or one emission of a watch.
+ *
+ * - `ok` — a fix, as a plain {@link Position} snapshot.
+ * - `denied` — code 1. Permanent for this origin until the user changes it; do not re-prompt.
+ * - `unavailable` — code 2. Transient; retry is reasonable.
+ * - `timeout` — code 3. Transient; retry, possibly with a larger `timeout`.
+ * - `unsupported` — no Geolocation API here (SSR, stripped webview). Not a failure; a capability answer.
+ * - `failed` — anything else, carrying the normalized `Error`: an unrecognized code, an unreadable position, or
+ *   a platform call that threw.
+ */
+export type PositionResult = {
+    readonly status: 'ok';
+    readonly position: Position;
+} | {
+    readonly status: 'denied';
+} | {
+    readonly status: 'unavailable';
+} | {
+    readonly status: 'timeout';
+} | {
+    readonly status: 'unsupported';
+} | {
+    readonly status: 'failed';
+    readonly error: Error;
+};
+/** The `status` discriminant of a {@link PositionResult} — for a consumer's own switch or status→copy map. */
+export type PositionStatus = PositionResult['status'];
+/**
+ * Tunes a position request. Mirrors the platform's `PositionOptions`, restated here so the public API of this
+ * slice owns its own input type and can document what each field actually costs.
+ */
+export interface PositionRequestOptions {
+    /**
+     * Asks for the most accurate fix the device can give — GPS rather than wifi/cell triangulation. Slower to
+     * acquire and materially more battery-hungry; leave it off unless the accuracy genuinely changes the UI.
+     */
+    readonly enableHighAccuracy?: boolean;
+    /**
+     * Milliseconds to wait for a fix before answering `timeout`. Unset means wait indefinitely — which is why a
+     * request with no timeout can leave a UI spinning forever indoors. A cold GPS fix can need 10–30s.
+     */
+    readonly timeout?: number;
+    /**
+     * Milliseconds a cached fix may be old and still be handed back instantly. `0` (the platform default) forces
+     * a fresh acquisition every time; a few seconds is usually a better trade for a UI that asks repeatedly.
+     */
+    readonly maximumAge?: number;
+}
+/**
+ * Translates a value from a geolocation error callback into its {@link PositionResult}. Exported for the two
+ * sibling entry points; absent from the barrel.
+ *
+ * Never throws — a hostile error object degrades to `failed`, never to an exception thrown inside a platform
+ * callback.
+ *
+ * @param raw The value handed to a `getCurrentPosition` / `watchPosition` error callback.
+ */
+export declare function toPositionResult(raw: unknown): PositionResult;
+/**
+ * Translates a value from a geolocation success callback into its {@link PositionResult}, converting the host
+ * object into a plain snapshot on the way. Exported for the two sibling entry points; absent from the barrel.
+ *
+ * A success callback that carries nothing readable becomes `failed` rather than `ok` with a hollow position —
+ * a consumer must never receive a `status: 'ok'` it cannot plot.
+ *
+ * Never throws.
+ *
+ * @param raw The value handed to a `getCurrentPosition` / `watchPosition` success callback.
+ */
+export declare function toPositionSuccess(raw: unknown): PositionResult;

package/dist/foundation/geolocation/UseGeolocation.d.ts

@@ -0,0 +1,38 @@
+import { ComputedRef, MaybeRefOrGetter } from 'vue';
+import { Position } from './Coordinates';
+import { GeolocationState } from './GeolocationReading';
+import { PositionRequestOptions, PositionResult } from './PositionResult';
+/**
+ * What {@link useGeolocation} returns — the reactive form of a {@link GeolocationReading} plus the action that
+ * refreshes it.
+ */
+export interface GeolocationControls {
+    /** The lifecycle state — drive the whole UI off this one switch. */
+    readonly status: ComputedRef<GeolocationState>;
+    /**
+     * The most recent successful fix, or `null` before the first one. Deliberately NOT cleared by a later
+     * failure — check `status.value === 'ok'` when only a currently-valid reading will do.
+     */
+    readonly position: ComputedRef<Position | null>;
+    /** The error behind a `failed` status, or `null` for every other status. Never stale. */
+    readonly error: ComputedRef<Error | null>;
+    /** Convenience for `status === 'locating'` — the flag a button's `disabled` / spinner wants. */
+    readonly locating: ComputedRef<boolean>;
+    /**
+     * Requests a fix, writing the outcome to this composable's state and also resolving to it. Never throws,
+     * never rejects. Call it from a user gesture — it is what raises the permission prompt.
+     *
+     * @param overrides Options for this call only, replacing the composable-level ones. Omit to use those.
+     */
+    readonly request: (overrides?: PositionRequestOptions) => Promise<PositionResult>;
+}
+/**
+ * Exposes the device's position as reactive state, with a `request()` that fetches it on demand.
+ *
+ * Requests nothing on mount — see the header for why that is deliberate. Inherits the slice's never-throws
+ * contract: `request` resolves to a {@link PositionResult}, never rejects.
+ *
+ * @param options Default tuning for every `request()` call. A ref or getter is read at call time, so the value
+ *   in effect is always the current one.
+ */
+export declare function useGeolocation(options?: MaybeRefOrGetter<PositionRequestOptions | undefined>): GeolocationControls;

package/dist/foundation/geolocation/UseWatchPosition.d.ts

@@ -0,0 +1,16 @@
+import { MaybeRefOrGetter, ShallowRef } from 'vue';
+import { GeolocationReading } from './GeolocationReading';
+import { PositionRequestOptions } from './PositionResult';
+/**
+ * Tracks the device's position for as long as the scope lives, clearing the watch when it is disposed.
+ *
+ * Starts on mount — see the header. Every fix and every failure arrives through the same
+ * {@link GeolocationReading} shape `useGeolocation` exposes, minus the manual `request`; the last successful
+ * fix survives a later failure, so a map keeps its pin when the signal drops.
+ *
+ * Inherits the slice's never-throws contract.
+ *
+ * @param options Accuracy / timeout / cache-age tuning. Changing any of the three values restarts the watch.
+ * @returns The current reading. Holds {@link IdleGeolocationReading} during SSR and until mount.
+ */
+export declare function useWatchPosition(options?: MaybeRefOrGetter<PositionRequestOptions | undefined>): Readonly<ShallowRef<GeolocationReading>>;

package/dist/foundation/geolocation/WatchPosition.d.ts

@@ -0,0 +1,19 @@
+import { PositionRequestOptions, PositionResult } from './PositionResult';
+/** Receives every emission of a watch — a new fix, or a failure. Called with the same union as a one-shot read. */
+export type PositionHandler = (result: PositionResult) => void;
+/**
+ * Subscribes to the device's position and calls `handler` on every fix and every failure.
+ *
+ * Unlike {@link getCurrentPosition}, a watch does not end: it keeps reporting until disposed, which is why the
+ * return value is the disposer. **Always call it** — in a watcher's `onCleanup`, on route change, when the
+ * feature is toggled off. A live watch holds the location hardware on.
+ *
+ * Emits `unsupported` once, synchronously, where there is no Geolocation API, then never again.
+ *
+ * Never throws — neither this call nor any emission.
+ *
+ * @param handler Called with each {@link PositionResult}. A throw from it is swallowed.
+ * @param options Accuracy / timeout / cache-age tuning. See {@link PositionRequestOptions}.
+ * @returns The disposer. Idempotent; safe to call more than once and after emissions have stopped.
+ */
+export declare function watchPosition(handler: PositionHandler, options?: PositionRequestOptions): () => void;

package/dist/foundation/geolocation/index.d.ts

@@ -0,0 +1,10 @@
+export { type LatLng, type Coordinates, type Position } from './Coordinates';
+export { canLocate } from './CanLocate';
+export { type PositionResult, type PositionStatus, type PositionRequestOptions, UnreadablePositionMessage, } from './PositionResult';
+export { getCurrentPosition } from './GetCurrentPosition';
+export { watchPosition, type PositionHandler } from './WatchPosition';
+export { getGeolocationPermission, type PermissionQueryState } from './GeolocationPermission';
+export { distanceBetween, EarthRadiusMetres } from './DistanceBetween';
+export { type GeolocationState, type GeolocationReading } from './GeolocationReading';
+export { useGeolocation, type GeolocationControls } from './UseGeolocation';
+export { useWatchPosition } from './UseWatchPosition';

package/dist/foundation/geolocation/index.js

@@ -0,0 +1,236 @@
+import { t as toError } from "../../chunks/ToError-CyTBsmLO.js";
+import { q as queryPermission } from "../../chunks/QueryPermission--OKfvS9c.js";
+import { shallowRef, computed, toValue, onMounted, watch, onScopeDispose } from "vue";
+function readFiniteNumber(source, key) {
+  try {
+    const value = source[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+function readObject(source, key) {
+  try {
+    const value = source[key];
+    return typeof value === "object" && value !== null ? value : null;
+  } catch {
+    return null;
+  }
+}
+function toPosition(raw) {
+  if (typeof raw !== "object" || raw === null) return null;
+  const coords = readObject(raw, "coords");
+  if (coords === null) return null;
+  const latitude = readFiniteNumber(coords, "latitude");
+  const longitude = readFiniteNumber(coords, "longitude");
+  const accuracy = readFiniteNumber(coords, "accuracy");
+  if (latitude === null || longitude === null || accuracy === null) return null;
+  return {
+    latitude,
+    longitude,
+    accuracy,
+    altitude: readFiniteNumber(coords, "altitude"),
+    altitudeAccuracy: readFiniteNumber(coords, "altitudeAccuracy"),
+    heading: readFiniteNumber(coords, "heading"),
+    speed: readFiniteNumber(coords, "speed"),
+    timestamp: readFiniteNumber(raw, "timestamp") ?? Date.now()
+  };
+}
+function geolocationApi() {
+  try {
+    if (typeof navigator === "undefined") return void 0;
+    const geolocation = navigator.geolocation;
+    if (typeof geolocation !== "object" || geolocation === null) return void 0;
+    if (typeof geolocation.getCurrentPosition !== "function") return void 0;
+    return geolocation;
+  } catch {
+    return void 0;
+  }
+}
+function canLocate() {
+  return geolocationApi() !== void 0;
+}
+const PermissionDeniedCode = 1;
+const PositionUnavailableCode = 2;
+const TimeoutCode = 3;
+const UnreadablePositionMessage = "Geolocation reported a position with no readable coordinates.";
+function readErrorCode(raw) {
+  if (typeof raw !== "object" || raw === null) return null;
+  try {
+    const code = raw.code;
+    return typeof code === "number" ? code : null;
+  } catch {
+    return null;
+  }
+}
+function toPositionResult(raw) {
+  switch (readErrorCode(raw)) {
+    case PermissionDeniedCode:
+      return { status: "denied" };
+    case PositionUnavailableCode:
+      return { status: "unavailable" };
+    case TimeoutCode:
+      return { status: "timeout" };
+    default:
+      return { status: "failed", error: toError(raw) };
+  }
+}
+function toPositionSuccess(raw) {
+  const position = toPosition(raw);
+  if (position === null) return { status: "failed", error: new Error(UnreadablePositionMessage) };
+  return { status: "ok", position };
+}
+function getCurrentPosition(options) {
+  const api = geolocationApi();
+  if (api === void 0) return Promise.resolve({ status: "unsupported" });
+  return new Promise((resolve) => {
+    let settled = false;
+    const settle = (result) => {
+      if (settled) return;
+      settled = true;
+      resolve(result);
+    };
+    try {
+      api.getCurrentPosition(
+        (raw) => settle(toPositionSuccess(raw)),
+        (error) => settle(toPositionResult(error)),
+        options
+      );
+    } catch (error) {
+      settle({ status: "failed", error: toError(error) });
+    }
+  });
+}
+function watchPosition(handler, options) {
+  let disposed = false;
+  let watchId;
+  const emit = (result) => {
+    if (disposed) return;
+    try {
+      handler(result);
+    } catch {
+    }
+  };
+  const api = geolocationApi();
+  if (api === void 0 || typeof api.watchPosition !== "function") {
+    emit({ status: "unsupported" });
+    return () => {
+      disposed = true;
+    };
+  }
+  try {
+    const id = api.watchPosition(
+      (raw) => emit(toPositionSuccess(raw)),
+      (error) => emit(toPositionResult(error)),
+      options
+    );
+    if (typeof id === "number") watchId = id;
+  } catch (error) {
+    emit({ status: "failed", error: toError(error) });
+  }
+  return () => {
+    if (disposed) return;
+    disposed = true;
+    if (watchId === void 0) return;
+    const id = watchId;
+    watchId = void 0;
+    try {
+      if (typeof api.clearWatch === "function") api.clearWatch(id);
+    } catch {
+    }
+  };
+}
+function getGeolocationPermission() {
+  return queryPermission("geolocation");
+}
+const EarthRadiusMetres = 63710088e-1;
+const DegreesToRadians = Math.PI / 180;
+function isMeasurable(a, b) {
+  return Number.isFinite(a.latitude) && Number.isFinite(a.longitude) && Number.isFinite(b.latitude) && Number.isFinite(b.longitude);
+}
+function distanceBetween(a, b) {
+  if (!isMeasurable(a, b)) return Number.NaN;
+  const latitudeA = a.latitude * DegreesToRadians;
+  const latitudeB = b.latitude * DegreesToRadians;
+  const halfLatitudeDelta = (b.latitude - a.latitude) * DegreesToRadians / 2;
+  const halfLongitudeDelta = (b.longitude - a.longitude) * DegreesToRadians / 2;
+  const chord = Math.sin(halfLatitudeDelta) ** 2 + Math.cos(latitudeA) * Math.cos(latitudeB) * Math.sin(halfLongitudeDelta) ** 2;
+  return 2 * EarthRadiusMetres * Math.atan2(Math.sqrt(chord), Math.sqrt(1 - chord));
+}
+const IdleGeolocationReading = {
+  status: "idle",
+  position: null,
+  error: null
+};
+function applyPositionResult(previous, result) {
+  return {
+    status: result.status,
+    position: result.status === "ok" ? result.position : previous.position,
+    error: result.status === "failed" ? result.error : null
+  };
+}
+function useGeolocation(options) {
+  const reading = shallowRef(IdleGeolocationReading);
+  let latestRequest = 0;
+  const request = async (overrides) => {
+    latestRequest += 1;
+    const token = latestRequest;
+    reading.value = { ...reading.value, status: "locating" };
+    const result = await getCurrentPosition(overrides ?? toValue(options));
+    if (token === latestRequest) reading.value = applyPositionResult(reading.value, result);
+    return result;
+  };
+  return {
+    status: computed(() => reading.value.status),
+    position: computed(() => reading.value.position),
+    error: computed(() => reading.value.error),
+    locating: computed(() => reading.value.status === "locating"),
+    request
+  };
+}
+function useWatchPosition(options) {
+  const reading = shallowRef(IdleGeolocationReading);
+  let dispose;
+  function stop() {
+    dispose?.();
+    dispose = void 0;
+  }
+  function start() {
+    stop();
+    reading.value = { ...reading.value, status: "locating" };
+    const resolved = toValue(options);
+    dispose = watchPosition(
+      (result) => {
+        reading.value = applyPositionResult(reading.value, result);
+      },
+      {
+        enableHighAccuracy: resolved?.enableHighAccuracy,
+        timeout: resolved?.timeout,
+        maximumAge: resolved?.maximumAge
+      }
+    );
+  }
+  onMounted(start);
+  watch(
+    [
+      () => toValue(options)?.enableHighAccuracy,
+      () => toValue(options)?.timeout,
+      () => toValue(options)?.maximumAge
+    ],
+    start
+  );
+  onScopeDispose(stop);
+  return reading;
+}
+export {
+  EarthRadiusMetres,
+  UnreadablePositionMessage,
+  canLocate,
+  distanceBetween,
+  getCurrentPosition,
+  getGeolocationPermission,
+  useGeolocation,
+  useWatchPosition,
+  watchPosition
+};
+//# sourceMappingURL=index.js.map

package/dist/foundation/geolocation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../../src/foundation/geolocation/Coordinates.ts","../../../src/foundation/geolocation/CanLocate.ts","../../../src/foundation/geolocation/PositionResult.ts","../../../src/foundation/geolocation/GetCurrentPosition.ts","../../../src/foundation/geolocation/WatchPosition.ts","../../../src/foundation/geolocation/GeolocationPermission.ts","../../../src/foundation/geolocation/DistanceBetween.ts","../../../src/foundation/geolocation/GeolocationReading.ts","../../../src/foundation/geolocation/UseGeolocation.ts","../../../src/foundation/geolocation/UseWatchPosition.ts"],"sourcesContent":["// The boundary type of the geolocation vector: a flat, plain, structurally-cloneable snapshot of one fix.\n//\n// WHY NOT PASS `GeolocationPosition` THROUGH. The object the platform hands the success callback is a HOST\n// object, and every awkward property of one applies:\n//  - it is not structurally cloneable in a useful way and does not survive `JSON.stringify` — its data sits on\n//    accessors on the prototype, so a naive clone or serialize yields `{}`. Storing it in reactive state and then\n//    persisting that state (localStorage, an IndexedDB cache, a `postMessage` to a worker) silently loses the\n//    coordinates;\n//  - it is LIVE in some engines — the same `coords` object mutated in place on the next fix — so a consumer\n//    holding two \"different\" readings can find they compare equal;\n//  - nesting (`position.coords.latitude`) forces every consumer and every assertion through two hops for data\n//    that has exactly one shape.\n// So the conversion happens once, here, at the boundary: the platform object never leaves this slice, and what\n// a consumer holds is an ordinary frozen-in-time record of numbers.\n//\n// FLAT, NOT NESTED. `Position` is `Coordinates` plus `timestamp` rather than `{ coords, timestamp }`. There is\n// no second coordinate set to disambiguate, and flattening makes both the consumer's read and the test's\n// `toEqual` a single level.\n//\n// `number | null`, NOT `number | undefined`, for the optional channels. That is what the platform reports for a\n// device with no altimeter or no heading, `null` survives `structuredClone` and `JSON` round-trips unchanged\n// (an optional property carrying `undefined` does not — it disappears), and it keeps \"the platform answered,\n// with nothing\" distinct from \"the key was never set\".\n//\n// HOSTILE READS. Every property here is read off an object this module did not create, through guarded reads:\n// a host accessor can throw, and a test double or a polyfill can supply anything at all. An unreadable required\n// field yields `null` from {@link toPosition} — a defined answer the caller turns into a `failed` result —\n// rather than an exception escaping a platform callback, where nothing can catch it.\n\n/** The minimum a point needs to be positioned on a sphere — the input {@link distanceBetween} accepts. */\nexport interface LatLng {\n  /** Degrees north of the equator, negative for south. */\n  readonly latitude: number;\n\n  /** Degrees east of the prime meridian, negative for west. */\n  readonly longitude: number;\n}\n\n/** One fix's spatial data, flattened out of the platform's `GeolocationCoordinates`. */\nexport interface Coordinates extends LatLng {\n  /** Radius of the 95%-confidence circle around the position, in metres. Always present; never negative. */\n  readonly accuracy: number;\n\n  /** Metres above the WGS-84 ellipsoid, or `null` where the device cannot measure altitude. */\n  readonly altitude: number | null;\n\n  /** Confidence interval on {@link Coordinates.altitude}, in metres, or `null` when altitude is `null`. */\n  readonly altitudeAccuracy: number | null;\n\n  /** Direction of travel in degrees clockwise from true north, or `null` when stationary or unmeasurable. */\n  readonly heading: number | null;\n\n  /** Ground speed in metres per second, or `null` where the device cannot measure it. */\n  readonly speed: number | null;\n}\n\n/** A complete fix: where the device was, and when. The value every entry point in this slice hands back. */\nexport interface Position extends Coordinates {\n  /** Milliseconds since the epoch at which the fix was taken — same base as `Date.now()`. */\n  readonly timestamp: number;\n}\n\n/**\n * Reads one numeric field off an object of unknown provenance. Returns `null` for a missing field, a\n * non-numeric one, `NaN`/`Infinity`, or an accessor that throws — all of which mean the same thing to the\n * caller: no usable number here.\n */\nfunction readFiniteNumber(source: object, key: string): number | null {\n  try {\n    const value: unknown = (source as Record<string, unknown>)[key];\n    return typeof value === 'number' && Number.isFinite(value) ? value : null;\n  } catch {\n    return null;\n  }\n}\n\n/** Reads a nested object field, guarded the same way. Returns `null` when it is absent or not an object. */\nfunction readObject(source: object, key: string): object | null {\n  try {\n    const value: unknown = (source as Record<string, unknown>)[key];\n    return typeof value === 'object' && value !== null ? value : null;\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Converts the platform's position object into a plain {@link Position}, or `null` when it carries no usable\n * fix. Exported for the sibling modules that own the platform callbacks; absent from the barrel, where a\n * consumer only ever meets the converted form.\n *\n * `latitude`, `longitude` and `accuracy` are load-bearing: without all three there is no position to report, so\n * an unreadable one collapses the whole reading to `null`. The optional channels degrade individually to\n * `null`. A missing or unreadable `timestamp` falls back to `Date.now()` — the read is happening now, and a fix\n * without a time is harder to use than one with an approximate one.\n *\n * Never throws.\n *\n * @param raw The value handed to a `getCurrentPosition` / `watchPosition` success callback.\n * @returns The plain snapshot, or `null` if no fix could be read out of it.\n */\nexport function toPosition(raw: unknown): Position | null {\n  if (typeof raw !== 'object' || raw === null) return null;\n\n  const coords = readObject(raw, 'coords');\n  if (coords === null) return null;\n\n  const latitude = readFiniteNumber(coords, 'latitude');\n  const longitude = readFiniteNumber(coords, 'longitude');\n  const accuracy = readFiniteNumber(coords, 'accuracy');\n  if (latitude === null || longitude === null || accuracy === null) return null;\n\n  return {\n    latitude,\n    longitude,\n    accuracy,\n    altitude: readFiniteNumber(coords, 'altitude'),\n    altitudeAccuracy: readFiniteNumber(coords, 'altitudeAccuracy'),\n    heading: readFiniteNumber(coords, 'heading'),\n    speed: readFiniteNumber(coords, 'speed'),\n    timestamp: readFiniteNumber(raw, 'timestamp') ?? Date.now(),\n  };\n}\n","// Capability detection for the Geolocation API — the one guard every other module in this slice runs first.\n//\n// Three absences collapse to the same answer, and all three are ordinary rather than exceptional:\n//  - no `navigator` at all — SSR, or a worker without one;\n//  - `navigator` present but no `geolocation` — a stripped embedded webview, a privacy build, a test double;\n//  - `geolocation` present but not actually callable — a partial polyfill, a `Proxy` stand-in.\n// Each is checked by shape rather than by trusting the type declarations, because at runtime the DOM lib's\n// promise that `navigator.geolocation` exists is only a promise.\n//\n// The whole probe sits in a `try`: on a hardened page `navigator` can be a `Proxy` whose `get` trap throws, and\n// a capability probe that throws would defeat its own purpose.\n//\n// NOT DETECTED HERE: whether geolocation is permitted. A secure-context violation, a `Permissions-Policy` block\n// and a user denial all leave the API present and callable — they surface as a `denied` / `failed` RESULT from\n// the call, not as a missing capability. `canLocate()` answers \"is there an API to ask\", never \"will it work\".\n\n/**\n * Returns `navigator.geolocation` when it is present and callable, `undefined` otherwise. Exported for the\n * sibling modules, which need the object itself; absent from the barrel, where {@link canLocate} is the boolean\n * a consumer wants.\n *\n * Never throws.\n */\nexport function geolocationApi(): Geolocation | undefined {\n  try {\n    if (typeof navigator === 'undefined') return undefined;\n\n    const geolocation: unknown = navigator.geolocation;\n    if (typeof geolocation !== 'object' || geolocation === null) return undefined;\n    if (typeof (geolocation as Geolocation).getCurrentPosition !== 'function') return undefined;\n\n    return geolocation as Geolocation;\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Whether this environment exposes a usable Geolocation API.\n *\n * Use it to decide whether to render a \"Use my location\" affordance at all. It does NOT predict success: the\n * API can be present and still answer `denied` (user or policy) or `unavailable` (no fix). Treat a `false` as\n * \"hide the feature\" and the call's own result as \"what happened\".\n *\n * Never throws. Returns `false` under SSR.\n */\nexport function canLocate(): boolean {\n  return geolocationApi() !== undefined;\n}\n","// The shared vocabulary of a position request: what goes in (options), what comes back (a discriminated\n// result), and the translation of the platform's error object into it. Both entry points — the one-shot\n// `getCurrentPosition` and the streaming `watchPosition` — speak exactly this, so a consumer writes ONE switch\n// and reuses it for both.\n//\n// THE CODE MAPPING IS THE POINT OF THIS MODULE. `GeolocationPositionError` reports failure as a bare integer,\n// and the three values mean things a UI must treat completely differently:\n//   1 PERMISSION_DENIED    → the user (or a `Permissions-Policy` header) said no. Asking again does nothing\n//                            until they change it in browser settings — so the UI must stop asking and explain.\n//   2 POSITION_UNAVAILABLE → the request was allowed but no fix came back: indoors, no GPS, radio off. This one\n//                            IS worth retrying, and is the single most common failure in the wild.\n//   3 TIMEOUT              → allowed, still trying, ran out of `timeout` ms. Retryable, and a hint that the\n//                            budget was too tight for a cold GPS fix.\n// Collapsing them into one \"location error\" is what the module exists to prevent: it produces UIs that tell a\n// user in a basement to check their browser permissions.\n//\n// The codes are compared as NUMERIC LITERALS, not as `GeolocationPositionError.PERMISSION_DENIED`. The named\n// constants live on the platform's own constructor, which does not exist under SSR and does not exist on the\n// plain `{ code: 1 }` object a test double or a Cordova-era polyfill throws. The integers are frozen by the W3C\n// spec and are the only part of the error that is reliably there.\n//\n// A code outside 1–3 (including a missing or unreadable one) is NOT silently bucketed into `unavailable`: it\n// becomes `failed` carrying a normalized `Error`, so a future spec addition or a broken polyfill surfaces as\n// something a consumer can log rather than as a plausible-looking lie.\n\nimport { toError } from '../errors';\n\nimport { toPosition, type Position } from './Coordinates';\n\n/** `GeolocationPositionError.PERMISSION_DENIED` — the user or a policy refused. */\nconst PermissionDeniedCode = 1;\n\n/** `GeolocationPositionError.POSITION_UNAVAILABLE` — allowed, but no fix could be acquired. */\nconst PositionUnavailableCode = 2;\n\n/** `GeolocationPositionError.TIMEOUT` — allowed, but the fix did not arrive inside the timeout budget. */\nconst TimeoutCode = 3;\n\n/** The message on the `Error` reported when the platform hands back a position nothing can be read out of. */\nexport const UnreadablePositionMessage = 'Geolocation reported a position with no readable coordinates.';\n\n/**\n * The outcome of a position request — one-shot or one emission of a watch.\n *\n * - `ok` — a fix, as a plain {@link Position} snapshot.\n * - `denied` — code 1. Permanent for this origin until the user changes it; do not re-prompt.\n * - `unavailable` — code 2. Transient; retry is reasonable.\n * - `timeout` — code 3. Transient; retry, possibly with a larger `timeout`.\n * - `unsupported` — no Geolocation API here (SSR, stripped webview). Not a failure; a capability answer.\n * - `failed` — anything else, carrying the normalized `Error`: an unrecognized code, an unreadable position, or\n *   a platform call that threw.\n */\nexport type PositionResult =\n  | { readonly status: 'ok'; readonly position: Position }\n  | { readonly status: 'denied' }\n  | { readonly status: 'unavailable' }\n  | { readonly status: 'timeout' }\n  | { readonly status: 'unsupported' }\n  | { readonly status: 'failed'; readonly error: Error };\n\n/** The `status` discriminant of a {@link PositionResult} — for a consumer's own switch or status→copy map. */\nexport type PositionStatus = PositionResult['status'];\n\n/**\n * Tunes a position request. Mirrors the platform's `PositionOptions`, restated here so the public API of this\n * slice owns its own input type and can document what each field actually costs.\n */\nexport interface PositionRequestOptions {\n  /**\n   * Asks for the most accurate fix the device can give — GPS rather than wifi/cell triangulation. Slower to\n   * acquire and materially more battery-hungry; leave it off unless the accuracy genuinely changes the UI.\n   */\n  readonly enableHighAccuracy?: boolean;\n\n  /**\n   * Milliseconds to wait for a fix before answering `timeout`. Unset means wait indefinitely — which is why a\n   * request with no timeout can leave a UI spinning forever indoors. A cold GPS fix can need 10–30s.\n   */\n  readonly timeout?: number;\n\n  /**\n   * Milliseconds a cached fix may be old and still be handed back instantly. `0` (the platform default) forces\n   * a fresh acquisition every time; a few seconds is usually a better trade for a UI that asks repeatedly.\n   */\n  readonly maximumAge?: number;\n}\n\n/**\n * Reads the numeric `code` off a value of unknown provenance. Returns `null` for a missing or non-numeric code\n * and for an accessor that throws — a platform error object is read inside a callback, where an exception\n * cannot be caught by the original caller.\n */\nfunction readErrorCode(raw: unknown): number | null {\n  if (typeof raw !== 'object' || raw === null) return null;\n  try {\n    const code: unknown = (raw as Record<string, unknown>).code;\n    return typeof code === 'number' ? code : null;\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Translates a value from a geolocation error callback into its {@link PositionResult}. Exported for the two\n * sibling entry points; absent from the barrel.\n *\n * Never throws — a hostile error object degrades to `failed`, never to an exception thrown inside a platform\n * callback.\n *\n * @param raw The value handed to a `getCurrentPosition` / `watchPosition` error callback.\n */\nexport function toPositionResult(raw: unknown): PositionResult {\n  switch (readErrorCode(raw)) {\n    case PermissionDeniedCode:\n      return { status: 'denied' };\n    case PositionUnavailableCode:\n      return { status: 'unavailable' };\n    case TimeoutCode:\n      return { status: 'timeout' };\n    default:\n      return { status: 'failed', error: toError(raw) };\n  }\n}\n\n/**\n * Translates a value from a geolocation success callback into its {@link PositionResult}, converting the host\n * object into a plain snapshot on the way. Exported for the two sibling entry points; absent from the barrel.\n *\n * A success callback that carries nothing readable becomes `failed` rather than `ok` with a hollow position —\n * a consumer must never receive a `status: 'ok'` it cannot plot.\n *\n * Never throws.\n *\n * @param raw The value handed to a `getCurrentPosition` / `watchPosition` success callback.\n */\nexport function toPositionSuccess(raw: unknown): PositionResult {\n  const position = toPosition(raw);\n  if (position === null) return { status: 'failed', error: new Error(UnreadablePositionMessage) };\n  return { status: 'ok', position };\n}\n","// The one-shot read: `navigator.geolocation.getCurrentPosition` turned from a two-callback platform call into\n// an awaitable that resolves to a typed result.\n//\n// DEFINING CONTRACT: NOTHING HERE THROWS, and the returned promise never rejects. This is called straight from\n// a click handler, where a rejection nobody caught is an unhandled error and the user sees nothing happen at\n// all. Missing API, denial, no fix, timeout, an unreadable position, even a platform call that throws\n// synchronously — every path resolves to a `PositionResult` the caller switches on.\n//\n// SETTLE-ONCE. A promise executor can only settle once, but the platform hands us two callbacks and there is no\n// contract we control that says exactly one of them fires. A partial polyfill firing both — or a watch-style\n// implementation calling success repeatedly — would make every call after the first a silent no-op that is\n// invisible in a debugger. The explicit `settled` flag makes \"first answer wins\" a stated rule rather than a\n// side effect of how promises happen to work.\n//\n// NO TIMEOUT IS ADDED HERE. With no `timeout` option the platform waits indefinitely, and this module does not\n// impose a default: silently answering `timeout` at some invented deadline while the real request is still\n// running would report a failure the platform never had. A caller that needs a bound passes one — see\n// `PositionRequestOptions.timeout`, which documents why it usually should.\n\nimport { toError } from '../errors';\n\nimport { geolocationApi } from './CanLocate';\nimport { toPositionResult, toPositionSuccess, type PositionRequestOptions, type PositionResult } from './PositionResult';\n\n/**\n * Reads the device's current position once.\n *\n * The first call from an origin triggers the browser's permission prompt, so call it from a user gesture: a\n * prompt with no visible cause is the one users reflexively dismiss, and a dismissal is a `denied` that sticks.\n *\n * Never throws, never rejects — every outcome, including the absence of the API, arrives as a\n * {@link PositionResult}.\n *\n * @param options Accuracy / timeout / cache-age tuning. See {@link PositionRequestOptions}.\n * @returns The outcome: a fix, a typed refusal (`denied` / `unavailable` / `timeout`), `unsupported`, or `failed`.\n */\nexport function getCurrentPosition(options?: PositionRequestOptions): Promise<PositionResult> {\n  const api = geolocationApi();\n  if (api === undefined) return Promise.resolve({ status: 'unsupported' });\n\n  return new Promise<PositionResult>((resolve) => {\n    let settled = false;\n\n    /** Resolves with the first answer and ignores every later one. See the header. */\n    const settle = (result: PositionResult): void => {\n      if (settled) return;\n      settled = true;\n      resolve(result);\n    };\n\n    try {\n      api.getCurrentPosition(\n        (raw) => settle(toPositionSuccess(raw)),\n        (error) => settle(toPositionResult(error)),\n        options,\n      );\n    } catch (error) {\n      // A synchronous throw from the platform call itself — an insecure context on some engines, a stand-in\n      // with the wrong arity. The API was present, so this is `failed`, not `unsupported`.\n      settle({ status: 'failed', error: toError(error) });\n    }\n  });\n}\n","// The streaming read: a continuous subscription to the device's position, handed back as a disposer.\n//\n// A FORGOTTEN WATCH IS A BATTERY BUG, and the worst kind — invisible in every metric a web app has. `watchId`\n// registrations are owned by the browser, not by the page's component tree: they outlive the component that\n// started them, they are not garbage-collected when the last reference to the handler is dropped, and a\n// high-accuracy watch holds the GPS radio ACTIVE for as long as it lives. A single watch started in an effect\n// with no cleanup keeps draining after the user has navigated away from the screen that wanted it, and a\n// remount starts a second one on top. Hence the shape: this returns a disposer, not an id — there is no way to\n// call it and be handed something you can forget to clean up without noticing you were handed it.\n//\n// The disposer is IDEMPOTENT. Browsers recycle watch ids, so a second `clearWatch(id)` after the id has been\n// reissued would cancel an unrelated watch belonging to some other part of the app. The `disposed` flag makes\n// double-dispose (a watcher re-run that cleans up twice, a defensive `finally`) a no-op instead of sabotage.\n//\n// EMISSIONS AFTER DISPOSE ARE DROPPED. `clearWatch` stops future acquisitions but does not un-queue a callback\n// the platform has already scheduled, so a late fix can arrive after the consumer has torn down. The same flag\n// gates the handler.\n//\n// Every emission is the same `PositionResult` union `getCurrentPosition` resolves to — including `unsupported`,\n// emitted once and synchronously where there is no API, so a subscriber always hears exactly one answer rather\n// than waiting forever for a fix that cannot come. A throwing handler is swallowed: a consumer's broken render\n// must not kill the subscription or throw inside a platform callback.\n\nimport { toError } from '../errors';\n\nimport { geolocationApi } from './CanLocate';\nimport { toPositionResult, toPositionSuccess, type PositionRequestOptions, type PositionResult } from './PositionResult';\n\n/** Receives every emission of a watch — a new fix, or a failure. Called with the same union as a one-shot read. */\nexport type PositionHandler = (result: PositionResult) => void;\n\n/**\n * Subscribes to the device's position and calls `handler` on every fix and every failure.\n *\n * Unlike {@link getCurrentPosition}, a watch does not end: it keeps reporting until disposed, which is why the\n * return value is the disposer. **Always call it** — in a watcher's `onCleanup`, on route change, when the\n * feature is toggled off. A live watch holds the location hardware on.\n *\n * Emits `unsupported` once, synchronously, where there is no Geolocation API, then never again.\n *\n * Never throws — neither this call nor any emission.\n *\n * @param handler Called with each {@link PositionResult}. A throw from it is swallowed.\n * @param options Accuracy / timeout / cache-age tuning. See {@link PositionRequestOptions}.\n * @returns The disposer. Idempotent; safe to call more than once and after emissions have stopped.\n */\nexport function watchPosition(handler: PositionHandler, options?: PositionRequestOptions): () => void {\n  let disposed = false;\n  let watchId: number | undefined;\n\n  /** Hands the subscriber a result, absorbing a throw from their own handler and ignoring post-dispose noise. */\n  const emit = (result: PositionResult): void => {\n    if (disposed) return;\n    try {\n      handler(result);\n    } catch {\n      // The subscriber's handler failed. Their problem, and not a reason to break the subscription or to let an\n      // exception escape into a platform callback, where nothing can catch it.\n    }\n  };\n\n  const api = geolocationApi();\n  if (api === undefined || typeof api.watchPosition !== 'function') {\n    emit({ status: 'unsupported' });\n    return () => {\n      disposed = true;\n    };\n  }\n\n  try {\n    const id: unknown = api.watchPosition(\n      (raw) => emit(toPositionSuccess(raw)),\n      (error) => emit(toPositionResult(error)),\n      options,\n    );\n    // A spec-conformant implementation returns a number. Anything else is kept out of `watchId` so the disposer\n    // never hands `clearWatch` a value it cannot act on.\n    if (typeof id === 'number') watchId = id;\n  } catch (error) {\n    emit({ status: 'failed', error: toError(error) });\n  }\n\n  return () => {\n    if (disposed) return;\n    disposed = true;\n\n    if (watchId === undefined) return;\n    const id = watchId;\n    // Cleared before the call, so a throwing `clearWatch` cannot leave the disposer able to fire it twice.\n    watchId = undefined;\n\n    try {\n      if (typeof api.clearWatch === 'function') api.clearWatch(id);\n    } catch {\n      // A stand-in without a working `clearWatch`. Nothing further to do — the flag already stopped emissions.\n    }\n  };\n}\n","// The permission read — deliberately a one-line delegation, not an implementation.\n//\n// `foundation/notifications` already owns the `navigator.permissions.query` wrapper, and it was written\n// generically precisely so this slice would not need a second one: it already handles the API being absent\n// (SSR, older Safari), Safari throwing synchronously for a name it does not implement, and an off-spec state\n// string — all collapsing to `unsupported`. Re-implementing that here would give the ecosystem two wrappers\n// that drift apart, and a `geolocation` permission read that behaves subtly differently from a `notifications`\n// one for no reason a consumer could predict.\n//\n// Its home in `notifications` is historical, not semantic: notifications are the one permission needing BOTH\n// the Permissions API and a second, notification-specific source, so the generic wrapper was written there\n// first. Nothing about it is notification-specific — its own header says so.\n//\n// THIS IS A READ, NOT A REQUEST. Geolocation has no `requestPermission()`; the only way to raise the prompt is\n// to ask for a position. So the flow is: `getGeolocationPermission()` to decide what to render (`prompt` → show\n// the button, `denied` → show the \"enable it in settings\" copy), then `getCurrentPosition()` to actually ask.\n//\n// `unsupported` is not `prompt`. Where the Permissions API is missing, the grant is simply unknown — and a\n// consumer must not read \"we could not tell\" as \"the user has not been asked yet\". Geolocation itself may well\n// be present and working there; `canLocate()` is the capability question, this is the grant question.\n\nimport { queryPermission, type PermissionQueryState } from '../notifications';\n\nexport type { PermissionQueryState };\n\n/**\n * Reads the current geolocation grant without prompting for it.\n *\n * A snapshot — the returned promise fires no event on a later change. Use `usePermissionState('geolocation')`\n * from `foundation/notifications` to follow changes (a revoke from site settings, a grant given in another tab).\n *\n * Never throws, never rejects.\n *\n * @returns `granted` / `denied` / `prompt`, or `unsupported` where the Permissions API cannot answer.\n */\nexport function getGeolocationPermission(): Promise<PermissionQueryState> {\n  return queryPermission('geolocation');\n}\n","// Great-circle distance between two points — the one piece of this slice with no platform dependency at all.\n//\n// WHY HAVERSINE. It is the standard trade for UI distance: exact on a sphere, ~0.5% worst-case error against\n// the real ellipsoid (Vincenty's inverse formula closes that gap at maybe 40× the code and an iterative solve\n// that can fail to converge on near-antipodal pairs). For \"2.3 km away\" on a card, 0.5% is 11 metres. It is\n// also numerically well-behaved for SMALL separations, which is the case a UI actually hits — the older\n// spherical law of cosines is algebraically equivalent but loses catastrophic precision under ~1 km, where\n// `acos` of a value that has rounded to exactly 1 collapses to 0.\n//\n// THE ANTIMERIDIAN IS HANDLED BY THE FORMULA, NOT BY A SPECIAL CASE. The longitude term is `sin²(Δλ/2)`, and\n// sin² is periodic with period π in its argument — so a Δλ of 359° and one of −1° produce the identical term.\n// A pair straddling the 180th meridian therefore comes out as the ~111 km it really is, with no normalization,\n// no `Δλ > 180 → Δλ − 360` correction, and no branch to get wrong. Anything computed on raw degree deltas\n// (`Math.abs(b.longitude - a.longitude) * 111_000`, the naive Euclidean version) reports ~39,900 km for that\n// same pair. This is the reason the module exists rather than a one-line helper per consumer.\n//\n// `atan2(√a, √(1−a))` rather than `asin(√a)`: identical for small `a`, but numerically stable for\n// near-antipodal points where `a` approaches 1 and `asin`'s derivative goes to infinity.\n//\n// RADIUS. 6,371,008.8 m — the IUGG mean radius (R₁) of the WGS-84 ellipsoid, the same constant every mapping\n// library uses. The Earth is not a sphere, so the choice of a single radius, not the formula, is the dominant\n// error term: 6,371,000 vs 6,378,137 (equatorial) shifts every result by ~0.1%.\n//\n// NEVER THROWS. Non-finite input yields `NaN` — a value that propagates visibly and compares false against\n// every threshold — rather than an exception or a plausible-looking wrong number.\n\nimport type { LatLng } from './Coordinates';\n\n/** IUGG mean Earth radius (R₁), in metres. The sphere the haversine result is measured on. */\nexport const EarthRadiusMetres = 6_371_008.8;\n\n/** Degrees → radians. */\nconst DegreesToRadians = Math.PI / 180;\n\n/** Whether all four coordinate components are real numbers this can compute on. */\nfunction isMeasurable(a: LatLng, b: LatLng): boolean {\n  return (\n    Number.isFinite(a.latitude) &&\n    Number.isFinite(a.longitude) &&\n    Number.isFinite(b.latitude) &&\n    Number.isFinite(b.longitude)\n  );\n}\n\n/**\n * Great-circle (\"as the crow flies\") distance between two points, in metres.\n *\n * Pure and symmetric — `distanceBetween(a, b) === distanceBetween(b, a)` — and exactly `0` for identical\n * points. Correct across the antimeridian and the poles without any special-casing by the caller. Accepts\n * anything with `latitude` / `longitude`, so a {@link Position} from this slice can be passed directly.\n *\n * Not road distance and not ellipsoidal: ~0.5% worst case against a geodesic solution, dominated by the\n * spherical-Earth assumption rather than by the formula. Fine for proximity, sorting, and radius filters; not\n * for surveying.\n *\n * Never throws. Returns `NaN` if any component is `NaN`, `Infinity`, or otherwise not a finite number.\n *\n * @param a One endpoint.\n * @param b The other endpoint.\n * @returns Metres along the great circle, or `NaN` for unmeasurable input.\n */\nexport function distanceBetween(a: LatLng, b: LatLng): number {\n  if (!isMeasurable(a, b)) return Number.NaN;\n\n  const latitudeA = a.latitude * DegreesToRadians;\n  const latitudeB = b.latitude * DegreesToRadians;\n  const halfLatitudeDelta = ((b.latitude - a.latitude) * DegreesToRadians) / 2;\n  const halfLongitudeDelta = ((b.longitude - a.longitude) * DegreesToRadians) / 2;\n\n  const chord =\n    Math.sin(halfLatitudeDelta) ** 2 +\n    Math.cos(latitudeA) * Math.cos(latitudeB) * Math.sin(halfLongitudeDelta) ** 2;\n\n  return 2 * EarthRadiusMetres * Math.atan2(Math.sqrt(chord), Math.sqrt(1 - chord));\n}\n","// The render-facing state shape of the vector, plus the pure reducer that folds a `PositionResult` into it.\n//\n// Kept OUT of the composable files, and free of Vue, for two reasons: both composables need exactly the same\n// fold (a one-shot request and a watch emission update state identically), and the interesting decisions below\n// are then testable without a renderer.\n//\n// TWO STATUSES THE PLATFORM DOES NOT HAVE. `idle` (never asked) and `locating` (asked, waiting) are states a UI\n// must render — an empty frame vs. a spinner — and neither is a `PositionResult`. Extending the result union\n// rather than adding a parallel `loading` boolean keeps the whole lifecycle in ONE switch, so no consumer can\n// render a \"no location\" empty state while a request is still in flight.\n//\n// A LATER FAILURE DOES NOT ERASE THE LAST FIX. `position` holds the most recent successful reading and survives\n// a subsequent `denied` / `timeout` / `unavailable`. A map that drops its pin the moment a watch misses one\n// update is worse than one showing a slightly stale position with a \"signal lost\" note — and the consumer can\n// always ignore `position` when `status !== 'ok'` if it wants the strict reading. `error` does the opposite: it\n// is cleared on every non-`failed` outcome, so a stale message can never outlive the failure it described.\n\nimport type { Position } from './Coordinates';\nimport type { PositionResult, PositionStatus } from './PositionResult';\n\n/**\n * Where a geolocation consumer sits in its lifecycle: the platform's outcomes, plus the two states that exist\n * only in the UI — `idle` (nothing requested yet) and `locating` (a request is in flight).\n */\nexport type GeolocationState = 'idle' | 'locating' | PositionStatus;\n\n/** The state both {@link useGeolocation} and {@link useWatchPosition} expose. */\nexport interface GeolocationReading {\n  /** The lifecycle state — drive the whole UI off this one switch. */\n  readonly status: GeolocationState;\n\n  /**\n   * The most recent successful fix, or `null` before the first one. Deliberately NOT cleared by a later\n   * failure — check `status === 'ok'` when only a currently-valid reading will do.\n   */\n  readonly position: Position | null;\n\n  /** The error behind a `failed` status, or `null` for every other status. Never stale. */\n  readonly error: Error | null;\n}\n\n/** The starting state: nothing requested, nothing known. */\nexport const IdleGeolocationReading: GeolocationReading = {\n  status: 'idle',\n  position: null,\n  error: null,\n};\n\n/**\n * Folds one {@link PositionResult} into the current reading. Pure; exported for the two composables and for tests,\n * absent from the barrel.\n *\n * @param previous The reading being updated — its `position` is what carries a past fix forward.\n * @param result The outcome to apply.\n * @returns The next reading.\n */\nexport function applyPositionResult(previous: GeolocationReading, result: PositionResult): GeolocationReading {\n  return {\n    status: result.status,\n    position: result.status === 'ok' ? result.position : previous.position,\n    error: result.status === 'failed' ? result.error : null,\n  };\n}\n","// The Vue binding of the one-shot read — the position as reactive state, plus the one action that fetches it,\n// so a \"Use my location\" button is a `status` switch and a `request()` call rather than four refs re-declared\n// per consumer.\n//\n// NOTHING HAPPENS ON MOUNT, ON PURPOSE. This composable does not request a position when it mounts. The first\n// request raises the browser's permission prompt, and a prompt that appears on page load — with no visible\n// cause the user can connect it to — is the one users reflexively dismiss, which records a `denied` that sticks\n// for the origin and cannot be undone from script. So the request is always the consumer's explicit act,\n// ideally inside a click handler. Mount-time tracking is what `useWatchPosition` is for, and it is opt-in by\n// being a different composable. It is also why nothing here touches `navigator` at setup time: the SSR pass\n// runs this file, and only `request()` — which can only be called from the client — reaches the platform.\n//\n// STALE RESPONSES LOSE. A double-clicked button, or a re-request while a slow cold GPS fix is still resolving,\n// leaves two requests in flight. Without a guard the SLOWER one wins simply by finishing last, so a fresh\n// `denied` could be overwritten by a stale `ok` from before the user revoked. A monotonic token means only the\n// most recent request may write state; the earlier promise still resolves to its own result for whoever awaited\n// it, which keeps `request()`'s return value honest per call.\n//\n// Options are accepted as a ref or getter and read through `toValue` at call time, so a reactive source is\n// followed without the composable ever caching a stale copy — the Vue counterpart of the original's\n// options-in-a-ref indirection. A per-call argument overrides them, for the \"retry with a bigger timeout\" path.\n\nimport { computed, shallowRef, toValue, type ComputedRef, type MaybeRefOrGetter, type ShallowRef } from 'vue';\n\nimport type { Position } from './Coordinates';\nimport { getCurrentPosition } from './GetCurrentPosition';\nimport {\n  applyPositionResult,\n  IdleGeolocationReading,\n  type GeolocationReading,\n  type GeolocationState,\n} from './GeolocationReading';\nimport type { PositionRequestOptions, PositionResult } from './PositionResult';\n\n/**\n * What {@link useGeolocation} returns — the reactive form of a {@link GeolocationReading} plus the action that\n * refreshes it.\n */\nexport interface GeolocationControls {\n  /** The lifecycle state — drive the whole UI off this one switch. */\n  readonly status: ComputedRef<GeolocationState>;\n\n  /**\n   * The most recent successful fix, or `null` before the first one. Deliberately NOT cleared by a later\n   * failure — check `status.value === 'ok'` when only a currently-valid reading will do.\n   */\n  readonly position: ComputedRef<Position | null>;\n\n  /** The error behind a `failed` status, or `null` for every other status. Never stale. */\n  readonly error: ComputedRef<Error | null>;\n\n  /** Convenience for `status === 'locating'` — the flag a button's `disabled` / spinner wants. */\n  readonly locating: ComputedRef<boolean>;\n\n  /**\n   * Requests a fix, writing the outcome to this composable's state and also resolving to it. Never throws,\n   * never rejects. Call it from a user gesture — it is what raises the permission prompt.\n   *\n   * @param overrides Options for this call only, replacing the composable-level ones. Omit to use those.\n   */\n  readonly request: (overrides?: PositionRequestOptions) => Promise<PositionResult>;\n}\n\n/**\n * Exposes the device's position as reactive state, with a `request()` that fetches it on demand.\n *\n * Requests nothing on mount — see the header for why that is deliberate. Inherits the slice's never-throws\n * contract: `request` resolves to a {@link PositionResult}, never rejects.\n *\n * @param options Default tuning for every `request()` call. A ref or getter is read at call time, so the value\n *   in effect is always the current one.\n */\nexport function useGeolocation(\n  options?: MaybeRefOrGetter<PositionRequestOptions | undefined>,\n): GeolocationControls {\n  const reading: ShallowRef<GeolocationReading> = shallowRef(IdleGeolocationReading);\n\n  /** Monotonic request token — only the newest request may write state. See the header. */\n  let latestRequest = 0;\n\n  const request = async (overrides?: PositionRequestOptions): Promise<PositionResult> => {\n    latestRequest += 1;\n    const token = latestRequest;\n\n    reading.value = { ...reading.value, status: 'locating' };\n\n    const result = await getCurrentPosition(overrides ?? toValue(options));\n\n    if (token === latestRequest) reading.value = applyPositionResult(reading.value, result);\n    return result;\n  };\n\n  return {\n    status: computed(() => reading.value.status),\n    position: computed(() => reading.value.position),\n    error: computed(() => reading.value.error),\n    locating: computed(() => reading.value.status === 'locating'),\n    request,\n  };\n}\n","// The Vue binding of the watch — position tracking bound to a scope's lifetime.\n//\n// THE CLEANUP IS THE WHOLE POINT. `watchPosition` returns a disposer precisely because a watch outlives the\n// code that started it, and this composable exists so that \"as long as this component is mounted\" is the\n// lifetime a consumer gets for free. The disposer is called from `onScopeDispose` and again before every\n// restart, so the watch is cleared on unmount and on every option change. A watch that survived unmount would\n// keep the GPS radio active for the rest of the session with nothing on screen referencing it — a battery\n// drain no page-level metric would ever attribute to this component.\n//\n// TRACKING STARTS ON MOUNT, unlike `useGeolocation`, which requests nothing until asked. That is the trade a\n// consumer makes by choosing this composable: mounting it may raise the permission prompt, so mount it on the\n// screen that actually shows a live position — behind the toggle, not above it.\n//\n// STARTED FROM `onMounted`, NEVER FROM AN IMMEDIATE WATCHER. `watchPosition` reads `navigator.geolocation`, and\n// an immediate watcher also runs during a server render, where that global does not exist. `onMounted` is\n// client-only by construction, so the SSR pass yields the idle reading and the watch begins at hydration.\n//\n// THE WATCHED SOURCE IS THE THREE OPTION VALUES, NOT THE OPTIONS OBJECT. Watching the object itself would\n// restart the watch on every change of identity for the overwhelmingly common `useWatchPosition({ timeout:\n// 5000 })` call site. Watching the primitives restarts only when a value genuinely changed, which is the\n// intended behaviour: a changed accuracy or timeout budget requires a new watch, since the platform has no way\n// to retune a live one.\n\nimport {\n  onMounted,\n  onScopeDispose,\n  shallowRef,\n  toValue,\n  watch,\n  type MaybeRefOrGetter,\n  type ShallowRef,\n} from 'vue';\n\nimport { applyPositionResult, IdleGeolocationReading, type GeolocationReading } from './GeolocationReading';\nimport type { PositionRequestOptions } from './PositionResult';\nimport { watchPosition } from './WatchPosition';\n\n/**\n * Tracks the device's position for as long as the scope lives, clearing the watch when it is disposed.\n *\n * Starts on mount — see the header. Every fix and every failure arrives through the same\n * {@link GeolocationReading} shape `useGeolocation` exposes, minus the manual `request`; the last successful\n * fix survives a later failure, so a map keeps its pin when the signal drops.\n *\n * Inherits the slice's never-throws contract.\n *\n * @param options Accuracy / timeout / cache-age tuning. Changing any of the three values restarts the watch.\n * @returns The current reading. Holds {@link IdleGeolocationReading} during SSR and until mount.\n */\nexport function useWatchPosition(\n  options?: MaybeRefOrGetter<PositionRequestOptions | undefined>,\n): Readonly<ShallowRef<GeolocationReading>> {\n  const reading: ShallowRef<GeolocationReading> = shallowRef(IdleGeolocationReading);\n\n  let dispose: (() => void) | undefined;\n\n  function stop(): void {\n    dispose?.();\n    dispose = undefined;\n  }\n\n  function start(): void {\n    stop();\n    reading.value = { ...reading.value, status: 'locating' };\n\n    const resolved = toValue(options);\n    dispose = watchPosition(\n      (result) => {\n        reading.value = applyPositionResult(reading.value, result);\n      },\n      {\n        enableHighAccuracy: resolved?.enableHighAccuracy,\n        timeout: resolved?.timeout,\n        maximumAge: resolved?.maximumAge,\n      },\n    );\n  }\n\n  onMounted(start);\n  // Non-immediate on purpose: an immediate watcher runs on the server, where `navigator` is absent. Three\n  // separate getters rather than one returning a tuple — Vue compares each source with `Object.is`, so an\n  // options object of a fresh identity carrying the same three values does not restart the watch.\n  watch(\n    [\n      () => toValue(options)?.enableHighAccuracy,\n      () => toValue(options)?.timeout,\n      () => toValue(options)?.maximumAge,\n    ],\n    start,\n  );\n  onScopeDispose(stop);\n\n  return reading;\n}\n"],"names":[],"mappings":";;;AAmEA,SAAS,iBAAiB,QAAgB,KAA4B;AACpE,MAAI;AACF,UAAM,QAAkB,OAAmC,GAAG;AAC9D,WAAO,OAAO,UAAU,YAAY,OAAO,SAAS,KAAK,IAAI,QAAQ;AAAA,EACvE,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAGA,SAAS,WAAW,QAAgB,KAA4B;AAC9D,MAAI;AACF,UAAM,QAAkB,OAAmC,GAAG;AAC9D,WAAO,OAAO,UAAU,YAAY,UAAU,OAAO,QAAQ;AAAA,EAC/D,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAiBO,SAAS,WAAW,KAA+B;AACxD,MAAI,OAAO,QAAQ,YAAY,QAAQ,KAAM,QAAO;AAEpD,QAAM,SAAS,WAAW,KAAK,QAAQ;AACvC,MAAI,WAAW,KAAM,QAAO;AAE5B,QAAM,WAAW,iBAAiB,QAAQ,UAAU;AACpD,QAAM,YAAY,iBAAiB,QAAQ,WAAW;AACtD,QAAM,WAAW,iBAAiB,QAAQ,UAAU;AACpD,MAAI,aAAa,QAAQ,cAAc,QAAQ,aAAa,KAAM,QAAO;AAEzE,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,IACA,UAAU,iBAAiB,QAAQ,UAAU;AAAA,IAC7C,kBAAkB,iBAAiB,QAAQ,kBAAkB;AAAA,IAC7D,SAAS,iBAAiB,QAAQ,SAAS;AAAA,IAC3C,OAAO,iBAAiB,QAAQ,OAAO;AAAA,IACvC,WAAW,iBAAiB,KAAK,WAAW,KAAK,KAAK,IAAA;AAAA,EAAI;AAE9D;ACnGO,SAAS,iBAA0C;AACxD,MAAI;AACF,QAAI,OAAO,cAAc,YAAa,QAAO;AAE7C,UAAM,cAAuB,UAAU;AACvC,QAAI,OAAO,gBAAgB,YAAY,gBAAgB,KAAM,QAAO;AACpE,QAAI,OAAQ,YAA4B,uBAAuB,WAAY,QAAO;AAElF,WAAO;AAAA,EACT,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAWO,SAAS,YAAqB;AACnC,SAAO,qBAAqB;AAC9B;AClBA,MAAM,uBAAuB;AAG7B,MAAM,0BAA0B;AAGhC,MAAM,cAAc;AAGb,MAAM,4BAA4B;AAqDzC,SAAS,cAAc,KAA6B;AAClD,MAAI,OAAO,QAAQ,YAAY,QAAQ,KAAM,QAAO;AACpD,MAAI;AACF,UAAM,OAAiB,IAAgC;AACvD,WAAO,OAAO,SAAS,WAAW,OAAO;AAAA,EAC3C,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAWO,SAAS,iBAAiB,KAA8B;AAC7D,UAAQ,cAAc,GAAG,GAAA;AAAA,IACvB,KAAK;AACH,aAAO,EAAE,QAAQ,SAAA;AAAA,IACnB,KAAK;AACH,aAAO,EAAE,QAAQ,cAAA;AAAA,IACnB,KAAK;AACH,aAAO,EAAE,QAAQ,UAAA;AAAA,IACnB;AACE,aAAO,EAAE,QAAQ,UAAU,OAAO,QAAQ,GAAG,EAAA;AAAA,EAAE;AAErD;AAaO,SAAS,kBAAkB,KAA8B;AAC9D,QAAM,WAAW,WAAW,GAAG;AAC/B,MAAI,aAAa,KAAM,QAAO,EAAE,QAAQ,UAAU,OAAO,IAAI,MAAM,yBAAyB,EAAA;AAC5F,SAAO,EAAE,QAAQ,MAAM,SAAA;AACzB;ACvGO,SAAS,mBAAmB,SAA2D;AAC5F,QAAM,MAAM,eAAA;AACZ,MAAI,QAAQ,OAAW,QAAO,QAAQ,QAAQ,EAAE,QAAQ,eAAe;AAEvE,SAAO,IAAI,QAAwB,CAAC,YAAY;AAC9C,QAAI,UAAU;AAGd,UAAM,SAAS,CAAC,WAAiC;AAC/C,UAAI,QAAS;AACb,gBAAU;AACV,cAAQ,MAAM;AAAA,IAChB;AAEA,QAAI;AACF,UAAI;AAAA,QACF,CAAC,QAAQ,OAAO,kBAAkB,GAAG,CAAC;AAAA,QACtC,CAAC,UAAU,OAAO,iBAAiB,KAAK,CAAC;AAAA,QACzC;AAAA,MAAA;AAAA,IAEJ,SAAS,OAAO;AAGd,aAAO,EAAE,QAAQ,UAAU,OAAO,QAAQ,KAAK,GAAG;AAAA,IACpD;AAAA,EACF,CAAC;AACH;AChBO,SAAS,cAAc,SAA0B,SAA8C;AACpG,MAAI,WAAW;AACf,MAAI;AAGJ,QAAM,OAAO,CAAC,WAAiC;AAC7C,QAAI,SAAU;AACd,QAAI;AACF,cAAQ,MAAM;AAAA,IAChB,QAAQ;AAAA,IAGR;AAAA,EACF;AAEA,QAAM,MAAM,eAAA;AACZ,MAAI,QAAQ,UAAa,OAAO,IAAI,kBAAkB,YAAY;AAChE,SAAK,EAAE,QAAQ,eAAe;AAC9B,WAAO,MAAM;AACX,iBAAW;AAAA,IACb;AAAA,EACF;AAEA,MAAI;AACF,UAAM,KAAc,IAAI;AAAA,MACtB,CAAC,QAAQ,KAAK,kBAAkB,GAAG,CAAC;AAAA,MACpC,CAAC,UAAU,KAAK,iBAAiB,KAAK,CAAC;AAAA,MACvC;AAAA,IAAA;AAIF,QAAI,OAAO,OAAO,SAAU,WAAU;AAAA,EACxC,SAAS,OAAO;AACd,SAAK,EAAE,QAAQ,UAAU,OAAO,QAAQ,KAAK,GAAG;AAAA,EAClD;AAEA,SAAO,MAAM;AACX,QAAI,SAAU;AACd,eAAW;AAEX,QAAI,YAAY,OAAW;AAC3B,UAAM,KAAK;AAEX,cAAU;AAEV,QAAI;AACF,UAAI,OAAO,IAAI,eAAe,WAAY,KAAI,WAAW,EAAE;AAAA,IAC7D,QAAQ;AAAA,IAER;AAAA,EACF;AACF;AC9DO,SAAS,2BAA0D;AACxE,SAAO,gBAAgB,aAAa;AACtC;ACRO,MAAM,oBAAoB;AAGjC,MAAM,mBAAmB,KAAK,KAAK;AAGnC,SAAS,aAAa,GAAW,GAAoB;AACnD,SACE,OAAO,SAAS,EAAE,QAAQ,KAC1B,OAAO,SAAS,EAAE,SAAS,KAC3B,OAAO,SAAS,EAAE,QAAQ,KAC1B,OAAO,SAAS,EAAE,SAAS;AAE/B;AAmBO,SAAS,gBAAgB,GAAW,GAAmB;AAC5D,MAAI,CAAC,aAAa,GAAG,CAAC,UAAU,OAAO;AAEvC,QAAM,YAAY,EAAE,WAAW;AAC/B,QAAM,YAAY,EAAE,WAAW;AAC/B,QAAM,qBAAsB,EAAE,WAAW,EAAE,YAAY,mBAAoB;AAC3E,QAAM,sBAAuB,EAAE,YAAY,EAAE,aAAa,mBAAoB;AAE9E,QAAM,QACJ,KAAK,IAAI,iBAAiB,KAAK,IAC/B,KAAK,IAAI,SAAS,IAAI,KAAK,IAAI,SAAS,IAAI,KAAK,IAAI,kBAAkB,KAAK;AAE9E,SAAO,IAAI,oBAAoB,KAAK,MAAM,KAAK,KAAK,KAAK,GAAG,KAAK,KAAK,IAAI,KAAK,CAAC;AAClF;AChCO,MAAM,yBAA6C;AAAA,EACxD,QAAQ;AAAA,EACR,UAAU;AAAA,EACV,OAAO;AACT;AAUO,SAAS,oBAAoB,UAA8B,QAA4C;AAC5G,SAAO;AAAA,IACL,QAAQ,OAAO;AAAA,IACf,UAAU,OAAO,WAAW,OAAO,OAAO,WAAW,SAAS;AAAA,IAC9D,OAAO,OAAO,WAAW,WAAW,OAAO,QAAQ;AAAA,EAAA;AAEvD;ACUO,SAAS,eACd,SACqB;AACrB,QAAM,UAA0C,WAAW,sBAAsB;AAGjF,MAAI,gBAAgB;AAEpB,QAAM,UAAU,OAAO,cAAgE;AACrF,qBAAiB;AACjB,UAAM,QAAQ;AAEd,YAAQ,QAAQ,EAAE,GAAG,QAAQ,OAAO,QAAQ,WAAA;AAE5C,UAAM,SAAS,MAAM,mBAAmB,aAAa,QAAQ,OAAO,CAAC;AAErE,QAAI,UAAU,cAAe,SAAQ,QAAQ,oBAAoB,QAAQ,OAAO,MAAM;AACtF,WAAO;AAAA,EACT;AAEA,SAAO;AAAA,IACL,QAAQ,SAAS,MAAM,QAAQ,MAAM,MAAM;AAAA,IAC3C,UAAU,SAAS,MAAM,QAAQ,MAAM,QAAQ;AAAA,IAC/C,OAAO,SAAS,MAAM,QAAQ,MAAM,KAAK;AAAA,IACzC,UAAU,SAAS,MAAM,QAAQ,MAAM,WAAW,UAAU;AAAA,IAC5D;AAAA,EAAA;AAEJ;AClDO,SAAS,iBACd,SAC0C;AAC1C,QAAM,UAA0C,WAAW,sBAAsB;AAEjF,MAAI;AAEJ,WAAS,OAAa;AACpB,cAAA;AACA,cAAU;AAAA,EACZ;AAEA,WAAS,QAAc;AACrB,SAAA;AACA,YAAQ,QAAQ,EAAE,GAAG,QAAQ,OAAO,QAAQ,WAAA;AAE5C,UAAM,WAAW,QAAQ,OAAO;AAChC,cAAU;AAAA,MACR,CAAC,WAAW;AACV,gBAAQ,QAAQ,oBAAoB,QAAQ,OAAO,MAAM;AAAA,MAC3D;AAAA,MACA;AAAA,QACE,oBAAoB,UAAU;AAAA,QAC9B,SAAS,UAAU;AAAA,QACnB,YAAY,UAAU;AAAA,MAAA;AAAA,IACxB;AAAA,EAEJ;AAEA,YAAU,KAAK;AAIf;AAAA,IACE;AAAA,MACE,MAAM,QAAQ,OAAO,GAAG;AAAA,MACxB,MAAM,QAAQ,OAAO,GAAG;AAAA,MACxB,MAAM,QAAQ,OAAO,GAAG;AAAA,IAAA;AAAA,IAE1B;AAAA,EAAA;AAEF,iBAAe,IAAI;AAEnB,SAAO;AACT;"}

package/dist/foundation/gestures/GestureAxis.d.ts

@@ -0,0 +1,11 @@
+/** Which axis a gesture is constrained to. */
+export declare const GestureAxis: {
+    /** Horizontal only — vertical movement neither triggers recognition nor appears in the payload. */
+    readonly X: "x";
+    /** Vertical only — horizontal movement neither triggers recognition nor appears in the payload. */
+    readonly Y: "y";
+    /** Unconstrained — recognition uses straight-line distance and both deltas are reported. */
+    readonly Both: "both";
+};
+/** One of the {@link GestureAxis} values. */
+export type GestureAxis = (typeof GestureAxis)[keyof typeof GestureAxis];