@tomtom-org/maps-sdk 1.0.0-rc.4 → 1.0.0-rc.6

package/map/dist/index.d.ts

@@ -1,13 +1,70 @@
-import { AllLayoutProperties, AllPaintProperties, BackgroundLayerSpecification, CircleLayerSpecification, CustomLayerInterface, DataDrivenPropertyValueSpecification, ExpressionFilterSpecification, ExpressionSpecification, FillExtrusionLayerSpecification, FillLayerSpecification, FilterSpecification, GeoJSONSource, GeoJSONSourceSpecification, HeatmapLayerSpecification, LayerSpecification, LineLayerSpecification, LngLat, Map as Map$1, MapGeoJSONFeature, MapOptions, Point2D, RequestParameters, ResourceType, Source, SourceSpecification, StyleImageMetadata, StyleImageSource, StyleSpecification, SymbolLayerSpecification } from "maplibre-gl";
-import { Anything, AreaAnalyticsMetricKey, AreaAnalyticsMetrics, BBox, CommonPlaceProps, CountrySectionProps, DelayMagnitude, DisplayUnits, DistanceDisplayUnits, EntryPoint, GeopoliticalView, GetPositionEntryPointOption, GlobalConfig, Instruction, Language, POICategory, Place, Places, PolygonFeature, PolygonFeatures, Route, RouteProps, Routes, SDKErrorCode, SectionProps, SectionType, SpeedLimitSectionProps, TimeDisplayUnits, TrafficAreaAnalytics, TrafficIncident, TrafficIncidentBaseProperties, TrafficIncidentCategory, TrafficIncidentDetails, TrafficIncidentTimeValidity, TrafficSectionProps, Waypoint, WaypointLike, Waypoints } from "@tomtom-org/maps-sdk/core";
+import { AllLayoutProperties, AllPaintProperties, BackgroundLayerSpecification, CircleLayerSpecification, ControlPosition, CustomLayerInterface, DataDrivenPropertyValueSpecification, ExpressionFilterSpecification, ExpressionSpecification, FillExtrusionLayerSpecification, FillLayerSpecification, FilterSpecification, GeoJSONSource, GeoJSONSourceSpecification, HeatmapLayerSpecification, LayerSpecification, LineLayerSpecification, LngLat, Map as Map$1, MapGeoJSONFeature, MapOptions, Point2D, RequestParameters, ResourceType, Source, SourceSpecification, StyleImageMetadata, StyleImageSource, StyleSpecification, SymbolLayerSpecification } from "maplibre-gl";
+import { APIErrorDetails, Anything, AreaAnalyticsMetricKey, AreaAnalyticsMetrics, BBox, CommonPlaceProps, CountrySectionProps, DelayMagnitude, DisplayUnits, DistanceDisplayUnits, EntryPoint, GeopoliticalView, GetPositionEntryPointOption, GlobalConfig, HasLngLat, Instruction, Language, POICategory, Place, Places, PolygonFeature, PolygonFeatures, PrivatePreviewAccess, Route, RouteProps, Routes, SDKErrorCode, SectionProps, SectionType, SpeedLimitSectionProps, TimeDisplayUnits, TrafficAreaAnalytics, TrafficIncident, TrafficIncidentBaseProperties, TrafficIncidentCategory, TrafficIncidentDetails, TrafficIncidentTimeValidity, TrafficSectionProps, Waypoint, WaypointLike, Waypoints } from "@tomtom-org/maps-sdk/core";
+//#region src/shared/types/style.d.ts
+/**
+ * A light or dark theme.
+ *
+ * Use it to classify a map style as light or dark, or to apply light or dark configurations to the
+ * map modules that support them.
+ *
+ * @group Map Style
+ */
+type LightDark = 'light' | 'dark';
+//#endregion
 //#region src/attribution/types/attributionOptions.d.ts
 /**
- * What the map's attribution ("copyright") shows besides the credits of its data sources.
+ * Corner of the map the attribution is anchored to.
+ *
+ * @remarks
+ * These are MapLibre's own control corners, so the attribution stacks with any other
+ * control placed in the same corner.
+ *
+ * @see {@link AttributionOptions.position}
+ *
+ * @group Map
+ */
+type AttributionPosition = ControlPosition;
+/**
+ * Distance in CSS pixels between the attribution and the map edges it is anchored to.
+ *
+ * @remarks
+ * A single number applies to both axes. The object form sets them apart: `horizontal` is
+ * the gap to the left or right edge, `vertical` the gap to the top or bottom edge. Which
+ * edges those are follows {@link AttributionOptions.position}.
+ *
+ * @example
+ * ```typescript
+ * padding: 16                              // 16px from both edges
+ * padding: { horizontal: 12, vertical: 8 } // the default
+ * padding: { vertical: 24 }                // 24px from the anchored horizontal edge, default 12px in
+ * ```
+ *
+ * @see {@link AttributionOptions.padding}
+ *
+ * @group Map
+ */
+type AttributionPadding = number | {
+  horizontal?: number;
+  vertical?: number;
+};
+/**
+ * Where the map's attribution ("copyright") sits, the credits of your own it shows besides
+ * those of the map's data sources, and whether a backdrop sits behind it.
+ *
+ * @remarks
+ * The TomTom and OpenStreetMap credits show as logos, any other source's as text after them.
+ * Pass this as the `attribution` option of {@link TomTomMapParams} to move them clear of
+ * your own layout, or to credit data of your own.
+ *
+ * Attribution is a licensing requirement, so no option turns it off: wherever you move it,
+ * it has to stay visible, legible and uncovered over the map.
  *
  * @example
  * ```typescript
  * const map = new TomTomMap({
- *   attribution: { credits: ['Weather data by Open-Meteo.com'] },
+ *   apiKey: 'your-api-key',
+ *   // Logos in the top-left, clear of a bottom bar of your own
+ *   attribution: { position: 'top-left', padding: 16 },
  *   mapLibre: { container: 'map' },
  * });
  * ```
@@ -17,12 +74,24 @@ import { Anything, AreaAnalyticsMetricKey, AreaAnalyticsMetrics, BBox, CommonPla
  * @group Map
  */
 type AttributionOptions = {
+  /**
+   * Corner of the map the attribution is anchored to.
+   *
+   * @defaultValue `'bottom-right'`
+   */
+  position?: AttributionPosition;
+  /**
+   * Distance in CSS pixels to the map edges the attribution is anchored to.
+   *
+   * @defaultValue `{ horizontal: 12, vertical: 8 }`
+   */
+  padding?: AttributionPadding;
   /**
    * Your own credits, shown next to TomTom's and kept across style switches.
    *
    * @remarks
-   * Each credit is text or HTML, such as a link. A credit that another credit already contains shows once, so one
-   * that repeats the style's own wording, such as `© OpenStreetMap`, doesn't show twice.
+   * Each credit is text or HTML, such as a link. A credit that repeats one the map already shows, such as
+   * `© OpenStreetMap`, shows once.
    *
    * @example
    * ```typescript
@@ -30,8 +99,49 @@ type AttributionOptions = {
    * ```
    */
   credits?: string[];
+  /**
+   * Whether a soft, blurred backdrop sits behind the logos, so they stand out from the map's labels.
+   *
+   * @remarks
+   * It follows the style's theme, light over a light style and dark over a dark one, and fades out
+   * past the logos without moving them. Turn it off where your own UI already gives the attribution
+   * a calm background.
+   *
+   * @defaultValue `true`
+   */
+  backdrop?: boolean;
 };
 //#endregion
+//#region src/attribution/AttributionLogosControl.d.ts
+/**
+ * Class on the element holding the attribution logos, `tomtom-attribution-logos`.
+ *
+ * @remarks
+ * Use it to tell the attribution apart from your own controls in a corner, never to hide it:
+ * the credits are a licensing requirement.
+ *
+ * @group Map
+ */
+export declare const ATTRIBUTION_LOGOS_CLASS = "tomtom-attribution-logos";
+/**
+ * Class on each individual logo inside {@link ATTRIBUTION_LOGOS_CLASS}.
+ *
+ * @ignore
+ */
+export declare const ATTRIBUTION_LOGO_CLASS = "tomtom-attribution-logo";
+/**
+ * Class on the credits no logo covers, set as text after the logos.
+ *
+ * @ignore
+ */
+export declare const ATTRIBUTION_CREDITS_CLASS = "tomtom-attribution-credits";
+/**
+ * Class on the soft backdrop behind the marks.
+ *
+ * @ignore
+ */
+export declare const ATTRIBUTION_BACKDROP_CLASS = "tomtom-attribution-backdrop";
+//#endregion
 //#region src/shared/layers/layerIDs.d.ts
 /**
  * Key layer IDs from the vector map style for positioning custom layers.
@@ -67,9 +177,9 @@ type AttributionOptions = {
  *   beforeLayerConfig: 'lowestBuilding'
  * });
  *
- * // On top of everything
- * const onTop = await GeometriesModule.create(map, {
- *   beforeLayerConfig: 'top'
+ * // Per part: the fill under the roads, the border on top
+ * const fillUnderRoads = await GeometriesModule.create(map, {
+ *   beforeLayerConfig: { fill: 'lowestRoadLine' }
  * });
  * ```
  *
@@ -155,11 +265,12 @@ export declare const mapStyleLayerIDs: {
    */
   readonly lowest3D: "3D - Building";
   /**
-   * The lowest road line layer in the stack.
+   * The tunnel railway outlines, low among the road network's line layers: only the subway and
+   * railway fill tunnels sit below it.
    *
    * @remarks
-   * It holds the tunnel railway outlines. Use it to position content below the road network,
-   * such as base layers or features that should appear beneath transportation infrastructure.
+   * Use it to position content below the roads, such as base layers or features that should
+   * appear beneath transportation infrastructure.
    *
    * **Note:** Not available in the Satellite style.
    */
@@ -491,7 +602,9 @@ type IndexedFeature<F> = {
  * carries all of it, next to what the style itself gave the layer.
  *
  * The snapshot and the contributions belong to the style they were taken from, so both are dropped
- * when a new style arrives; every module re-registers what it still wants as it restores itself.
+ * when a new style arrives; every module re-registers what it still wants as it restores itself. A
+ * switch to the style already loaded reloads nothing, so both stay: the layers still carry what the
+ * composer wrote, and a module that withdraws its say gets the style's own value back.
  *
  * @ignore
  */
@@ -499,6 +612,11 @@ declare abstract class AbstractLayerComposer<CONTRIBUTIONS> {
   protected readonly mapLibreMap: Map$1;
   protected readonly byLayer: Map<string, CONTRIBUTIONS>;
   protected constructor(tomtomMap: TomTomMap);
+  /** What the style itself gave the layer, with no contribution yet. */
+  protected abstract snapshot(layerId: string): CONTRIBUTIONS;
+  /** Writes the value the layer's contributions compose into. */
+  protected abstract write(layerId: string, contributions: CONTRIBUTIONS): void;
+  protected contribute(layerId: string, withdraws: boolean, register: (contributions: CONTRIBUTIONS) => void): void;
 }
 //#endregion
 //#region src/shared/layers/layerVisibilityComposer.d.ts
@@ -511,9 +629,11 @@ type LayerVisibilityContributions = {
  * The single owner of a style layer's `visibility`, for the layers more than one module shows or
  * hides.
  *
- * A style-owned module shows or hides the style layers it owns, and a styling toggle shows or hides
- * a few layers nested among them: `pois.microMarkers` among the POIs, `roads.arrows` among the
- * base-map roads. If each wrote the layout property itself, the later write would undo the other.
+ * A style-owned module shows or hides the style layers it owns, and a part knob shows or hides a few
+ * layers nested among them, through {@link LayerPartToggles}: the POIs `microMarkers.visible` among
+ * the POIs, the base map's `roads.arrows.visible` among its roads. The styling module's
+ * `layers.query(...).setVisible` has a say in any of them too. If each wrote the layout property
+ * itself, the later write would undo the other.
  *
  * So a layer is hidden when any contributor hides it, shown when one shows it and none hides it,
  * and left as the style shipped it when no contributor has a say.
@@ -533,6 +653,8 @@ declare class LayerVisibilityComposer extends AbstractLayerComposer<LayerVisibil
    * @param visible - `true` to show the layer unless another contributor hides it, `false` to hide it.
    */
   setVisible(layerId: string, contributor: string, visible: boolean | undefined): void;
+  protected snapshot(layerId: string): LayerVisibilityContributions;
+  protected write(layerId: string, layer: LayerVisibilityContributions): void;
 }
 //#endregion
 //#region src/shared/TomTomMapSource.d.ts
@@ -582,12 +704,49 @@ export declare abstract class AbstractSourceWithLayers<SOURCE_SPEC extends Sourc
   setLayersVisible(visible: boolean, filter?: LayerSpecFilter): void;
   get sourceAndLayerIDs(): SourceWithLayerIDs;
 }
+/**
+ * A source that keeps the event states of its features itself, rather than in the features it shows:
+ * a custom layer's objects, a style source's features. The event proxy addresses each feature by the
+ * key read off it.
+ * @ignore
+ */
+type EventStateKeeper<KEY extends string | number = string | number> = {
+  /** The key of a rendered feature of this source; `undefined` for one it cannot address. */
+  eventStateKeyOf(feature: MapGeoJSONFeature): KEY | undefined;
+  eventStateOf(key: KEY): EventState | undefined;
+  /** The keys that have a state. */
+  keysWithEventState(): KEY[];
+  putEventState(key: KEY, state: EventState | undefined): void;
+};
+/**
+ * The id of a style source's feature, which feature state addresses it by.
+ * @ignore
+ */
+type FeatureId = string | number;
+/**
+ * The features of a style source that take an event state as one, as the parts of a building do.
+ * @ignore
+ */
+type FeatureGroups = {
+  /** The id standing for the group of the feature with this id: its own, when it is in none. */
+  groupOf(sourceLayer: string | null, id: FeatureId): FeatureId;
+  /** The ids of the features of the group with this id. */
+  membersOf(sourceLayer: string | null, id: FeatureId): FeatureId[];
+};
 /**
  * Source with layers which are coming from the downloaded TT map style.
  * * Examples are parts of the base map, traffic, pois, and hillshade.
+ *
+ * It draws no features of its own to put an event state in, so it puts it on the style's features as
+ * the feature state `eventState`, for the style's paint to read with `['feature-state', 'eventState']`.
  * @ignore
  */
