@tomtom-org/maps-sdk 0.61.0 → 0.62.0

package/map/dist/index.d.ts

@@ -268,19 +268,19 @@ export type StandardStyleID = (typeof standardStyleIDs)[number];
 /**
  * Configuration for a TomTom standard map style.
  *
- * Provides options to customize which modules are included.
+ * Provides options to customize which style parts are included.
  *
  * @example
  * ```typescript
- * // Standard style with all default modules
+ * // Standard style with every style part
  * const style: StandardStyle = {
  *   id: 'standardLight'
  * };
  *
- * // Exclude traffic modules
+ * // Leave the traffic parts out
  * const styleNoTraffic: StandardStyle = {
  *   id: 'standardLight',
- *   include: ['hillshade']  // Only include hillshade, exclude traffic
+ *   include: ['terrain']
  * };
  * ```
  *
@@ -294,33 +294,11 @@ export type StandardStyle = {
    */
   id?: StandardStyleID;
   /**
-   * Modules to include when loading the style.
-   * * Use this to selectively enable only needed modules for better performance.
+   * Which {@link StylePart}s to load. Leave it out for every part; `[]` loads none.
    *
-   * If not specified, all available modules are included by default.
-   * If an empty array is provided, no optional modules will be included.
-   *
-   * @default All available modules
-   *
-   * @remarks
-   * Available modules:
-   * - `trafficIncidents`: Real-time traffic incidents (accidents, closures)
-   * - `trafficFlow`: Real-time traffic flow visualization
-   * - `hillshade`: Terrain elevation data, for hillshade shading and 3D terrain
-   *
-   * @example
-   * ```typescript
-   * // Include only traffic modules
-   * include: ['trafficIncidents', 'trafficFlow']
-   *
-   * // Include only hillshade
-   * include: ['hillshade']
-   *
-   * // Include no optional modules
-   * include: []
-   * ```
+   * @default All style parts
    */
-  include?: StyleModule[];
+  include?: StylePart[];
 };
 /**
  * Where a custom style comes from: a URL to fetch it from, or the specification itself. Exactly one.
@@ -402,22 +380,21 @@ export type CustomStyle = CustomStyleSource & {
   lightDarkTheme?: LightDark;
 };
 /**
- * Array of all available style modules.
+ * Every {@link StylePart}.
  *
  * @group Map Style
  */
-export declare const styleModules: readonly ["trafficIncidents", "trafficFlow", "hillshade"];
+export declare const styleParts: readonly ["trafficIncidents", "trafficFlow", "terrain"];
 /**
- * Optional map modules that can be included with a style.
+ * Optional part of a standard style, included or left out with {@link StandardStyle.include}.
  *
- * @remarks
- * - `trafficIncidents`: Shows real-time traffic incidents on the map
- * - `trafficFlow`: Shows real-time traffic flow with color-coded speeds
- * - `hillshade`: Adds terrain elevation data, drawn by {@link TerrainModule} as hillshade shading and 3D terrain
+ * - `trafficIncidents`: real-time traffic incidents
+ * - `trafficFlow`: real-time traffic flow
+ * - `terrain`: elevation data, drawn by {@link TerrainModule} as hillshade and 3D terrain
  *
  * @group Map Style
  */
-export type StyleModule = (typeof styleModules)[number];
+export type StylePart = (typeof styleParts)[number];
 /**
  * Map style specification for initialization.
  *
@@ -439,7 +416,7 @@ export type StyleModule = (typeof styleModules)[number];
  * style: {
  *   type: 'standard',
  *   id: 'standardLight',
- *   include: ['trafficFlow', 'hillshade']
+ *   include: ['trafficFlow', 'terrain']
  * }
  *
  * // 3. Custom style from URL
@@ -1416,7 +1393,7 @@ type LayerFilterContributions = {
 /**
  * The single owner of a style layer's `filter`.
  *
- * Several modules narrow the same layer: {@link POIsModule.filterCategories} adds a category clause
+ * Several modules narrow the same layer: the {@link POIsModule} category filter adds a clause
  * to the POI layer, and the styling knob `pois.zoomShift` rewrites the density term inside that same
  * layer's filter. Each rebuilding the filter from its own snapshot of the style means whichever
  * writes last drops the other's work, with nothing to show that it happened.
@@ -1596,7 +1573,7 @@ export type StylingEvents = CombinedEvents<MapGeoJSONFeature, StylingSettings, n
  * never shows them while {@link POIsModule} or {@link BaseMapModule} hides them, and unsetting one
  * leaves the layers as their module has them.
  *
- * `pois.zoomShift` rewrites the POI layer filters, which {@link POIsModule.filterCategories} also
+ * `pois.zoomShift` rewrites the POI layer filters, which the {@link POIsModule} category filter also
  * narrows: the two compose, so either can be set at any time and neither drops the other.
  *
  * @example
@@ -1944,7 +1921,7 @@ export type SetStyleOptions = {
    * Whether to drop the SDK state instead of carrying it over to the new style.
    *
    * - `false` (default): module data and configuration, filters and the style parts of the
-   *   previous style (traffic, hillshade) are restored onto the new style.
+   *   previous style (traffic, terrain) are restored onto the new style.
    * - `true`: a clean switch. Modules re-bind to the new style with default configuration and
    *   nothing shown, and only the style parts named in the new style input are loaded.
    *
@@ -2207,7 +2184,7 @@ export declare class TomTomMap {
    *   style: {
    *     type: 'standard',
    *     id: 'standardLight',
-   *     include: ['trafficFlow', 'hillshade']
+   *     include: ['trafficFlow', 'terrain']
    *   },
    *   language: 'en-US',
    *   events: {
@@ -2287,7 +2264,7 @@ export declare class TomTomMap {
    * map.setStyle({
    *   type: 'standard',
    *   id: 'standardLight',
-   *   include: ['trafficFlow', 'hillshade']
+   *   include: ['trafficFlow', 'terrain']
    * });
    * ```
    *
@@ -2315,7 +2292,7 @@ export declare class TomTomMap {
    *
    * @see {@link TomTomMapParams.style} - For setting style during initialization
    * @see {@link StyleChangeHandler} - For handling style change events
-   * @see {@link getStyle} - For retrieving the current style
+   * @see {@link getStyleInput} - For retrieving the current style input
    * @see [Map Styles Guide](https://docs.tomtom.com/maps-sdk-js/guides/map/styles)
    */
   setStyle: (style: StyleInput, options?: SetStyleOptions) => Promise<void>;
@@ -2324,46 +2301,18 @@ export declare class TomTomMap {
   private isSuperseded;
   private notifyHandlers;
   /**
-   * Retrieves the current style configuration of the map.
-   *
-   * @returns The current {@link StyleInput} configuration, or `undefined` if no style is set.
-   *
-   * @remarks
-   * Returns the style configuration as it was set, not the fully resolved MapLibre style object.
-   * Use this to inspect or store the current style configuration for later restoration.
-   *
-   * **Return Value:**
-   * - String ID (e.g., `'standardLight'`) for simple style configurations
-   * - Style object with `type`, `id`, and optional `include` properties for detailed configurations
-   * - `undefined` if no style has been explicitly set
-   *
-   * @example
-   * ```typescript
-   * const currentStyle = map.getStyle();
-   * console.log('Current style:', currentStyle);
+   * The {@link StyleInput} the map was last given, through its parameters or {@link setStyle}.
    *
-   * // Save style for later
-   * const savedStyle = map.getStyle();
-   *
-   * // Later, restore it
-   * if (savedStyle) {
-   *   map.setStyle(savedStyle);
-   * }
-   * ```
+   * The input as it was given, not the resolved style specification: that is
+   * {@link StylingModule.exportStyle}, or `mapLibreMap.getStyle()`.
    *
    * @example
-   * Conditional logic based on current style:
    * ```typescript
-   * const style = map.getStyle();
-   * if (typeof style === 'string' && style.includes('Dark')) {
-   *   console.log('Dark mode is active');
-   * }
+   * const style = map.getStyleInput();
+   * if (style) map.setStyle(style);
    * ```
-   *
-   * @see {@link setStyle} - For changing the map style
-   * @see {@link StyleInput} - For available style configuration options
    */
-  getStyle: () => StyleInput | undefined;
+  getStyleInput: () => StyleInput | undefined;
   /**
    * Re-tags the `tomtom-user-agent` header this map sends on its MapLibre requests (style, tiles,
    * sprites, glyphs), letting a product embedding the SDK count the traffic under its own name,
@@ -2609,7 +2558,7 @@ export declare class TomTomMap {
    * ```typescript
    * map.addStyleChangeHandler({
    *   onStyleAboutToChange: async () => {
-   *     await saveStateToAPI(map.getStyle());
+   *     await saveStateToAPI(map.getStyleInput());
    *   },
    *   onStyleChanged: async () => {
    *     await loadStateFromAPI();
@@ -2626,7 +2575,7 @@ export declare class TomTomMap {
    *   },
    *   onStyleChanged: () => {
    *     document.body.classList.remove('style-changing');
-   *     const style = map.getStyle();
+   *     const style = map.getStyleInput();
    *     if (typeof style === 'string' && style.includes('Dark')) {
    *       document.body.classList.add('dark-mode');
    *     } else {
@@ -2711,6 +2660,7 @@ export declare class TomTomMap {
  *
  * @see {@link GeometryBeforeLayerConfig} for GeometriesModule layer positioning options
  * @see {@link RoutingBeforeLayerConfig} for RoutingModule layer positioning options
+ * @see {@link PlacesBeforeLayerConfig} for PlacesModule layer positioning options
  *
  * @group Map Style
  */
@@ -3052,6 +3002,11 @@ export declare class AddedSourceWithLayers<SOURCE_SPEC extends SourceSpecificati
   private ensureLayersAddedToMap;
   ensureAddedToMapWithVisibility(visible: boolean, addLayersToMap: boolean): void;
 }
+/**
+ * A copy of the feature with the given event state, or without one.
+ * @ignore
+ */
+export declare const withEventState: <F extends Feature>(feature: F, eventState: EventState | undefined) => F;
 /**
  * Options for the {@link GeoJSONSourceWithLayers.show} method.
  * @ignore
@@ -3092,9 +3047,16 @@ export declare class GeoJSONSourceWithLayers<T extends FeatureCollection = Featu
   findById(id: string | number | undefined): IndexedFeature<T['features'][number]> | undefined;
   clear(): void;
   private findFeature;
+  private showWithFeatures;
   putEventState(options: PutEventStateOptions): void;
   cleanEventState(options: CleanEventStateOptions): void;
   cleanEventStates(options?: CleanEventStatesOptions): void;
+  /**
+   * Collects the ids of the shown features by event state into `into`, skipping an id already
+   * listed under its state, so several sources showing the same features can share one result.
+   * A feature without an id is skipped: {@link ByIdOrIndex} could not address it by one.
+   */
+  getEventStates(into?: EventStateIds): EventStateIds;
 }
 //#endregion
 //#region src/shared/types/mapsSDKLayerSpecs.d.ts
@@ -3399,26 +3361,20 @@ type EventType = ClickEventType | HoverEventType;
  */
 type EventState = EventType | 'recently-hovered';
 /**
- * Parameters to identify a feature by its ID or index in a given features array.
+ * Parameters to identify a shown feature by its ID or by its index.
  * @group User Interaction Events
  */
 type ByIdOrIndex = {
   /**
-   * The unique identifier of the feature.
-   *
-   * @remarks
-   * This ID corresponds to the `id` property of the feature being targeted.
-   * Cannot be used together with `index`.
+   * The id of the feature: its `properties.id`, else its top-level `id` — the id the
+   * module's `getShown()` and event handlers hand back. Cannot be used together with `index`.
    */
-  id: string;
+  id: string | number;
 } | {
   /**
-   * The index of the feature in the feature array.
-   *
-   * @remarks
-   * Zero-based index referring to the position in the features array
-   * that was passed to the module's show method.
-   * Cannot be used together with `id`.
+   * The zero-based position of the feature in the collection the module's `getShown()`
+   * returns for it. Where a module draws its features in several sources, each source counts
+   * its own. Cannot be used together with `id`.
    */
   index: number;
 };
@@ -3590,6 +3546,22 @@ type CleanEventStatesOptions = {
    */
   show?: boolean;
 };
+/**
+ * The ids of the shown features that have an event state, by state: what `putEventState` and
+ * user interactions have put, and `cleanEventState(s)` hasn't taken off yet.
+ *
+ * @remarks
+ * A state no feature has is absent rather than an empty array. The ids are those
+ * {@link ByIdOrIndex} takes, so each can go straight back into `putEventState` or `cleanEventState`.
+ *
+ * @example
+ * ```typescript
+ * const { click: [selectedID] = [] } = placesModule.getEventStates();
+ * ```
+ *
+ * @group User Interaction Events
+ */
+type EventStateIds = Partial<Record<EventState, (string | number)[]>>;
 /**
  * Properties part for an object that can have event state.
  *
@@ -5479,6 +5451,16 @@ 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>;
+  /**
+   * What {@link userEvents} builds a scope from, for a subclass that builds a richer one.
+   * @ignore
+   */
+  protected userEventsOptions<T, WHERE_SCOPE>(sourceNames: (keyof SOURCES_WITH_LAYERS)[], options: EventScopeOptions<T, WHERE_SCOPE>): UserEventsOptions<T, WHERE_SCOPE>;
+  /**
+   * The current sources of the given names, skipping the ones this module does not have now.
+   * @ignore
+   */
+  protected sourcesNamed(sourceNames: (keyof SOURCES_WITH_LAYERS)[]): SOURCES_WITH_LAYERS[keyof SOURCES_WITH_LAYERS][];
   /**
    * `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}.
@@ -5515,6 +5497,42 @@ export declare abstract class AbstractMapModule<SOURCES_WITH_LAYERS extends Sour
   protected buildEvents<T, TShown, WHERE_SCOPE, NAMED_SCOPES extends object>(moduleWide: CombinedEvents<T, CFG, TShown, WHERE_SCOPE>, scopes: NAMED_SCOPES): CombinedEvents<T, CFG, TShown, WHERE_SCOPE> & NAMED_SCOPES;
 }
 //#endregion
+//#region src/shared/UserEventsWithStates.d.ts
+/**
+ * A named events scope of a module that draws its own data: the {@link UserEvents} of one part of
+ * what the module shows, plus the event states of those features.
+ *
+ * @remarks
+ * The module's own `putEventState`, `cleanEventState`, `cleanEventStates` and `getEventStates` act
+ * on the features its `show` takes; a scope's act on the scope's features alone, by the ids its
+ * handlers receive — `routing.events.waypoints` on the waypoints, `custom.events.<source>` on one
+ * source. A {@link UserEvents.where} narrowing returns plain {@link UserEvents}: a state belongs to
+ * a feature, not to a predicate over features.
+ *
+ * @example
+ * ```typescript
+ * routing.events.waypoints.putEventState({ id: waypoint.id, state: 'click' });
+ * const { hover: hoveredStops = [] } = routing.events.waypoints.getEventStates();
+ * ```
+ *
+ * @group User Interaction Events
+ */
+export declare class UserEventsWithStates<T = MapGeoJSONFeature> extends UserEvents<T> {
+  private readonly eventStates;
+  /**
+   * @param sources Resolves the sources this scope's features are drawn in, on every call.
+   */
+  constructor(options: UserEventsOptions<T, never>, sources: () => GeoJSONSourceWithLayers[]);
+  /** Puts an event state on one of this scope's features; see {@link PutEventStateOptions}. */
+  putEventState(options: PutEventStateOptions): void;
+  /** Takes the event state off one of this scope's features. */
+  cleanEventState(options: CleanEventStateOptions): void;
+  /** Takes the given event states, or all of them, off this scope's features. */
+  cleanEventStates(options?: CleanEventStatesOptions): void;
+  /** The ids of this scope's features that have an event state, by state. */
+  getEventStates(): EventStateIds;
+}
+//#endregion
 //#region src/shared/AbstractDataOwnedMapModule.d.ts
 /**
  * Base class for the map modules that add and own their own GeoJSON sources, layers and images:
@@ -5530,6 +5548,12 @@ export declare abstract class AbstractMapModule<SOURCES_WITH_LAYERS extends Sour
  *
  * Every such module hides and shows through {@link setVisible}, which keeps the data it shows.
  *
+ * Owning the features also lets it read and write their {@link EventState | event states}:
+ * {@link putEventState}, {@link cleanEventState}, {@link cleanEventStates} and
+ * {@link getEventStates} act on the features its `show` takes, and each named scope of its
+ * `events` carries the same four over its own part ({@link UserEventsWithStates}). A style change
+ * shows again what its sources draw, not the data `show` was given, so the states survive it.
+ *
  * @typeParam SOURCES_WITH_LAYERS - The GeoJSON sources, with their layers, this module owns
  * @typeParam CFG - The configuration type for this module, or undefined if no configuration is needed
  *
@@ -5538,6 +5562,7 @@ export declare abstract class AbstractMapModule<SOURCES_WITH_LAYERS extends Sour
 export declare abstract class AbstractDataOwnedMapModule<SOURCES_WITH_LAYERS extends GeoJSONSourcesWithLayers, CFG extends (MapModuleCommonConfig & {
   visible?: boolean;
 }) | undefined = undefined> extends AbstractMapModule<SOURCES_WITH_LAYERS, CFG> {
+  private readonly eventStates;
   /**
    * Owning the data it draws, such a module always remembers something a clean style switch must
    * forget, so the inherited no-op becomes a duty here. A module that remembers nothing
@@ -5577,6 +5602,75 @@ export declare abstract class AbstractDataOwnedMapModule<SOURCES_WITH_LAYERS ext
    * module with nothing shown draws nothing; `getShown()` returns what is shown.
    */
   isVisible(): boolean;
