@mapslibvn/core 0.4.0 → 0.5.0

package/README.md

@@ -1,7 +1,71 @@
 # @mapslibvn/core
 
-Client TypeScript không phụ thuộc giao diện cho Places API MapsLibVN, kèm kiểu dữ liệu, chuẩn hóa
-tiếng Việt và chuỗi ghi nguồn dùng chung.
+[![npm version](https://img.shields.io/npm/v/@mapslibvn/core.svg)](https://www.npmjs.com/package/@mapslibvn/core)
+[![npm downloads](https://img.shields.io/npm/dm/@mapslibvn/core.svg)](https://www.npmjs.com/package/@mapslibvn/core)
+[![minzipped size](https://img.shields.io/bundlephobia/minzip/@mapslibvn/core)](https://bundlephobia.com/package/@mapslibvn/core)
+[![license](https://img.shields.io/npm/l/@mapslibvn/core.svg)](https://www.npmjs.com/package/@mapslibvn/core)
+
+**The Vietnam-first geodata client for TypeScript/JavaScript.** Framework-agnostic, no runtime dependencies, and built from day one to understand Vietnamese addresses the way people actually type them — no diacritics, abbreviated street types, old-vs-new administrative names, and hẻm/ngõ (alley) numbering that generic geocoders get wrong.
+
+`@mapslibvn/core` is the foundation shared by [`@mapslibvn/web`](https://www.npmjs.com/package/@mapslibvn/web), [`@mapslibvn/react`](https://www.npmjs.com/package/@mapslibvn/react) and [`@mapslibvn/react-native`](https://www.npmjs.com/package/@mapslibvn/react-native) — but it works just as well on its own, in any Node.js service, CLI, or non-map UI (search bars, address forms, delivery apps, coverage checks…).
+
+## Why teams pick it
+
+- 🇻🇳 **Vietnamese text handling, built in** — `normalizeVi`, `stripDiacritics`, `expandAbbrev`, `applyBrandAlias` normalize things like "chung cu", "P. Bến Thành" or "Cty" the way Vietnamese users actually search.
+- 🏠 **Real address parsing** — `parseAddress` splits a raw Vietnamese address string into house number, hẻm/ngõ, street, ward, district and province, with a confidence score.
+- 🌍 **Pick your POI sources** — mix OpenStreetMap, Overture Maps and Foursquare Open Places per request, or just use the sensible "all" default.
+- 🧭 **Headless turn-by-turn navigation** — a pure state machine (`createNavigator`) handling rerouting, off-route detection, maneuver formatting and voice-announcement timing, with zero UI dependency. It's the same engine powering the web and React Native navigation layers.
+- 📦 **Small and fully typed** — ESM-only, one flat export surface, gzip barrel kept under 20 kB by CI.
+- ⚖️ **Attribution helpers included** — `attributionText()` / `attributionHtml()` so you stay compliant with OSM/Overture/Foursquare data licenses even outside a map view.
+
+## Install
+
+```bash
+npm install @mapslibvn/core
+```
+
+Works with Node.js 22+ on the server, and any modern browser with `fetch`.
+
+## Quick start
+
+```ts
+import { createClient } from '@mapslibvn/core';
+
+const places = createClient({
+  apiKey: 'mlv_live_…',
+  baseUrl: 'https://api.ai-solutions.io.vn',
+});
+
+const { items } = await places.autocomplete('cho ben thanh', {
+  near: [106.7, 10.776],
+  limit: 5,
+});
+```
+
+The client covers autocomplete, search, nearby, geocode, reverse geocode, place details, directions, style URLs and edit suggestions. Never ship a secret key in client-side code or commit it to source control — browser-facing keys must be origin-restricted.
+
+📖 Full API reference: <https://mapslibvn-docs.pages.dev/sdk/>
+
+📦 Part of the MapsLibVN SDK family: [`@mapslibvn/web`](https://www.npmjs.com/package/@mapslibvn/web) · [`@mapslibvn/react`](https://www.npmjs.com/package/@mapslibvn/react) · [`@mapslibvn/react-native`](https://www.npmjs.com/package/@mapslibvn/react-native)
+
+Source license: MIT. When you display map data, you must keep attribution as described in the docs and `THIRD_PARTY_NOTICES.md`.
+
+---
+
+## Tiếng Việt
+
+**Client TypeScript/JavaScript "Việt Nam trước" cho dữ liệu địa lý.** Không phụ thuộc framework, không cần thư viện ngoài lúc chạy, và được xây dựng ngay từ đầu để hiểu địa chỉ tiếng Việt đúng như người dùng thật gõ — không dấu, viết tắt loại đường, tên hành chính cũ/mới, và cách đánh số hẻm/ngõ mà các bộ geocoder thông thường không xử lý đúng.
+
+`@mapslibvn/core` là nền tảng dùng chung cho [`@mapslibvn/web`](https://www.npmjs.com/package/@mapslibvn/web), [`@mapslibvn/react`](https://www.npmjs.com/package/@mapslibvn/react) và [`@mapslibvn/react-native`](https://www.npmjs.com/package/@mapslibvn/react-native) — nhưng vẫn dùng tốt độc lập trong bất kỳ service Node.js, CLI hay giao diện không có bản đồ nào (ô tìm kiếm, form địa chỉ, app giao hàng, kiểm tra vùng phủ…).
+
+## Vì sao nên chọn
+
+- 🇻🇳 **Xử lý tiếng Việt có sẵn** — `normalizeVi`, `stripDiacritics`, `expandAbbrev`, `applyBrandAlias` chuẩn hoá "chung cư", "P. Bến Thành", "Cty" đúng cách người Việt hay tìm.
+- 🏠 **Phân tích địa chỉ thật** — `parseAddress` tách một chuỗi địa chỉ tiếng Việt thành số nhà, hẻm/ngõ, đường, phường, quận, tỉnh, kèm điểm tin cậy (`confidence`).
+- 🌍 **Tự chọn nguồn POI** — trộn OpenStreetMap, Overture Maps và Foursquare Open Places theo từng request, hoặc dùng mặc định "cả ba" (`all`).
+- 🧭 **Dẫn đường không giao diện** — một máy trạng thái thuần (`createNavigator`) lo việc tính lại tuyến, phát hiện lệch tuyến, định dạng chỉ dẫn rẽ và thời điểm đọc thoại — không phụ thuộc UI, dùng chung cho cả lớp dẫn đường web lẫn React Native.
+- 📦 **Nhỏ gọn và có kiểu đầy đủ** — chỉ ESM, một điểm export duy nhất, CI giữ trần gzip dưới 20 kB.
+- ⚖️ **Có sẵn hàm ghi nguồn** — `attributionText()` / `attributionHtml()` để tuân thủ giấy phép dữ liệu OSM/Overture/Foursquare kể cả khi không hiển thị bản đồ.
 
 ## Cài đặt
 
@@ -11,7 +75,7 @@ npm install @mapslibvn/core
 
 Yêu cầu Node.js 22+ khi chạy phía máy chủ. Trình duyệt hiện đại có sẵn `fetch` cũng dùng được.
 
-## Ví dụ
+## Bắt đầu nhanh
 
 ```ts
 import { createClient } from '@mapslibvn/core';
@@ -27,11 +91,10 @@ const { items } = await places.autocomplete('cho ben thanh', {
 });
 ```
 
-API gồm autocomplete, search, nearby, geocode, reverse geocode, chi tiết địa điểm, style URL và
-gửi đề xuất chỉnh sửa. Không đưa khóa bí mật vào mã nguồn hoặc commit; khóa trình duyệt phải giới
-hạn đúng origin.
+API gồm autocomplete, search, nearby, geocode, reverse geocode, chi tiết địa điểm, chỉ đường (directions), style URL và gửi đề xuất chỉnh sửa. Không đưa khóa bí mật vào mã nguồn hoặc commit; khóa trình duyệt phải giới hạn đúng origin.
+
+📖 Tài liệu API đầy đủ: <https://mapslibvn-docs.pages.dev/sdk/>
 
-Tài liệu: <https://mapslibvn-docs.pages.dev/sdk/>
+📦 Nằm trong họ SDK MapsLibVN: [`@mapslibvn/web`](https://www.npmjs.com/package/@mapslibvn/web) · [`@mapslibvn/react`](https://www.npmjs.com/package/@mapslibvn/react) · [`@mapslibvn/react-native`](https://www.npmjs.com/package/@mapslibvn/react-native)
 
-Giấy phép mã nguồn: MIT. Khi hiển thị dữ liệu bản đồ, phải giữ attribution theo tài liệu và
-`THIRD_PARTY_NOTICES.md`.
+Giấy phép mã nguồn: MIT. Khi hiển thị dữ liệu bản đồ, phải giữ attribution theo tài liệu và `THIRD_PARTY_NOTICES.md`.

package/THIRD_PARTY_NOTICES.md

@@ -9,7 +9,7 @@ MapsLibVN **không liên kết với, không được tài trợ hay chứng th
 nhãn hiệu của bên thứ ba; tên đó xuất hiện ở đây và trong tài liệu chỉ để mô tả nguồn gốc kỹ
 thuật của thư viện mà MapsLibVN sử dụng.
 
-Cập nhật: 04/09/2026.
+Cập nhật: 12/09/2026.
 
 ## 1. Thư viện được đóng gói hoặc là peer dependency của SDK
 
@@ -20,6 +20,8 @@ Cập nhật: 04/09/2026.
 | react, react-dom | 18.3.1 (peer, chỉ `@mapslibvn/react`) | MIT | |
 | @maplibre/maplibre-react-native | 11.3.8 (peer, chỉ `@mapslibvn/react-native`) | MIT | bộ vẽ bản đồ native iOS/Android |
 | react, react-native | react ≥ 19.1, react-native ≥ 0.80 (peer, chỉ `@mapslibvn/react-native`) | MIT | |
+| expo-location, expo-task-manager | 57.0.17 (peer **tuỳ chọn**, chỉ entry `@mapslibvn/react-native/expo`) | MIT | định vị tiền cảnh và nền cho dẫn đường |
+| expo-speech, expo-audio, expo-keep-awake | 57.0.3 / 57.0.5 / 57.0.1 (peer **tuỳ chọn**, chỉ entry `@mapslibvn/react-native/expo`) | MIT | đọc câu chỉ dẫn, phiên âm thanh khi nền, giữ màn hình sáng |
 
 Nguyên văn giấy phép ở mục 4.
 
@@ -385,9 +387,38 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SO
 Gói này nhúng MapLibre Native (Android, iOS) khi build app — xem thông báo giấy phép trong
 chính gói đó cho các thành phần native.
 
+### 4.9 expo-location, expo-task-manager, expo-speech, expo-audio, expo-keep-awake — MIT
+
+```
+The MIT License (MIT)
+
+Copyright (c) 2015-present 650 Industries, Inc. (aka Expo)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+Các gói này là peer dependency **tuỳ chọn**: chỉ app import `@mapslibvn/react-native/expo` (dẫn
+đường) mới cài; SDK không đóng gói mã của chúng.
+
 ## 5. Công cụ phía máy chủ (không phân phối, liệt kê để minh bạch)
 
 Planetiler (Apache-2.0), tippecanoe (BSD-2-Clause), osmium-tool (GPL-3.0 — dùng như công cụ
 dòng lệnh, không liên kết mã), pyosmium (BSD-2-Clause), DuckDB (MIT), PostgreSQL
-(PostgreSQL License), PostGIS (GPL-2.0 — chạy như dịch vụ), Hono (MIT), cloudflared
+(PostgreSQL License), PostGIS (GPL-2.0 — chạy như dịch vụ), Valhalla (MIT — engine chỉ đường, chạy như dịch vụ riêng trên máy chủ, không liên kết mã), Hono (MIT), cloudflared
 (Apache-2.0), Astro Starlight (MIT), Vitest (MIT), Playwright (Apache-2.0).

package/dist/index.d.ts

@@ -177,6 +177,68 @@ interface PoiFeature {
     group: string;
     lngLat: [number, number];
 }
+/** Phương tiện cho `GET /v1/directions` (spec dẫn đường A). */
+type TravelMode = 'motorbike' | 'car' | 'walk';
+type DirectionsLang = 'vi' | 'en';
+/** Loại bước rẽ theo tập cố định của MapsLibVN — không phụ thuộc engine. */
+type ManeuverKind = 'depart' | 'arrive' | 'continue' | 'slight_right' | 'slight_left' | 'turn_right' | 'turn_left' | 'sharp_right' | 'sharp_left' | 'uturn_right' | 'uturn_left' | 'ramp_straight' | 'ramp_right' | 'ramp_left' | 'exit_right' | 'exit_left' | 'keep_right' | 'keep_left' | 'merge' | 'merge_right' | 'merge_left' | 'roundabout_enter' | 'roundabout_exit' | 'ferry_enter' | 'ferry_exit' | 'elevator' | 'steps' | 'escalator' | 'building_enter' | 'building_exit' | 'other';
+interface RouteStep {
+    kind: ManeuverKind;
+    instruction: string;
+    /** Câu rẽ ngắn gọn để đọc lúc còn cách xa (spec B); Valhalla không trả → null. */
+    verbal_alert: string | null;
+    verbal_pre: string | null;
+    verbal_post: string | null;
+    street_names: string[];
+    distance_m: number;
+    duration_s: number;
+    /** Chỉ số điểm trong polyline của CẢ tuyến (đã dịch qua các leg). */
+    shape_begin: number;
+    shape_end: number;
+    /** [lng, lat] điểm bắt đầu bước. */
+    location: [number, number];
+    /** Số lối ra khi `kind = roundabout_enter`, còn lại null. */
+    roundabout_exit: number | null;
+}
+interface RouteLeg {
+    distance_m: number;
+    duration_s: number;
+    /** Chỉ số điểm đầu của leg trong polyline tuyến. */
+    shape_offset: number;
+    steps: RouteStep[];
+}
+interface Route {
+    mode: TravelMode;
+    distance_m: number;
+    duration_s: number;
+    /** [minLng, minLat, maxLng, maxLat] */
+    bbox: [number, number, number, number];
+    /** polyline6 của cả tuyến — giải mã bằng `decodePolyline6` → `[lng, lat][]`. */
+    geometry: string;
+    legs: RouteLeg[];
+    flags: {
+        toll: boolean;
+        highway: boolean;
+        ferry: boolean;
+    };
+}
+interface Waypoint {
+    /** [lng, lat] điểm người dùng gửi. */
+    location: [number, number];
+    /** [lng, lat] điểm trên tuyến gần nhất (đầu leg tương ứng). */
+    snapped: [number, number];
+    name: string | null;
+}
+interface DirectionsResponse {
+    routes: Route[];
+    waypoints: Waypoint[];
+    attribution: string;
+    /** Thông tin chẩn đoán, không phải hợp đồng ổn định. */
+    engine?: {
+        name: string;
+        graph: string | null;
+    };
+}
 
 type Theme = 'light' | 'dark';
 interface ClientOptions {
@@ -206,6 +268,19 @@ interface AttributionResponse {
         license?: string;
     }[];
 }
+interface DirectionsOptions {
+    /** [lat, lng] — vĩ độ trước, cùng quy ước với `near`. */
+    from: [number, number];
+    to: [number, number];
+    /** Tối đa 5 điểm dừng, mỗi điểm [lat, lng]. */
+    via?: [number, number][];
+    /** Mặc định máy chủ: `motorbike`. */
+    mode?: TravelMode;
+    /** Mặc định máy chủ: `vi`. */
+    lang?: DirectionsLang;
+    /** Xin thêm một tuyến thay thế (bị bỏ qua khi có `via`). */
+    alternatives?: boolean;
+}
 declare function createClient(options: ClientOptions): {
     baseUrl: string;
     attribution: () => Promise<AttributionResponse>;
@@ -245,6 +320,8 @@ declare function createClient(options: ClientOptions): {
         items: GeocodeItem[];
     }>;
     reverse: (lat: number, lng: number) => Promise<ReverseResponse>;
+    /** Chỉ đường (spec dẫn đường A). Response dùng [lng, lat]; tham số vào dùng [lat, lng]. */
+    directions: (opts: DirectionsOptions) => Promise<DirectionsResponse>;
     /** Gửi đóng góp/sửa POI (spec 6.1). Khoá phải có scope edits:write. */
     suggestEdit: (edit: SuggestEditRequest) => Promise<SuggestEditResponse>;
 };
@@ -300,6 +377,7 @@ declare function adminAliasKeys(input: AdminAliasKeyInput): string[];
  * không có API đổi layout property của lớp có sẵn. Web dùng `applyLanguage` lúc chạy nhưng
  * chia sẻ `nameExpression`/`isNameLabelLayer` từ đây.
  */
+
 type Lang = 'vi' | 'en';
 interface StyleLayerLike {
     id: string;
@@ -311,6 +389,11 @@ interface StyleLike {
     layers?: readonly StyleLayerLike[] | undefined;
 }
 declare const POI_LAYER_ID = "poi";
+/**
+ * Lớp symbol đầu tiên của từng theme MapsLibVN — chèn tuyến dẫn đường trước lớp này để nhãn đường
+ * nằm trên tuyến (spec C mục 4). `packages/style/src/first-symbol-layer.test.ts` bảo vệ giá trị.
+ */
+declare const FIRST_SYMBOL_LAYER_ID: Readonly<Record<Theme, string>>;
 declare function isPoiStyleLayer(layer: StyleLayerLike): boolean;
 declare function nameExpression(lang: Lang): unknown[];
 /** Lớp nhãn tên (symbol có `text-field` tham chiếu `name`), trừ lớp chủ quyền luôn tiếng Việt. */
@@ -421,4 +504,324 @@ declare function applyToponymAlias(normalized: string): string;
  */
 declare function viKey(normalized: string): string;
 
-export { ATTRIBUTION_LINKS, type AdminAliasKeyInput, type AlleyKeyword, type AttributionLink, type AttributionResponse, type AutocompleteItem, type AutocompleteType, type ClientOptions, DEFAULT_POI_SOURCES, type EditChanges, type EditKind, type GeocodeItem, type GeocodeMatched, type GeocodePrecision, type Lang, type MapsLibVNClient, MapsLibVNError, NAME_FILLERS, POI_LAYER_ID, POI_SOURCES, POI_SOURCE_PROFILES, type ParsedAddress, type Place, type PlaceAddress, type PlaceCategory, type PlaceDetails, type PlaceSource, type PoiFeature, type PoiSource, type PoiSourceProfile, type ReverseAddress, type ReverseResponse, type SearchKeys, type StyleLayerLike, type StyleLike, type SuggestEditRequest, type SuggestEditResponse, TOPONYM_ALIAS, type Theme, type ToponymEntry, adminAliasKeys, applyBrandAlias, applyToponymAlias, attributionHtml, attributionText, createClient, expandAbbrev, filterNameAlt, foldTelex, hidePoiLayer, isNameLabelLayer, isPoiStyleLayer, localizeStyle, looksLikeTelex, nameCore, nameExpression, normalizePoiSources, normalizeVi, parseAddress, parsePoiSourcesCsv, poiSourceClause, poiSourcesKey, profileForSources, searchKeys, stripDiacritics, viKey };
+/**
+ * Polyline mã hoá kiểu Google với precision 1e6 (Valhalla `legs[].shape`).
+ * Toạ độ trả về theo thứ tự GeoJSON `[lng, lat]`.
+ */
+declare function decodePolyline6(encoded: string): [number, number][];
+/** Mã hoá `[lng, lat][]` thành polyline6; Worker dùng để nối shape các leg thành một chuỗi. */
+declare function encodePolyline6(coords: readonly (readonly [number, number])[]): string;
+
+declare const MANEUVER_KINDS: readonly ManeuverKind[];
+/**
+ * Mã maneuver Valhalla (0–43, `TripDirections_Maneuver_Type`) → kind MapsLibVN. Đặt ở core để Worker
+ * và SDK dùng một bản (spec A mục 6); bảng chỉ là dữ liệu, không phải logic gọi engine.
+ * Mã transit 30–36 và 0 (kNone) không có trong bảng → `other`.
+ */
+declare const VALHALLA_MANEUVER_KIND: Readonly<Record<number, ManeuverKind>>;
+declare function maneuverKindFromValhalla(type: number): ManeuverKind;
+
+/** Một điểm định vị. Lớp dán (web/RN) đổi từ API nền tảng sang dạng này. */
+interface GeoFix {
+    lng: number;
+    lat: number;
+    /** Bán kính sai số (m). Thiếu → coi là 10 m. */
+    accuracy_m?: number;
+    /** Độ so với bắc, thuận chiều kim đồng hồ; null/undefined khi đứng yên hoặc không có. */
+    heading?: number | null;
+    speed_mps?: number | null;
+    /** ms epoch — nguồn thời gian duy nhất của máy trạng thái. */
+    timestamp: number;
+}
+/** Nguồn tuyến. `MapsLibVNClient` của `createClient` thoả kiểu này không cần bọc. */
+interface RouteProvider {
+    directions(opts: DirectionsOptions): Promise<DirectionsResponse>;
+}
+interface PositionError {
+    code: 'denied' | 'unavailable' | 'timeout';
+    message: string;
+    raw?: unknown;
+}
+/** Nguồn vị trí do lớp dán cung cấp; core chỉ định nghĩa kiểu để web và RN cùng hình. */
+interface PositionSource {
+    subscribe(onFix: (fix: GeoFix) => void, onError?: (error: PositionError) => void): () => void;
+}
+type NavigationStatus = 'idle' | 'navigating' | 'off_route' | 'rerouting' | 'arrived' | 'stopped';
+interface NavigationThresholds {
+    /** Ngưỡng lệch cơ sở; hiệu dụng = max(offRoute_m, 1.5 × accuracy_m). */
+    offRoute_m: number;
+    /** Số fix liên tiếp ngoài ngưỡng để xác nhận lệch. */
+    offRouteFixes: number;
+    /** … và đã kéo dài ít nhất bấy nhiêu giây (theo timestamp fix). */
+    offRouteSeconds: number;
+    /** Fix kém hơn thì bỏ, không cập nhật gì. */
+    maxAccuracy_m: number;
+    /** Đọc "Trong X nữa, …" khi còn ≤. */
+    approach_m: number;
+    /** Đọc câu rẽ khi còn ≤. */
+    pre_m: number;
+    /** Bán kính đến nơi / qua điểm via. */
+    arrive_m: number;
+    rerouteCooldown_s: number;
+    rerouteMaxFailures: number;
+}
+/** Số khởi điểm theo spec B mục 4.3; chốt lại sau thực địa (Task 20). */
+declare const NAVIGATION_THRESHOLDS: Readonly<Record<TravelMode, NavigationThresholds>>;
+interface NavigationProgress {
+    status: NavigationStatus;
+    route: Route;
+    routeIndex: number;
+    legIndex: number;
+    /** Chỉ số step PHẲNG qua mọi leg (spec B 4.4). */
+    stepIndex: number;
+    step: RouteStep;
+    /** Step có điểm rẽ kế tiếp; null khi step hiện tại là arrive cuối. */
+    nextStep: RouteStep | null;
+    /** [lng, lat] điểm đã bám lên tuyến. */
+    snapped: [number, number];
+    /** Hướng đi (độ): heading GPS khi speed_mps > 1, còn không thì hướng đoạn tuyến. */
+    bearing: number;
+    /** Chỉ số đỉnh đầu của đoạn polyline đang ở. */
+    shapeIndex: number;
+    traveled_m: number;
+    remaining_m: number;
+    /** ETA: phần còn lại của step hiện tại theo tỉ lệ + tổng duration các step sau. */
+    remaining_s: number;
+    /** Tới điểm rẽ của nextStep; 0 khi không còn. */
+    distanceToStep_m: number;
+    /** Khoảng cách vuông góc từ fix tới tuyến. */
+    offRoute_m: number;
+    fix: GeoFix;
+}
+interface Announcement {
+    text: string;
+    kind: 'depart' | 'post' | 'approach' | 'pre' | 'arrive';
+    stepIndex: number;
+    /** 3 = câu rẽ / đến nơi / khởi hành, 2 = "Trong X nữa", 1 = verbal_post. */
+    priority: 1 | 2 | 3;
+}
+interface NavigationEvents {
+    status: {
+        status: NavigationStatus;
+        previous: NavigationStatus;
+    };
+    progress: NavigationProgress;
+    step: {
+        stepIndex: number;
+        step: RouteStep;
+    };
+    waypoint: {
+        legIndex: number;
+        waypoint: Waypoint;
+    };
+    offRoute: {
+        distance_m: number;
+        fix: GeoFix;
+    };
+    reroute: {
+        reason: 'off_route' | 'manual';
+        response: DirectionsResponse;
+    };
+    rerouteFailed: {
+        error: unknown;
+        attempts: number;
+        final: boolean;
+    };
+    announce: Announcement;
+    arrive: {
+        waypoint: Waypoint;
+        fix: GeoFix;
+    };
+}
+interface NavigatorOptions {
+    response: DirectionsResponse;
+    /** Mặc định 0. */
+    routeIndex?: number;
+    /** Bắt buộc khi `reroute` là 'auto' (mặc định). */
+    provider?: RouteProvider;
+    /** Mặc định 'auto'. */
+    reroute?: 'auto' | 'manual';
+    /** Mặc định 'vi'; dùng cho câu "Trong X nữa" và request tính lại. */
+    lang?: DirectionsLang;
+    thresholds?: Partial<NavigationThresholds>;
+}
+interface Navigator {
+    readonly status: NavigationStatus;
+    readonly progress: NavigationProgress | null;
+    /** Đồng bộ. Fix kém accuracy hoặc timestamp không tăng bị bỏ. */
+    update(fix: GeoFix): void;
+    /** Thay tuyến: reset bước, lịch đọc, bộ đếm lệch; fix kế tiếp bám trên toàn tuyến. */
+    setRoute(response: DirectionsResponse, routeIndex?: number): void;
+    /** Gọi provider ngay (bỏ cooldown và trần lỗi). */
+    reroute(): Promise<void>;
+    stop(): void;
+    on<K extends keyof NavigationEvents>(event: K, handler: (e: NavigationEvents[K]) => void): void;
+    off<K extends keyof NavigationEvents>(event: K, handler: (e: NavigationEvents[K]) => void): void;
+}
+
+/** Hình học cầu và chiếu điểm cho dẫn đường (spec B 4.1). Toạ độ luôn `[lng, lat]`. */
+type LngLat = readonly [number, number];
+declare function haversineM(a: LngLat, b: LngLat): number;
+/** Hướng từ a tới b, độ [0, 360) thuận chiều kim đồng hồ từ bắc. */
+declare function bearingDeg(a: LngLat, b: LngLat): number;
+/** Chênh góc nhỏ nhất giữa hai hướng, [0, 180]. */
+declare function angleDiffDeg(a: number, b: number): number;
+interface Projection {
+    /** Vị trí trên đoạn, 0 = a, 1 = b (đã kẹp). */
+    t: number;
+    point: [number, number];
+    /** Khoảng cách từ p tới điểm chiếu (m). */
+    distance_m: number;
+}
+/**
+ * Chiếu p lên đoạn ab trong mặt phẳng cục bộ quanh a (equirectangular, đủ chính xác cho đoạn dưới
+ * vài km). Đoạn suy biến (a = b) → t = 0.
+ */
+declare function projectOnSegment(p: LngLat, a: LngLat, b: LngLat): Projection;
+/** Khoảng cách cộng dồn (m) tại từng đỉnh; `cum[0] = 0`; mảng rỗng → rỗng. */
+declare function cumulativeDistances(coords: readonly LngLat[]): number[];
+
+interface FlatStep {
+    step: RouteStep;
+    legIndex: number;
+    indexInLeg: number;
+    /** Mét từ đầu tuyến tới điểm rẽ của step (đầu step). */
+    begin_m: number;
+    /** = begin_m của step kế, hoặc tổng chiều dài với step cuối. */
+    end_m: number;
+}
+interface RouteIndex {
+    coords: [number, number][];
+    /** cum[i] = mét từ đầu tuyến tới đỉnh i. */
+    cum: number[];
+    total_m: number;
+    /** Step phẳng qua mọi leg, theo thứ tự đi. */
+    steps: FlatStep[];
+    /** Mét tại điểm đầu từng leg (`shape_offset`). */
+    legBegin_m: number[];
+}
+declare function buildRouteIndex(route: Route): RouteIndex;
+/**
+ * Step đang ở tại along_m: step có begin_m ≤ along < end_m. Step dài 0 (arrive tại via) không bao
+ * giờ là "đang ở" trừ step cuối cùng khi along ≥ total.
+ */
+declare function stepAt(index: RouteIndex, along_m: number): number;
+interface ProgressAt {
+    stepIndex: number;
+    legIndex: number;
+    distanceToStep_m: number;
+    remaining_m: number;
+    remaining_s: number;
+}
+declare function progressAt(index: RouteIndex, along_m: number): ProgressAt;
+
+interface SnapResult {
+    /** Đỉnh đầu của đoạn được chọn. */
+    shapeIndex: number;
+    t: number;
+    point: [number, number];
+    /** Khoảng cách vuông góc fix → tuyến (m). */
+    distance_m: number;
+    /** Mét từ đầu tuyến tới điểm chiếu. */
+    along_m: number;
+}
+interface SnapOptions {
+    /** null → tìm trên toàn tuyến (fix đầu sau start/setRoute). */
+    fromShapeIndex: number | null;
+    /** Đoạn có mốc đầu ≤ cum[from] + window_m mới được xét. */
+    window_m: number;
+    heading?: number | null | undefined;
+}
+declare function snapToRoute(index: RouteIndex, p: LngLat, opts: SnapOptions): SnapResult | null;
+
+/** "85 mét", "1,2 ki-lô-mét" (viết đủ để giọng đọc phát âm đúng), "12 ki-lô-mét"; en tương ứng. */
+declare function formatDistance(m: number, lang?: DirectionsLang): string;
+/** Bản ngắn cho UI: "85 m", "1,2 km", "12 km". */
+declare function formatDistanceShort(m: number): string;
+/** ≥ 200 m làm tròn 50; dưới 200 m làm tròn 10; tối thiểu 10. */
+declare function roundForSpeech(m: number): number;
+declare function lowerFirst(text: string): string;
+/** "Trong 190 mét nữa, rẽ phải vào Nguyễn Du." — Valhalla 3.8.3 không tự ghép khoảng cách vào alert. */
+declare function composeApproach(distance_m: number, step: RouteStep, lang: DirectionsLang): string | null;
+/**
+ * Lịch đọc spec B mục 4.5. `announced` giữ khoá `${stepIndex}:${kind}` đã đọc (navigator xoá khi đổi
+ * tuyến). `stepChanged` = fix này vừa đổi step (hoặc là fix đầu).
+ */
+declare function planAnnouncements(p: NavigationProgress, th: NavigationThresholds, lang: DirectionsLang, announced: Set<string>, stepChanged: boolean): Announcement[];
+
+interface SimulateOptions {
+    /** Mặc định theo mode: walk 1.4, motorbike 8, car 12. */
+    speed_mps?: number;
+    /** Mặc định 1. */
+    interval_s?: number;
+    /** Mặc định 8. */
+    accuracy_m?: number;
+    /** Nhiễu vị trí đều trong hình tròn bán kính này; mặc định 0. */
+    jitter_m?: number;
+    /** Mặc định 1. */
+    seed?: number;
+    /** Mặc định 1_700_000_000_000. */
+    start_ms?: number;
+}
+declare const SIMULATE_DEFAULT_SPEED_MPS: Readonly<Record<TravelMode, number>>;
+/** PRNG xác định (mulberry32) để test và demo lặp lại được. */
+declare function mulberry32(seed: number): () => number;
+/** Đi dọc polyline với vận tốc hằng; heading = hướng đoạn; thuần và xác định. */
+declare function simulateFixes(route: Route, opts?: SimulateOptions): GeoFix[];
+
+/** Máy trạng thái dẫn đường thuần (spec B mục 4.4–4.5): không DOM, không timer, thời gian từ fix. */
+declare function createNavigator(opts: NavigatorOptions): Navigator;
+
+/** Vai của từng feature trong source tuyến — web và RN cùng lọc theo `properties.kind`. */
+type RouteFeatureKind = 'alt' | 'active' | 'traveled' | 'puck';
+interface RouteLineFeature {
+    type: 'Feature';
+    geometry: {
+        type: 'LineString';
+        coordinates: [number, number][];
+    };
+    properties: {
+        kind: 'alt' | 'active' | 'traveled';
+        index: number;
+    };
+}
+interface RoutePuckFeature {
+    type: 'Feature';
+    geometry: {
+        type: 'Point';
+        coordinates: [number, number];
+    };
+    properties: {
+        kind: 'puck';
+        bearing: number;
+    };
+}
+type RouteFeature = RouteLineFeature | RoutePuckFeature;
+interface RouteFeatureCollection {
+    type: 'FeatureCollection';
+    features: RouteFeature[];
+}
+/** Điểm cắt tuyến chính: trước là đã đi, sau là còn lại. */
+interface RouteProgressCut {
+    shapeIndex: number;
+    snapped: [number, number];
+    /** Hướng đi (độ) cho puck; thiếu → 0. */
+    bearing?: number;
+}
+interface RouteFeaturesOptions {
+    active: number;
+    progress?: RouteProgressCut | null;
+    /** Thêm feature Point `puck` tại `snapped` khi có `progress`. Mặc định false. */
+    puck?: boolean;
+}
+declare const EMPTY_ROUTE_FEATURES: RouteFeatureCollection;
+/** Giải mã polyline6 của mọi tuyến trong response — làm một lần rồi cache ở lớp dán. */
+declare function decodeRoutes(response: DirectionsResponse): [number, number][][];
+/**
+ * Dựng FeatureCollection cho source tuyến: tuyến khác `active` là `alt`; tuyến `active` bị cắt tại
+ * `progress` thành `traveled` + `active` (cả hai đi qua điểm bám); không có `progress` thì nguyên
+ * tuyến là `active`. `puck` thêm một Point tại điểm bám mang `bearing`. Không đột biến `coords`.
+ */
+declare function routeFeatures(coords: readonly (readonly [number, number][])[], opts: RouteFeaturesOptions): RouteFeatureCollection;
+
+export { ATTRIBUTION_LINKS, type AdminAliasKeyInput, type AlleyKeyword, type Announcement, type AttributionLink, type AttributionResponse, type AutocompleteItem, type AutocompleteType, type ClientOptions, DEFAULT_POI_SOURCES, type DirectionsLang, type DirectionsOptions, type DirectionsResponse, EMPTY_ROUTE_FEATURES, type EditChanges, type EditKind, FIRST_SYMBOL_LAYER_ID, type FlatStep, type GeoFix, type GeocodeItem, type GeocodeMatched, type GeocodePrecision, type Lang, type LngLat, MANEUVER_KINDS, type ManeuverKind, type MapsLibVNClient, MapsLibVNError, NAME_FILLERS, NAVIGATION_THRESHOLDS, type NavigationEvents, type NavigationProgress, type NavigationStatus, type NavigationThresholds, type Navigator, type NavigatorOptions, POI_LAYER_ID, POI_SOURCES, POI_SOURCE_PROFILES, type ParsedAddress, type Place, type PlaceAddress, type PlaceCategory, type PlaceDetails, type PlaceSource, type PoiFeature, type PoiSource, type PoiSourceProfile, type PositionError, type PositionSource, type ProgressAt, type Projection, type ReverseAddress, type ReverseResponse, type Route, type RouteFeature, type RouteFeatureCollection, type RouteFeatureKind, type RouteFeaturesOptions, type RouteIndex, type RouteLeg, type RouteLineFeature, type RouteProgressCut, type RouteProvider, type RoutePuckFeature, type RouteStep, SIMULATE_DEFAULT_SPEED_MPS, type SearchKeys, type SimulateOptions, type SnapOptions, type SnapResult, type StyleLayerLike, type StyleLike, type SuggestEditRequest, type SuggestEditResponse, TOPONYM_ALIAS, type Theme, type ToponymEntry, type TravelMode, VALHALLA_MANEUVER_KIND, type Waypoint, adminAliasKeys, angleDiffDeg, applyBrandAlias, applyToponymAlias, attributionHtml, attributionText, bearingDeg, buildRouteIndex, composeApproach, createClient, createNavigator, cumulativeDistances, decodePolyline6, decodeRoutes, encodePolyline6, expandAbbrev, filterNameAlt, foldTelex, formatDistance, formatDistanceShort, haversineM, hidePoiLayer, isNameLabelLayer, isPoiStyleLayer, localizeStyle, looksLikeTelex, lowerFirst, maneuverKindFromValhalla, mulberry32, nameCore, nameExpression, normalizePoiSources, normalizeVi, parseAddress, parsePoiSourcesCsv, planAnnouncements, poiSourceClause, poiSourcesKey, profileForSources, progressAt, projectOnSegment, roundForSpeech, routeFeatures, searchKeys, simulateFixes, snapToRoute, stepAt, stripDiacritics, viKey };