-export declare class StyleSourceWithLayers<SOURCE_SPEC extends SourceSpecification = SourceSpecification, RUNTIME_SOURCE extends Source = Source> extends AbstractSourceWithLayers<SOURCE_SPEC, RUNTIME_SOURCE> {
+export declare class StyleSourceWithLayers<SOURCE_SPEC extends SourceSpecification = SourceSpecification, RUNTIME_SOURCE extends Source = Source> extends AbstractSourceWithLayers<SOURCE_SPEC, RUNTIME_SOURCE> implements EventStateKeeper<string> {
+  private readonly eventStates;
+  /** The features that take a state as one; each feature on its own without it. */
+  featureGroups?: FeatureGroups;
+  /** Feature state written with an event state, such as the look it shows in; `undefined` takes it off. */
+  eventStateLook?: (sourceLayer: string | null, state: EventState | undefined) => Record<string, unknown>;
   constructor(map: Map$1, runtimeSource: RUNTIME_SOURCE, filter?: LayerSpecFilter);
   /**
    * Shows or hides the layers `filter` selects as `contributor`'s say in the map's
@@ -595,6 +754,26 @@ export declare class StyleSourceWithLayers<SOURCE_SPEC extends SourceSpecificati
    * being overwritten.
    */
   setLayersVisibleThrough(composer: LayerVisibilityComposer, contributor: string, visible: boolean, filter?: LayerSpecFilter): void;
+  /** `undefined` for a feature without an id, which feature state cannot address. */
+  eventStateKeyOf(feature: MapGeoJSONFeature): string | undefined;
+  eventStateOf(key: string): EventState | undefined;
+  keysWithEventState(): string[];
+  putEventState(key: string, state: EventState | undefined): void;
+  /** Takes over the states the keeper of the style before kept, putting each on this one's source. */
+  takeEventStatesFrom(previous: StyleSourceWithLayers): void;
+  /** Takes every state off, the map's feature state included. */
+  clearEventStates(): void;
+  /**
+   * Puts every state on its group again, onto the members found since it was put, and keys a state put
+   * on a feature before it joined a group by the group, so taking the group's state off takes it off.
+   */
+  rewriteEventStates(): void;
+  /**
+   * Sets feature state on every feature of the group the feature with this id is in, removing each
+   * property whose value is `undefined`.
+   */
+  writeFeatureState(sourceLayer: string | null, featureId: FeatureId, values: Readonly<Record<string, unknown>>): void;
+  private writeEventState;
 }
 /**
  * Source with layers which originally is not in the map style, but it's to be added after the map is initialized.
@@ -638,6 +817,8 @@ type GeoJSONSourceClusterOptions = Pick<GeoJSONSourceSpecification, 'cluster' |
 export declare class GeoJSONSourceWithLayers<T extends FeatureCollection = FeatureCollection> extends AddedSourceWithLayers<GeoJSONSourceSpecification, GeoJSONSource> {
   shownFeatures: T;
   private readonly showListeners;
+  private featuresById?;
+  private eventStatesUnshown;
   constructor(map: Map$1, sourceId: string, layerSpecs: ToBeAddedLayerSpecWithoutSource[], addLayersToMap?: boolean, clusterOptions?: GeoJSONSourceClusterOptions);
   show(featureCollection: T, { automaticVisibility }?: ShowOptions): void;
   /**
@@ -646,14 +827,20 @@ export declare class GeoJSONSourceWithLayers<T extends FeatureCollection = Featu
   onShow(listener: () => void): void;
   /**
    * Canonical id-based lookup into `shownFeatures.features`, by each feature's `properties.id`,
-   * otherwise its `id`. On duplicate ids, the first match wins. Returns `undefined` for a nullish
-   * or absent id.
+   * otherwise its `id`. On duplicate ids, the first match wins. Returns `undefined` for an absent id.
    */
   findById(id: string | number | undefined): IndexedFeature<T['features'][number]> | undefined;
   clear(): void;
+  /** Whether the source shows no feature. */
+  isEmpty(): boolean;
+  /** {@link show}, skipped where the source is empty and stays so: it isn't reloaded with nothing. */
+  showUnlessStillEmpty(featureCollection: T, options?: ShowOptions): void;
+  /** {@link clear}, skipped where the source is empty already. */
+  clearUnlessEmpty(): void;
   private findFeature;
   private showWithFeatures;
   setEventState(options: SetEventStateOptions): void;
+  private showUnshownEventStates;
   clearEventState(options: ClearEventStateOptions): void;
   clearEventStates(options?: ClearEventStatesOptions): void;
   /**
@@ -673,11 +860,14 @@ type CustomLayerHitCallbacks<HIT extends CustomLayerHit> = {
  * itself, handing each change to the app's `setState`.
  * @ignore
  */
-export declare class CustomLayerSourceWithLayers<HIT extends CustomLayerHit = CustomLayerHit> {
+export declare class CustomLayerSourceWithLayers<HIT extends CustomLayerHit = CustomLayerHit> implements EventStateKeeper<HIT['id']> {
   readonly map: Map$1;
   readonly layerId: string;
   private readonly callbacks;
-  /** The layer's id: a custom layer has no source, and the handler index files by source id. */
+  /**
+   * A source id of its own: a custom layer has no source, and the handler index files by source id.
+   * Not its layer id, which a module's `sourceID` may equal, sharing its handlers and hovers.
+   */
   readonly source: {
     readonly id: string;
   };
@@ -692,9 +882,9 @@ export declare class CustomLayerSourceWithLayers<HIT extends CustomLayerHit = Cu
   hitFeatures(point: Point2D): MapGeoJSONFeature[];
   /** What the hit tester returned for a feature {@link hitFeatures} made. */
   hitOf(feature: MapGeoJSONFeature): HIT;
+  eventStateKeyOf(feature: MapGeoJSONFeature): HIT['id'] | undefined;
   eventStateOf(id: HIT['id']): EventState | undefined;
-  /** The ids that have a state. */
-  idsWithEventState(): HIT['id'][];
+  keysWithEventState(): HIT['id'][];
   putEventState(id: HIT['id'], state: EventState | undefined): void;
   /**
    * Forgets every state, and hands none to the app from now on: the proxy can still hold this
@@ -910,6 +1100,11 @@ type HasAdditionalLayersConfig = {
 };
 //#endregion
 //#region src/shared/types/events.d.ts
+/**
+ * The event states a click puts on a feature.
+ * @ignore
+ */
+export declare const CLICK_EVENT_STATES: readonly ["click", "contextmenu"];
 /**
  * Subtype for click events.
  *
@@ -925,13 +1120,19 @@ type HasAdditionalLayersConfig = {
  *
  * @group User Interaction Events
  */
-type ClickEventType = 'click' | 'contextmenu';
+export type ClickEventType = (typeof CLICK_EVENT_STATES)[number];
+/**
+ * The event states the pointer puts on a feature it rests on. `recently-hovered` is not one of them.
+ * @ignore
+ */
+export declare const HOVER_EVENT_STATES: readonly ["hover", "hover-move", "long-hover"];
 /**
  * Subtype for hover events with timing distinction.
  *
  * @remarks
  * - `hover`: Fires once when the cursor first enters a feature.
- * - `hover-move`: Fires on every mouse movement while the cursor stays over the same feature.
+ * - `hover-move`: Fires as the cursor moves while it stays over the same feature, at most once per
+ *   animation frame.
  *   Use it for coordinates that follow the cursor along the feature, for example to move a tooltip
  *   or snap to a route line.
  * - `long-hover`: Fires after the cursor stays over a feature for a configured duration (typically 300-800ms).
@@ -947,7 +1148,7 @@ type ClickEventType = 'click' | 'contextmenu';
  *
  * @group User Interaction Events
  */
-type HoverEventType = 'hover' | 'hover-move' | 'long-hover';
+export type HoverEventType = (typeof HOVER_EVENT_STATES)[number];
 /**
  * Subtype for drag events, with the mouse or a single finger.
  *
@@ -972,7 +1173,7 @@ type HoverEventType = 'hover' | 'hover-move' | 'long-hover';
  *
  * @group User Interaction Events
  */
-type DragEventType = 'dragstart' | 'drag' | 'dragend';
+export type DragEventType = 'dragstart' | 'drag' | 'dragend';
 /**
  * A user event type the SDK supports beyond basic MapLibre events.
  *
@@ -989,7 +1190,7 @@ type DragEventType = 'dragstart' | 'drag' | 'dragend';
  *
  * @group User Interaction Events
  */
-type EventType = ClickEventType | HoverEventType | DragEventType;
+export type EventType = ClickEventType | HoverEventType | DragEventType;
 /**
  * The user event a feature is in, or `recently-hovered` for a moment after the pointer leaves it,
  * as stored in `properties.eventState`.
@@ -1003,12 +1204,12 @@ type EventType = ClickEventType | HoverEventType | DragEventType;
  *
  * @group User Interaction Events
  */
-type EventState = SetEventStateOptions['state'] | 'recently-hovered';
+export type EventState = SetEventStateOptions['state'] | 'recently-hovered';
 /**
  * Parameters to identify a shown feature by its ID or by its index.
  * @group User Interaction Events
  */
-type ByIdOrIndex = {
+export type ByIdOrIndex = {
   /**
    * The feature's `properties.id`, otherwise its top-level `id`. This is the id the module's
    * `getShown()` and event handlers return. You can't combine it with `index`.
@@ -1054,7 +1255,7 @@ type ByIdOrIndex = {
  *
  * @group User Interaction Events
  */
-type SetEventStateOptions = ByIdOrIndex & {
+export type SetEventStateOptions = ByIdOrIndex & {
   /**
    * The event state to set.
    *
@@ -1124,7 +1325,7 @@ type SetEventStateOptions = ByIdOrIndex & {
  *
  * @group User Interaction Events
  */
-type ClearEventStateOptions = ByIdOrIndex & {
+export type ClearEventStateOptions = ByIdOrIndex & {
   /**
    * Whether to show the feature after clearing the event state.
    *
@@ -1160,7 +1361,7 @@ type ClearEventStateOptions = ByIdOrIndex & {
  *
  * @group User Interaction Events
  */
-type ClearEventStatesOptions = {
+export type ClearEventStatesOptions = {
   /**
    * The event states to clear.
    *
@@ -1206,7 +1407,7 @@ type ClearEventStatesOptions = {
  *
  * @group User Interaction Events
  */
-type EventStateIds = Partial<Record<EventState, (string | number)[]>>;
+export type EventStateIds = Partial<Record<EventState, (string | number)[]>>;
 /**
  * The properties part of an object that can have an event state.
  *
@@ -1235,7 +1436,7 @@ type EventStateIds = Partial<Record<EventState, (string | number)[]>>;
  *
  * @group User Interaction Events
  */
-type SupportsEvents = {
+export type SupportsEvents = {
   /**
    * The feature's current event state.
    *
@@ -1256,24 +1457,27 @@ type SupportsEvents = {
  * The SDK calls it when a user interacts with features on the map, for example on click or hover.
  * It receives the feature, the event location and all features at the event coordinates.
  *
- * In GeoJSON modules (places, routes, geometries), `topFeature` is the original feature you passed
- * to `show()`. In vector tile modules (POIs, traffic), `topFeature` comes from MapLibre's internal
- * feature representation.
+ * In GeoJSON modules (places, routes, geometries), `topFeature` is the feature as the module shows
+ * it, with its dates and nested objects intact, but not the object you passed to `show()`. In
+ * vector tile modules (POIs, traffic), `topFeature` comes from MapLibre's internal feature
+ * representation.
  *
  * Depending on `MapEventsConfig.precisionMode`, the `lngLat` coordinates may be near the feature
  * rather than exactly on it. In a drag event, `topFeature` and `allEventFeatures` are the ones
  * pressed at `dragstart`, and `lngLat` is where the pointer is now.
  *
- * `allEventFeatures` holds the module's features at the event coordinates, each once even when
+ * `allEventFeatures` holds the features at the event coordinates from the source that drew
+ * `topFeature`, such as a route's waypoints but not its lines, each once even when
  * drawn across several layers or tiles, in the same shape as `topFeature`, which is the first.
- * To inspect every feature there across all modules, including the base map, project `lngLat` to
+ * A handler registered through `where()` gets only the ones in its scope: on its layers, and taken
+ * by its predicate. To inspect every feature there across all modules, including the base map, project `lngLat` to
  * a pixel and call `map.mapLibreMap.queryRenderedFeatures` around it.
  *
  * @typeParam T - The type of the top feature being interacted with
  *
  * @param topFeature - The event's primary target feature, positioned on top of any overlapping features.
  * @param lngLat - The geographic coordinates where the event occurred
- * @param allEventFeatures - The features at the event coordinates, scoped to the module whose handler fired.
+ * @param allEventFeatures - The features at the event coordinates, scoped to the source that drew `topFeature`.
  * @param sourceWithLayers - The source and layer configuration to which the `topFeature` belongs
  *
  * @example
@@ -1289,7 +1493,7 @@ type SupportsEvents = {
  * @example
  * Hover handler for places with feature inspection:
  * ```ts
- * placesModule.events.on('hover', (place, lngLat, allFeatures, source) => {
+ * placesModule.events.places.on('hover', (place, lngLat, allFeatures, source) => {
  *   // Show tooltip with place information
  *   showTooltip({
  *     title: place.properties.poi?.name,
@@ -1308,19 +1512,19 @@ type SupportsEvents = {
  *
  * @group User Interaction Events
  */
-type UserEventHandler<T> = (topFeature: T, lngLat: LngLat, allEventFeatures: T[], sourceWithLayers: SourceWithLayers) => void;
+export type UserEventHandler<T> = (topFeature: T, lngLat: LngLat, allEventFeatures: T[], sourceWithLayers: SourceWithLayers) => void;
 /**
  * Allowed CSS cursor styles for map interactions.
  *
  * @group User Interaction Events
  */
-type CSSCursor = 'alias' | 'all-scroll' | 'auto' | 'cell' | 'context-menu' | 'col-resize' | 'copy' | 'crosshair' | 'default' | 'e-resize' | 'ew-resize' | 'grab' | 'grabbing' | 'help' | 'move' | 'n-resize' | 'ne-resize' | 'nesw-resize' | 'ns-resize' | 'nw-resize' | 'nwse-resize' | 'no-drop' | 'none' | 'not-allowed' | 'pointer' | 'progress' | 'row-resize' | 's-resize' | 'se-resize' | 'sw-resize' | 'text' | 'vertical-text' | 'w-resize' | 'wait' | 'zoom-in' | 'zoom-out';
+export type CSSCursor = 'alias' | 'all-scroll' | 'auto' | 'cell' | 'context-menu' | 'col-resize' | 'copy' | 'crosshair' | 'default' | 'e-resize' | 'ew-resize' | 'grab' | 'grabbing' | 'help' | 'move' | 'n-resize' | 'ne-resize' | 'nesw-resize' | 'ns-resize' | 'nw-resize' | 'nwse-resize' | 'no-drop' | 'none' | 'not-allowed' | 'pointer' | 'progress' | 'row-resize' | 's-resize' | 'se-resize' | 'sw-resize' | 'text' | 'vertical-text' | 'w-resize' | 'wait' | 'zoom-in' | 'zoom-out';
 /**
  * Event configuration options related to how the cursor appears during interactions.
  *
  * @group User Interaction Events
  */
-type EventHandlerCursorConfig = {
+export type EventHandlerCursorConfig = {
   /**
    * The cursor to show when hovering over interactive features, one of the CSS cursor keywords
    * {@link CSSCursor} lists.
@@ -1355,7 +1559,7 @@ type EventHandlerCursorConfig = {
  *
  * @group User Interaction Events
  */
-type EventHandlerHoverConfig = {
+export type EventHandlerHoverConfig = {
   /**
    * How long, in milliseconds, a feature stays `recently-hovered` after the pointer leaves it.
    * `0` clears its state at once.
@@ -1373,7 +1577,7 @@ type EventHandlerHoverConfig = {
  *
  * @group User Interaction Events
  */
-type EventHandlerConfig = EventHandlerCursorConfig & EventHandlerHoverConfig;
+export type EventHandlerConfig = EventHandlerCursorConfig & EventHandlerHoverConfig;
 //#endregion
 //#region src/shared/types/filters.d.ts
 /**
@@ -1399,10 +1603,10 @@ export type FilterShowMode = (typeof filterShowModes)[number];
  * @example
  * ```typescript
  * // Show only these categories
- * const includeFilter: ValuesFilter<string> = { show: 'only', values: ['RESTAURANT', 'CAFE', 'BAR'] };
+ * const onlyFilter: ValuesFilter<string> = { show: 'only', values: ['RESTAURANT', 'CAFE', 'BAR'] };
  *
  * // Hide these categories
- * const excludeFilter: ValuesFilter<string> = { show: 'all-except', values: ['PARKING_GARAGE'] };
+ * const allExceptFilter: ValuesFilter<string> = { show: 'all-except', values: ['PARKING_GARAGE'] };
  * ```
  *
  * @group Shared
@@ -1455,7 +1659,7 @@ type CustomImage<I extends string = string> = {
    */
   id: I;
   /**
-   * The URL or data URI of the icon image.
+   * The icon image: a URL, a data URI, SVG markup or an `img` element.
    *
    * @remarks
    * To add a new icon to the sprite, set it. To reference an existing sprite icon, leave it out
@@ -1725,7 +1929,8 @@ export declare const MAP_ITALIC_FONT = "NotoSans-MediumItalic";
  */
 export declare const DEFAULT_TEXT_SIZE: ExpressionSpecification;
 /**
- * All font faces available in the TomTom map style.
+ * The font faces of the TomTom map style a label can name. The style also draws some of its own
+ * labels in the condensed `NotoSans-Condensed*` faces, which this list leaves out.
  *
  * @remarks
  * Use it to select or validate fonts when creating custom layers. The `Noto-*` faces draw every
@@ -1755,11 +1960,10 @@ export declare const DEFAULT_TEXT_SIZE: ExpressionSpecification;
  */
 export declare const mapFonts: readonly ["Noto-Regular", "NotoSans-MediumItalic", "Noto-Bold", "Noto-Medium", "NotoSans-RegularItalic", "NotoSans-BoldItalic", "NotoSerif-Regular", "NotoSerif-Medium", "NotoSerif-Bold", "NotoSerif-RegularItalic", "NotoSerif-MediumItalic", "NotoSerif-BoldItalic"];
 /**
- * A font face available in the TomTom map style.
+ * A font face of {@link mapFonts}.
  *
  * @remarks
- * Use it for type-safe font selection in text layers. It only accepts the fonts available in
- * the map style.
+ * Use it for type-safe font selection in text layers. It only accepts the faces {@link mapFonts} lists.
  *
  * @example
  * ```typescript
@@ -1973,17 +2177,6 @@ type MapModuleCommonConfig = {
   events?: EventHandlerConfig;
 };
 //#endregion
-//#region src/shared/types/style.d.ts
-/**
- * A light or dark theme.
- *
- * Use it to classify a map style as light or dark, or to apply light or dark configurations to the
- * map modules that support them.
- *
- * @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
@@ -2013,9 +2206,10 @@ type ResolvedEventScope = {
    */
   layerFilter?: LayerSpecFilter;
   /**
-   * Decides whether a rendered feature belongs to this scope. It receives the raw MapLibre
-   * feature. A module's `mapping` is composed into this function at `where()` time, so the
-   * caller's predicate still sees the module's own feature type.
+   * Decides whether a rendered feature belongs to this scope. It receives the feature as shown:
+   * from a GeoJSON source, the shown feature, with no `layer` or `source`, and from a vector tile
+   * source the MapLibre feature. A module's `mapping` is composed into this function at `where()`
+   * time, so the caller's predicate still sees the module's own feature type.
    */
   featureMatches?: (feature: MapGeoJSONFeature) => boolean;
 };
@@ -2103,8 +2297,9 @@ type HandlerEntry = {
 type HandlerRegistration = Pick<HandlerEntry, 'config' | 'owner' | 'scope'>;
 /**
  * One event type's handlers, bucketed by the layer they listen to. Each bucket is in registration
- * order, and `findHandlers` lists the buckets in the order of its types, so `findHandlers()[0]` is
- * the first one registered for the first type that has one. That is what claims the hover cursor.
+ * order, and `findHandlers` lists the buckets in the order of its types, so its first entry, which
+ * {@link AbstractEventProxy.firstHandler} finds alone, is the first one registered for the first type
+ * that has one. That is what claims the hover cursor.
  *
  * @ignore
  */
@@ -2129,6 +2324,9 @@ type HandlersByLayer = Record<string, HandlerEntry[]>;
  *     contextmenu: {},
  *     'hover-move': {},
  *     'long-hover': {},
+ *     dragstart: {},
+ *     drag: {},
+ *     dragend: {},
  * };
  * ```
  *
@@ -2139,9 +2337,9 @@ type EventHandlers = Record<EventType, HandlersByLayer>;
  * @ignore
  */
 declare abstract class AbstractEventProxy {
-  protected interactiveLayerIDs: string[];
-  protected handlers: EventHandlers;
-  private registered;
+  protected readonly interactiveLayerIDs: string[];
+  protected readonly handlers: EventHandlers;
+  private readonly registered;
   /**
    * Adds the given layers as interactive, so we'll listen to them for hover and click.
    *
@@ -2155,12 +2353,13 @@ declare abstract class AbstractEventProxy {
   private indexHandler;
   private unindexHandlers;
   /**
-   * Detaches this source's handlers that the predicate matches, then stops listening to any
-   * layer none of the survivors still covers.
+   * Detaches the handlers on this source id that the predicate matches, then stops listening to
+   * any layer none of the survivors still covers.
    *
    * The source has to be part of the match: `UserEvents.on` registers one handler function
    * across several sources and unsubscribes them one at a time, so the function alone does not
-   * identify which registration to drop.
+   * identify which registration to drop. It goes by id, which the source keeps across a style
+   * change and across a config change that drops it and adds it back.
    */
   private dropHandlers;
   /**
@@ -2174,11 +2373,11 @@ declare abstract class AbstractEventProxy {
   /**
    * Removes a single handler function for the given source and event type.
    * Other handlers registered for the same source and type are not affected.
-   * @param sourceWithLayers The source whose handler should be removed.
+   * @param sourceId The id of the source whose handler should be removed.
    * @param type The event type.
    * @param handler The exact function reference to remove.
    */
-  removeHandler(sourceWithLayers: SourceWithLayers, type: EventType, handler: UserEventHandler<any>): void;
+  removeHandler(sourceId: string, type: EventType, handler: UserEventHandler<any>): void;
   /**
    * Removes every handler this owner registered for the given source and event type — what
    * `events.off(type)` means. Scoped handlers go with the rest: a scope is a way of registering,
@@ -2187,20 +2386,16 @@ declare abstract class AbstractEventProxy {
    * Matching is by owner rather than by layer set, because two modules can share one MapLibre
    * source ID (POIs and the base map both use `vectorTiles`) and neither may drop the other's
    * handlers.
-   * @param sourceWithLayers The source whose handlers should go.
+   * @param sourceId The id of the source whose handlers should go.
    * @param type The event type to be removed.
    * @param owner The module that registered them.
    */
-  remove(sourceWithLayers: SourceWithLayers, type: EventType, owner: HandlerOwner): void;
+  remove(sourceId: string, type: EventType, owner: HandlerOwner): void;
   /**
    * Removes every handler of the source, of every event type, whoever registered it.
    * @param sourceWithLayers The source going away.
    */
   removeSource(sourceWithLayers: SourceWithLayers): void;
-  /**
-   * Removes all interactive sources and layers.
-   */
-  removeAll(): void;
   /**
    * Whether any handler, of any event type, listens to this layer.
    * @param layerId The layer id a rendered feature was drawn from.
@@ -2224,23 +2419,29 @@ declare abstract class AbstractEventProxy {
    * A style change, and a layer added or removed afterwards, both leave the filed layer ids stale. MapLibre
    * answers a rendered-features query that names a missing layer with nothing, so one stale id blanks every
    * module's events.
-   * @param sourcesWithLayers The new sources with layers to replace existing ones.
+   * @param sourcesWithLayers Every source the owner has now. A handler of the owner on a source missing from
+   * them is filed under no layer, and comes back with the source, as a config change that drops a source and
+   * then adds it again does.
    * @param owner The module whose sources these are. Only its own handlers are refreshed: two
    * modules can share one MapLibre source ID, so the ID alone cannot tell them apart.
    * @returns Each source the owner's handlers pointed at, mapped to the one that replaced it.
    */
   updateIfRegistered(sourcesWithLayers: SourcesWithLayers, owner: AnyMapModule): Map<SourceWithLayers, SourceWithLayers>;
+  private handlersToRefile;
   /**
    * The handlers that should fire for a hit on `layerId`.
    *
    * The bucket *is* the layer, so no layer matching is needed here: a handler is filed under
    * exactly the layers its scope selects, which is what keeps a click on a POI out of the base
    * map's handler even though both register against the `vectorTiles` source.
-   *
-   * When a feature is supplied, handlers whose scope rejects it are dropped too — that is what
-   * lets a feature-scoped handler drive its own hover cursor.
    */
-  protected findHandlers: (types: EventType[], layerId: string | undefined, feature?: MapGeoJSONFeature) => HandlerEntry[];
+  protected findHandlers: (types: EventType[], layerId: string | undefined) => HandlerEntry[];
+  /**
+   * The first of {@link findHandlers} that accepts `feature`, without building the list: the pointer
+   * path asks for it on every frame. A handler whose scope rejects the feature claims nothing, as a
+   * press on a feature a drag handler rejects starts no drag.
+   */
+  protected firstHandler(types: readonly EventType[], layerId: string | undefined, feature: MapGeoJSONFeature | undefined): HandlerEntry | undefined;
 }
 //#endregion
 //#region src/init/types/mapEventsConfig.d.ts
@@ -2445,18 +2646,16 @@ type MapEventsConfig = EventHandlerConfig & {
  * - Validate if a style ID is a standard style
  * - Display available options to users
  *
- * The array is declared with `const` and an `as const` assertion, for type safety
- * and to prevent modifications at runtime.
+ * The array is declared `as const`, so the compiler treats it as read-only. Nothing freezes it at runtime.
  *
  * @example
  * ```typescript
  * import { standardStyleIDs } from '@tomtom-org/maps-sdk/map';
  *
  * // Build a dropdown menu with all standard styles
- * const styleSelector = document.getElementById('style-selector');
+ * const styleSelector = document.querySelector<HTMLSelectElement>('#style-selector');
  * standardStyleIDs.forEach((styleId) => {
- *   const option = new Option(styleId);
- *   styleSelector.add(option);
+ *   styleSelector?.add(new Option(styleId));
  * });
  *
  * // Check if a style ID is valid
@@ -2519,6 +2718,7 @@ type StandardStyle = {
   id?: StandardStyleID;
   /**
    * Which {@link StylePart}s to load. Leave it out to load every part, or pass `[]` to load none.
+   * Left out in a `setStyle` that carries state over, it keeps the previous style's parts.
    *
    * @default All style parts
    */
@@ -2652,7 +2852,29 @@ type TomTomMapParams = Partial<GlobalConfig> & {
    */
   events?: MapEventsConfig;
   /**
-   * Your own credits in the map's attribution, as {@link AttributionOptions} describes.
+   * Where the map's attribution ("copyright") for its data sources sits, your own credits in it,
+   * and whether a backdrop sits behind it.
+   *
+   * The map always shows the TomTom and OpenStreetMap credits as logos, by default in the
+   * bottom-right corner over a soft backdrop. Move them to another corner, change their
+   * distance to the map edges, add credits of your own, or drop the backdrop.
+   *
+   * The attribution is a licensing requirement, so no option turns it off: wherever you
+   * place it, keep it visible, readable and uncovered.
+   *
+   * @example
+   * ```typescript
+   * // Logos in the top-left, 16px from both edges
+   * attribution: { position: 'top-left', padding: 16 }
+   *
+   * // Logos in the default corner, clear of a 64px bottom bar of your own
+   * attribution: { padding: { horizontal: 12, vertical: 72 } }
+   *
+   * // Your own data's credit, after TomTom's
+   * attribution: { credits: ['Weather data by Open-Meteo.com'] }
+   * ```
+   *
+   * @see {@link AttributionOptions}
    */
   attribution?: AttributionOptions;
   /**
@@ -2737,12 +2959,14 @@ declare class EventsProxy extends AbstractEventProxy {
   private hoveringFeature?;
   private hoveringFeatures?;
   private hoveringSourceWithLayers?;
+  private hoveringHandler?;
   private longHoverTimeoutHandlerID?;
   private readonly recentHovers;
   private firstDelayedHoverSinceMapMove;
   private lastClickedFeature?;
   private lastClickedSourceWithLayers?;
   private lastCursorStyle;
+  private mouseButtonDown;
   private pendingMouseMove?;
   private mouseMoveFrameRequested;
   private lastHandledMouseMove?;
@@ -2775,7 +2999,6 @@ declare class EventsProxy extends AbstractEventProxy {
    * extends Feature`).
    */
   private toCallerFeatures;
-  private callerFeaturesFor;
   /**
    * Hit-tests the custom layer's objects with the rendered features, while handlers listen to it.
    */
@@ -2791,15 +3014,16 @@ declare class EventsProxy extends AbstractEventProxy {
    * hover states treat a custom layer's objects as any module's features.
    */
   private withCustomLayerHits;
+  private readonly isQueryable;
   private queryRenderedFeatures;
   private clearLongHoverTimeout;
   private restartLongHoverTimeout;
-  private handleLongHoverTimeout;
+  private readonly handleLongHoverTimeout;
   private claimsHover;
   private claimingHandler;
   private readonly sameClaim;
   private rehover;
-  private onMouseStart;
+  private onMoveStart;
   private onMouseOut;
   private onMouseDown;
   private onMouseUp;
@@ -2807,7 +3031,6 @@ declare class EventsProxy extends AbstractEventProxy {
   /**
    * Holds a press on a draggable feature, and keeps MapLibre from panning the map under it. The
    * top feature decides, as for every other event.
-   * @returns Whether the press is on a draggable feature.
    */
   private onPressStart;
   private onPressMove;
@@ -2824,6 +3047,7 @@ declare class EventsProxy extends AbstractEventProxy {
    * straight there.
    */
   private onMouseMove;
+  private readonly onMouseMoveFrame;
   private handleMouseMove;
   /**
    * Handles the pointer arriving on a different feature: cursor, `eventState` marker, and the
@@ -2833,7 +3057,6 @@ declare class EventsProxy extends AbstractEventProxy {
   private dispatchHoverEnter;
   private dispatchHoverMove;
   private dispatchToHandlers;
-  private hoverGracePeriodFor;
   private clearRecentHoverLater;
   private updateHoverCursor;
   private onMapClick;
@@ -2850,9 +3073,16 @@ export type UserEventsOptions<T, WHERE_SCOPE, SOURCE extends SourceWithLayers =
    * The source(s) whose features this scope handles events for. Several sources back one scope
    * when they carry the same data in different display modes — hexgrid, square and heatmap in
    * {@link TrafficAreaAnalyticsModule}, clustered and unclustered places in {@link PlacesModule}.
-   * Resolved on every `on` and `off`, since a style switch or a config change replaces them.
+   * Resolved on every `on` and event-state call, and by `off` without {@link sourceIds}, since a
+   * style switch or a config change replaces them.
    */
   sourcesWithLayers: () => SOURCE[];
+  /**
+   * The ids of the sources this scope covers, the ones the module dropped for now included: a
+   * handler on a dropped source waits in the event proxy for it to come back, so `off` has to
+   * reach it there. Without it, `off` covers the current sources.
+   */
+  sourceIds?: () => string[];
   /**
    * The module, or custom layer, that owns these sources. Kept with every handler so a
    * style-change restore can tell handlers apart when two modules share one MapLibre source ID.
@@ -2866,7 +3096,8 @@ export type UserEventsOptions<T, WHERE_SCOPE, SOURCE extends SourceWithLayers =
    */
   config?: () => EventHandlerConfig | undefined;
   /**
-   * Transforms a raw {@link MapGeoJSONFeature} into the feature type `T` this scope exposes, so
+   * Transforms the feature as shown, the one {@link ResolvedEventScope.featureMatches} receives,
+   * into the feature type `T` this scope exposes, so
    * callers receive the module's own feature shape. Applied before handlers and before any
    * {@link UserEvents.where} predicate, so a predicate also sees `T`.
    */
@@ -2900,13 +3131,14 @@ export type UserEventsOptions<T, WHERE_SCOPE, SOURCE extends SourceWithLayers =
  *
  * A handler has this signature:
  * ```typescript
- * (feature: T, lngLat: LngLat, features: T[]) => void
+ * (feature: T, lngLat: LngLat, features: T[], sourceWithLayers: SourceWithLayers) => void
  * ```
  *
  * It receives:
  * - `feature` - The primary feature under the cursor.
  * - `lngLat` - The geographic coordinates of the event.
  * - `features` - All features at this location, when several overlap.
+ * - `sourceWithLayers` - The source, with its layers, the feature was found in.
  *
  * The SDK manages the cursor (pointer on hover) and handles overlapping features. Hover delays
  * are configurable, and removing handlers cleans up memory safely.
@@ -2955,12 +3187,12 @@ export type UserEventsOptions<T, WHERE_SCOPE, SOURCE extends SourceWithLayers =
  * const places = await PlacesModule.create(map);
  *
  * // Show title on hover
- * places.events.on('hover', (place) => {
+ * const offHover = places.events.places.on('hover', (place) => {
  *   tooltip.show(place.properties.title);
  * });
  *
  * // Show details on click
- * places.events.on('click', (place, lngLat) => {
+ * const offClick = places.events.places.on('click', (place, lngLat) => {
  *   sidebar.show({
  *     title: place.properties.title,
  *     address: place.properties.address.freeformAddress,
@@ -2968,10 +3200,10 @@ export type UserEventsOptions<T, WHERE_SCOPE, SOURCE extends SourceWithLayers =
  *   });
  * });
  *
- * // Cleanup on component unmount
+ * // Cleanup on component unmount: only these handlers, not other code's
  * onUnmount(() => {
- *   places.events.off('hover');
- *   places.events.off('click');
+ *   offHover();
+ *   offClick();
  * });
  * ```
  *
@@ -3003,7 +3235,7 @@ export declare class UserEvents<T = MapGeoJSONFeature, WHERE_SCOPE = never> {
    * this one, but two feature predicates read better as a single `a(f) && b(f)`.
    *
    * @param scope A predicate over this scope's feature type or, where the module supports one, a
-   * scope object such as `{ layerGroups }`. See {@link EventScope}.
+   * scope object such as `{ layerGroups }`.
    * @param config The event configuration for handlers registered through the returned instance.
    * Each scope can carry its own, which is how two parts of one module get different hover
    * cursors. Defaults to the configuration this instance already uses.
@@ -3040,8 +3272,9 @@ export declare class UserEvents<T = MapGeoJSONFeature, WHERE_SCOPE = never> {
    * The handler receives:
    * - `feature` - The primary feature that triggered the event.
    * - `lngLat` - The geographic coordinates of the event, as a MapLibre `LngLat` (`lngLat.lng`, `lngLat.lat`).
-   * - `features` - This module's features at the event location, de-duplicated for overlapping
-   *   features within the module. To inspect features across all modules, query
+   * - `features` - The features at the event location from the source that drew `feature`,
+   *   de-duplicated across its layers. Under {@link where}, only the ones in its scope: on its
+   *   layers, and taken by its predicate. To inspect features across all modules, query
    *   `map.mapLibreMap.queryRenderedFeatures(...)` directly, as {@link UserEventHandler} shows.
    *
    * Note that:
@@ -3104,24 +3337,23 @@ export declare class UserEvents<T = MapGeoJSONFeature, WHERE_SCOPE = never> {
   /**
    * Removes all event handlers for an event type.
    *
-   * This stops further event notifications for that type. Clean up this way to prevent memory
-   * leaks and unwanted behaviour.
+   * This stops further event notifications for that type, from every handler of it.
    *
    * @param type The event type to stop listening for.
    *
    * @remarks
-   * - It removes **all** of this module's handlers for the event type on the features these events
+   * - It removes **all** of this module's handlers for the event type on the sources these events
    *   cover, whichever of the module's events objects registered them. So
    *   `places.events.places.off('click')` also takes a `places.events.on('click', …)` handler off the
    *   pins, while that handler keeps firing on connections.
-   * - To remove a single handler, call the unsubscribe function {@link on} returns.
+   * - To remove a single handler, call the unsubscribe function {@link on} returns. That is how a
+   *   component cleans up on unmount, since `off` also removes the handlers other code put on the
+   *   module, such as a plugin's.
    * - Other event types and other modules' handlers stay active. It also resets this module's cursor
    *   behaviour, and you can safely call it more than once, even when no handler exists.
    *
-   * Always call it when a component unmounts, ideally from a framework lifecycle hook. Also use it
-   * to switch between interaction modes, to disable interactions temporarily, or to replace a
-   * handler by calling `off()` and then `on()`. Remove handlers before you remove features from
-   * the map.
+   * Use it to switch between interaction modes, to disable interactions temporarily, or to replace
+   * a handler by calling `off()` and then `on()`.
    *
    * @example
    * ```typescript
@@ -3143,14 +3375,13 @@ export declare class UserEvents<T = MapGeoJSONFeature, WHERE_SCOPE = never> {
    * ```typescript
    * // React component cleanup, with `pois` from `await POIsModule.get(map)`
    * useEffect(() => {
-   *   pois.events.on('click', handlePoiClick);
-   *   pois.events.on('hover', handlePoiHover);
-   *
-   *   return () => {
-   *     // Cleanup on unmount
-   *     pois.events.off('click');
-   *     pois.events.off('hover');
-   *   };
+   *   const unsubscribes = [
+   *     pois.events.on('click', handlePoiClick),
+   *     pois.events.on('hover', handlePoiHover),
+   *   ];
+   *
+   *   // Cleanup on unmount, leaving other code's handlers in place
+   *   return () => unsubscribes.forEach((unsubscribe) => unsubscribe());
    * }, [pois]);
    * ```
    *
@@ -3220,7 +3451,6 @@ export declare class CustomLayer<HIT extends CustomLayerHit = CustomLayerHit> {
    * Takes the layer off the map, stops placing it after style changes, and drops its event handlers.
    */
   remove(): void;
-  private placeOnceReady;
   private place;
   private anchorLayerID;
 }
@@ -3306,7 +3536,13 @@ type StylingFoundationsKnob = KnobEntry<StylingFoundationsKnobId, StylingFoundat
  * @group Map Styling
  */
 type StylingFoundationsModuleConfig = MapModuleCommonConfig & KnobConfigOf<{ [ID in StylingFoundationsKnobId]: StylingFoundationsKnobValueOf<ID>; }> & {
-  labels?: Pick<LabelConfig, 'customTypeface'>;
+  labels?: {
+    /**
+     * A typeface of your own font files for every map label, which the SDK's own labels follow
+     * unless their module sets a typeface of its own. While set, it wins over the `labels.typeface` knob.
+     */
+    customTypeface?: NonNullable<LabelConfig['customTypeface']>;
+  };
 };
 //#endregion
 //#region src/styling/knobCatalogue.d.ts
@@ -3322,7 +3558,6 @@ type KnobDefinitionOf<KIND extends StylingFoundationsKnobKind> = Omit<KnobEntry<
  *
  * Ids are public API — additive only. Ranges follow the validated grammar of TomTom's style editor (factors
  * 0.5–1.5 in 0.1 steps) so a value that looks right in the designer's tool looks right here.
- * @ignore
  */
 declare const knobDefinitions: {
   readonly 'colors.accent': {
@@ -3575,10 +3810,10 @@ export type BaseMapLayerGroupName = (typeof baseMapLayerGroupNames)[number];
  *
  * @example
  * ```typescript
- * // Show only roads and borders
+ * // Roads and borders alone
  * const roadsOnly: BaseMapLayerGroups = { show: 'only', values: ['roads', 'roadLabels', 'borders'] };
  *
- * // Show everything except buildings
+ * // Everything but the buildings
  * const noBuildings: BaseMapLayerGroups = { show: 'all-except', values: ['buildings2D', 'buildings3D'] };
  * ```
  *
@@ -3587,8 +3822,8 @@ export type BaseMapLayerGroupName = (typeof baseMapLayerGroupNames)[number];
 export type BaseMapLayerGroups = ValuesFilter<BaseMapLayerGroupName>;
 /**
  * The road parts {@link BaseMapModule} shows or hides on their own, finer than the layer groups.
- * TomTom's style designers chose this granularity as toggle-worthy. An unset part is drawn as the
- * style ships it.
+ * TomTom's style designers chose this granularity as toggle-worthy. An unset part follows its group,
+ * and is drawn as the style ships it while nothing sets the group or `visible`.
  *
  * @group Base Map
  */
@@ -3610,6 +3845,44 @@ export type BaseMapRoadsConfig = {
     visible?: boolean;
   };
 };
+/**
+ * How far a 3D building under one event state turns towards a colour.
+ *
+ * @group Base Map
+ */
+export type BaseMapBuildingStateLook = {
+  /** The colour the building turns towards, as a CSS colour. Unset, the building stays as drawn. */
+  color?: string;
+  /** How far it turns, 0 (not at all) to 1 (fully). */
+  intensity?: number;
+};
+/**
+ * How the base map's 3D buildings look while hovered or clicked.
+ *
+ * @remarks
+ * A building takes the event state while a handler of {@link BaseMapModule.events} reaches it, such
+ * as one scoped to the `buildings3D` layer group. The click state stays until the next click lands
+ * elsewhere.
+ *
+ * @example
+ * ```typescript
+ * const baseMap = await BaseMapModule.get(map, {
+ *   groups: { buildings3D: { visible: true } },
+ *   buildings3D: { hover: { color: '#f3a712' }, click: { color: '#e4572e', intensity: 0.8 } },
+ * });
+ * baseMap.events
+ *   .where({ layerGroups: { show: 'only', values: ['buildings3D'] } })
+ *   .on('click', (building) => console.log(building.id, building.properties));
+ * ```
+ *
+ * @group Base Map
+ */
+export type BaseMapBuildings3DConfig = {
+  /** The hovered building. Its intensity is `0.35` when unset. */
+  hover?: BaseMapBuildingStateLook;
+  /** The clicked building. Its intensity is `0.7` when unset. */
+  click?: BaseMapBuildingStateLook;
+};
 /**
  * The configuration of the BaseMapModule, at initialization or at runtime.
  *
@@ -3665,6 +3938,10 @@ export type BaseMapModuleConfig = MapModuleCommonConfig & {
    * The visibility of road parts on their own. A part never shows while its group is hidden.
    */
   roads?: BaseMapRoadsConfig;
+  /**
+   * How the 3D buildings look while hovered or clicked. Their visibility is `groups.buildings3D`.
+   */
+  buildings3D?: BaseMapBuildings3DConfig;
 };
 //#endregion
 //#region src/styling/styleLayerGroups.d.ts
@@ -3806,6 +4083,7 @@ export declare class LayerSelection {
   /**
    * Replaces the filter the style gave every matched layer. The filters other modules add, such as
    * POI categories and traffic filters, still narrow it, and so do the clauses of {@link addFilterClause}.
+   * `undefined` draws the layers unfiltered; {@link reset} gives them the style's filter back.
    */
   setFilter(filter: FilterSpecification | undefined): this;
   /**
@@ -3849,6 +4127,7 @@ declare class LayerOverrides {
   private readonly filters;
   private readonly clauses;
   private readonly visibility;
+  private contributed;
   constructor(mapLibreMap: Map$1, filterComposer: LayerFilterComposer, visibilityComposer: LayerVisibilityComposer, warn: (key: string, message: string) => void);
   /**
    * Points the registry at the loaded style; overrides are kept and re-applied by {@link reapply}.
@@ -3856,22 +4135,31 @@ declare class LayerOverrides {
    * the style already loaded does, so what they replaced still holds.
    */
   index(layers: LayerSpecification[], sources: StyleSources, newStyle: boolean): void;
-  /** Forgets every override (a clean style switch, which also clears the filter composer). */
-  clear(): void;
+  /**
+   * Forgets every override (a clean style switch).
+   * `layersKept` is true when MapLibre kept the layers the overrides were made on, as a `setStyle` to
+   * the style already loaded does: what the paint and layout overrides replaced is written back first,
+   * where the layer still holds the edit, and the filters, clauses and visibility leave the composers,
+   * which drop contributions only on a new style. Elsewhere a reset ran first, such as the style knobs'.
+   */
+  clear(layersKept: boolean): void;
   resolve(query: LayerQuery): string[];
-  override(query: LayerQuery, override: PropertyOverride): void;
+  override(query: LayerQuery, overrides: PropertyOverride[]): void;
   addFilterClause(query: LayerQuery, clause: ExpressionFilterSpecification): void;
   removeFilterClause(query: LayerQuery, clause: ExpressionFilterSpecification): void;
   overrideFilter(query: LayerQuery, filter: FilterSpecification | undefined): void;
   overrideVisibility(query: LayerQuery, visible: boolean): void;
   reset(query: LayerQuery): void;
   /**
-   * Lands every override again on top of the current style, a derivation worked out again from the
-   * value it replaces. That value is re-read after a new style is indexed, even where that style's own
-   * value equals the override, and else only where a knob wrote under it since; a layer still
-   * carrying the override keeps the value it replaced.
+   * Lands every override again on top of the current style where the value it replaces moved, a
+   * derivation worked out again from it. That value is re-read after a new style is indexed, even where
+   * that style's own value equals the override, and else only where a knob wrote under it since; a
+   * layer still carrying the override is left as it is. The filters, clauses and visibility go back to
+   * the composers once per indexed style.
    */
   reapply(): void;
+  private withdrawFromKeptLayers;
+  private landOrWarn;
   private resolveToEdit;
   private read;
   private land;
@@ -3886,7 +4174,7 @@ declare class LayerOverrides {
  *
  * | Name | Theme label | Reaches |
  * |---|---|---|
- * | `land` | Land (base) | Map background and other bare-land features. On the mono styles, every map colour left unset derives from it, borders and labels included. |
+ * | `land` | Land (base) | Map background and other bare-land features. On the mono styles, every map colour left unset derives from it, borders and labels included, and `roadMajor` and `roadOutline` from a given `road` too. |
  * | `water` | Water | Waterbodies, waterways and other water features. Also influences glaciers, water labels and ferry lines. |
  * | `vegetation` | Vegetation | Forests and other land cover such as grass and shrubland. Also influences earth cover vegetation at smaller scales. |
  * | `park` | Park & Recreation | City parks and sport/recreation grounds. Also influences National Parks and other protected areas at smaller scales. |
@@ -3905,6 +4193,8 @@ declare class LayerOverrides {
 type MapColorName = 'land' | 'water' | 'vegetation' | 'park' | 'artificial' | 'roadMajor' | 'road' | 'roadOutline' | 'label' | 'labelHalo' | 'accent';
 /**
  * The colours that recolour base-map layers, which are every {@link MapColorName} but `accent`.
+ *
+ * @group Map Styling
  */
 type BaseMapColorName = Exclude<MapColorName, 'accent'>;
 /**
@@ -3926,6 +4216,8 @@ type MapColors = Partial<Record<MapColorName, string>>;
 type PaintColorProperty = 'fill-color' | 'fill-outline-color' | 'line-color' | 'text-color' | 'text-halo-color' | 'fill-extrusion-color' | 'background-color' | 'hillshade-shadow-color' | 'hillshade-highlight-color' | 'hillshade-accent-color';
 /**
  * Every {@link BaseMapColorName}, in the themes' Foundations order, to build a base-map colour picker from.
+ *
+ * @group Map Styling
  */
 export declare const baseMapColorNames: readonly BaseMapColorName[];
 /**
@@ -3934,6 +4226,58 @@ export declare const baseMapColorNames: readonly BaseMapColorName[];
  * @group Map Styling
  */
 export declare const mapColorNames: readonly MapColorName[];
+/**
+ * Whether a caller-supplied key names one of the map colours.
+ * @ignore
+ */
+export declare const isMapColorName: (name: string) => name is MapColorName;
+/**
+ * The id of a map colour's knob.
+ * @ignore
+ */
+export declare const mapColorKnobId: <NAME extends MapColorName>(name: NAME) => `colors.${NAME}`;
+//#endregion
+//#region src/styling/mapLight.d.ts
+/**
+ * Where the map's light comes from, as a compass: the light the styling module's `view.light.*` knobs
+ * set, which the 3D buildings of the style and the plugins drawing their own lit surfaces share.
+ *
+ * @group Map Styling
+ */
+type MapLight = {
+  /**
+   * The compass direction the light comes from, in degrees clockwise from north, whatever the map's
+   * bearing.
+   */
+  direction: number;
+  /**
+   * How high the light stands, in degrees above the horizon: 90 is straight overhead.
+   */
+  altitude: number;
+};
+/**
+ * Gets where the map's light comes from right now, so a layer drawing its own lit surfaces can share
+ * it. A light aligned with the viewport turns with the map, so read it again after the camera moves.
+ *
+ * @remarks
+ * The standard styles place no light of their own, so this returns `undefined` until one is set,
+ * through the styling module's `view.light.direction` or `view.light.altitude` knob, MapLibre's
+ * `setLight`, or a style that declares a light. The 3D buildings and the textured surfaces of the
+ * landmarks-3d plugin follow it while their own light knobs are unset.
+ *
+ * @returns The light's direction and altitude, or `undefined` while the map has no light placed, or
+ * places it with an expression, such as one that moves it with the zoom, that no one direction
+ * stands for. The plugins then light their surfaces from their presets.
+ *
+ * @example
+ * ```typescript
+ * await StylingFoundationsModule.get(map, { view: { light: { direction: 250, altitude: 20 } } });
+ * const light = getMapLight(map); // { direction: 250, altitude: 20 } at bearing 0
+ * ```
+ *
+ * @group Map Styling
+ */
+export declare const getMapLight: (map: TomTomMap) => MapLight | undefined;
 //#endregion
 //#region src/shared/knobs.d.ts
 /**
@@ -3944,16 +4288,17 @@ export declare const mapColorNames: readonly MapColorName[];
  * learned one catalogue can read the other.
  *
  * - `toggle`: `true`/`false`, e.g. whether an overlay is drawn.
- * - `factor`: a multiplier over what the style already does (`1` = unchanged).
+ * - `factor`: a multiplier over the default, the style's or the module's own (`1` = unchanged).
  * - `number`: an absolute number with a range.
- * - `offset`: an `[x, y]` displacement on screen, x to the right and y down, each within the
- *   knob's range. The description gives the unit.
- * - `color`: a CSS colour string.
+ * - `offset`: an `[x, y]` displacement on screen, x to the right and y down, each checked against
+ *   the knob's range as far as its `bounds` say. The description gives the unit.
+ * - `color`: a CSS colour in hex, `rgb()`, `hsl()` or a colour name, the syntaxes a map style paints.
  * - `enum`: one of the knob's `options`.
  * - `enums`: a list of the knob's `options`, e.g. the categories a filter shows. The description
  *   says when the order matters.
- * - `colors`: a list of colours, each a CSS colour string or one of the knob's `options`, which
- *   are names the module resolves to colours, such as styling knob ids. An empty list is the knob's default.
+ * - `colors`: a list of colours, each a `color` knob's value or one of the knob's `options`, which
+ *   are names the module resolves to colours, such as styling knob ids. The description says what an
+ *   empty list does.
  * - `image`: the id of an image in the loaded style's sprite, e.g. `poi-toll_plaza`.
  * - `text`: any string, e.g. the label written after a distance.
  * @group Shared
@@ -4054,12 +4399,13 @@ type ValuesFilterKnobId<PATH extends string> = `${PATH}.${keyof ValuesFilter<unk
  * `groups.water.visible`. See {@link baseMapKnobCatalogue} for what each one does.
  *
  * @remarks
- * Every {@link BaseMapLayerGroupName} contributes one `groups.<group>.visible` id, and every road
- * part of {@link BaseMapRoadsConfig} one `roads.<part>.visible` id.
+ * Every {@link BaseMapLayerGroupName} contributes one `groups.<group>.visible` id, every road
+ * part of {@link BaseMapRoadsConfig} one `roads.<part>.visible` id, and the hover and click looks
+ * of {@link BaseMapBuildings3DConfig} a `color` and an `intensity` id each.
  *
  * @group Base Map
  */
-type BaseMapKnobId = 'visible' | `groups.${BaseMapLayerGroupName}.visible` | `roads.${keyof BaseMapRoadsConfig}.visible`;
+type BaseMapKnobId = 'visible' | `groups.${BaseMapLayerGroupName}.visible` | `roads.${keyof BaseMapRoadsConfig}.visible` | `buildings3D.${keyof BaseMapBuildings3DConfig}.${keyof BaseMapBuildingStateLook}`;
 /**
  * The value type of a base-map knob, the plain value its path holds in {@link BaseMapModuleConfig}.
  *
@@ -4068,12 +4414,13 @@ type BaseMapKnobId = 'visible' | `groups.${BaseMapLayerGroupName}.visible` | `ro
 type BaseMapKnobValueOf<ID extends BaseMapKnobId> = KnobPlainValue<ValueAt<BaseMapModuleConfig, ID>>;
 /**
  * One entry of {@link baseMapKnobCatalogue}. The value in force is the one at its path in
- * {@link BaseMapModule.getConfig}. Without one, the style decides. For a road part, {@link getKnob}
- * reports whether the style ships it shown.
+ * {@link BaseMapModule.getConfig}. Without one, its layers follow `visible` and any other group that
+ * reaches them, and the style where nothing does. For a road part, {@link getKnob} reports whether the
+ * style ships it shown.
  *
  * @group Base Map
  */
-type BaseMapKnob = KnobEntry<BaseMapKnobId, 'toggle'>;
+type BaseMapKnob = KnobEntry<BaseMapKnobId, 'toggle' | 'color' | 'number'>;
 //#endregion
 //#region src/pois/util/poiCategoryMapping.d.ts
 /**
@@ -4104,13 +4451,15 @@ type MapStylePOICategory = POICategory;
  * - `circle-icon` - Simple circular markers.
  * - `base-map` - Mimics the map's built-in POI layer style with category icons, combining the `main`,
  *   `selected` and `micro` layers. To render only `micro`, hide `main` with
- *   `layers.main.layout.visibility = 'none'`.
+ *   `layers.main.layout.visibility = 'none'`. `main` starts at zoom 10, so below it the places not
+ *   hovered or clicked draw only as `micro` dots; `layers.main.minzoom` lowers that floor.
  * - `pin-clustered` - The same teardrop pins as `pin` for unclustered places, with nearby
  *   places aggregated into a single icon. A single-category cluster shows the matching
  *   base-map POI sprite with a small count badge in the top-right. A mixed-category
  *   cluster shows a larger centred count circle instead of the icon. Cluster features
  *   expose `clusterBaseMapIconIDs` (comma-separated, deduplicated) on their properties.
- *   {@link PlacesModuleConfig.cluster} configures both.
+ *   {@link PlacesModuleConfig.cluster} configures both. The `micro` layer also draws every place,
+ *   clustered or not, as a base-map micro dot.
  *
  * @group Places
  */
@@ -4312,8 +4661,8 @@ type PlaceLayersConfig = {
    * The main place marker layer specification.
    *
    * @remarks
-   * It sets the look of all place markers on the map, and renders places
-   * that are not highlighted or selected.
+   * It sets the look of the places that are not highlighted or selected. The `selected`
+   * layer draws those, and takes its own override.
    */
   main?: Partial<ToBeAddedLayerSpecTemplate<SymbolLayerSpecification>>;
   /**
@@ -4335,7 +4684,7 @@ type PlaceLayersConfig = {
    * It sets the look of places when they are highlighted or selected, such as on hover
    * or click. It renders on top of the main layer, so selected places are always visible.
    *
-   * This layer reacts to 'hover' and 'click' event states.
+   * This layer draws the places in any event state but `recently-hovered`.
    */
   selected?: Partial<ToBeAddedLayerSpecTemplate<SymbolLayerSpecification>>;
   /**
@@ -4377,8 +4726,8 @@ type PlaceLayersConfig = {
    * @remarks
    * It replaces the cluster icon entirely when a cluster spans multiple POI
    * categories. The count circle takes the centre, with {@link clusterMixedCount}
-   * rendered on top. Its filter checks for "all clusters with a mixed
-   * dedup-concat", so single-category clusters use {@link cluster} and
+   * rendered on top. It draws only the clusters whose places span more than one
+   * category, so single-category clusters use {@link cluster} and
    * {@link clusterBadge} instead.
    */
   clusterMixedBadge?: Partial<ToBeAddedLayerSpecTemplate<CircleLayerSpecification>>;
@@ -4532,7 +4881,8 @@ type PlaceConnectionLabelConfig = {
  * Appearance of the cluster count badge under the `pin-clustered` marker type.
  *
  * @remarks
- * Each field applies to single-category and mixed-category clusters alike. The matching
+ * Each field applies to single-category and mixed-category clusters alike, but for `radius`, set
+ * per kind, and `offset`, which mixed-category clusters ignore. The matching
  * {@link PlaceLayersConfig} entry (`clusterBadge`, `clusterCount`, `clusterMixedBadge`,
  * `clusterMixedCount`) overrides it for the paint and layout properties it names.
  *
@@ -4652,7 +5002,7 @@ type PlacesClusterConfig = {
  */
 type PlacesClusterSourceConfig = {
   /**
-   * How near places merge into one cluster, in pixels.
+   * How near places merge into one cluster, in pixels. MapLibre reads `0` as `50`.
    *
    * @default 60
    */
@@ -4660,6 +5010,10 @@ type PlacesClusterSourceConfig = {
   /**
    * Highest zoom that clusters places; past it every place is drawn on its own.
    *
+   * @remarks
+   * Takes `1` to `17`. MapLibre reads `0` as `17`, and its place data stops at zoom 18, so `18` or
+   * more never splits a cluster.
+   *
    * @default 17
    */
   maxZoom?: number;
@@ -4702,8 +5056,8 @@ type PlaceEntryPointsShowFor = 'all' | 'selected' | 'clicked';
  *
  * @remarks
  * Each layer ID derives from the PlacesModule instance prefix:
- * - `point` - A circle on each entry point, larger for a `main` one than for the rest.
- * - `line` - A dotted line from the place to each of its entry points.
+ * - `point` - `<prefix>-entry-point`, a circle on each entry point, larger for a `main` one than for the rest.
+ * - `line` - `<prefix>-entry-point-line`, a dotted line from the place to each of its entry points.
  *
  * @group Places
  */
@@ -4800,7 +5154,7 @@ type PlacesBeforeLayerConfig = PartsBeforeLayerConfig<'places' | 'connections'>;
  * };
  *
  * // Advanced configuration with custom properties
- * const config: PlacesModuleConfig = {
+ * const baseMapConfig: PlacesModuleConfig = {
  *   markerType: 'base-map',
  *   icon: {
  *     categoryIcons: [
@@ -4831,7 +5185,7 @@ type PlacesModuleConfig<P extends CommonPlaceProps = CommonPlaceProps> = MapModu
    *
    * @remarks
    * {@link PlaceIconConfig.categoryIcons} replace its icon for the categories they name, under
-   * every marker type.
+   * every marker type. The `micro` dots and the `pin-clustered` cluster pin keep the style's sprites.
    *
    * @default 'pin'
    */
@@ -5059,7 +5413,7 @@ export declare const placesKnobIds: readonly PlacesKnobId[];
  *   the main layer's `icon-image` expression binds to with `['get', 'iconID']`.
  *   The base map's POI-Micro-like layer inherits the style's `['get','group']`
  *   expression verbatim, so custom `PlaceIconConfig.categoryIcons` sprites apply
- *   only to the `main` layer.
+ *   only to the `main` and `selected` layers.
  * - The `base-map` and `pin-clustered` marker types also populate
  *   {@link PlaceDisplayProps.category | category} and
  *   {@link PlaceDisplayProps.group | group}, so the base map style's own
@@ -5092,9 +5446,9 @@ export type PlaceDisplayProps = {
    * The unique ID of the place feature.
    *
    * @remarks
-   * MapLibre doesn't reuse the feature IDs, so the SDK either generates one on the
-   * fly or promotes `properties.id` with the source's `promoteId` option. It
-   * identifies the feature in events, hit-testing and data updates.
+   * The place's own `id`, or one the SDK generates when it has none. The SDK copies it to
+   * `properties.id`, which identifies the feature on every source, clustered ones included, in
+   * events, hit-testing and data updates.
    *
    * @example
    * ```typescript
@@ -5128,7 +5482,7 @@ export type PlaceDisplayProps = {
    *   sprite, so its ID carries that sprite's namespace.
    * - `circle-icon` and `base-map` pick the base map's `poi-<category>` image.
    * - A custom `PlaceIconConfig.categoryIcons` entry overrides the default for
-   *   the main layer on any marker type.
+   *   the main and selected layers on any marker type.
    *
    * @example
    * ```typescript
@@ -5143,9 +5497,8 @@ export type PlaceDisplayProps = {
    *
    * @remarks
    * Populated only for the `base-map` and `pin-clustered` marker types. Values are the lowercased
-   * IDs the base map style uses, derived with {@link toBaseMapPOICategory}. It
-   * drives the inherited `text-color` expression on the main and selected
-   * POI-like layers.
+   * IDs the base map style uses, derived from the place's POI category. The style expressions the
+   * POI-like layers inherit read it, such as their `text-color`.
    *
    * @example
    * ```typescript
@@ -5159,9 +5512,9 @@ export type PlaceDisplayProps = {
    * The base map style POI group the place belongs to.
    *
    * @remarks
-   * Populated only for the `base-map` and `pin-clustered` marker types. It drives the inherited
-   * `text-color` expression on the base map's POI layers.
-   * Valid values are those {@link toBaseMapPOIGroup} produces, such as
+   * Populated only for the `base-map` and `pin-clustered` marker types. The style expressions the
+   * POI-like layers inherit read it, such as their `text-color` and the `POI - Micro` `icon-image`.
+   * Values are the base map style's groups, such as
    * `eat_and_drink`, `lodging`, `driving`, `transport`, `shopping`,
    * `healthcare`, `finance`, `cultural`, `leisure`, `sport`, `outdoor`,
    * `protected`, `public`, `religion`, `military`, `business`, `education`,
@@ -5181,8 +5534,10 @@ export type PlaceDisplayProps = {
  *   poi: {
  *     name: 'Central Station',
  *     categories: ['RAILWAY_STATION'],
+ *     localizedCategories: ['railway station'],
  *   },
  *   address: {
+ *     freeformAddress: 'Stationsplein, 1012 AB Amsterdam',
  *     streetName: 'Damrak',
  *     municipalitySubdivision: 'Amsterdam',
  *     countryCode: 'NL',
@@ -5245,8 +5600,8 @@ type PlaceEntryPointFeature = Feature<Point, PlaceEntryPointProps & {
  */
 type ConnectionFeatureProps = {
   id: string;
-  fromId?: string;
-  toId?: string;
+  fromId: string;
+  toId: string;
   label: string;
 } & SupportsEvents;
 /**
@@ -5325,7 +5680,7 @@ export type PlacesEvents = CombinedEvents<MapGeoJSONFeature, PlacesModuleConfig,
    * `cluster: true`, `cluster_id` and `point_count` in its properties.
    */
   places: UserEventsWithStates<Place<DisplayPlaceProps>>;
-  /** The lines and labels connecting places to their parent, when connections are shown. */
+  /** The lines and labels between pairs of places, when connections are shown. */
   connections: UserEventsWithStates<MapGeoJSONFeature>;
   /** The entry points of places, when {@link PlacesModuleConfig.entryPoints} draws them. */
   entryPoints: UserEventsWithStates<PlaceEntryPointFeature>;
@@ -5370,12 +5725,12 @@ export type PlacesEvents = CombinedEvents<MapGeoJSONFeature, PlacesModuleConfig,
  * // Display places from search
  * await placesModule.show(searchResults);
  *
- * // Handle clicks
- * placesModule.events.on('click', (feature) => {
+ * // Handle clicks on places, leaving out clusters, connections and entry points
+ * placesModule.events.places.on('click', (feature) => {
  *   console.log('Clicked:', feature.properties);
  * });
  *
- * placesModule.events.on('hover', (feature) => {
+ * placesModule.events.places.on('hover', (feature) => {
  *   showTooltip(feature.properties.poi?.name);
  * });
  * ```
@@ -5388,7 +5743,7 @@ export declare class PlacesModule extends AbstractDataOwnedMapModule<PlacesSourc
   private layerSpecs;
   private connectionLayerSpecs;
   private entryPointLayerSpecs;
-  private refreshingEntryPoints;
+  private entryPointsRefreshHeld;
   private currentClusterOptions?;
   private sourceID;
   private unclusteredSourceID;
@@ -5469,8 +5824,11 @@ export declare class PlacesModule extends AbstractDataOwnedMapModule<PlacesSourc
   private showPlaces;
   private updateConnectionsData;
   private updateEntryPointsData;
+  private withoutEntryPointsRefresh;
   private applyVisibilityTo;
   private applyPlacesVisibility;
+  private applyConnectionsVisibility;
+  private applyEntryPointsVisibility;
   private setupImages;
   private updateData;
   /**
@@ -5487,13 +5845,13 @@ export declare class PlacesModule extends AbstractDataOwnedMapModule<PlacesSourc
    *   Places that carry `properties.eventState`, such as `getShown().places`, keep theirs.
    * - Drops the shown connections (see {@link PlaceConnectionDisplay}).
    * - Applies the current module styling configuration.
-   * - Generates labels if the label config is set.
+   * - Labels each place with its title, which `label.title` replaces.
    * - Waits for the module to be ready before displaying.
    *
    * Data sources:
    * - TomTom Search API results
    * - Custom place objects matching the Place interface
-   * - GeoJSON Point features
+   * - GeoJSON Point features with an `id` and a `properties.type`
    *
    * {@link ShownPlaces} names the places services whose results are not places, and what shows them.
    *
@@ -5511,10 +5869,16 @@ export declare class PlacesModule extends AbstractDataOwnedMapModule<PlacesSourc
    * ```typescript
    * await placesModule.show({
    *   type: 'Feature',
+   *   id: 'amsterdam-central',
    *   geometry: { type: 'Point', coordinates: [4.9041, 52.3676] },
    *   properties: {
+   *     type: 'POI',
    *     address: { freeformAddress: 'Amsterdam' },
-   *     poi: { name: 'Amsterdam Central' }
+   *     poi: {
+   *       name: 'Amsterdam Central',
+   *       categories: ['RAILWAY_STATION'],
+   *       localizedCategories: ['railway station']
+   *     }
    *   }
    * });
    * ```
@@ -5563,7 +5927,7 @@ export declare class PlacesModule extends AbstractDataOwnedMapModule<PlacesSourc
    *     label: { title: (c) => `${c.distanceMeters} m` }
    *   }
    * });
-   * await places.show([station, ...cafes]);
+   * await places.show([station, ...cafes.features]);
    * await places.showConnections(
    *   cafes.features.map((cafe) => ({
    *     from: station.id,
@@ -5611,8 +5975,8 @@ export declare class PlacesModule extends AbstractDataOwnedMapModule<PlacesSourc
 //#endregion
 //#region src/places/utils/preparePlacesForDisplay.d.ts
 /**
- * Returns the POI name, otherwise the free-form address, as the label {@link PlacesModule} gives a
- * place when {@link PlaceLabelConfig.title} is not a function.
+ * Returns the POI name, otherwise the free-form address, otherwise an empty string, as the label
+ * {@link PlacesModule} gives a place when {@link PlaceLabelConfig.title} is not a function.
  *
  * @example
  * ```typescript
@@ -5738,21 +6102,6 @@ export declare const poiCategoryGroups: {
  * Each group contains multiple {@link MapStylePOICategory} values that share a common theme.
  * With a group, a single filter value shows or hides multiple related POI types.
  *
- * Available groups:
- * - `FOOD_DRINKS_GROUP` - Restaurants, cafes, fast food, wineries, etc.
- * - `SHOPPING_GROUP` - Stores, malls, markets, supermarkets, etc.
- * - `TRANSPORTATION_GROUP` - Airports, train stations, bus stops, ferry terminals, etc.
- * - `HEALTH_GROUP` - Hospitals, clinics, pharmacies, doctors, dentists, etc.
- * - `PARKING_GROUP` - Parking garages and open parking areas
- * - `HOLIDAY_TOURISM_GROUP` - Tourist attractions, museums, beaches, scenic views, etc.
- * - `EV_CHARGING_STATIONS_GROUP` - Electric vehicle charging stations
- * - `GAS_STATIONS_GROUP` - Gas and petrol stations
- * - `ACCOMMODATION_GROUP` - Hotels, motels, camping grounds, etc.
- * - `ENTERTAINMENT_GROUP` - Cinemas, theaters, nightlife, casinos, etc.
- * - `SPORTS_LEISURE_GROUP` - Stadiums, sports centers, swimming pools, golf courses, etc.
- * - `EDUCATION_GROUP` - Schools, universities, libraries, cultural centers
- * - `GOVERNMENT_GROUP` - Government offices, courthouses, embassies, police, fire stations
- *
  * @example
  * Filter to show only food-related POIs:
  * ```ts
@@ -5815,7 +6164,8 @@ type POIIconConfig = {
    * - The map style knows fewer categories than search does. `CAFE` and `CAFE_PUB` are one category
    *   on the map, so an entry for either reaches both POIs, and the first entry listed wins.
    * - The image is scaled with the style's own icons, `sizeFactor` included, so one the size
-   *   of a style POI icon keeps the map's density. `offsetX` and `offsetY` move it.
+   *   of a style POI icon keeps the map's density. A non-zero `offsetX` or `offsetY` replaces the
+   *   style's own icon offset; without one, the image takes the style's.
    * - Entries without an `image` change no POI.
    * - The micro markers of minor POIs keep the style's dots.
    */
@@ -6066,74 +6416,57 @@ type PresetDefinition = {
  * The map presets the SDK ships: named bundles of knob settings for common intents, across the
  * modules that hold the look of the map. Each is data over the knob catalogues, so a preset is
  * exactly as durable as the knobs it sets, and an app can start from one and adjust.
- * @ignore
  */
-declare const mapPresets: {
+declare const presetSettings: {
   readonly 'data-viz': {
-    readonly name: "Data visualisation";
-    readonly description: "A quiet base for your own data on top: smaller labels, fewer markers, thinner roads, no badges competing with the overlay.";
-    readonly settings: {
-      readonly stylingFoundations: {
-        readonly 'labels.sizeFactor': 0.9;
-        readonly 'symbols.sizeFactor': 0.9;
-        readonly 'roads.widthFactor': 0.8;
-      };
-      readonly baseMap: {
-        readonly 'roads.exitNumbers.visible': false;
-        readonly 'roads.arrows.visible': false;
-      };
-      readonly pois: {
-        readonly 'microMarkers.visible': false;
-        readonly minZoom: 14;
-      };
+    readonly stylingFoundations: {
+      readonly 'labels.sizeFactor': 0.9;
+      readonly 'symbols.sizeFactor': 0.9;
+      readonly 'roads.widthFactor': 0.8;
+    };
+    readonly baseMap: {
+      readonly 'roads.exitNumbers.visible': false;
+      readonly 'roads.arrows.visible': false;
+    };
+    readonly pois: {
+      readonly 'microMarkers.visible': false;
+      readonly minZoom: 14;
     };
   };
   readonly 'night-driving': {
-    readonly name: "Night driving";
-    readonly description: "Bigger labels and shields, wider roads, POIs out of the way until close up.";
-    readonly settings: {
-      readonly stylingFoundations: {
-        readonly 'labels.sizeFactor': 1.2;
-        readonly 'symbols.sizeFactor': 1.2;
-        readonly 'roads.widthFactor': 1.2;
-      };
-      readonly baseMap: {
-        readonly 'roads.exitNumbers.visible': true;
-        readonly 'roads.arrows.visible': true;
-      };
-      readonly pois: {
-        readonly 'microMarkers.visible': false;
-        readonly minZoom: 13;
-      };
+    readonly stylingFoundations: {
+      readonly 'labels.sizeFactor': 1.2;
+      readonly 'symbols.sizeFactor': 1.2;
+      readonly 'roads.widthFactor': 1.2;
+    };
+    readonly baseMap: {
+      readonly 'roads.exitNumbers.visible': true;
+      readonly 'roads.arrows.visible': true;
+    };
+    readonly pois: {
+      readonly 'microMarkers.visible': false;
+      readonly minZoom: 13;
     };
   };
   readonly minimal: {
-    readonly name: "Minimal";
-    readonly description: "The bare map: smaller labels, no road markings, exit badges or POI dots until close up. Hide buildings and shields with BaseMapModule.";
-    readonly settings: {
-      readonly stylingFoundations: {
-        readonly 'labels.sizeFactor': 0.9;
-      };
-      readonly baseMap: {
-        readonly 'roads.exitNumbers.visible': false;
-        readonly 'roads.arrows.visible': false;
-        readonly 'roads.restricted.visible': false;
-        readonly 'roads.underConstruction.visible': false;
-      };
-      readonly pois: {
-        readonly 'microMarkers.visible': false;
-        readonly minZoom: 16;
-      };
+    readonly stylingFoundations: {
+      readonly 'labels.sizeFactor': 0.9;
+    };
+    readonly baseMap: {
+      readonly 'roads.exitNumbers.visible': false;
+      readonly 'roads.arrows.visible': false;
+      readonly 'roads.restricted.visible': false;
+      readonly 'roads.underConstruction.visible': false;
+    };
+    readonly pois: {
+      readonly 'microMarkers.visible': false;
+      readonly minZoom: 16;
     };
   };
   readonly globe: {
-    readonly name: "Globe";
-    readonly description: "A globe with an atmosphere for the zoomed-out view; flattens to Mercator as you zoom in.";
-    readonly settings: {
-      readonly stylingFoundations: {
-        readonly 'view.projection': "globe";
-        readonly 'view.sky.visible': true;
-      };
+    readonly stylingFoundations: {
+      readonly 'view.projection': "globe";
+      readonly 'view.sky.visible': true;
     };
   };
 };
@@ -6142,7 +6475,7 @@ declare const mapPresets: {
  *
  * @group Map Styling
  */
-type MapPresetId = keyof typeof mapPresets;
+type MapPresetId = keyof typeof presetSettings;
 /**
  * A named bundle of knob settings, TomTom's cartographic opinions in code, across the modules that
  * hold the look of the map. Apply one with {@link applyMapPreset}.
@@ -6212,9 +6545,12 @@ export type StylingFoundationsEvents = CombinedEvents<MapGeoJSONFeature, Styling
  * @remarks
  * The catalogue's `appliesTo` says which styles a knob works on. `any-style` knobs (sizes, widths)
  * scale whatever the style already does, so they survive style-version bumps. A zoom ramp has each
- * stop's output scaled, and any other expression `E` becomes `["*", 1.3, E]`. `tomtom-styles` knobs
- * (the map colours) reach their layers through the TomTom styles this SDK version is verified
- * against. On a style layer they do not recognise, setting one warns once and does nothing.
+ * stop's output scaled, and any other expression `E` becomes `["*", 1.3, E]`, unless a `zoom` sits
+ * inside it, where no wrapper may go: that value stays as the style has it, with a warning.
+ *
+ * `tomtom-styles` knobs (the map colours) reach their layers through the TomTom styles this SDK
+ * version is verified against. On a style layer they do not recognise, setting one warns once and
+ * does nothing.
  *
  * After every `setStyle` that carries state over, the settings are re-applied on top of whatever the
  * other modules restored. A clean switch (`resetState: true`) drops them.
@@ -6311,7 +6647,8 @@ export declare class StylingFoundationsModule extends AbstractStyleOwnedMapModul
    * The ten are the style themes' Foundations palette, each listed with what it reaches under
    * {@link MapColorName}. Partial objects are fine. The colours you leave out stay as they are,
    * except on the mono styles, which derive the other nine from `land` as their theme does. There,
-   * the theme's own formulas re-derive them from the given `land`.
+   * the theme's own formulas re-derive them from the given `land`, and `roadMajor` and `roadOutline`
+   * from a given `road` too.
    *
    * @remarks
    * Each colour re-derives every shade the style built from it, such as a trunk variant, an outline
@@ -6343,7 +6680,8 @@ export declare class StylingFoundationsModule extends AbstractStyleOwnedMapModul
    * It includes whatever the SDK's data modules (places, routes) have on the map. Its tile URLs
    * carry the API key the map was created with, so strip or rotate the key before publishing.
    * Labels set in a `customTypeface` come out in the style's own Noto faces, since only the SDK can
-   * draw font files beside the glyph service.
+   * draw font files beside the glyph service. `view.space.color` paints the map's container, which no
+   * style specification carries.
    */
   exportStyle(): StyleSpecification;
   /**
@@ -6665,8 +7003,8 @@ type StyleKnobId = keyof StyleKnobDefinitions;
 type StyleKnobValueOf<ID extends StyleKnobId> = KnobValueOf<StyleKnobDefinitions[ID]['kind']>;
 /**
  * The map-wide id of a style colour knob, for every colour of the loaded style a module's knob sets.
- * These are the ten map colours and the accent, the sky, the POI labels, the traffic levels and the
- * hillshade tones. {@link getStyleColor} reads the one in force. The light's colour is not one: no
+ * These are the ten map colours and the accent, the sky and the space around a globe, the POI labels,
+ * the traffic levels and the hillshade tones. {@link getStyleColor} reads the one in force. The light's colour is not one: no
  * pixel is drawn in it.
  *
  * @group Map Styling
@@ -6694,7 +7032,7 @@ export declare const styleColorKnobIds: readonly StyleColorKnobId[];
  *
  * @param id - The colour's map-wide id, from {@link styleColorKnobIds}.
  * @returns The colour, or `undefined` where the style draws it with an expression no single colour
- * stands for, or has no layer for it.
+ * stands for, has no layer for it, or is still loading.
  *
  * @example
  * ```typescript
@@ -6713,7 +7051,8 @@ export declare const getStyleColor: (map: TomTomMap, id: StyleColorKnobId) => st
  * - The constructor throws one with `WEBGL_UNSUPPORTED` when the browser cannot create a WebGL2 context, or
  *   `INSECURE_BASE_URL` when `commonBaseURL` is neither `https:` nor `http:` on a loopback address.
  * - Every failure after construction reaches the handlers {@link TomTomMap.addErrorHandler} registers.
- *   These are a style, tile, sprite or glyph that failed to load, and a lost WebGL context.
+ *   These are a style, tile, sprite or glyph that failed to load, a plugin's data that failed to load, such as
+ *   the Landmarks 3D tiles, and a lost WebGL context.
  *   {@link TomTomMap.setStyle} also rejects with a style that fails to load, and so do module creation and
  *   the module calls that wait for the map, until a later switch loads a style.
  *
@@ -6721,13 +7060,15 @@ export declare const getStyleColor: (map: TomTomMap, id: StyleColorKnobId) => st
  * ```typescript
  * map.addErrorHandler((error) => {
  *   if (error.code === 'INVALID_CREDENTIALS') showMessage('The map could not load: check the API key');
- *   else if (error.code === 'INSUFFICIENT_PERMISSIONS') showMessage('The map could not load: check the APIs and domains the key allows');
+ *   else if (error.privatePreviewAccess) showMessage(`Request access to ${error.privatePreviewAccess.product}: ${error.privatePreviewAccess.requestAccessURL}`);
+ *   else if (error.apiErrorCode === 'InvalidReferer') showMessage('The map could not load: add this domain to the API key');
+ *   else if (error.code === 'INSUFFICIENT_PERMISSIONS') showMessage('The map could not load: check the APIs the key allows');
  * });
  * ```
  *
  * @group Map
  */
-export declare class TomTomMapError extends Error {
+export declare class TomTomMapError extends Error implements APIErrorDetails {
   /**
    * What went wrong. Branch on it, not on the message.
    */
@@ -6745,17 +7086,34 @@ export declare class TomTomMapError extends Error {
    * The HTTP status of the request that failed, when a response came back.
    */
   readonly status?: number;
+  readonly apiErrorCode?: string;
+  readonly privatePreviewAccess?: PrivatePreviewAccess;
   /**
    * The map source whose tiles or data failed to load, when the failure was one of a source's.
    */
   readonly sourceId?: string;
-  constructor(message: string, options: {
+  constructor(message: string, options: APIErrorDetails & {
     code: SDKErrorCode;
     status?: number;
     sourceId?: string;
     cause?: unknown;
   });
 }
+/**
+ * The {@link TomTomMapError} a request failed with, for a map source that fetches its own data: pass the response
+ * it got, or what `fetch` threw when none arrived. Fire it as the `error` of a MapLibre `error` event with the
+ * source's `sourceId`, and the map's error handlers get it.
+ * @param options.privatePreviewAccess The access the source's API needs, for one in Private Preview.
+ * @ignore
+ */
+export declare const toTomTomMapRequestError: (failure: {
+  response: Response;
+} | {
+  fetchError: unknown;
+}, options: {
+  sourceId: string;
+  privatePreviewAccess?: PrivatePreviewAccess;
+}) => Promise<TomTomMapError>;
 //#endregion
 //#region src/TomTomMap.d.ts
 /**
@@ -6764,8 +7122,8 @@ export declare class TomTomMapError extends Error {
  * @remarks
  * The SDK calls them when the map style changes through {@link TomTomMap.setStyle}. Use them to clean
  * up or reinitialize custom map features when the style switches. For example, save and restore
- * custom layers or sources, reinitialize map modules, update UI components for the new style, or
- * clean up resources tied to the previous style.
+ * custom layers or sources, update UI components for the new style, or clean up resources tied to
+ * the previous style. The SDK modules restore or reset themselves in handlers of their own.
  *
  * The lifecycle is:
  * 1. `onStyleAboutToChange` runs before the new style is applied.
@@ -6801,7 +7159,8 @@ export type StyleChangeHandler = {
    * @remarks
    * Use it to clean up or save state before the current style is removed. It 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.
+   * old style is torn down while it runs. A {@link TomTomMap.setStyle} called while it still runs
+   * calls it again, before the first call settles.
    *
    * @param context - What kind of switch is happening. See {@link StyleChangeContext}.
    * @returns void or a Promise that resolves when preparation is complete
@@ -6816,6 +7175,11 @@ export type StyleChangeHandler = {
    * {@link StyleChangeHandler.priority}, and the promise {@link TomTomMap.setStyle} returns resolves
    * only once the last one has finished.
    *
+   * A switch whose style fails to load runs none for its own style, and the map keeps the style it
+   * had: undo what `onStyleAboutToChange` did from a {@link TomTomMap.addErrorHandler} handler. When
+   * that style had loaded for a switch the failed one superseded, they run for it instead, with its
+   * context.
+   *
    * @param context - What kind of switch is happening. See {@link StyleChangeContext}.
    * @returns void or a Promise that resolves when reinitialization is complete
    */
@@ -6870,7 +7234,8 @@ export type SetStyleOptions = {
    * - `false` (default): module data and configuration, filters and the style parts of the
    *   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.
+   *   nothing shown, and only the style parts the new style input asks for are loaded, every part
+   *   for one that names none.
    *
    * The map language and geopolitical view are not SDK state, so both survive either case. Only
    * {@link TomTomMap.setLanguage} and {@link TomTomMap.setGeopoliticalView} change them.
@@ -6956,8 +7321,8 @@ export declare class TomTomMap {
    * @example
    * ```typescript
    * if (map.mapReady) {
-   *   // Safe to initialize modules
-   *   const trafficFlowModule = await TrafficFlowModule.get(map);
+   *   // The style is loaded, so its layers can be read
+   *   const layerIds = map.mapLibreMap.getStyle().layers.map((layer) => layer.id);
    * }
    * ```
    */
@@ -7007,7 +7372,7 @@ export declare class TomTomMap {
    */
   _params: InternalTomTomMapParams;
   /**
-   * Whether the loaded style draws a light or a dark map.
+   * Whether the map's style, the one {@link getStyleInput} returns, 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
@@ -7078,16 +7443,19 @@ export declare class TomTomMap {
   private readonly styleChangeHandlers;
   private readonly errorHandlers;
   private failStyleLoadInFlight;
+  private pendingError;
   private styleLoadError;
   private readonly styleLoadFailureHandlers;
   private vectorTilesReloadPending;
   private incidentTilesReloadPending;
   private styleGivenToMapLibre;
+  private loadedStyleInput;
   private styleRequestSequence;
   private styleLoadInFlight;
   private styleLayerIds;
   private styleLoads;
-  private firstStyleUnfinished;
+  private styleDataUnannounced;
+  private unfinishedStyle;
   private readonly moduleSourcesAndLayers;
   /**
    * Constructs a new TomTom Map instance and attaches it to a DOM element.
@@ -7178,13 +7546,15 @@ export declare class TomTomMap {
    * @param options - Options for the style change behaviour. 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. Once it resolves, the map is safe to read and draw on again.
+   * Awaiting it is optional, but a call you don't await needs a `.catch` for a style that fails to
+   * load. Once it resolves, the map is safe to read and draw on again.
    * @throws A {@link TomTomMapError} if the style itself fails to load, leaving {@link mapReady} `false`
-   * and the map on the style it had: the code of the HTTP status it got, `NETWORK_NOT_AVAILABLE` when no response
+   * and the map on the style it had, which {@link getStyleInput} and {@link styleLightDarkTheme} answer with
+   * again: the code of the HTTP status it got, `NETWORK_NOT_AVAILABLE` when no response
    * arrived, else `STYLE_LOAD_FAILED`. The error handlers get it too, and module creation and the module calls
    * that wait for the map reject with it until a later switch loads a style. A tile or source that fails to load
-   * does not fail the switch. Called before the map's first style loaded, a failed switch finishes
-   * that style instead, and {@link mapReady} turns `true`.
+   * does not fail the switch. Called before the map's first style loaded, or once the style of a switch it
+   * superseded has loaded, a failed switch finishes that style instead, and {@link mapReady} turns `true`.
    *
    * @remarks
    * By default, the switch carries state over. It merges the previous style's parts with the new
@@ -7203,7 +7573,8 @@ export declare class TomTomMap {
    * - Once the style has loaded, {@link mapReady} is back to `true` and the SDK awaits every
    *   `onStyleChanged` handler by {@link StyleChangeHandler.priority}.
    * - A `setStyle` call made while another one is still in flight supersedes it. No `onStyleChanged`
-   *   handler runs for the older call, and its promise resolves. A load it had already started ends
+   *   handler runs for the older call unless the newer one fails once the older style has loaded, and
+   *   its promise resolves. A load it had already started ends
    *   first, so MapLibre can draw that style briefly; if it fails, only the error handlers hear of it.
    * - Passing the style already loaded runs the whole lifecycle without reloading it. This is how
    *   `resetState: true` doubles as a reset of the SDK modules over the current style.
@@ -7234,7 +7605,7 @@ export declare class TomTomMap {
    * @example
    * Clean style switch without state preservation:
    * ```typescript
-   * // Complete reset - removes all SDK layers and modules
+   * // Clean switch - the modules re-bind with their default configuration and nothing shown
    * map.setStyle('streetDark', { resetState: true });
    * ```
    *
@@ -7260,8 +7631,10 @@ export declare class TomTomMap {
    */
   setStyle: (style: StyleInput, options?: SetStyleOptions) => Promise<void>;
   private applyStyle;
+  private settleFailedLoad;
   private loadIntoMapLibre;
   private isSuperseded;
+  private restoreLoadedStyleInput;
   private fitCanvasToContainer;
   private recordStyleLayers;
   /**
@@ -7277,9 +7650,11 @@ export declare class TomTomMap {
   get _styleLoads(): number;
   private notifyHandlers;
   /**
-   * The {@link StyleInput} the map was last given, through its parameters or {@link setStyle}.
+   * The {@link StyleInput} in force: the one the map was last given, through its parameters or
+   * {@link setStyle}, with the previous style's parts merged in unless the switch was clean. After a
+   * switch whose style failed to load, it is the style the map kept.
    *
-   * It is the input as given, not the resolved style specification. For that, use
+   * It is a style input, not the resolved style specification. For that, use
    * {@link StylingFoundationsModule.exportStyle} or `mapLibreMap.getStyle()`.
    *
    * @example
@@ -7310,9 +7685,11 @@ export declare class TomTomMap {
    * @param language The language for map translations.
    *
    * @remarks
-   * It updates all localizable map labels to the language, and falls back to the default label
-   * name where the language is unavailable. You can call it before or after the map has fully
-   * loaded. Before the map is ready, it applies once the style loads.
+   * It updates all localizable labels of the map style to the language, and falls back to the default
+   * label name where the language is unavailable. The labels of SDK modules and of your own layers keep
+   * the text they were given. You can call it before or after the map has fully
+   * loaded. While the map is not ready, it applies once a style loads: after a switch whose style
+   * failed to load, that is the next {@link setStyle} that loads one.
    *
    * The {@link TrafficIncidentsModuleFeature} descriptions follow it too, so it reloads the
    * incident tiles when their language changes.
@@ -7364,7 +7741,9 @@ export declare class TomTomMap {
    * the map is viewed from. Set it at construction through {@link core!GlobalConfig.geopoliticalView}.
    *
    * @remarks
-   * - The visible tiles reload in place, and the view persists across every style change.
+   * - The visible tiles reload in place, and the view persists across every style change. While the
+   *   map is not ready, they reload once a style loads: after a switch whose style failed to load,
+   *   that is the next {@link setStyle} that loads one.
    * - Applies to the TomTom Orbis vector tiles. The tiles do not serve `CN` and `RU`, which leave
    *   the default view. See {@link core!GeopoliticalView}.
    * - Services keep the view of the global configuration, or of each call.
@@ -7446,14 +7825,7 @@ export declare class TomTomMap {
    * (`module.events.on(...)`) return.
    *
    * @remarks
-   * Use it when you have custom layers or sources to recreate after style changes, when your
-   * application responds to style switches (e.g. light/dark mode transitions), when you save and
-   * restore state during style changes, or when map modules need to reinitialize on style changes.
-   *
-   * The handler lifecycle is:
-   * 1. `onStyleAboutToChange()` runs before the style change begins.
-   * 2. The style changes.
-   * 3. `onStyleChanged()` runs after the new style has fully loaded.
+   * {@link StyleChangeHandler} says when each callback runs, and what to use them for.
    *
    * You can register several handlers. They run by {@link StyleChangeHandler.priority}, lowest first,
    * and in registration order where it is equal. The SDK awaits
@@ -7547,12 +7919,7 @@ export declare class TomTomMap {
    *   },
    *   onStyleChanged: () => {
    *     document.body.classList.remove('style-changing');
-   *     const style = map.getStyleInput();
-   *     if (typeof style === 'string' && style.includes('Dark')) {
-   *       document.body.classList.add('dark-mode');
-   *     } else {
-   *       document.body.classList.remove('dark-mode');
-   *     }
+   *     document.body.classList.toggle('dark-mode', map.styleLightDarkTheme === 'dark');
    *   }
    * });
    * ```
@@ -7614,19 +7981,22 @@ export declare class TomTomMap {
    * - A tile, sprite or glyph that fails to load gets the code of the HTTP status, `NETWORK_NOT_AVAILABLE` when
    *   no response arrived, otherwise `INTERNAL`. A tile's source is in `sourceId`. A tile answered with `404`
    *   isn't reported.
+   * - A plugin's data that fails to load, such as the Landmarks 3D tiles, gets its codes the same way, under
+   *   the plugin's source.
    * - A lost WebGL context gets `WEBGL_CONTEXT_LOST`.
    * - While no handler is registered, each failure is logged with `console.error` instead.
    * - The constructor throws its own failures, `WEBGL_UNSUPPORTED` and `INSECURE_BASE_URL`, since no
    *   handler exists yet.
    *
+   * {@link TomTomMapError} has what each error carries, and how to read a refused API key.
+   *
    * @returns A function that unregisters the handler.
    *
    * @example
    * ```typescript
    * const removeHandler = map.addErrorHandler((error) => {
-   *   if (error.code === 'INVALID_CREDENTIALS') showMessage('The map could not load: check the API key');
-   *   else if (error.code === 'INSUFFICIENT_PERMISSIONS') showMessage('The map could not load: check the APIs and domains the key allows');
-   *   else if (error.code === 'WEBGL_CONTEXT_LOST') showMessage('The map stopped drawing: reload the page');
+   *   if (error.code === 'WEBGL_CONTEXT_LOST') showMessage('The map stopped drawing: reload the page');
+   *   else console.warn(error);
    * });
    * ```
    */
@@ -7649,8 +8019,8 @@ export type ShownFeaturesType<TShownFeatures> = [TShownFeatures] extends [never]
  * It offers one API for subscribing to module-level events that aren't tied to user
  * interaction with map features. It supports two event types:
  *
- * - `config-change`: emitted whenever `applyConfig`, `resetConfig` or any module-specific
- *   setter changes the module's configuration.
+ * - `config-change`: emitted after every change to the module's configuration, which
+ *   [What triggers `config-change`](https://docs.tomtom.com/maps-sdk-js/guides/map/module-events#what-triggers-config-change) lists.
  * - `shown-features`: emitted by modules that have a `show` method, immediately after
  *   features are displayed on the map.
  *
@@ -7658,8 +8028,8 @@ export type ShownFeaturesType<TShownFeatures> = [TShownFeatures] extends [never]
  * without clearing the entire listener list.
  *
  * @typeParam TConfig - The module's configuration type.
- * @typeParam TShownFeatures - The type of data passed to `show()`. Use `never` for
- *   modules that have no `show` method.
+ * @typeParam TShownFeatures - What the module hands its `shown-features` handlers. Use `never`
+ *   for modules that have no `show` method.
  *
  * @example
  * ```typescript
@@ -7685,8 +8055,8 @@ export declare class ModuleEvents<TConfig, TShownFeatures = never> {
   /**
    * Subscribes to config-change events.
    *
-   * The handler receives the module's full current configuration right after any change made
-   * with `applyConfig`, a module-specific setter or `resetConfig`.
+   * The handler receives the module's full current configuration right after every change to it,
+   * which [What triggers `config-change`](https://docs.tomtom.com/maps-sdk-js/guides/map/module-events#what-triggers-config-change) lists.
    *
    * @param type - `'config-change'`
    * @param handler - Receives the module's config, or `undefined` when the config is cleared.
@@ -7711,14 +8081,16 @@ export declare class ModuleEvents<TConfig, TShownFeatures = never> {
    * the map with new data. Only modules that have a `show` method offer it.
    *
    * @param type - `'shown-features'`
-   * @param handler - Receives the data that was passed to `show()`.
+   * @param handler - Receives what the module shows: the data passed to `show()`, or, from a module
+   *   that shows several kinds, an object naming which, such as `PlacesModule`'s `{ places }`
+   *   or `{ connections }`.
    * @returns An unsubscribe function. Call it to remove **only this handler**, leaving the
    *   other handlers for the same event type registered.
    *
    * @example
    * ```typescript
-   * const unsubscribe = places.events.on('shown-features', (features) => {
-   *   fitMapToResults(features);
+   * const unsubscribe = places.events.on('shown-features', (shown) => {
+   *   if ('places' in shown) fitMapToResults(shown.places);
    * });
    *
    * // Later:
@@ -7729,9 +8101,9 @@ export declare class ModuleEvents<TConfig, TShownFeatures = never> {
   /**
    * Removes **all** handlers for the given event type at once.
    *
-   * To remove a single handler, call the unsubscribe function that {@link on} returns instead.
-   * Use `off` for bulk teardown, for example when unmounting a component that registered
-   * several handlers.
+   * To remove a single handler, call the unsubscribe function that {@link on} returns instead,
+   * which is also how a component cleans up on unmount: `off` also removes the handlers other
+   * code put on the module, such as a plugin's.
    *
    * @param type - The event type whose handlers should all be cleared. A module takes
    *   `'shown-features'` only if it has a `show` method.
@@ -7801,11 +8173,11 @@ export declare class CombinedEvents<T, CFG, TShown = never, WHERE_SCOPE = never>
    * Narrows these events to part of what they cover, as {@link UserEvents.where} does.
    *
    * @param scope A predicate over this module's feature type or, where the module supports one,
-   * a scope object such as `{ layerGroups }` on {@link BaseMapModule}. See {@link EventScope}.
+   * a scope object such as `{ layerGroups }` on {@link BaseMapModule}.
    * @param config Event configuration for handlers registered through the returned instance, so
    * each scope can have its own hover cursor.
    * @returns A {@link UserEvents} covering only the narrowed set. Lifecycle events stay on the
-   * module (or named scope) they belong to.
+   * module.
    *
    * @example
    * ```typescript
@@ -7819,8 +8191,9 @@ export declare class CombinedEvents<T, CFG, TShown = never, WHERE_SCOPE = never>
    * `dragstart`, `drag`, `dragend`).
    *
    * @param type - The user event type.
-   * @param handler - Called with the feature, click/hover coordinates, all features at the
-   *   point, and the source configuration.
+   * @param handler - Called with the feature, click/hover coordinates, the features at the point
+   *   from the source that drew it (under `where()`, the ones in its scope), and that source with
+   *   its layers.
    * @returns An unsubscribe function. Call it to remove **only this handler**.
    *
    * @example
@@ -7835,8 +8208,8 @@ export declare class CombinedEvents<T, CFG, TShown = never, WHERE_SCOPE = never>
   /**
    * Subscribes to config-change events.
    *
-   * It fires after `applyConfig`, `setVisible` or any module-specific setter changes the
-   * configuration. The handler receives the module's full updated configuration.
+   * It fires after every change to the module's configuration, which [What triggers `config-change`](https://docs.tomtom.com/maps-sdk-js/guides/map/module-events#what-triggers-config-change)
+   * lists. The handler receives the module's full updated configuration.
    *
    * @param type - `'config-change'`
    * @param handler - Receives the module's config, or `undefined` when the config is cleared.
@@ -7858,13 +8231,15 @@ export declare class CombinedEvents<T, CFG, TShown = never, WHERE_SCOPE = never>
    * the map. Only modules that have a `show` method offer it.
    *
    * @param type - `'shown-features'`
-   * @param handler - Receives the data that was passed to `show()`.
+   * @param handler - Receives what the module shows: the data passed to `show()`, or, from a module
+   *   that shows several kinds, an object naming which, such as `PlacesModule`'s `{ places }`
+   *   or `{ connections }`.
    * @returns An unsubscribe function. Call it to remove **only this handler**.
    *
    * @example
    * ```typescript
-   * const unsubscribe = places.events.on('shown-features', (features) => {
-   *   fitMapToResults(features);
+   * const unsubscribe = places.events.on('shown-features', (shown) => {
+   *   if ('places' in shown) fitMapToResults(shown.places);
    * });
    * unsubscribe();
    * ```
@@ -7877,9 +8252,9 @@ export declare class CombinedEvents<T, CFG, TShown = never, WHERE_SCOPE = never>
    * `dragstart`, `drag`, `dragend`) and
    * module lifecycle types (`config-change`, and `shown-features` on a module that has a `show` method).
    *
-   * To remove a single handler, call the unsubscribe function that {@link on} returns instead.
-   * Use `off` for bulk teardown, for example when unmounting a component that registered
-   * several handlers of the same type.
+   * To remove a single handler, call the unsubscribe function that {@link on} returns instead,
+   * which is also how a component cleans up on unmount: `off` also removes the handlers other
+   * code put on the module, such as a plugin's.
    *
    * @param type - The event type whose handlers should all be cleared.
    *
@@ -7927,8 +8302,9 @@ export declare class LayerFilterComposer extends AbstractLayerComposer<LayerFilt
    * the other contributors.
    *
    * @param layerId - The style layer whose filter is rewritten.
-   * @param contributor - A key unique to the contributor, e.g. `'styling.zoomShift'`.
-   * @param transform - Receives the style's own filter, returns the filter to use instead.
+   * @param contributor - A key unique to the contributor, e.g. `'styleKnobs.zoomShift'`.
+   * @param transform - Receives the filter as the style and the transforms registered before it
+   * left it, and returns the filter to use instead.
    */
   setTransform(layerId: string, contributor: string, transform: LayerFilterTransform | undefined): void;
   /**
@@ -7940,8 +8316,8 @@ export declare class LayerFilterComposer extends AbstractLayerComposer<LayerFilt
    * @param clause - The clause to add, in expression syntax.
    */
   setClause(layerId: string, contributor: string, clause: ExpressionFilterSpecification | undefined): void;
-  private contribute;
-  private apply;
+  protected snapshot(layerId: string): LayerFilterContributions;
+  protected write(layerId: string, contributions: LayerFilterContributions): void;
 }
 //#endregion
 //#region src/shared/AbstractMapModule.d.ts
@@ -7949,14 +8325,7 @@ export declare class LayerFilterComposer extends AbstractLayerComposer<LayerFilt
  * How a module builds user events over some of its sources.
  * @ignore
  */
-type EventScopeOptions<T, WHERE_SCOPE> = {
-  /** Turns a raw MapLibre feature into the feature type this scope exposes. */
-  mapping?: (feature: MapGeoJSONFeature) => T;
-  /** Resolves a module-specific scope object, such as BaseMapModule's `{ layerGroups }`. */
-  scopeResolver?: (scope: WHERE_SCOPE) => ResolvedEventScope;
-  /** Leaves out part of what the sources draw, as a `where()` would. A `where()` on top narrows within it. */
-  scope?: ResolvedEventScope;
-};
+type EventScopeOptions<T, WHERE_SCOPE> = Pick<UserEventsOptions<T, WHERE_SCOPE>, 'mapping' | 'scopeResolver' | 'scope'>;
 /**
  * Base class for all Maps SDK map modules.
  *
@@ -7989,7 +8358,12 @@ type EventScopeOptions<T, WHERE_SCOPE> = {
  * @example
  * ```typescript
  * class CustomModule extends AbstractDataOwnedMapModule<MySourcesWithLayers, MyConfig> {
- *   constructor(tomtomMap: TomTomMap, config?: MyConfig) {
+ *   static async create(tomtomMap: TomTomMap, config?: MyConfig): Promise<CustomModule> {
+ *     // Wait for the map's style first, as the SDK's own factories do.
+ *     return new CustomModule(tomtomMap, config);
+ *   }
+ *
+ *   private constructor(tomtomMap: TomTomMap, config?: MyConfig) {
  *     super(tomtomMap, config);
  *   }
  *   // Implement abstract methods...
@@ -8015,6 +8389,7 @@ export declare abstract class AbstractMapModule<SOURCES_WITH_LAYERS extends Sour
    * @ignore
    */
   protected sourcesWithLayers: SOURCES_WITH_LAYERS;
+  private readonly sourceIdsByName;
   /**
    * @ignore
    */
@@ -8048,21 +8423,21 @@ export declare abstract class AbstractMapModule<SOURCES_WITH_LAYERS extends Sour
    * dropping another's work, and what holds the filter the style itself shipped. A module may
    * still set the filter of a layer it added and owns alone.
    *
-   * Assigned in this constructor, which already runs `_initSourcesWithLayers` and `applyConfig`,
-   * so a subclass field would be assigned too late for either to use it.
+   * A getter rather than a field, so the composer is created only for the modules that use it,
+   * and is already there for `_initSourcesWithLayers` and `applyConfig`, which this constructor runs.
    * @ignore
    */
-  protected readonly filterComposer: LayerFilterComposer;
+  protected get filterComposer(): LayerFilterComposer;
   /**
-   * Indicates that this module is currently adding its sources and layers to the map, so during this time it might not function properly.
+   * Whether this module is bound to the current style: `false` while it adds its sources and layers, when it might not function properly.
    * @see waitUntilModuleReady
    * @private
    */
   private moduleReady;
   /**
    * Builds this module on a Maps SDK map.
-   * @param tomtomMap The map. If it isn't initialized yet, the module initializes itself once it is.
-   * @param config Optional configuration that the module initializes with as soon as the map is ready.
+   * @param tomtomMap The map, with its style loaded: the `get` and `create` factories wait for it.
+   * @param config Optional configuration that the module initializes with.
    */
   protected constructor(tomtomMap: TomTomMap, config?: CFG);
   /**
@@ -8187,8 +8562,8 @@ export declare abstract class AbstractMapModule<SOURCES_WITH_LAYERS extends Sour
   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.
+   * switch does not bring it back. The sources are rebuilt right after, empty, and the event
+   * states come off any style source the switch keeps, 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
@@ -8352,7 +8727,7 @@ export declare abstract class AbstractMapModule<SOURCES_WITH_LAYERS extends Sour
  * const { hover: hoveredStops = [] } = routing.events.waypoints.getEventStates();
  * ```
  *
- * @group User Interaction Events
+ * @group Events
  */
 export declare class UserEventsWithStates<T = MapGeoJSONFeature> extends UserEvents<T> {
   private readonly eventStates;
@@ -8449,7 +8824,8 @@ export declare abstract class AbstractDataOwnedMapModule<SOURCES_WITH_LAYERS ext
    */
   protected userEventsWithStates<T = MapGeoJSONFeature>(sourceNames: (keyof SOURCES_WITH_LAYERS)[], options?: Pick<UserEventsOptions<T, never>, 'mapping' | 'scope'>): UserEventsWithStates<T>;
   /**
-   * Puts an event state on one of the shown features, as a user interaction would.
+   * Puts an event state on one of the shown features, replacing the one it had: unlike a user's
+   * hover, this one replaces a click.
    *
    * @remarks
    * The state is what the module's own layers draw (place pins and entry points, route outlines,
@@ -8463,7 +8839,8 @@ export declare abstract class AbstractDataOwnedMapModule<SOURCES_WITH_LAYERS ext
    * // Select a feature from a list, as a click would
    * module.setEventState({ id: feature.properties.id, state: 'click' });
    *
-   * // Hover a second one without taking the hover off the first
+   * // Hover one, then a second one without taking the hover off the first
+   * module.setEventState({ index: 1, state: 'hover' });
    * module.setEventState({ index: 2, state: 'hover', mode: 'add' });
    * ```
    */
@@ -8516,8 +8893,8 @@ export declare abstract class AbstractDataOwnedMapModule<SOURCES_WITH_LAYERS ext
 //#endregion
 //#region src/shared/AbstractStyleOwnedMapModule.d.ts
 /**
- * Base class for the base map, POIs, traffic tiles and terrain modules, which control sources and
- * layers the loaded map style already provides under fixed global IDs.
+ * Base class for the base map, POIs, traffic tiles, terrain and styling foundations modules, which
+ * control sources and layers the loaded map style already provides under fixed global IDs.
  *
  * @remarks
  * The style owns the data, so such a module brings no data of its own and shows nothing by
@@ -8537,8 +8914,8 @@ export declare abstract class AbstractDataOwnedMapModule<SOURCES_WITH_LAYERS ext
  */
 export declare abstract class AbstractStyleOwnedMapModule<SOURCES_WITH_LAYERS extends StyleSourcesWithLayers, CFG extends MapModuleCommonConfig | undefined = undefined> extends AbstractMapModule<SOURCES_WITH_LAYERS, CFG> {
   /**
-   * The map's single owner of the visibility of a style layer that a styling toggle shows or hides
-   * as well as its owning module. A getter rather than a field: the base constructor already runs
+   * The map's single owner of the visibility of a style layer that a part knob or the styling
+   * module's layer edits show or hide as well as its owning module. A getter rather than a field: the base constructor already runs
    * `applyConfig`, which writes through it.
    * @ignore
    */
@@ -8551,7 +8928,8 @@ export declare abstract class AbstractStyleOwnedMapModule<SOURCES_WITH_LAYERS ex
  * `bounds` hold.
  *
  * @remarks
- * A `color` must parse as a CSS colour. An `image` or `text` value need only be a string. Only a
+ * A `color` must be a CSS colour in hex, `rgb()`, `hsl()` or a colour name. An `image` or `text` value
+ * need only be a string. Only a
  * loaded map knows whether the sprite has the image.
  *
  * @param knob - The knob's entry in its catalogue.
@@ -8594,7 +8972,9 @@ export declare const knobValueIn: (config: unknown, id: string) => unknown;
  */
 export declare const configWithKnobs: <CONFIG extends object>(config: CONFIG, values: Readonly<Record<string, unknown>>) => CONFIG;
 /**
- * The configuration without the value at a knob id's path, dropping each object that leaves empty.
+ * The configuration without the value at a knob id's path, each object along the path copied and each
+ * one it leaves empty dropped, so a value set and then removed leaves the configuration as it was. A
+ * knob that is not set returns the configuration itself.
  * @ignore
  */
 export declare const configWithoutKnob: <CONFIG extends object>(config: CONFIG, id: string) => CONFIG;
@@ -8687,14 +9067,15 @@ export declare const setKnob: <CONFIG, ID extends string, KNOB extends ID>(modul
  */
 export declare const setKnobs: <CONFIG, ID extends string>(module: KnobTarget<CONFIG>, catalogue: readonly KnobEntry<ID>[], values: KnobValues<CONFIG, ID>) => void;
 /**
- * Returns the value set for a knob, otherwise the module's own value where it knows it
- * (`StylingFoundationsModule` reads the loaded style), otherwise the catalogue's default.
+ * Returns the value set for a knob, otherwise the module's own value where it knows it (a style-owned
+ * module's look knob reads the loaded style), otherwise the catalogue's default.
  *
  * @param module - A map module, or a plugin with knobs, such as `MapEffects`.
  * @param catalogue - Its knob catalogue.
  * @param id - The knob's id.
  * @returns The value, or `undefined` for a knob with no default or a style value that is a
- * data-driven expression.
+ * data-driven expression. A data-driven expression the module's configuration holds comes back as
+ * it is, which {@link setKnob} refuses.
  * @throws `Error` for an id the catalogue lacks.
  *
  * @example
@@ -8707,7 +9088,7 @@ export declare const setKnobs: <CONFIG, ID extends string>(module: KnobTarget<CO
 export declare const getKnob: <CONFIG, ID extends string, KNOB extends ID>(module: KnobTarget<CONFIG>, catalogue: readonly KnobEntry<ID>[], id: KNOB) => KnobOutput<CONFIG, KNOB>;
 /**
  * Unsets one knob, so the module is back at its own value for it, as {@link getKnob} reads it.
- * To unset every knob, use the module's `resetConfig`.
+ * To unset every knob, use the module's `resetConfig`, which resets the rest of its configuration too.
  *
  * @param module - A map module, or a plugin with knobs, such as `MapEffects`.
  * @param catalogue - Its knob catalogue.
@@ -8723,6 +9104,19 @@ export declare const getKnob: <CONFIG, ID extends string, KNOB extends ID>(modul
  */
 export declare const resetKnob: <CONFIG, ID extends string, KNOB extends ID>(module: KnobTarget<CONFIG>, catalogue: readonly KnobEntry<ID>[], id: KNOB) => void;
 //#endregion
+//#region src/shared/layers/expressionTransforms.d.ts
+/** @ignore */
+export declare const mentionsZoom: (value: unknown) => boolean;
+/**
+ * The style's own value with `wrap` around it, or around every stop's output of a top-level zoom
+ * ramp, where a wrapper around the ramp would be illegal.
+ *
+ * Returns `undefined` for a legacy `{ stops }` function, or an expression that holds `zoom` anywhere
+ * else, so the caller can leave the style's value untouched.
+ * @ignore
+ */
+export declare const wrapZoomFreeParts: (value: unknown, wrap: (part: unknown) => unknown) => unknown;
+//#endregion
 //#region src/shared/layers/sourcesIDs.d.ts
 /**
  * Source identifier for base map vector tiles.
@@ -8787,6 +9181,35 @@ export declare const TRAFFIC_INCIDENTS_SOURCE_ID = "vectorTilesIncidents";
  */
 export declare const TRAFFIC_FLOW_SOURCE_ID = "vectorTilesFlow";
 //#endregion
+//#region src/shared/mapUtils.d.ts
+/**
+ * Runs `run` at once on a ready map, else once it is ready. A style that fails to load runs nothing:
+ * that failure is the map's error to report, and the next style comes through a style change handler.
+ * @ignore
+ */
+export declare const runWhenMapIsReady: (tomtomMap: TomTomMap, run: () => void) => void;
+/**
+ * Returns `beforeLayerID` when the current style has that layer, else the anchor it falls back to
+ * when the style has that one, else undefined — the top of the layer stack.
+ *
+ * MapLibre refuses both `addLayer` and `moveLayer` against a layer the style does not have: it
+ * fires an `ErrorEvent` and gives up, so the layer is either never added or left where it was. Not
+ * every anchor in the map style layer IDs exists in every style — the satellite style has none of
+ * `lowestRoadLine`, `lowestBuilding` and `lowest3D` — so a layer positioned against one has to check
+ * first. The top of the stack is the documented fallback for a missing reference layer, and the
+ * POIs for a missing `lowest3D`.
+ *
+ * @ignore
+ * @param map MapLibre map
+ * @param beforeLayerID The wanted anchor layer, if any.
+ */
+export declare const existingAnchorLayerID: (map: Map$1, beforeLayerID: string | undefined) => string | undefined;
+/**
+ * The standard style a style input loads: the default one when the input names none.
+ * @ignore
+ */
+export declare const standardStyleIdOf: (styleInput?: StyleInput) => StandardStyleID;
+//#endregion
 //#region src/base/BaseMapModule.d.ts
 type BaseSourceAndLayers = {
   vectorTiles: StyleSourceWithLayers;
@@ -8829,7 +9252,9 @@ export type BaseMapEvents = CombinedEvents<MapGeoJSONFeature, BaseMapModuleConfi
  *
  * @remarks
  * This module owns whether each base-map layer group is shown, and the road parts within them
- * (`roads.arrows.visible`, `roads.exitNumbers.visible`, …), which never show in a group it hides.
+ * (`roads.arrows.visible`, `roads.exitNumbers.visible`, …), which never show in a group it hides. It
+ * also owns how the 3D buildings react to hover and click (`buildings3D.hover`, `buildings3D.click`),
+ * and the colours of the ones {@link BaseMapModule.setBuildingColors} picks by id.
  * {@link StylingFoundationsModule} knobs set how the base map looks. See [Who owns what](https://docs.tomtom.com/maps-sdk-js/guides/map/modules#who-owns-what).
  * {@link baseMapKnobCatalogue} lists every setting of its configuration.
  *
@@ -8852,6 +9277,7 @@ export type BaseMapEvents = CombinedEvents<MapGeoJSONFeature, BaseMapModuleConfi
  * - Show only specific layer groups, such as roads only.
  * - Create custom map appearances by hiding certain elements.
  * - Build overlay maps with selective base layers.
+ * - Light up the 3D buildings on hover and click, and colour the ones you pick.
  *
  * @example
  * Basic usage:
@@ -8913,6 +9339,11 @@ export type BaseMapEvents = CombinedEvents<MapGeoJSONFeature, BaseMapModuleConfi
 export declare class BaseMapModule extends AbstractStyleOwnedMapModule<BaseSourceAndLayers, BaseMapModuleConfig> {
   private layersByGroup?;
   private roadParts;
+  private buildingParts;
+  private buildingLayerIds;
+  private buildingColors;
+  private writtenBuildingColors;
+  private buildingLooks;
   /**
    * Asynchronously retrieves a BaseMapModule instance for the given map.
    *
@@ -8964,6 +9395,14 @@ export declare class BaseMapModule extends AbstractStyleOwnedMapModule<BaseSourc
    * @ignore
    */
   protected _applyConfig(config: BaseMapModuleConfig | undefined): BaseMapModuleConfig | undefined;
+  /**
+   * @ignore
+   */
+  protected restoreDataAndConfigImpl(): void;
+  /**
+   * @ignore
+   */
+  protected discardShownData(): void;
   /**
    * @ignore
    */
@@ -9020,8 +9459,8 @@ export declare class BaseMapModule extends AbstractStyleOwnedMapModule<BaseSourc
    * - Showing `all-except` them: Affects every layer outside those groups, which stay as they were
    * - Changes apply immediately if the map is ready
    *
-   * Every call is kept in the configuration's `groups` or `visible`, so a style change restores
-   * all of them. The road parts, such as `roads.arrows.visible`, stay set.
+   * Every call is kept in the configuration's `groups` or `visible` (a call without `layerGroups`
+   * replaces the `groups` record with `visible`), so a style change restores all of them. The road parts, such as `roads.arrows.visible`, stay set.
    *
    * The available groups are the {@link BaseMapLayerGroupName} values.
    *
@@ -9043,7 +9482,7 @@ export declare class BaseMapModule extends AbstractStyleOwnedMapModule<BaseSourc
    *   }
    * });
    *
-   * // Show everything except place labels
+   * // Show everything but the place labels, leaving them as they are
    * baseMap.setVisible(true, {
    *   layerGroups: {
    *     show: 'all-except',
@@ -9062,6 +9501,57 @@ export declare class BaseMapModule extends AbstractStyleOwnedMapModule<BaseSourc
   setVisible(visible: boolean, options?: {
     layerGroups?: BaseMapLayerGroups;
   }): void;
+  /**
+   * Gives single 3D buildings a colour of their own, by feature id, in place of the colours given before.
+   *
+   * @param colors - CSS colours by the id of the building's feature, the `id` a handler of
+   * {@link events} receives on it. Pass `{}` to give every building the style's colour back.
+   *
+   * @remarks
+   * The ids are the map data's own, the same across tiles and zoom levels, so you can colour a building
+   * before it loads. The map data splits a building of several heights into parts, each with an id
+   * of its own: the id of any part colours the whole building, and the building lights up as one on
+   * hover and click. A hovered or clicked building turns from its colour towards the one
+   * `buildings3D.hover` or `buildings3D.click` sets. The colours stay through a style change that keeps
+   * state.
+   *
+   * @example
+   * ```typescript
+   * baseMap.events
+   *   .where({ layerGroups: { show: 'only', values: ['buildings3D'] } })
+   *   .on('click', (building) => {
+   *     baseMap.setBuildingColors({ ...baseMap.getBuildingColors(), [String(building.id)]: '#e4572e' });
+   *   });
+   * ```
+   */
+  setBuildingColors(colors: Readonly<Record<string, string>>): void;
+  /**
+   * The colours {@link setBuildingColors} gave, by feature id.
+   */
+  getBuildingColors(): Record<string, string>;
+  /**
+   * The id of the 3D building standing at a position, to colour with {@link setBuildingColors}. For a
+   * building the map data splits into parts, the id of its whole outline.
+   *
+   * @param position - A point inside the building's footprint.
+   *
+   * @returns `undefined` where no building stands, or until the tiles holding it have loaded: wait
+   * until the map is idle with the place in view.
+   *
+   * @remarks
+   * A geocoded address can sit on the street in front of its building rather than inside it, so
+   * use a point within the footprint, such as a place's own position.
+   *
+   * @example
+   * ```typescript
+   * if (!map.mapLibreMap.loaded()) await map.mapLibreMap.once('idle');
+   * const empireState = baseMap.getBuildingIdAt([-73.98566, 40.74844]);
+   * if (empireState !== undefined) baseMap.setBuildingColors({ [empireState]: '#e4572e' });
+   * ```
+   */
+  getBuildingIdAt(position: HasLngLat): string | number | undefined;
+  private regroupBuildings;
+  private writeBuildingColors;
   private writeVisibility;
   private layerSettings;
   /**
@@ -9104,7 +9594,7 @@ export declare class BaseMapModule extends AbstractStyleOwnedMapModule<BaseSourc
    * The unified events interface of this module, for both user interactions and module
    * lifecycle events.
    *
-   * User interaction events are `click`, `contextmenu`, `hover` and `long-hover`:
+   * User interaction events are every {@link EventType}, such as `click`, `contextmenu`, `hover` and `long-hover`:
    * ```typescript
    * const unsub = baseMap.events.on('click', (feature, lngLat) => {
    *   console.log('Clicked on:', feature.properties);
@@ -9126,12 +9616,13 @@ export declare class BaseMapModule extends AbstractStyleOwnedMapModule<BaseSourc
 //#region src/base/knobCatalogue.d.ts
 /**
  * Every base-map knob with its kind and description: `visible`, then one toggle per layer group in
- * {@link baseMapLayerGroupNames} order, then one per road part. It is static data, readable with no
- * map loaded.
+ * {@link baseMapLayerGroupNames} order, then one per road part, then the colour and intensity of
+ * a hovered and a clicked 3D building. It is static data, readable with no map loaded.
  *
  * @remarks
- * A knob is a plain display value in {@link BaseMapModuleConfig}, at the path its id names. None
- * carries a `default`. Unset layers draw as the style ships them, and some groups ship hidden.
+ * A knob is a plain display value in {@link BaseMapModuleConfig}, at the path its id names. Only
+ * the intensities carry a `default`. Unset layers draw as the style ships them, and some groups
+ * ship hidden.
  *
  * Not knobs: `events`.
  *
@@ -9180,7 +9671,7 @@ export type CustomGeoJSONImageSpec = {
  * module added.
  *
  * @remarks
- * If no layer on the map has the `layerID`, the layer goes on top, as MapLibre's `addLayer` does.
+ * If no layer on the map has the `layerID`, the layer goes on top.
  *
  * @example
  * ```typescript
@@ -9276,7 +9767,7 @@ export type CustomGeoJSONSourceSpec = {
  */
 export type CustomGeoJSONModuleConfig<TSources extends Record<string, FeatureCollection> = Record<string, FeatureCollection>> = MapModuleCommonConfig & {
   /**
-   * The sources, keyed by an arbitrary user-defined name, that this module manages.
+   * The sources, keyed by a user-defined name other than `on`, `off` and `where`, that this module manages.
    *
    * @remarks
    * The set of source names is fixed at module creation time, as is each source's `sourceID`.
@@ -9328,7 +9819,7 @@ export type CustomGeoJSONModuleConfig<TSources extends Record<string, FeatureCol
    *
    * @remarks
    * A shown source draws its layers while it holds features. `show()` and `clear()` never change
-   * this. A hidden module keeps its data until {@link CustomGeoJSONModule.setVisible} shows it again.
+   * this. A hidden module keeps its data, and draws it again when {@link CustomGeoJSONModule.setVisible} shows it.
    *
    * @default true
    */
@@ -9461,7 +9952,8 @@ export declare class CustomGeoJSONModule<TSources extends Record<string, Feature
    * them on one map.
    *
    * @param config The module configuration. `sources` is required and must contain at
-   * least one entry, and each entry must have at least one layer.
+   * least one entry, and each entry must have at least one layer. A source can't be named `on`, `off`
+   * or `where`.
    */
   static create<TSources extends Record<string, FeatureCollection> = Record<string, FeatureCollection>>(tomtomMap: TomTomMap, config: CustomGeoJSONModuleConfig<TSources>): Promise<CustomGeoJSONModule<TSources>>;
   private constructor();
@@ -9478,6 +9970,7 @@ export declare class CustomGeoJSONModule<TSources extends Record<string, Feature
    */
   protected _applyConfig(config: CustomGeoJSONModuleConfig<TSources> | undefined): CustomGeoJSONModuleConfig<TSources> | undefined;
   private updateLayersForExistingSources;
+  private stackAddedInArrayOrder;
   /** @ignore */
   protected applyVisibility(config: CustomGeoJSONModuleConfig<TSources> | undefined): void;
   private applySourceVisibility;
@@ -9515,8 +10008,7 @@ export declare class CustomGeoJSONModule<TSources extends Record<string, Feature
   /**
    * Returns the feature collection currently shown on each source.
    *
-   * A source that was never shown, or was cleared, returns the empty feature
-   * collection that `GeoJSONSourceWithLayers` keeps as initial state.
+   * A source that was never shown, or was cleared, returns an empty feature collection.
    */
   getShown(): { [K in keyof TSources]: TSources[K]; };
   /**
@@ -9525,6 +10017,7 @@ export declare class CustomGeoJSONModule<TSources extends Record<string, Feature
    * @ignore
    */
   protected eventStateSources(): Array<keyof TSources>;
+  private sourceNames;
   /**
    * The events of every source, with one named scope per source in
    * {@link CustomGeoJSONModuleConfig.sources}.
@@ -9549,8 +10042,8 @@ export declare class CustomGeoJSONModule<TSources extends Record<string, Feature
  * {@link customGeoJSONKnobCatalogue} for what each one does.
  *
  * @remarks
- * It covers every setting but `sources`, `images` and `beforeLayerConfig`, which hold the caller's own MapLibre
- * layers, source options, images and layer placement rather than plain values.
+ * It covers every setting but `sources`, `images`, `beforeLayerConfig` and `events`, which hold the caller's own
+ * MapLibre layers, source options, images, layer placement and handlers rather than plain values.
  *
  * @group Custom
  */
@@ -9604,9 +10097,12 @@ export declare const geometryFillStyles: readonly ["filled", "outline", "inverte
  * How {@link GeometriesModule} fills a polygon.
  *
  * - `'filled'`   — Coloured fill with thin border (default)
- * - `'outline'`  — Transparent fill with thick coloured border
+ * - `'outline'`  — Transparent fill with thick border
  * - `'inverted'` — Colours the area **outside** the polygon (donut geometry)
  *
+ * In {@link GeometriesModule}, `'outline'` only sets defaults: an explicit `fill.opacity`,
+ * `line.width` or `line.opacity` still wins over its look, and any configured colour over its grey border.
+ *
  * Set it in config with {@link GeometryFillConfig.style | fill.style}, or per-feature in
  * `properties.fillStyle`.
  *
@@ -9655,11 +10151,11 @@ export type GeometryPaletteMode = (typeof geometryPaletteModes)[number];
  */
 export type GeometryFillConfig = {
   /**
-   * How every feature shown by this module is filled.
+   * How every feature shown by this module is filled, one of the {@link GeometryFillStyle} values,
+   * `'filled'` by default.
    *
-   * - `'filled'` — Coloured fill with thin border (default)
-   * - `'outline'` — Transparent fill with thick coloured border
-   * - `'inverted'` — Colours the area **outside** the polygon (donut geometry)
+   * `'outline'` only sets the defaults of `fill.opacity`, `line.width` and `line.opacity`: leave
+   * those unset to see its transparent fill and thick border.
    *
    * Individual features can override this by setting `fillStyle` in their properties.
    *
@@ -9675,11 +10171,12 @@ export type GeometryFillConfig = {
   style?: GeometryFillStyle;
   /**
    * The fill colour, as a CSS colour string (`'#FF5733'`) or a MapLibre expression for data-driven
-   * styling, like `['get', 'color']`.
+   * styling, like `['get', 'zoneColor']`.
    *
    * @remarks
    * Overrides {@link GeometryFillConfig.palette | palette} and the top-level
    * {@link GeometriesModuleConfig.color}, for the fill and the border. The latter lists the full order.
+   * A feature an expression yields no colour for takes the top-level `color`, never the palette.
    */
   color?: string | ExpressionSpecification;
   /**
@@ -9709,7 +10206,7 @@ export type GeometryFillConfig = {
   /**
    * Fill opacity, 0 (transparent) to 1 (opaque). Also accepts a MapLibre expression.
    *
-   * @default 0.15
+   * @default 0.15, or 0 under the `'outline'` fill style
    */
   opacity?: DataDrivenPropertyValueSpecification<number>;
 };
@@ -9717,6 +10214,10 @@ export type GeometryFillConfig = {
  * The label drawn at the center of each geometry: its text, and how it looks.
  *
  * @remarks
+ * A geometry draws it at its `placeCoordinates` property, else a MultiPolygon on its longest outer
+ * ring. A Polygon without `placeCoordinates`, and a geometry of the `'inverted'` fill style without
+ * them, draws none.
+ *
  * Unset fields keep the defaults: the feature's `title` as text, size 15, bold font, and
  * theme-adaptive colours, `'#333333'` text with a `'#FFFFFF'` halo on light map styles and the
  * reverse on dark.
@@ -9777,7 +10278,7 @@ export type GeometryLabelConfig = LabelConfig & {
  * // Data-driven border
  * const line: GeometryLineConfig = {
  *   color: ['get', 'borderColor'],
- *   width: ['case', ['get', 'selected'], 4, 2],
+ *   width: ['case', ['==', ['get', 'selected'], true], 4, 2],
  * };
  * ```
  *
@@ -9796,14 +10297,14 @@ export type GeometryLineConfig = {
   /**
    * Border opacity, 0 (transparent) to 1 (opaque). Also accepts a MapLibre expression.
    *
-   * @default 1
+   * @default 1, or 0.9 under the `'outline'` fill style
    */
   opacity?: DataDrivenPropertyValueSpecification<number>;
   /**
    * Border width in pixels. Also accepts a MapLibre expression, such as
-   * `['case', ['get', 'selected'], 4, 2]`.
+   * `['case', ['==', ['get', 'selected'], true], 4, 2]`.
    *
-   * @default 2
+   * @default 2, or 5 under the `'outline'` fill style
    */
   width?: DataDrivenPropertyValueSpecification<number>;
   /**
@@ -9847,10 +10348,9 @@ export type GeometryLayersConfig = {
  * How a hovered or clicked geometry is drawn, with a denser fill and a wider border in its own colours.
  *
  * @remarks
- * The factors multiply the fill opacity and border width in force, including the configured
- * {@link GeometryFillConfig.opacity | fill.opacity} and {@link GeometryLineConfig.width | line.width}.
- * A `line-width` in {@link GeometryLayersConfig.line | layers.line} is drawn as given. The geometries draw their event states
- * once a handler covers them, or {@link GeometriesModule.setEventState} puts one.
+ * The factors multiply the fill opacity and border width in force, configured or default. A
+ * `fill-opacity` in the `layers.fill` override, or a `line-width` in `layers.line`, is drawn as given. The geometries draw their event
+ * states once a handler covers them, or the module's `setEventState` puts one.
  *
  * @example
  * ```typescript
@@ -9867,7 +10367,7 @@ 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.
      *
-     * @default `2`
+     * @default 2
      */
     opacityFactor?: number;
   };
@@ -9876,7 +10376,7 @@ export type GeometryHighlightConfig = {
     /**
      * Multiplier on the border width. `1` draws the border as on any other geometry. Clamped to 1 to 3.
      *
-     * @default `1.75`
+     * @default 1.75
      */
     widthFactor?: number;
   };
@@ -9942,7 +10442,7 @@ export type GeometryLineLabelConfig = GeometryLabelConfig & {
  * Controls where geometry layers are placed in the map's layer stack.
  *
  * @remarks
- * A single {@link BeforeLayerConfig} (`'top'` or a layer id) positions **all** geometry layers
+ * A single {@link BeforeLayerConfig} (`'top'` or a {@link MapStyleLayerID}) positions **all** geometry layers
  * together. The record form positions the parts independently, `all` covering any it doesn't name:
  * - `fill` — the fill layer.
  * - `line` — the border/outline, with its line labels.
@@ -9998,7 +10498,7 @@ export type GeometryBeforeLayerConfig = PartsBeforeLayerConfig<'fill' | 'line'>;
  *     opacity: 0.4
  *   },
  *   line: {
- *     color: '#000000', width: ['case', ['get', 'highlighted'], 4, 2],
+ *     color: '#000000', width: ['case', ['==', ['get', 'highlighted'], true], 4, 2],
  *   },
  *   label: {
  *     title: ['concat', ['get', 'name'], '\n', ['get', 'area'], ' km²']
@@ -10145,7 +10645,7 @@ type GeometrySourcesWithLayers = {
 export type GeometriesEvents<CFG = GeometriesModuleConfig> = CombinedEvents<MapGeoJSONFeature, CFG, PolygonFeatures> & {
   /** The fills, their borders and the labels along the borders, all drawn from the same features. */
   geometry: UserEventsWithStates<MapGeoJSONFeature>;
-  /** The title points, one per polygon, that `getShown()` lists under `geometryLabel`. */
+  /** The title points, one per geometry the title can be placed on, that `getShown()` lists under `geometryLabel`. */
   geometryLabel: UserEventsWithStates<MapGeoJSONFeature>;
 };
 /**
@@ -10463,8 +10963,11 @@ export declare class GeometriesModule extends AbstractGeometriesModule<Geometrie
    *
    * Feature properties:
    * - `title`: The text of the center and border labels, unless `label.title` or `lineLabel.title` sets
-   *   theirs. Without one, a text `label.title`, then `address.freeformAddress`, fills it in
-   * - `color`: Override fill colour per feature
+   *   theirs. Without one, a text `label.title`, then `address.freeformAddress`, fills it in. A Polygon
+   *   draws its center label only with `placeCoordinates`
+   * - `placeCoordinates`: The `[longitude, latitude]` of the center label, which a MultiPolygon
+   *   otherwise places on its longest outer ring
+   * - `color`: Override the fill and border colour per feature; `line.color` still wins for the border
    * - `fillStyle`: Override the module's `fill.style` per feature
    * - `id`: The id that event states and event handlers use, generated when missing. A feature's
    *   top-level `id` isn't read, so the top-level id of a geometry data result matches nothing
@@ -10566,7 +11069,7 @@ type GeometryLabelKnobLeaf = Exclude<keyof LabelConfig, 'customTypeface'>;
  *
  * @group Geometries
  */
-type GeometriesKnobId = 'color' | 'visible' | `fill.${keyof GeometryFillConfig}` | `line.${keyof GeometryLineConfig}` | `highlight.${LeafPathOf<GeometryHighlightConfig>}` | `label.${Exclude<keyof GeometryLabelConfig, 'title' | 'customTypeface'>}` | `lineLabel.${Exclude<keyof GeometryLineLabelConfig, 'title' | 'customTypeface'>}`;
+type GeometriesKnobId = 'color' | 'visible' | `fill.${keyof GeometryFillConfig}` | `line.${keyof GeometryLineConfig}` | `highlight.${LeafPathOf<GeometryHighlightConfig>}` | `label.${GeometryLabelKnobLeaf}` | `lineLabel.${Exclude<keyof GeometryLineLabelConfig, 'title' | 'customTypeface'>}`;
 /**
  * The value type of a geometries knob, the plain value its path holds in
  * {@link GeometriesModuleConfig}. The MapLibre expressions the config also takes there are not knob
@@ -10619,7 +11122,9 @@ export type ReachableRangesModuleConfig = MapModuleCommonConfig & {
    *
    * @remarks
    * `show()` and `clear()` never change it. A hidden module keeps its ranges until
-   * {@link ReachableRangesModule.setVisible} shows it again.
+   * {@link ReachableRangesModule.setVisible} shows it again. A layer hidden through its
+   * {@link ReachableRangesModuleConfig.layers | layers} entry's `layout.visibility` stays hidden while
+   * the module is shown.
    *
    * @default true
    */
@@ -10649,6 +11154,11 @@ export type ReachableRangesModuleConfig = MapModuleCommonConfig & {
   beforeLayerConfig?: GeometryBeforeLayerConfig;
   /**
    * MapLibre overrides for the band, border and label layers.
+   *
+   * @remarks
+   * `label`, the centre label, draws only for a range that is a MultiPolygon or carries
+   * `placeCoordinates`. The Polygons `calculateReachableRanges` returns are neither, so their titles
+   * show along their borders alone.
    */
   layers?: GeometryLayersConfig;
 };
@@ -10697,8 +11207,8 @@ export type ReachableRangeFillConfig = {
    * the innermost one, drawn at the full opacity, so the bands fade out away from the origin.
    *
    * @remarks
-   * With `'inverted'`, the world beyond the largest range is the outermost band. A lone range is the
-   * outermost band too, so it takes the factor.
+   * With `'inverted'`, the world beyond the largest range is the outermost band. When no origin has
+   * more than one range, each range is the outermost band too, so it takes the factor.
    *
    * @default 1
    */
@@ -10899,11 +11409,11 @@ export declare class ReachableRangesModule extends AbstractGeometriesModule<Reac
  * @remarks
  * Use cases:
  * - Search result boundaries (e.g., city limits, postal codes)
- * - Reachable range polygons
  * - Delivery zones
  * - Custom area highlights
  *
- * These properties override default styling and allow per-feature customization.
+ * These properties override default styling and allow per-feature customization. The reachable
+ * ranges module sets `title`, `color` and `fillStyle` itself.
  *
  * @example
  * ```typescript
@@ -10947,10 +11457,10 @@ export type ExtraGeometryDisplayProps = {
    */
   title?: string;
   /**
-   * The geometry's fill colour.
+   * The geometry's fill and border colour.
    *
    * @remarks
-   * Overrides the default fill colour from the module configuration.
+   * Overrides the module configuration's colours, but `line.color` still wins for the border.
    * Accepts any valid CSS colour value.
    *
    * Colour formats:
@@ -10982,7 +11492,6 @@ export type ExtraGeometryDisplayProps = {
  * @remarks
  * The GeometriesModule uses them to render:
  * - Search API geometry results
- * - Reachable range polygons
  * - Custom polygon overlays
  * - Administrative boundaries
  *
@@ -10991,11 +11500,12 @@ export type ExtraGeometryDisplayProps = {
  * @example
  * ```typescript
  * const geometry: DisplayGeometryProps = {
- *   type: 'Polygon',
+ *   type: 'Geography',
  *   id: 'geom-123',
  *   title: 'Amsterdam',
  *   color: '#0080FF',
  *   address: {
+ *     freeformAddress: 'Amsterdam',
  *     municipalitySubdivision: 'Amsterdam',
  *     countryCode: 'NL'
  *   }
@@ -11106,7 +11616,7 @@ type POIsModuleFeature = Feature<Point, {
 /**
  * The source and layer IDs of the POIs module.
  */
-type PoIsSourcesAndLayers = {
+type POIsSourcesAndLayers = {
   /**
    * The places of interest with their layer ids.
    */
@@ -11218,11 +11728,10 @@ type PoIsSourcesAndLayers = {
  *
  * @group POIs
  */
-export declare class POIsModule extends AbstractStyleOwnedMapModule<PoIsSourcesAndLayers, POIsModuleConfig> {
-  private categoriesFilter?;
-  private idsFilter?;
+export declare class POIsModule extends AbstractStyleOwnedMapModule<POIsSourcesAndLayers, POIsModuleConfig> {
   private addedIcons;
   private microMarkers;
+  private appliedFilters;
   /**
    * Retrieves a POIsModule instance for the given map.
    *
@@ -11325,7 +11834,10 @@ export declare class POIsModule extends AbstractStyleOwnedMapModule<PoIsSourcesA
    * - `click`: User clicks on a POI
    * - `contextmenu`: User right-clicks on a POI
    * - `hover`: Mouse enters a POI
+   * - `hover-move`: Mouse moves over a POI
    * - `long-hover`: Mouse hovers over POI for extended time
+   * - `dragstart`, `drag` and `dragend`: a handler for any of them makes POIs draggable ({@link DragEventType})
+   * - `config-change`: The module's config changed
    *
    * Event feature properties:
    * - `id`: Unique POI identifier
@@ -11357,14 +11869,14 @@ type UndrawnSectionType = 'country' | 'distinct' | 'lanes' | 'leg' | 'roadShield
  *
  * @remarks
  * It covers every section type the API can return, except the ones nothing draws. It derives from
- * the core {@link SectionType} vocabulary, and {@link SECTION_REGISTRY} is keyed by it. So a section
+ * the core {@link SectionType} vocabulary, and the module's section registry is keyed by it. So a section
  * type added to core must be registered there, or named undrawn above, before this package compiles.
  *
  * @group Routing
  */
 type DrawnSectionType = Exclude<SectionType, UndrawnSectionType>;
 /**
- * The section types whose layers are generated from {@link SECTION_REGISTRY}.
+ * The section types whose layers are generated from the module's section registry.
  *
  * @remarks
  * They are plain line overlays over the route, or a sign along it, one registration each. The
@@ -11537,7 +12049,6 @@ declare const SECTION_REGISTRY: {
     readonly sourceKey: "incidents";
     readonly visible: true;
     readonly style: "inline";
-    readonly pattern: "solid";
     readonly knobs: readonly ["visible", "opacity", "widthPreset", "widthFactor", "style"];
   };
   readonly tunnel: {
@@ -11559,7 +12070,7 @@ declare const SECTION_REGISTRY: {
  * The knobs one section type answers to.
  *
  * @remarks
- * Read off {@link SECTION_REGISTRY}, so `sections.traffic.color` is a compile error rather than a
+ * Read off the module's section registry, so `sections.traffic.color` is a compile error rather than a
  * setting that draws nothing, since `traffic` colours its line by `magnitudeOfDelay`.
  *
  * @group Routing
@@ -11614,7 +12125,7 @@ export declare const sectionDrawsByDefault: (type: DrawnSectionType) => boolean;
  * A generated type whose presentation is a road sign carrying the section's own value.
  *
  * @remarks
- * Derived from the knob catalogue, so offering `sign` and being drawn as one are the same fact.
+ * Derived from the registry's `knobs`, so offering `sign` and being drawn as one are the same fact.
  * @ignore
  */
 type SignPostingSectionType = { [T in GeneratedSectionType]: 'sign' extends SectionKnobOf<T> ? T : never; }[GeneratedSectionType];
@@ -11687,7 +12198,7 @@ type RouteStateProps = {
  * @example
  * ```typescript
  * const routeProps: DisplayRouteRelatedProps = {
- *   id: 'route-0-section-3',
+ *   id: 'section-3',
  *   routeState: 'selected',
  *   routeIndex: 0  // First route shown
  * };
@@ -11730,7 +12241,7 @@ type DisplayRouteRelatedProps = RouteStateProps & {
  * @example
  * ```typescript
  * const summary: DisplayRouteSummaryProps = {
- *   id: 'route-0-summary',
+ *   id: 'route-0',
  *   routeIndex: 0,
  *   routeState: 'selected',
  *   formattedDistance: '15 km',
@@ -11763,6 +12274,7 @@ type DisplayRouteSummaryProps = DisplayRouteRelatedProps & {
    *
    * @remarks
    * Human-readable travel time with appropriate units:
+   * - Under half a minute: "< 1 min"
    * - Short: "15 min"
    * - Medium: "1 hr 30 min"
    * - Long: "2 hr 15 min"
@@ -11810,8 +12322,9 @@ type DisplayRouteSummaryProps = DisplayRouteRelatedProps & {
    * `+6 min` or `-3 min`.
    *
    * @remarks
-   * Absent on the selected route, and where both durations round to the same minute. It is the
-   * difference of the rounded durations, so it matches the durations the bubbles show.
+   * Absent on the selected route, on every route while none is selected, and where both durations
+   * round to the same minute. It is the difference of the rounded durations, so it matches the
+   * durations the bubbles show.
    */
   formattedDurationDifference?: string;
   /**
@@ -11862,7 +12375,7 @@ type DisplayRouteProps = RouteProps & RouteStateProps & SupportsEvents;
  *     coordinates: [4.9, 52.3]
  *   },
  *   properties: {
- *     id: 'route-0-summary',
+ *     id: 'route-0',
  *     routeIndex: 0,
  *     routeState: 'selected',
  *     formattedDistance: '15 km',
@@ -11889,7 +12402,7 @@ type DisplayRouteSummary = Feature<Point, DisplayRouteSummaryProps>;
  *       type: 'Feature',
  *       geometry: { type: 'Point', coordinates: [4.9, 52.3] },
  *       properties: {
- *         id: 'route-0-summary',
+ *         id: 'route-0',
  *         routeIndex: 0,
  *         routeState: 'selected',
  *         formattedDistance: '15 km',
@@ -11900,7 +12413,7 @@ type DisplayRouteSummary = Feature<Point, DisplayRouteSummaryProps>;
  *       type: 'Feature',
  *       geometry: { type: 'Point', coordinates: [4.85, 52.35] },
  *       properties: {
- *         id: 'route-1-summary',
+ *         id: 'route-1',
  *         routeIndex: 1,
  *         routeState: 'deselected',
  *         formattedDistance: '19 km',
@@ -11996,10 +12509,10 @@ type WaypointIndexType = typeof START_INDEX | typeof MIDDLE_INDEX | typeof FINIS
  * including route position and stop numbering.
  *
  * @remarks
- * Waypoints display differently by their position:
- * - Start: Origin marker (often "A" or green pin)
- * - Middle: Numbered stop markers (1, 2, 3, etc.)
- * - Finish: Destination marker (often "B" or red pin)
+ * Waypoints display differently by their position, each pin in the route colour unless configured:
+ * - Start: the origin pin, with its own glyph
+ * - Middle: a stop pin carrying its stop mark, a number from 1 or, under `stopNumbering: 'letters'`, a letter from A
+ * - Finish: the destination pin, with its own glyph
  *
  * @example
  * ```typescript
@@ -12075,7 +12588,8 @@ type WaypointDisplayProps = Omit<PlaceDisplayProps, 'id'> & {
    *
    * @remarks
    * Stops are the waypoints between origin and destination, numbered from 1. It is
-   * present only for middle waypoints.
+   * present only for middle waypoints. A `null` placeholder among them still counts, so the
+   * stops after it keep their numbers.
    *
    * Display behaviour:
    * - Start waypoint: undefined
@@ -12107,7 +12621,8 @@ type WaypointDisplayProps = Omit<PlaceDisplayProps, 'id'> & {
    *
    * @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.
+   * default (e.g. `30 min`). Absent when the waypoint carries no wait, or one under 30 seconds,
+   * which rounds to no minutes.
    *
    * @example
    * ```typescript
@@ -12121,30 +12636,36 @@ type WaypointDisplayProps = Omit<PlaceDisplayProps, 'id'> & {
  * `waypoints.label.title` receive it, with the properties it was given (a place's, when it was a
  * search result) and its {@link WaypointDisplayProps}.
  *
+ * @remarks
+ * `waypoints.label.title` runs first, so it sees neither the mapped icon nor the `stopDisplayLabel`;
+ * `waypoints.icon.mapping` sees the title.
+ *
  * @group Routing
  */
 type DisplayWaypoint = Waypoint<WaypointDisplayProps & Partial<CommonPlaceProps>>;
 //#endregion
 //#region src/routing/types/routeModuleConfig.d.ts
 /**
- * The MapLibre layer id of a generated section's line layer.
+ * The name of a generated section's line layer: its key under `layers.sections.<type>`.
  *
  * @remarks
- * Derived from the section type, so `motorway` is drawn by `routeSectionMotorwayLine`.
+ * Derived from the section type, so `motorway` is drawn by `routeSectionMotorwayLine`. Each module
+ * instance prefixes it into the MapLibre layer id, which `sourceAndLayerIDs` lists.
  * @group Routing
  */
 type SectionLineLayerName<T extends GeneratedSectionType = GeneratedSectionType> = `routeSection${Capitalize<T>}Line`;
 /**
- * The MapLibre layer id of a section's icon layer.
+ * The name of a section's icon layer, before the instance prefix of its MapLibre layer id.
  *
  * @remarks
- * Added to a generated section as soon as `sections.<type>.icon` asks for one, so `motorway` draws
+ * Added to a generated section once `sections.<type>.icon.image` is set, so `motorway` draws
  * its icon through `routeSectionMotorwaySymbol`.
  * @group Routing
  */
 type SectionSymbolLayerName<T extends GeneratedSectionType = GeneratedSectionType> = `routeSection${Capitalize<T>}Symbol`;
 /**
- * The MapLibre layer id drawing the signs of one generated section type.
+ * The name of the layer drawing the signs of one generated section type, before the instance
+ * prefix of its MapLibre layer id.
  *
  * @remarks
  * Present for the types that post their own value on a sign, so `speedLimit` draws its signs
@@ -12153,8 +12674,8 @@ type SectionSymbolLayerName<T extends GeneratedSectionType = GeneratedSectionTyp
  */
 type SectionSignLayerName<T extends GeneratedSectionType = GeneratedSectionType> = `routeSection${Capitalize<T>}Sign`;
 /**
- * The MapLibre layer id of the kerb stripes a generated section draws over its tight sections'
- * line.
+ * The name of the layer of the kerb stripes a generated section draws over its tight sections'
+ * line, before the instance prefix of its MapLibre layer id.
  *
  * @remarks
  * Present for the types that take a `kerb`, so `curve` draws its kerb through
@@ -12462,12 +12983,13 @@ type RouteLayersConfig = {
     /**
      * Line layer ringing each focused section of the selected route, drawn with a
      * `line-gap-width` as wide as the widest line along the route, so the route and its
-     * sections show through.
+     * sections show through. It sits under the route's own lines, which cover it where the
+     * road doubles back and where focused sections meet.
      */
     routeSectionFocusOutline?: Partial<ToBeAddedLayerSpecTemplate<LineLayerSpecification>>;
     /**
-     * Line layer ringing each focused section of a deselected route, under the selected
-     * route where they cross.
+     * Line layer ringing each focused section of a deselected route, under that route's own
+     * lines and so under the selected route where they cross.
      */
     routeDeselectedSectionFocusOutline?: Partial<ToBeAddedLayerSpecTemplate<LineLayerSpecification>>;
   } & HasAdditionalLayersConfig;
@@ -12488,7 +13010,11 @@ type RouteLayersConfig = {
  *   start: { style: { fillColor: '#1B7A43' } },
  *   finish: { image: { image: '/flag.svg', pixelRatio: 2 } },
  *   // Stops that are charging stations look like the map's charging stations:
- *   mapping: { to: 'poiCategory', fn: (waypoint) => waypoint.properties.poi?.categories?.[0] },
+ *   mapping: {
+ *     to: 'poiCategory',
+ *     fn: (waypoint) =>
+ *       waypoint.properties.poi?.categories?.includes('CHARGING_LOCATION') ? 'CHARGING_LOCATION' : undefined,
+ *   },
  * };
  * ```
  *
@@ -12515,9 +13041,8 @@ type WaypointIconConfig = {
    * Images for `mapping` to pick by id.
    *
    * @remarks
-   * Each is added under its own `id`, so `mapping` returns that id. An entry's `offsetX`/`offsetY`
-   * shift that icon from the waypoint's position, and apply only to an entry with an `image`. An
-   * entry naming a sprite icon by `id` alone ignores them.
+   * Each is added under its own `id`, so `mapping` returns that id. Its offsets follow
+   * {@link CustomImage}.
    */
   customIcons?: CustomImage[];
   /**
@@ -12723,6 +13248,9 @@ type SectionKnobs = {
    * them off here, and so does `speedLimit`, which posts a sign per section rather than banding
    * the route. The rest draw only when you ask. `motorway` and `urban` each run nearly a route's
    * whole length, so a band drawn for them buries the route line.
+   *
+   * `curve` and `curvyStretch` also need the route request to ask for them, with
+   * `sectionTypes: [...defaultSectionTypes, 'curve', 'curvyStretch']`.
    */
   visible?: boolean;
   /**
@@ -12788,7 +13316,7 @@ type SectionKnobs = {
  *
  * @example
  * ```typescript
- * // Blue curves with yellow kerbs
+ * // On a route calculated with `sectionTypes: [...defaultSectionTypes, 'curve']`: blue curves with yellow kerbs
  * sections: { curve: { visible: true, color: '#0057B8', kerb: { color: '#FFD700' } } }
  * // One plain line
  * sections: { curve: { visible: true, kerb: { visible: false } } }
@@ -12821,9 +13349,8 @@ type SectionSignUnit = 'km/h' | 'mph';
  * Where a section's signs are posted along the stretch they belong to.
  *
  * @remarks
- * - `atChange` - The default. One sign stands where the value changes and none after it, which is
- *   where the road posts its own. Sections of a sign-posting type tile the route end to end, and no
- *   two consecutive ones carry the same value, so every section boundary is a change.
+ * - `atChange` - The default. One sign stands at the start of each section and none along it. A
+ *   section mostly starts where the value changes, which is where the road posts its own.
  * - `along` - The sign repeats down the stretch at a fixed screen spacing, so a reader zoomed into
  *   the middle of a long one still sees the value in force. A stretch too short on screen to fit a
  *   sign draws none.
@@ -12867,8 +13394,8 @@ type SectionSignPriority = 'belowMapLabels' | 'belowRouteIcons' | 'aboveRouteIco
  * entry posts the white disc in km/h.
  *
  * Where mph is posted, the number is converted and rounded to the step signs come in. Without
- * `country` sections, the display units decide the face and the unit, and an explicit {@link unit}
- * overrides both.
+ * `country` sections, the display units decide the face and the unit. An explicit {@link unit}
+ * overrides the unit wherever it came from, and leaves the face alone.
  *
  * A sign stands where the limit changes, and {@link placement} repeats it down the stretch instead.
  * Signs scale with the zoom, as the ferry and toll-road icons do, a tenth smaller than the tunnel
@@ -12929,7 +13456,8 @@ type SectionSignConfig = {
  *
  * @example
  * ```typescript
- * const routes = await calculateRoute({ locations, sectionTypes: ['country'] });
+ * // `country` is among the default section types.
+ * const routes = await calculateRoute({ locations });
  * await routing.showRoutes(routes);
  * ```
  *
@@ -12981,7 +13509,8 @@ type CountryCrossingLabelConfig = {
  * - `duration` - The travel time, traffic included.
  * - `distance` - The route's length, in the display units.
  * - `durationDifference` - How much longer or shorter the route takes than the selected one, such
- *   as `+6 min`. Only the other routes show it, and only when the difference rounds to a minute.
+ *   as `+6 min`. Only the other routes show it, only while a route is selected, and only when the
+ *   difference rounds to a minute.
  * - `trafficDelay` - The summary's `trafficDelayInSeconds`, the delay of the traffic events along
  *   the route, on a line of its own beside an icon coloured by the worst delay along the route.
  *   Only a route with a delay shows it.
@@ -13006,8 +13535,8 @@ type SummaryBubbleRoutes = 'all' | 'selected' | 'alternatives';
  * @remarks
  * The bubble is the text's background, so the text takes no halo. A `title` replaces the text
  * {@link SummaryBubblesConfig.fields} builds. A function title is called for each route when the
- * routes are shown, when another is selected and when the display units change. A route it returns
- * an empty string for gets no bubble.
+ * routes are shown, when another is selected, when the display units or the `title` itself change
+ * and when the bubbles turn visible again. A route it returns an empty string for gets no bubble.
  *
  * @example
  * ```typescript
@@ -13419,8 +13948,9 @@ type RoutingKnob = KnobEntry<RoutingKnobId, Exclude<KnobKind, 'offset' | 'colors
  *
  * @remarks
  * Knobs are plain display values in {@link RoutingModuleConfig}, at the paths their ids name.
- * `layers`, `beforeLayerConfig`, the waypoint images, icon mapping and label title, which take
- * structured, function or MapLibre values, and `events` aren't knobs. A `displayUnits` knob left
+ * `layers`, `beforeLayerConfig`, the waypoint images, icon mapping, label title and
+ * `customTypeface`, which take structured, function or MapLibre values or font files, and `events`
+ * aren't knobs. A `displayUnits` knob left
  * unset follows the global config.
  *
  * @group Routing
@@ -13439,9 +13969,10 @@ export declare const routingKnobIds: readonly RoutingKnobId[];
  * theme or knob has recoloured.
  *
  * @remarks
- * It covers every route layer: the route lines, waypoints, sections, guidance lines, summary
- * bubbles and border crossings. Read it to find a layer's name and what it paints by default, not
- * to spread into {@link RoutingModuleConfig.layers}, which says why.
+ * It covers the route lines, waypoints, sections, guidance lines, summary bubbles, border crossings
+ * and the section focus rings. A generated section type's icon layer is not among them: it exists only
+ * once `sections.<type>.icon.image` is set. Read it to find a layer's name and what it paints by
+ * default, not to spread into {@link RoutingModuleConfig.layers}, which says why.
  *
  * The module builds its own layers per map, so on a dark style, under a theme or with a map
  * typeface, the colours and fonts it draws differ from these.
@@ -13473,7 +14004,11 @@ type DisplayInstructionArrowProps = {
 /**
  * @ignore
  */
-type DisplayInstructionArrows = FeatureCollection<Point, Instruction & DisplayInstructionArrowProps & DisplayRouteRelatedProps>;
+type DisplayInstructionArrow = Feature<Point, Instruction & DisplayInstructionArrowProps & DisplayRouteRelatedProps>;
+/**
+ * @ignore
+ */
+type DisplayInstructionArrows = FeatureCollection<Point, DisplayInstructionArrow['properties']>;
 /**
  * @ignore
  */
@@ -13481,7 +14016,7 @@ type DisplayInstruction = Feature<LineString, Instruction & DisplayRouteRelatedP
 /**
  * @ignore
  */
-type DisplayInstructions = FeatureCollection<LineString, Instruction & DisplayRouteRelatedProps>;
+type DisplayInstructions = FeatureCollection<LineString, DisplayInstruction['properties']>;
 //#endregion
 //#region src/routing/types/planningWaypoint.d.ts
 /**
@@ -13501,6 +14036,9 @@ type DisplayInstructions = FeatureCollection<LineString, Instruction & DisplayRo
  * - `WaypointLike`: Full waypoint with coordinates and optional properties
  * - `null`: Placeholder for unset or removed waypoints
  *
+ * `showWaypoints` draws no pin for a placeholder, but it keeps its position, so the stops after it
+ * keep their numbers.
+ *
  * @example
  * ```typescript
  * // Array of waypoints with some unset
@@ -13511,7 +14049,7 @@ type DisplayInstructions = FeatureCollection<LineString, Instruction & DisplayRo
  * ];
  *
  * // Filter out null waypoints before routing
- * const validWaypoints = waypoints.filter(w => w !== null);
+ * const validWaypoints = waypoints.filter((waypoint) => waypoint !== null);
  * ```
  *
  * @group Routing
@@ -13687,7 +14225,7 @@ type DisplayTrafficSectionProps = DisplaySectionProps & TrafficSectionProps & {
  *
  * @remarks
  * `whiteDisc` is the white disc with a red ring used across most of Europe and in the United Kingdom,
- * `yellowDisc` the same shape as the Nordics post it, and `plaque` the upright rectangle reading
+ * `yellowDisc` the same shape as Sweden, Finland and Iceland post it, and `plaque` the upright rectangle reading
  * `SPEED LIMIT` used in the United States.
  * @ignore
  */
@@ -13717,15 +14255,11 @@ type DisplaySpeedLimitSectionProps = DisplaySectionProps & SpeedLimitSectionProp
 /**
  * @ignore
  */
-type RoutingSourcesWithLayers = { [K in SectionSourceKey<BandedSectionType>]: GeoJSONSourceWithLayers<RouteSections>; } & {
+type RoutingSourcesWithLayers = { [K in SectionSourceKey<BandedSectionType | Exclude<BespokeSectionType, 'traffic'>>]: GeoJSONSourceWithLayers<RouteSections>; } & {
   speedLimitSections: GeoJSONSourceWithLayers<RouteSections<DisplaySpeedLimitSectionProps>>;
   mainLines: GeoJSONSourceWithLayers<Routes<DisplayRouteProps>>;
   waypoints: GeoJSONSourceWithLayers<Waypoints<WaypointDisplayProps>>;
-  vehicleRestricted: GeoJSONSourceWithLayers<RouteSections>;
   incidents: GeoJSONSourceWithLayers<RouteSections<DisplayTrafficSectionProps>>;
-  ferries: GeoJSONSourceWithLayers<RouteSections>;
-  tollRoads: GeoJSONSourceWithLayers<RouteSections>;
-  tunnels: GeoJSONSourceWithLayers<RouteSections>;
   instructionLines: GeoJSONSourceWithLayers<DisplayInstructions>;
   instructionArrows: GeoJSONSourceWithLayers<DisplayInstructionArrows>;
   summaryBubbles: GeoJSONSourceWithLayers<DisplayRouteSummaries>;
@@ -13770,7 +14304,8 @@ type ShowRoutesOptions = {
    * @remarks
    * It is zero-based, matching the position in the routes array. The selected route
    * displays with full colour and prominence, and the other routes are dimmed to show
-   * they are alternatives.
+   * they are alternatives. An index outside the routes selects none, so every route draws
+   * deselected.
    *
    * @default 0 (the first route is shown as selected)
    *
@@ -13950,8 +14485,8 @@ export declare class RoutingModule extends AbstractDataOwnedMapModule<RoutingSou
    */
   private addConfiguredImages;
   /**
-   * Draws the shown waypoints again when a waypoint setting or the time unit their stop durations
-   * read in changed: the icon, stop mark and title each waypoint draws are on the feature.
+   * Draws the shown waypoints again when a setting their features carry or the time unit their stop
+   * durations read in changed: the icon, stop mark and title each waypoint draws are on the feature.
    */
   private reshowWaypoints;
   private displayWaypointsOf;
@@ -13975,27 +14510,26 @@ export declare class RoutingModule extends AbstractDataOwnedMapModule<RoutingSou
    * units and what a `title` function returned for it. Every other setting is the layer's.
    */
   private reshowSummaryBubbles;
-  /** What {@link applySummaryBubbleColors} last painted the bubbles with; see {@link appliedCrossingColors}. */
+  /** What {@link applySummaryBubbleColors} last painted the bubbles with; see {@link appliedCrossingFill}. */
   private appliedSummaryBubbleColors;
   /**
    * Paints the summary bubbles' images in the colours their config and the map's theme resolve to.
    *
    * @remarks
-   * The bubble and the icon of a delay of no known magnitude are images, so a new colour replaces
-   * them. The text colours are in the layer spec, which every config change and restore rebuilds.
+   * The two bubbles and the major and unknown delay icons are images, so a new colour replaces the
+   * one it draws into, and only that one. The text colours are in the layer spec, which every config
+   * change and restore rebuilds.
    */
   private applySummaryBubbleColors;
-  /** The colours the crossings draw with, which follow the map's theme unless configured. */
-  private crossingColors;
   /**
-   * What {@link applyCountryCrossingConfig} last painted the crossings with.
+   * The colour {@link applyCountryCrossingConfig} last painted the crossing bubble in.
    *
    * @remarks
    * Tracked here rather than re-derived from `this.config`, because the theme is an input the
    * config cannot see: a style or a map colour knob moves the resolved colours while the config
    * says the same thing. Cleared when the sources are rebuilt, so a restored style repaints from scratch.
    */
-  private appliedCrossingColors;
+  private appliedCrossingFill;
   /**
    * Brings the border crossings in line with a changed configuration.
    *
@@ -14003,9 +14537,8 @@ export declare class RoutingModule extends AbstractDataOwnedMapModule<RoutingSou
    * The source is gated on `visible`, as the summary bubbles' is, so switching them back on
    * re-derives the features: a layer spec cannot put back data the source does not hold.
    *
-   * Both colours are applied here rather than left to the layer spec: the bubble is an image, so
-   * a new colour has to replace it, and the label's colour follows the map theme, which the spec
-   * that built the layer cannot know about after a style change.
+   * The bubble is an image, so a new colour replaces it here; the label's colour is in the layer
+   * spec, which every config change and restore rebuilds.
    */
   private applyCountryCrossingConfig;
   /**
@@ -14022,15 +14555,16 @@ export declare class RoutingModule extends AbstractDataOwnedMapModule<RoutingSou
    * only while its `sections.<type>.visible` is on as well.
    *
    * @remarks
-   * "Has features" alone is not enough for sections. Almost every route has urban stretches, a
-   * tunnel or a country crossing somewhere along it, so it would draw all seventeen types the moment
-   * a route is shown, whatever the caller asked for.
+   * "Has features" alone is not enough for sections. Almost every route has urban or motorway
+   * stretches somewhere along it, so it would draw every drawn type the route carries the moment it
+   * is shown, whatever the caller asked for.
    *
    * This runs right after anything that shows features and after any config change, in the same
    * tick, so nothing renders in between.
    * @ignore
    */
   protected applyVisibility(config: RoutingModuleConfig | undefined): void;
+  private applySourcesVisibility;
   /** The id of the layer posting this type's signs, for a type that posts them. */
   private signLayerID;
   /**
@@ -14393,7 +14927,7 @@ type HillshadeColors = {
   shaded?: string;
   /** The slopes facing the light. */
   lit?: string;
-  /** The steepest terrain, whichever way it faces. */
+  /** The steepest terrain, whichever way it faces. Used by the `standard` method only. */
   steep?: string;
 };
 /**
@@ -14448,12 +14982,13 @@ type TerrainElevationConfig = {
   /**
    * Whether the map surface is raised in 3D or flat.
    *
-   * @default Flat, unless MapLibre code raised a terrain of its own.
+   * @default Flat, unless the style or your MapLibre code raised a terrain of its own.
    */
   visible?: boolean;
   /**
-   * Vertical scaling of the surface. `1` is true elevation. Higher values emphasise the relief.
-   * It stays while `visible` is off, so turning it back on restores it.
+   * Vertical scaling of the surface this module raises. `1` is true elevation. Higher values emphasise
+   * the relief. It stays while `visible` is off, so turning it back on restores it. With `visible`
+   * unset, a terrain the style or your MapLibre code raised keeps its own.
    *
    * @default 1
    */
@@ -14596,6 +15131,7 @@ export declare class TerrainModule extends AbstractStyleOwnedMapModule<TerrainSo
   protected _initSourcesWithLayers(): {
     hillshade: StyleSourceWithLayers<import("maplibre-gl").SourceSpecification, import("maplibre-gl").Source>;
   };
+  private captureMapTerrain;
   /**
    * @ignore
    */
@@ -14702,7 +15238,7 @@ type AreaAnalyticsScaleMode = 'predefinedRange' | 'currentRange' | 'raw';
  * @example
  * ```typescript
  * // Stops whose values are actual congestion-level values (0–100)
- * const colorStops: AreaAnalyticsColorStopsConfig = {
+ * const rawStops: AreaAnalyticsColorStopsConfig = {
  *   scaleMode: 'raw',
  *   stops: [
  *     { value: 0,   color: '#2dc653' },
@@ -14712,7 +15248,7 @@ type AreaAnalyticsScaleMode = 'predefinedRange' | 'currentRange' | 'raw';
  * };
  *
  * // Stops as 0–100 % of the predefined metric range (speed: 0–120 km/h)
- * const colorStops: AreaAnalyticsColorStopsConfig = {
+ * const predefinedRangeStops: AreaAnalyticsColorStopsConfig = {
  *   scaleMode: 'predefinedRange',
  *   stops: [
  *     { value: 0,   color: '#e03030' },  // 0 km/h
@@ -14722,7 +15258,7 @@ type AreaAnalyticsScaleMode = 'predefinedRange' | 'currentRange' | 'raw';
  * };
  *
  * // Stops as 0–100 % of the live data range (maximum contrast regardless of absolute values)
- * const colorStops: AreaAnalyticsColorStopsConfig = {
+ * const currentRangeStops: AreaAnalyticsColorStopsConfig = {
  *   scaleMode: 'currentRange',
  *   stops: [
  *     { value: 0,   color: '#2dc653' },  // 0% = loaded minimum
@@ -14785,7 +15321,8 @@ type AreaAnalyticsHeightConfig = {
   scaleMode?: Exclude<AreaAnalyticsScaleMode, 'raw'>;
   /**
    * True visual maximum extrusion height in meters.
-   * A cell at the top of the range reaches this height, and none rises above it.
+   * A cell at the top of the range reaches this height, and none rises above it unless
+   * `minMeters` is higher, which every cell then rises to.
    *
    * @defaultValue 1000
    */
@@ -14859,10 +15396,10 @@ type AreaAnalyticsMetricConfig = {
  * @example
  * ```typescript
  * // Every mode on top of the map
- * const config: TrafficAreaAnalyticsModuleConfig = { beforeLayerConfig: 'top' };
+ * const onTop: TrafficAreaAnalyticsModuleConfig = { beforeLayerConfig: 'top' };
  *
  * // Flat modes below labels, extrusions below place labels
- * const config: TrafficAreaAnalyticsModuleConfig = {
+ * const split: TrafficAreaAnalyticsModuleConfig = {
  *   beforeLayerConfig: { all: 'lowestLabel', 'hexgrid-3d': 'lowestPlaceLabel', 'square-3d': 'lowestPlaceLabel' },
  * };
  * ```
@@ -14937,7 +15474,9 @@ type AreaAnalyticsRegionLineConfig = {
   width?: number;
 };
 /**
- * Default values for all {@link TrafficAreaAnalyticsModuleConfig} options.
+ * Default values for the {@link TrafficAreaAnalyticsModuleConfig} options with a fixed default.
+ * The region colour follows the map's theme, each display mode has its own default place in the
+ * layer stack, and a raw height's `metersPerUnit` defaults to 1.
  *
  * Use these as a reference for what the module applies when a property is omitted,
  * or spread them as a base when constructing a config programmatically.
@@ -15250,6 +15789,7 @@ export type TrafficCommonFilter = {
    * @remarks
    * Provides finer-grained control for street and service roads.
    * Applies to sub-categories of {@link StreetRoadSubCategory} and {@link ServiceRoadSubCategory}.
+   * Roads with no sub-category, such as motorways, match none of the values, so `show: 'only'` drops them.
    *
    * @example
    * ```ts
@@ -15267,7 +15807,8 @@ export type TrafficCommonFilter = {
  */
 export type FiltersWithAlternatives<FILTER> = FILTER & {
   /**
-   * Further filters, each an alternative a feature may match instead of the one set beside them.
+   * Further filters, each an alternative a feature may match instead of the one set beside them. An
+   * alternative with no field set adds none, rather than matching every feature.
    */
   any?: FILTER[];
 };
@@ -15304,7 +15845,9 @@ export type TrafficFlowFilter = TrafficCommonFilter & {
  * The filters deciding which roads show traffic flow, alternatives in `any` included.
  *
  * @remarks
- * A road shows when it matches the filter the fields set here, or one of `any`. The knobs of
+ * A road shows when it matches the filter the fields set here, or one of `any`. A filter with no field
+ * set adds no alternative, so with no field set here only `any` decides, and with neither every road
+ * shows. The knobs of
  * {@link trafficFlowKnobCatalogue} set the fields here, while `any` is config only.
  *
  * @example
@@ -15436,7 +15979,7 @@ export type IncidentHighlightConfig = {
  */
 export type IncidentLineConfig = {
   /**
-   * Opacity of the incident lines, from 0 to 1. The markers and the outline of a highlighted
+   * Opacity of the incident lines, from 0 to 1, a value outside it clamped. The markers and the outline of a highlighted
    * incident stay opaque, so a focused incident still stands out.
    *
    * @defaultValue `1`
@@ -15475,11 +16018,14 @@ export type TrafficIncidentDetailsLayersConfig = {
   innerChevron?: Partial<ToBeAddedLayerSpecTemplate<LineLayerSpecification>>;
   /** The patterned stripe of the `unknown` (no delay) and `indefinite` (road closed) incidents. */
   innerPattern?: Partial<ToBeAddedLayerSpecTemplate<LineLayerSpecification>>;
-  /** The category icon of every incident but jams and closed roads. */
+  /**
+   * The category icon of every incident whose delay is not `indefinite`, but jams, closed roads,
+   * animals on the road and narrow lanes.
+   */
   incidentMarker?: Partial<ToBeAddedLayerSpecTemplate<SymbolLayerSpecification>>;
   /** The jam icon with its delay text. */
   jamMarker?: Partial<ToBeAddedLayerSpecTemplate<SymbolLayerSpecification>>;
-  /** The closed-road icon. */
+  /** The closed-road icon, on every incident with an `indefinite` delay, whatever its category. */
   closedRoadMarker?: Partial<ToBeAddedLayerSpecTemplate<SymbolLayerSpecification>>;
 };
 /**
@@ -15498,8 +16044,8 @@ export type TrafficIncidentDetailsModuleConfig = MapModuleCommonConfig & {
    * The map-style layer to position incident layers before. Pass `'top'` to
    * pin them above every other layer. Defaults to `'lowestLabel'`, which
    * keeps incidents below map labels (roads, places, POIs) so labels stay
-   * readable. The routing module and the flat area analytics layers use the
-   * same default.
+   * readable. The routing module's route lines and the flat area analytics
+   * layers use the same default.
    */
   beforeLayerConfig?: BeforeLayerConfig;
   /**
@@ -15624,7 +16170,9 @@ export type TrafficIncidentsFilter = TrafficCommonFilter & {
  * The filters deciding which incidents are shown, alternatives in `any` included.
  *
  * @remarks
- * An incident shows when it matches the filter the fields set here, or one of `any`. The knobs of
+ * An incident shows when it matches the filter the fields set here, or one of `any`. A filter with no
+ * field set adds no alternative, so with no field set here only `any` decides, and with neither every
+ * incident shows. The knobs of
  * {@link trafficIncidentsKnobCatalogue} set the fields here, while `any` is config only.
  *
  * @example
@@ -15660,7 +16208,7 @@ export type IncidentIconsConfig = {
  * The colours of the incident lines, per delay magnitude.
  *
  * @remarks
- * If unset, a magnitude keeps the loaded style's colour. The incident details highlight, the route
+ * If unset, a magnitude keeps the loaded style's colour. The incident details lines, the route
  * traffic sections and bloom's `only` scope read these, so a recoloured magnitude stays recoloured
  * there too.
  *
@@ -15673,7 +16221,7 @@ export type TrafficIncidentColors = {
   moderate?: string;
   /** Major delays. */
   major?: string;
-  /** Indefinite delays, meaning closed roads. */
+  /** The outline of indefinite delays, meaning closed roads. */
   closed?: string;
 };
 /**
@@ -15758,7 +16306,8 @@ type TrafficFlowKnobId = 'visible' | ValuesFilterKnobId<`filters.${Exclude<keyof
 type TrafficFlowKnobValueOf<ID extends TrafficFlowKnobId> = KnobPlainValue<ValueAt<TrafficFlowModuleConfig, ID>>;
 /**
  * One entry of {@link trafficFlowKnobCatalogue}. The value in force is the one at its path in
- * {@link TrafficFlowModule.getConfig}, otherwise its `default`.
+ * {@link TrafficFlowModule.getConfig}, otherwise its `default`. With neither, a colour is the loaded
+ * style's own, and any other entry says what it follows.
  *
  * @group Traffic Flow
  */
@@ -15806,11 +16355,16 @@ type TrafficIncidentDetailsKnobValueOf<ID extends TrafficIncidentDetailsKnobId>
 /**
  * One entry of {@link trafficIncidentDetailsKnobCatalogue}. The value in force is the one at its
  * path in {@link TrafficIncidentDetailsModule.getConfig}, otherwise its `default`. With neither, the
- * map's light/dark theme decides.
+ * map's light/dark theme decides. Under `highlight: false`, a `highlight.*` knob reads its
+ * `default` though nothing draws it, and setting one turns the highlight back on.
  *
  * @group Traffic Incident Details
  */
 type TrafficIncidentDetailsKnob = KnobEntry<TrafficIncidentDetailsKnobId, TrafficKnobKind>;
+/**
+ * An area analytics knob's path below `metrics.<metric>.`, whichever metric takes it.
+ * @ignore
+ */
 type AreaAnalyticsMetricKnobLeaf = 'palette' | `height.${KeyOfEither<AreaAnalyticsHeightConfig>}` | `filters.${keyof AreaAnalyticsMetricFilter}`;
 /**
  * The id of an area analytics knob, its path into {@link TrafficAreaAnalyticsModuleConfig}, e.g.
@@ -15822,7 +16376,7 @@ type AreaAnalyticsMetricKnobLeaf = 'palette' | `height.${KeyOfEither<AreaAnalyti
  *
  * @group Traffic Area Analytics
  */
-type TrafficAreaAnalyticsKnobId = 'visible' | 'displayMode' | 'activeMetric' | 'regionPolygon.color' | `regionPolygon.fill.${keyof AreaAnalyticsRegionFillConfig}` | `regionPolygon.line.${keyof AreaAnalyticsRegionLineConfig}` | `metrics.${AreaAnalyticsMetricKey}.${AreaAnalyticsMetricKnobLeaf}`;
+type TrafficAreaAnalyticsKnobId = 'visible' | 'displayMode' | 'activeMetric' | `regionPolygon.${LeafPathOf<AreaAnalyticsRegionPolygonConfig>}` | `metrics.${AreaAnalyticsMetricKey}.${AreaAnalyticsMetricKnobLeaf}`;
 /**
  * The value type of an area analytics knob, the plain value its path holds in
  * {@link TrafficAreaAnalyticsModuleConfig}.
@@ -15846,8 +16400,8 @@ type TrafficAreaAnalyticsKnob = KnobEntry<TrafficAreaAnalyticsKnobId, TrafficKno
  *
  * @remarks
  * The module owns whether flow is shown, which roads show it and how the flow lines look
- * (`colors.*`, `widthFactor`). The `filters.*` knobs set the fields of `filters`. Its `any`, the
- * further filters a road may match instead, is config only, as are `events`.
+ * (`colors.*`, `widthFactor`, `opacityFactor`). The `filters.*` knobs set the fields of `filters`. Its
+ * `any`, the further filters a road may match instead, is config only, as are `events`.
  *
  * @group Traffic Flow
  */
@@ -15864,8 +16418,8 @@ export declare const trafficFlowKnobIds: readonly TrafficFlowKnobId[];
  *
  * @remarks
  * The module owns whether incidents are shown, which, and how their lines look (`colors.*`,
- * `widthFactor`). The `filters.*` knobs set the fields of `filters`. Its `any`, the further
- * filters an incident may match instead, is config only, as are `events`.
+ * `widthFactor`, `opacityFactor`). The `filters.*` knobs set the fields of `filters`. Its `any`, the
+ * further filters an incident may match instead, is config only, as are `events`.
  *
  * @group Traffic Incidents
  */
@@ -15916,7 +16470,7 @@ export declare const trafficAreaAnalyticsKnobIds: readonly TrafficAreaAnalyticsK
 //#region src/traffic/layers/areaAnalyticsLayers.d.ts
 /**
  * Returns a metric's cell colour stops. These are its `colorStops` if they hold a stop, otherwise its
- * `palette` (`trafficLight` when unset) spread evenly from 0 to 100 % of the metric's range, as
+ * `palette` (its {@link AREA_ANALYTICS_DEFAULTS} one when unset) spread evenly from 0 to 100 % of the metric's range, as
  * {@link AreaAnalyticsMetricConfig.palette} describes.
  *
  * @group Traffic Area Analytics
@@ -15928,7 +16482,7 @@ export declare const resolveColorStops: (metric: AreaAnalyticsMetricKey, metricC
  * Properties attached to each area analytics display feature.
  *
  * @remarks
- * They include all optional metric fields from the API response, a stable `id` that
+ * They include every metric, a metric the API response lacks reading 0, a stable `id` that
  * MapLibre's `promoteId` uses for event state tracking, and `eventState` (from
  * `SupportsEvents`), which drives hover/click styling.
  *
@@ -15983,6 +16537,8 @@ type AreaAnalyticsSourcesWithLayers = {
  * await module.show(analytics);
  * ```
  *
+ * @see [Traffic Area Analytics Module Guide](https://docs.tomtom.com/maps-sdk-js/guides/map/traffic-area-analytics-module)
+ *
  * @group Traffic Area Analytics
  */
 export declare class TrafficAreaAnalyticsModule extends AbstractDataOwnedMapModule<AreaAnalyticsSourcesWithLayers, TrafficAreaAnalyticsModuleConfig> {
@@ -16005,7 +16561,8 @@ export declare class TrafficAreaAnalyticsModule extends AbstractDataOwnedMapModu
    * All configuration properties are optional. Built-in defaults fill every field that `config`
    * omits, or all of them if you omit `config`. After `create()` resolves,
    * {@link TrafficAreaAnalyticsModule.getConfig} returns the display mode, the active metric and
-   * every metric's settings with defaults filled in, so you don't need to reference them. A field
+   * every metric's `palette` and `height` with defaults filled in, so you don't need to reference
+   * them. A `height` you pass replaces the default one whole, its unset fields left out. A field
    * you clear by passing `undefined` to its setter is left out until the next `applyConfig`,
    * `updateConfig` or knob write, which fills its default in again.
    *
@@ -16267,11 +16824,11 @@ type TrafficFlowSourcesWithLayers = {
  * - Real-time traffic data from vector tiles
  * - Filter road closures
  *
- * The colours:
+ * The standard styles' colours, which `colors.*` can change:
  * - Green: Free-flowing traffic
  * - Yellow/Orange: Slow traffic
  * - Red: Heavy congestion
- * - Dark gray: Road closures
+ * - Red outline: Road closures
  *
  * @example
  * Basic usage:
@@ -16320,6 +16877,7 @@ type TrafficFlowSourcesWithLayers = {
  * @group Traffic Flow
  */
 export declare class TrafficFlowModule extends AbstractStyleOwnedMapModule<TrafficFlowSourcesWithLayers, TrafficFlowModuleConfig> {
+  private appliedFilters;
   /**
    * Retrieves a TrafficFlowModule instance for the given map.
    *
@@ -16337,7 +16895,9 @@ export declare class TrafficFlowModule extends AbstractStyleOwnedMapModule<Traff
    *
    * {@link trafficFlowKnobCatalogue} lists the plain-valued settings as data.
    *
-   * If the style lacks traffic flow, `get()` reloads it with the `trafficFlow` part included.
+   * If the style lacks traffic flow, `get()` reloads it with the `trafficFlow` part included. A later
+   * `get()` on the same map returns the same instance, and a config passed to it replaces the one it
+   * holds, as `applyConfig` does.
    *
    * @example
    * Default initialization:
@@ -16360,12 +16920,6 @@ export declare class TrafficFlowModule extends AbstractStyleOwnedMapModule<Traff
    *   }
    * });
    * ```
-   *
-   * @remarks
-   * `TrafficFlowModule` controls the traffic-flow source and layers the map style already
-   * provides, under fixed global IDs. Every instance is another handle on that shared state, so
-   * visibility and filters you apply through one show through all of them. A config passed to a
-   * later `get()` replaces the one it holds, as `applyConfig` does.
    */
   static get(map: TomTomMap, config?: TrafficFlowModuleConfig): Promise<TrafficFlowModule>;
   private constructor();
@@ -16410,25 +16964,24 @@ export declare class TrafficFlowModule extends AbstractStyleOwnedMapModule<Traff
    * @remarks
    * This is the only way to read live flow values, because Orbis traffic flow is vector tiles, with
    * no service for a road, a point or an area. Results cover what is drawn in the current viewport and zoom, so a
-   * hidden module returns none, and a segment crossing a tile boundary appears once per tile. See {@link TrafficFlowModuleFeature} for what each carries.
+   * hidden module returns none. A segment appears once per layer drawing it, its outline included, and once per
+   * tile it crosses, so the results do not count segments. See {@link TrafficFlowModuleFeature} for what each carries.
    *
    * @example
    * ```typescript
    * const rendered = trafficFlow.getRenderedFeatures();
-   * console.log(`Visible flow segments: ${rendered.trafficFlow.length}`);
    * rendered.trafficFlow.forEach(segment => {
    *   console.log('Road segment:', segment.properties);
    * });
    * ```
    *
    * @example
-   * Analyze congestion in viewport:
+   * Check the viewport for congestion:
    * ```typescript
    * const rendered = trafficFlow.getRenderedFeatures();
-   * const congested = rendered.trafficFlow.filter(
+   * const congested = rendered.trafficFlow.some(
    *   segment => segment.properties.relativeSpeed < 0.5
    * );
-   * console.log(`Congested segments: ${congested.length}`);
    * ```
    */
   getRenderedFeatures(): {
@@ -16534,15 +17087,14 @@ type Sources = {
  * @group Traffic Incident Details
  */
 export declare class TrafficIncidentDetailsModule extends AbstractDataOwnedMapModule<Sources, TrafficIncidentDetailsModuleConfig> {
-  private lastFeatureIds;
   private lastFocusIds;
   private readonly shownFeaturesHandlers;
   /**
    * Creates a new module instance on the given map, once the map is ready.
    *
-   * `TrafficIncidentDetailsModule` owns the sources, layers and images it adds, all suffixed per
-   * instance. So every call returns a new, independent instance, and you can stack several on
-   * one map.
+   * `TrafficIncidentDetailsModule` owns the sources and layers it adds, all suffixed per instance,
+   * and shares only its direction chevron image. So every call returns a new, independent instance,
+   * and you can stack several on one map.
    *
    * {@link trafficIncidentDetailsKnobCatalogue} lists the plain-valued settings of `config` as data.
    *
@@ -16573,12 +17125,8 @@ export declare class TrafficIncidentDetailsModule extends AbstractDataOwnedMapMo
    */
   clear(): Promise<void>;
   /**
-   * Returns the currently shown incidents, which are the exact data passed to {@link show}.
-   *
-   * It reads the module's client-side cache (`shownFeatures`), like the other GeoJSON modules
-   * (`PlacesModule`, `TrafficAreaAnalyticsModule`, `GeometriesModule`). It does not hit-test the
-   * viewport. The proxy already scopes and de-duplicates the `allEventFeatures` it dispatches to
-   * click handlers, so no caller needs viewport-level de-duplication here.
+   * Returns the currently shown incidents, which are the exact data passed to {@link show}, not
+   * what the viewport hit-tests.
    */
   getShown(): {
     incidents: TrafficIncidentDetails;
@@ -16752,6 +17300,7 @@ type TrafficIncidentsSourcesWithLayers = {
  * @group Traffic Incidents
  */
 export declare class TrafficIncidentsModule extends AbstractStyleOwnedMapModule<TrafficIncidentsSourcesWithLayers, TrafficIncidentsModuleConfig> {
+  private appliedFilters;
   /**
    * Retrieves a TrafficIncidentsModule instance for the given map.
    *
@@ -16772,6 +17321,8 @@ export declare class TrafficIncidentsModule extends AbstractStyleOwnedMapModule<
    * {@link trafficIncidentsKnobCatalogue} lists the plain-valued settings as data.
    *
    * When the style lacks traffic incidents, `get()` reloads it with the `trafficIncidents` part included.
+   * A later `get()` on the same map returns the same instance, and a config passed to it replaces the
+   * one it holds, as `applyConfig` does.
    *
    * @example
    * Default initialization:
@@ -16795,12 +17346,6 @@ export declare class TrafficIncidentsModule extends AbstractStyleOwnedMapModule<
    *   }
    * });
    * ```
-   *
-   * @remarks
-   * `TrafficIncidentsModule` controls the traffic-incident source and layers the map style already
-   * provides, under fixed global IDs. Every instance is another handle on that shared state, so
-   * visibility and filters you apply through one show through all of them. A config passed to a
-   * later `get()` replaces the one it holds, as `applyConfig` does.
    */
   static get(map: TomTomMap, config?: TrafficIncidentsModuleConfig): Promise<TrafficIncidentsModule>;
   private constructor();
@@ -16892,26 +17437,25 @@ export declare class TrafficIncidentsModule extends AbstractStyleOwnedMapModule<
    *
    * @remarks
    * It returns all incident features currently rendered in the visible map area,
-   * including both incident areas/lines and icon markers. See {@link TrafficIncidentsModuleFeature}
-   * for what each carries.
+   * including both incident areas/lines and icon markers. An incident appears once per layer
+   * drawing it, its outline, line and icon each, and once per tile it crosses, so the results do
+   * not count incidents. See {@link TrafficIncidentsModuleFeature} for what each carries.
    *
    * @example
    * ```typescript
    * const rendered = incidents.getRenderedFeatures();
-   * console.log(`Visible incidents: ${rendered.trafficIncidents.length}`);
    * rendered.trafficIncidents.forEach(incident => {
    *   console.log('Incident:', incident.properties);
    * });
    * ```
    *
    * @example
-   * Filter and analyze visible incidents:
+   * Check the viewport for accidents:
    * ```typescript
    * const rendered = incidents.getRenderedFeatures();
-   * const accidents = rendered.trafficIncidents.filter(
+   * const accidentInView = rendered.trafficIncidents.some(
    *   incident => incident.properties.category === 'accident'
    * );
-   * console.log(`Accidents in view: ${accidents.length}`);
    * ```
    */
   getRenderedFeatures(): {
@@ -16970,8 +17514,8 @@ export declare const hueDistance: ({ h: hue }: HslColor, { h: otherHue }: HslCol
  * - `mercatorMeters` - EPSG:3857 (Web Mercator) metres, which stretch ground metres by 1/cos(latitude):
  *   the frame of geometry authored in that coordinate system, such as 3D tiles.
  *
- * Its metres are EPSG:3857's, on the WGS84 equator's radius, which makes them 0.11% longer than the
- * metres of MapLibre's `MercatorCoordinate`.
+ * Its metres are EPSG:3857's, on the WGS84 equator's radius, which makes them 0.11% shorter than the
+ * metres of MapLibre's `MercatorCoordinate`, on its mean Earth radius.
  *
  * @group Utils
  */
@@ -17106,8 +17650,10 @@ export declare const calculatePaddedCenter: (options: CalculateMapCenterOptions)
  * portion of the map (the area UI components don't cover). The function returns a larger bounding
  * box that accounts for the space the UI elements take.
  *
- * Its latitudes stay within Web Mercator's ±85.051129. For a `toBeContainedBBox` across the
- * antimeridian, with west greater than east, the returned east passes 180, as `fitBounds` takes it.
+ * It expands the latitudes in Web Mercator, as `fitBounds` frames them, and they stay within its ±85.051129.
+ * The returned longitudes can pass ±180, as `fitBounds` takes them: east always does for a
+ * `toBeContainedBBox` across the antimeridian, with west greater than east, and either one does when
+ * the expansion reaches past it.
  *
  * @returns The expanded bounding box as [west, south, east, north], or null if the visible area is too small
  *
@@ -17115,4 +17661,4 @@ export declare const calculatePaddedCenter: (options: CalculateMapCenterOptions)
  */
 export declare const calculateFittingBBox: (options: CalculateFittingBBoxOptions) => BBox | null;
 //#endregion
-export type { AreaAnalyticsBeforeLayerConfig, AreaAnalyticsColorStop, AreaAnalyticsColorStopsConfig, AreaAnalyticsDisplayMode, AreaAnalyticsHeightConfig, AreaAnalyticsMetricConfig, AreaAnalyticsMetricFilter, AreaAnalyticsPalette, AreaAnalyticsRegionFillConfig, AreaAnalyticsRegionLineConfig, AreaAnalyticsRegionPolygonConfig, AreaAnalyticsScaleMode, AttributionOptions, BaseMapColorName, BaseMapKnob, BaseMapKnobId, BaseMapKnobValueOf, BeforeLayerConfig, BespokeSectionType, ByIdOrIndex, CSSCursor, ClearEventStateOptions, ClearEventStatesOptions, ClickEventType, CountryCrossingConfig, CountryCrossingFeature, CountryCrossingLabelConfig, CustomGeoJSONKnob, CustomGeoJSONKnobId, CustomGeoJSONKnobValueOf, CustomImage, CustomLayerEventsOptions, CustomLayerHit, CustomLayerHitTest, CustomLayerOptions, CustomTypeface, CustomTypefaceFile, DefaultPlaceIconConfig, DisplayCountryCrossing, DisplayCountryCrossingProps, DisplayCountryCrossings, DisplayRouteProps, DisplayRouteRelatedProps, DisplayRouteSummaries, DisplayRouteSummary, DisplayRouteSummaryProps, DisplayWaypoint, DragEventType, DrawnSectionType, EventHandlerConfig, EventHandlerCursorConfig, EventHandlerHoverConfig, EventScope, EventState, EventStateIds, EventType, ExtraFeatureProp, FeatureLabelConfig, FeaturePropValue, FilterablePOICategory, GeneratedSectionType, GeoJSONSourceClusterOptions, GeoJSONSourcesWithLayers, GeometriesKnob, GeometriesKnobId, GeometriesKnobValueOf, HasAdditionalLayersConfig, HasBeforeID, HillshadeColors, HillshadeLightAlignment, HillshadeLightConfig, HillshadeMethod, HoverEventType, HslColor, IconMapping, IndexedFeature, LabelConfig, LayerPropertyDerivation, LayerPropertyValues, LayerQuery, LayerSpecFilter, LayerSpecTemplate, LayerSpecWithSource, LightDark, MapColorName, MapColors, MapEventsConfig, MapFont, MapLibreOptions, MapModuleCommonConfig, MapPreset, MapPresetId, MapPresetSettings, MapRequestTransform, MapStyleLayerID, MapStylePOICategory, MapTypeface, POIIconConfig, POILabelConfig, POIsKnob, POIsKnobId, POIsKnobValueOf, POIsModuleConfig, POIsModuleFeature, POIsModuleSerializableConfig, PartsBeforeLayerConfig, PinIconConfig, PlaceClusterBadgeConfig, PlaceConnectionDisplay, PlaceConnectionLabelConfig, PlaceConnectionLayerName, PlaceConnectionsConfig, PlaceConnectionsLayersConfig, PlaceEntryPointFeature, PlaceEntryPointProps, PlaceEntryPointsConfig, PlaceEntryPointsLayersConfig, PlaceEntryPointsShowFor, PlaceIconConfig, PlaceLabelConfig, PlaceLayerName, PlaceLayersConfig, PlacesBeforeLayerConfig, PlacesClusterConfig, PlacesClusterSourceConfig, PlacesKnob, PlacesKnobId, PlacesKnobValueOf, PlacesMarkerType, PlacesModuleConfig, PlacesModuleSerializableConfig, PlanningWaypoint, RGBAColor, ReachableRangesKnob, ReachableRangesKnobId, ReachableRangesKnobValueOf, RenderedRef, ResolvedEventScope, RouteHighlightConfig, RouteLayersConfig, RouteStateProps, RouteWaypointSize, RouteWidth, RoutingBeforeLayerConfig, RoutingKnob, RoutingKnobId, RoutingKnobValueOf, RoutingModuleConfig, RoutingModuleSerializableConfig, SVGIconStyleOptions, SectionDisplayConfig, SectionDrawStyle, SectionIconConfig, SectionIconPlacement, SectionKerbConfig, SectionKerbLayerName, SectionKnobName, SectionKnobOf, SectionLineLayerName, SectionSignConfig, SectionSignLayerName, SectionSignPlacement, SectionSignPriority, SectionSignUnit, SectionSourceKey, SectionSymbolLayerName, SectionTypeWithKnob, SectionsDisplayConfig, SerializableCustomImage, SerializableFeatureLabelConfig, SerializablePinIconConfig, SetEventStateOptions, ShowOptions, SourceWithLayerIDs, SourceWithLayers, SourcesWithLayers, StandardStyle, StandardStyleID, StyleColorKnobId, StyleInput, StyleKnobId, StyleKnobValueOf, StyleLayerGroupName, StyleModuleLayerGroupName, StylePart, StyleSourcesWithLayers, StylingFoundationsKnob, StylingFoundationsKnobAppliesTo, StylingFoundationsKnobId, StylingFoundationsKnobKind, StylingFoundationsKnobRange, StylingFoundationsKnobValue, StylingFoundationsKnobValueOf, StylingFoundationsModuleConfig, SummaryBubbleField, SummaryBubbleLabelConfig, SummaryBubbleRoutes, SummaryBubblesConfig, SupportsEvents, TerrainElevationConfig, TerrainHillshadeConfig, TerrainKnob, TerrainKnobId, TerrainKnobValueOf, TerrainModuleConfig, ToBeAddedLayerSpec, ToBeAddedLayerSpecTemplate, ToBeAddedLayerSpecWithoutSource, TomTomMapParams, TrafficAreaAnalyticsKnob, TrafficAreaAnalyticsKnobId, TrafficAreaAnalyticsKnobValueOf, TrafficAreaAnalyticsLayersConfig, TrafficAreaAnalyticsModuleConfig, TrafficFlowKnob, TrafficFlowKnobId, TrafficFlowKnobValueOf, TrafficIncidentDetailsKnob, TrafficIncidentDetailsKnobId, TrafficIncidentDetailsKnobValueOf, TrafficIncidentsKnob, TrafficIncidentsKnobId, TrafficIncidentsKnobValueOf, UserEventHandler, WaypointDisplayProps, WaypointHighlightConfig, WaypointIconConfig, WaypointIndexType, WaypointLabelConfig, WaypointStopNumbering, WaypointsConfig };
+export type { AreaAnalyticsBeforeLayerConfig, AreaAnalyticsColorStop, AreaAnalyticsColorStopsConfig, AreaAnalyticsDisplayMode, AreaAnalyticsHeightConfig, AreaAnalyticsMetricConfig, AreaAnalyticsMetricFilter, AreaAnalyticsPalette, AreaAnalyticsRegionFillConfig, AreaAnalyticsRegionLineConfig, AreaAnalyticsRegionPolygonConfig, AreaAnalyticsScaleMode, AttributionOptions, AttributionPadding, AttributionPosition, BaseMapColorName, BaseMapKnob, BaseMapKnobId, BaseMapKnobValueOf, BeforeLayerConfig, BespokeSectionType, CountryCrossingConfig, CountryCrossingFeature, CountryCrossingLabelConfig, CustomGeoJSONKnob, CustomGeoJSONKnobId, CustomGeoJSONKnobValueOf, CustomImage, CustomLayerEventsOptions, CustomLayerHit, CustomLayerHitTest, CustomLayerOptions, CustomTypeface, CustomTypefaceFile, DefaultPlaceIconConfig, DisplayCountryCrossing, DisplayCountryCrossingProps, DisplayCountryCrossings, DisplayRouteProps, DisplayRouteRelatedProps, DisplayRouteSummaries, DisplayRouteSummary, DisplayRouteSummaryProps, DisplayWaypoint, DrawnSectionType, EventScope, ExtraFeatureProp, FeatureLabelConfig, FeaturePropValue, FilterablePOICategory, GeneratedSectionType, GeoJSONSourceClusterOptions, GeoJSONSourcesWithLayers, GeometriesKnob, GeometriesKnobId, GeometriesKnobValueOf, HasAdditionalLayersConfig, HasBeforeID, HillshadeColors, HillshadeLightAlignment, HillshadeLightConfig, HillshadeMethod, HslColor, IconMapping, IndexedFeature, LabelConfig, LayerPropertyDerivation, LayerPropertyValues, LayerQuery, LayerSpecFilter, LayerSpecTemplate, LayerSpecWithSource, LightDark, MapColorName, MapColors, MapEventsConfig, MapFont, MapLibreOptions, MapLight, MapModuleCommonConfig, MapPreset, MapPresetId, MapPresetSettings, MapRequestTransform, MapStyleLayerID, MapStylePOICategory, MapTypeface, POIIconConfig, POILabelConfig, POIsKnob, POIsKnobId, POIsKnobValueOf, POIsModuleConfig, POIsModuleFeature, POIsModuleSerializableConfig, PartsBeforeLayerConfig, PinIconConfig, PlaceClusterBadgeConfig, PlaceConnectionDisplay, PlaceConnectionLabelConfig, PlaceConnectionLayerName, PlaceConnectionsConfig, PlaceConnectionsLayersConfig, PlaceEntryPointFeature, PlaceEntryPointProps, PlaceEntryPointsConfig, PlaceEntryPointsLayersConfig, PlaceEntryPointsShowFor, PlaceIconConfig, PlaceLabelConfig, PlaceLayerName, PlaceLayersConfig, PlacesBeforeLayerConfig, PlacesClusterConfig, PlacesClusterSourceConfig, PlacesKnob, PlacesKnobId, PlacesKnobValueOf, PlacesMarkerType, PlacesModuleConfig, PlacesModuleSerializableConfig, PlanningWaypoint, RGBAColor, ReachableRangesKnob, ReachableRangesKnobId, ReachableRangesKnobValueOf, RenderedRef, ResolvedEventScope, RouteHighlightConfig, RouteLayersConfig, RouteStateProps, RouteWaypointSize, RouteWidth, RoutingBeforeLayerConfig, RoutingKnob, RoutingKnobId, RoutingKnobValueOf, RoutingModuleConfig, RoutingModuleSerializableConfig, SVGIconStyleOptions, SectionDisplayConfig, SectionDrawStyle, SectionIconConfig, SectionIconPlacement, SectionKerbConfig, SectionKerbLayerName, SectionKnobName, SectionKnobOf, SectionLineLayerName, SectionSignConfig, SectionSignLayerName, SectionSignPlacement, SectionSignPriority, SectionSignUnit, SectionSourceKey, SectionSymbolLayerName, SectionTypeWithKnob, SectionsDisplayConfig, SerializableCustomImage, SerializableFeatureLabelConfig, SerializablePinIconConfig, ShowOptions, SourceWithLayerIDs, SourceWithLayers, SourcesWithLayers, StandardStyle, StandardStyleID, StyleColorKnobId, StyleInput, StyleKnobId, StyleKnobValueOf, StyleLayerGroupName, StyleModuleLayerGroupName, StylePart, StyleSourcesWithLayers, StylingFoundationsKnob, StylingFoundationsKnobAppliesTo, StylingFoundationsKnobId, StylingFoundationsKnobKind, StylingFoundationsKnobRange, StylingFoundationsKnobValue, StylingFoundationsKnobValueOf, StylingFoundationsModuleConfig, SummaryBubbleField, SummaryBubbleLabelConfig, SummaryBubbleRoutes, SummaryBubblesConfig, TerrainElevationConfig, TerrainHillshadeConfig, TerrainKnob, TerrainKnobId, TerrainKnobValueOf, TerrainModuleConfig, ToBeAddedLayerSpec, ToBeAddedLayerSpecTemplate, ToBeAddedLayerSpecWithoutSource, TomTomMapParams, TrafficAreaAnalyticsKnob, TrafficAreaAnalyticsKnobId, TrafficAreaAnalyticsKnobValueOf, TrafficAreaAnalyticsLayersConfig, TrafficAreaAnalyticsModuleConfig, TrafficFlowKnob, TrafficFlowKnobId, TrafficFlowKnobValueOf, TrafficIncidentDetailsKnob, TrafficIncidentDetailsKnobId, TrafficIncidentDetailsKnobValueOf, TrafficIncidentsKnob, TrafficIncidentsKnobId, TrafficIncidentsKnobValueOf, WaypointDisplayProps, WaypointHighlightConfig, WaypointIconConfig, WaypointIndexType, WaypointLabelConfig, WaypointStopNumbering, WaypointsConfig };