@goway.to/maps 0.0.0-stage → 0.1.0

package/dist/creditHeight.js

@@ -0,0 +1,12 @@
+/**
+ * Where the map's data credit publishes its measured height, so a screen's
+ * bottom-right chrome can stand above it however many lines it wraps to
+ * (`creditRise.ts`). A screen that floats chrome over the bottom-right
+ * provides a shared value; `MapAttribution` writes it, the chrome reads it on
+ * the UI thread. Absent, nothing is measured and nothing moves.
+ */
+import { createContext, useContext } from 'react';
+export const MapCreditHeightContext = createContext(null);
+export function useMapCreditHeight() {
+    return useContext(MapCreditHeightContext);
+}

package/dist/creditLabels.d.ts

@@ -0,0 +1,30 @@
+export declare const CREDIT_LABELS: {
+    readonly show: {
+        readonly en: "Show map credits";
+        readonly ar: "إظهار مصادر الخريطة";
+        readonly bn: "মানচিত্রের কৃতিত্ব দেখান";
+        readonly ca: "Mostra els crèdits del mapa";
+        readonly de: "Kartenquellen anzeigen";
+        readonly es: "Mostrar los créditos del mapa";
+        readonly fr: "Afficher les crédits de la carte";
+        readonly hi: "मानचित्र के श्रेय दिखाएँ";
+        readonly ja: "地図のクレジットを表示";
+        readonly 'pt-BR': "Mostrar os créditos do mapa";
+        readonly ru: "Показать источники карты";
+        readonly 'zh-Hans': "显示地图来源";
+    };
+    readonly hide: {
+        readonly en: "Hide map credits";
+        readonly ar: "إخفاء مصادر الخريطة";
+        readonly bn: "মানচিত্রের কৃতিত্ব লুকান";
+        readonly ca: "Amaga els crèdits del mapa";
+        readonly de: "Kartenquellen ausblenden";
+        readonly es: "Ocultar los créditos del mapa";
+        readonly fr: "Masquer les crédits de la carte";
+        readonly hi: "मानचित्र के श्रेय छिपाएँ";
+        readonly ja: "地図のクレジットを隠す";
+        readonly 'pt-BR': "Ocultar os créditos do mapa";
+        readonly ru: "Скрыть источники карты";
+        readonly 'zh-Hans': "隐藏地图来源";
+    };
+};

package/dist/creditLabels.js

@@ -0,0 +1,30 @@
+export const CREDIT_LABELS = {
+    show: {
+        en: 'Show map credits',
+        ar: 'إظهار مصادر الخريطة',
+        bn: 'মানচিত্রের কৃতিত্ব দেখান',
+        ca: 'Mostra els crèdits del mapa',
+        de: 'Kartenquellen anzeigen',
+        es: 'Mostrar los créditos del mapa',
+        fr: 'Afficher les crédits de la carte',
+        hi: 'मानचित्र के श्रेय दिखाएँ',
+        ja: '地図のクレジットを表示',
+        'pt-BR': 'Mostrar os créditos do mapa',
+        ru: 'Показать источники карты',
+        'zh-Hans': '显示地图来源',
+    },
+    hide: {
+        en: 'Hide map credits',
+        ar: 'إخفاء مصادر الخريطة',
+        bn: 'মানচিত্রের কৃতিত্ব লুকান',
+        ca: 'Amaga els crèdits del mapa',
+        de: 'Kartenquellen ausblenden',
+        es: 'Ocultar los créditos del mapa',
+        fr: 'Masquer les crédits de la carte',
+        hi: 'मानचित्र के श्रेय छिपाएँ',
+        ja: '地図のクレジットを隠す',
+        'pt-BR': 'Ocultar os créditos do mapa',
+        ru: 'Скрыть источники карты',
+        'zh-Hans': '隐藏地图来源',
+    },
+};

package/dist/creditRise.d.ts

