@tomtom-org/maps-sdk 0.52.0 → 0.54.0

package/map/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { BackgroundLayerSpecification, CircleLayerSpecification, DataDrivenPropertyValueSpecification, ExpressionFilterSpecification, ExpressionSpecification, GeoJSONSource, GeoJSONSourceSpecification, LayerSpecification, LegacyFilterSpecification, LineLayerSpecification, LngLat, Map, MapGeoJSONFeature, MapOptions, Source, SourceSpecification, StyleImageInterface, StyleImageMetadata, StyleSpecification, SymbolLayerSpecification } from "maplibre-gl";
+import { BackgroundLayerSpecification, CircleLayerSpecification, DataDrivenPropertyValueSpecification, ExpressionSpecification, GeoJSONSource, GeoJSONSourceSpecification, LayerSpecification, LineLayerSpecification, LngLat, Map, MapGeoJSONFeature, MapOptions, Source, SourceSpecification, StyleImageInterface, StyleImageMetadata, StyleSpecification, SymbolLayerSpecification } from "maplibre-gl";
 import { Anything, AreaAnalyticsMetricKey, AreaAnalyticsMetrics, BBox, ChargingSpeed, ChargingStop, CommonPlaceProps, DelayMagnitude, DisplayUnits, GetPositionEntryPointOption, GlobalConfig, Instruction, Language, POICategory, Place, Places, PolygonFeature, PolygonFeatures, Route, RouteProps, Routes, SectionProps, TrafficAreaAnalytics, TrafficIncident, TrafficIncidentBaseProperties, TrafficIncidentCategory, TrafficIncidentDetails, TrafficIncidentTimeValidity, TrafficSectionProps, Waypoint, WaypointLike, Waypoints } from "@tomtom-org/maps-sdk/core";
 //#region src/init/types/mapEventsConfig.d.ts
 /**
@@ -192,6 +192,15 @@ type MapEventsConfig = EventHandlerCursorConfig & {
   longHoverDelayOnStillMapMS?: number;
 };
 //#endregion
+//#region src/shared/types/style.d.ts
+/**
+ * Indicator of a light or dark theme.
+ * * Can be used to classify a map style as light or dark, or to apply light or dark configurations to map modules if they support it.
+ *
+ * @group Map Style
+ */
+type LightDark = 'light' | 'dark';
+//#endregion
 //#region src/init/types/mapInit.d.ts
 /**
  * Array of all available standard style identifiers.
@@ -397,6 +406,27 @@ export type CustomStyle = {
    * ```
    */
   json?: StyleSpecification;
+  /**
+   * Whether the style draws a light or a dark map.
+   *
+   * Overlays that are drawn on top of the style — places, routes, waypoint labels, the pin
+   * sprite — pick their colours from this, so that their text stays legible on the canvas
+   * underneath. {@link TomTomMap.styleLightDarkTheme} reports the value in effect.
+   *
+   * Leave it out and the SDK reads the theme off the loaded style, from the colour its
+   * `background` layer paints the canvas with. Set it when that guess is wrong or when you
+   * would rather not depend on a guess: a style whose canvas is hidden behind full-coverage
+   * imagery, or one whose background colour does not represent what the map ends up looking
+   * like.
+   *
+   * @default Read from the background colour of the loaded style, falling back to `'light'`
+   *
+   * @example
+   * ```typescript
+   * style: { type: 'custom', url: 'https://example.com/midnight.json', lightDarkTheme: 'dark' }
+   * ```
+   */
+  lightDarkTheme?: LightDark;
 };
 /**
  * Array of all available style modules.
@@ -618,21 +648,77 @@ export type StyleChangeHandler = {
    *
    * @remarks
    * Use this to perform cleanup or save state before the current style is removed.
-   * This method can be synchronous or asynchronous.
+   * This method can be synchronous or asynchronous: the SDK awaits it before handing the new
+   * style to MapLibre, so nothing of the old style is torn down while it runs.
    *
+   * @param context - What kind of switch is happening; see {@link StyleChangeContext}.
    * @returns void or a Promise that resolves when preparation is complete
    */
-  onStyleAboutToChange?: () => void | Promise<void>;
+  onStyleAboutToChange?: (context: StyleChangeContext) => void | Promise<void>;
   /**
    * Callback invoked after a new style has been fully loaded.
    *
    * @remarks
    * Use this to restore state, reinitialize layers, or perform other setup
-   * that depends on the new style being ready. This method can be synchronous or asynchronous.
+   * that depends on the new style being ready. This method can be synchronous or asynchronous:
+   * handlers run one after the other, in registration order, and the promise returned by
+   * {@link TomTomMap.setStyle} resolves only once the last one has finished.
    *
+   * @param context - What kind of switch is happening; see {@link StyleChangeContext}.
    * @returns void or a Promise that resolves when reinitialization is complete
    */
-  onStyleChanged?: () => void | Promise<void>;
+  onStyleChanged?: (context: StyleChangeContext) => void | Promise<void>;
+};
+/**
+ * What a {@link StyleChangeHandler} is told about the style switch it is reacting to.
+ *
+ * @remarks
+ * The SDK's own modules read `resetState` to decide between restoring themselves (data, config,
+ * filters) onto the new style, or re-binding to it with defaults and nothing shown. Your handlers
+ * get the same information, so a custom overlay can make the same choice.
+ *
+ * @example
+ * ```typescript
+ * map.addStyleChangeHandler({
+ *   onStyleChanged: ({ resetState }) => {
+ *     if (resetState) dropCustomLayers();
+ *     else reattachCustomLayers();
+ *   },
+ * });
+ * ```
+ *
+ * @group Map Style
+ */
+export type StyleChangeContext = {
+  /**
+   * `true` for a clean switch (`setStyle(style, { resetState: true })`), `false` when the switch
+   * carries SDK state over (`setStyle(style)` or `setStyle(style, { resetState: false })`).
+   */
+  resetState: boolean;
+};
+/**
+ * Options accepted by {@link TomTomMap.setStyle}.
+ *
+ * @group Map Style
+ */
+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.
+   * - `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.
+   *
+   * The map language is not SDK state: it is re-applied in both cases, and only
+   * {@link TomTomMap.setLanguage} changes it.
+   *
+   * Registered {@link StyleChangeHandler}s run in both cases and receive the value in their
+   * {@link StyleChangeContext}.
+   *
+   * @default false
+   */
+  resetState?: boolean;
 };
 /**
  * Main TomTom Map class for displaying interactive maps in web applications.
@@ -754,7 +840,7 @@ export declare class TomTomMap {
    * });
    * ```
    *
