@mapmap/maps 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1180 @@
+import maplibregl, { StyleSpecification, Map, MapOptions } from 'maplibre-gl';
+
+/**
+ * The MapMap logo control: a small wordmark on the map, the same
+ * convention as Google Maps' and Mapbox's marks. On by default in
+ * {@link MapMapMap}; positionable, and removable with `logo: false`
+ * (attribution itself is separate and never removable).
+ *
+ * The mark is an inline SVG (no network fetch, works offline and under
+ * strict CSPs): the MapMap brand lockup — the three-colour route mark
+ * plus the lowercase wordmark. Height stays at 20px so existing layouts
+ * hold.
+ */
+/** Corner positions accepted by the logo control. */
+type LogoPosition = "bottom-right" | "bottom-left" | "top-right" | "top-left";
+/** Options for {@link LogoControl}. */
+interface LogoOptions {
+    /** Corner to render in. Default `bottom-right`, above the attribution. */
+    position?: LogoPosition;
+    /** Link target when clicked. Default the MapMap site. */
+    href?: string;
+}
+/**
+ * The inline wordmark (height 20px): the outline-light lockup — the
+ * line-art route mark plus the dark wordmark — over a white halo stroke
+ * so it stays legible on any base map.
+ */
+declare const LOGO_SVG: string;
+/**
+ * A MapLibre `IControl` rendering the MapMap wordmark. Typed structurally
+ * (`onAdd`/`onRemove`) so it needs no maplibre-gl import and works with
+ * any instance the host app bundles.
+ */
+declare class LogoControl {
+    private container;
+    private readonly href;
+    constructor(options?: LogoOptions);
+    onAdd(): HTMLElement;
+    onRemove(): void;
+}
+
+/**
+ * MapMap style assembly - pure, browser-free port of the `sn-style` crate.
+ *
+ * This module mirrors `crates/sn-style` (theme.rs + compile.rs), the
+ * canonical MapMap Studio theme engine, so client-side and build-side
+ * styles compile identically. A {@link Theme} is a small, agent-friendly
+ * JSON document (named palette slots + per-layer overrides) that
+ * {@link buildStyle} turns into a full MapLibre style-spec v8 style over
+ * the MapMap territory tiles (OpenMapTiles schema, as emitted by
+ * `sn-factory`'s Planetiler stage and served as PMTiles).
+ *
+ * The `pmtiles://` URL prefix is resolved by the pmtiles protocol handler
+ * that {@link registerPmtilesProtocol} installs on the MapLibre instance.
+ *
+ * Attribution: "© OpenStreetMap contributors" (ODbL) and "© OpenMapTiles"
+ * (CC-BY 4.0 schema) are legally required and stamped on every compiled
+ * style's tile source. There is no theme field that can remove them.
+ */
+
+/** A loose JSON object - skeleton layers are assembled as plain JSON. */
+type JsonObject = Record<string, unknown>;
+/** Which built-in palette a theme starts from. */
+type MapMapTheme = "light" | "dark";
+/** The OSM attribution string. Legally required (ODbL) - never removed. */
+declare const OSM_ATTRIBUTION = "\u00A9 OpenStreetMap contributors";
+/** The OpenMapTiles schema attribution (CC-BY 4.0). */
+declare const OPENMAPTILES_ATTRIBUTION = "\u00A9 OpenMapTiles";
+/**
+ * Combined attribution stamped on every compiled style's tile source.
+ * Legally required (ODbL + CC-BY) - enforced, not themable: no theme
+ * field can remove it.
+ */
+declare const FULL_ATTRIBUTION = "\u00A9 OpenStreetMap contributors \u00A9 OpenMapTiles";
+/** Default glyph endpoint (PBF fontstacks), mirroring `sn_style::DEFAULT_GLYPHS_URL`. */
+declare const DEFAULT_GLYPHS_URL = "https://fonts.mapmap.ai/{fontstack}/{range}.pbf";
+/** A sensible default territory tiles URL (overridable per map). */
+declare const DEFAULT_TERRITORY_TILES_URL = "pmtiles://https://tiles.mapmap.ai/territories/planet.pmtiles";
+/**
+ * Every source-layer the Planetiler (OpenMapTiles-schema) tiles emit.
+ * The style skeleton covers all of them; extra layers referencing anything
+ * else are rejected. Mirrors `sn_style::SOURCE_LAYERS`.
+ */
+declare const SOURCE_LAYERS: readonly string[];
+/**
+ * The named palette slots as `[slot, lightDefault, darkDefault]`, mirroring
+ * `sn_style::palette_slots()`. Order is stable and documentation-worthy: it
+ * is the order a Studio UI should present them in.
+ */
+declare const PALETTE_SLOTS: readonly (readonly [string, string, string])[];
+/**
+ * Per-layer override: merged onto the skeleton layer with the same id.
+ * Mirrors `sn_style::LayerOverride`.
+ */
+interface LayerOverride {
+    /** Hide the layer entirely (`layout.visibility = "none"`). */
+    visible?: boolean;
+    /** Paint properties merged over the skeleton's (per-key, override wins). */
+    paint?: Record<string, unknown>;
+    /** Layout properties merged over the skeleton's. */
+    layout?: Record<string, unknown>;
+    /** Replace the skeleton's filter (per-attribute styling hook). */
+    filter?: unknown;
+    minzoom?: number;
+    maxzoom?: number;
+}
+/**
+ * A MapMap Studio theme: the unit users and agents edit, store and publish.
+ * Mirrors `sn_style::Theme` (all fields carry serde defaults, so everything
+ * is optional here).
+ */
+interface Theme {
+    /** Human-readable theme name, e.g. `"midnight-fleet"`. */
+    name?: string;
+    /** Built-in palette to start from. Defaults to `"light"`. */
+    base?: MapMapTheme;
+    /** Palette overrides by slot name (see {@link PALETTE_SLOTS}). */
+    palette?: Record<string, string>;
+    /** Per-layer overrides by skeleton layer id. */
+    layers?: Record<string, LayerOverride>;
+    /**
+     * Render buildings as 3D extrusions. Adds a `building-3d` fill-extrusion
+     * layer (zoom 15+) driven by the tiles' `render_height` /
+     * `render_min_height` attributes, and caps the flat `building` footprint
+     * layer at that zoom so the two hand off cleanly (the extrusion rises
+     * from flat as you zoom in). Web-safe; native navigation SDKs should
+     * leave this off by default until MapLibre Native's fill-extrusion
+     * memory use at street zooms is fixed (maplibre-native#4107). Mirrors
+     * `Theme::buildings_3d`.
+     */
+    buildings_3d?: boolean;
+    /**
+     * Label fonts. Every fontstack must exist on the glyph server; until that
+     * ships (P2), leave this at its default (`"Noto Sans Regular"`).
+     */
+    fonts?: {
+        regular?: string;
+    };
+    /** Override the glyph endpoint (defaults to {@link DEFAULT_GLYPHS_URL}). */
+    glyphs?: string;
+    /** Optional sprite URL (icons/shields - P2, no default sprite exists). */
+    sprite?: string;
+    /**
+     * Extra fully-formed MapLibre layers appended above the skeleton (below
+     * labels). Each must reference the `territory` source and a known
+     * source-layer.
+     */
+    extra_layers?: JsonObject[];
+    /**
+     * Non-style extras carried by the THEME DOCUMENT, not the compiled
+     * style. Studio stores its navigation design block here (`extra.nav`;
+     * see `nav-design.ts`). {@link buildStyle} ignores it entirely - the
+     * compiled `style.json` is byte-identical with or without it. Mirrors
+     * `Theme::extra` in the canonical Rust crate: the hosted styles API
+     * stores the block verbatim (bounded at 256 KB serialised) and serves it
+     * back from `GET /styles/{id}/theme`, so a Studio design survives
+     * publishing - consume it via `createMap` with a theme document or
+     * `navDesignFromThemeUrl` with the hosted theme URL.
+     */
+    extra?: {
+        nav?: unknown;
+    };
+}
+interface BuildStyleOptions {
+    /**
+     * Theme to build: a built-in name (`"light"` / `"dark"`) or a full
+     * {@link Theme} document. Defaults to `"light"`.
+     */
+    theme?: MapMapTheme | Theme;
+    /**
+     * PMTiles URL for the territory tiles. Accepts either a `pmtiles://…` URL
+     * or a plain `https://…` URL (the `pmtiles://` prefix is added for you).
+     */
+    territoryTilesUrl?: string;
+}
+/** Ensure a tiles URL carries the `pmtiles://` protocol prefix. */
+declare function toPmtilesUrl(url: string): string;
+declare function buildStyle(options?: BuildStyleOptions): StyleSpecification;
+
+/**
+ * Studio navigation-design block (`extra.nav`) - types, defaults and parser.
+ *
+ * MapMap Studio's Navigation panel designs the turn-by-turn look - route
+ * line, current-position puck and banner instruction - and stores the result
+ * as a small design-token block under `extra.nav` in the theme JSON it
+ * downloads/copies. This module reads that block so the same theme file
+ * styles real navigation UI: `RouteLayer`, `PositionPuck` and
+ * `GuidanceBanner` all accept a design from it.
+ *
+ * LOCKSTEP: this file mirrors `website/lib/studio-nav.ts` (the Studio
+ * reference parser) - identical interfaces, defaults, clamps and URL rules.
+ * Keep the two in sync so a theme previews in Studio exactly as the SDK
+ * renders it. Not imported from the website because the packages do not
+ * depend on each other.
+ *
+ * PUBLISH NOTE: the block travels with the THEME DOCUMENT, never with the
+ * compiled `style.json`. That includes hosted publishing: the canonical
+ * `sn_style` crate stores `extra` verbatim (bounded at 256 KB serialised)
+ * and the gateway serves it back from `GET /styles/{id}/theme`, so a design
+ * survives Studio's publish flow too. Read it from a theme file you pass to
+ * `createMap` / `buildStyle`, or fetch it from a hosted style with
+ * {@link navDesignFromThemeUrl} — a compiled style URL alone never carries
+ * it.
+ */
+
+/** Route-line tokens (defaults match {@link RouteLayer}'s built-in look). */
+interface NavRouteDesign {
+    /** Line colour. Default is MapMap signal blue (`SIGNAL_BLUE`). */
+    color: string;
+    /** Line width in px at mid zoom. */
+    width: number;
+    /** Line opacity, 0-1. */
+    opacity: number;
+    /** Casing (outline) colour drawn under the line. */
+    casingColor: string;
+}
+/** Current-position puck tokens. */
+interface NavPuckDesign {
+    /** Puck fill colour. */
+    color: string;
+    /** Puck diameter in px. */
+    size: number;
+    /** Whether the heading arrow is drawn on the puck. */
+    headingArrow: boolean;
+    /**
+     * Optional custom puck image (`https:` or `data:` URI, PNG/SVG). When set
+     * it replaces the built-in dot + arrow; `size` still scales it. Optional
+     * since v1 - themes saved without it load unchanged.
+     */
+    imageUrl?: string;
+}
+/** Banner-instruction tokens (defaults match {@link GuidanceBanner}). */
+interface NavBannerDesign {
+    /** Banner background colour. */
+    background: string;
+    /** Banner text (and arrow) colour. */
+    textColor: string;
+    /** Primary text size in px. */
+    fontSize: number;
+    /** Whether the lane diagram row is shown when lanes are present. */
+    showLanes: boolean;
+    /** Inner padding in px, 6-24. Optional since v1; default 10. */
+    padding?: number;
+    /** Corner radius in px, 0-24. Optional since v1; default 10. */
+    cornerRadius?: number;
+    /** Maximum banner width in px, 200-520. Optional since v1; default 340. */
+    maxWidth?: number;
+    /**
+     * Banner height in px, 40-120. Optional since v1; unset means auto -
+     * the banner takes its natural content height (old themes keep theirs).
+     */
+    height?: number;
+}
+/**
+ * Drive-camera tokens: how the chase cam frames a turn-by-turn drive.
+ * The whole block is optional since v1 - themes saved without it load
+ * unchanged and the SDK keeps its built-in framing. Every field is itself
+ * optional (absent = the documented default). `NavigationCamera` reads
+ * `pitch`/`zoom` as its option defaults; `speedMps` drives Studio's demo
+ * drive (and any route simulator) - a camera following real GPS fixes
+ * ignores it.
+ */
+interface NavCameraDesign {
+    /** Chase-cam tilt in degrees, 0-85. Default 60. */
+    pitch?: number;
+    /** Chase-cam zoom, 14-20. Default 17.5. */
+    zoom?: number;
+    /** Drive speed in metres per second, 2-40. Default 12 (~43 km/h). */
+    speedMps?: number;
+}
+/**
+ * Defaults for the optional `camera` block. LOCKSTEP: mirrors
+ * `NAV_CAMERA_DEFAULTS` in `website/lib/studio-nav.ts`.
+ */
+declare const NAV_CAMERA_DEFAULTS: {
+    readonly pitch: 60;
+    readonly zoom: 17.5;
+    readonly speedMps: 12;
+};
+/** The `extra.nav` block: navigation design tokens for the SDKs. */
+interface NavDesign {
+    /** Block schema version; currently always 1. */
+    version: 1;
+    route: NavRouteDesign;
+    puck: NavPuckDesign;
+    banner: NavBannerDesign;
+    /**
+     * Optional since v1: drive-camera framing (pitch/zoom) and speed. Absent
+     * means "SDK built-ins" - the block stays `version: 1` either way.
+     */
+    camera?: NavCameraDesign;
+}
+/**
+ * Defaults mirror what the SDK draws today with no design: `RouteLayer`'s
+ * signal-blue line over a dark casing, and `GuidanceBanner`'s dark pill.
+ */
+declare function defaultNavDesign(): NavDesign;
+/**
+ * Lenient parse of an `extra.nav` value: unknown or malformed fields fall
+ * back to the defaults, so an imported theme never fails on its nav block.
+ * LOCKSTEP: identical semantics to `parseNavDesign` in
+ * `website/lib/studio-nav.ts` (same clamps, same fallbacks).
+ */
+declare function parseNavDesign(value: unknown): NavDesign;
+/**
+ * Reads and parses the `extra.nav` block from a Studio theme document.
+ * Returns `undefined` when the theme carries no nav block at all (so
+ * callers can tell "no design" apart from "default design"); a present but
+ * malformed block parses leniently to the defaults.
+ */
+declare function navDesignFromTheme(theme: Theme | undefined | null): NavDesign | undefined;
+/**
+ * Fetches a hosted theme document and reads its `extra.nav` block.
+ *
+ * Point it at the gateway's theme endpoint - the design a Studio publish
+ * stores alongside the compiled style:
+ *
+ * ```ts
+ * const design = await navDesignFromThemeUrl(
+ *   "https://api.mapmap.ai/styles/midnight-fleet-a1b2c3/theme",
+ * );
+ * ```
+ *
+ * The endpoint is public (no API key) and never cached, so this always
+ * reflects the latest published version. Returns `undefined` when the
+ * theme carries no nav block (same contract as {@link navDesignFromTheme});
+ * throws on network failure, a non-2xx response or a non-JSON body.
+ *
+ * @param fetchImpl Optional `fetch` replacement (tests, Node polyfills).
+ *   Defaults to the global `fetch`.
+ */
+declare function navDesignFromThemeUrl(url: string, fetchImpl?: typeof fetch): Promise<NavDesign | undefined>;
+
+/**
+ * MapMapMap - the branded MapLibre GL map.
+ *
+ * A thin wrapper over `maplibregl.Map`. MapLibre does all the rendering; this
+ * class only wires in the MapMap default style, registers the pmtiles
+ * protocol, and keeps the gateway `apiKey`/`baseUrl` handy so routing and ADR
+ * helpers can reuse them.
+ */
+
+/**
+ * Register the `pmtiles://` protocol on a MapLibre instance. Idempotent per
+ * maplibre-gl instance, and safe to call before constructing any map.
+ * Exposed for apps that build their own `maplibregl.Map` (possibly from
+ * their own bundled maplibre-gl copy) but still want to read MapMap PMTiles.
+ */
+declare function registerPmtilesProtocol(gl?: typeof maplibregl): void;
+interface MapMapOptions {
+    /**
+     * The MapMap wordmark on the map (like the Google Maps / Mapbox marks).
+     * Default on at bottom-right, above the attribution; `false` removes
+     * it, or pass `{ position, href }` to customise.
+     */
+    logo?: boolean | LogoOptions;
+    /** The container element or its id. */
+    container: string | HTMLElement;
+    /** Gateway API key (`snk_…`), used by routing and ADR helpers. */
+    apiKey?: string;
+    /** Gateway base URL for routing/ADR. Defaults to `https://api.mapmap.ai`. */
+    baseUrl?: string;
+    /**
+     * Style to load. A theme name (`"light"` / `"dark"`), a MapMap Studio
+     * `Theme` document, a full MapLibre `StyleSpecification`, or a style URL.
+     * Defaults to `"light"`.
+     */
+    style?: MapMapTheme | Theme | StyleSpecification | string;
+    /** Override the territory PMTiles URL used by the default styles. */
+    territoryTilesUrl?: string;
+    /** Initial centre as `[lng, lat]`. Defaults to the UK. */
+    center?: [number, number];
+    /** Initial zoom. Defaults to `5`. */
+    zoom?: number;
+    /**
+     * Extra MapLibre `MapOptions` merged last (escape hatch for hash, bearing,
+     * maxBounds, etc.). `container` and `style` here are ignored.
+     */
+    mapOptions?: Partial<Omit<MapOptions, "container" | "style">>;
+}
+/** The MapMap map: a branded, tiles-and-routing-ready MapLibre map. */
+declare class MapMapMap {
+    /** The underlying MapLibre map. Use it for any native MapLibre call. */
+    readonly map: Map;
+    /** Gateway API key, if provided. */
+    readonly apiKey: string | undefined;
+    /** Gateway base URL (no trailing slash). */
+    readonly baseUrl: string;
+    /**
+     * The Studio navigation design (`extra.nav`) parsed from the theme passed
+     * as `style`, when it carried one. `RouteLayer`, `PositionPuck` and
+     * `GuidanceBanner` pick this up as their default look; `undefined` means
+     * the theme had no nav block (or `style` was not a theme document).
+     */
+    readonly navDesign: NavDesign | undefined;
+    constructor(options: MapMapOptions);
+    /**
+     * Toggle 3D building extrusions at runtime — the live equivalent of
+     * compiling the style with `buildings_3d: true` (see `Theme`): adds or
+     * removes the `building-3d` fill-extrusion layer and hands the flat
+     * `building` footprint layer off at zoom 15. The extrusion takes its
+     * colour from the current `building` fill, so it follows the theme.
+     * Idempotent; safe to call before the style has loaded (it applies on
+     * load). Requires the MapMap skeleton's `building` layer — on a custom
+     * style without one this throws rather than guessing.
+     *
+     * Mobile note: leave 3D off in native navigation views for now
+     * (maplibre-native#4107 — fill-extrusion memory at street zooms).
+     */
+    setBuildings3d(enabled: boolean): void;
+    /** Resolves once the style and first tiles are loaded. */
+    whenReady(): Promise<void>;
+    /** Remove the map and release its WebGL context. */
+    destroy(): void;
+}
+/** Functional alias for {@link MapMapMap}, mirroring the Mapbox `new Map` feel. */
+declare function createMap(options: MapMapOptions): MapMapMap;
+
+/**
+ * Shared public types for @mapmap/maps.
+ *
+ * These are runtime-free (type-only) so the pure logic modules that import
+ * them stay loadable in Node without a browser or maplibre-gl.
+ */
+/** A longitude/latitude pair, accepted in the three common shapes. */
+type LngLatLike = [number, number] | {
+    lng: number;
+    lat: number;
+} | {
+    lon: number;
+    lat: number;
+};
+/** OSRM routing profile. MapMap ships `driving`, `walking` and `truck`. */
+type RouteProfile = "driving" | "walking" | "truck" | (string & {});
+/**
+ * Truck / ADR vehicle parameters forwarded to the gateway's OSRM truck
+ * vendor extensions. All optional; only `truck`-profile requests honour them.
+ */
+interface TruckParams {
+    /** Vehicle height, metres. */
+    heightM?: number;
+    /** Vehicle width, metres. */
+    widthM?: number;
+    /** Vehicle length, metres. */
+    lengthM?: number;
+    /** Gross weight, tonnes. */
+    weightT?: number;
+    /** Carrying dangerous goods (ADR). */
+    hazmat?: boolean;
+    /**
+     * ADR 8.6.4 tunnel restriction code, e.g. `"C"` or `"B/D"`. The slash is
+     * URL-encoded automatically.
+     */
+    tunnelCode?: string;
+}
+/** Options for a single route request. */
+interface RouteOptions {
+    /** Routing profile. Defaults to `"driving"`. */
+    profile?: RouteProfile;
+    /** Truck / ADR parameters (only meaningful with `profile: "truck"`). */
+    truck?: TruckParams;
+    /** Request spoken `voiceInstructions` on each step (see `guidance.ts`). */
+    voice?: boolean;
+    /** Request visual `bannerInstructions` (and lane data) on each step. */
+    banner?: boolean;
+    /** BCP 47 narration language, e.g. `"en-GB"`. */
+    language?: string;
+}
+/** A parsed GeoJSON LineString geometry (`[lng, lat]` positions). */
+interface RouteGeometry {
+    type: "LineString";
+    coordinates: [number, number][];
+}
+/** A parsed OSRM route, normalised to the fields callers actually use. */
+interface ParsedRoute {
+    /** Total distance, metres. */
+    distanceM: number;
+    /** Total duration, seconds. */
+    durationS: number;
+    /** Route line as GeoJSON, ready to hand to a MapLibre source. */
+    geometry: RouteGeometry;
+    /** The raw OSRM `routes[0]` object, for callers that need leg/step detail. */
+    raw: Record<string, unknown>;
+}
+/** The ADR category of a tunnel, `"A"` (least restrictive) … `"E"`. */
+type AdrTunnelCategory = "A" | "B" | "C" | "D" | "E";
+/**
+ * Physical truck dimensions for the ADR vehicle profile (mirrors
+ * `sn_adr::TruckDimensions`). All optional; unset fields default to the EU
+ * 96/53/EC maximum-authorised articulated vehicle (4.0 m high, 2.55 m wide,
+ * 16.5 m long, 40 t gross), matching the Rust `Default`.
+ */
+interface AdrDimensions {
+    /** Vehicle height, metres. Defaults to `4.0`. */
+    heightM?: number;
+    /** Vehicle width, metres. Defaults to `2.55`. */
+    widthM?: number;
+    /** Vehicle length, metres. Defaults to `16.5`. */
+    lengthM?: number;
+    /** Gross combination weight, tonnes. Defaults to `40`. */
+    grossWeightT?: number;
+    /** Heaviest single-axle load, tonnes, if known. */
+    axleLoadT?: number;
+    /** Number of axles, if known. */
+    axleCount?: number;
+}
+/**
+ * Input for the gateway's `POST /adr/check` compliance endpoint: the
+ * vehicle's ADR profile plus the category of the tunnel to check. Serialised
+ * on the wire as `{"adr": <AdrVehicleProfile>, "tunnel_category": "A".."E"}`
+ * (see `sn-gateway` `routes/adr.rs`).
+ */
+interface AdrCheckRequest {
+    /** Carrying dangerous goods. */
+    hazmat: boolean;
+    /**
+     * The *vehicle load's* ADR 8.6.4 tunnel restriction code, e.g. `"C"` or
+     * `"C/E"`. Omit when carrying dangerous goods of unknown code (the
+     * gateway then conservatively treats the load as code `B`). This is not
+     * the tunnel's category — that goes in {@link tunnelCategory}.
+     */
+    tunnelCode?: string;
+    /** Vehicle dimensions. Defaults to the EU standard artic maximums. */
+    dimensions?: AdrDimensions;
+    /** The ADR category of the *tunnel* to check, `"A"` … `"E"`. */
+    tunnelCategory: AdrTunnelCategory;
+}
+/** Parsed response from `POST /adr/check`. */
+interface AdrCheckResult {
+    /** `"allowed"` or `"blocked"`. */
+    status: string;
+    /** Human-readable justification citing ADR 8.6.4 where blocked. */
+    reason?: string;
+    /** The raw response body. */
+    raw: Record<string, unknown>;
+}
+
+/**
+ * RouteLayer - fetch an OSRM route from the MapMap gateway and draw it.
+ *
+ * The route request/parse logic lives in the pure `osrm` module; this class
+ * owns the network call and the MapLibre source/layers (a signal-blue line
+ * with a darker casing, matching the brand).
+ */
+
+/** MapMap brand signal blue (see website `--signal`). */
+declare const SIGNAL_BLUE = "#3a86ff";
+interface RouteLayerOptions {
+    /** Gateway base URL. Defaults to the map's `baseUrl` when given a map. */
+    baseUrl?: string;
+    /** Gateway API key. Defaults to the map's `apiKey` when given a map. */
+    apiKey?: string;
+    /** Unique id prefix for the source/layers. Defaults to `"mapmap-route"`. */
+    id?: string;
+    /**
+     * Studio route design (`extra.nav` `route` block). Defaults to the map's
+     * `navDesign.route` when given a `MapMapMap` whose theme carried one;
+     * without a design the layer keeps its built-in signal-blue look.
+     */
+    design?: NavRouteDesign;
+}
+/** Draws MapMap routes on a MapLibre map. */
+declare class RouteLayer {
+    private readonly map;
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly sourceId;
+    private readonly casingLayerId;
+    private readonly lineLayerId;
+    private readonly design;
+    private lastRoute;
+    constructor(map: MapMapMap | Map, options?: RouteLayerOptions);
+    private readonly handleStyleLoad;
+    /**
+     * Route from `from` to `to` (with optional intermediate `via` points passed
+     * through `options` is not supported here - pass a coordinate list to
+     * {@link routePath} for that), draw the line, and return the parsed route.
+     */
+    route(from: LngLatLike, to: LngLatLike, options?: RouteOptions): Promise<ParsedRoute>;
+    /** Route through an ordered list of coordinates and draw the result. */
+    routePath(points: LngLatLike[], options?: RouteOptions): Promise<ParsedRoute>;
+    /** The most recently drawn route, if any. */
+    get current(): ParsedRoute | undefined;
+    /**
+     * Draw (or update) a parsed route's line on the map. Safe to call before
+     * the style has loaded: the route is stored and installed on the next
+     * `style.load` instead of throwing MapLibre's "Style is not done loading".
+     */
+    draw(route: ParsedRoute): void;
+    /** Add-or-update the source and layers for a route on the current style. */
+    private install;
+    /** Remove the route's layers and source from the map. */
+    clear(): void;
+    /**
+     * Remove the route and detach the layer's `style.load` listener. Call
+     * when disposing of the layer (the map itself is left untouched).
+     */
+    destroy(): void;
+}
+
+/** Maximum accepted `data:` puck-image payload (matches Studio's upload cap). */
+declare const MAX_PUCK_IMAGE_BYTES: number;
+/** A current-position puck marker for MapMap maps. */
+declare class PositionPuck {
+    /** The puck's root DOM element (the Marker element). */
+    readonly element: HTMLElement;
+    private readonly map;
+    private readonly marker;
+    private readonly design;
+    private added;
+    /**
+     * Creates the puck (not yet on the map - it appears on the first
+     * {@link setLocation}). The design defaults to the map's
+     * `navDesign.puck` when given a `MapMapMap` whose theme carried an
+     * `extra.nav` block, then to the built-in blue puck.
+     */
+    constructor(map: MapMapMap | Map, design?: NavPuckDesign);
+    /**
+     * Moves the puck (adding it to the map on the first call). `headingDeg`
+     * rotates the whole element - arrow or custom image - clockwise from
+     * north; omit it to keep the previous heading.
+     */
+    setLocation(location: {
+        lat: number;
+        lon: number;
+    }, headingDeg?: number): void;
+    /** Removes the puck from the map. `setLocation` re-adds it. */
+    remove(): void;
+}
+
+/** One place to show on the map - a store, depot, branch, POI. */
+interface Place {
+    /** Stable unique id, e.g. your store number. */
+    id: string;
+    /** Display name. */
+    name: string;
+    /** Latitude, degrees. */
+    lat: number;
+    /** Longitude, degrees. */
+    lon: number;
+    /**
+     * Arbitrary extra data (opening hours, phone, …). Copied onto the GeoJSON
+     * feature properties, so it is available to data-driven styling and comes
+     * back on the place handed to `onPlaceClick` / `popup`.
+     */
+    properties?: Record<string, unknown>;
+}
+/** A GeoJSON Point feature, as accepted in a {@link PlacesFeatureCollection}. */
+interface PlacePointFeature {
+    type: "Feature";
+    id?: string | number;
+    geometry: {
+        type: "Point";
+        coordinates: number[];
+    };
+    properties?: Record<string, unknown> | null;
+}
+/**
+ * A plain GeoJSON FeatureCollection of Points, accepted anywhere a `Place[]`
+ * is (structurally compatible with `@types/geojson`'s
+ * `FeatureCollection<Point>`). See {@link placesFromGeoJSON} for how ids and
+ * names are derived.
+ */
+interface PlacesFeatureCollection {
+    type: "FeatureCollection";
+    features: PlacePointFeature[];
+}
+/** Either input shape for {@link PlacesLayer} / `setPlaces`. */
+type PlacesInput = Place[] | PlacesFeatureCollection;
+/** A place with its straight-line distance attached (see `nearest`). */
+type PlaceWithDistance = Place & {
+    /** Straight-line (haversine) distance from the origin, metres. */
+    distanceM: number;
+};
+/** A place with gateway drive time attached (see `nearestByDriveTime`). */
+type PlaceWithDriveTime = Place & {
+    /** Drive time from the origin, seconds. */
+    durationS: number;
+    /** Driven distance from the origin, metres (`null` when not returned). */
+    distanceM: number | null;
+};
+/** A custom pin image for unclustered places. */
+interface PlacesIcon {
+    /** Image URL (any format `Map#loadImage` accepts, e.g. PNG). */
+    url: string;
+    /** MapLibre `icon-size` scale factor. Defaults to `1`. */
+    size?: number;
+}
+/** Options for {@link PlacesLayer.nearestByDriveTime}. */
+interface NearestByDriveTimeOptions {
+    /** How many places to return. Defaults to `1`. */
+    n?: number;
+    /**
+     * Gateway costing model, e.g. `"auto"` (default) or `"truck"` (Premium
+     * price class - see `POST /matrix` in the API docs).
+     */
+    costing?: string;
+    /**
+     * Valhalla-style costing options forwarded verbatim, e.g.
+     * `{ truck: { height: 4.0 } }`.
+     */
+    costingOptions?: Record<string, unknown>;
+}
+interface PlacesLayerOptions {
+    /** Initial places. Also settable later via {@link PlacesLayer.setPlaces}. */
+    places?: PlacesInput;
+    /** Cluster nearby places into count badges. Defaults to `true`. */
+    cluster?: boolean;
+    /** Cluster radius in pixels. Defaults to MapLibre's `50`. */
+    clusterRadius?: number;
+    /** Max zoom to cluster at. Defaults to MapLibre's `14`. */
+    clusterMaxZoom?: number;
+    /** Pin and cluster colour. Defaults to MapMap signal blue (`#3a86ff`). */
+    color?: string;
+    /**
+     * Custom pin image for unclustered places (a symbol layer instead of the
+     * default circle). If the image fails to load, the circle look is used.
+     */
+    icon?: PlacesIcon;
+    /**
+     * Fit the map to the places the first time they are set. Defaults to
+     * `false` (the map view is left alone).
+     */
+    fitBounds?: boolean;
+    /** Unique id prefix for the source/layers. Defaults to `"mapmap-places"`. */
+    id?: string;
+    /** Gateway base URL. Defaults to the map's `baseUrl` when given a map. */
+    baseUrl?: string;
+    /** Gateway API key. Defaults to the map's `apiKey` when given a map. */
+    apiKey?: string;
+    /** Called when an individual (unclustered) place is clicked. */
+    onPlaceClick?: (place: Place, lngLat: {
+        lng: number;
+        lat: number;
+    }) => void;
+    /**
+     * Built-in popup: return HTML (a string is set with `setHTML`, an element
+     * with `setDOMContent`) and a `maplibregl.Popup` opens at the place on
+     * click. Omit for no popup.
+     */
+    popup?: (place: Place) => string | HTMLElement;
+}
+/**
+ * Normalise a GeoJSON FeatureCollection of Points to `Place[]`. The id comes
+ * from `feature.id`, then `properties.id`, then the feature index; the name
+ * from `properties.name` (else `""`). Non-Point features are skipped.
+ */
+declare function placesFromGeoJSON(collection: PlacesFeatureCollection): Place[];
+/** Straight-line (haversine) distance between two points, metres. */
+declare function haversineDistanceM(a: {
+    lat: number;
+    lon: number;
+}, b: {
+    lat: number;
+    lon: number;
+}): number;
+/** Draws customer places on a MapLibre map, with clustering and popups. */
+declare class PlacesLayer {
+    private readonly map;
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly sourceId;
+    private readonly clustersLayerId;
+    private readonly clusterCountLayerId;
+    private readonly pointsLayerId;
+    private readonly iconImageId;
+    private readonly cluster;
+    private readonly clusterRadius;
+    private readonly clusterMaxZoom;
+    private readonly color;
+    private readonly icon;
+    private readonly wantFitBounds;
+    private readonly onPlaceClick;
+    private readonly popupFn;
+    private places;
+    private data;
+    private popup;
+    private fitted;
+    private destroyed;
+    constructor(map: MapMapMap | Map, options?: PlacesLayerOptions);
+    private readonly handleStyleLoad;
+    private readonly handleMouseEnter;
+    private readonly handleMouseLeave;
+    private readonly handlePlaceClick;
+    private readonly handleClusterClick;
+    /**
+     * Replace the layer's places - a `Place[]` or a GeoJSON FeatureCollection
+     * of Points. Updates the existing GeoJSON source in place; safe to call
+     * before the style has loaded (installed on the next `style.load`). With
+     * `fitBounds: true` the first non-empty set also fits the map view.
+     */
+    setPlaces(places: PlacesInput): void;
+    /** The layer's current places (normalised to `Place[]`). */
+    get current(): Place[];
+    /**
+     * The nearest `n` places (default `1`) to `origin` by straight-line
+     * (haversine) distance, each with `distanceM` attached. Pure and instant -
+     * no network. For road-network answers use {@link nearestByDriveTime}.
+     */
+    nearest(origin: {
+        lat: number;
+        lon: number;
+    }, n?: number): PlaceWithDistance[];
+    /**
+     * The nearest `n` places (default `1`) to `origin` by drive time, via the
+     * gateway's `POST /matrix` (one source, all places as targets). Resolves
+     * to places sorted by `durationS` ascending, with the driven `distanceM`
+     * attached; unreachable places (`null` duration) are dropped. Needs the
+     * gateway `baseUrl`/`apiKey` - picked up from a `MapMapMap` automatically,
+     * or pass them as layer options.
+     */
+    nearestByDriveTime(origin: {
+        lat: number;
+        lon: number;
+    }, options?: NearestByDriveTimeOptions): Promise<PlaceWithDriveTime[]>;
+    /** Add-or-update the source and layers on the current style. */
+    private install;
+    /** Cluster circles (sized by count) and the count badge on top. */
+    private installClusterLayers;
+    /**
+     * The unclustered-places layer: a circle pin by default, or a symbol
+     * layer once the custom `icon` image has loaded (falling back to the
+     * circle look if it fails, like PositionPuck's image fallback).
+     */
+    private installPointsLayer;
+    private addCirclePointsLayer;
+    private addIconPointsLayer;
+    /** Open the built-in popup for a place, replacing any previous one. */
+    private openPopup;
+    /** Remove the places' layers, source, image and popup from the map. */
+    clear(): void;
+    /**
+     * Remove the places and detach every listener (style.load, clicks,
+     * hovers). Call when disposing of the layer (the map is left untouched).
+     */
+    destroy(): void;
+}
+
+/**
+ * NavigationCamera - the turnkey chase-cam for turn-by-turn navigation.
+ *
+ * Packages the Google-Maps-style follow camera on top of MapLibre's native
+ * camera: per-fix `easeTo` with linear easing (continuous glide, no
+ * rubber-banding), course-up bearing, a tilted pitch preset, and a
+ * screen-offset that anchors the puck low-centre so the camera looks ahead.
+ * User gestures (drag, rotate, pitch, zoom) switch the camera to `"free"`
+ * mode; it auto-recentres after a configurable idle period. An `overview()`
+ * mode fits the whole route top-down, and `resume()` returns to the chase
+ * cam at the last known fix.
+ *
+ * Like `RouteLayer`, the class holds only a structural handle on the map
+ * (`easeTo`, `fitBounds`, `stop`, events, container) so it is unit-testable
+ * against a fake without a WebGL context.
+ *
+ * Globe projection note: {@link NavigationCamera.isSupported} returns
+ * `false` when the map runs the globe (or vertical-perspective) projection.
+ * At navigation zooms globe renders much like mercator, but the pixel-offset
+ * anchor maths and the top-down overview framing assume a mercator camera;
+ * switch the map to mercator (`map.setProjection({ type: "mercator" })`)
+ * before navigating, or accept an unanchored follow.
+ */
+
+/** A GPS fix to follow. */
+interface CameraFix {
+    lat: number;
+    lon: number;
+}
+/** The camera's current behaviour. */
+type NavigationCameraMode = "follow" | "overview" | "free";
+interface NavigationCameraOptions {
+    /**
+     * Camera tilt in degrees, clamped to 0-85. Default `60` - MapLibre's
+     * non-experimental ceiling; values above 60 may show rendering artefacts
+     * and flatten DOM-marker pucks. When the requested pitch exceeds the
+     * map's `maxPitch`, the limit is raised to match.
+     *
+     * Precedence: this option > the Studio design's `camera.pitch` (when the
+     * map is a `MapMapMap` whose theme carried `extra.nav.camera`) > the
+     * built-in default.
+     */
+    pitch?: number;
+    /**
+     * Follow-mode zoom. Default `17`. Same precedence as `pitch`: option >
+     * Studio design `camera.zoom` > built-in default.
+     */
+    zoom?: number;
+    /**
+     * Where the fix (and puck) sits vertically on screen, as a fraction of
+     * the container height from the top, clamped to 0-1. Default `0.72` -
+     * the puck rides low so the camera looks up the road ahead.
+     */
+    anchorY?: number;
+    /**
+     * Ease duration per {@link NavigationCamera.follow} call, milliseconds.
+     * Default `900`, and always capped by the observed fix interval so a
+     * fast fix cadence never queues up lagging animations.
+     */
+    easeMs?: number;
+    /**
+     * Idle time after the last user gesture before the camera recentres
+     * itself back to follow mode, milliseconds. Default `6000`; `0` disables
+     * auto-recentre (the app must call {@link NavigationCamera.resume}).
+     */
+    autoRecentreMs?: number;
+}
+/** Anything with a `PositionPuck`-shaped `setLocation` can be co-driven. */
+type CoDrivenPuck = Pick<PositionPuck, "setLocation">;
+/** A follow-mode chase camera for MapMap maps. */
+declare class NavigationCamera {
+    private readonly m;
+    private readonly pitch;
+    private readonly zoom;
+    private readonly anchorY;
+    private readonly easeMs;
+    private readonly autoRecentreMs;
+    private currentMode;
+    private puck;
+    private lastFix;
+    private lastCourse;
+    private lastFixAt;
+    private lastRoute;
+    private recentreTimer;
+    private destroyed;
+    private readonly onInteraction;
+    /**
+     * `false` when the map runs the globe (or vertical-perspective)
+     * projection, whose camera geometry breaks the low-anchor offset maths
+     * and top-down overview framing. Switch to mercator for navigation.
+     */
+    static isSupported(map: MapMapMap | Map): boolean;
+    constructor(map: MapMapMap | Map, options?: NavigationCameraOptions);
+    /** The camera's current behaviour: `"follow"`, `"overview"` or `"free"`. */
+    get mode(): NavigationCameraMode;
+    /**
+     * Co-drive a {@link PositionPuck}: every {@link follow} call also
+     * `setLocation`s the puck, so camera and puck never diverge.
+     */
+    attachPuck(puck: CoDrivenPuck): void;
+    /**
+     * Glide the camera to a fix, course-up when `courseDeg` is given
+     * (bearing is left unchanged when it is `undefined`). Each call eases
+     * with linear timing over `easeMs` capped by the observed fix interval,
+     * and interrupts the previous ease (no queue buildup). The fix and an
+     * attached puck are always updated, but the camera only moves in
+     * `"follow"` mode - `"free"` and `"overview"` record the fix for
+     * {@link resume}.
+     */
+    follow(fix: CameraFix, courseDeg?: number): void;
+    /**
+     * Fit the route top-down (pitch 0, north-up). Pass the route geometry on
+     * the first call; later calls reuse the last geometry given. A no-op
+     * when no geometry has ever been provided.
+     */
+    overview(routeGeometry?: RouteGeometry): void;
+    /**
+     * Return to follow mode, gliding back to the last fix (with its last
+     * known course) when one has been recorded.
+     */
+    resume(): void;
+    /** Remove the map listeners and cancel any pending auto-recentre. */
+    destroy(): void;
+    private easeToFix;
+    /**
+     * The pixel offset that renders the followed fix at `anchorY` of the
+     * container height: `(anchorY - 0.5) * height` (0.5 is the natural
+     * centre; positive y moves the puck down the screen).
+     */
+    private anchorOffsetY;
+    private scheduleRecentre;
+    private clearRecentreTimer;
+}
+
+/**
+ * AdrCheck - optional helper for the gateway's `POST /adr/check` endpoint.
+ *
+ * The ADR 8.6.4 tunnel compliance engine, exposed directly. No MapLibre
+ * dependency; just a typed fetch wrapper.
+ */
+
+/**
+ * Builds the exact wire body the gateway deserialises
+ * (`sn-gateway` `routes/adr.rs` → `sn_adr::AdrVehicleProfile`):
+ * `{"adr": {"dimensions": {…}, "tunnel_code"?, "hazmat"}, "tunnel_category"}`.
+ * Unset dimensions default to the EU 96/53/EC artic maximums, mirroring
+ * `TruckDimensions::default()`. Exported for contract tests.
+ */
+declare function buildAdrCheckBody(request: AdrCheckRequest): Record<string, unknown>;
+interface AdrCheckOptions {
+    /** Gateway base URL, e.g. `https://api.mapmap.ai`. */
+    baseUrl: string;
+    /** Gateway API key (`snk_…`). */
+    apiKey?: string;
+}
+/** Calls `POST /adr/check` and returns the parsed compliance decision. */
+declare class AdrCheck {
+    private readonly baseUrl;
+    private readonly apiKey;
+    constructor(options: AdrCheckOptions);
+    check(request: AdrCheckRequest): Promise<AdrCheckResult>;
+}
+
+/** Guidance-related query options. */
+interface GuidanceQuery {
+    voice?: boolean;
+    banner?: boolean;
+    language?: string;
+}
+/** Build the OSRM query string (without the leading `?`) for a request. */
+declare function buildRouteQuery(truck?: TruckParams, guidance?: GuidanceQuery): string;
+/**
+ * Build the full OSRM route URL. `baseUrl` is the gateway origin (trailing
+ * slashes are trimmed); `points` is the ordered coordinate path.
+ */
+declare function buildRouteUrl(baseUrl: string, profile: RouteProfile, points: LngLatLike[], truck?: TruckParams, guidance?: GuidanceQuery): string;
+/**
+ * Parse an OSRM route response into a {@link ParsedRoute}. Throws with the
+ * OSRM `code`/`message` when the response is not `Ok` or carries no route.
+ */
+declare function parseOsrmRoute(body: unknown): ParsedRoute;
+
+/**
+ * Coordinate helpers - pure, browser-free logic.
+ *
+ * The gateway speaks the OSRM HTTP API: coordinates are `lon,lat` pairs
+ * separated by `;`. MapLibre and GeoJSON use `[lng, lat]` order, so the one
+ * job here is to normalise the three accepted input shapes into that wire
+ * format without ever swapping the axes by accident.
+ */
+
+/** Normalise any accepted shape to a `[lng, lat]` tuple. */
+declare function toLngLat(point: LngLatLike): [number, number];
+/** Format one point as an OSRM `lon,lat` coordinate. */
+declare function formatCoord(point: LngLatLike): string;
+/**
+ * Format an ordered list of points as an OSRM coordinate path
+ * (`lon,lat;lon,lat;…`). At least two points are required, matching the
+ * gateway, which rejects single-coordinate requests.
+ */
+declare function formatCoords(points: LngLatLike[]): string;
+
+/**
+ * Turn-by-turn guidance helpers: voice + banner instructions and lanes.
+ *
+ * The gateway's OSRM endpoint returns Mapbox-shaped `voiceInstructions`
+ * (plain + SSML announcements with distance triggers) and
+ * `bannerInstructions` (primary line with a maneuver glyph, lane
+ * sub-banners) on each step when requested with
+ * `voice: true` / `banner: true` route options. This module extracts them
+ * from a parsed route, renders a banner as a DOM element, and speaks
+ * announcements through the browser's `SpeechSynthesis`.
+ *
+ * Everything except {@link GuidanceBanner} and {@link speak} is pure and
+ * covered by unit tests.
+ */
+
+/** A spoken instruction with its trigger distance before the maneuver. */
+interface VoiceInstruction {
+    /** Metres before the end of the step at which to announce. */
+    distanceAlongGeometry: number;
+    /** Plain text for speech synthesis. */
+    announcement: string;
+    /** SSML form, preferred by engines that support it. */
+    ssmlAnnouncement?: string;
+}
+/** One lane entry of a banner lane diagram. */
+interface LaneIndication {
+    /** Turn directions this lane allows (OSRM indication strings). */
+    directions: string[];
+    /**
+     * Whether the lane can be used for the maneuver. `undefined` means
+     * unknown, not unusable — banner components omit the flag for
+     * non-recommended lanes (see {@link bannerLanes}).
+     */
+    valid?: boolean;
+    /** Whether guidance recommends this lane. */
+    active?: boolean;
+}
+/** A typed fragment of banner content. */
+interface BannerComponent {
+    type: string;
+    text: string;
+    directions?: string[];
+    active?: boolean;
+}
+/** One banner line. */
+interface BannerContent {
+    text: string;
+    type?: string;
+    modifier?: string;
+    components?: BannerComponent[];
+}
+/** The visual banner shown while travelling a step. */
+interface BannerInstruction {
+    distanceAlongGeometry: number;
+    primary: BannerContent;
+    secondary?: BannerContent;
+    sub?: BannerContent;
+}
+/** Guidance data for one step of the route. */
+interface StepGuidance {
+    /** Step index within the flattened route. */
+    stepIndex: number;
+    /** Step length in metres. */
+    distanceM: number;
+    /**
+     * Written instruction for the step's upcoming maneuver. Taken from
+     * `maneuver.instruction` when a server emits it (Mapbox-style); the
+     * MapMap gateway does not, so it falls back to the step's final voice
+     * announcement (the pre-transition instruction) and then to the banner
+     * primary text. Undefined only when the step carries no guidance at all.
+     */
+    instruction?: string;
+    /** Spoken announcements, ordered by descending trigger distance. */
+    voice: VoiceInstruction[];
+    /** Visual banners for the upcoming maneuver. */
+    banners: BannerInstruction[];
+}
+/**
+ * Extracts per-step guidance from a parsed route (requires the route to
+ * have been requested with `steps: true` and voice/banner enabled).
+ * Steps without instructions yield empty arrays, never holes.
+ */
+declare function extractGuidance(route: ParsedRoute): StepGuidance[];
+/**
+ * Strips SSML tags down to speakable plain text. Entities are decoded in a
+ * single pass (never re-scanning already-decoded output), so text whose
+ * literal content looks like an entity — e.g. `&amp;lt;`, the gateway's
+ * escape of a literal `&lt;` — round-trips correctly. Decodes the five
+ * named XML entities plus decimal numeric references (`&#39;`).
+ */
+declare function ssmlToText(ssml: string): string;
+/**
+ * Lane entries of a banner's sub line, if it carries a lane diagram.
+ *
+ * Banner lane components only carry `active` (the recommended lane) — the
+ * gateway drops the per-lane `valid` flag from banners, keeping it in the
+ * raw route's `intersections[].lanes`. An active lane is by definition
+ * usable, so `valid` is `true` for active lanes and *unknown* (undefined,
+ * never `false`) for the rest: a non-recommended lane may still be legal.
+ * Read `route.raw` `legs[].steps[].intersections[].lanes` for the full
+ * `valid` set.
+ */
+declare function bannerLanes(banner: BannerInstruction): LaneIndication[];
+/**
+ * Unicode arrow for a lane/maneuver direction (OSRM indication strings).
+ * A text-only fallback; sprite-based lane icons ship with the map assets.
+ */
+declare function directionArrow(direction: string): string;
+/** Options for {@link speak}. */
+interface SpeakOptions {
+    /** BCP 47 language for the utterance, e.g. `en-GB`. */
+    lang?: string;
+    /** Speech rate (0.1–10, default 1). */
+    rate?: number;
+}
+/**
+ * Speaks a voice instruction through the browser's `SpeechSynthesis`.
+ * Prefers the SSML body's text (browsers do not accept raw SSML). Returns
+ * false when speech synthesis is unavailable (e.g. non-browser contexts).
+ * De-duplication is the caller's responsibility: speak each instruction
+ * once as its trigger distance is crossed.
+ */
+declare function speak(instruction: VoiceInstruction, options?: SpeakOptions): boolean;
+/**
+ * A minimal DOM banner: primary text with a maneuver arrow, optional lane
+ * row. Style with the `mapmap-banner` / `mapmap-banner-lanes` classes, pass
+ * a Studio design (`extra.nav` `banner` block, e.g. `map.navDesign?.banner`)
+ * to match a Studio theme, or read {@link StepGuidance} yourself for fully
+ * custom UI.
+ */
+declare class GuidanceBanner {
+    /** The banner root element; attach it wherever your UI needs it. */
+    readonly element: HTMLElement;
+    private readonly design;
+    constructor(container?: HTMLElement, design?: NavBannerDesign);
+    /** Renders a banner instruction (or hides the element with `null`). */
+    update(banner: BannerInstruction | null): void;
+}
+
+export { AdrCheck, type AdrCheckOptions, type AdrCheckRequest, type AdrCheckResult, type AdrDimensions, type AdrTunnelCategory, type BannerComponent, type BannerContent, type BannerInstruction, type BuildStyleOptions, type CameraFix, DEFAULT_GLYPHS_URL, DEFAULT_TERRITORY_TILES_URL, FULL_ATTRIBUTION, GuidanceBanner, LOGO_SVG, type LaneIndication, type LayerOverride, type LngLatLike, LogoControl, type LogoOptions, type LogoPosition, MAX_PUCK_IMAGE_BYTES, MapMapMap, type MapMapOptions, type MapMapTheme, NAV_CAMERA_DEFAULTS, type NavBannerDesign, type NavCameraDesign, type NavDesign, type NavPuckDesign, type NavRouteDesign, NavigationCamera, type NavigationCameraMode, type NavigationCameraOptions, type NearestByDriveTimeOptions, OPENMAPTILES_ATTRIBUTION, OSM_ATTRIBUTION, PALETTE_SLOTS, type ParsedRoute, type Place, type PlacePointFeature, type PlaceWithDistance, type PlaceWithDriveTime, type PlacesFeatureCollection, type PlacesIcon, type PlacesInput, PlacesLayer, type PlacesLayerOptions, PositionPuck, type RouteGeometry, RouteLayer, type RouteLayerOptions, type RouteOptions, type RouteProfile, SIGNAL_BLUE, SOURCE_LAYERS, type SpeakOptions, type StepGuidance, type Theme, type TruckParams, type VoiceInstruction, bannerLanes, buildAdrCheckBody, buildRouteQuery, buildRouteUrl, buildStyle, createMap, defaultNavDesign, directionArrow, extractGuidance, formatCoord, formatCoords, haversineDistanceM, navDesignFromTheme, navDesignFromThemeUrl, parseNavDesign, parseOsrmRoute, placesFromGeoJSON, registerPmtilesProtocol, speak, ssmlToText, toLngLat, toPmtilesUrl };