@tomtom-org/maps-sdk 0.59.0 → 0.60.0

package/map/dist/index.d.ts

@@ -2645,12 +2645,13 @@ export declare class TomTomMap {
  * ```typescript
  * // Routes appear below labels but above the base map
  * const routingModule = await RoutingModule.create(map);
- * // Uses mapStyleLayerIDs.lowestLabel by default
+ * // Uses mapStyleLayerIDs.lowestLabel by default; `beforeLayerConfig` moves the route lines
+ * const underRoads = await RoutingModule.create(map, { beforeLayerConfig: { mainLines: 'lowestRoadLine' } });
  * ```
  *
  * **GeometriesModule** - Configurable layer positioning for polygon areas:
  * ```typescript
- * // Default: below labels
+ * // Default: on top of the map, below the geometry titles
  * const geometriesModule = await GeometriesModule.create(map);
  *
  * // Custom: below buildings to show at ground level
@@ -2686,10 +2687,10 @@ export declare class TomTomMap {
  * - If a reference layer doesn't exist, a module repositioning its layers puts them on top of the
  *   style instead. A layer added with a `beforeID` that never appears is reported through
  *   `console.error` and skipped, since a missing anchor there is usually a typo.
- * - Both RoutingModule and GeometriesModule default to `lowestLabel` for optimal visibility
+ * - RoutingModule draws its lines below `lowestLabel` by default; GeometriesModule adds its layers on top
  *
  * @see {@link GeometryBeforeLayerConfig} for GeometriesModule layer positioning options
- * @see {@link RouteLayersConfig} for RoutingModule layer configuration
+ * @see {@link RoutingBeforeLayerConfig} for RoutingModule layer positioning options
  *
  * @group Map Style
  */
@@ -3268,6 +3269,27 @@ type MapStyleLayerID = keyof typeof mapStyleLayerIDs;
  * @group Shared
  */
 type BeforeLayerConfig = 'top' | MapStyleLayerID;
+/**
+ * Where a module's layers go in the map's layer stack: one {@link BeforeLayerConfig} for the whole
+ * module, or one per part of it.
+ *
+ * @remarks
+ * In the record form a part takes its own entry, else `all`. A part neither names stays where the
+ * module puts it by default, and a part's own layers keep their order wherever it goes.
+ *
+ * @typeParam PART - The names of the module's parts that move independently.
+ *
+ * @example
+ * ```typescript
+ * const everything: GeometryBeforeLayerConfig = 'top';
+ * const split: GeometryBeforeLayerConfig = { all: 'lowestLabel', fill: 'lowestRoadLine' };
+ * ```
+ *
+ * @group Shared
+ */
+type PartsBeforeLayerConfig<PART extends string> = BeforeLayerConfig | ({
+  all?: BeforeLayerConfig;
+} & { [P in PART]?: BeforeLayerConfig; });
 /**
  * Configuration for adding custom layers to a map module based on its controlled source data.
  *
@@ -5250,7 +5272,7 @@ export declare abstract class AbstractMapModule<SOURCES_WITH_LAYERS extends Sour
    * 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
+   * The given configuration **replaces** the current one
    * rather than being merged into it. To change one part of it, use {@link updateConfig}.
    *
    * @example
@@ -5278,8 +5300,8 @@ export declare abstract class AbstractMapModule<SOURCES_WITH_LAYERS extends Sour
    *
    * @example
    * ```typescript
-   * routing.applyConfig({ displayUnits: 'imperial', theme: { mainColor: '#0a3653' } });
-   * routing.updateConfig({ theme: { mainColor: '#c2185b' } }); // displayUnits stays imperial
+   * routing.applyConfig({ displayUnits: 'imperial', color: '#0a3653' });
+   * routing.updateConfig({ color: '#c2185b' }); // displayUnits stays imperial
    * ```
    *
    * @see {@link applyConfig} to apply a whole configuration
@@ -6432,8 +6454,7 @@ export declare const geometryFillStyles: readonly ["filled", "outline", "inverte
 //#endregion
 //#region src/geometry/types/geometriesModuleConfig.d.ts
 /**
- * Fill configuration for geometry styling — the interior color, opacity, and (optionally) where the
- * fill layer sits in the map's layer stack.
+ * Fill configuration for geometry styling — the interior color and opacity.
  *
  * @example
  * ```typescript
@@ -6469,15 +6490,6 @@ export type GeometryFillConfig = {
    * @default 0.15
    */
   opacity?: DataDrivenPropertyValueSpecification<number>;
-  /**
-   * Layer positioning for the **fill** layer only.
-   *
-   * @remarks
-   * Overrides the top-level {@link GeometriesModuleConfig.beforeLayerConfig} for the fill.
-   * Use this to sink the fill below the road network while the border stays above, e.g.
-   * `fill: { beforeLayerConfig: 'lowestRoadLine' }`, `line: { beforeLayerConfig: 'top' }`.
-   */
-  beforeLayerConfig?: BeforeLayerConfig;
 };
 /**
  * The label drawn at the center of each geometry: its text, and how it looks.
@@ -6593,15 +6605,6 @@ export type GeometryLineConfig = {
    * ```
    */
   layer?: Partial<ToBeAddedLayerSpecTemplate<LineLayerSpecification>>;
-  /**
-   * Layer positioning for the **border/outline** layer only.
-   *
-   * @remarks
-   * Overrides the top-level {@link GeometriesModuleConfig.beforeLayerConfig} for the border.
-   * Pair with {@link GeometryFillConfig.beforeLayerConfig} to split the fill and border across
-   * the layer stack (e.g. fill below roads, border on top).
-   */
-  beforeLayerConfig?: BeforeLayerConfig;
 };
 /**
  * Labels placed along the polygon border lines, repeating the geometry's title.
@@ -6661,13 +6664,13 @@ export type GeometryLineLabel = LabelConfig & {
  * Controls where geometry layers are placed in the map's layer stack.
  *
  * @remarks
- * Use this to ensure geometries appear above or below other map features like
- * labels, roads, or other data layers.
- *
- * @remarks
  * A single {@link BeforeLayerConfig} (`'top'` or a layer id) positions **all** geometry layers
- * together. The object form positions the fill and border independently — `all` is the fallback
- * for any target it doesn't name.
+ * together. The record form positions the parts independently, `all` covering any it doesn't name:
+ * - `fill` — the fill layer.
+ * - `line` — the border/outline, with its line labels.
+ *
+ * A part the config names no target for sits where the module adds it, just below the geometry
+ * titles; `'top'` keeps those titles above the geometries themselves.
  *
  * @example
  * ```typescript
@@ -6683,24 +6686,7 @@ export type GeometryLineLabel = LabelConfig & {
  *
  * @group Geometries
  */