-   * @see {@link https://maplibre.org/maplibre-gl-js-docs/api/map/ | MapLibre Map Documentation}
+   * @see {@link https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/ | MapLibre Map Documentation}
    */
   readonly mapLibreMap: Map;
   /**
@@ -765,8 +851,32 @@ export declare class TomTomMap {
    * @ignore
    */
   _params: InternalTomTomMapParams;
-  styleLightDarkTheme: LightDark;
+  /**
+   * Whether the loaded style draws a light or a dark map.
+   *
+   * @remarks
+   * The SDK's own overlays read it to pick text and halo colours that stay legible over the
+   * base map, and it is the property to bind your own UI to rather than parsing the style ID.
+   *
+   * A standard style is classified from its ID. A custom style reads `'light'` until it has
+   * loaded — nothing about it is known before that — and is then classified from the colour its
+   * `background` layer paints the canvas with; a custom style with no readable background colour
+   * stays `'light'`. So read it inside an
+   * {@link TomTomMap.addStyleChangeHandler | onStyleChanged} handler, or after awaiting
+   * {@link setStyle}, rather than right after calling it.
+   *
+   * @example
+   * ```typescript
+   * await map.setStyle({ type: 'custom', url: 'https://example.com/my-style.json' });
+   * document.body.classList.toggle('dark-mode', map.styleLightDarkTheme === 'dark');
+   * ```
+   */
+  get styleLightDarkTheme(): LightDark;
+  private _styleLightDarkTheme;
   private readonly styleChangeHandlers;
+  private styleGivenToMapLibre;
+  private styleRequestSequence;
+  private styleLoadInFlight;
   /**
    * Constructs a new TomTom Map instance and attaches it to a DOM element.
    *
@@ -830,9 +940,9 @@ export declare class TomTomMap {
    *
    * @see {@link MapLibreOptions}
    * @see {@link TomTomMapParams}
-   * @see {@link https://maplibre.org/maplibre-gl-js-docs/api/map/ | MapLibre Map Parameters}
+   * @see {@link https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/ | MapLibre Map Parameters}
    * @see [Map Quickstart Guide](https://docs.tomtom.com/maps-sdk-js/guides/map/quickstart)
-   * @see [Map Styles Guide](https://docs.tomtom.com/maps-sdk-js/guides/map/map-styles)
+   * @see [Map Styles Guide](https://docs.tomtom.com/maps-sdk-js/guides/map/styles)
    * @see [User Interaction Events Guide](https://docs.tomtom.com/maps-sdk-js/guides/map/user-events)
    */
   constructor(mapParams: TomTomMapParams);
@@ -845,27 +955,35 @@ export declare class TomTomMap {
    * Changes the map style dynamically without reloading the entire map.
    *
    * @param style - The new style to apply. Can be a string ID or a detailed style configuration.
-   * @param options - Configuration options for the style change behavior.
-   * @param options.keepState - Whether to preserve SDK-rendered items and configurations when changing styles.
-   * When `true` (default), maintains traffic layers, routes, markers, and other SDK features.
-   * When `false`, performs a clean style switch without preserving previous state.
+   * @param options - Configuration options for the style change behavior, see {@link SetStyleOptions}.
+   * @returns A promise that resolves once the new style is loaded and every registered
+   * {@link StyleChangeHandler} has finished — including the SDK modules restoring themselves.
+   * Awaiting it is optional; it is the moment after which the map is safe to read and draw on again.
+   * @throws If the style itself fails to load, leaving {@link mapReady} `false` and the map on
+   * the style it had. A tile or source that fails to load does not fail the switch.
    *
    * @remarks
-   * **Behavior:**
-   * - Temporarily sets {@link mapReady} to `false` during the transition
-   * - Triggers all registered {@link StyleChangeHandler} callbacks
-   * - Resets {@link mapReady} to `true` when the new style is fully loaded
-   *
-   * **State Preservation (keepState: true):**
+   * **Carried-over state (the default):**
    * - Merges style parts from the previous style with the new one
-   * - Maintains SDK module layers (traffic, routes, POIs, etc.)
-   * - Preserves language settings
+   * - Restores SDK module data and configuration (traffic, routes, POIs, etc.)
    *
-   * **Clean Switch (keepState: false):**
-   * - Applies the new style without merging previous configuration
-   * - Removes all SDK module layers
+   * **Clean switch (resetState: true):**
+   * - Applies exactly the style you passed, without merging previous style parts
+   * - SDK modules re-bind to the new style with default configuration and nothing shown
    * - Useful for complete style resets
    *
+   * Both keep the map language: it is configuration, not state, and it survives every style
+   * change until {@link setLanguage} changes it.
+   *
+   * **Behavior:**
+   * - Sets {@link mapReady} to `false` for the duration of the transition
+   * - Awaits every `onStyleAboutToChange` handler, then hands the new style to MapLibre
+   * - Once the style has loaded, sets {@link mapReady} back to `true` and awaits every
+   *   `onStyleChanged` handler in registration order
+   * - A `setStyle` call made while another one is still in flight supersedes it: the older
+   *   call's style is never applied and its promise resolves as soon as that is known
+   * - Passing the style already loaded runs the whole lifecycle without reloading it, which is
+   *   how `resetState: true` doubles as a reset of the SDK modules over the current style
    * @example
    * Simple style change:
    * ```typescript
@@ -874,6 +992,13 @@ export declare class TomTomMap {
    * ```
    *
    * @example
+   * Wait for the switch to complete before drawing on the map:
+   * ```typescript
+   * await map.setStyle('standardDark');
+   * // modules have restored themselves; map.mapReady is true again
+   * ```
+   *
+   * @example
    * Style change with detailed configuration:
    * ```typescript
    * map.setStyle({
@@ -887,7 +1012,7 @@ export declare class TomTomMap {
    * Clean style switch without state preservation:
    * ```typescript
    * // Complete reset - removes all SDK layers and modules
-   * map.setStyle('standardDark', { keepState: false });
+   * map.setStyle('standardDark', { resetState: true });
    * ```
    *
    * @example
@@ -908,11 +1033,13 @@ 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 [Map Styles Guide](https://docs.tomtom.com/maps-sdk-js/guides/map/map-styles)
+   * @see [Map Styles Guide](https://docs.tomtom.com/maps-sdk-js/guides/map/styles)
    */
-  setStyle: (style: StyleInput, options?: {
-    keepState?: boolean;
-  }) => void;
+  setStyle: (style: StyleInput, options?: SetStyleOptions) => Promise<void>;
+  private applyStyle;
+  private loadIntoMapLibre;
+  private isSuperseded;
+  private notifyHandlers;
   /**
    * Retrieves the current style configuration of the map.
    *
@@ -986,7 +1113,9 @@ export declare class TomTomMap {
    * - When using locale codes (with `-`), only the language portion is used for labels
    *
    * **Persistence:**
-   * - Language setting persists across style changes (when `keepState: true`)
+   * - The language persists across every style change, a clean switch
+   *   ({@link SetStyleOptions.resetState}) included: it is map configuration rather than SDK
+   *   state, and this method is the only thing that changes it
    * - Set during initialization via {@link TomTomMapParams.language} for immediate application
    *
    * @example
@@ -1022,7 +1151,7 @@ export declare class TomTomMap {
   /**
    * Retrieves the current visible map area as a GeoJSON bounding box.
    *
-   * @returns A {@link https://tools.ietf.org/html/rfc7946#section-5 | GeoJSON BBox} array
+   * @returns A {@link https://datatracker.ietf.org/doc/html/rfc7946#section-5 | GeoJSON BBox} array
    * in the format `[west, south, east, north]` representing the map's current viewport bounds.
    *
    * @remarks
@@ -1063,8 +1192,8 @@ export declare class TomTomMap {
    * map.mapLibreMap.fitBounds([[west, south], [east, north]]);
    * ```
    *
-   * @see {@link https://tools.ietf.org/html/rfc7946#section-5 | GeoJSON BBox Specification}
-   * @see {@link https://maplibre.org/maplibre-gl-js-docs/api/geography/#lnglatbounds | MapLibre LngLatBounds}
+   * @see {@link https://datatracker.ietf.org/doc/html/rfc7946#section-5 | GeoJSON BBox Specification}
+   * @see {@link https://maplibre.org/maplibre-gl-js/docs/API/classes/LngLatBounds/ | MapLibre LngLatBounds}
    */
   getBBox(): BBox;
   private handleStyleData;
@@ -1092,13 +1221,16 @@ export declare class TomTomMap {
    *
    * **Multiple Handlers:**
    * - Multiple handlers can be registered and will all be called in registration order
+   * - Async callbacks are awaited one after the other; the promise returned by {@link setStyle}
+   *   resolves once the last one has finished
    * - Each handler's errors are caught independently and logged to the console
    * - One failing handler won't prevent others from executing
    *
    * **Important Notes:**
    * - Handlers are only triggered by {@link setStyle} calls, not initial map construction
-   * - Only called when `keepState: true` in {@link setStyle} options
-   * - Handlers persist for the lifetime of the TomTomMap instance
+   * - Handlers run for a clean switch as well as for one that carries state over, and receive
+   *   which one it is in their {@link StyleChangeContext}
+   * - Handlers persist for the lifetime of the TomTomMap instance unless unsubscribed
    *
    * @example
    * Basic usage:
@@ -1257,8 +1389,10 @@ export declare class TomTomMap {
  * the corresponding reference layers in the new style, maintaining the intended visual hierarchy.
  *
  * **Important Notes:**
- * - `lowestBuilding` is not available in the Satellite style
- * - If a reference layer doesn't exist, custom layers will be added on top of the style
+ * - `lowestRoadLine` and `lowestBuilding` are not available in the Satellite style
+ * - If a reference layer doesn't exist, a module repositioning its layers puts them on top of the
+ *   style instead. A layer added with a `beforeID` that never appears is reported through
+ *   `console.error` and skipped, since a missing anchor there is usually a typo.
  * - Both RoutingModule and GeometriesModule default to `lowestLabel` for optimal visibility
  *
  * @see {@link GeometryBeforeLayerConfig} for GeometriesModule layer positioning options
@@ -1312,6 +1446,8 @@ export declare const mapStyleLayerIDs: {
    * Represents tunnel railway outlines. Use to position content below the road network,
    * useful for showing base layers or features that should appear beneath transportation
    * infrastructure.
+   *
+   * **Note:** Not available in the Satellite style.
    */
   readonly lowestRoadLine: "Tunnel - Railway outline";
   /**
@@ -1715,6 +1851,20 @@ type SourceWithLayers = StyleSourceWithLayers | GeoJSONSourceWithLayers;
 type SourcesWithLayers = {
   [name: string]: SourceWithLayers;
 };
+/**
+ * The sources a style-owned module controls, keyed by the name the module gives them.
+ * @ignore
+ */
+type StyleSourcesWithLayers = {
+  [name: string]: StyleSourceWithLayers;
+};
+/**
+ * The sources a data-owned module adds and owns, keyed by the name the module gives them.
+ * @ignore
+ */
+type GeoJSONSourcesWithLayers = {
+  [name: string]: GeoJSONSourceWithLayers;
+};
 /**
  * Contains the IDs of a source and its related layers.
  *
@@ -2455,6 +2605,46 @@ type CustomImage<I extends string = string> = {
    * ```
    */
   availabilityLevel?: AvailabilityLevel;
+  /**
+   * Horizontal offset of the icon from its anchor point, in pixels.
+   *
+   * @remarks
+   * Positive values shift the icon right, negative values shift it left.
+   * The offset is applied before `icon-size` scaling, matching the
+   * MapLibre `icon-offset` convention.
+   *
+   * Only takes effect when `image` is also provided — an icon referencing an
+   * existing sprite icon by `id` alone ignores `offsetX`/`offsetY`.
+   *
+   * @default 0
+   *
+   * @example
+   * ```typescript
+   * // Shift the icon 10px to the right of its coordinate
+   * offsetX: 10
+   * ```
+   */
+  offsetX?: number;
+  /**
+   * Vertical offset of the icon from its anchor point, in pixels.
+   *
+   * @remarks
+   * Positive values shift the icon down, negative values shift it up.
+   * The offset is applied before `icon-size` scaling, matching the
+   * MapLibre `icon-offset` convention.
+   *
+   * Only takes effect when `image` is also provided — an icon referencing an
+   * existing sprite icon by `id` alone ignores `offsetX`/`offsetY`.
+   *
+   * @default 0
+   *
+   * @example
+   * ```typescript
+   * // Shift the icon 10px above its coordinate
+   * offsetY: -10
+   * ```
+   */
+  offsetY?: number;
 };
 /**
  * Options to style SDK SVG icons with custom colors and opacity.
@@ -2484,25 +2674,6 @@ type SVGIconStyleOptions = {
   outlineOpacity?: number;
 };
 //#endregion
-//#region src/shared/types/mapLibreUtils.d.ts
-/**
- * @ignore
- */
-type FilterSyntaxVersion = 'expression' | 'legacy';
-/**
- * @ignore
- */
-type MultiSyntaxFilter = {
-  /**
-   * Filter expression following the new expression syntax.
-   */
-  expression: ExpressionFilterSpecification;
-  /**
-   * Filter expression following the legacy syntax.
-   */
-  legacy: LegacyFilterSpecification;
-};
-//#endregion
 //#region src/shared/types/mapModule.d.ts
 /**
  * Contains configuration options common to all map modules.
@@ -2516,15 +2687,6 @@ type MapModuleCommonConfig = {
   events?: EventHandlerConfig;
 };
 //#endregion
-//#region src/shared/types/style.d.ts
-/**
- * Indicator of a light or dark theme.
- * * Can be used to classify a map style as light or dark, or to apply light or dark configurations to map modules if they support it.
- *
- * @group Map Style
- */
-type LightDark = 'light' | 'dark';
-//#endregion
 //#region src/shared/eventScope.d.ts
 /**
  * What `where()` accepts: a predicate over the feature type this surface exposes, or — where the
@@ -3461,10 +3623,6 @@ type EventScopeOptions<T, WHERE_SCOPE> = {
   /** Resolves a module-specific scope object, such as BaseMapModule's `{ layerGroups }`. */
   scopeResolver?: (scope: WHERE_SCOPE) => ResolvedEventScope;
 };
-/**
- * Whether a map module is based on a map style or on added GeoJSON data.
- */
-type MapModuleSource = 'style' | 'geojson';
 /**
  * Base class for all Maps SDK map modules.
  *
@@ -3477,22 +3635,23 @@ type MapModuleSource = 'style' | 'geojson';
  * The class manages the module's sources, layers, and configuration, automatically
  * handling map style changes by restoring the module's state when needed.
  *
- * The `sourceType` a module passes up says who owns the sources and layers it controls, and
- * therefore how its instances behave:
+ * No module extends this class directly. Each one extends the subclass that says who owns the
+ * sources and layers it controls, and therefore how its instances behave:
  *
- * - `'geojson'` — the module adds and owns its own sources, layers and images, suffixed per
- *   instance. Multi-instance, built with `create(map, config?)`.
- * - `'style'` — the module controls sources and layers the map style already provides, under fixed
- *   global IDs. A shared controller, obtained with `get(map, config?)`.
+ * - {@link AbstractDataOwnedMapModule} — the module adds and owns its own sources, layers and
+ *   images, suffixed per instance. Multi-instance, built with `create(map, config?)`.
+ * - {@link AbstractStyleOwnedMapModule} — the module controls sources and layers the map style
+ *   already provides, under fixed global IDs. A shared controller, obtained with
+ *   `get(map, config?)`.
  *
  * @typeParam SOURCES_WITH_LAYERS - The type defining the sources and layers used by this module
  * @typeParam CFG - The configuration type for this module, or undefined if no configuration is needed. When defined, must extend MapModuleCommonConfig.
  *
  * @example
  * ```typescript
- * class CustomModule extends AbstractMapModule<MySourcesWithLayers, MyConfig> {
+ * class CustomModule extends AbstractDataOwnedMapModule<MySourcesWithLayers, MyConfig> {
  *   constructor(tomtomMap: TomTomMap, config?: MyConfig) {
- *     super('geojson', tomtomMap, config);
+ *     super(tomtomMap, config);
  *   }
  *   // Implement abstract methods...
  * }
@@ -3501,7 +3660,6 @@ type MapModuleSource = 'style' | 'geojson';
  * @group Shared
  */
 export declare abstract class AbstractMapModule<SOURCES_WITH_LAYERS extends SourcesWithLayers, CFG extends MapModuleCommonConfig | undefined = undefined> {
-  private readonly sourceType;
   /**
    * @ignore
    */
@@ -3542,6 +3700,10 @@ export declare abstract class AbstractMapModule<SOURCES_WITH_LAYERS extends Sour
    * has its own counter without per-subclass boilerplate. Use as a suffix on
    * auto-generated source and layer IDs to keep them stable across style changes and
    * unique across module instances.
+   *
+   * Only the data-owned modules need it, because the style-owned ones work under fixed global
+   * IDs. It is assigned here all the same: this constructor already runs
+   * `_initSourcesWithLayers`, which reads it, so a subclass field would be assigned too late.
    * @ignore
    */
   protected readonly instanceIndex: number;
@@ -3560,10 +3722,9 @@ export declare abstract class AbstractMapModule<SOURCES_WITH_LAYERS extends Sour
    * Builds this module based on a given Maps SDK map.
    * @param tomtomMap The map. It may or may not be initialized at this stage,
    * but the module ensures to initialize itself once it is.
-   * @param sourceType Whether the module is based on a map style or on added GeoJSON data.
    * @param config Optional configuration to initialize directly as soon as the map is ready.
    */
-  protected constructor(sourceType: MapModuleSource, tomtomMap: TomTomMap, config?: CFG);
+  protected constructor(tomtomMap: TomTomMap, config?: CFG);
   /**
    * Initializes the sources with layers of this module.
    * @param config The optional configuration for the module.
@@ -3650,6 +3811,19 @@ export declare abstract class AbstractMapModule<SOURCES_WITH_LAYERS extends Sour
    */
   resetConfig(): void;
   private restoreDataAndConfig;
+  private resetOnNewStyle;
+  /**
+   * Forgets whatever this module remembers beyond its configuration, so that a clean style
+   * switch does not bring it back. The sources are rebuilt empty right after, so there is
+   * nothing to clear on the map.
+   *
+   * A data-owned module always remembers something, so {@link AbstractDataOwnedMapModule} makes
+   * this abstract. A style-owned module overrides it only when it keeps state of its own, such
+   * as raw layer edits.
+   * @protected
+   * @ignore
+   */
+  protected discardShownData(): void;
   /**
    * implementation needed to restore the module state (data and config applied to the module).
    * to be used to restore module state after map style change
@@ -3770,7 +3944,174 @@ 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/AbstractDataOwnedMapModule.d.ts
+/**
+ * Base class for the map modules that add and own their own GeoJSON sources, layers and images:
+ * places, routes, geometries, the traffic overlays and bring-your-own-data.
+ *
+ * @remarks
+ * The module owns the data it draws. Its generated IDs therefore carry a per-instance suffix
+ * (see `instanceIndex`), and the module is safely multi-instance: every `create(map, config?)`
+ * call returns another module with its own sources and layers.
+ *
+ * Owning the data brings the duty this class states: a clean style switch must forget the data
+ * the module remembers having shown, through {@link discardShownData}.
+ *
+ * @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
+ *
+ * @group Shared
+ */
+export declare abstract class AbstractDataOwnedMapModule<SOURCES_WITH_LAYERS extends GeoJSONSourcesWithLayers, CFG extends MapModuleCommonConfig | undefined = undefined> extends AbstractMapModule<SOURCES_WITH_LAYERS, CFG> {
+  /**
+   * 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
+   * implements this as a no-op, and says why.
+   * @protected
+   * @ignore
+   */
+  protected abstract discardShownData(): void;
+}
+//#endregion
+//#region src/shared/AbstractStyleOwnedMapModule.d.ts
+/**
+ * Base class for the map modules that control sources and layers the loaded map style already
+ * provides, under fixed global IDs: the base map, POIs, the traffic tiles and hillshade.
+ *
+ * @remarks
+ * The style owns the data, so such a module adds no sources of its own and shows nothing by
+ * itself. It changes how the parts the style provides are drawn, filtered and made visible.
+ * The SDK memoizes one instance per map, obtained with `get(map, config?)`, so every handle on it
+ * sees the same state.
+ *
+ * Because those sources and layers arrive with the style, they are in place as soon as the new
+ * style is loaded, and the module re-binds to them in the same tick. That is what the base class
+ * already does, so this class adds no behaviour: it names the kind, and it narrows the sources a
+ * module of this kind can hold.
+ *
+ * @typeParam SOURCES_WITH_LAYERS - The style sources, with their layers, this module controls
+ * @typeParam CFG - The configuration type for this module, or undefined if no configuration is needed
+ *
+ * @group Shared
+ */
+export declare abstract class AbstractStyleOwnedMapModule<SOURCES_WITH_LAYERS extends StyleSourcesWithLayers, CFG extends MapModuleCommonConfig | undefined = undefined> extends AbstractMapModule<SOURCES_WITH_LAYERS, CFG> {}
+//#endregion
 //#region src/shared/layers/commonLayerProps.d.ts
+/**
+ * Bold font face used in the TomTom map style.
+ *
+ * @remarks
+ * This is the primary bold font used for prominent labels and headings in the map.
+ * Use this constant when creating custom layers to maintain visual consistency with the map style.
+ *
+ * @example
+ * ```typescript
+ * import { MAP_BOLD_FONT } from '@tomtom-org/maps-sdk/map';
+ *
+ * const textLayer = {
+ *   type: 'symbol',
+ *   layout: {
+ *     'text-font': [MAP_BOLD_FONT],
+ *     'text-field': ['get', 'name']
+ *   }
+ * };
+ * ```
+ *
+ * @group Map Style
+ */
+export declare const MAP_BOLD_FONT = "Noto-Bold";
+/**
+ * Regular font face used in the TomTom map style.
+ *
+ * @remarks
+ * This is the standard font used for most text labels on the map.
+ * Use this constant when creating custom layers to maintain visual consistency with the map style.
+ *
+ * @example
+ * ```typescript
+ * import { MAP_REGULAR_FONT } from '@tomtom-org/maps-sdk/map';
+ *
+ * const textLayer = {
+ *   type: 'symbol',
+ *   layout: {
+ *     'text-font': [MAP_REGULAR_FONT],
+ *     'text-field': ['get', 'description']
+ *   }
+ * };
+ * ```
+ *
+ * @group Map Style
+ */
+export declare const MAP_REGULAR_FONT = "Noto-Regular";
+/**
+ * Medium weight font face used in the TomTom map style.
+ *
+ * @remarks
+ * This font provides a middle ground between regular and bold weights.
+ * Use this constant when creating custom layers to maintain visual consistency with the map style.
+ *
+ * @example
+ * ```typescript
+ * import { MAP_MEDIUM_FONT } from '@tomtom-org/maps-sdk/map';
+ *
+ * const textLayer = {
+ *   type: 'symbol',
+ *   layout: {
+ *     'text-font': [MAP_MEDIUM_FONT],
+ *     'text-field': ['get', 'title']
+ *   }
+ * };
+ * ```
+ *
+ * @group Map Style
+ */
+export declare const MAP_MEDIUM_FONT = "Noto-Medium";
+/**
+ * Italic font face used in the TomTom map style.
+ *
+ * @remarks
+ * This is the italic variant used for emphasized or secondary text labels.
+ * Use this constant when creating custom layers to maintain visual consistency with the map style.
+ *
+ * @example
+ * ```typescript
+ * import { MAP_ITALIC_FONT } from '@tomtom-org/maps-sdk/map';
+ *
+ * const textLayer = {
+ *   type: 'symbol',
+ *   layout: {
+ *     'text-font': [MAP_ITALIC_FONT],
+ *     'text-field': ['get', 'subtitle']
+ *   }
+ * };
+ * ```
+ *
+ * @group Map Style
+ */
+export declare const MAP_ITALIC_FONT = "NotoSans-MediumItalic";
+/**
+ * Default text size expression used in the TomTom map style.
+ *
+ * @remarks
+ * This MapLibre expression defines zoom-dependent text sizing that scales from 12px at zoom 10
+ * to 14px at zoom 16. Use this for consistent text sizing across zoom levels.
+ *
+ * @example
+ * ```typescript
+ * import { DEFAULT_TEXT_SIZE } from '@tomtom-org/maps-sdk/map';
+ *
+ * const textLayer = {
+ *   type: 'symbol',
+ *   layout: {
+ *     'text-size': DEFAULT_TEXT_SIZE,
+ *     'text-field': ['get', 'name']
+ *   }
+ * };
+ * ```
+ *
+ * @group Map Style
+ */
+export declare const DEFAULT_TEXT_SIZE: ExpressionSpecification;
 /**
  * Array of all available font faces in the TomTom map style.
  *
@@ -3798,7 +4139,7 @@ export declare abstract class AbstractMapModule<SOURCES_WITH_LAYERS extends Sour
  *
  * @group Map Style
  */
-declare const mapFonts: readonly ["Noto-Regular", "NotoSans-MediumItalic", "Noto-Bold", "Noto-Medium"];
+export declare const mapFonts: readonly ["Noto-Regular", "NotoSans-MediumItalic", "Noto-Bold", "Noto-Medium"];
 /**
  * Type representing valid font faces available in the TomTom map style.
  *
@@ -4251,11 +4592,11 @@ export type BaseMapEvents = CombinedEvents<MapGeoJSONFeature, BaseMapModuleConfi
  * ```
  *
  * @see [Base Map Guide](https://docs.tomtom.com/maps-sdk-js/guides/map/base-map)
- * @see [Map Styles Guide](https://docs.tomtom.com/maps-sdk-js/guides/map/map-styles)
+ * @see [Map Styles Guide](https://docs.tomtom.com/maps-sdk-js/guides/map/styles)
  *
  * @group Base Map
  */
-export declare class BaseMapModule extends AbstractMapModule<BaseSourceAndLayers, BaseMapModuleConfig> {
+export declare class BaseMapModule extends AbstractStyleOwnedMapModule<BaseSourceAndLayers, BaseMapModuleConfig> {
   private layersByGroup?;
   /**
    * Asynchronously retrieves a BaseMapModule instance for the given map.
@@ -4723,7 +5064,7 @@ export type CustomGeoJSONEvents<TSources extends Record<string, FeatureCollectio
  *
  * @group Custom
  */
-export declare class CustomGeoJSONModule<TSources extends Record<string, FeatureCollection> = Record<string, FeatureCollection>> extends AbstractMapModule<CustomGeoJSONSourcesWithLayers<TSources>, CustomGeoJSONModuleConfig<TSources>> {
+export declare class CustomGeoJSONModule<TSources extends Record<string, FeatureCollection> = Record<string, FeatureCollection>> extends AbstractDataOwnedMapModule<CustomGeoJSONSourcesWithLayers<TSources>, CustomGeoJSONModuleConfig<TSources>> {
   private resolvedSourceIDs;
   private resolvedLayerSpecs;
   private lastShown;
@@ -4754,6 +5095,10 @@ export declare class CustomGeoJSONModule<TSources extends Record<string, Feature
   protected _applyConfig(config: CustomGeoJSONModuleConfig<TSources> | undefined): CustomGeoJSONModuleConfig<TSources> | undefined;
   private updateLayersForExistingSources;
   private applyVisibility;
+  /**
+   * @ignore
+   */
+  protected discardShownData(): void;
   /**
    * @ignore
    */
@@ -4834,6 +5179,13 @@ export declare const colorPalettes: {
 };
 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/geometryTheme.d.ts
 /**
@@ -4883,6 +5235,10 @@ export type GeometryFillConfig = {
    * Fill color: a hex string (`'#FF5733'`), a palette name (`'blues'`, see {@link colorPaletteIDs}), or a MapLibre expression
    * for data-driven styling (e.g. `['get', 'color']`).
    *
+   * @remarks
+   * When unset the default is theme-adaptive: `'#0A3653'` on light map styles, `'#5FA8D8'` on dark.
+   * Custom styles are treated as light — pass a colour explicitly on a dark custom style.
+   *
    * @default '#0A3653'
    */
   color?: ColorPaletteOptions | DataDrivenPropertyValueSpecification<string>;
@@ -4972,6 +5328,9 @@ export type GeometryLineConfig = {
   /**
    * Border/outline color: a hex string or a MapLibre expression (e.g. `['get', 'borderColor']`).
    *
+   * @remarks
+   * When unset the default is theme-adaptive: `'#0A3653'` on light map styles, `'#5FA8D8'` on dark.
+   *
    * @default '#0A3653'
    */
   color?: DataDrivenPropertyValueSpecification<string>;
@@ -5064,6 +5423,9 @@ export type GeometryLineLabelConfig = {
   /**
    * Color of the border label text.
    *
+   * @remarks
+   * When unset the default is theme-adaptive: `'#333333'` on light map styles, `'#FFFFFF'` on dark.
+   *
    * @default '#333333'
    *
    * @example
@@ -5078,6 +5440,9 @@ export type GeometryLineLabelConfig = {
    *
    * The halo improves legibility against complex or dark backgrounds.
    *
+   * @remarks
+   * When unset the default is theme-adaptive: `'#FFFFFF'` on light map styles, `'#333333'` on dark.
+   *
    * @default '#FFFFFF'
    *
    * @example
@@ -5430,7 +5795,7 @@ export type GeometriesEvents = CombinedEvents<MapGeoJSONFeature, GeometriesModul
  *
  * @group Geometries
  */
-export declare class GeometriesModule extends AbstractMapModule<GeometrySourcesWithLayers, GeometriesModuleConfig> {
+export declare class GeometriesModule extends AbstractDataOwnedMapModule<GeometrySourcesWithLayers, GeometriesModuleConfig> {
   private titleLayerSpecs;
   private geometryFillLayerSpecs;
   private geometryOutlineLayerSpecs;
@@ -5501,6 +5866,14 @@ export declare class GeometriesModule extends AbstractMapModule<GeometrySourcesW
    */
   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();
+  /**
+   * Default fill / plain-outline colour a feature falls back to when it carries no `color`.
+   * Resolved from the active theme; once the styling module ships this also reads the map's
+   * published accent (`mapAccentColor(this.tomtomMap) ?? …`).
+   */
+  private get defaultColor();
   /**
    * @ignore
    */
@@ -5571,6 +5944,10 @@ export declare class GeometriesModule extends AbstractMapModule<GeometrySourcesW
    */
   applyTextConfig(textConfig: GeometryTextConfig): void;
   private updateLayerAndData;
+  /**
+   * @ignore
+   */
+  protected discardShownData(): void;
   /**
    * @ignore
    */
@@ -5974,7 +6351,7 @@ type HillshadeSourcesWithLayers = {
  *
  * @group Hillshade
  */
-export declare class HillshadeModule extends AbstractMapModule<HillshadeSourcesWithLayers, HillshadeModuleConfig> {
+export declare class HillshadeModule extends AbstractStyleOwnedMapModule<HillshadeSourcesWithLayers, HillshadeModuleConfig> {
   /**
    * Retrieves a HillshadeModule instance for the given map.
    *
@@ -7161,7 +7538,7 @@ export type PlacesEvents = CombinedEvents<MapGeoJSONFeature, PlacesModuleConfig,
  *
  * @group Places
  */
-export declare class PlacesModule extends AbstractMapModule<PlacesSourcesAndLayers, PlacesModuleConfig> {
+export declare class PlacesModule extends AbstractDataOwnedMapModule<PlacesSourcesAndLayers, PlacesModuleConfig> {
   private layerSpecs;
   private connectionLayerSpecs;
   private currentClusterMode;
@@ -7197,6 +7574,10 @@ export declare class PlacesModule extends AbstractMapModule<PlacesSourcesAndLaye
    * @ignore
    */
   protected _applyConfig(config: PlacesModuleConfig | undefined): PlacesModuleConfig | undefined;
+  /**
+   * @ignore
+   */
+  protected discardShownData(): void;
   /**
    * @ignore
    */
@@ -7929,7 +8310,7 @@ type PoIsSourcesAndLayers = {
  *
  * @group POIs
  */
-export declare class POIsModule extends AbstractMapModule<PoIsSourcesAndLayers, POIsModuleConfig> {
+export declare class POIsModule extends AbstractStyleOwnedMapModule<PoIsSourcesAndLayers, POIsModuleConfig> {
   private categoriesFilter?;
   private originalFilter?;
   /**
@@ -8290,24 +8671,26 @@ type RouteLayersConfig = {
       routeIncidentDashedLine?: Partial<ToBeAddedLayerSpecTemplate<LineLayerSpecification>>;
     } & HasAdditionalLayersConfig;
     /**
-     * Toll road section layers.
+     * Layers for the `tollRoad` section type.
      *
      * @remarks
-     * Identifies route segments that require toll payments.
+     * Marks the stretches of the route that cost money to drive, by any charging scheme:
+     * per-use tolls, motorways that need a vignette, and urban road-charge zones.
      */
     tollRoad?: {
       /**
-       * Symbol layer for marking toll booths or toll segments.
+       * Symbol layer marking the charged stretches with an icon.
        *
        * @remarks
-       * Use for icons or markers indicating toll-related points along the route.
+       * Defaults to the toll-plaza icon, which is the closest the base-map sprite offers to
+       * a generic road-charge icon. Override it to distinguish the schemes yourself.
        */
       routeTollRoadSymbol?: Partial<ToBeAddedLayerSpecTemplate<SymbolLayerSpecification>>;
       /**
-       * Line layer used to outline toll road segments.
+       * Line layer used to outline the charged stretches.
        *
        * @remarks
-       * Typically styled to visually differentiate toll segments from regular roads.
+       * Typically styled to visually differentiate charged stretches from regular roads.
        */
       routeTollRoadOutline?: Partial<ToBeAddedLayerSpecTemplate<LineLayerSpecification>>;
     } & HasAdditionalLayersConfig;
@@ -8442,6 +8825,10 @@ type ChargingStopIconConfig = {
    * @remarks
    * These icons can be referenced in the `mapping` configuration to customize
    * the appearance of charging stop markers based on specific criteria.
+   *
+   * An entry's `offsetX`/`offsetY` shift that icon from the charging stop's coordinate.
+   * They only take effect when the same entry also provides an `image`; an entry naming an
+   * existing sprite icon by `id` alone ignores them.
    */
   customIcons?: CustomImage[];
   /**
@@ -9459,6 +9846,20 @@ export type WaypointDisplayProps = PlaceDisplayProps & {
    * ```
    */
   stopDisplayIndex?: number;
+  /**
+   * How long the route waits at this waypoint, formatted for display.
+   *
+   * @remarks
+   * Taken from {@link WaypointProps.pauseDurationSeconds} and rendered on the stop's label by
+   * default (e.g. `30 min`). Absent when the waypoint carries no wait. Charging-stop pins carry
+   * the same property, so both kinds of pin say how long you are there in the same words.
+   *
+   * @example
+   * ```typescript
+   * stopDuration: '30 min'
+   * ```
+   */
+  stopDuration?: string;
 };
 /**
  * @ignore
@@ -9627,7 +10028,7 @@ export type RoutingEvents = CombinedEvents<MapGeoJSONFeature, RoutingModuleConfi
  *
  * @group Routing
  */
-export declare class RoutingModule extends AbstractMapModule<RoutingSourcesWithLayers, RoutingModuleConfig> {
+export declare class RoutingModule extends AbstractDataOwnedMapModule<RoutingSourcesWithLayers, RoutingModuleConfig> {
   private layersSpecs;
   private layerIDPrefix;
   private readonly shownFeaturesHandlers;
@@ -9679,6 +10080,8 @@ export declare class RoutingModule extends AbstractMapModule<RoutingSourcesWithL
    * @ignore
    */
   protected _applyConfig(config?: RoutingModuleConfig): RoutingModuleConfig;
+  /** @ignore */
+  protected discardShownData(): void;
   /**
    * @ignore
    */
@@ -9705,7 +10108,7 @@ export declare class RoutingModule extends AbstractMapModule<RoutingSourcesWithL
    * **Route Features:**
    * - Main route lines (selected and deselected styles)
    * - Traffic sections with delays
-   * - Ferry, tunnel, and toll sections
+   * - Ferry, tunnel, and charged-road (`tollRoad`) sections
    * - EV charging stations (for EV routes)
    * - Turn-by-turn instruction lines and arrows
    * - Summary bubbles with distance/time/traffic info
@@ -9814,7 +10217,7 @@ export declare class RoutingModule extends AbstractMapModule<RoutingSourcesWithL
    * - `incidents`: Traffic incidents on routes
    * - `ferries`: Ferry sections
    * - `chargingStops`: EV charging stations
-   * - `tollRoads`: Toll road sections
+   * - `tollRoads`: Sections that cost money to drive — the `tollRoad` section type
    * - `tunnels`: Tunnel sections
    * - `vehicleRestricted`: Vehicle-restricted sections
    * - `instructionLines`: Turn-by-turn instruction lines
@@ -10124,9 +10527,13 @@ type AreaAnalyticsBeforeLayerConfig = {
  */
 type AreaAnalyticsRegionPolygonConfig = {
   /**
-   * Color used for both the fill and outline of the region boundary.
+   * CSS colour used for both the fill and outline of the region boundary.
    *
-   * @defaultValue '#000000'
+   * When omitted, a theme-adaptive default is used. Known standard styles are classified as
+   * light or dark; a custom style is treated as light, so set `color` explicitly if a custom
+   * style is dark.
+   *
+   * @defaultValue Black (`#000000`) on light styles, white (`#FFFFFF`) on dark styles
    */
   color?: string;
   /**
@@ -10246,9 +10653,11 @@ declare const AREA_ANALYTICS_DEFAULTS: {
       };
     };
   };
-  /** @see {@link AreaAnalyticsRegionPolygonConfig} */
+  /**
+   * @see {@link AreaAnalyticsRegionPolygonConfig}
+   * `color` is omitted — the layer builders apply a theme-adaptive default.
+   */
   regionPolygon: {
-    color: string;
     fillOpacity: number;
     outlineOpacity: number;
     outlineWidth: number;
@@ -10398,7 +10807,7 @@ type AreaAnalyticsSourcesWithLayers = {
  *
  * @group Traffic Area Analytics
  */
-export declare class TrafficAreaAnalyticsModule extends AbstractMapModule<AreaAnalyticsSourcesWithLayers, TrafficAreaAnalyticsConfig> {
+export declare class TrafficAreaAnalyticsModule extends AbstractDataOwnedMapModule<AreaAnalyticsSourcesWithLayers, TrafficAreaAnalyticsConfig> {
   private heatmapLayerSpec;
   private hexFillLayerSpec;
   private hexExtrusionLayerSpec;
@@ -10451,6 +10860,8 @@ export declare class TrafficAreaAnalyticsModule extends AbstractMapModule<AreaAn
   /** @ignore */
   protected _applyConfig(config: TrafficAreaAnalyticsConfig | undefined): TrafficAreaAnalyticsConfig | undefined;
   /** @ignore */
+  protected discardShownData(): void;
+  /** @ignore */
   protected restoreDataAndConfigImpl(): void;
   /**
    * Displays area analytics data on the map.
@@ -10612,6 +11023,7 @@ export declare class TrafficAreaAnalyticsModule extends AbstractMapModule<AreaAn
   get events(): CombinedEvents<AreaAnalyticsTileFeature, TrafficAreaAnalyticsConfig, TrafficAreaAnalytics>;
   private get mode();
   private get activeMetric();
+  private get lightDark();
   private applyModeVisibility;
   private hideAllDataLayers;
   private addHighlightLayersToMap;
@@ -10957,7 +11369,7 @@ type TrafficFlowSourcesWithLayers = {
  *
  * @group Traffic Flow
  */
-export declare class TrafficFlowModule extends AbstractMapModule<TrafficFlowSourcesWithLayers, FlowConfig> {
+export declare class TrafficFlowModule extends AbstractStyleOwnedMapModule<TrafficFlowSourcesWithLayers, FlowConfig> {
   private originalFilters;
   /**
    * Retrieves a TrafficFlowModule instance for the given map.
@@ -11159,7 +11571,9 @@ export declare class TrafficFlowModule extends AbstractMapModule<TrafficFlowSour
  */
 type IncidentFocusStyle = {
   /**
-   * Colour of the outline painted beneath the focused stripe. Defaults to `#000`.
+   * Colour of the outline painted beneath the focused stripe.
+   *
+   * @defaultValue `#000` on light map styles, `#FFF` on dark styles
    */
   outlineColor?: string;
   /**
@@ -11191,8 +11605,8 @@ type TrafficIncidentOverlayConfig = MapModuleCommonConfig & {
   /**
    * Visual treatment for {@link TrafficIncidentOverlayModule.setFocus}.
    *
-   * - Omit (or `undefined`) — use the SDK default treatment: a black outline
-   *   beneath the focused stripe and a `1.6×` width pop.
+   * - 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.
@@ -11230,8 +11644,9 @@ type Sources = {
  * ## Focus
  *
  * {@link setFocus} writes MapLibre feature-state `focused=true|false` on each rendered
- * incident. The default visual treatment widens the focused subset and paints a black
- * outline beneath it; unfocused incidents are unchanged. Override or disable the visual
+ * 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`.
@@ -11298,7 +11713,7 @@ type Sources = {
  *
  * @group Traffic
  */
-export declare class TrafficIncidentOverlayModule extends AbstractMapModule<Sources, TrafficIncidentOverlayConfig> {
+export declare class TrafficIncidentOverlayModule extends AbstractDataOwnedMapModule<Sources, TrafficIncidentOverlayConfig> {
   private lastResult;
   private lastFeatureIds;
   private lastFocusIds;
@@ -11322,6 +11737,8 @@ export declare class TrafficIncidentOverlayModule extends AbstractMapModule<Sour
   protected _applyConfig(config: TrafficIncidentOverlayConfig | undefined): TrafficIncidentOverlayConfig | undefined;
   private applyBeforeLayer;
   /** @ignore */
+  protected discardShownData(): void;
+  /** @ignore */
   protected restoreDataAndConfigImpl(): void;
   /**
    * Render the service result. Replaces any previously shown snapshot.
@@ -11360,7 +11777,7 @@ export declare class TrafficIncidentOverlayModule extends AbstractMapModule<Sour
    * Mark a subset of currently-rendered incidents as "focused" via MapLibre
    * feature-state. `null` clears the state. Paint expressions in
    * `incidentDetailsLayers.ts` read `['feature-state', 'focused']` and pop the
-   * focused subset (wider stripe + black outline). Unfocused features are
+   * focused subset (wider stripe + a theme-aware outline). Unfocused features are
    * unchanged — the focus treatment adds emphasis, it does not dim the rest.
    *
    * No effect if called before `show()`.
@@ -11706,7 +12123,7 @@ type TrafficIncidentsSourcesWithLayers = {
  *
  * @group Traffic Incidents
  */
-export declare class TrafficIncidentsModule extends AbstractMapModule<TrafficIncidentsSourcesWithLayers, IncidentsConfig> {
+export declare class TrafficIncidentsModule extends AbstractStyleOwnedMapModule<TrafficIncidentsSourcesWithLayers, IncidentsConfig> {
   private originalFilters;
   /**
    * Retrieves a TrafficIncidentsModule instance for the given map.
@@ -12031,4 +12448,4 @@ export declare const calculatePaddedCenter: (options: CalculateMapCenterOptions)
  */
 export declare const calculateFittingBBox: (options: CalculateFittingBBoxOptions) => BBox | null;
 //#endregion
-export type { AREA_ANALYTICS_DEFAULTS, AreaAnalyticsBeforeLayerConfig, AreaAnalyticsColorStop, AreaAnalyticsColorStopsConfig, AreaAnalyticsColorTheme, AreaAnalyticsDisplayMode, AreaAnalyticsHeightConfig, AreaAnalyticsMetricConfig, AreaAnalyticsMetricFilter, AreaAnalyticsRegionPolygonConfig, AreaAnalyticsValueType, AvailabilityLevel, BeforeLayerConfig, ByIdOrIndex, CSSCursor, ChargingSpeedIconMapping, ChargingStopIconConfig, ChargingStopIconMapping, ChargingStopTextConfig, ChargingStopsConfig, CleanEventStateOptions, CleanEventStatesOptions, ClickEventType, CustomImage, DefaultPlaceIconConfig, DisplayRouteProps, DisplayRouteRelatedProps, DisplayRouteSummaries, DisplayRouteSummary, DisplayRouteSummaryProps, EVAvailabilityConfig, EventHandlerConfig, EventHandlerCursorConfig, EventType, FilterShowMode, FilterSyntaxVersion, FilterablePOICategory, HasAdditionalLayersConfig, HasBeforeID, HillshadeModuleConfig, HoverEventType, IncidentFocusStyle, LayerSpecFilter, LayerSpecTemplate, LayerSpecWithSource, LightDark, MapEventsConfig, MapFont, MapModuleCommonConfig, MapStyleLayerID, MultiSyntaxFilter, POIsModuleConfig, POIsModuleFeature, PlaceConnectionDisplay, PlaceConnectionLayerName, PlaceConnectionsConfig, PlaceConnectionsLayersConfig, PlaceIconConfig, PlaceLayerName, PlaceLayersConfig, PlaceTextConfig, PlacesModuleConfig, PlacesTheme, PlanningWaypoint, PutEventStateOptions, RouteLayersConfig, RouteStateProps, RouteTheme, RouteWaypointSize, RouteWidth, RoutingModuleConfig, SVGIconStyleOptions, SourceWithLayerIDs, SourceWithLayers, SourcesWithLayers, SupportsEvents, SymbolLayerSpecWithoutSource, ToBeAddedLayerSpec, ToBeAddedLayerSpecTemplate, ToBeAddedLayerSpecWithoutSource, TrafficAreaAnalyticsConfig, TrafficIncidentOverlayConfig, UserEventHandler, ValuesFilter, WaypointsConfig };
+export type { AREA_ANALYTICS_DEFAULTS, AreaAnalyticsBeforeLayerConfig, AreaAnalyticsColorStop, AreaAnalyticsColorStopsConfig, AreaAnalyticsColorTheme, AreaAnalyticsDisplayMode, AreaAnalyticsHeightConfig, AreaAnalyticsMetricConfig, AreaAnalyticsMetricFilter, AreaAnalyticsRegionPolygonConfig, AreaAnalyticsValueType, AvailabilityLevel, BeforeLayerConfig, ByIdOrIndex, CSSCursor, ChargingSpeedIconMapping, ChargingStopIconConfig, ChargingStopIconMapping, ChargingStopTextConfig, ChargingStopsConfig, CleanEventStateOptions, CleanEventStatesOptions, ClickEventType, CustomImage, DefaultPlaceIconConfig, DisplayRouteProps, DisplayRouteRelatedProps, DisplayRouteSummaries, DisplayRouteSummary, DisplayRouteSummaryProps, EVAvailabilityConfig, EventHandlerConfig, EventHandlerCursorConfig, EventType, FilterShowMode, FilterablePOICategory, GeoJSONSourcesWithLayers, HasAdditionalLayersConfig, HasBeforeID, HillshadeModuleConfig, HoverEventType, IncidentFocusStyle, LayerSpecFilter, LayerSpecTemplate, LayerSpecWithSource, LightDark, MapEventsConfig, MapFont, MapModuleCommonConfig, MapStyleLayerID, POIsModuleConfig, POIsModuleFeature, PlaceConnectionDisplay, PlaceConnectionLayerName, PlaceConnectionsConfig, PlaceConnectionsLayersConfig, PlaceIconConfig, PlaceLayerName, PlaceLayersConfig, PlaceTextConfig, PlacesModuleConfig, PlacesTheme, PlanningWaypoint, PutEventStateOptions, RouteLayersConfig, RouteStateProps, RouteTheme, RouteWaypointSize, RouteWidth, RoutingModuleConfig, SVGIconStyleOptions, SourceWithLayerIDs, SourceWithLayers, SourcesWithLayers, StyleSourcesWithLayers, SupportsEvents, SymbolLayerSpecWithoutSource, ToBeAddedLayerSpec, ToBeAddedLayerSpecTemplate, ToBeAddedLayerSpecWithoutSource, TrafficAreaAnalyticsConfig, TrafficIncidentOverlayConfig, UserEventHandler, ValuesFilter, WaypointsConfig };