@mapmap/maps reference

Generated from the published @mapmap/maps 0.25.1 type declarations by website/scripts/sdk-reference.mjs. Do not edit by hand: change the JSDoc in the package, or the examples in website/content/sdk-reference/maps.examples.md, and regenerate.

Every public export of the web maps SDK, from the main entry point and each subpath (/live, /models, /tiles, /avatars, /road-signs, /direction-icons, /asset-markers). For the task-by-task guide, read Web maps in SDKs & installation, Maps, tiles & Studio and Live layers.

npm install @mapmap/maps@0.25.1 maplibre-gl

Other SDK references: @mapmap/points, @mapmap/core, @mapmap/tile, @mapmap/react-native, @mapmap/voice, MapMapKit, ai.mapmap:core.

663 exports across 8 entry points: 32 classes, 240 functions, 173 interfaces, 84 types, 134 constants.

How to read this page

Each entry gives the declaration as published, the JSDoc description, and a table of parameters or properties with their types. The Default column quotes the default the source states (an @default tag or a "Default ..." sentence in the JSDoc). "required" means the property must be given; "not stated" means the source gives no default, so none is claimed here. Classes, factories and the main entry functions each carry a minimal example; examples marked from the source are the package's own @example.

Setup used by the examples

The examples below share one map, made once in src/map.ts, as a reader's own project would. Replace snk_… with your key.

// src/map.ts
import "maplibre-gl/dist/maplibre-gl.css";
import { createMap } from "@mapmap/maps";

export const map = createMap({ container: "map", apiKey: "snk_…", center: [-0.1276, 51.5072], zoom: 12 });

Contents

• @mapmap/maps: 441 exports
• @mapmap/maps/direction-icons: no exports of its own, 7 re-exported from an earlier entry point
• @mapmap/maps/avatars: 29 exports
• @mapmap/maps/road-signs: 42 exports
• @mapmap/maps/asset-markers: 53 exports, plus 26 re-exported from an earlier entry point
• @mapmap/maps/models: 31 exports
• @mapmap/maps/tiles: 2 exports
• @mapmap/maps/live: 65 exports

@mapmap/maps

import { /* … */ } from "@mapmap/maps";

Classes (@mapmap/maps)

AdrCheck, CameraAlertChip, ColourThemeLayer, CreditControl, DataLayer, FlowRouteEffectLayer, Geocoder, GuidanceBanner, InteractionRegistry, IsochroneError, IsochroneLayer, LogoControl, MapMapMap, MarkersLayer, NavigationCamera, PlacesLayer, PositionPuck, ProgramCache, RouteLayer, SearchBox, ThemeScheduler, TransitStopsLayer, TransitVehiclesLayer, VoiceGuidance

AdrCheck

Class

class AdrCheck { … }

Calls POST /adr/check and returns the parsed compliance decision.

Constructor and methods

• constructor(options: AdrCheckOptions)
• check(request: AdrCheckRequest): Promise<AdrCheckResult>

Example

import { AdrCheck } from "@mapmap/maps";

const adr = new AdrCheck({ baseUrl: "https://api.mapmap.ai", apiKey: "snk_…" });
const result = await adr.check({ hazmat: true, tunnelCode: "D/E", tunnelCategory: "C" });
console.log(result.status, result.reason);

CameraAlertChip

Class

class CameraAlertChip { … }

A minimal DOM safety-alert chip: kind icon, kind label and (when known) the limit and distance, in a calm or escalated state.

Style with the mapmap-alert-chip class, or pass a Studio design (extra.nav alerts block, e.g. map.navDesign?.alerts) to match a Studio theme. Framework-free and DOM-only, exactly like GuidanceBanner; head units should read alertChipContent instead.

The chip NEVER overlaps the speed or the limit: its position comes from a constrained slot enum, and aboveSpeed reserves its own clearance.

Constructor and methods

• constructor(container?: HTMLElement, design?: NavAlertsDesign)
• update(alert: CameraAlert | null, state?: { speeding?: boolean; }): void: Renders an alert (or hides the chip with null). state.speeding drives the escalated state; the chip itself shows regardless, because the visual alert is unconditional. A kind whose design turns alertWhileDriving off hides the chip: the customer chose not to surface that kind while driving.

Example

import { CameraAlertChip } from "@mapmap/maps";

const chip = new CameraAlertChip(document.getElementById("alerts") ?? undefined);
chip.update({ kind: "speed", limitKph: 50, distanceM: 300 }, { speeding: false });
// Hide it again:
chip.update(null);

ColourThemeLayer

Class

class ColourThemeLayer implements CustomLayerInterface { … }

A post-process custom layer that grades the composed frame through a LUT.

Implements CustomLayerInterface.

Constructor and methods

• constructor(options: ColourThemeLayerOptions)
• setLut(lut: LutBytes, strength?: number): void: Swap the LUT (and optionally the strength); the next frame uses it.
• setStrength(strength: number): void: Set the blend with the ungraded frame, 0..1.
• onAdd(map: Map, gl: WebGL2RenderingContext): void
• onRemove(_map: Map, gl: WebGL2RenderingContext): void
• render(glArg: CustomLayerGl, _args: unknown): void

Example

import { map } from "./map.ts";
import { ColourThemeLayer, IDENTITY_LUT } from "@mapmap/maps";

// A LUT that leaves colours unchanged; build your own with buildLut or lutFromPngData.
const grade = new ColourThemeLayer({ lut: IDENTITY_LUT, strength: 0.8 });
map.map.addLayer(grade);
grade.setStrength(0.5);

CreditControl

Class

class CreditControl<T extends CreditInnerControl = CreditInnerControl> { … }

A MapLibre IControl that renders MapLibre's attribution as the v2 map credit. attribution is the wrapped control, unchanged.

Constructor and methods

• constructor(attribution: T, options?: CreditOptions)
• getDefaultPosition(): ChromeCorner
• onAdd(map: unknown): HTMLElement
• onRemove(map?: unknown): void
• setTheme(theme: MapBrandTheme): void: Switch between the Day and Night credit (same size and shape; the colour pair follows the ground).

Example

import * as maplibregl from "maplibre-gl";
import { CreditControl } from "@mapmap/maps";

// For a plain maplibregl.Map: createMap already adds the credit for you.
const map = new maplibregl.Map({ container: "map", style: "https://example.com/style.json", attributionControl: false });
const credit = new CreditControl(new maplibregl.AttributionControl({ compact: false }), { theme: "day" });
map.addControl(credit);
credit.setTheme("night");

DataLayer

Class

class DataLayer { … }

A GeoJSON or PMTiles data layer on a MapMap map. See the module docs.

Constructor and methods

• constructor(map: MapMapMap, opts: DataLayerOptions)
• setData(data: GeoJSON.FeatureCollection | string): void: Replace the data (inline or a GeoJSON URL). Clears hover and selection.
• updateData(diff: GeoJSONSourceDiff): void: Apply a MapLibre GeoJSON diff (add, remove, update by id) without re-sending the whole dataset. Needs inline data with a unique id on every feature (or promoteId); the change survives a theme swap.
• setFilter(filter: FilterSpecification | null): void: Filter every layer of this DataLayer (null clears). Survives a theme swap.
• selected(): GeoJSON.Feature[]: The selected features.
• select(ids: (string | number)[]): void: Select features by id (feature id, or the promoteId value).
• clearSelection(): void: Clear the selection.
• on(event: DataLayerEventType, handler: (e: DataLayerEvent) => void): () => void: Listen for click, hover or select. Returns an unsubscribe function.
• remove(): void: Remove the source, its layers, the popup and every listener.

Example

import { map } from "./map.ts";
import { DataLayer } from "@mapmap/maps";

const sites = new DataLayer(map, {
  data: "https://example.com/sites.geojson",
  mode: "point",
  style: { categories: { property: "status", values: { open: "#1a7f37", closed: "#cf222e" } } },
});
const off = sites.on("click", (e) => console.log(e.feature?.properties));
// Later:
off();
sites.remove();

FlowRouteEffectLayer

Class

class FlowRouteEffectLayer implements CustomLayerInterface { … }

A MapLibre custom layer (CustomLayerInterface) drawing the flowing route ribbon. Construct via createRouteEffect (the registry) or use MapMapMap.setRouteEffect("flow"), which manages the lifecycle.

Implements CustomLayerInterface.

Constructor and methods

• constructor(geometry: RouteGeometry, options?: RouteFlowOptions)
• setGeometry(geometry: RouteGeometry): void: Swap the ribbon onto a new route line (e.g. after a reroute).
• onAdd(map: Map, gl: WebGL2RenderingContext): void
• onRemove(_map: Map, gl: WebGL2RenderingContext): void
• render(gl: CustomLayerGl, args: unknown): void

Example

import { map } from "./map.ts";
import { FlowRouteEffectLayer } from "@mapmap/maps";

const flow = new FlowRouteEffectLayer(
  { type: "LineString", coordinates: [[-0.1276, 51.5072], [-0.0877, 51.5055]] },
  { width: 8 },
);
map.map.addLayer(flow);
// After a reroute:
flow.setGeometry({ type: "LineString", coordinates: [[-0.1276, 51.5072], [-0.1, 51.52]] });

Geocoder

Class

class Geocoder { … }

Calls the gateway's geocoding endpoints and returns parsed hits.

Constructor and methods

• constructor(options: GeocoderOptions)
• geocode(query: string, options?: GeocodeOptions): Promise<GeocodeHit[]>: Forward geocode: free-text query → hits, best first.
• reverse(point: LngLatLike, options?: ReverseGeocodeOptions): Promise<GeocodeHit[]>: Reverse geocode: point → nearest hits, nearest first.

Example

import { map } from "./map.ts";
import { Geocoder } from "@mapmap/maps";

