@tomtom-org/maps-sdk 0.51.5 → 0.52.0

package/map/dist/index.d.ts

@@ -230,7 +230,7 @@ type MapEventsConfig = EventHandlerCursorConfig & {
  *
  * @group Map Style
  */
-declare const standardStyleIDs: readonly ["standardLight", "standardDark", "drivingLight", "drivingDark", "monoLight", "monoDark", "satellite"];
+export declare const standardStyleIDs: readonly ["standardLight", "standardDark", "drivingLight", "drivingDark", "monoLight", "monoDark", "satellite"];
 /**
  * Identifier for a TomTom-hosted standard map style.
  *
@@ -254,7 +254,7 @@ declare const standardStyleIDs: readonly ["standardLight", "standardDark", "driv
  *
  * @group Map Style
  */
-type StandardStyleID = (typeof standardStyleIDs)[number];
+export type StandardStyleID = (typeof standardStyleIDs)[number];
 /**
  * Configuration for a TomTom standard map style.
  *
@@ -282,7 +282,7 @@ type StandardStyleID = (typeof standardStyleIDs)[number];
  *
  * @group Map Style
  */
-type StandardStyle = {
+export type StandardStyle = {
   /**
    * Standard style identifier.
    *
@@ -362,7 +362,7 @@ type StandardStyle = {
  *
  * @group Map Style
  */
-type CustomStyle = {
+export type CustomStyle = {
   /**
    * URL to a MapLibre/Mapbox style JSON.
    *
@@ -403,7 +403,7 @@ type CustomStyle = {
  *
  * @group Map Style
  */
-declare const styleModules: readonly ["trafficIncidents", "trafficFlow", "hillshade"];
+export declare const styleModules: readonly ["trafficIncidents", "trafficFlow", "hillshade"];
 /**
  * Optional map modules that can be included with a style.
  *
@@ -414,7 +414,7 @@ declare const styleModules: readonly ["trafficIncidents", "trafficFlow", "hillsh
  *
  * @group Map Style
  */
-type StyleModule = (typeof styleModules)[number];
+export type StyleModule = (typeof styleModules)[number];
 /**
  * Map style specification for initialization.
  *
@@ -454,7 +454,7 @@ type StyleModule = (typeof styleModules)[number];
  *
  * @group Map Style
  */
-type StyleInput = StandardStyleID | (StandardStyle & {
+export type StyleInput = StandardStyleID | (StandardStyle & {
   type: 'standard';
 }) | (CustomStyle & {
   type: 'custom';
@@ -476,7 +476,7 @@ type StyleInput = StandardStyleID | (StandardStyle & {
  *
  * @group Map
  */
-type MapLibreOptions = Omit<MapOptions, 'style' | 'attributionControl'>;
+export type MapLibreOptions = Omit<MapOptions, 'style' | 'attributionControl'>;
 /**
  * Parameters for initializing a TomTom map instance.
  *
@@ -502,7 +502,7 @@ type MapLibreOptions = Omit<MapOptions, 'style' | 'attributionControl'>;
  *
  * @group Map
  */
-type TomTomMapParams = Partial<GlobalConfig> & {
+export type TomTomMapParams = Partial<GlobalConfig> & {
   /**
    * Map style to load.
    *
@@ -569,7 +569,7 @@ type TomTomMapParams = Partial<GlobalConfig> & {
  *
  * @ignore
  */
-type InternalTomTomMapParams = GlobalConfig & TomTomMapParams;
+export type InternalTomTomMapParams = GlobalConfig & TomTomMapParams;
 //#endregion
 //#region src/TomTomMap.d.ts
 /**
@@ -612,7 +612,7 @@ type InternalTomTomMapParams = GlobalConfig & TomTomMapParams;
  *
  * @group Map Style
  */
-type StyleChangeHandler = {
+export type StyleChangeHandler = {
   /**
    * Callback invoked immediately before a style change begins.
    *
@@ -699,7 +699,7 @@ type StyleChangeHandler = {
  *
  * @group Map
  */
-declare class TomTomMap {
+export declare class TomTomMap {
   /**
    * Indicates whether the map style has been fully loaded and is ready for interaction.
    *
@@ -1219,22 +1219,22 @@ declare class TomTomMap {
  * **RoutingModule** - Positions route visualizations below labels for readability:
  * ```typescript
  * // Routes appear below labels but above the base map
- * const routingModule = await RoutingModule.get(map);
+ * const routingModule = await RoutingModule.create(map);
  * // Uses mapStyleLayerIDs.lowestLabel by default
  * ```
  *
  * **GeometriesModule** - Configurable layer positioning for polygon areas:
  * ```typescript
  * // Default: below labels
- * const geometriesModule = await GeometriesModule.get(map);
+ * const geometriesModule = await GeometriesModule.create(map);
  *
  * // Custom: below buildings to show at ground level
- * const geometriesModule = await GeometriesModule.get(map, {
+ * const geometriesModule = await GeometriesModule.create(map, {
  *   beforeLayerConfig: 'lowestBuilding'
  * });
  *
  * // On top of everything
- * const geometriesModule = await GeometriesModule.get(map, {
+ * const geometriesModule = await GeometriesModule.create(map, {
  *   beforeLayerConfig: 'top'
  * });
  * ```
@@ -1266,7 +1266,7 @@ declare class TomTomMap {
  *
  * @group Map Style
  */
-declare const mapStyleLayerIDs: {
+export declare const mapStyleLayerIDs: {
   /**
    * Country name label layer.
    *
@@ -1509,14 +1509,14 @@ interface FeatureCollection<G extends Geometry | null = Geometry, P = GeoJsonPro
  * MapLibre `MapGeoJSONFeature`s, plain GeoJSON `Feature`s, and cached originals alike.
  */
 /** Minimal shape needed to look a feature up by id. @ignore */
-type RenderedRef = {
+export type RenderedRef = {
   id?: string | number;
   properties?: {
     id?: unknown;
   } | null;
 };
 /** A feature together with its index in the array it was found in. @ignore */
-type IndexedFeature<F> = {
+export type IndexedFeature<F> = {
   feature: F;
   index: number;
 };
@@ -1532,13 +1532,13 @@ type IndexedFeature<F> = {
  * features that only carry a top-level id). Returns `undefined` when neither is set.
  * @ignore
  */
-declare const renderedRefId: (rendered: RenderedRef) => string | number | undefined;
+export declare const renderedRefId: (rendered: RenderedRef) => string | number | undefined;
 /**
  * Find the first feature whose {@link renderedRefId} equals `id`, with its index, or
  * `undefined` (also for a nullish `id`).
  * @ignore
  */
-declare const findFeatureByRefId: <F extends RenderedRef>(features: readonly F[], id: string | number | undefined) => IndexedFeature<F> | undefined;
+export declare const findFeatureByRefId: <F extends RenderedRef>(features: readonly F[], id: string | number | undefined) => IndexedFeature<F> | undefined;
 //#endregion
 //#region src/shared/TomTomMapSource.d.ts
 /**
@@ -1546,7 +1546,7 @@ declare const findFeatureByRefId: <F extends RenderedRef>(features: readonly F[]
  * * The source might already be initialized from the map style, or it might be initialized here.
  * @ignore
  */
-declare class TomTomMapSource<SOURCE_SPEC extends SourceSpecification = SourceSpecification, RUNTIME_SOURCE extends Source = Source> {
+export declare class TomTomMapSource<SOURCE_SPEC extends SourceSpecification = SourceSpecification, RUNTIME_SOURCE extends Source = Source> {
   readonly id: string;
   readonly spec?: SOURCE_SPEC | undefined;
   runtimeSource?: RUNTIME_SOURCE | undefined;
@@ -1559,7 +1559,7 @@ declare class TomTomMapSource<SOURCE_SPEC extends SourceSpecification = SourceSp
  * Contains a source and the layers to render its data.
  * @ignore
  */
-declare abstract class AbstractSourceWithLayers<SOURCE_SPEC extends SourceSpecification = SourceSpecification, RUNTIME_SOURCE extends Source = Source, LAYER_SPEC extends LayerSpecification = LayerSpecification> {
+export declare abstract class AbstractSourceWithLayers<SOURCE_SPEC extends SourceSpecification = SourceSpecification, RUNTIME_SOURCE extends Source = Source, LAYER_SPEC extends LayerSpecification = LayerSpecification> {
   readonly map: Map;
   readonly source: TomTomMapSource<SOURCE_SPEC, RUNTIME_SOURCE>;
   readonly _layerSpecs: LAYER_SPEC[];
@@ -1578,27 +1578,26 @@ declare abstract class AbstractSourceWithLayers<SOURCE_SPEC extends SourceSpecif
   private isLayerVisible;
   setLayersVisible(visible: boolean, filter?: LayerSpecFilter): void;
   get sourceAndLayerIDs(): SourceWithLayerIDs;
-  equalSourceAndLayerIDs(other: SourceWithLayers): boolean;
 }
 /**
  * @ignore
  * @param loadedMap
  * @param sourceIDs
  */
-declare const filterLayersBySources: (loadedMap: Map, sourceIDs: string[]) => LayerSpecWithSource[];
+export declare const filterLayersBySources: (loadedMap: Map, sourceIDs: string[]) => LayerSpecWithSource[];
 /**
  * Source with layers which are coming from the downloaded TT map style.
  * * Examples are parts of the base map, traffic, pois, and hillshade.
  * @ignore
  */
-declare class StyleSourceWithLayers<SOURCE_SPEC extends SourceSpecification = SourceSpecification, RUNTIME_SOURCE extends Source = Source> extends AbstractSourceWithLayers<SourceSpecification, RUNTIME_SOURCE> {
+export declare class StyleSourceWithLayers<SOURCE_SPEC extends SourceSpecification = SourceSpecification, RUNTIME_SOURCE extends Source = Source> extends AbstractSourceWithLayers<SourceSpecification, RUNTIME_SOURCE> {
   constructor(map: Map, runtimeSource: RUNTIME_SOURCE, filter?: LayerSpecFilter);
 }
 /**
  * Source with layers which originally is not in the map style, but it's to be added after the map is initialized.
  * @ignore
  */
-declare class AddedSourceWithLayers<SOURCE_SPEC extends SourceSpecification = SourceSpecification, RUNTIME_SOURCE extends Source = Source> extends AbstractSourceWithLayers<SOURCE_SPEC, RUNTIME_SOURCE, ToBeAddedLayerSpec> {
+export declare class AddedSourceWithLayers<SOURCE_SPEC extends SourceSpecification = SourceSpecification, RUNTIME_SOURCE extends Source = Source> extends AbstractSourceWithLayers<SOURCE_SPEC, RUNTIME_SOURCE, ToBeAddedLayerSpec> {
   constructor(map: Map, sourceId: string, sourceSpec: SOURCE_SPEC, layerSpecs: ToBeAddedLayerSpecWithoutSource[]);
   private ensureLayersAddedToMap;
   ensureAddedToMapWithVisibility(visible: boolean, addLayersToMap: boolean): void;
@@ -1607,7 +1606,7 @@ declare class AddedSourceWithLayers<SOURCE_SPEC extends SourceSpecification = So
  * Options for the {@link GeoJSONSourceWithLayers.show} method.
  * @ignore
  */
-type ShowOptions = {
+export type ShowOptions = {
   /**
    * When `true` (default), layer visibility is automatically set based on whether
    * the feature collection is non-empty. Pass `false` from state-update calls
@@ -1623,11 +1622,11 @@ type ShowOptions = {
  * can be configured with at construction time. Forwarded verbatim to MapLibre.
  * @ignore
  */
-type GeoJSONSourceClusterOptions = Pick<GeoJSONSourceSpecification, 'cluster' | 'clusterRadius' | 'clusterMaxZoom' | 'clusterMinPoints' | 'clusterProperties'>;
+export type GeoJSONSourceClusterOptions = Pick<GeoJSONSourceSpecification, 'cluster' | 'clusterRadius' | 'clusterMaxZoom' | 'clusterMinPoints' | 'clusterProperties'>;
 /**
  * @ignore
  */
-declare class GeoJSONSourceWithLayers<T extends FeatureCollection = FeatureCollection> extends AddedSourceWithLayers<GeoJSONSourceSpecification, GeoJSONSource> {
+export declare class GeoJSONSourceWithLayers<T extends FeatureCollection = FeatureCollection> extends AddedSourceWithLayers<GeoJSONSourceSpecification, GeoJSONSource> {
   shownFeatures: T;
   constructor(map: Map, sourceId: string, layerSpecs: ToBeAddedLayerSpecWithoutSource[], addLayersToMap?: boolean, clusterOptions?: GeoJSONSourceClusterOptions);
   show(featureCollection: T, { automaticVisibility }?: ShowOptions): void;
@@ -2526,15 +2525,286 @@ type MapModuleCommonConfig = {
  */
 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
+ * module defines one — its own scope object. {@link UserEvents.where} turns either into a
+ * {@link ResolvedEventScope}.
+ *
+ * @typeParam T - Feature type this surface exposes, which a predicate therefore receives.
+ * @typeParam WHERE_SCOPE - The module's own scope object, such as {@link BaseMapEventScope}.
+ *   `never` on a module that only supports predicates, leaving just the predicate arm.
+ *
+ * @ignore
+ */
+export type EventScope<T, WHERE_SCOPE> = ((feature: T) => boolean) | WHERE_SCOPE;
+/**
+ * A scope narrowed down to the two things the event proxy can act on.
+ *
+ * Every public way of expressing a scope — a feature predicate, `{ layerGroups }` on
+ * {@link BaseMapModule}, a module's named scope — resolves to one of these before it reaches
+ * {@link AbstractEventProxy}. Both parts are optional: an unscoped handler carries neither.
+ *
+ * @ignore
+ */
+export type ResolvedEventScope = {
+  /**
+   * Selects which of the source's layers the handler listens to. Applied fresh whenever the
+   * layer set changes, so a scope keeps meaning the same thing across style changes.
+   */
+  layerFilter?: LayerSpecFilter;
+  /**
+   * Decides whether a rendered feature belongs to this scope. 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.
+   */
+  featureMatches?: (feature: MapGeoJSONFeature) => boolean;
+};
+/**
+ * Combines an existing scope with a narrower one, so `where(a).where(b)` means "a and b".
+ * Both axes intersect independently.
+ *
+ * Chaining is not a feature to reach for — two predicates read better as one `a(f) && b(f)`, and
+ * layer plus feature narrowing is a single {@link BaseMapEventScope}. It exists because `where()`
+ * returns a `UserEvents`, which has a `where()` of its own: without intersecting here, a second
+ * call would silently replace the first and *widen* the scope.
+ * @ignore
+ */
+export declare const combineEventScopes: (outer: ResolvedEventScope | undefined, inner: ResolvedEventScope | undefined) => ResolvedEventScope | undefined;
+/**
+ * The layer specs a scope selects out of a source, resolved against the source's *current*
+ * layers. Called again on every style change so a scope never holds stale layer IDs.
+ * @ignore
+ */
+export declare const scopedLayerSpecs: (sourceWithLayers: SourceWithLayers, scope: ResolvedEventScope | undefined) => LayerSpecification[];
+/**
+ * Names a module cannot use for a named event scope, because a scope is attached as a property
+ * onto the module-wide events object and would shadow one of its methods.
+ * @ignore
+ */
+export declare const reservedScopeNames: readonly string[];
+/**
+ * Guards {@link reservedScopeNames}. SDK-authored scope names are covered by a unit test, but
+ * {@link CustomGeoJSONModule} takes its scope names from the caller's own `sources`, so this
+ * has to hold at runtime too.
+ * @ignore
+ */
+export declare const assertNoReservedScopeNames: (names: string[], context: string) => void;
+//#endregion
+//#region src/shared/ModuleEvents.d.ts
+/**
+ * Lifecycle event module for map modules.
+ *
+ * Provides a unified API for subscribing to module-level events that are not tied
+ * to user interaction with map features. Two event types are supported:
+ *
+ * - `config-change`: emitted whenever the module's configuration is updated
+ *   (via `applyConfig`, `resetConfig`, or any module-specific setter that mutates config).
+ * - `shown-features`: emitted by modules that have a `show` method, immediately after
+ *   features are displayed on the map.
+ *
+ * Each `on()` call returns an unsubscribe function so individual handlers can be
+ * removed 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.
+ *
+ * @example
+ * ```typescript
+ * const unsubscribeConfig = trafficFlow.events.on('config-change', (config) => {
+ *   console.log('New config:', config);
+ * });
+ *
+ * const unsubscribeShown = places.events.on('shown-features', (features) => {
+ *   console.log('Shown:', features);
+ * });
+ *
+ * // Later:
+ * unsubscribeConfig();
+ * unsubscribeShown();
+ * ```
+ *
+ * @group Events
+ */
+/**
+ * `'shown-features'`, except on a module with no `show` — where `TShownFeatures` is `never` and
+ * this collapses to `never`, making the overload uncallable. Without it a handler could be
+ * registered for an event the module can never emit.
+ *
+ * @group Events
+ */
+export type ShownFeaturesType<TShownFeatures> = [TShownFeatures] extends [never] ? never : 'shown-features';
+export declare class ModuleEvents<TConfig, TShownFeatures = never> {
+  private readonly configChangeHandlers;
+  private readonly shownFeaturesHandlers;
+  constructor(configChangeHandlers: ((config: TConfig | undefined) => void)[], shownFeaturesHandlers: ((features: TShownFeatures) => void)[]);
+  /**
+   * Subscribe to config-change events.
+   *
+   * The handler is called with the module's full current configuration immediately after
+   * any mutation — whether through `applyConfig`, a module-specific setter, or `resetConfig`.
+   *
+   * @param type - `'config-change'`
+   * @param handler - Receives the module's config (or `undefined` when config is cleared).
+   * @returns An unsubscribe function. Call it to remove **only this handler** without
+   *   affecting other registered handlers for the same event type.
+   *
+   * @example
+   * ```typescript
+   * const unsub = trafficFlow.events.on('config-change', (config) => {
+   *   toggle.checked = config?.visible ?? false;
+   * });
+   *
+   * // Later:
+   * unsub();
+   * ```
+   */
+  on(type: 'config-change', handler: (config: TConfig | undefined) => void): () => void;
+  /**
+   * Subscribe to shown-features events.
+   *
+   * The handler is called immediately after a module's `show()` method (or equivalent)
+   * has updated the map with new data. Only available on modules that have a `show` method.
+   *
+   * @param type - `'shown-features'`
+   * @param handler - Receives the data that was passed to `show()`.
+   * @returns An unsubscribe function. Call it to remove **only this handler** without
+   *   affecting other registered handlers for the same event type.
+   *
+   * @example
+   * ```typescript
+   * const unsub = places.events.on('shown-features', (features) => {
+   *   fitMapToResults(features);
+   * });
+   *
+   * // Later:
+   * unsub();
+   * ```
+   */
+  on(type: ShownFeaturesType<TShownFeatures>, handler: (features: TShownFeatures) => void): () => void;
+  /**
+   * Remove **all** handlers for the given event type at once.
+   *
+   * Prefer the unsubscribe function returned by {@link on} when you need to remove a
+   * single handler. Use `off` for bulk teardown — e.g. when unmounting a component that
+   * registered multiple handlers.
+   *
+   * @param type - The event type whose handlers should all be cleared.
+   *
+   * @example
+   * ```typescript
+   * // Clear all config-change listeners in one call
+   * trafficFlow.events.off('config-change');
+   * ```
+   */
+  off(type: 'config-change' | 'shown-features'): void;
+}
+//#endregion
 //#region src/shared/AbstractEventProxy.d.ts
-type SourceEventTypeHandler = {
+/**
+ * Any map module, whatever its sources and config. The event proxy only ever compares owners by
+ * identity, so it needs no more than "some module" — but naming the class says who may own a
+ * handler, which a bare `object` did not. The two type parameters are irrelevant to identity, and
+ * pinning them would drag every module's concrete types through this file.
+ *
+ * @ignore
+ */
+type AnyMapModule = AbstractMapModule<any, any>;
+/**
+ * One entry in the handler index: the caller's function plus everything dispatch needs to decide
+ * whether it should fire. A caller supplies a {@link HandlerRegistration}; the proxy files this.
+ *
+ * Repeated `on()` calls append rather than replace, so several entries can listen to one layer and
+ * all of them fire.
+ *
+ * @ignore
+ */
+type HandlerEntry = {
+  /**
+   * The source the handler was registered against — **all** of its layers, not just the ones
+   * this entry listens to; `layerIDs` is that narrowing.
+   *
+   * Kept because the handler receives it as its last argument, because a GeoJSON source can
+   * substitute the caller's typed original back in for the rendered feature, and because
+   * dropping by source needs its ID. Replaced wholesale on a style change.
+   */
   sourceWithLayers: SourceWithLayers;
-  layerIDs: string[];
+  /**
+   * The layers this entry actually listens to: `sourceWithLayers`' layers narrowed by `scope`,
+   * so a scoped handler holds a subset and an unscoped one holds the lot.
+   *
+   * It is also *where the entry is filed* — it appears in `handlers[type][layerID]` under each
+   * of these — which is why a style change re-files the entry rather than just overwriting the
+   * set. A Set rather than a list because a layer-scoped handler tests membership per dispatch
+   * to narrow the features its caller sees, and the base map contributes ~90 layers to test
+   * against.
+   */
+  layerIDs: Set<string>;
+  /**
+   * The handler to call, already wrapped by {@link UserEvents} with the module's feature mapping
+   * and any `where()` predicate — so by the time dispatch reaches it, it takes the module's own
+   * feature type and has already declined features outside its scope.
+   */
   fn: UserEventHandler<any>;
+  /** Event configuration this entry registered with — its hover cursor, chiefly. */
   config?: EventHandlerConfig;
+  /**
+   * The module that registered this handler. Two modules can share one MapLibre source ID —
+   * POIs and the base map both use `vectorTiles` — so a style-change refresh has to tell their
+   * handlers apart by owner rather than by source ID alone.
+   */
+  owner: AnyMapModule;
+  /**
+   * How the registration was narrowed, if at all. Kept alongside `layerIDs` rather than being
+   * spent when it is resolved: `layerFilter` has to run again over the new layer set after a
+   * style change, and `featureMatches` decides per dispatch whether this entry claims the
+   * hover cursor for the feature under the pointer.
+   */
+  scope?: ResolvedEventScope;
 };
-type SourceEventHandlers = Partial<Record<EventType, SourceEventTypeHandler[]>>;
-type EventHandlers = Record<string, SourceEventHandlers>;
+/**
+ * How a handler was registered: the parts of a {@link HandlerEntry} a caller supplies, as opposed
+ * to the layers and source the proxy resolves for it. Grouped rather than passed as three trailing
+ * arguments, so a call site names what it means instead of positioning an `undefined` config
+ * before an owner.
+ *
+ * @ignore
+ */
+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 — `findHandlers()[0]` is the first one registered, which is what claims the hover cursor.
+ *
+ * @ignore
+ */
+type HandlersByLayer = Record<string, HandlerEntry[]>;
+/**
+ * Every registered handler, indexed by event type and then by the layer it listens to. A handler
+ * scoped to several layers appears under each of them, so dispatch is a lookup rather than a scan:
+ * a hit on `layerId` fires exactly `handlers[type][layerId]`.
+ *
+ * Keyed this way, the interactive-layer list is local information — a layer is interactive while
+ * some type still holds a non-empty bucket for it, so releasing one costs five lookups instead of
+ * a walk over every registered handler.
+ *
+ * @example
+ * ```typescript
+ * const handlers = {
+ *     click: {
+ *         'Buildings': [{ sourceWithLayers, layerIDs: Set { 'Buildings', 'Roads' }, fn, … }],
+ *         'Roads':     [ …the same handler again, plus any other listening to Roads ],
+ *     },
+ *     hover: { 'Water': [ … ] },
+ *     contextmenu: {},
+ *     'hover-move': {},
+ *     'long-hover': {},
+ * };
+ * ```
+ *
+ * @ignore
+ */
+type EventHandlers = Record<EventType, HandlersByLayer>;
 /**
  * @ignore
  */
@@ -2543,61 +2813,90 @@ declare abstract class AbstractEventProxy {
   protected handlers: EventHandlers;
   /**
    * Adds the given layers as interactive, so we'll listen to them for hover and click.
-   * @param sourceWithLayers The sources and layers to listen to.
+   *
+   * Only the layers a handler's scope actually selects are added. Marking the whole source
+   * interactive would let an out-of-scope feature rendered on top shadow an in-scope one, since
+   * dispatch matches on the topmost hit.
+   * @param layerIDs The scoped layers to listen to.
    */
   private ensureInteractiveLayerIDsAdded;
+  private releaseUnusedInteractiveLayerIDs;
+  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.
+   *
+   * 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.
+   */
+  private dropHandlers;
   /**
    * Register an event listener to the list.
    * @param sourceWithLayers The sources and layers to added.
    * @param handlerFn Function that will handle the event.
    * @param type Type of event to listen to.
-   * @param config Optional configuration for the event handler.
+   * @param registration How the handler was registered — see {@link HandlerRegistration}.
    */
-  addEventHandler<T = MapGeoJSONFeature>(sourceWithLayers: SourceWithLayers, handlerFn: UserEventHandler<T>, type: EventType, config: EventHandlerConfig | undefined): void;
+  addEventHandler<T = MapGeoJSONFeature>(sourceWithLayers: SourceWithLayers, handlerFn: UserEventHandler<T>, type: EventType, registration: HandlerRegistration): void;
   /**
    * Removes a single handler function for the given source and event type.
    * Other handlers registered for the same source and type are not affected.
-   * Unlike {@link remove}, this does not remove the source from the interactive layer list —
-   * other handlers may still depend on it.
    * @param sourceWithLayers The source whose handler should be removed.
    * @param type The event type.
    * @param handlerFn The exact function reference to remove.
    */
   removeHandler(sourceWithLayers: SourceWithLayers, type: EventType, handlerFn: UserEventHandler<any>): void;
   /**
-   * Removes the given sources and layers from the interactive list. When not present, nothing happens.
+   * 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,
+   * not a separate surface to tear down.
+   *
+   * 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 type The event type to be removed.
-   * @param sourceWithLayers The sources and layers to remove, matched by source and layer IDs.
+   * @param owner The module that registered them.
    */
-  remove(sourceWithLayers: SourceWithLayers, type: EventType): void;
+  remove(sourceWithLayers: SourceWithLayers, type: EventType, owner: AnyMapModule): void;
   /**
    * Removes all interactive sources and layers.
    */
   removeAll(): void;
   /**
-   * Returns whether this source is registered for events (has handlers attached).
-   * @param sourceId The source id (should be linked to a SourceWithLayers instance).
+   * Whether any handler, of any event type, listens to this layer.
+   * @param layerId The layer id a rendered feature was drawn from.
    */
-  hasSourceID(sourceId: string): boolean;
+  hasHandlerForLayer(layerId: string): boolean;
   /**
-   * Look up the {@link SourceWithLayers} registered for the given source ID, if any.
-   *
-   * The SDK assumes at most one `SourceWithLayers` per MapLibre source ID — each
-   * module creates its own source — so any non-empty handler bucket gives us the
-   * right reference. We iterate event-type buckets defensively to skip transient
-   * empty arrays left mid-`removeHandler` before the bucket itself is deleted.
+   * Look up the {@link SourceWithLayers} a layer's handlers were registered against, if any.
    *
-   * NOTE: if two modules ever register against the same source ID with overlapping
-   * layers, this returns the first one we encounter.
+   * The SDK assumes at most one `SourceWithLayers` per MapLibre source ID — each module creates
+   * its own source — and a layer belongs to exactly one source, so any handler listening to the
+   * layer carries the right reference.
    */
-  protected sourceWithLayersFor(sourceId: string | undefined): SourceWithLayers | undefined;
+  protected sourceWithLayersFor(layerId: string | undefined): SourceWithLayers | undefined;
   /**
    * Updates the given sourcesWithLayers, if they have any handlers.
    * * (This is typically called to refresh any registered, stale sourceWithLayers references after a map style has changed).
    * @param sourcesWithLayers The new sources with layers to replace existing ones.
+   * @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.
+   */
+  updateIfRegistered(sourcesWithLayers: SourcesWithLayers, owner: AnyMapModule): void;
+  /**
+   * 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.
    */
-  updateIfRegistered(sourcesWithLayers: SourcesWithLayers): void;
-  protected findHandlers: (types: EventType[], sourceId: string | undefined, layerId: string | undefined) => SourceEventTypeHandler[];
+  protected findHandlers: (types: EventType[], layerId: string | undefined, feature?: MapGeoJSONFeature) => HandlerEntry[];
 }
 //#endregion
 //#region src/shared/EventsProxy.d.ts
@@ -2606,7 +2905,7 @@ declare abstract class AbstractEventProxy {
  * To have full control on hovers and clicks when multiple overlapping layers are present, that logic must be centralized here.
  * @ignore
  */
-declare class EventsProxy extends AbstractEventProxy {
+export declare class EventsProxy extends AbstractEventProxy {
   private readonly map;
   private readonly mapCanvas;
   private enabled;
@@ -2620,6 +2919,8 @@ declare class EventsProxy extends AbstractEventProxy {
   private lastClickedFeature?;
   private lastClickedSourceWithLayers?;
   private lastCursorStyle;
+  private pendingMouseMove?;
+  private mouseMoveFrameRequested;
   private readonly config;
   constructor(map: Map, config?: MapEventsConfig);
   private listenToEvents;
@@ -2638,6 +2939,7 @@ declare class EventsProxy extends AbstractEventProxy {
    * extends Feature`).
    */
   private toCallerFeatures;
+  private callerFeaturesFor;
   private getRenderedFeatures;
   private clearLongHoverTimeout;
   private restartLongHoverTimeout;
@@ -2646,372 +2948,68 @@ declare class EventsProxy extends AbstractEventProxy {
   private onMouseOut;
   private onMouseDown;
   private onMouseUp;
+  /**
+   * Mouse movement arrives far more often than the browser paints, and each pass runs a
+   * `queryRenderedFeatures` — by a wide margin the most expensive thing this proxy does. Only
+   * the newest position matters by the time anything is drawn, so moves are coalesced into one
+   * pass per animation frame and the intermediate ones are dropped.
+   *
+   * Hover semantics are unaffected: `detectHoverState` compares against the previously handled
+   * position, so a coalesced move is indistinguishable from the pointer having travelled
+   * straight there.
+   */
   private onMouseMove;
+  private handleMouseMove;
+  /**
+   * Handles the pointer arriving on a different feature: cursor, `eventState` marker, and the
+   * `hover` handlers themselves.
+   * @returns the caller-facing features, if they had to be built, so `hover-move` can reuse them.
+   */
+  private dispatchHoverEnter;
+  private dispatchHoverMove;
+  private dispatchToHandlers;
   private updateHoverCursor;
   private onMapClick;
 }
 //#endregion
-//#region src/shared/AbstractMapModule.d.ts
-/**
- * Whether a map module is based on a map style or on added GeoJSON data.
- */
-type MapModuleSource = 'style' | 'geojson';
+//#region src/shared/UserEvents.d.ts
 /**
- * Base class for all Maps SDK map modules.
- *
- * This abstract class provides the foundation for creating map modules that can display
- * and manage various types of data on a TomTom map. It handles module lifecycle management,
- * including initialization, configuration updates, and automatic restoration after map style changes.
- *
- * @remarks
- * All map modules extend this class to ensure consistent behavior across the SDK.
- * The class manages the module's sources, layers, and configuration, automatically
- * handling map style changes by restoring the module's state when needed.
- *
- * @typeParam SOURCES_WITH_LAYERS - The type defining the sources and layers used by this module
- * @typeParam CFG - The configuration type for this module, or undefined if no configuration is needed. When defined, must extend MapModuleCommonConfig.
- *
- * @example
- * ```typescript
- * class CustomModule extends AbstractMapModule<MySourcesWithLayers, MyConfig> {
- *   constructor(tomtomMap: TomTomMap, config?: MyConfig) {
- *     super('geojson', tomtomMap, config);
- *   }
- *   // Implement abstract methods...
- * }
- * ```
- *
- * @group Shared
+ * Everything {@link UserEvents} needs to register handlers for one scope of one module.
+ * @ignore
  */
-declare abstract class AbstractMapModule<SOURCES_WITH_LAYERS extends SourcesWithLayers, CFG extends MapModuleCommonConfig | undefined = undefined> {
-  private readonly sourceType;
-  /**
-   * @ignore
-   */
-  protected readonly tomtomMap: TomTomMap;
-  /**
-   * @ignore
-   */
-  protected readonly eventsProxy: EventsProxy;
-  /**
-   * @ignore
-   */
-  protected readonly mapLibreMap: Map;
-  /**
-   * @ignore
-   */
-  protected sourcesWithLayers: SOURCES_WITH_LAYERS;
+export type UserEventsOptions<T, WHERE_SCOPE> = {
+  eventProxy: EventsProxy;
   /**
-   * @ignore
+   * 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}.
    */
-  protected _sourceAndLayerIDs: Record<keyof SOURCES_WITH_LAYERS, SourceWithLayerIDs>;
+  sourcesWithLayers: SourceWithLayers[];
   /**
-   * @ignore
+   * The module 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.
    */
-  protected config?: CFG;
+  owner: AnyMapModule;
   /**
-   * @ignore
+   * Event configuration for every handler registered through this instance — the hover cursor,
+   * chiefly. A scope built by {@link UserEvents.where} inherits the module's unless `where` is
+   * given one of its own, which is how two parts of one module get different cursors.
    */
-  protected _initializing: boolean;
+  config?: EventHandlerConfig;
   /**
-   * Handlers registered via events.on('config-change', …).
-   * Stored here so the array reference stays stable across multiple events getter calls.
-   * @ignore
+   * Transforms a raw {@link MapGeoJSONFeature} 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`.
    */
-  protected readonly configChangeHandlers: ((config: CFG | undefined) => void)[];
+  mapping?: (feature: MapGeoJSONFeature) => T;
+  /** The scope already applied to this instance, if it came from {@link UserEvents.where}. */
+  scope?: ResolvedEventScope;
   /**
-   * Monotonically increasing index unique to this instance within its concrete module
-   * class. Auto-assigned in the constructor based on `new.target`, so each subclass
-   * has its own counter without per-subclass boilerplate. Use as a suffix on
-   * auto-generated source and layer IDs to keep them stable across style changes and
-   * unique across module instances.
-   * @ignore
+   * Turns a module-specific scope object into a {@link ResolvedEventScope}. Only modules with a
+   * typed layer vocabulary supply one — today that is {@link BaseMapModule} and its layer groups.
    */
-  protected readonly instanceIndex: number;
-  /**
-   * Per-concrete-class instance counter. WeakMap-keyed so unloaded classes can be GC'd.
-   * @ignore
-   */
-  private static readonly instanceCounters;
-  /**
-   * Indicates that this module is currently adding its sources and layers to the map, so during this time it might not function properly.
-   * @see waitUntilModuleReady
-   * @private
-   */
-  private moduleReady;
-  /**
-   * Builds this module based on a given Maps SDK map.
-   * @param tomtomMap The map. It may or may not be initialized at this stage,
-   * but the module ensures to initialize itself once it is.
-   * @param sourceType Whether the module is based on a map style or on added GeoJSON data.
-   * @param config Optional configuration to initialize directly as soon as the map is ready.
-   */
-  protected constructor(sourceType: MapModuleSource, tomtomMap: TomTomMap, config?: CFG);
-  /**
-   * Initializes the sources with layers of this module.
-   * @param config The optional configuration for the module.
-   * @param restore Whether we are restoring an existing module after the map style got reloaded.
-   * @protected
-   * @ignore
-   */
-  protected initSourcesWithLayers(config?: CFG, restore?: boolean): void;
-  /**
-   * Initializes the sources with layers for the specific module.
-   * @protected
-   * @ignore
-   */
-  protected abstract _initSourcesWithLayers(config?: CFG, restore?: boolean): SOURCES_WITH_LAYERS;
-  protected waitUntilModuleReady(): Promise<void>;
-  /**
-   * Applies a configuration to this module.
-   *
-   * This method updates the module's behavior and appearance based on the provided configuration.
-   * The configuration is stored internally and will be automatically reapplied if the map style changes.
-   *
-   * @param config - The configuration object to apply to the module. Pass `undefined` to reset
-   * the configuration to default values.
-   *
-   * @remarks
-   * When a configuration is applied, the module updates its visual representation and behavior
-   * accordingly. The configuration persists across map style changes, ensuring consistent
-   * module behavior even when the map's base style is modified.
-   *
-   * @example
-   * ```typescript
-   * // Apply a new configuration
-   * myModule.applyConfig({ visible: true, opacity: 0.8 });
-   *
-   * // Reset to default configuration
-   * myModule.applyConfig(undefined);
-   * ```
-   *
-   * @see {@link resetConfig} for a convenience method to reset configuration
-   * @see {@link getConfig} to retrieve the current configuration
-   */
-  applyConfig(config: CFG | undefined): void;
-  /**
-   * Emits a `config-change` event to all registered handlers.
-   * Skipped during module initialisation to avoid spurious events.
-   * @ignore
-   */
-  protected emitConfigChange(): void;
-  /**
-   * Internal implementation to apply config for the specific module.
-   * @param config The config to apply. this.config contains the previous configuration (if any).
-   * Once the method returns config, it will be assigned to this.config.
-   * @protected
-   * @ignore
-   */
-  protected abstract _applyConfig(config: CFG | undefined): CFG | undefined;
-  /**
-   * Resets the configuration of this module to its default values.
-   *
-   * This is a convenience method that clears any previously applied configuration
-   * and restores the module to its initial state. This is equivalent to calling
-   * `applyConfig(undefined)`.
-   *
-   * @remarks
-   * After calling this method, the module will behave as if no configuration was ever applied.
-   * Any custom settings, styling, or behavior modifications will be removed and replaced
-   * with default values.
-   *
-   * @example
-   * ```typescript
-   * // Apply some configuration
-   * myModule.applyConfig({ visible: true, opacity: 0.5 });
-   *
-   * // Later, reset to defaults
-   * myModule.resetConfig();
-   * ```
-   *
-   * @see {@link applyConfig} to apply a new configuration
-   * @see {@link getConfig} to retrieve the current configuration before resetting
-   */
-  resetConfig(): void;
-  private restoreDataAndConfig;
-  /**
-   * implementation needed to restore the module state (data and config applied to the module).
-   * to be used to restore module state after map style change
-   * @protected
-   * @ignore
-   */
-  protected restoreDataAndConfigImpl(): void;
-  /**
-   * Retrieves a copy of the current module configuration.
-   *
-   * This method returns a shallow copy of the configuration object that is currently
-   * applied to the module. If no configuration has been applied, it returns `undefined`.
-   *
-   * @returns A shallow copy of the current configuration object, or `undefined` if no
-   * configuration is currently applied. The returned object is a copy to prevent
-   * unintended modifications to the internal state.
-   *
-   * @remarks
-   * The returned configuration object is a shallow copy, which means that while the
-   * top-level properties are copied, any nested objects or arrays are still referenced
-   * from the original configuration. This is sufficient for most use cases but should
-   * be kept in mind when dealing with complex configurations.
-   *
-   * @example
-   * ```typescript
-   * // Apply a configuration
-   * myModule.applyConfig({ visible: true, opacity: 0.8 });
-   *
-   * // Later, retrieve the current configuration
-   * const currentConfig = myModule.getConfig();
-   * console.log(currentConfig); // { visible: true, opacity: 0.8 }
-   *
-   * // When no config is applied
-   * myModule.resetConfig();
-   * console.log(myModule.getConfig()); // undefined
-   * ```
-   *
-   * @see {@link applyConfig} to modify the configuration
-   * @see {@link resetConfig} to clear the configuration
-   */
-  getConfig(): NonNullable<CFG> | undefined;
-  /**
-   * Gets the source and layer identifiers for all sources managed by this module.
-   *
-   * This property provides access to the MapLibre source and layer IDs that were created
-   * and are managed by this module. These IDs can be used to interact directly with
-   * MapLibre's API or to identify which layers belong to this module.
-   *
-   * @returns A record mapping each source name to its corresponding source ID and layer IDs.
-   * Each entry contains the MapLibre source identifier and an array of layer identifiers
-   * associated with that source.
-   *
-   * @remarks
-   * The returned IDs are useful when you need to:
-   * - Directly manipulate layers using MapLibre's native API
-   * - Identify which layers on the map belong to this module
-   * - Set layer ordering or positioning relative to other layers
-   * - Access source or layer properties through MapLibre methods
-   *
-   * @example
-   * ```typescript
-   * const ids = myModule.sourceAndLayerIDs;
-   * console.log(ids);
-   * // {
-   * //   mySource: {
-   * //     sourceID: 'my-source-id',
-   * //     layerIDs: ['layer-1', 'layer-2']
-   * //   }
-   * // }
-   *
-   * // Use with MapLibre API
-   * const map = myModule.mapLibreMap;
-   * ids.mySource.layerIDs.forEach(layerId => {
-   *   map.setLayoutProperty(layerId, 'visibility', 'visible');
-   * });
-   * ```
-   */
-  get sourceAndLayerIDs(): Record<keyof SOURCES_WITH_LAYERS, SourceWithLayerIDs>;
-}
-//#endregion
-//#region src/shared/ModuleEvents.d.ts
-/**
- * Lifecycle event module for map modules.
- *
- * Provides a unified API for subscribing to module-level events that are not tied
- * to user interaction with map features. Two event types are supported:
- *
- * - `config-change`: emitted whenever the module's configuration is updated
- *   (via `applyConfig`, `resetConfig`, or any module-specific setter that mutates config).
- * - `shown-features`: emitted by modules that have a `show` method, immediately after
- *   features are displayed on the map.
- *
- * Each `on()` call returns an unsubscribe function so individual handlers can be
- * removed 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.
- *
- * @example
- * ```typescript
- * const unsubscribeConfig = trafficFlow.events.on('config-change', (config) => {
- *   console.log('New config:', config);
- * });
- *
- * const unsubscribeShown = places.events.on('shown-features', (features) => {
- *   console.log('Shown:', features);
- * });
- *
- * // Later:
- * unsubscribeConfig();
- * unsubscribeShown();
- * ```
- *
- * @group Events
- */
-declare class ModuleEvents<TConfig, TShownFeatures = never> {
-  private readonly configChangeHandlers;
-  private readonly shownFeaturesHandlers;
-  constructor(configChangeHandlers: ((config: TConfig | undefined) => void)[], shownFeaturesHandlers: ((features: TShownFeatures) => void)[]);
-  /**
-   * Subscribe to config-change events.
-   *
-   * The handler is called with the module's full current configuration immediately after
-   * any mutation — whether through `applyConfig`, a module-specific setter, or `resetConfig`.
-   *
-   * @param type - `'config-change'`
-   * @param handler - Receives the module's config (or `undefined` when config is cleared).
-   * @returns An unsubscribe function. Call it to remove **only this handler** without
-   *   affecting other registered handlers for the same event type.
-   *
-   * @example
-   * ```typescript
-   * const unsub = trafficFlow.events.on('config-change', (config) => {
-   *   toggle.checked = config?.visible ?? false;
-   * });
-   *
-   * // Later:
-   * unsub();
-   * ```
-   */
-  on(type: 'config-change', handler: (config: TConfig | undefined) => void): () => void;
-  /**
-   * Subscribe to shown-features events.
-   *
-   * The handler is called immediately after a module's `show()` method (or equivalent)
-   * has updated the map with new data. Only available on modules that have a `show` method.
-   *
-   * @param type - `'shown-features'`
-   * @param handler - Receives the data that was passed to `show()`.
-   * @returns An unsubscribe function. Call it to remove **only this handler** without
-   *   affecting other registered handlers for the same event type.
-   *
-   * @example
-   * ```typescript
-   * const unsub = places.events.on('shown-features', (features) => {
-   *   fitMapToResults(features);
-   * });
-   *
-   * // Later:
-   * unsub();
-   * ```
-   */
-  on(type: 'shown-features', handler: (features: TShownFeatures) => void): () => void;
-  /**
-   * Remove **all** handlers for the given event type at once.
-   *
-   * Prefer the unsubscribe function returned by {@link on} when you need to remove a
-   * single handler. Use `off` for bulk teardown — e.g. when unmounting a component that
-   * registered multiple handlers.
-   *
-   * @param type - The event type whose handlers should all be cleared.
-   *
-   * @example
-   * ```typescript
-   * // Clear all config-change listeners in one call
-   * trafficFlow.events.off('config-change');
-   * ```
-   */
-  off(type: 'config-change' | 'shown-features'): void;
-}
-//#endregion
-//#region src/shared/UserEvents.d.ts
+  scopeResolver?: (scope: WHERE_SCOPE) => ResolvedEventScope;
+};
 /**
  * Event handling interface for map features.
  *
@@ -3105,38 +3103,52 @@ declare class ModuleEvents<TConfig, TShownFeatures = never> {
  *
  * @group Events
  */
-declare class UserEvents<T = MapGeoJSONFeature> {
-  private readonly eventProxy;
-  private readonly config;
-  /**
-   * Optional function that transforms a raw {@link MapGeoJSONFeature} into the
-   * feature type `T` exposed by the module. When provided, every feature passed (fired)
-   * to event handlers is first run through this function, so callers receive the
-   * module's own feature shape instead of the underlying MapLibre feature.
-   *
-   * When omitted, `T` defaults to `MapGeoJSONFeature` and features are forwarded
-   * as-is.
-   */
-  private readonly mapping?;
+export declare class UserEvents<T = MapGeoJSONFeature, WHERE_SCOPE = never> {
   private readonly sources;
-  constructor(eventProxy: EventsProxy,
+  private readonly options;
+  constructor(options: UserEventsOptions<T, WHERE_SCOPE>);
   /**
-   * The source(s) whose features this module handles events for.
-   * Pass an array to register handlers across multiple sources representing similar data in different display modes (e.g. hexgrid + square
-   * in {@link TrafficAreaAnalyticsModule}). A single value is also accepted for
-   * backwards compatibility.
-   */
-  sourcesWithLayers: SourceWithLayers | SourceWithLayers[], config: EventHandlerConfig | undefined,
-  /**
-   * Optional function that transforms a raw {@link MapGeoJSONFeature} into the
-   * feature type `T` exposed by the module. When provided, every feature passed (fired)
-   * to event handlers is first run through this function, so callers receive the
-   * module's own feature shape instead of the underlying MapLibre feature.
+   * Narrows these events to part of what they cover, returning a {@link UserEvents} over just
+   * that part.
+   *
+   * Two things can be narrowed. A **feature predicate** keeps only the features you care about —
+   * available on every module, since only the module's own data can tell a major incident from a
+   * minor one. A **layer scope** keeps only part of the map's layers; the SDK offers this where
+   * a stable, typed vocabulary for those layers exists, which today means
+   * {@link BaseMapModule}'s layer groups.
    *
-   * When omitted, `T` defaults to `MapGeoJSONFeature` and features are forwarded
-   * as-is.
+   * A new instance, rather than this one narrowed in place: callers hold `events` and narrow it
+   * more than once, and mutating would make the second `where()` mean "first AND second" while
+   * leaving the surface it came from silently scoped — and its `config` overridden.
+   *
+   * Narrowing on both axes is one call, not two — {@link BaseMapModule}'s scope object takes a
+   * `features` predicate alongside its `layerGroups`. A further `where()` does intersect with
+   * this one, but two feature predicates read better as a single `a(f) && b(f)`.
+   *
+   * @param scope See {@link EventScope} — a predicate over this scope's feature type, or, where
+   * the module supports one, a scope object such as `{ layerGroups }`.
+   * @param config 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.
+   *
+   * @example
+   * ```typescript
+   * // Feature scope: only major incidents are clickable.
+   * trafficIncidents.events.where((incident) => incident.properties.magnitude === 'major')
+   *     .on('click', showIncidentDetails);
+   *
+   * // Layer scope with its own cursor, on the base map.
+   * baseMap.events
+   *     .where({ layerGroups: { mode: 'include', names: ['roadLabels'] } }, { cursorOnHover: 'pointer' })
+   *     .on('click', showRoadName);
+   *
+   * // A named scope, narrowed by a predicate.
+   * routing.events.tunnels.where((section) => section.properties.lengthInMeters > 500)
+   *     .on('click', showLongTunnel);
+   * ```
    */
-  mapping?: ((feature: MapGeoJSONFeature) => T) | undefined);
+  where(scope: EventScope<T, WHERE_SCOPE>, config?: EventHandlerConfig): UserEvents<T, WHERE_SCOPE>;
+  private resolveScope;
   /**
    * Register an event handler for user interactions with map features.
    *
@@ -3216,6 +3228,7 @@ declare class UserEvents<T = MapGeoJSONFeature> {
    * ```
    */
   on(type: EventType, handler: UserEventHandler<T>): () => void;
+  private toRegisteredHandler;
   /**
    * Remove all event handlers for a specific event type.
    *
@@ -3302,10 +3315,18 @@ declare class UserEvents<T = MapGeoJSONFeature> {
  * underlying {@link ModuleEvents} instance. Each `on` call returns an unsubscribe function.
  * Both user and module event types are also removable in bulk via {@link off}.
  *
+ * Named scopes, where a module has them, hang off this object as properties and are themselves
+ * `CombinedEvents` — so a scope carries the lifecycle events that module actually scopes.
+ * {@link where} narrows ad hoc instead, and returns a plain {@link UserEvents}: a filter you build
+ * on the spot has no lifecycle of its own.
+ *
  * @typeParam T - Feature type surfaced by user interaction handlers.
  * @typeParam CFG - Module configuration type passed to `config-change` handlers.
  * @typeParam TShown - Data type passed to `shown-features` handlers. Use `never` for
  *   modules that have no `show` method.
+ * @typeParam WHERE_SCOPE - Module-specific scope object accepted by {@link where}, in addition to a
+ *   feature predicate. `never` for modules that only support predicates. Unrelated to a module's
+ *   *named* scopes, which are properties on this object rather than an argument to it.
  *
  * @example
  * ```typescript
@@ -3332,10 +3353,27 @@ declare class UserEvents<T = MapGeoJSONFeature> {
  *
  * @group Events
  */
-declare class CombinedEvents<T, CFG, TShown = never> {
+export declare class CombinedEvents<T, CFG, TShown = never, WHERE_SCOPE = never> {
   private readonly userEventsInstance;
   private readonly moduleEventsInstance;
-  constructor(userEventsInstance: UserEvents<T>, moduleEventsInstance: ModuleEvents<CFG, TShown>);
+  constructor(userEventsInstance: UserEvents<T, WHERE_SCOPE>, moduleEventsInstance: ModuleEvents<CFG, TShown>);
+  /**
+   * Narrows these events to part of what they cover — see {@link UserEvents.where}.
+   *
+   * @param scope See {@link EventScope} — a predicate over this module's feature type, or, where
+   * the module supports one, 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.
+   *
+   * @example
+   * ```typescript
+   * trafficIncidents.events.where((incident) => incident.properties.magnitude === 'major')
+   *     .on('click', showIncidentDetails);
+   * ```
+   */
+  where(scope: EventScope<T, WHERE_SCOPE>, config?: EventHandlerConfig): UserEvents<T, WHERE_SCOPE>;
   /**
    * Subscribe to a user interaction event (`click`, `contextmenu`, `hover`, `long-hover`).
    *
@@ -3371,45 +3409,365 @@ declare class CombinedEvents<T, CFG, TShown = never> {
    * unsub();
    * ```
    */
-  on(type: 'config-change', handler: (config: CFG | undefined) => void): () => void;
+  on(type: 'config-change', handler: (config: CFG | undefined) => void): () => void;
+  /**
+   * Subscribe to shown-features events.
+   *
+   * Fires immediately after the module's `show()` method (or equivalent) has rendered
+   * new data on the map. Only available on modules that have a `show` method.
+   *
+   * @param type - `'shown-features'`
+   * @param handler - Receives the data that was passed to `show()`.
+   * @returns An unsubscribe function. Call it to remove **only this handler**.
+   *
+   * @example
+   * ```typescript
+   * const unsub = places.events.on('shown-features', (features) => {
+   *   fitMapToResults(features);
+   * });
+   * unsub();
+   * ```
+   */
+  on(type: ShownFeaturesType<TShown>, handler: (features: TShown) => void): () => void;
+  /**
+   * Remove **all** handlers for the given event type at once.
+   *
+   * Accepts both user interaction types (`click`, `contextmenu`, `hover`, `long-hover`) and
+   * module lifecycle types (`config-change`, `shown-features`).
+   *
+   * Prefer the unsubscribe function returned by {@link on} when you need to remove a single
+   * handler. Use `off` for bulk teardown — e.g. when unmounting a component that registered
+   * multiple handlers of the same type.
+   *
+   * @param type - The event type whose handlers should all be cleared.
+   *
+   * @example
+   * ```typescript
+   * places.events.off('click');          // clear all click handlers
+   * places.events.off('config-change');  // clear all config-change handlers
+   * ```
+   */
+  off(type: EventType | 'config-change' | 'shown-features'): void;
+}
+//#endregion
+//#region src/shared/AbstractMapModule.d.ts
+/**
+ * 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;
+};
+/**
+ * Whether a map module is based on a map style or on added GeoJSON data.
+ */
+type MapModuleSource = 'style' | 'geojson';
+/**
+ * Base class for all Maps SDK map modules.
+ *
+ * This abstract class provides the foundation for creating map modules that can display
+ * and manage various types of data on a TomTom map. It handles module lifecycle management,
+ * including initialization, configuration updates, and automatic restoration after map style changes.
+ *
+ * @remarks
+ * All map modules extend this class to ensure consistent behavior across the SDK.
+ * The class manages the module's sources, layers, and configuration, automatically
+ * handling map style changes by restoring the module's state when needed.
+ *
+ * The `sourceType` a module passes up says who owns the sources and layers it controls, and
+ * therefore how its instances behave:
+ *
+ * - `'geojson'` — the module adds and owns its own sources, layers and images, suffixed per
+ *   instance. Multi-instance, built with `create(map, config?)`.
+ * - `'style'` — the module controls sources and layers the map style already provides, under fixed
+ *   global IDs. A shared controller, obtained with `get(map, config?)`.
+ *
+ * @typeParam SOURCES_WITH_LAYERS - The type defining the sources and layers used by this module
+ * @typeParam CFG - The configuration type for this module, or undefined if no configuration is needed. When defined, must extend MapModuleCommonConfig.
+ *
+ * @example
+ * ```typescript
+ * class CustomModule extends AbstractMapModule<MySourcesWithLayers, MyConfig> {
+ *   constructor(tomtomMap: TomTomMap, config?: MyConfig) {
+ *     super('geojson', tomtomMap, config);
+ *   }
+ *   // Implement abstract methods...
+ * }
+ * ```
+ *
+ * @group Shared
+ */
+export declare abstract class AbstractMapModule<SOURCES_WITH_LAYERS extends SourcesWithLayers, CFG extends MapModuleCommonConfig | undefined = undefined> {
+  private readonly sourceType;
+  /**
+   * @ignore
+   */
+  protected readonly tomtomMap: TomTomMap;
+  /**
+   * @ignore
+   */
+  protected readonly eventsProxy: EventsProxy;
+  /**
+   * @ignore
+   */
+  protected readonly mapLibreMap: Map;
+  /**
+   * @ignore
+   */
+  protected sourcesWithLayers: SOURCES_WITH_LAYERS;
+  /**
+   * @ignore
+   */
+  protected _sourceAndLayerIDs: Record<keyof SOURCES_WITH_LAYERS, SourceWithLayerIDs>;
+  /**
+   * @ignore
+   */
+  protected config?: CFG;
+  /**
+   * @ignore
+   */
+  protected _initializing: boolean;
+  /**
+   * Handlers registered via events.on('config-change', …).
+   * Stored here so the array reference stays stable across multiple events getter calls.
+   * @ignore
+   */
+  protected readonly configChangeHandlers: ((config: CFG | undefined) => void)[];
+  /**
+   * Monotonically increasing index unique to this instance within its concrete module
+   * class. Auto-assigned in the constructor based on `new.target`, so each subclass
+   * has its own counter without per-subclass boilerplate. Use as a suffix on
+   * auto-generated source and layer IDs to keep them stable across style changes and
+   * unique across module instances.
+   * @ignore
+   */
+  protected readonly instanceIndex: number;
+  /**
+   * Per-concrete-class instance counter. WeakMap-keyed so unloaded classes can be GC'd.
+   * @ignore
+   */
+  private static readonly instanceCounters;
+  /**
+   * Indicates that this module is currently adding its sources and layers to the map, so during this time it might not function properly.
+   * @see waitUntilModuleReady
+   * @private
+   */
+  private moduleReady;
+  /**
+   * Builds this module based on a given Maps SDK map.
+   * @param tomtomMap The map. It may or may not be initialized at this stage,
+   * but the module ensures to initialize itself once it is.
+   * @param sourceType Whether the module is based on a map style or on added GeoJSON data.
+   * @param config Optional configuration to initialize directly as soon as the map is ready.
+   */
+  protected constructor(sourceType: MapModuleSource, tomtomMap: TomTomMap, config?: CFG);
+  /**
+   * Initializes the sources with layers of this module.
+   * @param config The optional configuration for the module.
+   * @param restore Whether we are restoring an existing module after the map style got reloaded.
+   * @protected
+   * @ignore
+   */
+  protected initSourcesWithLayers(config?: CFG, restore?: boolean): void;
+  /**
+   * Initializes the sources with layers for the specific module.
+   * @protected
+   * @ignore
+   */
+  protected abstract _initSourcesWithLayers(config?: CFG, restore?: boolean): SOURCES_WITH_LAYERS;
+  protected waitUntilModuleReady(): Promise<void>;
+  /**
+   * Applies a configuration to this module.
+   *
+   * This method updates the module's behavior and appearance based on the provided configuration.
+   * The configuration is stored internally and will be automatically reapplied if the map style changes.
+   *
+   * @param config - The configuration object to apply to the module. Pass `undefined` to reset
+   * the configuration to default values.
+   *
+   * @remarks
+   * When a configuration is applied, the module updates its visual representation and behavior
+   * accordingly. The configuration persists across map style changes, ensuring consistent
+   * module behavior even when the map's base style is modified.
+   *
+   * Unless a module documents otherwise, the given configuration **replaces** the current one
+   * rather than being merged into it. To change one part of it, spread the current
+   * configuration into the new one: `myModule.applyConfig({ ...myModule.getConfig(), theme })`.
+   *
+   * @example
+   * ```typescript
+   * // Apply a new configuration
+   * myModule.applyConfig({ visible: true, opacity: 0.8 });
+   *
+   * // Reset to default configuration
+   * myModule.applyConfig(undefined);
+   * ```
+   *
+   * @see {@link resetConfig} for a convenience method to reset configuration
+   * @see {@link getConfig} to retrieve the current configuration
+   */
+  applyConfig(config: CFG | undefined): void;
+  /**
+   * Emits a `config-change` event to all registered handlers.
+   * Skipped during module initialisation to avoid spurious events.
+   * @ignore
+   */
+  protected emitConfigChange(): void;
+  /**
+   * Internal implementation to apply config for the specific module.
+   * @param config The config to apply. this.config contains the previous configuration (if any).
+   * Once the method returns config, it will be assigned to this.config.
+   * @protected
+   * @ignore
+   */
+  protected abstract _applyConfig(config: CFG | undefined): CFG | undefined;
+  /**
+   * Resets the configuration of this module to its default values.
+   *
+   * This is a convenience method that clears any previously applied configuration
+   * and restores the module to its initial state. This is equivalent to calling
+   * `applyConfig(undefined)`.
+   *
+   * @remarks
+   * After calling this method, the module will behave as if no configuration was ever applied.
+   * Any custom settings, styling, or behavior modifications will be removed and replaced
+   * with default values.
+   *
+   * @example
+   * ```typescript
+   * // Apply some configuration
+   * myModule.applyConfig({ visible: true, opacity: 0.5 });
+   *
+   * // Later, reset to defaults
+   * myModule.resetConfig();
+   * ```
+   *
+   * @see {@link applyConfig} to apply a new configuration
+   * @see {@link getConfig} to retrieve the current configuration before resetting
+   */
+  resetConfig(): void;
+  private restoreDataAndConfig;
+  /**
+   * implementation needed to restore the module state (data and config applied to the module).
+   * to be used to restore module state after map style change
+   * @protected
+   * @ignore
+   */
+  protected restoreDataAndConfigImpl(): void;
+  /**
+   * Retrieves a copy of the current module configuration.
+   *
+   * This method returns a shallow copy of the configuration object that is currently
+   * applied to the module. If no configuration has been applied, it returns `undefined`.
+   *
+   * @returns A shallow copy of the current configuration object, or `undefined` if no
+   * configuration is currently applied. The returned object is a copy to prevent
+   * unintended modifications to the internal state.
+   *
+   * @remarks
+   * The returned configuration object is a shallow copy, which means that while the
+   * top-level properties are copied, any nested objects or arrays are still referenced
+   * from the original configuration. This is sufficient for most use cases but should
+   * be kept in mind when dealing with complex configurations.
+   *
+   * @example
+   * ```typescript
+   * // Apply a configuration
+   * myModule.applyConfig({ visible: true, opacity: 0.8 });
+   *
+   * // Later, retrieve the current configuration
+   * const currentConfig = myModule.getConfig();
+   * console.log(currentConfig); // { visible: true, opacity: 0.8 }
+   *
+   * // When no config is applied
+   * myModule.resetConfig();
+   * console.log(myModule.getConfig()); // undefined
+   * ```
+   *
+   * @see {@link applyConfig} to modify the configuration
+   * @see {@link resetConfig} to clear the configuration
+   */
+  getConfig(): NonNullable<CFG> | undefined;
   /**
-   * Subscribe to shown-features events.
+   * Gets the source and layer identifiers for all sources managed by this module.
    *
-   * Fires immediately after the module's `show()` method (or equivalent) has rendered
-   * new data on the map. Only available on modules that have a `show` method.
+   * This property provides access to the MapLibre source and layer IDs that were created
+   * and are managed by this module. These IDs can be used to interact directly with
+   * MapLibre's API or to identify which layers belong to this module.
    *
-   * @param type - `'shown-features'`
-   * @param handler - Receives the data that was passed to `show()`.
-   * @returns An unsubscribe function. Call it to remove **only this handler**.
+   * @returns A record mapping each source name to its corresponding source ID and layer IDs.
+   * Each entry contains the MapLibre source identifier and an array of layer identifiers
+   * associated with that source.
+   *
+   * @remarks
+   * The returned IDs are useful when you need to:
+   * - Directly manipulate layers using MapLibre's native API
+   * - Identify which layers on the map belong to this module
+   * - Set layer ordering or positioning relative to other layers
+   * - Access source or layer properties through MapLibre methods
    *
    * @example
    * ```typescript
-   * const unsub = places.events.on('shown-features', (features) => {
-   *   fitMapToResults(features);
+   * const ids = myModule.sourceAndLayerIDs;
+   * console.log(ids);
+   * // {
+   * //   mySource: {
+   * //     sourceID: 'my-source-id',
+   * //     layerIDs: ['layer-1', 'layer-2']
+   * //   }
+   * // }
+   *
+   * // Use with MapLibre API
+   * const map = myModule.mapLibreMap;
+   * ids.mySource.layerIDs.forEach(layerId => {
+   *   map.setLayoutProperty(layerId, 'visibility', 'visible');
    * });
-   * unsub();
    * ```
    */
-  on(type: 'shown-features', handler: (features: TShown) => void): () => void;
+  get sourceAndLayerIDs(): Record<keyof SOURCES_WITH_LAYERS, SourceWithLayerIDs>;
   /**
-   * Remove **all** handlers for the given event type at once.
+   * User events over the named sources of this module — what every named scope is.
    *
-   * Accepts both user interaction types (`click`, `contextmenu`, `hover`, `long-hover`) and
-   * module lifecycle types (`config-change`, `shown-features`).
+   * `sourceNames` may list several sources when they carry the same data in different display
+   * modes — clustered and unclustered places, or the hexgrid/square/heatmap trio — and missing
+   * ones are skipped, so an optional source costs the caller nothing.
    *
-   * Prefer the unsubscribe function returned by {@link on} when you need to remove a single
-   * handler. Use `off` for bulk teardown — e.g. when unmounting a component that registered
-   * multiple handlers of the same type.
+   * A scope carries no lifecycle events: a module has one configuration and one `show` stream,
+   * neither of which a scope narrows. Both live on the module's own `events`.
+   * @ignore
+   */
+  protected userEvents<T = MapGeoJSONFeature, WHERE_SCOPE = never>(sourceNames: (keyof SOURCES_WITH_LAYERS)[], options?: EventScopeOptions<T, WHERE_SCOPE>): UserEvents<T, WHERE_SCOPE>;
+  /**
+   * The event surface of a module with no `show`: user events over the named sources, plus
+   * `config-change`. `shown-features` is not subscribable here — `TShown` is `never`, which
+   * makes the overload uncallable.
+   * @ignore
+   */
+  protected moduleEvents<T = MapGeoJSONFeature, WHERE_SCOPE = never>(sourceNames: (keyof SOURCES_WITH_LAYERS)[], options?: EventScopeOptions<T, WHERE_SCOPE>): CombinedEvents<T, CFG, never, WHERE_SCOPE>;
+  /**
+   * The event surface of a module that has a `show`. `shownFeaturesHandlers` is passed
+   * positionally, and must be the very array `show` iterates: handing over a throwaway would
+   * accept subscriptions that can never fire.
+   * @ignore
+   */
+  protected moduleEventsWithShown<T, TShown, WHERE_SCOPE = never>(sourceNames: (keyof SOURCES_WITH_LAYERS)[], shownFeaturesHandlers: ((features: TShown) => void)[], options?: EventScopeOptions<T, WHERE_SCOPE>): CombinedEvents<T, CFG, TShown, WHERE_SCOPE>;
+  /**
+   * Attaches named scopes to the module's event surface, so `events.on(...)` and
+   * `events.<scope>.on(...)` live on one object.
    *
-   * @param type - The event type whose handlers should all be cleared.
+   * A module only declares scopes where it manages more than one surface; with a single source,
+   * `events` already is that scope and a named alias would just duplicate it.
    *
-   * @example
-   * ```typescript
-   * places.events.off('click');          // clear all click handlers
-   * places.events.off('config-change');  // clear all config-change handlers
-   * ```
+   * The two scope type parameters are unrelated, and a module typically has one or the other:
+   * `NAMED_SCOPES` is the object of scopes hung off `events` as properties (RoutingModule's
+   * `mainLines`, `waypoints`, …), while `WHERE_SCOPE` is the scope object `events.where(…)`
+   * accepts as an argument (BaseMapModule's `{ layerGroups }`).
+   * @ignore
    */
-  off(type: EventType | 'config-change' | 'shown-features'): void;
+  protected buildEvents<T, TShown, WHERE_SCOPE, NAMED_SCOPES extends object>(moduleWide: CombinedEvents<T, CFG, TShown, WHERE_SCOPE>, scopes: NAMED_SCOPES): CombinedEvents<T, CFG, TShown, WHERE_SCOPE> & NAMED_SCOPES;
 }
 //#endregion
 //#region src/shared/layers/commonLayerProps.d.ts
@@ -3480,7 +3838,7 @@ type MapFont = (typeof mapFonts)[number];
  *
  * @group POIs
  */
-declare const POI_SOURCE_ID = "vectorTiles";
+export declare const POI_SOURCE_ID = "vectorTiles";
 /**
  * Source identifier for hillshade terrain visualization.
  *
@@ -3490,7 +3848,7 @@ declare const POI_SOURCE_ID = "vectorTiles";
  *
  * @group Hillshade
  */
-declare const HILLSHADE_SOURCE_ID = "hillshade";
+export declare const HILLSHADE_SOURCE_ID = "hillshade";
 /**
  * Source identifier for base map vector tiles.
  *
@@ -3500,7 +3858,7 @@ declare const HILLSHADE_SOURCE_ID = "hillshade";
  *
  * @group Base Map
  */
-declare const BASE_MAP_SOURCE_ID = "vectorTiles";
+export declare const BASE_MAP_SOURCE_ID = "vectorTiles";
 /**
  * Source identifier for traffic incidents vector tiles.
  *
@@ -3510,7 +3868,7 @@ declare const BASE_MAP_SOURCE_ID = "vectorTiles";
  *
  * @group Traffic Incidents
  */
-declare const TRAFFIC_INCIDENTS_SOURCE_ID = "vectorTilesIncidents";
+export declare const TRAFFIC_INCIDENTS_SOURCE_ID = "vectorTilesIncidents";
 /**
  * Source identifier for traffic flow vector tiles.
  *
@@ -3520,7 +3878,27 @@ declare const TRAFFIC_INCIDENTS_SOURCE_ID = "vectorTilesIncidents";
  *
  * @group Traffic Flow
  */
-declare const TRAFFIC_FLOW_SOURCE_ID = "vectorTilesFlow";
+export declare const TRAFFIC_FLOW_SOURCE_ID = "vectorTilesFlow";
+//#endregion
+//#region src/shared/sharedInstance.d.ts
+/**
+ * Returns the shared instance of a style-owned module for this map, building it on first use.
+ *
+ * Style-owned modules control sources and layers the map style already provides, under fixed
+ * global IDs, so a second instance would be a second controller over one piece of shared state.
+ * Callers get the same instance instead — two components each asking for hillshade is reasonable
+ * code, and making them hoist a shared reference would be work pushed onto them for no benefit.
+ *
+ * @param map The map the module belongs to.
+ * @param moduleClass The concrete module class, which together with the map identifies the instance.
+ * @param construct Builds the instance. Called at most once per map and class.
+ * @param applyToExisting Applies the caller's configuration to an instance that already exists.
+ * Omit it when the caller passed no configuration: `get(map)` is a plain accessor and must not
+ * re-apply defaults over settings someone else already made.
+ *
+ * @ignore
+ */
+export declare const sharedInstance: <MODULE>(map: TomTomMap, moduleClass: Function, construct: () => MODULE, applyToExisting?: (existing: MODULE) => void) => Promise<MODULE>;
 //#endregion
 //#region src/base/types/baseMapModuleConfig.d.ts
 /**
@@ -3534,11 +3912,10 @@ declare const TRAFFIC_FLOW_SOURCE_ID = "vectorTilesFlow";
  * style's own draw order rather than the settlement hierarchy.
  *
  * @see {@link BaseMapLayerGroupName}
- * @see {@link BaseMapModuleInitConfig.layerGroupsFilter}
  *
  * @group Base Map
  */
-declare const baseMapLayerGroupNames: readonly ["land", "water", "buildings2D", "roads", "railways", "ferries", "borders", "buildings3D", "natureLabels", "roadLabels", "roadShields", "houseNumbers", "smallerTownLabels", "stateLabels", "cityLabels", "allPlaceLabels", "capitalLabels", "countryLabels"];
+export declare const baseMapLayerGroupNames: readonly ["land", "water", "buildings2D", "roads", "railways", "ferries", "borders", "buildings3D", "natureLabels", "roadLabels", "roadShields", "houseNumbers", "smallerTownLabels", "stateLabels", "cityLabels", "allPlaceLabels", "capitalLabels", "countryLabels"];
 /**
  * Name of a base map layer group.
  *
@@ -3587,7 +3964,7 @@ declare const baseMapLayerGroupNames: readonly ["land", "water", "buildings2D",
  *
  * @group Base Map
  */
-type BaseMapLayerGroupName = (typeof baseMapLayerGroupNames)[number];
+export type BaseMapLayerGroupName = (typeof baseMapLayerGroupNames)[number];
 /**
  * Layer group visibility configuration with explicit visible state.
  *
@@ -3613,7 +3990,7 @@ type BaseMapLayerGroupName = (typeof baseMapLayerGroupNames)[number];
  *
  * @group Base Map
  */
-type BaseMapLayerGroupsVisibility = BaseMapLayerGroups & {
+export type BaseMapLayerGroupsVisibility = BaseMapLayerGroups & {
   visible: boolean;
 };
 /**
@@ -3657,7 +4034,7 @@ type BaseMapLayerGroupsVisibility = BaseMapLayerGroups & {
  *
  * @group Base Map
  */
-type BaseMapLayerGroups = {
+export type BaseMapLayerGroups = {
   /**
    * Filter mode determining whether groups are included or excluded.
    *
@@ -3726,7 +4103,7 @@ type BaseMapLayerGroups = {
  *
  * @group Base Map
  */
-type BaseMapModuleConfig = MapModuleCommonConfig & {
+export type BaseMapModuleConfig = MapModuleCommonConfig & {
   /**
    * Controls the visibility of all layers associated with this module.
    *
@@ -3737,9 +4114,6 @@ type BaseMapModuleConfig = MapModuleCommonConfig & {
    * Optional visibility configuration for specific layer groups.
    *
    * @remarks
-   * **Important:** The layer groups specified here must be included in the
-   * module (not excluded by `layerGroupsFilter` during initialization).
-   *
    * Use this to control visibility of layer groups at runtime without
    * reinitializing the module.
    *
@@ -3762,90 +4136,41 @@ type BaseMapModuleConfig = MapModuleCommonConfig & {
    */
   layerGroupsVisibility?: BaseMapLayerGroupsVisibility;
 };
+//#endregion
+//#region src/base/BaseMapModule.d.ts
+type BaseSourceAndLayers = {
+  vectorTiles: StyleSourceWithLayers;
+};
 /**
- * Initialization configuration for the BaseMapModule.
- *
- * Extends {@link BaseMapModuleConfig} with additional options available only
- * during module initialization.
- *
- * @remarks
- * **Initialization vs Runtime:**
- * - `layerGroupsFilter`: Only available at init - determines which groups to load
- * - `layerGroupsVisibility`: Available at init and runtime - controls visibility
+ * Scope accepted by `baseMap.events.where(...)`, in addition to a plain feature predicate.
  *
- * **Use Cases:**
- * - Create minimal maps with only essential layers
- * - Build custom map styles by excluding certain features
- * - Optimize performance by not loading unnecessary layers
+ * `layerGroups` narrows to part of the map — road labels, water, buildings — using the same
+ * {@link BaseMapLayerGroupName} vocabulary as `setVisible`. `features` narrows within those
+ * layers, and the two combine.
  *
  * @example
  * ```typescript
- * // Initialize with only roads and water
- * const initConfig: BaseMapModuleInitConfig = {
- *   layerGroupsFilter: {
- *     mode: 'include',
- *     names: ['roads', 'roadLabels', 'water', 'land']
- *   },
- *   visible: true
- * };
- *
- * // Exclude buildings from initialization
- * const noBuildingsConfig: BaseMapModuleInitConfig = {
- *   layerGroupsFilter: {
- *     mode: 'exclude',
- *     names: ['buildings2D', 'buildings3D', 'houseNumbers']
- *   }
- * };
- *
- * // Minimal map for data overlay
- * const overlayBaseConfig: BaseMapModuleInitConfig = {
- *   layerGroupsFilter: {
- *     mode: 'include',
- *     names: ['water', 'land', 'borders']
- *   },
- *   visible: true
- * };
+ * baseMap.events
+ *     .where({ layerGroups: { mode: 'include', names: ['roadLabels', 'roadShields'] } },
+ *            { cursorOnHover: 'pointer' })
+ *     .on('click', (feature) => showRoadName(feature.properties.name));
  * ```
  *
  * @group Base Map
  */
-type BaseMapModuleInitConfig = BaseMapModuleConfig & {
-  /**
-   * Layer groups to include/exclude during module initialization.
-   *
-   * @remarks
-   * **One-time configuration:** This can only be set during initialization.
-   * Once the module is created, you cannot change which groups are loaded,
-   * only their visibility via `layerGroupsVisibility`.
-   *
-   * @example
-   * ```typescript
-   * // Load only essential layers
-   * layerGroupsFilter: {
-   *   mode: 'include',
-   *   names: ['land', 'water', 'roads', 'borders']
-   * }
-   *
-   * // Load everything except 3D buildings
-   * layerGroupsFilter: {
-   *   mode: 'exclude',
-   *   names: ['buildings3D']
-   * }
-   *
-   * // Minimal overlay map
-   * layerGroupsFilter: {
-   *   mode: 'include',
-   *   names: ['water', 'land']
-   * }
-   * ```
-   */
-  layerGroupsFilter?: BaseMapLayerGroups;
-};
-//#endregion
-//#region src/base/BaseMapModule.d.ts
-type BaseSourceAndLayers = {
-  vectorTiles: StyleSourceWithLayers;
+export type BaseMapEventScope = {
+  /** Which layer groups this scope covers. */
+  layerGroups: BaseMapLayerGroups;
+  /** Optional further narrowing to particular features within those layers. */
+  features?: (feature: MapGeoJSONFeature) => boolean;
 };
+/**
+ * Event surface of {@link BaseMapModule}. The base map manages one source, so it has no named
+ * scopes — `events` is that scope, narrowed on demand with `where()`.
+ *
+ * @group Base Map
+ */
+export type BaseMapEvents = CombinedEvents<MapGeoJSONFeature, BaseMapModuleConfig, never, BaseMapEventScope>;
 /**
  * Base Map Module for controlling standard map layers and their visibility.
  *
@@ -3892,13 +4217,7 @@ type BaseSourceAndLayers = {
  * @example
  * Working with layer groups:
  * ```typescript
- * // Show only roads and borders
- * const baseMap = await BaseMapModule.get(map, {
- *   layerGroupsFilter: {
- *     mode: 'include',
- *     names: ['roads', 'roadLabels', 'borders']
- *   }
- * });
+ * const baseMap = await BaseMapModule.get(map);
  *
  * // Hide buildings and labels
  * baseMap.setVisible(false, {
@@ -3936,7 +4255,7 @@ type BaseSourceAndLayers = {
  *
  * @group Base Map
  */
-declare class BaseMapModule extends AbstractMapModule<BaseSourceAndLayers, BaseMapModuleConfig> {
+export declare class BaseMapModule extends AbstractMapModule<BaseSourceAndLayers, BaseMapModuleConfig> {
   private layersByGroup?;
   /**
    * Asynchronously retrieves a BaseMapModule instance for the given map.
@@ -3950,6 +4269,12 @@ declare class BaseMapModule extends AbstractMapModule<BaseSourceAndLayers, BaseM
    * @returns A promise that resolves to the initialized BaseMapModule.
    *
    * @remarks
+   * **Instances:**
+   * `BaseMapModule` controls the base-map source and layers the map style already provides, under
+   * fixed global IDs, so every map has exactly one — a second `get()` returns the same instance.
+   * To work with part of the map, name the layer groups per call: `setVisible(false, {
+   * layerGroups })` for visibility, `events.where({ layerGroups })` for events.
+   *
    * **Initialization:**
    * - Waits for map to be ready before creating module
    * - Validates that required sources exist in the map style
@@ -3957,7 +4282,6 @@ declare class BaseMapModule extends AbstractMapModule<BaseSourceAndLayers, BaseM
    *
    * **Configuration Options:**
    * - `visible`: Initial visibility state
-   * - `layerGroupsFilter`: Which layer groups to include/exclude
    * - `layerGroupsVisibility`: Fine-grained visibility per group
    *
    * @throws Error if the base map source is not found in the style
@@ -3973,31 +4297,20 @@ declare class BaseMapModule extends AbstractMapModule<BaseSourceAndLayers, BaseM
    * ```typescript
    * const baseMap = await BaseMapModule.get(map, {
    *   visible: true,
-   *   layerGroupsFilter: {
-   *     mode: 'exclude',
-   *     names: ['buildings3D', 'houseNumbers']
-   *   }
-   * });
-   * ```
-   *
-   * @example
-   * Show only specific groups:
-   * ```typescript
-   * const baseMap = await BaseMapModule.get(map, {
-   *   layerGroupsFilter: {
+   *   layerGroupsVisibility: {
    *     mode: 'include',
-   *     names: ['water', 'land', 'borders']
-   *   },
-   *   visible: true
+   *     names: ['buildings3D', 'houseNumbers'],
+   *     visible: false
+   *   }
    * });
    * ```
    */
-  static get(tomtomMap: TomTomMap, config?: BaseMapModuleInitConfig): Promise<BaseMapModule>;
+  static get(tomtomMap: TomTomMap, config?: BaseMapModuleConfig): Promise<BaseMapModule>;
   private constructor();
   /**
    * @ignore
    */
-  protected _initSourcesWithLayers(config: BaseMapModuleInitConfig | undefined): {
+  protected _initSourcesWithLayers(): {
     vectorTiles: StyleSourceWithLayers<import("maplibre-gl").SourceSpecification, import("maplibre-gl").Source>;
   };
   /**
@@ -4011,12 +4324,19 @@ declare class BaseMapModule extends AbstractMapModule<BaseSourceAndLayers, BaseM
   /**
    * Checks if any base map layers are currently visible.
    *
-   * @returns `true` if at least one base map layer is visible, `false` if all are hidden.
+   * @param options - Optional settings for fine-grained control.
+   * @param options.layerGroups - Ask about specific layer groups instead of all layers.
+   *
+   * @returns `true` if at least one of the layers asked about is visible, `false` if all are
+   * hidden.
    *
    * @remarks
    * This checks the actual visibility state of layers in the map, not just the
    * module's configuration setting.
    *
+   * Mirrors {@link setVisible}, so a group toggled through one can be read back through the
+   * other — which is how a per-group control reflects the state the style actually starts in.
+   *
    * @example
    * ```typescript
    * if (baseMap.isVisible()) {
@@ -4025,8 +4345,17 @@ declare class BaseMapModule extends AbstractMapModule<BaseSourceAndLayers, BaseM
    *   console.log('Base map is hidden');
    * }
    * ```
+   *
+   * @example
+   * Ask about one group:
+   * ```typescript
+   * // buildings3D ships hidden in most styles
+   * const shown = baseMap.isVisible({ layerGroups: { mode: 'include', names: ['buildings3D'] } });
+   * ```
    */
-  isVisible(): boolean;
+  isVisible(options?: {
+    layerGroups?: BaseMapLayerGroups;
+  }): boolean;
   /**
    * Sets the visibility of base map layers.
    *
@@ -4142,7 +4471,7 @@ declare class BaseMapModule extends AbstractMapModule<BaseSourceAndLayers, BaseM
    * unsub(); // remove by returned function
    * ```
    */
-  get events(): CombinedEvents<MapGeoJSONFeature, BaseMapModuleConfig, never>;
+  get events(): BaseMapEvents;
 }
 //#endregion
 //#region src/custom/types/customGeoJSONModuleConfig.d.ts
@@ -4153,7 +4482,7 @@ type DistributiveOmit<T, K extends string> = T extends unknown ? Omit<T, K> : ne
  *
  * @group Custom
  */
-type CustomGeoJSONImageData = HTMLImageElement | ImageBitmap | ImageData | StyleImageInterface | {
+export type CustomGeoJSONImageData = HTMLImageElement | ImageBitmap | ImageData | StyleImageInterface | {
   width: number;
   height: number;
   data: Uint8Array | Uint8ClampedArray;
@@ -4166,7 +4495,7 @@ type CustomGeoJSONImageData = HTMLImageElement | ImageBitmap | ImageData | Style
  *
  * @group Custom
  */
-type CustomGeoJSONImageSpec = {
+export type CustomGeoJSONImageSpec = {
   /**
    * The image data, in any format accepted by MapLibre's `addImage`. Asynchronous
    * sources (URLs, SVG strings) are not supported here — pre-load them and pass an
@@ -4197,7 +4526,7 @@ type CustomGeoJSONImageSpec = {
  *
  * @group Custom
  */
-type CustomGeoJSONLayerSpec = DistributiveOmit<LayerSpecWithSource, 'source' | 'id'> & {
+export type CustomGeoJSONLayerSpec = DistributiveOmit<LayerSpecWithSource, 'source' | 'id'> & {
   id?: string;
   beforeID?: string;
 };
@@ -4208,7 +4537,7 @@ type CustomGeoJSONLayerSpec = DistributiveOmit<LayerSpecWithSource, 'source' | '
  *
  * @group Custom
  */
-type CustomGeoJSONSourceSpec = {
+export type CustomGeoJSONSourceSpec = {
   /**
    * Optional MapLibre source ID. Auto-generated as
    * `custom-geojson-${instanceIndex}-${sourceName}` when absent.
@@ -4252,7 +4581,7 @@ type CustomGeoJSONSourceSpec = {
  *
  * @group Custom
  */
-type CustomGeoJSONModuleConfig<TSources extends Record<string, FeatureCollection> = Record<string, FeatureCollection>> = MapModuleCommonConfig & {
+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.
    *
@@ -4311,7 +4640,17 @@ type CustomGeoJSONSourcesWithLayers<TSources extends Record<string, FeatureColle
  *
  * @group Custom
  */
-type CustomGeoJSONEvents<TSources extends Record<string, FeatureCollection>> = { [K in keyof TSources]: CombinedEvents<MapGeoJSONFeature, CustomGeoJSONModuleConfig<TSources>, TSources[K]>; };
+/**
+ * What `module.events.on('shown-features', ...)` receives. This module's `show` names the source
+ * it writes, so the event names it too — the one module whose shown data is per source.
+ *
+ * @group Custom
+ */
+export type CustomGeoJSONShownFeatures<TSources extends Record<string, FeatureCollection>> = { [K in keyof TSources]: {
+  sourceName: K;
+  data: TSources[K];
+}; }[keyof TSources];
+export type CustomGeoJSONEvents<TSources extends Record<string, FeatureCollection>> = CombinedEvents<MapGeoJSONFeature, CustomGeoJSONModuleConfig<TSources>, CustomGeoJSONShownFeatures<TSources>> & { [K in keyof TSources]: UserEvents<MapGeoJSONFeature>; };
 /**
  * Module for displaying customer-owned GeoJSON data with TomTom SDK support.
  *
@@ -4324,6 +4663,11 @@ type CustomGeoJSONEvents<TSources extends Record<string, FeatureCollection>> = {
  * this module makes no assumptions about how data is rendered — the caller passes raw
  * MapLibre layer specs (`circle`, `heatmap`, `fill`, `line`, `symbol`, …).
  *
+ * @remarks
+ * Because the sources and layers are caller-supplied, the module has no built-in defaults:
+ * `resetConfig()` (or `applyConfig(undefined)`) returns to the configuration passed to
+ * {@link CustomGeoJSONModule.create | create}, and `getConfig()` never becomes `undefined`.
+ *
  * @typeParam TSources - A record mapping source names to the {@link FeatureCollection}
  * type each source carries. Pass this generic when you want type-safe `show` /
  * `getShown` per source.
@@ -4331,7 +4675,7 @@ type CustomGeoJSONEvents<TSources extends Record<string, FeatureCollection>> = {
  * @example
  * Single source, default generic:
  * ```typescript
- * const module = await CustomGeoJSONModule.get(map, {
+ * const module = await CustomGeoJSONModule.create(map, {
  *     sources: {
  *         points: {
  *             layers: [{ type: 'circle', paint: { 'circle-radius': 4, 'circle-color': '#0a3653' } }],
@@ -4351,7 +4695,7 @@ type CustomGeoJSONEvents<TSources extends Record<string, FeatureCollection>> = {
  *     buildings: FeatureCollection<Polygon, { name: string }>;
  * };
  *
- * const module = await CustomGeoJSONModule.get<Sources>(map, {
+ * const module = await CustomGeoJSONModule.create<Sources>(map, {
  *     sources: {
  *         heatmap: { layers: [{ type: 'heatmap', paint: { 'heatmap-radius': 12 } }] },
  *         buildings: { layers: [{ type: 'fill', paint: { 'fill-color': '#5a5' } }] },
@@ -4367,7 +4711,7 @@ type CustomGeoJSONEvents<TSources extends Record<string, FeatureCollection>> = {
  * ```typescript
  * type Buildings = FeatureCollection<Point, { Name: string }>;
  *
- * const module = await CustomGeoJSONModule.get<{ heatmap: Buildings; markers: Buildings }>(map, {
+ * const module = await CustomGeoJSONModule.create<{ heatmap: Buildings; markers: Buildings }>(map, {
  *     sources: {
  *         heatmap: { layers: heatmapLayers },
  *         markers: { layers: markerLayers },
@@ -4379,19 +4723,24 @@ type CustomGeoJSONEvents<TSources extends Record<string, FeatureCollection>> = {
  *
  * @group Custom
  */
-declare class CustomGeoJSONModule<TSources extends Record<string, FeatureCollection> = Record<string, FeatureCollection>> extends AbstractMapModule<CustomGeoJSONSourcesWithLayers<TSources>, CustomGeoJSONModuleConfig<TSources>> {
+export declare class CustomGeoJSONModule<TSources extends Record<string, FeatureCollection> = Record<string, FeatureCollection>> extends AbstractMapModule<CustomGeoJSONSourcesWithLayers<TSources>, CustomGeoJSONModuleConfig<TSources>> {
   private resolvedSourceIDs;
   private resolvedLayerSpecs;
   private lastShown;
-  private shownFeaturesHandlersBySource;
+  private initialConfig;
+  private readonly shownFeaturesHandlers;
   /**
    * Creates a new {@link CustomGeoJSONModule} once the map is ready.
    *
+   * `CustomGeoJSONModule` owns the sources, layers and images it adds, all suffixed per instance.
+   * Every call therefore returns a **new, independent** instance, and stacking several of them on
+   * one map is a supported thing to do.
+   *
    * @param tomtomMap The TomTomMap instance.
    * @param config Module configuration. `sources` is required and must contain at
    * least one entry; each entry must have at least one layer.
    */
-  static get<TSources extends Record<string, FeatureCollection> = Record<string, FeatureCollection>>(tomtomMap: TomTomMap, config: CustomGeoJSONModuleConfig<TSources>): Promise<CustomGeoJSONModule<TSources>>;
+  static create<TSources extends Record<string, FeatureCollection> = Record<string, FeatureCollection>>(tomtomMap: TomTomMap, config: CustomGeoJSONModuleConfig<TSources>): Promise<CustomGeoJSONModule<TSources>>;
   private constructor();
   /**
    * @ignore
@@ -4459,15 +4808,15 @@ declare class CustomGeoJSONModule<TSources extends Record<string, FeatureCollect
    * @example
    * ```typescript
    * module.events.buildings.on('click', (feature, lngLat) => { ... });
-   * module.events.heatmap.on('shown-features', (data) => { ... });
-   * module.events.buildings.on('config-change', (config) => { ... });
+   * module.events.on('shown-features', ({ sourceName, data }) => { ... });
+   * module.events.on('config-change', (config) => { ... });
    * ```
    */
   get events(): CustomGeoJSONEvents<TSources>;
 }
 //#endregion
 //#region src/geometry/layers/colorPalettes.d.ts
-declare const colorPalettes: {
+export declare const colorPalettes: {
   warm: string[];
   browns: string[];
   cold: string[];
@@ -4483,8 +4832,8 @@ declare const colorPalettes: {
   fadedRainbow: string[];
   pastelRainbow: string[];
 };
-type ColorPaletteOptions = keyof typeof colorPalettes;
-declare const colorPaletteIDs: ColorPaletteOptions[];
+export type ColorPaletteOptions = keyof typeof colorPalettes;
+export declare const colorPaletteIDs: ColorPaletteOptions[];
 //#endregion
 //#region src/geometry/types/geometryTheme.d.ts
 /**
@@ -4499,13 +4848,13 @@ declare const colorPaletteIDs: ColorPaletteOptions[];
  *
  * @group Geometries
  */
-type GeometryTheme = 'filled' | 'outline' | 'inverted';
+export type GeometryTheme = 'filled' | 'outline' | 'inverted';
 /**
  * All valid {@link GeometryTheme} values.
  *
  * @group Geometries
  */
-declare const geometryThemes: readonly ["filled", "outline", "inverted"];
+export declare const geometryThemes: readonly ["filled", "outline", "inverted"];
 //#endregion
 //#region src/geometry/types/geometriesModuleConfig.d.ts
 /**
@@ -4518,7 +4867,7 @@ declare const geometryThemes: readonly ["filled", "outline", "inverted"];
  * const fill: GeometryFillConfig = { color: '#FF5733', opacity: 0.3 };
  *
  * // Palette name
- * const fill: GeometryFillConfig = { color: 'red', opacity: 0.25 };
+ * const fill: GeometryFillConfig = { color: 'blues', opacity: 0.25 };
  *
  * // Data-driven color based on properties
  * const fill: GeometryFillConfig = {
@@ -4529,9 +4878,9 @@ declare const geometryThemes: readonly ["filled", "outline", "inverted"];
  *
  * @group Geometries
  */
-type GeometryFillConfig = {
+export type GeometryFillConfig = {
   /**
-   * Fill color: a hex string (`'#FF5733'`), a palette name (`'red'`), or a MapLibre expression
+   * Fill color: a hex string (`'#FF5733'`), a palette name (`'blues'`, see {@link colorPaletteIDs}), or a MapLibre expression
    * for data-driven styling (e.g. `['get', 'color']`).
    *
    * @default '#0A3653'
@@ -4573,7 +4922,7 @@ type GeometryFillConfig = {
  *
  * @group Geometries
  */
-type GeometryTextConfig = {
+export type GeometryTextConfig = {
   /**
    * Text content to display as label.
    *
@@ -4619,7 +4968,7 @@ type GeometryTextConfig = {
  *
  * @group Geometries
  */
-type GeometryLineConfig = {
+export type GeometryLineConfig = {
   /**
    * Border/outline color: a hex string or a MapLibre expression (e.g. `['get', 'borderColor']`).
    *
@@ -4692,7 +5041,7 @@ type GeometryLineConfig = {
  *
  * @group Geometries
  */
-type GeometryLineLabelConfig = {
+export type GeometryLineLabelConfig = {
   /**
    * Minimum zoom level at which border labels are visible.
    *
@@ -4810,7 +5159,7 @@ type GeometryLineLabelConfig = {
  *
  * @group Geometries
  */
-type GeometryBeforeLayerConfig = BeforeLayerConfig | GeometryBeforeLayerTargets;
+export type GeometryBeforeLayerConfig = BeforeLayerConfig | GeometryBeforeLayerTargets;
 /**
  * Per-layer positioning targets for the object form of {@link GeometryBeforeLayerConfig}.
  *
@@ -4820,7 +5169,7 @@ type GeometryBeforeLayerConfig = BeforeLayerConfig | GeometryBeforeLayerTargets;
  *
  * @group Geometries
  */
-type GeometryBeforeLayerTargets = {
+export type GeometryBeforeLayerTargets = {
   /** Fallback position for any layer not named by `fill` / `line`. */
   all?: BeforeLayerConfig;
   /** Position for the fill layer. */
@@ -4868,7 +5217,7 @@ type GeometryBeforeLayerTargets = {
  *
  * @group Geometries
  */
-type GeometriesModuleConfig = MapModuleCommonConfig & {
+export type GeometriesModuleConfig = MapModuleCommonConfig & {
   /**
    * Fill color, opacity, and (optional) fill-layer positioning.
    *
@@ -4925,7 +5274,7 @@ type GeometriesModuleConfig = MapModuleCommonConfig & {
    * @example
    * ```typescript
    * // Show the "rest of the world" outside a country
-   * const module = await GeometriesModule.get(map, {
+   * const module = await GeometriesModule.create(map, {
    *     theme: 'inverted',
    *     fill: { color: 'black', opacity: 0.5 }
    * });
@@ -4970,6 +5319,18 @@ type GeometrySourcesWithLayers = {
   geometry: GeoJSONSourceWithLayers<PolygonFeatures>;
   geometryLabel: GeoJSONSourceWithLayers<FeatureCollection<Point>>;
 };
+/**
+ * Event surface of {@link GeometriesModule}: the module's own events, plus one named scope per
+ * surface it manages.
+ *
+ * @group Geometries
+ */
+export type GeometriesEvents = CombinedEvents<MapGeoJSONFeature, GeometriesModuleConfig, PolygonFeatures> & {
+  /** The geometry fills and outlines. */
+  geometry: UserEvents<MapGeoJSONFeature>;
+  /** The labels rendered on top of the geometries. */
+  geometryLabel: UserEvents<MapGeoJSONFeature>;
+};
 /**
  * Geometries Module for displaying polygon areas with custom styling on the map.
  *
@@ -5003,7 +5364,7 @@ type GeometrySourcesWithLayers = {
  * import { GeometriesModule } from '@tomtom-org/maps-sdk/map';
  *
  * // Initialize module
- * const geometriesModule = await GeometriesModule.get(map);
+ * const geometriesModule = await GeometriesModule.create(map);
  *
  * // Display a polygon
  * await geometriesModule.show({
@@ -5021,7 +5382,7 @@ type GeometrySourcesWithLayers = {
  * @example
  * Custom styling:
  * ```typescript
- * const geometriesModule = await GeometriesModule.get(map, {
+ * const geometriesModule = await GeometriesModule.create(map, {
  *   fill: { color: '#FF5733', opacity: 0.3 },
  *   line: { color: '#C70039', width: 3 },
  *   textConfig: {
@@ -5069,7 +5430,7 @@ type GeometrySourcesWithLayers = {
  *
  * @group Geometries
  */
-declare class GeometriesModule extends AbstractMapModule<GeometrySourcesWithLayers, GeometriesModuleConfig> {
+export declare class GeometriesModule extends AbstractMapModule<GeometrySourcesWithLayers, GeometriesModuleConfig> {
   private titleLayerSpecs;
   private geometryFillLayerSpecs;
   private geometryOutlineLayerSpecs;
@@ -5096,19 +5457,20 @@ declare class GeometriesModule extends AbstractMapModule<GeometrySourcesWithLaye
    * - `beforeLayerConfig`: Layer ordering — a single target, or `{ all, fill, line }` to split them
    *
    * **Multiple Instances:**
-   * You can create multiple GeometriesModule instances on the same map,
-   * each managing different sets of geometries with different styles.
+   * `GeometriesModule` owns the sources, layers and images it adds, all suffixed per instance.
+   * Every call therefore returns a **new, independent** instance, so you can put several on the
+   * same map, each managing a different set of geometries with different styles.
    *
    * @example
    * Default initialization:
    * ```typescript
-   * const geometriesModule = await GeometriesModule.get(map);
+   * const geometriesModule = await GeometriesModule.create(map);
    * ```
    *
    * @example
    * With custom styling:
    * ```typescript
-   * const geometriesModule = await GeometriesModule.get(map, {
+   * const geometriesModule = await GeometriesModule.create(map, {
    *   fill: { color: 'blue', opacity: 0.25 },
    *   line: { color: 'darkblue', width: 2, opacity: 0.8 },
    *   textConfig: {
@@ -5121,7 +5483,7 @@ declare class GeometriesModule extends AbstractMapModule<GeometrySourcesWithLaye
    * @example
    * Data-driven styling:
    * ```typescript
-   * const geometriesModule = await GeometriesModule.get(map, {
+   * const geometriesModule = await GeometriesModule.create(map, {
    *   fill: {
    *     // Color based on feature properties
    *     color: [
@@ -5137,7 +5499,7 @@ declare class GeometriesModule extends AbstractMapModule<GeometrySourcesWithLaye
    * });
    * ```
    */
-  static get(tomtomMap: TomTomMap, config?: GeometriesModuleConfig): Promise<GeometriesModule>;
+  static create(tomtomMap: TomTomMap, config?: GeometriesModuleConfig): Promise<GeometriesModule>;
   private constructor();
   /**
    * @ignore
@@ -5314,7 +5676,7 @@ declare class GeometriesModule extends AbstractMapModule<GeometrySourcesWithLaye
   /**
    * Gets the events interface for handling user interactions with geometries.
    *
-   * @returns A `UserEvents` instance for registering event handlers.
+   * @returns The module's events, with `on` / `off` for handlers and `where` for scoping.
    *
    * @remarks
    * **Supported Events:**
@@ -5356,12 +5718,12 @@ declare class GeometriesModule extends AbstractMapModule<GeometrySourcesWithLaye
    * });
    * ```
    */
-  get events(): CombinedEvents<import('maplibre-gl').MapGeoJSONFeature, GeometriesModuleConfig, PolygonFeatures>;
+  get events(): GeometriesEvents;
 }
 //#endregion
 //#region src/geometry/prepareReachableRangesForDisplay.d.ts
 /** Custom label generator for reachable range features. */
-type ReachableRangeLabelFn = (feature: PolygonFeature, index: number) => string;
+export type ReachableRangeLabelFn = (feature: PolygonFeature, index: number) => string;
 /**
  * Attaches labels and applies theme-specific geometry to reachable range polygon features.
  *
@@ -5385,7 +5747,7 @@ type ReachableRangeLabelFn = (feature: PolygonFeature, index: number) => string;
  *
  * @group Geometries
  */
-declare const buildReachableRangeFeatures: (features: PolygonFeature[], labels: string[], theme?: GeometryTheme) => PolygonFeature[];
+export declare const buildReachableRangeFeatures: (features: PolygonFeature[], labels: string[], theme?: GeometryTheme) => PolygonFeature[];
 /**
  * Prepares the output of `calculateReachableRanges` for display with {@link GeometriesModule}.
  *
@@ -5410,7 +5772,7 @@ declare const buildReachableRangeFeatures: (features: PolygonFeature[], labels:
  *
  * @group Geometries
  */
-declare const prepareReachableRangesForDisplay: (result: PolygonFeatures, theme?: GeometryTheme, label?: ReachableRangeLabelFn) => PolygonFeatures;
+export declare const prepareReachableRangesForDisplay: (result: PolygonFeatures, theme?: GeometryTheme, label?: ReachableRangeLabelFn) => PolygonFeatures;
 //#endregion
 //#region src/geometry/geometryConfigs.d.ts
 /**
@@ -5427,7 +5789,7 @@ declare const prepareReachableRangesForDisplay: (result: PolygonFeatures, theme?
  *
  * @group Geometries
  */
-declare const themedGeometryConfig: (palette?: ColorPaletteOptions, beforeLayerConfig?: GeometryBeforeLayerConfig) => GeometriesModuleConfig;
+export declare const themedGeometryConfig: (palette?: ColorPaletteOptions, beforeLayerConfig?: GeometryBeforeLayerConfig) => GeometriesModuleConfig;
 /**
  * Returns a {@link GeometriesModuleConfig} for reachable ranges.
  *
@@ -5442,14 +5804,14 @@ declare const themedGeometryConfig: (palette?: ColorPaletteOptions, beforeLayerC
  *
  * @example
  * ```typescript
- * const module = await GeometriesModule.get(map, reachableRangeGeometryConfig());
+ * const module = await GeometriesModule.create(map, reachableRangeGeometryConfig());
  * const result = await calculateReachableRanges([...]);
  * module.show(result); // labels and theme applied automatically
  * ```
  *
  * @group Geometries
  */
-declare const reachableRangeGeometryConfig: (palette?: ColorPaletteOptions, theme?: GeometryTheme, beforeLayerConfig?: GeometryBeforeLayerConfig, label?: ReachableRangeLabelFn) => GeometriesModuleConfig;
+export declare const reachableRangeGeometryConfig: (palette?: ColorPaletteOptions, theme?: GeometryTheme, beforeLayerConfig?: GeometryBeforeLayerConfig, label?: ReachableRangeLabelFn) => GeometriesModuleConfig;
 //#endregion
 //#region src/geometry/types/geometryDisplayProps.d.ts
 /**
@@ -5486,7 +5848,7 @@ declare const reachableRangeGeometryConfig: (palette?: ColorPaletteOptions, them
  *
  * @group Geometries
  */
-type ExtraGeometryDisplayProps = {
+export type ExtraGeometryDisplayProps = {
   /**
    * Display title for the geometry.
    *
@@ -5562,7 +5924,7 @@ type ExtraGeometryDisplayProps = {
  *
  * @group Geometries
  */
-type DisplayGeometryProps = CommonPlaceProps & ExtraGeometryDisplayProps;
+export type DisplayGeometryProps = CommonPlaceProps & ExtraGeometryDisplayProps;
 //#endregion
 //#region src/hillshade/HillshadeModule.d.ts
 /**
@@ -5612,7 +5974,7 @@ type HillshadeSourcesWithLayers = {
  *
  * @group Hillshade
  */
-declare class HillshadeModule extends AbstractMapModule<HillshadeSourcesWithLayers, HillshadeModuleConfig> {
+export declare class HillshadeModule extends AbstractMapModule<HillshadeSourcesWithLayers, HillshadeModuleConfig> {
   /**
    * Retrieves a HillshadeModule instance for the given map.
    *
@@ -5653,6 +6015,12 @@ declare class HillshadeModule extends AbstractMapModule<HillshadeSourcesWithLaye
    *   visible: false
    * });
    * ```
+   *
+   * @remarks
+   * **Instances:**
+   * `HillshadeModule` controls the hillshade source and layers the map style already provides,
+   * under fixed global IDs. Every instance is another handle on that same shared state, so
+   * visibility applied through one is visible through all of them.
    */
   static get(map: TomTomMap, config?: HillshadeModuleConfig): Promise<HillshadeModule>;
   private constructor();
@@ -5764,7 +6132,7 @@ type HillshadeModuleConfig = MapModuleCommonConfig & {
  * POI category mappings that have a direct equivalent in Map Display POI categories.
  * @ignore
  */
-declare const mapDisplayPoiCategoryMappings: Partial<Record<POICategory, string>>;
+export declare const mapDisplayPoiCategoryMappings: Partial<Record<POICategory, string>>;
 /**
  * Map style POI category type.
  *
@@ -5784,11 +6152,11 @@ declare const mapDisplayPoiCategoryMappings: Partial<Record<POICategory, string>
  *
  * @group POIs
  */
-type MapStylePOICategory = keyof typeof mapDisplayPoiCategoryMappings;
+export type MapStylePOICategory = keyof typeof mapDisplayPoiCategoryMappings;
 /**
  * @ignore
  */
-declare const toBaseMapPOICategory: (category: POICategory) => string;
+export declare const toBaseMapPOICategory: (category: POICategory) => string;
 /**
  * The deduplicated set of base-map POI categories — the right-hand side of
  * {@link completeMapDisplayPoiCategoryMappings}. Each value names the
@@ -5799,11 +6167,11 @@ declare const toBaseMapPOICategory: (category: POICategory) => string;
  *
  * @ignore
  */
-declare const baseMapPOICategoryValues: readonly string[];
+export declare const baseMapPOICategoryValues: readonly string[];
 /**
  * @ignore
  */
-declare const toBaseMapPOIGroup: (category: POICategory) => string | undefined;
+export declare const toBaseMapPOIGroup: (category: POICategory) => string | undefined;
 //#endregion
 //#region src/places/types/placeDisplayProps.d.ts
 /**
@@ -5844,7 +6212,7 @@ declare const toBaseMapPOIGroup: (category: POICategory) => string | undefined;
  *
  * @group Places
  */
-type PlaceDisplayProps = {
+export type PlaceDisplayProps = {
   /**
    * Unique identifier for the place feature.
    *
@@ -5954,7 +6322,7 @@ type PlaceDisplayProps = {
  *
  * @group Places
  */
-type DisplayPlaceProps = CommonPlaceProps & PlaceDisplayProps;
+export type DisplayPlaceProps = CommonPlaceProps & PlaceDisplayProps;
 //#endregion
 //#region src/places/types/placesModuleConfig.d.ts
 /**
@@ -5973,7 +6341,13 @@ type DisplayPlaceProps = CommonPlaceProps & PlaceDisplayProps;
  *
  * @group Places
  */
-type PlacesTheme = 'pin' | 'circle-icon' | 'base-map' | 'pin-clustered';
+type PlacesTheme = (typeof placesThemes)[number];
+/**
+ * All valid {@link PlacesTheme} values.
+ *
+ * @group Places
+ */
+export declare const placesThemes: readonly ["pin", "circle-icon", "base-map", "pin-clustered"];
 /**
  * Configuration for EV charging station availability display.
  *
@@ -5989,14 +6363,14 @@ type PlacesTheme = 'pin' | 'circle-icon' | 'base-map' | 'pin-clustered';
  * @example
  * ```typescript
  * // Enable with defaults
- * const places = await PlacesModule.get(map, {
+ * const places = await PlacesModule.create(map, {
  *   evAvailability: { enabled: true }
  * });
  * const stations = await search({ poiCategories: ['ELECTRIC_VEHICLE_STATION'] });
  * places.show(await getPlacesWithEVAvailability(stations));
  *
  * // Custom threshold and format
- * const places = await PlacesModule.get(map, {
+ * const places = await PlacesModule.create(map, {
  *   evAvailability: {
  *     enabled: true,
  *     threshold: 0.5,
@@ -6005,7 +6379,7 @@ type PlacesTheme = 'pin' | 'circle-icon' | 'base-map' | 'pin-clustered';
  * });
  *
  * // Combine with custom icon
- * const places = await PlacesModule.get(map, {
+ * const places = await PlacesModule.create(map, {
  *   icon: {
  *     categoryIcons: [{
  *       id: 'ELECTRIC_VEHICLE_STATION',
@@ -6675,7 +7049,119 @@ type PlacesSourcesAndLayers = {
    */
   connections: GeoJSONSourceWithLayers<ConnectionFeatureCollection>;
 };
-declare class PlacesModule extends AbstractMapModule<PlacesSourcesAndLayers, PlacesModuleConfig> {
+/**
+ * What {@link PlacesModule.show} accepts, and what `shown-features` handlers receive back.
+ *
+ * @group Places
+ */
+export type ShownPlaces = Place | Place[] | Places;
+/**
+ * What `places.events.on('shown-features', ...)` receives: whichever of places or connections was
+ * just rendered.
+ *
+ * @group Places
+ */
+export type PlacesShownFeatures = {
+  places: ShownPlaces;
+} | {
+  connections: PlaceConnectionDisplay[];
+};
+/**
+ * Event surface of {@link PlacesModule}: the module's own events, plus one named scope per
+ * surface it manages.
+ *
+ * @group Places
+ */
+export type PlacesEvents = CombinedEvents<MapGeoJSONFeature, PlacesModuleConfig, PlacesShownFeatures> & {
+  /** The place pins themselves, clustered or not. */
+  places: UserEvents<Place<DisplayPlaceProps>>;
+  /** The lines and labels connecting places to their parent, when connections are shown. */
+  connections: UserEvents<MapGeoJSONFeature>;
+};
+/**
+ * Map module for displaying and managing place markers.
+ *
+ * The PlacesModule provides functionality to display location markers (pins) on the map
+ * for points of interest, search results, or custom locations. It supports various marker
+ * styles, custom icons, text labels, and interactive events.
+ *
+ * @remarks
+ * **Features:**
+ * - Multiple marker styles (pin, circle-icon, base-map POI-like)
+ * - Custom icons per POI category
+ * - Text labels with styling options
+ * - Data-driven styling via MapLibre expressions
+ * - Interactive events (click, hover, etc.)
+ * - Support for custom feature properties
+ * - EV charging station availability display (opt-in)
+ *
+ * **Marker Styles:**
+ * - `pin`: Traditional teardrop-shaped map pins
+ * - `circle-icon`: Simple circular markers (previously named `circle`)
+ * - `base-map`: Mimics the map's built-in POI layer styling (combines `main`, `selected`, and `micro` layers). For micro-only rendering, hide the `main` layer via `layers.main.layout.visibility = 'none'`.
+ *
+ * **EV Charging Station Availability:**
+ * When displaying EV charging stations with availability data from
+ * {@link getPlacesWithEVAvailability}, the module can:
+ * - Show available/total charging points (e.g., "3/10")
+ * - Color-code availability (green = good, orange = limited, red = none/low)
+ * - Display as formatted text within the station's label
+ *
+ * This feature is disabled by default. To enable it, set `evAvailability.enabled` to `true`
+ * in the configuration.
+ *
+ * **Common Use Cases:**
+ * - Search result visualization
+ * - Custom location markers
+ * - Store locators
+ * - EV charging station maps with real-time availability
+ * - Delivery/pickup points
+ * - Saved locations display
+ *
+ * @example
+ * ```typescript
+ * // Create places module with pin markers
+ * const placesModule = await PlacesModule.create(map, {
+ *   icon: {
+ *     categoryIcons: []
+ *   },
+ *   text: {
+ *     field: (place) => place.properties.poi?.name || 'Unknown'
+ *   },
+ *   theme: 'pin'
+ * });
+ *
+ * // Display places from search
+ * await placesModule.show(searchResults);
+ *
+ * // EV Charging Stations - Opt-in to availability display
+ * const evStations = await PlacesModule.create(map, {
+ *   evAvailability: { enabled: true }
+ * });
+ * const results = await search({ poiCategories: ['ELECTRIC_VEHICLE_STATION'] });
+ * evStations.show(await getPlacesWithEVAvailability(results)); // Shows availability
+ *
+ * // Granular control: Enable for searched stations only, background stations without
+ * const bgStations = await PlacesModule.create(map); // EV availability disabled
+ * const searched = await PlacesModule.create(map, {
+ *   evAvailability: { enabled: true }
+ * });
+ *
+ * // Handle clicks
+ * placesModule.events.on('click', (feature) => {
+ *   console.log('Clicked:', feature.properties);
+ * });
+ *
+ * placesModule.events.on('hover', (feature) => {
+ *   showTooltip(feature.properties.poi?.name);
+ * });
+ * ```
+ *
+ * @see [Places Guide](https://docs.tomtom.com/maps-sdk-js/guides/map/places)
+ *
+ * @group Places
+ */
+export declare class PlacesModule extends AbstractMapModule<PlacesSourcesAndLayers, PlacesModuleConfig> {
   private layerSpecs;
   private connectionLayerSpecs;
   private currentClusterMode;
@@ -6687,12 +7173,17 @@ declare class PlacesModule extends AbstractMapModule<PlacesSourcesAndLayers, Pla
   private shownConnections;
   private readonly shownFeaturesHandlers;
   /**
-   * Make sure the map is ready before create an instance of the module and any other interaction with the map
+   * Creates a new module instance on the given map, waiting until the map is ready first.
+   *
+   * `PlacesModule` owns the sources, layers and images it adds, all suffixed per instance. Every
+   * call therefore returns a **new, independent** instance, and stacking several of them on one
+   * map is a supported thing to do.
+   *
    * @param tomtomMap The TomTomMap instance.
    * @param config  The module optional configuration
    * @returns {Promise} Returns a promise with a new instance of this module
    */
-  static get(tomtomMap: TomTomMap, config?: PlacesModuleConfig): Promise<PlacesModule>;
+  static create(tomtomMap: TomTomMap, config?: PlacesModuleConfig): Promise<PlacesModule>;
   private constructor();
   /**
    * @ignore
@@ -6855,7 +7346,7 @@ declare class PlacesModule extends AbstractMapModule<PlacesSourcesAndLayers, Pla
    * await placesModule.show([place1, place2, place3]);
    * ```
    */
-  show(places: Place | Place[] | Places): Promise<void>;
+  show(places: ShownPlaces): Promise<void>;
   /**
    * Removes all places from the map.
    *
@@ -6890,7 +7381,7 @@ declare class PlacesModule extends AbstractMapModule<PlacesSourcesAndLayers, Pla
    *
    * @example
    * ```typescript
-   * const places = await PlacesModule.get(map, {
+   * const places = await PlacesModule.create(map, {
    *   connections: {
    *     label: (c) => `${c.distanceMeters} m`
    *   }
@@ -6979,7 +7470,7 @@ declare class PlacesModule extends AbstractMapModule<PlacesSourcesAndLayers, Pla
    * ```
    */
   cleanEventStates(options?: CleanEventStatesOptions): void;
-  get events(): CombinedEvents<Place<DisplayPlaceProps>, PlacesModuleConfig, Place | Place[] | Places>;
+  get events(): PlacesEvents;
 }
 //#endregion
 //#region src/places/utils/preparePlacesForDisplay.d.ts
@@ -6988,40 +7479,40 @@ declare class PlacesModule extends AbstractMapModule<PlacesSourcesAndLayers, Pla
  * @param place The place to display.
  * @ignore
  */
-declare const buildPlaceTitle: (place: Place) => string;
+export declare const buildPlaceTitle: (place: Place) => string;
 /**
  * Gets the map style sprite image ID to display on the map for the give place.
  * @ignore
  */
-declare const getIconIDForPlace: (place: Place, instanceIndex: number, config?: PlacesModuleConfig) => string;
+export declare const getIconIDForPlace: (place: Place, instanceIndex: number, config?: PlacesModuleConfig) => string;
 /**
  * Maps a Place category to the poi layer one, so the latter's style can apply it.
  * @ignore
  */
-declare const getPOILayerCategoryForPlace: (place: Place, config?: PlacesModuleConfig) => string | undefined;
+export declare const getPOILayerCategoryForPlace: (place: Place, config?: PlacesModuleConfig) => string | undefined;
 /**
  * Maps a Place to the base map POI group used by the style's `text-color` and
  * `POI - Micro` icon expressions (e.g., `eat_and_drink`, `lodging`, `driving`).
  * @ignore
  */
-declare const getPOIGroupForPlace: (place: Place, config?: PlacesModuleConfig) => string | undefined;
+export declare const getPOIGroupForPlace: (place: Place, config?: PlacesModuleConfig) => string | undefined;
 /**
  * Transforms the input of a "show" call to FeatureCollection "Places".
  * @ignore
  */
-declare const toPlaces: (places: Place | Place[] | Places) => Places;
+export declare const toPlaces: (places: Place | Place[] | Places) => Places;
 /**
  * prepare places features to be displayed on map by adding needed  properties for title, icon and style
  * @ignore
  */
-declare const preparePlacesForDisplay: (placesInput: Place | Place[] | Places, instanceIndex: number, config?: PlacesModuleConfig) => Places<DisplayPlaceProps>;
+export declare const preparePlacesForDisplay: (placesInput: Place | Place[] | Places, instanceIndex: number, config?: PlacesModuleConfig) => Places<DisplayPlaceProps>;
 //#endregion
 //#region src/pois/layers/poisLayers.d.ts
 /**
  * Layer IDs for POIs on the map.
  * @ignore
  */
-declare const poiLayerIDs: string[];
+export declare const poiLayerIDs: string[];
 //#endregion
 //#region src/pois/types/poiCategoryGroups.d.ts
 /**
@@ -7073,7 +7564,7 @@ declare const poiLayerIDs: string[];
  *
  * @group POIs
  */
-declare const poiCategoryGroups: Record<string, MapStylePOICategory[]>;
+export declare const poiCategoryGroups: Record<string, MapStylePOICategory[]>;
 /**
  * POI category group type.
  *
@@ -7140,7 +7631,7 @@ declare const poiCategoryGroups: Record<string, MapStylePOICategory[]>;
  *
  * @group POIs
  */
-type POICategoryGroup = keyof typeof poiCategoryGroups;
+export type POICategoryGroup = keyof typeof poiCategoryGroups;
 //#endregion
 //#region src/pois/types/poisModuleConfig.d.ts
 /**
@@ -7347,7 +7838,7 @@ type POIsModuleFeature = Feature<Point, {
  * @param categories list of filtered categories.
  * @ignore
  */
-declare const getStyleCategories: (categories: FilterablePOICategory[]) => string[];
+export declare const getStyleCategories: (categories: FilterablePOICategory[]) => string[];
 /**
  * IDs of sources and layers for places of interest module.
  */
@@ -7438,7 +7929,7 @@ type PoIsSourcesAndLayers = {
  *
  * @group POIs
  */
-declare class POIsModule extends AbstractMapModule<PoIsSourcesAndLayers, POIsModuleConfig> {
+export declare class POIsModule extends AbstractMapModule<PoIsSourcesAndLayers, POIsModuleConfig> {
   private categoriesFilter?;
   private originalFilter?;
   /**
@@ -7475,6 +7966,12 @@ declare class POIsModule extends AbstractMapModule<PoIsSourcesAndLayers, POIsMod
    *   }
    * });
    * ```
+   *
+   * @remarks
+   * **Instances:**
+   * `POIsModule` controls the POI sources and layers the map style already provides, under fixed
+   * global IDs. Every instance is another handle on that same shared state, so visibility and
+   * filters applied through one are visible through all of them.
    */
   static get(map: TomTomMap, config?: POIsModuleConfig): Promise<POIsModule>;
   private constructor();
@@ -7593,7 +8090,7 @@ declare class POIsModule extends AbstractMapModule<PoIsSourcesAndLayers, POIsMod
   /**
    * Gets the events interface for handling user interactions with POIs.
    *
-   * @returns A `UserEvents` instance for registering event handlers.
+   * @returns The module's events, with `on` / `off` for handlers and `where` for scoping.
    *
    * @remarks
    * **Supported Events:**
@@ -8215,7 +8712,7 @@ type RoutingModuleConfig = MapModuleCommonConfig & {
  * @param instanceIndex - Optional instance index for image ID suffixes.
  * @ignore
  */
-declare const buildRoutingLayers: (config?: RoutingModuleConfig, layerIDPrefix?: string, instanceIndex?: number) => Required<RouteLayersConfig>;
+export declare const buildRoutingLayers: (config?: RoutingModuleConfig, layerIDPrefix?: string, instanceIndex?: number) => Required<RouteLayersConfig>;
 /**
  * Default routing layers configuration. Calls routingLayers with no parameters.
  *
@@ -8237,38 +8734,38 @@ declare const buildRoutingLayers: (config?: RoutingModuleConfig, layerIDPrefix?:
  *
  * @group Routing
  */
-declare const defaultRoutingLayers: Required<RouteLayersConfig>;
+export declare const defaultRoutingLayers: Required<RouteLayersConfig>;
 //#endregion
 //#region src/routing/layers/shared.d.ts
 /**
  * Main route line foreground color.
  * @ignore
  */
-declare const ROUTE_LINE_FOREGROUND_COLOR = "#36A8F0";
+export declare const ROUTE_LINE_FOREGROUND_COLOR = "#36A8F0";
 /**
  * Main route outline color.
  * @ignore
  */
-declare const ROUTE_LINE_OUTLINE_COLOR = "#105287";
+export declare const ROUTE_LINE_OUTLINE_COLOR = "#105287";
 /**
  * Deselected route line foreground color.
  * @ignore
  */
-declare const DESELECTED_FOREGROUND_COLOR = "#ABAFB3";
+export declare const DESELECTED_FOREGROUND_COLOR = "#ABAFB3";
 /**
  * Deselected route line outline color.
  * @ignore
  */
-declare const DESELECTED_OUTLINE_COLOR = "#3C4956";
+export declare const DESELECTED_OUTLINE_COLOR = "#3C4956";
 /**
  * @ignore
  */
-declare const DESELECTED_SECONDARY_COLOR = "#727C85";
+export declare const DESELECTED_SECONDARY_COLOR = "#727C85";
 /**
  * Main route line width based on zoom level.
  * @ignore
  */
-declare const ROUTE_LINE_FOREGROUND_WIDTH: ExpressionSpecification;
+export declare const ROUTE_LINE_FOREGROUND_WIDTH: ExpressionSpecification;
 /**
  * Used for showing/hiding layer depending on layer being part of selected route or not.
  *
@@ -8279,7 +8776,7 @@ declare const ROUTE_LINE_FOREGROUND_WIDTH: ExpressionSpecification;
  * filter: SELECTED_ROUTE_FILTER
  * @group Routing
  */
-declare const SELECTED_ROUTE_FILTER: ExpressionSpecification;
+export declare const SELECTED_ROUTE_FILTER: ExpressionSpecification;
 /**
  * Used for showing/hiding layer depending on layer being part of deselected route or not.
  *
@@ -8290,76 +8787,76 @@ declare const SELECTED_ROUTE_FILTER: ExpressionSpecification;
  * filter: DESELECTED_ROUTE_FILTER
  * @group Routing
  */
-declare const DESELECTED_ROUTE_FILTER: ExpressionSpecification;
+export declare const DESELECTED_ROUTE_FILTER: ExpressionSpecification;
 /**
  * Main route line outline width (medium) based on zoom level.
  * @ignore
  */
-declare const ROUTE_LINE_OUTLINE_WIDTH: ExpressionSpecification;
+export declare const ROUTE_LINE_OUTLINE_WIDTH: ExpressionSpecification;
 /**
  * Returns the foreground line width expression for the given size preset.
  * @ignore
  */
-declare const getLineForegroundWidth: (size?: RouteWidth) => ExpressionSpecification;
+export declare const getLineForegroundWidth: (size?: RouteWidth) => ExpressionSpecification;
 /**
  * Returns the outline line width expression for the given size preset.
  * @ignore
  */
-declare const getLineOutlineWidth: (size?: RouteWidth) => ExpressionSpecification;
+export declare const getLineOutlineWidth: (size?: RouteWidth) => ExpressionSpecification;
 /**
  * Returns the waypoint icon size expression for the given size preset.
  * @ignore
  */
-declare const getWaypointIconSize: (size?: RouteWaypointSize) => ExpressionSpecification;
+export declare const getWaypointIconSize: (size?: RouteWaypointSize) => ExpressionSpecification;
 /**
  * Returns the toll road outline width expression for the given size preset.
  * @ignore
  */
-declare const getTollRoadOutlineWidth: (size?: RouteWidth) => ExpressionSpecification;
+export declare const getTollRoadOutlineWidth: (size?: RouteWidth) => ExpressionSpecification;
 /**
  * Returns the instruction line width expression for the given size preset.
  * @ignore
  */
-declare const getInstructionLineWidth: (size?: RouteWidth) => ExpressionSpecification;
+export declare const getInstructionLineWidth: (size?: RouteWidth) => ExpressionSpecification;
 /**
  * Returns the instruction outline width expression for the given size preset.
  * @ignore
  */
-declare const getInstructionOutlineWidth: (size?: RouteWidth) => ExpressionSpecification;
+export declare const getInstructionOutlineWidth: (size?: RouteWidth) => ExpressionSpecification;
 /**
  * @ignore
  */
-declare const MAJOR_DELAY_COLOR = "#AD0000";
+export declare const MAJOR_DELAY_COLOR = "#AD0000";
 /**
  * @ignore
  */
-declare const MODERATE_DELAY_COLOR = "#FB2D09";
+export declare const MODERATE_DELAY_COLOR = "#FB2D09";
 /**
  * @ignore
  */
-declare const MINOR_DELAY_COLOR = "#FFC105";
+export declare const MINOR_DELAY_COLOR = "#FFC105";
 /**
  * @ignore
  */
-declare const MINOR_DELAY_LABEL_COLOR = "#f58240";
+export declare const MINOR_DELAY_LABEL_COLOR = "#f58240";
 /**
  * @ignore
  */
-declare const UNKNOWN_DELAY_COLOR = "#000000";
+export declare const UNKNOWN_DELAY_COLOR = "#000000";
 /**
  * @ignore
  */
-declare const UNKNOWN_DELAY_BG_COLOR = "#C7D2D8";
+export declare const UNKNOWN_DELAY_BG_COLOR = "#C7D2D8";
 /**
  * Dashed-line color for `magnitudeOfDelay === 'unknown'` (rendered as a red dashed overlay).
  * @ignore
  */
-declare const UNKNOWN_DELAY_DASH_COLOR = "rgba(190, 39, 27, 1)";
+export declare const UNKNOWN_DELAY_DASH_COLOR = "rgba(190, 39, 27, 1)";
 /**
  * Dashed-line color for `magnitudeOfDelay === 'indefinite'` (rendered as a gray dashed overlay).
  * @ignore
  */
-declare const INDEFINITE_DELAY_DASH_COLOR = "rgba(137, 150, 168, 1)";
+export declare const INDEFINITE_DELAY_DASH_COLOR = "rgba(137, 150, 168, 1)";
 //#endregion
 //#region src/routing/types/displayRoutes.d.ts
 /**
@@ -8853,19 +9350,19 @@ type PlanningWaypoint = WaypointLike | null;
 /**
  * @group Routing
  */
-declare const START_INDEX = "start";
+export declare const START_INDEX = "start";
 /**
  * @group Routing
  */
-declare const MIDDLE_INDEX = "middle";
+export declare const MIDDLE_INDEX = "middle";
 /**
  * @group Routing
  */
-declare const FINISH_INDEX = "finish";
+export declare const FINISH_INDEX = "finish";
 /**
  * @group Routing
  */
-type WaypointIndexType = typeof START_INDEX | typeof MIDDLE_INDEX | typeof FINISH_INDEX;
+export type WaypointIndexType = typeof START_INDEX | typeof MIDDLE_INDEX | typeof FINISH_INDEX;
 /**
  * Display properties for a waypoint marker on the map.
  *
@@ -8911,7 +9408,7 @@ type WaypointIndexType = typeof START_INDEX | typeof MIDDLE_INDEX | typeof FINIS
  *
  * @group Routing
  */
-type WaypointDisplayProps = PlaceDisplayProps & {
+export type WaypointDisplayProps = PlaceDisplayProps & {
   /**
    * The index of the waypoint in relation to the other waypoints.
    *
@@ -8943,8 +9440,8 @@ type WaypointDisplayProps = PlaceDisplayProps & {
    * The stop index to be displayed.
    *
    * @remarks
-   * Stops are the non-soft waypoints added between origin and destination,
-   * numbered starting from 1. Only present for middle waypoints.
+   * Stops are the waypoints between origin and destination, numbered starting from 1.
+   * Only present for middle waypoints.
    *
    * **Display Behavior:**
    * - Start waypoint: undefined
@@ -8966,11 +9463,7 @@ type WaypointDisplayProps = PlaceDisplayProps & {
 /**
  * @ignore
  */
-declare const INDEX_TYPE = "indexType";
-/**
- * @ignore
- */
-declare const STOP_DISPLAY_INDEX = "stopDisplayIndex";
+export declare const STOP_DISPLAY_INDEX = "stopDisplayIndex";
 //#endregion
 //#region src/routing/types/routingSourcesAndLayers.d.ts
 /**
@@ -9042,6 +9535,45 @@ type ShowRoutesOptions = {
 };
 //#endregion
 //#region src/routing/RoutingModule.d.ts
+/**
+ * What `routing.events.on('shown-features', ...)` receives: whichever of routes or waypoints was
+ * just rendered.
+ *
+ * @group Routing
+ */
+export type RoutingShownFeatures = {
+  routes: Route | Routes;
+} | {
+  waypoints: PlanningWaypoint[] | Waypoints;
+};
+/**
+ * Event surface of {@link RoutingModule}: the module's own events, plus one named scope per part
+ * of a route it draws.
+ *
+ * @group Routing
+ */
+export type RoutingEvents = CombinedEvents<MapGeoJSONFeature, RoutingModuleConfig, RoutingShownFeatures> & {
+  /** The route lines themselves. */
+  mainLines: UserEvents<Route<DisplayRouteProps>>;
+  /** Origin, destination and intermediate stops. */
+  waypoints: UserEvents<Waypoint<WaypointDisplayProps>>;
+  /** Charging stops along an EV route. */
+  chargingStops: UserEvents<RouteSection>;
+  /** The summary bubbles shown against each alternative. */
+  summaryBubbles: UserEvents<DisplayRouteSummary>;
+  /** Traffic incidents on the route. */
+  incidents: UserEvents<RouteSection<DisplayTrafficSectionProps>>;
+  /** Sections the vehicle is restricted from. */
+  vehicleRestricted: UserEvents<RouteSection>;
+  /** Ferry sections. */
+  ferries: UserEvents<RouteSection>;
+  /** Toll road sections. */
+  tollRoads: UserEvents<RouteSection>;
+  /** Tunnel sections. */
+  tunnels: UserEvents<RouteSection>;
+  /** The guidance instruction lines. */
+  instructionLines: UserEvents<DisplayInstruction>;
+};
 /**
  * Map module for displaying and managing route visualizations.
  *
@@ -9069,7 +9601,7 @@ type ShowRoutesOptions = {
  * @example
  * ```typescript
  * // Create the module
- * const routingModule = await RoutingModule.getInstance(map, {
+ * const routingModule = await RoutingModule.create(map, {
  *   displayUnits: {
  *     distance: { type: 'metric' }
  *   }
@@ -9095,7 +9627,7 @@ type ShowRoutesOptions = {
  *
  * @group Routing
  */
-declare class RoutingModule extends AbstractMapModule<RoutingSourcesWithLayers, RoutingModuleConfig> {
+export declare class RoutingModule extends AbstractMapModule<RoutingSourcesWithLayers, RoutingModuleConfig> {
   private layersSpecs;
   private layerIDPrefix;
   private readonly shownFeaturesHandlers;
@@ -9106,6 +9638,11 @@ declare class RoutingModule extends AbstractMapModule<RoutingSourcesWithLayers,
    * @returns {Promise} Returns a promise with a new instance of this module
    *
    * @remarks
+   * **Instances:**
+   * `RoutingModule` owns the sources, layers and images it adds, all suffixed per instance. Every
+   * call therefore returns a **new, independent** instance, and stacking several of them on one
+   * map is a supported thing to do.
+   *
    * **Configuration Options:**
    * - `displayUnits`: Distance units (metric/imperial)
    * - `waypointsSource`: Waypoint entry point options
@@ -9117,13 +9654,13 @@ declare class RoutingModule extends AbstractMapModule<RoutingSourcesWithLayers,
    * @example
    * Default initialization:
    * ```typescript
-   * const routingModule = await RoutingModule.get(map);
+   * const routingModule = await RoutingModule.create(map);
    * ```
    *
    * @example
    * With custom configuration:
    * ```typescript
-   * const routingModule = await RoutingModule.get(map, {
+   * const routingModule = await RoutingModule.create(map, {
    *   displayUnits: 'imperial',
    *   waypointsSource: {
    *     entryPoints: 'main-when-available'
@@ -9131,7 +9668,7 @@ declare class RoutingModule extends AbstractMapModule<RoutingSourcesWithLayers,
    * });
    * ```
    */
-  static get(tomtomMap: TomTomMap, config?: RoutingModuleConfig): Promise<RoutingModule>;
+  static create(tomtomMap: TomTomMap, config?: RoutingModuleConfig): Promise<RoutingModule>;
   private constructor();
   private createSourcesWithLayers;
   /**
@@ -9317,42 +9854,29 @@ declare class RoutingModule extends AbstractMapModule<RoutingSourcesWithLayers,
     summaryBubbles: DisplayRouteSummaries;
   };
   /**
-   * Unified events interface for the routing module, split into two namespaces:
+   * Unified events interface for the routing module.
    *
-   * **`events.user`** — user interaction events, keyed by source:
-   * ```typescript
-   * routing.events.user.mainLines.on('click', (route) => { ... });
-   * routing.events.user.waypoints.on('hover', (waypoint) => { ... });
-   * ```
+   * `events` itself covers every route feature and the module's lifecycle events; the named
+   * scopes below cover one part of a route each, and every one of them can be narrowed further
+   * with `where()`.
    *
-   * **`events.module`** — module lifecycle events:
    * ```typescript
-   * const unsub = routing.events.module.on('config-change', (config) => { ... });
-   * const unsub = routing.events.module.on('shown-features', (features) => {
+   * routing.events.mainLines.on('click', (route) => { ... });
+   * routing.events.waypoints.on('hover', (waypoint) => { ... });
+   *
+   * // Only the long tunnels, with their own hover cursor:
+   * routing.events.tunnels
+   *     .where((section) => section.properties.lengthInMeters > 500, { cursorOnHover: 'help' })
+   *     .on('click', showTunnel);
+   *
+   * const unsub = routing.events.on('config-change', (config) => { ... });
+   * routing.events.on('shown-features', (features) => {
    *   if ('routes' in features) { ... }
    * });
    * unsub();
    * ```
    */
-  get events(): {
-    user: {
-      mainLines: UserEvents<Route<DisplayRouteProps>>;
-      waypoints: UserEvents<Waypoint<WaypointDisplayProps>>;
-      chargingStops: UserEvents<RouteSection>;
-      summaryBubbles: UserEvents<DisplayRouteSummary>;
-      incidents: UserEvents<RouteSection<DisplayTrafficSectionProps>>;
-      vehicleRestricted: UserEvents<RouteSection>;
-      ferries: UserEvents<RouteSection>;
-      tollRoads: UserEvents<RouteSection>;
-      tunnels: UserEvents<RouteSection>;
-      instructionLines: UserEvents<DisplayInstruction>;
-    };
-    module: ModuleEvents<RoutingModuleConfig, {
-      routes: Route | Routes;
-    } | {
-      waypoints: PlanningWaypoint[] | Waypoints;
-    }>;
-  };
+  get events(): RoutingEvents;
   /**
    * Returns the map style layer under which route lines are rendered.
    * * Useful if you want to render extra layers just above the route ones but not on top of everything else.
@@ -9808,7 +10332,7 @@ type TrafficAreaAnalyticsConfig = MapModuleCommonConfig & {
  * Resolves the effective color stops for a given color configuration.
  * @ignore
  */
-declare const resolveColorStops: (colorConfig: AreaAnalyticsColorTheme | AreaAnalyticsColorStopsConfig) => AreaAnalyticsColorStop[];
+export declare const resolveColorStops: (colorConfig: AreaAnalyticsColorTheme | AreaAnalyticsColorStopsConfig) => AreaAnalyticsColorStop[];
 //#endregion
 //#region src/traffic/types/trafficAreaAnalyticsFeature.d.ts
 /**
@@ -9821,7 +10345,7 @@ declare const resolveColorStops: (colorConfig: AreaAnalyticsColorTheme | AreaAna
  *
  * @group Traffic Area Analytics
  */
-type AreaAnalyticsDisplayProperties = AreaAnalyticsMetrics & SupportsEvents & {
+export type AreaAnalyticsDisplayProperties = AreaAnalyticsMetrics & SupportsEvents & {
   /**
    * Stable feature identifier (typically the tile centre coordinates stringified
    * or the H3 cell index).
@@ -9833,7 +10357,7 @@ type AreaAnalyticsDisplayProperties = AreaAnalyticsMetrics & SupportsEvents & {
  *
  * @group Traffic Area Analytics
  */
-type AreaAnalyticsTileFeature = Feature<Point | Polygon, AreaAnalyticsDisplayProperties>;
+export type AreaAnalyticsTileFeature = Feature<Point | Polygon, AreaAnalyticsDisplayProperties>;
 //#endregion
 //#region src/traffic/TrafficAreaAnalyticsModule.d.ts
 /**
@@ -9864,7 +10388,7 @@ type AreaAnalyticsSourcesWithLayers = {
  * import { TrafficAreaAnalyticsModule } from '@tomtom-org/maps-sdk/map';
  * import { trafficAreaAnalytics } from '@tomtom-org/maps-sdk/services';
  *
- * const module = await TrafficAreaAnalyticsModule.get(map, {
+ * const module = await TrafficAreaAnalyticsModule.create(map, {
  *   displayMode: 'hexgrid-3d',
  *   metric: { active: 'congestionLevel' },
  * });
@@ -9874,7 +10398,7 @@ type AreaAnalyticsSourcesWithLayers = {
  *
  * @group Traffic Area Analytics
  */
-declare class TrafficAreaAnalyticsModule extends AbstractMapModule<AreaAnalyticsSourcesWithLayers, TrafficAreaAnalyticsConfig> {
+export declare class TrafficAreaAnalyticsModule extends AbstractMapModule<AreaAnalyticsSourcesWithLayers, TrafficAreaAnalyticsConfig> {
   private heatmapLayerSpec;
   private hexFillLayerSpec;
   private hexExtrusionLayerSpec;
@@ -9893,10 +10417,14 @@ declare class TrafficAreaAnalyticsModule extends AbstractMapModule<AreaAnalytics
    *
    * All configuration properties are optional. When `config` is omitted (or only
    * partially supplied), built-in defaults are applied for every missing field.
-   * After `get()` resolves, {@link TrafficAreaAnalyticsModule.getConfig} always returns a
+   * After `create()` resolves, {@link TrafficAreaAnalyticsModule.getConfig} always returns a
    * fully-populated configuration — there is no need to reference any default
    * values yourself.
    *
+   * `TrafficAreaAnalyticsModule` owns the sources, layers and images it adds, all suffixed per
+   * instance. Every call therefore returns a **new, independent** instance, and stacking several
+   * of them on one map is a supported thing to do.
+   *
    * @param tomtomMap - The TomTomMap instance.
    * @param config - Optional initial configuration. Omit to use all defaults.
    * @returns A promise that resolves with the initialised module.
@@ -9904,11 +10432,11 @@ declare class TrafficAreaAnalyticsModule extends AbstractMapModule<AreaAnalytics
    * @example
    * ```typescript
    * // No config needed — defaults are applied automatically.
-   * const module = await TrafficAreaAnalyticsModule.get(map);
+   * const module = await TrafficAreaAnalyticsModule.create(map);
    * await module.show(analytics);
    *
    * // Or override specific properties while keeping everything else at default:
-   * const module = await TrafficAreaAnalyticsModule.get(map, {
+   * const module = await TrafficAreaAnalyticsModule.create(map, {
    *   displayMode: 'heatmap',
    *   metricConfig: {
    *     congestionLevel: { color: 'heat' },
@@ -9916,7 +10444,7 @@ declare class TrafficAreaAnalyticsModule extends AbstractMapModule<AreaAnalytics
    * });
    * ```
    */
-  static get(tomtomMap: TomTomMap, config?: TrafficAreaAnalyticsConfig): Promise<TrafficAreaAnalyticsModule>;
+  static create(tomtomMap: TomTomMap, config?: TrafficAreaAnalyticsConfig): Promise<TrafficAreaAnalyticsModule>;
   private constructor();
   /** @ignore */
   protected _initSourcesWithLayers(config?: TrafficAreaAnalyticsConfig, _restore?: boolean): AreaAnalyticsSourcesWithLayers;
@@ -10104,7 +10632,7 @@ declare class TrafficAreaAnalyticsModule extends AbstractMapModule<AreaAnalytics
  *
  * @group Traffic
  */
-declare const roadCategories: readonly ["motorway", "motorway_link", "trunk", "trunk_link", "primary", "primary_link", "secondary", "secondary_link", "tertiary", "tertiary_link", "street", "service", "track"];
+export declare const roadCategories: readonly ["motorway", "motorway_link", "trunk", "trunk_link", "primary", "primary_link", "secondary", "secondary_link", "tertiary", "tertiary_link", "street", "service", "track"];
 /**
  * Road hierarchy category type.
  *
@@ -10124,7 +10652,7 @@ declare const roadCategories: readonly ["motorway", "motorway_link", "trunk", "t
  *
  * @group Traffic
  */
-type RoadCategory = (typeof roadCategories)[number];
+export type RoadCategory = (typeof roadCategories)[number];
 /**
  * Available street road sub-category identifiers.
  *
@@ -10133,7 +10661,7 @@ type RoadCategory = (typeof roadCategories)[number];
  *
  * @group Traffic
  */
-declare const streetRoadSubCategories: readonly ["unclassified", "residential", "living_street"];
+export declare const streetRoadSubCategories: readonly ["unclassified", "residential", "living_street"];
 /**
  * Street road sub-category type.
  *
@@ -10147,7 +10675,7 @@ declare const streetRoadSubCategories: readonly ["unclassified", "residential",
  *
  * @group Traffic
  */
-type StreetRoadSubCategory = (typeof streetRoadSubCategories)[number];
+export type StreetRoadSubCategory = (typeof streetRoadSubCategories)[number];
 /**
  * Available service road sub-category identifiers.
  *
@@ -10156,7 +10684,7 @@ type StreetRoadSubCategory = (typeof streetRoadSubCategories)[number];
  *
  * @group Traffic
  */
-declare const serviceRoadSubCategories: readonly ["parking", "driveway", "alley"];
+export declare const serviceRoadSubCategories: readonly ["parking", "driveway", "alley"];
 /**
  * Service road sub-category type.
  *
@@ -10170,7 +10698,7 @@ declare const serviceRoadSubCategories: readonly ["parking", "driveway", "alley"
  *
  * @group Traffic
  */
-type ServiceRoadSubCategory = (typeof serviceRoadSubCategories)[number];
+export type ServiceRoadSubCategory = (typeof serviceRoadSubCategories)[number];
 /**
  * Road sub-category type.
  *
@@ -10179,7 +10707,7 @@ type ServiceRoadSubCategory = (typeof serviceRoadSubCategories)[number];
  *
  * @group Traffic
  */
-type RoadSubCategory = StreetRoadSubCategory | ServiceRoadSubCategory;
+export type RoadSubCategory = StreetRoadSubCategory | ServiceRoadSubCategory;
 /**
  * Common filter configuration shared between traffic incidents and flow visualization.
  *
@@ -10188,7 +10716,7 @@ type RoadSubCategory = StreetRoadSubCategory | ServiceRoadSubCategory;
  *
  * @group Traffic
  */
-type TrafficCommonFilter = {
+export type TrafficCommonFilter = {
   /**
    * Filters traffic data by road hierarchy categories.
    *
@@ -10229,7 +10757,7 @@ type TrafficCommonFilter = {
  *
  * @group Traffic Flow
  */
-type TrafficFlowFilter = TrafficCommonFilter & {
+export type TrafficFlowFilter = TrafficCommonFilter & {
   /**
    * Controls road closure display in the traffic flow layer.
    *
@@ -10267,7 +10795,7 @@ type TrafficFlowFilter = TrafficCommonFilter & {
  *
  * @group Traffic Flow
  */
-type TrafficFlowFilters = {
+export type TrafficFlowFilters = {
   /**
    * Array of flow filters combined with OR logic.
    *
@@ -10285,7 +10813,7 @@ type TrafficFlowFilters = {
  *
  * @group Traffic Flow
  */
-type FlowConfig = MapModuleCommonConfig & {
+export type FlowConfig = MapModuleCommonConfig & {
   /**
    * Controls the visibility of the traffic flow layers.
    *
@@ -10309,7 +10837,7 @@ type FlowConfig = MapModuleCommonConfig & {
  *
  * @group Traffic Flow
  */
-type TrafficFlowModuleFeature = Feature<LineString, {
+export type TrafficFlowModuleFeature = Feature<LineString, {
   /**
    * Road hierarchy category type.
    */
@@ -10429,7 +10957,7 @@ type TrafficFlowSourcesWithLayers = {
  *
  * @group Traffic Flow
  */
-declare class TrafficFlowModule extends AbstractMapModule<TrafficFlowSourcesWithLayers, FlowConfig> {
+export declare class TrafficFlowModule extends AbstractMapModule<TrafficFlowSourcesWithLayers, FlowConfig> {
   private originalFilters;
   /**
    * Retrieves a TrafficFlowModule instance for the given map.
@@ -10471,6 +10999,12 @@ declare class TrafficFlowModule extends AbstractMapModule<TrafficFlowSourcesWith
    *   }
    * });
    * ```
+   *
+   * @remarks
+   * **Instances:**
+   * `TrafficFlowModule` controls the traffic-flow source and layers the map style already
+   * provides, under fixed global IDs. Every instance is another handle on that same shared state,
+   * so visibility and filters applied through one are visible through all of them.
    */
   static get(map: TomTomMap, config?: FlowConfig): Promise<TrafficFlowModule>;
   private constructor();
@@ -10745,7 +11279,7 @@ type Sources = {
  *
  * const map = new TomTomMap({ mapLibre: { container: 'map', center: [4.9, 52.37], zoom: 13 } });
  *
- * const overlay = await TrafficIncidentOverlayModule.get(map);
+ * const overlay = await TrafficIncidentOverlayModule.create(map);
  * const result = await trafficIncidentDetails({
  *     bbox: [4.85, 52.34, 4.95, 52.40],
  *     timeValidityFilter: ['present'],
@@ -10764,12 +11298,23 @@ type Sources = {
  *
  * @group Traffic
  */
-declare class TrafficIncidentOverlayModule extends AbstractMapModule<Sources, TrafficIncidentOverlayConfig> {
+export declare class TrafficIncidentOverlayModule extends AbstractMapModule<Sources, TrafficIncidentOverlayConfig> {
   private lastResult;
   private lastFeatureIds;
   private lastFocusIds;
   private readonly shownFeaturesHandlers;
-  static get(tomtomMap: TomTomMap, config?: TrafficIncidentOverlayConfig): Promise<TrafficIncidentOverlayModule>;
+  /**
+   * Creates a new module instance on the given map, waiting until the map is ready first.
+   *
+   * `TrafficIncidentOverlayModule` owns the sources, layers and images it adds, all suffixed per
+   * instance. Every call therefore returns a **new, independent** instance, and stacking several
+   * of them on one map is a supported thing to do.
+   *
+   * @param tomtomMap The TomTomMap instance.
+   * @param config The module optional configuration.
+   * @returns {Promise} Returns a promise with a new instance of this module.
+   */
+  static create(tomtomMap: TomTomMap, config?: TrafficIncidentOverlayConfig): Promise<TrafficIncidentOverlayModule>;
   private constructor();
   /** @ignore */
   protected _initSourcesWithLayers(config?: TrafficIncidentOverlayConfig, _restore?: boolean): Sources;
@@ -10834,7 +11379,7 @@ declare class TrafficIncidentOverlayModule extends AbstractMapModule<Sources, Tr
  *
  * @group Traffic Incidents
  */
-type DelayFilter = {
+export type DelayFilter = {
   /**
    * Requires incidents to have an associated delay.
    *
@@ -10872,7 +11417,7 @@ type DelayFilter = {
  *
  * @group Traffic Incidents
  */
-type TrafficIncidentsFilter = TrafficCommonFilter & {
+export type TrafficIncidentsFilter = TrafficCommonFilter & {
   /**
    * Filters incidents by category type.
    *
@@ -10943,7 +11488,7 @@ type TrafficIncidentsFilter = TrafficCommonFilter & {
  *
  * @group Traffic Incidents
  */
-type TrafficIncidentsFilters = {
+export type TrafficIncidentsFilters = {
   /**
    * Array of incident filters combined with OR logic.
    *
@@ -10961,7 +11506,7 @@ type TrafficIncidentsFilters = {
  *
  * @group Traffic Incidents
  */
-type IncidentsCommonConfig = {
+export type IncidentsCommonConfig = {
   /**
    * Controls the visibility of the traffic incident layers.
    *
@@ -10985,7 +11530,7 @@ type IncidentsCommonConfig = {
  *
  * @group Traffic Incidents
  */
-type IncidentsConfig = MapModuleCommonConfig & IncidentsCommonConfig & {
+export type IncidentsConfig = MapModuleCommonConfig & IncidentsCommonConfig & {
   /**
    * Configuration specific to incident icon display.
    *
@@ -11000,7 +11545,7 @@ type IncidentsConfig = MapModuleCommonConfig & IncidentsCommonConfig & {
 /**
  * Defines the structure of a traffic incident feature, which extends the basic GeoJSON feature with specific properties related to traffic incidents. This type is used to represent individual traffic incidents on the map, providing details such as the description of the incident, its severity, and the road category where it is occurring.
  */
-type TrafficIncidentsModuleFeature = Feature<Geometry, TrafficIncidentBaseProperties & {
+export type TrafficIncidentsModuleFeature = Feature<Geometry, TrafficIncidentBaseProperties & {
   /**
    * Description of the traffic incident, providing details about the nature of the incident.
    */
@@ -11161,7 +11706,7 @@ type TrafficIncidentsSourcesWithLayers = {
  *
  * @group Traffic Incidents
  */
-declare class TrafficIncidentsModule extends AbstractMapModule<TrafficIncidentsSourcesWithLayers, IncidentsConfig> {
+export declare class TrafficIncidentsModule extends AbstractMapModule<TrafficIncidentsSourcesWithLayers, IncidentsConfig> {
   private originalFilters;
   /**
    * Retrieves a TrafficIncidentsModule instance for the given map.
@@ -11203,6 +11748,12 @@ declare class TrafficIncidentsModule extends AbstractMapModule<TrafficIncidentsS
    *   }
    * });
    * ```
+   *
+   * @remarks
+   * **Instances:**
+   * `TrafficIncidentsModule` controls the traffic-incident source and layers the map style already
+   * provides, under fixed global IDs. Every instance is another handle on that same shared state,
+   * so visibility and filters applied through one are visible through all of them.
    */
   static get(map: TomTomMap, config?: IncidentsConfig): Promise<TrafficIncidentsModule>;
   private constructor();
@@ -11406,7 +11957,7 @@ declare class TrafficIncidentsModule extends AbstractMapModule<TrafficIncidentsS
  *
  * @group Utils
  */
-type CalculateMapCenterOptions = {
+export type CalculateMapCenterOptions = {
   /** The TomTomMap instance or MapLibre map instance */
   map: TomTomMap | Map;
   /** Array of HTML elements or DOM selector strings that are positioned over the map */
@@ -11417,7 +11968,7 @@ type CalculateMapCenterOptions = {
  *
  * @group Utils
  */
-type CalculateMapBoundsOptions = CalculateMapCenterOptions & {
+export type CalculateMapBoundsOptions = CalculateMapCenterOptions & {
   /**
    * Additional padding in pixels to apply around the UI elements or map edges. Default is 0.
    */
@@ -11428,7 +11979,7 @@ type CalculateMapBoundsOptions = CalculateMapCenterOptions & {
  *
  * @group Utils
  */
-type CalculateFittingBBoxOptions = CalculateMapBoundsOptions & {
+export type CalculateFittingBBoxOptions = CalculateMapBoundsOptions & {
   /**
    * The target bounding box [west, south, east, north] that should be contained in the unobscured area
    */
@@ -11448,7 +11999,7 @@ type CalculateFittingBBoxOptions = CalculateMapBoundsOptions & {
  *
  * @group Utils
  */
-declare const calculatePaddedBBox: (options: CalculateMapBoundsOptions) => BBox | null;
+export declare const calculatePaddedBBox: (options: CalculateMapBoundsOptions) => BBox | null;
 /**
  * Calculates the center point in lng-lat coordinates of the visible map area
  * that does not overlap with the given UI HTML elements.
@@ -11462,7 +12013,7 @@ declare const calculatePaddedBBox: (options: CalculateMapBoundsOptions) => BBox
  *
  * @group Utils
  */
-declare const calculatePaddedCenter: (options: CalculateMapCenterOptions) => Position | null;
+export declare const calculatePaddedCenter: (options: CalculateMapCenterOptions) => Position | null;
 /**
  * Calculates an expanded bounding box that, when the map is zoomed to it, ensures that the given to-be-contained bounding box
  * is visible within the area not obscured by surrounding UI elements, including optional padding.
@@ -11478,6 +12029,6 @@ declare const calculatePaddedCenter: (options: CalculateMapCenterOptions) => Pos
  *
  * @group Utils
  */
-declare const calculateFittingBBox: (options: CalculateFittingBBoxOptions) => BBox | null;
+export declare const calculateFittingBBox: (options: CalculateFittingBBoxOptions) => BBox | null;
 //#endregion
-export { type AREA_ANALYTICS_DEFAULTS, AbstractMapModule, AbstractSourceWithLayers, AddedSourceWithLayers, type AreaAnalyticsBeforeLayerConfig, type AreaAnalyticsColorStop, type AreaAnalyticsColorStopsConfig, type AreaAnalyticsColorTheme, type AreaAnalyticsDisplayMode, AreaAnalyticsDisplayProperties, type AreaAnalyticsHeightConfig, type AreaAnalyticsMetricConfig, type AreaAnalyticsMetricFilter, type AreaAnalyticsRegionPolygonConfig, AreaAnalyticsTileFeature, type AreaAnalyticsValueType, type AvailabilityLevel, BASE_MAP_SOURCE_ID, BaseMapLayerGroupName, BaseMapLayerGroups, BaseMapLayerGroupsVisibility, BaseMapModule, BaseMapModuleConfig, BaseMapModuleInitConfig, type BeforeLayerConfig, type ByIdOrIndex, type CSSCursor, CalculateFittingBBoxOptions, CalculateMapBoundsOptions, CalculateMapCenterOptions, type ChargingSpeedIconMapping, type ChargingStopIconConfig, type ChargingStopIconMapping, type ChargingStopTextConfig, type ChargingStopsConfig, type CleanEventStateOptions, type CleanEventStatesOptions, type ClickEventType, ColorPaletteOptions, CombinedEvents, CustomGeoJSONEvents, CustomGeoJSONImageData, CustomGeoJSONImageSpec, CustomGeoJSONLayerSpec, CustomGeoJSONModule, CustomGeoJSONModuleConfig, CustomGeoJSONSourceSpec, type CustomImage, CustomStyle, DESELECTED_FOREGROUND_COLOR, DESELECTED_OUTLINE_COLOR, DESELECTED_ROUTE_FILTER, DESELECTED_SECONDARY_COLOR, type DefaultPlaceIconConfig, DelayFilter, DisplayGeometryProps, DisplayPlaceProps, type DisplayRouteProps, type DisplayRouteRelatedProps, type DisplayRouteSummaries, type DisplayRouteSummary, type DisplayRouteSummaryProps, type EVAvailabilityConfig, type EventHandlerConfig, type EventHandlerCursorConfig, type EventType, EventsProxy, ExtraGeometryDisplayProps, FINISH_INDEX, type FilterShowMode, type FilterSyntaxVersion, type FilterablePOICategory, FlowConfig, GeoJSONSourceClusterOptions, GeoJSONSourceWithLayers, GeometriesModule, GeometriesModuleConfig, GeometryBeforeLayerConfig, GeometryBeforeLayerTargets, GeometryFillConfig, GeometryLineConfig, GeometryLineLabelConfig, GeometryTextConfig, GeometryTheme, HILLSHADE_SOURCE_ID, type HasAdditionalLayersConfig, type HasBeforeID, HillshadeModule, type HillshadeModuleConfig, type HoverEventType, INDEFINITE_DELAY_DASH_COLOR, INDEX_TYPE, type IncidentFocusStyle, IncidentsCommonConfig, IncidentsConfig, IndexedFeature, InternalTomTomMapParams, type LayerSpecFilter, type LayerSpecTemplate, type LayerSpecWithSource, type LightDark, MAJOR_DELAY_COLOR, MIDDLE_INDEX, MINOR_DELAY_COLOR, MINOR_DELAY_LABEL_COLOR, MODERATE_DELAY_COLOR, type MapEventsConfig, type MapFont, MapLibreOptions, type MapModuleCommonConfig, type MapStyleLayerID, MapStylePOICategory, ModuleEvents, type MultiSyntaxFilter, POICategoryGroup, POI_SOURCE_ID, POIsModule, type POIsModuleConfig, type POIsModuleFeature, type PlaceConnectionDisplay, type PlaceConnectionLayerName, type PlaceConnectionsConfig, type PlaceConnectionsLayersConfig, PlaceDisplayProps, type PlaceIconConfig, type PlaceLayerName, type PlaceLayersConfig, type PlaceTextConfig, PlacesModule, type PlacesModuleConfig, type PlacesTheme, type PlanningWaypoint, type PutEventStateOptions, ROUTE_LINE_FOREGROUND_COLOR, ROUTE_LINE_FOREGROUND_WIDTH, ROUTE_LINE_OUTLINE_COLOR, ROUTE_LINE_OUTLINE_WIDTH, ReachableRangeLabelFn, RenderedRef, RoadCategory, RoadSubCategory, type RouteLayersConfig, type RouteStateProps, type RouteTheme, type RouteWaypointSize, type RouteWidth, RoutingModule, type RoutingModuleConfig, SELECTED_ROUTE_FILTER, START_INDEX, STOP_DISPLAY_INDEX, type SVGIconStyleOptions, ServiceRoadSubCategory, ShowOptions, type SourceWithLayerIDs, type SourceWithLayers, type SourcesWithLayers, StandardStyle, StandardStyleID, StreetRoadSubCategory, StyleChangeHandler, StyleInput, StyleModule, StyleSourceWithLayers, type SupportsEvents, type SymbolLayerSpecWithoutSource, TRAFFIC_FLOW_SOURCE_ID, TRAFFIC_INCIDENTS_SOURCE_ID, type ToBeAddedLayerSpec, type ToBeAddedLayerSpecTemplate, type ToBeAddedLayerSpecWithoutSource, TomTomMap, TomTomMapParams, TomTomMapSource, type TrafficAreaAnalyticsConfig, TrafficAreaAnalyticsModule, TrafficCommonFilter, TrafficFlowFilter, TrafficFlowFilters, TrafficFlowModule, TrafficFlowModuleFeature, type TrafficIncidentOverlayConfig, TrafficIncidentOverlayModule, TrafficIncidentsFilter, TrafficIncidentsFilters, TrafficIncidentsModule, TrafficIncidentsModuleFeature, UNKNOWN_DELAY_BG_COLOR, UNKNOWN_DELAY_COLOR, UNKNOWN_DELAY_DASH_COLOR, type UserEventHandler, UserEvents, type ValuesFilter, WaypointDisplayProps, WaypointIndexType, type WaypointsConfig, baseMapLayerGroupNames, baseMapPOICategoryValues, buildPlaceTitle, buildReachableRangeFeatures, buildRoutingLayers, calculateFittingBBox, calculatePaddedBBox, calculatePaddedCenter, colorPaletteIDs, colorPalettes, defaultRoutingLayers, filterLayersBySources, findFeatureByRefId, geometryThemes, getIconIDForPlace, getInstructionLineWidth, getInstructionOutlineWidth, getLineForegroundWidth, getLineOutlineWidth, getPOIGroupForPlace, getPOILayerCategoryForPlace, getStyleCategories, getTollRoadOutlineWidth, getWaypointIconSize, mapDisplayPoiCategoryMappings, mapStyleLayerIDs, poiCategoryGroups, poiLayerIDs, preparePlacesForDisplay, prepareReachableRangesForDisplay, reachableRangeGeometryConfig, renderedRefId, resolveColorStops, roadCategories, serviceRoadSubCategories, standardStyleIDs, streetRoadSubCategories, styleModules, themedGeometryConfig, toBaseMapPOICategory, toBaseMapPOIGroup, toPlaces };
+export type { AREA_ANALYTICS_DEFAULTS, AreaAnalyticsBeforeLayerConfig, AreaAnalyticsColorStop, AreaAnalyticsColorStopsConfig, AreaAnalyticsColorTheme, AreaAnalyticsDisplayMode, AreaAnalyticsHeightConfig, AreaAnalyticsMetricConfig, AreaAnalyticsMetricFilter, AreaAnalyticsRegionPolygonConfig, AreaAnalyticsValueType, AvailabilityLevel, BeforeLayerConfig, ByIdOrIndex, CSSCursor, ChargingSpeedIconMapping, ChargingStopIconConfig, ChargingStopIconMapping, ChargingStopTextConfig, ChargingStopsConfig, CleanEventStateOptions, CleanEventStatesOptions, ClickEventType, CustomImage, DefaultPlaceIconConfig, DisplayRouteProps, DisplayRouteRelatedProps, DisplayRouteSummaries, DisplayRouteSummary, DisplayRouteSummaryProps, EVAvailabilityConfig, EventHandlerConfig, EventHandlerCursorConfig, EventType, FilterShowMode, FilterSyntaxVersion, FilterablePOICategory, HasAdditionalLayersConfig, HasBeforeID, HillshadeModuleConfig, HoverEventType, IncidentFocusStyle, LayerSpecFilter, LayerSpecTemplate, LayerSpecWithSource, LightDark, MapEventsConfig, MapFont, MapModuleCommonConfig, MapStyleLayerID, MultiSyntaxFilter, POIsModuleConfig, POIsModuleFeature, PlaceConnectionDisplay, PlaceConnectionLayerName, PlaceConnectionsConfig, PlaceConnectionsLayersConfig, PlaceIconConfig, PlaceLayerName, PlaceLayersConfig, PlaceTextConfig, PlacesModuleConfig, PlacesTheme, PlanningWaypoint, PutEventStateOptions, RouteLayersConfig, RouteStateProps, RouteTheme, RouteWaypointSize, RouteWidth, RoutingModuleConfig, SVGIconStyleOptions, SourceWithLayerIDs, SourceWithLayers, SourcesWithLayers, SupportsEvents, SymbolLayerSpecWithoutSource, ToBeAddedLayerSpec, ToBeAddedLayerSpecTemplate, ToBeAddedLayerSpecWithoutSource, TrafficAreaAnalyticsConfig, TrafficIncidentOverlayConfig, UserEventHandler, ValuesFilter, WaypointsConfig };