@mapmap/maps 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,4 +1,259 @@
-import maplibregl, { StyleSpecification, Map, MapOptions } from 'maplibre-gl';
+import maplibregl, { CustomLayerInterface, Map, StyleSpecification, MapOptions, ExpressionSpecification } from 'maplibre-gl';
+
+/**
+ * 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>;
+}
+
+/**
+ * Effects engine - named, geometry-anchored visual effects rendered through
+ * MapLibre's stable `CustomLayerInterface` (first-party GLSL, no runtime
+ * dependencies). The first effect is `"flow"`: an animated energy ribbon
+ * along the active route line, drawn as a triangle strip with a flowing
+ * pulse gradient driven by a time uniform.
+ *
+ * Deliberately NOT full-map post-processing: MapLibre has no official
+ * post-process hook, so every effect here anchors to geometry and rides the
+ * supported custom-layer API. New effects register in {@link ROUTE_EFFECTS}.
+ *
+ * Accessibility and resilience:
+ * - `prefers-reduced-motion: reduce` freezes the ribbon to a static
+ *   gradient (no animation loop, no repaints).
+ * - If WebGL setup for the custom layer fails (shader compile/link, lost
+ *   context), the effect silently disables itself - the ordinary route
+ *   line underneath is untouched - and logs a single console warning.
+ *
+ * The tessellation and colour helpers are pure and unit-tested in Node;
+ * only the layer object itself touches WebGL.
+ */
+
+/** The names the effects registry knows. Grows as effects land. */
+type RouteEffectName = "flow";
+/** Options for the `"flow"` route effect (all optional). */
+interface RouteFlowOptions {
+    /** Ribbon colour (hex or rgb()/rgba()). Defaults to MapMap signal blue. */
+    color?: string;
+    /** Ribbon width in CSS pixels. Defaults to `10`. */
+    width?: number;
+    /** Flow speed in pulse cycles per second. Defaults to `0.6`. */
+    speed?: number;
+    /** MapLibre layer id. Defaults to `"mapmap-route-effect"`. */
+    id?: string;
+}
+/** Floats per ribbon vertex: x, y (mercator), nx, ny (unit normal), progress. */
+declare const RIBBON_FLOATS_PER_VERTEX = 5;
+/** A tessellated route ribbon, ready for a `TRIANGLE_STRIP` draw. */
+interface RibbonMesh {
+    /**
+     * Interleaved vertex data, {@link RIBBON_FLOATS_PER_VERTEX} floats per
+     * vertex: mercator position, the unit extrusion normal (the shader
+     * extrudes `pos + normal * halfWidth`, so width stays zoom-correct
+     * without re-tessellating), and progress along the route (0 at the
+     * start, 1 at the end - the flowing gradient's coordinate).
+     */
+    vertices: Float32Array;
+    /** Number of vertices (two per route point kept). */
+    vertexCount: number;
+}
+/**
+ * Project a `[lng, lat]` to web-mercator world coordinates in [0, 1]
+ * (MapLibre's `MercatorCoordinate` convention: x east, y south).
+ */
+declare function lngLatToMercator(lngLat: [number, number]): [number, number];
+/**
+ * Tessellate a route line into a centreline triangle strip: two vertices
+ * per point, each carrying the point's mercator position, a unit extrusion
+ * normal (averaged between adjacent segments at joins - a bevel-free miter
+ * that slightly thins very sharp corners, which is invisible on a soft
+ * glow ribbon), and normalised progress along the line.
+ *
+ * Pure: no WebGL, no map. Consecutive duplicate points are dropped; fewer
+ * than two distinct points yield an empty mesh.
+ */
+declare function tessellateRouteRibbon(coordinates: [number, number][]): RibbonMesh;
+/**
+ * Parse a CSS colour to premultiplication-ready `[r, g, b, a]` (0-1
+ * channels). Supports the hex forms and `rgb()`/`rgba()`; anything else
+ * (named colours, `hsl()`) returns `undefined` and the caller falls back
+ * to the default - this runs where no canvas is guaranteed, so no
+ * browser colour parser is available.
+ */
+declare function parseCssColour(colour: string): [number, number, number, number] | undefined;
+/** Whether the user has asked for reduced motion. Safe without a DOM. */
+declare function prefersReducedMotion(): boolean;
+/** Default flow parameters (exported so docs/tests state one truth). */
+declare const FLOW_DEFAULTS: {
+    readonly color: "#3a86ff";
+    readonly width: 10;
+    readonly speed: 0.6;
+};
+/**
+ * A MapLibre custom layer (`CustomLayerInterface`) drawing the flowing
+ * route ribbon. Construct via {@link createRouteEffect} (the registry) or
+ * use `MapMapMap.setRouteEffect("flow")`, which manages the lifecycle.
+ */
+declare class FlowRouteEffectLayer implements CustomLayerInterface {
+    readonly id: string;
+    readonly type: "custom";
+    readonly renderingMode: "2d";
+    private geometry;
+    private readonly colour;
+    private readonly widthPx;
+    private readonly speed;
+    private readonly animate;
+    private mapRef;
+    private glRef;
+    private program;
+    private buffer;
+    private vertexCount;
+    private repeats;
+    private startedAt;
+    private failed;
+    private aPos;
+    private aNormal;
+    private aProgress;
+    private uMatrix;
+    private uHalfWidth;
+    private uColor;
+    private uPhase;
+    private uRepeats;
+    constructor(geometry: RouteGeometry, options?: RouteFlowOptions);
+    /** Swap the ribbon onto a new route line (e.g. after a reroute). */
+    setGeometry(geometry: RouteGeometry): void;
+    onAdd(map: Map, gl: WebGLRenderingContext | WebGL2RenderingContext): void;
+    onRemove(_map: Map, gl: WebGLRenderingContext | WebGL2RenderingContext): void;
+    render(gl: WebGLRenderingContext | WebGL2RenderingContext, args: unknown): void;
+    private upload;
+}
+/** A route effect layer: a custom layer that can retarget its geometry. */
+interface RouteEffectLayer extends CustomLayerInterface {
+    setGeometry(geometry: RouteGeometry): void;
+}
+/**
+ * The effect registry: name -> layer factory. New effects (ambient life,
+ * seasonal snow, fog-of-exploration) add an entry here and a name to
+ * {@link RouteEffectName}.
+ */
+declare const ROUTE_EFFECTS: Record<RouteEffectName, (geometry: RouteGeometry, options?: RouteFlowOptions) => RouteEffectLayer>;
+/**
+ * Create a named route effect layer. Throws an agent-readable error for
+ * unknown names (the accepted list included).
+ */
+declare function createRouteEffect(name: RouteEffectName, geometry: RouteGeometry, options?: RouteFlowOptions): RouteEffectLayer;
 
 /**
  * The MapMap logo control: a small wordmark on the map, the same
@@ -104,6 +359,23 @@ interface LayerOverride {
     minzoom?: number;
     maxzoom?: number;
 }
+/**
+ * The optional visual-effects block, mirroring `sn_style::Effects`. Unlike
+ * `extra`, this IS carried into the compiled style — as
+ * `metadata["mapmap:effects"]` — so any consumer of a compiled `style.json`
+ * (hosted style URL, baked territory package) can honour it without the
+ * theme document. Renderers that do not know the effects engine ignore the
+ * metadata and render the style unchanged.
+ */
+interface ThemeEffects {
+    /** Route-line effect: `"flow"` (animated energy ribbon) or `"none"`. */
+    route?: "flow" | "none";
+    /**
+     * Effect parameters, validated per effect. For `flow`: `color` (CSS
+     * colour), `width` (px, 0.5-40), `speed` (cycles/s, 0-10).
+     */
+    params?: Record<string, unknown>;
+}
 /**
  * A MapMap Studio theme: the unit users and agents edit, store and publish.
  * Mirrors `sn_style::Theme` (all fields carry serde defaults, so everything
@@ -146,22 +418,38 @@ interface Theme {
      * source-layer.
      */
     extra_layers?: JsonObject[];