// A MapMapMap satisfies GeocoderOptions, so the map's gateway and key are reused.
const geocoder = new Geocoder(map);
const [best] = await geocoder.geocode("Temple Meads, Bristol");
if (best) map.map.flyTo({ center: best.lngLat, zoom: 15 });
const here = await geocoder.reverse([-2.5813, 51.4491]);
console.log(here[0]?.name, here[0]?.distanceM);

GuidanceBanner

Class

class GuidanceBanner { … }

A minimal DOM banner: primary text with a maneuver icon from the platform direction set (the same direction-icons glyphs the MapMap apps use, ferry, roundabouts, forks, ramps and all), plus an optional lane row. Style with the mapmap-banner / mapmap-banner-lanes / mapmap-banner-icon classes, pass a Studio design (extra.nav banner block, e.g. map.navDesign?.banner) to match a Studio theme, or read StepGuidance yourself for fully custom UI. The icon is drawn in the banner's text colour; its secondary shapes (class="mm2": the rest of a roundabout ring, other lanes) are that same colour at 35% opacity, never a fixed grey. Retune the opacity with .mapmap-banner-icon .mm2 { fill-opacity: …; stroke-opacity: … }.

Roundabouts draw for the side traffic drives on: clockwise for left-hand traffic (roundabout_lht_*), anticlockwise for right-hand traffic. The side comes from the route, never a default; when it is unknown the banner draws the plain turn glyph for the exit direction.

Constructor and methods

• constructor(container?: HTMLElement, design?: NavBannerDesign)
• update(banner: BannerInstruction | null, step?: Pick<StepGuidance, "mode" | "drivingSide" | "bannerIcon">): void: Renders a banner instruction (or hides the element with null). step is icon context: pass the StepGuidance entry the banner came from. Its bannerIcon is the glyph for the manoeuvre the banner describes (the next step's, with that step's own driving side and, at a roundabout, the paired through-angle exit), and a ferry-mode step draws the ferry glyph. Without bannerIcon (a hand-built { mode, drivingSide }), the glyph comes from the banner's own type and modifier with that drivingSide; with no side a roundabout draws the plain turn glyph for its direction.

Example

import { GuidanceBanner } from "@mapmap/maps";

const banner = new GuidanceBanner(document.getElementById("banner") ?? undefined);
banner.update({
  distanceAlongGeometry: 120,
  primary: { text: "Baldwin Street", type: "turn", modifier: "left" },
});

InteractionRegistry

Class

class InteractionRegistry { … }

The per-map interaction registry behind MapMapMap.addInteraction. Exported for apps that drive a plain maplibregl.Map.

Constructor and methods

• constructor(map: Map)
• add(id: string, interaction: Interaction): void: Add (or replace) the interaction id.
• remove(id: string): void: Remove the interaction id. Unknown ids are ignored.
• ids(): string[]: The registered interaction ids, in the order they were added.
• setFeatureState(target: InteractionTarget & { id: string | number; }, state: Record<string, unknown>): void: Set feature state on every source layer behind target: a featureset sets it once per distinct source and source layer (building and building-3d share one), so a paint expression reading ["feature-state", ...] on any of those layers sees it.
• destroy(): void: Detach every listener and forget every interaction.

Example

import * as maplibregl from "maplibre-gl";
import { InteractionRegistry } from "@mapmap/maps";

// For a plain maplibregl.Map; a MapMapMap has the same thing as map.addInteraction.
const map = new maplibregl.Map({ container: "map", style: "https://example.com/style.json" });
const interactions = new InteractionRegistry(map);
interactions.add("poi-click", {
  type: "click",
  target: { featuresetId: "poi" },
  handler: (e) => {
    console.log(e.feature?.properties);
    return true; // handled: stop here
  },
});

IsochroneError

Class

class IsochroneError extends Error { … }

A failed showReachability: the HTTP status and the gateway's RFC 9457 problem fields. The message keeps the long-standing form isochrone request failed: HTTP <status> (<title> - <detail>).

Extends Error.

Constructor and methods

• constructor(status: number, problem: Record<string, unknown> | undefined)

Example

import { map } from "./map.ts";
import { IsochroneError, IsochroneLayer } from "@mapmap/maps";

const reach = new IsochroneLayer(map);
try {
  await reach.showReachability({ origin: [-30, 45], minutes: [15] });
} catch (err) {
  if (err instanceof IsochroneError && err.noRoadsNearOrigin) {
    console.log("Move the origin onto land near a road", err.status);
  } else {
    throw err;
  }
}

IsochroneLayer

Class

class IsochroneLayer { … }

Renders reachability rings from the gateway's POST /isochrone.

Constructor and methods

• constructor(map: MapMapMap | Map, options?: IsochroneLayerOptions)
• showReachability(options: ShowReachabilityOptions): Promise<IsochroneFeatureCollection>: 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.
• clear(): void: Remove the rings' layers and source from the map.
• destroy(): void: Remove the rings and detach the layer's style.load listener and any pending wait for the style.

Example

import { map } from "./map.ts";
import { IsochroneLayer } from "@mapmap/maps";

const reach = new IsochroneLayer(map);
const rings = await reach.showReachability({ origin: [-0.1276, 51.5072], mode: "driving", minutes: [10, 20, 30] });
console.log(rings.features.length);

LogoControl

Class

class LogoControl { … }

A MapLibre IControl rendering the MapMap mark. Typed structurally (onAdd/onRemove) so it needs no maplibre-gl import and works with any instance the host app bundles.

Constructor and methods

• constructor(options?: LogoOptions)
• getDefaultPosition(): LogoPosition
• onAdd(): HTMLElement
• onRemove(): void
• setTheme(theme: MapBrandTheme): void: Switch between the Day and Night mark.

Example

import * as maplibregl from "maplibre-gl";
import { LogoControl } from "@mapmap/maps";

// createMap adds the mark itself; this is for a plain maplibregl.Map.
const map = new maplibregl.Map({ container: "map", style: "https://example.com/style.json" });
const logo = new LogoControl({ position: "bottom-left", theme: "day" });
map.addControl(logo);

MapMapMap

Class

class MapMapMap { … }

The MapMap map: a branded, tiles-and-routing-ready MapLibre map.

Constructor and methods

• constructor(options: MapMapOptions)

• setTerrain(terrain: boolean | TerrainOptions): void: Turn terrain on or off after construction. false removes the DEM sources and any hillshade layer this SDK added.

• setRouteEffect(effect: RouteEffectName | null, options?: SetRouteEffectOptions): void

  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.

  tsCopy

  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 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.

• setRouteEffectGeometry(geometry: RouteGeometry | null): 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 setRouteEffect for routes drawn outside a RouteLayer.

• setBuildings3d(enabled: boolean): void: 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).

• setStyle(style: MapMapTheme | Theme | StyleSpecification | string, options?: Parameters<Map["setStyle"]>[1]): void: Swap the map style: a theme name ("light" / "dark"), a Studio Theme document, a full StyleSpecification or a style URL, the same values the style option takes. Theme names and documents build against the same territory tiles the map was created with. Everything the SDK draws comes back on the new style: routes, places, markers, terrain, route effects, and every persistent source and layer (addPersistentLayer, DataLayer), in order, at its slot. navDesign and poiDesign stay as they were read at construction.

• slot(slot: Slot): string | undefined

  The beforeId for an insertion slot on the live style, or undefined to append on top. See SLOT_ANCHORS for what each slot means.

  tsCopy

  map.map.addLayer(myLayer, map.slot("bottom"));
  

  A layer added this way is gone after the next setStyle; use addPersistentLayer for one that stays.

• addPersistentSource(id: string, source: SourceSpecification): void: Add a source that survives setStyle. Calling it again with the same id replaces the registered source: a GeoJSON source swaps its data in place (setData); any other change needs removePersistent first, because MapLibre cannot change a source's type or URL under the layers drawing it.

• addPersistentLayer(layer: LayerSpecification, opts?: PersistentLayerOptions): void

  Add a layer that survives setStyle, at an insertion slot or below a layer id. Persistent layers are re-added on every style load in the order they were added, each at its slot resolved against the NEW style, so a theme swap keeps them in order and in place.

  tsCopy

  map.addPersistentSource("depots", { type: "geojson", data: depots });
  map.addPersistentLayer(
    { id: "depots", type: "circle", source: "depots", paint: { "circle-radius": 6 } },
    { slot: "middle" },
  );
  map.setStyle("dark"); // the depots stay, above the roads, below the labels
  

  The layer's source must be a persistent source or one every style you switch to carries (territory); a layer whose source is missing after a swap is skipped with one console warning.

• removePersistent(id: string): void: Remove a persistent source or layer, from the map and the registry. Removing a source also removes every persistent layer drawing it. Unknown ids are ignored.

• persistentIds(): PersistentIds: The persistent source and layer ids, in the order they were added.

• addInteraction(id: string, interaction: Interaction): void: Run interaction.handler on clicks or hovers over a layer, a basemap featureset (poi, place-labels, buildings) or the map itself. Shaped like Mapbox GL JS addInteraction; a handler returning true stops the event reaching interactions further down. Adding an id that exists replaces it. Interactions survive setStyle.

• removeInteraction(id: string): void: Remove the interaction id. Unknown ids are ignored.

• setFeatureState(target: InteractionTarget & { id: string | number; }, state: Record<string, unknown>): void: Set feature state on a layer's or featureset's features, for paint expressions that read ["feature-state", key]. Basemap features carry stable ids, so this works on poi and place-labels without promoteId. On buildings it is best effort: the tiles merge neighbouring footprints of the same height into one feature, so the state lands on that whole group.

• whenReady(): Promise<void>: Resolves once the style and first tiles are loaded. Safe to call at any point in the map's life, not just before its first load: map.loaded() goes false again whenever a source is loading (a theme swap, a pan into new tiles) while load only ever fires once, so this waits on idle too rather than hanging.

• destroy(): void: Remove the map and release its WebGL context. Anything still queued behind a style load is dropped first, so nothing touches the map after this returns.