@@ -0,0 +1,28 @@
+/**
+ * How much room the map's data credit takes at the bottom-right, and how far
+ * the chrome an app floats above it must rise when the credit is taller than
+ * one line.
+ *
+ * The chrome is laid out {@link MAP_CREDIT_CLEARANCE} above the bottom edge:
+ * room for the credit FOLDED, or spelled out on one line. Spelled out on a
+ * phone it wraps — the sources, the official building data while it is drawn,
+ * and any disclosure it carries — so the credit measures itself
+ * (`MapAttribution`, through `creditHeight.ts`) and the chrome rises by
+ * {@link creditRise} of that height: the two never overlap, whatever the
+ * credit says. Folded, the rise is zero and nothing moves.
+ *
+ * A worklet, so the UI thread runs exactly what `test/creditRise.test.ts`
+ * checks.
+ */
+/** Between the credit and the edge below it. */
+export declare const CREDIT_GAP = 4;
+/** Between the top of the credit and the chrome above it. */
+export declare const CREDIT_BREATHING = 8;
+/**
+ * How much of the bottom-right the credit occupies above the bottom edge: its
+ * gap, one caption line on its plate, and room to breathe. Bottom-right chrome
+ * a screen floats there starts above it, plus {@link creditRise}.
+ */
+export declare const MAP_CREDIT_CLEARANCE = 36;
+/** px the chrome above the credit rises for a credit plate this tall. */
+export declare function creditRise(plateHeight: number): number;

package/dist/creditRise.js

@@ -0,0 +1,33 @@
+/**
+ * How much room the map's data credit takes at the bottom-right, and how far
+ * the chrome an app floats above it must rise when the credit is taller than
+ * one line.
+ *
+ * The chrome is laid out {@link MAP_CREDIT_CLEARANCE} above the bottom edge:
+ * room for the credit FOLDED, or spelled out on one line. Spelled out on a
+ * phone it wraps — the sources, the official building data while it is drawn,
+ * and any disclosure it carries — so the credit measures itself
+ * (`MapAttribution`, through `creditHeight.ts`) and the chrome rises by
+ * {@link creditRise} of that height: the two never overlap, whatever the
+ * credit says. Folded, the rise is zero and nothing moves.
+ *
+ * A worklet, so the UI thread runs exactly what `test/creditRise.test.ts`
+ * checks.
+ */
+/** Between the credit and the edge below it. */
+export const CREDIT_GAP = 4;
+/** Between the top of the credit and the chrome above it. */
+export const CREDIT_BREATHING = 8;
+/**
+ * How much of the bottom-right the credit occupies above the bottom edge: its
+ * gap, one caption line on its plate, and room to breathe. Bottom-right chrome
+ * a screen floats there starts above it, plus {@link creditRise}.
+ */
+export const MAP_CREDIT_CLEARANCE = 36;
+/** px the chrome above the credit rises for a credit plate this tall. */
+export function creditRise(plateHeight) {
+    'worklet';
+    if (!(plateHeight > 0))
+        return 0;
+    return Math.max(0, CREDIT_GAP + plateHeight + CREDIT_BREATHING - MAP_CREDIT_CLEARANCE);
+}