+    /**
+     * Optional visual effects (route ribbon etc.). Compiled into
+     * `metadata["mapmap:effects"]` on the style — see {@link ThemeEffects}.
+     * Mirrors `Theme::effects`.
+     */
+    effects?: ThemeEffects;
     /**
      * 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
+     * see `nav-design.ts`) and its POI category design (`extra.poi`; see
+     * `poi-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.
+     * `navDesignFromThemeUrl` / `poiDesignFromThemeUrl` with the hosted
+     * theme URL.
      */
     extra?: {
         nav?: unknown;
+        poi?: unknown;
     };
 }
 interface BuildStyleOptions {
+    /**
+     * Label language: an ISO 639 code selects `name:<code>` with a
+     * local-name fallback; the literal `"local"` selects the local name
+     * outright; omitted keeps the default (English-first). The tiles carry
+     * the OSM `name:*` set, so switching involves no tile rebuild.
+     */
+    labelLanguage?: string;
     /**
      * Theme to build: a built-in name (`"light"` / `"dark"`) or a full
      * {@link Theme} document. Defaults to `"light"`.
@@ -175,6 +463,22 @@ interface BuildStyleOptions {
 }
 /** Ensure a tiles URL carries the `pmtiles://` protocol prefix. */
 declare function toPmtilesUrl(url: string): string;
+/**
+ * The `metadata` key a compiled style carries its effects block under.
+ * Shared with `sn-style` (compile.rs) and read back by `MapMapMap` to
+ * auto-enable the route effect for styles that request one.
+ */
+declare const EFFECTS_METADATA_KEY = "mapmap:effects";
+/**
+ * The effects block from a compiled style's `metadata`, if the style
+ * carries a valid one (`{ route: "flow", params? }`). Lenient by design —
+ * it reads FOREIGN styles (hosted URLs, baked packages), so anything
+ * malformed returns `undefined` rather than throwing.
+ */
+declare function effectsFromStyleMetadata(metadata: unknown): {
+    route: "flow";
+    params?: Record<string, unknown>;
+} | undefined;
 declare function buildStyle(options?: BuildStyleOptions): StyleSpecification;
 
 /**
@@ -331,6 +635,128 @@ declare function navDesignFromTheme(theme: Theme | undefined | null): NavDesign
  */
 declare function navDesignFromThemeUrl(url: string, fetchImpl?: typeof fetch): Promise<NavDesign | undefined>;
 
+/**
+ * Studio POI category-design block (`extra.poi`) - types, defaults, parser
+ * and appliers.
+ *
+ * MapMap Studio's POIs panel colours the ~8 POI categories - the coloured
+ * category dot drawn under a POI label, and the `poi-labels` text colour -
+ * and stores the result as a small design-token block under `extra.poi` in
+ * the theme JSON it downloads/copies/publishes, exactly like the navigation
+ * design under `extra.nav` (see nav-design.ts). This module reads that
+ * block and applies the label-text part to a live MapLibre map; the dot
+ * images themselves are runtime-rasterised by their host (the MapMap
+ * website today - sprite-based icons arrive with marker packs).
+ *
+ * LOCKSTEP: this file mirrors `website/lib/studio-poi.ts` (the Studio
+ * reference parser) - identical category ids, built-in colours, leniency
+ * and expression building. The class->category mapping mirrors
+ * `website/lib/poi-icons.ts` (`POI_CLASS_CATEGORIES`). Keep them in sync so
+ * a theme previews in Studio exactly as the SDK applies 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`. 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. Read it from a theme file you pass to `createMap` / `buildStyle`,
+ * or fetch it from a hosted style with {@link poiDesignFromThemeUrl} - a
+ * compiled style URL alone never carries it.
+ */
+
+/** One category's overrides. Both fields optional: absent = built-in. */
+interface PoiCategoryDesign {
+    /** Dot fill colour (replaces the built-in category brand colour). */
+    color?: string;
+    /** Label text colour for this category (replaces `textSecondary`). */
+    textColor?: string;
+}
+/** The `extra.poi` block: POI category design. */
+interface PoiDesign {
+    /** Block schema version; currently always 1. */
+    version: 1;
+    /** Overrides by category id; empty = all built-in. */
+    categories: Record<string, PoiCategoryDesign>;
+}
+/**
+ * The valid category ids with their built-in dot colours, in presentation
+ * order. LOCKSTEP: mirrors `POI_CATEGORIES` in `website/lib/poi-icons.ts`.
+ */
+declare const POI_CATEGORY_COLORS: readonly (readonly [string, string])[];
+/** The valid category ids, in presentation order. */
+declare const POI_CATEGORY_IDS: readonly string[];
+/**
+ * OpenMapTiles `poi` layer `class` values grouped into the categories
+ * above; every class not listed falls through to `services`. LOCKSTEP:
+ * mirrors `POI_CLASS_CATEGORIES` in `website/lib/poi-icons.ts`.
+ */
+declare const POI_CLASS_CATEGORIES: Record<string, string[]>;
+/** The built-in dot colour for a category id. */
+declare function builtInPoiColor(categoryId: string): string | undefined;
+/** No overrides: every category keeps its built-in dot and label colours. */
+declare function defaultPoiDesign(): PoiDesign;
+/** True when the design changes nothing. */
+declare function poiDesignIsDefault(design: PoiDesign): boolean;
+/**
+ * Lenient parse of an `extra.poi` value: unknown category ids and invalid
+ * colours are dropped rather than failing, so an imported theme never
+ * breaks on its POI block. LOCKSTEP: identical semantics to
+ * `parsePoiDesign` in `website/lib/studio-poi.ts`.
+ */
+declare function parsePoiDesign(value: unknown): PoiDesign;
+/**
+ * Reads and parses the `extra.poi` block from a Studio theme document.
+ * Returns `undefined` when the theme carries no poi block at all (so
+ * callers can tell "no design" apart from "default design"); a present but
+ * malformed block parses leniently to the defaults. Same contract as
+ * `navDesignFromTheme`.
+ */
+declare function poiDesignFromTheme(theme: Theme | undefined | null): PoiDesign | undefined;
+/**
+ * Fetches a hosted theme document and reads its `extra.poi` block - point
+ * it at the gateway's public, never-cached theme endpoint, e.g.
+ * `https://api.mapmap.ai/styles/midnight-fleet-a1b2c3/theme`. Returns
+ * `undefined` when the theme carries no poi block; throws on network
+ * failure, a non-2xx response or a non-JSON body. Same contract as
+ * {@link navDesignFromThemeUrl}.
+ *
+ * @param fetchImpl Optional `fetch` replacement (tests, Node polyfills).
+ */
+declare function poiDesignFromThemeUrl(url: string, fetchImpl?: typeof fetch): Promise<PoiDesign | undefined>;
+/**
+ * The `poi-labels` `text-color` value for a design: the plain fallback
+ * colour when no category overrides label text, otherwise a `match`
+ * expression keyed on the tile's `class` property. Every non-services
+ * category always gets an arm (override or fallback) so unmatched classes
+ * - the `services` fallback arm - never inherit another category's colour.
+ * LOCKSTEP: mirrors `poiTextColorExpression` in `website/lib/studio-poi.ts`.
+ */
+declare function poiTextColorExpression(design: PoiDesign, fallback: string): unknown;
+/** The subset of the MapLibre map surface {@link applyPoiDesign} touches. */
+interface PoiPaintMap {
+    getStyle(): {
+        layers?: {
+            id: string;
+            type?: string;
+        }[];
+    } | undefined;
+    setPaintProperty(layerId: string, name: string, value: unknown): unknown;
+}
+/**
+ * Applies a design's per-category label text colours to every `poi-labels`
+ * layer on a live map (including per-territory clones named
+ * `poi-labels@<territory>`). `fallbackTextColor` is the colour
+ * non-overridden categories keep - pass the style's `poi-labels` text
+ * colour (the theme's `textSecondary` slot; defaults to the light-base
+ * value). A default design restores the plain fallback, so this is safe to
+ * call on every design change.
+ *
+ * NOTE: runtime paint changes do not survive a later `setStyle`; re-apply
+ * after style swaps (the MapMap website bakes the expression into the
+ * style object instead for exactly this reason).
+ */
+declare function applyPoiDesign(map: PoiPaintMap, design: PoiDesign, fallbackTextColor?: string): void;
+
 /**
  * MapMapMap - the branded MapLibre GL map.
  *
@@ -378,6 +804,15 @@ interface MapMapOptions {
      */
     mapOptions?: Partial<Omit<MapOptions, "container" | "style">>;
 }
