@tomtom-org/maps-sdk 0.56.0 → 0.58.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, 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";
+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, EntryPoint, 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.
@@ -27,7 +27,8 @@ type LightDark = 'light' | 'dark';
  *   precisionMode: 'box',
  *   paddingBoxPx: 5,
  *   cursorOnHover: 'pointer',
- *   longHoverDelayOnStillMapMS: 300
+ *   longHoverDelayOnStillMapMS: 300,
+ *   hoverGracePeriodMS: 400
  * };
  *
  * // Mobile-optimized with larger hit area
@@ -46,7 +47,7 @@ type LightDark = 'light' | 'dark';
  *
  * @group User Interaction Events
  */
-type MapEventsConfig = EventHandlerCursorConfig & {
+type MapEventsConfig = EventHandlerConfig & {
   /**
    * Optional configuration to show custom cursor when clicking (mouse down).
    *
@@ -311,7 +312,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 +433,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
  */
@@ -547,20 +548,12 @@ export type TomTomMapParams = Partial<GlobalConfig> & {
    */
   style?: StyleInput;
   /**
-   * Event handler configuration for map interactions.
-   *
-   * Define callbacks for various map events like clicks, hovers, and movements.
+   * How user events are detected and timed, and which cursors they show, for every module.
+   * Change it later with {@link TomTomMap.updateEventsConfig}.
    *
    * @example
    * ```typescript
-   * events: {
-   *   onClick: (event) => {
-   *     console.log('Clicked at', event.lngLat);
-   *   },
-   *   onMoveEnd: () => {
-   *     console.log('Map moved to', map.getCenter());
-   *   }
-   * }
+   * events: { paddingBoxPx: 10, longHoverDelayOnStillMapMS: 500, hoverGracePeriodMS: 1000 }
    * ```
    */
   events?: MapEventsConfig;
@@ -577,7 +570,6 @@ export type TomTomMapParams = Partial<GlobalConfig> & {
    *   zoom: 12,
    *   pitch: 45,
    *   bearing: -17.6,
-   *   antialias: true,
    *   maxZoom: 18,
    *   minZoom: 8
    * }
@@ -944,7 +936,6 @@ export declare class TomTomMap {
    *     zoom: 13,
    *     pitch: 45,
    *     bearing: -17.6,
-   *     antialias: true,
    *     maxZoom: 18,
    *     minZoom: 8
    *   }
@@ -1163,6 +1154,22 @@ export declare class TomTomMap {
    * @see {@link https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes | ISO 639-1 Language Codes}
    */
   setLanguage(language: Language): void;
+  /**
+   * Changes the map's user events configuration at runtime.
+   *
+   * @param config Merged into the current configuration, set at construction through
+   * {@link TomTomMapParams.events}: what it leaves out, or sets `undefined`, keeps its value.
+   *
+   * @remarks
+   * A module's own `events` config still overrides the cursor and `hoverGracePeriodMS` for its
+   * features. A long hover or a grace period already running keeps the delay it started with.
+   *
+   * @example
+   * ```typescript
+   * map.updateEventsConfig({ longHoverDelayOnStillMapMS: 600, hoverGracePeriodMS: 1000 });
+   * ```
+   */
+  updateEventsConfig(config: MapEventsConfig): void;
   /**
    * Retrieves the current visible map area as a GeoJSON bounding box.
    *
@@ -1779,8 +1786,13 @@ export type GeoJSONSourceClusterOptions = Pick<GeoJSONSourceSpecification, 'clus
  */
 export declare class GeoJSONSourceWithLayers<T extends FeatureCollection = FeatureCollection> extends AddedSourceWithLayers<GeoJSONSourceSpecification, GeoJSONSource> {
   shownFeatures: T;
+  private readonly showListeners;
   constructor(map: Map, sourceId: string, layerSpecs: ToBeAddedLayerSpecWithoutSource[], addLayersToMap?: boolean, clusterOptions?: GeoJSONSourceClusterOptions);
   show(featureCollection: T, { automaticVisibility }?: ShowOptions): void;
+  /**
+   * Calls `listener` after every `show`, including the ones an event-state change makes.
+   */
+  onShow(listener: () => void): void;
   /**
    * Canonical id-based lookup into `shownFeatures.features` via {@link findFeatureByRefId}
    * (first match wins on duplicate ids). Returns `undefined` for a nullish or absent id.
@@ -2061,6 +2073,18 @@ type HoverEventType = 'hover' | 'hover-move' | 'long-hover';
  * @group User Interaction Events
  */
 type EventType = ClickEventType | HoverEventType;
+/**
+ * The state a feature carries in `properties.eventState`: the user event it is in, or
+ * `recently-hovered` for a moment after the pointer leaves it.
+ *
+ * @remarks
+ * `recently-hovered` lasts {@link EventHandlerHoverConfig.hoverGracePeriodMS}, then clears on its own
+ * unless the feature is hovered or clicked again first. The SDK's own layers draw it as no state;
+ * read it to keep something shown while the pointer travels, as the entry points of places do.
+ *
+ * @group User Interaction Events
+ */
+type EventState = EventType | 'recently-hovered';
 /**
  * Parameters to identify a feature by its ID or index in a given features array.
  * @group User Interaction Events
@@ -2241,7 +2265,7 @@ type CleanEventStatesOptions = {
    * states: ['click', 'contextmenu', 'hover', 'long-hover']
    * ```
    */
-  states?: EventType[];
+  states?: EventState[];
   /**
    * Whether to show the feature after cleaning the event state.
    *
@@ -2288,11 +2312,12 @@ type SupportsEvents = {
    * @remarks
    * - `undefined`: No active event state (normal appearance)
    * - Event type: Active state that affects styling and behavior
+   * - `recently-hovered`: The pointer just left the feature; see {@link EventState}
    *
    * This property is automatically managed by the SDK based on user
    * interactions and programmatic state changes.
    */
-  eventState?: EventType;
+  eventState?: EventState;
 };
 /**
  * Handler function for user interaction events on map features.
@@ -2389,103 +2414,66 @@ type EventHandlerCursorConfig = {
    */
   cursorOnHover?: CSSCursor;
 };
+/**
+ * Event configuration options related to hover states.
+ *
+ * @group User Interaction Events
+ */
+type EventHandlerHoverConfig = {
+  /**
+   * How long, in milliseconds, a feature stays `recently-hovered` after the pointer leaves it.
+   * `0` clears its state at once.
+   *
+   * @remarks
+   * Set on the map (`events` of the map parameters) for every module, or on one module's
+   * `events` config to override it there.
+   *
+   * @default 400
+   */
+  hoverGracePeriodMS?: number;
+};
 /**
  * Optional events configuration for a map module.
  *
  * @group User Interaction Events
  */
-type EventHandlerConfig = EventHandlerCursorConfig;
+type EventHandlerConfig = EventHandlerCursorConfig & EventHandlerHoverConfig;
 //#endregion
 //#region src/shared/types/filters.d.ts
 /**
- * Filter mode determining whether to include or exclude specified values.
- *
- * @remarks
- * Controls how the values list is interpreted:
- * - `all_except`: Show everything except the specified values (exclusion mode)
- * - `only`: Show only the specified values, hide everything else (inclusion mode)
- *
- * @example
- * ```typescript
- * // Exclusion mode
- * const mode: FilterShowMode = 'all_except';
- *
- * // Inclusion mode
- * const mode: FilterShowMode = 'only';
- * ```
+ * Every {@link FilterShowMode}, for validating one at runtime.
  *
  * @group Shared
  */
-type FilterShowMode = 'all_except' | 'only';
+export declare const filterShowModes: readonly ["only", "all-except"];
 /**
- * Generic filter configuration for showing or hiding items by value.
- *
- * Provides a flexible way to control visibility of categorized items (e.g., POI categories,
- * layer groups, road types) using either inclusion or exclusion mode.
- *
- * @typeParam T - The type of values being filtered (e.g., string literals, enums)
+ * How a {@link ValuesFilter} reads its `values`:
+ * - `only`: show only these values, hide everything else
+ * - `all-except`: show everything except these values
  *
- * @remarks
- * **Filter Modes:**
- * - `only`: Whitelist mode - only specified values are shown
- * - `all_except`: Blacklist mode - all values except specified ones are shown
+ * @group Shared
+ */
+export type FilterShowMode = (typeof filterShowModes)[number];
+/**
+ * Shows or hides items by value — POI categories, traffic road categories, incident magnitudes.
  *
- * **Common Use Cases:**
- * - Filtering POI categories (show only restaurants)
- * - Hiding map layer groups (hide all except roads)
- * - Filtering traffic incidents by type
- * - Controlling road categories in traffic flow
+ * @typeParam T - The type of values being filtered
  *
  * @example
  * ```typescript
- * // Show only specific categories
- * const includeFilter: ValuesFilter<string> = {
- *   show: 'only',
- *   values: ['RESTAURANT', 'CAFE', 'BAR']
- * };
+ * // Show only these categories
+ * const includeFilter: ValuesFilter<string> = { show: 'only', values: ['RESTAURANT', 'CAFE', 'BAR'] };
  *
- * // Hide specific categories
- * const excludeFilter: ValuesFilter<string> = {
- *   show: 'all_except',
- *   values: ['PARKING_GARAGE']
- * };
- *
- * // Type-safe with string literals
- * type RoadType = 'motorway' | 'trunk' | 'primary';
- * const roadFilter: ValuesFilter<RoadType> = {
- *   show: 'only',
- *   values: ['motorway', 'trunk']
- * };
+ * // Hide these categories
+ * const excludeFilter: ValuesFilter<string> = { show: 'all-except', values: ['PARKING_GARAGE'] };
  * ```
  *
  * @group Shared
  */
-type ValuesFilter<T> = {
-  /**
-   * Filter mode determining whether values list is inclusive or exclusive.
-   *
-   * @remarks
-   * - `only`: Shows only the items in the values array (whitelist)
-   * - `all_except`: Shows all items except those in the values array (blacklist)
-   */
+export type ValuesFilter<T> = {
+  /** Whether `values` is the set to show or the set to hide. */
   show: FilterShowMode;
-  /**
-   * Array of values to include or exclude based on the show mode.
-   *
-   * @remarks
-   * The interpretation of this array depends on the `show` property:
-   * - If `show` is `'only'`, only these values will be visible
-   * - If `show` is `'all_except'`, these values will be hidden
-   *
-   * @example
-   * ```typescript
-   * // Include only these values
-   * values: ['RESTAURANT', 'HOTEL']
-   *
-   * // Exclude these values
-   * values: ['PARKING']
-   * ```
-   */
+  /** The values to show or hide, depending on `show`. */
   values: T[];
 };
 //#endregion
@@ -2537,9 +2525,9 @@ type CustomImage<I extends string = string> = {
    *
    * This ID is used to reference the icon when styling map features.
    * The specific values depend on the context:
-   * - For POI categories: Use MapStylePOICategory values (e.g., 'RESTAURANT', 'HOTEL_MOTEL')
+   * - For POI categories: Use MapStylePOICategory values (e.g., 'RESTAURANT', 'HOTEL_OR_MOTEL')
    * - For route waypoints: Use waypoint identifiers (e.g., 'waypoint-start', 'waypoint-end')
-   * - For charging stations: Use station type identifiers (e.g., 'ELECTRIC_VEHICLE_STATION')
+   * - For charging stations: Use station type identifiers (e.g., 'CHARGING_LOCATION')
    * - For custom markers: Use any unique string identifier
    */
   id: I;
@@ -2607,12 +2595,12 @@ type CustomImage<I extends string = string> = {
    * // Define custom icons for both availability states
    * categoryIcons: [
    *   {
-   *     id: 'ELECTRIC_VEHICLE_STATION',
+   *     id: 'CHARGING_LOCATION',
    *     image: greenChargingSVG,
    *     availabilityLevel: 'available'
    *   },
    *   {
-   *     id: 'ELECTRIC_VEHICLE_STATION',
+   *     id: 'CHARGING_LOCATION',
    *     image: redChargingSVG,
    *     availabilityLevel: 'occupied'
    *   }
@@ -3092,14 +3080,20 @@ export declare class EventsProxy extends AbstractEventProxy {
   private hoveringFeatures?;
   private hoveringSourceWithLayers?;
   private longHoverTimeoutHandlerID?;
+  private readonly recentHoverTimeouts;
   private firstDelayedHoverSinceMapMove;
   private lastClickedFeature?;
   private lastClickedSourceWithLayers?;
   private lastCursorStyle;
   private pendingMouseMove?;
   private mouseMoveFrameRequested;
-  private readonly config;
+  private config;
   constructor(map: Map, config?: MapEventsConfig);
+  /**
+   * Merges `config` into the current configuration; what it leaves out, or sets `undefined`,
+   * keeps its value. Timers already running keep the delay they started with.
+   */
+  updateConfig(config: MapEventsConfig): void;
   private listenToEvents;
   enable(enabled: boolean): void;
   private toPaddedBounds;
@@ -3145,6 +3139,8 @@ export declare class EventsProxy extends AbstractEventProxy {
   private dispatchHoverEnter;
   private dispatchHoverMove;
   private dispatchToHandlers;
+  private hoverGracePeriodFor;
+  private clearRecentHoverLater;
   private updateHoverCursor;
   private onMapClick;
 }
@@ -3844,8 +3840,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 +3855,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 +4017,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 +4085,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.
@@ -4090,9 +4110,8 @@ export declare abstract class AbstractStyleOwnedMapModule<SOURCES_WITH_LAYERS ex
  * The kind of value a display knob takes.
  *
  * @remarks
- * One vocabulary for every knob catalogue in the SDK — map styling and any module that describes
- * its display as knobs draw from the same set, so an agent that learned one catalogue can read the
- * other.
+ * One vocabulary for every knob catalogue in the SDK and its plugins, so a UI or an agent that
+ * learned one catalogue can read the other.
  *
  * - `toggle`: `true`/`false`, e.g. whether an overlay is drawn.
  * - `factor`: a multiplier over what the style already does (`1` = unchanged).
@@ -4115,77 +4134,6 @@ export type KnobRange = {
   max: number;
   step?: number;
 };
-/**
- * A single, machine-readable description of one display knob.
- *
- * @remarks
- * The point of describing knobs as data is that a caller — increasingly a coding agent rather than
- * a person reading docs — can ask what a module actually exposes instead of guessing layer ids from
- * training data. Three things follow from having it:
- *
- * - **ground before generating** — write against what the module exposes, not what you remember;
- * - **validate** — ranges and allowed values arrive as data, so a bad value is caught before it
- *   is rendered;
- * - **report and diff** — the paired settings object is plain and serializable, so a display change
- *   is reviewable in a pull request.
- *
- * A visual editor cannot do any of those: it cannot be read, diffed, or put in a pull request.
- *
- * Modules narrow this shape with their own descriptor type — e.g. `StylingKnobDescriptor` requires
- * `available` and `appliesTo`, while a module whose knobs are always applicable omits them.
- *
- * @group Shared
- */
-export type KnobDescriptor<T = unknown> = {
-  /**
-   * Stable, dotted identifier, e.g. `labels.sizeFactor`. Treat these as public API: they are what
-   * a caller stores, diffs and passes back.
-   */
-  id: string;
-  /** What kind of value the knob takes. */
-  kind: KnobKind;
-  /** One-line description of what turning this knob does. */
-  description: string;
-  /** The value in force when nothing has been configured. */
-  default: T;
-  /** The value in force now. */
-  current: T;
-  /** Whether {@link KnobDescriptor.current} came from configuration rather than the default. */
-  overridden: boolean;
-  /** Inclusive bounds, for `factor` and `number` knobs. */
-  range?: KnobRange;
-  /** 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
-   * are always applicable; set to `false` by modules where a knob can be present in the catalogue
-   * but do nothing on the current style.
-   */
-  available?: boolean;
-  /**
-   * Which styles or contexts the knob works in. A string rather than a fixed union so each
-   * module can choose its own vocabulary — styling uses `'any-style' | 'tomtom-styles'`.
-   */
-  appliesTo?: string;
-};
-/**
- * Builds one knob descriptor, working out `overridden` from whether a configured value was given.
- * Pass `available` / `appliesTo` / `range` / `options` through `extra` when the module uses them.
- * @ignore
- */
-export declare const knob: <T, ID extends string, KIND extends KnobKind, Extra extends object = Record<string, never>>(id: ID, kind: KIND, description: string, defaultValue: T, configured: T | undefined, extra?: Extra) => KnobDescriptor<T> & {
-  id: ID;
-  kind: KIND;
-} & Extra;
-/**
- * Reduces a knob catalogue to a plain, serializable object of the values in force.
- *
- * @remarks
- * Only knobs whose value was configured are included, so the result is a diff against the defaults
- * rather than a dump of everything — which is what makes it reviewable.
- * @ignore
- */
-export declare const knobSettings: (knobs: KnobDescriptor[]) => Record<string, unknown>;
 //#endregion
 //#region src/shared/layers/commonLayerProps.d.ts
 /**
@@ -4372,15 +4320,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 +4376,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.
@@ -4710,8 +4668,12 @@ export type BaseMapEvents = CombinedEvents<MapGeoJSONFeature, BaseMapModuleConfi
  * buildings, labels, and other vector tile layers from the base map style.
  *
  * @remarks
+ * **What this module owns:** whether each base-map layer group is shown. How the base map looks is
+ * {@link StylingModule} knobs, whose `basemap.<group>` and `buildings.*` toggles switch the same groups.
+ * See [Who owns what](https://docs.tomtom.com/maps-sdk-js/guides/map/modules#who-owns-what).
+ *
  * **Managed Layers:**
- * - Background and terrain
+ * - Background and land cover
  * - Water bodies and coastlines
  * - Country and administrative borders
  * - Buildings (2D and 3D)
@@ -4722,7 +4684,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
@@ -6190,18 +6152,12 @@ export declare class GeometriesModule extends AbstractDataOwnedMapModule<Geometr
    * ```
    *
    * @example
-   * From search API response:
+   * From a place's geometry:
    * ```typescript
-   * import { search } from '@tomtom-org/maps-sdk/services';
-   *
-   * const result = await search.geometrySearch({
-   *   query: 'Amsterdam',
-   *   geometryList: [{ type: 'CIRCLE', position: [52.37, 4.89], radius: 5000 }]
-   * });
+   * import { geocodeOne, geometryData } from '@tomtom-org/maps-sdk/services';
    *
-   * if (result.results[0].dataSources?.geometry) {
-   *   await geometries.show(result.results[0].dataSources.geometry);
-   * }
+   * const amsterdam = await geocodeOne('Amsterdam');
+   * await geometries.show(await geometryData({ geometries: [amsterdam] }));
    * ```
    */
   show(geometries: PolygonFeatures): Promise<void>;
@@ -6494,207 +6450,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.
@@ -6892,20 +6647,59 @@ export type PlaceDisplayProps = {
  */
 export type DisplayPlaceProps = CommonPlaceProps & PlaceDisplayProps;
 //#endregion
-//#region src/places/types/placesModuleConfig.d.ts
+//#region src/places/types/entryPointDisplay.d.ts
 /**
- * Icon style options for displaying places on the map.
+ * Properties of an entry point drawn by {@link PlacesModule}: the {@link EntryPoint} itself, whose
+ * position is the feature geometry, plus where it came from.
  *
- * @remarks
- * **Available Styles:**
- * - `pin`: Traditional map pin markers (teardrop shape)
- * - `circle-icon`: Simple circular markers (previously named `circle`)
- * - `base-map`: Mimics the map's built-in POI layer style with category icons (combines `main`, `selected`, and `micro` layers). For micro-only rendering, hide the `main` layer via `layers.main.layout.visibility = 'none'`.
- * - `pin-clustered`: Same teardrop pins as `pin` for un-clustered places, with nearby
- *   places aggregated into a single icon. Single-category clusters render the matching
- *   base-map POI sprite with a small black count badge in the top-right; mixed-category
- *   clusters render a larger centred count circle in place of the icon. Cluster features
- *   expose `clusterBaseMapIconIDs` (comma-separated, deduplicated) on their properties.
+ * @group Places
+ */
+type PlaceEntryPointProps = Omit<EntryPoint, 'position'> & {
+  /**
+   * Unique identifier of the entry point feature, derived from its place.
+   */
+  id: string;
+  /**
+   * `id` of the place the entry point belongs to, as shown by the module.
+   */
+  placeID: string;
+  /**
+   * Index of the entry point in the `entryPoints` of its place.
+   */
+  entryPointIndex: number;
+} & SupportsEvents;
+/**
+ * What `places.events.entryPoints` handlers receive: the entry point as a point feature, whether its
+ * circle or its line was hit, together with the place it belongs to.
+ *
+ * @remarks
+ * The place is passed as shown, with its own geometry. To route to the entrance, pass this feature
+ * as the route location.
+ *
+ * @group Places
+ */
+type PlaceEntryPointFeature = Feature<Point, PlaceEntryPointProps & {
+  /**
+   * The place the entry point belongs to. Absent only when that place left the map while the
+   * event was being handled.
+   */
+  place?: Place<DisplayPlaceProps>;
+}>;
+//#endregion
+//#region src/places/types/placesModuleConfig.d.ts
+/**
+ * Icon style options for displaying places on the map.
+ *
+ * @remarks
+ * **Available Styles:**
+ * - `pin`: Traditional map pin markers (teardrop shape)
+ * - `circle-icon`: Simple circular markers (previously named `circle`)
+ * - `base-map`: Mimics the map's built-in POI layer style with category icons (combines `main`, `selected`, and `micro` layers). For micro-only rendering, hide the `main` layer via `layers.main.layout.visibility = 'none'`.
+ * - `pin-clustered`: Same teardrop pins as `pin` for un-clustered places, with nearby
+ *   places aggregated into a single icon. Single-category clusters render the matching
+ *   base-map POI sprite with a small black count badge in the top-right; mixed-category
+ *   clusters render a larger centred count circle in place of the icon. Cluster features
+ *   expose `clusterBaseMapIconIDs` (comma-separated, deduplicated) on their properties.
  *
  * @group Places
  */
@@ -6934,7 +6728,7 @@ export declare const placesThemes: readonly ["pin", "circle-icon", "base-map", "
  * const places = await PlacesModule.create(map, {
  *   evAvailability: { enabled: true }
  * });
- * const stations = await search({ poiCategories: ['ELECTRIC_VEHICLE_STATION'] });
+ * const stations = await discoverPlaces({ poiCategories: ['CHARGING_LOCATION'] });
  * places.show(await getPlacesWithEVAvailability(stations));
  *
  * // Custom threshold and format
@@ -6950,7 +6744,7 @@ export declare const placesThemes: readonly ["pin", "circle-icon", "base-map", "
  * const places = await PlacesModule.create(map, {
  *   icon: {
  *     categoryIcons: [{
- *       id: 'ELECTRIC_VEHICLE_STATION',
+ *       id: 'CHARGING_LOCATION',
  *       image: customEvIconSvg,
  *       pixelRatio: 2
  *     }]
@@ -7034,7 +6828,7 @@ type DefaultPlaceIconConfig = {
  * const iconConfig: PlaceIconConfig = {
  *   categoryIcons: [
  *     { category: 'RESTAURANT', image: '/icons/food.png', pixelRatio: 2 },
- *     { category: 'HOTEL_MOTEL', image: '/icons/hotel.png', pixelRatio: 2 }
+ *     { category: 'HOTEL_OR_MOTEL', image: '/icons/hotel.png', pixelRatio: 2 }
  *   ]
  * };
  * ```
@@ -7449,6 +7243,81 @@ type PlaceConnectionsConfig = {
    */
   layers?: PlaceConnectionsLayersConfig;
 };
+/**
+ * Which shown places get their entry points drawn.
+ *
+ * @remarks
+ * - `all`: every place that has entry points.
+ * - `selected`: hovered or clicked places, the ones the `selected` layer highlights. A
+ *   `recently-hovered` place counts too, so the pointer can cross the map to an entrance.
+ * - `clicked`: clicked places, which stay clicked until the next click lands elsewhere.
+ *
+ * `selected` and `clicked` follow the module's event states, which exist once an event handler is
+ * registered on the module or {@link PlacesModule.putEventState} is called. Hovering or clicking an
+ * entry point keeps the entry points of its place drawn when a handler covers them: one on `events`
+ * or `events.entryPoints`, not on `events.places` alone.
+ *
+ * @group Places
+ */
+type PlaceEntryPointsShowFor = 'all' | 'selected' | 'clicked';
+/**
+ * MapLibre layer customization for entry points.
+ *
+ * @remarks
+ * The layer IDs are derived from the PlacesModule instance prefix:
+ * - `point`: a circle on each entry point, larger for a `main` one than for the rest
+ * - `line`: a dotted line from the place to each of its entry points
+ *
+ * @group Places
+ */
+type PlaceEntryPointsLayersConfig = {
+  /**
+   * Entry point circle layer specification.
+   */
+  point?: Partial<ToBeAddedLayerSpecTemplate<CircleLayerSpecification>>;
+  /**
+   * Place-to-entry-point line layer specification.
+   */
+  line?: Partial<ToBeAddedLayerSpecTemplate<LineLayerSpecification>>;
+};
+/**
+ * Configuration for drawing the entry points (entrances) of the shown places.
+ *
+ * @remarks
+ * Draws `properties.entryPoints` of each place, whichever service returned it.
+ *
+ * @example
+ * ```typescript
+ * const places = await PlacesModule.create(map, {
+ *   entryPoints: { showFor: 'clicked', minZoom: 16 }
+ * });
+ * // The handler is what makes places clickable, and so what lets them reach the `click` state.
+ * places.events.on('click', (feature) => console.log(feature.properties.title));
+ * ```
+ *
+ * @group Places
+ */
+type PlaceEntryPointsConfig = {
+  /**
+   * Which places get their entry points drawn.
+   *
+   * @default 'selected'
+   */
+  showFor?: PlaceEntryPointsShowFor;
+  /**
+   * Zoom level below which no entry point is drawn.
+   *
+   * @remarks
+   * Under the `pin-clustered` theme it is never lower than 18, the first zoom without clusters.
+   *
+   * @default 15
+   */
+  minZoom?: number;
+  /**
+   * Custom MapLibre layer specifications for the entry point circles and lines.
+   */
+  layers?: PlaceEntryPointsLayersConfig;
+};
 /**
  * Configuration options for the PlacesModule.
  *
@@ -7543,6 +7412,13 @@ type PlacesModuleConfig<P extends CommonPlaceProps = CommonPlaceProps> = MapModu
    * (a dashed line) and no label.
    */
   connections?: PlaceConnectionsConfig;
+  /**
+   * Configuration for drawing the entry points of the shown places.
+   *
+   * @remarks
+   * When omitted, entry points are not drawn.
+   */
+  entryPoints?: PlaceEntryPointsConfig;
   /**
    * Additional properties to compute for each place feature.
    *
@@ -7611,6 +7487,14 @@ type ConnectionFeatureProps = {
  */
 type ConnectionFeatureCollection = FeatureCollection<LineString, ConnectionFeatureProps>;
 //#endregion
+//#region src/places/utils/prepareEntryPointsForDisplay.d.ts
+/**
+ * Each entry point is two features sharing one id: its circle, then its line. The circle comes
+ * first, so an id lookup (event states, event payloads) always lands on it.
+ * @ignore
+ */
+type EntryPointFeatureCollection = FeatureCollection<Point | LineString, PlaceEntryPointProps>;
+//#endregion
 //#region src/places/PlacesModule.d.ts
 type PlacesSourcesAndLayers = {
   /**
@@ -7632,6 +7516,10 @@ type PlacesSourcesAndLayers = {
    * Connections source id with corresponding layers ids (line + label).
    */
   connections: GeoJSONSourceWithLayers<ConnectionFeatureCollection>;
+  /**
+   * Entry points source id with corresponding layers ids (line + point).
+   */
+  entryPoints: GeoJSONSourceWithLayers<EntryPointFeatureCollection>;
 };
 /**
  * What {@link PlacesModule.show} accepts, and what `shown-features` handlers receive back.
@@ -7661,14 +7549,19 @@ export type PlacesEvents = CombinedEvents<MapGeoJSONFeature, PlacesModuleConfig,
   places: UserEvents<Place<DisplayPlaceProps>>;
   /** The lines and labels connecting places to their parent, when connections are shown. */
   connections: UserEvents<MapGeoJSONFeature>;
+  /** The entry points of places, when {@link PlacesModuleConfig.entryPoints} draws them. */
+  entryPoints: UserEvents<PlaceEntryPointFeature>;
 };
 export declare class PlacesModule extends AbstractDataOwnedMapModule<PlacesSourcesAndLayers, PlacesModuleConfig> {
   private layerSpecs;
   private connectionLayerSpecs;
+  private entryPointLayerSpecs;
+  private refreshingEntryPoints;
   private currentClusterMode;
   private sourceID;
   private unclusteredSourceID;
   private connectionSourceID;
+  private entryPointSourceID;
   private layerIDPrefix;
   private defaultPlaceIconID;
   private shownConnections;
@@ -7690,10 +7583,13 @@ export declare class PlacesModule extends AbstractDataOwnedMapModule<PlacesSourc
    * @ignore
    */
   protected _initSourcesWithLayers(config?: PlacesModuleConfig, restore?: boolean): PlacesSourcesAndLayers;
+  private addOverlaySource;
+  private replaceLayerSpecs;
   private partitionSpecsForSources;
   private buildLayerSpecs;
   private buildClusterOptions;
   private buildConnectionLayerSpecs;
+  private buildEntryPointLayerSpecs;
   /**
    * @ignore
    */
@@ -7798,8 +7694,9 @@ export declare class PlacesModule extends AbstractDataOwnedMapModule<PlacesSourc
   applyExtraFeatureProps<P extends CommonPlaceProps = CommonPlaceProps>(extraFeatureProps: NonNullable<PlacesModuleConfig<P>['extraFeatureProps']>): void;
   private updateLayersAndData;
   private rebuildSourcesAndLayers;
-  private updateConnectionLayersAndData;
   private updateConnectionsData;
+  private updateEntryPointsData;
+  private applyLayersVisibility;
   private applyPlacesVisibility;
   private setupImages;
   private updateData;
@@ -7824,9 +7721,9 @@ export declare class PlacesModule extends AbstractDataOwnedMapModule<PlacesSourc
    * @example
    * Display search results:
    * ```typescript
-   * import { search } from '@tomtom-org/maps-sdk/services';
+   * import { discoverPlaces } from '@tomtom-org/maps-sdk/services';
    *
-   * const results = await search({ query: 'coffee' });
+   * const results = await discoverPlaces({ query: 'coffee' });
    * await placesModule.show(results);
    * ```
    *
@@ -8140,13 +8037,13 @@ export type POICategoryGroup = keyof typeof poiCategoryGroups;
 /**
  * A POI classification or group that can be filtered.
  *
- * Can be either a specific POI category (like RESTAURANT, HOTEL_MOTEL) or a
+ * Can be either a specific POI category (like RESTAURANT, HOTEL_OR_MOTEL) or a
  * broader category group (like FOOD_DRINKS_GROUP, SHOPPING_GROUP) that contains
  * multiple related categories.
  *
  * @remarks
  * **Category vs Group:**
- * - Category: Specific POI type (e.g., RESTAURANT, GAS_STATION)
+ * - Category: Specific POI type (e.g., RESTAURANT, FUEL_STATION)
  * - Group: Collection of related categories (e.g., FOOD_DRINKS_GROUP includes restaurants, cafes, bars)
  *
  * Using groups is more convenient when you want to filter multiple related categories at once.
@@ -8193,7 +8090,7 @@ type FilterablePOICategory = MapStylePOICategory | POICategoryGroup;
  * const noParkingConfig: POIsModuleConfig = {
  *   filters: {
  *     categories: {
- *       show: 'all_except',
+ *       show: 'all-except',
  *       values: ['PARKING_GROUP']
  *     }
  *   }
@@ -8227,25 +8124,20 @@ type POIsModuleConfig = MapModuleCommonConfig & {
    */
   filters?: {
     /**
-     * Category filter configuration.
-     *
-     * @remarks
-     * By default, all categories are included in the map.
-     * - Use `all_except` show mode to hide some categories/groups
-     * - Use `only` mode to show only specific categories/groups and hide everything else
+     * Categories or category groups to show or hide, per {@link FilterShowMode}.
      *
      * @example
      * ```typescript
      * // Show only restaurants and hotels
      * categories: {
      *   show: 'only',
-     *   values: ['RESTAURANT', 'HOTEL_MOTEL']
+     *   values: ['RESTAURANT', 'HOTEL_OR_MOTEL']
      * }
      *
      * // Hide parking
      * categories: {
-     *   show: 'all_except',
-     *   values: ['PARKING_GARAGE', 'OPEN_PARKING_AREA']
+     *   show: 'all-except',
+     *   values: ['PARKING_GARAGE', 'OPEN_CAR_PARKING_AREA']
      * }
      *
      * // Show only food-related POIs
@@ -8308,7 +8200,7 @@ type POIsModuleFeature = Feature<Point, {
    *
    * @remarks
    * Used for styling and filtering purposes. Maps to a specific POI type
-   * (e.g., RESTAURANT, HOTEL_MOTEL).
+   * (e.g., RESTAURANT, HOTEL_OR_MOTEL).
    *
    * @example 'restaurant'
    */
@@ -8360,6 +8252,10 @@ type PoIsSourcesAndLayers = {
  * and include businesses, landmarks, and other points of interest.
  *
  * @remarks
+ * **What this module owns:** whether the style's POIs are shown, and which categories. Their size,
+ * label colours and zoom thresholds are `pois.*` knobs on {@link StylingModule}.
+ * See [Who owns what](https://docs.tomtom.com/maps-sdk-js/guides/map/modules#who-owns-what).
+ *
  * **Features:**
  * - Toggle POI visibility on/off
  * - Filter by POI categories or category groups
@@ -8367,7 +8263,7 @@ type PoIsSourcesAndLayers = {
  * - Based on vector tile data in the map style
  *
  * **POI Categories:**
- * - Individual categories (e.g., RESTAURANT, HOTEL_MOTEL, PARKING_GARAGE)
+ * - Individual categories (e.g., RESTAURANT, HOTEL_OR_MOTEL, PARKING_GARAGE)
  * - Category groups (e.g., FOOD_DRINKS_GROUP, SHOPPING_GROUP, TRANSPORTATION_GROUP)
  *
  * **Difference from PlacesModule:**
@@ -8393,13 +8289,13 @@ type PoIsSourcesAndLayers = {
  * // Show only restaurants and hotels
  * poisModule.filterCategories({
  *   show: 'only',
- *   values: ['RESTAURANT', 'HOTEL_MOTEL']
+ *   values: ['RESTAURANT', 'HOTEL_OR_MOTEL']
  * });
  *
  * // Hide parking garages
  * poisModule.filterCategories({
- *   show: 'all_except',
- *   values: ['PARKING_GARAGE', 'OPEN_PARKING_AREA']
+ *   show: 'all-except',
+ *   values: ['PARKING_GARAGE', 'OPEN_CAR_PARKING_AREA']
  * });
  * ```
  *
@@ -8414,7 +8310,7 @@ type PoIsSourcesAndLayers = {
  *
  * // Hide transportation POIs
  * pois.filterCategories({
- *   show: 'all_except',
+ *   show: 'all-except',
  *   values: ['TRANSPORTATION_GROUP']
  * });
  * ```
@@ -8519,32 +8415,8 @@ export declare class POIsModule extends AbstractStyleOwnedMapModule<PoIsSourcesA
   /**
    * Filters POIs by category or category group.
    *
-   * @param categoriesFilter - Filter configuration specifying which categories to show/hide.
-   * Pass `undefined` to reset to default (show all).
-   *
-   * @remarks
-   * **Filter Modes:**
-   * - `only`: Show only the specified categories, hide all others
-   * - `all_except`: Show all categories except the specified ones
-   *
-   * **Category Types:**
-   * - Individual categories (e.g., 'RESTAURANT', 'HOTEL_MOTEL')
-   * - Category groups (e.g., 'FOOD_DRINKS_GROUP', 'SHOPPING_GROUP')
-   *
-   * **Available Category Groups:**
-   * - FOOD_DRINKS_GROUP
-   * - SHOPPING_GROUP
-   * - TRANSPORTATION_GROUP
-   * - HEALTH_GROUP
-   * - PARKING_GROUP
-   * - HOLIDAY_TOURISM_GROUP
-   * - EV_CHARGING_STATIONS_GROUP
-   * - GAS_STATIONS_GROUP
-   * - ACCOMMODATION_GROUP
-   * - ENTERTAINMENT_GROUP
-   * - SPORTS_LEISURE_GROUP
-   * - EDUCATION_GROUP
-   * - GOVERNMENT_GROUP
+   * @param categoriesFilter - Categories (`'RESTAURANT'`) or {@link POICategoryGroup | groups}
+   * (`'FOOD_DRINKS_GROUP'`) to show or hide, per {@link FilterShowMode}. `undefined` shows all.
    *
    * @example
    * Show only restaurants:
@@ -8559,7 +8431,7 @@ export declare class POIsModule extends AbstractStyleOwnedMapModule<PoIsSourcesA
    * Hide parking:
    * ```typescript
    * pois.filterCategories({
-   *   show: 'all_except',
+   *   show: 'all-except',
    *   values: ['PARKING_GROUP']
    * });
    * ```
@@ -9449,13 +9321,13 @@ type SectionIconConfig = {
    * - `center`: one icon at the middle of each section.
    * - `along`: icons repeated along the section.
    *
-   * @defaultValue `"center"`
+   * @defaultValue `"center"` on the generated types; `ferry` and `tollRoad` keep their own placement.
    */
   placement?: 'center' | 'along';
   /**
    * Icon scale, where `1` is the sprite image's own size.
    *
-   * @defaultValue 1
+   * @defaultValue `1` on the generated types; `ferry` and `tollRoad` keep their own zoom-ramped size.
    */
   size?: number;
 };
@@ -11197,13 +11069,20 @@ 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.
+ * The ten semantic map colours — the *Foundations* palette of TomTom's style themes, under their own
+ * names and in their order. One name drives every layer and shade the style derives from it.
  *
- * | Name | Map Maker | Reaches |
+ * | Name | Theme label | 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. |
@@ -11236,11 +11115,11 @@ 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];
 /**
- * The ten map colour names, in Map Maker's Foundations order.
+ * The ten map colour names, in the themes' Foundations order.
  *
  * @group Map Styling
  */
@@ -11309,15 +11188,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}.
@@ -11331,6 +11201,13 @@ type StylingPresetId = keyof typeof stylingPresets;
  * @group Map Styling
  */
 export declare const stylingPresetIds: StylingPresetId[];
+/**
+ * Every styling preset with its name, use case and the knob values it applies, in catalogue order.
+ * Static data: no map is needed to read it.
+ *
+ * @group Map Styling
+ */
+export declare const stylingPresetCatalogue: readonly StylingPreset[];
 //#endregion
 //#region src/styling/types/stylingTypes.d.ts
 /**
@@ -11379,58 +11256,31 @@ type StylingKnobRange = KnobRange & {
   step: number;
 };
 /**
- * One entry of the styling catalogue returned by {@link StylingModule.describe}: everything a UI or
- * an agent needs to offer the knob, validate a value for it and show its state.
- *
- * @remarks
- * Narrows the shared {@link KnobDescriptor}: styling ids and value types are known, `range.step` is
- * always given, and `available` / `appliesTo` are required — every styling knob answers both.
+ * One entry of {@link stylingKnobCatalogue}: what a UI or a coding agent needs to offer the knob and
+ * validate a value for it, with no map loaded. The value in force is {@link StylingModule.get}.
  *
  * @group Map Styling
  */
-type StylingKnobDescriptor = KnobDescriptor & {
+type StylingKnob = {
   /** The knob's id, as accepted by {@link StylingModule.set}. */
   id: StylingKnobId;
   kind: StylingKnobKind;
-  /**
-   * The value the loaded style ships with. `undefined` when the style defines it as a data-driven
-   * expression that no single value stands for; `reset` still restores it exactly.
-   */
-  default: StylingKnobValue | undefined;
-  /** The value in effect right now: the override if there is one, otherwise the default. */
-  current: StylingKnobValue | undefined;
+  /** One line on what turning the knob does. */
+  description: string;
   /** 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, and the SDK also warns once in the console when that happens. Check this before
-   * offering the knob in a UI or to an agent. Map-level knobs are always available bar
-   * `view.terrain`, which needs the style to carry an elevation source.
-   */
-  available: boolean;
   /** Which styles the knob works on; see {@link stylingKnobAppliesTo}. */
   appliesTo: StylingKnobAppliesTo;
 };
-/**
- * The machine-readable styling catalogue: what can be styled on the loaded style, with defaults,
- * ranges and current values. Additive across SDK minor versions; knob ids are public API.
- *
- * @group Map Styling
- */
-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 = {
+type StylingPreset = {
   id: StylingPresetId;
   name: string;
   /** One line on the use case the preset serves. */
@@ -11461,7 +11311,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 +11351,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 +11375,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';
@@ -11538,11 +11403,126 @@ type KnobDefinitionOf<KIND extends StylingKnobKind> = KnobDefinition & {
 /**
  * The styling knob catalogue: what the SDK can restyle on a TomTom standard style, and how.
  *
- * Ids are public API — additive only. Ranges follow TomTom Map Maker's validated grammar (factors
+ * Ids are public API — additive only. Ranges follow the validated grammar of TomTom's style editor (factors
  * 0.5–1.5 in 0.1 steps) so a value that looks right in the designer's tool looks right here.
  * @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,71 +11594,9 @@ 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.
+ * The id of a styling knob — see {@link stylingKnobCatalogue} for what each one does.
  *
  * @group Map Styling
  */
@@ -11689,6 +11607,14 @@ type StylingKnobId = keyof typeof knobDefinitions;
  * @group Map Styling
  */
 export declare const stylingKnobIds: StylingKnobId[];
+/**
+ * Every styling knob with its kind, description, range or options and the styles it works on, in
+ * catalogue order. Static data: a UI or a coding agent reads it with no map loaded, and
+ * {@link StylingModule.get} gives the value in force on a live one.
+ *
+ * @group Map Styling
+ */
+export declare const stylingKnobCatalogue: readonly StylingKnob[];
 /**
  * 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.
@@ -11710,6 +11636,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
@@ -11723,15 +11755,15 @@ export type StylingEvents = CombinedEvents<MapGeoJSONFeature, StylingSettings, n
  * hand-editing MapLibre layers.
  *
  * Every adjustable thing is a **knob** with a stable id, a kind, a range and a default read from the
- * loaded style. {@link describe} returns that catalogue as data, so a UI or an AI agent can build
- * controls, validate values and diff state without knowing anything about the style's layers.
+ * loaded style. The ids form the {@link StylingKnobId} union, and {@link stylingKnobCatalogue} lists
+ * each one's kind, range and description as data, with no map needed to read it.
  *
  * @remarks
  * **Which styles a knob works on** is `appliesTo` in the catalogue. `any-style` knobs (sizes,
  * widths) wrap whatever the style already does — `text-size: E` becomes `["*", 1.3, E]` — so they
  * work on a custom style too. `tomtom-styles` knobs (toggles, colours) reach their layers through
- * the TomTom styles this SDK version is verified against; on any other style they report
- * `available: false`, warn once and do nothing rather than failing silently.
+ * the TomTom styles this SDK version is verified against; on any other style setting one warns once
+ * and does nothing, rather than failing silently.
  *
  * **Style changes.** Settings are re-applied after every `setStyle` that carries state over, on top of
  * whatever the other modules restored, and dropped on a clean switch (`resetState: true`).
@@ -11750,9 +11782,9 @@ export type StylingEvents = CombinedEvents<MapGeoJSONFeature, StylingSettings, n
  * styling.set('roads.exitNumbers', false);
  * styling.set('traffic.flow.slowColor', '#f59e0b');
  *
- * // Everything a control panel or an agent needs, as data:
- * for (const knob of styling.describe().knobs) {
- *   console.log(knob.id, knob.kind, knob.range, knob.current);
+ * // The catalogue as data, and each knob's value in force:
+ * for (const knob of stylingKnobCatalogue) {
+ *   console.log(knob.id, knob.kind, knob.range, styling.get(knob.id));
  * }
  *
  * // Serializable, diffable, re-applicable:
@@ -11774,9 +11806,11 @@ export declare class StylingModule extends AbstractStyleOwnedMapModule<Record<st
   private mapColorTargetsByKey;
   private mapColorTargetsByKnob;
   private mapColorAnchors;
+  private landDerivedColors;
   private warned;
   private reindexed;
   private originalSpaceColor;
+  private layerOverrides;
   /**
    * Retrieves the styling module of the given map, creating it on first use.
    *
@@ -11809,23 +11843,25 @@ export declare class StylingModule extends AbstractStyleOwnedMapModule<Record<st
    */
   protected _applyConfig(settings: StylingSettings | undefined): StylingSettings | undefined;
   /**
-   * The styling catalogue for the loaded style: every knob with its kind, range, default, current
-   * value and how many layers it reaches.
-   *
-   * @remarks
-   * Meant to be consumed as data — build a control panel from it, hand it to an agent, or diff two
-   * calls. Knob ids and the shape of the entries are public API and change additively only.
+   * @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
-   * const { knobs } = styling.describe();
-   * const sliders = knobs.filter((knob) => knob.kind === 'factor' && knob.available);
+   * styling.layers.query({ group: 'roadLabels' }).setPaint({ 'text-color': '#93c5fd' });
    * ```
    */
-  describe(): StylingCatalogue;
+  get layers(): {
+    query: (query: LayerQuery) => LayerSelection;
+  };
   /**
    * 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 {@link stylingPresetCatalogue} for
    * what each one sets.
    *
    * @param id - The preset to apply.
@@ -11861,7 +11897,7 @@ export declare class StylingModule extends AbstractStyleOwnedMapModule<Record<st
    * Sets one knob. The value is validated against the knob's kind and range before anything is
    * touched, and applied to every layer the knob reaches.
    *
-   * @param id - The knob to set; see {@link describe} for the catalogue.
+   * @param id - The knob to set; see {@link stylingKnobCatalogue} for the catalogue.
    * @param value - A number for `factor`/`number` knobs (within `range`), a boolean for `toggle`
    * knobs, a CSS colour string for `color` knobs.
    * @throws `RangeError` when the value is not valid for the knob; `Error` for an unknown id.
@@ -11887,14 +11923,16 @@ 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.
+   * Recolours the whole base map with up to ten semantic colours in one call — the style
+   * themes' Foundations palette, each listed with what it reaches under {@link MapColorName}. Partial
+   * objects are fine; colours not given stay as they are, except on the mono styles, which derive
+   * the other nine from `land` as their theme does: there the theme's own formulas re-derive them
+   * from the `land` given.
    *
    * @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.
+   * are also the `colors.*` knobs, so `get`, `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
@@ -11907,6 +11945,7 @@ export declare class StylingModule extends AbstractStyleOwnedMapModule<Record<st
    * ```typescript
    * styling.setMapColors({ land: '#f3f5f7', water: '#accbe2', roadMajor: '#a1b8ce', label: '#364659' });
    * styling.reset('colors.roadMajor'); // one colour back to the style
+   * styling.setMapColors(deriveMapColors(['#0b2a3a', '#0fa8c8', '#f6efe3'])); // map-theme plugin assigns the roles
    * ```
    */
   setMapColors(colors: MapColors): void;
@@ -11934,22 +11973,24 @@ 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 refreshMapColor;
+  private derivedMapColorOf;
+  private mapColorsOf;
   private refreshMapColorProperty;
   private refreshProjection;
   private refreshSky;
-  private refreshTerrain;
   private refreshVisibility;
-  private refreshMinZoom;
+  private refreshZoomBound;
+  private styleZoomBound;
   private refreshZoomOffset;
   private refreshScaledProperty;
   private refreshColor;
   private setProperty;
-  private describeKnob;
   private defaultOf;
   private mapLevelDefaultOf;
   private assertKnob;
@@ -11957,6 +11998,147 @@ 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
+ * **What this module owns:** whether the hillshade is shown, and whether and how high the surface is raised.
+ * Shading method, light direction, strength, zoom range and colours are `hillshade.*` {@link StylingModule} knobs.
+ * See [Who owns what](https://docs.tomtom.com/maps-sdk-js/guides/map/modules#who-owns-what).
+ *
+ * - **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.
@@ -12153,7 +12335,7 @@ type AreaAnalyticsMetricConfig = {
  * @example
  * ```typescript
  * // Move all layers below the lowest label
- * const config: TrafficAreaAnalyticsConfig = {
+ * const config: TrafficAreaAnalyticsModuleConfig = {
  *   beforeLayerConfig: {
  *     heatmap: 'lowestLabel',
  *     hexgrid: { flat2D: 'lowestLabel', extrusion3D: 'lowestPlaceLabel' },
@@ -12162,7 +12344,7 @@ type AreaAnalyticsMetricConfig = {
  * };
  *
  * // Only reposition the heatmap layer
- * const config: TrafficAreaAnalyticsConfig = {
+ * const config: TrafficAreaAnalyticsModuleConfig = {
  *   beforeLayerConfig: { heatmap: 'top' },
  * };
  * ```
@@ -12246,7 +12428,7 @@ declare const TRAFFIC_LIGHT_COLORS: {
   readonly bad: "#e03030";
 };
 /**
- * Default values for all {@link TrafficAreaAnalyticsConfig} options.
+ * Default values for all {@link TrafficAreaAnalyticsModuleConfig} options.
  *
  * Use these as a reference for what the module applies when a property is omitted,
  * or spread them as a base when constructing a config programmatically.
@@ -12254,13 +12436,13 @@ declare const TRAFFIC_LIGHT_COLORS: {
  * @group Traffic Area Analytics
  */
 declare const AREA_ANALYTICS_DEFAULTS: {
-  /** @see {@link TrafficAreaAnalyticsConfig.visible} */
+  /** @see {@link TrafficAreaAnalyticsModuleConfig.visible} */
   visible: true;
-  /** @see {@link TrafficAreaAnalyticsConfig.displayMode} */
+  /** @see {@link TrafficAreaAnalyticsModuleConfig.displayMode} */
   displayMode: "hexgrid-3d";
-  /** @see {@link TrafficAreaAnalyticsConfig.activeMetric} */
+  /** @see {@link TrafficAreaAnalyticsModuleConfig.activeMetric} */
   activeMetric: "congestionLevel";
-  /** @see {@link TrafficAreaAnalyticsConfig.metricConfig} */
+  /** @see {@link TrafficAreaAnalyticsModuleConfig.metricConfig} */
   metricConfig: {
     congestionLevel: {
       color: {
@@ -12385,7 +12567,7 @@ declare const AREA_ANALYTICS_DEFAULTS: {
  *
  * @example
  * ```typescript
- * const config: TrafficAreaAnalyticsConfig = {
+ * const config: TrafficAreaAnalyticsModuleConfig = {
  *   displayMode: 'hexgrid-3d',
  *   activeMetric: 'congestionLevel',
  *   metricConfig: {
@@ -12410,7 +12592,7 @@ declare const AREA_ANALYTICS_DEFAULTS: {
  *
  * @group Traffic Area Analytics
  */
-type TrafficAreaAnalyticsConfig = MapModuleCommonConfig & {
+type TrafficAreaAnalyticsModuleConfig = MapModuleCommonConfig & {
   /**
    * Controls the visibility of the area analytics layers.
    *
@@ -12517,7 +12699,7 @@ type AreaAnalyticsSourcesWithLayers = {
  *
  * @group Traffic Area Analytics
  */
-export declare class TrafficAreaAnalyticsModule extends AbstractDataOwnedMapModule<AreaAnalyticsSourcesWithLayers, TrafficAreaAnalyticsConfig> {
+export declare class TrafficAreaAnalyticsModule extends AbstractDataOwnedMapModule<AreaAnalyticsSourcesWithLayers, TrafficAreaAnalyticsModuleConfig> {
   private heatmapLayerSpec;
   private hexFillLayerSpec;
   private hexExtrusionLayerSpec;
@@ -12563,12 +12745,13 @@ export declare class TrafficAreaAnalyticsModule extends AbstractDataOwnedMapModu
    * });
    * ```
    */
-  static create(tomtomMap: TomTomMap, config?: TrafficAreaAnalyticsConfig): Promise<TrafficAreaAnalyticsModule>;
+  static create(tomtomMap: TomTomMap, config?: TrafficAreaAnalyticsModuleConfig): Promise<TrafficAreaAnalyticsModule>;
   private constructor();
   /** @ignore */
-  protected _initSourcesWithLayers(config?: TrafficAreaAnalyticsConfig, _restore?: boolean): AreaAnalyticsSourcesWithLayers;
+  protected _initSourcesWithLayers(config?: TrafficAreaAnalyticsModuleConfig, _restore?: boolean): AreaAnalyticsSourcesWithLayers;
   /** @ignore */
-  protected _applyConfig(config: TrafficAreaAnalyticsConfig | undefined): TrafficAreaAnalyticsConfig | undefined;
+  protected _applyConfig(config: TrafficAreaAnalyticsModuleConfig | undefined): TrafficAreaAnalyticsModuleConfig | undefined;
+  private moveLayersToSpecPositions;
   /** @ignore */
   protected discardShownData(): void;
   /** @ignore */
@@ -12730,7 +12913,7 @@ export declare class TrafficAreaAnalyticsModule extends AbstractDataOwnedMapModu
    * });
    * ```
    */
-  get events(): CombinedEvents<AreaAnalyticsTileFeature, TrafficAreaAnalyticsConfig, TrafficAreaAnalytics>;
+  get events(): CombinedEvents<AreaAnalyticsTileFeature, TrafficAreaAnalyticsModuleConfig, TrafficAreaAnalytics>;
   private get mode();
   private get activeMetric();
   private get lightDark();
@@ -12863,7 +13046,7 @@ export type TrafficCommonFilter = {
    * @example
    * ```ts
    * // Hide minor local streets
-   * roadSubCategories: { show: 'all_except', values: ['living_street'] }
+   * roadSubCategories: { show: 'all-except', values: ['living_street'] }
    * ```
    */
   roadSubCategories?: ValuesFilter<RoadSubCategory>;
@@ -12935,7 +13118,7 @@ export type TrafficFlowFilters = {
  *
  * @group Traffic Flow
  */
-export type FlowConfig = MapModuleCommonConfig & {
+export type TrafficFlowModuleConfig = MapModuleCommonConfig & {
   /**
    * Controls the visibility of the traffic flow layers.
    *
@@ -12957,6 +13140,12 @@ export type FlowConfig = MapModuleCommonConfig & {
  * Defines the structure of a traffic flow feature, which extends the basic GeoJSON feature
  * with properties extracted from the traffic flow vector tiles.
  *
+ * @remarks
+ * `absoluteSpeed`, `partOfTwoWayRoad` and `openlr` stay `undefined` with the standard styles, which do
+ * not request their tile tags; a custom style whose flow source asks for them populates them.
+ * No flow tile carries free-flow speed, travel time, delay or confidence: for historical speed and
+ * congestion over an area, use the Traffic Area Analytics service.
+ *
  * @group Traffic Flow
  */
 export type TrafficFlowModuleFeature = Feature<LineString, {
@@ -13012,6 +13201,10 @@ type TrafficFlowSourcesWithLayers = {
  * traffic speed conditions using color-coded road segments.
  *
  * @remarks
+ * **What this module owns:** whether the style's traffic-flow layers are shown, and for which roads.
+ * Each flow level's colour and the line width are `traffic.flow.*` knobs on {@link StylingModule}.
+ * See [Who owns what](https://docs.tomtom.com/maps-sdk-js/guides/map/modules#who-owns-what).
+ *
  * **Features:**
  * - Toggle traffic flow visibility on/off
  * - Filter by road categories and types
@@ -13057,7 +13250,7 @@ type TrafficFlowSourcesWithLayers = {
  * trafficFlow.filter({
  *   any: [{
  *     roadCategories: {
- *       show: 'all_except',
+ *       show: 'all-except',
  *       values: ['street']
  *     }
  *   }]
@@ -13079,7 +13272,7 @@ type TrafficFlowSourcesWithLayers = {
  *
  * @group Traffic Flow
  */
-export declare class TrafficFlowModule extends AbstractStyleOwnedMapModule<TrafficFlowSourcesWithLayers, FlowConfig> {
+export declare class TrafficFlowModule extends AbstractStyleOwnedMapModule<TrafficFlowSourcesWithLayers, TrafficFlowModuleConfig> {
   /**
    * Retrieves a TrafficFlowModule instance for the given map.
    *
@@ -13127,7 +13320,7 @@ export declare class TrafficFlowModule extends AbstractStyleOwnedMapModule<Traff
    * provides, under fixed global IDs. Every instance is another handle on that same shared state,
    * so visibility and filters applied through one are visible through all of them.
    */
-  static get(map: TomTomMap, config?: FlowConfig): Promise<TrafficFlowModule>;
+  static get(map: TomTomMap, config?: TrafficFlowModuleConfig): Promise<TrafficFlowModule>;
   private constructor();
   /**
    * @ignore
@@ -13138,7 +13331,7 @@ export declare class TrafficFlowModule extends AbstractStyleOwnedMapModule<Traff
   /**
    * @ignore
    */
-  protected _applyConfig(config: FlowConfig | undefined): FlowConfig | undefined;
+  protected _applyConfig(config: TrafficFlowModuleConfig | undefined): TrafficFlowModuleConfig | undefined;
   private getLayers;
   /**
    * Applies filters to traffic flow display.
@@ -13182,7 +13375,7 @@ export declare class TrafficFlowModule extends AbstractStyleOwnedMapModule<Traff
    * trafficFlow.filter({
    *   any: [{
    *     roadCategories: {
-   *       show: 'all_except',
+   *       show: 'all-except',
    *       values: ['street']
    *     }
    *   }]
@@ -13235,16 +13428,9 @@ export declare class TrafficFlowModule extends AbstractStyleOwnedMapModule<Traff
    * @returns An object containing visible traffic flow features.
    *
    * @remarks
-   * Returns all traffic flow features currently rendered in the visible map area.
-   * These represent road segments with real-time traffic speed information.
-   *
-   * **Feature Properties:**
-   * Properties depend on the traffic flow vector tile schema and may include:
-   * - Current speed
-   * - Free flow speed
-   * - Road category
-   * - Congestion level
-   * - Road closure status
+   * The only way to read live flow values: Orbis traffic flow is vector tiles, with no service for a
+   * road, a point or an area. Results cover the current viewport and zoom, and a segment crossing a
+   * tile boundary appears once per tile. See {@link TrafficFlowModuleFeature} for what each carries.
    *
    * @example
    * ```typescript
@@ -13260,7 +13446,7 @@ export declare class TrafficFlowModule extends AbstractStyleOwnedMapModule<Traff
    * ```typescript
    * const shown = trafficFlow.getShown();
    * const congested = shown.trafficFlow.filter(
-   *   segment => segment.properties.speed < segment.properties.freeFlowSpeed * 0.5
+   *   segment => segment.properties.relativeSpeed < 0.5
    * );
    * console.log(`Congested segments: ${congested.length}`);
    * ```
@@ -13268,7 +13454,7 @@ export declare class TrafficFlowModule extends AbstractStyleOwnedMapModule<Traff
   getShown(): {
     trafficFlow: TrafficFlowModuleFeature[];
   };
-  get events(): CombinedEvents<TrafficFlowModuleFeature, FlowConfig, never>;
+  get events(): CombinedEvents<TrafficFlowModuleFeature, TrafficFlowModuleConfig, never>;
 }
 //#endregion
 //#region src/traffic/types/trafficIncidentOverlayConfig.d.ts
@@ -13296,7 +13482,7 @@ type IncidentFocusStyle = {
  *
  * @group Traffic
  */
-type TrafficIncidentOverlayConfig = MapModuleCommonConfig & {
+type TrafficIncidentOverlayModuleConfig = MapModuleCommonConfig & {
   /**
    * Initial visibility of all incident layers. Defaults to `true`.
    * `show()` never flips this flag — if `false`, the module loads data but
@@ -13422,7 +13608,7 @@ type Sources = {
  *
  * @group Traffic
  */
-export declare class TrafficIncidentOverlayModule extends AbstractDataOwnedMapModule<Sources, TrafficIncidentOverlayConfig> {
+export declare class TrafficIncidentOverlayModule extends AbstractDataOwnedMapModule<Sources, TrafficIncidentOverlayModuleConfig> {
   private lastResult;
   private lastFeatureIds;
   private lastFocusIds;
@@ -13438,12 +13624,12 @@ export declare class TrafficIncidentOverlayModule extends AbstractDataOwnedMapMo
    * @param config The module optional configuration.
    * @returns {Promise} Returns a promise with a new instance of this module.
    */
-  static create(tomtomMap: TomTomMap, config?: TrafficIncidentOverlayConfig): Promise<TrafficIncidentOverlayModule>;
+  static create(tomtomMap: TomTomMap, config?: TrafficIncidentOverlayModuleConfig): Promise<TrafficIncidentOverlayModule>;
   private constructor();
   /** @ignore */
-  protected _initSourcesWithLayers(config?: TrafficIncidentOverlayConfig, _restore?: boolean): Sources;
+  protected _initSourcesWithLayers(config?: TrafficIncidentOverlayModuleConfig, _restore?: boolean): Sources;
   /** @ignore */
-  protected _applyConfig(config: TrafficIncidentOverlayConfig | undefined): TrafficIncidentOverlayConfig | undefined;
+  protected _applyConfig(config: TrafficIncidentOverlayModuleConfig | undefined): TrafficIncidentOverlayModuleConfig | undefined;
   private applyBeforeLayer;
   /** @ignore */
   protected discardShownData(): void;
@@ -13481,7 +13667,7 @@ export declare class TrafficIncidentOverlayModule extends AbstractDataOwnedMapMo
   getShown(): {
     incidents: TrafficIncidentDetails;
   };
-  get events(): CombinedEvents<TrafficIncident, TrafficIncidentOverlayConfig, TrafficIncidentDetails>;
+  get events(): CombinedEvents<TrafficIncident, TrafficIncidentOverlayModuleConfig, TrafficIncidentDetails>;
   /**
    * Mark a subset of currently-rendered incidents as "focused" via MapLibre
    * feature-state. `null` clears the state. Paint expressions in
@@ -13579,7 +13765,7 @@ export type TrafficIncidentsFilter = TrafficCommonFilter & {
    * magnitudes: { show: 'only', values: ['moderate', 'major'] }
    *
    * // Hide minor incidents
-   * magnitudes: { show: 'all_except', values: ['minor'] }
+   * magnitudes: { show: 'all-except', values: ['minor'] }
    * ```
    */
   magnitudes?: ValuesFilter<DelayMagnitude>;
@@ -13656,7 +13842,7 @@ export type IncidentsCommonConfig = {
  *
  * @group Traffic Incidents
  */
-export type IncidentsConfig = MapModuleCommonConfig & IncidentsCommonConfig & {
+export type TrafficIncidentsModuleConfig = MapModuleCommonConfig & IncidentsCommonConfig & {
   /**
    * Configuration specific to incident icon display.
    *
@@ -13724,6 +13910,10 @@ type TrafficIncidentsSourcesWithLayers = {
  * events like accidents, road closures, construction, and hazards.
  *
  * @remarks
+ * **What this module owns:** whether the style's incident layers are shown, and which incidents.
+ * Each magnitude's colour and the line width are `traffic.incidents.*` knobs on {@link StylingModule}.
+ * See [Who owns what](https://docs.tomtom.com/maps-sdk-js/guides/map/modules#who-owns-what).
+ *
  * **Features:**
  * - Toggle incidents visibility on/off
  * - Separate control for incident icons
@@ -13776,7 +13966,7 @@ type TrafficIncidentsSourcesWithLayers = {
  * trafficIncidentsModule.filter({
  *   any: [{
  *     incidentCategories: {
- *       show: 'all_except',
+ *       show: 'all-except',
  *       values: ['roadworks']
  *     }
  *   }]
@@ -13832,7 +14022,7 @@ type TrafficIncidentsSourcesWithLayers = {
  *
  * @group Traffic Incidents
  */
-export declare class TrafficIncidentsModule extends AbstractStyleOwnedMapModule<TrafficIncidentsSourcesWithLayers, IncidentsConfig> {
+export declare class TrafficIncidentsModule extends AbstractStyleOwnedMapModule<TrafficIncidentsSourcesWithLayers, TrafficIncidentsModuleConfig> {
   /**
    * Retrieves a TrafficIncidentsModule instance for the given map.
    *
@@ -13880,7 +14070,7 @@ export declare class TrafficIncidentsModule extends AbstractStyleOwnedMapModule<
    * provides, under fixed global IDs. Every instance is another handle on that same shared state,
    * so visibility and filters applied through one are visible through all of them.
    */
-  static get(map: TomTomMap, config?: IncidentsConfig): Promise<TrafficIncidentsModule>;
+  static get(map: TomTomMap, config?: TrafficIncidentsModuleConfig): Promise<TrafficIncidentsModule>;
   private constructor();
   /**
    * @ignore
@@ -13891,7 +14081,7 @@ export declare class TrafficIncidentsModule extends AbstractStyleOwnedMapModule<
   /**
    * @ignore
    */
-  protected _applyConfig(config: IncidentsConfig | undefined): IncidentsConfig | undefined;
+  protected _applyConfig(config: TrafficIncidentsModuleConfig | undefined): TrafficIncidentsModuleConfig | undefined;
   /**
    * Applies filters to traffic incidents display.
    *
@@ -14073,7 +14263,7 @@ export declare class TrafficIncidentsModule extends AbstractStyleOwnedMapModule<
   getShown(): {
     trafficIncidents: TrafficIncidentsModuleFeature[];
   };
-  get events(): CombinedEvents<TrafficIncidentsModuleFeature, IncidentsConfig, never>;
+  get events(): CombinedEvents<TrafficIncidentsModuleFeature, TrafficIncidentsModuleConfig, never>;
 }
 //#endregion
 //#region src/utils/colorUtils.d.ts
@@ -14083,12 +14273,34 @@ export declare class TrafficIncidentsModule extends AbstractStyleOwnedMapModule<
  */
 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.
+ * {@link parseColor} as an {@link RGBAColor} tuple.
  * @ignore
  */
 export declare const parseCssColor: (cssColor: string) => RGBAColor | undefined;
+/**
+ * A colour in HSL: hue in degrees (none for a grey), saturation, lightness and alpha 0–1 — the shape
+ * of culori's `Hsl`, so culori's functions take it.
+ * @ignore
+ */
+type HslColor = {
+  mode: 'hsl';
+  h?: number;
+  s: number;
+  l: number;
+  alpha?: number;
+};
+/**
+ * The HSL of a CSS colour, or `undefined` when it cannot be parsed. Read through sRGB, so an
+ * `hsl()` literal comes back canonical — white has no saturation, a grey no hue.
+ * @ignore
+ */
+export declare const toHsl: (cssColor: string) => HslColor | undefined;
+/**
+ * Formats an HSL colour as a CSS `hsl()`/`hsla()` string, rounded to what the map styles themselves
+ * use: whole degrees and percents.
+ * @ignore
+ */
+export declare const formatStyleHsl: (hsl: Omit<HslColor, "mode">) => string;
 //#endregion
 //#region src/utils/types/paddedBounds.d.ts
 /**
@@ -14170,4 +14382,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, EventHandlerHoverConfig, EventState, EventType, ExtraFeatureProp, FeaturePropValue, FilterablePOICategory, GeneratedSectionType, GeoJSONSourcesWithLayers, HasAdditionalLayersConfig, HasBeforeID, HoverEventType, HslColor, IncidentFocusStyle, LayerQuery, LayerSpecFilter, LayerSpecTemplate, LayerSpecWithSource, LightDark, MapColorName, MapColors, MapEventsConfig, MapFont, MapModuleCommonConfig, MapStyleLayerID, POIsModuleConfig, POIsModuleFeature, PlaceConnectionDisplay, PlaceConnectionLayerName, PlaceConnectionsConfig, PlaceConnectionsLayersConfig, PlaceEntryPointFeature, PlaceEntryPointProps, PlaceEntryPointsConfig, PlaceEntryPointsLayersConfig, PlaceEntryPointsShowFor, 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, StylingColorKnobId, StylingKnob, StylingKnobAppliesTo, StylingKnobId, StylingKnobKind, StylingKnobRange, StylingKnobValue, StylingKnobValueOf, StylingPreset, StylingPresetId, StylingSettings, SupportsEvents, SymbolLayerSpecWithoutSource, TRAFFIC_LIGHT_COLORS, TerrainModuleConfig, ToBeAddedLayerSpec, ToBeAddedLayerSpecTemplate, ToBeAddedLayerSpecWithoutSource, TrafficAreaAnalyticsModuleConfig, TrafficIncidentOverlayModuleConfig, UserEventHandler, WaypointsConfig };