package/dist/dragAxes.web.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Rotate and pitch as two independent gestures, on a renderer that ships them
+ * as one.
+ *
+ * ## The defect this exists to remove
+ *
+ * `MapInteractionOptions` has carried `rotate` and `pitch` as separate flags
+ * since the seam was written, and the native fork wires them to two separate
+ * props (`touchRotate`, `touchPitch`). MapLibre GL JS does not: on a desktop,
+ * bearing AND pitch both come out of ONE handler, `map.dragRotate` — Ctrl-drag
+ * or right-drag, horizontal for bearing, vertical for pitch. Toggling that
+ * handler on `rotate` alone therefore made `{ rotate: false, pitch: true }`
+ * mean "two-finger pitch on a touchscreen, and no way to tilt on a desktop",
+ * while the same options on native meant "pitch works". One options object,
+ * two behaviours, and nothing said so.
+ *
+ * That matters more than a rendering nicety because `MapInteractionOptions` is
+ * public in `@goway.to/maps`: an integrator reads the two flags,
+ * passes them, and gets a different map per platform.
+ *
+ * ## The contract
+ *
+ * **`rotate` and `pitch` are independent, on every platform.** Each names one
+ * camera axis the user may drive, and neither implies the other.
+ *
+ * ## How it is honoured here
+ *
+ * `DragRotateHandler` is a facade over two real handlers — `_mouseRotate` and
+ * `_mousePitch` (`src/ui/handler/shim/drag_rotate.ts`; its own `enable()` is
+ * `_mouseRotate.enable()` plus `_mousePitch.enable()` when `pitchWithRotate` is
+ * set, and `disable()` turns both off). Driving those two directly is the only
+ * way to get one axis without the other, because the public facade has no
+ * arity between "both" and "neither" and `pitchWithRotate` is a construction
+ * option that cannot be changed on a live map.
+ *
+ * They are underscore-prefixed, so this is a documented reach past the public
+ * API rather than an accident, and it degrades rather than throws if a future
+ * MapLibre stops splitting the two: the fallback enables the facade whenever
+ * EITHER axis is wanted, which keeps pitch reachable (the defect) at the cost
+ * of a bearing drag that `rotate: false` did not ask for. `setMaxPitch(0)`
+ * remains the backstop on the other side, so the fallback can never leak pitch
+ * into a map that asked for none.
+ */
+/** The two halves of MapLibre's desktop drag handler, as far as this file cares. */
+interface DragAxisHandler {
+    enable(): void;
+    disable(): void;
+}
+/** `map.dragRotate`: the facade, and the two handlers it is a facade over. */
+export interface DragRotateLike extends DragAxisHandler {
+    _mouseRotate?: DragAxisHandler;
+    _mousePitch?: DragAxisHandler;
+}
+/**
+ * Enable exactly the desktop drag axes asked for.
+ *
+ * @returns `true` when the two axes were set independently, `false` when the
+ *          facade fallback was used — exposed so a test can tell the two paths
+ *          apart, and so this file is honest about which one ran.
+ */
+export declare function applyDragAxes(dragRotate: DragRotateLike, axes: {
+    rotate: boolean;
+    pitch: boolean;
+}): boolean;
+export {};

package/dist/dragAxes.web.js