+  /**
+   * The sources drawing the features `show` takes, which the event-state methods act on. Several
+   * when the module draws those features more than once; missing ones are skipped.
+   * @protected
+   * @ignore
+   */
+  protected abstract eventStateSources(): (keyof SOURCES_WITH_LAYERS)[];
+  /**
+   * A named events scope over the given sources, carrying their event states as well.
+   * @ignore
+   */
+  protected userEventsWithStates<T = MapGeoJSONFeature>(sourceNames: (keyof SOURCES_WITH_LAYERS)[], options?: Pick<UserEventsOptions<T, never>, 'mapping'>): UserEventsWithStates<T>;
+  /**
+   * Puts an event state on one of the shown features, as a user interaction would.
+   *
+   * @remarks
+   * The state is what the module's own layers draw (place pins and entry points, route outlines,
+   * geometries, details-module incidents, area-analytics cells), what layers of yours read with
+   * `['get', 'eventState']`, and what {@link getEventStates} returns. It lasts as long as the shown
+   * feature does: through {@link setVisible}, style and configuration changes, not through a new
+   * `show`, a `clear` or a `setStyle` with `resetState`.
+   *
+   * @example
+   * ```typescript
+   * // Select a feature from a list, as a click would
+   * module.putEventState({ id: feature.id, state: 'click' });
+   *
+   * // Hover a second one without taking the hover off the first
+   * module.putEventState({ index: 2, state: 'hover', mode: 'add' });
+   * ```
+   */
+  putEventState(options: PutEventStateOptions): void;
+  /**
+   * Takes the event state off one of the shown features.
+   *
+   * @example
+   * ```typescript
+   * module.cleanEventState({ id: feature.id });
+   * ```
+   */
+  cleanEventState(options: CleanEventStateOptions): void;
+  /**
+   * Takes the given event states, or all of them, off the shown features.
+   *
+   * @example
+   * ```typescript
+   * module.cleanEventStates(); // every state
+   * module.cleanEventStates({ states: ['hover'] }); // hovers only, selections stay
+   * ```
+   */
+  cleanEventStates(options?: CleanEventStatesOptions): void;
+  /**
+   * Returns the ids of the shown features that have an event state, by state.
+   *
+   * @remarks
+   * The read side of {@link putEventState} and {@link cleanEventStates}: it reflects those and
+   * the states user interactions put. The ids are those `getShown()` and the event handlers hand
+   * back, so each can go straight back into {@link putEventState}.
+   *
+   * @example
+   * ```typescript
+   * // Keep a list in sync with the selected feature
+   * const { click: [selectedID] = [] } = module.getEventStates();
+   *
+   * // Is this feature hovered?
+   * const hovered = module.getEventStates().hover?.includes(feature.id) ?? false;
+   * ```
+   */
+  getEventStates(): EventStateIds;
 }
 //#endregion
 //#region src/shared/layers/layerVisibilityComposer.d.ts
@@ -5786,12 +5880,24 @@ export declare const validateKnobValue: (knob: KnobEntry<string>, value: unknown
 export declare const setKnob: <CONFIG extends MapModuleCommonConfig, ID extends string, KNOB extends ID>(module: Pick<AbstractMapModule<SourcesWithLayers, CONFIG>, "getConfig" | "applyConfig">, catalogue: readonly KnobEntry<ID>[], id: KNOB, value: KnobPlainValue<ValueAt<CONFIG, KNOB>>) => void;
 //#endregion
 //#region src/shared/layers/sourcesIDs.d.ts
+/**
+ * Source identifier for base map vector tiles.
+ *
+ * @remarks
+ * References the primary vector tile source containing roads, buildings,
+ * land use, water bodies, and other fundamental map features.
+ *
+ * @group Base Map
+ */
+export declare const BASE_MAP_SOURCE_ID = "vectorTiles";
 /**
  * Source identifier for POI (Point of Interest) vector tiles.
  *
  * @remarks
  * Used to reference the POI layer in the map style, which contains
- * business locations, landmarks, and other points of interest.
+ * business locations, landmarks, and other points of interest. The base map
+ * tiles carry them, so this is {@link BASE_MAP_SOURCE_ID} under the name the
+ * POI layers are selected by.
  *
  * @group POIs
  */
@@ -5816,16 +5922,6 @@ export declare const HILLSHADE_SOURCE_ID = "hillshade";
  * @group Terrain
  */
 export declare const TERRAIN_SOURCE_ID = "hillshade-terrain";
-/**
- * Source identifier for base map vector tiles.
- *
- * @remarks
- * References the primary vector tile source containing roads, buildings,
- * land use, water bodies, and other fundamental map features.
- *
- * @group Base Map
- */
-export declare const BASE_MAP_SOURCE_ID = "vectorTiles";
 /**
  * Source identifier for traffic incidents vector tiles.
  *
@@ -6480,7 +6576,7 @@ export type CustomGeoJSONShownFeatures<TSources extends Record<string, FeatureCo
   sourceName: K;
   data: TSources[K];
 }; }[keyof TSources];
-export type CustomGeoJSONEvents<TSources extends Record<string, FeatureCollection>> = CombinedEvents<MapGeoJSONFeature, CustomGeoJSONModuleConfig<TSources>, CustomGeoJSONShownFeatures<TSources>> & { [K in keyof TSources]: UserEvents<MapGeoJSONFeature>; };
+export type CustomGeoJSONEvents<TSources extends Record<string, FeatureCollection>> = CombinedEvents<MapGeoJSONFeature, CustomGeoJSONModuleConfig<TSources>, CustomGeoJSONShownFeatures<TSources>> & { [K in keyof TSources]: UserEventsWithStates<MapGeoJSONFeature>; };
 /**
  * Module for displaying customer-owned GeoJSON data with TomTom SDK support.
  *
@@ -6557,7 +6653,7 @@ export type CustomGeoJSONEvents<TSources extends Record<string, FeatureCollectio
 export declare class CustomGeoJSONModule<TSources extends Record<string, FeatureCollection> = Record<string, FeatureCollection>> extends AbstractDataOwnedMapModule<CustomGeoJSONSourcesWithLayers<TSources>, CustomGeoJSONModuleConfig<TSources>> {
   private resolvedSourceIDs;
   private resolvedLayerSpecs;
-  private lastShown;
+  private shownSourceNames;
   private initialConfig;
   private readonly shownFeaturesHandlers;
   /**
@@ -6620,6 +6716,12 @@ export declare class CustomGeoJSONModule<TSources extends Record<string, Feature
    * feature collection that `GeoJSONSourceWithLayers` keeps as initial state.
    */
   getShown(): { [K in keyof TSources]: TSources[K]; };
+  /**
+   * Every source: the module's event-state methods act on all of them, as a `show` without a
+   * source name does. Act on one source through its scope, `events.<sourceName>`.
+   * @ignore
+   */
+  protected eventStateSources(): Array<keyof TSources>;
   /**
    * Per-source events surface.
    *
@@ -6692,33 +6794,6 @@ export declare const customGeoJSONKnobCatalogue: readonly CustomGeoJSONKnob[];
  */
 export declare const customGeoJSONKnobIds: readonly CustomGeoJSONKnobId[];
 //#endregion
-//#region src/geometry/layers/colorPalettes.d.ts
-export declare const colorPalettes: {
-  warm: string[];
-  browns: string[];
-  cold: string[];
-  fadedBlues: string[];
-  blues: string[];
-  greens: string[];
-  fadedGreenToBlue: string[];
-  blueToRed: string[];
-  greenToYellow: string[];
-  pastel: string[];
-  retro: string[];
-  contrastRetro: string[];
-  fadedRainbow: string[];
-  pastelRainbow: string[];
-};
-export type ColorPaletteOptions = keyof typeof colorPalettes;
-export declare const colorPaletteIDs: ColorPaletteOptions[];
-/**
- * Adapts a fill palette for the active map theme. Light themes pass through unchanged; for dark
- * themes each colour is nudged toward a mid, saturated tone — pale ramps are deepened so they read
- * against the dark base map, near-black ramps are lifted so they don't vanish.
- * @ignore
- */
-export declare const adaptPaletteForTheme: (colors: string[], lightDark: LightDark) => string[];
-//#endregion
 //#region src/geometry/types/geometryFillStyle.d.ts
 /**
  * How {@link GeometriesModule} fills a polygon.
@@ -6749,8 +6824,8 @@ export declare const geometryFillStyles: readonly ["filled", "outline", "inverte
  * // Solid color with opacity
  * const fill: GeometryFillConfig = { color: '#FF5733', opacity: 0.3 };
  *
- * // One colour per feature, in turn, from a palette
- * const fill: GeometryFillConfig = { palette: 'blues', opacity: 0.25 };
+ * // One colour per feature, in turn, from your own palette
+ * const fill: GeometryFillConfig = { palette: ['#1d3f8a', '#e63312', '#f5d000'], opacity: 0.25 };
  *
  * // Data-driven color based on properties
  * const fill: GeometryFillConfig = {
@@ -6772,14 +6847,15 @@ export type GeometryFillConfig = {
    */
   color?: string | ExpressionSpecification;
   /**
-   * Named palette the features take their fill colours from, one per feature in turn
-   * (see {@link colorPaletteIDs}). On dark map styles its colours are adapted to stay legible.
+   * CSS colours the features are filled with, one per feature in turn, starting over after the last.
+   * An empty list counts as unset.
    *
    * @remarks
    * Overrides the top-level {@link GeometriesModuleConfig.color}, for the fill and the border; the
-   * full order is on the latter.
+   * full order is on the latter. To follow a map theme, pass its colours — e.g.
+   * `[colors.accent, colors.vegetation, colors.water]` from the map-theme plugin's `deriveMapColors`.
    */
-  palette?: ColorPaletteOptions;
+  palette?: string[];
   /**
    * Fill opacity, 0 (transparent) to 1 (opaque). Also accepts a MapLibre expression.
    *
@@ -6905,11 +6981,43 @@ export type GeometryLineConfig = {
    */
   layer?: Partial<ToBeAddedLayerSpecTemplate<LineLayerSpecification>>;
 };
+/**
+ * How a hovered or clicked geometry is drawn: a denser fill and a wider border, in its own colours.
+ *
+ * @remarks
+ * The factors multiply the fill opacity and border width in force, the configured
+ * {@link GeometryFillConfig.opacity | fill.opacity} and {@link GeometryLineConfig.width | line.width}
+ * included; a `line.layer` `line-width` is drawn as given. The geometries draw their event states
+ * once a handler covers them, or {@link GeometriesModule.putEventState} puts one.
+ *
+ * @example
+ * ```typescript
+ * // A bolder border alone
+ * const highlight: GeometryHighlightConfig = { fillOpacityFactor: 1, lineWidthFactor: 2.5 };
+ * ```
+ *
+ * @group Geometries
+ */
+export type GeometryHighlightConfig = {
+  /**
+   * Multiplier on the fill opacity, at most opaque; `1` draws the fill as on any other geometry.
+   * Clamped to 1 to 4.
+   *
+   * @defaultValue `2`
+   */
+  fillOpacityFactor?: number;
+  /**
+   * Multiplier on the border width; `1` draws the border as on any other geometry. Clamped to 1 to 3.
+   *
+   * @defaultValue `1.75`
+   */
+  lineWidthFactor?: number;
+};
 /**
  * Labels placed along the polygon border lines: the center label's fields, plus where along the
  * border they repeat.
  *
- * When set, a symbol layer is added to the geometry source.
+ * When set, the border labels are drawn, including when set after the module is created.
  *
  * @remarks
  * Defaults for the unset fields:
@@ -7077,6 +7185,10 @@ export type GeometriesModuleConfig = MapModuleCommonConfig & {
    * Controls the outline appearance of polygon geometries.
    */
   line?: GeometryLineConfig;
+  /**
+   * How a hovered or clicked geometry is drawn.
+   */
+  highlight?: GeometryHighlightConfig;
   /**
    * Layer positioning configuration.
    *
@@ -7128,9 +7240,8 @@ export type GeometriesModuleConfig = MapModuleCommonConfig & {
    * properties from domain data.
    *
    * @remarks
-   * Used internally by {@link reachableRangeGeometryConfig} to generate budget
-   * labels (e.g. `'30 min'`) from feature properties. For most use cases,
-   * the standard config fields (`fill`, `label`, `fillStyle`) suffice.
+   * For most use cases the standard config fields (`fill`, `label`, `fillStyle`) suffice. Reachable
+   * ranges have their own module, {@link ReachableRangesModule}, which titles and colours each band.
    *
    * @example
    * ```typescript
@@ -7167,7 +7278,7 @@ export type GeometriesModuleConfig = MapModuleCommonConfig & {
  */
 export type GeometriesModuleSerializableConfig = Omit<GeometriesModuleConfig, 'transformFeaturesForDisplay'>;
 //#endregion
-//#region src/geometry/GeometriesModule.d.ts
+//#region src/geometry/AbstractGeometriesModule.d.ts
 /**
  * IDs of sources and layers from a geometry module.
  */
@@ -7176,17 +7287,157 @@ type GeometrySourcesWithLayers = {
   geometryLabel: GeoJSONSourceWithLayers<FeatureCollection<Point>>;
 };
 /**
- * Event surface of {@link GeometriesModule}: the module's own events, plus one named scope per
- * surface it manages.
+ * Event surface of a polygon module ({@link GeometriesModule}, {@link ReachableRangesModule}): the
+ * module's own events, plus one named scope per surface it manages.
  *
  * @group Geometries
  */