-export type GeometryBeforeLayerConfig = BeforeLayerConfig | GeometryBeforeLayerTargets;
-/**
- * Per-layer positioning targets for the object form of {@link GeometryBeforeLayerConfig}.
- *
- * `fill` and `line` position their respective layers; `all` is the fallback applied to any
- * target not explicitly set. A per-layer `beforeLayerConfig` inside {@link GeometryFillConfig}
- * or {@link GeometryLineConfig} wins over the value here.
- *
- * @group Geometries
- */
-export type GeometryBeforeLayerTargets = {
-  /** Fallback position for any layer not named by `fill` / `line`. */
-  all?: BeforeLayerConfig;
-  /** Position for the fill layer. */
-  fill?: BeforeLayerConfig;
-  /** Position for the border/outline layer (and its line labels). */
-  line?: BeforeLayerConfig;
-};
+export type GeometryBeforeLayerConfig = PartsBeforeLayerConfig<'fill' | 'line'>;
 /**
  * Configuration options for the GeometriesModule.
  *
@@ -6771,7 +6757,7 @@ export type GeometriesModuleConfig = MapModuleCommonConfig & {
    */
   visible?: boolean;
   /**
-   * Fill color, opacity, and (optional) fill-layer positioning.
+   * Fill color and opacity.
    *
    * Controls the interior color and transparency of polygon geometries.
    */