+/** Options for {@link MapMapMap.setRouteEffect}. */
+interface SetRouteEffectOptions extends RouteFlowOptions {
+    /**
+     * The route line to attach the effect to. Optional: when omitted the
+     * effect is ARMED and applies as soon as a `RouteLayer` draws a route
+     * (RouteLayer feeds every drawn geometry to the map automatically).
+     */
+    geometry?: RouteGeometry;
+}
 /** 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. */
@@ -393,7 +828,62 @@ declare class MapMapMap {
      * the theme had no nav block (or `style` was not a theme document).
      */
     readonly navDesign: NavDesign | undefined;
+    /**
+     * The Studio POI category design (`extra.poi`) parsed from the theme
+     * passed as `style`, when it carried one. Apply its label-text part with
+     * `applyPoiDesign(map.map, map.poiDesign)`; `undefined` means the theme
+     * had no poi block (or `style` was not a theme document).
+     */
+    readonly poiDesign: PoiDesign | undefined;
+    private effectName;
+    private effectOptions;
+    private effectGeometry;
+    private effectExplicit;
+    private effectLayer;
     constructor(options: MapMapOptions);
+    private readonly handleStyleLoadForEffects;
+    /** The current style's `metadata`, if it can be read yet. */
+    private styleMetadata;
+    /**
+     * Set (or clear) the visual effect on the active route line - the
+     * effects-engine entry point (see `effects.ts`). The first effect is
+     * `"flow"`: an animated energy ribbon flowing along the route, drawn in
+     * a MapLibre custom layer with first-party GLSL.
+     *
+     * ```ts
+     * const route = await routes.route(from, to);
+     * map.setRouteEffect("flow");                       // uses the drawn route
+     * map.setRouteEffect("flow", { color: "#ff7a1f" }); // options
+     * map.setRouteEffect(null);                          // back to the plain line
+     * ```
+     *
+     * Geometry: pass `{ geometry }` explicitly, or omit it and the effect
+     * attaches to whatever route a `RouteLayer` on this map draws (current
+     * and future - RouteLayer reports every drawn line via
+     * {@link setRouteEffectGeometry}).
+     *
+     * Styles whose theme carried an `effects` block auto-enable their effect
+     * from the compiled style's metadata; calling this method (with any
+     * value, including `null`) overrides the style's wish for the lifetime
+     * of this map.
+     *
+     * Accessibility/resilience (see effects.ts): honours
+     * `prefers-reduced-motion` (static gradient, no animation) and falls
+     * back to the plain route line with a single console warning if WebGL
+     * setup fails.
+     */
+    setRouteEffect(effect: RouteEffectName | null, options?: SetRouteEffectOptions): void;
+    /**
+     * Attach the active route effect to a route line (or detach it with
+     * `null`). `RouteLayer` calls this on every `draw()`/`clear()`, so apps
+     * normally never do - pass `geometry` to {@link setRouteEffect} for
+     * routes drawn outside a RouteLayer.
+     */
+    setRouteEffectGeometry(geometry: RouteGeometry | null): void;
+    private effectLayerId;
+    private removeEffectLayer;
+    /** Reconcile the effect state with the map: install, update or remove. */
+    private applyRouteEffect;
     /**
      * Toggle 3D building extrusions at runtime — the live equivalent of
      * compiling the style with `buildings_3d: true` (see `Theme`): adds or
@@ -416,125 +906,6 @@ declare class MapMapMap {
 /** 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.
  *
@@ -558,17 +929,32 @@ interface RouteLayerOptions {
      * without a design the layer keeps its built-in signal-blue look.
      */
     design?: NavRouteDesign;
+    /**
+     * Colour of the already-travelled part of the line once
+     * {@link RouteLayer.setProgress} is used (the Google-style "vanishing
+     * route line"). Defaults to a dimmed grey.
+     */
+    progressColor?: string;
 }
 /** Draws MapMap routes on a MapLibre map. */
 declare class RouteLayer {
     private readonly map;
+    /** The owning MapMapMap, when built from one - fed each drawn route so
+     * an armed route effect (`setRouteEffect`) attaches automatically. */
+    private readonly owner;
     private readonly baseUrl;
     private readonly apiKey;
     private readonly sourceId;
     private readonly casingLayerId;
     private readonly lineLayerId;
+    private readonly maneuverSourceId;
+    private readonly maneuverLayerId;
+    private readonly arrowImageId;
     private readonly design;
+    private readonly progressColor;
     private lastRoute;
+    private progress;
+    private maneuver;
     constructor(map: MapMapMap | Map, options?: RouteLayerOptions);
     private readonly handleStyleLoad;
     /**
@@ -589,6 +975,26 @@ declare class RouteLayer {
     draw(route: ParsedRoute): void;
     /** Add-or-update the source and layers for a route on the current style. */
     private install;
+    /**
+     * Sets how much of the route has been travelled, as a fraction in `[0, 1]`
+     * of the line's length. The travelled part dims to `progressColor` (the
+     * "vanishing route line"); `0` restores the untinted line. The value is
+     * remembered across {@link draw} calls and style swaps. Pair with the
+     * guidance module's distance-remaining to derive the fraction.
+     */
+    setProgress(fraction: number): void;
+    /** Applies the current progress fraction to the line layer's gradient. */
+    private applyProgress;
+    /**
+     * Shows (or moves) the upcoming-manoeuvre arrow: a small map-aligned
+     * arrow at `lngLat` rotated to `bearingDeg` (clockwise from north).
+     * Survives style swaps until {@link clearManeuver}.
+     */
+    setManeuver(lngLat: [number, number], bearingDeg: number): void;
+    /** Hides the manoeuvre arrow. */
+    clearManeuver(): void;
+    /** Add-or-update the manoeuvre arrow source/layer for the current style. */
+    private installManeuver;
     /** Remove the route's layers and source from the map. */
     clear(): void;
     /**
@@ -600,6 +1006,29 @@ declare class RouteLayer {
 
 /** Maximum accepted `data:` puck-image payload (matches Studio's upload cap). */
 declare const MAX_PUCK_IMAGE_BYTES: number;
+/**
+ * The signed shortest-arc rotation from `fromDeg` to `toDeg`, in degrees.
+ * Always in `(-180, 180]`, so a heading tween never spins the long way
+ * round the compass (350° -> 10° is +20°, not -340°).
+ */
+declare function shortestArcDeg(fromDeg: number, toDeg: number): number;
+/** Options for {@link PositionPuck}. */
+interface PositionPuckOptions {
+    /**
+     * Animate between fixes instead of snapping (default `true`). Position
+     * lerps linearly and heading tweens along the shortest arc, over a
+     * duration adapted to the observed fix interval (like the
+     * `NavigationCamera` glide, so puck and camera arrive together). Falls
+     * back to instant placement where `requestAnimationFrame` is missing.
+     */
+    interpolate?: boolean;
+    /** Test seam: clock override, defaults to `Date.now`. */
+    now?: () => number;
+    /** Test seam: frame scheduler override, defaults to rAF. */
+    requestFrame?: (callback: () => void) => number;
+    /** Test seam: frame canceller override, defaults to cancelAnimationFrame. */
+    cancelFrame?: (handle: number) => void;
+}
 /** A current-position puck marker for MapMap maps. */
 declare class PositionPuck {
     /** The puck's root DOM element (the Marker element). */
@@ -608,25 +1037,200 @@ declare class PositionPuck {
     private readonly marker;
     private readonly design;
     private added;
+    private readonly interpolate;
+    private readonly now;
+    private readonly requestFrame?;
+    private readonly cancelFrame?;
+    private frameHandle;
+    /** The position/heading currently rendered on the marker. */
+    private rendered;
+    private lastFixAt;
     /**
      * 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);
+    constructor(map: MapMapMap | Map, design?: NavPuckDesign, options?: PositionPuckOptions);
     /**
      * 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.
+     *
+     * With interpolation on (the default) every call after the first glides
+     * from the currently rendered position - a fix arriving mid-tween
+     * retargets smoothly rather than jumping.
      */
     setLocation(location: {
         lat: number;
         lon: number;
     }, headingDeg?: number): void;
-    /** Removes the puck from the map. `setLocation` re-adds it. */
+    /** Removes the puck from the map (cancelling any tween). `setLocation` re-adds it. */
     remove(): void;
+    /** Applies a position/heading to the marker immediately. */
+    private render;
+    /** Runs a linear position lerp + shortest-arc heading tween via rAF. */
+    private tween;
+    /** Cancels an in-flight tween, leaving the marker where it rendered last. */
+    private cancelTween;
+}
+
+/**
+ * Auto day/night theme switching from sun position.
+ *
+ * A dependency-free solar calculator (the standard sunrise equation, as
+ * published at https://en.wikipedia.org/wiki/Sunrise_equation, itself a
+ * restatement of the NOAA solar calculation details,
+ * https://gml.noaa.gov/grad/solcalc/calcdetails.html) plus a small
+ * scheduler that flips between light and dark at sunrise/sunset. Nothing
+ * here touches a map: pair {@link ThemeScheduler} with
+ * `MapMapMap.setStyle("light" | "dark")` (or any other callback) in the
+ * app. Territory packages already ship paired light/dark styles, so the
+ * switch works offline too.
+ */
+/** Sun-times result: either both events, or a polar day/night marker. */
+type SunTimes = {
+    sunrise: Date;
+    sunset: Date;
+} | "polarDay" | "polarNight";
+/**
+ * Sunrise and sunset (standard -0.833° horizon: refraction + solar disc)
+ * for the civil day containing `date` (UTC) at `lat`/`lng`, or a polar
+ * marker when the sun never crosses the horizon that day.
+ */
+declare function sunTimes(date: Date, lat: number, lng: number): SunTimes;
+/** The theme the sun dictates at `date` for `lat`/`lng`. */
+declare function resolveTheme(date: Date, lat: number, lng: number): "light" | "dark";
+/** Options for {@link ThemeScheduler}. */
+interface ThemeSchedulerOptions {
+    /** Latitude used for the solar calculation. */
+    lat: number;
+    /** Longitude used for the solar calculation. */
+    lng: number;
+    /** Called (immediately on construction, then at each sunrise) for light. */
+    onLight: () => void;
+    /** Called (immediately on construction, then at each sunset) for dark. */
+    onDark: () => void;
+    /** Test seam: clock override, defaults to `Date.now`. */
+    now?: () => number;
+    /** Test seam: timer override, defaults to `setTimeout`. */
+    setTimeoutFn?: (callback: () => void, ms: number) => ReturnType<typeof setTimeout>;
+    /** Test seam: timer canceller, defaults to `clearTimeout`. */
+    clearTimeoutFn?: (handle: ReturnType<typeof setTimeout>) => void;
+}
+/**
+ * Applies the sun-appropriate theme now and at every subsequent
+ * sunrise/sunset until {@link dispose}. No OSS map SDK ships this
+ * out of the box; pair with the OS dark-mode signal in the app if the
+ * user's system preference should win instead.
+ */
+declare class ThemeScheduler {
+    private lat;
+    private lng;
+    private readonly onLight;
+    private readonly onDark;
+    private readonly now;
+    private readonly setTimeoutFn;
+    private readonly clearTimeoutFn;
+    private handle;
+    private applied;
+    private disposed;
+    constructor(options: ThemeSchedulerOptions);
+    /** The theme most recently applied, if any. */
+    get current(): "light" | "dark" | undefined;
+    /** Moves the observer (e.g. a new GPS fix region) and re-evaluates. */
+    setPosition(lat: number, lng: number): void;
+    /** Stops all future flips. */
+    dispose(): void;
+    /** Applies the theme for now and arms the timer for the next boundary. */
+    private evaluate;
+    /** Milliseconds until the next sunrise/sunset (or the polar re-check). */
+    private nextBoundaryDelay;
+}
+
+/**
+ * Runtime label-language switching.
+ *
+ * MapMap tiles carry OpenMapTiles multilingual `name:*` fields
+ * (https://openmaptiles.org/schema/), so a map can switch label language
+ * without new tiles: rewrite each symbol layer's `text-field` to prefer
+ * `name:{language}`. `setMapLanguage(map, "de")` does exactly that for
+ * every layer whose text-field reads name fields (other text — road refs,
+ * house numbers — is left untouched). Pass `null` to restore the compiled
+ * style's default (`name:en` first).
+ *
+ * Server-side, themes can bake a language in with `theme.language`; this
+ * helper is the client-side equivalent for user-facing toggles. For
+ * right-to-left scripts (Arabic, Hebrew) also install MapLibre's RTL text
+ * plugin in the app (`maplibregl.setRTLTextPlugin(...)`) — the SDK does
+ * not fetch remote scripts on your behalf.
+ */
+
+/**
+ * The `text-field` expression for labels in `language` — the requested
+ * language first, the Latin transliteration second, the local name last.
+ * `null` yields the compiled default (`name:en`, then `name`).
+ */
+declare function languageTextField(language: string | null): unknown;
+/**
+ * True when a layer's `text-field` reads `name`/`name:*` properties —
+ * i.e. it is a place/POI/road-name label whose language can switch.
+ * Fields reading other properties (`ref` shields, house numbers) are not.
+ */
+declare function isNameTextField(textField: unknown): boolean;
+/**
+ * Switches every name-label layer of the map's current style to
+ * `language` (`null` restores the style's default). Returns the ids of
+ * the layers it rewrote. Throws on a malformed language tag. Reapply
+ * after `setStyle` — a style swap resets label languages.
+ */
+declare function setMapLanguage(map: MapMapMap | Map, language: string | null): string[];
+
+/**
+ * Probe batch upload - the browser side of opt-in aggregate collection.
+ *
+ * The wasm nav core (`@mapmap/core` `GuidanceSession`) accumulates aggregates
+ * on-device and hands back the exact body to POST via `finishProbeJson()`;
+ * this helper delivers it to the gateway's `POST /v1/probe`, with the same
+ * status handling and retry policy as the mobile SDKs. Aggregates only - the
+ * core is architecturally incapable of emitting a trajectory.
+ *
+ * Consent is the caller's responsibility: only upload for a key whose operator
+ * has set `probe_opt_in`, and - in a browser - only with the user's opt-in
+ * (ePrivacy/PECR) consent. See `docs/PROBE-SDK-INTEGRATION.md`.
+ *
+ * @example
+ * ```ts
+ * const body = session.finishProbeJson(arrived, Date.now());
+ * if (body) void uploadProbeBatch("https://api.mapmap.ai", apiKey, body);
+ * ```
+ */
+/** The outcome of an upload attempt. */
+type ProbeUploadOutcome = "accepted" | "refused" | "notEnabled" | "rejected" | "gaveUp";
+/** Options for {@link uploadProbeBatch}. All optional. */
+interface UploadProbeOptions {
+    /** Injectable fetch (defaults to the global). */
+    fetch?: typeof fetch;
+    /** Total attempts including the first (default 4). */
+    maxAttempts?: number;
+    /** Attempt number → delay before the next try, ms (default `attempt*1000`). */
+    backoffMs?: (attempt: number) => number;
+    /** Injectable delay, for deterministic tests (default `setTimeout`). */
+    sleep?: (ms: number) => Promise<void>;
+    /** Abort signal forwarded to fetch. */
+    signal?: AbortSignal;
 }
+/** The `/v1/probe` endpoint for a gateway origin (trailing slashes trimmed). */
+declare function buildProbeUrl(baseUrl: string): string;
+/**
+ * POST one probe body to `{baseUrl}/v1/probe` with a bearer key. Transient
+ * failures (network or `5xx`) are retried with bounded backoff; permanent ones
+ * (`400`/`403`/`501`) are not. Resolves with the terminal outcome and never
+ * rejects, so a fire-and-forget `void uploadProbeBatch(...)` is safe.
+ *
+ * @param body the string returned by `GuidanceSession.finishProbeJson()`.
+ */
+declare function uploadProbeBatch(baseUrl: string, apiKey: string, body: string, options?: UploadProbeOptions): Promise<ProbeUploadOutcome>;
 
 /** One place to show on the map - a store, depot, branch, POI. */
 interface Place {
@@ -639,9 +1243,14 @@ interface Place {
     /** 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`.
+     * Arbitrary extra data (opening hours, phone, …). Every key is copied
+     * verbatim onto the top level of the GeoJSON feature's `properties`,
+     * alongside the reserved `id`, `name` and `__mapmapIndex` keys (which win
+     * on collision) - so scalar values are directly addressable from a
+     * data-driven `color` expression, e.g. `["get", "category"]`. MapLibre
+     * JSON-stringifies nested objects/arrays at render time, so keep anything
+     * you want to style on as a top-level string/number/boolean. The whole
+     * object also comes back on the place handed to `onPlaceClick` / `popup`.
      */
     properties?: Record<string, unknown>;
 }
@@ -710,8 +1319,22 @@ interface PlacesLayerOptions {
     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;
+    /**
+     * Pin colour: a CSS colour string, or a MapLibre expression evaluated
+     * against each feature's `properties` for per-category pins, e.g.
+     * `["match", ["get", "category"], "food", "#e63946", "#3a86ff"]` (see
+     * {@link Place.properties} for what an expression can `get`). Defaults to
+     * MapMap signal blue (`#3a86ff`). Only styles the default circle pins -
+     * ignored with a custom `icon`. A cluster mixes categories, so an
+     * expression never applies to clusters: they use `clusterColor`.
+     */
+    color?: string | ExpressionSpecification;
+    /**
+     * Cluster circle colour. Defaults to `color` when that is a plain string,
+     * else to MapMap signal blue (a cluster mixes categories, so a
+     * data-driven `color` expression cannot apply to it).
+     */
+    clusterColor?: 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.
@@ -740,6 +1363,26 @@ interface PlacesLayerOptions {
      */
     popup?: (place: Place) => string | HTMLElement;
 }
+/** The generated MapLibre source/layer ids (see {@link PlacesLayer.ids}). */
+interface PlacesLayerIds {
+    /** The GeoJSON source id. */
+    source: string;
+    /** The unclustered-points layer id (circle, or symbol with `icon`). */
+    points: string;
+    /** The cluster circles layer id (only installed with `cluster: true`). */
+    clusters: string;
+    /** The cluster count badge layer id (only installed with `cluster: true`). */
+    clusterCounts: string;
+}
+/** Options for {@link PlacesLayer.select}. */
+interface PlacesSelectOptions {
+    /** Open the layer's configured `popup` at the place. Defaults to `true`. */
+    popup?: boolean;
+    /** Ease the camera to the place. Defaults to `true`. */
+    flyTo?: boolean;
+    /** Zoom for the camera move (with `flyTo`). Keeps the current zoom if omitted. */
+    zoom?: number;
+}
 /**
  * Normalise a GeoJSON FeatureCollection of Points to `Place[]`. The id comes
  * from `feature.id`, then `properties.id`, then the feature index; the name
@@ -768,6 +1411,7 @@ declare class PlacesLayer {
     private readonly clusterRadius;
     private readonly clusterMaxZoom;
     private readonly color;
+    private readonly clusterColor;
     private readonly icon;
     private readonly wantFitBounds;
     private readonly onPlaceClick;
@@ -785,13 +1429,37 @@ declare class PlacesLayer {
     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.
+     * of Points. Never silently drops an update: once the source exists the
+     * data is applied immediately, even while `isStyleLoaded()` is transiently
+     * `false` mid-render (search-as-you-type just works); calls made before
+     * the source has first been installed are stashed - the latest one wins -
+     * and 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 generated MapLibre source/layer ids - public API for escape-hatch
+     * styling (`map.setPaintProperty`, `queryRenderedFeatures`, …) beyond the
+     * layer's options. Stable for the layer's lifetime, derived from the `id`
+     * option (default `"mapmap-places"`). The cluster ids are only installed
+     * on the map with `cluster: true` (the default), and `points` is a circle
+     * layer by default or a symbol layer once a custom `icon` has loaded.
+     */
+    get ids(): PlacesLayerIds;
+    /**
+     * Programmatically select a place by id - list-to-map sync for a store
+     * finder's results list. Opens the layer's configured `popup` at the
+     * place (`popup: false` to skip, no-op without a `popup` option) and
+     * eases the camera to it (`flyTo: false` to skip; `zoom` to also zoom).
+     * Returns the selected place, or `undefined` for an unknown id (in which
+     * case nothing happens). Does NOT invoke `onPlaceClick` - a programmatic
+     * selection is not a user click.
+     */
+    select(id: string, options?: PlacesSelectOptions): Place | undefined;
+    /** Close the popup opened by {@link select} or a place click, if any. */
+    deselect(): void;
     /**
      * The nearest `n` places (default `1`) to `origin` by straight-line
      * (haversine) distance, each with `distanceM` attached. Pure and instant -
@@ -969,6 +1637,255 @@ declare class NavigationCamera {
     private scheduleRecentre;
     private clearRecentreTimer;
 }
+/**
+ * Initial great-circle bearing from `a` to `b`, degrees clockwise from
+ * north, normalised to `[0, 360)`.
+ */
+declare function bearingBetween(a: [number, number], b: [number, number]): number;
+/**
+ * The signed shortest-arc rotation from bearing `from` to bearing `to`,
+ * in `(-180, 180]` degrees - the slerp-style delta the flythrough eases
+ * along so the chase cam never spins the long way round.
+ */
+declare function shortestArcDelta(from: number, to: number): number;
+/** A camera pose along a flythrough: where to look from, and which way. */
+interface FlythroughPose {
+    /** Camera target on the route, `[lng, lat]`. */
+    center: [number, number];
+    /** Chase-cam bearing: towards a point `lookAheadM` up the road. */
+    bearing: number;
+}
+/**
+ * The camera pose at progress `t` (0-1) along a route: the interpolated
+ * point that fraction of the total distance along the line, with a
+ * chase-cam bearing towards the point `lookAheadM` further on. Pure -
+ * exported for tests and for apps that drive the camera themselves.
+ */
+declare function flythroughPose(coordinates: [number, number][], t: number, lookAheadM?: number): FlythroughPose;
+interface FlythroughOptions {
+    /**
+     * Camera tilt in degrees, clamped 0-85. Default `60` (the cinematic
+     * chase look; see {@link NavigationCameraOptions.pitch} for caveats
+     * above 60).
+     */
+    pitch?: number;
+    /** Camera zoom held through the replay. Default `16`. */
+    zoom?: number;
+    /**
+     * Total replay duration in milliseconds. Default `20000`. Ignored when
+     * `speedMps` is given.
+     */
+    durationMs?: number;
+    /**
+     * Replay ground speed in metres/second along the route - the duration
+     * becomes `routeLength / speedMps`. Wins over `durationMs`.
+     */
+    speedMps?: number;
+    /**
+     * How far up the road the chase cam looks to derive its bearing,
+     * metres. Default `200`; larger = calmer bearing on wiggly roads.
+     */
+    lookAheadM?: number;
+    /**
+     * Bearing smoothing rate per second (the fraction of the remaining
+     * shortest-arc turn closed each second). Default `3`; higher = snappier.
+     */
+    bearingEase?: number;
+}
+/** The handle a {@link flythrough} returns. */
+interface FlythroughController {
+    /** Start (or resume) the replay. Restarts from 0 when it had finished. */
+    play(): void;
+    /** Freeze the replay where it is. */
+    pause(): void;
+    /** Pause and rewind to the start (the camera jumps to the start pose). */
+    stop(): void;
+    /** Scrub to progress `t` (0-1, clamped) and apply the pose immediately. */
+    seek(t: number): void;
+    /** Playback-rate multiplier (`1` = real duration, `2` = double). */
+    speed: number;
+    /** Current progress, 0-1. */
+    readonly progress: number;
+    /** Whether the replay is currently advancing. */
+    readonly playing: boolean;
+    /** Subscribe to progress updates; returns the unsubscribe function. */
+    onProgress(listener: (t: number) => void): () => void;
+    /** Pause and detach everything. The controller is dead afterwards. */
+    destroy(): void;
+}
+/**
+ * Cinematic route replay: fly the camera along a route line with a
+ * chase-cam bearing (eased along the shortest arc, so junctions glide
+ * instead of spinning), at a configurable pitch/zoom/speed. Returns a
+ * transport-style controller; nothing moves until `play()` or `seek()`.
+ *
+ * ```ts
+ * const route = await routes.route(from, to);
+ * const replay = flythrough(map, route, { pitch: 60, durationMs: 15000 });
+ * replay.onProgress((t) => scrubber.value = String(t));
+ * replay.play();
+ * ```
+ *
+ * Drives the camera with `jumpTo` once per animation frame (the standard
+ * MapLibre scrub pattern). Runs under any projection; on globe the ride is
+ * unanchored but valid. Accepts a `ParsedRoute` (from `RouteLayer`) or a
+ * bare GeoJSON LineString geometry.
+ */
+declare function flythrough(map: MapMapMap | Map, route: RouteGeometry | ParsedRoute, options?: FlythroughOptions): FlythroughController;
+/**
+ * Scrollytelling: bind a flythrough to a scroll position, so scrolling a
+ * story column scrubs the camera along the route. The binder pauses the
+ * controller (scroll owns the timeline) and seeks it to the scrolled
+ * fraction - immediately on bind, then on every scroll. Returns the
+ * unbind function.
+ *
+ * ```ts
+ * const replay = flythrough(map, route);
+ * const unbind = bindFlythroughToScroll(replay, document.querySelector("#story")!);
+ * ```
+ */
+declare function bindFlythroughToScroll(controller: FlythroughController, target?: HTMLElement | Window): () => void;
+
+/**
+ * IsochroneLayer - walkability rings (reachability contours) on a MapMap
+ * map, backed by the gateway's live `POST /isochrone` endpoint (Valhalla
+ * isochrone; see docs/API.md).
+ *
+ * One call - `showReachability({ origin, mode: "walk", minutes: [5, 10, 15] })` -
+ * renders concentric reachability rings: graduated-opacity fills (nearest
+ * ring strongest), contour outlines, and "N min" labels along each
+ * contour. The estate-agent / store-catchment / "how walkable is this
+ * flat?" view in one line.
+ *
+ * Follows the RouteLayer pattern: gateway base URL/key picked up from a
+ * `MapMapMap` automatically, layers survive `setStyle` theme swaps via
+ * re-installation on `style.load`, and `clear()`/`destroy()` tidy up.
+ */
+
+/**
+ * Travel mode for the rings. The friendly names map onto gateway costings
+ * (`walk` → `pedestrian`, `cycle` → `bicycle`, `drive` → `auto`); any
+ * other string is passed through as a raw Valhalla costing (e.g.
+ * `"truck"`, `"motor_scooter"`).
+ */
+type ReachabilityMode = "walk" | "cycle" | "drive" | "truck" | (string & {});
+interface ShowReachabilityOptions {
+    /** Where the rings radiate from. */
+    origin: LngLatLike;
+    /** Travel mode. Defaults to `"walk"` - these are walkability rings. */
+    mode?: ReachabilityMode;
+    /** Ring contours in minutes, e.g. `[5, 10, 15]`. At least one. */
+    minutes: number[];
+    /** Ring colour. Defaults to MapMap signal blue. */
+    color?: string;
+    /**
+     * Valhalla-style costing options forwarded verbatim, e.g.
+     * `{ pedestrian: { use_lit: 1.0 } }`.
+     */
+    costingOptions?: Record<string, unknown>;
+}
+interface IsochroneLayerOptions {
+    /** 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-isochrone"`. */
+    id?: string;
+}
+/** The GeoJSON FeatureCollection the gateway returns, passed through. */
+interface IsochroneFeatureCollection {
+    type: "FeatureCollection";
+    features: {
+        type: "Feature";
+        geometry: {
+            type: string;
+            coordinates: unknown;
+        };
+        properties?: Record<string, unknown> | null;
+    }[];
+}
+/** Renders reachability rings from the gateway's `POST /isochrone`. */
+declare class IsochroneLayer {
+    private readonly map;
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly sourceId;
+    private readonly fillLayerId;
+    private readonly lineLayerId;
+    private readonly labelLayerId;
+    private lastData;
+    private lastMinutes;
+    private lastColor;
+    constructor(map: MapMapMap | Map, options?: IsochroneLayerOptions);
+    private readonly handleStyleLoad;
+    /**
+     * Fetch and render reachability rings. Returns the GeoJSON
+     * FeatureCollection the gateway produced (each feature carries a
+     * `contour` property in minutes), for callers who also want the raw
+     * shapes. Replaces any rings already shown by this layer.
+     */
+    showReachability(options: ShowReachabilityOptions): Promise<IsochroneFeatureCollection>;
+    /** The most recently drawn rings, if any. */
+    get current(): IsochroneFeatureCollection | undefined;
+    /** Draw (or update) a ring collection. Safe before the style has loaded. */
+    private draw;
+    /** Add-or-update the source and ring layers on the current style. */
+    private install;
+    /**
+     * Graduated fill opacity: the nearest contour (fewest minutes) is the
+     * most opaque, the farthest the faintest, interpolated on each
+     * feature's `contour` property. With one contour it is a constant.
+     */
+    private fillOpacity;
+    /** Remove the rings' layers and source from the map. */
+    clear(): void;
+    /** Remove the rings and detach the layer's `style.load` listener. */
+    destroy(): void;
+}
+
+/**
+ * Self-diagnosing map errors - the SDK tells you what went wrong and how
+ * to fix it, instead of a silently blank map.
+ *
+ * `MapMapMap` runs these checks at construction (and listens for tile
+ * auth failures); each detected issue produces ONE `console.error` per
+ * page with an actionable message and a docs link. Everything here is
+ * best-effort and defensive: no check may ever throw or require a DOM
+ * (server-side rendering and Node tests just skip the DOM checks).
+ *
+ * Issues covered - the documented gotchas that burn real integrations:
+ * - a container whose height resolves to 0px (MapLibre renders into a
+ *   0-tall canvas: no error, no map)
+ * - a container element that is not attached to the DOM
+ * - two maplibre-gl copies on one page (duplicate dependency /
+ *   micro-frontends - breaks the shared WebGL context and styles)
+ * - WebGL unavailable (headless browsers, blocked GPU, old devices)
+ * - missing/invalid API key (a 401 from the tile or routing endpoints)
+ */
+/** The distinct issues the diagnostics can report. */
+type DiagnosticIssue = "container-zero-height" | "container-detached" | "duplicate-maplibre" | "webgl-unavailable" | "invalid-api-key";
+/** Reset the once-per-page dedup - for tests (and hot-reload tooling). */
+declare function resetDiagnostics(): void;
+/** What `runMapDiagnostics` needs; everything optional and structural. */
+interface MapDiagnosticsInput {
+    /** The `container` option as given: an element or an element id. */
+    container?: string | HTMLElement;
+    /**
+     * The constructed map (or any object with a MapLibre-style `on`). Used
+     * to watch for tile-request auth failures.
+     */
+    map?: unknown;
+    /** The maplibre-gl module the SDK is using (duplicate detection). */
+    maplibre?: unknown;
+    /** The gateway API key, if one was configured. */
+    apiKey?: string | undefined;
+}
+/**
+ * Run the construction-time checks and attach the 401 watcher. Called by
+ * `MapMapMap` automatically; exported for apps wrapping a raw
+ * `maplibregl.Map` that still want the self-diagnosis.
+ */
+declare function runMapDiagnostics(input: MapDiagnosticsInput): void;
 
 /**
  * AdrCheck - optional helper for the gateway's `POST /adr/check` endpoint.
@@ -1177,4 +2094,121 @@ declare class GuidanceBanner {
     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 };
+/**
+ * Spoken turn-by-turn guidance over the browser's `SpeechSynthesis`.
+ *
+ * {@link VoiceGuidance} consumes the guidance updates emitted by the
+ * `@mapmap/core` wasm `GuidanceSession` (`{ state: "navigating" | "arrived"
+ * | "offRoute", spoken?, severity?, … }`). The core already schedules each
+ * spoken prompt by its trigger distance and repeats it on every update
+ * until it is superseded, so the speaking rule is simple: announce each
+ * `utteranceId` exactly once, the first time it appears.
+ *
+ * Severity (derived in the Rust core — see `InstructionSeverity`) maps to
+ * prosody and earcons:
+ *
+ * - `info` — normal manoeuvres: base rate/pitch, no earcon by default;
+ * - `warning` — approaching a restriction (toll, ferry): slight pitch
+ *   lift, warning earcon when configured;
+ * - `critical` — prohibitions (ADR tunnel block, gate): pitch and rate
+ *   lift, pending speech cancelled so the prompt is never queued behind
+ *   chatter, critical earcon when configured.
+ *
+ * Off-route updates carry no instruction; they play the warning earcon
+ * once per off-route episode (the app recalculates and speech resumes on
+ * the new session).
+ *
+ * Earcons are lazy URLs (see `map-assets/earcons/`, generated by
+ * `scripts/generate-earcons.py`) — nothing is bundled with the SDK.
+ * Everything no-ops safely where `speechSynthesis` is unavailable
+ * (non-browser contexts, some webviews).
+ */
+/** Instruction urgency, as emitted by the core (`InstructionSeverity`). */
+type GuidanceSeverity = "info" | "warning" | "critical";
+/** The spoken prompt of a core guidance update. */
+interface GuidanceSpokenPrompt {
+    /** Plain text for speech synthesis. */
+    text: string;
+    /** SSML form; browsers reject raw SSML, so it is stripped to text. */
+    ssml?: string | null;
+    /** Metres before the manoeuvre at which the core released the prompt. */
+    triggerDistanceM: number;
+    /** Unique utterance id — the de-duplication key. */
+    utteranceId: string;
+}
+/** The subset of a core guidance update that {@link VoiceGuidance} reads. */
+interface VoiceGuidanceUpdate {
+    /** Guidance state, as emitted by the wasm `GuidanceSession`. */
+    state: "navigating" | "arrived" | "offRoute";
+    /** Spoken prompt currently due (repeated until superseded). */
+    spoken?: GuidanceSpokenPrompt | null;
+    /** Urgency of the current step's instruction (default `info`). */
+    severity?: GuidanceSeverity;
+    /** BCP 47 locale of the instruction text, when the payload carries one. */
+    voiceLocale?: string;
+}
+/** Options for {@link VoiceGuidance}. */
+interface VoiceGuidanceOptions {
+    /** BCP 47 language for utterances, e.g. `en-GB`. An update's
+     * `voiceLocale` takes precedence when present. */
+    lang?: string;
+    /** Base speech rate (0.1–10, default 1). Critical prompts speak
+     * slightly faster than this base. */
+    rate?: number;
+    /** Volume for speech and earcons, 0–1 (default 1). */
+    volume?: number;
+    /** Start muted. */
+    muted?: boolean;
+    /** Severity → earcon audio URL. Absent entries play nothing. */
+    earcons?: Partial<Record<GuidanceSeverity, string>>;
+}
+/** Speech parameters for one severity level. */
+interface SeverityProsody {
+    /** Utterance rate. */
+    rate: number;
+    /** Utterance pitch (0–2, 1 = neutral). */
+    pitch: number;
+    /** Whether pending speech is cancelled before this prompt. */
+    interrupt: boolean;
+}
+/**
+ * Prosody for a severity level at a base rate. Pure — exported for tests
+ * and for custom voice layers that want the same house style.
+ */
+declare function severityProsody(severity: GuidanceSeverity, baseRate?: number): SeverityProsody;
+/**
+ * Speaks core guidance updates through the browser's `SpeechSynthesis`,
+ * with severity-aware prosody, optional earcons, and mute/volume
+ * controls. Feed every update from the wasm `GuidanceSession` to
+ * {@link VoiceGuidance.update}.
+ */
+declare class VoiceGuidance {
+    private readonly options;
+    private volume;
+    private mutedState;
+    private lastUtteranceId;
+    private offRouteAnnounced;
+    constructor(options?: VoiceGuidanceOptions);
+    /** Whether this environment can speak at all. */
+    get available(): boolean;
+    /** Whether announcements are currently muted. */
+    get muted(): boolean;
+    /** Mute announcements (also cancels anything mid-utterance). */
+    mute(): void;
+    /** Unmute announcements. Prompts seen while muted are not replayed. */
+    unmute(): void;
+    /** Set the volume for speech and earcons (clamped to 0–1). */
+    setVolume(volume: number): void;
+    /**
+     * Consume one guidance update. Speaks the update's prompt the first
+     * time its `utteranceId` appears; plays the warning earcon once per
+     * off-route episode. Safe to call in any environment.
+     */
+    update(update: VoiceGuidanceUpdate): void;
+    /** Cancel any speech in progress and forget the de-duplication state. */
+    dispose(): void;
+    private speak;
+    private playEarcon;
+}
+
+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, type DiagnosticIssue, EFFECTS_METADATA_KEY, 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, MAX_PUCK_IMAGE_BYTES, type MapDiagnosticsInput, 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, 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, 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 RibbonMesh, type RouteEffectLayer, type RouteEffectName, type RouteFlowOptions, type RouteGeometry, RouteLayer, type RouteLayerOptions, type RouteOptions, type RouteProfile, SIGNAL_BLUE, SOURCE_LAYERS, type SetRouteEffectOptions, type SeverityProsody, type ShowReachabilityOptions, type SpeakOptions, type StepGuidance, type SunTimes, type Theme, type ThemeEffects, ThemeScheduler, type ThemeSchedulerOptions, type TruckParams, type UploadProbeOptions, VoiceGuidance, type VoiceGuidanceOptions, type VoiceGuidanceUpdate, type VoiceInstruction, applyPoiDesign, bannerLanes, bearingBetween, bindFlythroughToScroll, buildAdrCheckBody, buildProbeUrl, buildRouteQuery, buildRouteUrl, buildStyle, builtInPoiColor, createMap, createRouteEffect, defaultNavDesign, defaultPoiDesign, directionArrow, effectsFromStyleMetadata, extractGuidance, flythrough, flythroughPose, formatCoord, formatCoords, haversineDistanceM, isNameTextField, languageTextField, lngLatToMercator, navDesignFromTheme, navDesignFromThemeUrl, parseCssColour, parseNavDesign, parseOsrmRoute, parsePoiDesign, placesFromGeoJSON, poiDesignFromTheme, poiDesignFromThemeUrl, poiDesignIsDefault, poiTextColorExpression, prefersReducedMotion, registerPmtilesProtocol, resetDiagnostics, resolveTheme, runMapDiagnostics, setMapLanguage, severityProsody, shortestArcDeg, shortestArcDelta, speak, ssmlToText, sunTimes, tessellateRouteRibbon, toLngLat, toPmtilesUrl, uploadProbeBatch };