@mapmap/maps 0.10.1 → 0.11.1

package/README.md

@@ -458,13 +458,48 @@ const decision = await adr.check({ hazmat: true, tunnelCode: "C", tunnelCategory
 // { status: "allowed" | "blocked", reason?, raw }
 ```
 
+### `class Geocoder` - search and reverse lookup
+
+Typed access to the gateway's `GET /geocode` and `GET /geocode/reverse`
+endpoints - a search box or "what did the user tap" lookup needs no
+hand-rolled HTTP. Pass the map to reuse its `baseUrl`/`apiKey`, or
+`{ baseUrl, apiKey }` to use it without a map (no MapLibre dependency):
+
+```ts
+import { Geocoder } from "@mapmap/maps";
+
+const geocoder = new Geocoder(map); // or { baseUrl: "https://api.mapmap.ai", apiKey: "snk_…" }
+
+// Forward: free-text → hits, best first. Bias towards the map centre.
+const hits = await geocoder.geocode("tate modern", {
+  bias: map.map.getCenter(),
+  limit: 5,
+});
+// hits[0]: { lngLat: [lng, lat], name, kind, street, city, postcode,
+//            categories?, details?, id?, raw }
+
+// Reverse: point → nearest hits. kinds/categories/name are the
+// first-party filters ("nearest cafe", "nearest Lloyds bank").
+const places = await geocoder.reverse(evt.lngLat, { kinds: ["poi"] });
+```
+
+Errors surface the gateway's problem+json `title`/`detail`; a 501 is
+reported as "geocoding is not enabled on this deployment" (self-host
+without a geocoding backend), not as a bad request.
+
 ### Pure helpers (no browser required)
 
 Exported for server-side or test use - none of these touch MapLibre:
 
 - `buildStyle({ theme, territoryTilesUrl })` → a MapLibre `StyleSpecification`.
 - `buildRouteUrl(baseUrl, profile, points, truck?)` / `buildRouteQuery(truck?)`.
+  Note the API key is NOT embedded in the URL: fetch it yourself and add the
+  `Authorization: Bearer snk_…` header (`RouteLayer` does this internally).
 - `parseOsrmRoute(body)` → `ParsedRoute`.
+- `buildGeocodeUrl(baseUrl, query, opts?)` /
+  `buildReverseGeocodeUrl(baseUrl, point, opts?)` /
+  `parseGeocodeResponse(body)` → `GeocodeHit[]`. Same auth note as
+  `buildRouteUrl`.
 - `toLngLat` / `formatCoord` / `formatCoords` - coordinate normalisation.
 - `haversineDistanceM(a, b)` - straight-line distance in metres.
 - `placesFromGeoJSON(collection)` - GeoJSON Points → `Place[]`.
@@ -777,7 +812,12 @@ and `"N min"` labels, survives theme swaps, and resolves to the raw GeoJSON
 The map diagnoses the classic silent failures at construction and logs ONE
 actionable `console.error` per issue per page, each with a docs link:
 
-- `[container-zero-height]` - the 0px container (top blank-map cause)
+- `[container-zero-height]` - the 0px container (top blank-map cause).
+  Watch for CSS cascade layers here: Tailwind v4 utilities live in a
+  layer, unlayered maplibre-gl.css does not, so `absolute inset-0` on the
+  container silently loses to `.maplibregl-map { position: relative }`.
+  Use inline styles for the container's position/size, or import
+  maplibre-gl.css into a CSS layer.
 - `[container-detached]` - container not in the DOM
 - `[duplicate-maplibre]` - two maplibre-gl copies on one page
 - `[webgl-unavailable]` - no WebGL context available

package/dist/index.d.ts

@@ -2871,7 +2871,18 @@ declare class NavigationCamera {
     private lastRoute;
     private recentreTimer;
     private destroyed;
+    /** Whether the current free-mode gesture actually moved the map. */
+    private movedWhileFree;
     private readonly onInteraction;
+    /** A user-driven move between pointer-down and pointer-up: a real drag. */
+    private readonly onUserMove;
+    /**
+     * Pointer-up. Taking the camera on pointer-down is what lets a drag
+     * start at all, but it would also mean a plain tap — picking a place on
+     * the map, say — silently stopped the chase for the whole idle period.
+     * So a gesture that never actually moved the map hands it straight back.
+     */
+    private readonly onGestureEnd;
     /**
      * `false` when the map runs the globe (or vertical-perspective)
      * projection, whose camera geometry breaks the low-anchor offset maths
@@ -3207,6 +3218,122 @@ declare class AdrCheck {
     check(request: AdrCheckRequest): Promise<AdrCheckResult>;
 }
 
+/** The document kinds the reverse endpoint can filter by. */
+type GeocodeKind = "address" | "street" | "locality" | "poi" | "postcode";
+/** Options for forward geocoding (`GET /geocode`). */
+interface GeocodeOptions {
+    /** Maximum results, 1-10. */
+    limit?: number;
+    /** Result language, e.g. `"en"`, `"de"`, `"fr"`. */
+    lang?: string;
+    /**
+     * Location bias: reorders candidates towards this point, never excludes
+     * one. The map centre is the natural value for a search box.
+     */
+    bias?: LngLatLike;
+    /**
+     * Map zoom (0-20) controlling the bias strength: zoomed in favours
+     * nearby results, zoomed out favours prominence. Only meaningful with
+     * `bias`.
+     */
+    zoom?: number;
+    /**
+     * Hard bounding-box filter, `[minLon, minLat, maxLon, maxLat]` (WGS84).
+     * Unlike `bias` this excludes results outside the box outright.
+     */
+    bbox?: [number, number, number, number];
+}
+/** Options for reverse geocoding (`GET /geocode/reverse`). */
+interface ReverseGeocodeOptions {
+    /** Maximum results. */
+    limit?: number;
+    /**
+     * Restrict hits to these kinds. `["poi"]` is the "what place did the
+     * user tap" lookup. First-party backend only.
+     */
+    kinds?: GeocodeKind[];
+    /**
+     * Category browse: the nearest places of these categories, nearest
+     * first (`["cafe"]`, `["fuel", "charging_station"]`). Implies
+     * `kinds=poi`. First-party backend only.
+     */
+    categories?: string[];
+    /**
+     * Restrict hits to places of this name or brand, nearest first - the
+     * "nearest Lloyds bank" question. First-party backend only.
+     */
+    name?: string;
+}
+/** One geocode result, flattened from the wire FeatureCollection. */
+interface GeocodeHit {
+    /** `[lng, lat]` - GeoJSON order, ready for a MapLibre camera or marker. */
+    lngLat: [number, number];
+    /** Display name (`properties.name`), when the hit carries one. */
+    name?: string;
+    /** Stable id (`osm:…`), first-party backend only. */
+    id?: string;
+    /** Document kind: `poi`, `address`, `street`, `locality`, `postcode`, … */
+    kind?: string;
+    /** Address parts, present when known. */
+    housenumber?: string;
+    street?: string;
+    city?: string;
+    postcode?: string;
+    state?: string;
+    country?: string;
+    countrycode?: string;
+    /** POI categories, e.g. `["arts_centre"]`. */
+    categories?: string[];
+    /** Distance from the query point in metres - reverse hits only. */
+    distanceM?: number;
+    /**
+     * Curated OSM display attributes on first-party POI hits:
+     * `opening_hours`, `phone`, `website`, `brand`, `wheelchair`, EV
+     * `socket:*` connectors and friends. Keys absent in OSM are omitted.
+     */
+    details?: Record<string, unknown>;
+    /** The raw GeoJSON feature, for anything not modelled above. */
+    raw: Record<string, unknown>;
+}
+/**
+ * Build the full forward-geocode URL. `baseUrl` is the gateway origin
+ * (trailing slashes are trimmed). Note the API key is NOT embedded -
+ * fetches of this URL need the `Authorization: Bearer snk_…` header,
+ * exactly like {@link buildRouteUrl}.
+ */
+declare function buildGeocodeUrl(baseUrl: string, query: string, options?: GeocodeOptions): string;
+/** Build the full reverse-geocode URL. Same auth caveat as forward. */
+declare function buildReverseGeocodeUrl(baseUrl: string, point: LngLatLike, options?: ReverseGeocodeOptions): string;
+/**
+ * Parse a geocode response body (either endpoint) into {@link GeocodeHit}s.
+ * Throws when the body is not a FeatureCollection. Features without a
+ * Point geometry are skipped: the gateway only emits Points, so anything
+ * else is not a hit this parser can represent.
+ */
+declare function parseGeocodeResponse(body: unknown): GeocodeHit[];
+/**
+ * What the Geocoder needs. A `MapMapMap` satisfies this shape, so
+ * `new Geocoder(map)` reuses the map's gateway origin and key - the same
+ * convention as every other SDK class.
+ */
+interface GeocoderOptions {
+    /** Gateway base URL, e.g. `https://api.mapmap.ai`. */
+    baseUrl: string;
+    /** Gateway API key (`snk_…`). */
+    apiKey?: string | undefined;
+}
+/** Calls the gateway's geocoding endpoints and returns parsed hits. */
+declare class Geocoder {
+    private readonly baseUrl;
+    private readonly apiKey;
+    constructor(options: GeocoderOptions);
+    /** Forward geocode: free-text query → hits, best first. */
+    geocode(query: string, options?: GeocodeOptions): Promise<GeocodeHit[]>;
+    /** Reverse geocode: point → nearest hits, nearest first. */
+    reverse(point: LngLatLike, options?: ReverseGeocodeOptions): Promise<GeocodeHit[]>;
+    private request;
+}
+
 /** Guidance-related query options. */
 interface GuidanceQuery {
     voice?: boolean;
@@ -3754,4 +3881,4 @@ declare class VoiceGuidance {
     private playEarcon;
 }
 
-export { ALERT_CONTRAST_MIN, AdrCheck, type AdrCheckOptions, type AdrCheckRequest, type AdrCheckResult, type AdrDimensions, type AdrTunnelCategory, type AlertChipContent, type AlertContrastIssue, type AlertPresentation, type AttributionPosition, BAKED_MARKERS_GLYPH_ID, type BannerComponent, type BannerContent, type BannerInstruction, type BuildStyleOptions, type CameraAlert, CameraAlertChip, type CameraFix, DEFAULT_GLYPHS_URL, DEFAULT_TERRAIN_ATTRIBUTION, DEFAULT_TERRAIN_URL, DEFAULT_TERRITORY_TILES_URL, type DiagnosticIssue, EFFECTS_METADATA_KEY, type EndpointMarker, type EndpointsDesign, FLOW_DEFAULTS, FULL_ATTRIBUTION, FlowRouteEffectLayer, type FlythroughController, type FlythroughOptions, type FlythroughPose, GuidanceBanner, type GuidanceSeverity, type GuidanceSpokenPrompt, type IsochroneFeatureCollection, IsochroneLayer, type IsochroneLayerOptions, LOGO_SVG, type LaneIndication, type LayerOverride, type LngLatLike, LogoControl, type LogoOptions, type LogoPosition, MARKERS_ID, MARKER_DEFAULT_COLOUR, MARKER_GLYPH_IDS, MARKER_GLYPH_VIEWBOX, MARKER_LABEL_TEXT_SIZES, MARKER_PIN_BODY_PATH, MARKER_SIZES, MARKER_SIZES_PX, MAX_MARKER_ID_LENGTH, MAX_MARKER_IMAGE_BYTES, MAX_MARKER_ITEMS, MAX_MARKER_LABEL_LENGTH, MAX_MARKER_TEXT_LENGTH, MAX_PUCK_IMAGE_BYTES, type MapDiagnosticsInput, type MapDisplayMode, MapMapMap, type MapMapOptions, type MapMapTheme, type MarkerGlyphId, type MarkerItem, type MarkerSize, type MarkersBlock, MarkersLayer, type MarkersLayerIds, type MarkersLayerOptions, NAV_ALERT_AUDIO_MODES, NAV_ALERT_CHIP_POSITIONS, NAV_ALERT_ICON_SETS, NAV_ALERT_LEAD_DISTANCES, NAV_ALERT_LEAD_DISTANCE_M, NAV_ALERT_MODES, NAV_ALERT_SOUNDS, NAV_ALERT_SOUND_BASE_URL, NAV_ALERT_SOUND_FILES, NAV_CAMERA_DEFAULTS, NAV_CAMERA_KINDS, type NavAlertAudioMode, type NavAlertChipPosition, type NavAlertIconSet, type NavAlertKindDesign, type NavAlertLeadDistance, type NavAlertMode, type NavAlertSound, type NavAlertsDesign, type NavBannerDesign, type NavCameraDesign, type NavCameraKind, type NavDesign, type NavPuckDesign, type NavRouteDesign, NavigationCamera, type NavigationCameraMode, type NavigationCameraOptions, type NearestByDriveTimeOptions, OPENMAPTILES_ATTRIBUTION, OSM_ATTRIBUTION, PALETTE_SLOTS, POI_CATEGORY_COLORS, POI_CATEGORY_IDS, POI_CLASS_CATEGORIES, type ParsedRoute, type Place, type PlacePointFeature, type PlaceWithDistance, type PlaceWithDriveTime, type PlacesFeatureCollection, type PlacesIcon, type PlacesInput, type PlacesLabelOptions, PlacesLayer, type PlacesLayerIds, type PlacesLayerOptions, type PlacesSelectOptions, type PoiCategoryDesign, type PoiDesign, PositionPuck, type PositionPuckOptions, type ProbeUploadOutcome, RIBBON_FLOATS_PER_VERTEX, ROUTE_EFFECTS, type ReachabilityMode, type RenderMarkerImageOptions, type RenderedMarkerImage, type RibbonMesh, type RouteEffectLayer, type RouteEffectName, type RouteFlowOptions, type RouteGeometry, RouteLayer, type RouteLayerIds, type RouteLayerOptions, type RouteLineStyle, type RouteOptions, type RouteProfile, SIGNAL_BLUE, SOURCE_LAYERS, type SetRouteEffectOptions, type SeverityProsody, type ShowReachabilityOptions, type SpeakOptions, type StepGuidance, type SunTimes, type TerrainOptions, type Theme, type ThemeEffects, ThemeScheduler, type ThemeSchedulerOptions, type TruckParams, type UploadProbeOptions, VoiceGuidance, type VoiceGuidanceOptions, type VoiceGuidanceUpdate, type VoiceInstruction, alertChipContent, alertContrastIssues, alertIconSvg, alertIconUrl, alertPresentation, alertSoundUrl, alertSpeedReadoutColor, applyPoiDesign, applyTerrain, bannerLanes, bearingBetween, bindFlythroughToScroll, buildAdrCheckBody, buildProbeUrl, buildRouteQuery, buildRouteUrl, buildStyle, builtInPoiColor, cameraKindLabel, cameraKindsShownOnMap, cameraShownOnMap, cameraSpriteName, cameraSymbolLayer, contrastRatio, createMap, createRouteEffect, defaultNavAlertsDesign, defaultNavDesign, defaultPoiDesign, directionArrow, effectsFromStyleMetadata, extractGuidance, flythrough, flythroughPose, formatCoord, formatCoords, hasBakedMarkers, haversineDistanceM, isMarkerGlyphId, isNameTextField, laneArrowDirection, languageTextField, lngLatToMercator, markerGlyphPaths, markerImage, markerImageDataKey, markerImageKey, markerText, markerTextImageKey, markersFromTheme, markersFromThemeUrl, navAlertLeadDistanceM, navAlertSoundUrl, navCameraKind, navDesignFromTheme, navDesignFromThemeUrl, parseCssColour, parseHexColor, parseMarkers, parseNavAlertsDesign, parseNavDesign, parseOsrmRoute, parsePoiDesign, placesFromGeoJSON, poiDesignFromTheme, poiDesignFromThemeUrl, poiDesignIsDefault, poiTextColorExpression, prefersReducedMotion, registerPmtilesProtocol, relativeLuminance, removeTerrain, renderMarkerImage, resetDiagnostics, resolveTerrain, resolveTheme, runMapDiagnostics, setMapLanguage, severityProsody, shortestArcDeg, shortestArcDelta, speak, ssmlToText, sunTimes, tessellateRouteRibbon, toLngLat, toPmtilesUrl, truncateChars, uploadProbeBatch };
+export { ALERT_CONTRAST_MIN, AdrCheck, type AdrCheckOptions, type AdrCheckRequest, type AdrCheckResult, type AdrDimensions, type AdrTunnelCategory, type AlertChipContent, type AlertContrastIssue, type AlertPresentation, type AttributionPosition, BAKED_MARKERS_GLYPH_ID, type BannerComponent, type BannerContent, type BannerInstruction, type BuildStyleOptions, type CameraAlert, CameraAlertChip, type CameraFix, DEFAULT_GLYPHS_URL, DEFAULT_TERRAIN_ATTRIBUTION, DEFAULT_TERRAIN_URL, DEFAULT_TERRITORY_TILES_URL, type DiagnosticIssue, EFFECTS_METADATA_KEY, type EndpointMarker, type EndpointsDesign, FLOW_DEFAULTS, FULL_ATTRIBUTION, FlowRouteEffectLayer, type FlythroughController, type FlythroughOptions, type FlythroughPose, type GeocodeHit, type GeocodeKind, type GeocodeOptions, Geocoder, type GeocoderOptions, GuidanceBanner, type GuidanceSeverity, type GuidanceSpokenPrompt, type IsochroneFeatureCollection, IsochroneLayer, type IsochroneLayerOptions, LOGO_SVG, type LaneIndication, type LayerOverride, type LngLatLike, LogoControl, type LogoOptions, type LogoPosition, MARKERS_ID, MARKER_DEFAULT_COLOUR, MARKER_GLYPH_IDS, MARKER_GLYPH_VIEWBOX, MARKER_LABEL_TEXT_SIZES, MARKER_PIN_BODY_PATH, MARKER_SIZES, MARKER_SIZES_PX, MAX_MARKER_ID_LENGTH, MAX_MARKER_IMAGE_BYTES, MAX_MARKER_ITEMS, MAX_MARKER_LABEL_LENGTH, MAX_MARKER_TEXT_LENGTH, MAX_PUCK_IMAGE_BYTES, type MapDiagnosticsInput, type MapDisplayMode, MapMapMap, type MapMapOptions, type MapMapTheme, type MarkerGlyphId, type MarkerItem, type MarkerSize, type MarkersBlock, MarkersLayer, type MarkersLayerIds, type MarkersLayerOptions, NAV_ALERT_AUDIO_MODES, NAV_ALERT_CHIP_POSITIONS, NAV_ALERT_ICON_SETS, NAV_ALERT_LEAD_DISTANCES, NAV_ALERT_LEAD_DISTANCE_M, NAV_ALERT_MODES, NAV_ALERT_SOUNDS, NAV_ALERT_SOUND_BASE_URL, NAV_ALERT_SOUND_FILES, NAV_CAMERA_DEFAULTS, NAV_CAMERA_KINDS, type NavAlertAudioMode, type NavAlertChipPosition, type NavAlertIconSet, type NavAlertKindDesign, type NavAlertLeadDistance, type NavAlertMode, type NavAlertSound, type NavAlertsDesign, type NavBannerDesign, type NavCameraDesign, type NavCameraKind, type NavDesign, type NavPuckDesign, type NavRouteDesign, NavigationCamera, type NavigationCameraMode, type NavigationCameraOptions, type NearestByDriveTimeOptions, OPENMAPTILES_ATTRIBUTION, OSM_ATTRIBUTION, PALETTE_SLOTS, POI_CATEGORY_COLORS, POI_CATEGORY_IDS, POI_CLASS_CATEGORIES, type ParsedRoute, type Place, type PlacePointFeature, type PlaceWithDistance, type PlaceWithDriveTime, type PlacesFeatureCollection, type PlacesIcon, type PlacesInput, type PlacesLabelOptions, PlacesLayer, type PlacesLayerIds, type PlacesLayerOptions, type PlacesSelectOptions, type PoiCategoryDesign, type PoiDesign, PositionPuck, type PositionPuckOptions, type ProbeUploadOutcome, RIBBON_FLOATS_PER_VERTEX, ROUTE_EFFECTS, type ReachabilityMode, type RenderMarkerImageOptions, type RenderedMarkerImage, type ReverseGeocodeOptions, type RibbonMesh, type RouteEffectLayer, type RouteEffectName, type RouteFlowOptions, type RouteGeometry, RouteLayer, type RouteLayerIds, type RouteLayerOptions, type RouteLineStyle, type RouteOptions, type RouteProfile, SIGNAL_BLUE, SOURCE_LAYERS, type SetRouteEffectOptions, type SeverityProsody, type ShowReachabilityOptions, type SpeakOptions, type StepGuidance, type SunTimes, type TerrainOptions, type Theme, type ThemeEffects, ThemeScheduler, type ThemeSchedulerOptions, type TruckParams, type UploadProbeOptions, VoiceGuidance, type VoiceGuidanceOptions, type VoiceGuidanceUpdate, type VoiceInstruction, alertChipContent, alertContrastIssues, alertIconSvg, alertIconUrl, alertPresentation, alertSoundUrl, alertSpeedReadoutColor, applyPoiDesign, applyTerrain, bannerLanes, bearingBetween, bindFlythroughToScroll, buildAdrCheckBody, buildGeocodeUrl, buildProbeUrl, buildReverseGeocodeUrl, buildRouteQuery, buildRouteUrl, buildStyle, builtInPoiColor, cameraKindLabel, cameraKindsShownOnMap, cameraShownOnMap, cameraSpriteName, cameraSymbolLayer, contrastRatio, createMap, createRouteEffect, defaultNavAlertsDesign, defaultNavDesign, defaultPoiDesign, directionArrow, effectsFromStyleMetadata, extractGuidance, flythrough, flythroughPose, formatCoord, formatCoords, hasBakedMarkers, haversineDistanceM, isMarkerGlyphId, isNameTextField, laneArrowDirection, languageTextField, lngLatToMercator, markerGlyphPaths, markerImage, markerImageDataKey, markerImageKey, markerText, markerTextImageKey, markersFromTheme, markersFromThemeUrl, navAlertLeadDistanceM, navAlertSoundUrl, navCameraKind, navDesignFromTheme, navDesignFromThemeUrl, parseCssColour, parseGeocodeResponse, parseHexColor, parseMarkers, parseNavAlertsDesign, parseNavDesign, parseOsrmRoute, parsePoiDesign, placesFromGeoJSON, poiDesignFromTheme, poiDesignFromThemeUrl, poiDesignIsDefault, poiTextColorExpression, prefersReducedMotion, registerPmtilesProtocol, relativeLuminance, removeTerrain, renderMarkerImage, resetDiagnostics, resolveTerrain, resolveTheme, runMapDiagnostics, setMapLanguage, severityProsody, shortestArcDeg, shortestArcDelta, speak, ssmlToText, sunTimes, tessellateRouteRibbon, toLngLat, toPmtilesUrl, truncateChars, uploadProbeBatch };

package/dist/index.js

@@ -4,7 +4,7 @@ import maplibregl from 'maplibre-gl';
 import { Protocol } from 'pmtiles';
 
 // src/diagnostics.ts
-var DOCS = "https://mapmap.ai/docs";
+var DOCS = "https://mapmap.ai/docs/maps";
 var reported = /* @__PURE__ */ new Set();
 var MAPLIBRE_REGISTRY_KEY = /* @__PURE__ */ Symbol.for("mapmap.maplibre-instances");
 function resetDiagnostics() {
@@ -36,14 +36,14 @@ function checkContainer(container) {
   if (!element.isConnected) {
     report(
       "container-detached",
-      `the map container element is not attached to the DOM, so nothing can render. Append it to the document before constructing the map. ${DOCS}#container`
+      `the map container element is not attached to the DOM, so nothing can render. Append it to the document before constructing the map. ${DOCS}#container-not-in-the-dom`
     );
     return;
   }
   if (element.clientHeight === 0) {
     report(
       "container-zero-height",
-      `the map container's height is 0px, so MapLibre is rendering into an invisible canvas (no error, no map). Give it a real height, e.g. #map { height: 100vh; }. If the height arrives later (CSS load, layout), you can ignore this. ${DOCS}#container-height`
+      `the map container's height is 0px, so MapLibre is rendering into an invisible canvas (no error, no map). Give it a real height, e.g. #map { height: 100vh; }. Sizing the container with CSS-layer framework utilities (e.g. Tailwind v4 \`absolute inset-0\`) does not work: maplibre-gl.css is unlayered, so its \`.maplibregl-map { position: relative }\` beats any layered utility and collapses the container - use inline styles for the container's position/size, or import maplibre-gl.css into a CSS layer. If the height arrives later (CSS load, layout), you can ignore this. ${DOCS}#zero-height-container`
     );
   }
 }
@@ -60,7 +60,7 @@ function checkDuplicateMaplibre(maplibre) {
   if (registry.size > 1) {
     report(
       "duplicate-maplibre",
-      `two different maplibre-gl instances are loaded on this page (duplicate dependency, a CDN <script> next to the bundled copy, or micro-frontends). Maps, styles and the pmtiles protocol registration will not be shared between them. De-duplicate so the app owns a single maplibre-gl - it is a peerDependency of @mapmap/maps for exactly this reason. ${DOCS}#duplicate-maplibre`
+      `two different maplibre-gl instances are loaded on this page (duplicate dependency, a CDN <script> next to the bundled copy, or micro-frontends). Maps, styles and the pmtiles protocol registration will not be shared between them. De-duplicate so the app owns a single maplibre-gl - it is a peerDependency of @mapmap/maps for exactly this reason. ${DOCS}#two-maplibre-gl-copies`
     );
   }
 }
@@ -72,7 +72,7 @@ function checkWebgl() {
     if (!gl) {
       report(
         "webgl-unavailable",
-        `this browser/environment reports no WebGL support, so the map cannot render. Common causes: headless browsers without --use-gl, blocked GPU/hardware acceleration, remote desktops. ${DOCS}#webgl`
+        `this browser/environment reports no WebGL support, so the map cannot render. Common causes: headless browsers without --use-gl, blocked GPU/hardware acceleration, remote desktops. ${DOCS}#webgl-unavailable`
       );
     }
   } catch {
@@ -89,7 +89,7 @@ function watchForAuthFailures(map, apiKey) {
       if (basemapMissing) {
         report(
           "basemap-not-found",
-          `the basemap tiles returned HTTP 404, so the map renders blank. The territory tiles URL points at a file that does not exist. Check \`territoryTilesUrl\` (or your custom \`style\`) - the default MapMap tiles are served at the CDN root (e.g. https://tiles.mapmap.ai/planet.pmtiles), not under a /territories/ prefix. ${DOCS}#tiles`
+          `the basemap tiles returned HTTP 404, so the map renders blank. The territory tiles URL points at a file that does not exist. Check \`territoryTilesUrl\` (or your custom \`style\`) - the default MapMap tiles are served at the CDN root (e.g. https://tiles.mapmap.ai/planet.pmtiles), not under a /territories/ prefix. ${DOCS}#basemap-tiles-404`
         );
         return;
       }
@@ -97,7 +97,7 @@ function watchForAuthFailures(map, apiKey) {
       if (!unauthorised) return;
       report(
         "invalid-api-key",
-        apiKey ? `the gateway rejected your API key (HTTP 401). Check the \`apiKey\` for typos or revocation - keys look like "snk_\u2026". ${DOCS}#authentication` : `a request was rejected with HTTP 401 and no \`apiKey\` was configured. Pass one to the map (\`new MapMapMap({ apiKey: "snk_\u2026" })\`) - issue a free key with POST https://api.mapmap.ai/v1/keys. ${DOCS}#authentication`
+        apiKey ? `the gateway rejected your API key (HTTP 401). Check the \`apiKey\` for typos or revocation - keys look like "snk_\u2026". ${DOCS}#401-unauthorised` : `a request was rejected with HTTP 401 and no \`apiKey\` was configured. Pass one to the map (\`new MapMapMap({ apiKey: "snk_\u2026" })\`) - issue a free key with POST https://api.mapmap.ai/v1/keys. ${DOCS}#401-unauthorised`
       );
     });
   } catch {
@@ -4708,7 +4708,11 @@ function firstRow(value) {
 }
 
 // src/camera.ts
+var GESTURE_END_EVENTS = ["mouseup", "touchend", "touchcancel"];
 var INTERACTION_EVENTS = [
+  "mousedown",
+  "touchstart",
+  "wheel",
   "dragstart",
   "rotatestart",
   "pitchstart",
@@ -4727,13 +4731,33 @@ var NavigationCamera = class {
   constructor(map, options = {}) {
     this.currentMode = "follow";
     this.destroyed = false;
+    /** Whether the current free-mode gesture actually moved the map. */
+    this.movedWhileFree = false;
     // Bound once so `off` in destroy() removes exactly what `on` added.
     this.onInteraction = (ev) => {
       if (!ev?.originalEvent || this.destroyed) return;
+      this.movedWhileFree = false;
       this.currentMode = "free";
       this.m.stop();
       this.scheduleRecentre();
     };
+    /** A user-driven move between pointer-down and pointer-up: a real drag. */
+    this.onUserMove = (ev) => {
+      if (!ev?.originalEvent || this.destroyed) return;
+      this.movedWhileFree = true;
+    };
+    /**
+     * Pointer-up. Taking the camera on pointer-down is what lets a drag
+     * start at all, but it would also mean a plain tap — picking a place on
+     * the map, say — silently stopped the chase for the whole idle period.
+     * So a gesture that never actually moved the map hands it straight back.
+     */
+    this.onGestureEnd = () => {
+      if (this.destroyed || this.currentMode !== "free") return;
+      if (this.movedWhileFree) return;
+      this.clearRecentreTimer();
+      this.resume();
+    };
     this.m = map instanceof MapMapMap ? map.map : map;
     const design = map instanceof MapMapMap ? map.navDesign?.camera : void 0;
     this.pitch = clamp(options.pitch ?? design?.pitch ?? DEFAULT_PITCH, 0, 85);
@@ -4748,6 +4772,10 @@ var NavigationCamera = class {
     for (const event of INTERACTION_EVENTS) {
       this.m.on(event, this.onInteraction);
     }
+    for (const event of GESTURE_END_EVENTS) {
+      this.m.on(event, this.onGestureEnd);
+    }
+    this.m.on("move", this.onUserMove);
   }
   /**
    * `false` when the map runs the globe (or vertical-perspective)
@@ -4826,6 +4854,10 @@ var NavigationCamera = class {
     for (const event of INTERACTION_EVENTS) {
       this.m.off(event, this.onInteraction);
     }
+    for (const event of GESTURE_END_EVENTS) {
+      this.m.off(event, this.onGestureEnd);
+    }
+    this.m.off("move", this.onUserMove);
   }
   easeToFix(fix, courseDeg, duration) {
     this.m.easeTo({
@@ -5344,6 +5376,110 @@ var AdrCheck = class {
   }
 };
 
+// src/geocode.ts
+function lonLatParam(point) {
+  const [lng, lat] = toLngLat(point);
+  return `${lng},${lat}`;
+}
+function buildGeocodeUrl(baseUrl, query, options = {}) {
+  const params = new URLSearchParams({ q: query });
+  if (options.limit != null) params.set("limit", String(options.limit));
+  if (options.lang != null) params.set("lang", options.lang);
+  if (options.bias != null) params.set("bias", lonLatParam(options.bias));
+  if (options.zoom != null) params.set("zoom", String(options.zoom));
+  if (options.bbox != null) params.set("bbox", options.bbox.join(","));
+  return `${baseUrl.replace(/\/+$/, "")}/geocode?${params.toString()}`;
+}
+function buildReverseGeocodeUrl(baseUrl, point, options = {}) {
+  const [lng, lat] = toLngLat(point);
+  const params = new URLSearchParams({ lon: String(lng), lat: String(lat) });
+  if (options.limit != null) params.set("limit", String(options.limit));
+  if (options.kinds?.length) params.set("kinds", options.kinds.join(","));
+  if (options.categories?.length) {
+    params.set("categories", options.categories.join(","));
+  }
+  if (options.name != null) params.set("name", options.name);
+  return `${baseUrl.replace(/\/+$/, "")}/geocode/reverse?${params.toString()}`;
+}
+function parseGeocodeResponse(body) {
+  if (typeof body !== "object" || body === null || body["type"] !== "FeatureCollection" || !Array.isArray(body["features"])) {
+    throw new Error("geocode response was not a GeoJSON FeatureCollection");
+  }
+  const features = body.features;
+  const hits = [];
+  for (const feature of features) {
+    if (typeof feature !== "object" || feature === null) continue;
+    const f = feature;
+    const geometry = f["geometry"];
+    const coords = geometry?.["coordinates"];
+    if (geometry?.["type"] !== "Point" || !Array.isArray(coords) || typeof coords[0] !== "number" || typeof coords[1] !== "number") {
+      continue;
+    }
+    const props = f["properties"] ?? {};
+    const str2 = (key) => typeof props[key] === "string" ? props[key] : void 0;
+    const hit = { lngLat: [coords[0], coords[1]], raw: f };
+    const name = str2("name");
+    if (name !== void 0) hit.name = name;
+    const id = str2("id");
+    if (id !== void 0) hit.id = id;
+    const kind = str2("type");
+    if (kind !== void 0) hit.kind = kind;
+    for (const key of [
+      "housenumber",
+      "street",
+      "city",
+      "postcode",
+      "state",
+      "country",
+      "countrycode"
+    ]) {
+      const value = str2(key);
+      if (value !== void 0) hit[key] = value;
+    }
+    if (Array.isArray(props["categories"])) {
+      hit.categories = props["categories"].filter(
+        (c) => typeof c === "string"
+      );
+    }
+    if (typeof props["distance_m"] === "number") {
+      hit.distanceM = props["distance_m"];
+    }
+    if (typeof props["details"] === "object" && props["details"] !== null) {
+      hit.details = props["details"];
+    }
+    hits.push(hit);
+  }
+  return hits;
+}
+var Geocoder = class {
+  constructor(options) {
+    this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+    this.apiKey = options.apiKey;
+  }
+  /** Forward geocode: free-text query → hits, best first. */
+  geocode(query, options = {}) {
+    return this.request(buildGeocodeUrl(this.baseUrl, query, options));
+  }
+  /** Reverse geocode: point → nearest hits, nearest first. */
+  reverse(point, options = {}) {
+    return this.request(buildReverseGeocodeUrl(this.baseUrl, point, options));
+  }
+  async request(url) {
+    const headers = { Accept: "application/json" };
+    if (this.apiKey) headers["Authorization"] = `Bearer ${this.apiKey}`;
+    const response = await fetch(url, { headers });
+    const body = await response.json().catch(() => null);
+    if (!response.ok) {
+      const problem = typeof body === "object" && body !== null ? body : void 0;
+      const context = [problem?.["title"], problem?.["detail"]].filter((v) => typeof v === "string" && v.length > 0).join(" - ");
+      throw new Error(
+        response.status === 501 ? `geocoding is not enabled on this deployment (HTTP 501)${context ? ` (${context})` : ""}` : `geocoding failed: HTTP ${response.status}${context ? ` (${context})` : ""}`
+      );
+    }
+    return parseGeocodeResponse(body);
+  }
+};
+
 // src/guidance.ts
 var CSS_COLOUR = /^(?:rgba?|hsla?|hwb|lab|lch|oklab|oklch|color|color-mix|var)\((?:[\w\s.,%/#-]|\([\w\s.,%/#-]*\))*\)$/i;
 function safeColour(value, fallback) {
@@ -5857,6 +5993,6 @@ function clampVolume(volume) {
   return Math.min(1, Math.max(0, volume));
 }
 
-export { ALERT_CONTRAST_MIN, AdrCheck, BAKED_MARKERS_GLYPH_ID, CameraAlertChip, DEFAULT_GLYPHS_URL, DEFAULT_TERRAIN_ATTRIBUTION, DEFAULT_TERRAIN_URL, DEFAULT_TERRITORY_TILES_URL, EFFECTS_METADATA_KEY, FLOW_DEFAULTS, FULL_ATTRIBUTION, FlowRouteEffectLayer, GuidanceBanner, IsochroneLayer, LOGO_SVG, LogoControl, MARKERS_ID, MARKER_DEFAULT_COLOUR, MARKER_GLYPH_IDS, MARKER_GLYPH_VIEWBOX, MARKER_LABEL_TEXT_SIZES, MARKER_PIN_BODY_PATH, MARKER_SIZES, MARKER_SIZES_PX, MAX_MARKER_ID_LENGTH, MAX_MARKER_IMAGE_BYTES, MAX_MARKER_ITEMS, MAX_MARKER_LABEL_LENGTH, MAX_MARKER_TEXT_LENGTH, MAX_PUCK_IMAGE_BYTES, MapMapMap, MarkersLayer, NAV_ALERT_AUDIO_MODES, NAV_ALERT_CHIP_POSITIONS, NAV_ALERT_ICON_SETS, NAV_ALERT_LEAD_DISTANCES, NAV_ALERT_LEAD_DISTANCE_M, NAV_ALERT_MODES, NAV_ALERT_SOUNDS, NAV_ALERT_SOUND_BASE_URL, NAV_ALERT_SOUND_FILES, NAV_CAMERA_DEFAULTS, NAV_CAMERA_KINDS, NavigationCamera, OPENMAPTILES_ATTRIBUTION, OSM_ATTRIBUTION, PALETTE_SLOTS, POI_CATEGORY_COLORS, POI_CATEGORY_IDS, POI_CLASS_CATEGORIES, PlacesLayer, PositionPuck, RIBBON_FLOATS_PER_VERTEX, ROUTE_EFFECTS, RouteLayer, SIGNAL_BLUE, SOURCE_LAYERS, ThemeScheduler, VoiceGuidance, alertChipContent, alertContrastIssues, alertIconSvg, alertIconUrl, alertPresentation, alertSoundUrl, alertSpeedReadoutColor, applyPoiDesign, applyTerrain, bannerLanes, bearingBetween, bindFlythroughToScroll, buildAdrCheckBody, buildProbeUrl, buildRouteQuery, buildRouteUrl, buildStyle, builtInPoiColor, cameraKindLabel, cameraKindsShownOnMap, cameraShownOnMap, cameraSpriteName, cameraSymbolLayer, contrastRatio, createMap, createRouteEffect, defaultNavAlertsDesign, defaultNavDesign, defaultPoiDesign, directionArrow, effectsFromStyleMetadata, extractGuidance, flythrough, flythroughPose, formatCoord, formatCoords, hasBakedMarkers, haversineDistanceM, isMarkerGlyphId, isNameTextField, laneArrowDirection, languageTextField, lngLatToMercator, markerGlyphPaths, markerImage, markerImageDataKey, markerImageKey, markerText, markerTextImageKey, markersFromTheme, markersFromThemeUrl, navAlertLeadDistanceM, navAlertSoundUrl, navCameraKind, navDesignFromTheme, navDesignFromThemeUrl, parseCssColour, parseHexColor, parseMarkers, parseNavAlertsDesign, parseNavDesign, parseOsrmRoute, parsePoiDesign, placesFromGeoJSON, poiDesignFromTheme, poiDesignFromThemeUrl, poiDesignIsDefault, poiTextColorExpression, prefersReducedMotion, registerPmtilesProtocol, relativeLuminance, removeTerrain, renderMarkerImage, resetDiagnostics, resolveTerrain, resolveTheme, runMapDiagnostics, setMapLanguage, severityProsody, shortestArcDeg, shortestArcDelta, speak, ssmlToText, sunTimes, tessellateRouteRibbon, toLngLat, toPmtilesUrl, truncateChars, uploadProbeBatch };
+export { ALERT_CONTRAST_MIN, AdrCheck, BAKED_MARKERS_GLYPH_ID, CameraAlertChip, DEFAULT_GLYPHS_URL, DEFAULT_TERRAIN_ATTRIBUTION, DEFAULT_TERRAIN_URL, DEFAULT_TERRITORY_TILES_URL, EFFECTS_METADATA_KEY, FLOW_DEFAULTS, FULL_ATTRIBUTION, FlowRouteEffectLayer, Geocoder, GuidanceBanner, IsochroneLayer, LOGO_SVG, LogoControl, MARKERS_ID, MARKER_DEFAULT_COLOUR, MARKER_GLYPH_IDS, MARKER_GLYPH_VIEWBOX, MARKER_LABEL_TEXT_SIZES, MARKER_PIN_BODY_PATH, MARKER_SIZES, MARKER_SIZES_PX, MAX_MARKER_ID_LENGTH, MAX_MARKER_IMAGE_BYTES, MAX_MARKER_ITEMS, MAX_MARKER_LABEL_LENGTH, MAX_MARKER_TEXT_LENGTH, MAX_PUCK_IMAGE_BYTES, MapMapMap, MarkersLayer, NAV_ALERT_AUDIO_MODES, NAV_ALERT_CHIP_POSITIONS, NAV_ALERT_ICON_SETS, NAV_ALERT_LEAD_DISTANCES, NAV_ALERT_LEAD_DISTANCE_M, NAV_ALERT_MODES, NAV_ALERT_SOUNDS, NAV_ALERT_SOUND_BASE_URL, NAV_ALERT_SOUND_FILES, NAV_CAMERA_DEFAULTS, NAV_CAMERA_KINDS, NavigationCamera, OPENMAPTILES_ATTRIBUTION, OSM_ATTRIBUTION, PALETTE_SLOTS, POI_CATEGORY_COLORS, POI_CATEGORY_IDS, POI_CLASS_CATEGORIES, PlacesLayer, PositionPuck, RIBBON_FLOATS_PER_VERTEX, ROUTE_EFFECTS, RouteLayer, SIGNAL_BLUE, SOURCE_LAYERS, ThemeScheduler, VoiceGuidance, alertChipContent, alertContrastIssues, alertIconSvg, alertIconUrl, alertPresentation, alertSoundUrl, alertSpeedReadoutColor, applyPoiDesign, applyTerrain, bannerLanes, bearingBetween, bindFlythroughToScroll, buildAdrCheckBody, buildGeocodeUrl, buildProbeUrl, buildReverseGeocodeUrl, buildRouteQuery, buildRouteUrl, buildStyle, builtInPoiColor, cameraKindLabel, cameraKindsShownOnMap, cameraShownOnMap, cameraSpriteName, cameraSymbolLayer, contrastRatio, createMap, createRouteEffect, defaultNavAlertsDesign, defaultNavDesign, defaultPoiDesign, directionArrow, effectsFromStyleMetadata, extractGuidance, flythrough, flythroughPose, formatCoord, formatCoords, hasBakedMarkers, haversineDistanceM, isMarkerGlyphId, isNameTextField, laneArrowDirection, languageTextField, lngLatToMercator, markerGlyphPaths, markerImage, markerImageDataKey, markerImageKey, markerText, markerTextImageKey, markersFromTheme, markersFromThemeUrl, navAlertLeadDistanceM, navAlertSoundUrl, navCameraKind, navDesignFromTheme, navDesignFromThemeUrl, parseCssColour, parseGeocodeResponse, parseHexColor, parseMarkers, parseNavAlertsDesign, parseNavDesign, parseOsrmRoute, parsePoiDesign, placesFromGeoJSON, poiDesignFromTheme, poiDesignFromThemeUrl, poiDesignIsDefault, poiTextColorExpression, prefersReducedMotion, registerPmtilesProtocol, relativeLuminance, removeTerrain, renderMarkerImage, resetDiagnostics, resolveTerrain, resolveTheme, runMapDiagnostics, setMapLanguage, severityProsody, shortestArcDeg, shortestArcDelta, speak, ssmlToText, sunTimes, tessellateRouteRibbon, toLngLat, toPmtilesUrl, truncateChars, uploadProbeBatch };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map