• setColorTheme(theme: ColorThemeSpec | null): Promise<void>

  Grade the whole map through a colour theme (a 16x16x16 LUT), the Mapbox setColorTheme equivalent. null removes it.

  tsCopy

  await map.setColorTheme({ data: "https://example.com/night.png" }); // Mapbox-format 256x16 PNG
  await map.setColorTheme({ lut: bytes, strength: 0.6 });             // raw LUT bytes or base64
  map.setColorTheme(null);
  

  The theme is drawn by a custom layer ("mapmap-colour-theme") that the SDK keeps on top: it moves back above anything added later, and comes back after setStyle. Strength 0 removes the layer (no identity pass), while getColorTheme() still reports it. Resolves once the LUT is decoded; rejects with a readable message for a bad image, a LUT that is not 12288 bytes, or a strength outside 0..1. A later call wins over an earlier one still decoding.

  Over a style already graded at compile time (one carrying metadata["mapmap:color-theme"]) it still works, and logs one warning.

• getColorTheme(): { digest: string; strength: number; } | null: The runtime colour theme in force: its LUT digest (FNV-1a 64, 16 hex characters, the same digest compile-time grading stamps in metadata["mapmap:color-theme"]) and strength, or null with none.

• addClip(id: string, opts: ClipOptions): void

  Hide the basemap's buildings (or POI labels) inside a polygon, the Mapbox clip layer equivalent. Works on its own, with no model:

  tsCopy

  map.addClip("new-tower", { polygon: site });                       // buildings
  map.addClip("plaza", { polygon: plaza, types: ["buildings", "symbols"] });
  map.removeClip("new-tower");
  

  A feature that touches the polygon is not drawn (the style-spec distance filter, which MapLibre GL JS and Native both evaluate). Clips survive setStyle, apply to building-3d when setBuildings3d(true) adds it later, and two clips on one layer hide features inside either polygon. Calling it again with the same id replaces that clip. The polygon may have at most 500 vertices in total.