-export type GeometriesEvents = CombinedEvents<MapGeoJSONFeature, GeometriesModuleConfig, PolygonFeatures> & {
-  /** The geometry fills and outlines. */
-  geometry: UserEvents<MapGeoJSONFeature>;
-  /** The labels rendered on top of the geometries. */
-  geometryLabel: UserEvents<MapGeoJSONFeature>;
+export type GeometriesEvents<CFG = GeometriesModuleConfig> = CombinedEvents<MapGeoJSONFeature, CFG, PolygonFeatures> & {
+  /** The fills and outlines. */
+  geometry: UserEventsWithStates<MapGeoJSONFeature>;
+  /** The labels rendered on top of them. */
+  geometryLabel: UserEventsWithStates<MapGeoJSONFeature>;
 };
+/**
+ * Base of the modules that draw polygons with the geometry layers — fills, borders, border labels and
+ * titles: {@link GeometriesModule} and {@link ReachableRangesModule}.
+ *
+ * @remarks
+ * A subclass says how its own config reads as the geometry layers' ({@link displayConfig}) and how
+ * what it is shown becomes the polygons drawn ({@link prepareShown}); visibility, layer ordering,
+ * events and restoring after a style change are shared.
+ *
+ * @group Geometries
+ */
+export declare abstract class AbstractGeometriesModule<CFG extends MapModuleCommonConfig & Pick<GeometriesModuleConfig, 'visible' | 'beforeLayerConfig' | 'highlight'>> extends AbstractDataOwnedMapModule<GeometrySourcesWithLayers, CFG> {
+  private titleLayerSpecs;
+  private geometryFillLayerSpecs;
+  private geometryOutlineLayerSpecs;
+  private lineLabelLayerSpecs;
+  private sourceID;
+  private fillLayerID;
+  private outlineLayerID;
+  private lineLabelLayerID;
+  private titleSourceID;
+  private titleLayerID;
+  private lastRawInput;
+  private readonly shownFeaturesHandlers;
+  protected constructor(map: TomTomMap, config?: CFG);
+  /**
+   * What the ids of this module's sources and layers start with, before the instance index. Unique
+   * per subclass, whose instances are counted apart.
+   * @ignore
+   */
+  protected abstract get idPrefix(): string;
+  /**
+   * The geometry layers' config for this module's own. Called while the module is constructed, so it
+   * reads nothing but `config`.
+   * @ignore
+   */
+  protected abstract displayConfig(config: CFG | undefined): GeometriesModuleConfig | undefined;
+  /**
+   * The polygons drawn for what `show` was given, before the geometry layers' own preparation.
+   * @ignore
+   */
+  protected abstract prepareShown(input: PolygonFeatures, config: CFG | undefined): PolygonFeatures;
+  /** Current light/dark map theme, re-read on every layer/data build so style switches repaint. */
+  protected get lightDark(): LightDark;
+  /**
+   * The map's colour for what carries no `color` under a config without a top-level `color`: the
+   * accent when a theme has set one, otherwise a colour that follows the active light/dark theme.
+   */
+  protected get defaultColor(): string;
+  /**
+   * @ignore
+   */
+  protected _initSourcesWithLayers(config?: CFG, restore?: boolean): GeometrySourcesWithLayers;
+  /**
+   * @ignore
+   */
+  protected _applyConfig(config: CFG | undefined): CFG | undefined;
+  /** @ignore */
+  protected applyVisibility(config: CFG | undefined): void;
+  private get partLayerIDs();
+  private applyBeforeLayerConfig;
+  private updateLayers;
+  /**
+   * @ignore
+   */
+  protected discardShownData(): void;
+  /**
+   * @ignore
+   */
+  protected restoreDataAndConfigImpl(): void;
+  /**
+   * Draws what `show` was last given again, prepared for `config`, keeping the identity of the
+   * polygons `shown` before.
+   * @ignore
+   */
+  protected displayAgain(config: CFG | undefined, shown: PolygonFeatures): void;
+  private prepare;
+  private display;
+  /**
+   * Replaces what the module shows; the subclass's `show`.
+   * @ignore
+   */
+  protected showPolygons(input: PolygonFeatures): Promise<void>;
+  /**
+   * Removes everything the module shows.
+   *
+   * @remarks
+   * - Clears both the polygons and their labels
+   * - Does not reset styling configuration
+   * - Module remains initialized and ready for new data
+   *
+   * @example
+   * ```typescript
+   * await module.clear();
+   * await module.show(newData);
+   * ```
+   */
+  clear(): Promise<void>;
+  /**
+   * Returns the polygons and labels currently drawn, as prepared for display.
+   *
+   * @example
+   * ```typescript
+   * const shown = module.getShown();
+   * console.log(`Polygons: ${shown.geometry.features.length}`);
+   * ```
+   */
+  getShown(): {
+    geometry: PolygonFeatures;
+    geometryLabel: FeatureCollection<Point, GeoJsonProperties>;
+  };
+  /** @ignore */
+  protected eventStateSources(): (keyof GeometrySourcesWithLayers)[];
+  /**
+   * Gets the events interface for handling user interactions with the polygons.
+   *
+   * @returns The module's events, with `on` / `off` for handlers and `where` for scoping.
+   *
+   * @remarks
+   * **Supported Events:**
+   * - `click`: User clicks on a polygon
+   * - `contextmenu`: User right-clicks on a polygon
+   * - `hover`: Mouse enters a polygon
+   * - `long-hover`: Mouse hovers over a polygon for extended time
+   *
+   * @example
+   * ```typescript
+   * module.events.on('click', (feature, lngLat) => {
+   *   console.log('Clicked:', feature.properties);
+   *   console.log('Location:', lngLat);
+   * });
+   *
+   * // Only the polygons, not their labels
+   * module.events.geometry.on('hover', (feature) => showTooltip(feature.properties.title));
+   * ```
+   */
+  get events(): GeometriesEvents<CFG>;
+}
+//#endregion
+//#region src/geometry/GeometriesModule.d.ts
 /**
  * Geometries Module for displaying polygon areas with custom styling on the map.
  *
@@ -7208,9 +7459,10 @@ export type GeometriesEvents = CombinedEvents<MapGeoJSONFeature, GeometriesModul
  * - Accepts GeoJSON Polygon and MultiPolygon features
  * - Supports FeatureCollection for multiple geometries
  * - Compatible with TomTom Search API geometry results
+ * - Reachable ranges have a module of their own, {@link ReachableRangesModule}
  *
  * **Styling:**
- * - Use predefined color palettes or custom colors
+ * - One colour, a palette of your own, or the map's accent by default
  * - Apply MapLibre expressions for dynamic styling
  * - Per-feature styling via feature properties
  *
@@ -7286,19 +7538,7 @@ export type GeometriesEvents = CombinedEvents<MapGeoJSONFeature, GeometriesModul
  *
  * @group Geometries
  */
-export declare class GeometriesModule extends AbstractDataOwnedMapModule<GeometrySourcesWithLayers, GeometriesModuleConfig> {
-  private titleLayerSpecs;
-  private geometryFillLayerSpecs;
-  private geometryOutlineLayerSpecs;
-  private lineLabelLayerSpecs;
-  private sourceID;
-  private fillLayerID;
-  private outlineLayerID;
-  private lineLabelLayerID;
-  private titleSourceID;
-  private titleLayerID;
-  private lastRawInput;
-  private readonly shownFeaturesHandlers;
+export declare class GeometriesModule extends AbstractGeometriesModule<GeometriesModuleConfig> {
   /**
    * Make sure the map is ready before create an instance of the module and any other interaction with the map
    * @param tomtomMap The TomTomMap instance.
@@ -7358,83 +7598,12 @@ export declare class GeometriesModule extends AbstractDataOwnedMapModule<Geometr
    */
   static create(tomtomMap: TomTomMap, config?: GeometriesModuleConfig): Promise<GeometriesModule>;
   private constructor();
-  /** Current light/dark map theme, re-read on every layer/data build so style switches repaint. */
-  private get lightDark();
-  /**
-   * The map's fill / plain-outline colour for a feature that carries no `color` and a config without
-   * a top-level `color`: the published accent when a theme has set one, otherwise a colour that
-   * follows the active light/dark theme.
-   */
-  private get defaultColor();
-  /**
-   * @ignore
-   */
-  protected _initSourcesWithLayers(config?: GeometriesModuleConfig, restore?: boolean): GeometrySourcesWithLayers;
-  /**
-   * @ignore
-   */
-  protected _applyConfig(config: GeometriesModuleConfig | undefined): GeometriesModuleConfig | undefined;
   /** @ignore */
-  protected applyVisibility(config: GeometriesModuleConfig | undefined): void;
-  private get partLayerIDs();
-  /**
-   * Positions the geometry layers relative to other map layers.
-   *
-   * @param layerConfig - Layer positioning. A single {@link BeforeLayerConfig} (`'top'` or a layer
-   * id) moves all geometry layers together; the record form (`{ all?, fill?, line? }`) positions the
-   * fill and border independently, leaving a part it names no target for where it is.
-   *
-   * **Available Layer IDs:** the keys of `mapStyleLayerIDs`.
-   *
-   * @example
-   * ```typescript
-   * // Place all geometry layers below labels
-   * geometries.moveBeforeLayer('lowestLabel');
-   *
-   * // Fill below the road network, border on top
-   * geometries.moveBeforeLayer({ fill: 'lowestRoadLine', line: 'top' });
-   * ```
-   */
-  moveBeforeLayer(layerConfig: GeometryBeforeLayerConfig): void;
-  private applyBeforeLayerConfig;
-  /**
-   * Updates the label at the center of each displayed geometry: its text and styling.
-   *
-   * @param label - New label configuration.
-   *
-   * @remarks
-   * **Configuration:**
-   * - `text`: label text, a string or a MapLibre expression; the feature's `title` when unset
-   * - `size`, `color`, `haloColor`, `haloWidth`, `opacity`, `font`: label styling
-   * - Changes apply to currently shown and future geometries
-   *
-   * @example
-   * ```typescript
-   * // Show feature property as label
-   * geometries.applyLabelConfig({
-   *   text: ['get', 'name']
-   * });
-   *
-   * // Conditional labels, in white
-   * geometries.applyLabelConfig({
-   *   text: [
-   *     'case',
-   *     ['has', 'label'],
-   *     ['get', 'label'],
-   *     ['get', 'title']
-   *   ],
-   *   color: '#FFFFFF',
-   * });
-   * ```
-   */
-  applyLabelConfig(label: GeometryLabelConfig): void;
-  private updateLayers;
-  /**
-   * @ignore
-   */
-  protected discardShownData(): void;
-  private prepare;
-  private display;
+  protected get idPrefix(): string;
+  /** @ignore */
+  protected displayConfig(config: GeometriesModuleConfig | undefined): GeometriesModuleConfig | undefined;
+  /** @ignore */
+  protected prepareShown(geometries: PolygonFeatures, config: GeometriesModuleConfig | undefined): PolygonFeatures;
   /**
    * Displays the given polygon geometries on the map.
    *
@@ -7492,114 +7661,9 @@ export declare class GeometriesModule extends AbstractDataOwnedMapModule<Geometr
    * ```
    */
   show(geometries: PolygonFeatures): Promise<void>;
-  /**
-   * Removes all geometries from the map.
-   *
-   * @remarks
-   * - Clears both geometry layers and labels
-   * - Does not reset styling configuration
-   * - Module remains initialized and ready for new data
-   *
-   * @example
-   * ```typescript
-   * // Clear displayed geometries
-   * await geometries.clear();
-   *
-   * // Show new geometries
-   * await geometries.show(newGeometries);
-   * ```
-   */
-  clear(): Promise<void>;
-  /**
-   * Returns the currently shown geometries.
-   *
-   * @returns The geometries currently displayed on the map.
-   *
-   * @remarks
-   * Returns the exact data that was passed to the `show()` method.
-   *
-   * @example
-   * ```typescript
-   * const shown = geometriesModule.getShown();
-   * console.log(`Geometries: ${shown.geometry.features.length}`);
-   * ```
-   */
-  getShown(): {
-    geometry: PolygonFeatures;
-    geometryLabel: FeatureCollection<Point, GeoJsonProperties>;
-  };
-  /**
-   * Gets the events interface for handling user interactions with geometries.
-   *
-   * @returns The module's events, with `on` / `off` for handlers and `where` for scoping.
-   *
-   * @remarks
-   * **Supported Events:**
-   * - `click`: User clicks on a geometry
-   * - `contextmenu`: User right-clicks on a geometry
-   * - `hover`: Mouse enters a geometry
-   * - `long-hover`: Mouse hovers over geometry for extended time
-   *
-   * **Event Features:**
-   * - Receive the original feature data passed to `show()`
-   * - Access feature properties and geometry
-   * - Get click/hover coordinates
-   *
-   * @example
-   * Basic event handling:
-   * ```typescript
-   * geometries.events.on('click', (feature, lngLat) => {
-   *   console.log('Clicked:', feature.properties);
-   *   console.log('Location:', lngLat);
-   * });
-   * ```
-   *
-   * @example
-   * Multiple handlers:
-   * ```typescript
-   * // Highlight on hover
-   * geometries.events.on('hover', (feature) => {
-   *   highlightGeometry(feature.id);
-   * });
-   *
-   * // Show details on click
-   * geometries.events.on('click', (feature) => {
-   *   showDetailPanel(feature.properties);
-   * });
-   *
-   * // Context menu
-   * geometries.events.on('contextmenu', (feature, lngLat) => {
-   *   showContextMenu(lngLat, feature);
-   * });
-   * ```
-   */
-  get events(): GeometriesEvents;
 }
 //#endregion
 //#region src/geometry/types/geometryConfigOptions.d.ts
-/**
- * Custom title generator for reachable range features: the text of each range's labels.
- *
- * @group Geometries
- */
-export type ReachableRangeTitleFn = (feature: PolygonFeature, index: number) => string;
-/**
- * Options of {@link prepareReachableRangesForDisplay}.
- *
- * @group Geometries
- */
-export type ReachableRangesDisplayOptions = {
-  /**
-   * How each range is filled.
-   *
-   * @default 'filled'
-   */
-  fillStyle?: GeometryFillStyle;
-  /**
-   * Each range's title, shown by its labels. Unset, it is the feature's `budget`, e.g. `'30 min'`.
-   */
-  title?: ReachableRangeTitleFn;
-};
 /**
  * Options of {@link fillStyledGeometryConfig}.
  *
@@ -7607,11 +7671,10 @@ export type ReachableRangesDisplayOptions = {
  */
 export type FillStyledGeometryConfigOptions = {
   /**
-   * Color palette for polygon fills.
-   *
-   * @default 'fadedRainbow'
+   * CSS colours the features are filled with, one per feature in turn. Unset, they draw in the
+   * module's default colour, the map's accent when a theme sets one ({@link GeometriesModuleConfig.color}).
    */
-  palette?: ColorPaletteOptions;
+  palette?: NonNullable<GeometryFillConfig['palette']>;
   /**
    * Layer positioning.
    *
@@ -7619,61 +7682,38 @@ export type FillStyledGeometryConfigOptions = {
    */
   beforeLayerConfig?: GeometryBeforeLayerConfig;
 };
-/**
- * Options of {@link reachableRangeGeometryConfig}: the palette and positioning of
- * {@link fillStyledGeometryConfig}, and how {@link prepareReachableRangesForDisplay} fills and titles
- * each range.
- *
- * @group Geometries
- */
-export type ReachableRangeGeometryConfigOptions = FillStyledGeometryConfigOptions & ReachableRangesDisplayOptions;
 //#endregion
 //#region src/geometry/geometryConfigs.d.ts
 /**
- * Config that draws each polygon by its own fill style, with palette-based coloring.
+ * Config that draws each polygon by its own fill style, optionally coloured from a palette.
  *
  * Includes data-driven expressions so each feature's `fillStyle` property controls its
  * styling, line labels config, and positions layers below map labels.
  *
- * For reachable ranges, use {@link reachableRangeGeometryConfig} which extends this
- * with auto-generated labels.
+ * Reachable ranges have their own module, {@link ReachableRangesModule}, drawn in these styles too.
  *
  * @example
  * ```typescript
- * const zones = await GeometriesModule.create(map, fillStyledGeometryConfig({ palette: 'retro' }));
+ * const zones = await GeometriesModule.create(map, fillStyledGeometryConfig({ palette: ['#e63312', '#1d3f8a'] }));
  * ```
  *
  * @group Geometries
  */
 export declare const fillStyledGeometryConfig: ({ palette, beforeLayerConfig }?: FillStyledGeometryConfigOptions) => GeometriesModuleConfig;
-/**
- * Returns a {@link GeometriesModuleConfig} for reachable ranges.
- *
- * Builds on {@link fillStyledGeometryConfig} and overrides `transformFeaturesForDisplay` so the
- * raw output of `calculateReachableRanges` can be passed directly to {@link GeometriesModule.show}
- * — titles are derived from each feature's `budget` property.
- *
- * @example
- * ```typescript
- * const module = await GeometriesModule.create(map, reachableRangeGeometryConfig());
- * const result = await calculateReachableRanges([...]);
- * module.show(result); // titles and fill style applied automatically
- *
- * module.applyConfig(reachableRangeGeometryConfig({ palette: 'cold', fillStyle: 'inverted' }));
- * ```
- *
- * @group Geometries
- */
-export declare const reachableRangeGeometryConfig: ({ palette, beforeLayerConfig, fillStyle, title }?: ReachableRangeGeometryConfigOptions) => GeometriesModuleConfig;
 //#endregion
 //#region src/geometry/types/geometriesKnobs.d.ts
+/**
+ * The style fields both geometry labels share, as knobs: the {@link LabelConfig} fields.
+ * @ignore
+ */
+type GeometryLabelKnobLeaf = keyof LabelConfig;
 /**
  * The id of a geometries knob: its path into {@link GeometriesModuleConfig}, e.g. `fill.opacity` or
  * `lineLabel.minZoom`. See {@link geometriesKnobCatalogue} for what each one does.
  *
  * @group Geometries
  */
-type GeometriesKnobId = 'color' | 'visible' | 'fillStyle' | `fill.${keyof GeometryFillConfig}` | `line.${Exclude<keyof GeometryLineConfig, 'layer'>}` | `label.${Exclude<keyof GeometryLabelConfig, 'text'>}` | `lineLabel.${Exclude<keyof GeometryLineLabelConfig, 'text'>}`;
+type GeometriesKnobId = 'color' | 'visible' | 'fillStyle' | `fill.${keyof GeometryFillConfig}` | `line.${Exclude<keyof GeometryLineConfig, 'layer'>}` | `highlight.${keyof GeometryHighlightConfig}` | `label.${Exclude<keyof GeometryLabelConfig, 'text'>}` | `lineLabel.${Exclude<keyof GeometryLineLabelConfig, 'text'>}`;
 /**
  * The value type a given geometries knob takes: the plain value its path holds in
  * {@link GeometriesModuleConfig}. The MapLibre expressions the config also takes there are not knob
@@ -7689,13 +7729,136 @@ type GeometriesKnobValueOf<ID extends GeometriesKnobId> = KnobPlainValue<ValueAt
  *
  * @group Geometries
  */
-type GeometriesKnob = KnobEntry<GeometriesKnobId, Exclude<KnobKind, 'colors'>>;
+type GeometriesKnob = KnobEntry<GeometriesKnobId, Exclude<KnobKind, 'image' | 'text'>>;
+//#endregion
+//#region src/geometry/types/reachableRangesModuleConfig.d.ts
+/**
+ * The text of a reachable range's labels.
+ *
+ * @param feature - The range, as given to {@link ReachableRangesModule.show}.
+ * @param index - Its position in what `show` was given.
+ *
+ * @group Geometries
+ */
+export type ReachableRangeTitleFn = (feature: PolygonFeature, index: number) => string;
+/**
+ * Configuration of the {@link ReachableRangesModule}.
+ *
+ * @remarks
+ * The bands take their colours from the map unless {@link ReachableRangesModuleConfig.palette | palette}
+ * sets them: a ramp from the map's accent (innermost band) toward its land colour (outermost), reversed
+ * for the `'inverted'` fill style, both read from {@link TomTomMap.mapColors}. A theme set through `StylingModule.setMapColors` — e.g. from
+ * the map-theme plugin's `deriveMapColors` — recolours the bands with the rest of the map. Without one,
+ * the ramp runs between the map style's own light or dark defaults: `'#0A3653'` toward white on light
+ * styles, `'#5FA8D8'` toward `'#333333'` on dark ones (custom styles count as light), and follows a
+ * switch between them.
+ *
+ * @example
+ * ```typescript
+ * // The area outside the 30-minute range dimmed, in your own colours
+ * const config: ReachableRangesModuleConfig = {
+ *     fillStyle: 'inverted',
+ *     palette: ['#e63312', '#f5a000', '#1d3f8a'],
+ * };
+ * ```
+ *
+ * @see {@link ReachableRangesModuleSerializableConfig} for the part that survives JSON.
+ *
+ * @group Geometries
+ */
+export type ReachableRangesModuleConfig = MapModuleCommonConfig & {
+  /**
+   * Whether the module draws anything: bands, borders and their labels.
+   *
+   * @remarks
+   * `show()` and `clear()` never change it — a hidden module keeps its ranges until
+   * {@link ReachableRangesModule.setVisible} shows it again.
+   *
+   * @default true
+   */
+  visible?: boolean;
+  /**
+   * How the bands are filled.
+   *
+   * - `'filled'` — each band coloured, the innermost on top.
+   * - `'outline'` — only each range's border, thick and coloured.
+   * - `'inverted'` — the area **outside** each range coloured: the world beyond the largest range,
+   *   then a ring between each range and the next smaller one.
+   *
+   * @default 'filled'
+   */
+  fillStyle?: GeometryFillStyle;
+  /**
+   * CSS colours of the bands, the innermost band first, starting over after the last. An empty list
+   * counts as unset: the bands then ramp from the map's accent toward its land colour, the other way
+   * round for `'inverted'`, which deepens away from the origin.
+   *
+   * @remarks
+   * Bands are ranked per origin, so with several origins the ranges of the same rank share a colour.
+   */
+  palette?: string[];
+  /**
+   * How the labels along each range's border look. Their text is the range's title.
+   */
+  label?: LabelConfig;
+  /**
+   * How a hovered or clicked band is drawn.
+   */
+  highlight?: GeometryHighlightConfig;
+  /**
+   * Where the bands sit in the map's layer stack: a single target, or `{ all, fill, line }` to
+   * place the fill and the borders apart.
+   *
+   * @default 'lowestLabel'
+   */
+  beforeLayerConfig?: GeometryBeforeLayerConfig;
+  /**
+   * Each range's title, the text of its labels. Unset, it is the range's `budget`, e.g. `'30 min'`
+   * or `'10 km'`, else its position in what `show` was given, from 1.
+   */
+  title?: ReachableRangeTitleFn;
+};
+/**
+ * The part of a {@link ReachableRangesModuleConfig} that survives JSON, for saving `getConfig()` and
+ * replaying it with `applyConfig()`.
+ *
+ * @remarks
+ * It leaves out `title`, a function, which a replay adds back in code.
+ *
+ * @group Geometries
+ */
+export type ReachableRangesModuleSerializableConfig = Omit<ReachableRangesModuleConfig, 'title'>;
+//#endregion
+//#region src/geometry/types/reachableRangesKnobs.d.ts
+/**
+ * The id of a reachable ranges knob: its path into {@link ReachableRangesModuleConfig}, e.g. `palette`
+ * or `label.size`. See {@link reachableRangesKnobCatalogue} for what each one does.
+ *
+ * @group Geometries
+ */
+type ReachableRangesKnobId = 'visible' | 'fillStyle' | 'palette' | `highlight.${keyof GeometryHighlightConfig}` | `label.${GeometryLabelKnobLeaf}`;
+/**
+ * The value type a given reachable ranges knob takes: the plain value its path holds in
+ * {@link ReachableRangesModuleConfig}. The MapLibre expressions the config also takes there are not
+ * knob values.
+ *
+ * @group Geometries
+ */
+type ReachableRangesKnobValueOf<ID extends ReachableRangesKnobId> = KnobPlainValue<ValueAt<ReachableRangesModuleConfig, ID>>;
+/**
+ * One entry of {@link reachableRangesKnobCatalogue}. The value in force is the one at its path in
+ * {@link ReachableRangesModule.getConfig}, else its `default`; with neither, the map style or the
+ * map's colours decide.
+ *
+ * @group Geometries
+ */
+type ReachableRangesKnob = KnobEntry<ReachableRangesKnobId, Exclude<KnobKind, 'offset' | 'image' | 'text'>>;
 //#endregion
 //#region src/geometry/knobCatalogue.d.ts
 /**
  * Every geometries knob with its kind, description, range or options and, where one value holds
- * everywhere, its default: the module-wide knobs, the fill and border, then the center and border
- * labels. Static data, readable with no map loaded.
+ * everywhere, its default: the module-wide knobs, the fill and border, how a hovered or clicked
+ * geometry draws them, then the center and border labels. Static data, readable with no map loaded.
  *
  * @remarks
  * A knob is a plain display value in {@link GeometriesModuleConfig}, at the path its id names. Not
@@ -7712,55 +7875,116 @@ export declare const geometriesKnobCatalogue: readonly GeometriesKnob[];
  * @group Geometries
  */
 export declare const geometriesKnobIds: readonly GeometriesKnobId[];
-//#endregion
-//#region src/geometry/prepareReachableRangesForDisplay.d.ts
 /**
- * Attaches labels and applies fill-style-specific geometry to reachable range polygon features.
+ * Every reachable ranges knob with its kind, description, range or options and, where one value holds
+ * everywhere, its default: the module-wide knobs, how a hovered or clicked band draws, then the labels
+ * along each range's border. Static data, readable with no map loaded.
  *
- * Features must be ordered **largest budget first** (e.g. 30 min, 20 min, 10 min).
- * For the `inverted` fill style, polygons are converted to donuts and one extra innermost feature is appended.
- *
- * @param features  Polygon features from `calculateReachableRange`, ordered largest budget first.
- * @param labels    Label per feature in matching order (e.g. `['30 min', '20 min', '10 min']`).
- * @param fillStyle Fill style. Defaults to `'filled'`.
- *
- * @example
- * ```typescript
- * const features = [range30min, range20min, range10min];
- * const labels   = ['30 min', '20 min', '10 min'];
+ * @remarks
+ * A knob is a plain display value in {@link ReachableRangesModuleConfig}, at the path its id names.
+ * Not knobs: `beforeLayerConfig` and `title`, which take structured or function values; and `events`.
  *
- * module.show({
- *     type: 'FeatureCollection',
- *     features: buildReachableRangeFeatures(features, labels, 'inverted'),
- * });
- * ```
+ * @group Geometries
+ */
+export declare const reachableRangesKnobCatalogue: readonly ReachableRangesKnob[];
+/**
+ * Every reachable ranges knob id, in catalogue order.
  *
  * @group Geometries
  */
-export declare const buildReachableRangeFeatures: (features: PolygonFeature[], labels: string[], fillStyle?: GeometryFillStyle) => PolygonFeature[];
+export declare const reachableRangesKnobIds: readonly ReachableRangesKnobId[];
+//#endregion
+//#region src/geometry/ReachableRangesModule.d.ts
 /**
- * Prepares the output of `calculateReachableRanges` for display with {@link GeometriesModule}.
+ * Event surface of {@link ReachableRangesModule}: the module's own events, plus one named scope per
+ * surface it manages.
  *
- * Derives titles from each feature's `budget` property by default, applies fill-style-specific
- * geometry, and preserves the bounding box. Pass the returned value directly to `module.show()`.
+ * @group Geometries
+ */
+export type ReachableRangesEvents = GeometriesEvents<ReachableRangesModuleConfig>;
+/**
+ * Reachable Ranges Module: the areas reachable from one or more origins within a budget of time,
+ * distance, fuel or charge, as `calculateReachableRanges` returns them, drawn as bands.
  *
- * Note: when using {@link reachableRangeGeometryConfig} this is called automatically — you only
- * need this function for explicit control over titles or fill style.
+ * @remarks
+ * **What it does for you:**
+ * - Titles each range from its budget (`'30 min'`, `'10 km'`, `'20 % remaining'`) and labels its border
+ * - Ranks the ranges of each origin, innermost first, and colours them by rank
+ * - Draws them in any order given: a smaller range always sits on top of the larger ones around it
+ * - With `fillStyle: 'inverted'`, dims the world outside the largest range of every origin and draws a
+ *   ring outside each smaller one
  *
- * Features must be ordered **largest budget first** (e.g. 30 min, 20 min, 10 min).
+ * **Colours:** the bands ramp from the map's accent (innermost) toward its land colour (outermost),
+ * both read from {@link TomTomMap.mapColors} and followed as they change — so a theme set with
+ * `StylingModule.setMapColors`, e.g. from the map-theme plugin's `deriveMapColors`, recolours the
+ * bands too. {@link ReachableRangesModuleConfig.palette | palette} sets your own instead.
  *
- * @param result Raw output of `calculateReachableRanges`.
+ * **Multiple Instances:** the module owns the sources and layers it adds, suffixed per instance, so
+ * several can share a map.
  *
  * @example
  * ```typescript
- * // explicit control:
- * module.show(prepareReachableRangesForDisplay(result, { fillStyle: 'inverted' }));
- * module.show(prepareReachableRangesForDisplay(result, { title: (feature) => myTitle(feature) }));
+ * import { calculateReachableRanges } from '@tomtom-org/maps-sdk/services';
+ * import { ReachableRangesModule } from '@tomtom-org/maps-sdk/map';
+ *
+ * const ranges = await ReachableRangesModule.create(map);
+ * await ranges.show(
+ *     await calculateReachableRanges(
+ *         [10, 20, 30].map((value) => ({ origin: [4.9, 52.37], budget: { type: 'timeMinutes', value } })),
+ *     ),
+ * );
+ *
+ * ranges.applyConfig({ fillStyle: 'inverted' });
  * ```
  *
+ * @see [Reachable Ranges Guide](https://docs.tomtom.com/maps-sdk-js/guides/services/routing/reachable-ranges)
+ *
  * @group Geometries
  */
-export declare const prepareReachableRangesForDisplay: (result: PolygonFeatures, { fillStyle, title }?: ReachableRangesDisplayOptions) => PolygonFeatures;
+export declare class ReachableRangesModule extends AbstractGeometriesModule<ReachableRangesModuleConfig> {
+  /**
+   * Waits for the map to be ready, then creates a new module on it.
+   *
+   * @param tomtomMap - The TomTomMap instance.
+   * @param config - The module's configuration.
+   * @returns A new, independent instance: every call adds its own sources and layers.
+   *
+   * @example
+   * ```typescript
+   * const ranges = await ReachableRangesModule.create(map, { fillStyle: 'outline' });
+   * ```
+   */
+  static create(tomtomMap: TomTomMap, config?: ReachableRangesModuleConfig): Promise<ReachableRangesModule>;
+  private constructor();
+  /** @ignore */
+  protected get idPrefix(): string;
+  /** @ignore */
+  protected displayConfig(config: ReachableRangesModuleConfig | undefined): GeometriesModuleConfig;
+  /** @ignore */
+  protected prepareShown(ranges: PolygonFeatures, config: ReachableRangesModuleConfig | undefined): PolygonFeatures;
+  private get landColor();
+  /**
+   * Displays reachable ranges, replacing the ones shown.
+   *
+   * @param ranges - The ranges, as `calculateReachableRanges` returns them: any number of budgets,
+   * from any number of origins, in any order. Each range's `budget` titles it and its `origin` groups
+   * it with the others from the same place.
+   *
+   * @example
+   * ```typescript
+   * // Two origins, three budgets each, in one call
+   * const origins = [[4.9, 52.37], [4.48, 51.92]];
+   * await ranges.show(
+   *     await calculateReachableRanges(
+   *         origins.flatMap((origin) =>
+   *             [5, 10, 15].map((value) => ({ origin, budget: { type: 'distanceKM', value } })),
+   *         ),
+   *     ),
+   * );
+   * ```
+   */
+  show(ranges: PolygonFeatures): Promise<void>;
+}
 //#endregion
 //#region src/geometry/types/geometryDisplayProps.d.ts
 /**
@@ -8429,6 +8653,21 @@ type PlaceConnectionsConfig = {
    * metadata). When omitted, no label is rendered.
    */
   label?: (connection: PlaceConnectionDisplay) => string;
+  /**
+   * Colour of the connection lines, over the module's {@link PlacesModuleConfig.color}. Unset, they
+   * take that colour, else the map's accent, else a blue that follows the light/dark theme.
+   */
+  color?: string;
+  /**
+   * Colour of the labels along the lines. Unset: a darker shade of the line colour on a light
+   * map, a lighter one on a dark map.
+   */
+  textColor?: string;
+  /**
+   * Colour of the halo around the labels. Unset: `'#FFFFFF'` on a light map, `'#333333'` on a dark
+   * one, as for the places' own labels.
+   */
+  haloColor?: string;
   /**
    * Custom MapLibre layer specifications for connection line and label.
    */
@@ -8640,6 +8879,33 @@ type PlaceEntryPointsConfig = {
    */
   layers?: PlaceEntryPointsLayersConfig;
 };
+/**
+ * Where the places module's layers sit in the map's layer stack: one target for everything it
+ * draws, or one per part of it.
+ *
+ * @remarks
+ * The parts, named after the module's event scopes, and where each sits by default:
+ * - `places` — the markers and their labels, selected places, clusters with their badges and
+ *   counts, and entry points. Above the map's layers, except the small POI dots the `base-map` and
+ *   `pin-clustered` marker types draw, which sit below the map's place labels. A target puts them
+ *   all beneath it, the dots right under the markers.
+ * - `connections` — the lines {@link PlacesModule.showConnections} draws, and their labels. Below
+ *   the map's labels.
+ *
+ * Each part keeps its own layers' order wherever it goes. A target the style lacks puts the part
+ * on top.
+ *
+ * @example
+ * ```typescript
+ * // The markers under the map's labels, the connections where they are
+ * const underLabels: PlacesBeforeLayerConfig = { places: 'lowestLabel' };
+ * // Everything on top of the map
+ * const everything: PlacesBeforeLayerConfig = 'top';
+ * ```
+ *
+ * @group Places
+ */
+type PlacesBeforeLayerConfig = PartsBeforeLayerConfig<'places' | 'connections'>;
 /**
  * Configuration options for the PlacesModule.
  *
@@ -8696,8 +8962,8 @@ type PlacesModuleConfig<P extends CommonPlaceProps = CommonPlaceProps> = MapModu
   markerType?: PlacesMarkerType;
   /**
    * The colour of this module's own drawing: the default pin fill, the label of a hovered or
-   * clicked place, connection lines and entry points. Connection labels, and entry points on a
-   * light map, take a darker shade of it.
+   * clicked place, connection lines and entry points. Connection labels take a darker shade of it
+   * on a light map and a lighter one on a dark map; entry points take the darker one on a light map.
    *
    * @remarks
    * A more specific setting wins for its element: `icon.default.style.fillColor` for the pin,
@@ -8737,6 +9003,13 @@ type PlacesModuleConfig<P extends CommonPlaceProps = CommonPlaceProps> = MapModu
    * wins over `label` and `color` for the properties it names.
    */
   layers?: PlaceLayersConfig;
+  /**
+   * Where the module's layers sit in the map's layer stack, for everything it draws or per part.
+   *
+   * @remarks
+   * Left out, every layer sits where {@link PlacesBeforeLayerConfig} says it does by default.
+   */
+  beforeLayerConfig?: PlacesBeforeLayerConfig;
   /**
    * Configuration for EV charging station availability display.
    *
@@ -8860,12 +9133,12 @@ type PlacesModuleSerializableConfig = Omit<PlacesModuleConfig, 'label' | 'icon'
  *
  * @remarks
  * Only settings that take a plain value: `label.title`, `cluster.source.clusterProperties`,
- * `evAvailability.formatText` and anything holding an image, a callback or MapLibre layers are not
- * knobs.
+ * `evAvailability.formatText`, `connections.label` and anything holding an image, a callback or
+ * MapLibre layers are not knobs.
  *
  * @group Places
  */
-type PlacesKnobId = 'markerType' | 'color' | 'visible' | `icon.default.style.${keyof SVGIconStyleOptions}` | `label.${Exclude<keyof PlaceLabelConfig, 'title'>}` | `cluster.badge.${Exclude<keyof PlaceClusterBadgeConfig, 'radius'>}` | `cluster.badge.radius.${keyof NonNullable<PlaceClusterBadgeConfig['radius']>}` | `cluster.source.${Exclude<keyof NonNullable<PlacesClusterConfig['source']>, 'clusterProperties'>}` | `evAvailability.${Exclude<keyof EVAvailabilityConfig, 'formatText'>}` | `entryPoints.${Exclude<keyof PlaceEntryPointsConfig, 'layers'>}`;
+type PlacesKnobId = 'markerType' | 'color' | 'visible' | `icon.default.style.${keyof SVGIconStyleOptions}` | `label.${Exclude<keyof PlaceLabelConfig, 'title'>}` | `cluster.badge.${Exclude<keyof PlaceClusterBadgeConfig, 'radius'>}` | `cluster.badge.radius.${keyof NonNullable<PlaceClusterBadgeConfig['radius']>}` | `cluster.source.${Exclude<keyof NonNullable<PlacesClusterConfig['source']>, 'clusterProperties'>}` | `evAvailability.${Exclude<keyof EVAvailabilityConfig, 'formatText'>}` | `entryPoints.${Exclude<keyof PlaceEntryPointsConfig, 'layers'>}` | `connections.${Exclude<keyof PlaceConnectionsConfig, 'label' | 'layers'>}`;
 /**
  * The value type a given places knob takes: the plain value its path holds in
  * {@link PlacesModuleConfig}. The MapLibre expressions the config also takes there are not knob
@@ -8891,8 +9164,9 @@ type PlacesKnob = KnobEntry<PlacesKnobId, Exclude<KnobKind, 'factor' | 'colors'
  * @remarks
  * A knob is a plain display value in {@link PlacesModuleConfig}, at the path its id names.
  * - Not knobs: the label `title`, `clusterProperties`, `evAvailability.formatText`,
- *   `icon.default.image`, `icon.categoryIcons`, `icon.mapping`, `connections`, `layers`,
- *   `extraFeatureProps` and `events`, which take callbacks, images or MapLibre values.
+ *   `icon.default.image`, `icon.categoryIcons`, `icon.mapping`, `connections.label`, `layers`,
+ *   `beforeLayerConfig`, `extraFeatureProps` and `events`, which take callbacks, images, structured
+ *   or MapLibre values.
  * - `entryPoints` draws nothing until it is set, and `evAvailability` until `enabled` is `true`.
  *   `cluster` applies under the `pin-clustered` marker type only.
  *
@@ -9182,11 +9456,11 @@ export type PlacesShownFeatures = {
  */
 export type PlacesEvents = CombinedEvents<MapGeoJSONFeature, PlacesModuleConfig, PlacesShownFeatures> & {
   /** The place pins themselves, clustered or not. */
-  places: UserEvents<Place<DisplayPlaceProps>>;
+  places: UserEventsWithStates<Place<DisplayPlaceProps>>;
   /** The lines and labels connecting places to their parent, when connections are shown. */
-  connections: UserEvents<MapGeoJSONFeature>;
+  connections: UserEventsWithStates<MapGeoJSONFeature>;
   /** The entry points of places, when {@link PlacesModuleConfig.entryPoints} draws them. */
-  entryPoints: UserEvents<PlaceEntryPointFeature>;
+  entryPoints: UserEventsWithStates<PlaceEntryPointFeature>;
 };
 /**
  * Map module for displaying and managing place markers.
@@ -9321,76 +9595,35 @@ export declare class PlacesModule extends AbstractDataOwnedMapModule<PlacesSourc
    */
   protected restoreDataAndConfigImpl(): void;
   /**
-   * Changes the {@link PlacesMarkerType | kind of marker} places are drawn with.
-   *
-   * @remarks
-   * Redraws the places already shown, and leaves the rest of the configuration as it is.
-   */
-  applyMarkerType(markerType: PlacesMarkerType): void;
-  /**
-   * Updates the icon configuration for displayed places.
-   *
-   * @param iconConfig - New icon configuration settings.
-   *
-   * @remarks
-   * - Changes apply immediately to currently shown places
-   * - Custom icons are loaded if not already in style
-   * - Other configuration properties remain unchanged
-   *
-   * @example
-   * ```typescript
-   * placesModule.applyIconConfig({
-   *   categoryIcons: [
-   *     { id: 'RESTAURANT', image: '/icons/food.png' }
-   *   ]
-   * });
-   * ```
-   */
-  applyIconConfig<P extends CommonPlaceProps = CommonPlaceProps>(iconConfig: PlaceIconConfig<P>): void;
-  /**
-   * Replaces the {@link PlacesModuleConfig.label | label} configuration of the displayed places.
+   * Applies a configuration to this module, replacing the current one.
    *
-   * @remarks
-   * Supports both functions and MapLibre expressions for dynamic text.
+   * @typeParam P - The place shape the `label.title`, `icon.mapping` and `extraFeatureProps`
+   * callbacks expect, as with {@link PlacesModule.create}.
    *
    * @example
    * ```typescript
-   * // Use function
-   * placesModule.applyLabelConfig({
-   *   title: (place) => place.properties.poi?.name || 'Unknown'
-   * });
-   *
-   * // Use MapLibre expression
-   * placesModule.applyLabelConfig({
-   *   title: ['get', 'title'],
-   *   size: 14,
-   *   color: '#333'
-   * });
+   * places.applyConfig<MyPlaceProps>({ label: { title: (place) => place.properties.storeName } });
    * ```
    */
-  applyLabelConfig<P extends CommonPlaceProps = CommonPlaceProps>(label: PlaceLabelConfig<P>): void;
-  private applyConfigPart;
+  applyConfig<P extends CommonPlaceProps = CommonPlaceProps>(config: PlacesModuleConfig<P> | undefined): void;
   /**
-   * Applies additional feature properties to displayed places.
-   *
-   * @param extraFeatureProps - Object mapping property names to values or functions.
+   * Changes part of the configuration and keeps the rest, redrawing the places already shown.
    *
-   * @remarks
-   * Useful for adding computed properties or metadata for styling/filtering.
+   * @typeParam P - The place shape the `label.title`, `icon.mapping` and `extraFeatureProps`
+   * callbacks expect, as with {@link PlacesModule.create}.
    *
    * @example
    * ```typescript
-   * placesModule.applyExtraFeatureProps({
-   *   category: (place) => place.properties.poi?.localizedCategories?.[0],
-   *   brand: (place) => place.properties.poi?.brands?.[0] ?? '',
-   *   isOpen: true
-   * });
+   * places.updateConfig({ markerType: 'base-map' });
+   * places.updateConfig({ icon: { categoryIcons: [{ id: 'RESTAURANT', image: '/icons/food.png' }] } });
+   * places.updateConfig<MyPlaceProps>({ extraFeatureProps: { brand: (place) => place.properties.brand } });
    * ```
    */
-  applyExtraFeatureProps<P extends CommonPlaceProps = CommonPlaceProps>(extraFeatureProps: NonNullable<PlacesModuleConfig<P>['extraFeatureProps']>): void;
+  updateConfig<P extends CommonPlaceProps = CommonPlaceProps>(partial: PlacesModuleConfig<P>): void;
   /** @ignore */
   protected applyVisibility(config: PlacesModuleConfig | undefined): void;
   private updateLayersAndData;
+  private restackLayers;
   private updatePlacesLayers;
   private rebuildSourcesAndLayers;
   private updateConnectionsData;
@@ -9534,55 +9767,8 @@ export declare class PlacesModule extends AbstractDataOwnedMapModule<PlacesSourc
     places: Places<DisplayPlaceProps>;
     connections: PlaceConnectionDisplay[];
   };
-  /**
-   * Programmatically sets an event state on a specific place.
-   *
-   * @param options - Configuration for the event state to apply.
-   *
-   * @remarks
-   * Use this to make places appear clicked or hovered programmatically.
-   *
-   * The state lives on the shown place: a style change, `applyConfig` and a marker type change keep
-   * it, while {@link show} of new results, {@link clear} and a `setStyle` with `resetState` drop
-   * it, whatever the ids.
-   *
-   * @example
-   * ```typescript
-   * // Make first place appear clicked
-   * placesModule.putEventState({
-   *   index: 0,
-   *   state: 'click',
-   *   mode: 'put'
-   * });
-   * ```
-   */
-  putEventState(options: PutEventStateOptions): void;
-  /**
-   * Removes an event state from a specific place.
-   *
-   * @param options - Configuration for which event state to remove.
-   *
-   * @example
-   * ```typescript
-   * placesModule.cleanEventState({ index: 0 });
-   * ```
-   */
-  cleanEventState(options: CleanEventStateOptions): void;
-  /**
-   * Removes event states from multiple places.
-   *
-   * @param options - Optional filter for which states to remove.
-   *
-   * @example
-   * ```typescript
-   * // Remove all event states
-   * placesModule.cleanEventStates();
-   *
-   * // Remove only hover states
-   * placesModule.cleanEventStates({ states: ['hover'] });
-   * ```
-   */
-  cleanEventStates(options?: CleanEventStatesOptions): void;
+  /** @ignore */
+  protected eventStateSources(): (keyof PlacesSourcesAndLayers)[];
   get events(): PlacesEvents;
 }
 //#endregion