@@ -6781,7 +6767,7 @@ export type GeometriesModuleConfig = MapModuleCommonConfig & {
    */
   label?: GeometryLabel;
   /**
-   * Border/outline configuration, and (optional) border-layer positioning.
+   * Border/outline configuration.
    *
    * Controls the outline appearance of polygon geometries.
    */
@@ -6789,9 +6775,8 @@ export type GeometriesModuleConfig = MapModuleCommonConfig & {
   /**
    * Layer positioning configuration.
    *
-   * Controls where geometry layers appear in the map's layer stack.
-   * Use `'top'` to place above all layers, or specify a layer ID to place
-   * below that layer.
+   * Controls where geometry layers appear in the map's layer stack: `'top'` places them above all
+   * layers, a layer ID below that layer, and a `{ all, fill, line }` record each part on its own.
    *
    * @example
    * ```typescript
@@ -6801,8 +6786,8 @@ export type GeometriesModuleConfig = MapModuleCommonConfig & {
    * // Below map labels
    * beforeLayerConfig: 'lowestLabel'
    *
-   * // Below POI layer
-   * beforeLayerConfig: 'POI'
+   * // Fill below the road network, border below labels
+   * beforeLayerConfig: { fill: 'lowestRoadLine', line: 'lowestLabel' }
    * ```
    */
   beforeLayerConfig?: GeometryBeforeLayerConfig;
@@ -7000,8 +6985,8 @@ export declare class GeometriesModule extends AbstractDataOwnedMapModule<Geometr
    * @remarks
    * **Configuration Options:**
    * - `color`: Base colour for fill and border
-   * - `fill`: Fill color, opacity, and optional fill-layer positioning
-   * - `line`: Border/outline styling and optional border-layer positioning
+   * - `fill`: Fill color and opacity
+   * - `line`: Border/outline styling
    * - `label`: Center label text and styling
    * - `beforeLayerConfig`: Layer ordering — a single target, or `{ all, fill, line }` to split them
    *
@@ -7067,30 +7052,20 @@ export declare class GeometriesModule extends AbstractDataOwnedMapModule<Geometr
    */
   protected _applyConfig(config: GeometriesModuleConfig | undefined): GeometriesModuleConfig | undefined;
   private applyVisibility;
-  /** Resolve a positioning target to the map-style layer id the geometry layers should sit before. */
-  private resolveBeforeID;
-  private moveLayersBefore;
-  private get fillLayerIDs();
-  private get lineLayerIDs();
+  private get partLayerIDs();
   /**
    * Positions the geometry layers relative to other map layers.
    *
    * @param layerConfig - Layer positioning. A single {@link BeforeLayerConfig} (`'top'` or a layer
-   * id) moves all geometry layers together; the object form (`{ all?, fill?, line? }`) positions the
-   * fill and border independently.
+   * id) moves all geometry layers together; the record form (`{ all?, fill?, line? }`) positions the
+   * fill and border independently, leaving a part it names no target for where it is.
    *
-   * @remarks
-   * A per-layer `beforeLayerConfig` set inside the `fill` / `line` config sections takes precedence
-   * over the value passed here.
-   *
-   * **Available Layer IDs:** predefined ids from `mapStyleLayerIDs`, or a custom layer id.
+   * **Available Layer IDs:** the keys of `mapStyleLayerIDs`.
    *
    * @example
    * ```typescript
-   * import { mapStyleLayerIDs } from '@tomtom-org/maps-sdk/map';
-   *
    * // Place all geometry layers below labels
-   * geometries.moveBeforeLayer(mapStyleLayerIDs.lowestLabel);
+   * geometries.moveBeforeLayer('lowestLabel');
    *
    * // Fill below the road network, border on top
    * geometries.moveBeforeLayer({ fill: 'lowestRoadLine', line: 'top' });
@@ -9798,7 +9773,7 @@ type SectionLinePattern = 'solid' | 'dashed' | 'dotted';
  * One of the uniform knobs {@link SectionDisplayConfig} offers.
  * @group Routing
  */
-type SectionKnobName = 'visible' | 'color' | 'opacity' | 'width' | 'style' | 'pattern' | 'icon' | 'sign';
+type SectionKnobName = 'visible' | 'color' | 'opacity' | 'width' | 'widthFactor' | 'style' | 'pattern' | 'icon' | 'sign';
 /**
  * The key one section type's source, events scope and `getShown()` entry are filed under.
  *
@@ -9823,42 +9798,42 @@ declare const SECTION_REGISTRY: {
     readonly visible: false;
     readonly style: "halo";
     readonly pattern: "solid";
-    readonly knobs: readonly ["visible", "color", "opacity", "width", "style", "pattern", "icon"];
+    readonly knobs: readonly ["visible", "color", "opacity", "width", "widthFactor", "style", "pattern", "icon"];
   };
   readonly carTrain: {
     readonly sourceKey: "carTrainSections";
     readonly visible: true;
     readonly style: "halo";
     readonly pattern: "dashed";
-    readonly knobs: readonly ["visible", "color", "opacity", "width", "style", "pattern", "icon"];
+    readonly knobs: readonly ["visible", "color", "opacity", "width", "widthFactor", "style", "pattern", "icon"];
   };
   readonly importantRoadStretch: {
     readonly sourceKey: "importantRoadStretchSections";
     readonly visible: false;
     readonly style: "halo";
     readonly pattern: "solid";
-    readonly knobs: readonly ["visible", "color", "opacity", "width", "style", "pattern", "icon"];
+    readonly knobs: readonly ["visible", "color", "opacity", "width", "widthFactor", "style", "pattern", "icon"];
   };
   readonly lowEmissionZone: {
     readonly sourceKey: "lowEmissionZoneSections";
     readonly visible: true;
     readonly style: "halo";
     readonly pattern: "solid";
-    readonly knobs: readonly ["visible", "color", "opacity", "width", "style", "pattern", "icon"];
+    readonly knobs: readonly ["visible", "color", "opacity", "width", "widthFactor", "style", "pattern", "icon"];
   };
   readonly motorway: {
     readonly sourceKey: "motorwaySections";
     readonly visible: false;
     readonly style: "halo";
     readonly pattern: "solid";
-    readonly knobs: readonly ["visible", "color", "opacity", "width", "style", "pattern", "icon"];
+    readonly knobs: readonly ["visible", "color", "opacity", "width", "widthFactor", "style", "pattern", "icon"];
   };
   readonly pedestrian: {
     readonly sourceKey: "pedestrianSections";
     readonly visible: false;
     readonly style: "halo";
     readonly pattern: "dashed";
-    readonly knobs: readonly ["visible", "color", "opacity", "width", "style", "pattern", "icon"];
+    readonly knobs: readonly ["visible", "color", "opacity", "width", "widthFactor", "style", "pattern", "icon"];
   };
   readonly speedLimit: {
     readonly sourceKey: "speedLimitSections";
@@ -9870,56 +9845,56 @@ declare const SECTION_REGISTRY: {
     readonly visible: true;
     readonly style: "halo";
     readonly pattern: "dashed";
-    readonly knobs: readonly ["visible", "color", "opacity", "width", "style", "pattern", "icon"];
+    readonly knobs: readonly ["visible", "color", "opacity", "width", "widthFactor", "style", "pattern", "icon"];
   };
   readonly unpaved: {
     readonly sourceKey: "unpavedSections";
     readonly visible: false;
     readonly style: "halo";
     readonly pattern: "dashed";
-    readonly knobs: readonly ["visible", "color", "opacity", "width", "style", "pattern", "icon"];
+    readonly knobs: readonly ["visible", "color", "opacity", "width", "widthFactor", "style", "pattern", "icon"];
   };
   readonly urban: {
     readonly sourceKey: "urbanSections";
     readonly visible: false;
     readonly style: "halo";
     readonly pattern: "solid";
-    readonly knobs: readonly ["visible", "color", "opacity", "width", "style", "pattern", "icon"];
+    readonly knobs: readonly ["visible", "color", "opacity", "width", "widthFactor", "style", "pattern", "icon"];
   };
   readonly ferry: {
     readonly sourceKey: "ferries";
     readonly visible: true;
     readonly style: "inline";
     readonly pattern: "solid";
-    readonly knobs: readonly ["visible", "color", "opacity", "width", "style", "pattern", "icon"];
+    readonly knobs: readonly ["visible", "color", "opacity", "width", "widthFactor", "style", "pattern", "icon"];
   };
   readonly tollRoad: {
     readonly sourceKey: "tollRoads";
     readonly visible: true;
     readonly style: "halo";
     readonly pattern: "solid";
-    readonly knobs: readonly ["visible", "color", "opacity", "width", "style", "pattern", "icon"];
+    readonly knobs: readonly ["visible", "color", "opacity", "width", "widthFactor", "style", "pattern", "icon"];
   };
   readonly traffic: {
     readonly sourceKey: "incidents";
     readonly visible: true;
     readonly style: "inline";
     readonly pattern: "solid";
-    readonly knobs: readonly ["visible", "opacity", "width", "style"];
+    readonly knobs: readonly ["visible", "opacity", "width", "widthFactor", "style"];
   };
   readonly tunnel: {
     readonly sourceKey: "tunnels";
     readonly visible: true;
     readonly style: "inline";
     readonly pattern: "solid";
-    readonly knobs: readonly ["visible", "color", "opacity", "width", "style", "pattern", "icon"];
+    readonly knobs: readonly ["visible", "color", "opacity", "width", "widthFactor", "style", "pattern", "icon"];
   };
   readonly vehicleRestricted: {
     readonly sourceKey: "vehicleRestricted";
     readonly visible: true;
     readonly style: "inline";
     readonly pattern: "dotted";
-    readonly knobs: readonly ["visible", "color", "opacity", "width", "style", "pattern", "icon"];
+    readonly knobs: readonly ["visible", "color", "opacity", "width", "widthFactor", "style", "pattern", "icon"];
   };
 };
 /**
@@ -10479,7 +10454,9 @@ type WaypointsConfig = {
  * Route line thickness preset.
  *
  * @remarks
- * Controls the thickness of the main route line and its outline at all zoom levels.
+ * Controls the thickness of the route line, its outline, the section lines and the instruction
+ * lines at all zoom levels. Each preset is a zoom profile of its own, tuned so the outline stays a
+ * readable rim at every thickness; a `widthFactor` multiplies whichever preset applies.
  *
  * Available options:
  * - `"s"` - Thin line, suitable for dense or cluttered maps
@@ -10493,7 +10470,8 @@ type RouteWidth = 's' | 'm' | 'l';
  * Route waypoint icon size preset.
  *
  * @remarks
- * Controls the scale of waypoint pin icons at all zoom levels.
+ * Controls the scale of waypoint pin icons at all zoom levels: `"s"` is 0.75 × `"m"` and `"l"` is
+ * 1.25 × `"m"`. {@link RoutingModuleConfig.waypointSizeFactor} multiplies whichever preset applies.
  *
  * Available options:
  * - `"s"` - Small icons
@@ -10503,51 +10481,6 @@ type RouteWidth = 's' | 'm' | 'l';
  * @group Routing
  */
 type RouteWaypointSize = 's' | 'm' | 'l';
-/**
- * Generic styling for route visualization.
- *
- * @remarks
- * * Provides high-level theming options for route appearance.
- * * Can be overwritten by more specific layer styling configurations.
- *
- * @group Routing
- */
-type RouteTheme = {
-  /**
-   * The primary color applied to the route line, outline, and waypoint icons.
-   *
-   * @remarks
-   * Affects the main selected route line foreground, the route outline (a darker shade
-   * is derived automatically), and the waypoint icon fill.
-   * Can be overwritten by more specific layer styling configurations.
-   *
-   * When unset, the map's accent colour applies if a theme sets one ({@link TomTomMap.mapColors}).
-   *
-   * Available options:
-   * - Any valid CSS color string (e.g., `"#FF0000"`, `"rgb(255,0,0)"`, `"red"`, etc.)
-   */
-  mainColor?: string;
-  /**
-   * Line thickness preset for the main route line and its outline.
-   *
-   * @remarks
-   * Scales the route line width at all zoom levels using predefined profiles.
-   * Can be overwritten by more specific layer styling configurations.
-   *
-   * @defaultValue `"m"`
-   */
-  routeWidth?: RouteWidth;
-  /**
-   * Icon size preset for route waypoint pins.
-   *
-   * @remarks
-   * Scales the waypoint icon at all zoom levels using predefined profiles.
-   * Can be overwritten by more specific layer styling configurations.
-   *
-   * @defaultValue `"m"`
-   */
-  waypointSize?: RouteWaypointSize;
-};
 /**
  * The icon drawn on a route section.
  *
@@ -10574,11 +10507,12 @@ type SectionIconConfig = {
    */
   placement?: 'center' | 'along';
   /**
-   * Icon scale, where `1` is the sprite image's own size.
+   * Icon scale, where `1` is the sprite image's own size. Clamped to
+   * {@link SECTION_ICON_SIZE_FACTOR_RANGE}, 0.25 to 2.
    *
    * @defaultValue `1` on the generated types; the bespoke types that draw an icon keep their own zoom-ramped size.
    */
-  size?: number;
+  sizeFactor?: number;
 };
 type SectionKnobs = {
   /**
@@ -10607,6 +10541,11 @@ type SectionKnobs = {
    * Line width preset. Defaults to the route's own width.
    */
   width?: RouteWidth;
+  /**
+   * Multiplier over the section's {@link width} preset; the two compose. Defaults to the route's
+   * own `widthFactor`, and is clamped to {@link ROUTE_WIDTH_FACTOR_RANGE}, 0.5 to 2.
+   */
+  widthFactor?: number;
   /**
    * Whether the section bands the route (`halo`) or stands in for the route line along its own
    * stretch (`inline`). This decides both where the section's line sits in the layer order and
@@ -10712,6 +10651,10 @@ type SectionSignConfig = {
   /**
    * What a sign gives way to when another symbol wants the same spot.
    *
+   * @remarks
+   * Where the route icons sit is {@link RoutingModuleConfig.beforeLayerConfig}'s to say; this
+   * places the signs relative to them and to the map's labels.
+   *
    * @defaultValue follows {@link placement}: `'belowRouteIcons'` under `atChange`, where the sign
    * is the only one posting that change; `'belowMapLabels'` under `along`, where the next repeat
    * posts it again.
@@ -10827,6 +10770,35 @@ type SectionDisplayConfig<T extends DrawnSectionType = DrawnSectionType> = Pick<
  * @group Routing
  */
 type SectionsDisplayConfig = { [T in DrawnSectionType]?: SectionDisplayConfig<T>; };
+/**
+ * Where the route's layers sit in the map's layer stack: one target for the whole route, or one per
+ * part of it.
+ *
+ * @remarks
+ * The parts, and where each sits by default:
+ * - `mainLines` — the route lines, with every section line (the bands drawn under the route line
+ *   and the stretches drawn over it). Below the map's labels.
+ * - `instructionLines` — the guidance lines and their arrows. Below the map's labels, above the
+ *   route lines.
+ * - `icons` — every icon the route draws: waypoints, summary bubbles, charging stops, border
+ *   crossings and section icons. Most sit above the map's labels; section icons drawn on generated
+ *   section types and the tunnel sign sit below them. A target puts them all beneath it, those two lowest.
+ *
+ * Each part keeps its own layers' order wherever it goes. Section signs are not a part: their
+ * {@link SectionSignConfig.priority} settles which symbols they give way to, among the route icons
+ * and the map labels wherever this put them.
+ *
+ * @example
+ * ```typescript
+ * // The whole route on top of the map
+ * const everything: RoutingBeforeLayerConfig = 'top';
+ * // Route lines under the road network, icons where they are
+ * const lines: RoutingBeforeLayerConfig = { mainLines: 'lowestRoadLine' };
+ * ```
+ *
+ * @group Routing
+ */
+type RoutingBeforeLayerConfig = PartsBeforeLayerConfig<'mainLines' | 'instructionLines' | 'icons'>;
 /**
  * Configuration options for the routing module.
  *
@@ -10852,14 +10824,47 @@ type RoutingModuleConfig = MapModuleCommonConfig & {
    */
   displayUnits?: DisplayUnits;
   /**
-   * Main styling configuration for the route visualization.
+   * The colour of the route line, its outline and the waypoint icons, as any CSS colour string.
+   *
+   * @remarks
+   * The outline takes a darker shade of it. When unset, the map's accent colour applies if a
+   * theme sets one ({@link TomTomMap.mapColors}), else the SDK's own route blue. `layers` overrides
+   * it layer by layer.
+   */
+  color?: string;
+  /**
+   * Thickness preset of the route line and its outline, which the section and instruction lines
+   * follow.
+   *
+   * @defaultValue `"m"`
+   */
+  width?: RouteWidth;
+  /**
+   * Multiplier over the {@link width} preset, `1` leaving it unchanged; the two compose, so
+   * `{ width: 'l', widthFactor: 1.5 }` draws 1.5 × the `"l"` profile.
+   *
+   * @remarks
+   * Clamped to {@link ROUTE_WIDTH_FACTOR_RANGE}, 0.5 to 2. Sections without a `widthFactor` of
+   * their own follow it.
+   *
+   * @defaultValue `1`
+   */
+  widthFactor?: number;
+  /**
+   * Size preset of the waypoint pins.
+   *
+   * @defaultValue `"m"`
+   */
+  waypointSize?: RouteWaypointSize;
+  /**
+   * Multiplier over the {@link waypointSize} preset, `1` leaving it unchanged; the two compose.
    *
    * @remarks
-   * * Provides high-level styling options that affect the overall appearance of the route,
-   * such as the primary color used for route lines and waypoints.
-   * * Can be overwritten by more specific layer styling configurations.
+   * Clamped to {@link ROUTE_WAYPOINT_SIZE_FACTOR_RANGE}, 0.5 to 2.
+   *
+   * @defaultValue `1`
    */
-  theme?: RouteTheme;
+  waypointSizeFactor?: number;
   /**
    * Configuration for the waypoints source and layers to display them on the map.
    *
@@ -10913,6 +10918,13 @@ type RoutingModuleConfig = MapModuleCommonConfig & {
    * knobs cannot express.
    */
   sections?: SectionsDisplayConfig;
+  /**
+   * Where the route's layers sit in the map's layer stack, for the whole route or per part.
+   *
+   * @remarks
+   * Left out, every layer sits where {@link RoutingBeforeLayerConfig} says it does by default.
+   */
+  beforeLayerConfig?: RoutingBeforeLayerConfig;
   /**
    * Custom layer styling configuration.
    *
@@ -10933,9 +10945,11 @@ type RoutingModuleConfig = MapModuleCommonConfig & {
  * @param layerIDPrefix - Optional prefix to add to layer IDs for supporting multiple instances.
  * @param instanceIndex - Optional instance index for image ID suffixes.
  * @param lightDark - The map style's light/dark theme, which the country crossing plaque colours follow.
+ * @param existingLayerID - The anchor a configured `beforeLayerConfig` target resolves to, given the
+ * layer it names: that layer when the style has it, else undefined for the top of the stack.
  * @ignore
  */
-export declare const buildRoutingLayers: (config?: RoutingModuleConfig, layerIDPrefix?: string, instanceIndex?: number, lightDark?: LightDark) => Required<RouteLayersConfig>;
+export declare const buildRoutingLayers: (config?: RoutingModuleConfig, layerIDPrefix?: string, instanceIndex?: number, lightDark?: LightDark, existingLayerID?: (layerID: string | undefined) => string | undefined) => Required<RouteLayersConfig>;
 /**
  * Default routing layers configuration. Calls routingLayers with no parameters.
  *
@@ -11017,39 +11031,72 @@ export declare const DESELECTED_ROUTE_FILTER: ExpressionSpecification;
  */
 export declare const ROUTE_LINE_OUTLINE_WIDTH: ExpressionSpecification;
 /**
- * Returns the foreground line width expression for the given size preset.
+ * The values {@link RoutingModuleConfig.widthFactor} and a section's `widthFactor` are clamped to.
+ *
+ * @remarks
+ * 0.5 of the thin preset is the thinnest that still draws a line inside its outline, 1 px within
+ * 2 px at the lowest zoom; 2 of the thick one is a 30 px line at street zooms, about a motorway's
+ * width. Beyond either end the route stops reading as a line over the roads it follows.
+ * @group Routing
+ */
+export declare const ROUTE_WIDTH_FACTOR_RANGE: KnobRange;
+/**
+ * The values {@link RoutingModuleConfig.waypointSizeFactor} is clamped to.
+ *
+ * @remarks
+ * Spans a pin from about 14 px wide, half the small preset zoomed out, to 120 px, twice the large
+ * one zoomed in.
+ * @group Routing
+ */
+export declare const ROUTE_WAYPOINT_SIZE_FACTOR_RANGE: KnobRange;
+/**
+ * The values {@link SectionIconConfig.sizeFactor} is clamped to.
+ *
+ * @remarks
+ * Relative to the sprite image, which the built-in section icons already draw at 0.5 to 1 of: down
+ * to half that, and up to twice the image.
+ * @group Routing
+ */
+export declare const SECTION_ICON_SIZE_FACTOR_RANGE: KnobRange;
+/**
+ * How thick a route line is drawn: a preset and a multiplier over it.
+ * @ignore
+ */
+export type RouteLineWidth = Pick<RoutingModuleConfig, 'width' | 'widthFactor'>;
+/**
+ * Returns the foreground line width expression for the given width.
  * @ignore
  */
-export declare const getLineForegroundWidth: (size?: RouteWidth) => ExpressionSpecification;
+export declare const getLineForegroundWidth: (lineWidth?: RouteLineWidth) => ExpressionSpecification;
 /**
- * Returns the outline line width expression for the given size preset.
+ * Returns the outline line width expression for the given width.
  * @ignore
  */
-export declare const getLineOutlineWidth: (size?: RouteWidth) => ExpressionSpecification;
+export declare const getLineOutlineWidth: (lineWidth?: RouteLineWidth) => ExpressionSpecification;
 /**
- * Returns the waypoint icon size expression for the given size preset.
+ * Returns the waypoint icon size expression for the given size preset and multiplier.
  * @ignore
  */
-export declare const getWaypointIconSize: (size?: RouteWaypointSize) => ExpressionSpecification;
+export declare const getWaypointIconSize: (size?: RouteWaypointSize, sizeFactor?: number) => ExpressionSpecification;
 /**
- * Returns the width expression of a section halo for the given size preset.
+ * Returns the width expression of a section halo for the given width.
  *
  * @remarks
  * Wider than {@link getLineOutlineWidth} at every zoom, which is what makes a section drawn
  * beneath the route show as a band around it rather than disappear under the route's own outline.
  * @ignore
  */
-export declare const getSectionHaloWidth: (size?: RouteWidth) => ExpressionSpecification;
+export declare const getSectionHaloWidth: (lineWidth?: RouteLineWidth) => ExpressionSpecification;
 /**
- * Returns the instruction line width expression for the given size preset.
+ * Returns the instruction line width expression for the given width.
  * @ignore
  */
-export declare const getInstructionLineWidth: (size?: RouteWidth) => ExpressionSpecification;
+export declare const getInstructionLineWidth: (lineWidth?: RouteLineWidth) => ExpressionSpecification;
 /**
- * Returns the instruction outline width expression for the given size preset.
+ * Returns the instruction outline width expression for the given width.
  * @ignore
  */
-export declare const getInstructionOutlineWidth: (size?: RouteWidth) => ExpressionSpecification;
+export declare const getInstructionOutlineWidth: (lineWidth?: RouteLineWidth) => ExpressionSpecification;
 /**
  * @ignore
  */
@@ -11944,7 +11991,7 @@ export type RoutingEvents = CombinedEvents<MapGeoJSONFeature, RoutingModuleConfi
 export declare class RoutingModule extends AbstractDataOwnedMapModule<RoutingSourcesWithLayers, RoutingModuleConfig> {
   private layersSpecs;
   private layerIDPrefix;
-  private appliedMainColor?;
+  private appliedRouteColor?;
   private readonly shownFeaturesHandlers;
   /**
    * Make sure the map is ready before create an instance of the module and any other interaction with the map
@@ -11985,7 +12032,7 @@ export declare class RoutingModule extends AbstractDataOwnedMapModule<RoutingSou
    */
   static create(tomtomMap: TomTomMap, config?: RoutingModuleConfig): Promise<RoutingModule>;
   private constructor();
-  private mainColorOf;
+  private routeColorOf;
   private buildLayersSpecs;
   private createSourcesWithLayers;
   /**
@@ -12069,7 +12116,8 @@ export declare class RoutingModule extends AbstractDataOwnedMapModule<RoutingSou
    * `aboveRouteIcons` anchors to nothing, which puts the layer on top. The other two differ only
    * in where the search starts: under the base map's labels for `belowMapLabels`, and at them for
    * `belowRouteIcons`, since a section's own icon layer is pinned below the labels and a sign
-   * sent under that would give way to every place name on the way.
+   * sent under that would give way to every place name on the way. The arrows drawn along the
+   * lines are not icons, even when `beforeLayerConfig` lifts the lines above the labels.
    */
   private signAnchorLayerID;
   /** @ignore */
@@ -12285,11 +12333,12 @@ export declare class RoutingModule extends AbstractDataOwnedMapModule<RoutingSou
    */
   get events(): RoutingEvents;
   /**
-   * Returns the map style layer under which route lines are rendered.
+   * Returns the map style layer under which route lines are rendered, or undefined when they are
+   * on top of the stack.
    * * Useful if you want to render extra layers just above the route ones but not on top of everything else.
-   * * It might differ depending on the loaded style/version.
+   * * Follows `beforeLayerConfig`, and might differ depending on the loaded style/version.
    */
-  getLayerToRenderLinesUnder(): string;
+  getLayerToRenderLinesUnder(): string | undefined;
 }
 //#endregion
 //#region src/terrain/types/terrainModuleConfig.d.ts
@@ -12624,47 +12673,29 @@ type AreaAnalyticsMetricConfig = {
   filters?: AreaAnalyticsMetricFilter;
 };
 /**
- * Per-layer-type positioning configuration for area analytics layers.
+ * Where the area analytics layers sit in the map's layer stack.
  *
- * Controls where each analytics layer type sits in the map's layer stack independently.
- * Each property accepts `'top'` (above all layers) or a well-known style layer ID.
- * Omitted properties fall back to their default positions.
+ * @remarks
+ * A single {@link BeforeLayerConfig} positions every display mode's layer; the record form positions
+ * them independently, keyed by {@link AreaAnalyticsDisplayMode}, `all` covering any it doesn't name.
+ * A mode neither names keeps its default: `'lowestLabel'` for `heatmap`, `hexgrid-2d` and
+ * `square-2d`, `'lowestPlaceLabel'` for `hexgrid-3d` and `square-3d`. The region boundary always
+ * sits below the map's labels.
  *
  * @example
  * ```typescript
- * // Move all layers below the lowest label
- * const config: TrafficAreaAnalyticsModuleConfig = {
- *   beforeLayerConfig: {
- *     heatmap: 'lowestLabel',
- *     hexgrid: { flat2D: 'lowestLabel', extrusion3D: 'lowestPlaceLabel' },
- *     square:  { flat2D: 'lowestLabel', extrusion3D: 'lowestPlaceLabel' },
- *   },
- * };
+ * // Every mode on top of the map
+ * const config: TrafficAreaAnalyticsModuleConfig = { beforeLayerConfig: 'top' };
  *
- * // Only reposition the heatmap layer
+ * // Flat modes below labels, extrusions below place labels
  * const config: TrafficAreaAnalyticsModuleConfig = {
- *   beforeLayerConfig: { heatmap: 'top' },
+ *   beforeLayerConfig: { all: 'lowestLabel', 'hexgrid-3d': 'lowestPlaceLabel', 'square-3d': 'lowestPlaceLabel' },
  * };
  * ```
  *
  * @group Traffic Area Analytics
  */
-type AreaAnalyticsBeforeLayerConfig = {
-  /** Layer position for the heatmap layer. Defaults to `'lowestLabel'`. */
-  heatmap?: BeforeLayerConfig;
-  hexgrid?: {
-    /** Layer position for the flat hexgrid fill layer. Defaults to `'lowestLabel'`. */
-    flat2D?: BeforeLayerConfig;
-    /** Layer position for the extruded hexgrid layer. Defaults to `'lowestPlaceLabel'`. */
-    extrusion3D?: BeforeLayerConfig;
-  };
-  square?: {
-    /** Layer position for the flat square fill layer. Defaults to `'lowestLabel'`. */
-    flat2D?: BeforeLayerConfig;
-    /** Layer position for the extruded square layer. Defaults to `'lowestPlaceLabel'`. */
-    extrusion3D?: BeforeLayerConfig;
-  };
-};
+type AreaAnalyticsBeforeLayerConfig = PartsBeforeLayerConfig<AreaAnalyticsDisplayMode>;
 /**
  * Display configuration for the actual region boundary geometry.
  *
@@ -12917,8 +12948,7 @@ type TrafficAreaAnalyticsModuleConfig = MapModuleCommonConfig & {
    */
   metricConfig?: Partial<Record<AreaAnalyticsMetricKey, AreaAnalyticsMetricConfig>>;
   /**
-   * Per-layer-type positioning — controls where each analytics layer type sits in the map layer stack.
-   * Omitted layer types fall back to their default positions (`'lowestLabel'` for flat/heatmap, `'lowestPlaceLabel'` for extrusions).
+   * Where the analytics layers sit in the map's layer stack, for all display modes or per mode.
    */
   beforeLayerConfig?: AreaAnalyticsBeforeLayerConfig;
   /**
@@ -13050,6 +13080,7 @@ export declare class TrafficAreaAnalyticsModule extends AbstractDataOwnedMapModu
   protected _initSourcesWithLayers(config?: TrafficAreaAnalyticsModuleConfig, _restore?: boolean): AreaAnalyticsSourcesWithLayers;
   /** @ignore */
   protected _applyConfig(config: TrafficAreaAnalyticsModuleConfig | undefined): TrafficAreaAnalyticsModuleConfig | undefined;
+  private get modeLayerSpecs();
   private moveLayersToSpecPositions;
   /** @ignore */
   protected discardShownData(): void;
@@ -13183,11 +13214,11 @@ export declare class TrafficAreaAnalyticsModule extends AbstractDataOwnedMapModu
     square: FeatureCollection<Polygon, AreaAnalyticsDisplayProperties>;
   };
   /**
-   * Repositions analytics layers independently by layer type.
+   * Repositions the analytics layers, all together or per display mode.
    *
-   * Only the properties present in `layerConfig` are repositioned; omitted layer types are left in place.
+   * Only the display modes `layerConfig` names a target for are repositioned; the others are left in place.
    *
-   * @param layerConfig - Per-layer-type positioning config. Each value is `'top'` or a `MapStyleLayerID`.
+   * @param layerConfig - A single target for every mode, or one per {@link AreaAnalyticsDisplayMode}.
    */
   moveBeforeLayer(layerConfig: AreaAnalyticsBeforeLayerConfig): void;
   /**
@@ -13804,8 +13835,8 @@ export type TrafficIncidentOverlayModuleConfig = MapModuleCommonConfig & {
    * Position incident layers before this map-style layer. Pass `'top'` to
    * pin them above every other layer. Defaults to `'lowestLabel'`, which
    * keeps incidents below map labels (roads, places, POIs) so labels stay
-   * readable — the same default the routing, analytics, and geometries
-   * modules use.
+   * readable — the same default the routing module and the flat area
+   * analytics layers use.
    */
   beforeLayerConfig?: BeforeLayerConfig;
   /**
@@ -14656,4 +14687,4 @@ export declare const calculatePaddedCenter: (options: CalculateMapCenterOptions)
  */
 export declare const calculateFittingBBox: (options: CalculateFittingBBoxOptions) => BBox | null;
 //#endregion
-export type { AREA_ANALYTICS_DEFAULTS, AreaAnalyticsBeforeLayerConfig, AreaAnalyticsColorStop, AreaAnalyticsColorStopsConfig, AreaAnalyticsColorTheme, AreaAnalyticsDisplayMode, AreaAnalyticsHeightConfig, AreaAnalyticsMetricConfig, AreaAnalyticsMetricFilter, AreaAnalyticsRegionPolygonConfig, AreaAnalyticsValueType, AvailabilityLevel, BaseMapColorName, BeforeLayerConfig, BespokeSectionType, ByIdOrIndex, CSSCursor, ChargingSpeedIconMapping, ChargingStopIconConfig, ChargingStopIconMapping, ChargingStopTextConfig, ChargingStopsConfig, CleanEventStateOptions, CleanEventStatesOptions, ClickEventType, CountryCrossingAlignment, CountryCrossingConfig, CountryCrossingFeature, CustomImage, DefaultPlaceIconConfig, DisplayCountryCrossing, DisplayCountryCrossingProps, DisplayCountryCrossings, DisplayRouteProps, DisplayRouteRelatedProps, DisplayRouteSummaries, DisplayRouteSummary, DisplayRouteSummaryProps, DrawnSectionType, EVAvailabilityConfig, EventHandlerConfig, EventHandlerCursorConfig, EventHandlerHoverConfig, EventState, EventType, ExtraFeatureProp, FeaturePropValue, FilterablePOICategory, GeneratedSectionType, GeoJSONSourcesWithLayers, HasAdditionalLayersConfig, HasBeforeID, HoverEventType, HslColor, LabelConfig, LayerQuery, LayerSpecFilter, LayerSpecTemplate, LayerSpecWithSource, LightDark, MapColorName, MapColors, MapEventsConfig, MapFont, MapModuleCommonConfig, MapStyleLayerID, POIsModuleConfig, POIsModuleFeature, PlaceClusterBadgeConfig, PlaceConnectionDisplay, PlaceConnectionLayerName, PlaceConnectionsConfig, PlaceConnectionsLayersConfig, PlaceEntryPointFeature, PlaceEntryPointProps, PlaceEntryPointsConfig, PlaceEntryPointsLayersConfig, PlaceEntryPointsShowFor, PlaceIconConfig, PlaceLayerName, PlaceLayersConfig, PlaceTextConfig, PlacesClusterConfig, PlacesModuleConfig, PlacesTheme, PlanningWaypoint, PutEventStateOptions, RGBAColor, RouteLayersConfig, RouteStateProps, RouteTheme, RouteWaypointSize, RouteWidth, RoutingModuleConfig, SVGIconStyleOptions, SectionDisplayConfig, SectionDrawStyle, SectionIconConfig, SectionKnobName, SectionKnobOf, SectionLineLayerName, SectionLinePattern, SectionSignConfig, SectionSignLayerName, SectionSignPlacement, SectionSignPriority, SectionSignUnit, SectionSourceKey, SectionSymbolLayerName, SectionsDisplayConfig, SourceWithLayerIDs, SourceWithLayers, SourcesWithLayers, StyleSourcesWithLayers, StylingColorKnobId, StylingKnob, StylingKnobAppliesTo, StylingKnobId, StylingKnobKind, StylingKnobRange, StylingKnobValue, StylingKnobValueOf, StylingPreset, StylingPresetId, StylingSettings, SupportsEvents, SymbolLayerSpecWithoutSource, TRAFFIC_LIGHT_COLORS, TerrainModuleConfig, ToBeAddedLayerSpec, ToBeAddedLayerSpecTemplate, ToBeAddedLayerSpecWithoutSource, TrafficAreaAnalyticsModuleConfig, UserEventHandler, WaypointsConfig };
+export type { AREA_ANALYTICS_DEFAULTS, AreaAnalyticsBeforeLayerConfig, AreaAnalyticsColorStop, AreaAnalyticsColorStopsConfig, AreaAnalyticsColorTheme, AreaAnalyticsDisplayMode, AreaAnalyticsHeightConfig, AreaAnalyticsMetricConfig, AreaAnalyticsMetricFilter, AreaAnalyticsRegionPolygonConfig, AreaAnalyticsValueType, AvailabilityLevel, BaseMapColorName, BeforeLayerConfig, BespokeSectionType, ByIdOrIndex, CSSCursor, ChargingSpeedIconMapping, ChargingStopIconConfig, ChargingStopIconMapping, ChargingStopTextConfig, ChargingStopsConfig, CleanEventStateOptions, CleanEventStatesOptions, ClickEventType, CountryCrossingAlignment, CountryCrossingConfig, CountryCrossingFeature, CustomImage, DefaultPlaceIconConfig, DisplayCountryCrossing, DisplayCountryCrossingProps, DisplayCountryCrossings, DisplayRouteProps, DisplayRouteRelatedProps, DisplayRouteSummaries, DisplayRouteSummary, DisplayRouteSummaryProps, DrawnSectionType, EVAvailabilityConfig, EventHandlerConfig, EventHandlerCursorConfig, EventHandlerHoverConfig, EventState, EventType, ExtraFeatureProp, FeaturePropValue, FilterablePOICategory, GeneratedSectionType, GeoJSONSourcesWithLayers, HasAdditionalLayersConfig, HasBeforeID, HoverEventType, HslColor, LabelConfig, LayerQuery, LayerSpecFilter, LayerSpecTemplate, LayerSpecWithSource, LightDark, MapColorName, MapColors, MapEventsConfig, MapFont, MapModuleCommonConfig, MapStyleLayerID, POIsModuleConfig, POIsModuleFeature, PartsBeforeLayerConfig, PlaceClusterBadgeConfig, PlaceConnectionDisplay, PlaceConnectionLayerName, PlaceConnectionsConfig, PlaceConnectionsLayersConfig, PlaceEntryPointFeature, PlaceEntryPointProps, PlaceEntryPointsConfig, PlaceEntryPointsLayersConfig, PlaceEntryPointsShowFor, PlaceIconConfig, PlaceLayerName, PlaceLayersConfig, PlaceTextConfig, PlacesClusterConfig, PlacesModuleConfig, PlacesTheme, PlanningWaypoint, PutEventStateOptions, RGBAColor, RouteLayersConfig, RouteStateProps, RouteWaypointSize, RouteWidth, RoutingBeforeLayerConfig, RoutingModuleConfig, SVGIconStyleOptions, SectionDisplayConfig, SectionDrawStyle, SectionIconConfig, SectionKnobName, SectionKnobOf, SectionLineLayerName, SectionLinePattern, SectionSignConfig, SectionSignLayerName, SectionSignPlacement, SectionSignPriority, SectionSignUnit, SectionSourceKey, SectionSymbolLayerName, SectionsDisplayConfig, SourceWithLayerIDs, SourceWithLayers, SourcesWithLayers, StyleSourcesWithLayers, StylingColorKnobId, StylingKnob, StylingKnobAppliesTo, StylingKnobId, StylingKnobKind, StylingKnobRange, StylingKnobValue, StylingKnobValueOf, StylingPreset, StylingPresetId, StylingSettings, SupportsEvents, SymbolLayerSpecWithoutSource, TRAFFIC_LIGHT_COLORS, TerrainModuleConfig, ToBeAddedLayerSpec, ToBeAddedLayerSpecTemplate, ToBeAddedLayerSpecWithoutSource, TrafficAreaAnalyticsModuleConfig, UserEventHandler, WaypointsConfig };