@@ -0,0 +1,70 @@
+/**
+ * Rotate and pitch as two independent gestures, on a renderer that ships them
+ * as one.
+ *
+ * ## The defect this exists to remove
+ *
+ * `MapInteractionOptions` has carried `rotate` and `pitch` as separate flags
+ * since the seam was written, and the native fork wires them to two separate
+ * props (`touchRotate`, `touchPitch`). MapLibre GL JS does not: on a desktop,
+ * bearing AND pitch both come out of ONE handler, `map.dragRotate` — Ctrl-drag
+ * or right-drag, horizontal for bearing, vertical for pitch. Toggling that
+ * handler on `rotate` alone therefore made `{ rotate: false, pitch: true }`
+ * mean "two-finger pitch on a touchscreen, and no way to tilt on a desktop",
+ * while the same options on native meant "pitch works". One options object,
+ * two behaviours, and nothing said so.
+ *
+ * That matters more than a rendering nicety because `MapInteractionOptions` is
+ * public in `@goway.to/maps`: an integrator reads the two flags,
+ * passes them, and gets a different map per platform.
+ *
+ * ## The contract
+ *
+ * **`rotate` and `pitch` are independent, on every platform.** Each names one
+ * camera axis the user may drive, and neither implies the other.
+ *
+ * ## How it is honoured here
+ *
+ * `DragRotateHandler` is a facade over two real handlers — `_mouseRotate` and
+ * `_mousePitch` (`src/ui/handler/shim/drag_rotate.ts`; its own `enable()` is
+ * `_mouseRotate.enable()` plus `_mousePitch.enable()` when `pitchWithRotate` is
+ * set, and `disable()` turns both off). Driving those two directly is the only
+ * way to get one axis without the other, because the public facade has no
+ * arity between "both" and "neither" and `pitchWithRotate` is a construction
+ * option that cannot be changed on a live map.
+ *
+ * They are underscore-prefixed, so this is a documented reach past the public
+ * API rather than an accident, and it degrades rather than throws if a future
+ * MapLibre stops splitting the two: the fallback enables the facade whenever
+ * EITHER axis is wanted, which keeps pitch reachable (the defect) at the cost
+ * of a bearing drag that `rotate: false` did not ask for. `setMaxPitch(0)`
+ * remains the backstop on the other side, so the fallback can never leak pitch
+ * into a map that asked for none.
+ */
+/**
+ * Enable exactly the desktop drag axes asked for.
+ *
+ * @returns `true` when the two axes were set independently, `false` when the
+ *          facade fallback was used — exposed so a test can tell the two paths
+ *          apart, and so this file is honest about which one ran.
+ */
+export function applyDragAxes(dragRotate, axes) {
+    const rotateHandler = dragRotate._mouseRotate;
+    const pitchHandler = dragRotate._mousePitch;
+    if (rotateHandler && pitchHandler) {
+        // `disable()` on the facade first: it is the only call that clears an axis
+        // the constructor enabled, and the two `enable()`s below then put back
+        // exactly what was asked for.
+        dragRotate.disable();
+        if (axes.rotate)
+            rotateHandler.enable();
+        if (axes.pitch)
+            pitchHandler.enable();
+        return true;
+    }
+    if (axes.rotate || axes.pitch)
+        dragRotate.enable();
+    else
+        dragRotate.disable();
+    return false;
+}

package/dist/engineContext.web.d.ts

@@ -0,0 +1,13 @@
+import type { Map as MapLibreMap } from 'maplibre-gl';
+import type { MapPluginHandle } from './plugin';
+export interface WebEngine {
+    map: MapLibreMap;
+    /** The DOM elements of the markers on this map: a click on one is not a click on the map. */
+    markerElements: Set<HTMLElement>;
+    /** The plugins attached to this map, consulted for presses, the cursor and errors. */
+    plugins: Set<MapPluginHandle<unknown>>;
+    /** The element the engine draws into. */
+    container: HTMLElement;
+}
+export declare const WebEngineContext: import("react").Context<WebEngine | null>;
+export declare function useWebEngine(): WebEngine;

package/dist/engineContext.web.js