@@ -9700,7 +9886,7 @@ export declare const preparePlacesForDisplay: <P extends CommonPlaceProps = Comm
  * @example
  * Use with POI module filtering:
  * ```ts
- * poisModule.filterCategories({ show: 'only', values: ['FOOD_DRINKS_GROUP', 'ENTERTAINMENT_GROUP'] });
+ * poisModule.updateConfig({ filters: { categories: { show: 'only', values: ['FOOD_DRINKS_GROUP', 'ENTERTAINMENT_GROUP'] } } });
  * ```
  *
  * @see {@link POICategoryGroup} - Type representing all available group names
@@ -10049,7 +10235,7 @@ type PoIsSourcesAndLayers = {
    * Places of interest with corresponding layer ids.
    * TODO: technically source ID is vectorTiles if POIs stay included in base map for Orbis
    */
-  poi: StyleSourceWithLayers;
+  pois: StyleSourceWithLayers;
 };
 /**
  * POIs Module for controlling Points of Interest displayed in the map style.
@@ -10097,31 +10283,25 @@ type PoIsSourcesAndLayers = {
  * Filter specific categories:
  * ```typescript
  * // Show only restaurants and hotels
- * poisModule.filterCategories({
- *   show: 'only',
- *   values: ['RESTAURANT', 'HOTEL_OR_MOTEL']
+ * poisModule.updateConfig({
+ *   filters: { categories: { show: 'only', values: ['RESTAURANT', 'HOTEL_OR_MOTEL'] } },
  * });
  *
  * // Hide parking garages
- * poisModule.filterCategories({
- *   show: 'all-except',
- *   values: ['PARKING_GARAGE', 'OPEN_CAR_PARKING_AREA']
+ * poisModule.updateConfig({
+ *   filters: { categories: { show: 'all-except', values: ['PARKING_GARAGE', 'OPEN_CAR_PARKING_AREA'] } },
  * });
+ *
+ * // Show every POI again
+ * poisModule.updateConfig({ filters: undefined });
  * ```
  *
  * @example
  * Filter using category groups:
  * ```typescript
  * // Show only food and shopping POIs
- * poisModule.filterCategories({
- *   show: 'only',
- *   values: ['FOOD_DRINKS_GROUP', 'SHOPPING_GROUP']
- * });
- *
- * // Hide transportation POIs
- * pois.filterCategories({
- *   show: 'all-except',
- *   values: ['TRANSPORTATION_GROUP']
+ * poisModule.updateConfig({
+ *   filters: { categories: { show: 'only', values: ['FOOD_DRINKS_GROUP', 'SHOPPING_GROUP'] } },
  * });
  * ```
  *
@@ -10187,7 +10367,7 @@ export declare class POIsModule extends AbstractStyleOwnedMapModule<PoIsSourcesA
    * @ignore
    */
   protected _initSourcesWithLayers(): {
-    poi: StyleSourceWithLayers<import("maplibre-gl").SourceSpecification, import("maplibre-gl").Source>;
+    pois: StyleSourceWithLayers<import("maplibre-gl").SourceSpecification, import("maplibre-gl").Source>;
   };
   /**
    * @ignore
@@ -10222,38 +10402,7 @@ export declare class POIsModule extends AbstractStyleOwnedMapModule<PoIsSourcesA
    */
   setVisible(visible: boolean): void;
   private _setVisible;
