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

package/CHANGELOG.md

@@ -1,5 +1,396 @@
 # Changelog
 
+## 1.0.0-rc.4
+
+### Major Changes
+
+- [#2748](https://github.com/tomtom-internal/maps-sdk-js/pull/2748) [`2597ffe`](https://github.com/tomtom-internal/maps-sdk-js/commit/2597ffeaff5f42079109938b277590c95726ca33) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - **Breaking:** core, services: a route or leg summary's `trafficDelayInSeconds` and `trafficLengthInMeters` are optional, present only when the routing service sends them, rather than `0` when it leaves them out
+  
+  - core: `trafficDelayInSeconds` is the delay of the traffic events along `trafficLengthInMeters`. For the gap to free-flow, use `Math.max(0, liveTrafficIncidentsTravelTimeInSeconds - noTrafficTravelTimeInSeconds)`, with `computeTravelTimeFor: 'all'`
+  - agent-toolkit: the route shape `analyseData`, `processData`, `clusterIncidents` and `createTracker` give the model says what `trafficDelayInSeconds` measures and how to work out the gap to free-flow
+  - examples: `react-route-planner` shows the traffic delay against free flow, and the delay of the traffic events on a row of its own
+
+### Minor Changes
+
+- [#2724](https://github.com/tomtom-internal/maps-sdk-js/pull/2724) [`2cf2e55`](https://github.com/tomtom-internal/maps-sdk-js/commit/2cf2e554793280c067cef0f3864486eb617711ce) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - **Breaking:** core: the bbox utilities read and return a box crossing the antimeridian as `west > east`, as RFC 7946 and the services do, so fitting the map to results around Fiji frames Fiji rather than the whole world
+  
+  - **Breaking:** core: `bboxFromCoordsArray`, and `bboxFromGeoJSON` on points, return the box across the antimeridian when it is narrower than the one from the lowest to the highest longitude. A tie, or input spanning -180 to 180, keeps the latter, so every country in the world still gives `[-180, …, 180]`
+  - **Breaking:** core: `bboxFromGeoJSON` reads a line or ring along its edges, which don't wrap, so a ring past 180 gives the box across the antimeridian and one from -100 to 100 stays `[-100, …, 100]`
+  - **Breaking:** core: `bboxFromBBoxes`, and `bboxFromGeoJSON` on several features or parts, return the narrowest box containing every input, so merging a box across the antimeridian with another keeps both
+  - **Breaking:** core: `polygonFromBBox` draws a box across the antimeridian with its east edge at `east + 360`, around the box rather than the rest of the world, and `bboxFromGeoJSON` reads that ring back as the same box
+  - map: `TomTomMap.getBBox` with padding returns a view across the antimeridian as `west > east`, and a view wider than 180° whole
+  - services: `geometrySearch` ranks a polygon across the antimeridian by its own width when it keeps the largest 50
+  - agent-toolkit: `getTrafficAreaAnalytics` reads a `bbox` across the antimeridian as the area it covers, and the tools describe a bbox as `[west, south, east, north]`. It needs SDK 1.0.0-rc.4
+
+- [#2752](https://github.com/tomtom-internal/maps-sdk-js/pull/2752) [`52ac9b4`](https://github.com/tomtom-internal/maps-sdk-js/commit/52ac9b4b89fa5c8019b24725c8074d3ed3e24a20) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - **Breaking:** core: `Language` holds every language the map labels carry, so `map.setLanguage('hi-IN')` labels the map in Hindi, and the services send each API a code it takes
+  
+  - **Breaking:** core: `Language` and `languages` gain `ca-ES`, `et-EE`, `eu-ES`, `gl-ES`, `he-IL`, `hi-IN`, `hr-HR`, `ja-JP`, `kk-KZ`, `lv-LV`, `ro-RO`, `sr-RS` and `uk-UA`, so a `Record<Language, …>` of your own needs an entry for each
+  - map: the map labels in each of them, and the traffic incident descriptions in Catalan, Estonian, Hebrew, Japanese, Latvian and Romanian
+  - services: a behaviour change. `zh-Hans` goes out as `zh-CN` and `zh-Hant` as `zh-TW`, so every service but traffic incidents, which lack Simplified Chinese, answers in that script, where it picked the script by place and answered Singapore in English. Search, geocoding, suggestions and POI categories take both, where they answered each with a 400
+  - services: search, geocoding and suggestions answer `hi-IN` and `ja-JP` in local names, and POI categories in English. All four answer `en-CA` in British English and `es-MX` in Latin American Spanish, where they answered each with a 400. POI categories take `ngt` and `ngt-Latn` too
+  - services: `trafficIncidentDetails` takes every `Language`, answering in the nearest language the incident tiles have, or in English, where it answered one it lacks, such as `en-AU` or `pt-BR`, with a 406
+  - examples: `map-language` offers Hebrew, Hindi, Japanese, Serbian and Ukrainian
+
+- [#2738](https://github.com/tomtom-internal/maps-sdk-js/pull/2738) [`6170ae7`](https://github.com/tomtom-internal/maps-sdk-js/commit/6170ae7d8e350c299e48d51d4a0a7824ec1bfb5a) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - **Breaking:** core: `main-when-available` uses a place's first untyped entry point when none is typed `'main'`, so a reverse geocoded place routes to the road-snapped point the service returns rather than to the queried point
+  
+  - **Breaking:** core: `getPosition(place, { useEntryPoint: 'main-when-available' })` returns that entry point's position. A place whose entry points are all `'minor'` keeps its own position
+  - **Breaking:** services: `calculateRoute` with `useEntryPoints: 'main-when-available'` sends such a stop at that entry point
+  - **Breaking:** map: `RoutingModule` with `waypoints.entryPoints: 'main-when-available'` draws such a waypoint at that entry point
+
+- [#2729](https://github.com/tomtom-internal/maps-sdk-js/pull/2729) [`77ef508`](https://github.com/tomtom-internal/maps-sdk-js/commit/77ef5080de0f74301d781e84f65628e5673797e6) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - **Breaking:** map: `styling.layers.query` selects style layers by exact id, derives a paint or layout value from the one beneath it, and narrows a layer's filter with one more clause, all kept across style switches; `POIsModule` hides or shows single POIs by id, which makes `filters.categories` optional
+  
+  - map: `LayerQuery` takes `ids`, the exact style layer ids to select
+  - map: `setPaint` and `setLayout` take a function `(valueUnder, layerId) => value` for any property, worked out from the style's own value, or the one a knob set, and again whenever that value changes
+  - map: `addFilterClause` and `removeFilterClause` add a clause to a layer's filter, `and`-ed with the style's own and with the filters other modules add, instead of replacing it as `setFilter` does
+  - map: `POIsModule`'s `filters.ids` takes a `ValuesFilter` of POI ids, beside `filters.categories`
+  - **Breaking:** map: `POIsModuleConfig`'s `filters.categories` is optional, so `filters` can hold `ids` alone. Code reading `config.filters.categories` must handle `undefined`
+  - examples: `map-styling-playground` adds a motorway name halo derived from the one beneath it and a road name filter clause, and `poi-filters` hides a POI you click
+
+- [#2757](https://github.com/tomtom-internal/maps-sdk-js/pull/2757) [`2478847`](https://github.com/tomtom-internal/maps-sdk-js/commit/2478847effe8a949fdce057874c236cf20e66dad) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - map: add a MapLibre custom layer with `map.addCustomLayer`, which keeps it in its place through style switches and lets its objects take clicks and hovers
+  - `beforeLayerConfig` places it as on a module. The new `'lowest3D'` anchor, `mapStyleLayerIDs.lowest3D`, puts a 3D layer under the style's 3D buildings, otherwise under the POIs, and module layers placed before `lowestLabel` stay below it, even the ones added later. Module layers at `'poi'` or `'top'` stay above it, also where it falls back to the POIs or the top
+  - An id the map already has throws, until that layer's `remove()`
+  - After every `setStyle`, before the modules restore, the layer goes back to its place, added again if the switch dropped it, and the module layers go back over or under it as they were. `remove()` takes it off for good
+  - A `hitTest` returns the objects under the pointer, topmost first. They join the map's user events in layer order, so the layer's `events`, priority, the hover cursor and the event states work as on a module's features, with `setState` to draw the states
+
+- [#2766](https://github.com/tomtom-internal/maps-sdk-js/pull/2766) [`22215a6`](https://github.com/tomtom-internal/maps-sdk-js/commit/22215a65286f7a6bd274c2aa6bb75cf81e5fee1e) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - **Breaking:** map: drag features on every module and scope with the new `dragstart`, `drag` and `dragend` events, such as a route's waypoints, its lines or a place's pin
+  
+  - map: a drag handler makes its features draggable with the mouse or one finger. They show the new `cursorOnDraggable` cursor, `'grab'` by default, the map doesn't pan under the drag, and the release fires no `click`
+  - map: `RoutingModule` reports the drag on `events.waypoints` and `events.mainLines` and plans nothing, so you call `calculateRoute` and `showRoutes` with the moved or inserted stop, or let the route dragging plugin do it
+  - **Breaking:** map: `EventType` also holds the three drag types, so a `switch` or a `Record` over it needs them. Event states keep to the click and hover types, as `EventState` and `SetEventStateOptions.state` now say on their own
+  - examples: `react-route-planner` drags stops on the map and pulls new ones onto the route line through the route dragging plugin, re-planning the route as you drag
+
+- [#2757](https://github.com/tomtom-internal/maps-sdk-js/pull/2757) [`2478847`](https://github.com/tomtom-internal/maps-sdk-js/commit/2478847effe8a949fdce057874c236cf20e66dad) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - map: line up a custom layer's three.js or WebGL scene with the map, in metres around a place, with `localFrameMatrix`
+  - It turns `defaultProjectionData.mainMatrix` into a `Float64Array`, composed in double precision, which a three.js camera or a WebGL uniform takes
+  - `centerLatitude` scales heights at the map centre's latitude, as MapLibre scales its 3D buildings and terrain, and `units: 'mercatorMeters'` takes geometry authored in EPSG:3857 metres
+
+- [#2775](https://github.com/tomtom-internal/maps-sdk-js/pull/2775) [`21cda10`](https://github.com/tomtom-internal/maps-sdk-js/commit/21cda10b55fb241f20387a93fa1a7090a4f7c851) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - **Breaking:** map: `SectionLinePattern`, deprecated in 1.0.0-rc.3, is removed. Use `LinePattern`, the same type, which geometries and reachable range borders share too
+
+- [#2756](https://github.com/tomtom-internal/maps-sdk-js/pull/2756) [`1da0aa4`](https://github.com/tomtom-internal/maps-sdk-js/commit/1da0aa4de06db25efe6a11c392cc73e10a77a229) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - **Breaking:** map: `TomTomMap` takes a `transformRequest` that holds or rewrites each map request after the SDK's own, and may return a promise, so an app can wait for its proxy session or point tiles at its own cache
+  
+  - map: `transformRequest`, typed `MapRequestTransform`, gets the request the SDK built, with its URL, headers and credentials, and stays in place through `setLanguage` and `setGeopoliticalView`
+  - **Breaking:** map: the map no longer awaits `globalThis.__DEMOS_PROXY_ENSURE_SESSION__` before its requests. An app that set it passes the same function as `transformRequest` instead: `transformRequest: async (request) => { await ensureSession(); return request; }`
+  - examples: `map-request-transform` holds the map's tile requests behind a toggle and counts them
+
+- [#2726](https://github.com/tomtom-internal/maps-sdk-js/pull/2726) [`eae0ebd`](https://github.com/tomtom-internal/maps-sdk-js/commit/eae0ebd9ca51c18ad9b4d3edeb3cd8d062834189) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - **Breaking:** map: when the map's style fails to load, a module's `create()` or `get()` rejects with the style's `TomTomMapError`, the one the error handlers get, so an `await` on it lands in your `catch` instead of waiting forever
+  
+  - **Breaking:** map: after a style load fails, a module call that waits for the map, such as `showRoutes` or `show`, rejects with that error too, until a `setStyle` loads a style. Once one loads, create again only the modules whose `create()` or `get()` rejected: the others restore themselves
+  - map: a style, tile, sprite or glyph request that gets no response, offline or blocked, reaches the error handlers as `NETWORK_NOT_AVAILABLE`, which can be retried, instead of `STYLE_LOAD_FAILED` or `INTERNAL`
+  - examples: `multiple-maps-landmarks` logs a map whose style fails to load instead of leaving an unhandled rejection
+
+- [#2660](https://github.com/tomtom-internal/maps-sdk-js/pull/2660) [`e6ab97c`](https://github.com/tomtom-internal/maps-sdk-js/commit/e6ab97cffc81eaa8fe417cde4a12e38829f70626) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - **Breaking:** services: `calculateRoute` returns the curves of each route as `sections.curve` and the winding stretches they make up as `sections.curvyStretch` when its `sectionTypes` names them, so you can keep a motion-sick passenger off winding roads or send a motorcyclist down them
+  
+  - **Breaking:** core: `SectionType`, `sectionTypes`, `inputSectionTypes` and `inputSectionTypesWithGuidance` include `'curve'` and `'curvyStretch'`. A `Record<SectionType, …>` needs an entry for each
+  - **Breaking:** services: `InputSectionType` includes them too
+  - **Breaking:** map: `DrawnSectionType`, `GeneratedSectionType`, `drawnSectionTypes` and `generatedSectionTypes` include them, so a `Record<DrawnSectionType, …>` needs an entry for each. `SectionKnobName` includes `'kerb'`, so a `Record<SectionKnobName, …>` needs one for it
+  - core: each curve has its `headingChangeInDegrees`, positive to the right, its `radiusInMeters` where it turns tightest, its `lengthInMeters` and a `curvinessScore`, its arc weighted by how tight it is as roadcurvature.com scores roads, a `severity` from 0 to 1, how much a driver slows down for it from the speed limit on the road into it, weighing its radius, how far it turns and whether it's a turn at a junction, and on a route with guidance the `maneuver` of a junction instruction on it. An instruction that keeps to the road, such as "Turn left to stay on the SS38" at a hairpin, names none
+  - core: each curvy stretch groups three or more curves within 500 m of each other, ended by a curve with a maneuver, with its `curveCount`, `hairpinCount` (its hairpins, curves turning 140° or more on a radius of 40 m or less, which the new `isHairpin` tells), `lengthInMeters`, `minRadiusInMeters` and `curvinessScore`, its curves' scores added up
+  - core: `getCurveSections` and `getCurvyStretchSections` find them with thresholds of your own. A curve's `severity` reads the route's `speedLimit` sections, so ask for them along with the curves
+  - services: `calculateRoute` takes those thresholds as `curveDetection`, a `CurveDetectionOptions` with the turn, radius and straight that make a curve and the curve count and gap that make a curvy stretch
+  - core: the new `withCurveSections` finds a route's curves and curvy stretches again with other thresholds, keeping its other sections, so you can tune them on routes you already have, with no new request
+  - core: `compareRoutes` and `getSectionsWithin` weigh `curve` and `curvyStretch` when you pass no `types`, on routes that carry them
+  - services: the SDK finds `curve` and `curvyStretch` in the route's geometry, only when a `sectionTypes` list names them, so a `calculateRoute` without `sectionTypes` does no more work than before. `inputSectionTypes` and `inputSectionTypesWithGuidance` name them, so a list built from those finds them too. It never sends them to the routing API
+  - core: the new `defaultSectionTypes` names the sections a `calculateRoute` without `sectionTypes` returns, so `sectionTypes: [...defaultSectionTypes, 'curve', 'curvyStretch']` keeps them all and adds the curves
+  - map: the routing module draws `curve` and `curvyStretch` as bands when you switch them on with `sections.curve: { visible: true }`, at the width of every other section band. The curves draw rose, a colour no traffic delay takes, deeper the higher their `severity`, above the stretch they make up, which draws the same rose fainter
+  - map: from zoom 12, a curve of 60 m radius or less carries a kerb, short stripes of a tint of its colour, nearly white on a light map and nearly black on a dark one. The new `sections.curve.kerb.color` knob sets the stripes' colour, and `sections.curve.kerb.visible: false` draws one plain line. `layers.sections.curve` takes the kerb as `routeSectionCurveKerb`
+  - examples: the new `route-curves` example ranks a mountain trip's routes by how winding they are and takes the straightest or the curviest. It shows all their curves, the open-road bends, the turns in towns, the curvy stretches each route has of its own, the curves in tunnels or the hairpins, with their speed limit signs, names how hard a curve you click is, and tells where a curvy stretch you click anywhere along starts, how long it takes and which towns it runs between. Its sliders, folded away under the picker, set what counts as a curve and a curvy stretch, and find them again on the routes shown. The `route-sections-playground` picker adds the Stelvio Pass, and `map-styling-playground` draws a route's curves over Twin Peaks
+  - examples: `react-route-planner` adds a Curvy roads lane and counts each alternative's curvy stretches of its own, and a Curvy route draws its curves and curvy stretches
+
+- [#2722](https://github.com/tomtom-internal/maps-sdk-js/pull/2722) [`9eff3f9`](https://github.com/tomtom-internal/maps-sdk-js/commit/9eff3f9f11ae3c358e0df83e9241cfb4a00f7282) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - **Breaking:** map: the `maplibre-gl` peer dependency moves up to `^6.15.0`
+  - **Breaking:** services: the `zod` peer dependency moves up to `^4.6.7`.
+  - services: `geometryData` reports a `geometries` list over 20 as one issue on that field, not as a union mismatch.
+
+- [#2786](https://github.com/tomtom-internal/maps-sdk-js/pull/2786) [`aba3679`](https://github.com/tomtom-internal/maps-sdk-js/commit/aba36798344f38c50ef4b4e4ec94737e30d15785) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - **Breaking:** services: along-route results from `discoverPlaces({ route })` carry their detour as typed `AlongRoutePlaceProps`, `detourTimeInSeconds` and `detourDistanceInMeters`, so you read them without a cast
+  
+  - **Breaking:** services: the untyped `properties.detourTime`, `detourDistance` and `detourOffset` are now `detourTimeInSeconds`, `detourDistanceInMeters` and `detourOffsetInMeters`. Either detour can be negative, when the route through the place is faster or shorter than the original
+  - services: `detourOffsetInMeters` comes with results sorted by `'detourOffset'`
+  - examples: `nodejs-along-route-search` prints each charger's detour
+
+- [#2751](https://github.com/tomtom-internal/maps-sdk-js/pull/2751) [`6d77703`](https://github.com/tomtom-internal/maps-sdk-js/commit/6d777037d17e27262728700e190cfce76a641142) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - **Breaking:** services: `geocodeOne` and `discoverOnePlace` reject with an `SDKError` coded `NOT_FOUND` when nothing matches, naming the `'Geocode'` or `'FuzzySearch'` service, so you can branch on `error.code` as for any other failed call
+  
+  - The message is unchanged. A `catch` that filters on `instanceof SDKError` now receives a miss too, where it used to get a plain `Error`.
+
+- [#2750](https://github.com/tomtom-internal/maps-sdk-js/pull/2750) [`94d3c8e`](https://github.com/tomtom-internal/maps-sdk-js/commit/94d3c8ea13a3b02631f152a03dd30af42ae5fd55) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - **Breaking:** services: request validation rejects a parameter the service doesn't know, and names it, so a misplaced key such as a top-level `poiCategories` fails with `INVALID_REQUEST` instead of being dropped silently
+  
+  - **Breaking:** services: an unknown parameter rejects with an `unrecognized_keys` issue, and one the service takes inside an object parameter points there: `poiCategories is not a parameter of AlongRouteSearch. Did you mean filters.poiCategories?`. The check reads only the parameters you pass, not the global configuration, and a parameter set to `undefined` counts as absent. `validateRequest: false` skips it
+  - **Breaking:** services: an along-route `discoverPlaces` with neither a `query` nor a filter other than `indexes` rejects in validation, rather than with the API's `400 "The requested route cannot be calculated"`
+  - services: `calculateRoute` validates `useEntryPoints`, `extendedRouteRepresentations` and `guidance`
+
+- [#2777](https://github.com/tomtom-internal/maps-sdk-js/pull/2777) [`158afa7`](https://github.com/tomtom-internal/maps-sdk-js/commit/158afa707ae299e93d9e55044595b1f2ee3183ab) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - **Breaking:** services: a request a service can't build, such as a geometry type geometry search doesn't take sent with `validateRequest: false`, rejects with an `SDKError` coded `INVALID_REQUEST` instead of a plain `Error`, so you can branch on `error.code` as for any other failed call
+  
+  - What the request builder threw is on `cause`, and the message is unchanged.
+  - If the parameters passed validation and the request still can't be built, the code is `INTERNAL`.
+
+- [#2749](https://github.com/tomtom-internal/maps-sdk-js/pull/2749) [`669e18c`](https://github.com/tomtom-internal/maps-sdk-js/commit/669e18c9e98582fa66ec1193fbac6061a8090948) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - **Breaking:** services: a rate-limited (`429`) call backs off 447 ms before its first retry by default instead of retrying at once, and each wait is drawn between half and all of the backoff, so clients rate-limited together don't retry together
+
+- [#2744](https://github.com/tomtom-internal/maps-sdk-js/pull/2744) [`d899f3f`](https://github.com/tomtom-internal/maps-sdk-js/commit/d899f3ffc413ef6182564d46deb67ec026ec7fc0) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - **Breaking:** services: `when` takes a `localDateTime`, a wall-clock time such as `'2026-10-19T08:15:00'` that the routing API reads in the origin's time zone, so you can route at 08:15 in Tokyo from a browser anywhere without a UTC offset
+  
+  - With `arriveBy`, `calculateRoute` reads a `localDateTime` in the time zone of the route's final destination. `calculateReachableRange` takes it with `departAt`
+  - The format is `YYYY-MM-DDTHH:mm:ss`, typed as `LocalDateTime`. Request validation rejects a time without seconds, with an offset or a `Z`, a date that doesn't exist, and a `when` with both or neither of `date` and `localDateTime`
+  - **Breaking:** `DepartArriveParams` is a union of `{ date }` and `{ localDateTime }`, so code reading `when.date` off it gets `Date | undefined`. Narrow it first, for example with `Extract<DepartArriveParams, { date: Date }>`. Passing `{ option, date }` is unchanged
+
+### Patch Changes
+
+- [#2697](https://github.com/tomtom-internal/maps-sdk-js/pull/2697) [`3d9c9a3`](https://github.com/tomtom-internal/maps-sdk-js/commit/3d9c9a34b897cf8eb791096620ed3e18dead1966) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - map: the style's 3D buildings have softened corners, rounded over the last metre of their walls, and the new `buildings3D.roundedCornerDistanceMeters` knob of `StylingFoundationsModule` sets how far the rounding reaches
+  
+  - map: `0` gives the sharp corners back, and a few metres rounds the buildings. A style that sets its own `fill-extrusion-rounded-corner-distance` keeps it
+  - examples: `map-styling-playground` adds a 3D buildings section with the knob
+
+- [#2768](https://github.com/tomtom-internal/maps-sdk-js/pull/2768) [`377e6db`](https://github.com/tomtom-internal/maps-sdk-js/commit/377e6db35cf111ae7dee92f5773cea951e8f93ed) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - core: `aggregateIntoCells` groups your points into hexagons, squares or your own polygons, such as districts, and gives each cell the median, mean, count, sum, min or max of a value, as GeoJSON polygons any map module draws
+  
+  - core: each point's grid cell comes from its coordinates, so large data sets stay fast, and the cells across the antimeridian stay side by side. `minCount` leaves out the cells with too few points, and `gridOrigin` keeps the cells in place while your points change
+  - map: `TrafficAreaAnalyticsModule` finds each tile's hexagon or square from its coordinates on the same cell grid, instead of testing it against every cell, and draws the same cells as before
+  - examples: `byod-geojson-cells-custom-module` colours Berlin by the median asking price per square metre in each hexagon or square
+
+- [#2746](https://github.com/tomtom-internal/maps-sdk-js/pull/2746) [`1d0f01d`](https://github.com/tomtom-internal/maps-sdk-js/commit/1d0f01d454e1906311653ba27e3cd28ead030a00) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - core: `servesGeopoliticalView(view, api)` tells whether the SDK sends a geopolitical view to an API, so you can label a result with the view its request carried
+  
+  - core: `GeopoliticalViewAPI` names the APIs it answers for: `'mapTiles'`, `'search'`, `'placeDetails'`, `'reverseGeocoding'` and `'geocoding'`
+  - map, services: the map's tiles and every search, place details, reverse geocoding and geocoding request decide which view to send from it, so your label and the request always agree
+  - examples: `geopolitical-views-playground` labels each address with the view its reverse geocoding request carried
+
+- [#2709](https://github.com/tomtom-internal/maps-sdk-js/pull/2709) [`d7c6017`](https://github.com/tomtom-internal/maps-sdk-js/commit/d7c6017d33623dfdd8f7157e34c846beed0e3518) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - core, services, map: exported classes keep their names in the minified bundles, so `SDKError.name` is `'SDKError'`, `TomTomConfig.name` is `'TomTomConfig'` and `RoutingModule.name` is `'RoutingModule'`
+
+- [#2747](https://github.com/tomtom-internal/maps-sdk-js/pull/2747) [`aa774bd`](https://github.com/tomtom-internal/maps-sdk-js/commit/aa774bd738ad7af7a8f9cd37b9036eb25ec3b158) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - map: Add your own credits to the map's attribution with `attribution: { credits }` on `TomTomMap`. They show next to TomTom's and stay across style switches.
+  
+  - examples: `byod-geojson-heatmap-custom-module` credits its listed-buildings dataset in the map's attribution
+
+- [#2727](https://github.com/tomtom-internal/maps-sdk-js/pull/2727) [`38c246a`](https://github.com/tomtom-internal/maps-sdk-js/commit/38c246acc98f827acb8ad9c039330d381a933f43) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - map: `setMapColors` paints city parks and sport grounds with `park` on every standard style, where `streetDark` and the mono styles gave them `artificial`'s colour
+  
+  - map: with `park` left unset, the parks keep the style's own colour whatever `artificial` is set to
+
+- [#2754](https://github.com/tomtom-internal/maps-sdk-js/pull/2754) [`7521d57`](https://github.com/tomtom-internal/maps-sdk-js/commit/7521d571a8528cc02badcc74b271cb7428c77aab) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - map: `TrafficIncidentDetailsModule` fades every incident outside the focus set with the new `highlight.unfocusedOpacityFactor`, so the incidents you focus are the ones that stand out
+  
+  - map: it fades their lines, icons and delay text while a focus is set, multiplies `line.opacity`, leaves a hovered or clicked incident at full strength and survives a style change. It's `1` by default, which leaves them as they are, and the `highlight.unfocusedOpacityFactor` knob sets it by id
+  - examples: `traffic-incident-details` fades the other incidents when you click one
+
+- [#2716](https://github.com/tomtom-internal/maps-sdk-js/pull/2716) [`f58a405`](https://github.com/tomtom-internal/maps-sdk-js/commit/f58a4058a7564b1e5ccaf0467b91df306914bf54) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - map: the map language labels the map in `zh-Hant`, `zh-Hans`, `ko-Latn-KR`, `ru-Latn-RU`, `ngt-Latn` and `nb-NO` too, where those showed the local name or the wrong script
+  
+  - examples: `map-language` offers Simplified and Traditional Chinese
+
+- [#2736](https://github.com/tomtom-internal/maps-sdk-js/pull/2736) [`a67b68d`](https://github.com/tomtom-internal/maps-sdk-js/commit/a67b68d05fc97280748c14ed433dbc55e437d6c5) Thanks [@AlvaroGraca-TomTom](https://github.com/AlvaroGraca-TomTom)! - map: with a proxy `commonBaseURL`, the map sends credentials and TomTom headers only to URLs on the proxy's own origin and under its path, not to a host or path that only starts with the same text
+
+- [#2742](https://github.com/tomtom-internal/maps-sdk-js/pull/2742) [`2fcc1ab`](https://github.com/tomtom-internal/maps-sdk-js/commit/2fcc1abc07bcdf89aff3942ff1207637ed00f419) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - core, services, map: the `license` field reads `SEE LICENSE IN LICENSE.txt`, the form npm and license scanners recognise, so they point to the package's own `LICENSE.txt` instead of reporting an unknown license
+
+- [#2714](https://github.com/tomtom-internal/maps-sdk-js/pull/2714) [`ae29916`](https://github.com/tomtom-internal/maps-sdk-js/commit/ae29916a1389e3d9ba9a5c378ea85c141d435389) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - services: `getSearchSuggestions` validates its own parameters before sending either request, so an invalid `filters.boundingBox` rejects under that name rather than `geoBias`, and an invalid call costs no request
+
+- [#2717](https://github.com/tomtom-internal/maps-sdk-js/pull/2717) [`d089a5c`](https://github.com/tomtom-internal/maps-sdk-js/commit/d089a5c3f7d1ce419a18a0dc8a26607b2f5263d3) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - services: geometry search sends a closed polygon ring of 50 vertices whole and samples a longer one to 50 evenly spaced vertices, where a ring just over a multiple of 50 sent as few as 26
+
+- [#2766](https://github.com/tomtom-internal/maps-sdk-js/pull/2766) [`22215a6`](https://github.com/tomtom-internal/maps-sdk-js/commit/22215a65286f7a6bd274c2aa6bb75cf81e5fee1e) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - services: `createLatestRequest({ supersede: 'on-answer' })` shows each answer of requests that start faster than they answer, such as a route re-planned during a drag, and never an older answer after a newer one
+
+- [#2705](https://github.com/tomtom-internal/maps-sdk-js/pull/2705) [`4ff91a2`](https://github.com/tomtom-internal/maps-sdk-js/commit/4ff91a2a6c9e62e5c3ec8db8f15e12d692d86aa3) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - services: along-route `discoverPlaces` rejects a `maxDetourTimeSeconds` above `3600`, the service's maximum, in request validation rather than after a round trip
+
+## 1.0.0-rc.3
+
+### Minor Changes
+
+- [#2674](https://github.com/tomtom-internal/maps-sdk-js/pull/2674) [`61026c0`](https://github.com/tomtom-internal/maps-sdk-js/commit/61026c0adaa35986bc0a9d11a3cdb4b342acb9d6) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - **Breaking:** core: ten plain POI sub-categories have codes of their own, such as `SCHOOL_GENERIC`, so a search can ask for plain schools without childcare or driving schools
+  
+  - **Breaking:** core: a place in one of them reads as its own code rather than its parent's. Where you match `SCHOOL`, `THEATER`, `SPORTS_CENTER`, `MARINA`, `WEIGH_STATION`, `OPEN_CAR_PARKING_AREA`, `COLLEGE_OR_UNIVERSITY`, `CAR_WASH`, `AMUSEMENT_PARK` or `TRAFFIC_CONTROL_DEPARTMENT` in `poi.categories`, match its `_GENERIC` code too
+  - **Breaking:** core: a `Record<POICategory, …>` needs an entry for each of the ten codes
+  - services: a `poiCategoryQuery` or `resolvePOICategories` word that names a plain sub-category best, such as `'rto'` or `'open car parking area'`, resolves to its `_GENERIC` code, which searches that sub-category alone rather than its parent and the parent's other sub-categories
+  - services: a word no longer spends one of its three codes on a sub-category of another code it already has, so `'medical'` and `'care'` also find `EMERGENCY_MEDICAL_SERVICE`
+  - map: a place with one of the new codes takes its parent's base-map icon, pin and `categoryIcons` entry
+
+- [#2659](https://github.com/tomtom-internal/maps-sdk-js/pull/2659) [`a580975`](https://github.com/tomtom-internal/maps-sdk-js/commit/a5809754b51feb9a1583cd23d149364e17727bb9) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - **Breaking:** map: a route's border crossings stand in a bubble above the route, the summary bubble's shape with its tail on the border, instead of a plaque on the route line; `countryCrossings.alignment` is removed with its knob and the `CountryCrossingAlignment` type, and crossings no longer carry a `bearing`
+  
+  - The default bubble takes the selected summary bubble's default colours, so it follows the light or dark style, `setMapColors()` and the `colors.label` and `colors.labelHalo` knobs: white on a light style, dark grey on a dark one, the map's label halo lightened under a theme. `countryCrossings.color` and `countryCrossings.label.color` still override either.
+  - A crossing hides where a waypoint pin, a summary bubble, another symbol drawn above it or a crossing close by would cover it, and shows again once there's room.
+  - Migration: drop `alignment` from `countryCrossings`. A bubble stays level with the screen.
+  - examples: `route-sections-playground` drops its crossing alignment control and gains a map look picker, light, dark and an amber theme, that the crossings follow.
+
+- [#2659](https://github.com/tomtom-internal/maps-sdk-js/pull/2659) [`a580975`](https://github.com/tomtom-internal/maps-sdk-js/commit/a5809754b51feb9a1583cd23d149364e17727bb9) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - services: an instruction's `pathPointIndex` is the route point at its maneuver, rather than the first point a few metres short of it, so it usually falls inside the `lanes` section leading to the maneuver
+  
+  - **Breaking:** a `lanes` section's `properties` read `IS_MANEUVER`, as documented, where they passed the API's `isManeuver` through. Match `'IS_MANEUVER'` instead.
+
+- [#2686](https://github.com/tomtom-internal/maps-sdk-js/pull/2686) [`5c52f46`](https://github.com/tomtom-internal/maps-sdk-js/commit/5c52f4619177d4776e32a167e871578ef4f4a2bf) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - **Breaking:** map: the types of place events, traffic features and waypoint ids match what the map hands your code
+  
+  - **Breaking:** map: under `pin-clustered`, a cluster no longer reaches the `events.places` handlers, which are typed `Place`, nor takes their hover and click states. The module-wide `events` receive it, with `cluster: true`, `cluster_id` and `point_count` in its properties
+  - **Breaking:** map: `roadSubcategory` is optional on `TrafficIncidentsModuleFeature`, and absent off `street` and `service` roads, as on `TrafficFlowModuleFeature`
+  - **Breaking:** map: a `TrafficFlowModuleFeature`'s geometry is a `LineString` or a `MultiLineString`, so check `geometry.type` before you read its coordinates
+  - **Breaking:** map: a waypoint keeps the id you give it, a number included, so `WaypointDisplayProps.id` is `string | number`
+
+- [#2650](https://github.com/tomtom-internal/maps-sdk-js/pull/2650) [`3ce0603`](https://github.com/tomtom-internal/maps-sdk-js/commit/3ce0603daadfa044b4797a25db21278f1c267302) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - **Breaking:** core: `getDistinctSections` finds the stretches each route has to itself, and `calculateRoute` returns them as `sections.distinct` whenever it returns two or more routes. `getImportantRoads` names the main roads a route takes, by road number
+  
+  - **Breaking:** core: `SectionType` and `sectionTypes` include `'distinct'`, which a request's `sectionTypes` can't ask for: the SDK adds it. A `Record<SectionType, …>` needs an entry for it
+  - **Breaking:** services: `InputSectionType` is only the types a request can ask for, so `leg` and `distinct` no longer compile in `sectionTypes`; type a list as `InputSectionTypes` rather than `SectionType[]`. `InputSectionTypes` is read-only, so build a list whole rather than `push` onto one. `inputSectionTypes`, `inputSectionTypesWithGuidance` and `sectionTypes` are read-only lists of their exact types
+  - core: each distinct section runs from where its route leaves the others to where it rejoins them, with its `lengthInMeters`, and `minLengthInMeters` leaves out the short ones
+  - core: `getSectionOverlap` gives the stretch two sections of one route share, whatever their types, as a `RouteSpan`
+  - core: `getSectionsWithin` lists a route's sections of every type within spans of it, such as the ferries, tolls and traffic on its distinct sections, with each section's share there to prorate a jam's delay
+  - core: `compareRoutes` tells what a route adds and avoids against a reference route, such as the selected alternative, or the route `costModel: { traffic: 'historical' }` gives, to say which jams and closures the live route avoids
+  - core: `getImportantRoads` groups a route's `importantRoadStretch` sections road by road, each with its `name`, its length and its stretches to ring with `setSectionFocus`; `within: sections.distinct` names what sets a route apart
+  - map: summary bubbles sit on their route's longest distinct section, read from `sections.distinct` when every route carries it, so a route crossing another at a junction keeps its whole stretch for the bubble
+  - examples: the `route-with-alternatives` and `react-route-planner` examples name the main roads of the stretches each route has to itself, and highlight a route the same way from the map or its card
+  - examples: each card in `route-with-alternatives` says what its route adds and avoids against the selected route, or against the usual route a toggle draws: ferries, car trains, tolls, closures, roadworks, traffic and unpaved roads
+
+- [#2675](https://github.com/tomtom-internal/maps-sdk-js/pull/2675) [`d1471c3`](https://github.com/tomtom-internal/maps-sdk-js/commit/d1471c3f69ed7a865e3e6b044632bd04c92271be) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - **Breaking:** map: a route you select with a click takes the selected style alone, and a feature an `events.where()` predicate rejects stays inert, so narrowing a click to the alternatives keeps the selected route from reacting to the pointer
+  
+  - **Breaking:** map: an `events.where()` predicate decides on the top-most feature under the pointer. One it rejects keeps the map cursor and takes no hover or click highlight, and the handler doesn't run, even with a matching feature beneath
+  - map: `selectRoute` clears the `click` state of the route lines and summary bubbles, so a route you select with a click no longer stays highlighted
+  - map: a long hover comes on the feature under the pointer when it comes due, so a still pointer no longer long-hovers a route as it was before a click selected it, which drew its wider outline
+  - examples: `route-summary-bubbles-playground` selects only alternatives on click
+
+- [#2688](https://github.com/tomtom-internal/maps-sdk-js/pull/2688) [`af7a24e`](https://github.com/tomtom-internal/maps-sdk-js/commit/af7a24e336bcd2062fa102e78e3614787f5888d5) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - services: **Breaking:** the service types say what each call returns and takes, from reverse geocoding and geometry data to the errors, and a call can set its own `retry`
+  - services: **Breaking:** `reverseGeocode` resolves a `ReverseGeocodingResponse`, a `Place` or, where nothing matches, the queried point without `properties`; checking `properties` narrows it to a `Place`
+  - services: **Breaking:** `geometryData` given a `Places` collection types each polygon's properties as `PlaceGeometryProps`, its place's properties plus `placeCoordinates`, and gives a polygon that matches no place `null` properties; a `Place[]` or geometry IDs return plain `PolygonFeatures`
+  - services: a service call's `retry` overrides the global one field by field, and `retry: undefined` turns retrying off for that call
+  - services: **Breaking:** a service call no longer takes `displayUnits`, which no service reads
+  - services: **Breaking:** `calculateReachableRanges` rejects a `404`, a `5xx` or an error without a status, as it does a `401`, `403` or `429`, and skips only the other `4xx`, such as the `400` `MAP_MATCHING_FAILURE` of an origin off the road network
+  - services: **Breaking:** `SDKError.service` is a `ServiceName`, the union of the services' names, and reachable ranges report `'ReachableRange'`, not `'Reachable Range'`
+  - services: **Breaking:** the wire-format types `PoiCategoriesResponseAPI`, `PoiCategoryAPI`, `PlaceDetailsResponseAPI` and `PlaceDetailsResultAPI` are no longer exported
+  - services: **Breaking:** `minFuzzyLevel` and `maxFuzzyLevel` take a `FuzzyLevel`, the whole numbers `1` to `4`
+  - core: **Breaking:** a route traffic section's `tec` is optional, and absent when the service sends no TEC codes
+
+### Patch Changes
+
+- [#2680](https://github.com/tomtom-internal/maps-sdk-js/pull/2680) [`46ecb86`](https://github.com/tomtom-internal/maps-sdk-js/commit/46ecb861d06cbfbc9cc952f098ae31d68528c6c3) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - core: `languages` is a runtime export, and the distance formatter, bounding-box and route helpers handle their edge cases
+  
+  - core: `formatDistance` rounds below 10 m to one decimal, rounds a negative distance to the same magnitude as its positive, rounds feet and yards once rather than twice, and takes `undefined`
+  - core: `bboxCenter` centres a box that crosses the antimeridian, and `bboxFromGeoJSON` reads the 2D edges of a 3D `bbox`
+  - core: `getProgressAtNearestRoutePoint` returns `undefined` on a route under two coordinates, rather than throwing
+  - core: `getCoordinateAtRouteProgress` returns `undefined` past an end whose progress entry lacks the value, rather than `0`
+  - core: `findBestWaypointInsertionIndices` and `withInsertedWaypoints` prepend on a route under two coordinates
+  - core: `getRouteProgressForSection` and `getSectionBBox` take any `RouteSpan`, such as the one `getSectionOverlap` returns
+  - core: `TomTomConfig.instance.reset()` restores the retry defaults, even after a caller edited `get().retry`
+
+- [#2659](https://github.com/tomtom-internal/maps-sdk-js/pull/2659) [`a580975`](https://github.com/tomtom-internal/maps-sdk-js/commit/a5809754b51feb9a1583cd23d149364e17727bb9) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - core: `getInstructionLanes(route, instruction)` finds the `lanes` section leading to an instruction's maneuver, so a directions panel can show the lanes to take under each step
+  
+  - examples: `route-with-guidance` lists its instructions in a Directions panel, and both it and `react-route-planner` draw the lanes to take under each instruction that has them, as a small SVG sign of their own.
+
+- [#2687](https://github.com/tomtom-internal/maps-sdk-js/pull/2687) [`7ff2c57`](https://github.com/tomtom-internal/maps-sdk-js/commit/7ff2c5703f66f90c521d192a65a622ad439562f2) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - map: images without a DOM, base-map places under offset POI icons and a module's `events.off()` handle their edge cases
+  
+  - map: a module given an SVG image where there is no DOM, as in a server render or a Node.js test, adds no image rather than throwing a `TypeError`
+  - map: a `base-map` place keeps the style's icon offset when `POIsModule` offsets its own `categoryIcons` entry for the same category, rather than drawing its sprite that many pixels away
+  - map: `events.off('shown-features')` stops compiling on a module with no `show` method, which never emits that event, as `events.on('shown-features', …)` already did
+
+- [#2695](https://github.com/tomtom-internal/maps-sdk-js/pull/2695) [`7f4c439`](https://github.com/tomtom-internal/maps-sdk-js/commit/7f4c4393b880abcb828f719f9b099d87f40f24a0) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - map: geometries and reachable ranges can blend `fill.palette` from its first colour to its last, fade the bands away from the origin, and dash or dot their borders
+  
+  - map: `fill.paletteMode: 'ramp'` shades the features, or the bands, evenly from the palette's first colour to its last, blended in OKLCH. `'cycle'`, the default, takes the colours in turn as before
+  - map: `ReachableRangesModule`'s `fill.outermostOpacityFactor` multiplies the outermost band's fill opacity, and steps the bands between evenly from the innermost one. A lone range takes the factor
+  - map: `line.pattern` (`'solid'`, `'dashed'` or `'dotted'`) breaks up the borders of `GeometriesModule` and `ReachableRangesModule`, scaled with the border width
+  - map: the new settings are knobs of `geometriesKnobCatalogue` and `reachableRangesKnobCatalogue`
+  - map: `LinePattern` now types every line pattern; `SectionLinePattern` is deprecated in its favour
+  - examples: `geometry-config-playground` sets the border pattern, `multiple-geometries` swaps palettes and switches them between cycling and ramping, and `reachable-ranges-playground` offers two- and five-colour palettes to ramp
+
+- [#2698](https://github.com/tomtom-internal/maps-sdk-js/pull/2698) [`b7be724`](https://github.com/tomtom-internal/maps-sdk-js/commit/b7be7243dcf5df5897ea6ef3053eb382588a72e6) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - map: light the 3D buildings with the `view.light` knobs of `StylingFoundationsModule`, kept across style switches
+  
+  - `view.light.direction`, `view.light.altitude`, `view.light.alignment`, `view.light.color` and `view.light.intensity` set MapLibre's light. A part you leave unset takes the style's own light, otherwise MapLibre's default
+  - `stylingFoundationsKnobKinds` gains `number`, the kind of the direction, altitude and intensity
+  - `exportStyle()` carries the light the knobs set
+  - Once a light knob has been set, a clean `setStyle(…, { resetState: true })` draws the new style's light, rather than keeping the one the knobs had set
+  - examples: `map-styling-playground` shows the light knobs in a View light section
+
+- [#2658](https://github.com/tomtom-internal/maps-sdk-js/pull/2658) [`80d6897`](https://github.com/tomtom-internal/maps-sdk-js/commit/80d68974f433320a332b59dea66c0904a0118349) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - map: road shields, POI icons and road patterns no longer go missing when the map's own sprite loads more slowly than the place pins' sprite
+
+- [#2685](https://github.com/tomtom-internal/maps-sdk-js/pull/2685) [`9825c67`](https://github.com/tomtom-internal/maps-sdk-js/commit/9825c67233d1175c668fff544c92c916bf474297) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - map: modules keep their state across style switches, routes draw with a traffic halo, and events, images and knobs handle their edge cases
+  
+  - map: `RoutingModule` draws its routes when `sections.traffic.style` is `'halo'`, at creation, after a style switch and when switched at runtime
+  - map: `routeIndex` on route sections, summary bubbles and border crossings is the route's position among the shown routes, so `selectRoute` and clicks work when only some routes are shown
+  - map: `selectRoute` waits for the module before reading the shown routes, so a `showRoutes` it follows unawaited keeps its routes; a new `showRoutes` starts its summary bubbles with no click state
+  - map: route jam labels follow `displayUnits.time`, and a speed limit that changes at a border takes the country the route enters
+  - map: speed-limit signs anchor to their own instance's layers, and go to the top on a style without their usual anchor
+  - map: `PlacesModule` restores what it showed synchronously on a style switch, repaints its default pin when created with no config, and no longer fires `shown-features` for the restore
+  - map: a place category icon with no image resolves to the sprite's own id, a `poiCategory` icon mapping draws the `categoryIcons` entry for the category it returns, and `layers.*.layout` overrides win over the computed text and icon offsets
+  - map: `POIsModule` keeps its category icons after a `setStyle` to the style already loaded, and `FOOD_DRINKS_GROUP`, `HEALTH_GROUP` and `ENTERTAINMENT_GROUP` no longer pull in delicatessens, welfare organisations and clubs
+  - map: a centre title keeps its own hover and click state rather than its polygon's, and two identical reachable ranges no longer shade the inverted style
+  - map: raw layer edits stay on top of every module's knobs, a preset switch fires `config-change` once per module, and an unknown preset id such as `'toString'` throws the documented error
+  - map: event handlers survive a style switch that leaves their scope with no layers, hover detects a feature with id 0 and the same id in two sources, and a handler that unsubscribes mid-dispatch no longer skips the next one
+  - map: a slow image load no longer overwrites a newer image or re-adds a removed one, and `addOrUpdateImage` leaves a caller's `onload` alone
+  - map: a `setStyle` called before the first style load finishes on the style it asked for, or on the first style when its own fails to load
+  - map: `TrafficAreaAnalyticsModule` moves its hover outlines and highlights with their cells on a `beforeLayerConfig` change, and its heatmap stays valid when every tile has the same value
+  - map: an incident with an average speed of 0 km/h keeps it, and the jam delay label rounds to whole minutes first, with a marker sized for the rounded label
+  - map: `CustomGeoJSONModule` gives a feature with no id one no other feature holds, keeps a layer hidden that its spec sets to `visibility: 'none'`, re-adds an image whose options change, and no longer fires `shown-features` on a style switch
+  - map: a retry after the first style fails to load loads it, and a `setGeopoliticalView` or `setLanguage` called mid-switch applies once the map is ready without undoing a later call
+  - map: a display-units change keeps the hover and click states of route jams and speed-limit signs, `showWaypoints` draws with a config applied while it waited, a waypoint Feature with `properties: null` no longer throws, and speed-limit signs show mph in Jersey, Guernsey, the Isle of Man, the US territories, seven British Overseas Territories, eight Caribbean states and Samoa
+  - map: a dotted ferry or tunnel line draws its dots, and a named routing layer override placed under another routing layer, by its bare name or its full id, lands there rather than on top
+  - map: `PlacesModule` keeps entry point and connection event states across a style switch, a cluster rebuild and a config change, and a custom icon's label offset accounts for its `pixelRatio` and an SVG's drawn size, an SVG with only a width or a height taking the other from its viewBox
+  - map: `POIsModule` no longer turns on micro markers the style hides, `styling.layers` visibility edits no longer show a layer a module hides, a style sky that draws nothing no longer hides the theme sky while one with colours but no atmosphere counts as shown, and base-map group knobs apply in the order given
+  - map: an events scope you hold registers on the current sources after a style switch, clicking the empty map clears a click state set before one, an `on()` unsubscribe removes only its own registration, and a hovered place redrawn as selected doesn't fire `hover` twice
+  - map: a layer added in the same config change follows the layer it is pinned under when that layer moves
+  - map: geometries with their own ids keep them, and their event states, after a config change
+  - map: area analytics cells stop at `maxMeters`, their hover outlines and highlights follow the metric filter, and an empty `colorStops` falls back to the palette; `TrafficIncidentDetailsModule.show()` keeps the layers its `layers` config hides; an incident delay or report count of 0 is kept
+  - map: `calculateFittingBBox` clamps latitudes to the Web Mercator range and handles a box across the antimeridian, and `calculatePaddedBBox` covers a rotated map and cuts a panel touching one edge from its closest edge
+  - map: a module's `applyConfig` and `resetConfig` reach the event handlers already registered, so a new hover cursor or grace period applies, and a click on a cluster whose id matches a shown feature's hands the handler the cluster
+  - map: `TrafficFlowModule`, `TrafficIncidentsModule` and `TerrainModule` show and hide their layers alongside `styling.layers` edits, so an edit no longer shows traffic or a hillshade the module hides, and `BaseMapModule` no longer misrecords an `all-except` visibility for a layer group the style has no layers for
+  - map: a section's halo no longer vanishes under the route outline when the section sets a narrower `widthFactor` or `widthPreset`, and setting `countryCrossings.visible: true` while they are shown keeps a clicked crossing's state
+  - map: a `setStyle` call a newer one supersedes resolves even when its style fails to load, as documented
+  - map: area analytics extrusion highlights follow an extrusion height that ramps with zoom
+  - map: `POIsModuleSerializableConfig` is exported, and `stylingFoundationsKnobIds` is `readonly` like the other modules' knob id lists, so code that mutates it stops compiling
+  - map: `PlaceLayerName` leaves out `'additional'`, which names no layer, and `RouteLayersConfig.sections` names only the layers each type draws: `speedLimit` its sign layer, the other generated types their line and icon layers
+  - map: `PlacesModule.updateData` and a show after a config change drop the category, icon and extra properties the previous config added, and a custom module's layers that reference each other stack in dependency order at creation, on `applyConfig` and after a style switch
+  - map: `CustomGeoJSONLayerSpec` takes only the six layer types a GeoJSON source draws (circle, line, fill, fill-extrusion, symbol and heatmap)
+  - map: a route module with only some `displayUnits` of its own follows a global unit-system change for the rest
+  - map: a POIs event handler no longer receives base-map features, nor a base-map handler POI ones, and a `recently-hovered` state clears after its handler unsubscribes
+  - map: area analytics fall back to the defaults for each fill and line field left `undefined`, an inverted display cuts every region out of the mask, and `setHeight(undefined)` clears the extrusion height
+  - map: a jam with a delay of 0 shows no "1 min" marker, and a whole-hour jam delay gets the small sprite
+  - map: `setLayout` takes `visibility` as `'visible'` or `'none'` only, since a visibility expression was drawn as always visible, and `getStyleInput()` is typed as never `undefined`
+  - map: routes relabel on the next config change after a global display-units change, a style switch in between included, and a layer override's `reset()` after a style switch restores the new style's value, or after a `setStyle` to the style already loaded the value it replaced
+  - map: an `off()` followed by a style switch no longer leaves a hover, click or recently-hovered state stuck on a source
+  - map: a place config change gives back the place's own value of a property an `extraFeatureProps` entry replaced, and a clicked `micro` dot under `pin-clustered` keeps its state across a config change and a style switch
+  - map: `CustomGeoJSONModule.applyConfig` throws a clear error before changing anything when the config names other sources or `sourceID`s than the module was created with, where it used to apply half of it
+  - map: area analytics hover and click highlights stay off the cells a layer filter hides
+
+- [#2692](https://github.com/tomtom-internal/maps-sdk-js/pull/2692) [`cbc4dc9`](https://github.com/tomtom-internal/maps-sdk-js/commit/cbc4dc9857d306db1eca93d1e9d5a23b1f901141) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - core, services, map: the package now installs on Node.js 22 with any package manager
+  
+  - The `engines` field asks for Node.js 22 or newer instead of 24, and no longer names a pnpm version, so npm and pnpm stop warning about it on Node.js 22 and `engine-strict` installs succeed
+
+- [#2676](https://github.com/tomtom-internal/maps-sdk-js/pull/2676) [`383a6c6`](https://github.com/tomtom-internal/maps-sdk-js/commit/383a6c6e62ce6a183bc1a062a7fa88be5fd7278f) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - map: Fade a route, the traffic overlays, the incidents you show and your place icons, each with one opacity setting
+  
+  - `RoutingModule` `opacity` fades the route lines and their outlines, selected and deselected; sections keep `sections.<type>.opacity`
+  - `TrafficFlowModule` and `TrafficIncidentsModule` `opacityFactor` multiply the style's own line opacity, its zoom ramp kept; the incident icons stay opaque
+  - `TrafficIncidentDetailsModule` `line.opacity` fades the incident lines; the markers and the highlight outline stay opaque
+  - `PlacesModule` `icon.opacity` fades the icons of every marker type, the cluster pin included; a selected place stays opaque
+  - Each is a knob in its module's catalogue
+  - `route-styling-playground` fades the route through `opacity`, `places-customize-playground` gains an icon opacity slider, and `traffic-incident-focus` fades the flow through `opacityFactor`
+
+- [#2681](https://github.com/tomtom-internal/maps-sdk-js/pull/2681) [`97c0508`](https://github.com/tomtom-internal/maps-sdk-js/commit/97c050866cb312ca1c4e3cfa22c8cbc4d116fd46) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - services: `calculateReachableRange` rejects an arrival time with a message that shows the `when` shape to use instead, `when: { option: 'departAt', date }`
+
+- [#2642](https://github.com/tomtom-internal/maps-sdk-js/pull/2642) [`1d75842`](https://github.com/tomtom-internal/maps-sdk-js/commit/1d75842ba862bf87648eb33beef02d64df7db366) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - map: Choose what a route's summary bubble says, its colour, typeface and the zooms it shows at, or write your own text per route
+  
+  - `summaryBubbles.fields` lists `duration`, `distance` and `trafficDelay` in the order shown; a bubble with nothing to say isn't drawn, so `['trafficDelay']` shows bubbles on delayed routes alone
+  - `summaryBubbles.minZoom`, `maxZoom`, `color` and `label` (`color`, `size`, `opacity`, `typeface`, `customTypeface`) are knobs in `routingKnobCatalogue`, all but `customTypeface`
+  - `summaryBubbles.label.title` takes a function of the route's summary, or a MapLibre expression, and writes its text in place of the fields
+  - The bubbles now follow the map: a theme's `labelHalo` and `label` colours once one sets them, else dark bubbles and light text on a dark style
+  - New `route-summary-bubbles-playground` example, its panel built from the catalogue
+
+- [#2643](https://github.com/tomtom-internal/maps-sdk-js/pull/2643) [`507e4e5`](https://github.com/tomtom-internal/maps-sdk-js/commit/507e4e52902adbd216ecc9cd8d45c60e7b7b02fd) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - map: Summary bubbles keep clear of each other, show on the routes you choose and give each alternative's time against the selected route
+  
+  - Each bubble sits on a stretch of road its route has to itself, so routes sharing a motorway no longer hide each other's bubble, and it stays put when another route is selected
+  - `summaryBubbles.routes` shows the bubbles on `all` routes, the `selected` one alone or its `alternatives`
+  - The `durationDifference` field writes each other route's time against the selected one, such as `+6 min`, and `selectRoute` re-times the bubbles
+  - The `route-summary-bubbles-playground` example opens with bubbles timed against the selected route
+
+- [#2684](https://github.com/tomtom-internal/maps-sdk-js/pull/2684) [`eb4da3f`](https://github.com/tomtom-internal/maps-sdk-js/commit/eb4da3f3cad8af1ddc9c4e9d926736fd4a104ab1) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - services: validation catches the inputs that used to crash or reach the API, and routing, search suggestions and the shared pipeline handle their edge cases
+  
+  - services: validation rejects, as `INVALID_REQUEST`, what used to throw a plain `Error` or come back as a 400: an empty Polygon or a Point in `geometrySearch`, an impossible date such as `'2024-02-30'` in `trafficAreaAnalytics`, more than 100 incident ids, a non-integer fuzzy level or a `minFuzzyLevel` above `maxFuzzyLevel`, a routing avoid area with no bounding box, a one-point path, a non-integer `maxAlternatives`, an along-route search route under two positions, a zero reachable-range budget, a non-integer or out-of-range `limit` or `heading`, and an undefined `commonBaseURL`
+  - services: validation also rejects an empty array as a route location, a stop's `candidateEntryPoints` off the globe or `preferredEntryPointIndex` past them, an empty `geometrySearch` geometry list or ring, `days` beside an `endDate` in `trafficAreaAnalytics`, and a bare bbox of other than four numbers; it now accepts a GeometryCollection where a bounding box is read, bare or inside a Feature or FeatureCollection, and the documented `weightKG: 0`
+  - services: validation checks GeoJSON input against its type: a route waypoint's position, every position of a path, an along-route search route or a polygon ring, and a `geometrySearch` Circle centre must be on the globe, a bounding box can't be an empty array or collection, a path given as a Feature must hold a LineString, a stop's `pauseDurationSeconds` can't be negative and its `legCostModel` takes only known route types and avoid values, a geometry's coordinates must match its `type`, and a GeoJSON `bbox` must hold 4 or 6 numbers; `extendedPostalCodesFor`, `mapcodes`, `openingHours`, `timeZone`, `relatedPois` and `filters.indexes` reject values outside their types
+  - services: a validation error from a union schema lists what each branch rejected
+  - services: `onAPIResponse` receives the API's response body, as its type says, rather than the fetch envelope, and fires once per call
+  - services: proxy-credentials mode is decided per call, so a call with its own `apiKey` no longer sends `credentials: 'include'` under a global proxy setup
+  - services: an error response labelled JSON whose body doesn't parse still rejects with its status
+  - services: `calculateRoute` keeps the leg point indices right after a one-coordinate first leg, gives a road-shield section with no references `[]`, no longer lets an origin's `candidateEntryPoints` override `useEntryPoints`, maps TEC cause codes 16, 22 and 23 to `'other'` as the TPEG2-TEC table defines them, and gives each instruction with no road info an object of its own
+  - services: `trafficAreaAnalytics` no longer throws a `RangeError` over a region with hundreds of thousands of tiles, and `calculateReachableRanges` stops listening to the batch's abort signal once each call settles
+  - services: `getSearchSuggestions` shows a brand asked for alongside address-type kinds
+  - services: `getSearchSuggestions` no longer offers a category refinement whose `refine()` fails for a category id the SDK doesn't know, and leaves out autocomplete segments of a type the SDK doesn't know
+  - services: `getPOICategories` and `resolvePOICategories` validate their parameters and reject with `SDKAbortError` on an aborted signal even when the cache or the known codes answer the call
+  - services: `SDKServiceError.status` is `readonly`, like the other error fields
+  - services: `geocode` keeps in `geographyType` only the types core's `geographyTypes` lists, and rejects `extendedPostalCodesFor: ['POI']` as `INVALID_REQUEST`
+  - services: a blank `poiCategoryQuery` rejects rather than searching with no category filter
+  - services: `calculateReachableRanges` no longer needs `AbortSignal.any`, which React Native lacks, and the search cursor no longer needs `atob` and `btoa`
+  - services: a search or geocode result at distance 0 keeps its `distance`, Kosovo's `XK` maps to `XKX`, and `getPOICategories` hands out a copy of its cache
+  - services: `VehicleModel` and `VehicleDimensions` are exported
+  - core: `TomTomConfig.instance.put` drops `undefined` retry fields rather than storing them over the defaults
+
+- [#2690](https://github.com/tomtom-internal/maps-sdk-js/pull/2690) [`e56d293`](https://github.com/tomtom-internal/maps-sdk-js/commit/e56d293fdc713cd7301713ac16bdc1ff581910d4) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - core, services, map: an app now bundles only the SDK code its imports use, so most single imports come out far smaller
+  
+  - core: importing one helper, such as `generateId`, bundles under 1 KB minified instead of about 30 KB with lodash
+  - services: `geocode` bundles about 14 KB minified instead of 68 KB, and `calculateRoute` 32 KB instead of 86 KB, with lodash
+  - map: `TomTomMap` bundles about 44 KB minified on top of MapLibre instead of 123 KB, with lodash
+  - core, services, map: the package declares `sideEffects: false`, so bundlers drop the modules an app doesn't import
+
+- [#2700](https://github.com/tomtom-internal/maps-sdk-js/pull/2700) [`f0d3922`](https://github.com/tomtom-internal/maps-sdk-js/commit/f0d392242f16d86eaf4aa0fd7f1b44888295e8ee) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - map: a route's speed limit signs draw from zoom 12.5 by default instead of 11, two and a half zooms after the tunnel and closed-road signs, so they no longer crowd the overview of a route; `sections.speedLimit.sign.minZoom` still sets it, in steps of half a zoom in `routingKnobCatalogue`
+  
+  - examples: `route-speed-signs` sets `sign.minZoom` to 10, so its tiles post the signs on a whole route; `route-sections-playground` moves its `sign.minZoom` slider by half a zoom
+
 ## 1.0.0-rc.2
 
 ### Minor Changes

package/README.md

@@ -60,12 +60,14 @@ It's built on [MapLibre GL JS](https://docs.tomtom.com/maps-sdk-js/guides/map/ab
 
    Then follow the [Map quickstart](https://docs.tomtom.com/maps-sdk-js/guides/map/quickstart) or the [Services quickstart](https://docs.tomtom.com/maps-sdk-js/guides/services/quickstart), or start from a runnable app in the [examples gallery](https://docs.tomtom.com/maps-sdk-js/examples/).
 
+<!-- The public repository's README opens with everything above this line: keep this line verbatim, and every link above it valid there. -->
+
 ### Requirements
 
-- **Node.js 24+** at install time, the minimum the package declares, whether or not you target the browser.
+- **Node.js 22+** at install time, the minimum the package declares, whether or not you target the browser. Any package manager works: npm, pnpm or Yarn.
 - **A browser with WebGL** for the Map bundle.
 - **A bundler** such as Vite or webpack, because the SDK ships as ES modules. Under Vite, `TomTomMap` sets up MapLibre's web worker on its own; [Vite projects](https://docs.tomtom.com/maps-sdk-js/introduction/project-setup#vite-projects) says when another bundler, such as webpack, needs it set up by hand.
-- **Peer dependencies**, installed by the commands above: MapLibre GL JS 6.13+, Turf 7, culori 4, Lodash 4 and Zod 4.
+- **Peer dependencies**, installed by the commands above: MapLibre GL JS 6.15+, Turf 7, culori 4, Lodash 4 and Zod 4.
 - **TypeScript is optional**: the type definitions ship with the package, with no `@types` package to install.
 
 [Project setup](https://docs.tomtom.com/maps-sdk-js/introduction/project-setup) has the full requirements and the [React, Vue and Node.js](https://docs.tomtom.com/maps-sdk-js/introduction/project-setup#framework-specific-setup) setups.
@@ -127,8 +129,9 @@ Separate packages, each declaring the SDK as a peer dependency:
 | [**Map Theme**](https://docs.tomtom.com/maps-sdk-js/guides/plugins/map-theme) | Themes the map from a brand's swatches, your page's CSS, a logo or a photo |
 | [**Map Effects**](https://docs.tomtom.com/maps-sdk-js/guides/plugins/map-effects) | Post-processing such as bloom, depth of field, colour grading and vignette, on any style |
 | [**Fly-over**](https://docs.tomtom.com/maps-sdk-js/guides/plugins/flyover) | A camera that flies along a route, framing the junctions ahead |
+| [**Route dragging**](https://docs.tomtom.com/maps-sdk-js/guides/plugins/route-dragging) | Lets your users edit a route by dragging its stops and its line, re-planned as they drag |
 | [**Viewport places**](https://docs.tomtom.com/maps-sdk-js/guides/plugins/viewport-places) | Keeps search results for the visible map area on the map as it moves |
-| [**Landmarks 3D**](https://docs.tomtom.com/maps-sdk-js/guides/plugins/landmarks-3d) | Detailed 3D models of recognizable buildings, in Private Preview |
+| [**Landmarks 3D**](https://docs.tomtom.com/maps-sdk-js/guides/plugins/landmarks-3d) | Detailed 3D models of recognizable buildings, in Private Preview, and the base map's buildings in 3D with windows, lights and shadows |
 
 ## Coming from MapLibre GL JS
 
@@ -148,6 +151,7 @@ Where the SDK has a feature for the job, prefer it. It survives style switches a
 - [**Where your API key runs**](https://docs.tomtom.com/maps-sdk-js/guides/security/where-your-api-key-runs): anyone who opens the page can read a key used from the browser, but not one used from Node.js.
 - [**Proxying your API calls**](https://docs.tomtom.com/maps-sdk-js/guides/security/proxying-api-calls): keep the key on your server by routing the SDK's requests through your own proxy, then [harden that proxy](https://docs.tomtom.com/maps-sdk-js/guides/security/hardening-your-proxy).
 - [**What the SDK sends, and where**](https://docs.tomtom.com/maps-sdk-js/guides/security/what-the-sdk-sends): the data your users' browsers send to TomTom, for your privacy notice.
+- [**Reporting a vulnerability**](https://github.com/tomtom-international/maps-sdk-js/blob/main/SECURITY.md): report it privately, never in a public issue.
 
 ## Resources for AI agents
 

package/THIRD_PARTY.txt

@@ -152,7 +152,7 @@ terms above.
 ---
 
 Name: maplibre-gl
-Version: 6.13.0
+Version: 6.15.0
 License: BSD-3-Clause
 Bundled: false (peer dependency)
 Required by: map
@@ -283,7 +283,7 @@ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 ---
 
 Name: zod
-Version: 4.6.5
+Version: 4.6.7
 License: MIT
 Bundled: false (peer dependency)
 Required by: services