mahal_map 1.7.2 → 2.0.0

package/README.md

@@ -7,15 +7,52 @@ Mahal Map - JavaScript/TypeScript SDK для работы с картой Mahal
 ## Установка
 
 ```sh
-npm install mahal_map maplibre-gl
+npm install mahal_map maplibre-gl @grammaps/maps3d-web
 ```
 
-`maplibre-gl` является peer dependency. Его нужно установить в приложении или подключить отдельным browser script перед SDK.
+Обе зависимости — `peerDependencies`, в бандл `mahal_map` они не входят. Библиотека их не импортирует: MapLibre и `Maps3D` приходят снаружи, аргументами `create()` либо через `window`.
 
-`@grammaps/maps3d-web` объявлен peer dependency пакета (в `package.json` помечен как `optional` — без него `engine: "legacy"` работает как обычно). Для `engine: "3d"` он обязателен в рантайме: установите его явно.
+- `maplibre-gl` (3–6) — обязателен всегда.
+- `@grammaps/maps3d-web` (>=0.5.0) — даёт стили, тайлы, объём, пробки, рельеф, планы этажей, клик по объектам. Помечен `optional`: без него карта поднимется на запасном векторном стиле, но 3D и слоёв платформы на ней не будет.
 
-```sh
-npm i mahal_map maplibre-gl @grammaps/maps3d-web
+MapLibre можно не класть в свою сборку вовсе — платформа отдаёт согласованную версию вместе с веб-воркером:
+
+```ts
+const maplibregl = await Maps3D.maplibre({ base: "https://navi.gram.tj" });
+```
+
+## Миграция с 1.x на 2.0
+
+Собственных URL стилей у `mahal_map` больше нет — их целиком отдаёт `@grammaps/maps3d-web`.
+
+| 1.x                                            | 2.0                                                            |
+| ---------------------------------------------- | -------------------------------------------------------------- |
+| `engine: "legacy"` (по умолчанию)              | Удалён. Единственный путь — платформа через `Maps3D`.           |
+| `engine: "3d"`                                 | Больше не нужен, опция игнорируется.                            |
+| `autoAddVectorSource: true`                    | Удалён. Тот же векторный стиль применяется сам, когда нет `Maps3D`. |
+| `preset: "standard-night"`                     | `theme: "dark"`, либо полный URL в `style`.                     |
+| `preset: "road-urban-lab-v2"`                  | `theme: "light"`, либо полный URL в `style`.                    |
+| `lang` менял URL стиля                          | Стиль не трогает — язык подписей приходит из самого стиля.      |
+| `layer.setBuildingsEnabled(...)` напрямую      | `map.toggle3DBuildings(...)` или `map.setLayer("buildings", ...)`. |
+
+`engine` и `autoAddVectorSource` оставлены в типах как `@deprecated`, чтобы не ломать компиляцию, но на поведение не влияют.
+
+Что появилось: реестр слоёв (`setLayer`/`getLayers`/`onLayers`), выделение зданий, клик по дорогам, рельеф, планы этажей, перекрытия, семейства стилей `navigator`/`mobile` и автоматический `antialias`.
+
+Минимальный диф:
+
+```diff
+ const map = MahalMap.create(
+   {
+     container: "map",
+-    engine: "3d",
+     theme: "dark",
+-    preset: "standard-night",
+     enable3D: true,
+   },
+   maplibregl,
+   Maps3D,
+ );
 ```
 
 ## Быстрый старт через NPM
@@ -23,6 +60,7 @@ npm i mahal_map maplibre-gl @grammaps/maps3d-web
 ```ts
 import maplibregl from "maplibre-gl";
 import "maplibre-gl/dist/maplibre-gl.css";
+import { Maps3D } from "@grammaps/maps3d-web";
 import { MahalMap, keyUtils } from "mahal_map";
 
 keyUtils.saveKey("YOUR_MAP_API_KEY");
@@ -30,11 +68,12 @@ keyUtils.saveKey("YOUR_MAP_API_KEY");
 const map = MahalMap.create(
   {
     container: "map",
-    center: [69.624024, 40.279687],
-    zoom: 12,
+    center: [68.787, 38.573],
+    zoom: 16.6,
     theme: "light",
   },
   maplibregl,
+  Maps3D,
 );
 ```
 
@@ -44,6 +83,8 @@ const map = MahalMap.create(
 <div id="map" style="width: 100%; height: 500px"></div>
 ```
 
+`Maps3D` — третий, необязательный аргумент: не передан — SDK возьмёт его из `window.Maps3D`. Стиль, `transformRequest` с ключом, сглаживание и подключение 3D библиотека делает сама.
+
 ## Быстрый старт через Browser SDK
 
 Сначала подключите MapLibre, затем `mahal_map.sdk.js`. Для browser SDK параметр `apikey` обязателен: без него карта не инициализируется.
