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

package/core/dist/index.d.ts

@@ -1,3 +1,40 @@
+//#region src/types/apiErrorDetails.d.ts
+/**
+ * The access a Private Preview API needs on the API key, and where to request it.
+ *
+ * @group Errors
+ */
+type PrivatePreviewAccess = {
+  /**
+   * The API the key needs access to, as TomTom Sales names it, such as `'Calculate Reachable Range'`.
+   */
+  product: string;
+  /**
+   * Where to request that access.
+   */
+  requestAccessURL: string;
+};
+/**
+ * What a TomTom API said about a request it failed, as a service's `SDKServiceError` and the map's
+ * `TomTomMapError` both carry it.
+ *
+ * @group Errors
+ */
+type APIErrorDetails = {
+  /**
+   * The API's own name for the error, from its `detailedError.code`, when its response carries one.
+   *
+   * On an `INSUFFICIENT_PERMISSIONS` it tells the causes apart: `'Forbidden'` when the API is not enabled for
+   * the key, `'InvalidReferer'` when the key's domain restriction refused the page.
+   */
+  readonly apiErrorCode?: string;
+  /**
+   * The access the API key lacks, on an `INSUFFICIENT_PERMISSIONS` from a Private Preview API, such as
+   * Calculate Reachable Range or the Landmarks 3D tiles, that named no other cause. The message names it too.
+   */
+  readonly privatePreviewAccess?: PrivatePreviewAccess;
+};
+//#endregion
 //#region ../node_modules/.pnpm/@types+geojson@7946.0.16/node_modules/@types/geojson/index.d.ts
 /**
  * The value values for the "type" property of GeoJSON Objects.
@@ -291,14 +328,6 @@ type AggregatedCells<S extends CellStatistic, G extends CellGrid> = [G] extends
  *
  * Use it for objects whose shape is not fixed, such as extensible properties or arbitrary user data.
  *
- * @example
- * ```typescript
- * function processCustomData(data: Anything) {
- *   // Access properties dynamically
- *   console.log(data['customField']);
- * }
- * ```
- *
  * @group Shared
  */
 type Anything = {
@@ -322,13 +351,13 @@ type Anything = {
  * @example
  * ```typescript
  * // Plain coordinate pair
- * const pos1: HasLngLat = [4.9041, 52.3676];
+ * const pair: HasLngLat = [4.9041, 52.3676];
  *
  * // GeoJSON Point geometry
- * const pos2: HasLngLat = { type: 'Point', coordinates: [4.9041, 52.3676] };
+ * const point: HasLngLat = { type: 'Point', coordinates: [4.9041, 52.3676] };
  *
  * // GeoJSON Feature<Point> — e.g. a Place from search results
- * const pos3: HasLngLat = searchResults.features[0];
+ * const feature: HasLngLat = searchResults.features[0];
  * ```
  *
  * @group Shared
@@ -410,6 +439,7 @@ type OptionalBBox = BBox | undefined;
  *       [4.8, 52.3]
  *     ]]
  *   },
+ *   bbox: [4.8, 52.3, 5.0, 52.4],
  *   properties: {
  *     name: 'Amsterdam',
  *     population: 872680
@@ -443,11 +473,13 @@ type PolygonFeature<P = GeoJsonProperties> = Omit<Feature<Polygon | MultiPolygon
  *     {
  *       type: 'Feature',
  *       geometry: { type: 'Polygon', coordinates: [...] },
+ *       bbox: [4.88, 52.36, 4.92, 52.38],
  *       properties: { name: 'District 1', area: 500000 }
  *     },
  *     {
  *       type: 'Feature',
  *       geometry: { type: 'Polygon', coordinates: [...] },
+ *       bbox: [4.92, 52.36, 4.96, 52.38],
  *       properties: { name: 'District 2', area: 750000 }
  *     }
  *   ]
@@ -456,16 +488,11 @@ type PolygonFeature<P = GeoJsonProperties> = Omit<Feature<Polygon | MultiPolygon
  *
  * @group Shared
  */
