@tomtom-org/maps-sdk 0.56.0 → 0.57.0

package/map/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { BackgroundLayerSpecification, CircleLayerSpecification, DataDrivenPropertyValueSpecification, ExpressionFilterSpecification, ExpressionSpecification, GeoJSONSource, GeoJSONSourceSpecification, LayerSpecification, LineLayerSpecification, LngLat, Map, MapGeoJSONFeature, MapOptions, Source, SourceSpecification, StyleImageInterface, StyleImageMetadata, StyleSpecification, SymbolLayerSpecification } from "maplibre-gl";
+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
 /**
@@ -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
@@ -432,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
  */
@@ -577,7 +577,6 @@ export type TomTomMapParams = Partial<GlobalConfig> & {
    *   zoom: 12,
    *   pitch: 45,
    *   bearing: -17.6,
-   *   antialias: true,
    *   maxZoom: 18,
    *   minZoom: 8
    * }
@@ -944,7 +943,6 @@ export declare class TomTomMap {
    *     zoom: 13,
    *     pitch: 45,
    *     bearing: -17.6,
-   *     antialias: true,
    *     maxZoom: 18,
    *     minZoom: 8
    *   }
@@ -3844,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
@@ -3860,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.
@@ -4003,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
@@ -4065,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.
@@ -4372,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.
  *
@@ -4418,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.
@@ -4711,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)
@@ -4722,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
@@ -6494,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.
@@ -11197,6 +11028,13 @@ 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
 /**
@@ -11236,7 +11074,7 @@ type MapColors = Partial<Record<MapColorName, string>>;
  * `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"];
+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];
 /**
@@ -11309,15 +11147,6 @@ declare const stylingPresets: {
       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}.
@@ -11406,8 +11235,7 @@ type StylingKnobDescriptor = KnobDescriptor & {
   /**
    * Whether the knob has anything to work on in the loaded style. `false` means setting it would
    * 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.
+   * 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}. */
@@ -11461,7 +11289,15 @@ type StylingSettings = MapModuleCommonConfig & { [K in StylingKnobId]?: StylingK
 /** @ignore */
 type ScalableProperty = 'text-size' | 'icon-size' | 'line-width';
 /** @ignore */
-type ColorProperty = Extract<PaintColorProperty, '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
@@ -11493,6 +11329,17 @@ 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';
@@ -11506,10 +11353,6 @@ type KnobMechanism =
 {
   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';
@@ -11543,6 +11386,121 @@ type KnobDefinitionOf<KIND extends StylingKnobKind> = KnobDefinition & {
  * @ignore
  */
 declare const knobDefinitions: {
+  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">;
@@ -11614,68 +11572,6 @@ declare const knobDefinitions: {
   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.
@@ -11710,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
@@ -11777,6 +11779,7 @@ export declare class StylingModule extends AbstractStyleOwnedMapModule<Record<st
   private warned;
   private reindexed;
   private originalSpaceColor;
+  private layerOverrides;
   /**
    * Retrieves the styling module of the given map, creating it on first use.
    *
@@ -11808,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.
@@ -11825,7 +11845,7 @@ 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
+   * (`data-viz`, `night-driving`, `minimal`, `globe`). See `describe().presets` for
    * what each one sets.
    *
    * @param id - The preset to apply.
@@ -11934,17 +11954,17 @@ export declare class StylingModule extends AbstractStyleOwnedMapModule<Record<st
   private capture;
   private originalValueOf;
   private resolveMapColor;
-  private demSourceId;
   private refreshKnob;
   private refreshMechanism;
+  private refreshLayer;
   private refreshSpace;
   private defaultSpaceColor;
   private refreshMapColorProperty;
   private refreshProjection;
   private refreshSky;
-  private refreshTerrain;
   private refreshVisibility;
-  private refreshMinZoom;
+  private refreshZoomBound;
+  private styleZoomBound;
   private refreshZoomOffset;
   private refreshScaledProperty;
   private refreshColor;
@@ -11957,6 +11977,143 @@ export declare class StylingModule extends AbstractStyleOwnedMapModule<Record<st
   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.
@@ -12569,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 */
@@ -14170,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, 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 };
+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 };