@tomtom-org/maps-sdk 0.55.1 → 0.56.0

package/map/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { BackgroundLayerSpecification, CircleLayerSpecification, DataDrivenPropertyValueSpecification, ExpressionFilterSpecification, ExpressionSpecification, GeoJSONSource, GeoJSONSourceSpecification, LayerSpecification, LineLayerSpecification, LngLat, Map, MapGeoJSONFeature, MapOptions, Source, SourceSpecification, StyleImageInterface, StyleImageMetadata, StyleSpecification, SymbolLayerSpecification } from "maplibre-gl";
-import { Anything, AreaAnalyticsMetricKey, AreaAnalyticsMetrics, BBox, ChargingSpeed, ChargingStop, ChargingStopProps, CommonPlaceProps, DelayMagnitude, DisplayUnits, GetPositionEntryPointOption, GlobalConfig, Instruction, Language, POICategory, Place, Places, PolygonFeature, PolygonFeatures, Route, RouteProps, Routes, SectionProps, SectionType, TrafficAreaAnalytics, TrafficIncident, TrafficIncidentBaseProperties, TrafficIncidentCategory, TrafficIncidentDetails, TrafficIncidentTimeValidity, TrafficSectionProps, Waypoint, WaypointLike, Waypoints } from "@tomtom-org/maps-sdk/core";
+import { Anything, AreaAnalyticsMetricKey, AreaAnalyticsMetrics, BBox, ChargingSpeed, ChargingStop, ChargingStopProps, CommonPlaceProps, CountrySectionProps, DelayMagnitude, DisplayUnits, GetPositionEntryPointOption, GlobalConfig, Instruction, Language, POICategory, Place, Places, PolygonFeature, PolygonFeatures, Route, RouteProps, Routes, SectionProps, SectionType, TrafficAreaAnalytics, TrafficIncident, TrafficIncidentBaseProperties, TrafficIncidentCategory, TrafficIncidentDetails, TrafficIncidentTimeValidity, TrafficSectionProps, Waypoint, WaypointLike, Waypoints } from "@tomtom-org/maps-sdk/core";
 //#region src/shared/types/style.d.ts
 /**
  * Indicator of a light or dark theme.
@@ -342,9 +342,35 @@ export type StandardStyle = {
   version?: string;
 };
 /**
- * Configuration for a custom map style.
+ * Where a custom style comes from: a URL to fetch it from, or the specification itself. Exactly one.
+ *
+ * @example
+ * ```typescript
+ * const fromUrl: CustomStyleSource = { url: 'https://example.com/my-custom-style.json' };
+ *
+ * const fromJson: CustomStyleSource = {
+ *   json: { version: 8, sources: { ... }, layers: [ ... ] },
+ * };
+ * ```
  *
- * Allows using your own map style either via URL or direct JSON specification.
+ * @group Map Style
+ */
+export type CustomStyleSource = {
+  /**
+   * URL to a MapLibre/Mapbox style JSON, without an API key — the SDK adds the configured one.
+   */
+  url: string;
+  json?: never;
+} | {
+  /**
+   * The complete style, as a
+   * [MapLibre Style Specification](https://maplibre.org/maplibre-style-spec/) object.
+   */
+  json: StyleSpecification;
+  url?: never;
+};
+/**
+ * Configuration for a custom map style.
  *
  * @remarks
  * Use custom styles for:
@@ -371,41 +397,7 @@ export type StandardStyle = {
  *
  * @group Map Style
  */
