@goway.to/maps 0.0.0-stage → 0.1.0

package/dist/locationStore.js

@@ -0,0 +1,132 @@
+/**
+ * The reader's location permission and position, as external stores.
+ *
+ * `<UserLocation>` reads both through `useSyncExternalStore`, so the dot
+ * appears the moment a permission is granted — by `useUserLocation().locate()`
+ * on a tap, or because it already was — with no effect anywhere.
+ *
+ * The permission is READ (`getForegroundPermissionsAsync`, which never
+ * prompts) when the first `<UserLocation>` subscribes, and settled by
+ * `useUserLocation` whenever it asks. Nothing here can show a prompt.
+ *
+ * The position is watched only while something subscribes AND the permission
+ * is granted, and it is kept in memory only: no store, cache or history.
+ */
+import * as Location from 'expo-location';
+import { isDrawableCoordinate, reportMapDefect } from './shared';
+function createPermissionStore() {
+    let state = 'unknown';
+    let reading = false;
+    const listeners = new Set();
+    const notify = () => {
+        for (const listener of listeners)
+            listener();
+    };
+    const settle = (next) => {
+        if (next === state)
+            return;
+        state = next;
+        notify();
+    };
+    const read = () => {
+        if (reading || state !== 'unknown')
+            return;
+        reading = true;
+        Location.getForegroundPermissionsAsync()
+            .then((permission) => settle(permission.granted ? 'granted' : 'denied'))
+            .catch(() => settle('denied'))
+            .finally(() => {
+            reading = false;
+        });
+    };
+    return {
+        subscribe(listener) {
+            listeners.add(listener);
+            read();
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        getSnapshot() {
+            return state;
+        },
+        /** What `useUserLocation` learned by asking. */
+        settle,
+    };
+}
+/** The one permission store; the platform's permission is one per app. */
+export const locationPermission = createPermissionStore();
+function createPositionStore() {
+    let position = null;
+    let watcher = null;
+    let starting = false;
+    let unsubscribePermission = null;
+    const listeners = new Set();
+    const notify = () => {
+        for (const listener of listeners)
+            listener();
+    };
+    const stop = () => {
+        watcher?.remove();
+        watcher = null;
+        if (position !== null) {
+            position = null;
+            notify();
+        }
+    };
+    const start = () => {
+        if (watcher || starting || locationPermission.getSnapshot() !== 'granted')
+            return;
+        starting = true;
+        Location.watchPositionAsync({ accuracy: Location.Accuracy.Balanced, distanceInterval: 10 }, (fix) => {
+            const next = { latitude: fix.coords.latitude, longitude: fix.coords.longitude };
+            // A fix with no usable position is "no dot", not "no map".
+            if (!isDrawableCoordinate(next)) {
+                reportMapDefect('userLocation', 'Skipped a location fix with a non-drawable coordinate.');
+                return;
+            }
+            position = next;
+            notify();
+        })
+            .then((subscription) => {
+            if (listeners.size === 0)
+                subscription.remove();
+            else
+                watcher = subscription;
+        })
+            .catch(() => {
+            // No fix available is not a map failure; the dot simply does not appear.
+        })
+            .finally(() => {
+            starting = false;
+        });
+    };
+    const onPermission = () => {
+        if (locationPermission.getSnapshot() === 'granted')
+            start();
+        else
+            stop();
+    };
+    return {
+        subscribe(listener) {
+            listeners.add(listener);
+            if (listeners.size === 1) {
+                unsubscribePermission = locationPermission.subscribe(onPermission);
+                onPermission();
+            }
+            return () => {
+                listeners.delete(listener);
+                if (listeners.size === 0) {
+                    unsubscribePermission?.();
+                    unsubscribePermission = null;
+                    stop();
+                }
+            };
+        },
+        getSnapshot() {
+            return position;
+        },
+    };
+}
+/** The reader's position while a `<UserLocation>` is drawn, in memory only. */
+export const userPosition = createPositionStore();

package/dist/mapRef.d.ts

@@ -0,0 +1,4 @@
+import type { MapViewRef } from './types';
+export declare const MapRefContext: import("react").Context<MapViewRef | null>;
+/** The enclosing `MapView`'s handle. Throws outside one: there is no map to move. */
+export declare function useMap(): MapViewRef;

package/dist/mapRef.js

@@ -0,0 +1,13 @@
+/**
+ * `useMap()` — the nearest `MapView`'s handle, for chrome laid over a map
+ * (a "locate me" button, a re-frame) to call from its own event handlers.
+ */
+import { createContext, useContext } from 'react';
+export const MapRefContext = createContext(null);
+/** The enclosing `MapView`'s handle. Throws outside one: there is no map to move. */
+export function useMap() {
+    const handle = useContext(MapRefContext);
+    if (!handle)
+        throw new Error('useMap() must be called inside a <MapView>.');
+    return handle;
+}

package/dist/moveMarkers.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The marks a camera COMMAND carries, so the map reports the camera it
+ * produces as the app's move and never as the reader's. Every command
+ * `@goway.to/maps` issues is marked; an engine plugin that moves the camera
+ * itself passes {@link PROGRAMMATIC} as the command's event data
+ * (`map.easeTo(options, PROGRAMMATIC)`).
+ */
+/**
+ * Marker put on every camera COMMAND the map issues, read back off the event.
+ *
+ * Marking our own commands (rather than sniffing for a DOM `originalEvent`) is
+ * the safer direction of failure: a command somebody forgets to mark reads as a
+ * user gesture, so "Search this area" appears once when it need not have. The
+ * alternative — treat anything unrecognised as programmatic — hides the button
+ * for good and looks like the feature was never built.
+ */
+export declare const PROGRAMMATIC: {
+    readonly gowayProgrammatic: true;
+};
+/**
+ * One frame of a caller-driven animation (`MapCameraOptions.transient`): a
+ * programmatic move whose `moveend` is not a settled camera.
+ */
+export declare const PROGRAMMATIC_TRANSIENT: {
+    readonly gowayProgrammatic: true;
+    readonly gowayTransient: true;
+};

package/dist/moveMarkers.js

@@ -0,0 +1,22 @@
+/**
+ * The marks a camera COMMAND carries, so the map reports the camera it
+ * produces as the app's move and never as the reader's. Every command
+ * `@goway.to/maps` issues is marked; an engine plugin that moves the camera
+ * itself passes {@link PROGRAMMATIC} as the command's event data
+ * (`map.easeTo(options, PROGRAMMATIC)`).
+ */
+/**
+ * Marker put on every camera COMMAND the map issues, read back off the event.
+ *
+ * Marking our own commands (rather than sniffing for a DOM `originalEvent`) is
+ * the safer direction of failure: a command somebody forgets to mark reads as a
+ * user gesture, so "Search this area" appears once when it need not have. The
+ * alternative — treat anything unrecognised as programmatic — hides the button
+ * for good and looks like the feature was never built.
+ */
+export const PROGRAMMATIC = { gowayProgrammatic: true };
+/**
+ * One frame of a caller-driven animation (`MapCameraOptions.transient`): a
+ * programmatic move whose `moveend` is not a settled camera.
+ */
+export const PROGRAMMATIC_TRANSIENT = { gowayProgrammatic: true, gowayTransient: true };

package/dist/nativeCameraReports.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The native canvas's camera reports: MapLibre Native's region events and its
+ * style load turned into `MapViewProps.onCameraChanged`.
+ *
+ * The counterpart of `cameraReports.web.ts`, kept free of React Native so it
+ * runs in a test; `MapCanvas.native.tsx` creates one per engine (a retry
+ * remounts the engine and creates another) and forwards the engine's events.
+ *
+ *  - `onRegionIsChanging`: the live camera, never settled.
+ *  - `onRegionDidChange`: a settled camera, unless the move was a frame of a
+ *    caller-driven animation (`MapCameraOptions.transient`).
+ *  - the style load: the camera the map opened at, by the rule both forks
+ *    share (`loadedCamera.ts`), read with `getViewState()`.
+ *
+ * `source` is the engine's own answer: MapLibre Native says whether a finger
+ * caused the change, so GoWay never infers it from a marker on the command.
+ */
+import { type CameraReading } from './loadedCamera';
+import type { MapCameraChange } from './types';
+/** MapLibre Native's `ViewState`, structurally (`center` and `bounds` in MapLibre order). */
+export interface NativeViewState {
+    center: readonly [number, number];
+    zoom: number;
+    bearing: number;
+    pitch: number;
+    bounds: readonly [number, number, number, number];
+}
+/** A region event's payload (`ViewStateChangeEvent`). */
+export interface NativeRegionChange extends NativeViewState {
+    userInteraction: boolean;
+}
+/** MapLibre Native's view state, in GoWay's terms. */
+export declare function cameraReadingOf(view: NativeViewState): CameraReading;
+export interface NativeCameraReports {
+    /** GoWay commanded the camera; `transient` for one frame of a caller-driven animation. */
+    commanded(transient: boolean): void;
+    regionWillChange(region: NativeRegionChange): void;
+    regionIsChanging(region: NativeRegionChange): void;
+    /** `true` when the change was a settled camera, `false` for a transient frame. */
+    regionDidChange(region: NativeRegionChange): boolean;
+    /** The style finished loading; only the engine's first load reports. */
+    loaded(getViewState: () => Promise<NativeViewState>): void;
+}
+export declare function createNativeCameraReports(listener: () => ((change: MapCameraChange) => void) | null | undefined): NativeCameraReports;

package/dist/nativeCameraReports.js

@@ -0,0 +1,73 @@
+/**
+ * The native canvas's camera reports: MapLibre Native's region events and its
+ * style load turned into `MapViewProps.onCameraChanged`.
+ *
+ * The counterpart of `cameraReports.web.ts`, kept free of React Native so it
+ * runs in a test; `MapCanvas.native.tsx` creates one per engine (a retry
+ * remounts the engine and creates another) and forwards the engine's events.
+ *
+ *  - `onRegionIsChanging`: the live camera, never settled.
+ *  - `onRegionDidChange`: a settled camera, unless the move was a frame of a
+ *    caller-driven animation (`MapCameraOptions.transient`).
+ *  - the style load: the camera the map opened at, by the rule both forks
+ *    share (`loadedCamera.ts`), read with `getViewState()`.
+ *
+ * `source` is the engine's own answer: MapLibre Native says whether a finger
+ * caused the change, so GoWay never infers it from a marker on the command.
+ */
+import { createLoadedCameraReporter } from './loadedCamera';
+/** MapLibre Native's view state, in GoWay's terms. */
+export function cameraReadingOf(view) {
+    const [west, south, east, north] = view.bounds;
+    return {
+        viewport: {
+            latitude: view.center[1],
+            longitude: view.center[0],
+            zoom: view.zoom,
+            bearing: view.bearing,
+            pitch: view.pitch,
+        },
+        bounds: { west, south, east, north },
+    };
+}
+export function createNativeCameraReports(listener) {
+    const loadedReport = createLoadedCameraReporter();
+    // A frame of a caller-driven animation is not a settled camera. The flag is
+    // the latest COMMAND's: every camera command declares it, and a move the
+    // reader starts ends it — a flyover the reader interrupted, or one that
+    // stopped without its closing ordinary move, leaves nothing behind, so the
+    // reader's settles are final again (on the web the marker is per event).
+    // Not cleared at every move start: a flyover's frames cross the bridge as
+    // commands ahead of their region events, so the next command's flag can
+    // already be set when the previous frame's move starts.
+    let transientCommand = false;
+    const report = (region, isFinal) => {
+        listener()?.({
+            ...cameraReadingOf(region),
+            source: region.userInteraction ? 'user' : 'programmatic',
+            isFinal,
+        });
+    };
+    return {
+        commanded(transient) {
+            transientCommand = transient;
+        },
+        regionWillChange(region) {
+            if (region.userInteraction)
+                transientCommand = false;
+            loadedReport.moveStarted();
+        },
+        regionIsChanging(region) {
+            report(region, false);
+        },
+        regionDidChange(region) {
+            const transient = transientCommand && !region.userInteraction;
+            loadedReport.moveEnded(transient);
+            report(region, !transient);
+            return !transient;
+        },
+        loaded(getViewState) {
+            loadedReport.loaded(async () => cameraReadingOf(await getViewState()), listener);
+        },
+    };
+}

package/dist/plugin.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Engine plugins: what an app attaches to the web engine beyond sources,
+ * layers and markers — a three.js custom layer, terrain, a camera rule.
+ *
+ * A plugin is an imperative object with a lifecycle, and the `<MapPlugin>`
+ * component is the ONE place an app's plugin is bound to the engine: it
+ * attaches when the engine is ready, hands the plugin every new `props` through
+ * `update`, and detaches it when the component unmounts or the engine is
+ * rebuilt. The app passes props; it never runs an effect.
+ *
+ * Web only. On native `<MapPlugin>` renders nothing: MapLibre Native has no
+ * custom-layer API.
+ *
+ * `@goway.to/maps/plugin` is this module: the protocol, and the guards every
+ * coordinate and command crossing into an engine goes through — pure, with no
+ * React and no React Native, so an engine module (and its tests) can load it.
+ */
+import type { Map as MapLibreMap } from 'maplibre-gl';
+export { asFinite, isDrawableBounds, isDrawableCoordinate, isDrawableGeoJSON, optionalScalar, reportMapDefect, runEngineCommand, toLngLat, } from './shared';
+export { PROGRAMMATIC, PROGRAMMATIC_TRANSIENT } from './moveMarkers';
+/** A source's failure, as the engine reported it. */
+export interface MapSourceError {
+    sourceId: string;
+    /** The HTTP status, when the failure was a response. */
+    status?: number;
+    message?: string;
+}
+export interface MapPluginHost {
+    /** The element the engine draws into. */
+    container: HTMLElement;
+}
+export interface MapPluginHandle<Props> {
+    /** New props for an attached plugin. */
+    update?(props: Props): void;
+    /** Undo everything `attach` did. */
+    detach(): void;
+    /**
+     * A press at a screen point, after the markers and before the basemap's
+     * labels. `true` takes it: no label is resolved and `onPress` does not fire.
+     */
+    press?(point: {
+        x: number;
+        y: number;
+    }): boolean;
+    /** Whether the pointer at `point` is over something this plugin draws (the cursor says so). */
+    hover?(point: {
+        x: number;
+        y: number;
+    }): boolean;
+    /**
+     * Whether a source's error is the plugin's to handle — a decorative source
+     * that may legitimately 404 — rather than the map's degraded state. The
+     * plugin reports what it takes, if anything is worth reporting.
+     */
+    ownsError?(error: MapSourceError): boolean;
+}
+export interface MapPlugin<Props> {
+    attach(map: MapLibreMap, props: Props, host: MapPluginHost): MapPluginHandle<Props>;
+}
+export interface MapPluginProps<Props> {
+    plugin: MapPlugin<Props>;
+    props: Props;
+}

package/dist/plugin.js

@@ -0,0 +1,2 @@
+export { asFinite, isDrawableBounds, isDrawableCoordinate, isDrawableGeoJSON, optionalScalar, reportMapDefect, runEngineCommand, toLngLat, } from './shared';
+export { PROGRAMMATIC, PROGRAMMATIC_TRANSIENT } from './moveMarkers';

package/dist/queryLayers.d.ts

@@ -0,0 +1,19 @@
+export interface QueryLayers {
+    tap: readonly string[];
+    labels: readonly string[];
+}
+export declare const NO_QUERY_LAYERS: QueryLayers;
+interface StyleLayerLike {
+    id: string;
+    type: string;
+    'source-layer'?: string;
+}
+/** The tap and label layer ids of a style document. */
+export declare function queryLayersOf(layers: readonly StyleLayerLike[] | undefined): QueryLayers;
+/**
+ * The query layers of the style at `url`, fetched once per URL and shared. A
+ * style that cannot be read answers with none: presses then resolve to bare
+ * map, which is what they did before labels were tappable.
+ */
+export declare function queryLayersForUrl(url: string): Promise<QueryLayers>;
+export {};

package/dist/queryLayers.js

@@ -0,0 +1,54 @@
+/**
+ * Which style layers a press and a label read are queried against, derived
+ * from the style document itself.
+ *
+ * Deriving beats naming: layers can be flag-gated, renamed, or absent from a
+ * style GoWay did not author, and the OpenMapTiles `source-layer` is the part
+ * no style gets to rename. Web reads the loaded style from the engine; native,
+ * whose engine does not hand the style back to JS, reads the same document
+ * over the network once per URL ({@link queryLayersForUrl}).
+ *
+ * `tap` is symbols AND circles — the POI dot is what sits at the anchor, and
+ * the label is drawn below it, so a tap on the dot has to resolve. `labels` is
+ * symbols only: a dot whose label lost its collision is not a NAME on screen.
+ */
+import { isLabelSourceLayer } from './labels';
+export const NO_QUERY_LAYERS = { tap: [], labels: [] };
+/** The tap and label layer ids of a style document. */
+export function queryLayersOf(layers) {
+    const tap = [];
+    const labels = [];
+    for (const layer of layers ?? []) {
+        const sourceLayer = layer['source-layer'];
+        if (!sourceLayer || !isLabelSourceLayer(sourceLayer))
+            continue;
+        if (layer.type === 'symbol') {
+            tap.push(layer.id);
+            labels.push(layer.id);
+        }
+        else if (layer.type === 'circle') {
+            tap.push(layer.id);
+        }
+    }
+    return { tap, labels };
+}
+const byUrl = new Map();
+/**
+ * The query layers of the style at `url`, fetched once per URL and shared. A
+ * style that cannot be read answers with none: presses then resolve to bare
+ * map, which is what they did before labels were tappable.
+ */
+export function queryLayersForUrl(url) {
+    let pending = byUrl.get(url);
+    if (!pending) {
+        pending = fetch(url)
+            .then((response) => (response.ok ? response.json() : null))
+            .then((style) => queryLayersOf(style?.layers))
+            .catch(() => {
+            byUrl.delete(url);
+            return NO_QUERY_LAYERS;
+        });
+        byUrl.set(url, pending);
+    }
+    return pending;
+}

package/dist/shared-exports.d.ts

@@ -0,0 +1,17 @@
+/** What both entries export beyond their platform's components. */
+export { useMap } from './mapRef';
+export { useUserLocation } from './useUserLocation';
+export type { LocationErrorReason, LocationPermissionStatus, UserLocationApi, UserLocationState, } from './useUserLocation';
+export { DefaultMapMarker } from './DefaultMapMarker';
+export { MAP_CREDIT_CLEARANCE, MAP_DATA_CREDITS } from './MapAttribution';
+export { MAP_BRAND_CLEARANCE, MAP_BRAND_HEIGHT, MAP_BRAND_WIDTH } from './MapBrand';
+export { CREDIT_GAP, creditRise } from './creditRise';
+export { sameLabelSet } from './labels';
+export { MapChromeLiftContext, useMapChromeLift } from './chromeLift';
+export type { MapChromeLift } from './chromeLift';
+export { MapCreditHeightContext, useMapCreditHeight } from './creditHeight';
+export { BrandedChromeProvider, useBrandedChrome } from './brand/BrandedChrome';
+export { GowayLogo, gowayLogoHeight } from './brand/GowayLogo';
+export type { GowayLogoProps, GowayLogoVariant } from './brand/GowayLogo';
+export { DEFAULT_MAP_STYLE } from './styleUrl';
+export type { GeoBoundingBox, GeoCoordinate, GeoJSONSourceProps, LayerProps, MapCameraChange, MapCameraOptions, MapCameraTarget, MapCreditDisclosure, MapCreditLink, MapError, MapErrorReason, MapFitOptions, MapFrame, MapInitialViewState, MapInteractionOptions, MapLabelFeature, MapLabelKind, MapLayerType, MapMarkerCluster, MapMarkerData, MapMarkerItem, MapMoveSource, MapPadding, MapPressEvent, MapViewport, MapViewProps, MapViewRef, MarkersProps, RasterDEMSourceProps, ResolvedMapViewport, UserLocationProps, } from './types';

package/dist/shared-exports.js

@@ -0,0 +1,13 @@
+/** What both entries export beyond their platform's components. */
+export { useMap } from './mapRef';
+export { useUserLocation } from './useUserLocation';
+export { DefaultMapMarker } from './DefaultMapMarker';
+export { MAP_CREDIT_CLEARANCE, MAP_DATA_CREDITS } from './MapAttribution';
+export { MAP_BRAND_CLEARANCE, MAP_BRAND_HEIGHT, MAP_BRAND_WIDTH } from './MapBrand';
+export { CREDIT_GAP, creditRise } from './creditRise';
+export { sameLabelSet } from './labels';
+export { MapChromeLiftContext, useMapChromeLift } from './chromeLift';
+export { MapCreditHeightContext, useMapCreditHeight } from './creditHeight';
+export { BrandedChromeProvider, useBrandedChrome } from './brand/BrandedChrome';
+export { GowayLogo, gowayLogoHeight } from './brand/GowayLogo';
+export { DEFAULT_MAP_STYLE } from './styleUrl';

package/dist/shared.d.ts

@@ -0,0 +1,170 @@
+import type { GeoBoundingBox, GeoCoordinate, MapInteractionOptions, MapMarkerData, MapPadding, MapViewport } from './types';
+/** MapLibre position order, on both engines. */
+export type LngLat = [longitude: number, latitude: number];
+/** MapLibre `[west, south, east, north]`, on both engines. */
+export type LngLatBoundsArray = [west: number, south: number, east: number, north: number];
+export declare function toLngLat(coordinate: GeoCoordinate): LngLat;
+export declare function fromLngLat(position: readonly [number, number]): GeoCoordinate;
+/**
+ * A box in engine order, its east edge carried past 180 when it crosses the
+ * antimeridian so both engines frame the strip it describes.
+ */
+export declare function toBoundsArray(bounds: GeoBoundingBox): LngLatBoundsArray;
+/** Every interaction is on unless a caller turns it off. */
+export declare function resolveInteraction(options?: MapInteractionOptions): Required<MapInteractionOptions>;
+/**
+ * Normalise a `moveTo` target: a bare coordinate leaves the camera's zoom alone.
+ *
+ * `Number.isFinite`, not `typeof === 'number'` — `typeof NaN` IS `'number'`, so
+ * the old test accepted `{ latitude, longitude, zoom: NaN }` as a viewport and
+ * passed that `NaN` on to the engine. See {@link asFinite} for what that costs.
+ * A viewport whose zoom is not a number is treated as the bare coordinate it
+ * usefully is.
+ */
+export declare function isViewport(target: GeoCoordinate | MapViewport): target is MapViewport;
+/**
+ * A camera scalar the engine can use, or `undefined`.
+ *
+ * Zoom, bearing, pitch, duration and maxZoom are the seam's unchecked numbers,
+ * and a `NaN` in any of them is not a bad frame — it is the SAME crash a bad
+ * coordinate is, one step later. `transform.setZoom(NaN)` survives MapLibre's
+ * own `clamp` (every comparison against `NaN` is false), so `_scale` and
+ * `worldSize` become `NaN`; the next unprojection — `map.getBounds()`, which
+ * this canvas calls on every `move` event, and which `jumpTo` fires
+ * SYNCHRONOUSLY — builds a `LngLat` out of two `NaN`s and throws
+ * `Invalid LngLat object: (NaN, NaN)` from inside the caller's own React
+ * handler. The camera simply not moving is the better failure.
+ */
+export declare function asFinite(value: number | null | undefined): number | undefined;
+/**
+ * A scalar an engine's options object may carry — or NOTHING AT ALL.
+ *
+ * ## The defect this exists to remove
+ *
+ * `{ maxZoom: undefined }` and `{}` look interchangeable in TypeScript, and to
+ * MapLibre GL JS they are opposites. `Map._cameraForBoxAndBearing` fills in its
+ * own defaults with
+ *
+ * ```
+ * options = extend({ padding, offset: [0, 0], maxZoom: this.transform.maxZoom }, options);
+ * ```
+ *
+ * and `extend` is `for (const k in src) dest[k] = src[k]` — an OWN key wins
+ * even when its value is `undefined`. So passing the key at all replaces the
+ * engine's maximum zoom with `undefined`, and the very next line is
+ *
+ * ```
+ * const zoom = Math.min(scaleZoom(tr.scale * Math.min(scaleX, scaleY)), options.maxZoom);
+ * ```
+ *
+ * `Math.min(anything, undefined)` is `NaN`. That `NaN` divides into
+ * `offsetAtFinalZoom`, reaches the centre `cameraForBoxAndBearing` unprojects,
+ * and `new LngLat(NaN, NaN)` THROWS — from inside the React effect that asked
+ * for the fit, which is the error boundary and the whole app. Omitting the key
+ * is the only way to mean "use yours".
+ *
+ * Every optional scalar this seam forwards therefore goes through here, so
+ * "the caller did not say" can never arrive as "the caller said nothing".
+ */
+export declare function optionalScalar<K extends string>(key: K, value: number | null | undefined): Partial<Record<K, number>>;
+/**
+ * Fit padding, expanded to the four-sided form both engines want — or `null`
+ * when it is not a number the engine can use.
+ *
+ * See {@link isDrawableCoordinate} for why a non-finite number is refused here
+ * rather than passed on: MapLibre's `cameraForBoxAndBearing` divides the free
+ * viewport by the padding, and `NaN` propagates all the way to the LngLat it
+ * constructs for the new centre, which throws. A NEGATIVE padding does not
+ * throw, but it is never what a caller meant (it frames content OUTSIDE the
+ * viewport), and a negative pair is one of the ways the free space lands on
+ * exactly zero, which does throw. So negatives clamp to zero and non-finite
+ * values refuse the fit outright.
+ */
+export declare function resolvePadding(padding: MapPadding | undefined, fallback: number): {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+} | null;
+/**
+ * Both MapLibre engines build a `LngLat` out of whatever they are handed, and
+ * `LngLat` THROWS on a non-number — `Invalid LngLat object: (NaN, NaN)`. Thrown
+ * from a React effect (setting a marker's position, framing a route) that
+ * reaches the nearest error boundary, so one bad pin takes the whole screen
+ * down and the user sees "Something went wrong" instead of a map.
+ *
+ * `@goway.to/maps` is the single seam every coordinate crosses on its way to
+ * an engine, so it is where that stops being possible. A marker whose
+ * coordinate is not drawable is DROPPED (a map missing one pin is a degraded
+ * map; a map that throws is no map) and a camera move whose target is not
+ * drawable is a no-op.
+ *
+ * ## Why this is not `isValidCoordinate`
+ *
+ * `@goway.to/sdk/geo`'s `isValidCoordinate` is the PRODUCT's rule — a real point
+ * on the earth, longitude within ±180. This is the ENGINE's rule, which is
+ * looser on longitude on purpose: MapLibre reports unwrapped longitudes across
+ * the antimeridian (a click at 181°E comes back as 181, not −179), and feeding
+ * one of those back in is legal and does the right thing. Rejecting it here
+ * would break panning past the date line in the name of safety. Latitude is
+ * bounded, because `LngLat` throws outside ±90 too.
+ */
+export declare function isDrawableCoordinate(value: unknown): value is GeoCoordinate;
+/** The same rule as {@link isDrawableCoordinate}, applied to a box's corners. */
+export declare function isDrawableBounds(bounds: GeoBoundingBox | null | undefined): bounds is GeoBoundingBox;
+/**
+ * The markers an engine may be given, with the undrawable ones removed.
+ *
+ * Returns the INPUT ARRAY when nothing is wrong, so the common path adds one
+ * pass and no allocation, and the forks' effect dependencies do not change
+ * identity every render.
+ */
+export declare function drawableMarkers(markers: readonly MapMarkerData[] | undefined): readonly MapMarkerData[];
+/**
+ * Every position in a GeoJSON document is a point the engine can project, and
+ * every geometry has enough of them to BE that geometry.
+ *
+ * The arity check is not pedantry about RFC 7946: a one-point `LineString` and
+ * an empty ring are exactly what a mis-sliced route produces, they draw
+ * nothing, and they are indistinguishable from "the route did not arrive"
+ * unless something says so.
+ *
+ * A composite geometry needs the same check one level up, for the same reason
+ * and one that is easier to miss: `[].every()` is `true`, so an empty
+ * `coordinates` array satisfies every per-part rule vacuously. An empty
+ * `Polygon` has no ring that can fail `ring()`, and a `MultiPolygon` of `[[]]`
+ * has no polygon that can. Both are what a slice that matched nothing
+ * produces, both reach the engine, and both draw exactly nothing — so every
+ * composite array is required to be non-empty BEFORE its parts are checked.
+ */
+export declare function isDrawableGeoJSON(data: GeoJSON.GeoJSON | null | undefined): boolean;
+export declare function reportMapDefect(key: string, message: string): void;
+/**
+ * Run one engine command, and let a throw cost the COMMAND rather than the app.
+ *
+ * This is the BACKSTOP, deliberately separate from the checks above. Those
+ * refuse the bad values we know about; this one is for the ones we do not. Every
+ * guard in this file was written after a crash, which is the evidence that the
+ * next non-finite number will arrive from somewhere nobody predicted — a
+ * renderer upgrade that starts rejecting an input it used to accept, a new
+ * option forwarded through an unexamined path, a device API that changes shape.
+ *
+ * What makes that catastrophic rather than cosmetic is WHERE these calls run:
+ * a camera move issued from a `useEffect` throws inside React's commit phase,
+ * so the nearest error boundary unmounts the tree and the user gets "Something
+ * went wrong" instead of a map. A camera that did not move is a map. That is
+ * the whole trade, and it is not close.
+ *
+ * It is not a licence to stop validating: a swallowed throw is a `console.warn`
+ * nobody reads, so anything we can name is still refused BEFORE it gets here,
+ * by a check that says which value was wrong and why.
+ *
+ * Answers whether the command ran: `false` is a dropped command, which a
+ * caller waiting on its outcome (a camera move's settle) must not wait for.
+ */
+export declare function runEngineCommand(command: string, run: () => void): boolean;
+/**
+ * `key NaN` — never `JSON.stringify`, which prints `NaN` and `Infinity` as
+ * `null` and so erases the one detail the reader needs.
+ */
+export declare function describeNumbers(value: unknown): string;