-  /**
-   * Filters POIs by category or category 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:
-   * ```typescript
-   * pois.filterCategories({
-   *   show: 'only',
-   *   values: ['RESTAURANT']
-   * });
-   * ```
-   *
-   * @example
-   * Hide parking:
-   * ```typescript
-   * pois.filterCategories({
-   *   show: 'all-except',
-   *   values: ['PARKING_GROUP']
-   * });
-   * ```
-   *
-   * @example
-   * Reset filter (show all):
-   * ```typescript
-   * pois.filterCategories(undefined);
-   * ```
-   */
-  filterCategories(categoriesFilter?: ValuesFilter<FilterablePOICategory> | undefined): void;
-  private _filterCategories;
+  private applyCategoriesFilter;
   /**
    * Returns features currently visible in the viewport.
    *
@@ -10262,14 +10411,14 @@ export declare class POIsModule extends AbstractStyleOwnedMapModule<PoIsSourcesA
    * @example
    * ```typescript
    * const shown = poisModule.getShown();
-   * console.log(`Visible POIs: ${shown.poi.length}`);
-   * shown.poi.forEach(poi => {
+   * console.log(`Visible POIs: ${shown.pois.length}`);
+   * shown.pois.forEach(poi => {
    *   console.log(poi.properties.name, poi.properties.category);
    * });
    * ```
    */
   getShown(): {
-    poi: POIsModuleFeature[];
+    pois: POIsModuleFeature[];
   };
   /**
    * Gets the events interface for handling user interactions with POIs.
@@ -11032,6 +11181,14 @@ type WaypointsConfig = {
      */
     style?: SVGIconStyleOptions;
   };
+  /**
+   * How the waypoint labels look: size, font, colours and opacity.
+   *
+   * @remarks
+   * Unset colours follow the map's light/dark theme, as the labels of places and geometries do:
+   * `'#333333'` text on a `'#FFFFFF'` halo on a light map, the two swapped on a dark one.
+   */
+  label?: LabelConfig;
   /**
    * Controls how entry points are used when displaying waypoints on the map.
    *
@@ -11336,6 +11493,28 @@ type CountryCrossingConfig = {
    */
   alignment?: CountryCrossingAlignment;
 };
+/**
+ * How a hovered or clicked route is drawn: its outline widens, in the outline colour, whether the
+ * route is selected or not.
+ *
+ * @remarks
+ * The routes draw their event states once a handler covers them, or
+ * {@link RoutingModule.putEventState} puts one. A `layers.mainLines` outline `line-width` is drawn
+ * as given instead.
+ *
+ * @group Routing
+ */
+type RouteHighlightConfig = {
+  /**
+   * Multiplier on the outline width of a hovered or clicked route; `1` draws it as any other.
+   *
+   * @remarks
+   * Clamped to {@link ROUTE_HIGHLIGHT_OUTLINE_WIDTH_FACTOR_RANGE}, 1 to 1.25.
+   *
+   * @defaultValue `1.2`
+   */
+  outlineWidthFactor?: number;
+};
 /**
  * Appearance of one route section type.
  *
@@ -11465,6 +11644,10 @@ type RoutingModuleConfig = MapModuleCommonConfig & {
    * @defaultValue `1`
    */
   widthFactor?: number;
+  /**
+   * How a hovered or clicked route is drawn.
+   */
+  highlight?: RouteHighlightConfig;
   /**
    * Size preset of the waypoint pins.
    *
@@ -11585,7 +11768,7 @@ type LeafPathOf<T> = { [KEY in keyof T & string]-?: NonNullable<T[KEY]> extends
  *
  * @group Routing
  */
-type RoutingKnobId = 'visible' | 'color' | 'width' | 'widthFactor' | 'waypointSize' | 'waypointSizeFactor' | `waypoints.icon.style.${keyof SVGIconStyleOptions}` | 'waypoints.entryPoints' | `displayUnits.distance.${keyof DistanceDisplayUnits}` | `displayUnits.time.${keyof TimeDisplayUnits}` | 'chargingStops.visible' | 'chargingStops.label.visible' | 'summaryBubbles.visible' | `countryCrossings.${keyof CountryCrossingConfig}` | { [T in DrawnSectionType]: `sections.${T}.${LeafPathOf<SectionDisplayConfig<T>>}`; }[DrawnSectionType];
+type RoutingKnobId = 'visible' | 'color' | 'width' | 'widthFactor' | `highlight.${keyof RouteHighlightConfig}` | 'waypointSize' | 'waypointSizeFactor' | `waypoints.icon.style.${keyof SVGIconStyleOptions}` | `waypoints.label.${Extract<keyof LabelConfig, 'color' | 'haloColor'>}` | 'waypoints.entryPoints' | `displayUnits.distance.${keyof DistanceDisplayUnits}` | `displayUnits.time.${keyof TimeDisplayUnits}` | 'chargingStops.visible' | 'chargingStops.label.visible' | 'summaryBubbles.visible' | `countryCrossings.${keyof CountryCrossingConfig}` | { [T in DrawnSectionType]: `sections.${T}.${LeafPathOf<SectionDisplayConfig<T>>}`; }[DrawnSectionType];
 /**
  * The value type a given routing knob takes: the plain value its path holds in {@link RoutingModuleConfig}.
  *
@@ -11635,7 +11818,8 @@ type TrafficDelayColors = Record<Extract<DelayMagnitude, 'minor' | 'moderate' |
  * @param config - Optional routing module configuration to customize layer properties.
  * @param layerIDPrefix - Optional prefix to add to layer IDs for supporting multiple instances.
  * @param instanceIndex - Optional instance index for image ID suffixes.
- * @param lightDark - The map style's light/dark theme, which the country crossing plaque colours follow.
+ * @param lightDark - The map style's light/dark theme, which the waypoint labels and the country
+ * crossing plaques follow.
  * @param existingLayerID - The anchor a configured `beforeLayerConfig` target resolves to, given the
  * layer it names: that layer when the style has it, else undefined for the top of the stack.
  * @param trafficColors - The colours traffic sections draw each delay magnitude in.
@@ -11749,6 +11933,15 @@ export declare const ROUTE_WAYPOINT_SIZE_FACTOR_RANGE: KnobRange;
  * @group Routing
  */
 export declare const SECTION_ICON_SIZE_FACTOR_RANGE: KnobRange;
+/**
+ * The values {@link RouteHighlightConfig.outlineWidthFactor} is clamped to.
+ *
+ * @remarks
+ * A section halo is drawn beneath the route at 1.26 times its outline width or more, at every
+ * preset and zoom; a wider outline on a hovered route would cover it.
+ * @group Routing
+ */
+export declare const ROUTE_HIGHLIGHT_OUTLINE_WIDTH_FACTOR_RANGE: KnobRange;
 type IconSize = NonNullable<SymbolLayerSpecification['layout']>['icon-size'];
 /**
  * The icon size of a section layer under the given {@link SectionIconConfig.sizeFactor}: the size
@@ -12626,29 +12819,29 @@ export type RoutingShownFeatures = {
  *
  * @group Routing
  */