@@ -0,0 +1,12 @@
+/**
+ * The web engine, published to a `MapView`'s children once its style has
+ * loaded. Only the web forks read it.
+ */
+import { createContext, useContext } from 'react';
+export const WebEngineContext = createContext(null);
+export function useWebEngine() {
+    const engine = useContext(WebEngineContext);
+    if (!engine)
+        throw new Error('A map component must be rendered inside a <MapView>.');
+    return engine;
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `@goway.to/maps` — GoWay's maps SDK for React Native (this entry) and the web
+ * (`index.web.ts`, chosen by the `browser` export condition). One API on both.
+ */
+export { MapView } from './MapView';
+export { Markers } from './Markers';
+export { GeoJSONSource } from './GeoJSONSource';
+export { RasterDEMSource } from './RasterDEMSource';
+export { Layer } from './Layer';
+export { UserLocation } from './UserLocation';
+export { MapPlugin } from './MapPlugin';
+export * from './shared-exports';

package/dist/index.js

@@ -0,0 +1,12 @@
+/**
+ * `@goway.to/maps` — GoWay's maps SDK for React Native (this entry) and the web
+ * (`index.web.ts`, chosen by the `browser` export condition). One API on both.
+ */
+export { MapView } from './MapView';
+export { Markers } from './Markers';
+export { GeoJSONSource } from './GeoJSONSource';
+export { RasterDEMSource } from './RasterDEMSource';
+export { Layer } from './Layer';
+export { UserLocation } from './UserLocation';
+export { MapPlugin } from './MapPlugin';
+export * from './shared-exports';

package/dist/index.web.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `@goway.to/maps` on the web — the same API as `index.ts`, built on
+ * `maplibre-gl`. Every web fork is named explicitly: an export condition does
+ * not apply to a relative import.
+ */
+export { MapView } from './MapView.web';
+export { Markers } from './Markers.web';
+export { GeoJSONSource } from './GeoJSONSource.web';
+export { RasterDEMSource } from './RasterDEMSource.web';
+export { Layer } from './Layer.web';
+export { UserLocation } from './UserLocation.web';
+export { MapPlugin } from './MapPlugin.web';
+export * from './shared-exports';

package/dist/index.web.js

@@ -0,0 +1,13 @@
+/**
+ * `@goway.to/maps` on the web — the same API as `index.ts`, built on
+ * `maplibre-gl`. Every web fork is named explicitly: an export condition does
+ * not apply to a relative import.
+ */
+export { MapView } from './MapView.web';
+export { Markers } from './Markers.web';
+export { GeoJSONSource } from './GeoJSONSource.web';
+export { RasterDEMSource } from './RasterDEMSource.web';
+export { Layer } from './Layer.web';
+export { UserLocation } from './UserLocation.web';
+export { MapPlugin } from './MapPlugin.web';
+export * from './shared-exports';

package/dist/labels.d.ts

@@ -0,0 +1,202 @@
+import type { GeoCoordinate, MapLabelFeature, MapLabelKind } from './types';
+/**
+ * How far around the tap the engine is asked to look, in px (web) / dp (native).
+ *
+ * The measurement above says 10 px is the minimum that reaches both a POI's dot
+ * and its label. 18 is that plus finger slop, and a generous pad costs nothing
+ * because {@link pickLabelFeature} resolves a crowded box by distance — the
+ * nearest label still wins, so widening the net changes what a sloppy tap hits
+ * and never what an accurate one hits.
+ *
+ * One number for mouse and touch on purpose. Sniffing the pointer type is
+ * unreliable (a browser-synthesised click from a touch is an ordinary
+ * `MouseEvent`), and a click 14 px from a label is a click that meant the
+ * label: a tap on genuinely empty ground was measured to return nothing at any
+ * pad, so the failure this could cause — "I clicked nothing and got something"
+ * — has nothing to be caused by.
+ */
+export declare const LABEL_HIT_PAD_PX = 18;
+/**
+ * Source-layers a tap may resolve against, in the OpenMapTiles v3 vocabulary.
+ *
+ * Read from GoWay's tile schema (`@goway.to/sdk`) rather than spelled here: a
+ * wrong source-layer name is the failure mode that logs nothing and throws
+ * nothing, and the schema is the one place those names are recorded.
+ *
+ * This is every layer GoWay's style puts a NAME on. `transportation` is absent
+ * although the style draws a symbol from it — that symbol is `road-oneway`, an
+ * arrow, and an arrow is not a label. `building` and `housenumber` are absent
+ * because a house number is an address fragment, not a thing with a name.
+ */
+export declare const LABEL_SOURCE_LAYERS: readonly string[];
+/**
+ * One hit, as a fork hands it over: the engine's feature with the engine
+ * removed.
+ *
+ * `properties` stays an opaque bag rather than a parsed shape because it is the
+ * TILES' vocabulary, not GoWay's — `class`, `subclass`, `rank` and the whole
+ * `name:*` family arrive exactly as OpenMapTiles wrote them, and
+ * {@link toLabelFeature} is the single place that decides which of them GoWay
+ * is willing to speak.
+ */
+export interface QueriedLabel {
+    /** The tiles' own feature id, where they carry one. */
+    featureId?: string | number | null;
+    /** OpenMapTiles source-layer (`poi`, `transportation_name`, …). */
+    sourceLayer: string;
+    /** The style layer that drew it. Diagnostics only. */
+    layerId?: string;
+    properties: Readonly<Record<string, unknown>>;
+    /** The feature's own point, for a Point geometry. */
+    coordinate?: GeoCoordinate | null;
+    /**
+     * The feature's vertices, for a line geometry — a street, a river.
+     *
+     * A street name has no point: it is drawn ALONG the way, and the way runs off
+     * both edges of the tile. So the anchor for a line is the nearest point on
+     * the line to the tap ({@link pickLabelFeature}), which is both a real place
+     * on the street and the closest thing there is to "where the user pointed".
+     */
+    path?: readonly GeoCoordinate[] | null;
+}
+/**
+ * The name the basemap is DRAWING, or `null`.
+ *
+ * Exactly `coalesce(name:latin, name)` — the `text-field` expression of
+ * GoWay's styles. Not `name_en`, not `name_int`: a label that says
+ * one thing on screen and another in the sheet is a worse bug than no sheet,
+ * and the user tapped what they could read.
+ */
+export declare function labelNameOf(properties: Readonly<Record<string, unknown>>): string | null;
+/**
+ * What kind of named thing this is, decided by SOURCE-LAYER rather than by
+ * guesswork over the name.
+ *
+ * Four kinds, because four is what the product acts on differently — see
+ * `MapLabelKind` in `types.ts` for what each one means and what a tap on it
+ * does.
+ */
+export declare function labelKindOf(sourceLayer: string): MapLabelKind | null;
+/** Whether a source-layer can answer a tap at all. */
+export declare function isLabelSourceLayer(sourceLayer: string): boolean;
+/**
+ * One queried hit as a GoWay label, or `null` when it is not one.
+ *
+ * `fallback` is where the user tapped. It is used when the feature has no
+ * anchor of its own — a label placed over a POLYGON, such as a park, whose name
+ * sits at the pole of inaccessibility that exists only inside MapLibre's
+ * placement and not in the tile. The tap is inside the polygon by construction,
+ * so it is a truthful point for that thing.
+ *
+ * Anything derived from a queried geometry goes through `isDrawableCoordinate`
+ * for the reason the whole seam exists — a `NaN` reaching MapLibre is a THROW
+ * out of the effect that positions things, not a misplaced pin (see
+ * `shared.ts`).
+ */
+export declare function toLabelFeature(candidate: QueriedLabel, fallback: GeoCoordinate, anchor?: GeoCoordinate | null): MapLabelFeature | null;
+/**
+ * Every hit in the box, as GoWay labels, each anchored where it really is.
+ *
+ * Split from the ranking below because the two halves need different things and
+ * one platform cannot do them together. Anchoring is PURE GEOMETRY — no
+ * projection — which is what lets the native fork do it synchronously for every
+ * candidate and then pay for exactly one projection each, instead of one bridge
+ * call per vertex of every street in the box.
+ */
+export declare function labelCandidatesOf(candidates: readonly QueriedLabel[], tapCoordinate: GeoCoordinate): MapLabelFeature[];
+/**
+ * The label a tap meant, out of everything inside the padded box.
+ *
+ * ## The rule, written down rather than left to the renderer's return order
+ *
+ * 1. **Nearest wins.** Distance in SCREEN PIXELS from the tap to the label's
+ *    own anchor — a point for a POI or a city, and for a street or a river the
+ *    nearest point on the line, which is a real place on that way rather than a
+ *    vertex that may be half a tile away. Pixels, not degrees: a degree is a
+ *    different distance at every latitude, and the user is pointing at pixels.
+ * 2. **A label with no anchor of its own is ranked as if it were at the edge of
+ *    the pad.** A park's name is placed by MapLibre at a pole of inaccessibility
+ *    that does not exist in the tile, so its only honest position is "somewhere
+ *    in this box". Scoring it at zero would make it beat everything; scoring it
+ *    at {@link LABEL_HIT_PAD_PX} makes it lose to anything genuinely nearer and
+ *    win over nothing.
+ * 3. **Then the kind**, most specific first: a POI you can walk into, then the
+ *    street it is on, then water, then the district or city containing all of
+ *    them. A city label spans the screen and is never what a tap meant while
+ *    something smaller is under the finger.
+ * 4. **Then the tiles' own `rank`**, OpenMapTiles' importance ordering.
+ * 5. **Then the id**, so the answer is deterministic rather than dependent on
+ *    the order a renderer happened to return its layers in.
+ */
+export declare function pickLabelFeature(labels: readonly MapLabelFeature[], point: {
+    x: number;
+    y: number;
+}, project: (coordinate: GeoCoordinate) => {
+    x: number;
+    y: number;
+} | null): MapLabelFeature | null;
+/**
+ * Where a line-drawn label should be considered to BE: the point on the way
+ * nearest the tap.
+ *
+ * Not the nearest VERTEX, which on a long straight avenue can be far from a tap
+ * that landed squarely on the street. The result is a real point on the way,
+ * which is what a pin should sit on and what "directions to this street" needs.
+ *
+ * ## Why this is flat geometry rather than a projection
+ *
+ * The search runs in a local planar frame — longitude scaled by `cos(latitude)`
+ * — instead of in screen pixels. Over one tile at label zooms the difference is
+ * immaterial, and it buys the thing that matters: no projection, so this is
+ * pure, testable, and cheap enough for the NATIVE fork, where every projection
+ * is a bridge call and projecting every vertex of every street in the box would
+ * not be affordable. Both forks therefore anchor identically.
+ *
+ * Returns `null` for anything that is not a usable line, so the caller falls
+ * back to the feature's own point and then to the tap.
+ */
+export declare function anchorFor(candidate: QueriedLabel, tap: GeoCoordinate): GeoCoordinate | null;
+/**
+ * The labels currently on screen, deduplicated and capped.
+ *
+ * Both forks report their viewport's labels so the overlay can avoid stacking
+ * its own text on top of one. Two things make
+ * that safe to do on every settled frame:
+ *
+ *  - **Dedup by id.** One POI is drawn by a dot layer and a label layer, and a
+ *    feature that straddles a tile boundary is returned once per tile.
+ *  - **A cap.** A wide, dense viewport is bounded by the collision system to
+ *    tens of labels in practice (44 over central Barcelona at z16, measured),
+ *    but "in practice" is not a bound, and this list crosses into React state.
+ */
+export declare function collectLabelFeatures(candidates: readonly QueriedLabel[], fallback: GeoCoordinate, limit?: number): readonly MapLabelFeature[];
+/**
+ * Whether two reported label sets are the same set.
+ *
+ * The canvas re-reports on every settled frame, and a fresh array of equal
+ * labels would rebuild every marker on the map for no reason. Ids only: a
+ * label's name and class come from the same tile feature, so an id that has
+ * not changed describes a label that has not changed.
+ */
+export declare function sameLabelSet(a: readonly MapLabelFeature[], b: readonly MapLabelFeature[]): boolean;
+/**
+ * A rendered feature as either engine hands it back. maplibre-gl puts
+ * `sourceLayer` and `layer` on the feature; MapLibre Native returns plain
+ * GeoJSON, where the source-layer arrives as a property — and the two platform
+ * SDKs do not agree on its key.
+ */
+export interface RenderedFeatureLike {
+    id?: string | number | null;
+    sourceLayer?: unknown;
+    layer?: {
+        id?: string;
+    } | null;
+    properties?: Readonly<Record<string, unknown>> | null;
+    geometry?: GeoJSON.Geometry | null;
+}
+/**
+ * The engine's features, with the engine removed. A feature this cannot
+ * classify is dropped rather than guessed at: the source-layer decides whether
+ * a hit is a POI or a district, and being wrong opens the wrong sheet.
+ */
+export declare function queriedLabelsOf(features: readonly RenderedFeatureLike[]): QueriedLabel[];