-type PolygonFeatures<P = GeoJsonProperties> = Omit<FeatureCollection<Polygon | MultiPolygon, P>, 'features' | 'bbox'> & {
+type PolygonFeatures<P = GeoJsonProperties> = Omit<FeatureCollectionWithProperties<Polygon | MultiPolygon, P>, 'features' | 'properties'> & {
   /**
    * The polygon or multi-polygon features.
    */
   features: PolygonFeature<P>[];
-  /**
-   * The bounding box of all features in the collection, including any bounding boxes they have.
-   * It is present only if the collection has features.
-   */
-  bbox?: BBox;
 };
 /**
  * A GeoJSON FeatureCollection with an optional `properties` field at the collection level.
@@ -532,7 +559,7 @@ export declare const geopoliticalViews: readonly ["Unified", "AE", "AR", "BN", "
  *
  * @example
  * ```typescript
- * // The map and every service, from India's perspective
+ * // The map and the services GeopoliticalViewAPI lists, from India's perspective
  * TomTomConfig.instance.put({ apiKey: 'YOUR_API_KEY', geopoliticalView: 'IN' });
  * ```
  *
@@ -573,7 +600,7 @@ export type GeopoliticalViewAPI = 'mapTiles' | 'search' | 'placeDetails' | 'reve
  * const position = getPosition(place, { useEntryPoint: 'main-when-available' });
  *
  * // Get center position ignoring entry points
- * const centerPos = getPosition(place, { useEntryPoint: 'ignore' });
+ * const center = getPosition(place, { useEntryPoint: 'ignore' });
  * ```
  *
  * @group Shared
@@ -586,21 +613,9 @@ type GetPositionEntryPointOption = 'main-when-available' | 'ignore';
  */
 type GetPositionOptions = {
   /**
-   * Whether to use entry point positions when available.
-   *
-   * With `'main-when-available'`, you get an entry point's coordinates, as {@link GetPositionEntryPointOption}
-   * describes. Use it for routing, to direct users to the correct entrance.
+   * Whether to use entry point positions when available, as {@link GetPositionEntryPointOption} describes.
    *
    * @default 'ignore'
-   *
-   * @example
-   * ```typescript
-   * // For routing to a specific entrance
-   * { useEntryPoint: 'main-when-available' }
-   *
-   * // For displaying place center on map
-   * { useEntryPoint: 'ignore' }
-   * ```
    */
   useEntryPoint?: GetPositionEntryPointOption;
 };
@@ -625,13 +640,6 @@ type TomTomAPIHeaders = {
  *
  * They set the language of map labels, place names, addresses and other textual content.
  *
- * The array includes:
- * - Region-specific language variants (e.g., `en-US`, `en-GB`, `pt-BR`, `pt-PT`)
- * - Script-specific variants (e.g., `zh-Hans` for Simplified Chinese, `zh-Hant` for Traditional Chinese)
- * - Special codes like `ngt` (Neutral Ground Truth) for language-neutral content
- * - Latin script alternatives (e.g., `ngt-Latn`, `ko-Latn-KR`, `ru-Latn-RU`)
- * - Cyrillic script variants (e.g., `ru-Cyrl-RU`)
- *
  * Use it to check whether a user-provided language code is supported, to generate language
  * selection UI or to iterate over all language options.
  *
@@ -641,18 +649,11 @@ type TomTomAPIHeaders = {
  * @example
  * ```typescript
  * // Validate a language code
- * const userLanguage = 'en-US';
- * if (languages.includes(userLanguage)) {
+ * const userLanguage: string = 'en-US';
+ * const knownLanguages: readonly string[] = languages;
+ * if (knownLanguages.includes(userLanguage)) {
  *   console.log('Language is supported');
  * }
- *
- * // Create a language selector
- * languages.forEach(lang => {
- *   console.log(`Available language: ${lang}`);
- * });
- *
- * // Check total number of supported languages
- * console.log(`Total languages: ${languages.length}`);
  * ```
  *
  * @group Shared
@@ -665,27 +666,16 @@ export declare const languages: readonly ["ngt", "ngt-Latn", "ar", "eu-ES", "bg-
  * - Map labels and text on vector tiles.
  * - Place names, addresses and other textual content in service responses.
  *
- * `Language` lists every language the map labels carry. A service that lacks one answers in local names,
- * as the places services do for `hi-IN` and `ja-JP`. Text a service writes itself, such as route
- * instructions, POI category names and traffic incident descriptions, comes in the nearest language it has,
- * or in English.
- *
  * It covers locales with region-specific variants, such as `en-US` and `en-GB`. Special codes
  * such as `ngt` (Neutral Ground Truth) and `ngt-Latn` give language-neutral or Latin script alternatives.
  *
- * @see [Supported languages documentation](https://docs.tomtom.com/map-display-api/documentation/vector/content-v2#list-of-supported-languages)
- *
- * @example
- * ```typescript
- * // Use US English
- * const language: Language = 'en-US';
- *
- * // Use simplified Chinese
- * const language: Language = 'zh-Hans';
+ * @remarks
+ * `Language` lists every language the map labels carry. Where a service lacks one:
+ * - Names come in their local language, as the places services give them for `hi-IN` and `ja-JP`.
+ * - Text the service writes itself, such as route instructions, POI category names and traffic
+ *   incident descriptions, comes in the nearest language it has, or in English.
  *
- * // Use neutral ground truth (no translation)
- * const language: Language = 'ngt';
- * ```
+ * @see [Supported languages documentation](https://docs.tomtom.com/map-display-api/documentation/vector/content-v2#list-of-supported-languages)
  *
  * @group Shared
  */
@@ -712,11 +702,6 @@ export declare const connectorTypes: readonly ["StandardHouseholdCountrySpecific
  * - `Tesla`: Tesla proprietary connector
  * - `GBT20234Part2/3`: Chinese GB/T standard
  *
- * @example
- * ```typescript
- * const connectorType: ConnectorType = 'IEC62196Type2CCS';
- * ```
- *
  * @group Place
  */
 export type ConnectorType = (typeof connectorTypes)[number];
@@ -733,11 +718,6 @@ export declare const currentTypes: readonly ["AC1", "AC3", "DC"];
  * - `AC3`: Alternating Current, three-phase (faster AC charging, up to 22 kW)
  * - `DC`: Direct Current (DC fast charging, 50-350+ kW)
  *
- * @example
- * ```typescript
- * const currentType: CurrentType = 'DC';  // DC fast charging
- * ```
- *
  * @group Place
  */
 export type CurrentType = (typeof currentTypes)[number];
@@ -839,7 +819,7 @@ export type ConnectorCount = HasConnector & HasCount;
 //#endregion
 //#region src/types/place/ev/chargingStation.d.ts
 /**
- * Possible capabilities for a charging point.
+ * Every {@link ChargingPointCapability}.
  * @group Place
  */
 export declare const chargingPointCapabilities: readonly ["ChargingProfileCapable", "ChargingPreferencesCapable", "ChipCardSupport", "ContactlessCardSupport", "CreditCardPayable", "DebitCardPayable", "PedTerminal", "RemoteStartStopCapable", "Reservable", "RfidReader", "StartSessionConnectorRequired", "TokenGroupCapable", "UnlockCapable", "PlugAndCharge", "Unknown"];
@@ -863,16 +843,6 @@ export declare const chargingPointCapabilities: readonly ["ChargingProfileCapabl
  * - `PlugAndCharge`: Supports ISO 15118 Plug & Charge (automatic authentication)
  * - `Unknown`: Capability not specified
  *
- * @example
- * ```typescript
- * // Check for specific capabilities
- * const capabilities: ChargingPointCapability[] = [
- *   'CreditCardPayable',
- *   'Reservable',
- *   'RemoteStartStopCapable'
- * ];
- * ```
- *
  * @group Place
  */
 export type ChargingPointCapability = (typeof chargingPointCapabilities)[number];
@@ -891,11 +861,6 @@ export declare const chargingPointRestrictions: readonly ["EvOnly", "Plugged", "
  * - `Customers`: For customers/guests only (e.g., hotel, shop)
  * - `Motorcycles`: Suitable only for electric motorcycles or scooters
  *
- * @example
- * ```typescript
- * const restrictions: ChargingPointRestriction[] = ['EvOnly', 'Customers'];
- * ```
- *
  * @group Place
  */
 export type ChargingPointRestriction = (typeof chargingPointRestrictions)[number];
@@ -998,14 +963,11 @@ export type ChargingStation = {
  */
 type ChargingPark = {
   /**
-   * The connector counts, grouped by type and power level.
-   *
-   * They are static counts of how many connectors of each type the location has,
-   * without real-time availability status.
+   * How many connectors the location has, grouped by type and power level.
    */
   connectors: ConnectorCount[];
   /**
-   * The charging stations and their charging points (EVSEs), without real-time status.
+   * The charging stations and their charging points (EVSEs).
    *
    * Present on places returned by the search services.
    */
@@ -1045,10 +1007,7 @@ type PlaceDataSources = {
    */
   geometry?: GeometryDataSource;
   /**
-   * The data source for detailed POI information, which the Orbis places API doesn't return.
-   *
-   * @remarks
-   * To fetch a place's details, pass the place's own `id` to `getPlaceDetails`.
+   * The data source for detailed POI information: see {@link PoiDetailsDataSource}.
    */
   poiDetails?: PoiDetailsDataSource;
 };
@@ -1078,7 +1037,7 @@ type GeometryDataSource = {
  * Data source reference for detailed POI information, which the Orbis places API doesn't return.
  *
  * @remarks
- * To fetch a place's details, pass the place's own `id` to `getPlaceDetails`.
+ * To fetch a place's details, pass the place's own `id` to `getPlaceDetails` as its `entityId`.
  *
  * @group Place
  */
@@ -1105,13 +1064,6 @@ type PoiDetailsDataSource = {
  *
  * @see [IANA Time Zone Database](https://www.iana.org/time-zones)
  *
- * @example
- * ```typescript
- * const timezone: TimeZone = {
- *   ianaId: 'Europe/Amsterdam'
- * };
- * ```
- *
  * @group Shared
  */
 type TimeZone = {
@@ -1123,10 +1075,12 @@ type TimeZone = {
 //#endregion
 //#region src/types/place/poi/category.d.ts
 /**
+ * Every {@link POICategory}.
  * @group Place
  */
 export declare const poiCategories: readonly ["ABORIGINAL_LAND", "ADVENTURE_SPORTS_FACILITY", "ADVENTURE_VEHICLE_TRAIL", "ADVERTISING_COMPANY", "AFGHAN_RESTAURANT", "AFRICAN_RESTAURANT", "AGRICULTURAL_SUPPLIES", "AGRICULTURAL_TECHNOLOGY", "AGRICULTURE", "AIRFIELD", "AIRLINE_ACCESS", "AIRLINE_COMPANY", "AIRPORT", "AMBULANCE_UNIT", "AMERICAN_RESTAURANT", "AMPHITHEATER", "AMUSEMENT_PARK", "AMUSEMENT_PARK_GENERIC", "AMUSEMENT_PLACE", "ANIMAL_SERVICE", "ANIMAL_SHELTER", "ANTIQUE_ART_SHOP", "APARTMENT_RENTAL", "AQUATIC_ZOO", "ARABIAN_RESTAURANT", "ARBORETA_AND_BOTANICAL_GARDENS", "ARCH", "ARMENIAN_RESTAURANT", "ART_SCHOOL", "ASIAN_RESTAURANT", "ATHLETICS_TRACK", "ATM", "ATV_DEALER", "AUSTRALIAN_RESTAURANT", "AUSTRIAN_RESTAURANT", "AUTOMOBILE_COMPANY", "AUTOMOBILE_MANUFACTURING", "BAGS_LEATHERWEAR", "BAKERY", "BANDB_OR_GUEST_HOUSE", "BANK", "BANQUET_ROOMS", "BAR", "BARBECUE_RESTAURANT", "BASEBALL_PARK", "BASKETBALL_ARENA", "BASQUE_RESTAURANT", "BATTLEFIELD", "BAY", "BEACH", "BEACH_CLUB", "BEAUTY_SALON", "BEAUTY_SUPPLIES", "BELGIAN_RESTAURANT", "BETTING_STATION", "BISTRO", "BLOOD_BANK", "BOATING_EQUIPMENT_AND_ACCESSORIES", "BOAT_DEALER", "BOAT_LAUNCHING_RAMP", "BODYSHOP", "BOLIVIAN_RESTAURANT", "BOOK_SHOP", "BORDER_CONTROL", "BOWLING_CENTER", "BRAZILIAN_RESTAURANT", "BRIDGE", "BRITISH_RESTAURANT", "BUFFET_RESTAURANT", "BUILDING", "BULGARIAN_RESTAURANT", "BUNGALOW_RENTAL", "BURMESE_RESTAURANT", "BUSINESS_PARK", "BUSINESS_SERVICES", "BUS_CHARTER_COMPANY", "BUS_DEALER", "BUS_LINES", "BUS_STOP", "BUTCHER", "CABARET_THEATER", "CABINS_LODGES", "CABLE_AND_TELEPHONE_COMPANY", "CAFE", "CAFETERIA", "CAFE_PUB", "CALIFORNIAN_RESTAURANT", "CAMBODIAN_RESTAURANT", "CAMERAS_AND_PHOTOGRAPHY", "CAMPING_GROUND", "CANADIAN_RESTAURANT", "CANNABIS_SHOP", "CAPE", "CARAVAN_SITE", "CARIBBEAN_RESTAURANT", "CARPET_FLOOR_COVERINGS", "CAR_DEALER", "CAR_GLASS_REPLACEMENT_SHOP", "CAR_RENTAL", "CAR_REPAIR_AND_SERVICE", "CAR_WASH", "CAR_WASH_GENERIC", "CASINO_AND_GAMBLING", "CATERING_SERVICES", "CAVE", "CEMETERY", "CHALET_RENTAL", "CHARGING_LOCATION", "CHEMICAL_COMPANY", "CHICKEN_RESTAURANT", "CHILDCARE", "CHILDREN_S_CLOTHES", "CHILEAN_RESTAURANT", "CHINESE_RESTAURANT", "CHRISTMAS_OR_HOLIDAY_SHOP", "CHURCH", "CINEMA", "CLEANING_SERVICES", "CLOTHING_SHOP", "CLUB_AND_ASSOCIATION", "COCKTAIL_BAR", "COFFEE_SHOP", "COLLEGE_OR_UNIVERSITY", "COLLEGE_OR_UNIVERSITY_GENERIC", "COLOMBIAN_RESTAURANT", "COMEDY_CLUB", "COMMERCIAL_BUILDING", "COMMUNITY_CENTER", "COMPANY", "COMPUTER_AND_COMPUTER_SUPPLIES", "COMPUTER_AND_DATA_SERVICES", "CONCERT_HALL", "CONSTRUCTION_COMPANY", "CONSTRUCTION_MATERIAL_AND_EQUIPMENT", "CONSUMER_ELECTRONICS", "CONVENIENCE_STORE", "CORSICAN_RESTAURANT", "COTTAGE_RENTAL", "COURIER_DROP_BOX", "COURTHOUSE", "COVE", "CREOLE_RESTAURANT", "CREPERIE", "CRICKET_GROUND", "CUBAN_RESTAURANT", "CULTURAL_CENTER", "CURTAINS_TEXTILES", "CZECH_RESTAURANT", "C_DS_DVD_VIDEOS", "DAM", "DANCE_STUDIO_AND_SCHOOL", "DANISH_RESTAURANT", "DELICATESSEN", "DELIVERY_SERVICE", "DENTIST", "DEPARTMENT_STORE", "DINNER_THEATER", "DISCO_CLUB", "DIVERSIFIED_FINANCIALS", "DOCTOR", "DONGBEI_RESTAURANT", "DOUGHNUT_RESTAURANT", "DO_IT_YOURSELF_CENTERS", "DRIVE_IN_MOVIES", "DRIVE_THROUGH_BOTTLE_SHOP", "DRIVING_SCHOOL", "DRUG_STORE", "DRY_CLEANER", "DUNE", "DUTCH_RESTAURANT", "EGYPTIAN_RESTAURANT", "ELECTRICAL_APPLIANCES_SHOP", "ELECTRONICS_COMPANY", "EMBASSY", "EMERGENCY_MEDICAL_SERVICE", "EMERGENCY_ROOM", "ENGLISH_RESTAURANT", "ENTERTAINMENT", "EQUIPMENT_RENTAL", "ETHIOPIAN_RESTAURANT", "EXCHANGE", "EXHIBITION_CONVENTION_CENTER", "FACTORY_OUTLET", "FAIRGROUND", "FARM", "FARMERS_MARKET", "FAST_FOOD", "FERRY_TERMINAL", "FINNISH_RESTAURANT", "FIRE_STATION", "FISHING_AND_HUNTING_AREA", "FISHMONGER", "FITNESS_CLUB_AND_CENTER", "FLATS_OR_APARTMENT_COMPLEX", "FLORISTS", "FLYING_CLUB", "FONDUE_RESTAURANT", "FOOD_AND_DRINKS_SHOP", "FOOD_MARKET", "FOOTBALL_STADIUM", "FOOTWEAR_SHOE_REPAIRS", "FOREIGN_EXCHANGE", "FOREST_AREA", "FRENCH_RESTAURANT", "FUEL_STATION", "FUNERAL_SERVICE_AND_MORTUARIES", "FURNITURE_HOME_FURNISHINGS", "FUSION_RESTAURANT", "GARDEN_CENTERS_SERVICES", "GENERAL_HOSPITAL_AND_POLYCLINIC", "GENERAL_PRACTITIONER", "GERMAN_RESTAURANT", "GIFTS_CARDS_NOVELTIES_SOUVENIRS", "GLASSWARE_CERAMIC_SHOP", "GLASS_WINDOWS_STORE", "GOLD_EXCHANGE", "GOLF_COURSE", "GOVERNMENT_OFFICE", "GREEK_RESTAURANT", "GREENGROCER", "GRILL_RESTAURANT", "GROCERY_STORE", "GURUDWARA", "HAIRDRESSER", "HAMBURGER_RESTAURANT", "HARBOR", "HARDWARE_STORE", "HAWAIIAN_RESTAURANT", "HEALTHCARE_SERVICE", "HELIPORT_OR_HELIPAD", "HIGH_SCHOOL", "HIKING_TRAIL", "HILL", "HISTORICAL_PARK", "HISTORIC_SITE", "HOBBY_SHOP", "HOCKEY_CLUB", "HOLIDAY_RENTAL", "HOME_APPLIANCE_REPAIR", "HORSE_RACING_TRACK", "HORSE_RIDING", "HORSE_RIDING_TRAIL", "HORTICULTURE", "HOSPITAL", "HOSPITAL_FOR_WOMEN_AND_CHILDREN", "HOSPITAL_OF_CHINESE_MEDICINE", "HOSTEL", "HOTEL", "HOTEL_OR_MOTEL", "HOT_POT_RESTAURANT", "HOUSE_AND_GARDEN_FURNITURE_AND_FITTINGS", "HUNAN_RESTAURANT", "HUNGARIAN_RESTAURANT", "ICE_CREAM_PARLOR", "ICE_HOCKEY_ARENA", "ICE_RINK", "IMPORT_OR_EXPORT_AND_DISTRIBUTION", "INDIAN_RESTAURANT", "INDONESIAN_RESTAURANT", "INDUSTRIAL_BUILDING", "INFORMAL_MARKET", "INSURANCE_COMPANY", "INTERNATIONAL_RAILROAD_STATION", "INTERNATIONAL_RESTAURANT", "INTERNET_CAFE", "INVESTMENT_ADVISOR", "IRANIAN_RESTAURANT", "IRISH_RESTAURANT", "ISLAND", "ISRAELI_RESTAURANT", "ITALIAN_RESTAURANT", "JAMAICAN_RESTAURANT", "JAPANESE_RESTAURANT", "JAZZ_CLUB", "JEWELRY_CLOCKS_WATCHES", "JEWISH_RESTAURANT", "JUICE_BAR", "JUNIOR_COLLEGE_OR_COMMUNITY_COLLEGE", "KARAOKE_CLUB", "KITCHENS_BATHROOMS", "KOREAN_RESTAURANT", "KOSHER_RESTAURANT", "LANGUAGE_SCHOOL", "LATIN_AMERICAN_RESTAURANT", "LAUNDRY", "LEBANESE_RESTAURANT", "LEGAL_SERVICES", "LEISURE_CENTER", "LIGHTING_SHOPS", "LOCALE", "LOCAL_SPECIALITIES_SHOP", "LOTTERY_SHOP", "MALL", "MANUFACTURING_COMPANY", "MANUFACTURING_FACILITY", "MARINA", "MARINA_GENERIC", "MARKETPLACE", "MARSH", "MAUSOLEUM_OR_GRAVE", "MECHANICAL_ENGINEERING", "MEDIA_FACILITY", "MEDICAL_SUPPLIES_EQUIPMENT", "MEDICINAL_AND_RECREATIONAL_DISPENSARY", "MEDICINAL_MARIJUANA_DISPENSARY", "MEDITERRANEAN_RESTAURANT", "MEMORIAL", "MEN_S_CLOTHING", "MEXICAN_RESTAURANT", "MICROBREWERY", "MIDDLE_EASTERN_RESTAURANT", "MIDDLE_SCHOOL", "MILITARY_AIRPORT", "MINERAL_OR_HOT_SPRINGS", "MINING_COMPANY", "MOBILE_PHONE_SHOP", "MONGOLIAN_RESTAURANT", "MONUMENT", "MOROCCAN_RESTAURANT", "MOSQUE", "MOTEL", "MOTORCYCLE_DEALER", "MOTORCYCLE_REPAIR", "MOTORING_ORGANIZATION_OFFICE", "MOTOR_RACING_STADIUM", "MOUNTAIN_BIKE_TRAIL", "MOUNTAIN_PASS", "MOUNTAIN_PEAK", "MOVIE_THEATER", "MOVING_AND_STORAGE_COMPANY", "MULTI_PURPOSE_STADIUM", "MUSEUM", "MUSIC_CENTER", "MUSIC_INSTRUMENTS_STORE", "NAIL_SALON", "NATIONAL_RAILROAD_STATION", "NATURAL_FEATURE", "NATURAL_TOURIST_ATTRACTION", "NEPALESE_RESTAURANT", "NETBALL_STADIUM", "NEWSAGENTS_TOBACCONISTS", "NIGHTLIFE", "NON_GOVERNMENTAL_ORGANIZATION", "NORWEGIAN_RESTAURANT", "OASIS", "OBSERVATORY", "OFFICE_EQUIPMENT", "OIL_AND_NATURAL_GAS", "OPEN_CAR_PARKING_AREA", "OPEN_CAR_PARKING_AREA_GENERIC", "OPERA_HOUSE", "OPTICIAN", "ORGANIC_FOOD_RESTAURANT", "ORIENTAL_RESTAURANT", "PAGODA", "PAINTING_DECORATING", "PAKISTANI_RESTAURANT", "PAN", "PARK", "PARKING_GARAGE", "PARKWAY", "PARK_AND_RECREATION_AREA", "PASSENGER_TRANSPORT_TICKET_OFFICE", "PAWN_SHOP", "PEDESTRIAN_SUBWAY", "PERSONAL_CARE_FACILITY", "PERSONAL_SERVICE", "PERUVIAN_RESTAURANT", "PET_SUPPLIES", "PHARMACEUTICAL_COMPANY", "PHARMACY", "PHILIPPINE_RESTAURANT", "PHOTOCOPY_SHOP", "PHOTO_LAB_OR_DEVELOPMENT", "PICNIC_AREA", "PIZZERIA", "PLAIN_OR_FLAT", "PLANETARIUM", "PLATEAU", "POLICE_STATION", "POLISH_RESTAURANT", "PORTUGUESE_RESTAURANT", "PORT_WAREHOUSE_FACILITY", "POST_OFFICE", "PRE_SCHOOL", "PRIMARY_PRODUCER", "PRIMARY_RESOURCE_UTILITY", "PRIMARY_SCHOOL", "PRISON", "PRIVATE_AIRPORT", "PROTECTED_LAND", "PUB", "PUBLIC_AIRPORT", "PUBLIC_AMENITY", "PUBLIC_BATHROOM", "PUBLIC_CALL_BOX", "PUBLIC_LIBRARY", "PUBLIC_MARKET", "PUBLIC_TRANSPORT_STOP", "PUBLISHING_TECHNOLOGIES", "QUARRY", "RACE_TRACK", "RAILWAY_STATION", "RAPIDS", "REAL_ESTATE_AGENT", "REAL_ESTATE_COMPANY", "RECREATIONAL_CAMPING_GROUND", "RECREATIONAL_MARIJUANA_DISPENSARY", "RECREATIONAL_VEHICLE_DEALER", "RECREATION_AREA", "RECYCLING_SHOP", "REEF", "RELIGIOUS_SITE", "RENTAL_CAR_PARKING", "RESCUE_SERVICE", "RESEARCH_FACILITY", "RESERVOIR", "RESIDENTIAL_ACCOMMODATION", "RESIDENTIAL_ENTRANCE", "RESORT", "RESTAURANT", "RESTAURANT_AREA", "REST_AREA", "REST_CAMP", "RETAIL_OUTLET", "RETIREMENT_COMMUNITY", "RIDGE", "RIVER_CROSSING", "ROCKS", "ROCK_CLIMBING_TRAIL", "RUGBY_GROUND", "RUSSIAN_RESTAURANT", "SALAD_BAR", "SANDWICH_RESTAURANT", "SAUNA_SOLARIUM_MASSAGE", "SCANDINAVIAN_RESTAURANT", "SCHOOL", "SCHOOL_BUS_COMPANY", "SCHOOL_GENERIC", "SEAFOOD", "SECURED_ENTRANCE", "SECURITY_PRODUCTS", "SENIOR_HIGH_SCHOOL", "SERVICE_COMPANY", "SHANDONG_RESTAURANT", "SHOPPING_SERVICE", "SHOP_OR_STORE", "SICHUAN_RESTAURANT", "SKI_RESORT", "SNACKS_RESTAURANT", "SOCCER_STADIUM", "SOFTWARE_COMPANY", "SOUL_FOOD", "SOUP_RESTAURANT", "SPANISH_RESTAURANT", "SPECIALIST", "SPECIALTY_CLOTHING_SHOP", "SPECIALTY_FOODS", "SPECIAL_HOSPITAL", "SPORTS_CENTER", "SPORTS_CENTER_GENERIC", "SPORTS_EQUIPMENT_AND_CLOTHING", "SQUASH_COURT", "STADIUM", "STATION_ACCESS", "STATUE", "STEAK_HOUSE", "STOCK_EXCHANGE", "STREETCAR_STOP", "SUBWAY_ENTRANCE", "SUBWAY_STATION", "SUPERMARKET", "SUSHI_RESTAURANT", "SWEDISH_RESTAURANT", "SWIMMING_POOL", "SWISS_RESTAURANT", "SYNAGOG", "SYRIAN_RESTAURANT", "TAILOR_SHOP", "TAIWANESE_RESTAURANT", "TAKEOUT_FOOD", "TAPAS_RESTAURANT", "TAXI_LIMOUSINE_AND_SHUTTLE_SERVICE", "TAXI_STAND", "TAX_SERVICES", "TEA_HOUSE", "TELECOMMUNICATIONS", "TEMPLE", "TENNIS_COURT", "TEPPANYAKI_RESTAURANT", "THAI_RESTAURANT", "THEATER", "THEATER_GENERIC", "THEMATIC_SPORT_CENTER", "TIBETAN_RESTAURANT", "TIRE_SERVICE", "TOLL_GATE", "TOURIST_ATTRACTION", "TOURIST_INFORMATION", "TOWER", "TOYS_GAMES_SHOP", "TRAFFIC_CONTROL_DEPARTMENT", "TRAFFIC_CONTROL_DEPARTMENT_GENERIC", "TRAIL_SYSTEM", "TRANSPORT_ACCESS", "TRANSPORT_AUTHORITY_VEHICLE_REGISTRATION", "TRANSPORT_COMPANY", "TRAVEL_AGENT", "TRUCK_DEALER", "TRUCK_REPAIR_AND_SERVICE", "TRUCK_STOP", "TUNISIAN_RESTAURANT", "TUNNEL", "TURKISH_RESTAURANT", "URBAN_STATION", "VALLEY", "VAN_DEALER", "VARIETY_STORE", "VEGETARIAN_RESTAURANT", "VEHICLE_DEALER", "VEHICLE_REPAIR", "VENEZUELAN_RESTAURANT", "VETERINARY", "VIDEO_RENTAL_SHOP", "VIETNAMESE_RESTAURANT", "VIEWPOINT", "VILLA_RENTAL", "VOCATIONAL_SCHOOL", "WATER_HOLE", "WATER_SPORT", "WEDDING_SERVICES", "WEIGH_STATION", "WEIGH_STATION_GENERIC", "WELFARE_ORGANIZATION", "WELL", "WESTERN_RESTAURANT", "WHOLESALE_CLUB", "WILDERNESS_AREA", "WILDLIFE_PARK", "WINERY", "WINE_SPIRITS", "WOMEN_S_CLOTHING", "YACHT_BASIN", "ZOO", "ZOOS_ARBORETA_BOTANICAL_GARDEN"];
 /**
+ * The SDK's code for a category of point of interest, such as `'RESTAURANT'`.
  * @group Place
  */
 export type POICategory = (typeof poiCategories)[number];
@@ -1327,7 +1281,7 @@ type POI = {
   /**
    * The standardized category identifiers of the POI.
    *
-   * They are machine-readable names from the {@link POICategory} enum, such as `'ITALIAN_RESTAURANT'`,
+   * They are machine-readable {@link POICategory} codes, such as `'ITALIAN_RESTAURANT'`,
    * `'FUEL_STATION'` or `'HOTEL'`, parsed from the numeric category IDs the API returns.
    * Use them for filtering, programmatic category matching or mapping to icons.
    */
@@ -1380,7 +1334,7 @@ type RelatedPOI = {
   /**
    * The unique identifier of the related POI.
    *
-   * Pass it to the Place by ID service to fetch detailed information
+   * Pass it to `getPlaceDetails` as its `entityId` to fetch detailed information
    * about the related location.
    */
   id: string;
@@ -1407,11 +1361,6 @@ export declare const geographyTypes: readonly ["Country", "CountrySubdivision",
  * - `Neighbourhood`: Named neighborhood or area within a city
  * - `PostalCodeArea`: Area defined by postal/ZIP code
  *
- * @example
- * ```typescript
- * const geographyType: GeographyType = 'Municipality';  // City level
- * ```
- *
  * @group Place
  */
 export type GeographyType = (typeof geographyTypes)[number];
@@ -1442,11 +1391,10 @@ export type MapcodeType = 'Local' | 'International' | 'Alternative';
  *   code: '4J.P2'
  * };
  *
- * // International mapcode (no territory needed)
- * const intlMapcode: Mapcode = {
+ * // International mapcode (no territory or code)
+ * const internationalMapcode: Mapcode = {
  *   type: 'International',
- *   fullMapcode: 'VHXGB.4J9W',
- *   code: 'VHXGB.4J9W'
+ *   fullMapcode: 'VHXGB.4J9W'
  * };
  * ```
  *
@@ -1463,7 +1411,7 @@ export type Mapcode = {
   /**
    * The complete mapcode, including the territory if applicable.
    *
-   * Its format, always unambiguous, is "TERRITORY CODE" for local and "CODE" for international mapcodes.
+   * Its format, always unambiguous, is "TERRITORY CODE" for local and alternative mapcodes, and "CODE" for international ones.
    */
   fullMapcode: string;
   /**
@@ -1561,11 +1509,6 @@ export declare const placeTypes: readonly ["POI", "Street", "Geography", "Point
  * - `Address Range`: Range of addresses along a street segment
  * - `Cross Street`: Intersection of two streets
  *
- * @example
- * ```typescript
- * const placeType: PlaceType = 'POI';
- * ```
- *
  * @group Place
  */
 export type PlaceType = (typeof placeTypes)[number];
@@ -1710,14 +1653,11 @@ export type CommonPlaceProps = {
   chargingPark?: ChargingPark;
   /**
    * References to additional data sources, with IDs for fetching more detailed information
-   * from other services (geometry, availability, POI details).
+   * from other services (geometry).
    */
   dataSources?: PlaceDataSources;
   /**
    * The physical entry points (entrances) of the place.
-   *
-   * Navigation can use them to direct users to the correct entrance. Reverse geocoding
-   * returns them unclassified, so their `type` is absent.
    */
   entryPoints?: EntryPoint[];
   /**
@@ -1840,7 +1780,7 @@ export type Place<P extends CommonPlaceProps = CommonPlaceProps> = Omit<Feature<
 export type Places<P extends CommonPlaceProps = CommonPlaceProps, FeatureCollectionProps = unknown> = Omit<FeatureCollectionWithProperties<Point, P, FeatureCollectionProps>, 'features' | 'bbox'> & {
   /**
    * The bounding box of all the places, including their own bounding boxes.
-   * It is present only if there are places.
+   * It is present only when the places span an area.
    */
   bbox?: BBox;
   /**
@@ -1872,7 +1812,7 @@ export type Places<P extends CommonPlaceProps = CommonPlaceProps, FeatureCollect
  * const fuels: Fuel[] = ['Petrol', 'Diesel', 'LPG'];
  *
  * // Hydrogen fuel cell station
- * const fuels: Fuel[] = ['Hydrogen'];
+ * const hydrogenOnly: Fuel[] = ['Hydrogen'];
  * ```
  *
  * @group Place
@@ -1893,12 +1833,6 @@ export declare const budgetTypes: readonly ["timeMinutes", "distanceKM"];
  * - `timeMinutes`: Travel time in minutes (isochrone), as in "Where can I reach in 30 minutes?"
  * - `distanceKM`: Travel distance in kilometers (isodistance), as in "What's within 10 km?"
  *
- * @example
- * ```typescript
- * const timeType: BudgetType = 'timeMinutes';
- * const distanceType: BudgetType = 'distanceKM';
- * ```
- *
  * @group Reachable Range
  */
 export type BudgetType = (typeof budgetTypes)[number];
@@ -1939,12 +1873,6 @@ export type ReachableRangeBudget = {
    *
    * @remarks
    * Typical values are 5-60 minutes for time and 5-100 km for distance.
-   *
-   * @example
-   * ```typescript
-   * value: 30    // 30 minutes or km depending on type
-   * value: 15.5  // Decimal values supported
-   * ```
    */
   value: number;
 };
@@ -1983,9 +1911,10 @@ export type DelayMagnitude = 'unknown' | 'minor' | 'moderate' | 'major' | 'indef
  *
  * @remarks
  * A strict subset of {@link fullTrafficIncidentCategories}, so every value here is
- * also a valid response category. The two omitted values, `'animals-on-road'` and
- * `'narrow-lanes'`, have no Incident Details category and appear only on traffic
- * vector-tile features.
+ * also a valid response category.
+ *
+ * The two omitted values, `'animals-on-road'` and `'narrow-lanes'`, have no Incident
+ * Details category.
  *
  * @see https://docs.tomtom.com/traffic-api/documentation/tomtom-orbis-maps/v2/traffic-incidents/incident-details
  * @group Traffic
@@ -1995,12 +1924,9 @@ export declare const trafficIncidentRequestCategories: readonly ["accident", "br
  * All possible traffic incident categories.
  *
  * @remarks
- * It combines {@link trafficIncidentRequestCategories}, which you can both send as
- * filters and receive in responses, with the tile-only categories `'animals-on-road'`
- * and `'narrow-lanes'`. Those two appear on vector-tile features but never in an
- * Incident Details response or filter. Use this list for categories you receive, and
- * {@link trafficIncidentRequestCategories} for categories you send to the Incident
- * Details API as a `categoryFilter` input.
+ * It adds to {@link trafficIncidentRequestCategories} the two categories with no Incident Details
+ * category, which that list leaves out. Use this list for categories you receive, and that one for categories you send
+ * to the Incident Details API as a `categoryFilter` input.
  *
  * @group Traffic
  */
@@ -2136,8 +2062,7 @@ export type TrafficIncidentBaseProperties = {
 /**
  * Full properties of a traffic incident from the Incident Details service.
  *
- * Extends {@link TrafficIncidentBaseProperties} with fields available in the
- * Incident Details API response but not in map vector-tile features.
+ * Extends {@link TrafficIncidentBaseProperties} with fields of the Incident Details API response.
  *
  * @group Traffic
  */
@@ -2184,144 +2109,536 @@ export type TrafficIncident = Feature<Point | LineString, TrafficIncidentPropert
  *
  * @group Traffic
  */
-export type TrafficIncidentDetails = FeatureCollection<Point | LineString, TrafficIncidentProperties>;
+export type TrafficIncidentDetails = FeatureCollection<TrafficIncident['geometry'], TrafficIncident['properties']>;
 //#endregion
-//#region src/types/route/guidance.d.ts
-/**
- * Whether traffic drives on the left or right at the point of the maneuver.
- * @group Route
- */
-type DrivingSide = 'LEFT' | 'RIGHT';
-/**
- * A property of a road.
- * - `URBAN`: An urban road.
- * - `MOTORWAY`: A motorway.
- * - `CONTROLLED_ACCESS`: A controlled access road, with regulated traffic flow and regulated entries and exits.
- * @group Route
- */
-type RoadInformationProperty = 'URBAN' | 'MOTORWAY' | 'CONTROLLED_ACCESS';
-/**
- * A landmark that instructions can refer to.
- * @group Route
- */
-type Landmark = 'END_OF_ROAD' | 'AT_TRAFFIC_LIGHT' | 'ON_TO_BRIDGE' | 'ON_BRIDGE' | 'AFTER_BRIDGE' | 'INTO_TUNNEL' | 'INSIDE_TUNNEL' | 'AFTER_TUNNEL';
-/**
- * The maneuver, for example arrive or turn right.
- * @see https://docs.tomtom.com/routing-api/documentation/routing/calculate-route#maneuver-codes
- * @group Route
- */
-type Maneuver = 'DEPART' | 'WAYPOINT_LEFT' | 'WAYPOINT_RIGHT' | 'WAYPOINT_REACHED' | 'WAYPOINT_AHEAD' | 'ARRIVE' | 'ARRIVE_LEFT' | 'ARRIVE_RIGHT' | 'ARRIVE_AHEAD' | 'STRAIGHT' | 'KEEP_LEFT' | 'KEEP_RIGHT' | 'SLIGHT_RIGHT' | 'TURN_RIGHT' | 'SHARP_RIGHT' | 'SLIGHT_LEFT' | 'TURN_LEFT' | 'SHARP_LEFT' | 'MAKE_UTURN' | 'ROUNDABOUT_STRAIGHT' | 'ROUNDABOUT_SHARP_RIGHT' | 'ROUNDABOUT_RIGHT' | 'ROUNDABOUT_SLIGHT_RIGHT' | 'ROUNDABOUT_SLIGHT_LEFT' | 'ROUNDABOUT_LEFT' | 'ROUNDABOUT_SHARP_LEFT' | 'ROUNDABOUT_BACK' | 'EXIT_ROUNDABOUT' | 'EXIT_MOTORWAY_LEFT' | 'EXIT_MOTORWAY_RIGHT' | 'SWITCH_MOTORWAY_LEFT' | 'SWITCH_MOTORWAY_RIGHT' | 'ENTER_CARPOOL_LANE_LEFT' | 'ENTER_CARPOOL_LANE_RIGHT' | 'EXIT_CARPOOL_LANE_LEFT' | 'EXIT_CARPOOL_LANE_RIGHT' | 'MERGE_LEFT_LANE' | 'MERGE_RIGHT_LANE' | 'TAKE_SHIP_FERRY' | 'TAKE_CAR_TRAIN' | 'LEAVE_SHIP_FERRY' | 'LEAVE_CAR_TRAIN' | 'CROSS_BORDER' | 'TOLLGATE';
-/**
- * The side from which the road connects to the route.
- * @group Route
- */
-type SideRoadSide = 'LEFT' | 'RIGHT' | 'LEFT_AND_RIGHT';
-/**
- * A direction relative to the vehicle's approach, used by {@link ManeuverView} to describe the
- * junction geometry at a maneuver.
- *
- * These are relative directions, not angles in degrees. The API reports the road layout as a
- * small vocabulary of bearings.
- * @group Route
- */
-type ManeuverAngle = 'STRAIGHT' | 'SLIGHT_RIGHT' | 'RIGHT' | 'SHARP_RIGHT' | 'SLIGHT_LEFT' | 'LEFT' | 'SHARP_LEFT' | 'BACK';
-/**
- * The kind of roundabout a roundabout maneuver takes place on.
- * @group Route
- */
-type RoundaboutType = 'REGULAR' | 'SMALL';
-/**
- * A toll payment option.
- * @group Route
- */
-type TollPaymentType = 'CASH_COINS_AND_BILLS' | 'CASH_BILLS_ONLY' | 'CASH_COINS_ONLY' | 'CASH_EXACT_CHANGE' | 'CREDIT_CARD' | 'DEBIT_CARD' | 'TRAVEL_CARD' | 'ETC' | 'ETC_TRANSPONDER' | 'ETC_VIDEO_CAMERA' | 'SUBSCRIPTION';
+//#region src/types/route/summary.d.ts
 /**
- * A point on the route path, with its metadata.
+ * The summary of a route or route leg, with departure and arrival times, lengths and durations.
  * @group Route
  */
-type RoutePathPoint = {
+type SummaryBase = {
   /**
-   * The position of this point on the route.
+   * The estimated arrival time at the end of the route or leg.
+   *
+   * It is the departure time plus the travel time, accounting for traffic conditions.
    */
-  point: Position;
+  arrivalTime: Date;
   /**
-   * The distance in meters from the start of the route to this point.
+   * The departure time from the beginning of the route or leg, based on the one the routing
+   * request specified.
+   */
+  departureTime: Date;
+  /**
+   * Total length of the route or leg in meters.
    */
-  distanceInMeters: number;
+  lengthInMeters: number;
   /**
-   * The time in seconds from the start of the route to this point.
+   * The estimated travel time of the route or leg in seconds.
+   *
+   * @remarks
+   * It includes delays due to real-time traffic. For the free-flow travel time without traffic
+   * delays, use `noTrafficTravelTimeInSeconds`.
    */
   travelTimeInSeconds: number;
-};
-/**
- * The name of a street, road number, exit, intersection, tollgate or country in a guidance
- * instruction.
- * @group Route
- */
-type InstructionText = {
   /**
-   * The name as a text string.
+   * The delay in seconds of the traffic events along `trafficLengthInMeters`.
+   *
+   * @remarks
+   * It is present only when the routing service sends it, and it is not the gap to free-flow
+   * conditions.
+   *
+   * For the gap to free-flow, request the travel times with `computeTravelTimeFor: 'all'` and use
+   * `Math.max(0, liveTrafficIncidentsTravelTimeInSeconds - noTrafficTravelTimeInSeconds)`. The live
+   * travel time can fall below the free-flow one, so keep the floor at 0.
    */
-  text: string;
-};
-/**
- * A single road shield reference.
- * @group Route
- */
-type RoadShieldReference = {
+  trafficDelayInSeconds?: number;
   /**
-   * A unique identifier for the road shield.
+   * The length in meters of the route that traffic events delay, which is the portion with
+   * congestion or incidents.
+   *
+   * @remarks
+   * It is present only when the routing service sends it.
    */
-  reference: string;
+  trafficLengthInMeters?: number;
   /**
-   * The text to show on the road shield.
+   * The estimated travel time in seconds in free-flow conditions, as if there were no traffic
+   * delays (no congestion).
+   *
+   * It is present only if you request it with the `computeTravelTimeFor` parameter.
    */
-  shieldContent?: string;
+  noTrafficTravelTimeInSeconds?: number;
   /**
-   * The possible affixes to show in addition to the `shieldContent`.
+   * The estimated travel time in seconds from time-dependent historic traffic data.
+   *
+   * It is the expected travel time from typical traffic patterns at the requested departure
+   * time, such as rush hour or off-peak. It is present only if you request it with the
+   * `computeTravelTimeFor` parameter.
    */
-  affixes?: string[];
-};
-/**
- * A road shield, with extra information.
- * @group Route
- */
-type RoadShield = {
+  historicTrafficTravelTimeInSeconds?: number;
   /**
-   * The road number. Most road numbers have a 'letter' prefix, which is also returned.
+   * The estimated travel time in seconds from real-time traffic speed data, based on current
+   * live traffic conditions and incidents.
+   *
+   * It is present only if you request it with the `computeTravelTimeFor` parameter.
    */
-  roadNumber: InstructionText;
+  liveTrafficIncidentsTravelTimeInSeconds?: number;
   /**
-   * What the client needs to build an image of the road shield with the TomTom RoadShield API.
-   * It is present if a road shield image is available for this road.
+   * The distance in meters from the origin point to the first point where this route forks off from the reference route.
+   *
+   * @remarks
+   * If the route is identical to the reference route, it is the length of the route. Every
+   * alternative route summary has it, but the reference route's doesn't.
    */
-  roadShieldReference?: RoadShieldReference;
+  deviationDistanceInMeters?: number;
   /**
-   * The state code of the state the shield is in (second part of an ISO 3166-2 identifier).
-   * It is present if state codes are available for the shield's country.
+   * The travel time in seconds from the origin point to the first point where this route forks off from the reference route.
+   *
+   * @remarks
+   * If the route is identical to the reference route, it is the estimated travel time of the
+   * route. Every alternative route summary has it, but the reference route's doesn't.
    */
-  stateCode?: string;
+  deviationTimeInSeconds?: number;
   /**
-   * The country code (ISO 3166-1 alpha-3) of the country the shield is in.
+   * The coordinates of the first point where this route forks off from the reference route.
+   *
+   * @remarks
+   * If the route is identical to the reference route, it is the last point on the route.
+   * Every alternative route summary has it, but the reference route's doesn't.
    */
-  countryCode: string;
+  deviationPoint?: Position;
 };
 /**
- * Road information, including properties, street name and road shields.
+ * The summary of an entire route, with all journey statistics from origin to destination,
+ * including the stops along the way.
+ *
  * @group Route
  */
-type RoadInformation = {
-  /**
-   * The properties of the road, possibly several combined.
-   */
-  properties: RoadInformationProperty[];
+type RouteSummary = SummaryBase;
+/**
+ * The summary of a single route leg, the portion of the route between two consecutive waypoints.
+ *
+ * @remarks
+ * - An A→B route has 1 leg
+ * - An A→B→C route has 2 legs (A→B, B→C)
+ *
+ * @group Route
+ */
+type LegSummary = SummaryBase & {
+  /**
+   * The time in seconds the vehicle stands still at the stop this leg arrives at.
+   *
+   * @remarks
+   * It is the wait a {@link WaypointProps.pauseDurationSeconds} asked for, as the service actually
+   * planned it rather than an echo of the request. That is the gap between this leg's `arrivalTime`
+   * and the next leg's `departureTime`.
+   *
+   * - It is absent when the vehicle does not stop at the end of this leg.
+   * - It is absent on the last leg, which has no following departure. The routing service does not
+   *   accept a wait at the destination anyway.
+   * - This leg's own `travelTimeInSeconds` is driving only and *excludes* the stop, while the
+   *   route's total *includes* every stop. So driving time is the sum of the legs, and the time
+   *   spent standing still is the difference.
+   *
+   * @example
+   * ```typescript
+   * // A waypoint with pauseDurationSeconds: 1800
+   * stopTimeInSeconds: 1800
+   * ```
+   */
+  stopTimeInSeconds?: number;
+};
+//#endregion
+//#region src/types/route/route.d.ts
+/**
+ * All the road and route features that route calculation can avoid.
+ *
+ * Use it to derive the {@link Avoidable} type or to validate user input against the supported
+ * avoidance options.
+ *
+ * @remarks
+ * This readonly tuple is the source of truth for valid avoidance types. The {@link Avoidable}
+ * type derives from it, for type safety.
+ *
+ * @example
+ * ```typescript
+ * // Check if a string is a valid avoidance type
+ * const userInput: string = 'tollRoads';
+ * const knownAvoidables: readonly string[] = avoidableTypes;
+ * if (knownAvoidables.includes(userInput)) {
+ *   // userInput is valid
+ * }
+ * ```
+ *
+ * @group Route
+ */
+export declare const avoidableTypes: readonly ["tollRoads", "motorways", "ferries", "unpavedRoads", "carpools", "alreadyUsedRoads", "borderCrossings", "tunnels", "carTrains", "lowEmissionZones"];
+/**
+ * A route feature that the routing engine tries to avoid when calculating routes.
+ *
+ * Use it to customize routes for vehicle capabilities, user preferences or regulatory
+ * requirements. Note that avoidance is not guaranteed if no alternative route exists.
+ *
+ * @remarks
+ * The avoidance options:
+ * - `tollRoads`: Avoids roads requiring toll payments
+ * - `motorways`: Avoids high-speed limited-access highways
+ * - `ferries`: Avoids water crossings requiring ferry transport
+ * - `unpavedRoads`: Avoids unpaved/dirt roads (recommended for standard vehicles)
+ * - `carpools`: Avoids carpool/HOV (High Occupancy Vehicle) lanes
+ * - `alreadyUsedRoads`: Prevents using the same road segment multiple times
+ * - `borderCrossings`: Avoids crossing international borders
+ * - `tunnels`: Avoids underground tunnels
+ * - `carTrains`: Avoids car train transport segments
+ * - `lowEmissionZones`: Avoids zones with vehicle emission restrictions
+ *
+ * @example
+ * ```typescript
+ * // Avoid tolls and motorways for a scenic route
+ * const scenicAvoid: Avoidable[] = ['tollRoads', 'motorways'];
+ *
+ * // Avoid unpaved roads for a standard car
+ * const carAvoid: Avoidable[] = ['unpavedRoads'];
+ * ```
+ *
+ * @group Route
+ */
+export type Avoidable = (typeof avoidableTypes)[number];
+/**
+ * The primary mode of transportation for route calculation.
+ *
+ * It determines the road type preferences, speed calculations and routing rules of the
+ * calculated route. Currently, only `'car'` is supported.
+ *
+ * @remarks
+ * Future versions may support additional modes such as truck, taxi, bus, bicycle and pedestrian.
+ *
+ * @group Route
+ */
+export type TravelMode = 'car';
+/**
+ * The cumulative distance and time at a position along the route.
+ *
+ * Both fields are optional because a progress entry may omit either value. Interpolation
+ * utilities return the resolved, always-present equivalent, {@link RouteProgressAtPoint}.
+ *
+ * @group Route
+ */
+export type RouteProgress = {
+  /**
+   * Cumulative travel time in seconds from the route start.
+   */
+  travelTimeInSeconds?: number;
+  /**
+   * Cumulative distance in meters from the route start.
+   */
+  distanceInMeters?: number;
+};
+/**
+ * The progress at a specific coordinate on the route path.
+ *
+ * It adds to {@link RouteProgress} a `pointIndex` that identifies the coordinate's entry in
+ * the route's coordinate array.
+ *
+ * @remarks
+ * The `progress` array of a route always has entries for the first and last points. You can
+ * linearly interpolate the progress of intermediate points between entries.
+ *
+ * @example
+ * ```typescript
+ * const points: RouteProgressPoint[] = [
+ *   { pointIndex: 0,   travelTimeInSeconds: 0,   distanceInMeters: 0    },
+ *   { pointIndex: 50,  travelTimeInSeconds: 120,  distanceInMeters: 2500 },
+ *   { pointIndex: 100, travelTimeInSeconds: 300,  distanceInMeters: 5000 }
+ * ];
+ * ```
+ *
+ * @group Route
+ */
+export type RouteProgressPoint = RouteProgress & {
+  /**
+   * Zero-based index of this point in the route's coordinate array.
+   */
+  pointIndex: number;
+};
+/**
+ * A distance and a time along the route, both known.
+ *
+ * @group Route
+ */
+export type RouteProgressAtPoint = Required<RouteProgress>;
+/**
+ * The progress over a segment between two arbitrary points on the route path.
+ *
+ * @group Route
+ */
+export type RouteSegmentProgress = {
+  /** Progress at the start point. */
+  start: RouteProgressAtPoint;
+  /** Progress at the end point. */
+  end: RouteProgressAtPoint;
+  /** The distance and time the segment covers, as end minus start. */
+  delta: RouteProgressAtPoint;
+};
+/**
+ * Geographic coordinate and cumulative progress values at a specific point along a route.
+ *
+ * @group Utils
+ */
+export type RouteCoordinateAtProgress = RouteProgressAtPoint & {
+  /** Geographic position as a GeoJSON `[longitude, latitude]` coordinate. */
+  position: Position;
+};
+/**
+ * A discriminated union that identifies a position along a route.
+ * Provide exactly one of the three variants.
+ *
+ * @group Utils
+ */
+export type RouteProgressQuery = {
+  traveledTimeInSeconds: number;
+} | {
+  traveledDistanceInMeters: number;
+} | {
+  clockTime: Date;
+};
+/**
+ * All the information of a calculated route, including its summary statistics, sections,
+ * guidance instructions and progress data.
+ *
+ * @group Route
+ */
+export type RouteProps = {
+  /**
+   * The summary statistics of the entire route, with departure and arrival times, total length
+   * and duration.
+   */
+  summary: RouteSummary;
+  /**
+   * The route sections, which are portions of the route with distinct properties such as:
+   * - Countries traversed
+   * - Traffic incidents
+   * - Route legs (segments between waypoints)
+   * - Special road types (tunnels, ferries, toll roads)
+   */
+  sections: SectionsProps;
+  /**
+   * The turn-by-turn navigation instructions, with maneuvers, road names and instruction text.
+   *
+   * They are present only when guidance was requested and is available.
+   */
+  guidance?: Guidance;
+  /**
+   * The distance and time progress at key points along the route.
+   *
+   * It is present when extended route representations are requested, which is the default for route
+   * calculations. Use it to display progress information or calculate intermediate times.
+   */
+  progress?: RouteProgressPoint[];
+  /**
+   * The index of this route among the alternatives.
+   *
+   * The first route (index 0) is typically the recommended or best route, and the rest are alternatives.
+   */
+  index: number;
+};
+/**
+ * A calculated route, as a GeoJSON Feature.
+ *
+ * Its geometry is a LineString of the route path coordinates, and its properties hold all
+ * route information (summary, sections, guidance).
+ *
+ * @typeParam P - Type of the route properties (defaults to RouteProps)
+ *
+ * @example
+ * ```typescript
+ * const route: Route = {
+ *   type: 'Feature',
+ *   id: 'route-123',
+ *   geometry: {
+ *     type: 'LineString',
+ *     coordinates: [[4.9, 52.3], [4.91, 52.31], ...]
+ *   },
+ *   properties: {
+ *     summary: { lengthInMeters: 5000, travelTimeInSeconds: 300, ... },
+ *     sections: { ... },
+ *     index: 0
+ *   },
+ *   bbox: [4.9, 52.3, 4.91, 52.31]
+ * };
+ * ```
+ *
+ * @group Route
+ */
+export type Route<P extends RouteProps = RouteProps> = Omit<Feature<LineString, P>, 'id' | 'bbox'> & {
+  /**
+   * The unique identifier of this route, randomly generated to tell route alternatives apart.
+   */
+  id: string;
+  /**
+   * The bounding box of the entire route, or at least of its waypoints.
+   */
+  bbox: BBox;
+};
+/**
+ * A GeoJSON FeatureCollection of one or more calculated routes.
+ *
+ * It typically holds the main route (index 0) and optional alternative routes. `calculateRoute`
+ * sets no collection properties.
+ *
+ * @typeParam P - Type of individual route properties (defaults to RouteProps)
+ * @typeParam FeatureCollectionProps - Type of collection-level properties
+ *
+ * @example
+ * ```typescript
+ * const routes: Routes = {
+ *   type: 'FeatureCollection',
+ *   features: [
+ *     { type: 'Feature', geometry: {...}, properties: { index: 0, ... } }, // Main route
+ *     { type: 'Feature', geometry: {...}, properties: { index: 1, ... } }  // Alternative
+ *   ]
+ * };
+ * ```
+ *
+ * @group Route
+ */
+export type Routes<P extends RouteProps = RouteProps, FeatureCollectionProps = unknown> = Omit<FeatureCollectionWithProperties<LineString, P, FeatureCollectionProps>, 'features' | 'bbox'> & {
+  /**
+   * The route features.
+   */
+  features: Route<P>[];
+  /**
+   * The bounding box of all the routes, or at least of their waypoints. It is defined only if there are routes.
+   */
+  bbox?: BBox;
+};
+//#endregion
+//#region src/types/route/guidance.d.ts
+/**
+ * Whether traffic drives on the left or right at the point of the maneuver.
+ * @group Route
+ */
+type DrivingSide = 'LEFT' | 'RIGHT';
+/**
+ * A property of a road.
+ * - `URBAN`: An urban road.
+ * - `MOTORWAY`: A motorway.
+ * - `CONTROLLED_ACCESS`: A controlled access road, with regulated traffic flow and regulated entries and exits.
+ * @group Route
+ */
+type RoadInformationProperty = 'URBAN' | 'MOTORWAY' | 'CONTROLLED_ACCESS';
+/**
+ * A landmark that instructions can refer to.
+ * @group Route
+ */
+type Landmark = 'END_OF_ROAD' | 'AT_TRAFFIC_LIGHT' | 'ON_TO_BRIDGE' | 'ON_BRIDGE' | 'AFTER_BRIDGE' | 'INTO_TUNNEL' | 'INSIDE_TUNNEL' | 'AFTER_TUNNEL';
+/**
+ * The maneuver, for example arrive or turn right.
+ * @see https://docs.tomtom.com/routing-api/documentation/routing/calculate-route#maneuver-codes
+ * @group Route
+ */
+type Maneuver = 'DEPART' | 'WAYPOINT_LEFT' | 'WAYPOINT_RIGHT' | 'WAYPOINT_REACHED' | 'WAYPOINT_AHEAD' | 'ARRIVE' | 'ARRIVE_LEFT' | 'ARRIVE_RIGHT' | 'ARRIVE_AHEAD' | 'STRAIGHT' | 'KEEP_LEFT' | 'KEEP_RIGHT' | 'SLIGHT_RIGHT' | 'TURN_RIGHT' | 'SHARP_RIGHT' | 'SLIGHT_LEFT' | 'TURN_LEFT' | 'SHARP_LEFT' | 'MAKE_UTURN' | 'ROUNDABOUT_STRAIGHT' | 'ROUNDABOUT_SHARP_RIGHT' | 'ROUNDABOUT_RIGHT' | 'ROUNDABOUT_SLIGHT_RIGHT' | 'ROUNDABOUT_SLIGHT_LEFT' | 'ROUNDABOUT_LEFT' | 'ROUNDABOUT_SHARP_LEFT' | 'ROUNDABOUT_BACK' | 'EXIT_ROUNDABOUT' | 'EXIT_MOTORWAY_LEFT' | 'EXIT_MOTORWAY_RIGHT' | 'SWITCH_MOTORWAY_LEFT' | 'SWITCH_MOTORWAY_RIGHT' | 'ENTER_CARPOOL_LANE_LEFT' | 'ENTER_CARPOOL_LANE_RIGHT' | 'EXIT_CARPOOL_LANE_LEFT' | 'EXIT_CARPOOL_LANE_RIGHT' | 'MERGE_LEFT_LANE' | 'MERGE_RIGHT_LANE' | 'TAKE_SHIP_FERRY' | 'TAKE_CAR_TRAIN' | 'LEAVE_SHIP_FERRY' | 'LEAVE_CAR_TRAIN' | 'CROSS_BORDER' | 'TOLLGATE';
+/**
+ * The side from which the road connects to the route.
+ * @group Route
+ */
+type SideRoadSide = 'LEFT' | 'RIGHT' | 'LEFT_AND_RIGHT';
+/**
+ * A direction relative to the vehicle's approach, used by {@link ManeuverView} to describe the
+ * junction geometry at a maneuver.
+ *
+ * These are relative directions, not angles in degrees. The API reports the road layout as a
+ * small vocabulary of bearings.
+ * @group Route
+ */
+type ManeuverAngle = 'STRAIGHT' | 'SLIGHT_RIGHT' | 'RIGHT' | 'SHARP_RIGHT' | 'SLIGHT_LEFT' | 'LEFT' | 'SHARP_LEFT' | 'BACK';
+/**
+ * The kind of roundabout a roundabout maneuver takes place on.
+ * @group Route
+ */
+type RoundaboutType = 'REGULAR' | 'SMALL';
+/**
+ * A toll payment option.
+ * @group Route
+ */
+type TollPaymentType = 'CASH_COINS_AND_BILLS' | 'CASH_BILLS_ONLY' | 'CASH_COINS_ONLY' | 'CASH_EXACT_CHANGE' | 'CREDIT_CARD' | 'DEBIT_CARD' | 'TRAVEL_CARD' | 'ETC' | 'ETC_TRANSPONDER' | 'ETC_VIDEO_CAMERA' | 'SUBSCRIPTION';
+/**
+ * A point on the route path, with its metadata.
+ * @group Route
+ */
+type RoutePathPoint = RouteProgressAtPoint & {
+  /**
+   * The position of this point on the route.
+   */
+  point: Position;
+};
+/**
+ * The name of a street, road number, exit, intersection, tollgate or country in a guidance
+ * instruction.
+ * @group Route
+ */
+type InstructionText = {
+  /**
+   * The name as a text string.
+   */
+  text: string;
+};
+/**
+ * A single road shield reference.
+ * @group Route
+ */
+type RoadShieldReference = {
+  /**
+   * A unique identifier for the road shield.
+   */
+  reference: string;
+  /**
+   * The text to show on the road shield.
+   */
+  shieldContent?: string;
+  /**
+   * The possible affixes to show in addition to the `shieldContent`.
+   */
+  affixes?: string[];
+};
+/**
+ * A road shield, with extra information.
+ * @group Route
+ */
+type RoadShield = {
+  /**
+   * The road number. Most road numbers have a 'letter' prefix, which is also returned.
+   */
+  roadNumber: InstructionText;
+  /**
+   * What the client needs to build an image of the road shield with the TomTom RoadShield API.
+   * It is present if a road shield image is available for this road.
+   */
+  roadShieldReference?: RoadShieldReference;
+  /**
+   * The state code of the state the shield is in (second part of an ISO 3166-2 identifier).
+   * It is present if state codes are available for the shield's country.
+   */
+  stateCode?: string;
+  /**
+   * The country code (ISO 3166-1 alpha-3) of the country the shield is in.
+   */
+  countryCode: string;
+};
+/**
+ * Road information, including properties, street name and road shields.
+ * @group Route
+ */
+type RoadInformation = {
+  /**
+   * The properties of the road, possibly several combined.
+   */
+  properties: RoadInformationProperty[];
   /**
    * The street name of the road, if available.
    */
   streetName?: InstructionText;
   /**
-   * The road shields of this road.
-   * The list can be empty if none are available.
+   * The road shields of this road, absent when it has none.
    */
   roadShields?: RoadShield[];
   /**
@@ -2463,10 +2780,11 @@ type Instruction = {
   trafficLightOffsetInMeters?: number;
   /**
    * The roads right before the maneuver that connect to the route but are not part of it, in ascending order of offset on route.
-   * The driver can take them by accident when following the instruction, without considering the route's dynamic restrictions such as time or vehicle profile dependent ones.
-   * A dual-carriageway road might be one or several side roads, depending on how the driver might perceive it.
-   * Use them for a richer graphical presentation of the maneuver, showing the connected roads just before it.
-   * The list is empty if no road crosses the route before the maneuver. It is present if there are side roads within a reasonable distance before the maneuver.
+   *
+   * - The driver can take them by accident when following the instruction, whatever the route's time or vehicle restrictions.
+   * - A dual-carriageway road might be one or several side roads, depending on how the driver might perceive it.
+   * - Use them for a richer graphical presentation of the maneuver, showing the connected roads just before it.
+   * - The list is empty if no road crosses the route before the maneuver.
    */
   sideRoads?: SideRoad[];
   /**
@@ -2521,6 +2839,7 @@ type Instruction = {
    * The offset on the route, in meters, of an ambiguous exit from the maneuver point (`maneuverPoint`).
    * It is present if this maneuver is an exit and another exit within a reasonable distance before it may cause ambiguity.
    * The client might then need to resolve the ambiguity and compose an instruction such as "Take the 2nd exit".
+   *
    * The offset is absolute, so it is a positive integer even though the ambiguous exit is before the maneuver on the route.
    * It applies to maneuvers that are one of:
    * - EXIT_ROUNDABOUT
@@ -2532,15 +2851,7 @@ type Instruction = {
   offsetOfAmbiguousExitFromManeuverInMeters?: number;
   /**
    * The ordinal number of the exit to take at a roundabout, as in "take the first/second exit".
-   * It is present if the maneuver is a roundabout maneuver, meaning it is one of:
-   * - ROUNDABOUT_STRAIGHT
-   * - ROUNDABOUT_SLIGHT_RIGHT
-   * - ROUNDABOUT_RIGHT
-   * - ROUNDABOUT_SHARP_RIGHT
-   * - ROUNDABOUT_SLIGHT_LEFT
-   * - ROUNDABOUT_LEFT
-   * - ROUNDABOUT_SHARP_LEFT
-   * - ROUNDABOUT_BACK
+   * It is present if the maneuver is one of the `ROUNDABOUT_*` ones {@link Instruction.changeOfAngleInDegrees} lists.
    */
   roundaboutExitNumber?: number;
   /**
@@ -2575,179 +2886,29 @@ type Instruction = {
   countryCrossingFromName?: InstructionText;
   /**
    * The code (ISO 3166-1 alpha-3) of the country the border crossing occurs from.
-   * It is present if the maneuver is a border crossing, meaning it is one of:
-   * - CROSS_BORDER
-   * - TAKE_SHIP_FERRY
-   * - TAKE_CAR_TRAIN
-   * - LEAVE_SHIP_FERRY
-   * - LEAVE_CAR_TRAIN
+   * It is present on the maneuvers {@link Instruction.countryCrossingFromName} lists.
    */
   countryCrossingFromCode?: string;
   /**
    * The name of the country the border crossing occurs to.
-   * It is present if the maneuver is or leads to a border crossing, meaning it is one of:
-   * - CROSS_BORDER
-   * - TAKE_SHIP_FERRY
-   * - TAKE_CAR_TRAIN
-   * - LEAVE_SHIP_FERRY
-   * - LEAVE_CAR_TRAIN
-   */
-  countryCrossingToName?: InstructionText;
-  /**
-   * The code (ISO 3166-1 alpha-3) of the country the border crossing occurs to.
-   * It is present if the maneuver is a border crossing, meaning it is one of:
-   * - CROSS_BORDER
-   * - TAKE_SHIP_FERRY
-   * - TAKE_CAR_TRAIN
-   * - LEAVE_SHIP_FERRY
-   * - LEAVE_CAR_TRAIN
-   */
-  countryCrossingToCode?: string;
-};
-/**
- * The guidance elements of a route, present only when guidance was requested and is available.
- * @group Route
- */
-type Guidance = {
-  /**
-   * Main ordered list of instructions to follow.
-   */
-  instructions: Instruction[];
-};
-//#endregion
-//#region src/types/route/summary.d.ts
-/**
- * The summary of a route or route leg, with departure and arrival times, lengths and durations.
- * @group Route
- */
-type SummaryBase = {
-  /**
-   * The estimated arrival time at the end of the route or leg.
-   *
-   * It is the departure time plus the travel time, accounting for traffic conditions.
-   */
-  arrivalTime: Date;
-  /**
-   * The departure time from the beginning of the route or leg, based on the one the routing
-   * request specified.
-   */
-  departureTime: Date;
-  /**
-   * Total length of the route or leg in meters.
-   */
-  lengthInMeters: number;
-  /**
-   * The estimated travel time of the route or leg in seconds.
-   *
-   * @remarks
-   * It includes delays due to real-time traffic. For the free-flow travel time without traffic
-   * delays, use `noTrafficTravelTimeInSeconds`.
-   */
-  travelTimeInSeconds: number;
-  /**
-   * The delay in seconds of the traffic events along `trafficLengthInMeters`.
-   *
-   * @remarks
-   * It is present only when the routing service sends it, and it is not the gap to free-flow
-   * conditions. For the gap to free-flow, request the travel times with `computeTravelTimeFor: 'all'`
-   * and use `Math.max(0, liveTrafficIncidentsTravelTimeInSeconds - noTrafficTravelTimeInSeconds)`.
-   * The live travel time can fall below the free-flow one, so keep the floor at 0.
-   */
-  trafficDelayInSeconds?: number;
-  /**
-   * The length in meters of the route that traffic events delay, which is the portion with
-   * congestion or incidents.
-   *
-   * @remarks
-   * It is present only when the routing service sends it.
-   */
-  trafficLengthInMeters?: number;
-  /**
-   * The estimated travel time in seconds in free-flow conditions, as if there were no traffic
-   * delays (no congestion).
-   *
-   * It is present only if you request it with the `computeTravelTimeFor` parameter.
+   * It is present on the maneuvers {@link Instruction.countryCrossingFromName} lists.
    */
-  noTrafficTravelTimeInSeconds?: number;
-  /**
-   * The estimated travel time in seconds from time-dependent historic traffic data.
-   *
-   * It is the expected travel time from typical traffic patterns at the requested departure
-   * time, such as rush hour or off-peak. It is present only if you request it with the
-   * `computeTravelTimeFor` parameter.
-   */
-  historicTrafficTravelTimeInSeconds?: number;
-  /**
-   * The estimated travel time in seconds from real-time traffic speed data, based on current
-   * live traffic conditions and incidents.
-   *
-   * It is present only if you request it with the `computeTravelTimeFor` parameter.
-   */
-  liveTrafficIncidentsTravelTimeInSeconds?: number;
-  /**
-   * The distance in meters from the origin point to the first point where this route forks off from the reference route.
-   *
-   * @remarks
-   * If the route is identical to the reference route, it is the length of the route. Every
-   * alternative route summary has it, but the reference route's doesn't.
-   */
-  deviationDistanceInMeters?: number;
-  /**
-   * The travel time in seconds from the origin point to the first point where this route forks off from the reference route.
-   *
-   * @remarks
-   * If the route is identical to the reference route, it is the estimated travel time of the
-   * route. Every alternative route summary has it, but the reference route's doesn't.
-   */
-  deviationTimeInSeconds?: number;
+  countryCrossingToName?: InstructionText;
   /**
-   * The coordinates of the first point where this route forks off from the reference route.
-   *
-   * @remarks
-   * If the route is identical to the reference route, it is the last point on the route.
-   * Every alternative route summary has it, but the reference route's doesn't.
+   * The code (ISO 3166-1 alpha-3) of the country the border crossing occurs to.
+   * It is present on the maneuvers {@link Instruction.countryCrossingFromName} lists.
    */
-  deviationPoint?: Position;
+  countryCrossingToCode?: string;
 };
 /**
- * The summary of an entire route, with all journey statistics from origin to destination,
- * including the stops along the way.
- *
- * @group Route
- */
-type RouteSummary = SummaryBase;
-/**
- * The summary of a single route leg, the portion of the route between two consecutive waypoints.
- *
- * @remarks
- * - An A→B route has 1 leg
- * - An A→B→C route has 2 legs (A→B, B→C)
- *
+ * The guidance elements of a route, present only when guidance was requested and is available.
  * @group Route
  */
-type LegSummary = SummaryBase & {
+type Guidance = {
   /**
-   * The time in seconds the vehicle stands still at the stop this leg arrives at.
-   *
-   * @remarks
-   * It is the wait a {@link WaypointProps.pauseDurationSeconds} asked for, as the service actually
-   * planned it rather than an echo of the request. That is the gap between this leg's `arrivalTime`
-   * and the next leg's `departureTime`.
-   *
-   * - It is absent when the vehicle does not stop at the end of this leg.
-   * - It is absent on the last leg, which has no following departure. The routing service does not
-   *   accept a wait at the destination anyway.
-   * - This leg's own `travelTimeInSeconds` is driving only and *excludes* the stop, while the
-   *   route's total *includes* every stop. So driving time is the sum of the legs, and the time
-   *   spent standing still is the difference.
-   *
-   * @example
-   * ```typescript
-   * // A waypoint with pauseDurationSeconds: 1800
-   * stopTimeInSeconds: 1800
-   * ```
+   * Main ordered list of instructions to follow.
    */
-  stopTimeInSeconds?: number;
+  instructions: Instruction[];
 };
 //#endregion
 //#region src/types/route/sections.d.ts
@@ -2895,7 +3056,7 @@ export type TrafficIncidentTEC = {
  *   magnitudeOfDelay: 'moderate',
  *   delayInSeconds: 420,  // 7 minutes
  *   effectiveSpeedInKmh: 25,
- *   tec: { effectCode: 1, causes: [{ mainCauseCode: 101 }] }
+ *   tec: { effectCode: 1, causes: [{ mainCauseCode: 1 }] }
  * };
  * ```
  *
@@ -2956,7 +3117,7 @@ export type DistinctSectionProps = SectionProps & {
  *
  * @remarks
  * The SDK finds curves in the route's geometry, with {@link getCurveSections}. A small radius with a
- * large heading change makes a hard curve: a hairpin turns some 180° on a radius of 10 to 20 metres.
+ * large heading change makes a hard curve, up to a hairpin as {@link isHairpin} tells them.
  *
  * @example
  * ```typescript
@@ -3079,13 +3240,13 @@ export type CurvyStretchSectionProps = SectionProps & {
  */
 export type LegSectionProps = Omit<SectionProps, 'startPointIndex' | 'endPointIndex'> & {
   /**
-   * The index in the route coordinates where this leg starts, present only if the route
-   * polyline geometry is available.
+   * The index in the route coordinates where this leg starts. `calculateRoute` always sets it;
+   * only a route built by hand can leave it out.
    */
   startPointIndex?: number;
   /**
-   * The index in the route coordinates where this leg ends, present only if the route
-   * polyline geometry is available.
+   * The index in the route coordinates where this leg ends. `calculateRoute` always sets it;
+   * only a route built by hand can leave it out.
    */
   endPointIndex?: number;
   /**
@@ -3188,7 +3349,7 @@ export type SpeedLimitSectionProps = SectionProps & {
  */
 export type RoadShieldSectionProps = SectionProps & {
   /**
-   * The road shield code for this section.
+   * The references of the road shields along this section.
    */
   roadShieldReferences: RoadShieldReference[];
 };
@@ -3258,12 +3419,11 @@ export type SectionsProps = {
    *
    * @remarks
    * It is a subset of {@link SectionsProps.tollRoad | `tollRoad`}, so every stretch reported here is
-   * also reported there. Use `toll` for "will this route cost a toll to drive", and `tollRoad` for
+   * also reported there.
+   *
+   * Use `toll` for "will this route cost a toll to drive", and `tollRoad` for
    * "does this route cost anything at all to drive". `tollRoad` also covers vignette-only
    * motorways and urban charge zones, which carry no per-use toll.
-   *
-   * By default, it is included, since leaving `sectionTypes` unset requests it. A `sectionTypes`
-   * list has to name `'toll'` to keep it.
    */
   toll?: SectionProps[];
   /**
@@ -3271,12 +3431,7 @@ export type SectionsProps = {
    * that need a vignette and urban road-charge zones.
    *
    * @remarks
-   * It is a superset of {@link SectionsProps.toll | `toll`}. On a ticket motorway, the two report the
-   * same stretches. A vignette-only motorway or a city charge zone appears here and not in
-   * `toll`.
-   *
-   * By default, it is included, since leaving `sectionTypes` unset requests it. A `sectionTypes`
-   * list has to name `'tollRoad'` to keep it.
+   * It is a superset of {@link SectionsProps.toll | `toll`}: see there how the two differ.
    */
   tollRoad?: SectionProps[];
   /**
@@ -3300,7 +3455,7 @@ export type SectionsProps = {
  */
 export type SectionType = keyof SectionsProps;
 /**
- * The section types a route calculation returns when its request names none: every type the
+ * The section types a route calculation requests when its request has no `sectionTypes`: every type the
  * routing API returns, and `lanes` with guidance.
  *
  * @remarks
@@ -3316,7 +3471,8 @@ export type SectionType = keyof SectionsProps;
  */
 export declare const defaultSectionTypes: readonly ["carpool", "carTrain", "country", "ferry", "importantRoadStretch", "lowEmissionZone", "motorway", "pedestrian", "roadShields", "speedLimit", "toll", "tollRoad", "tollVignette", "traffic", "tunnel", "unpaved", "urban", "vehicleRestricted", "lanes"];
 /**
- * The section types a route calculation request can ask to include in the response.
+ * The section types a route calculation request can ask to include in the response, except `lanes`,
+ * which comes with guidance: see {@link inputSectionTypesWithGuidance}.
  * @group Route
  */
 export declare const inputSectionTypes: readonly ["carpool", "carTrain", "country", "ferry", "importantRoadStretch", "lowEmissionZone", "motorway", "pedestrian", "roadShields", "speedLimit", "toll", "tollRoad", "tollVignette", "traffic", "tunnel", "unpaved", "urban", "vehicleRestricted", "curve", "curvyStretch"];
@@ -3404,389 +3560,109 @@ type CurvyStretchSectionsOptions = {
  * ```typescript
  * // Only the hard curves, and the stretches of five or more of them
  * const curveDetection: CurveDetectionOptions = {
- *     curve: { maxRadiusInMeters: 100 },
- *     curvyStretch: { minCurveCount: 5 },
- * };
- * ```
- *
- * @group Utils
- */
-type CurveDetectionOptions = {
-  /** The thresholds a stretch of road has to reach to count as a curve. */
-  curve?: CurveSectionsOptions;
-  /** How close the curves found have to follow one another to make a curvy stretch. */
-  curvyStretch?: Omit<CurvyStretchSectionsOptions, 'curves'>;
-};
-/**
- * A route's sections of one type within the spans asked about.
- *
- * @group Utils
- */
-type SectionsWithinOfType<T extends SectionType> = {
-  /** The sections reaching into the spans, whole, in their order on the route. */
-  sections: NonNullable<SectionsProps[T]>;
-  /**
-   * Each section's share within the spans, from 0 to 1, in the order of `sections`. Use it to count
-   * only that part of what a section carries, such as a traffic section's delay.
-   */
-  shares: number[];
-  /** How far they run within the spans, together. */
-  lengthInMeters: number;
-};
-/**
- * A route's sections within the spans asked about, by type: only the types it has there.
- *
- * @group Utils
- */
-type SectionsWithin = { [T in SectionType]?: SectionsWithinOfType<T>; };
-/**
- * Where to look along a route for its sections, and of which types.
- *
- * @group Utils
- */
-type SectionsWithinOptions = {
-  /** Only counts the sections within these spans of the route, which must not overlap. Defaults to the whole route. */
-  within?: readonly RouteSpan[];
-  /** The section types to look for. Defaults to every type. */
-  types?: readonly SectionType[];
-};
-/**
- * How a route differs from a reference route: the stretches each drives alone, and their sections.
- *
- * @group Utils
- */
-type RouteComparison = {
-  /** The stretches only the route drives, of the two. */
-  distinct: DistinctSectionProps[];
-  /** The stretches only the reference drives, of the two. */
-  referenceDistinct: DistinctSectionProps[];
-  /** The route's sections on the stretches only it drives: what it takes on. */
-  adds: SectionsWithin;
-  /** The reference's sections on the stretches only it drives: what the route stays clear of. */
-  avoids: SectionsWithin;
-};
-/**
- * Which sections to weigh when comparing two routes.
- *
- * @group Utils
- */
-type CompareRoutesOptions = {
-  /**
-   * The section types to weigh. Defaults to every type `calculateRoute` can return, `curve` and
-   * `curvyStretch` included when the routes carry them, leaving out `leg` and `distinct`.
-   */
-  types?: readonly SectionType[];
-};
-/**
- * A road a route takes, as its important road stretches name it.
- *
- * @remarks
- * Its `index` is that of its most important stretch: the lower, the more important. Its `streetName`
- * is the first one its stretches carry.
- *
- * @group Utils
- */
-type ImportantRoad = Pick<ImportantRoadStretchProps, 'index' | 'streetName'> & {
-  /** What a driver calls it: its first road number, else its street name. Absent when it has neither. */
-  name?: string;
-  /**
-   * Its road numbers, those of its stretches in turn, each sorted in descending order of display
-   * priority. Empty when it has none.
-   */
-  roadNumbers: string[];
-  /** How far the route follows it, counting only the parts within the sections asked about. */
-  lengthInMeters: number;
-  /** The route's important road stretch sections on it, in order along the route. */
-  sections: ImportantRoadStretchProps[];
-};
-/**
- * Where to look for important roads along a route, and how much of each to require.
- *
- * @group Utils
- */
-type ImportantRoadsOptions = Pick<SectionsWithinOptions, 'within'> & {
-  /** Leaves out the roads the route follows for less than this within the spans. */
-  minLengthInMeters?: number;
-};
-//#endregion
-//#region src/types/route/route.d.ts
-/**
- * All the road and route features that route calculation can avoid.
- *
- * Use it to derive the {@link Avoidable} type or to validate user input against the supported
- * avoidance options.
- *
- * @remarks
- * This readonly tuple is the source of truth for valid avoidance types. The {@link Avoidable}
- * type derives from it, for type safety.
- *
- * @example
- * ```typescript
- * // Check if a string is a valid avoidance type
- * const userInput = 'tollRoads';
- * if (avoidableTypes.includes(userInput as Avoidable)) {
- *   // userInput is valid
- * }
- *
- * // Iterate over all available options
- * avoidableTypes.forEach(type => {
- *   console.log(`Available option: ${type}`);
- * });
- * ```
- *
- * @group Route
- */
-export declare const avoidableTypes: readonly ["tollRoads", "motorways", "ferries", "unpavedRoads", "carpools", "alreadyUsedRoads", "borderCrossings", "tunnels", "carTrains", "lowEmissionZones"];
-/**
- * A route feature that the routing engine tries to avoid when calculating routes.
- *
- * Use it to customize routes for vehicle capabilities, user preferences or regulatory
- * requirements. Note that avoidance is not guaranteed if no alternative route exists.
- *
- * @remarks
- * The avoidance options:
- * - `tollRoads`: Avoids roads requiring toll payments
- * - `motorways`: Avoids high-speed limited-access highways (useful for scenic routes or vehicle restrictions)
- * - `ferries`: Avoids water crossings requiring ferry transport
- * - `unpavedRoads`: Avoids unpaved/dirt roads (recommended for standard vehicles)
- * - `carpools`: Avoids carpool/HOV (High Occupancy Vehicle) lanes
- * - `alreadyUsedRoads`: Prevents using the same road segment multiple times (useful for delivery routes)
- * - `borderCrossings`: Avoids crossing international borders (useful for customs/visa considerations)
- * - `tunnels`: Avoids underground tunnels (useful for vehicles carrying hazardous materials)
- * - `carTrains`: Avoids car train transport segments
- * - `lowEmissionZones`: Avoids zones with vehicle emission restrictions
- *
- * @example
- * ```typescript
- * // Avoid tolls and motorways for a scenic route
- * const scenicAvoid: Avoidable[] = ['tollRoads', 'motorways'];
- *
- * // Avoid unpaved roads for a standard car
- * const carAvoid: Avoidable[] = ['unpavedRoads'];
- * ```
- *
- * @group Route
- */
-export type Avoidable = (typeof avoidableTypes)[number];
-/**
- * The primary mode of transportation for route calculation.
- *
- * It determines the road type preferences, speed calculations and routing rules of the
- * calculated route. Currently, only `'car'` is supported.
- *
- * @remarks
- * Future versions may support additional modes such as truck, taxi, bus, bicycle and pedestrian.
- *
- * @example
- * ```typescript
- * const travelMode: TravelMode = 'car';
- * ```
- *
- * @group Route
- */
-export type TravelMode = 'car';
-/**
- * The cumulative distance and time at a position along the route.
- *
- * Both fields are optional because a progress entry may omit either value. Interpolation
- * utilities return the resolved, always-present equivalent, {@link RouteProgressAtPoint}.
- *
- * @group Route
- */
-export type RouteProgress = {
-  /**
-   * Cumulative travel time in seconds from the route start.
-   */
-  travelTimeInSeconds?: number;
-  /**
-   * Cumulative distance in meters from the route start.
-   */
-  distanceInMeters?: number;
-};
-/**
- * The progress at a specific coordinate on the route path.
- *
- * It adds to {@link RouteProgress} a `pointIndex` that identifies the coordinate's entry in
- * the route's coordinate array.
- *
- * @remarks
- * The `progress` array of a route always has entries for the first and last points. You can
- * linearly interpolate the progress of intermediate points between entries.
- *
- * @example
- * ```typescript
- * const points: RouteProgressPoint[] = [
- *   { pointIndex: 0,   travelTimeInSeconds: 0,   distanceInMeters: 0    },
- *   { pointIndex: 50,  travelTimeInSeconds: 120,  distanceInMeters: 2500 },
- *   { pointIndex: 100, travelTimeInSeconds: 300,  distanceInMeters: 5000 }
- * ];
+ *     curve: { maxRadiusInMeters: 100 },
+ *     curvyStretch: { minCurveCount: 5 },
+ * };
  * ```
  *
- * @group Route
+ * @group Utils
  */
-export type RouteProgressPoint = RouteProgress & {
-  /**
-   * Zero-based index of this point in the route's coordinate array.
-   */
-  pointIndex: number;
+type CurveDetectionOptions = {
+  /** The thresholds a stretch of road has to reach to count as a curve. */
+  curve?: CurveSectionsOptions;
+  /** How close the curves found have to follow one another to make a curvy stretch. */
+  curvyStretch?: Omit<CurvyStretchSectionsOptions, 'curves'>;
 };
 /**
- * The resolved distance and time at an interpolated position on the route path.
- *
- * Both fields are required, because the SDK produces this type only when interpolation
- * fully resolves, meaning both bracketing progress entries carry valid values.
+ * A route's sections of one type within the spans asked about.
  *
- * @group Route
+ * @group Utils
  */
-export type RouteProgressAtPoint = Required<RouteProgress>;
+type SectionsWithinOfType<T extends SectionType> = {
+  /** The sections reaching into the spans, whole, in their order on the route. */
+  sections: NonNullable<SectionsProps[T]>;
+  /**
+   * Each section's share within the spans, from 0 to 1, in the order of `sections`. Use it to count
+   * only that part of what a section carries, such as a traffic section's delay.
+   */
+  shares: number[];
+  /** How far they run within the spans, together. */
+  lengthInMeters: number;
+};
 /**
- * The progress over a segment between two arbitrary points on the route path.
+ * A route's sections within the spans asked about, by type: only the types it has there.
  *
- * @group Route
+ * @group Utils
  */
-export type RouteSegmentProgress = {
-  /** Progress at the start point. */
-  start: RouteProgressAtPoint;
-  /** Progress at the end point. */
-  end: RouteProgressAtPoint;
-  /** The distance and time the segment covers, as end minus start. */
-  delta: RouteProgressAtPoint;
-};
+type SectionsWithin = { [T in SectionType]?: SectionsWithinOfType<T>; };
 /**
- * Geographic coordinate and cumulative progress values at a specific point along a route.
+ * Where to look along a route for its sections, and of which types.
  *
  * @group Utils
  */
-export type RouteCoordinateAtProgress = RouteProgressAtPoint & {
-  /** Geographic position as a GeoJSON `[longitude, latitude]` coordinate. */
-  position: Position;
+type SectionsWithinOptions = {
+  /** Only counts the sections within these spans of the route, which must not overlap. Defaults to the whole route. */
+  within?: readonly RouteSpan[];
+  /** The section types to look for. Defaults to every type. */
+  types?: readonly SectionType[];
 };
 /**
- * A discriminated union that identifies a position along a route.
- * Provide exactly one of the three variants.
+ * How a route differs from a reference route: the stretches each drives alone, and their sections.
  *
  * @group Utils
  */
-export type RouteProgressQuery = {
-  traveledTimeInSeconds: number;
-} | {
-  traveledDistanceInMeters: number;
-} | {
-  clockTime: Date;
+type RouteComparison = {
+  /** The stretches only the route drives, of the two. */
+  distinct: DistinctSectionProps[];
+  /** The stretches only the reference drives, of the two. */
+  referenceDistinct: DistinctSectionProps[];
+  /** The route's sections on the stretches only it drives: what it takes on. */
+  adds: SectionsWithin;
+  /** The reference's sections on the stretches only it drives: what the route stays clear of. */
+  avoids: SectionsWithin;
 };
 /**
- * All the information of a calculated route, including its summary statistics, sections,
- * guidance instructions and progress data.
+ * Which sections to weigh when comparing two routes.
  *
- * @group Route
+ * @group Utils
  */
-export type RouteProps = {
-  /**
-   * The summary statistics of the entire route, with departure and arrival times, total length
-   * and duration.
-   */
-  summary: RouteSummary;
-  /**
-   * The route sections, which are portions of the route with distinct properties such as:
-   * - Countries traversed
-   * - Traffic incidents
-   * - Route legs (segments between waypoints)
-   * - Special road types (tunnels, ferries, toll roads)
-   */
-  sections: SectionsProps;
-  /**
-   * The turn-by-turn navigation instructions, with maneuvers, road names and instruction text.
-   *
-   * They are present only when guidance was requested and is available.
-   */
-  guidance?: Guidance;
-  /**
-   * The distance and time progress at key points along the route.
-   *
-   * It is present when extended route representations are requested, which is the default for route
-   * calculations. Use it to display progress information or calculate intermediate times.
-   */
-  progress?: RouteProgressPoint[];
+type CompareRoutesOptions = {
   /**
-   * The index of this route among the alternatives.
-   *
-   * The first route (index 0) is typically the recommended or best route, and the rest are alternatives.
+   * The section types to weigh. Defaults to every type `calculateRoute` can return, `curve` and
+   * `curvyStretch` included when the routes carry them, leaving out `leg` and `distinct`.
    */
-  index: number;
+  types?: readonly SectionType[];
 };
 /**
- * A calculated route, as a GeoJSON Feature.
- *
- * Its geometry is a LineString of the route path coordinates, and its properties hold all
- * route information (summary, sections, guidance).
- *
- * @typeParam P - Type of the route properties (defaults to RouteProps)
+ * A road a route takes, as its important road stretches name it.
  *
- * @example
- * ```typescript
- * const route: Route = {
- *   type: 'Feature',
- *   id: 'route-123',
- *   geometry: {
- *     type: 'LineString',
- *     coordinates: [[4.9, 52.3], [4.91, 52.31], ...]
- *   },
- *   properties: {
- *     summary: { lengthInMeters: 5000, travelTimeInSeconds: 300, ... },
- *     sections: { ... },
- *     index: 0
- *   },
- *   bbox: [4.9, 52.3, 4.91, 52.31]
- * };
- * ```
+ * @remarks
+ * Its `index` is that of its most important stretch: the lower, the more important. Its `streetName`
+ * is the first one its stretches carry.
  *
- * @group Route
+ * @group Utils
  */
-export type Route<P extends RouteProps = RouteProps> = Omit<Feature<LineString, P>, 'id' | 'bbox'> & {
-  /**
-   * The unique identifier of this route, randomly generated to tell route alternatives apart.
-   */
-  id: string;
+type ImportantRoad = Pick<ImportantRoadStretchProps, 'index' | 'streetName'> & {
+  /** What a driver calls it: its first road number, else its street name. Absent when it has neither. */
+  name?: string;
   /**
-   * The bounding box of the entire route, or at least of its waypoints.
+   * Its road numbers, those of its stretches in turn, each sorted in descending order of display
+   * priority. Empty when it has none.
    */
-  bbox: BBox;
+  roadNumbers: string[];
+  /** How far the route follows it, counting only the parts within the sections asked about. */
+  lengthInMeters: number;
+  /** The route's important road stretch sections on it, in order along the route. */
+  sections: ImportantRoadStretchProps[];
 };
 /**
- * A GeoJSON FeatureCollection of one or more calculated routes.
- *
- * It typically holds the main route (index 0) and optional alternative routes. Its properties
- * can include metadata about the routing request.
- *
- * @typeParam P - Type of individual route properties (defaults to RouteProps)
- * @typeParam FeatureCollectionProps - Type of collection-level properties
- *
- * @example
- * ```typescript
- * const routes: Routes = {
- *   type: 'FeatureCollection',
- *   features: [
- *     { type: 'Feature', geometry: {...}, properties: { index: 0, ... } }, // Main route
- *     { type: 'Feature', geometry: {...}, properties: { index: 1, ... } }  // Alternative
- *   ],
- *   properties: {
- *     requestId: 'req-456',
- *     calculatedAt: new Date()
- *   }
- * };
- * ```
+ * Where to look for important roads along a route, and how much of each to require.
  *
- * @group Route
+ * @group Utils
  */
-export type Routes<P extends RouteProps = RouteProps, FeatureCollectionProps = unknown> = Omit<FeatureCollectionWithProperties<LineString, P, FeatureCollectionProps>, 'features' | 'bbox'> & {
-  /**
-   * The route features.
-   */
-  features: Route<P>[];
-  /**
-   * The bounding box of all the routes, or at least of their waypoints. It is defined only if there are routes.
-   */
-  bbox?: BBox;
+type ImportantRoadsOptions = Pick<SectionsWithinOptions, 'within'> & {
+  /** Leaves out the roads the route follows for less than this within the spans. */
+  minLengthInMeters?: number;
 };
 //#endregion
 //#region src/types/route/locations.d.ts
@@ -3799,8 +3675,8 @@ type WaypointProps = {
   /**
    * How long the vehicle waits at this stop, in seconds.
    *
-   * If you set it, the routing service adds the wait to the leg arriving at this waypoint, and
-   * the map shows it on the stop's pin.
+   * If you set it, the routing service plans the wait after the leg arriving at this waypoint and
+   * reports it as that leg's `stopTimeInSeconds`, and the map shows it on the stop's pin.
    *
    * @remarks
    * - The wait counts towards the route's `travelTimeInSeconds`, not only its arrival time.
@@ -3825,7 +3701,8 @@ type WaypointProps = {
  * @typeParam T - Additional custom properties beyond the standard waypoint properties
  *
  * @remarks
- * Every waypoint after the origin ends a route leg and creates an arrival instruction.
+ * Every waypoint after the origin ends a route leg and creates a waypoint instruction, or an
+ * arrival one at the destination.
  *
  * @example
  * ```typescript
@@ -3878,13 +3755,13 @@ type Waypoints<T extends Anything = Anything> = FeatureCollection<Point, Waypoin
  * @example
  * ```typescript
  * // As coordinate array
- * const wp1: WaypointLike = [4.9041, 52.3676];
+ * const coordinates: WaypointLike = [4.9041, 52.3676];
  *
  * // As Point geometry
- * const wp2: WaypointLike = { type: 'Point', coordinates: [4.9041, 52.3676] };
+ * const point: WaypointLike = { type: 'Point', coordinates: [4.9041, 52.3676] };
  *
  * // As full Waypoint Feature carrying custom properties
- * const wp3: WaypointLike = {
+ * const feature: WaypointLike = {
  *   type: 'Feature',
  *   geometry: { type: 'Point', coordinates: [4.9041, 52.3676] },
  *   properties: { name: 'Amsterdam' }
@@ -3971,7 +3848,7 @@ export declare const sdkErrorCodes: readonly ["INVALID_REQUEST", "INSECURE_BASE_
  *
  * | Code | When |
  * | --- | --- |
- * | `INVALID_REQUEST` | The SDK's request validation failed, a service could not build a request sent with `validateRequest: false`, or the API answered `400` or another `4xx` not below |
+ * | `INVALID_REQUEST` | The SDK's request validation failed, a service could not build a request sent with `validateRequest: false`, `discoverPlaces` found no category matching its `poiCategoryQuery`, or the API answered `400` or another `4xx` not below |
  * | `INSECURE_BASE_URL` | `commonBaseURL` is neither `https:` nor `http:` on a loopback address, checked even with `validateRequest: false` |
  * | `INVALID_CREDENTIALS` | The API answered `401`: the key is missing, invalid or expired |
  * | `INSUFFICIENT_PERMISSIONS` | The API answered `403`: the key is valid but not allowed this request, because that API is not enabled for it (a Private Preview API needs its access granted) or its domain restriction refused the page |
@@ -4000,7 +3877,7 @@ export type AreaAnalyticsMetricRange = {
   max: number;
 };
 /**
- * All traffic metric identifiers, ordered consistently across the SDK.
+ * Every {@link AreaAnalyticsMetricKey}, in the order the SDK lists metrics everywhere.
  *
  * @group Traffic
  */
@@ -4165,9 +4042,8 @@ export type AreaAnalyticsTimedEntry = NonNullable<AreaAnalyticsTimedData[keyof A
  * Traffic metrics for a single geographic tile within the analysis region.
  *
  * @remarks
- * All fields are optional, because only the metrics in the requested `metrics` are present.
- * Here, `networkLength` is the total length of road segments **within that tile** (meters),
- * not the region aggregate.
+ * As in {@link AreaAnalyticsMetrics}, only the requested `metrics` are present. Here, `networkLength` is
+ * the total length of road segments **within that tile** (meters), not the region aggregate.
  *
  * @group Traffic
  */
@@ -4203,8 +4079,8 @@ export type AreaAnalyticsAnomaly = {
  */
 export type AreaAnalyticsFeatureProperties = {
   /**
-   * Name of the analysis region, which the API echoes from a request that names one. The SDK names none, so it is
-   * absent.
+   * Name of the analysis region, which the API echoes from a request that names one. The SDK sends its region
+   * unnamed, so it is absent: the params' `name` names the report, not the region.
    */
   name?: string;
   /**
@@ -4224,7 +4100,7 @@ export type AreaAnalyticsFeatureProperties = {
    */
   timedData: AreaAnalyticsTimedData;
   /**
-   * Per-tile traffic metrics for the region, if heatmap data was requested.
+   * Per-tile traffic metrics for the region, present when the response has them, as the collection's `properties.heatmap` tells.
    */
   tiledData?: {
     tiles: AreaAnalyticsTileEntry[];
@@ -4332,16 +4208,10 @@ export type TrafficAreaAnalytics = {
  * - `metric`: International System (SI), used in most of the world (Europe, Asia, Africa,
  *   South America, Australia). It uses meters (m) and kilometers (km), decimal-based with no fractions.
  * - `imperial_us`: United States customary units, used in the United States. It uses feet (ft)
- *   for short distances (< 0.125 mi), and miles (mi) with fractions (¼, ½, ¾) for longer ones.
+ *   for short distances (< 0.125 mi), then miles (mi) to the quarter (¼, ½, ¾) under 3 mi, to the half
+ *   under 10 mi and whole from there.
  * - `imperial_uk`: United Kingdom imperial units, used in the United Kingdom. It uses yards (yd)
- *   for short distances (< 0.125 mi), and miles (mi) with fractions (¼, ½, ¾) for longer ones.
- *
- * @example
- * ```typescript
- * const system: DistanceUnitsType = 'metric';      // International
- * const usSystem: DistanceUnitsType = 'imperial_us';  // United States
- * const ukSystem: DistanceUnitsType = 'imperial_uk';  // United Kingdom
- * ```
+ *   for short distances (< 0.125 mi), then miles (mi) as `imperial_us` gives them.
  *
  * @group Utils
  */
@@ -4351,8 +4221,6 @@ type DistanceUnitsType = 'metric' | 'imperial_us' | 'imperial_uk';
 /**
  * The labels and unit system the SDK uses to display distances.
  *
- * The unit system is metric, US imperial or UK imperial.
- *
  * @group Configuration
  */
 export type DistanceDisplayUnits = {
@@ -4416,8 +4284,6 @@ export type TimeDisplayUnits = {
 /**
  * The display units for time and distance.
  *
- * Formatting utilities and map information displays use them to label durations and distances.
- *
  * @group Configuration
  */
 export type DisplayUnits = {
@@ -4516,11 +4382,6 @@ export type GlobalConfig = {
    * @default ''
    */
   apiKey: string;
-  /**
-   * An experimental alternative to the API Key which enables oauth2 access to APIs.
-   * * If provided, then the API key parameter will be ignored.
-   * @experimental
-   */
   /**
    * The language of SDK services and map content.
    *
@@ -4546,12 +4407,11 @@ export type GlobalConfig = {
   /**
    * The base URL of every TomTom request, for service calls and the style, tile, sprite and glyph URLs the map fetches.
    *
-   * Change it only to route those requests through a proxy of your own. If you also leave `apiKey` unset, the SDK
-   * switches to proxy-credentials mode. No key then leaves the browser, and requests carry the proxy's session cookie.
-   *
-   * It must be absolute and `https:`. The SDK accepts `http:` only for a loopback address (`localhost`, `127.0.0.0/8`,
-   * `[::1]`). Otherwise service calls reject, and the map constructor throws, with code `INSECURE_BASE_URL`, even
-   * with `validateRequest: false`.
+   * - Change it only to route those requests through a proxy of your own. If you also leave `apiKey` unset, the SDK
+   *   switches to proxy-credentials mode: no key leaves the browser, and requests carry the proxy's session cookie.
+   * - It must be absolute and `https:`, or `http:` for a loopback address (`localhost`, `*.localhost`, `127.0.0.0/8`,
+   *   `[::1]`). Otherwise service calls reject, and the map constructor throws, with code `INSECURE_BASE_URL`, even
+   *   with `validateRequest: false`.
    *
    * @default "https://api.tomtom.com"
    * @see [Proxying your API calls](https://docs.tomtom.com/maps-sdk-js/guides/security/proxying-api-calls)
@@ -4562,7 +4422,7 @@ export type GlobalConfig = {
    *
    * TomTom reads it to tell which SDK versions are in use. Turn it off when that header must not
    * leave the page, or when a proxy of yours should not have to allow it in its CORS preflight answer.
-   * A map reads it at construction. Its image requests (sprite sheets, raster tiles) never carry the header.
+   * A map reads it at construction. The images it loads by URL never carry the header; its sprite sheets and tiles do.
    *
    * @default true
    * @see [What the SDK sends](https://docs.tomtom.com/maps-sdk-js/guides/security/what-the-sdk-sends)
@@ -4631,7 +4491,7 @@ export declare class TomTomConfig {
   /**
    * The singleton instance of the configuration.
    */
-  static readonly instance: TomTomConfig;
+  static get instance(): TomTomConfig;
   private config;
   private constructor();
   /**
@@ -4679,16 +4539,12 @@ export declare class TomTomConfig {
 /**
  * Whether the SDK is configured for a credentials proxy, such as the demos proxy.
  *
- * That is the case with no `apiKey` and a non-default `commonBaseURL`. The proxy injects
- * the real key server-side from a cookie-gated session.
- *
- * In this mode, SDK requests attach `credentials: 'include'` so the proxy's session cookie
- * travels with them. Otherwise, as with direct TomTom usage or a customer-owned proxy that
- * keeps a real `apiKey`, credentials stay at the browser default. This keeps backends that
- * respond with `Access-Control-Allow-Origin: *` working, since the browser rejects
- * credentialed responses against a wildcard origin.
+ * That is the case with no `apiKey`, `undefined` and `''` alike, and a non-default `commonBaseURL`. The proxy
+ * injects the real key server-side from a cookie-gated session.
  *
- * An `apiKey` of `undefined` counts as unset, as `''` does.
+ * - In this mode, SDK requests attach `credentials: 'include'`, so the proxy's session cookie travels with them.
+ * - Otherwise, credentials stay at the browser default, which keeps backends that answer with
+ *   `Access-Control-Allow-Origin: *` working: the browser rejects credentialed responses against a wildcard origin.
  *
  * @param config - The config to inspect, by default the global {@link TomTomConfig}.
  * @group Configuration
@@ -4697,7 +4553,8 @@ export declare const isProxyCredentialsMode: (config?: Partial<Pick<GlobalConfig
 //#endregion
 //#region src/util/bbox.d.ts
 /**
- * Whether the bounding box has both a width and a height. It is `false` for a single point, a line, or `undefined`.
+ * Whether the bounding box has both a width and a height. It is `false` for a single point, a line along a
+ * meridian or a parallel, or `undefined`.
  *
  * @group Utils
  */
@@ -4717,7 +4574,8 @@ export declare const bboxFromBBoxes: (bboxes: OptionalBBox[]) => OptionalBBox;
  *   as GeoJSON to {@link bboxFromGeoJSON}, which follows its edges.
  * - It crosses the antimeridian, with `west > east`, when that box is narrower than the one from the
  *   lowest to the highest longitude. A tie, or positions spanning -180 to 180, keeps the latter.
- * - A very long array is sampled rather than scanned in full, which keeps the box close to exact.
+ * - Past 1000 positions, the array is sampled rather than scanned in full, so the box can leave out a
+ *   position between two samples.
  *
  * @group Utils
  */
@@ -4725,14 +4583,10 @@ export declare const bboxFromCoordsArray: (coordinates: Position[] | undefined)
 /**
  * Extracts or calculates a bounding box from GeoJSON objects.
  *
- * It handles various GeoJSON types, picking the best approach:
- * - It uses an existing `bbox` property, which is fastest.
- * - Otherwise, it calculates one from the geometry coordinates.
+ * - An existing `bbox` property wins over the geometry, as for Point features from TomTom services,
+ *   whose bbox may cover a broader area than the point itself.
+ * - Otherwise, it calculates one from the geometry coordinates, sampling large geometries.
  * - It aggregates the boxes of collections.
- * - It samples large geometries for performance.
- *
- * An existing bbox wins over the geometry. This matters for Point features from TomTom
- * services, whose bbox may cover a broader area than the point itself.
  *
  * A calculated box crosses the antimeridian, with `west > east`, when that is the narrower way to
  * enclose the input:
@@ -4752,32 +4606,6 @@ export declare const bboxFromCoordsArray: (coordinates: Position[] | undefined)
  * const bbox = bboxFromGeoJSON(place);
  * // Returns the bbox that came with the place
  *
- * // From a Polygon geometry (calculates bbox)
- * const polygon = {
- *   type: 'Polygon',
- *   coordinates: [[
- *     [4.88, 52.36],
- *     [4.90, 52.36],
- *     [4.90, 52.38],
- *     [4.88, 52.38],
- *     [4.88, 52.36]
- *   ]]
- * };
- * const polyBbox = bboxFromGeoJSON(polygon);
- * // Returns: [4.88, 52.36, 4.90, 52.38]
- *
- * // From a FeatureCollection (aggregates all features)
- * const places = await discoverPlaces({ query: 'coffee' });
- * const collectionBbox = bboxFromGeoJSON(places);
- * // Returns bbox encompassing all search results
- *
- * // From a LineString (calculates from coordinates)
- * const route = await calculateRoute({
- *   locations: [[4.9, 52.3], [4.5, 51.9]]
- * });
- * const routeBbox = bboxFromGeoJSON(route.features[0].geometry);
- * // Returns bbox containing the entire route
- *
  * // From an array of GeoJSON objects
  * const multiBbox = bboxFromGeoJSON([place1, place2, place3]);
  * // Returns bbox encompassing all three places
@@ -4799,8 +4627,6 @@ export declare const bboxCenter: (bbox: BBox) => Position;
  * For a box crossing the antimeridian, with `west > east`, the ring's east edge is `east + 360`, which
  * keeps it around the box rather than around the rest of the world.
  *
- * @param bbox The bounding box as `[west, south, east, north]`.
- *
  * @group Utils
  */
 export declare const polygonFromBBox: (bbox: BBox) => Feature<Polygon>;
@@ -4818,8 +4644,9 @@ export declare const polygonFromBBox: (bbox: BBox) => Feature<Polygon>;
  * @remarks
  * - A grid cell is found from the point's coordinates alone, so the cost grows with the points, not the
  *   cells. Every point with a value and finite coordinates lands in a cell, and the cells around the
- *   antimeridian stay side by side, their longitudes past ±180 where needed. A grid cell's `id` names
- *   its grid, column and row: `'hex:3:-2'`.
+ *   antimeridian stay side by side, their longitudes past ±180 where needed. With a `gridOrigin`, the
+ *   grid wraps around it instead, so its seam lies 180° from the origin. A grid cell's `id` names its
+ *   grid, column and row: `'hex:3:-2'`.
  * - Your own polygons are tested point by point, after a bounding-box check. A point inside several of
  *   them counts in each.
  * - The cell size is fixed. To follow the zoom, aggregate again on the map's `zoomend` with a size for
@@ -4855,9 +4682,9 @@ export declare const aggregateIntoCells: <P extends GeoJsonProperties, const S e
  *   them again with others.
  * - A curve ends at a straight longer than `maxStraightInMeters`, or where the road turns the
  *   other way, so an S-bend is two curves.
- * - A sharp corner between two straights, as at most junctions, is no curve: the road doesn't bend
- *   there. A roundabout is, and on a route with guidance a curve at a junction names its
- *   `maneuver`, as {@link CurveSectionProps} sets out.
+ * - A corner on a single vertex between two long straights is no curve: the road doesn't bend
+ *   there. A junction corner drawn round its kerb is one, and so is a roundabout. On a route with
+ *   guidance, a curve at a junction names its `maneuver`, as {@link CurveSectionProps} sets out.
  * - Where a route turns back at a waypoint, as at the end of a dead-end road, it makes no curve.
  * - Each curve's `severity` reads the route's `speedLimit` sections, when it has them.
  *
@@ -4960,8 +4787,10 @@ export declare const withCurveSections: (route: Route, { curve, curvyStretch }?:
  * @remarks
  * `calculateRoute` already fills `sections.distinct` with every distinct section when it returns two
  * or more routes. Call this to compare routes from separate calculations, or to keep only the
- * sections worth naming. Routes match on a road where they carry the same coordinates along it, as
- * the routes of one response do; routes from separate calculations may not.
+ * sections worth naming.
+ *
+ * Routes match on a road where they carry the same coordinates along it, as the routes of one
+ * response do; routes from separate calculations may not.
  *
  * @example
  * ```typescript
@@ -4976,7 +4805,7 @@ export declare const getDistinctSections: (routes: Routes | Route[], { minLength
 //#endregion
 //#region src/util/generateId.d.ts
 /**
- * Generate random id for map features
+ * A random id, distinct on every call, for features and sections.
  * @ignore
  */
 export declare const generateId: () => string;
@@ -5003,7 +4832,7 @@ export declare const servesGeopoliticalView: (view: GeopoliticalView, api: Geopo
 //#endregion
 //#region src/util/headers.d.ts
 /**
- * SDK name used TomTom custom header tomtom-user-agent
+ * The SDK name the `tomtom-user-agent` header starts with.
  * @ignore
  */
 export declare const TOMTOM_USER_AGENT_SDK_NAME = "MapsSDKJS";
@@ -5047,8 +4876,9 @@ export declare const getImportantRoads: (route: Route, { within, minLengthInMete
  * @remarks
  * `calculateRoute` returns `lanes` sections only with `guidance`, and not every maneuver has one.
  *
- * A section leads to the last instruction inside it or, when it ends at a stop line short of the
- * junction, to the next one after it. Where several lead to one instruction, the closest wins.
+ * A section leads to the last instruction at a junction inside it or, when it ends at a stop line
+ * short of the junction, to the next one after it. A maneuver at no junction, such as a departure, a
+ * waypoint, an arrival, a border or a tollgate, has no lanes. Where several lead to one instruction, the closest wins.
  * Instructions sharing a point, such as a roundabout's entry and exit, leave the lanes to the first.
  *
  * @param route - The route the instruction belongs to.
@@ -5073,37 +4903,18 @@ export declare const getInstructionLanes: (route: Route, instruction: Pick<Instr
 /**
  * Extracts the lng-lat position from various input formats.
  *
- * It normalizes the input to a standard GeoJSON Position, a lng-lat coordinate array.
  * It accepts:
  * - Raw coordinate arrays `[lng, lat]`
  * - GeoJSON Point geometries
  * - GeoJSON Point Features, including Places with entry points
  *
- * With `main-when-available`, a place with no entry point typed `'main'` uses its first untyped one, as
- * reverse geocoding returns them. {@link GetPositionEntryPointOption} has the full rule.
+ * With `main-when-available`, a place's entry point wins over its geometry, as
+ * {@link GetPositionEntryPointOption} sets out.
  *
- * @param hasLngLat An object that is or contains a lng-lat position.
- * @param options How to extract the position.
  * @returns The extracted position as `[longitude, latitude]`, or `null` if the input is invalid.
  *
  * @example
  * ```typescript
- * // From coordinate array
- * getPosition([4.9, 52.3]); // Returns: [4.9, 52.3]
- *
- * // From Point geometry
- * getPosition({
- *   type: 'Point',
- *   coordinates: [4.9, 52.3]
- * }); // Returns: [4.9, 52.3]
- *
- * // From Point Feature
- * getPosition({
- *   type: 'Feature',
- *   geometry: { type: 'Point', coordinates: [4.9, 52.3] },
- *   properties: {}
- * }); // Returns: [4.9, 52.3]
- *
  * // From Place with entry point
  * const place = {
  *   type: 'Feature',
@@ -5116,15 +4927,22 @@ export declare const getInstructionLanes: (route: Route, instruction: Pick<Instr
  * };
  * getPosition(place, { useEntryPoint: 'main-when-available' });
  * // Returns: [4.901, 52.301] (entry point instead of geometry)
- *
- * // Invalid input
- * getPosition(undefined); // Returns: null
  * ```
  *
  * @group Utils
  */
 export declare const getPosition: (hasLngLat: HasLngLat | undefined, options?: GetPositionOptions) => Position | null;
 //#endregion
+//#region src/util/polygon.d.ts
+/**
+ * A point strictly inside a polygon, given as its rings of `[x, y]` points, the outer ring first: the
+ * middle of the widest stretch inside it along a line near halfway up its extent, holes left out. The line
+ * runs between two heights of its points, so it never runs along an edge. Unlike the middle of its extent,
+ * which an L-shaped polygon can leave, or one of its corners, which a neighbouring polygon can share.
+ * @ignore
+ */
+export declare const pointInsidePolygon: (rings: readonly (readonly Position[])[]) => Position;
+//#endregion
 //#region src/util/route.d.ts
 /**
  * Finds the best index to insert a new waypoint into an existing route.
@@ -5140,26 +4958,11 @@ export declare const getPosition: (hasLngLat: HasLngLat | undefined, options?: G
  *
  * @remarks
  * - If the route has fewer than 2 coordinates or there are fewer than 2 existing waypoints, it returns 0.
- * - Fitting the waypoint along the route's progression minimizes detours, which keeps the route streamlined.
  *
  * @example
  * ```typescript
- * const route: Route = {
- *   type: 'Feature',
- *   id: 'route-1',
- *   geometry: {
- *     type: 'LineString',
- *     coordinates: [[4.9, 52.3], [4.95, 52.35], [5.0, 52.4]]
- *   },
- *   properties: { ... },
- *   bbox: [4.9, 52.3, 5.0, 52.4]
- * };
- *
- * const waypoints: WaypointLike[] = [
- *   [4.9, 52.3],   // origin
- *   [5.0, 52.4]    // destination
- * ];
- *
+ * // A route from [4.9, 52.3] to [5.0, 52.4], through [4.95, 52.35]
+ * const waypoints: WaypointLike[] = [[4.9, 52.3], [5.0, 52.4]];
  * const newWaypoint: WaypointLike = [4.95, 52.35];
  *
  * const insertIndex = findBestWaypointInsertionIndex(route, waypoints, newWaypoint);
@@ -5178,13 +4981,8 @@ export declare const findBestWaypointInsertionIndex: (route: Route, existingWayp
 /**
  * The multi-waypoint variant of {@link findBestWaypointInsertionIndex}.
  *
- * It projects every existing and new waypoint onto the route exactly once, then returns one
- * insertion slot per new waypoint. The i-th index is the slot in `existingWaypoints` where the
- * i-th new waypoint falls by its along-route location. Slot 0 is before the origin, and slot
- * `existingWaypoints.length` is after the destination.
- *
- * Several new waypoints may share a slot. To also merge them into the existing array in
- * along-route order, use {@link withInsertedWaypoints}, which ranks them within each slot.
+ * It projects every existing and new waypoint onto the route once, and gives each new waypoint
+ * the slot in `existingWaypoints` it falls in by its along-route location.
  *
  * @param route The existing calculated route, a Feature with LineString geometry.
  * @param existingWaypoints The existing waypoints in order, from origin through intermediate waypoints to destination.
@@ -5192,6 +4990,8 @@ export declare const findBestWaypointInsertionIndex: (route: Route, existingWayp
  * @returns The insertion slot indices, one per new waypoint, in input order.
  *
  * @remarks
+ * - Several new waypoints may share a slot. To merge them into the existing array in along-route
+ *   order too, use {@link withInsertedWaypoints}, which ranks them within each slot.
  * - An empty `newWaypoints` returns an empty array.
  * - If the route has fewer than 2 coordinates or there are fewer than 2 existing waypoints, every
  *   new waypoint gets `0`, so they would all prepend.
@@ -5212,30 +5012,13 @@ export declare const findBestWaypointInsertionIndices: (route: Route, existingWa
  *
  * @remarks
  * - It returns a new array and leaves the original waypoints array unmodified.
- * - It places the waypoint with the same logic as findBestWaypointInsertionIndex.
- * - It handles all edge cases, such as an empty route or fewer than 2 waypoints.
+ * - It places the waypoint with the same logic as findBestWaypointInsertionIndex, which says what it
+ *   does with a route of fewer than 2 coordinates or fewer than 2 waypoints.
  *
  * @example
  * ```typescript
- * const route: Route = {
- *   type: 'Feature',
- *   id: 'route-1',
- *   geometry: {
- *     type: 'LineString',
- *     coordinates: [[4.9, 52.3], [4.95, 52.35], [5.0, 52.4]]
- *   },
- *   properties: { ... },
- *   bbox: [4.9, 52.3, 5.0, 52.4]
- * };
- *
- * const waypoints: WaypointLike[] = [
- *   [4.9, 52.3],   // origin
- *   [5.0, 52.4]    // destination
- * ];
- *
- * const newWaypoint: WaypointLike = [4.95, 52.35];
- *
- * const updatedWaypoints = withInsertedWaypoint(route, waypoints, newWaypoint);
+ * // A route from [4.9, 52.3] to [5.0, 52.4], through [4.95, 52.35]
+ * const updatedWaypoints = withInsertedWaypoint(route, [[4.9, 52.3], [5.0, 52.4]], [4.95, 52.35]);
  * // Returns: [[4.9, 52.3], [4.95, 52.35], [5.0, 52.4]]
  * ```
  *
@@ -5245,21 +5028,16 @@ export declare const withInsertedWaypoint: (route: Route, existingWaypoints: Way
 /**
  * Returns a new array of waypoints with each new waypoint inserted at its optimal position.
  *
- * The multi-waypoint variant of {@link withInsertedWaypoint}. Unlike one-at-a-time insertion,
- * it projects every existing and new waypoint onto the route exactly once, then merges them:
- *
- * 1. It computes each new waypoint's insertion slot with {@link findBestWaypointInsertionIndices}.
- * 2. It ranks the new waypoints within each slot by along-route location. Waypoints that
- *    project to the same location keep their input order.
- *
- * The result holds the existing waypoints with the new ones spliced in at the right positions,
- * in along-route order, whatever the input order.
+ * The multi-waypoint variant of {@link withInsertedWaypoint}: it takes each new waypoint's slot from
+ * {@link findBestWaypointInsertionIndices}, and splices the new waypoints in along-route order,
+ * whatever their input order.
  *
  * @param route The existing calculated route, a Feature with LineString geometry.
  * @param existingWaypoints The existing waypoints in order, from origin through intermediate waypoints to destination.
  * @returns A new array with the waypoints inserted at their optimal positions.
  *
  * @remarks
+ * - Waypoints that project to the same location keep their input order.
  * - It returns a new array and leaves `existingWaypoints` unmodified.
  * - Passing an empty `newWaypoints` array returns a shallow copy of `existingWaypoints`.
  * - When the route has fewer than 2 coordinates or there are fewer than 2 existing waypoints, all
@@ -5291,7 +5069,7 @@ export declare const withInsertedWaypoints: (route: Route, existingWaypoints: Wa
  * @param pathIndex Zero-based index into the route's coordinate array.
  * @returns The interpolated {@link RouteProgressAtPoint}, or `undefined` when:
  *   - the route has no `progress` data
- *   - `pathIndex` is outside `[0, coordinates.length - 1]`
+ *   - `pathIndex` is not an integer, or is outside `[0, coordinates.length - 1]`
  *   - `pathIndex` falls outside the range covered by the progress entries
  *   - any required distance or time value is missing from the bracketing entries
  *
@@ -5476,8 +5254,9 @@ export declare const getProgressAtNearestRoutePoint: (route: Route, point: HasLn
  * @returns The types the route has within the spans, each with its sections there and their length.
  *
  * @remarks
- * - A section counts when it shares a segment with a span, as {@link getSectionOverlap} finds, and
- *   only its part within the spans adds to `lengthInMeters`. Its `shares` entry says how much of it
+ * - A section counts when some of its length lies within the spans, so a segment of no length
+ *   shared with one, which {@link getSectionOverlap} still finds, doesn't count. Only its part
+ *   within the spans adds to `lengthInMeters`. Its `shares` entry says how much of it
  *   that part is, to prorate a traffic section's `delayInSeconds`, for example.
  * - The sections come back whole, so their ids suit `RoutingModule.setSectionFocus` on the routes shown.
  * - Pass `sections.distinct` as `within` for what sets a route apart from its alternatives.
@@ -5542,14 +5321,16 @@ export declare const indexedMagnitudes: DelayMagnitude[];
  *
  * It shows hours and minutes, rounding and formatting by the duration's length.
  *
- * @param seconds The duration in seconds. Values under 30 seconds return `undefined`.
+ * @param seconds The duration in seconds. A negative duration formats as its absolute value.
  * @param options Custom display units for the hours and minutes text.
  *
- * @returns The formatted time, such as "1 hr 30 min" or "45 min", or `undefined` if the duration is too short.
+ * @returns The formatted time, such as "1 hr 30 min", "45 min" or "< 1 min". A number always gives a
+ * string; only an `undefined` duration returns `undefined`.
  *
  * @remarks
  * Rounding:
- * - Durations under 30 seconds return `undefined`.
+ * - `0` gives "0 min".
+ * - Any other duration under 30 seconds gives "< 1 min", in the minute units you set.
  * - 30-59 seconds round to "1 min".
  * - Minutes round to the nearest minute.
  * - Hours show once the duration rounds to an hour or more.
@@ -5564,8 +5345,9 @@ export declare const indexedMagnitudes: DelayMagnitude[];
  * @example
  * ```typescript
  * // Basic usage
- * formatDuration(0);       // undefined (too short)
- * formatDuration(20);      // undefined (too short)
+ * formatDuration(undefined); // undefined
+ * formatDuration(0);       // "0 min"
+ * formatDuration(20);      // "< 1 min"
  * formatDuration(30);      // "1 min"
  * formatDuration(60);      // "1 min"
  * formatDuration(100);     // "2 min"
@@ -5578,6 +5360,8 @@ export declare const indexedMagnitudes: DelayMagnitude[];
  * // Custom units
  * formatDuration(3660, { hours: 'h', minutes: 'm' });
  * // Returns: "1 h 01 m"
+ * formatDuration(20, { minutes: 'm' });
+ * // Returns: "< 1 m"
  *
  * // Route travel time
  * const route = await calculateRoute({ ... });
@@ -5588,9 +5372,18 @@ export declare const indexedMagnitudes: DelayMagnitude[];
  *
  * @group Utils
  */
-export declare const formatDuration: (seconds: number | undefined, options?: TimeDisplayUnits) => string | undefined;
+export declare function formatDuration(seconds: number, options?: TimeDisplayUnits): string;
+/**
+ * Formats a duration in seconds into a human-readable time string, as the overload above does for a
+ * number, or returns `undefined` for an `undefined` duration.
+ *
+ * @group Utils
+ */
+export declare function formatDuration(seconds: number | undefined, options?: TimeDisplayUnits): string | undefined;
 /**
  * Formats a distance in meters for display, by unit type. Fewer meters give more precision.
+ *
+ * To override the default units, use `options` or the global {@link TomTomConfig}.
  * @example
  * ```ts
  * const metric = { type: 'metric' } as const;
@@ -5625,4 +5418,4 @@ export declare const formatDuration: (seconds: number | undefined, options?: Tim
  */
 export declare const formatDistance: (meters: number | undefined, options?: DistanceDisplayUnits) => string;
 //#endregion
-export type { AggregateIntoCellsOptions, AggregatedCells, Anything, BBox, CellGrid, CellGridOptions, CellGridShape, CellStatistic, CellStatistics, CellValue, CellValueOptions, ChargingPark, CompareRoutesOptions, CurveDetectionOptions, CurveSectionsOptions, CurvyStretchSectionsOptions, DistanceUnitsType, DistinctSectionsOptions, DrivingSide, FeatureCollectionWithProperties, Fuel, GeometryDataSource, GetPositionEntryPointOption, GetPositionOptions, Guidance, HasBBox, HasLngLat, ImportantRoad, ImportantRoadsOptions, Instruction, InstructionText, Landmark, LatticeGridOptions, LegSummary, Maneuver, ManeuverAngle, ManeuverView, Moment, NumericPropertyKey, OpeningHours, OpeningHoursMode, OptionalBBox, POI, PathLike, PlaceDataSources, PoiDetailsDataSource, PolygonFeature, PolygonFeatures, RelatedPOI, RoadInformation, RoadInformationProperty, RoadShield, RoadShieldReference, RoundaboutType, RouteComparison, RoutePathPoint, RoutePlanningLocation, RoutePlanningLocationType, RouteSummary, SectionsWithin, SectionsWithinOfType, SectionsWithinOptions, SideRoad, SideRoadSide, Signpost, SummaryBase, TimeRange, TimeZone, TollPaymentType, TomTomAPIHeaders, Waypoint, WaypointLike, WaypointProps, Waypoints };
+export type { APIErrorDetails, AggregateIntoCellsOptions, AggregatedCells, Anything, BBox, CellGrid, CellGridOptions, CellGridShape, CellStatistic, CellStatistics, CellValue, CellValueOptions, ChargingPark, CompareRoutesOptions, CurveDetectionOptions, CurveSectionsOptions, CurvyStretchSectionsOptions, DistanceUnitsType, DistinctSectionsOptions, DrivingSide, FeatureCollectionWithProperties, Fuel, GeometryDataSource, GetPositionEntryPointOption, GetPositionOptions, Guidance, HasBBox, HasLngLat, ImportantRoad, ImportantRoadsOptions, Instruction, InstructionText, Landmark, LatticeGridOptions, LegSummary, Maneuver, ManeuverAngle, ManeuverView, Moment, NumericPropertyKey, OpeningHours, OpeningHoursMode, OptionalBBox, POI, PathLike, PlaceDataSources, PoiDetailsDataSource, PolygonFeature, PolygonFeatures, PrivatePreviewAccess, RelatedPOI, RoadInformation, RoadInformationProperty, RoadShield, RoadShieldReference, RoundaboutType, RouteComparison, RoutePathPoint, RoutePlanningLocation, RoutePlanningLocationType, RouteSummary, SectionsWithin, SectionsWithinOfType, SectionsWithinOptions, SideRoad, SideRoadSide, Signpost, SummaryBase, TimeRange, TimeZone, TollPaymentType, TomTomAPIHeaders, Waypoint, WaypointLike, WaypointProps, Waypoints };