-export type CustomStyle = {
-  /**
-   * URL to a MapLibre/Mapbox style JSON.
-   *
-   * The URL should not include the API key - it will be automatically added.
-   * Mutually exclusive with the `json` property.
-   *
-   * @example
-   * ```typescript
-   * url: 'https://api.tomtom.com/style/1/style/my-custom-style'
-   * ```
-   */
-  url?: string;
-  /**
-   * Direct style specification as JSON.
-   *
-   * Provide the complete MapLibre Style Specification object.
-   * Mutually exclusive with the `url` property.
-   *
-   * @see [MapLibre Style Specification](https://maplibre.org/maplibre-style-spec/)
-   *
-   * @example
-   * ```typescript
-   * json: {
-   *   version: 8,
-   *   sources: {
-   *     'my-source': { type: 'vector', url: '...' }
-   *   },
-   *   layers: [
-   *     { id: 'background', type: 'background', paint: { 'background-color': '#f0f0f0' } }
-   *   ]
-   * }
-   * ```
-   */
-  json?: StyleSpecification;
+export type CustomStyle = CustomStyleSource & {
   /**
    * Whether the style draws a light or a dark map.
    *
@@ -4107,9 +4099,11 @@ export declare abstract class AbstractStyleOwnedMapModule<SOURCES_WITH_LAYERS ex
  * - `number`: an absolute number with a range.
  * - `color`: a CSS colour string.
  * - `enum`: one of the knob's `options`.
+ * - `colors`: a list of colours, each a CSS colour string or one of the knob's `options` — names
+ *   the module resolves to colours, such as styling knob ids. An empty list is the knob's default.
  * @group Shared
  */
-export type KnobKind = 'toggle' | 'factor' | 'number' | 'color' | 'enum';
+export type KnobKind = 'toggle' | 'factor' | 'number' | 'color' | 'enum' | 'colors';
 /**
  * Inclusive bounds for a `factor` or `number` knob. `step` is what a slider would use; some ranges
  * (e.g. opacity 0–1) have no natural step and omit it.
@@ -4160,7 +4154,7 @@ export type KnobDescriptor<T = unknown> = {
   overridden: boolean;
   /** Inclusive bounds, for `factor` and `number` knobs. */
   range?: KnobRange;
-  /** The allowed values, for `enum` knobs. */
+  /** The allowed values, for `enum` knobs; the names accepted besides CSS colours, for `colors` knobs. */
   options?: readonly string[];
   /**
    * Whether the knob has anything to work on in the loaded style. Omitted by modules whose knobs
@@ -7497,7 +7491,7 @@ type PlaceConnectionsConfig = {
  *
  * @group Places
  */
-type PlacesModuleConfig = MapModuleCommonConfig & {
+type PlacesModuleConfig<P extends CommonPlaceProps = CommonPlaceProps> = MapModuleCommonConfig & {
   /**
    * Base style for all places.
    *
@@ -7580,10 +7574,26 @@ type PlacesModuleConfig = MapModuleCommonConfig & {
    * }
    * ```
    */
-  extraFeatureProps?: {
-    [key: string]: ((place: Place) => any) | any;
-  };
+  extraFeatureProps?: Record<string, ExtraFeatureProp<P>>;
+};
+/**
+ * A value a GeoJSON feature property can hold.
+ *
+ * @group Places
+ */
+type FeaturePropValue = string | number | boolean | null | undefined | FeaturePropValue[] | {
+  [key: string]: FeaturePropValue;
 };
+/**
+ * An entry of {@link PlacesModuleConfig.extraFeatureProps}: a fixed value written onto every place
+ * feature, or a function computing one per place.
+ *
+ * @typeParam P - The place properties the callbacks receive. Name it on the config
+ * (`PlacesModuleConfig<MyPlaceProps>`) to have callbacks typed for the places you show.
+ *
+ * @group Places
+ */
+type ExtraFeatureProp<P extends CommonPlaceProps = CommonPlaceProps> = FeaturePropValue | ((place: Place<P>) => FeaturePropValue);
 //#endregion
 //#region src/places/utils/prepareConnectionsForDisplay.d.ts
 /**
@@ -7652,89 +7662,6 @@ export type PlacesEvents = CombinedEvents<MapGeoJSONFeature, PlacesModuleConfig,
   /** The lines and labels connecting places to their parent, when connections are shown. */
   connections: UserEvents<MapGeoJSONFeature>;
 };
-/**
- * Map module for displaying and managing place markers.
- *
- * The PlacesModule provides functionality to display location markers (pins) on the map
- * for points of interest, search results, or custom locations. It supports various marker
- * styles, custom icons, text labels, and interactive events.
- *
- * @remarks
- * **Features:**
- * - Multiple marker styles (pin, circle-icon, base-map POI-like)
- * - Custom icons per POI category
- * - Text labels with styling options
- * - Data-driven styling via MapLibre expressions
- * - Interactive events (click, hover, etc.)
- * - Support for custom feature properties
- * - EV charging station availability display (opt-in)
- *
- * **Marker Styles:**
- * - `pin`: Traditional teardrop-shaped map pins
- * - `circle-icon`: Simple circular markers (previously named `circle`)
- * - `base-map`: Mimics the map's built-in POI layer styling (combines `main`, `selected`, and `micro` layers). For micro-only rendering, hide the `main` layer via `layers.main.layout.visibility = 'none'`.
- *
- * **EV Charging Station Availability:**
- * When displaying EV charging stations with availability data from
- * {@link getPlacesWithEVAvailability}, the module can:
- * - Show available/total charging points (e.g., "3/10")
- * - Color-code availability (green = good, orange = limited, red = none/low)
- * - Display as formatted text within the station's label
- *
- * This feature is disabled by default. To enable it, set `evAvailability.enabled` to `true`
- * in the configuration.
- *
- * **Common Use Cases:**
- * - Search result visualization
- * - Custom location markers
- * - Store locators
- * - EV charging station maps with real-time availability
- * - Delivery/pickup points
- * - Saved locations display
- *
- * @example
- * ```typescript
- * // Create places module with pin markers
- * const placesModule = await PlacesModule.create(map, {
- *   icon: {
- *     categoryIcons: []
- *   },
- *   text: {
- *     field: (place) => place.properties.poi?.name || 'Unknown'
- *   },
- *   theme: 'pin'
- * });
- *
- * // Display places from search
- * await placesModule.show(searchResults);
- *
- * // EV Charging Stations - Opt-in to availability display
- * const evStations = await PlacesModule.create(map, {
- *   evAvailability: { enabled: true }
- * });
- * const results = await search({ poiCategories: ['ELECTRIC_VEHICLE_STATION'] });
- * evStations.show(await getPlacesWithEVAvailability(results)); // Shows availability
- *
- * // Granular control: Enable for searched stations only, background stations without
- * const bgStations = await PlacesModule.create(map); // EV availability disabled
- * const searched = await PlacesModule.create(map, {
- *   evAvailability: { enabled: true }
- * });
- *
- * // Handle clicks
- * placesModule.events.on('click', (feature) => {
- *   console.log('Clicked:', feature.properties);
- * });
- *
- * placesModule.events.on('hover', (feature) => {
- *   showTooltip(feature.properties.poi?.name);
- * });
- * ```
- *
- * @see [Places Guide](https://docs.tomtom.com/maps-sdk-js/guides/map/places)
- *
- * @group Places
- */
 export declare class PlacesModule extends AbstractDataOwnedMapModule<PlacesSourcesAndLayers, PlacesModuleConfig> {
   private layerSpecs;
   private connectionLayerSpecs;
@@ -7757,7 +7684,7 @@ export declare class PlacesModule extends AbstractDataOwnedMapModule<PlacesSourc
    * @param config  The module optional configuration
    * @returns {Promise} Returns a promise with a new instance of this module
    */
-  static create(tomtomMap: TomTomMap, config?: PlacesModuleConfig): Promise<PlacesModule>;
+  static create<P extends CommonPlaceProps = CommonPlaceProps>(tomtomMap: TomTomMap, config?: PlacesModuleConfig<P>): Promise<PlacesModule>;
   private constructor();
   /**
    * @ignore
@@ -7868,9 +7795,7 @@ export declare class PlacesModule extends AbstractDataOwnedMapModule<PlacesSourc
    * });
    * ```
    */
-  applyExtraFeatureProps(extraFeatureProps: {
-    [key: string]: any;
-  }): void;
+  applyExtraFeatureProps<P extends CommonPlaceProps = CommonPlaceProps>(extraFeatureProps: NonNullable<PlacesModuleConfig<P>['extraFeatureProps']>): void;
   private updateLayersAndData;
   private rebuildSourcesAndLayers;
   private updateConnectionLayersAndData;
@@ -9258,6 +9183,18 @@ type RouteLayersConfig = {
      */
     routeSummaryBubbleSymbol?: Partial<ToBeAddedLayerSpecTemplate<SymbolLayerSpecification>>;
   } & HasAdditionalLayersConfig;
+  /**
+   * Border crossing layers.
+   *
+   * @remarks
+   * Anything {@link CountryCrossingConfig} cannot express about the plaque or its label.
+   */
+  countryCrossings?: {
+    /**
+     * Symbol layer writing each crossing's label on its plaque.
+     */
+    routeCountryCrossing?: Partial<ToBeAddedLayerSpecTemplate<SymbolLayerSpecification>>;
+  } & HasAdditionalLayersConfig;
 };
 /**
  * Mapping of charging stop speeds to sprite image IDs.
@@ -9512,9 +9449,6 @@ type SectionIconConfig = {
    * - `center`: one icon at the middle of each section.
    * - `along`: icons repeated along the section.
    *
-   * A section is a stretch of line, so there is no placement at its start: MapLibre places
-   * symbols on a line either once at its centre or repeatedly along it.
-   *
    * @defaultValue `"center"`
    */
   placement?: 'center' | 'along';
@@ -9579,6 +9513,23 @@ type SectionKnobs = {
  * @group Routing
  */
 type SectionSignUnit = 'km/h' | 'mph';
+/**
+ * Where a section's signs are posted along the stretch they belong to.
+ *
+ * @remarks
+ * - `atChange`, the default — one sign where the value changes, and none after it, which is where
+ *   the road posts its own. Sections of a sign-posting type tile the route end to end and no two
+ *   consecutive ones carry the same value, so every section boundary is a change.
+ * - `along` — the sign repeated down the stretch at a fixed screen spacing, so a reader zoomed into
+ *   the middle of a long one still sees the value in force. A stretch too short on screen to fit a
+ *   sign draws none.
+ *
+ * A stretch can run 50 km, so under `atChange` a reader zoomed in past its start sees no sign until
+ * the next change — as on the road itself.
+ *
+ * @group Routing
+ */
+type SectionSignPlacement = 'atChange' | 'along';
 /**
  * What a section's signs give way to when two symbols want the same spot.
  *
@@ -9587,9 +9538,8 @@ type SectionSignUnit = 'km/h' | 'mph';
  * one that gives way.
  *
  * - `belowMapLabels` — the signs give way to everything, the base map's own labels included, so a
- *   sign never lands on a street or place name. Sparse maps, and the price of a tidy one: in a city
- *   the labels take most of the room. Affordable because a sign repeats along its stretch, so one
- *   dropped where a label sits reappears further along.
+ *   sign never lands on a street or place name, at the cost of showing fewer in a city. Cheap under
+ *   `along` placement, where the dropped sign is posted again further down the stretch.
  * - `belowRouteIcons` — the signs give way to the route's own icons, each of which says something
  *   the road cannot, but take precedence over the base map's labels.
  * - `aboveRouteIcons` — the signs give way to nothing, for a map whose subject is the limits.
@@ -9616,24 +9566,32 @@ type SectionSignPriority = 'belowMapLabels' | 'belowRouteIcons' | 'aboveRouteIco
  * `country` sections the display units decide the face and the unit, and an explicit {@link unit}
  * overrides both.
  *
+ * A sign stands where the limit changes; {@link placement} repeats it down the stretch instead.
  * Signs scale with the zoom, as the ferry and toll-road icons do; {@link minzoom} decides how early
  * they appear at all.
  *
  * @group Routing
  */
 type SectionSignConfig = {
+  /**
+   * Where the signs are posted along the stretch.
+   *
+   * @defaultValue `'atChange'`, which is where the road posts its own.
+   */
+  placement?: SectionSignPlacement;
   /**
    * The lowest zoom the signs are drawn at.
    *
-   * @defaultValue 9, the zoom at which a sign is about a stretch of road a reader can see. Over
-   * a whole country the stretches fall in the same few pixels, so the few signs that survive the
-   * collision are an arbitrary sample rather than the limits of the drive.
+   * @defaultValue 10, where a sign is about a stretch of road a reader can see. Further out the
+   * stretches fall in the same few pixels and the surviving signs are an arbitrary sample.
    */
   minzoom?: number;
   /**
-   * Whether a sign gives way to the other icons the route draws, or takes precedence over them.
+   * What a sign gives way to when another symbol wants the same spot.
    *
-   * @defaultValue `'belowRouteIcons'`
+   * @defaultValue follows {@link placement}: `'belowRouteIcons'` under `atChange`, where the sign
+   * is the only one posting that change; `'belowMapLabels'` under `along`, where the next repeat
+   * posts it again.
    */
   priority?: SectionSignPriority;
   /**
@@ -9645,6 +9603,69 @@ type SectionSignConfig = {
    */
   unit?: SectionSignUnit;
 };
+/**
+ * How a border crossing's plaque is turned on the map.
+ *
+ * - `viewport` — level with the screen, however the map is rotated.
+ * - `route` — turned to the route's bearing where it crosses, so the plaque runs along the road. It
+ *   is kept upright, so the label never reads upside down.
+ *
+ * @group Routing
+ */
+type CountryCrossingAlignment = 'viewport' | 'route';
+/**
+ * Appearance of the border crossings along a route.
+ *
+ * @remarks
+ * A crossing is the seam between two consecutive `country` sections, so it is a point rather than a
+ * stretch, and takes knobs of its own instead of a place in the section catalogue. Each is a plaque
+ * naming both countries by their ISO 3166-1 alpha-2 codes in the direction of travel, `'ES → FR'`.
+ *
+ * The plaque follows the map's light/dark theme unless {@link color} or {@link textColor} says
+ * otherwise, so it stays legible across a style change without being reconfigured.
+ *
+ * @example
+ * ```typescript
+ * const routes = await calculateRoute({ locations, sectionTypes: ['country'] });
+ * await routing.showRoutes(routes);
+ * ```
+ *
+ * @group Routing
+ */
+type CountryCrossingConfig = {
+  /**
+   * Whether the crossings are drawn.
+   *
+   * @defaultValue `true`
+   */
+  visible?: boolean;
+  /**
+   * The lowest zoom a crossing is drawn at.
+   *
+   * @defaultValue 4, low enough for a continental route to show its borders while framed whole.
+   */
+  minzoom?: number;
+  /**
+   * The plaque colour behind the label.
+   *
+   * @defaultValue the SDK's near-black `'#1A2024'` on a light map, and the near-white `'#F1F3F5'`
+   * on a dark one.
+   */
+  color?: string;
+  /**
+   * The label colour.
+   *
+   * @defaultValue whichever of the SDK's near-black and near-white reads on the plaque, so
+   * setting {@link color} alone stays legible.
+   */
+  textColor?: string;
+  /**
+   * How the plaque is turned on the map.
+   *
+   * @defaultValue `'viewport'`
+   */
+  alignment?: CountryCrossingAlignment;
+};
 /**
  * Appearance of one route section type.
  *
@@ -9745,6 +9766,13 @@ type RoutingModuleConfig = MapModuleCommonConfig & {
      */
     visible?: boolean;
   };
+  /**
+   * Appearance of the border crossings along the route.
+   *
+   * @remarks
+   * Read off the route's `country` sections, so a route carrying none draws none.
+   */
+  countryCrossings?: CountryCrossingConfig;
   /**
    * Appearance of the route sections, keyed by section type.
    *
@@ -9781,9 +9809,10 @@ type RoutingModuleConfig = MapModuleCommonConfig & {
  * @param config - Optional routing module configuration to customize layer properties.
  * @param layerIDPrefix - Optional prefix to add to layer IDs for supporting multiple instances.
  * @param instanceIndex - Optional instance index for image ID suffixes.
+ * @param lightDark - The map style's light/dark theme, which the country crossing plaque colours follow.
  * @ignore
  */
-export declare const buildRoutingLayers: (config?: RoutingModuleConfig, layerIDPrefix?: string, instanceIndex?: number) => Required<RouteLayersConfig>;
+export declare const buildRoutingLayers: (config?: RoutingModuleConfig, layerIDPrefix?: string, instanceIndex?: number, lightDark?: LightDark) => Required<RouteLayersConfig>;
 /**
  * Default routing layers configuration. Calls routingLayers with no parameters.
  *
@@ -10201,6 +10230,63 @@ type DisplayRouteSummary = Feature<Point, DisplayRouteSummaryProps>;
  * @group Routing
  */
 type DisplayRouteSummaries = FeatureCollection<Point, DisplayRouteSummaryProps>;
+/**
+ * Display-ready props of one border crossing.
+ *
+ * @group Routing
+ */
+type DisplayCountryCrossingProps = DisplayRouteRelatedProps & {
+  /** ISO 3166-1 alpha-2 code of the country the route leaves. */
+  fromCountryCode: string;
+  /** ISO 3166-1 alpha-2 code of the country the route enters. */
+  toCountryCode: string;
+  /** The label the plaque is stretched around — `'ES → FR'`. */
+  label: string;
+  /**
+   * Bearing of the route where it crosses, in degrees clockwise from north.
+   *
+   * @remarks
+   * What `alignment: 'route'` turns the plaque by. Present whatever the alignment, so switching
+   * it is a restyle rather than a re-derive.
+   */
+  bearing: number;
+  /**
+   * `startPointIndex` of the `country` section the route leaves, which identifies that section
+   * on {@link RouteProps.sections} even when the route enters the same country twice.
+   */
+  fromSectionStartPointIndex: number;
+  /** `startPointIndex` of the `country` section the route enters. */
+  toSectionStartPointIndex: number;
+};
+/**
+ * GeoJSON feature of one border crossing, placed where the route enters the second country.
+ *
+ * @group Routing
+ */
+type DisplayCountryCrossing = Feature<Point, DisplayCountryCrossingProps>;
+/**
+ * A border crossing as an event hands it over: the drawn feature, plus the two `country` sections
+ * it joins.
+ *
+ * @remarks
+ * The sections are looked up on the route the crossing belongs to, so they are the same objects
+ * `route.properties.sections.country` holds rather than copies. They are absent only when the route
+ * that carried them is no longer shown.
+ *
+ * @group Routing
+ */
+type CountryCrossingFeature = Feature<Point, DisplayCountryCrossingProps & {
+  /** The `country` section the route leaves. */
+  fromSection?: CountrySectionProps;
+  /** The `country` section the route enters. */
+  toSection?: CountrySectionProps;
+}>;
+/**
+ * GeoJSON feature collection of the border crossings along the shown routes.
+ *
+ * @group Routing
+ */
+type DisplayCountryCrossings = FeatureCollection<Point, DisplayCountryCrossingProps>;
 //#endregion
 //#region src/routing/types/guidance.d.ts
 /**
@@ -10583,6 +10669,7 @@ type RoutingSourcesWithLayers = { [K in SectionSourceKey<GeneratedSectionType>]:
   instructionLines: GeoJSONSourceWithLayers<DisplayInstructions>;
   instructionArrows: GeoJSONSourceWithLayers<DisplayInstructionArrows>;
   summaryBubbles: GeoJSONSourceWithLayers<DisplayRouteSummaries>;
+  countryCrossings: GeoJSONSourceWithLayers<DisplayCountryCrossings>;
 };
 //#endregion
 //#region src/routing/types/showOptions.d.ts
@@ -10663,6 +10750,8 @@ export type RoutingEvents = CombinedEvents<MapGeoJSONFeature, RoutingModuleConfi
   chargingStops: UserEvents<RouteSection>;
   /** The summary bubbles shown against each alternative. */
   summaryBubbles: UserEvents<DisplayRouteSummary>;
+  /** The border crossings along the route, each carrying the two `country` sections it joins. */
+  countryCrossings: UserEvents<CountryCrossingFeature>;
   /** Traffic incidents on the route. */
   incidents: UserEvents<RouteSection<DisplayTrafficSectionProps>>;
   /** Sections the vehicle is restricted from. */
@@ -10791,6 +10880,29 @@ export declare class RoutingModule extends AbstractDataOwnedMapModule<RoutingSou
    * this instead of restyling the layer in place.
    */
   private showSpeedLimitSections;
+  /** The colours the crossings draw with, which follow the map's theme unless configured. */
+  private crossingColors;
+  /**
+   * What {@link applyCountryCrossingConfig} last painted the crossings with.
+   *
+   * @remarks
+   * Tracked here rather than re-derived from `this.config`, because the theme is an input the
+   * config cannot see: a style change moves the resolved colours while the config says the same
+   * thing. Cleared when the sources are rebuilt, so a restored style repaints from scratch.
+   */
+  private appliedCrossingColors;
+  /**
+   * Brings the border crossings in line with a changed configuration.
+   *
+   * @remarks
+   * The source is gated on `visible`, as the summary bubbles' is, so switching them back on
+   * re-derives the features: a layer spec cannot put back data the source does not hold.
+   *
+   * Both colours are applied here rather than left to the layer spec: the plaque is an image, so
+   * a new colour has to replace it, and the label's colour follows the map theme, which the spec
+   * that built the layer cannot know about after a style change.
+   */
+  private applyCountryCrossingConfig;
   /**
    * Re-derives the posted signs when the unit they read in changed.
    *
@@ -10977,6 +11089,7 @@ export declare class RoutingModule extends AbstractDataOwnedMapModule<RoutingSou
    * - `instructionLines`: Turn-by-turn instruction lines
    * - `instructionArrows`: Instruction arrow markers
    * - `summaryBubbles`: Route summary popups
+   * - `countryCrossings`: Border crossings along the route
    *
    * @example
    * ```typescript
@@ -11003,6 +11116,7 @@ export declare class RoutingModule extends AbstractDataOwnedMapModule<RoutingSou
     instructionLines: DisplayInstructions;
     instructionArrows: DisplayInstructionArrows;
     summaryBubbles: DisplayRouteSummaries;
+    countryCrossings: DisplayCountryCrossings;
     carpoolSections: RouteSections | undefined;
     carTrainSections: RouteSections | undefined;
     importantRoadStretchSections: RouteSections | undefined;
@@ -11084,6 +11198,140 @@ type LayerSelector = {
   idExcludes?: string[];
 };
 //#endregion
+//#region src/styling/mapColorCatalogue.d.ts
+/**
+ * The ten semantic map colours — TomTom Map Maker's *Foundations* palette, under its own names and
+ * in its own order. One name drives every layer and shade the style derives from it.
+ *
+ * | Name | Map Maker | Reaches |
+ * |---|---|---|
+ * | `land` | Land (base) | Map background and other bare-land features, influences admin borders/labels. Also used to derive all map colours if undefined. |
+ * | `water` | Water | Waterbodies, waterways and other water features. Also influences glaciers, water labels and ferry lines. |
+ * | `vegetation` | Vegetation | Forests and other land cover such as grass and shrubland. Also influences earth cover vegetation at smaller scales. |
+ * | `park` | Park & Recreation | City parks and sport/recreation grounds. Also influences National Parks and other protected areas at smaller scales. |
+ * | `artificial` | Artificial | Built-up-areas and man-made features such as landuse grounds and buildings. Also influences railways. |
+ * | `roadMajor` | Major Road | Most important road classes, from motorways & trunks to primary roads. Also influences outline and tunnel colours. |
+ * | `road` | Road | Less important road classes, from secondary/tertiary to streets and service roads. Also influences tunnel colours. |
+ * | `roadOutline` | Road Outline | Road outlines for secondary/tertiary roads and minor classes. Also influences road labels and all other outline colours. |
+ * | `label` | Label | Labels for capitals and other populated places/admin areas. Also influences border styling and all other label colours. |
+ * | `labelOutline` | Label Outline | Outlines for populated places and admin area labels. Also influences border outlines and all other label halos. |
+ *
+ * @group Map Styling
+ */
+type MapColorName = 'land' | 'water' | 'vegetation' | 'park' | 'artificial' | 'roadMajor' | 'road' | 'roadOutline' | 'label' | 'labelOutline';
+/**
+ * A partial set of map colours for {@link StylingModule.setMapColors}: any subset of the ten,
+ * each a CSS colour string.
+ *
+ * @example
+ * ```typescript
+ * styling.setMapColors({ land: '#f3f5f7', water: '#accbe2', roadMajor: '#a1b8ce', label: '#364659' });
+ * ```
+ *
+ * @group Map Styling
+ */
+type MapColors = Partial<Record<MapColorName, string>>;
+/**
+ * Every paint property the styling knobs write a colour to. Listed once as values, since
+ * `StylingModule` needs the set at runtime to pick MapLibre's paint setter over its layout one.
+ * @ignore
+ */
+declare const paintColorProperties: readonly ["fill-color", "fill-outline-color", "line-color", "text-color", "text-halo-color", "fill-extrusion-color", "background-color"];
+/** @ignore */
+type PaintColorProperty = (typeof paintColorProperties)[number];
+/**
+ * The ten map colour names, in Map Maker's Foundations order.
+ *
+ * @group Map Styling
+ */
+export declare const mapColorNames: MapColorName[];
+//#endregion
+//#region src/styling/presets.d.ts
+/**
+ * The styling presets the SDK ships: named bundles of knob settings for common intents. Each is data
+ * over the knob catalogue, so a preset is exactly as durable as the knobs it sets, and an app can
+ * start from one and adjust.
+ * @ignore
+ */
+declare const stylingPresets: {
+  readonly 'data-viz': {
+    readonly name: "Data visualisation";
+    readonly description: "A quiet base for your own data on top: fewer labels and markers, thinner roads, no badges competing with the overlay.";
+    readonly settings: {
+      readonly 'labels.sizeFactor': 0.9;
+      readonly 'symbols.sizeFactor': 0.9;
+      readonly 'roads.widthFactor': 0.8;
+      readonly 'roads.exitNumbers': false;
+      readonly 'roads.shields': false;
+      readonly 'roads.arrows': false;
+      readonly 'pois.microMarkers': false;
+      readonly 'pois.minZoom': 14;
+      readonly 'buildings.3d': false;
+    };
+  };
+  readonly 'night-driving': {
+    readonly name: "Night driving";
+    readonly description: "Bigger labels and shields, wider roads and traffic tubes, POIs out of the way until close up.";
+    readonly settings: {
+      readonly 'labels.sizeFactor': 1.2;
+      readonly 'symbols.sizeFactor': 1.2;
+      readonly 'roads.widthFactor': 1.2;
+      readonly 'roads.exitNumbers': true;
+      readonly 'roads.shields': true;
+      readonly 'roads.arrows': true;
+      readonly 'pois.minZoom': 13;
+      readonly 'pois.microMarkers': false;
+      readonly 'traffic.flow.widthFactor': 1.3;
+      readonly 'buildings.3d': false;
+    };
+  };
+  readonly minimal: {
+    readonly name: "Minimal";
+    readonly description: "The bare map: land, water, roads and the main place names. Everything decorative off.";
+    readonly settings: {
+      readonly 'labels.sizeFactor': 0.9;
+      readonly 'roads.exitNumbers': false;
+      readonly 'roads.shields': false;
+      readonly 'roads.arrows': false;
+      readonly 'roads.restricted': false;
+      readonly 'roads.underConstruction': false;
+      readonly 'buildings.footprints': false;
+      readonly 'buildings.3d': false;
+      readonly 'pois.microMarkers': false;
+      readonly 'pois.minZoom': 16;
+    };
+  };
+  readonly globe: {
+    readonly name: "Globe";
+    readonly description: "A globe with an atmosphere for the zoomed-out view; flattens to Mercator as you zoom in.";
+    readonly settings: {
+      readonly 'view.projection': "globe";
+      readonly 'view.sky': true;
+    };
+  };
+  readonly terrain: {
+    readonly name: "Terrain";
+    readonly description: "3D terrain with a sky for tilted views. Needs the hillshade style part and a pitched camera.";
+    readonly settings: {
+      readonly 'view.terrain': true;
+      readonly 'view.terrainExaggeration': 1.2;
+      readonly 'view.sky': true;
+    };
+  };
+};
+/**
+ * The id of a styling preset, as accepted by {@link StylingModule.applyPreset}.
+ *
+ * @group Map Styling
+ */
+type StylingPresetId = keyof typeof stylingPresets;
+/**
+ * Every styling preset id, in catalogue order.
+ *
+ * @group Map Styling
+ */
+export declare const stylingPresetIds: StylingPresetId[];
+//#endregion
 //#region src/styling/types/stylingTypes.d.ts
 /**
  * What kind of value a styling knob takes — a subset of the shared {@link KnobKind} vocabulary.
@@ -11092,10 +11340,11 @@ type LayerSelector = {
  * - `number`: an absolute number with a range, e.g. a minimum zoom.
  * - `toggle`: `true`/`false`, e.g. whether exit numbers are shown.
  * - `color`: a CSS colour string (`#rrggbb`, `hsl(…)`, `rgb(…)`, a named colour).
+ * - `enum`: one of the knob's `options`, e.g. the projection.
  *
  * @group Map Styling
  */
-export declare const stylingKnobKinds: readonly ["factor", "number", "toggle", "color"];
+export declare const stylingKnobKinds: readonly ["factor", "number", "toggle", "color", "enum"];
 /**
  * @group Map Styling
  */
@@ -11152,10 +11401,13 @@ type StylingKnobDescriptor = KnobDescriptor & {
   current: StylingKnobValue | undefined;
   /** The range of valid values, for `factor` and `number` knobs. */
   range?: StylingKnobRange;
+  /** The valid values, for `enum` knobs. */
+  options?: readonly string[];
   /**
    * Whether the knob has anything to work on in the loaded style. `false` means setting it would
-   * do nothing — the SDK also warns once in the console when that happens. Check this before
-   * offering the knob in a UI or to an agent.
+   * do nothing, and the SDK also warns once in the console when that happens. Check this before
+   * offering the knob in a UI or to an agent. Map-level knobs are always available bar
+   * `view.terrain`, which needs the style to carry an elevation source.
    */
   available: boolean;
   /** Which styles the knob works on; see {@link stylingKnobAppliesTo}. */
@@ -11169,6 +11421,22 @@ type StylingKnobDescriptor = KnobDescriptor & {
  */
 type StylingCatalogue = {
   knobs: StylingKnobDescriptor[];
+  /** The presets {@link StylingModule.applyPreset} accepts, with the settings each one applies. */
+  presets: StylingPresetDescriptor[];
+};
+/**
+ * A named bundle of knob settings — TomTom's cartographic opinions, in code. Apply one with
+ * {@link StylingModule.applyPreset}.
+ *
+ * @group Map Styling
+ */
+type StylingPresetDescriptor = {
+  id: StylingPresetId;
+  name: string;
+  /** One line on the use case the preset serves. */
+  description: string;
+  /** The knob values the preset applies; the same shape {@link StylingModule.applyConfig} takes. */
+  settings: StylingSettings;
 };
 /**
  * A serializable set of styling knob values — what {@link StylingModule.getConfig} returns and
@@ -11193,7 +11461,7 @@ type StylingSettings = MapModuleCommonConfig & { [K in StylingKnobId]?: StylingK
 /** @ignore */
 type ScalableProperty = 'text-size' | 'icon-size' | 'line-width';
 /** @ignore */
-type ColorProperty = 'line-color' | 'text-color' | 'text-halo-color';
+type ColorProperty = Extract<PaintColorProperty, 'line-color' | 'text-color' | 'text-halo-color'>;
 /**
  * How a knob reaches the style. A knob may use several (e.g. text and icon size together).
  * @ignore
@@ -11229,15 +11497,44 @@ type KnobMechanism =
 {
   type: 'zoomOffset';
   layers: LayerSelector[];
+} |
+/** Map-level: the projection the whole map is drawn in. */
+{
+  type: 'projection';
+} |
+/** Map-level: the sky/atmosphere (its colours come from the sibling colour knobs). */
+{
+  type: 'sky';
+} |
+/** Map-level: 3D terrain from the style's raster-dem source (exaggeration from the sibling knob). */
+{
+  type: 'terrain';
+} |
+/** Map-level: the colour behind the map canvas, which a globe leaves visible around the planet. */
+{
+  type: 'space';
+} |
+/**
+ * One of the ten semantic map colours: re-derives every literal it governs from the new colour,
+ * keeping each one's HSL offset from the style's own base (the anchor).
+ */
+{
+  type: 'mapColor';
+  color: MapColorName;
 };
 /** @ignore */
 type KnobDefinition = {
   kind: StylingKnobKind;
   description: string;
   range?: StylingKnobRange;
+  /** The valid values of an `enum` knob. */
+  options?: readonly string[];
   appliesTo: StylingKnobAppliesTo;
   mechanisms: KnobMechanism[];
 };
+type KnobDefinitionOf<KIND extends StylingKnobKind> = KnobDefinition & {
+  kind: KIND;
+};
 /**
  * The styling knob catalogue: what the SDK can restyle on a TomTom standard style, and how.
  *
@@ -11246,10 +11543,10 @@ type KnobDefinition = {
  * @ignore
  */
 declare const knobDefinitions: {
-  readonly 'labels.sizeFactor': KnobDefinition;
-  readonly 'symbols.sizeFactor': KnobDefinition;
-  readonly 'roads.widthFactor': KnobDefinition;
-  readonly 'pois.sizeFactor': KnobDefinition;
+  readonly 'labels.sizeFactor': KnobDefinitionOf<"factor">;
+  readonly 'symbols.sizeFactor': KnobDefinitionOf<"factor">;
+  readonly 'roads.widthFactor': KnobDefinitionOf<"factor">;
+  readonly 'pois.sizeFactor': KnobDefinitionOf<"factor">;
   readonly 'pois.minZoom': {
     readonly kind: "number";
     readonly description: "Zoom level from which base-map POIs appear (the style default is 6).";
@@ -11286,27 +11583,99 @@ declare const knobDefinitions: {
       readonly layers: [LayerSelector];
     }];
   };
-  readonly 'pois.labelColor': KnobDefinition;
-  readonly 'pois.labelOutlineColor': KnobDefinition;
-  readonly 'pois.microMarkers': KnobDefinition;
-  readonly 'roads.exitNumbers': KnobDefinition;
-  readonly 'roads.shields': KnobDefinition;
-  readonly 'roads.arrows': KnobDefinition;
-  readonly 'roads.restricted': KnobDefinition;
-  readonly 'roads.underConstruction': KnobDefinition;
-  readonly 'buildings.footprints': KnobDefinition;
-  readonly 'buildings.3d': KnobDefinition;
-  readonly 'traffic.flow.freeColor': KnobDefinition;
-  readonly 'traffic.flow.slowColor': KnobDefinition;
-  readonly 'traffic.flow.queueingColor': KnobDefinition;
-  readonly 'traffic.flow.stationaryColor': KnobDefinition;
-  readonly 'traffic.flow.closedColor': KnobDefinition;
-  readonly 'traffic.flow.widthFactor': KnobDefinition;
-  readonly 'traffic.incidents.minorColor': KnobDefinition;
-  readonly 'traffic.incidents.moderateColor': KnobDefinition;
-  readonly 'traffic.incidents.majorColor': KnobDefinition;
-  readonly 'traffic.incidents.closedColor': KnobDefinition;
-  readonly 'traffic.incidents.widthFactor': KnobDefinition;
+  readonly 'pois.labelColor': KnobDefinitionOf<"color">;
+  readonly 'pois.labelOutlineColor': KnobDefinitionOf<"color">;
+  readonly 'pois.microMarkers': KnobDefinitionOf<"toggle">;
+  readonly 'roads.exitNumbers': KnobDefinitionOf<"toggle">;
+  readonly 'roads.shields': KnobDefinitionOf<"toggle">;
+  readonly 'roads.arrows': KnobDefinitionOf<"toggle">;
+  readonly 'roads.restricted': KnobDefinitionOf<"toggle">;
+  readonly 'roads.underConstruction': KnobDefinitionOf<"toggle">;
+  readonly 'buildings.footprints': KnobDefinitionOf<"toggle">;
+  readonly 'buildings.3d': KnobDefinitionOf<"toggle">;
+  readonly 'traffic.flow.freeColor': KnobDefinitionOf<"color">;
+  readonly 'traffic.flow.slowColor': KnobDefinitionOf<"color">;
+  readonly 'traffic.flow.queueingColor': KnobDefinitionOf<"color">;
+  readonly 'traffic.flow.stationaryColor': KnobDefinitionOf<"color">;
+  readonly 'traffic.flow.closedColor': KnobDefinitionOf<"color">;
+  readonly 'traffic.flow.widthFactor': KnobDefinitionOf<"factor">;
+  readonly 'traffic.incidents.minorColor': KnobDefinitionOf<"color">;
+  readonly 'traffic.incidents.moderateColor': KnobDefinitionOf<"color">;
+  readonly 'traffic.incidents.majorColor': KnobDefinitionOf<"color">;
+  readonly 'traffic.incidents.closedColor': KnobDefinitionOf<"color">;
+  readonly 'traffic.incidents.widthFactor': KnobDefinitionOf<"factor">;
+  readonly 'colors.land': KnobDefinitionOf<"color">;
+  readonly 'colors.water': KnobDefinitionOf<"color">;
+  readonly 'colors.vegetation': KnobDefinitionOf<"color">;
+  readonly 'colors.park': KnobDefinitionOf<"color">;
+  readonly 'colors.artificial': KnobDefinitionOf<"color">;
+  readonly 'colors.roadMajor': KnobDefinitionOf<"color">;
+  readonly 'colors.road': KnobDefinitionOf<"color">;
+  readonly 'colors.roadOutline': KnobDefinitionOf<"color">;
+  readonly 'colors.label': KnobDefinitionOf<"color">;
+  readonly 'colors.labelOutline': KnobDefinitionOf<"color">;
+  readonly 'view.projection': {
+    readonly kind: "enum";
+    readonly description: "How the map is drawn: flat Mercator or a globe. The globe flattens to Mercator between zoom 11 and 12 by design.";
+    readonly options: readonly ["mercator", "globe"];
+    readonly appliesTo: "any-style";
+    readonly mechanisms: [{
+      readonly type: "projection";
+    }];
+  };
+  readonly 'view.sky': {
+    readonly kind: "toggle";
+    readonly description: "A sky with atmosphere behind the globe and above a tilted flat map. Without it MapLibre draws a fully transparent sky, so a globe arrives with no atmosphere.";
+    readonly appliesTo: "any-style";
+    readonly mechanisms: [{
+      readonly type: "sky";
+    }];
+  };
+  readonly 'view.skyColor': {
+    readonly kind: "color";
+    readonly description: "Colour of the sky (and of the atmosphere halo around the globe). Defaults to a daylit blue on a light style and a night blue on a dark one.";
+    readonly appliesTo: "any-style";
+    readonly mechanisms: [{
+      readonly type: "sky";
+    }];
+  };
+  readonly 'view.horizonColor': {
+    readonly kind: "color";
+    readonly description: "Colour of the sky at the horizon. Defaults with the style theme, so a dark map gets a dim horizon rather than a white one.";
+    readonly appliesTo: "any-style";
+    readonly mechanisms: [{
+      readonly type: "sky";
+    }];
+  };
+  readonly 'view.spaceColor': {
+    readonly kind: "color";
+    readonly description: "Colour behind the map, which a globe leaves visible around the planet. The map canvas is transparent, so without this the page background shows through. Defaults with the style theme: white on a light style, near-black on a dark one.";
+    readonly appliesTo: "any-style";
+    readonly mechanisms: [{
+      readonly type: "space";
+    }];
+  };
+  readonly 'view.terrain': {
+    readonly kind: "toggle";
+    readonly description: "3D terrain from the style's elevation source (the hillshade style part). Needs a tilted camera to show; MapLibre's terrain fog starts at pitch 60, which is also its default maxPitch.";
+    readonly appliesTo: "any-style";
+    readonly mechanisms: [{
+      readonly type: "terrain";
+    }];
+  };
+  readonly 'view.terrainExaggeration': {
+    readonly kind: "number";
+    readonly description: "Vertical exaggeration of the 3D terrain (1 = true elevation).";
+    readonly range: {
+      readonly min: 0.5;
+      readonly max: 3;
+      readonly step: 0.1;
+    };
+    readonly appliesTo: "any-style";
+    readonly mechanisms: [{
+      readonly type: "terrain";
+    }];
+  };
 };
 /**
  * The id of a styling knob — see {@link StylingModule.describe} for what each one does.
@@ -11320,7 +11689,20 @@ type StylingKnobId = keyof typeof knobDefinitions;
  * @group Map Styling
  */
 export declare const stylingKnobIds: StylingKnobId[];
-type ValueOfKind<KIND extends StylingKnobKind> = KIND extends 'toggle' ? boolean : KIND extends 'color' ? string : number;
+/**
+ * The id of a styling knob that holds a colour — every colour the styling module can name, and so
+ * resolve against whichever style is loaded.
+ *
+ * @group Map Styling
+ */
+type StylingColorKnobId = { [ID in StylingKnobId]: (typeof knobDefinitions)[ID]['kind'] extends 'color' ? ID : never; }[StylingKnobId];
+/**
+ * Every colour knob id, in catalogue order.
+ *
+ * @group Map Styling
+ */
+export declare const stylingColorKnobIds: StylingColorKnobId[];
+type ValueOfKind<KIND extends StylingKnobKind> = KIND extends 'toggle' ? boolean : KIND extends 'color' | 'enum' ? string : number;
 /**
  * The value type a given styling knob takes.
  *
@@ -11385,10 +11767,16 @@ export type StylingEvents = CombinedEvents<MapGeoJSONFeature, StylingSettings, n
  */
 export declare class StylingModule extends AbstractStyleOwnedMapModule<Record<string, never>, StylingSettings> {
   private originalValues;
+  private mapLevelState;
   private styleSources;
   private resolved;
   private scaleKnobsByTarget;
+  private mapColorTargetsByKey;
+  private mapColorTargetsByKnob;
+  private mapColorAnchors;
   private warned;
+  private reindexed;
+  private originalSpaceColor;
   /**
    * Retrieves the styling module of the given map, creating it on first use.
    *
@@ -11435,6 +11823,27 @@ export declare class StylingModule extends AbstractStyleOwnedMapModule<Record<st
    * ```
    */
   describe(): StylingCatalogue;
+  /**
+   * Applies a preset: a named bundle of knob settings the SDK ships for a common intent
+   * (`data-viz`, `night-driving`, `minimal`, `globe`, `terrain`). See `describe().presets` for
+   * what each one sets.
+   *
+   * @param id - The preset to apply.
+   * @param options - `merge: true` lays the preset over the current settings instead of replacing
+   * them (the default), so knobs the preset does not mention keep their values.
+   * @throws `Error` for an unknown preset id.
+   *
+   * @example
+   * ```typescript
+   * styling.applyPreset('data-viz');
+   * styling.set('labels.sizeFactor', 1.1); // then adjust
+   *
+   * styling.applyPreset('globe', { merge: true }); // keep the rest, switch to a globe with a sky
+   * ```
+   */
+  applyPreset(id: StylingPresetId, options?: {
+    merge?: boolean;
+  }): void;
   /**
    * The value a knob currently has: the override if one is set, otherwise the style's own default.
    *
@@ -11477,6 +11886,39 @@ export declare class StylingModule extends AbstractStyleOwnedMapModule<Record<st
    * ```
    */
   reset(id?: StylingKnobId): void;
+  /**
+   * Recolours the whole base map with up to ten semantic colours in one call — Map Maker's
+   * Foundations palette, each listed with what it reaches under {@link MapColorName}. Partial
+   * objects are fine; colours not given stay as they are.
+   *
+   * @remarks
+   * Each colour re-derives every shade the style built from it — a trunk variant, an outline, a
+   * tunnel — at the style's own HSL offset, so those relationships survive the recolour. The ten
+   * are also the `colors.*` knobs, so `describe()`, `reset` and settings persistence apply.
+   *
+   * Those offsets come off the loaded style, which makes a palette a recolour and not an
+   * inversion: dark land over `standardLight` pushes the derived shades to the ends of their
+   * range, so switch to `standardDark` first.
+   *
+   * @param colors - The colours to set, as CSS colour strings.
+   * @throws `RangeError` for a value that is not a colour; `Error` for an unknown colour name.
+   *
+   * @example
+   * ```typescript
+   * styling.setMapColors({ land: '#f3f5f7', water: '#accbe2', roadMajor: '#a1b8ce', label: '#364659' });
+   * styling.reset('colors.roadMajor'); // one colour back to the style
+   * ```
+   */
+  setMapColors(colors: MapColors): void;
+  /**
+   * The style as currently rendered — the loaded style with every knob applied — as a MapLibre
+   * style specification, to save, diff, serve yourself, or load back as a custom style.
+   *
+   * @remarks
+   * It includes whatever the SDK's data modules (places, routes) have on the map, and its tile
+   * URLs carry the API key the map was created with: strip or rotate it before publishing.
+   */
+  exportStyle(): StyleSpecification;
   /**
    * Lifecycle events of this module. The module owns no map features, so there are no user
    * interaction events; `config-change` fires with the full settings after every knob change.
@@ -11491,8 +11933,16 @@ export declare class StylingModule extends AbstractStyleOwnedMapModule<Record<st
   private resolveMechanism;
   private capture;
   private originalValueOf;
+  private resolveMapColor;
+  private demSourceId;
   private refreshKnob;
   private refreshMechanism;
+  private refreshSpace;
+  private defaultSpaceColor;
+  private refreshMapColorProperty;
+  private refreshProjection;
+  private refreshSky;
+  private refreshTerrain;
   private refreshVisibility;
   private refreshMinZoom;
   private refreshZoomOffset;
@@ -11501,6 +11951,7 @@ export declare class StylingModule extends AbstractStyleOwnedMapModule<Record<st
   private setProperty;
   private describeKnob;
   private defaultOf;
+  private mapLevelDefaultOf;
   private assertKnob;
   private validate;
   private warnOnce;
@@ -11783,6 +12234,17 @@ type AreaAnalyticsRegionPolygonConfig = {
    */
   inverted?: boolean;
 };
+/**
+ * The green / amber / red every metric's default colour stops and the `trafficLight` colour theme
+ * are drawn from.
+ *
+ * @ignore
+ */
+declare const TRAFFIC_LIGHT_COLORS: {
+  readonly good: "#2dc653";
+  readonly moderate: "#f5a623";
+  readonly bad: "#e03030";
+};
 /**
  * Default values for all {@link TrafficAreaAnalyticsConfig} options.
  *
@@ -11803,10 +12265,16 @@ declare const AREA_ANALYTICS_DEFAULTS: {
     congestionLevel: {
       color: {
         valueType: "raw";
-        stops: {
+        stops: ({
+          value: number;
+          color: "#2dc653";
+        } | {
           value: number;
-          color: string;
-        }[];
+          color: "#f5a623";
+        } | {
+          value: number;
+          color: "#e03030";
+        })[];
       };
       height: {
         maxHeightMeters: number;
@@ -11817,10 +12285,16 @@ declare const AREA_ANALYTICS_DEFAULTS: {
     speed: {
       color: {
         valueType: "relativeToPredefinedRangePCT";
-        stops: {
+        stops: ({
+          value: number;
+          color: "#e03030";
+        } | {
           value: number;
-          color: string;
-        }[];
+          color: "#f5a623";
+        } | {
+          value: number;
+          color: "#2dc653";
+        })[];
       };
       height: {
         maxHeightMeters: number;
@@ -11831,10 +12305,16 @@ declare const AREA_ANALYTICS_DEFAULTS: {
     travelTime: {
       color: {
         valueType: "relativeToPredefinedRangePCT";
-        stops: {
+        stops: ({
+          value: number;
+          color: "#2dc653";
+        } | {
+          value: number;
+          color: "#f5a623";
+        } | {
           value: number;
-          color: string;
-        }[];
+          color: "#e03030";
+        })[];
       };
       height: {
         maxHeightMeters: number;
@@ -11845,10 +12325,16 @@ declare const AREA_ANALYTICS_DEFAULTS: {
     freeFlowSpeed: {
       color: {
         valueType: "relativeToPredefinedRangePCT";
-        stops: {
+        stops: ({
+          value: number;
+          color: "#e03030";
+        } | {
+          value: number;
+          color: "#f5a623";
+        } | {
           value: number;
-          color: string;
-        }[];
+          color: "#2dc653";
+        })[];
       };
       height: {
         maxHeightMeters: number;
@@ -11859,10 +12345,16 @@ declare const AREA_ANALYTICS_DEFAULTS: {
     networkLength: {
       color: {
         valueType: "relativeToActualRangePCT";
-        stops: {
+        stops: ({
           value: number;
-          color: string;
-        }[];
+          color: "#2dc653";
+        } | {
+          value: number;
+          color: "#f5a623";
+        } | {
+          value: number;
+          color: "#e03030";
+        })[];
       };
       height: {
         maxHeightMeters: number;
@@ -13584,6 +14076,20 @@ export declare class TrafficIncidentsModule extends AbstractStyleOwnedMapModule<
   get events(): CombinedEvents<TrafficIncidentsModuleFeature, IncidentsConfig, never>;
 }
 //#endregion
+//#region src/utils/colorUtils.d.ts
+/**
+ * Red, green, blue and alpha of a colour, each 0–1.
+ * @ignore
+ */
+type RGBAColor = [number, number, number, number];
+/**
+ * Parses any CSS colour a map style writes — `#rgb`, `#rrggbb(aa)`, `rgb()`/`rgba()` in numbers or
+ * percentages, `hsl()`/`hsla()`, `transparent` and the named colours — or `undefined` for a string
+ * that is not one.
+ * @ignore
+ */
+export declare const parseCssColor: (cssColor: string) => RGBAColor | undefined;
+//#endregion
 //#region src/utils/types/paddedBounds.d.ts
 /**
  * Options for calculating map center.
@@ -13664,4 +14170,4 @@ export declare const calculatePaddedCenter: (options: CalculateMapCenterOptions)
  */
 export declare const calculateFittingBBox: (options: CalculateFittingBBoxOptions) => BBox | null;
 //#endregion
-export type { AREA_ANALYTICS_DEFAULTS, AreaAnalyticsBeforeLayerConfig, AreaAnalyticsColorStop, AreaAnalyticsColorStopsConfig, AreaAnalyticsColorTheme, AreaAnalyticsDisplayMode, AreaAnalyticsHeightConfig, AreaAnalyticsMetricConfig, AreaAnalyticsMetricFilter, AreaAnalyticsRegionPolygonConfig, AreaAnalyticsValueType, AvailabilityLevel, BeforeLayerConfig, BespokeSectionType, ByIdOrIndex, CSSCursor, ChargingSpeedIconMapping, ChargingStopIconConfig, ChargingStopIconMapping, ChargingStopTextConfig, ChargingStopsConfig, CleanEventStateOptions, CleanEventStatesOptions, ClickEventType, CustomImage, DefaultPlaceIconConfig, DisplayRouteProps, DisplayRouteRelatedProps, DisplayRouteSummaries, DisplayRouteSummary, DisplayRouteSummaryProps, DrawnSectionType, EVAvailabilityConfig, EventHandlerConfig, EventHandlerCursorConfig, EventType, FilterShowMode, FilterablePOICategory, GeneratedSectionType, GeoJSONSourcesWithLayers, HasAdditionalLayersConfig, HasBeforeID, HillshadeModuleConfig, HoverEventType, IncidentFocusStyle, LayerSpecFilter, LayerSpecTemplate, LayerSpecWithSource, LightDark, MapEventsConfig, MapFont, MapModuleCommonConfig, MapStyleLayerID, POIsModuleConfig, POIsModuleFeature, PlaceConnectionDisplay, PlaceConnectionLayerName, PlaceConnectionsConfig, PlaceConnectionsLayersConfig, PlaceIconConfig, PlaceLayerName, PlaceLayersConfig, PlaceTextConfig, PlacesModuleConfig, PlacesTheme, PlanningWaypoint, PutEventStateOptions, RouteLayersConfig, RouteStateProps, RouteTheme, RouteWaypointSize, RouteWidth, RoutingModuleConfig, SVGIconStyleOptions, SectionDisplayConfig, SectionDrawStyle, SectionIconConfig, SectionKnobName, SectionKnobOf, SectionLineLayerName, SectionLinePattern, SectionSignConfig, SectionSignLayerName, SectionSignPriority, SectionSignUnit, SectionSourceKey, SectionSymbolLayerName, SectionsDisplayConfig, SourceWithLayerIDs, SourceWithLayers, SourcesWithLayers, StyleSourcesWithLayers, StylingCatalogue, StylingKnobAppliesTo, StylingKnobDescriptor, StylingKnobId, StylingKnobKind, StylingKnobRange, StylingKnobValue, StylingKnobValueOf, StylingSettings, SupportsEvents, SymbolLayerSpecWithoutSource, ToBeAddedLayerSpec, ToBeAddedLayerSpecTemplate, ToBeAddedLayerSpecWithoutSource, TrafficAreaAnalyticsConfig, TrafficIncidentOverlayConfig, UserEventHandler, ValuesFilter, WaypointsConfig };
+export type { AREA_ANALYTICS_DEFAULTS, AreaAnalyticsBeforeLayerConfig, AreaAnalyticsColorStop, AreaAnalyticsColorStopsConfig, AreaAnalyticsColorTheme, AreaAnalyticsDisplayMode, AreaAnalyticsHeightConfig, AreaAnalyticsMetricConfig, AreaAnalyticsMetricFilter, AreaAnalyticsRegionPolygonConfig, AreaAnalyticsValueType, AvailabilityLevel, BeforeLayerConfig, BespokeSectionType, ByIdOrIndex, CSSCursor, ChargingSpeedIconMapping, ChargingStopIconConfig, ChargingStopIconMapping, ChargingStopTextConfig, ChargingStopsConfig, CleanEventStateOptions, CleanEventStatesOptions, ClickEventType, CountryCrossingAlignment, CountryCrossingConfig, CountryCrossingFeature, CustomImage, DefaultPlaceIconConfig, DisplayCountryCrossing, DisplayCountryCrossingProps, DisplayCountryCrossings, DisplayRouteProps, DisplayRouteRelatedProps, DisplayRouteSummaries, DisplayRouteSummary, DisplayRouteSummaryProps, DrawnSectionType, EVAvailabilityConfig, EventHandlerConfig, EventHandlerCursorConfig, EventType, ExtraFeatureProp, FeaturePropValue, FilterShowMode, FilterablePOICategory, GeneratedSectionType, GeoJSONSourcesWithLayers, HasAdditionalLayersConfig, HasBeforeID, HillshadeModuleConfig, HoverEventType, IncidentFocusStyle, LayerSpecFilter, LayerSpecTemplate, LayerSpecWithSource, LightDark, MapColorName, MapColors, MapEventsConfig, MapFont, MapModuleCommonConfig, MapStyleLayerID, POIsModuleConfig, POIsModuleFeature, PlaceConnectionDisplay, PlaceConnectionLayerName, PlaceConnectionsConfig, PlaceConnectionsLayersConfig, PlaceIconConfig, PlaceLayerName, PlaceLayersConfig, PlaceTextConfig, PlacesModuleConfig, PlacesTheme, PlanningWaypoint, PutEventStateOptions, RGBAColor, RouteLayersConfig, RouteStateProps, RouteTheme, RouteWaypointSize, RouteWidth, RoutingModuleConfig, SVGIconStyleOptions, SectionDisplayConfig, SectionDrawStyle, SectionIconConfig, SectionKnobName, SectionKnobOf, SectionLineLayerName, SectionLinePattern, SectionSignConfig, SectionSignLayerName, SectionSignPlacement, SectionSignPriority, SectionSignUnit, SectionSourceKey, SectionSymbolLayerName, SectionsDisplayConfig, SourceWithLayerIDs, SourceWithLayers, SourcesWithLayers, StyleSourcesWithLayers, StylingCatalogue, StylingColorKnobId, StylingKnobAppliesTo, StylingKnobDescriptor, StylingKnobId, StylingKnobKind, StylingKnobRange, StylingKnobValue, StylingKnobValueOf, StylingPresetDescriptor, StylingPresetId, StylingSettings, SupportsEvents, SymbolLayerSpecWithoutSource, TRAFFIC_LIGHT_COLORS, ToBeAddedLayerSpec, ToBeAddedLayerSpecTemplate, ToBeAddedLayerSpecWithoutSource, TrafficAreaAnalyticsConfig, TrafficIncidentOverlayConfig, UserEventHandler, ValuesFilter, WaypointsConfig };