• removeClip(id: string): void: Remove a clip; each layer gets back its own filter (or the other clips').

• clips(): string[]: The ids of the clips in place, in the order they were added.

Example

import { MapMapMap } from "@mapmap/maps";

// createMap(options) is the usual way in; the constructor takes the same options.
const map = new MapMapMap({ container: "map", apiKey: "snk_…", center: [-1.8904, 52.4862], zoom: 12 });
await map.whenReady();
map.setStyle("dark");
map.setBuildings3d(true);
map.addPersistentSource("depots", {
  type: "geojson",
  data: { type: "FeatureCollection", features: [] },
});
map.addPersistentLayer({ id: "depots", type: "circle", source: "depots" }, { slot: "top" });

MarkersLayer

Class

class MarkersLayer { … }

Draws a theme's custom markers & labels on a MapLibre map.

const markers = await markersFromThemeUrl(themeUrl);
if (markers) new MarkersLayer(map, markers);

Registers every needed marker image (rasterised glyph pins are cached by mm-marker-<icon>-<colour>-<size>; custom images by data-URI hash), builds one GeoJSON feature per marker carrying its image key, label, precomputed icon-size ratio and anchor, and installs the single mm-user-markers source + symbol layer. Survives setStyle like PlacesLayer (re-installed on every style.load).

Constructor and methods

• constructor(map: MapMapMap | Map, markers?: MarkersBlock, options?: MarkersLayerOptions)
• setMarkers(markers: MarkersBlock | undefined): void: Replace the layer's markers with a parsed block (undefined or an empty block clears the map of markers but keeps the layer alive). Custom images load asynchronously: their markers render as default pins until the image arrives, then swap in place; a failed or oversized image keeps the pin fallback.
• clear(): void: Remove the markers' layer, source and registered images from the map. Images are removed by the keys this layer REGISTERED, not by whatever items happens to hold now, deriving them from the items meant setMarkers(undefined) followed by clear()/destroy() removed nothing at all.
• destroy(): void: Remove the markers and detach the style.load listener and any pending wait for the style. Call when disposing of the layer (the map is left untouched). Any image load still in flight resolves into a no-op.

Example

import { map } from "./map.ts";
import { MarkersLayer, parseMarkers } from "@mapmap/maps";

const block = parseMarkers({
  version: 1,
  items: [{ id: "hq", lng: -0.1276, lat: 51.5072, icon: "star", colour: "#0b5fff", size: "m", label: "HQ" }],
});
const markers = new MarkersLayer(map, block);
// Later:
markers.destroy();

NavigationCamera

Class

class NavigationCamera { … }

A follow-mode chase camera for MapMap maps.

Constructor and methods

• static isSupported(map: MapMapMap | Map): boolean: 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.
• constructor(map: MapMapMap | Map, options?: NavigationCameraOptions)
• attachPuck(puck: CoDrivenPuck): void: Co-drive a PositionPuck: every follow call also setLocations the puck, so camera and puck never diverge.
• follow(fix: CameraFix, courseDeg?: number): 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 resume.
• overview(routeGeometry?: RouteGeometry): 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.
• resume(): void: Return to follow mode, gliding back to the last fix (with its last known course) when one has been recorded.
• destroy(): void: Remove the map listeners and cancel any pending auto-recentre.

Example

import { map } from "./map.ts";
import { NavigationCamera, PositionPuck } from "@mapmap/maps";

if (NavigationCamera.isSupported(map)) {
  const camera = new NavigationCamera(map, { pitch: 55, zoom: 17 });
  camera.attachPuck(new PositionPuck(map));
  navigator.geolocation.watchPosition((p) => {
    camera.follow({ lat: p.coords.latitude, lon: p.coords.longitude }, p.coords.heading ?? undefined);
  });
}

PlacesLayer

Class

class PlacesLayer { … }

Draws customer places on a MapLibre map, with clustering and popups.

Constructor and methods

• constructor(map: MapMapMap | Map, options?: PlacesLayerOptions)
• setPlaces(places: PlacesInput): void: Replace the layer's places - a Place[] or a GeoJSON FeatureCollection 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). Before the source exists it is installed as soon as the style is parsed, even while tiles are still loading; calls made before that are stashed - the latest one wins - and installed the moment the style is ready, with no later setPlaces or style swap needed. With fitBounds: true the first non-empty set also fits the map view.
• select(id: string, options?: PlacesSelectOptions): Place | undefined: 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.
• deselect(): void: Close the popup opened by select or a place click, if any.
• nearest(origin: { lat: number; lon: number; }, n?: number): PlaceWithDistance[]: 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 nearestByDriveTime.
• nearestByDriveTime(origin: { lat: number; lon: number; }, options?: NearestByDriveTimeOptions): Promise<PlaceWithDriveTime[]>: 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. Answers always describe the places that were asked about: the list is snapshotted at call time, so a setPlaces landing mid-flight (a search-as-you-type filter, say) cannot mis-pair the matrix rows with a different set of places.
• clear(): void: Remove the places' layers, source, image and popup from the map.
• destroy(): void: Remove the places and detach every listener (style.load, clicks, hovers, and a pending wait for the style). Call when disposing of the layer (the map is left untouched).

Example

import { map } from "./map.ts";
import { PlacesLayer } from "@mapmap/maps";

const stores = new PlacesLayer(map, {
  places: [
    { id: "a", name: "Old Market", lat: 51.4556, lon: -2.5795 },
    { id: "b", name: "Clifton", lat: 51.4648, lon: -2.6203 },
  ],
  cluster: true,
  onPlaceClick: (place) => console.log(place.name),
});
const nearest = stores.nearest({ lat: 51.4545, lon: -2.5879 }, 1);
console.log(nearest[0]?.distanceM);

PositionPuck

Class

class PositionPuck { … }

A current-position puck marker for MapMap maps.

Constructor and methods

• constructor(map: MapMapMap | Map, design?: NavPuckDesign, options?: PositionPuckOptions): Creates the puck (not yet on the map - it appears on the first 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.
• setLocation(location: { lat: number; lon: number; }, headingDeg?: number): void: 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.
• remove(): void: Removes the puck from the map (cancelling any tween). setLocation re-adds it.

Example

import { map } from "./map.ts";
import { PositionPuck } from "@mapmap/maps";

const puck = new PositionPuck(map);
puck.setLocation({ lat: 51.5072, lon: -0.1276 }, 90);

ProgramCache

Class

class ProgramCache<T> { … }

One compiled program (or any per-variant object) per shaderData.variantName. The prelude differs by variant, so a program built for one projection must never draw another.

Constructor and methods

• get(variant: string, build: () => T): T
• delete(gl: WebGL2RenderingContext, dispose: (t: T) => void): void: Dispose of every entry and empty the cache (call from onRemove).

Example

import { ProgramCache } from "@mapmap/maps";

// One compiled program per projection variant, inside your own custom layer.
const programs = new ProgramCache<WebGLProgram>();
export function programFor(gl: WebGL2RenderingContext, variant: string): WebGLProgram {
  return programs.get(variant, () => {
    const program = gl.createProgram();
    // ...compile and link the shaders for this variant...
    return program;
  });
}
export function release(gl: WebGL2RenderingContext): void {
  programs.delete(gl, (p) => gl.deleteProgram(p)); // from onRemove
}

RouteLayer

Class

class RouteLayer { … }

Draws MapMap routes on a MapLibre map.

Constructor and methods

• constructor(map: MapMapMap | Map, options?: RouteLayerOptions)
• route(from: LngLatLike, to: LngLatLike, options?: RouteOptions): Promise<ParsedRoute>: Route from from to to (with optional intermediate via points passed through options is not supported here - pass a coordinate list to routePath for that), draw the line, and return the parsed route.
• routePath(points: LngLatLike[], options?: RouteOptions): Promise<ParsedRoute>: Route through an ordered list of coordinates and draw the result. Concurrent calls are ordered by ISSUE, not by arrival: only the newest request draws. A destination retyped while the first request is still in flight used to leave the map showing whichever response happened to land last, so a driver could be looking at the line to the address they had already replaced. Each caller still receives its own parsed route, so a caller that wants the data of a superseded request keeps getting it - only the drawing is suppressed. RouteLayer.clear likewise supersedes anything in flight.
• draw(route: ParsedRoute): void: Draw (or update) a parsed route's line on the map. Safe to call before the style has loaded: the route is drawn as soon as the style is parsed, even while tiles are still loading, and before that it is stored (the latest call wins) and installed the moment the style is ready, instead of throwing MapLibre's "Style is not done loading".
• setWaypoints(waypoints: readonly LngLatLike[]): void: Set the intermediate stops drawn by the endpoint markers, in order. routePath fills these in from its own via points, so this is only needed when drawing a route parsed elsewhere (e.g. a route fetched by the app and handed to draw). An empty array clears them.
• drawGeometry(coordinates: [number, number][]): void: Draw a bare line from coordinates, without a parsed OSRM route. RouteLayer.draw expects a ParsedRoute because it is normally fed by RouteLayer.route. Callers that already have geometry and nothing else, an agent tool result, a stored polyline, a hand-built preview, had to invent a ParsedRoute with zeroed distance and duration that draw never reads. This is that path, named honestly.
• drawAlternatives(routes: ParsedRoute[], selectedIndex?: number): void: Draw a set of routes: one selected, the rest as dimmer alternatives beneath it. Offering alternatives is table stakes for a navigation UI, and the selected route keeps every feature of RouteLayer.draw (progress, manoeuvre arrow, corridors, route effects). Pass the index of the route to select; out-of-range values clamp to the first route. Calling with a single route is equivalent to draw, and calling with an empty array clears everything.
• onSelectAlternative(handler: ((index: number) => void) | undefined): void: Register a click handler for the alternative lines. The index is the position within the array last passed to RouteLayer.drawAlternatives, so a caller can re-issue that call with the new selection. Passing undefined removes the handler.
• setFerrySegments(segments: [number, number][][]): void: Draw ferry legs of the selected route as dashes over its line, so water crossings do not read as driving. Supplied as explicit geometries rather than derived from the route, because line-dasharray cannot be data-driven: a ferry leg needs its own layer, and only the caller knows which parts of their route are ferries.
• clearFerrySegments(): void: Remove the ferry dashes.
• setLineStyle(style: RouteLineStyle): void: Override the drawn line's paint at runtime, over whatever the design or the built-in look set. Route styling is not always static: a route can be provisional, or a straight-line approximation that must not be mistaken for a surveyed one. That is a paint change on a route already drawn, so it belongs here rather than in the constructor's design. Overrides survive style reloads. Pass {} to clear them.
• setProgress(fraction: number): void: 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 draw calls and style swaps. Pair with the guidance module's distance-remaining to derive the fraction.
• setManeuver(lngLat: [number, number], bearingDeg: number): void: Shows (or moves) the upcoming-manoeuvre arrow: a small map-aligned arrow at lngLat rotated to bearingDeg (clockwise from north). Survives style swaps until clearManeuver.
• clearManeuver(): void: Hides the manoeuvre arrow.
• setAlertCorridors(corridors: readonly (readonly [number, number])[][], design?: NavAlertsDesign): void: Highlights average-speed enforcement corridors on the route line. A corridor is a stretch of the route between an entry and an exit camera, so it is a property of the LINE, not a point alert: drawing it as a tinted overlay above the route is what makes "you are inside a section check right now" readable at a glance, and it is the only part of the alert design that persists rather than firing once. Pass the corridor geometries (arrays of [lng, lat] along the route) and, optionally, a Studio alerts design for the colour and opacity; without one the layer uses the design carried by the owning map, then a built-in tint. An empty array clears the highlight. Survives style swaps like the route itself.
• clearAlertCorridors(): void: Removes the corridor highlight (the route line itself is untouched).
• clear(): void: Remove the route's layers and source from the map. Any route request still in flight is superseded, so a late response cannot redraw a route the caller has already cleared.
• destroy(): void: Remove the route and detach the layer's style.load listener and any pending wait for the style. Call when disposing of the layer (the map itself is left untouched).

Example

import { map } from "./map.ts";
import { RouteLayer } from "@mapmap/maps";

const routes = new RouteLayer(map);
const route = await routes.route([-0.1276, 51.5072], [-1.2577, 51.752], {
  profile: "truck",
  truck: { heightM: 4.2, weightT: 26 },
});
console.log(`${(route.distanceM / 1000).toFixed(1)} km, ${Math.round(route.durationS / 60)} min`);

SearchBox

Class

class SearchBox { … }

A MapLibre IControl search bar: debounced suggestions, keyboard navigation, and a typed "select" event carrying the picked feature.

const box = new SearchBox({ apiKey: "snk_…" });
box.on("select", ({ suggestion, hit }) => {
  console.log(suggestion.name, hit?.postcode);
});
map.map.addControl(box, "top-left");

Constructor and methods

• constructor(options?: SearchBoxOptions)
• on(event: "select", listener: SearchBoxSelectListener): () => void: Subscribe to the "select" event. Returns an unsubscribe function.
• off(event: "select", listener: SearchBoxSelectListener): void: Unsubscribe a "select" listener.
• onAdd(map?: SearchBoxMap): HTMLElement: The IControl hook: build the DOM and take the map handle.
• onRemove(): void: The IControl hook: tear everything down.

Example

import type { IControl } from "maplibre-gl";
import { map } from "./map.ts";
import { SearchBox } from "@mapmap/maps";

const search = new SearchBox({ apiKey: "snk_…", placeholder: "Search places" });
// Up to 0.25.1, SearchBox's type does not match maplibre-gl 6's IControl
// (isStyleLoaded may return void there), so strict TypeScript needs this cast.
// Fixed at source for the next release, after which addControl(search) compiles as is.
map.map.addControl(search as unknown as IControl, "top-left");
search.on("select", (e) => console.log(e.suggestion.name, e.hit?.postcode));

ThemeScheduler

Class

class ThemeScheduler { … }

Applies the sun-appropriate theme now and at every subsequent sunrise/sunset until dispose. Pair with the OS dark-mode signal in the app if the user's system preference should win instead.

Constructor and methods

• constructor(options: ThemeSchedulerOptions)
• setPosition(lat: number, lng: number): void: Moves the observer (e.g. a new GPS fix region) and re-evaluates.
• dispose(): void: Stops all future flips.

Example

import { map } from "./map.ts";
import { ThemeScheduler } from "@mapmap/maps";

// Light map by day, dark after sunset, at the map's location.
const scheduler = new ThemeScheduler({
  lat: 51.5072,
  lng: -0.1276,
  onLight: () => map.setStyle("light"),
  onDark: () => map.setStyle("dark"),
});
// Later:
scheduler.dispose();

TransitStopsLayer

Class

class TransitStopsLayer { … }

Bus stops and bus lines from the MapMap tiles host (see module docs).

Constructor and methods

• constructor(map: MapMapMap, options?: TransitStopsLayerOptions)
• remove(): void: Remove the sources, layers and handlers.

Example

import { map } from "./map.ts";
import { TransitStopsLayer } from "@mapmap/maps";

const stops = new TransitStopsLayer(map, {
  onStopClick: (stop) => console.log(stop.id, stop.name, stop.lines),
});
// Later:
stops.remove();

TransitVehiclesLayer

Class

class TransitVehiclesLayer { … }

Live bus positions from GET /v1/transit/vehicles, drawn smoothly.

Constructor and methods

• constructor(map: MapMapMap, options?: TransitVehiclesLayerOptions)
• start(): void: Start polling and drawing. Safe to call before the style has loaded: the layer installs as soon as the style is parsed, even while tiles are still loading, and before that waits once for it (StyleWait).
• stop(): void: Stop polling and drawing. The vehicles last drawn stay on the map.
• remove(): void: Stop, and remove the layer's layers, source, image and popup.
• vehicles(): TransitVehicle[]: The vehicles as last drawn (interpolated positions).
• feedStatus(): TransitFeedReport: The feed's freshness after the latest poll (the last TransitFeedReport).
• lastAnswer(): TransitFeedAnswer | null: The last successful answer's counts, or null before the first answer.
• setFollowed(id: string | null): void: Follow one vehicle by id, or null to stop. Its feature carries followed: true; with marker: "bus" it wears a ring (2 px white, 2 px ink) and the others draw at 55 %. The camera is yours to move.
• followed(): string | null: The id passed to setFollowed, or null.
• onDraw(listener: (vehicles: readonly TransitDrawnVehicle[]) => void): () => void: Call listener with the vehicles as drawn after every draw (at most 10 a second while vehicles move) and when the followed vehicle changes. Returns the unsubscribe function. The 3D buses (TransitVehicles3dLayer, @mapmap/maps/models) are fed this way.
• setSpriteOpacity(factor: number): void: Fade the top-down sprite and its followed ring (marker: "bus"), or the heading arrow (the default), by factor (0 to 1, on top of every other dim), so a companion layer can crossfade with it. Labels, pucks and dots are untouched. Default 1.

Example

import { map } from "./map.ts";
import { TransitVehiclesLayer } from "@mapmap/maps";

const buses = new TransitVehiclesLayer(map, {
  bbox: "viewport",
  onFeedStatus: (report) => console.log(report.status),
});
buses.start();

VoiceGuidance

Class

class VoiceGuidance { … }

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 VoiceGuidance.update.

Constructor and methods

• constructor(options?: VoiceGuidanceOptions)
• mute(): void: Mute announcements (also cancels anything mid-utterance).
• unmute(): void: Unmute announcements. Prompts seen while muted are not replayed.
• setVolume(volume: number): void: Set the volume for speech and earcons (clamped to 0–1).
• update(update: VoiceGuidanceUpdate): 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.
• dispose(): void: Cancel any speech in progress and forget the de-duplication state.

Example

import { VoiceGuidance } from "@mapmap/maps";

const voice = new VoiceGuidance({ lang: "en-GB", volume: 0.9 });
voice.update({
  state: "navigating",
  spoken: { text: "In 300 metres, turn left", triggerDistanceM: 300, utteranceId: "step-4" },
});
voice.mute();

Functions (@mapmap/maps)

addBusMarkerImages, alertChipContent, alertContrastIssues, alertIconSvg, alertIconUrl, alertPresentation, alertSoundUrl, alertSpeedReadoutColor, applyColourTheme, applyGeoJSONDiff, applyPoiDesign, applyTerrain, bannerLanes, baseTheme, bearingBetween, bindFlythroughToScroll, buildAdrCheckBody, buildGeocodeUrl, buildLut, buildProbeUrl, buildRetrieveUrl, buildReverseGeocodeUrl, buildRouteQuery, buildRouteUrl, buildStyle, buildSuggestUrl, buildVertexSource, builtInPoiColor, busMarkerLayers, busPuckImage, busPuckImageOptions, busSilhouetteSdf, busSpriteBody, busTickImage, busVehicleType, cameraKindLabel, cameraKindsShownOnMap, cameraShownOnMap, cameraSpriteName, cameraSymbolLayer, capTransitBbox, checkSourceUrl, clipFilter, colourThemeMetadata, contrastRatio, createMap, createRouteEffect, creditTier, dataLayerColor, defaultNavAlertsDesign, defaultNavDesign, defaultPoiDesign, directionArrow, directionIconSvg, effectsFromStyleMetadata, extractGuidance, featuresetLayerIds, fixSetFromCollection, flythrough, flythroughPose, formatCoord, formatCoords, globeModelMatrix, gradeColourString, gradeStyleColours, hasBakedMarkers, haversineDistanceM, holdLayersOnTop, iconNameForManeuver, iconNameForStep, iconNamesForSteps, interpolateFixes, isMarkerGlyphId, isNameTextField, isSlot, keyedStyleUrl, keyedTilesUrl, laneArrowDirection, languageTextField, layersOnTopMoves, liveTargetLayerIds, lngLatToMercator, locateProjectionUniforms, lutApply, lutDigest, lutFromBase64, lutFromImageData, lutFromPngData, lutToBase64, lutToImageData, mapBrandSvg, mapGroundTheme, markerImage, markerImageDataKey, markerImageKey, markersFromTheme, markersFromThemeUrl, markerText, markerTextImageKey, mercatorModelMatrix, modelClipMatrices, multiplyMat4, namedBase, navAlertLeadDistanceM, navAlertSoundUrl, navCameraKind, navDesignFromTheme, navDesignFromThemeUrl, osmAndMoreCredit, parseCssColour, parseGeocodeResponse, parseHexColor, parseMarkers, parseNavAlertsDesign, parseNavDesign, parseOsrmRoute, parsePoiDesign, parseSuggestResponse, placesFromGeoJSON, poiDesignFromTheme, poiDesignFromThemeUrl, poiDesignIsDefault, poiTextColorExpression, prefersReducedMotion, projectionVariant, readProjection, registerPmtilesProtocol, relativeLuminance, removeTerrain, renderClockMs, renderMarkerImage, resetDiagnostics, resolveBaseId, resolveSlot, resolveTerrain, resolveTheme, runMapDiagnostics, setMapLanguage, setProjectionUniforms, severityProsody, shortCredit, shortestArcDeg, shortestArcDelta, speak, sphereFrame, sphereSurface, ssmlToText, styleFromBase, styleGroundTheme, subdivideMercator, sunTimes, supportsTerrainDraping, territoryTilesSourceUrl, tessellateRouteRibbon, tidyPlaceName, toLngLat, toPmtilesUrl, transitArchiveUrl, transitFreshnessLabel, transitStopFromProperties, transitTileJsonUrl, transitUrlsFromIndex, truncateChars, uploadProbeBatch, validateColourTheme, validateUseTheme

addBusMarkerImages

Function

function addBusMarkerImages(map: Pick<Map, "hasImage" | "addImage">): void;

Add the bus marker's images to the style, skipping any already there.

alertChipContent

Function

function alertChipContent(design: NavAlertsDesign, alert: CameraAlert): AlertChipContent;

The text/icon content of an alert chip, free of any styling tokens.

Options and types: NavAlertsDesign, CameraAlert.

alertContrastIssues

Function

function alertContrastIssues(design: NavAlertsDesign): AlertContrastIssue[];

Every chip colour pair in design that fails the contrast floor, in state order. An empty array means both states are legible (or, for colours this module cannot parse, not judgeable - those are skipped rather than reported as failures).

Advisory by design: the parser stays lenient and never rejects a theme on contrast. Studio surfaces these as warnings next to the pickers so a designer sees the problem while choosing, which is the only moment the warning can actually change the outcome.

Options and types: NavAlertsDesign.

alertIconSvg

Function

function alertIconSvg(design: NavAlertsDesign, kind: NavCameraKind | string): string;

The icon for a kind under a design, as a complete inline SVG string.

iconSet chooses the frame (a European circular plate, a US rounded plate, or no frame); the glyph inside always encodes the KIND, because that is the channel kind is allowed to travel on. "brand" draws the unframed glyph as its fallback - it expects an iconUrlOverrides entry, and alertIconUrl is what actually resolves one.

Options and types: NavAlertsDesign, NavCameraKind.

alertIconUrl

Function

function alertIconUrl(design: NavAlertsDesign, kind: NavCameraKind | string): string | undefined;

The override URL for a kind, if the design sets one. Overrides win over iconSet for that kind only; every other kind keeps the curated icon.

Options and types: NavAlertsDesign, NavCameraKind.

alertPresentation

Function

function alertPresentation(design: NavAlertsDesign, alert: CameraAlert, state?: {
    speeding?: boolean;
}): AlertPresentation;

Resolves a design plus live state into what to present.

Escalation is by INTENSITY, not identity: escalated restyles the same chip and re-uses the same earcon motif more insistently. It never swaps in a different icon or a different sound - kind is carried by the icon and by speech, urgency by timbre, and mixing the two channels is how drivers end up unable to tell "a camera" from "you are speeding".

Options and types: NavAlertsDesign, CameraAlert.

alertSoundUrl

Function

function alertSoundUrl(design: NavAlertsDesign, escalated: boolean): string;

The earcon URL for a design in the calm or escalated state.

A design-level alertSoundUrl / escalatedSoundUrl override wins; otherwise the chosen built-in resolves against the hosted earcon library. There is deliberately no per-kind sound: kind travels in the icon and in speech, urgency travels in timbre.

Options and types: NavAlertsDesign.

alertSpeedReadoutColor

Function

function alertSpeedReadoutColor(design: NavAlertsDesign, escalated: boolean): string | undefined;

The colour a host should paint the SPEED readout, given a design and whether the driver is speeding.

Deliberate division of labour: the escalation the driver reads is the speed number turning the escalated colour, while the alert chip stays legible in its own escalated tokens. Colouring the card and leaving the speed untouched puts the urgency on the wrong element - the driver has to act on the speed, so the speed is what changes. Returns undefined when calm, meaning "leave the readout in its normal colour".

Options and types: NavAlertsDesign.

applyColourTheme

Function

function applyColourTheme(style: StyleSpecification, theme: {
    color_theme?: ColourTheme;
    layers?: Record<string, {
        use_theme?: unknown;
    }>;
}): StyleSpecification;

The compilers' last step: grade style through theme.color_theme, skipping the layers whose override says use_theme: "none", and stamp metadata["mapmap:color-theme"] as the third metadata key (after effects and territories). A theme without color_theme returns style untouched, so its bytes do not move. LOCKSTEP with the end of sn_style::compile.

Options and types: ColourTheme.

applyGeoJSONDiff

Function

function applyGeoJSONDiff(data: GeoJSON.FeatureCollection, diff: GeoJSONSourceDiff, promoteId?: string): GeoJSON.FeatureCollection;

Apply a MapLibre GeoJSON diff to a local FeatureCollection.

applyPoiDesign

Function

function applyPoiDesign(map: PoiPaintMap, design: PoiDesign, fallbackTextColor?: string): void;

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).

Options and types: PoiDesign.

applyTerrain

Function

function applyTerrain(map: Map, cfg: ResolvedTerrain): void;

Add the sources/layers and switch terrain on. Safe to call repeatedly.

bannerLanes

Function

function bannerLanes(banner: BannerInstruction): LaneIndication[];

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.

Options and types: BannerInstruction.

baseTheme

Function

function baseTheme(id: string): Theme | undefined;

A fresh theme document for a named base, or undefined for an id the catalogue never had. Every call returns its own object, so editing one is safe.

bearingBetween

Function

function bearingBetween(a: [number, number], b: [number, number]): number;

Initial great-circle bearing from a to b, degrees clockwise from north, normalised to [0, 360).

bindFlythroughToScroll

Function

function bindFlythroughToScroll(controller: FlythroughController, target?: HTMLElement | Window): () => void;

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.

const replay = flythrough(map, route);
const unbind = bindFlythroughToScroll(replay, document.querySelector("#story")!);

Options and types: FlythroughController.

buildAdrCheckBody

Function

function buildAdrCheckBody(request: AdrCheckRequest): Record<string, unknown>;

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.

Options and types: AdrCheckRequest.

buildGeocodeUrl

Function

function buildGeocodeUrl(baseUrl: string, query: string, options?: GeocodeOptions): string;

Build the full forward-geocode URL. baseUrl is the gateway origin (trailing slashes are trimmed). Note the API key is NOT embedded - fetches of this URL need the Authorization: Bearer snk_… header, exactly like buildRouteUrl.

Options and types: GeocodeOptions.

buildLut

Function

function buildLut(fn: (r: number, g: number, b: number) => [number, number, number]): LutBytes;

Build a LUT by evaluating fn at every lattice point. fn gets the lattice indices (0..15) and returns 0..255 channel values, which are rounded and clamped.

buildProbeUrl

Function

function buildProbeUrl(baseUrl: string): string;

The /v1/probe endpoint for a gateway origin (trailing slashes trimmed).

buildRetrieveUrl

Function

function buildRetrieveUrl(gatewayUrl: string, id: string): string;

Build the GET /geocode/retrieve URL for one document id.

buildReverseGeocodeUrl

Function

function buildReverseGeocodeUrl(baseUrl: string, point: LngLatLike, options?: ReverseGeocodeOptions): string;

Build the full reverse-geocode URL. Same auth caveat as forward.

Options and types: LngLatLike, ReverseGeocodeOptions.

buildRouteQuery

Function

function buildRouteQuery(truck?: TruckParams, guidance?: GuidanceQuery): string;

Build the OSRM query string (without the leading ?) for a request.

Options and types: TruckParams.

buildRouteUrl

Function

function buildRouteUrl(baseUrl: string, profile: RouteProfile, points: LngLatLike[], 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.

Options and types: RouteProfile, LngLatLike, TruckParams.

buildStyle

Function

function buildStyle(options?: BuildStyleOptions): StyleSpecification;

Options and types: BuildStyleOptions.

buildSuggestUrl

Function

function buildSuggestUrl(gatewayUrl: string, query: string, options?: SuggestUrlOptions): string;

Build the GET /geocode/suggest URL. The API key is NOT embedded, fetches need the Authorization: Bearer snk_… header, exactly like buildGeocodeUrl.

Options and types: SuggestUrlOptions.

buildVertexSource

Function

function buildVertexSource(args: ProjectionArgs, body: string): string;

A GLSL ES 3.00 vertex shader around MapLibre's projection prelude. body uses in/out and calls projectTile(vec2) (mercator 0..1, ground) or projectTileFor3D(vec2, float elevationMetres).

Options and types: ProjectionArgs.

builtInPoiColor

Function

function builtInPoiColor(categoryId: string): string | undefined;

The built-in dot colour for a category id.

busMarkerLayers

Function

function busMarkerLayers(prefix: string, source: string, opacity: {
    feed: number;
    othersDimmed: boolean;
}): LayerSpecification[];

The bus marker's layer specs, bottom to top: the dot (z8 to 12), the heading tick and the line-number puck (z12 to 15.5), the followed ring, the sprite and its label (z15.5 and in). feed is the feed-level opacity, othersDimmed whether a vehicle is followed.

busPuckImage

Function

function busPuckImage(size?: number, options?: {
    followed?: boolean;
}): Rgba8;

The line-number puck as raw RGBA: an ink (#0f1115) disc of radius 9 with a 1.5 px white halo, centred on a 24 px square drawn at size pixels (default 48, pixel ratio 2). With followed, the ring the followed vehicle wears instead: 2 px white then 2 px ink, on a 28 px square (default 56). The layer stretches its middle column to fit the line number (busPuckImageOptions).

busPuckImageOptions

Function

function busPuckImageOptions(size?: number, options?: {
    followed?: boolean;
}): Partial<StyleImageMetadata>;

addImage options for a busPuckImage: its pixel ratio, a one-px stretchable middle column, and the content box icon-text-fit fits the line number into (for the followed puck, inset by the extra 2 px of ring so both pills are the same width around the same text).

busSilhouetteSdf

Function

function busSilhouetteSdf(heightPx?: number, radius?: number, type?: BusVehicleType): Sdf;

A top-down bus of body type, nose north, as a MapLibre SDF image (addImage(id, img, { sdf: true })): white, with the signed distance to the outline in alpha by the TinySDF convention (edge at alpha 191.25, so 192 rounds inside; radius px of distance per 255 * 1 alpha; MapLibre reads halo widths in true pixels when radius is 8). Drawn from the modelled bus's top view: the body outline, with the windscreen (a block behind the nose, the heading cue), the roof hatches and (single-decker) the roof pod's front edge cut out, so the halo colour shows through them as roof detail. At the default size the canvas is 48 px wide and the double-decker's 96 px tall (body 72 x 22 px); heightPx scales the double-decker's height and every other type by the same factor.

Options and types: BusVehicleType.

busSpriteBody

Function

function busSpriteBody(type?: BusVehicleType): {
    length: number;
    width: number;
};

A body type's outline length and width on the reference canvas, px.

Options and types: BusVehicleType.

busTickImage

Function

function busTickImage(pixelRatio?: number): Rgba8;

The heading tick as raw RGBA: an ink triangle 8 px wide and 6 px tall, pointing north, with a 1 px white edge, centred on a 12 x 10 px canvas drawn at pixelRatio (default 2). The layer orbits it round the puck with icon-offset, which MapLibre turns with icon-rotate, so one image serves every bearing.

busVehicleType

Function

function busVehicleType(properties: Record<string, unknown> | null | undefined): BusVehicleType | null;

The body type a feed feature's properties name, or null when they name none: vehicle_type ("double", "single", "mini" or "generic") first, then deck ("double" or "single"). Anything else is unknown.

cameraKindLabel

Function

function cameraKindLabel(kind: NavCameraKind | string): string;

Human-readable name for a camera kind, used in the chip's text and in the spoken announcement. Kind lives here and in the icon, never in the earcon.

Options and types: NavCameraKind.

cameraKindsShownOnMap

Function

function cameraKindsShownOnMap(design: NavAlertsDesign, mode?: MapDisplayMode): NavCameraKind[];

The camera kinds a style should draw in the given mode, in the canonical kind order. Feed it straight into a MapLibre filter (see cameraSymbolLayer); an empty array means "draw nothing", which a caller must honour by removing or hiding the layer.

Options and types: NavAlertsDesign, MapDisplayMode.

cameraShownOnMap

Function

function cameraShownOnMap(design: NavAlertsDesign, kind: NavCameraKind | string, mode?: MapDisplayMode): boolean;

Whether a kind's pin should be drawn on the map in the given mode.

Browsing and navigating are separate switches because they are separate decisions - the market warns with or without a planned route, so a design that shows a camera on the planning map is not thereby committed to a cluttered driving map, nor the reverse.

Options and types: NavAlertsDesign, NavCameraKind, MapDisplayMode.

cameraSpriteName

Function

function cameraSpriteName(kind: NavCameraKind | string, variant?: "light" | "dark"): string;

Sprite image id for a camera kind, as built into the published sprite sheet by map-assets/icons/cameras/generate.mjs.

LOCKSTEP: the file names in map-assets/sprites/svg/camera-*.svg are exactly these ids, spreet names each image after its file.

Options and types: NavCameraKind.

cameraSymbolLayer

Function

function cameraSymbolLayer(design: NavAlertsDesign, source: string, mode?: MapDisplayMode, variant?: "light" | "dark", id?: string): Record<string, unknown>;

A MapLibre symbol layer that draws camera POIs from the sprite sheet.

Additive by design: the style compiler is untouched and ships no camera layer of its own, because cameras arrive as host data (the gateway's POST /v1/cameras/along, projected into a GeoJSON source) rather than in the vector tiles. Point this at that source and the sprite icons built from map-assets/icons/cameras render at the design's size, zoom floor and per-mode visibility.

The features must carry a kind property holding one of NAV_CAMERA_KINDS or any wire spelling navCameraKind accepts (the gateway's redlight, OSM's traffic_signals, …); an unrecognised or absent value falls back to the unknown icon, never to a guess at a specific camera type.

Options and types: NavAlertsDesign, MapDisplayMode.

capTransitBbox

Function

function capTransitBbox(bbox: [number, number, number, number], maxSqDeg?: number): [number, number, number, number];

A [west, south, east, north] box shrunk around its centre to at most maxSqDeg square degrees (the gateway refuses larger ones).

checkSourceUrl

Function

function checkSourceUrl(url: string, allowPmtiles: boolean): string | undefined;

The URL rules for a customer source: https:// (or, with allowPmtiles, pmtiles://https://), no user name or password, no literal IP address, no localhost, no spaces, at most MAX_SOURCE_URL_CHARS. Returns the reason, or undefined when the URL passes. Mirrors sn_style::check_source_url.

clipFilter

Function

function clipFilter(polygon: Polygon | MultiPolygon, original: FilterSpecification | null | undefined, minzoom?: number): FilterSpecification;

A layer filter that keeps original and hides every feature touching polygon: ["all", original, [">", ["distance", polygon], 0]] (just the distance test when there is no original filter). With minzoom, the distance test only applies from that zoom up.

colourThemeMetadata

Function

function colourThemeMetadata(theme: ColourTheme, lut: LutBytes): Record<string, unknown>;

metadata["mapmap:color-theme"]: name, size, strength and the LUT digest.

Options and types: ColourTheme, LutBytes.

contrastRatio

Function

function contrastRatio(a: unknown, b: unknown): number | undefined;

WCAG 2.x contrast ratio between two hex colours, from 1 (identical) to 21 (black on white). Order-independent. Returns undefined when either colour cannot be parsed, so callers can distinguish "not judgeable" from "fails".

createMap

Function

function createMap(options: MapMapOptions): MapMapMap;

Functional alias for MapMapMap, mirroring the Mapbox new Map feel.

Options and types: MapMapOptions.

Example

import "maplibre-gl/dist/maplibre-gl.css";
import { createMap } from "@mapmap/maps";

const map = createMap({
  container: "map",       // an element id or the element itself
  apiKey: "snk_…",
  style: "light",         // or "dark", a Studio theme, a StyleSpecification or a style URL
  center: [-2.5879, 51.4545],
  zoom: 13,
});
await map.whenReady();
map.map.setPitch(45);     // map.map is the underlying MapLibre map

createRouteEffect

Function

function createRouteEffect(name: RouteEffectName, geometry: RouteGeometry, options?: RouteFlowOptions): RouteEffectLayer;

Create a named route effect layer. Throws an agent-readable error for unknown names (the accepted list included).

Options and types: RouteEffectName, RouteGeometry, RouteFlowOptions.

Example

import { map } from "./map.ts";
import { createRouteEffect } from "@mapmap/maps";

const effect = createRouteEffect("flow", {
  type: "LineString",
  coordinates: [[-0.1276, 51.5072], [-0.0877, 51.5055]],
});
map.map.addLayer(effect);

creditTier

Function

function creditTier(room: number, fullWidth: number, shortWidth: number): CreditTier;

The CreditTier for a credit with room px for its text, whose full line is fullWidth px and short line (with the (i) and its gap) shortWidth px wide at the 6px standard.

dataLayerColor

Function

function dataLayerColor(style?: DataLayerStyle): string | ExpressionSpecification;

The colour expression for style.

Options and types: DataLayerStyle.

defaultNavAlertsDesign

Function

function defaultNavAlertsDesign(): NavAlertsDesign;

Defaults for the optional alerts block. LOCKSTEP: mirrors defaultNavAlertsDesign in website/lib/studio-nav.ts.

Calm chip = the banner's dark pill, so an unstyled alert already matches the rest of the guidance surface. Escalated = a red that clears 4.5:1 against white text.

Per-kind defaults follow the "visual always, audio conditional" rule: the three confidently classified kinds alert unconditionally, a mobile site (a location where enforcement sometimes happens, not a device) warns only if speeding, and an unclassified camera stays on the map but does not interrupt a drive.

defaultNavDesign

Function

function defaultNavDesign(): NavDesign;

Defaults mirror what the SDK draws today with no design: RouteLayer's signal-blue line over a dark casing, and GuidanceBanner's dark pill.

defaultPoiDesign

Function

function defaultPoiDesign(): PoiDesign;

No overrides: every category keeps its built-in dot and label colours.

directionArrow

Function

function directionArrow(direction: string): string;

Unicode arrow for a lane/maneuver direction (OSRM indication strings). A text-only fallback; sprite-based lane icons ship with the map assets.

directionIconSvg

Function · also exported from @mapmap/maps/direction-icons

function directionIconSvg(type?: string, modifier?: string, drivingSide?: string): string;

Inline SVG markup for an OSRM-shaped maneuver (see iconNameForManeuver).

effectsFromStyleMetadata

Function

function effectsFromStyleMetadata(metadata: unknown): {
    route: "flow";
    params?: Record<string, unknown>;
} | undefined;

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.

extractGuidance

Function

function extractGuidance(route: ParsedRoute): StepGuidance[];

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.

Options and types: ParsedRoute.

featuresetLayerIds

Function

function featuresetLayerIds(id: FeaturesetId): readonly string[];

The layer ids a featureset covers (all of them, present or not).

Options and types: FeaturesetId.

fixSetFromCollection

Function

function fixSetFromCollection(collection: unknown): FixSet;

The fixes in one gateway answer, keyed by vehicle id. Features without a usable point or time are skipped.

flythrough

Function

function flythrough(map: MapMapMap | Map, route: RouteGeometry | ParsedRoute, options?: FlythroughOptions): FlythroughController;

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().

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.

Options and types: MapMapMap, RouteGeometry, ParsedRoute, FlythroughOptions.

Example

import { map } from "./map.ts";
import { RouteLayer, flythrough } from "@mapmap/maps";

const route = await new RouteLayer(map).route([-0.1276, 51.5072], [-0.0877, 51.5055]);
const replay = flythrough(map, route, { pitch: 60, durationMs: 15000 });
replay.play();

flythroughPose

Function

function flythroughPose(coordinates: [number, number][], t: number, lookAheadM?: number): FlythroughPose;

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.

formatCoord

Function

function formatCoord(point: LngLatLike): string;

Format one point as an OSRM lon,lat coordinate.

Options and types: LngLatLike.

formatCoords

Function

function formatCoords(points: 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.

Options and types: LngLatLike.

globeModelMatrix

Function

function globeModelMatrix(lngLat: [number, number], altitudeM: number): Float64Array;

Local metres in the three.js frame (X east, Y up, Z south) to unit-sphere space, column-major. A tangent plane at the anchor: the sphere curves away from it by about 2 m at 5 km, which is sub-pixel at every zoom where a 5 km scene fills the screen.

gradeColourString

Function

function gradeColourString(lut: LutBytes, value: string, strength?: number): string;

Grade one colour string, or return it unchanged when it is not one of the forms the compilers grade.

Graded: #rgb, #rgba, #rrggbb, #rrggbbaa (any case) and rgb(r,g,b) / rgba(r,g,b,a) with integer channels 0..255 (plain spaces allowed around each value). Output: hex in gives lowercase hex out, #rrggbb for the 3 and 6 digit forms and #rrggbbaa for the 4 and 8 digit forms (alpha kept); rgb()/rgba() in gives the same function out with no spaces, rgba keeping its original alpha token verbatim. Anything else (hsl(), named colours, percentages, #12), and everything at strength 0, is returned as is.

Options and types: LutBytes.

gradeStyleColours

Function

function gradeStyleColours(style: StyleSpecification, lut: LutBytes, opts?: GradeStyleOptions): StyleSpecification;

Grade every colour in a compiled style through lut: each string under layers[*].paint and layers[*].layout and under every entry of metadata["mapmap:territories"] (the per-territory paint diffs), recursing through expressions, so interpolate, step, match and case stops are graded too. Strings follow gradeColourString's rule.

Left untouched: layers in skipLayerIds, layers whose metadata["mapmap:use-theme"] is "none" (and those layers' entries in the territory diffs), and the root light, sky and sprite. That is the one difference from Mapbox's full-frame LUT, which the runtime ColourThemeLayer matches instead.

Returns a new style; the input is not modified.

Options and types: LutBytes, GradeStyleOptions.

hasBakedMarkers

Function

function hasBakedMarkers(map: MapMapMap | Map): boolean;

Whether the map's current style carries compiler-baked marker layers, i.e. its markers already render in any MapLibre client, with no SDK code.

Useful for deciding whether to construct a MarkersLayer at all: you only need one to CHANGE the markers at runtime, or to render the custom data: image markers a static sprite cannot carry.

Options and types: MapMapMap.

haversineDistanceM

Function

function haversineDistanceM(a: {
    lat: number;
    lon: number;
}, b: {
    lat: number;
    lon: number;
}): number;

Straight-line (haversine) distance between two points, metres.

holdLayersOnTop

Function

function holdLayersOnTop(map: Pick<Map, "getLayersOrder" | "getLayer" | "moveLayer" | "on" | "off">, ids: readonly string[] | (() => readonly string[])): () => void;

Keeps ids at the top of map's drawing order, bottom to top in the order given, from now on: once at the call and again on every styledata. Pass a function to have the ids read afresh on every raise. Ids not on the map are skipped, so the hold can start before its layers are added. Returns the release, which removes the listener (calling it again does nothing).

Example

import { map } from "./map.ts";
import { holdLayersOnTop } from "@mapmap/maps";

// Keep your own layers above the basemap through style swaps and later additions.
const release = holdLayersOnTop(map.map, ["depots-circles", "depots-labels"]);
// Later, to stop holding them:
release();

iconNameForManeuver

Function · also exported from @mapmap/maps/direction-icons

function iconNameForManeuver(type?: string, modifier?: string, drivingSide?: string): DirectionIconName;

Pick the icon for an OSRM-shaped maneuver (maneuver.type + maneuver.modifier, as returned by the MapMap gateway's OSRM endpoint and by Mapbox-style banner instructions).

Unknown or partial input degrades gracefully: unknown types fall back to the plain turn family and ultimately turn_straight, so the result is always a renderable icon.

iconNameForStep

Function · also exported from @mapmap/maps/direction-icons

function iconNameForStep(step: DirectionIconStep): DirectionIconName;

Pick the icon straight from an OSRM route step, the preferred entry point for a single step. Reads maneuver.type/maneuver.modifier, takes the driving side from the step's own driving_side (so a UK roundabout draws clockwise and a UK u-turn uturn_right with no caller configuration), and returns the ferry icon for ferry-mode legs.

Rendering a whole turn list? Use iconNamesForSteps instead, a roundabout's icon cannot be resolved from one step alone.

Options and types: DirectionIconStep.

iconNamesForSteps

Function · also exported from @mapmap/maps/direction-icons

function iconNamesForSteps(steps: readonly DirectionIconStep[]): DirectionIconName[];

Icons for a whole turn list, the entry point for anything rendering consecutive steps, because roundabouts can only be resolved in context.

A roundabout's icon should show the manoeuvre's THROUGH angle: the turn between the road you arrive on and the road you leave on. No single step carries that. The enter step knows the approach (bearing_before) and the matching exit step knows the road taken (bearing_after), so this pass pairs them and gives both the same modifier. The pair shares one driving side too: the enter step's, or the exit step's when only it has one.

Without it, every roundabout on a route draws the same generic ring: the MapMap gateway sends roundabout steps with no modifier at all, and stock OSRM sends the ENTRY tangent instead, which is "left" for every roundabout in a left-hand-traffic country. Either way the icon stops telling one exit from another, which is exactly what it is there for.

A supplied roundabout modifier is deliberately overridden: it describes a different angle from the one being drawn. Everything else is left to iconNameForStep untouched.

Options and types: DirectionIconStep.

interpolateFixes

Function

function interpolateFixes(prev: FixSet, next: FixSet, atMs: number): Rendered[];

Where every vehicle was at atMs (epoch milliseconds), between two consecutive polls. Pure: same inputs, same answer.

Options and types: FixSet.

isMarkerGlyphId

Function

function isMarkerGlyphId(value: unknown): value is MarkerGlyphId;

Whether value is one of the 21 marker glyph ids.

isNameTextField

Function

function isNameTextField(textField: unknown): boolean;

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.

isSlot

Function

function isSlot(value: unknown): value is Slot;

True when value is one of the three slot names.

keyedStyleUrl

Function

function keyedStyleUrl(url: string, apiKey: string | undefined, baseUrl?: string): string;

A style URL with the key added, when it names a document on the key's own gateway that carries the key through to its tiles: a hosted style (/styles/{id}.json) or a territory style (/tiles/{territory}/style.json). The gateway stamps a ?api_key= it was sent onto the tiles the document points at, so the basemap works from any website. Any other URL, a URL that already has an api_key, or no key: returned unchanged.

keyedTilesUrl

Function

function keyedTilesUrl(apiKey: string, baseUrl?: string): string;

The keyed basemap source URL: the gateway's TileJSON for KEYED_TILES_TERRITORY, carrying the key as ?api_key=.

A TileJSON URL rather than a bare {z}/{x}/{y} template on purpose: the gateway fills in the zoom range and bounds from the archive header, adds an archive-version cache buster to the tile template, and stamps the same api_key on it, so MapLibre stays authenticated down to every tile. The query form (not a header) is what lets a plain style URL carry the key, and it is accepted for browser keys restricted by allowed_origins.

baseUrl is the gateway that issued the key; a self-hosted gateway without a planet archive should pass territoryTilesUrl instead.

laneArrowDirection

Function

function laneArrowDirection(lane: LaneIndication): string;

The single direction a lane's arrow should show.

A lane that permits several movements ("straight or right") carries them all in directions, in the gateway's bitmask order, which is NOT the order the route cares about. Drawing directions[0] therefore shows a straight-ahead arrow on the lane the driver is being told to turn right from. activeDirection is the one the route actually takes, so it wins; the first permitted direction is only the fallback for lanes where the server could not resolve one.

Options and types: LaneIndication.

languageTextField

Function

function languageTextField(language: string | null): DataDrivenPropertyValueSpecification<string>;

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).

Typed as the widest value text-field accepts on both majors, because MapLibre 6 types setLayoutProperty's value parameter where 5.x took any, and a coalesce of gets is one such value. The expressions themselves are unchanged, so every caller keeps its current labels.

layersOnTopMoves

Function

function layersOnTopMoves(order: readonly string[], ids: readonly string[]): string[];

The ids to move to the top of order, in the order to move them (each one moved to the very top, so the last moved draws over the rest). Empty when the ids present already close order in their own order, or when none of them is present. Ids not in order are skipped and a repeated id counts once. Pure.

liveTargetLayerIds

Function

function liveTargetLayerIds(map: Map, target: InteractionTarget): string[];

The target's layer ids that exist in the live style, in style order.

Options and types: InteractionTarget.

lngLatToMercator

Function

function lngLatToMercator(lngLat: [number, number]): [number, number];

Project a [lng, lat] to web-mercator world coordinates in [0, 1] (MapLibre's MercatorCoordinate convention: x east, y south).

locateProjectionUniforms

Function

function locateProjectionUniforms(gl: WebGL2RenderingContext, program: WebGLProgram): Record<ProjectionUniform, WebGLUniformLocation | null>;

Uniform locations for PROJECTION_UNIFORMS. A name the variant's prelude does not declare (the mercator prelude has no fallback matrix) is null, which WebGL treats as a no-op when set.

lutApply

Function

function lutApply(lut: LutBytes, rgb: readonly [number, number, number], strength?: number): [number, number, number];

Grade one RGB colour (channels 0..255) through lut, blended with the original by strength (0 = untouched, 1 = fully graded, default 1).

The algorithm, in this exact order (LOCKSTEP with the Rust and Studio ports): per channel s = v / 255 * 15, i0 = floor(s), i1 = min(i0 + 1, 15), f = s - i0; trilinear interpolation of the eight lattice corners along red, then green, then blue, each step a + (b - a) * f; then round(in + (lut - in) * strength) per channel, clamped to 0..255. Rounding is half up; every value is non-negative, so Rust's f64::round gives the same integer.

Options and types: LutBytes.

lutDigest

Function

function lutDigest(lut: LutBytes): string;

FNV-1a 64-bit of the LUT bytes, as 16 lowercase hex characters.

Options and types: LutBytes.

lutFromBase64

Function

function lutFromBase64(s: string): LutBytes;

Decode a base64 LUT (standard alphabet, padded, no whitespace: the form the Rust validator accepts). Throws LUT_SIZE_MESSAGE for anything that is not valid base64 of exactly 12288 bytes.

lutFromImageData

Function

function lutFromImageData(image: LutImageData): LutBytes;

Read a Mapbox-format colour-theme image: 256 pixels wide, 16 high; blue picks the 16-pixel block (x = b * 16 + r), green is the row (y = g, top row 0). Alpha is ignored. Any other size throws, naming 256x16.

Options and types: LutImageData.

lutFromPngData

Function

function lutFromPngData(data: string): Promise<LutBytes>;

Decode a Mapbox-format colour-theme PNG (256x16) into LUT bytes, in the browser. data is what Mapbox's color-theme.data takes, plus a URL: a data: URI, an http(s):// URL (served with CORS), or the raw base64 of a PNG. The pixels are read with colour-space conversion off, so a PNG carrying a colour profile still gives its stored values. Rejects with a message naming the accepted forms or the 256x16 size.

lutToBase64

Function

function lutToBase64(lut: LutBytes): string;

Encode a LUT as standard padded base64.

Options and types: LutBytes.

lutToImageData

Function

function lutToImageData(lut: LutBytes): {
    width: number;
    height: number;
    data: Uint8ClampedArray;
};

The inverse of lutFromImageData: the LUT as 256x16 RGBA pixels (alpha 255), Mapbox's layout. The runtime layer uploads exactly this as its LUT texture, and it is what a PNG export writes.

Options and types: LutBytes.

mapBrandSvg

Function

function mapBrandSvg(theme: MapBrandTheme): string;

The composed v2/MapBrand SVG for one theme.

Options and types: MapBrandTheme.

mapGroundTheme

Function

function mapGroundTheme(map: GroundReadableMap, whenUnreadable: MapBrandTheme): MapBrandTheme;

Day or Night for the style a live map is drawing right now. Cheap enough to run on every styledata: it walks layer ids only until the first background layer (normally the first) and reads one paint value, rather than serialising the whole style.

Options and types: GroundReadableMap, MapBrandTheme.

markerImage

Function

function markerImage(v: unknown): string | undefined;

A usable custom marker image, or undefined: a data: URI of an accepted image type (png/jpeg/webp/svg+xml) whose decoded payload is at most 64 KB. Oversized or foreign URIs are rejected - the marker falls back to its glyph pin (the puck.ts cap precedent).

markerImageDataKey

Function

function markerImageDataKey(dataUri: string): string;

map.addImage cache key for a custom-image marker: the data URI is hashed (FNV-1a), so identical images share one registered copy no matter how many markers use them.

markerImageKey

Function

function markerImageKey(icon: MarkerGlyphId, colour: string, size: MarkerSize): string;

map.addImage cache key for a rasterised glyph marker: mm-marker-<icon>-<colour>-<size> (contract format; the colour is the normalised lowercase #rrggbb). Identical markers share one image.

Options and types: MarkerGlyphId, MarkerSize.

markersFromTheme

Function

function markersFromTheme(theme: Theme | undefined | null): MarkersBlock | undefined;

Reads and parses the extra.markers block from a Studio theme document. Returns undefined when the theme carries no markers block at all (so callers can tell "no markers" apart from "an empty designed set"); a present but malformed block parses leniently via parseMarkers.

Options and types: Theme.

markersFromThemeUrl

Function

function markersFromThemeUrl(url: string, fetchImpl?: typeof fetch): Promise<MarkersBlock | undefined>;

Fetches a hosted theme document and reads its extra.markers block - the same endpoint contract as navDesignFromThemeUrl:

const markers = await markersFromThemeUrl(
  "https://api.mapmap.ai/styles/midnight-fleet-a1b2c3/theme",
);
if (markers) new MarkersLayer(map, markers);

Returns undefined when the theme carries no markers block; throws on network failure, a non-2xx response or a non-JSON body. Bad DATA never throws - invalid items are skipped by the lenient parser.

markerText

Function

function markerText(value: unknown): string | undefined;

Normalise a short pin text: trimmed and cut to MAX_MARKER_TEXT_LENGTH characters, or undefined when nothing printable remains. Callers use undefined to mean "draw the glyph".

markerTextImageKey

Function

function markerTextImageKey(text: string, colour: string, size: MarkerSize): string;

map.addImage cache key for a rasterised SHORT-TEXT marker: mm-marker-text-<text>-<colour>-<size>. Deliberately distinct from markerImageKey so glyph pins keep their existing keys unchanged.

Options and types: MarkerSize.

mercatorModelMatrix

Function

function mercatorModelMatrix(lngLat: [number, number], altitudeM: number): Float64Array;

Local metres in the three.js frame (X east, Y up, Z south) to mercator 0..1 with a conformal z, column-major: the bridge every MapMap 3D layer has used on mercator, translate(MercatorCoordinate.fromLngLat(lngLat, altitudeM)) * scale(s, -s, s) * rotX(pi/2), s = meterInMercatorCoordinateUnits() at the anchor, built with the same operations three.js's makeTranslation().scale().multiply() performs.

modelClipMatrices

Function

function modelClipMatrices(args: ProjectionArgs, lngLat: [number, number], altitudeM: number): ClipMatrices;

The clip matrices for a scene anchored at lngLat. On a mercator frame this is exactly mainMatrix * mercatorModelMatrix(...), the matrix the layers used before the globe existed. On a globe frame the mercator matrix is built from MapLibre's mercator fallback, so the blend through the globe-to-mercator zoom band never squashes elevated geometry (the prelude's own fallback is fed metres where it expects mercator units).

Options and types: ProjectionArgs.

multiplyMat4

Function

function multiplyMat4(a: ArrayLike<number>, b: ArrayLike<number>): Float64Array;

a * b for column-major 4x4s, summed in exactly the order three.js's Matrix4.multiplyMatrices sums (a11*b11 + a12*b21 + a13*b31 + a14*b41), so a product computed here equals the one three.js computed bit for bit.

namedBase

Function

function namedBase(id: string): MapMapBase | undefined;

The catalogue entry for an id, following BASE_ID_ALIASES.