@tomtom-org/maps-sdk 0.64.0 → 1.0.0-rc.0

package/CHANGELOG.md

@@ -1,5 +1,77 @@
 # Changelog
 
+## 1.0.0-rc.0
+
+### Major Changes
+
+- [#2482](https://github.com/tomtom-internal/maps-sdk-js/pull/2482) [`e6590f2`](https://github.com/tomtom-internal/maps-sdk-js/commit/e6590f20417dea946a55d3201d50d29ce32a9697) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - core, services, map: 1.0.0, the first stable release of the SDK. The *Upgrading to 1.0 from a 0.x release* guide lists every change to apply from a 0.x release.
+
+### Minor Changes
+
+- [#2490](https://github.com/tomtom-internal/maps-sdk-js/pull/2490) [`62c5726`](https://github.com/tomtom-internal/maps-sdk-js/commit/62c572635b97c084af81b08b2b6b84f338c193ca) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - **Breaking:** core, services, map: the error codes take the TomTom Navigation SDK's names: `API_KEY_REJECTED` is `INVALID_CREDENTIALS`, `SERVICE_UNAVAILABLE` is `LIVE_SERVICE_NOT_AVAILABLE`, `NETWORK_ERROR` is `NETWORK_NOT_AVAILABLE` and `UNEXPECTED` is `INTERNAL`
+  **Breaking:** core, services, map: a `403` is `INSUFFICIENT_PERMISSIONS`, a valid key not allowed the request, and `INVALID_CREDENTIALS` is a `401` only, a key the API does not know
+  - services, map: `SDKError.canRetry` and `TomTomMapError.canRetry` are `true` for `RATE_LIMITED`, `LIVE_SERVICE_NOT_AVAILABLE` and `NETWORK_NOT_AVAILABLE`, the failures that clear on their own
+  - services: a `403` keeps the API's message, and `SDKServiceError.apiErrorCode` holds the API's own code: `'Forbidden'` when the API is not enabled for the key, `'InvalidReferer'` when its domain restriction refused the page
+  - services: `calculateReachableRange` and `calculateReachableRanges`, in Private Preview, name the access a key lacks, and link the Private Preview terms, in the message; the access is also in `SDKServiceError.privatePreviewAccess`, `{ product, requestAccessURL }`
+  - map: a style, tile, sprite or glyph answered `403` reaches the error handlers as `INSUFFICIENT_PERMISSIONS`
+
+- [#2512](https://github.com/tomtom-internal/maps-sdk-js/pull/2512) [`f8e49db`](https://github.com/tomtom-internal/maps-sdk-js/commit/f8e49dbf1876097b2a0c62cf5e6c1e1feb494178) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - **Breaking:** map: the sky, space, incident delay and hillshade knobs are named as every other knob is: a part's settings sit under it, and no name repeats its parent
+  - map: `StylingFoundationsModule` knob ids `view.sky`, `view.skyColor`, `view.horizonColor` and `view.spaceColor` are `view.sky.visible`, `view.sky.color`, `view.sky.horizonColor` and `view.space.color`, in `styleColorKnobIds`, `getStyleColor` and map presets too
+  - map: `TrafficIncidentsModule` `filters: { delays: { mustHaveDelay, minDelayMinutes } }` is `filters: { delays: { required, minMinutes } }`, and the knob ids follow
+  - map: `TerrainModule` `hillshade: { lightDirection, exaggeration, shadowColor, highlightColor, accentColor }` is `hillshade: { light: { direction }, intensity, colors: { shaded, lit, steep } }`, and the knob ids follow, in `styleColorKnobIds` and `getStyleColor` too; `exaggeration` is now only the raised surface's vertical scale
+  - agent-toolkit: `setMapStyling`'s globe example sets `view.sky.visible`
+
+- [#2485](https://github.com/tomtom-internal/maps-sdk-js/pull/2485) [`ac09c1e`](https://github.com/tomtom-internal/maps-sdk-js/commit/ac09c1e37d192837467d6575ce8bc99464e11455) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - **Breaking:** map: `PlacesKnob` and the traffic knob types list only the kinds their catalogues hold, so a `switch` over their `kind` drops the cases no entry reaches
+  - `PlacesKnob` no longer includes `text`
+  - `TrafficFlowKnob`, `TrafficIncidentsKnob`, `TrafficIncidentDetailsKnob` and `TrafficAreaAnalyticsKnob` no longer include `image`
+
+- [#2505](https://github.com/tomtom-internal/maps-sdk-js/pull/2505) [`308c3af`](https://github.com/tomtom-internal/maps-sdk-js/commit/308c3af3a5375b12293b2018413f4f78286739d6) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - **Breaking:** map: the last config properties and knob ids off the shared vocabulary follow it: a size preset is a `*Preset`, a fill style sits under `fill`, and a unit is named once
+  - map: `GeometriesModule` and `ReachableRangesModule` take `fill: { style }` instead of `fillStyle`, and `TrafficAreaAnalyticsModule` `regionPolygon: { fill: { style } }` instead of `regionPolygon.fillStyle`; a feature's `properties.fillStyle` stays
+  - map: `RoutingModule` `width`, `sections.<type>.width` and `waypoints.size` are `widthPreset`, `sections.<type>.widthPreset` and `waypoints.sizePreset`
+  - map: `PlacesModule` `cluster.source` takes `radius`, `maxZoom`, `minPoints` and `properties` instead of MapLibre's `clusterRadius`, `clusterMaxZoom`, `clusterMinPoints` and `clusterProperties`, typed by `PlacesClusterSourceConfig`
+  - map: `PlacesModule` `label.offset` is `label.distance`, since an `offset` is an `[x, y]` displacement on every module
+  - map: `TrafficAreaAnalyticsModule` `height.maxHeightMeters` and `height.minHeightMeters` are `height.maxMeters` and `height.minMeters`, in `setHeight` too
+  - map: each renamed property's knob id follows it
+  - agent-toolkit: the tools keep their parameters, and the plugin needs SDK 1.0.0-rc.0
+
+- [#2489](https://github.com/tomtom-internal/maps-sdk-js/pull/2489) [`640b53b`](https://github.com/tomtom-internal/maps-sdk-js/commit/640b53bf1c0ea20ce996053ee2f1a664310a381d) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - **Breaking:** map: the map loads TomTom standard styles only, so a custom style URL or style JSON no longer loads
+  - `StyleInput` no longer takes `{ type: 'custom', url }` or `{ type: 'custom', json }`, and `CustomStyle` and `CustomStyleSource` are no longer exported
+  - `lightDarkTheme` is gone with them: `map.styleLightDarkTheme` follows from the standard style ID
+  - Restyle a standard style at runtime with `StylingFoundationsModule` and `setMapColors` instead
+
+- [#2495](https://github.com/tomtom-internal/maps-sdk-js/pull/2495) [`530b895`](https://github.com/tomtom-internal/maps-sdk-js/commit/530b8955ebe0d6724b9dc14d5a0d08a37e4b4df8) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - **Breaking:** core, services, map: the SDK no longer offers real-time EV charging availability, nor routes and reachable ranges planned on a vehicle consumption model; search results keep their static EV station data
+  - services: `evChargingStationsAvailability`, `getPlacesWithEVAvailability`, `getPlaceWithEVAvailability` and `hasChargingAvailability` are removed
+  - services: long-distance EV routing is removed: `vehicle.preferences`, `chargingStopsStrategy` and `chargingStopsStrategies`
+  - services: `vehicle` takes `model.dimensions.weightKG`, `state.heading` and `restrictions` only: `engineType`, `model.engine`, `model.variantId` and the charge and fuel state are removed, with the electric, combustion and generic vehicle types
+  - core: the reachable-range budgets `remainingChargePCT`, `spentChargePCT` and `spentFuelLiters` are removed; a budget is `timeMinutes` or `distanceKM`
+  - core: route and leg summaries lose their battery, charge and fuel fields and `chargingInformationAtEndOfLeg`, with `ChargingStop`
+  - core: `ChargingPark.availability`, `ChargingPoint.status` and `dataSources.chargingAvailability` are removed; `StaticChargingPoint` becomes `ChargingPoint`, and `ChargingStation` takes no type parameter
+  - map: `PlacesModule` loses `evAvailability`, `categoryIcons` entries lose `availabilityLevel`, and `RoutingModule` loses `chargingStops`, with their knobs, events and shown data
+  
+  The *Upgrading to 1.0 from a 0.x release* guide lists every removed name.
+
+- [#2507](https://github.com/tomtom-internal/maps-sdk-js/pull/2507) [`9ab7e7c`](https://github.com/tomtom-internal/maps-sdk-js/commit/9ab7e7c4e5e97950f9c6ba06ff228ac99393a3d4) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - **Breaking:** map: each standard style ID is the Orbis style it loads, in camelCase
+  - map: `standardLight`, `standardDark`, `drivingLight`, `drivingDark` and `satellite` are `streetLight`, `streetDark`, `streetLightDriving`, `streetDarkDriving` and `streetSatellite`; `monoLight` and `monoDark` stay
+  - agent-toolkit: `setMapStandardStyle` takes the new IDs, `resetState` reverts to `streetLight`, and the plugin needs SDK 1.0.0-rc.0
+  - map-theme, landmarks-3d: their docs name the new IDs
+
+### Patch Changes
+
+- [#2500](https://github.com/tomtom-internal/maps-sdk-js/pull/2500) [`d19d11d`](https://github.com/tomtom-internal/maps-sdk-js/commit/d19d11d41546bac2dd870560b9508bb0b3a2ce2a) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - map: the `maplibre-gl` peer dependency moves up to `^6.12.0`
+
+- [#2506](https://github.com/tomtom-internal/maps-sdk-js/pull/2506) [`12099bd`](https://github.com/tomtom-internal/maps-sdk-js/commit/12099bdc040f3ce2d3990266bfb42024cda7956c) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - core, services, map: the package ships without source maps, so a stack trace through the SDK points into its minified bundles, which keep their function names
+  - An app's own source maps still lead a trace to the SDK's frames (`map/dist/map.es.js:1:84523`); share such a trace in a report and TomTom maps it back to the source
+
+- [#2505](https://github.com/tomtom-internal/maps-sdk-js/pull/2505) [`308c3af`](https://github.com/tomtom-internal/maps-sdk-js/commit/308c3af3a5375b12293b2018413f4f78286739d6) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - map: `TerrainModule` sets the hillshade light's height and what its direction turns with, and the `multidirectional` method fans its four lights around the light's direction
+  - map: `hillshade.light.altitude`, in degrees above the horizon, and `hillshade.light.alignment`, `viewport` or `map` (`hillshadeLightAlignments`), in the config and as `terrainKnobCatalogue` knobs
+  - map: with `method: 'multidirectional'`, `hillshade.light.direction` is the centre of four lights spread over 135°
+
+- [#2503](https://github.com/tomtom-internal/maps-sdk-js/pull/2503) [`a472dd0`](https://github.com/tomtom-internal/maps-sdk-js/commit/a472dd0183bbb6fb9c0da96ee18363e17b903b1f) Thanks [@DanielForniessoria-TomTom](https://github.com/DanielForniessoria-TomTom)! - map: `TrafficIncidentsModule` can show planned incidents, and its incident descriptions follow the map language
+  
+  - `timeValidity: ['present', 'future']` brings scheduled roadworks and closures in next to the incidents under way, also as the `timeValidity` knob
+  - `description` is in the map language, or the nearest one the traffic service has (`pt-PT` for `pt-BR`), else English; `map.setLanguage` reloads the incident tiles when that changes
+  - core: `trafficIncidentTimeValidities` lists every `TrafficIncidentTimeValidity`, `present` first
+
 ## 0.64.0
 
 ### Minor Changes

package/LICENSE.txt

@@ -1,8 +1,8 @@
 TOMTOM MAPS SDK FOR JAVASCRIPT LICENSE AGREEMENT (“AGREEMENT”)
 
-Last update: September 2026
+Last update: October 2026
 
-By downloading or accessing the “TomTom Maps SDK for JavaScript” (the “SDK”), you are entering into a binding agreement with TomTom Global Content B.V. (“TomTom”). The SDK comprises all software, binaries and source code made available by TomTom for it, whether through the TomTom Developer Portal or public code repositories (e.g. GitHub). This Agreement with TomTom consists of the terms and conditions below together with the Data Processing Schedule. You should not use the SDK if you cannot agree to both.
+By downloading or accessing the “TomTom Maps SDK for JavaScript” (the “SDK”), you are entering into a binding agreement with TomTom Global Content B.V. (“TomTom”). The SDK comprises all software, binaries and source code made available by TomTom for it, whether through the TomTom Developer Portal, package registries (e.g. npm) or otherwise. The example applications that TomTom publishes in public code repositories (e.g. GitHub) are not part of the SDK: they are licensed separately, under the license distributed with them. This Agreement with TomTom consists of the terms and conditions below together with the Data Processing Schedule. You should not use the SDK if you cannot agree to both.
 
 You may not use the SDK or accept this Agreement if you are barred from receiving it under the laws of the European Union or of any other country, including the country in which you are resident or from which you use the SDK. If you accept this Agreement on behalf of your employer or another entity, you represent and warrant that you have full legal authority to bind that employer or entity. If you do not have that authority, you may not accept this Agreement or use the SDK on their behalf.
 
@@ -14,7 +14,7 @@ You may not use the SDK or accept this Agreement if you are barred from receivin
 
 3.1. You agree to use the SDK only for purposes permitted by (a) this Agreement and (b) any applicable law, regulation or generally accepted practice or guideline in the relevant jurisdictions (including any laws regarding the export of data or software to and from the United States or other relevant countries).
 
-3.2. Other than as permitted by applicable legislation, you are prohibited from copying (except for backup purposes), modifying, adapting, (re)distributing, renting, lending, publicly presenting, decompiling, reverse engineering, disassembling or creating derivative works of the SDK or any part of it. Notwithstanding the foregoing, where the SDK is hosted on a public repository (e.g. GitHub, which allows forking under its terms of service), you may: (i) fork the repository solely for the purpose of submitting a pull request to TomTom, provided that such fork remains hosted within the platform and is not used as a basis for a separate or competing product or service; and (ii) download a local copy of the source code solely for the purpose of debugging your Permitted Application, provided that such copy is not shared or redistributed. The availability of the source code in a public repository does not constitute “Open-Source” licensing and grants you no rights under any Open Source Initiative (OSI) approved license. Neither that availability, nor any rights granted by the platform’s terms of service with respect to viewing or forking within the platform, shall be construed as a grant of rights to modify, fork or redistribute the SDK beyond those expressly granted in Clause 1 and this Clause 3.2.
+3.2. Other than as permitted by applicable legislation, you are prohibited from copying (except for backup purposes), modifying, adapting, (re)distributing, renting, lending, publicly presenting, decompiling, reverse engineering, disassembling or creating derivative works of the SDK or any part of it. Notwithstanding the foregoing, you may inspect the SDK as distributed to you, including any source code embedded in its source maps, solely for the purpose of debugging your Permitted Application, provided that it is not shared or redistributed. The readability of the SDK’s source code in its distribution does not constitute “Open-Source” licensing and grants you no rights under any Open Source Initiative (OSI) approved license, nor shall it be construed as a grant of rights to modify, fork or redistribute the SDK beyond those expressly granted in Clause 1 and this Clause 3.2.
 
 3.3. You may not use the SDK in connection with any illegal, fraudulent, dishonest or unethical activity or behaviour, and in particular not to create or develop, or help others create or develop, a product, service or library that competes, directly or indirectly, with the SDK or the TomTom APIs.
 
@@ -78,7 +78,7 @@ You may not use the SDK or accept this Agreement if you are barred from receivin
 
 11.4. The TomTom APIs and the SDK are provided as “Commercial Computer Software” or “restricted computer software”. Use, duplication or disclosure by the U.S. Government or a U.S. Government subcontractor is subject to the restrictions set forth in 48 C.F.R. Section 12.212 or 48 C.F.R. 227.2702, as applicable, or successor provisions. In respect of the Map API and Search API, the manufacturer is TomTom Global Content B.V.
 
-11.5. By submitting any suggestion, bug fix or code contribution (“Contribution”) to TomTom (e.g. via a GitHub Pull Request), you grant TomTom a perpetual, irrevocable, worldwide, royalty-free and non-exclusive license to use, reproduce, modify and distribute the Contribution as part of the SDK. You represent that you have the legal right to grant this license and that the Contribution does not infringe any third-party intellectual property rights.
+11.5. By submitting any suggestion, bug fix or code contribution (“Contribution”) to TomTom (e.g. via a GitHub issue or discussion), you grant TomTom a perpetual, irrevocable, worldwide, royalty-free and non-exclusive license to use, reproduce, modify and distribute the Contribution as part of the SDK. You represent that you have the legal right to grant this license and that the Contribution does not infringe any third-party intellectual property rights.
 
 THIRD PARTY SOFTWARE NOTICES
 

package/README.md

@@ -2,159 +2,177 @@
 
 # TomTom Maps SDK for JavaScript
 
-[🎮 **Examples**](https://docs.tomtom.com/maps-sdk-js/examples/) |
-[📖 **Documentation**](https://docs.tomtom.com/maps-sdk-js/introduction/overview) |
-[📋 **API Reference**](https://docs.tomtom.com/maps-sdk-js/api-reference/index.html) |
-[🐙 **GitHub**](https://github.com/tomtom-international/maps-sdk-js)
+[**Examples**](https://docs.tomtom.com/maps-sdk-js/examples/) |
+[**Documentation**](https://docs.tomtom.com/maps-sdk-js/introduction/overview) |
+[**API reference**](https://docs.tomtom.com/maps-sdk-js/api-reference/index.html) |
+[**Release notes**](https://docs.tomtom.com/maps-sdk-js/introduction/release-notes)
 
 [![NPM Version](https://img.shields.io/npm/v/@tomtom-org/maps-sdk.svg)](https://www.npmjs.com/package/@tomtom-org/maps-sdk)
 
 ![SDK Examples Collage](https://raw.githubusercontent.com/tomtom-international/maps-sdk-js/main/sdk-examples-collage.png)
 
-TomTom Maps SDK for JavaScript is a **JavaScript** library for building applications using [**TomTom** location maps and services](https://docs.tomtom.com/).
+**Maps SDK for JavaScript** is a **JavaScript/TypeScript** library for building applications with **TomTom** maps and location APIs.
 
-[//]: # ([![SDK Example Thumbnails](./sdk-examples-collage.png)](https://docs.tomtom.com/maps-sdk-js/examples/))
+It is built on [MapLibre GL JS](https://docs.tomtom.com/maps-sdk-js/guides/map/about-maplibre) and [GeoJSON](https://geojson.org/): TomTom maps and services work together out of the box, and the MapLibre map stays fully exposed, so its API and plugin ecosystem work alongside the SDK.
 
-It leverages the power of [MapLibre GL JS](https://github.com/maplibre/maplibre-gl-js) and [GeoJSON](https://geojson.org/)
-to seamlessly integrate TomTom maps and services with convenient out-of-the-box support, while staying highly customizable and extensible.
-<br/><br/>
+> Some capabilities of the SDK are released under [Public Preview](https://docs.tomtom.com/legal/public-preview) to collect feedback from the community. The [release notes](https://docs.tomtom.com/maps-sdk-js/introduction/release-notes) list what changes in each release.
 
-## ⚠️ Public Preview Notice
-We have released some capabilities in the Maps SDK under [Public Preview](https://docs.tomtom.com/legal/public-preview) to collect feedback from the community.
-- While our goal is to keep the design of the interface stable, breaking changes will occur, particularly in the earlier versions.
-- The versions will follow a 0.MAJOR.MINOR pattern for the time being.
-- Stay tuned with our release `CHANGELOG.md` files.
-<br/><br/>
+## Quickstart
 
-## 🚀 Getting Started
+1. **Get your TomTom API key** at [my.tomtom.com](https://my.tomtom.com/), following [these instructions](https://docs.tomtom.com/platform/documentation/dashboard/api-key-management). Before you ship, decide [where your API key runs](https://docs.tomtom.com/maps-sdk-js/guides/security/where-your-api-key-runs).
 
-```bash
-# npm and Yarn install the peer dependencies for you
-npm i @tomtom-org/maps-sdk
+2. **Install the SDK:**
 
-# pnpm does not, unless you ask it to
-echo "auto-install-peers=true" >> .npmrc && pnpm add @tomtom-org/maps-sdk
-```
+   ```bash
+   # npm and Yarn install the peer dependencies for you
+   npm install @tomtom-org/maps-sdk
 
-**Requirements**: a [TomTom API key](https://my.tomtom.com/) · Node.js 24+ at install time (the package's `engines` floor, browser target or not) · a WebGL-capable browser for the Map bundle.
+   # pnpm does not, unless you ask it to
+   echo "auto-install-peers=true" >> .npmrc && pnpm add @tomtom-org/maps-sdk
+   ```
 
-**Peer dependencies**, installed by the commands above: `maplibre-gl` v6 (rendering), `@turf/turf` v7 (geospatial analysis), `culori` v4 (colour maths), `lodash-es` v4, `zod` v4.
+3. **Using an AI coding agent? Install the SDK skill** in your project root, for Claude Code, Cursor, GitHub Copilot, Windsurf and [many more](https://www.npmjs.com/package/skills#available-agents):
 
-**TypeScript declarations ship with the package** — no `@types/…` to install, and the types are the primary API documentation.
-<br/><br/>
+   ```bash
+   npx skills add tomtom-international/maps-sdk-js --skill tomtom-maps-sdk-js
+   ```
 
-## 🧭 What you can build
+   The skill loads the SDK's patterns, coordinate conventions, service APIs and pitfalls into the agent's context, so the agent writes code against the real API instead of guessing it. Commit it so the whole team gets it. [AI coding with the SDK](https://docs.tomtom.com/maps-sdk-js/guides/ai-coding) lists the topics it covers and how to invoke them.
 
-**Map** (`@tomtom-org/maps-sdk/map`, browser) — an interactive vector map in seven TomTom styles (`standardLight`, `standardDark`, `monoLight`, `monoDark`, `drivingLight`, `drivingDark`, `satellite`), switchable at runtime, plus:
+4. **Start building.** Services return GeoJSON, and map modules show it unchanged:
 
-- **Search results and markers** — `PlacesModule`, with base-map POI icons from `POIsModule`
-- **Routes, waypoints and route sections** — `RoutingModule`
-- **Polygons and administrative boundaries** — `GeometriesModule`
-- **Reachable-range areas**, banded in the map's colours — `ReachableRangesModule`
-- **Your own GeoJSON (BYOD)** — `CustomGeoJSONModule`
-- **Traffic** — flow (`TrafficFlowModule`), incidents (`TrafficIncidentsModule`, `TrafficIncidentDetailsModule`) and area analytics (`TrafficAreaAnalyticsModule`)
-- **Terrain** — hillshade shading and 3D elevation, `TerrainModule`
-- **Styling** — label sizes, road widths, colours and presets with `StylingFoundationsModule`; base-map layer groups such as 3D buildings with `BaseMapModule`
-- **Click, hover and context-menu events**, one typed surface per module — `module.events.on(…)`
+   ```ts
+   import { TomTomConfig } from '@tomtom-org/maps-sdk/core';
+   import { PlacesModule, RoutingModule, TomTomMap } from '@tomtom-org/maps-sdk/map';
+   import { calculateRoute, discoverPlaces } from '@tomtom-org/maps-sdk/services';
 
-**Services** (`@tomtom-org/maps-sdk/services`, browser + Node.js + React Native) — typed [GeoJSON](https://geojson.org/) from TomTom APIs, usable with or without a map:
+   TomTomConfig.instance.put({ apiKey: 'YOUR_API_KEY', language: 'en-GB' });
 
-- **Search** — `discoverPlaces`, `discoverOnePlace`, `getSearchSuggestions`, `getPlaceDetails`, `getPOICategories`
-- **Geocoding and reverse geocoding** — `geocode`, `geocodeOne`, `reverseGeocode`
-- **Routing** — `calculateRoute`, with up to five alternatives, turn-by-turn guidance, toll/ferry/traffic sections and vehicle restrictions
-- **Isochrones (reachable range)** — `calculateReachableRange`, `calculateReachableRanges`, by time, distance, fuel or electric-energy budget (private preview: the API key needs Calculate Reachable Range access)
-- **EV charging** — `evChargingStationsAvailability`, `getPlaceWithEVAvailability`, `getPlacesWithEVAvailability`
-- **Traffic** — `trafficIncidentDetails`, `trafficAreaAnalytics`
-- **Geometry data** — `geometryData` for administrative boundaries
-- **Cancellation** — `createLatestRequest` keeps only the latest of a series (search-as-you-type, refetch on map move); every call also accepts an abort signal
-<br/><br/>
+   const map = new TomTomMap({ mapLibre: { container: 'map', center: [4.9, 52.37], zoom: 12 } });
 
-## 🗺️ Coming from MapLibre GL JS
+   const places = await PlacesModule.create(map);
+   await places.show(await discoverPlaces({ query: 'coffee', geoBias: { position: [4.9, 52.37] } }));
 
-The map **is** a MapLibre map. `TomTomMap` wraps a MapLibre `Map`, adds TomTom styles, data modules and services, and keeps the instance reachable — so MapLibre code, controls and plugins you already have keep working:
+   const routing = await RoutingModule.create(map);
+   await routing.showRoutes(await calculateRoute({ locations: [[4.9, 52.37], [5.12, 52.09]] }));
+   ```
 
-```ts
-import { NavigationControl } from 'maplibre-gl';
+   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/).
 
-map.mapLibreMap.addControl(new NavigationControl(), 'top-right');
-map.mapLibreMap.on('moveend', () => console.log(map.mapLibreMap.getCenter()));
-```
+### Requirements
 
-Cameras, sources, layers and style expressions stay MapLibre's. Where the SDK has a feature for the job, prefer it: it survives style switches and style upgrades, and its events coordinate across modules — for your own GeoJSON, that is `CustomGeoJSONModule`. See [About MapLibre](https://docs.tomtom.com/maps-sdk-js/guides/map/about-maplibre).
-<br/><br/>
+- **Node.js 24+** at install time, the minimum the package declares, whether or not you target the browser.
+- **A browser with WebGL** for the Map bundle.
+- **A bundler** such as Vite or webpack: 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.12+, 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.
 
-## 🤖 AI Coding Agent Skill
+[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.
 
-Install the SDK skill for AI coding agents (Claude Code, Cursor, GitHub Copilot, Windsurf, and [many more](https://www.npmjs.com/package/skills#available-agents)) to get SDK-specific assistance in your coding agent:
-```bash
-npx skills add tomtom-international/maps-sdk-js --skill tomtom-maps-sdk-js
-```
+## Bundles
 
-From 1.0 the identifier `tomtom-maps-sdk-js` is versioned like any export and changes only in a major release. [AI coding with the SDK](https://docs.tomtom.com/maps-sdk-js/guides/ai-coding) lists the topics it covers and how to invoke them.
+One package, `@tomtom-org/maps-sdk`, carries three bundles:
 
-Other machine-readable entry points, for agents and for the people configuring them:
+| Bundle | Import path | Runs in | Holds |
+| --- | --- | --- | --- |
+| [**Map**](https://docs.tomtom.com/maps-sdk-js/guides/map/quickstart) | `@tomtom-org/maps-sdk/map` | Browser | `TomTomMap` and its modules for places, routes, traffic and more |
+| [**Services**](https://docs.tomtom.com/maps-sdk-js/guides/services/quickstart) | `@tomtom-org/maps-sdk/services` | Browser, Node.js, React Native | One function per TomTom API, most returning GeoJSON |
+| [**Core**](https://docs.tomtom.com/maps-sdk-js/guides/core/quickstart) | `@tomtom-org/maps-sdk/core` | Anywhere | The shared configuration, types and utilities |
 
-- **Bundled `.d.ts` declarations** — the API surface an editor and an agent complete against
-- **[Context7 index](https://context7.com/tomtom-international/maps-sdk-js)** — this repository, indexed for agents using the Context7 MCP server
-- **[`examples/`](https://github.com/tomtom-international/maps-sdk-js/tree/main/examples)** — over 110 runnable apps, the best code to copy from
-<br/><br/>
-## How it works
+[How the SDK works](https://docs.tomtom.com/maps-sdk-js/guides/how-the-sdk-works) shows how the three fit together. Everything is tree-shakable: your bundle carries only the modules and services you import.
 
-The SDK is split into three cooperating bundles — **Map**, **Services**, and **Core**. Services call TomTom APIs and return typed [GeoJSON](https://geojson.org/) that Map modules consume directly. Core provides the shared config and types that bridge them. See [How the SDK Works](https://docs.tomtom.com/maps-sdk-js/guides/how-the-sdk-works) for a deeper dive.
+## What you can build
 
-```ts
-import { TomTomConfig } from '@tomtom-org/maps-sdk/core';
-import { TomTomMap, PlacesModule, RoutingModule } from '@tomtom-org/maps-sdk/map';
-import { discoverPlaces, calculateRoute } from '@tomtom-org/maps-sdk/services';
+### Map
+
+An interactive vector map in seven [TomTom styles](https://docs.tomtom.com/maps-sdk-js/guides/map/styles#built-in-styles) (`streetLight`, `streetDark`, `streetLightDriving`, `streetDarkDriving`, `monoLight`, `monoDark` and `streetSatellite`), [switching between them](https://docs.tomtom.com/maps-sdk-js/guides/map/styles#dynamic-style-switching) at runtime, in the [map language](https://docs.tomtom.com/maps-sdk-js/guides/map/styles#map-language) of your choice. [Map modules](https://docs.tomtom.com/maps-sdk-js/guides/map/modules) draw on it:
+
+- **[Places](https://docs.tomtom.com/maps-sdk-js/guides/map/places)**: search results as markers, with [styling](https://docs.tomtom.com/maps-sdk-js/guides/map/places-styling), clustering, and [connections and entry points](https://docs.tomtom.com/maps-sdk-js/guides/map/places-connections-and-entry-points)
+- **[Routes](https://docs.tomtom.com/maps-sdk-js/guides/map/routes)**: alternatives, waypoints, [route sections](https://docs.tomtom.com/maps-sdk-js/guides/map/routes-sections) for traffic, tolls and ferries, and [route styling](https://docs.tomtom.com/maps-sdk-js/guides/map/routes-styling)
+- **[Geometries](https://docs.tomtom.com/maps-sdk-js/guides/map/geometries)** and **[reachable ranges](https://docs.tomtom.com/maps-sdk-js/guides/map/reachable-ranges)**: polygons, administrative boundaries and isochrones
+- **[Custom GeoJSON](https://docs.tomtom.com/maps-sdk-js/guides/map/custom)**: your own data, on layers that survive style switches and take part in the map's events
+- **[Traffic](https://docs.tomtom.com/maps-sdk-js/guides/map/traffic)**: [flow](https://docs.tomtom.com/maps-sdk-js/guides/map/traffic-flow), [incidents](https://docs.tomtom.com/maps-sdk-js/guides/map/traffic-incidents), [planned ones](https://docs.tomtom.com/maps-sdk-js/guides/map/traffic-incidents#planned-incidents) included, [incident details](https://docs.tomtom.com/maps-sdk-js/guides/map/traffic-incident-details) and [area analytics](https://docs.tomtom.com/maps-sdk-js/guides/map/traffic-area-analytics-module)
+- **[Base map](https://docs.tomtom.com/maps-sdk-js/guides/map/base-map)** and **[POIs](https://docs.tomtom.com/maps-sdk-js/guides/map/pois)**: show or hide layer groups such as 3D buildings and road shields, and filter the base map's points of interest
+- **[Terrain](https://docs.tomtom.com/maps-sdk-js/guides/map/terrain)**: hillshade relief with its own light and colours, and 3D elevation
+- **[Events](https://docs.tomtom.com/maps-sdk-js/guides/map/events)**: click, hover and context-menu events on every module, and module events such as `config-change`
+
+[Map styling](https://docs.tomtom.com/maps-sdk-js/guides/map/styling) restyles the loaded map through **semantic knobs** instead of layer ids:
 
-// Configure once — all services and the map use this key
-TomTomConfig.instance.put({ apiKey: 'YOUR_API_KEY' });
+- **Every setting as data**: each module lists its settings in a knob catalogue, and `setKnob`, `getKnob` and `resetKnob` [set one by its id](https://docs.tomtom.com/maps-sdk-js/guides/map/modules#setting-a-knob-by-its-id), validated, on any module.
+- **Map-wide sizes and colours**: label, icon and road sizes, and the [ten map colours and the accent](https://docs.tomtom.com/maps-sdk-js/guides/map/styling-map-colors) that routes, geometries and pins take.
+- **[Presets](https://docs.tomtom.com/maps-sdk-js/guides/map/styling#presets)**: `applyMapPreset` sets a whole look in one call.
+- **[Globe and sky](https://docs.tomtom.com/maps-sdk-js/guides/map/styling-globe-and-sky)**: globe projection, sky and horizon.
+- **[Geopolitical views](https://docs.tomtom.com/maps-sdk-js/guides/core/geopolitical-views)**: disputed borders and territories as one country sees them, on the map and in search.
 
-const map = new TomTomMap({ mapLibre: { container: 'map', center: [4.9, 52.4], zoom: 12 } });
+### Services
 
-// Services return GeoJSON — map modules consume it directly
-const places = await PlacesModule.create(map);
-await places.show(await discoverPlaces({ query: 'coffee' }));
+Typed GeoJSON from the TomTom APIs, with or without a map:
 
-const routing = await RoutingModule.create(map);
-await routing.showRoutes(await calculateRoute({ locations: [[4.9, 52.4], [13.4, 52.5]] }));
+- **[Search](https://docs.tomtom.com/maps-sdk-js/guides/services/places/search)**: `discoverPlaces`, [search suggestions](https://docs.tomtom.com/maps-sdk-js/guides/services/places/suggest), [place details](https://docs.tomtom.com/maps-sdk-js/guides/services/places/place-by-id) and [POI categories](https://docs.tomtom.com/maps-sdk-js/guides/services/places/poi-categories)
+- **[Geocoding](https://docs.tomtom.com/maps-sdk-js/guides/services/places/geocoding)** and **[reverse geocoding](https://docs.tomtom.com/maps-sdk-js/guides/services/places/reverse-geocoding)**: `geocode`, `geocodeOne` and `reverseGeocode`
+- **[Routing](https://docs.tomtom.com/maps-sdk-js/guides/services/routing/quickstart)**: `calculateRoute`, with alternatives, [guidance](https://docs.tomtom.com/maps-sdk-js/guides/services/routing/guidance) and [vehicle restrictions](https://docs.tomtom.com/maps-sdk-js/guides/services/routing/vehicle)
+- **[Reachable ranges](https://docs.tomtom.com/maps-sdk-js/guides/services/routing/reachable-ranges)**: isochrones by time or distance budget, in Private Preview
+- **Traffic**: [incident details](https://docs.tomtom.com/maps-sdk-js/guides/services/traffic/traffic-incident-details) and [area analytics](https://docs.tomtom.com/maps-sdk-js/guides/services/traffic/traffic-area-analytics)
+- **[Geometry data](https://docs.tomtom.com/maps-sdk-js/guides/services/places/geometry-data)**: administrative boundaries for a search result
+- **[Request options and errors](https://docs.tomtom.com/maps-sdk-js/guides/services/request-options-and-errors)**: request validation, [cancellation](https://docs.tomtom.com/maps-sdk-js/guides/services/request-options-and-errors#cancelling-a-request) and deadlines, and [errors](https://docs.tomtom.com/maps-sdk-js/guides/services/request-options-and-errors#error-handling) that name what went wrong with an `SDKErrorCode`
+
+### Plugins
+
+Separate packages, each declaring the SDK as a peer dependency:
+
+| Plugin | What it does |
+| --- | --- |
+| [**Agent Toolkit**](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/overview) | Lets your users plan routes, search places and restyle the map in natural language, with the LLM and chat UI of your choice |
+| [**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 |
+| [**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 |
+
+## Coming from MapLibre GL JS
+
+The map **is** a MapLibre map. `TomTomMap` wraps a MapLibre `Map` and keeps it reachable as `map.mapLibreMap`, so the MapLibre code, controls and plugins you already have keep working:
+
+```ts
+import { NavigationControl } from 'maplibre-gl';
+
+map.mapLibreMap.addControl(new NavigationControl(), 'top-right');
+map.mapLibreMap.on('moveend', () => console.log(map.mapLibreMap.getCenter()));
 ```
-<br/><br/>
 
-## 📚 Documentation & Examples
+Where the SDK has a feature for the job, prefer it: it survives style switches and style releases, and its events coordinate across modules. [About MapLibre](https://docs.tomtom.com/maps-sdk-js/guides/map/about-maplibre#when-to-use-tomtom-sdk-vs-direct-maplibre) says which to use when.
 
-- **[Live Examples](https://docs.tomtom.com/maps-sdk-js/examples/)** — try the SDK in your browser
-- **[Getting Started](https://docs.tomtom.com/maps-sdk-js/introduction/overview)** — introduction and project setup
-- **[API Reference](https://docs.tomtom.com/maps-sdk-js/api-reference/index.html)** — complete API documentation
-- **[Release Notes](https://docs.tomtom.com/maps-sdk-js/introduction/release-notes)** — what's new and breaking changes
-- **[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
-<br/><br/>
+## Security and privacy
 
-## 📦 Bundles
+- [**Where your API key runs**](https://docs.tomtom.com/maps-sdk-js/guides/security/where-your-api-key-runs): a key used from the browser can be read by anyone who opens the page; a key used from Node.js cannot.
+- [**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.
 
-| Bundle | Import path | Platforms |
-|--------|-------------|-----------|
-| **[Map](https://docs.tomtom.com/maps-sdk-js/guides/map/quickstart)** — interactive maps in [styles](https://docs.tomtom.com/maps-sdk-js/guides/map/styles), with [POIs](https://docs.tomtom.com/maps-sdk-js/guides/map/pois), [traffic](https://docs.tomtom.com/maps-sdk-js/guides/map/traffic), [places](https://docs.tomtom.com/maps-sdk-js/guides/map/places), [routes](https://docs.tomtom.com/maps-sdk-js/guides/map/routes) and [geometries](https://docs.tomtom.com/maps-sdk-js/guides/map/geometries) | `@tomtom-org/maps-sdk/map` | web |
-| **[Services](https://docs.tomtom.com/maps-sdk-js/guides/services/quickstart)** — [GeoJSON](https://geojson.org/) services for [places](https://docs.tomtom.com/maps-sdk-js/guides/services/places/quickstart), [routing](https://docs.tomtom.com/maps-sdk-js/guides/services/routing/quickstart), geocoding and more | `@tomtom-org/maps-sdk/services` | web, Node.js, React Native |
-| **[Core](https://docs.tomtom.com/maps-sdk-js/api-reference/modules/core.html)** — shared config, types and utilities; no separate install needed | `@tomtom-org/maps-sdk/core` | web, Node.js, React Native |
+## Resources for AI agents
 
-## 📄 License
+Besides the [coding skill](#quickstart), these entry points serve agents and the people configuring them:
 
-This repository uses a **dual-licensing model**.
+- **Bundled `.d.ts` declarations**: the API surface an editor and an agent complete against.
+- **Markdown pages**: [project setup](https://docs.tomtom.com/maps-sdk-js/introduction/project-setup.md), and the [map](https://docs.tomtom.com/maps-sdk-js/guides/map/quickstart.md), [services](https://docs.tomtom.com/maps-sdk-js/guides/services/quickstart.md) and [core](https://docs.tomtom.com/maps-sdk-js/guides/core/quickstart.md) quickstarts, published for agents to read.
+- **[Context7 index](https://context7.com/tomtom-international/maps-sdk-js)**: this repository, indexed for agents using the Context7 MCP server.
+- **[`examples/`](https://github.com/tomtom-international/maps-sdk-js/tree/main/examples)**: over 110 runnable apps, the best code to copy from.
 
-### SDK Packages and plugins - Proprietary License
-The SDK packages (`@tomtom-org/maps-sdk/*` - core, services, map) and plugins (`@tomtom-org/maps-sdk-plugin-*`) are distributed under a **proprietary license**.
+[AI and the SDK](https://docs.tomtom.com/maps-sdk-js/introduction/ai) covers both the coding skill and the [Agent Toolkit](https://docs.tomtom.com/maps-sdk-js/guides/plugins/agent-toolkit/overview), for putting an LLM in front of your users.
 
-📜 **[LICENSE.txt](./LICENSE.txt)** - Full license terms
+## Documentation
 
-These packages require a TomTom API key and agreement to our terms of service.
+- [**Introduction**](https://docs.tomtom.com/maps-sdk-js/introduction/overview) and [**project setup**](https://docs.tomtom.com/maps-sdk-js/introduction/project-setup)
+- [**Guides**](https://docs.tomtom.com/maps-sdk-js/guides/how-the-sdk-works), starting with how the SDK works
+- [**Examples**](https://docs.tomtom.com/maps-sdk-js/examples/), live in your browser with their code
+- [**API reference**](https://docs.tomtom.com/maps-sdk-js/api-reference/index.html), every exported symbol with its signature and types
+- [**Release notes**](https://docs.tomtom.com/maps-sdk-js/introduction/release-notes) and the [changelog](./CHANGELOG.md)
+- [**Migrating from V6**](https://docs.tomtom.com/maps-sdk-js/guides/migration/v6-to-new-sdk), for apps on the TomTom Maps SDK for Web V6
 
-### Examples - Apache V2.0 License
-All example code in the `examples/` directory is **open-source** under the Apache V2.0 License.
+## License
 
-📜 **[examples/LICENSE](./examples/LICENSE)** - Apache V2.0 License
+This repository uses a **dual-licensing model**:
 
-The examples can be freely copied, modified, and used in your projects.
+- **SDK packages and plugins**: `@tomtom-org/maps-sdk` (core, services, map) and the `@tomtom-org/maps-sdk-plugin-*` packages are distributed under a **proprietary license**, in [LICENSE.txt](./LICENSE.txt). They require a TomTom API key and agreement to our terms of service.
+- **Examples**: the code in `examples/` is **open source** under the Apache 2.0 license, in [examples/LICENSE](./examples/LICENSE). Copy, modify and use it in your projects.
 
-### Source-Available Repository
-This repository is source-available for transparency and learning. This is a read-only mirror - see [CONTRIBUTING.md](./CONTRIBUTING.md) for how to provide feedback through issues and discussions.
+The [GitHub repository](https://github.com/tomtom-international/maps-sdk-js) carries the examples, the changelogs and the AI coding skill; the SDK's sources are not published. It is a read-only mirror: report bugs in its [issues](https://github.com/tomtom-international/maps-sdk-js/issues) and ask questions in its [discussions](https://github.com/tomtom-international/maps-sdk-js/discussions).

package/THIRD_PARTY.txt

@@ -152,7 +152,7 @@ terms above.
 ---
 
 Name: maplibre-gl
-Version: 6.11.2
+Version: 6.12.0
 License: BSD-3-Clause
 Bundled: false (peer dependency)
 Required by: map