@tomtom-org/maps-sdk 0.55.1 → 0.57.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 { AllLayoutProperties, AllPaintProperties, BackgroundLayerSpecification, CircleLayerSpecification, DataDrivenPropertyValueSpecification, ExpressionFilterSpecification, ExpressionSpecification, FilterSpecification, 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, 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.
@@ -311,7 +311,7 @@ export type StandardStyle = {
    * Available modules:
    * - `trafficIncidents`: Real-time traffic incidents (accidents, closures)
    * - `trafficFlow`: Real-time traffic flow visualization
-   * - `hillshade`: Terrain elevation shading
+   * - `hillshade`: Terrain elevation data, for hillshade shading and 3D terrain
    *
    * @example
    * ```typescript
@@ -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' };
  *
- * Allows using your own map style either via URL or direct JSON specification.
+ * const fromJson: CustomStyleSource = {
+ *   json: { version: 8, sources: { ... }, layers: [ ... ] },
+ * };
+ * ```
+ *
+ * @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.
    *
@@ -440,7 +432,7 @@ export declare const styleModules: readonly ["trafficIncidents", "trafficFlow",
  * @remarks
  * - `trafficIncidents`: Shows real-time traffic incidents on the map
  * - `trafficFlow`: Shows real-time traffic flow with color-coded speeds
- * - `hillshade`: Adds terrain elevation shading for topographic context
+ * - `hillshade`: Adds terrain elevation data, drawn by {@link TerrainModule} as hillshade shading and 3D terrain
  *
  * @group Map Style
  */
@@ -585,7 +577,6 @@ export type TomTomMapParams = Partial<GlobalConfig> & {
    *   zoom: 12,
    *   pitch: 45,
    *   bearing: -17.6,
-   *   antialias: true,
    *   maxZoom: 18,
    *   minZoom: 8
    * }
@@ -952,7 +943,6 @@ export declare class TomTomMap {
    *     zoom: 13,
    *     pitch: 45,
    *     bearing: -17.6,
-   *     antialias: true,
    *     maxZoom: 18,
    *     minZoom: 8
    *   }
@@ -3852,8 +3842,7 @@ export declare abstract class AbstractMapModule<SOURCES_WITH_LAYERS extends Sour
    * module behavior even when the map's base style is modified.
    *
    * Unless a module documents otherwise, the given configuration **replaces** the current one
-   * rather than being merged into it. To change one part of it, spread the current
-   * configuration into the new one: `myModule.applyConfig({ ...myModule.getConfig(), theme })`.
+   * rather than being merged into it. To change one part of it, use {@link updateConfig}.
    *
    * @example
    * ```typescript
@@ -3868,6 +3857,25 @@ export declare abstract class AbstractMapModule<SOURCES_WITH_LAYERS extends Sour
    * @see {@link getConfig} to retrieve the current configuration
    */
   applyConfig(config: CFG | undefined): void;
+  /**
+   * Changes part of the configuration and keeps the rest.
+   *
+   * The given properties are laid over the current configuration — one level deep, so a nested
+   * object you pass replaces the nested object that was there — and the result is applied with
+   * {@link applyConfig}. This is the same on every module, whatever its `applyConfig` does with a
+   * whole configuration.
+   *
+   * @param partial - The properties to change.
+   *
+   * @example
+   * ```typescript
+   * routing.applyConfig({ displayUnits: 'imperial', theme: { mainColor: '#0a3653' } });
+   * routing.updateConfig({ theme: { mainColor: '#c2185b' } }); // displayUnits stays imperial
+   * ```
+   *
+   * @see {@link applyConfig} to apply a whole configuration
+   */
+  updateConfig(partial: Partial<NonNullable<CFG>>): void;
   /**
    * Emits a `config-change` event to all registered handlers.
    * Skipped during module initialisation to avoid spurious events.
@@ -4011,6 +4019,12 @@ export declare abstract class AbstractMapModule<SOURCES_WITH_LAYERS extends Sour
    * @ignore
    */
   protected userEvents<T = MapGeoJSONFeature, WHERE_SCOPE = never>(sourceNames: (keyof SOURCES_WITH_LAYERS)[], options?: EventScopeOptions<T, WHERE_SCOPE>): UserEvents<T, WHERE_SCOPE>;
+  /**
+   * `config-change` alone: the event surface of a module with no `show` and nothing on the map a
+   * user can interact with, and the lifecycle half of {@link moduleEvents}.
+   * @ignore
+   */
+  protected lifecycleEvents(): ModuleEvents<CFG, never>;
   /**
    * The event surface of a module with no `show`: user events over the named sources, plus
    * `config-change`. `shown-features` is not subscribable here — `TShown` is `never`, which
@@ -4073,10 +4087,10 @@ export declare abstract class AbstractDataOwnedMapModule<SOURCES_WITH_LAYERS ext
 //#region src/shared/AbstractStyleOwnedMapModule.d.ts
 /**
  * Base class for the map modules that control sources and layers the loaded map style already
- * provides, under fixed global IDs: the base map, POIs, the traffic tiles and hillshade.
+ * provides, under fixed global IDs: the base map, POIs, the traffic tiles and the terrain.
  *
  * @remarks
- * The style owns the data, so such a module adds no sources of its own and shows nothing by
+ * The style owns the data, so such a module brings no data of its own and shows nothing by
  * itself. It changes how the parts the style provides are drawn, filtered and made visible.
  * The SDK memoizes one instance per map, obtained with `get(map, config?)`, so every handle on it
  * sees the same state.
@@ -4107,9 +4121,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 +4176,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
@@ -4378,15 +4394,25 @@ type MapFont = (typeof mapFonts)[number];
  */
 export declare const POI_SOURCE_ID = "vectorTiles";
 /**
- * Source identifier for hillshade terrain visualization.
+ * Source identifier of the style's elevation data, added by the `hillshade` style part.
  *
  * @remarks
- * References the raster source that provides terrain shading to visualize
- * elevation and topography on the map.
+ * A raster-dem source, drawn as the hillshade layer. {@link TerrainModule} raises the 3D surface
+ * from a copy of it, {@link TERRAIN_SOURCE_ID}.
  *
- * @group Hillshade
+ * @group Terrain
  */
 export declare const HILLSHADE_SOURCE_ID = "hillshade";
+/**
+ * Source identifier of the 3D terrain surface: a copy of {@link HILLSHADE_SOURCE_ID} that
+ * {@link TerrainModule} adds when elevation is first enabled.
+ *
+ * @remarks
+ * MapLibre renders hillshade and 3D terrain at a lower quality when both share one source.
+ *
+ * @group Terrain
+ */
+export declare const TERRAIN_SOURCE_ID = "hillshade-terrain";
 /**
  * Source identifier for base map vector tiles.
  *
@@ -4424,7 +4450,7 @@ export declare const TRAFFIC_FLOW_SOURCE_ID = "vectorTilesFlow";
  *
  * Style-owned modules control sources and layers the map style already provides, under fixed
  * global IDs, so a second instance would be a second controller over one piece of shared state.
- * Callers get the same instance instead — two components each asking for hillshade is reasonable
+ * Callers get the same instance instead — two components each asking for the terrain is reasonable
  * code, and making them hoist a shared reference would be work pushed onto them for no benefit.
  *
  * @param map The map the module belongs to.
@@ -4717,7 +4743,7 @@ export type BaseMapEvents = CombinedEvents<MapGeoJSONFeature, BaseMapModuleConfi
  *
  * @remarks
  * **Managed Layers:**
- * - Background and terrain
+ * - Background and land cover
  * - Water bodies and coastlines
  * - Country and administrative borders
  * - Buildings (2D and 3D)
@@ -4728,7 +4754,7 @@ export type BaseMapEvents = CombinedEvents<MapGeoJSONFeature, BaseMapModuleConfi
  * **Does NOT Include:**
  * - Traffic flow/incidents (use {@link TrafficFlowModule} or {@link TrafficIncidentsModule})
  * - Points of Interest/POIs (use {@link POIsModule})
- * - Hillshade/terrain shading (use {@link HillshadeModule})
+ * - Hillshade and 3D terrain (use {@link TerrainModule})
  *
  * **Use Cases:**
  * - Toggle base map visibility on/off
@@ -6500,207 +6526,6 @@ export type ExtraGeometryDisplayProps = {
  */
 export type DisplayGeometryProps = CommonPlaceProps & ExtraGeometryDisplayProps;
 //#endregion
-//#region src/hillshade/HillshadeModule.d.ts
-/**
- * IDs of sources and layers for hillshade module.
- */
-type HillshadeSourcesWithLayers = {
-  hillshade: StyleSourceWithLayers;
-};
-/**
- * Map module for displaying terrain shading (hillshade).
- *
- * The HillshadeModule adds realistic terrain depth perception to the map by rendering
- * shadow and highlight effects based on elevation data. This enhances the 3D appearance
- * of mountainous and hilly terrain.
- *
- * @remarks
- * **Features:**
- * - Realistic terrain shading
- * - Uses vector tile elevation data
- * - Lightweight performance impact
- * - Seamlessly integrates with other map layers
- * - Toggle visibility on/off
- *
- * **Common Use Cases:**
- * - Outdoor recreation maps (hiking, skiing)
- * - Geographic/topographic applications
- * - Environmental visualization
- * - Landscape planning tools
- *
- * @example
- * ```typescript
- * // Create the module with hillshade visible
- * const hillshade = await HillshadeModule.getInstance(map, {
- *   visible: true
- * });
- *
- * // Toggle visibility
- * hillshade.setVisible(false);
- *
- * // Listen to events
- * hillshade.events.on('click', (feature, lngLat) => {
- *   console.log('Clicked hillshade at:', lngLat);
- * });
- * ```
- *
- * @see [Hillshade Guide](https://docs.tomtom.com/maps-sdk-js/guides/map/hillshade)
- *
- * @group Hillshade
- */
-export declare class HillshadeModule extends AbstractStyleOwnedMapModule<HillshadeSourcesWithLayers, HillshadeModuleConfig> {
-  /**
-   * Retrieves a HillshadeModule instance for the given map.
-   *
-   * @param map - The TomTomMap instance to attach this module to.
-   * @param config - Optional configuration for initialization and visibility.
-   *
-   * @returns A promise that resolves to the initialized HillshadeModule.
-   *
-   * @remarks
-   * **Configuration:**
-   * - `visible`: Initial visibility state
-   * - `ensureAddedToStyle`: Auto-add hillshade to style if missing
-   *
-   * **Style Requirement:**
-   * - Hillshade must be included in the map style or added via `ensureAddedToStyle`
-   * - Some styles may not support hillshade (e.g., satellite)
-   *
-   * @throws Error if hillshade source is not in style and `ensureAddedToStyle` is false
-   *
-   * @example
-   * Default initialization:
-   * ```typescript
-   * const hillshadeModule = await HillshadeModule.get(map);
-   * ```
-   *
-   * @example
-   * Auto-add to style if missing:
-   * ```typescript
-   * const hillshadeModule = await HillshadeModule.get(map, {
-   *   visible: true
-   * });
-   * ```
-   *
-   * @example
-   * Start hidden:
-   * ```typescript
-   * const hillshadeModule = await HillshadeModule.get(map, {
-   *   visible: false
-   * });
-   * ```
-   *
-   * @remarks
-   * **Instances:**
-   * `HillshadeModule` controls the hillshade source and layers the map style already provides,
-   * under fixed global IDs. Every instance is another handle on that same shared state, so
-   * visibility applied through one is visible through all of them.
-   */
-  static get(map: TomTomMap, config?: HillshadeModuleConfig): Promise<HillshadeModule>;
-  private constructor();
-  /**
-   * @ignore
-   */
-  protected _initSourcesWithLayers(): {
-    hillshade: StyleSourceWithLayers<import("maplibre-gl").SourceSpecification, import("maplibre-gl").Source>;
-  };
-  /**
-   * @ignore
-   */
-  protected _applyConfig(config: HillshadeModuleConfig | undefined): HillshadeModuleConfig | undefined;
-  /**
-   * Sets the visibility of the hillshade layer.
-   *
-   * @param visible - `true` to show hillshade, `false` to hide it.
-   *
-   * @remarks
-   * Changes are applied immediately if the map is ready.
-   *
-   * @example
-   * ```typescript
-   * hillshade.setVisible(true);  // Show terrain shading
-   * hillshade.setVisible(false); // Hide terrain shading
-   * ```
-   */
-  setVisible(visible: boolean): void;
-  private _setVisible;
-  /**
-   * Checks if the hillshade layer is currently visible.
-   *
-   * @returns `true` if visible, `false` if hidden.
-   *
-   * @example
-   * ```typescript
-   * if (hillshade.isVisible()) {
-   *   console.log('Terrain shading is active');
-   * }
-   * ```
-   */
-  isVisible(): boolean;
-  /**
-   * Gets the unified events interface for this module, covering both user interactions
-   * and module lifecycle events.
-   *
-   * **User interaction events** (`click`, `contextmenu`, `hover`, `long-hover`):
-   * ```typescript
-   * hillshade.events.on('click', (feature, lngLat) => {
-   *   console.log('Clicked terrain at:', lngLat);
-   * });
-   * ```
-   *
-   * **Module lifecycle events** (`config-change`):
-   * ```typescript
-   * const unsub = hillshade.events.on('config-change', (config) => {
-   *   console.log('Hillshade config changed:', config);
-   * });
-   * unsub();
-   * ```
-   */
-  get events(): CombinedEvents<import('maplibre-gl').MapGeoJSONFeature, HillshadeModuleConfig, never>;
-}
-//#endregion
-//#region src/hillshade/types/hillshadeModuleConfig.d.ts
-/**
- * Configuration options for the HillshadeModule.
- *
- * Controls the appearance and visibility of terrain shading on the map.
- *
- * @remarks
- * The HillshadeModule uses vector tile elevation data to create shadow/highlight
- * effects that enhance the 3D perception of terrain features like mountains and valleys.
- *
- * **Configuration Options:**
- * - `visible`: Whether the hillshade layer is shown or hidden
- *
- * **Visual Effect:**
- * - Creates realistic terrain depth perception
- * - Lightweight performance impact
- * - Works alongside other map layers
- *
- * @example
- * ```typescript
- * // Show hillshade
- * const config: HillshadeModuleConfig = {
- *   visible: true
- * };
- *
- * // Hide hillshade initially
- * const hiddenConfig: HillshadeModuleConfig = {
- *   visible: false
- * };
- * ```
- *
- * @group Hillshade
- */
-type HillshadeModuleConfig = MapModuleCommonConfig & {
-  /**
-   * Controls the visibility of the hillshade layers.
-   *
-   * @default false
-   */
-  visible?: boolean;
-};
-//#endregion
 //#region src/pois/util/poiCategoryMapping.d.ts
 /**
  * POI category mappings that have a direct equivalent in Map Display POI categories.
@@ -7497,7 +7322,7 @@ type PlaceConnectionsConfig = {
  *
  * @group Places
  */
-type PlacesModuleConfig = MapModuleCommonConfig & {
+type PlacesModuleConfig<P extends CommonPlaceProps = CommonPlaceProps> = MapModuleCommonConfig & {
   /**
    * Base style for all places.
    *
@@ -7580,10 +7405,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 +7493,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 +7515,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 +7626,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 +9014,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 +9280,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 +9344,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 +9369,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 +9397,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;
   /**
@@ -9646,17 +9435,80 @@ type SectionSignConfig = {
   unit?: SectionSignUnit;
 };
 /**
- * Appearance of one route section type.
+ * How a border crossing's plaque is turned on the map.
  *
- * @remarks
- * The semantic tier for sections: enough to draw, recolour, resize or mute any section type the
- * module draws, without writing a MapLibre layer spec — see {@link DrawnSectionType} for the
- * types, and `layers.sections` for anything these knobs cannot express.
+ * - `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.
  *
- * Which knobs a type takes is part of its type. `traffic` colours its line by `magnitudeOfDelay`
- * and takes its icons from the incident data, so `sections.traffic.color` does not compile rather
- * than compiling and drawing nothing. {@link sectionSupportsKnob} answers the same question at
- * runtime, for a UI that builds its controls from the type.
+ * @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.
+ *
+ * @remarks
+ * The semantic tier for sections: enough to draw, recolour, resize or mute any section type the
+ * module draws, without writing a MapLibre layer spec — see {@link DrawnSectionType} for the
+ * types, and `layers.sections` for anything these knobs cannot express.
+ *
+ * Which knobs a type takes is part of its type. `traffic` colours its line by `magnitudeOfDelay`
+ * and takes its icons from the incident data, so `sections.traffic.color` does not compile rather
+ * than compiling and drawing nothing. {@link sectionSupportsKnob} answers the same question at
+ * runtime, for a UI that builds its controls from the type.
  *
  * @example
  * ```typescript
@@ -9745,6 +9597,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 +9640,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 +10061,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 +10500,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 +10581,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 +10711,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 +10920,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 +10947,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;
@@ -11083,6 +11028,138 @@ type LayerSelector = {
   /** The layer id must contain none of these fragments (case-insensitive). */
   idExcludes?: string[];
 };
+/**
+ * The style's sources, for selectors that constrain the source type.
+ * @ignore
+ */
+type StyleSources = Record<string, {
+  type: 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", "hillshade-shadow-color", "hillshade-highlight-color", "hillshade-accent-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;
+    };
+  };
+};
+/**
+ * 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
 /**
@@ -11092,10 +11169,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 +11230,12 @@ 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.
    */
   available: boolean;
   /** Which styles the knob works on; see {@link stylingKnobAppliesTo}. */
@@ -11169,6 +11249,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 +11289,15 @@ 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' | 'hillshade-shadow-color' | 'hillshade-highlight-color' | 'hillshade-accent-color'>;
+/**
+ * Paint properties set as plain literals by the `paintLiteral` mechanism. Listed as values for the
+ * same reason as `paintColorProperties`.
+ * @ignore
+ */
+declare const literalPaintProperties: readonly ["hillshade-method", "hillshade-illumination-direction", "hillshade-exaggeration"];
+/** @ignore */
+type LiteralProperty = (typeof literalPaintProperties)[number];
 /**
  * How a knob reaches the style. A knob may use several (e.g. text and icon size together).
  * @ignore
@@ -11225,19 +11329,55 @@ type KnobMechanism =
   type: 'minZoom';
   layers: LayerSelector[];
 } |
+/** Sets the maximum zoom of the matched layers. */
+{
+  type: 'maxZoom';
+  layers: LayerSelector[];
+} |
+/** M2 — sets a paint property to the knob's value as a plain literal on the matched layers. */
+{
+  type: 'paintLiteral';
+  property: LiteralProperty;
+  layers: LayerSelector[];
+} |
 /** Shifts the `["-", ["zoom"], offset]` density term inside the matched layers' filters. */
 {
   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: 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 +11386,125 @@ type KnobDefinition = {
  * @ignore
  */
 declare const knobDefinitions: {
-  readonly 'labels.sizeFactor': KnobDefinition;
-  readonly 'symbols.sizeFactor': KnobDefinition;
-  readonly 'roads.widthFactor': KnobDefinition;
-  readonly 'pois.sizeFactor': KnobDefinition;
+  readonly 'hillshade.method': {
+    readonly kind: "enum";
+    readonly description: "How the relief is shaded: standard (one light), basic, igor (softer), combined, or multidirectional (four lights).";
+    readonly options: readonly ["standard", "basic", "igor", "combined", "multidirectional"];
+    readonly appliesTo: "tomtom-styles";
+    readonly mechanisms: [{
+      readonly type: "paintLiteral";
+      readonly property: "hillshade-method";
+      readonly layers: [LayerSelector];
+    }];
+  };
+  readonly 'hillshade.lightDirection': {
+    readonly kind: "number";
+    readonly description: "Direction the light comes from, in degrees clockwise from north (335 is the cartographic default).";
+    readonly range: {
+      readonly min: 0;
+      readonly max: 359;
+      readonly step: 1;
+    };
+    readonly appliesTo: "tomtom-styles";
+    readonly mechanisms: [{
+      readonly type: "paintLiteral";
+      readonly property: "hillshade-illumination-direction";
+      readonly layers: [LayerSelector];
+    }];
+  };
+  readonly 'hillshade.exaggeration': {
+    readonly kind: "number";
+    readonly description: "Strength of the shading (0 = flat). The standard styles ramp it to zero by zoom 13; setting it replaces the ramp with a constant.";
+    readonly range: {
+      readonly min: 0;
+      readonly max: 1;
+      readonly step: 0.05;
+    };
+    readonly appliesTo: "tomtom-styles";
+    readonly mechanisms: [{
+      readonly type: "paintLiteral";
+      readonly property: "hillshade-exaggeration";
+      readonly layers: [LayerSelector];
+    }];
+  };
+  readonly 'hillshade.maxZoom': {
+    readonly kind: "number";
+    readonly description: "Zoom level up to which the shading is drawn (the standard styles stop at 13; 22 keeps it at every zoom).";
+    readonly range: {
+      readonly min: 10;
+      readonly max: 22;
+      readonly step: 1;
+    };
+    readonly appliesTo: "tomtom-styles";
+    readonly mechanisms: [{
+      readonly type: "maxZoom";
+      readonly layers: [LayerSelector];
+    }];
+  };
+  readonly 'hillshade.shadowColor': KnobDefinitionOf<"color">;
+  readonly 'hillshade.highlightColor': KnobDefinitionOf<"color">;
+  readonly 'hillshade.accentColor': 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 "basemap.land": KnobDefinitionOf<"toggle">;
+  readonly "basemap.water": KnobDefinitionOf<"toggle">;
+  readonly "basemap.roads": KnobDefinitionOf<"toggle">;
+  readonly "basemap.railways": KnobDefinitionOf<"toggle">;
+  readonly "basemap.ferries": KnobDefinitionOf<"toggle">;
+  readonly "basemap.borders": KnobDefinitionOf<"toggle">;
+  readonly "basemap.natureLabels": KnobDefinitionOf<"toggle">;
+  readonly "basemap.roadLabels": KnobDefinitionOf<"toggle">;
+  readonly "basemap.roadShields": KnobDefinitionOf<"toggle">;
+  readonly "basemap.houseNumbers": KnobDefinitionOf<"toggle">;
+  readonly "basemap.smallerTownLabels": KnobDefinitionOf<"toggle">;
+  readonly "basemap.stateLabels": KnobDefinitionOf<"toggle">;
+  readonly "basemap.cityLabels": KnobDefinitionOf<"toggle">;
+  readonly "basemap.allPlaceLabels": KnobDefinitionOf<"toggle">;
+  readonly "basemap.capitalLabels": KnobDefinitionOf<"toggle">;
+  readonly "basemap.countryLabels": KnobDefinitionOf<"toggle">;
+  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 +11541,37 @@ 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">;
 };
 /**
  * The id of a styling knob — see {@link StylingModule.describe} for what each one does.
@@ -11320,7 +11585,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.
  *
@@ -11328,6 +11606,112 @@ type ValueOfKind<KIND extends StylingKnobKind> = KIND extends 'toggle' ? boolean
  */
 type StylingKnobValueOf<ID extends StylingKnobId> = ValueOfKind<(typeof knobDefinitions)[ID]['kind']>;
 //#endregion
+//#region src/styling/layerQuery.d.ts
+/**
+ * How {@link StylingModule.layers} picks style layers: by the SDK's base-map group taxonomy, layer
+ * type, vector-tile source layer and case-insensitive id fragments. Every constraint given must hold.
+ *
+ * @group Map Styling
+ */
+type LayerQuery = {
+  /** A base-map layer group, the same vocabulary as {@link BaseMapModule}. */
+  group?: BaseMapLayerGroupName;
+  /** The style's own `metadata.group` values, for groups the SDK does not name. */
+  metadataGroups?: string[];
+  /** Layer types (`line`, `fill`, `symbol`, …). */
+  layerTypes?: LayerSpecification['type'][];
+  /** Vector-tile source layers (`roads`, `places`, `poi`, …). */
+  sourceLayers?: string[];
+  /** The layer id must contain one of these (case-insensitive). */
+  idIncludes?: string[];
+  /** The layer id must contain none of these (case-insensitive). */
+  idExcludes?: string[];
+};
+type PropertyOverride = {
+  kind: 'paint' | 'layout';
+  property: string;
+  value: unknown;
+};
+/**
+ * The advanced tier of the styling module: raw MapLibre paint, layout and filter edits over a
+ * query of style layers, re-applied across style switches.
+ *
+ * @remarks
+ * **This is the version-coupled tier.** Layer ids, expressions and even which layers exist belong to
+ * the loaded style version, so an edit may match nothing on the next one: the selection is then empty
+ * and the SDK warns once. Prefer a knob or {@link StylingModule.setMapColors} where one fits.
+ *
+ * Overrides are not part of `getConfig()`: they are edits to this style, not portable settings.
+ *
+ * @example
+ * ```typescript
+ * styling.layers.query({ group: 'roadLabels' }).setPaint({ 'text-color': '#93c5fd' });
+ * styling.layers.query({ metadataGroups: ['water'], layerTypes: ['fill'] }).setPaint({ 'fill-opacity': 0.6 });
+ * styling.layers.query({ idIncludes: ['railway'] }).setVisible(false);
+ * styling.layers.query({ group: 'roadLabels' }).reset();
+ * ```
+ *
+ * @group Map Styling
+ */
+export declare class LayerSelection {
+  private readonly registry;
+  readonly query: LayerQuery;
+  /**
+   * @ignore
+   */
+  constructor(registry: LayerOverrides, query: LayerQuery);
+  /**
+   * The ids of the layers the query matches in the loaded style, in draw order. Empty when the
+   * style has no such layers.
+   */
+  get layerIds(): string[];
+  /** Sets paint properties on every matched layer. */
+  setPaint(paint: Partial<AllPaintProperties>): this;
+  /** Sets layout properties on every matched layer. */
+  setLayout(layout: Partial<AllLayoutProperties>): this;
+  /**
+   * Replaces the filter the style gave every matched layer. The filters other modules add, such as
+   * POI categories and traffic filters, still narrow it.
+   */
+  setFilter(filter: FilterSpecification | undefined): this;
+  /** Shows or hides every matched layer. */
+  setVisible(visible: boolean): this;
+  /** Removes every override made through the styling module on the matched layers. */
+  reset(): this;
+}
+/**
+ * The styling module's registry of raw layer overrides: resolves queries against the loaded style,
+ * applies overrides, remembers what each property was before, and re-applies after a style switch.
+ * Filters go through the map's {@link LayerFilterComposer}, which holds the style's own filter.
+ * @ignore
+ */
+declare class LayerOverrides {
+  private readonly mapLibreMap;
+  private readonly filterComposer;
+  private readonly warn;
+  private layers;
+  private sources;
+  private readonly properties;
+  private readonly filters;
+  constructor(mapLibreMap: Map, filterComposer: LayerFilterComposer, warn: (key: string, message: string) => void);
+  /** Points the registry at a freshly loaded style; overrides are kept and re-applied by {@link reapply}. */
+  index(layers: LayerSpecification[], sources: StyleSources): void;
+  /** Forgets every override (a clean style switch, which also clears the filter composer). */
+  clear(): void;
+  resolve(query: LayerQuery): string[];
+  override(query: LayerQuery, override: PropertyOverride): void;
+  overrideFilter(query: LayerQuery, filter: FilterSpecification | undefined): void;
+  reset(query: LayerQuery): void;
+  /**
+   * Lands every override again on top of the current style. What an override replaces is re-read
+   * only where something else wrote under it since (a new style, or a knob on the same property);
+   * a layer still carrying the override keeps the value it replaced.
+   */
+  reapply(): void;
+  private read;
+  private write;
+}
+//#endregion
 //#region src/styling/StylingModule.d.ts
 /**
  * Event surface of {@link StylingModule}: it owns no map features, so only the lifecycle half is
@@ -11385,10 +11769,17 @@ 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;
+  private layerOverrides;
   /**
    * Retrieves the styling module of the given map, creating it on first use.
    *
@@ -11420,6 +11811,23 @@ export declare class StylingModule extends AbstractStyleOwnedMapModule<Record<st
    * @ignore
    */
   protected _applyConfig(settings: StylingSettings | undefined): StylingSettings | undefined;
+  /**
+   * @ignore
+   */
+  protected discardShownData(): void;
+  /**
+   * The advanced tier: raw MapLibre paint, layout and filter edits over a query of style layers,
+   * re-applied across style switches. Version-coupled by nature — see {@link LayerSelection} for
+   * the terms — so prefer a knob or {@link setMapColors} wherever one covers the intent.
+   *
+   * @example
+   * ```typescript
+   * styling.layers.query({ group: 'roadLabels' }).setPaint({ 'text-color': '#93c5fd' });
+   * ```
+   */
+  get layers(): {
+    query: (query: LayerQuery) => LayerSelection;
+  };
   /**
    * The styling catalogue for the loaded style: every knob with its kind, range, default, current
    * value and how many layers it reaches.
@@ -11435,6 +11843,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`). 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 +11906,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,21 +11953,167 @@ export declare class StylingModule extends AbstractStyleOwnedMapModule<Record<st
   private resolveMechanism;
   private capture;
   private originalValueOf;
+  private resolveMapColor;
   private refreshKnob;
   private refreshMechanism;
+  private refreshLayer;
+  private refreshSpace;
+  private defaultSpaceColor;
+  private refreshMapColorProperty;
+  private refreshProjection;
+  private refreshSky;
   private refreshVisibility;
-  private refreshMinZoom;
+  private refreshZoomBound;
+  private styleZoomBound;
   private refreshZoomOffset;
   private refreshScaledProperty;
   private refreshColor;
   private setProperty;
   private describeKnob;
   private defaultOf;
+  private mapLevelDefaultOf;
   private assertKnob;
   private validate;
   private warnOnce;
 }
 //#endregion
+//#region src/terrain/types/terrainModuleConfig.d.ts
+/**
+ * Configuration of the {@link TerrainModule}: the two ways it draws the relief of the style's
+ * elevation data.
+ *
+ * @remarks
+ * Unset, the hillshade is hidden like the other style parts the SDK adds (traffic flow and
+ * incidents), and the surface is left as the map draws it: flat on TomTom styles. So
+ * `resetConfig()` returns a TomTom style to flat and unshaded.
+ *
+ * @example
+ * ```typescript
+ * const config: TerrainModuleConfig = { hillshade: true, elevation: true, elevationExaggeration: 1.5 };
+ * ```
+ *
+ * @group Terrain
+ */
+type TerrainModuleConfig = MapModuleCommonConfig & {
+  /**
+   * Shows the hillshade: light and shadow on the map surface that reveal hills, valleys and
+   * mountains, at any camera pitch. Its look is set by the `hillshade.*` knobs of {@link StylingModule}.
+   *
+   * @default false
+   */
+  hillshade?: boolean;
+  /**
+   * Raises the map surface to the elevation data in 3D, or flattens it. Shows best with a
+   * pitched camera.
+   *
+   * @default The map's own terrain, if its style or MapLibre code raised one; none on TomTom styles.
+   */
+  elevation?: boolean;
+  /**
+   * Vertical scaling of the 3D surface: `1` is true elevation, higher values emphasise the
+   * relief. Kept while `elevation` is off, so turning it back on restores it.
+   *
+   * @default 1
+   */
+  elevationExaggeration?: number;
+};
+//#endregion
+//#region src/terrain/TerrainModule.d.ts
+/**
+ * The style source this module draws from: the raster-dem elevation source of the hillshade
+ * style part, with its hillshade layers.
+ */
+type TerrainSourcesWithLayers = {
+  hillshade: StyleSourceWithLayers;
+};
+/**
+ * Map module for the terrain relief: hillshade shading and the 3D surface, both drawn from the
+ * elevation data of the map style.
+ *
+ * @remarks
+ * - **Hillshade** shades slopes on the flat map, so the relief reads at any pitch.
+ * - **Elevation** raises the map surface in 3D, which a pitched camera shows. Combined with the
+ *   hillshade, a slope stays readable where the camera flattens it.
+ *
+ * `get()` adds the elevation style part when the style lacks it, and the module restores both
+ * after every style change. The 3D surface reads its own copy of the elevation source,
+ * {@link TERRAIN_SOURCE_ID}.
+ *
+ * @example
+ * ```typescript
+ * const terrain = await TerrainModule.get(map, { hillshade: true, elevation: true, elevationExaggeration: 1.3 });
+ * terrain.setElevationExaggeration(2);
+ * terrain.setElevationEnabled(false); // flat again, still shaded
+ * ```
+ *
+ * @see [Terrain Guide](https://docs.tomtom.com/maps-sdk-js/guides/map/terrain)
+ *
+ * @group Terrain
+ */
+export declare class TerrainModule extends AbstractStyleOwnedMapModule<TerrainSourcesWithLayers, TerrainModuleConfig> {
+  private mapTerrain;
+  private overridesMapTerrain;
+  /**
+   * Retrieves the terrain module of the given map, adding the elevation style part first when
+   * the style lacks it.
+   *
+   * @param config - Without it the hillshade is hidden, and the surface stays as the map draws it.
+   *
+   * @remarks
+   * **Instances:** one per map — a second `get()` returns the same instance, with the given config
+   * applied to it.
+   *
+   * @throws Error if the elevation source cannot be added to the style.
+   */
+  static get(map: TomTomMap, config?: TerrainModuleConfig): Promise<TerrainModule>;
+  private constructor();
+  /**
+   * @ignore
+   */
+  protected _initSourcesWithLayers(): {
+    hillshade: StyleSourceWithLayers<import("maplibre-gl").SourceSpecification, import("maplibre-gl").Source>;
+  };
+  /**
+   * @ignore
+   */
+  protected _applyConfig(config: TerrainModuleConfig | undefined): TerrainModuleConfig | undefined;
+  /**
+   * Shows or hides the hillshade shading.
+   */
+  setHillshadeVisible(visible: boolean): void;
+  /**
+   * Whether the hillshade shading is shown.
+   */
+  isHillshadeVisible(): boolean;
+  /**
+   * Raises the map surface in 3D, or flattens it, keeping the configured exaggeration.
+   */
+  setElevationEnabled(enabled: boolean): void;
+  /**
+   * Whether the map surface is raised in 3D.
+   */
+  isElevationEnabled(): boolean;
+  /**
+   * Sets the vertical {@link TerrainModuleConfig.elevationExaggeration | exaggeration} of the 3D
+   * surface, kept for when elevation is enabled later.
+   */
+  setElevationExaggeration(elevationExaggeration: number): void;
+  /**
+   * Lifecycle events of this module. The hillshade is a raster layer with no features to
+   * interact with, so there are no user interaction events; `config-change` fires after every
+   * change.
+   *
+   * @example
+   * ```typescript
+   * const unsubscribe = terrain.events.on('config-change', (config) => console.log(config));
+   * ```
+   */
+  get events(): ModuleEvents<TerrainModuleConfig>;
+  private showHillshade;
+  private showElevation;
+  private storeConfig;
+}
+//#endregion
 //#region src/traffic/types/trafficAreaAnalyticsConfig.d.ts
 /**
  * A single stop in an analytics color ramp.
@@ -11783,6 +12391,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 +12422,16 @@ declare const AREA_ANALYTICS_DEFAULTS: {
     congestionLevel: {
       color: {
         valueType: "raw";
-        stops: {
+        stops: ({
           value: number;
-          color: string;
-        }[];
+          color: "#2dc653";
+        } | {
+          value: number;
+          color: "#f5a623";
+        } | {
+          value: number;
+          color: "#e03030";
+        })[];
       };
       height: {
         maxHeightMeters: number;
@@ -11817,10 +12442,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 +12462,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 +12482,16 @@ declare const AREA_ANALYTICS_DEFAULTS: {
     freeFlowSpeed: {
       color: {
         valueType: "relativeToPredefinedRangePCT";
-        stops: {
+        stops: ({
           value: number;
-          color: string;
-        }[];
+          color: "#e03030";
+        } | {
+          value: number;
+          color: "#f5a623";
+        } | {
+          value: number;
+          color: "#2dc653";
+        })[];
       };
       height: {
         maxHeightMeters: number;
@@ -11859,10 +12502,16 @@ declare const AREA_ANALYTICS_DEFAULTS: {
     networkLength: {
       color: {
         valueType: "relativeToActualRangePCT";
-        stops: {
+        stops: ({
+          value: number;
+          color: "#2dc653";
+        } | {
           value: number;
-          color: string;
-        }[];
+          color: "#f5a623";
+        } | {
+          value: number;
+          color: "#e03030";
+        })[];
       };
       height: {
         maxHeightMeters: number;
@@ -12077,6 +12726,7 @@ export declare class TrafficAreaAnalyticsModule extends AbstractDataOwnedMapModu
   protected _initSourcesWithLayers(config?: TrafficAreaAnalyticsConfig, _restore?: boolean): AreaAnalyticsSourcesWithLayers;
   /** @ignore */
   protected _applyConfig(config: TrafficAreaAnalyticsConfig | undefined): TrafficAreaAnalyticsConfig | undefined;
+  private moveLayersToSpecPositions;
   /** @ignore */
   protected discardShownData(): void;
   /** @ignore */
@@ -13584,6 +14234,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 +14328,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, HoverEventType, IncidentFocusStyle, LayerQuery, 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, TerrainModuleConfig, ToBeAddedLayerSpec, ToBeAddedLayerSpecTemplate, ToBeAddedLayerSpecWithoutSource, TrafficAreaAnalyticsConfig, TrafficIncidentOverlayConfig, UserEventHandler, ValuesFilter, WaypointsConfig };