@@ -99,7 +140,7 @@ const map = MahalMap.create(
 `maps3dCtor` — импортированный конструктор `Maps3D` (третий, необязательный аргумент). Если не передан, SDK ищет его в `window.Maps3D`.
 
 ```ts
-import type { IMaps3DLayerOptions } from "mahal_map";
+import type { IMaps3DLayerOptions, Maps3DThemeName } from "mahal_map";
 
 interface IMahalMapOptions {
   container?: string | HTMLElement;
@@ -110,111 +151,130 @@ interface IMahalMapOptions {
   zoom?: number;
   pitch?: number;
   bearing?: number;
-  autoAddVectorSource?: boolean;
-  engine?: "legacy" | "3d";
   enable3D?: boolean;
   base?: string;
-  preset?: string;
-  maps3d?: Omit<IMaps3DLayerOptions, "apiKey" | "base" | "buildings">;
+  family?: "default" | "navigator" | "mobile";
+  preset?: Maps3DThemeName | string;
+  antialias?: boolean;
+  maps3d?: Omit<IMaps3DLayerOptions, "apiKey" | "base">;
 }
 ```
 
-| Параметр              | Тип                     | Описание                                                                                                                                                              |
-| --------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `container`           | `string \| HTMLElement` | ID контейнера или DOM-элемент. Если не передан, используется `"map"`.                                                                                                 |
-| `style`               | `string`                | Пользовательский URL стиля MapLibre. Если передан, `theme`, `lang` и map token не меняют URL стиля.                                                                   |
-| `theme`               | `"dark" \| "light"`     | Тема стандартного стиля. По умолчанию используется `light`.                                                                                                           |
-| `lang`                | `"tj" \| "ru"`          | Язык стандартного стиля. `tj` оставляет URL только с `token`, `ru` добавляет `lang=ru`.                                                                               |
-| `center`              | `[number, number]`      | Центр карты в формате `[lng, lat]`.                                                                                                                                   |
-| `zoom`                | `number`                | Начальный zoom.                                                                                                                                                       |
-| `pitch`               | `number`                | Начальный наклон камеры (нужен для 3D-вида). Если не задан и `enable3D` включен — авто `58` (при `pitch: 0` экструзия зданий не видна, камера смотрит строго сверху). |
-| `bearing`             | `number`                | Начальный поворот камеры.                                                                                                                                             |
-| `autoAddVectorSource` | `boolean`               | Использует встроенный vector style и блокирует смену стандартного стиля через `setStyle`.                                                                             |
-| `engine`              | `"legacy" \| "3d"`      | Переключатель движка карты. `"legacy"` (по умолчанию) — старые стили mtile.gram.tj. `"3d"` — новая платформа GramMaps (navi.gram.tj) с пресетами стиля и Maps3D.      |
-| `enable3D`            | `boolean`               | Подключает детальные 3D-здания (Maps3D). Работает только при `engine: "3d"`. По умолчанию `true` для `engine: "3d"` — передайте `false`, чтобы отключить.             |
-| `base`                | `string`                | Домен платформы GramMaps для `engine: "3d"`. По умолчанию `https://navi.gram.tj`.                                                                                     |
-| `preset`              | `string`                | Имя пресета стиля GramMaps (напр. `"standard-night"`) для `engine: "3d"`. По умолчанию `road-urban-lab-v2`/`standard-night` в зависимости от `theme`.                 |
-| `maps3d`              | `object`                | Доп. опции Maps3D слоя: `traffic`, `minZoom`, `lodBias`, `memoryBudget`, `maskReplaced`, `typeReplacements`.                                                          |
-
-### Новый 3D-движок (GramMaps / Maps3D)
-
-Токен передается как обычно, через `keyUtils.saveKey()` — отдельно ключ для Maps3D передавать не нужно.
+| Параметр    | Тип                                   | Описание                                                                                                                                                  |
+| ----------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `container` | `string \| HTMLElement`               | ID контейнера или DOM-элемент. Не передан — берётся `"map"`.                                                                                              |
+| `style`     | `string`                              | Полный URL своего стиля. Задан — стиль зафиксирован, `setStyle()` его не меняет.                                                                          |
+| `theme`     | `"dark" \| "light"`                   | Светлая/тёмная внутри выбранного `family`. По умолчанию `light`.                                                                                          |
+| `lang`      | `"tj" \| "ru"`                        | Язык для поиска и роутинга. На стиль не влияет — подписи приходят из самого стиля платформы.                                                              |
+| `center`    | `[number, number]`                    | Центр карты в формате `[lng, lat]`.                                                                                                                       |
+| `zoom`      | `number`                              | Начальный zoom.                                                                                                                                           |
+| `pitch`     | `number`                              | Начальный наклон камеры. Не задан и 3D включено — авто `58`: при `pitch: 0` объём зданий не виден, камера смотрит строго сверху.                          |
+| `bearing`   | `number`                              | Начальный поворот камеры.                                                                                                                                 |
+| `enable3D`  | `boolean`                             | Подключает Maps3D. По умолчанию `true`, когда `Maps3D` доступен.                                                                                          |
+| `base`      | `string`                              | Домен платформы. По умолчанию `https://navi.gram.tj`.                                                                                                     |
+| `family`    | `"default" \| "navigator" \| "mobile"` | Семейство стилей. `theme` выбирает внутри него: `default` → `light`/`dark`, `navigator` → `navigator-light`/`navigator-dark`, `mobile` → `mobile-*`.   |
+| `preset`    | `Maps3DThemeName \| string`           | Явное имя темы платформы или полный URL стиля вместо пары `family` + `theme`. Задан — стиль зафиксирован.                                                 |
+| `antialias` | `boolean`                             | Сглаживание сцены. По умолчанию `true` при включённом 3D: без него тонкая геометрия (перила, мачты, ряды сидений) на отдалении рассыпается в рябь.        |
+| `maps3d`    | `object`                              | Опции Maps3D: `buildings`, `traffic`, `indoor`, `closures`, `places`, `minZoom`, `lodBias`, `memoryBudget`, `maskReplaced`, `typeReplacements`.           |
+
+### Стили и темы
+
+Стили целиком приходят из `@grammaps/maps3d-web` — своего списка URL у `mahal_map` больше нет. Словарь тем один и тот же у SDK и у библиотеки:
+
+| `family`      | `theme: "light"`   | `theme: "dark"`   |
+| ------------- | ------------------ | ----------------- |
+| `"default"`   | `light`            | `dark`            |
+| `"navigator"` | `navigator-light`  | `navigator-dark`  |
+| `"mobile"`    | `mobile-light`     | `mobile-dark`     |
+
+Имя темы уходит в `Maps3D.styleUrl()`, адрес строит сам SDK. Неизвестное имя — явная ошибка с префиксом `[MahalMap SDK]`, а не пустая карта.
 
 ```ts
-import maplibregl from "maplibre-gl";
-import "maplibre-gl/dist/maplibre-gl.css";
-import { Maps3D } from "@grammaps/maps3d-web";
-import { MahalMap, keyUtils } from "mahal_map";
-
-keyUtils.saveKey("YOUR_MAP_API_KEY");
+// Навигаторная тёмная тема
+MahalMap.create({ container: "map", family: "navigator", theme: "dark" }, maplibregl, Maps3D);
 
-const map = MahalMap.create(
-  {
-    container: "map",
-    center: [68.78, 38.56],
-    zoom: 16.6,
-    pitch: 58,
-    theme: "dark",
-    engine: "3d",
-    enable3D: true,
-  },
-  maplibregl,
-  Maps3D,
-);
+// Смена темы внутри того же семейства
+map.setStyle("light"); // → navigator-light
 ```
 
-`Maps3D` (третий аргумент `create()`) — опционален: если не передан, SDK попробует взять его из `window.Maps3D`. `@grammaps/maps3d-web` — необязательный peer dependency, ставится только если используется `engine: "3d"`.
+> **Миграция с 1.x.** Имена пресетов прежнего поколения (`road-urban-lab-v2`, `standard-night`) больше не подставляются по умолчанию — словарь тем теперь один, платформенный. Если старый стиль всё ещё нужен, передайте его полным URL:
+>
+> ```ts
+> MahalMap.create(
+>   { container: "map", style: "https://navi.gram.tj/maps/standard-night.json" },
+>   maplibregl,
+>   Maps3D,
+> );
+> ```
 
-Получить слой Maps3D после создания карты:
+### Без `@grammaps/maps3d-web`
 
-```ts
-const layer = map.getMaps3DLayer();
-// или
-MahalMap.getMaps3DLayer(map);
-```
+Библиотека не установлена и в `window.Maps3D` ничего нет — карта всё равно поднимется: используется запасной векторный стиль `mtile.gram.tj` с подписью `?token=`, в консоль уходит предупреждение. На такой карте нет объёма, объектов, пробок, рельефа и реестра слоёв; `setStyle()` и `setLanguage()` стиль не меняют, методы реестра возвращают пустые значения (`false`, `null`, `[]`).
 
-`getMaps3DLayer()` возвращает реальный инстанс `Maps3D` (не обёртку) — типы `mahal_map` описывают всю его публичную поверхность, так что подключающему сервису не нужно ставить или типизировать `@grammaps/maps3d-web` отдельно.
+Этот путь — единственный, где ещё проверяется подписка JSApi: `createAsync()` не создаст карту, если подписки нет. С переданным `Maps3D` проверка пропускается — доступ гейтит сама платформа по `?key=`.
 
 ### Опции `maps3d` (расширенные)
 
-Передаются в `MahalMap.create({ maps3d: {...} })` при `engine: "3d"`:
-
-| Опция              | Тип                                              | По умолч. | Описание                                                                  |
-| ------------------ | ------------------------------------------------ | --------- | ------------------------------------------------------------------------- |
-| `traffic`          | `boolean \| { raster?, rasterMaxZoom?, graph? }` | `false`   | Слой пробок. `raster: true` — картинкой с сервера вместо векторного слоя. |
-| `minZoom`          | `number`                                         | `16`      | Зум появления детальных 3D.                                               |
-| `lodBias`          | `number`                                         | `1`       | `0` — всегда lod0 (детальный), `1` — lod1 на дальних зумах.               |
-| `memoryBudget`     | `number`                                         | `30`      | Сколько моделей держать в сцене одновременно.                             |
-| `maskReplaced`     | `boolean`                                        | `true`    | Прятать заменённые OSM-объекты (`anchor=replace`).                        |
-| `typeReplacements` | `boolean`                                        | `true`    | Рисовать замены по типу (`natural=tree` → 3D-дерево и т.п.).              |
+Передаются в `MahalMap.create({ maps3d: {...} })` и уходят в `Maps3D` как есть:
 
-`buildings: true` включается автоматически при `enable3D: true` — переопределять не нужно, если только не требуется передать сам объект опций.
+| Опция              | Тип                                                   | По умолч. | Описание                                                             |
+| ------------------ | ----------------------------------------------------- | --------- | -------------------------------------------------------------------- |
+| `buildings`        | `boolean \| { detail?: footprint\|volume\|roofs\|facade }` | `true` | Объёмные здания; объектом — их облик.                            |
+| `traffic`          | `boolean \| { raster?, rasterMaxZoom?, graph?, opacity?, arrows? }` | `false` | Слой пробок. `raster: true` — картинкой вместо векторного слоя. |
+| `indoor`           | `boolean \| { level? }`                                | `false`   | Планы этажей.                                                        |
+| `closures`         | `boolean \| object`                                    | `false`   | Перекрытия дорог.                                                    |
+| `places`           | `object`                                               | —         | Парковки, заправки, зарядки: `highlight`, `paid`, `free`, `unknown`. |
+| `minZoom`          | `number`                                               | `16`      | Зум появления объёма.                                                |
+| `lodBias`          | `number`                                               | `1`       | `0` — всегда детальная геометрия, `1` — упрощённая вдали.            |
+| `memoryBudget`     | `number`                                               | `30`      | Сколько 3D-моделей держать в памяти.                                 |
+| `maskReplaced`     | `boolean`                                              | `true`    | Прятать заменённые OSM-объекты (`anchor=replace`).                   |
+| `typeReplacements` | `boolean`                                              | `true`    | Рисовать замены по типу (`natural=tree` → 3D-дерево и т.п.).         |
 
-### 3D-здания
+`apiKey` и `base` в `maps3d` передавать не нужно — их подставляет сам `MahalMap` из сохранённого ключа и `options.base`.
 
-`Maps3D` рисует процедурные 3D-здания (three.js) вместо плоской `fill-extrusion` стиля: фаска кромок, вертикальный градиент и базовый цвет берутся из стиля, окна — из `metadata` пресета. При `engine: "3d"` слой создаётся и `attach`-ится к карте автоматически (`enable3D` по умолчанию `true`) — вручную поднимать `new Maps3D(...)` не нужно, только если требуется отдельный кастомный инстанс.
+### Реестр слоёв
 
-**Ручной `new Maps3D(...)` — отдельный сценарий.** Карту при этом создавайте с `enable3D: false`, иначе на неё повиснут два слоя Maps3D сразу (автоматический от `MahalMap` + ваш ручной) — дублирование зданий и лишний расход ресурсов:
+Единая дверь ко всем слоям платформы. Состояние слоя — три независимых поля: `wanted` (чего хочет приложение), `available` (что позволяют стиль и данные), `active` (что нарисовано сейчас).
 
 ```ts
-const apiKey = "YOUR_MAP_API_KEY";
-const base = "https://navi.gram.tj";
+map.setLayer("terrain", true, { mode: "on" });
+map.setLayer("traffic", true);
+map.setLayer("indoor", true, { level: 2 });
 
-const map = MahalMap.create(
-  { container: "map", engine: "3d", enable3D: false },
-  maplibregl,
-);
+const unsubscribe = map.onLayers((state) => {
+  console.log(state.id, state.wanted, state.available, state.active);
+});
 
-const layer = new Maps3D({ apiKey, base, buildings: true });
-await layer.attach(map.getMap()); // attach ждёт нативную карту MapLibre, не обёртку MahalMap
+map.getLayerState("terrain"); // снимок одного слоя или null
+map.getLayers(); // снимок всех — по нему рисуется панель слоёв
 ```
 
-Тема (окна/свет) приходит из `metadata` пресета стиля и применяется автоматически при `map.setStyle()` — пересоздавать слой не нужно. Ручные сеттеры перебивают её.
+| Слой               | Параметры                                | По умолчанию |
+| ------------------ | ---------------------------------------- | ------------ |
+| `buildings`        | `detail: footprint\|volume\|roofs\|facade` | включён    |
+| `objects`          | —                                        | включён      |
+| `traffic`          | —                                        | выключен     |
+| `trafficRaster`    | —                                        | выключен     |
+| `parking`          | `highlight`, `paid`, `free`, `unknown`   | включён      |
+| `fuel`, `charging` | —                                        | включены     |
+| `closures`         | —                                        | выключен     |
+| `indoor`           | `level`                                  | выключен     |
+| `terrain`          | `mode: auto\|on\|off`                     | `auto`       |
 
-Это работает только для встроенных пресетов **без** явного `options.preset`: `setStyle()` меняет пресет по теме (`light`/`dark` → `GRAM_PRESETS`), а при заданном `preset` считает стиль зафиксированным и ничего не делает (см. [`MahalMap.ts`](src/core/MahalMap.ts:363)). Чтобы сменить пресет/тему в этом случае — пересоздайте карту с другим `preset` или вызовите `map.getMap().setStyle(...)` напрямую.
+Слой может быть включён и при этом не нарисован: рельеф в режиме `auto` появляется на обзорных зумах, перекрытия требуют своего тайлсета, планы этажей — данных по зданию. Рельеф в режиме `on` заметно дороже по трафику и времени кадра.
+
+Парковки, заправки и зарядки `Maps3D` рисует сам, забирая эти классы у POI-слоёв стиля, — поэтому выключение слоя убирает объекты с карты полностью, а не оставляет значок стиля.
+
+`setLayer()` возвращает `false`, если такого слоя в подключённой сборке Maps3D нет (или Maps3D не передан вовсе). После полной смены стиля волю клиента возвращает `map.refreshLayers()` — при `setStyle()` библиотека вызывает его сама.
+
+### 3D-здания
+
+`Maps3D` рисует процедурные 3D-здания (three.js) вместо плоской `fill-extrusion` стиля: фаска кромок, вертикальный градиент и базовый цвет берутся из стиля, окна — из `metadata` темы. Слой создаётся и подключается автоматически (`enable3D` по умолчанию `true`) — вручную поднимать `new Maps3D(...)` не нужно.
+
+Тонкая настройка облика — через сам слой, после готовности:
 
 ```ts
-const layer = map.getMaps3DLayer();
+const layer = await map.whenMaps3DReady();
 
 const b = layer?.buildings;
 b?.setWindowStyle(7); // тип окна 0..9 (сетка, лента, curtain wall, ...)
@@ -227,16 +287,59 @@ b?.setSunIntensity(3.2);
 b?.setAmbient(0.76);
 b?.setSky(0.91);
 b?.setExposure(1.5);
+```
+
+Тема (окна/свет) приходит из `metadata` стиля и применяется автоматически при смене стиля — пересоздавать слой не нужно. Ручные сеттеры её перебивают.
+
+**Ручной `Maps3D.enhance(...)` — отдельный сценарий.** Карту при этом создавайте с `enable3D: false`: второй экземпляр на занятой карте `Maps3D` отклоняет.
+
+```ts
+const map = MahalMap.create(
+  { container: "map", enable3D: false },
+  maplibregl,
+  Maps3D,
+);
+
+const maps3d = Maps3D.enhance(map.getMap(), {
+  apiKey: "YOUR_MAP_API_KEY",
+  base: "https://navi.gram.tj",
+});
+await maps3d.ready; // enhance() ждёт нативную карту MapLibre, не обёртку MahalMap
+```
 
-layer?.onBuildingClick((info) => {
-  if (!info) return;
-  console.log(info.id, info.height, info.props);
+### Выделение зданий и клик по дорогам
+
+Клик по зданию и клик по дороге приходят независимо: одна точка может попасть и туда, и туда — что важнее, решает приложение.
+
+```ts
+map.setSelectionStyle({ color: "#e23b2f", opacity: 0.55, durationMs: 300 });
+
+map.onBuildingClick((building) => {
+  if (!building) return;
+  // SDK уже подсветил его
+  console.log(building.props?.osm_id, building.height);
+});
+
+map.onRoadClick((road) => {
+  if (!road) return;
+  console.log(road.nameRu ?? road.name, road.class);
 });
+
+// Выделить здание по osm_id — например, после поиска
+map.selectBuilding(123456789); // false, если здания нет в загруженных данных
+map.selectedBuilding(); // текущий id или null
+map.clearSelection();
+
+// Дорога под точкой холста, допуск по умолчанию 12 px
+map.roadAt({ x: 320, y: 240 });
+map.roadsNamed; // есть ли в текущем стиле названия дорог
 ```
 
+Подписываться можно сразу после `create()`, до готовности карты.
+
 #### Вкл/выкл 3D-здания на лету
 
-Переключение 3D-здания ⇄ штатные здания стиля, без пересоздания карты — через обёртку `MahalMap`. Она же умеет пересоздать слой, если его не было (`enable3D: false` при создании):
+Переключение объём ⇄ штатные здания стиля, без пересоздания карты. Умеет поднять слой, если его не было (`enable3D: false` при создании):
 
 ```ts
 const map = MahalMap.getInstance("map");
@@ -248,11 +351,11 @@ map.toggle3DBuildings(true); // вкл обратно
 MahalMap.toggle3DBuildings(map, false);
 ```
 
-`layer?.setBuildingsEnabled(false)` напрямую через слой **не используйте** — он не знает про штатный слой стиля `building-3d`, который `MahalMap` прячет при включённом 3D. Вызов только слоя оставит эти штатные здания скрытыми и одновременно выключит процедурные — в итоге зданий не будет видно вообще, до следующей перезагрузки стиля.
+Под капотом это `setLayer("buildings", enabled)`. Штатные здания стиля прячет и возвращает сам `Maps3D` — `mahal_map` их видимость не трогает, поэтому спорить за один слой некому. Эквивалентная запись: `map.setLayer("buildings", false)`.
 
 #### `map.whenMaps3DReady()`
 
-`attach()` слоя асинхронный: сразу после `create()` слой уже есть, но `layer.buildings` (окна, свет, кромки) появляется только после attach. Чтобы не гадать — дождитесь готовности:
+Подключение слоя асинхронное: сразу после `create()` слой уже есть, но `layer.buildings` (окна, свет, кромки) появляется только после него. Чтобы не гадать — дождитесь готовности:
 
 ```ts
 const layer = await map.whenMaps3DReady();
@@ -260,7 +363,7 @@ const layer = await map.whenMaps3DReady();
 layer?.buildings?.setWindowStyle(4);
 ```
 
-Промис резолвится в `undefined`, если движок не `"3d"`, слой выключен (`enable3D: false`) или attach упал — ошибка при этом уходит в `console.error`, а карта остаётся живой со штатными зданиями стиля.
+Промис резолвится в `undefined`, если `Maps3D` не передан, слой выключен (`enable3D: false`) или подключение упало — ошибка при этом уходит в `console.error`, а карта остаётся живой на штатных зданиях стиля.
 
 ### Подключение и выключение 3D-слоя: полный пример (Vue 3)
 
@@ -300,13 +403,12 @@ onMounted(async () => {
   const map = MahalMap.create(
     {
       container: "map",
-      engine: "3d", // платформа GramMaps вместо legacy-стилей
-      theme: "dark", // preset standard-night; "light" → road-urban-lab-v2
+      theme: "dark", // тема dark; "light" → тема light
       center: [68.787, 38.573],
       zoom: 16.6,
-      pitch: 58, // без наклона экструзия не видна
+      pitch: 58, // без наклона объём не виден
       bearing: -20,
-      enable3D: true, // значение по умолчанию для engine: "3d"
+      enable3D: true, // значение по умолчанию, когда Maps3D передан
       maps3d: { minZoom: 16, lodBias: 0 },
     },
     maplibregl,
@@ -378,14 +480,15 @@ onBeforeUnmount(() => {
 
 Что библиотека делает за вас против ручного подключения `@grammaps/maps3d-web`:
 
-| Ручной код                                      | Через `mahal_map`                                                 |
-| ----------------------------------------------- | ----------------------------------------------------------------- |
-| `style: base + "/maps/standard-night.json"`     | `engine: "3d"` + `theme` (или `preset` / `base` явно)             |
-| `transformRequest: Maps3D.transformRequest(..)` | ставится автоматически (и без Maps3D — своим фолбэком с `?key=`)  |
-| `new Maps3D({...}); await layer.attach(map)`    | `enable3D: true` + `maps3d: {...}`, `await map.whenMaps3DReady()` |
-| `setBuildingsEnabled` + `buildings.setWindows`  | `map.toggle3DBuildings(enabled)` — оба вызова разом               |
-| Плоские здания стиля поверх 3D после `setStyle` | скрываются сами на каждой загрузке стиля                          |
-| `layer.destroy(); map.remove()`                 | `map.destroy()`                                                    |
+| Ручной код                                          | Через `mahal_map`                                              |
+| --------------------------------------------------- | -------------------------------------------------------------- |
+| `...Maps3D.mapOptions({ base, apiKey, style })`      | `theme` + `family` (или `preset` / `style` / `base` явно)      |
+| `antialias: true` не забыть                          | ставится сам при включённом 3D                                 |
+| `Maps3D.enhance(map, opts); await maps3d.ready`      | `enable3D: true` + `maps3d: {...}`, `await map.whenMaps3DReady()` |
+| `map.setStyle(Maps3D.styleUrl("dark", base))`        | `map.setStyle("dark")` — внутри выбранного семейства            |
+| `maps3d.refreshLayers()` после смены стиля           | вызывается сам на `style.load`                                  |
+| `maps3d.destroy(); map.remove()`                     | `map.destroy()`                                                 |
+| ключ руками в каждый вызов                           | один `keyUtils.saveKey()` на всё                                |
 
 #### То же самое без сборщика (browser SDK)
 
@@ -401,7 +504,6 @@ onBeforeUnmount(() => {
   // Maps3D берётся из window.Maps3D — третий аргумент передавать не нужно.
   const map = MahalMap.create({
     container: "map",
-    engine: "3d",
     theme: "dark",
     center: [68.787, 38.573],
     zoom: 16.6,
@@ -426,30 +528,39 @@ onBeforeUnmount(() => {
 
 ### Пробки
 
+Через реестр слоёв:
+
 ```ts
-const layer = map.getMaps3DLayer();
+map.setLayer("traffic", true);
+map.setLayer("trafficRaster", true); // растровый вариант, без клика по дороге
+```
+
+Тонкие настройки — через сам слой:
 
-layer?.setTraffic(true);
-layer?.setTrafficOpacity(0.85);
-layer?.setTrafficClicks(true); // попап скорости по клику
-layer?.refreshTraffic();
+```ts
+const layer = map.getMaps3DLayer();
 
-// растровый вариант (картинка с сервера, без клика по дороге)
-layer?.setTrafficRaster(true);
+layer?.setTrafficOpacity?.(0.85);
+layer?.setTrafficClicks?.(true); // попап скорости по клику
+layer?.setTrafficGraph?.("yandex"); // osm | yandex | gis2 | mahal
+layer?.refreshTraffic?.();
 ```
 
+Либо сразу при создании карты: `maps3d: { traffic: { raster: true, opacity: 0.85 } }`.
+
 ### Жизненный цикл слоя
 
 ```ts
 const layer = map.getMaps3DLayer();
 
-layer?.setMinZoom(15);
-layer?.setObjectsLight({ sun: 1.8, ambient: 0.45, sky: 1.1, exposure: 1.15 });
-await layer?.refresh(); // перечитать модели после правок
-await layer?.clearCache(); // сбросить IndexedDB-кеш ассетов
+layer?.setMinZoom?.(15);
+layer?.setObjectsLight?.({ sun: 1.8, ambient: 0.45, sky: 1.1, exposure: 1.15 });
+await layer?.refresh?.(); // перечитать объекты в кадре
+await layer?.clearCache?.(); // сбросить IndexedDB-кеш моделей
+layer?.diagnostics?.(); // рельеф, потеря контекста WebGL, счётчики зданий
 ```
 
-Для полной остановки карты используйте только `map.destroy()` / `MahalMap.destroy(map)` — они сами вызывают `destroy()`/`remove()` у Maps3D слоя. **Не вызывайте `layer.destroy()`/`layer.remove()` напрямую**: `MahalMap` не узнает об этом и продолжит считать слой активным (внутренний `maps3dLayer`, `buildingsEnabled`, видимость штатных зданий стиля разойдутся с реальностью). Нужно временно выключить только 3D-здания — используйте `map.toggle3DBuildings(false)` (см. выше).
+Для полной остановки карты используйте только `map.destroy()` / `MahalMap.destroy(map)` — они сами вызывают `destroy()`/`remove()` у Maps3D слоя. **Не вызывайте `layer.destroy()`/`layer.remove()` напрямую**: `MahalMap` не узнает об этом и продолжит считать слой активным (внутренний `maps3dLayer` и `buildingsEnabled` разойдутся с реальностью). Нужно временно выключить только 3D-здания — используйте `map.toggle3DBuildings(false)` (см. выше).
 
 ## MahalMap
 
@@ -474,6 +585,114 @@ const map = MahalMap.create(
 
 В NPM-версии второй аргумент `maplibreObject` рекомендуется передавать явно. В browser SDK он берется из `window.maplibregl`.
 
+### `MahalMap.createAsync(options, maplibreObject?, maps3dCtor?)`
+
+Асинхронный вариант `create()`. Перед созданием карты проверяет подписку JSApi по map token и, если подписки нет, карту не создаёт вообще: MapLibre-инстанс не строится, промис отклоняется с ошибкой.
+
+```ts
+try {
+  const map = await MahalMap.createAsync(
+    {
+      container: "map",
+      center: [69.624024, 40.279687],
+      zoom: 12,
+      theme: "light",
+    },
+    maplibregl,
+  );
+} catch (error) {
+  // подписки нет — показать своё сообщение вместо карты
+  console.error(error);
+}
+```
+
+Правила проверки:
+
+| Условие | Поведение |
+| ------- | --------- |
+| `Maps3D` не передан, сервис ответил `success: true` | Карта создаётся на запасном стиле. |
+| `Maps3D` не передан, сервис ответил `success: false` | Карта **не** создаётся, промис отклоняется: `[MahalMap SDK] JSApi subscription is not active for this key: <message>`. |
+| `Maps3D` не передан, проверка не дошла (сеть, CORS, таймаут) | Fail-open: `console.warn` и карта создаётся. Падение сервиса проверки не гасит карты. |
+| `Maps3D` передан | Проверка **пропускается**, запрос не отправляется. |
+| Map token не сохранён | Проверка пропускается, дальше срабатывает обычная ошибка про `apikey`. |
+
+С переданным `Maps3D` вызов `createAsync()` ведёт себя ровно как `create()` — доступ к платформе контролируется параметром `?key=` на её стороне, отдельная подписка JSApi к ней отношения не имеет.
+
+Синхронный `MahalMap.create()` проверку не выполняет и работает как раньше.
+
+### Vue / Nuxt (ClientOnly, container как ref элемента)
+
+`container` принимает и `id` строкой, и сам DOM-элемент. Ниже рабочий вариант с проверкой подписки: карта строится только после `createAsync()`, поэтому при отсутствии подписки в контейнере не останется пустой карты.
+
+```vue
+<template>
+  <ClientOnly>
+    <div class="overflow-hidden rounded-2xl border">
+      <div ref="mapElement" class="h-[360px] w-full" />
+    </div>
+    <template #fallback>
+      <div class="flex h-[360px] items-center justify-center">{{ loadingLabel }}</div>
+    </template>
+  </ClientOnly>
+</template>
+
+<script setup lang="ts">
+import maplibregl from "maplibre-gl";
+import "maplibre-gl/dist/maplibre-gl.css";
+import type { MahalMap as MahalMapInstance } from "mahal_map";
+import { onBeforeUnmount, onMounted, ref } from "vue";
+
+const DUSHANBE_CENTER: [number, number] = [68.759965, 38.572419];
+
+const mapElement = ref<HTMLElement | null>(null);
+let map: MahalMapInstance | null = null;
+// onMounted асинхронный: компонент может размонтироваться, пока идёт проверка подписки.
+// Без флага карта создастся уже после unmount и останется висеть в памяти.
+let disposed = false;
+
+onMounted(async () => {
+  const { MahalMap, keyUtils } = await import("mahal_map");
+
+  keyUtils.saveKey(import.meta.env.VITE_MAHAL_API_KEY_TILE);
+
+  try {
+    const instance = await MahalMap.createAsync(
+      {
+        container: mapElement.value,
+        center: DUSHANBE_CENTER,
+        zoom: 11,
+      },
+      maplibregl,
+    );
+
+    if (disposed) {
+      instance.destroy();
+      return;
+    }
+
+    map = instance;
+  } catch (error) {
+    // подписки JSApi нет — показать своё сообщение вместо карты
+    console.error(error);
+  }
+});
+
+onBeforeUnmount(() => {
+  disposed = true;
+  map?.destroy();
+  map = null;
+});
+</script>
+```
+
+Замечания по этому паттерну:
+
+- Импорт `mahal_map` внутри `onMounted` обязателен в SSR-окружении: пакет работает с `window`/`document`.
+- `ClientOnly` (Nuxt) или эквивалент нужен по той же причине.
+- Для карты с `container` в виде элемента инстанс регистрируется под ключом по умолчанию `"map"`. Для нескольких карт на странице передавайте `container` строкой с разными `id`, иначе `getInstance()` вернёт не тот инстанс.
+- `map.destroy()` снимает карту, логотип и запись из реестра инстансов.
+- Синхронный `MahalMap.create()` в этом же коде работает без изменений — если проверка подписки не нужна, замените `await MahalMap.createAsync(...)` на `MahalMap.create(...)`.
+
 ### `MahalMap.onReady(container, callback)`
 
 Вызывает `callback`, когда карта создана и MapLibre завершил загрузку.
@@ -557,27 +776,27 @@ camera.flyTo({
 
 ### `map.setStyle(theme)`
 
-Переключает стандартную тему карты.
+Переключает светлую/тёмную тему внутри выбранного `family`.
 
 ```ts
-map.setStyle("dark");
-map.setStyle("light");
+map.setStyle("dark"); // family: "navigator" → navigator-dark
+map.setStyle("light"); // → navigator-light
 ```
 
-Если текущий язык `ru`, при переключении темы стиль будет загружен с `token=...&lang=ru`. Если язык `tj`, URL будет только с `token=...`.
+Адрес стиля строит `Maps3D.styleUrl()`. После загрузки нового стиля библиотека сама зовёт `refreshLayers()` — состояние слоёв переживает смену темы.
 
-Метод не меняет стиль, если карта создана с `autoAddVectorSource: true`. Если карта создана с пользовательским `style`, SDK не переписывает этот URL.
+Метод ничего не делает, если карта создана с явным `style` или `preset` (стиль зафиксирован), либо если `Maps3D` не передан — у запасного стиля вариантов по теме нет.
 
 ### `map.setLanguage(lang)`
 
-Переключает язык стандартного стиля карты.
+Запоминает язык для поиска и роутинга.
 
 ```ts
 map.setLanguage("ru");
 map.setLanguage("tj");
 ```
 
-`ru` добавляет `lang=ru`, `tj` возвращает стандартный URL только с `token=...`. Метод не переписывает пользовательский `options.style` и не меняет vector style при `autoAddVectorSource: true`.
+Стиль метод не трогает: подписи приходят из самого стиля платформы, отдельных URL по языкам больше нет.
 
 ### `map.setCenter(center)`
 
@@ -657,6 +876,23 @@ MahalMap.addMarker(map, marker);
 MahalMap.getMaps3DLayer(map);
 MahalMap.whenMaps3DReady(map);
 MahalMap.toggle3DBuildings(map, false);
+
+// Реестр слоёв
+MahalMap.setLayer(map, "terrain", true, { mode: "on" });
+MahalMap.getLayerState(map, "terrain");
+MahalMap.getLayers(map);
+MahalMap.onLayers(map, (state) => console.log(state.id, state.active));
+MahalMap.refreshLayers(map);
+
+// Выделение зданий и клики
+MahalMap.onBuildingClick(map, (building) => console.log(building?.id));
+MahalMap.selectBuilding(map, 123456789);
+MahalMap.selectedBuilding(map);
+MahalMap.setSelectionStyle(map, { color: "#e23b2f" });
+MahalMap.clearSelection(map);
+MahalMap.onRoadClick(map, (road) => console.log(road?.name));
+MahalMap.roadAt(map, { x: 320, y: 240 });
+
 MahalMap.destroy(map);
 ```
 
@@ -683,6 +919,7 @@ MahalMap.setZoom(map, 14);
 | Функция                                | Описание                                                      |
 | -------------------------------------- | ------------------------------------------------------------- |
 | `create(options)`                      | Создает карту. Требует `apikey` в URL SDK скрипта.            |
+| `createAsync(options)`                 | Создает карту после проверки подписки JSApi (только без Maps3D). |
 | `onReady(container, callback)`         | Выполняет callback после загрузки карты.                      |
 | `getInstance(container)`               | Возвращает инстанс карты.                                     |
 | `hasInstance(container)`               | Проверяет наличие инстанса.                                   |
@@ -694,9 +931,21 @@ MahalMap.setZoom(map, 14);
 | `setCenter(instance, center)`          | Меняет центр карты.                                           |
 | `setZoom(instance, zoom)`              | Меняет zoom карты.                                            |
 | `addMarker(instance, marker)`          | Добавляет маркер.                                             |
-| `getMaps3DLayer(instance)`             | Возвращает инстанс слоя Maps3D (только `engine: "3d"`).       |
+| `getMaps3DLayer(instance)`             | Возвращает инстанс слоя Maps3D (`undefined`, если Maps3D не передан). |
 | `whenMaps3DReady(instance)`            | Промис слоя Maps3D после `attach()` (готов `layer.buildings`). |
-| `toggle3DBuildings(instance, enabled)` | Вкл/выкл детальные 3D-здания на лету (только `engine: "3d"`). |
+| `toggle3DBuildings(instance, enabled)` | Вкл/выкл объёмные здания на лету.                             |
+| `setLayer(instance, id, on, params?)`  | Включить/выключить слой платформы.                            |
+| `getLayerState(instance, id)`          | Снимок состояния одного слоя.                                 |
+| `getLayers(instance)`                  | Снимок всех слоёв.                                            |
+| `onLayers(instance, callback)`         | Подписка на изменения слоёв; возвращает отписку.              |
+| `refreshLayers(instance)`              | Пере-применить волю клиента ко всем слоям.                    |
+| `onBuildingClick(instance, callback)`  | Клик по зданию.                                               |
+| `selectBuilding(instance, id, style?)` | Выделить здание по `osm_id`.                                  |
+| `clearSelection(instance)`             | Снять выделение.                                              |
+| `selectedBuilding(instance)`           | Идентификатор выделенного здания или `null`.                  |
+| `setSelectionStyle(instance, style)`   | Облик выделения.                                              |
+| `onRoadClick(instance, callback)`      | Клик по дороге.                                               |
+| `roadAt(instance, point, tolPx?)`      | Дорога под точкой холста.                                     |
 | `destroy(instance)`                    | Полностью удаляет карту.                                      |
 | `loadKeyFromScriptUrl()`               | Читает `apikey` из URL SDK скрипта.                           |
 | `loadLanguageFromScriptUrl()`          | Читает `lang` из URL SDK скрипта.                             |
@@ -838,7 +1087,9 @@ const map = MahalMap.create(
 );
 ```
 
-Когда передан `style`, SDK не добавляет `token` или `lang=ru` и не подменяет URL при `setStyle()` или `setLanguage()`.
+Стиль при этом считается зафиксированным: `setStyle()` и `setLanguage()` его не подменяют.
+
+С переданным `Maps3D` URL всё равно проходит через `Maps3D.mapOptions()`, поэтому `transformRequest` с ключом на месте — тайлы и шрифты платформы внутри своего стиля продолжают работать.
 
 ## Жизненный цикл
 
@@ -988,6 +1239,104 @@ interface MeasureShape {
 }
 ```
 
+## Сервисы поиска и маршрутов
+
+Сервисы работают независимо от карты: их можно вызывать без `MahalMap.create()`. Токен передаётся аргументом в каждый вызов — сохранённый через `keyUtils.saveKey()` map token для них не используется.
+
+```ts
+import { Search, SearchPoi, SearchByLocation, CheckJSApi, Router } from "mahal_map";
+```
+
+### `Search(text, token, additionalParam?)`
+
+Поиск адресов (геокодер). Вызовы дебаунсятся на 500 мс: при вводе по символу уходит один запрос.
+
+```ts
+const results = await Search("Рудаки 33", token, {
+  lat: "38.5598",
+  lng: "68.7870",
+  limit: 10,
+});
+```
+
+| Параметр | Тип | Описание |
+| -------- | --- | -------- |
+| `text` | `string` | Строка поиска. |
+| `token` | `string` | Токен сервиса. Обязателен, иначе `[MahalMap SDK] Search token is required`. |
+| `additionalParam.lat` / `.lng` | `string` | Точка для сортировки результатов по удалённости. |
+| `additionalParam.limit` | `number` | Максимум результатов. |
+| `additionalParam.type` | `string` | Фильтр по типу объекта. |
+
+Возвращает `ISearchResponse[]`.
+
+### `SearchPoi(text, token, additionalParam?)`
+
+Поиск POI (организации, объекты). Сигнатура и дебаунс те же, что у `Search`, таймер отдельный — параллельный ввод в двух полях не перебивает запросы друг друга.
+
+```ts
+const places = await SearchPoi("кафе", token, { lat: "38.5598", lng: "68.7870", limit: 20 });
+```
+
+Возвращает `ISearchResponse[]`.
+
+### `SearchByLocation(params)`
+
+Обратный геокодинг: адреса и POI по координатам. Без дебаунса.
+
+```ts
+const res = await SearchByLocation({
+  lat: 38.5598,
+  lng: 68.787,
+  token,
+});
+```
+
+| Поле | Тип | Обязательное |
+| ---- | --- | ------------ |
+| `lat` | `string \| number` | да |
+| `lng` | `string \| number` | да |
+| `token` | `string` | да |
+| `type` | `string` | нет |
+
+### `CheckJSApi(token)`
+
+Проверяет, активна ли подписка JSApi у токена.
+
+```ts
+const { success, message } = await CheckJSApi(token);
+
+if (!success) {
+  console.warn("Подписка не активна:", message);
+}
+```
+
+Промис резолвится и при отрицательном ответе — `success: false` это результат проверки, а не сбой. Исключение бросается только если вызов не дошёл до сервиса (сеть, CORS, таймаут) или токен пустой.
+
+Этот же вызов используется внутри [`MahalMap.createAsync()`](#mahalmapcreateasyncoptions-maplibreobject-maps3dctor), когда `Maps3D` не передан и карта поднимается на запасном стиле.
+
+### `Router(points, typeData, token)`
+
+Маршрут между точками.
+
+```ts
+const routes = await Router(
+  [
+    [68.787, 38.5598],
+    [68.809, 38.561],
+  ],
+  "geojson",
+  token,
+);
+```
+
+| Параметр | Тип | Описание |
+| -------- | --- | -------- |
+| `points` | `number[][]` | Точки в формате `[lng, lat]`. |
+| `typeData` | `string` | `"geojson"` — декодирует polyline в массив координат. Другое значение оставляет `geometry` строкой polyline. |
+| `token` | `string` | Токен сервиса. |
+
+Возвращает `IRoute[]`.
+
 ## License
 
 ISC