-export type RoutingEvents = CombinedEvents<MapGeoJSONFeature, RoutingModuleConfig, RoutingShownFeatures> & { [K in SectionSourceKey<GeneratedSectionType>]: UserEvents<RouteSection>; } & {
+export type RoutingEvents = CombinedEvents<MapGeoJSONFeature, RoutingModuleConfig, RoutingShownFeatures> & { [K in SectionSourceKey<GeneratedSectionType>]: UserEventsWithStates<RouteSection>; } & {
   /** The route lines themselves. */
-  mainLines: UserEvents<Route<DisplayRouteProps>>;
+  mainLines: UserEventsWithStates<Route<DisplayRouteProps>>;
   /** Origin, destination and intermediate stops. */
-  waypoints: UserEvents<Waypoint<WaypointDisplayProps>>;
+  waypoints: UserEventsWithStates<Waypoint<WaypointDisplayProps>>;
   /** Charging stops along an EV route. */
-  chargingStops: UserEvents<RouteSection>;
+  chargingStops: UserEventsWithStates<RouteSection>;
   /** The summary bubbles shown against each alternative. */
-  summaryBubbles: UserEvents<DisplayRouteSummary>;
+  summaryBubbles: UserEventsWithStates<DisplayRouteSummary>;
   /** The border crossings along the route, each carrying the two `country` sections it joins. */
-  countryCrossings: UserEvents<CountryCrossingFeature>;
+  countryCrossings: UserEventsWithStates<CountryCrossingFeature>;
   /** Traffic incidents on the route. */
-  incidents: UserEvents<RouteSection<DisplayTrafficSectionProps>>;
+  incidents: UserEventsWithStates<RouteSection<DisplayTrafficSectionProps>>;
   /** Sections the vehicle is restricted from. */
-  vehicleRestricted: UserEvents<RouteSection>;
+  vehicleRestricted: UserEventsWithStates<RouteSection>;
   /** Ferry sections. */
-  ferries: UserEvents<RouteSection>;
+  ferries: UserEventsWithStates<RouteSection>;
   /** Toll road sections. */
-  tollRoads: UserEvents<RouteSection>;
+  tollRoads: UserEventsWithStates<RouteSection>;
   /** Tunnel sections. */
-  tunnels: UserEvents<RouteSection>;
+  tunnels: UserEventsWithStates<RouteSection>;
   /** The guidance instruction lines. */
-  instructionLines: UserEvents<DisplayInstruction>;
+  instructionLines: UserEventsWithStates<DisplayInstruction>;
 };
 /**
  * Map module for displaying and managing route visualizations.
@@ -13027,6 +13220,8 @@ export declare class RoutingModule extends AbstractDataOwnedMapModule<RoutingSou
     chargingStops: DisplayChargingStops;
     tollRoads: RouteSections;
   };
+  /** @ignore */
+  protected eventStateSources(): (keyof RoutingSourcesWithLayers)[];
   /**
    * Unified events interface for the routing module.
    *
@@ -13147,7 +13342,7 @@ export declare const terrainKnobIds: readonly TerrainKnobId[];
 //#endregion
 //#region src/terrain/TerrainModule.d.ts
 /**
- * The style source this module draws from: the raster-dem elevation source of the hillshade
+ * The style source this module draws from: the raster-dem elevation source of the terrain
  * style part, with its hillshade layers.
  */
 type TerrainSourcesWithLayers = {
@@ -13174,7 +13369,7 @@ type TerrainSourcesWithLayers = {
  * @example
  * ```typescript
  * const terrain = await TerrainModule.get(map, { hillshade: true, elevation: true, elevationExaggeration: 1.3 });
- * terrain.setElevationExaggeration(2);
+ * terrain.updateConfig({ elevationExaggeration: 2 });
  * terrain.setElevationEnabled(false); // flat again, still shaded
  * ```
  *
@@ -13229,12 +13424,6 @@ export declare class TerrainModule extends AbstractStyleOwnedMapModule<TerrainSo
    * @returns The `elevation` setting; while nothing has set it, whether the map's own terrain raises it.
    */
   isElevationEnabled(): boolean;
-  /**
-   * Sets the vertical {@link TerrainModuleConfig.elevationExaggeration | exaggeration} of the 3D
-   * surface, kept for when elevation is enabled later. How strongly the slopes are shaded is the
-   * `hillshade.exaggeration` knob of {@link StylingModule} instead.
-   */
-  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
@@ -13277,17 +13466,23 @@ type AreaAnalyticsColorStop = {
  */
 type AreaAnalyticsDisplayMode = 'heatmap' | 'hexgrid-3d' | 'hexgrid-2d' | 'square-3d' | 'square-2d';
 /**
- * Preset color theme for area analytics visualization.
+ * Every {@link AreaAnalyticsPalette} name.
+ *
+ * @group Traffic Area Analytics
+ */
+export declare const areaAnalyticsPalettes: readonly ["trafficLight", "heat", "monochrome", "viridis", "plasma"];
+/**
+ * A named colour ramp for area analytics cells, listed from good to bad traffic.
  *
  * - `'trafficLight'` — Green → amber → red (default, traffic-signal style)
  * - `'heat'` — Blue → orange → red (heat-map style)
  * - `'monochrome'` — Light grey → dark grey (print-friendly)
- * - `'viridis'` — Purple → blue → green → yellow (perceptually uniform, colorblind-safe)
- * - `'plasma'` — Purple → magenta → orange → yellow (vivid, perceptually uniform)
+ * - `'viridis'` — Yellow → green → blue → purple (perceptually uniform, colorblind-safe)
+ * - `'plasma'` — Yellow → orange → magenta → purple (vivid, perceptually uniform)
  *
  * @group Traffic Area Analytics
  */
-type AreaAnalyticsColorTheme = 'trafficLight' | 'heat' | 'monochrome' | 'viridis' | 'plasma';
+type AreaAnalyticsPalette = (typeof areaAnalyticsPalettes)[number];
 /**
  * Determines how numeric `value` fields in color stops are interpreted.
  *
@@ -13311,7 +13506,7 @@ type AreaAnalyticsValueType = 'raw' | 'relativeToPredefinedRangePCT' | 'relative
  * @example
  * ```typescript
  * // Stops whose values are actual congestion-level values (0–100)
- * const color: AreaAnalyticsColorStopsConfig = {
+ * const colorStops: AreaAnalyticsColorStopsConfig = {
  *   valueType: 'raw',
  *   stops: [
  *     { value: 0,   color: '#2dc653' },
@@ -13321,7 +13516,7 @@ type AreaAnalyticsValueType = 'raw' | 'relativeToPredefinedRangePCT' | 'relative
  * };
  *
  * // Stops as 0–100 % of the predefined metric range (speed: 0–120 km/h)
- * const color: AreaAnalyticsColorStopsConfig = {
+ * const colorStops: AreaAnalyticsColorStopsConfig = {
  *   valueType: 'relativeToPredefinedRangePCT',
  *   stops: [
  *     { value: 0,   color: '#e03030' },  // 0 km/h
@@ -13331,7 +13526,7 @@ type AreaAnalyticsValueType = 'raw' | 'relativeToPredefinedRangePCT' | 'relative
  * };
  *
  * // Stops as 0–100 % of the live data range (maximum contrast regardless of absolute values)
- * const color: AreaAnalyticsColorStopsConfig = {
+ * const colorStops: AreaAnalyticsColorStopsConfig = {
  *   valueType: 'relativeToActualRangePCT',
  *   stops: [
  *     { value: 0,   color: '#2dc653' },  // 0% = loaded minimum
@@ -13370,7 +13565,7 @@ type AreaAnalyticsMetricFilter = {
  *
  * The shape depends on `scaleMode`:
  * - `'predefinedRange'` / `'currentRange'` (default): use `maxHeightMeters` to set a true visual ceiling.
- * - `'raw'`: use `scaleFactor` to multiply the raw metric value directly.
+ * - `'raw'`: use `metersPerUnit` to turn the raw metric value into metres of height.
  *
  * @group Traffic Area Analytics
  */
@@ -13396,14 +13591,14 @@ type AreaAnalyticsHeightConfig = {
    */
   minHeightMeters?: number;
 } | {
-  /** Raw scale mode: `scaleFactor` is multiplied directly with the raw metric value. */
+  /** Raw scale mode: the height is the raw metric value times `metersPerUnit`. */
   scaleMode: 'raw';
   /**
-   * Multiplier applied to the raw metric value to obtain extrusion height in meters.
+   * Metres of extrusion height per unit of the metric.
    *
    * @defaultValue 1
    */
-  scaleFactor?: number;
+  metersPerUnit?: number;
   /**
    * Minimum extrusion height in meters.
    *
@@ -13418,16 +13613,20 @@ type AreaAnalyticsHeightConfig = {
  */
 type AreaAnalyticsMetricConfig = {
   /**
-   * Color for this metric's visualization.
+   * Palette the cells of this metric are coloured with, spread evenly over the metric's range.
    *
-   * Pass a preset theme name (`AreaAnalyticsColorTheme`) or a custom
-   * `AreaAnalyticsColorStopsConfig` object with explicit stop values and a
-   * value-type hint. For `speed`, the color order is automatically inverted
-   * so that slow speeds render as "bad" (red) and fast speeds as "good" (green).
+   * @remarks
+   * On `speed` and `freeFlowSpeed`, where higher is better, the palette runs the other way, so slow
+   * traffic takes its bad end. On `networkLength` it spans the loaded data's range, on the other
+   * metrics their predefined range. `colorStops` wins over it.
    *
-   * @defaultValue `'trafficLight'` theme
+   * @defaultValue 'trafficLight'
+   */
+  palette?: AreaAnalyticsPalette;
+  /**
+   * Explicit colour stops for this metric's cells, used as given. Wins over `palette`.
    */
-  color?: AreaAnalyticsColorTheme | AreaAnalyticsColorStopsConfig;
+  colorStops?: AreaAnalyticsColorStopsConfig;
   /**
    * Extrusion height configuration for this metric.
    */
@@ -13509,17 +13708,6 @@ type AreaAnalyticsRegionPolygonConfig = {
    */
   inverted?: boolean;
 };
-/**
- * The green / amber / red every metric's default colour stops and the `trafficLight` colour theme
- * are drawn from.
- *
- * @ignore
- */
-declare const TRAFFIC_LIGHT_COLORS: {
-  readonly good: "#2dc653";
-  readonly moderate: "#f5a623";
-  readonly bad: "#e03030";
-};
 /**
  * Default values for all {@link TrafficAreaAnalyticsModuleConfig} options.
  *
@@ -13538,19 +13726,7 @@ declare const AREA_ANALYTICS_DEFAULTS: {
   /** @see {@link TrafficAreaAnalyticsModuleConfig.metricConfig} */
   metricConfig: {
     congestionLevel: {
-      color: {
-        valueType: "raw";
-        stops: ({
-          value: number;
-          color: "#2dc653";
-        } | {
-          value: number;
-          color: "#f5a623";
-        } | {
-          value: number;
-          color: "#e03030";
-        })[];
-      };
+      palette: "trafficLight";
       height: {
         maxHeightMeters: number;
         minHeightMeters: number;
@@ -13558,19 +13734,7 @@ declare const AREA_ANALYTICS_DEFAULTS: {
       };
     };
     speed: {
-      color: {
-        valueType: "relativeToPredefinedRangePCT";
-        stops: ({
-          value: number;
-          color: "#e03030";
-        } | {
-          value: number;
-          color: "#f5a623";
-        } | {
-          value: number;
-          color: "#2dc653";
-        })[];
-      };
+      palette: "trafficLight";
       height: {
         maxHeightMeters: number;
         minHeightMeters: number;
@@ -13578,19 +13742,7 @@ declare const AREA_ANALYTICS_DEFAULTS: {
       };
     };
     travelTime: {
-      color: {
-        valueType: "relativeToPredefinedRangePCT";
-        stops: ({
-          value: number;
-          color: "#2dc653";
-        } | {
-          value: number;
-          color: "#f5a623";
-        } | {
-          value: number;
-          color: "#e03030";
-        })[];
-      };
+      palette: "trafficLight";
       height: {
         maxHeightMeters: number;
         minHeightMeters: number;
@@ -13598,19 +13750,7 @@ declare const AREA_ANALYTICS_DEFAULTS: {
       };
     };
     freeFlowSpeed: {
-      color: {
-        valueType: "relativeToPredefinedRangePCT";
-        stops: ({
-          value: number;
-          color: "#e03030";
-        } | {
-          value: number;
-          color: "#f5a623";
-        } | {
-          value: number;
-          color: "#2dc653";
-        })[];
-      };
+      palette: "trafficLight";
       height: {
         maxHeightMeters: number;
         minHeightMeters: number;
@@ -13618,19 +13758,7 @@ declare const AREA_ANALYTICS_DEFAULTS: {
       };
     };
     networkLength: {
-      color: {
-        valueType: "relativeToActualRangePCT";
-        stops: ({
-          value: number;
-          color: "#2dc653";
-        } | {
-          value: number;
-          color: "#f5a623";
-        } | {
-          value: number;
-          color: "#e03030";
-        })[];
-      };
+      palette: "trafficLight";
       height: {
         maxHeightMeters: number;
         minHeightMeters: number;
@@ -13654,9 +13782,9 @@ declare const AREA_ANALYTICS_DEFAULTS: {
  *
  * @remarks
  * The active metric is set via `activeMetric` (defaults to `'congestionLevel'`).
- * Per-metric style settings (color, height, filters) are nested under `metricConfig` keyed by
+ * Per-metric style settings (palette or colour stops, height, filters) are nested under `metricConfig` keyed by
  * `AreaAnalyticsMetricKey`, making it easy to pre-configure multiple metrics independently and switch
- * between them at runtime via `setMetric()`.
+ * between them at runtime with `updateConfig({ activeMetric })`.
  *
  * @example
  * ```typescript
@@ -13665,12 +13793,12 @@ declare const AREA_ANALYTICS_DEFAULTS: {
  *   activeMetric: 'congestionLevel',
  *   metricConfig: {
  *     congestionLevel: {
- *       color: 'heat',
+ *       palette: 'heat',
  *       height: { maxHeightMeters: 80, scaleMode: 'predefinedRange' },
  *       filters: { min: 10 },
  *     },
  *     speed: {
- *       color: {
+ *       colorStops: {
  *         valueType: 'raw',
  *         stops: [
  *           { value: 0,   color: '#e03030' },
@@ -13705,11 +13833,11 @@ type TrafficAreaAnalyticsModuleConfig = MapModuleCommonConfig & {
    */
   activeMetric?: AreaAnalyticsMetricKey;
   /**
-   * Per-metric visualization configuration (color, height, filters).
+   * Per-metric visualization configuration (palette or colour stops, height, filters).
    *
-   * Metrics not listed here fall back to defaults (congestion color theme, metric-dependent height scale).
+   * Metrics not listed here fall back to defaults (the `trafficLight` palette, metric-dependent height scale).
    * `updateConfig` replaces this whole record, so to change one metric and keep the others' settings,
-   * use `setColor`, `setHeight` or `filter` with that metric.
+   * use `setPalette`, `setColorStops`, `setHeight` or `filter` with that metric.
    */
   metricConfig?: Partial<Record<AreaAnalyticsMetricKey, AreaAnalyticsMetricConfig>>;
   /**
@@ -13930,7 +14058,7 @@ export type TrafficFlowModuleConfig = MapModuleCommonConfig & {
   filters?: TrafficFlowFilters;
 };
 //#endregion
-//#region src/traffic/types/trafficIncidentOverlayConfig.d.ts
+//#region src/traffic/types/trafficIncidentDetailsConfig.d.ts
 /**
  * The values {@link IncidentFocusStyle.widthFactor} is clamped to.
  *
@@ -13942,7 +14070,7 @@ export type TrafficFlowModuleConfig = MapModuleCommonConfig & {
 export declare const INCIDENT_FOCUS_WIDTH_FACTOR_RANGE: KnobRange;
 /**
  * Visual treatment applied to the focused subset by
- * {@link TrafficIncidentOverlayModule.setFocus}.
+ * {@link TrafficIncidentDetailsModule.setFocus}, and to a hovered or clicked incident.
  *
  * @group Traffic
  */
@@ -13963,11 +14091,11 @@ export type IncidentFocusStyle = {
   widthFactor?: number;
 };
 /**
- * Configuration for {@link TrafficIncidentOverlayModule}.
+ * Configuration for {@link TrafficIncidentDetailsModule}.
  *
  * @group Traffic
  */
-export type TrafficIncidentOverlayModuleConfig = MapModuleCommonConfig & {
+export type TrafficIncidentDetailsModuleConfig = MapModuleCommonConfig & {
   /**
    * Whether the incident layers are shown. Defaults to `true`.
    * `show()` never flips this flag — if `false`, the module loads data but
@@ -13983,13 +14111,14 @@ export type TrafficIncidentOverlayModuleConfig = MapModuleCommonConfig & {
    */
   beforeLayerConfig?: BeforeLayerConfig;
   /**
-   * Visual treatment for {@link TrafficIncidentOverlayModule.setFocus}.
+   * Visual treatment for {@link TrafficIncidentDetailsModule.setFocus}, which a hovered or
+   * clicked incident draws too.
    *
    * - Omit (or `undefined`) — use the SDK default treatment: an outline beneath
    *   the focused stripe (black on light map styles, white on dark) and a `1.6×` width pop.
    * - `false` — disable the visual treatment. `setFocus(ids)` still writes
-   *   MapLibre `feature-state.focused`, so callers can drive their own
-   *   styling (extra layers, sidebar overlays, …) off that state.
+   *   MapLibre `feature-state.focused`, and user events `eventState`, so callers can drive
+   *   their own styling (extra layers, sidebar overlays, …) off those states.
    * - `{ outlineColor?, widthFactor? }` — override individual fields of the
    *   default treatment.
    */
@@ -14219,35 +14348,35 @@ type TrafficIncidentsKnobValueOf<ID extends TrafficIncidentsKnobId> = KnobPlainV
  */
 type TrafficIncidentsKnob = KnobEntry<TrafficIncidentsKnobId, TrafficKnobKind>;
 /**
- * The id of an incident overlay knob: its path into {@link TrafficIncidentOverlayModuleConfig}.
- * See {@link trafficIncidentOverlayKnobCatalogue} for what each one does.
+ * The id of an incident details knob: its path into {@link TrafficIncidentDetailsModuleConfig}.
+ * See {@link trafficIncidentDetailsKnobCatalogue} for what each one does.
  *
  * @group Traffic
  */
-type TrafficIncidentOverlayKnobId = 'visible' | `focus.${keyof IncidentFocusStyle}`;
+type TrafficIncidentDetailsKnobId = 'visible' | `focus.${keyof IncidentFocusStyle}`;
 /**
- * The value type a given incident overlay knob takes: the plain value its path holds in
- * {@link TrafficIncidentOverlayModuleConfig}.
+ * The value type a given incident details knob takes: the plain value its path holds in
+ * {@link TrafficIncidentDetailsModuleConfig}.
  *
  * @group Traffic
  */
-type TrafficIncidentOverlayKnobValueOf<ID extends TrafficIncidentOverlayKnobId> = KnobPlainValue<ValueAt<TrafficIncidentOverlayModuleConfig, ID>>;
+type TrafficIncidentDetailsKnobValueOf<ID extends TrafficIncidentDetailsKnobId> = KnobPlainValue<ValueAt<TrafficIncidentDetailsModuleConfig, ID>>;
 /**
- * One entry of {@link trafficIncidentOverlayKnobCatalogue}. The value in force is the one at its
- * path in {@link TrafficIncidentOverlayModule.getConfig}, else its `default`; with neither, the
+ * One entry of {@link trafficIncidentDetailsKnobCatalogue}. The value in force is the one at its
+ * path in {@link TrafficIncidentDetailsModule.getConfig}, else its `default`; with neither, the
  * map's light/dark theme decides.
  *
  * @group Traffic
  */
-type TrafficIncidentOverlayKnob = KnobEntry<TrafficIncidentOverlayKnobId, TrafficKnobKind>;
+type TrafficIncidentDetailsKnob = KnobEntry<TrafficIncidentDetailsKnobId, TrafficKnobKind>;
 /**
  * An area analytics knob's path below `metricConfig.<metric>.`, whichever metric takes it.
  * @ignore
  */
-type AreaAnalyticsMetricKnobLeaf = 'color' | `height.${KeyOfEither<AreaAnalyticsHeightConfig>}` | `filters.${keyof AreaAnalyticsMetricFilter}`;
+type AreaAnalyticsMetricKnobLeaf = 'palette' | `height.${KeyOfEither<AreaAnalyticsHeightConfig>}` | `filters.${keyof AreaAnalyticsMetricFilter}`;
 /**
  * The id of an area analytics knob: its path into {@link TrafficAreaAnalyticsModuleConfig}, e.g.
- * `displayMode` or `metricConfig.speed.color`. See {@link trafficAreaAnalyticsKnobCatalogue} for
+ * `displayMode` or `metricConfig.speed.palette`. See {@link trafficAreaAnalyticsKnobCatalogue} for
  * what each one does.
  *
  * @remarks
@@ -14260,10 +14389,6 @@ type TrafficAreaAnalyticsKnobId = 'visible' | 'displayMode' | 'activeMetric' | `
  * The value type a given area analytics knob takes: the plain value its path holds in
  * {@link TrafficAreaAnalyticsModuleConfig}.
  *
- * @remarks
- * `metricConfig.<metric>.color` is a theme name: the custom colour stops the config also takes there
- * are not a knob value.
- *
  * @group Traffic Area Analytics
  */
 type TrafficAreaAnalyticsKnobValueOf<ID extends TrafficAreaAnalyticsKnobId> = KnobPlainValue<ValueAt<TrafficAreaAnalyticsModuleConfig, ID>>;
@@ -14316,7 +14441,7 @@ export declare const trafficIncidentsKnobCatalogue: readonly TrafficIncidentsKno
  */
 export declare const trafficIncidentsKnobIds: readonly TrafficIncidentsKnobId[];
 /**
- * Every {@link TrafficIncidentOverlayModule} knob with its kind, description, range and, where one
+ * Every {@link TrafficIncidentDetailsModule} knob with its kind, description, range and, where one
  * value holds everywhere, its default. Static data, readable with no map loaded.
  *
  * @remarks
@@ -14326,20 +14451,20 @@ export declare const trafficIncidentsKnobIds: readonly TrafficIncidentsKnobId[];
  *
  * @group Traffic
  */
-export declare const trafficIncidentOverlayKnobCatalogue: readonly TrafficIncidentOverlayKnob[];
+export declare const trafficIncidentDetailsKnobCatalogue: readonly TrafficIncidentDetailsKnob[];
 /**
- * Every incident overlay knob id, in catalogue order.
+ * Every incident details knob id, in catalogue order.
  *
  * @group Traffic
  */
-export declare const trafficIncidentOverlayKnobIds: readonly TrafficIncidentOverlayKnobId[];
+export declare const trafficIncidentDetailsKnobIds: readonly TrafficIncidentDetailsKnobId[];
 /**
  * Every {@link TrafficAreaAnalyticsModule} knob with its kind, description, range or options and,
  * where one value holds everywhere, its default: the module-wide knobs first, then each metric's.
  * Static data, readable with no map loaded.
  *
  * @remarks
- * Not knobs: custom colour stops, `beforeLayerConfig` and `events`, which take structured values.
+ * Not knobs: `colorStops`, `beforeLayerConfig` and `events`, which take structured values.
  * The module bounds no height: a height knob's range is the span a UI offers.
  *
  * @group Traffic Area Analytics
@@ -14354,10 +14479,12 @@ export declare const trafficAreaAnalyticsKnobIds: readonly TrafficAreaAnalyticsK
 //#endregion
 //#region src/traffic/layers/areaAnalyticsLayers.d.ts
 /**
- * Resolves the effective color stops for a given color configuration.
+ * The colour stops a metric's cells are painted with: its `colorStops` when set, else its `palette`
+ * (`trafficLight` when unset) spread evenly from 0 to 100 % of the metric's range, as
+ * {@link AreaAnalyticsMetricConfig.palette} describes.
  * @ignore
  */
-export declare const resolveColorStops: (colorConfig: AreaAnalyticsColorTheme | AreaAnalyticsColorStopsConfig) => AreaAnalyticsColorStop[];
+export declare const resolveColorStops: (metric: AreaAnalyticsMetricKey, metricConfig?: Pick<AreaAnalyticsMetricConfig, "palette" | "colorStops">) => AreaAnalyticsColorStopsConfig;
 //#endregion
 //#region src/traffic/types/trafficAreaAnalyticsFeature.d.ts
 /**
@@ -14466,7 +14593,7 @@ export declare class TrafficAreaAnalyticsModule extends AbstractDataOwnedMapModu
    * const module = await TrafficAreaAnalyticsModule.create(map, {
    *   displayMode: 'heatmap',
    *   metricConfig: {
-   *     congestionLevel: { color: 'heat' },
+   *     congestionLevel: { palette: 'heat' },
    *   },
    * });
    * ```
@@ -14477,7 +14604,6 @@ export declare class TrafficAreaAnalyticsModule extends AbstractDataOwnedMapModu
   protected _initSourcesWithLayers(config?: TrafficAreaAnalyticsModuleConfig, _restore?: boolean): AreaAnalyticsSourcesWithLayers;
   /** @ignore */
   protected _applyConfig(config: TrafficAreaAnalyticsModuleConfig | undefined): TrafficAreaAnalyticsModuleConfig | undefined;
-  private get modeLayerSpecs();
   private moveLayersToSpecPositions;
   /** @ignore */
   protected discardShownData(): void;
@@ -14500,56 +14626,44 @@ export declare class TrafficAreaAnalyticsModule extends AbstractDataOwnedMapModu
    * ```
    */
   show(analytics: TrafficAreaAnalytics): Promise<void>;
+  private display;
   /**
    * Removes all area analytics data from the map.
    */
   clear(): Promise<void>;
   /**
-   * Switches the visualisation mode.
+   * Sets the palette of one or more metrics, as {@link AreaAnalyticsMetricConfig.palette} describes.
    *
-   * @param mode - One of `'heatmap'`, `'hexgrid-3d'`, `'hexgrid-2d'`, `'square-3d'`, `'square-2d'`.
-   */
-  setMode(mode: AreaAnalyticsDisplayMode): void;
-  /**
-   * Changes the active metric that drives colour and height.
+   * A metric whose `colorStops` are set keeps painting with them; clear those with
+   * `setColorStops(undefined)` for the palette to show.
    *
-   * Updates `activeMetric` in the config to the given metric key.
+   * @param palette - The palette, or `undefined` to clear it back to `trafficLight`.
+   * @param metrics - The metrics to set it on. When omitted, **all** metrics.
    *
-   * @param metric - One of `'congestionLevel'`, `'speed'`, `'travelTime'`, `'freeFlowSpeed'`, or `'networkLength'`.
+   * @example
+   * ```typescript
+   * module.setPalette('heat');                           // every metric
+   * module.setPalette('viridis', ['speed', 'freeFlowSpeed']);
+   * module.setPalette(undefined, ['speed']);             // back to 'trafficLight'
+   * ```
    */
-  setMetric(metric: AreaAnalyticsMetricKey): void;
+  setPalette(palette: AreaAnalyticsPalette | undefined, metrics?: AreaAnalyticsMetricKey[]): void;
   /**
-   * Sets the color for one or more metrics.
+   * Sets explicit colour stops on one or more metrics, which win over their palette.
    *
-   * Pass a preset theme name or a custom color-stops configuration.
-   * Pass `undefined` to clear the color override for the targeted metrics.
-   *
-   * @param color - A preset theme, an `AreaAnalyticsColorStopsConfig`, or `undefined` to clear.
-   * @param metrics - Optional list of metrics to target.
-   *   When omitted, the color is applied to **all** metrics.
+   * @param colorStops - The stops, or `undefined` to clear them so the palette paints again.
+   * @param metrics - The metrics to set them on. When omitted, **all** metrics.
    *
    * @example
    * ```typescript
-   * // Apply a theme to all metrics
-   * module.setColor('heat');
-   *
-   * // Apply a theme to specific metrics only
-   * module.setColor('heat', ['speed', 'freeFlowSpeed']);
-   *
-   * // Apply custom stops to a single metric
-   * module.setColor(
+   * module.setColorStops(
    *   { valueType: 'raw', stops: [{ value: 0, color: '#2dc653' }, { value: 100, color: '#e03030' }] },
    *   ['congestionLevel'],
    * );
-   *
-   * // Clear color override for all metrics
-   * module.setColor(undefined);
-   *
-   * // Clear color override for a specific metric
-   * module.setColor(undefined, ['speed']);
+   * module.setColorStops(undefined);                     // every metric back to its palette
    * ```
    */
-  setColor(color: AreaAnalyticsColorTheme | AreaAnalyticsColorStopsConfig | undefined, metrics?: AreaAnalyticsMetricKey[]): void;
+  setColorStops(colorStops: AreaAnalyticsColorStopsConfig | undefined, metrics?: AreaAnalyticsMetricKey[]): void;
   /**
    * Configures extrusion height behaviour for one or more metrics.
    *
@@ -14577,22 +14691,16 @@ export declare class TrafficAreaAnalyticsModule extends AbstractDataOwnedMapModu
    * @example
    * ```typescript
    * // Filter all metrics
-   * module.filter({ min: 20, max: 80 });
+   * module.setFilters({ min: 20, max: 80 });
    *
    * // Filter only a specific metric
-   * module.filter({ min: 50 }, ['congestionLevel']);
+   * module.setFilters({ min: 50 }, ['congestionLevel']);
    *
-   * // Clear filter for all metrics
-   * module.filter(undefined);
+   * // Clear the filters of every metric
+   * module.setFilters(undefined);
    * ```
    */
-  filter(filter?: AreaAnalyticsMetricFilter, metrics?: AreaAnalyticsMetricKey[]): void;
-  /**
-   * Clears any active tile filter for one or more metrics.
-   *
-   * @param metrics - Optional list of metrics to clear. When omitted, clears filters for **all** metrics.
-   */
-  clearFilter(metrics?: AreaAnalyticsMetricKey[]): void;
+  setFilters(filters: AreaAnalyticsMetricFilter | undefined, metrics?: AreaAnalyticsMetricKey[]): void;
   /**
    * Returns the currently displayed data for all visualisation modes.
    */
@@ -14601,14 +14709,8 @@ export declare class TrafficAreaAnalyticsModule extends AbstractDataOwnedMapModu
     hexgrid: FeatureCollection<Polygon, AreaAnalyticsDisplayProperties>;
     square: FeatureCollection<Polygon, AreaAnalyticsDisplayProperties>;
   };
-  /**
-   * Repositions the analytics layers, all together or per display mode.
-   *
-   * Only the display modes `layerConfig` names a target for are repositioned; the others are left in place.
-   *
-   * @param layerConfig - A single target for every mode, or one per {@link AreaAnalyticsDisplayMode}.
-   */
-  moveBeforeLayer(layerConfig: AreaAnalyticsBeforeLayerConfig): void;
+  /** @ignore */
+  protected eventStateSources(): (keyof AreaAnalyticsSourcesWithLayers)[];
   /**
    * Event interface for the hexgrid and square layers.
    *
@@ -14632,7 +14734,7 @@ export declare class TrafficAreaAnalyticsModule extends AbstractDataOwnedMapModu
    * ```
    */
   get events(): CombinedEvents<AreaAnalyticsTileFeature, TrafficAreaAnalyticsModuleConfig, TrafficAreaAnalytics>;
-  private get mode();
+  private setMetricField;
   private get activeMetric();
   private get lightDark();
   /** @ignore */
@@ -14748,34 +14850,20 @@ type TrafficFlowSourcesWithLayers = {
  * Filter by road type:
  * ```typescript
  * // Show only highway traffic
- * trafficFlow.filter({
- *   any: [{
- *     roadCategories: {
- *       show: 'only',
- *       values: ['motorway', 'trunk']
- *     }
- *   }]
+ * trafficFlow.updateConfig({
+ *   filters: { any: [{ roadCategories: { show: 'only', values: ['motorway', 'trunk'] } }] },
  * });
  *
  * // Hide local streets
- * trafficFlow.filter({
- *   any: [{
- *     roadCategories: {
- *       show: 'all-except',
- *       values: ['street']
- *     }
- *   }]
+ * trafficFlow.updateConfig({
+ *   filters: { any: [{ roadCategories: { show: 'all-except', values: ['street'] } }] },
  * });
- * ```
  *
- * @example
- * Show only road closures:
- * ```typescript
- * trafficFlow.filter({
- *   any: [{
- *     showRoadClosures: 'only'
- *   }]
- * });
+ * // Show only road closures
+ * trafficFlow.updateConfig({ filters: { any: [{ showRoadClosures: 'only' }] } });
+ *
+ * // Show all traffic again
+ * trafficFlow.updateConfig({ filters: undefined });
  * ```
  *
  * @see [Traffic Flow Guide](https://docs.tomtom.com/maps-sdk-js/guides/map/traffic-flow)
@@ -14846,78 +14934,7 @@ export declare class TrafficFlowModule extends AbstractStyleOwnedMapModule<Traff
    */
   protected _applyConfig(config: TrafficFlowModuleConfig | undefined): TrafficFlowModuleConfig | undefined;
   private getLayers;
-  /**
-   * Applies filters to traffic flow display.
-   *
-   * @param filters - Filter configuration for road types, categories, and closures.
-   * Pass `undefined` to reset to defaults (show all).
-   *
-   * @remarks
-   * **Filter Options:**
-   * - `roadCategories`: Filter by road importance (motorway, trunk, primary, etc.)
-   * - `roadSubCategories`: Filter by specific street types
-   * - `showRoadClosures`: Show only closures or exclude them
-   *
-   * **Available Road Categories:**
-   * - `motorway`: Major highways
-   * - `trunk`: Major roads
-   * - `primary`: Primary roads
-   * - `secondary`: Secondary roads
-   * - `tertiary`: Tertiary roads
-   * - `street`: Local streets
-   *
-   * **Filter Logic:**
-   * Uses "any" (OR) logic - traffic matching any filter is shown.
-   *
-   * @example
-   * Show only major roads:
-   * ```typescript
-   * trafficFlow.filter({
-   *   any: [{
-   *     roadCategories: {
-   *       show: 'only',
-   *       values: ['motorway', 'trunk', 'primary']
-   *     }
-   *   }]
-   * });
-   * ```
-   *
-   * @example
-   * Hide street-level traffic:
-   * ```typescript
-   * trafficFlow.filter({
-   *   any: [{
-   *     roadCategories: {
-   *       show: 'all-except',
-   *       values: ['street']
-   *     }
-   *   }]
-   * });
-   * ```
-   *
-   * @example
-   * Multiple filter criteria:
-   * ```typescript
-   * trafficFlow.filter({
-   *   any: [
-   *     {
-   *       roadCategories: { show: 'only', values: ['motorway'] }
-   *     },
-   *     {
-   *       showRoadClosures: 'only'
-   *     }
-   *   ]
-   * });
-   * ```
-   *
-   * @example
-   * Reset filters:
-   * ```typescript
-   * trafficFlow.filter(undefined);
-   * ```
-   */
-  filter(filters?: TrafficFlowFilters): void;
-  private _filter;
+  private applyFilters;
   /**
    * Sets the visibility of traffic flow layers.
    *
@@ -14972,7 +14989,7 @@ export declare class TrafficFlowModule extends AbstractStyleOwnedMapModule<Traff
   get events(): CombinedEvents<TrafficFlowModuleFeature, TrafficFlowModuleConfig, never>;
 }
 //#endregion
-//#region src/traffic/TrafficIncidentOverlayModule.d.ts
+//#region src/traffic/TrafficIncidentDetailsModule.d.ts
 type Sources = {
   incidents: GeoJSONSourceWithLayers<TrafficIncidentDetails>;
 };
@@ -14981,9 +14998,9 @@ type Sources = {
  *
  * Use this module when you fetch incidents via the Incident Details service and want
  * to display them as a developer-controlled overlay. {@link TrafficIncidentsModule} is
- * the vector-tile alternative — hidden in the default style, so the overlay renders
+ * the vector-tile alternative — hidden in the default style, so this module renders
  * on its own without collision; if you've enabled it elsewhere in your app, hide it
- * again before using the overlay to avoid double-rendering.
+ * again before using this module to avoid double-rendering.
  *
  * ## Rendering approach
  *
@@ -15003,10 +15020,11 @@ type Sources = {
  * {@link setFocus} writes MapLibre feature-state `focused=true|false` on each rendered
  * incident. The default visual treatment widens the focused subset and paints an
  * outline beneath it (black on light map styles, white on dark); unfocused incidents
- * are unchanged. Override or disable the visual
- * treatment via the `focus` config — `focus: false` keeps `setFocus` writing feature-state
- * but emits no halo layer and no width pop, leaving callers free to drive their own
- * styling off `feature-state.focused`.
+ * are unchanged. A hovered or clicked incident (its `eventState`, see
+ * {@link putEventState}) draws the same treatment. Override or disable it via the `focus`
+ * config — `focus: false` keeps `setFocus` writing feature-state but emits no halo layer
+ * and no width pop, leaving callers free to drive their own styling off
+ * `feature-state.focused` and `eventState`.
  *
  * ## API limitations
  *
@@ -15044,60 +15062,59 @@ type Sources = {
  * Fetch and render incidents for Amsterdam:
  * ```typescript
  * import { TomTomConfig } from '@tomtom-org/maps-sdk/core';
- * import { TomTomMap, TrafficIncidentOverlayModule } from '@tomtom-org/maps-sdk/map';
+ * import { TomTomMap, TrafficIncidentDetailsModule } from '@tomtom-org/maps-sdk/map';
  * import { trafficIncidentDetails } from '@tomtom-org/maps-sdk/services';
  *
  * TomTomConfig.instance.put({ apiKey: '<API_KEY>' });
  *
  * const map = new TomTomMap({ mapLibre: { container: 'map', center: [4.9, 52.37], zoom: 13 } });
  *
- * const overlay = await TrafficIncidentOverlayModule.create(map);
+ * const incidentDetailsModule = await TrafficIncidentDetailsModule.create(map);
  * const result = await trafficIncidentDetails({
  *     bbox: [4.85, 52.34, 4.95, 52.40],
  *     timeValidityFilter: ['present'],
  * });
- * await overlay.show(result);
+ * await incidentDetailsModule.show(result);
  *
  * // Highlight a subset.
- * overlay.setFocus([result.features[0].properties.id as string]);
+ * incidentDetailsModule.setFocus([result.features[0].properties.id as string]);
  * ```
  *
  * @see {@link TrafficIncidentsModule} — the vector-tile alternative. Hidden in the
  *   default style; if you've enabled it explicitly elsewhere in your app, hide it again
- *   before using the overlay to avoid double-rendering.
- * @see [Traffic Incident Overlay Guide](https://docs.tomtom.com/maps-sdk-js/guides/map/traffic-incident-overlay)
+ *   before using this module to avoid double-rendering.
+ * @see [Traffic Incident Details Guide](https://docs.tomtom.com/maps-sdk-js/guides/map/traffic-incident-details)
  * @see [Traffic Incident Details Service](https://docs.tomtom.com/maps-sdk-js/guides/services/traffic/traffic-incident-details)
  *
  * @group Traffic
  */
-export declare class TrafficIncidentOverlayModule extends AbstractDataOwnedMapModule<Sources, TrafficIncidentOverlayModuleConfig> {
-  private lastResult;
+export declare class TrafficIncidentDetailsModule extends AbstractDataOwnedMapModule<Sources, TrafficIncidentDetailsModuleConfig> {
   private lastFeatureIds;
   private lastFocusIds;
   private readonly shownFeaturesHandlers;
   /**
    * Creates a new module instance on the given map, waiting until the map is ready first.
    *
-   * `TrafficIncidentOverlayModule` owns the sources, layers and images it adds, all suffixed per
+   * `TrafficIncidentDetailsModule` owns the sources, layers and images it adds, all suffixed per
    * instance. Every call therefore returns a **new, independent** instance, and stacking several
    * of them on one map is a supported thing to do.
    *
-   * {@link trafficIncidentOverlayKnobCatalogue} lists the plain-valued settings of `config` as data.
+   * {@link trafficIncidentDetailsKnobCatalogue} lists the plain-valued settings of `config` as data.
    *
    * @param tomtomMap The TomTomMap instance.
    * @param config The module optional configuration.
    * @returns {Promise} Returns a promise with a new instance of this module.
    */
-  static create(tomtomMap: TomTomMap, config?: TrafficIncidentOverlayModuleConfig): Promise<TrafficIncidentOverlayModule>;
+  static create(tomtomMap: TomTomMap, config?: TrafficIncidentDetailsModuleConfig): Promise<TrafficIncidentDetailsModule>;
   private constructor();
   private buildLayerSpecs;
   private updateLayers;
   /** @ignore */
-  protected _initSourcesWithLayers(config?: TrafficIncidentOverlayModuleConfig, _restore?: boolean): Sources;
+  protected _initSourcesWithLayers(config?: TrafficIncidentDetailsModuleConfig, _restore?: boolean): Sources;
   /** @ignore */
-  protected _applyConfig(config: TrafficIncidentOverlayModuleConfig | undefined): TrafficIncidentOverlayModuleConfig | undefined;
+  protected _applyConfig(config: TrafficIncidentDetailsModuleConfig | undefined): TrafficIncidentDetailsModuleConfig | undefined;
   /** @ignore */
-  protected applyVisibility(config: TrafficIncidentOverlayModuleConfig | undefined): void;
+  protected applyVisibility(config: TrafficIncidentDetailsModuleConfig | undefined): void;
   private applyBeforeLayer;
   /** @ignore */
   protected discardShownData(): void;
@@ -15111,10 +15128,6 @@ export declare class TrafficIncidentOverlayModule extends AbstractDataOwnedMapMo
    * Remove all rendered incidents (source kept, data emptied).
    */
   clear(): Promise<void>;
-  /**
-   * Move incident layers before the given map-style layer, or to the top.
-   */
-  moveBeforeLayer(beforeLayerConfig: BeforeLayerConfig): void;
   /**
    * Returns the currently shown incidents — the exact data that was passed to {@link show}.
    *
@@ -15127,7 +15140,9 @@ export declare class TrafficIncidentOverlayModule extends AbstractDataOwnedMapMo
   getShown(): {
     incidents: TrafficIncidentDetails;
   };
-  get events(): CombinedEvents<TrafficIncident, TrafficIncidentOverlayModuleConfig, TrafficIncidentDetails>;
+  /** @ignore */
+  protected eventStateSources(): (keyof Sources)[];
+  get events(): CombinedEvents<TrafficIncident, TrafficIncidentDetailsModuleConfig, TrafficIncidentDetails>;
   /**
    * Mark a subset of currently-rendered incidents as "focused" via MapLibre
    * feature-state. `null` clears the state. Paint expressions in
@@ -15241,23 +15256,13 @@ type TrafficIncidentsSourcesWithLayers = {
  * Filter by incident type:
  * ```typescript
  * // Show only accidents and road closures
- * trafficIncidentsModule.filter({
- *   any: [{
- *     incidentCategories: {
- *       show: 'only',
- *       values: ['accident', 'road-closed']
- *     }
- *   }]
+ * trafficIncidentsModule.updateConfig({
+ *   filters: { any: [{ incidentCategories: { show: 'only', values: ['accident', 'road-closed'] } }] },
  * });
  *
  * // Hide construction
- * trafficIncidentsModule.filter({
- *   any: [{
- *     incidentCategories: {
- *       show: 'all-except',
- *       values: ['roadworks']
- *     }
- *   }]
+ * trafficIncidentsModule.updateConfig({
+ *   filters: { any: [{ incidentCategories: { show: 'all-except', values: ['roadworks'] } }] },
  * });
  * ```
  *
@@ -15265,31 +15270,20 @@ type TrafficIncidentsSourcesWithLayers = {
  * Filter by severity:
  * ```typescript
  * // Show only major delays
- * incidents.filter({
- *   any: [{
- *     magnitudes: {
- *       show: 'only',
- *       values: ['major']
- *     }
- *   }]
- * });
+ * incidents.updateConfig({ filters: { any: [{ magnitudes: { show: 'only', values: ['major'] } }] } });
  *
  * // Show incidents with at least 10 minutes delay
- * incidents.filter({
- *   any: [{
- *     delays: {
- *       mustHaveDelay: true,
- *       minDelayMinutes: 10
- *     }
- *   }]
- * });
+ * incidents.updateConfig({ filters: { any: [{ delays: { mustHaveDelay: true, minDelayMinutes: 10 } }] } });
+ *
+ * // Show every incident again
+ * incidents.updateConfig({ filters: undefined });
  * ```
  *
  * @see [Traffic Incidents Guide](https://docs.tomtom.com/maps-sdk-js/guides/map/traffic-incidents)
  * @see [Traffic Guide](https://docs.tomtom.com/maps-sdk-js/guides/map/traffic)
- * @see {@link TrafficIncidentOverlayModule} — for rendering incidents fetched via the
+ * @see {@link TrafficIncidentDetailsModule} — for rendering incidents fetched via the
  *   `trafficIncidentDetails()` REST service as a developer-controlled overlay (use the
- *   overlay when you need typed incident objects in app code; this vector-tile module
+ *   details module when you need typed incident objects in app code; this vector-tile module
  *   remains the recommended default for visual fidelity).
  *
  * @group Traffic Incidents
@@ -15355,63 +15349,7 @@ export declare class TrafficIncidentsModule extends AbstractStyleOwnedMapModule<
    * @ignore
    */
   protected _applyConfig(config: TrafficIncidentsModuleConfig | undefined): TrafficIncidentsModuleConfig | undefined;
-  /**
-   * Applies filters to traffic incidents display, incident lines and icons alike.
-   *
-   * @param filters - Pass `undefined` to reset.
-   *
-   * @remarks
-   * **Filter Options:**
-   * - `incidentCategories`: Filter by incident type
-   * - `magnitudes`: Filter by delay severity (minor/moderate/major/unknown)
-   * - `delays`: Filter by delay duration
-   * - `roadCategories`: Filter by road importance
-   * - `roadSubCategories`: Filter by specific road types
-   *
-   * **Available Incident Categories:**
-   * - `accident`, `road-closed`, `lane-closed`
-   * - `roadworks` (construction)
-   * - `jam` (traffic jam)
-   * - `fog`, `rain`, `frost`, `wind`, `flooding`
-   * - `danger`, `animals-on-road`, `narrow-lanes`
-   * - `broken-down-vehicle`
-   * - `other`
-   *
-   * **Delay Magnitudes:**
-   * - `minor`: Small delays
-   * - `moderate`: Moderate delays
-   * - `major`: Significant delays
-   * - `unknown`: Unknown or no delay info
-   *
-   * @example
-   * Filter by type:
-   * ```typescript
-   * incidents.filter({
-   *   any: [{
-   *     incidentCategories: {
-   *       show: 'only',
-   *       values: ['accident', 'road-closed']
-   *     }
-   *   }]
-   * });
-   * ```
-   *
-   * @example
-   * Filter by severity and delay:
-   * ```typescript
-   * incidents.filter({
-   *   any: [{
-   *     magnitudes: { show: 'only', values: ['major', 'moderate'] },
-   *     delays: {
-   *       mustHaveDelay: true,
-   *       minDelayMinutes: 5
-   *     }
-   *   }]
-   * });
-   * ```
-   */
-  filter(filters?: TrafficIncidentsFilters): void;
-  private _filter;
+  private applyFilters;
   private getLayers;
   /**
    * Sets the visibility of incident icon layers.
@@ -15419,7 +15357,9 @@ export declare class TrafficIncidentsModule extends AbstractStyleOwnedMapModule<
    * @param visible - `true` to show icons, `false` to hide them.
    *
    * @remarks
-   * This controls only the icon/symbol layers, not the incident area polygons or lines.
+   * This controls only the icon/symbol layers, not the incident area polygons or lines. It stores
+   * `icons.visible`, which overrides `visible` for the icons until the next {@link setVisible}:
+   * `setVisible(false)` then `setIconsVisible(true)` shows the icons alone.
    *
    * @example
    * ```typescript
@@ -15438,7 +15378,8 @@ export declare class TrafficIncidentsModule extends AbstractStyleOwnedMapModule<
    * @param visible - `true` to show incidents, `false` to hide them.
    *
    * @remarks
-   * This controls all incident layers including icons, lines, and polygons.
+   * This controls all incident layers including icons, lines, and polygons, and clears
+   * `icons.visible`, so the icons follow `visible` again.
    *
    * @example
    * ```typescript
@@ -15452,7 +15393,7 @@ export declare class TrafficIncidentsModule extends AbstractStyleOwnedMapModule<
    * Whether traffic incidents are set to be shown.
    *
    * @returns The `visible` setting; `false` while nothing has set it, as traffic is hidden until
-   * shown. {@link anyIconLayersVisible} reads the icon layers themselves.
+   * shown. {@link isIconsVisible} reads the icons setting.
    *
    * @example
    * ```typescript
@@ -15463,18 +15404,19 @@ export declare class TrafficIncidentsModule extends AbstractStyleOwnedMapModule<
    */
   isVisible(): boolean;
   /**
-   * Checks if any incident icon layers are currently visible.
+   * Whether the incident icons are set to be shown.
    *
-   * @returns `true` if any icon layer is visible, `false` if all icons are hidden.
+   * @returns The `icons.visible` setting and, while it is unset, {@link isVisible}. It is `true`
+   * for the icons-only state, `{ visible: false, icons: { visible: true } }`.
    *
    * @example
    * ```typescript
-   * if (incidents.anyIconLayersVisible()) {
-   *   console.log('Incident icons are shown');
-   * }
+   * incidents.setVisible(false);
+   * incidents.setIconsVisible(true);
+   * incidents.isIconsVisible(); // true: the icons show alone
    * ```
    */
-  anyIconLayersVisible(): boolean;
+  isIconsVisible(): boolean;
   /**
    * Returns features currently visible in the viewport.
    *
@@ -15639,4 +15581,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, BaseMapColorName, BaseMapKnob, BaseMapKnobId, BaseMapKnobValueOf, BeforeLayerConfig, BespokeSectionType, ByIdOrIndex, CSSCursor, ChargingSpeedIconMapping, ChargingStopIconConfig, ChargingStopIconMapping, ChargingStopLabelConfig, ChargingStopsConfig, CleanEventStateOptions, CleanEventStatesOptions, ClickEventType, CountryCrossingAlignment, CountryCrossingConfig, CountryCrossingFeature, CustomGeoJSONKnob, CustomGeoJSONKnobId, CustomGeoJSONKnobValueOf, CustomImage, DefaultPlaceIconConfig, DisplayCountryCrossing, DisplayCountryCrossingProps, DisplayCountryCrossings, DisplayRouteProps, DisplayRouteRelatedProps, DisplayRouteSummaries, DisplayRouteSummary, DisplayRouteSummaryProps, DrawnSectionType, EVAvailabilityConfig, EventHandlerConfig, EventHandlerCursorConfig, EventHandlerHoverConfig, EventState, EventType, ExtraFeatureProp, FeaturePropValue, FilterablePOICategory, GeneratedSectionType, GeoJSONSourcesWithLayers, GeometriesKnob, GeometriesKnobId, GeometriesKnobValueOf, HasAdditionalLayersConfig, HasBeforeID, HoverEventType, HslColor, LabelConfig, LayerQuery, LayerSpecFilter, LayerSpecTemplate, LayerSpecWithSource, LightDark, MapColorName, MapColors, MapEventsConfig, MapFont, MapModuleCommonConfig, MapStyleLayerID, POIsKnob, POIsKnobId, POIsKnobValueOf, POIsModuleConfig, POIsModuleFeature, PartsBeforeLayerConfig, PlaceClusterBadgeConfig, PlaceConnectionDisplay, PlaceConnectionLayerName, PlaceConnectionsConfig, PlaceConnectionsLayersConfig, PlaceEntryPointFeature, PlaceEntryPointProps, PlaceEntryPointsConfig, PlaceEntryPointsLayersConfig, PlaceEntryPointsShowFor, PlaceIconConfig, PlaceLabelConfig, PlaceLayerName, PlaceLayersConfig, PlacesClusterConfig, PlacesKnob, PlacesKnobId, PlacesKnobValueOf, PlacesMarkerType, PlacesModuleConfig, PlacesModuleSerializableConfig, PlanningWaypoint, PutEventStateOptions, RGBAColor, RouteLayersConfig, RouteStateProps, RouteWaypointSize, RouteWidth, RoutingBeforeLayerConfig, RoutingKnob, RoutingKnobId, RoutingKnobValueOf, RoutingModuleConfig, RoutingModuleSerializableConfig, SVGIconStyleOptions, SectionDisplayConfig, SectionDrawStyle, SectionIconConfig, SectionIconPlacement, SectionKnobName, SectionKnobOf, SectionLineLayerName, SectionLinePattern, SectionSignConfig, SectionSignLayerName, SectionSignPlacement, SectionSignPriority, SectionSignUnit, SectionSourceKey, SectionSymbolLayerName, SectionsDisplayConfig, SerializableCustomImage, SourceWithLayerIDs, SourceWithLayers, SourcesWithLayers, StyleSourcesWithLayers, StylingColorKnobId, StylingKnob, StylingKnobAppliesTo, StylingKnobId, StylingKnobKind, StylingKnobRange, StylingKnobValue, StylingKnobValueOf, StylingPreset, StylingPresetId, StylingSettings, SupportsEvents, SymbolLayerSpecWithoutSource, TRAFFIC_LIGHT_COLORS, TerrainKnob, TerrainKnobId, TerrainKnobValueOf, TerrainModuleConfig, ToBeAddedLayerSpec, ToBeAddedLayerSpecTemplate, ToBeAddedLayerSpecWithoutSource, TrafficAreaAnalyticsKnob, TrafficAreaAnalyticsKnobId, TrafficAreaAnalyticsKnobValueOf, TrafficAreaAnalyticsModuleConfig, TrafficFlowKnob, TrafficFlowKnobId, TrafficFlowKnobValueOf, TrafficIncidentOverlayKnob, TrafficIncidentOverlayKnobId, TrafficIncidentOverlayKnobValueOf, TrafficIncidentsKnob, TrafficIncidentsKnobId, TrafficIncidentsKnobValueOf, UserEventHandler, WaypointsConfig };
+export type { AREA_ANALYTICS_DEFAULTS, AreaAnalyticsBeforeLayerConfig, AreaAnalyticsColorStop, AreaAnalyticsColorStopsConfig, AreaAnalyticsDisplayMode, AreaAnalyticsHeightConfig, AreaAnalyticsMetricConfig, AreaAnalyticsMetricFilter, AreaAnalyticsPalette, AreaAnalyticsRegionPolygonConfig, AreaAnalyticsValueType, AvailabilityLevel, BaseMapColorName, BaseMapKnob, BaseMapKnobId, BaseMapKnobValueOf, BeforeLayerConfig, BespokeSectionType, ByIdOrIndex, CSSCursor, ChargingSpeedIconMapping, ChargingStopIconConfig, ChargingStopIconMapping, ChargingStopLabelConfig, ChargingStopsConfig, CleanEventStateOptions, CleanEventStatesOptions, ClickEventType, CountryCrossingAlignment, CountryCrossingConfig, CountryCrossingFeature, CustomGeoJSONKnob, CustomGeoJSONKnobId, CustomGeoJSONKnobValueOf, CustomImage, DefaultPlaceIconConfig, DisplayCountryCrossing, DisplayCountryCrossingProps, DisplayCountryCrossings, DisplayRouteProps, DisplayRouteRelatedProps, DisplayRouteSummaries, DisplayRouteSummary, DisplayRouteSummaryProps, DrawnSectionType, EVAvailabilityConfig, EventHandlerConfig, EventHandlerCursorConfig, EventHandlerHoverConfig, EventState, EventStateIds, EventType, ExtraFeatureProp, FeaturePropValue, FilterablePOICategory, GeneratedSectionType, GeoJSONSourcesWithLayers, GeometriesKnob, GeometriesKnobId, GeometriesKnobValueOf, HasAdditionalLayersConfig, HasBeforeID, HoverEventType, HslColor, LabelConfig, LayerQuery, LayerSpecFilter, LayerSpecTemplate, LayerSpecWithSource, LightDark, MapColorName, MapColors, MapEventsConfig, MapFont, MapModuleCommonConfig, MapStyleLayerID, POIsKnob, POIsKnobId, POIsKnobValueOf, POIsModuleConfig, POIsModuleFeature, PartsBeforeLayerConfig, PlaceClusterBadgeConfig, PlaceConnectionDisplay, PlaceConnectionLayerName, PlaceConnectionsConfig, PlaceConnectionsLayersConfig, PlaceEntryPointFeature, PlaceEntryPointProps, PlaceEntryPointsConfig, PlaceEntryPointsLayersConfig, PlaceEntryPointsShowFor, PlaceIconConfig, PlaceLabelConfig, PlaceLayerName, PlaceLayersConfig, PlacesBeforeLayerConfig, PlacesClusterConfig, PlacesKnob, PlacesKnobId, PlacesKnobValueOf, PlacesMarkerType, PlacesModuleConfig, PlacesModuleSerializableConfig, PlanningWaypoint, PutEventStateOptions, RGBAColor, ReachableRangesKnob, ReachableRangesKnobId, ReachableRangesKnobValueOf, RouteHighlightConfig, RouteLayersConfig, RouteStateProps, RouteWaypointSize, RouteWidth, RoutingBeforeLayerConfig, RoutingKnob, RoutingKnobId, RoutingKnobValueOf, RoutingModuleConfig, RoutingModuleSerializableConfig, SVGIconStyleOptions, SectionDisplayConfig, SectionDrawStyle, SectionIconConfig, SectionIconPlacement, SectionKnobName, SectionKnobOf, SectionLineLayerName, SectionLinePattern, SectionSignConfig, SectionSignLayerName, SectionSignPlacement, SectionSignPriority, SectionSignUnit, SectionSourceKey, SectionSymbolLayerName, SectionsDisplayConfig, SerializableCustomImage, SourceWithLayerIDs, SourceWithLayers, SourcesWithLayers, StyleSourcesWithLayers, StylingColorKnobId, StylingKnob, StylingKnobAppliesTo, StylingKnobId, StylingKnobKind, StylingKnobRange, StylingKnobValue, StylingKnobValueOf, StylingPreset, StylingPresetId, StylingSettings, SupportsEvents, SymbolLayerSpecWithoutSource, TerrainKnob, TerrainKnobId, TerrainKnobValueOf, TerrainModuleConfig, ToBeAddedLayerSpec, ToBeAddedLayerSpecTemplate, ToBeAddedLayerSpecWithoutSource, TrafficAreaAnalyticsKnob, TrafficAreaAnalyticsKnobId, TrafficAreaAnalyticsKnobValueOf, TrafficAreaAnalyticsModuleConfig, TrafficFlowKnob, TrafficFlowKnobId, TrafficFlowKnobValueOf, TrafficIncidentDetailsKnob, TrafficIncidentDetailsKnobId, TrafficIncidentDetailsKnobValueOf, TrafficIncidentsKnob, TrafficIncidentsKnobId, TrafficIncidentsKnobValueOf, UserEventHandler, WaypointsConfig };