npm - mahal_map - Versions diffs - 2.2.2 → 2.3.0 - Mend

mahal_map 2.2.2 → 2.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/README.md CHANGED Viewed

@@ -1,1754 +1,1808 @@
-# Mahal Map
-Mahal Map - JavaScript/TypeScript SDK для работы с картой Mahal поверх MapLibre GL JS.
-Документация ниже описывает только открытые функции карты: создание карты, управление инстансами, стили, язык, камера, маркеры и browser SDK.
-## Установка
-```sh
-npm install mahal_map maplibre-gl @grammaps/maps3d-web
-```
-Обе зависимости — `peerDependencies`, в бандл `mahal_map` они не входят. Библиотека их не импортирует: MapLibre и `Maps3D` приходят снаружи, аргументами `create()` либо через `window`.
-- `maplibre-gl` (`^6.10.0`) — обязателен всегда.
-- `@grammaps/maps3d-web` (>=0.5.0; рекомендуется 0.8.0 — в ней наведение на здание и починенный пикинг клика) — даёт стили, тайлы, объём, пробки, рельеф, планы этажей, клик по объектам. Помечен `optional`: без него карта поднимется на запасном векторном стиле, но 3D и слоёв платформы на ней не будет.
-MapLibre можно не класть в свою сборку вовсе — платформа отдаёт согласованную версию вместе с веб-воркером:
-```ts
-const maplibregl = await Maps3D.maplibre({ base: "https://navi.gram.tj" });
-```
-## Веб-воркер MapLibre
-MapLibre разбирает векторные тайлы в веб-воркере и ищет его файл рядом со своим модулем. Сборщик складывает библиотеку в общий бандл, рядом файла не оказывается, и вместо скрипта сервер отдаёт `index.html`.
-Симптом обманчивый: **карта показывает пустой фон, ошибок про карту нет**. В консоли лежит только `Uncaught SyntaxError: Unexpected token '<'` — ни слова ни про MapLibre, ни про воркер, ни про тайлы.
-`mahal_map` это распознаёт сам. Если через 8 с после создания карты не разобран ни один векторный тайл, в консоль уходит предупреждение с причиной и обоими решениями:
-```
-[MahalMap SDK] Карта пуста: ни один векторный тайл не разобран — похоже, не запустился веб-воркер MapLibre.
-```
-Проверка молчит на растровых стилях (им воркер не нужен), в фоновой вкладке (там MapLibre приостановлен) и когда фичи отрисованы. Отключается через `workerCheck: false`, своя задержка — `workerCheck: 12000`.
-### Решение 1 — взять библиотеку у платформы
-Версия согласована с Maps3D, веб-воркер приезжает вместе с ней, настраивать нечего:
-```ts
-const maplibregl = await Maps3D.maplibre({ base: "https://navi.gram.tj" });
-const map = MahalMap.create({ container: "map" }, maplibregl, Maps3D);
-```
-### Решение 2 — оставить свою сборку
-Тогда адрес воркера нужно свести с реальным файлом — и в разработке, и в собранной версии:
-```ts
-// vite.config.ts — чтобы адрес воркера совпал с файлом во время разработки
-export default defineConfig({ optimizeDeps: { exclude: ["maplibre-gl"] } });
-```
-```ts
-// в приложении — чтобы адрес совпал и в собранной версии
-import * as maplibregl from "maplibre-gl";
-import "maplibre-gl/dist/maplibre-gl.css";
-maplibregl.setWorkerUrl("/maplibre-gl-worker.mjs"); // файл скопирован в public/ из maplibre-gl/dist
-```
-> `import * as maplibregl` — не случайность: в MapLibre 6 default-экспорта нет, `import maplibregl from "maplibre-gl"` даёт `undefined`.
-## Миграция с 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
-```ts
-import * as 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");
-const map = MahalMap.create(
-  {
-    container: "map",
-    center: [68.787, 38.573],
-    zoom: 16.6,
-    theme: "light",
-  },
-  maplibregl,
-  Maps3D,
-);
-```
-Контейнер должен существовать в HTML:
-```html
-<div id="map" style="width: 100%; height: 500px"></div>
-```
-`Maps3D` — третий, необязательный аргумент: не передан — SDK возьмёт его из `window.Maps3D`. Стиль, `transformRequest` с ключом, сглаживание и подключение 3D библиотека делает сама.
-## Быстрый старт через Browser SDK
-Для browser SDK параметр `apikey` обязателен: без него карта не инициализируется.
-**MapLibre 6 поставляется только как ESM** — классической сборки `dist/maplibre-gl.js` для `<script src>` в ней больше нет. Поэтому библиотеку карты подключают модульным скриптом и передают в `create()` вторым аргументом:
-```html
-<link
-  rel="stylesheet"
-  href="https://cdn.jsdelivr.net/npm/maplibre-gl@6.10.0/dist/maplibre-gl.css"
-/>
-<script src="https://cp.mahal.tj/sdk/mahal_map.sdk.js?apikey=YOUR_MAP_API_KEY"></script>
-<div id="map" style="width: 100%; height: 500px"></div>
-<script type="module">
-  import * as maplibregl from "https://cdn.jsdelivr.net/npm/maplibre-gl@6.10.0/+esm";
-  const map = MahalMap.create(
-    {
-      container: "map",
-      center: [69.624024, 40.279687],
-      zoom: 12,
-    },
-    maplibregl,
-  );
-</script>
-```
-Через NPM язык можно передать при создании карты:
-```ts
-const map = MahalMap.create(
-  {
-    container: "map",
-    lang: "ru",
-    theme: "dark",
-  },
-  maplibregl,
-);
-```
-Через browser SDK язык можно передать в URL скрипта:
-```html
-<script src="https://cp.mahal.tj/sdk/mahal_map.sdk.js?apikey=YOUR_MAP_API_KEY&lang=ru"></script>
-```
-`lang` влияет на поиск и роутинг, но не на стиль: подписи на карте приходят из самого стиля платформы.
-## Параметры создания карты
-`MahalMap.create(options, maplibreObject?, maps3dCtor?)`
-`maps3dCtor` — импортированный конструктор `Maps3D` (третий, необязательный аргумент). Если не передан, SDK ищет его в `window.Maps3D`.
-```ts
-import type { IMaps3DLayerOptions, Maps3DThemeName } from "mahal_map";
-interface IMahalMapOptions {
-  container?: string | HTMLElement;
-  style?: string;
-  theme?: "dark" | "light";
-  lang?: "tj" | "ru";
-  center?: [number, number];
-  zoom?: number;
-  pitch?: number;
-  bearing?: number;
-  enable3D?: boolean;
-  base?: string;
-  family?: "default" | "navigator" | "mobile";
-  preset?: Maps3DThemeName | string;
-  antialias?: boolean;
-  workerCheck?: boolean | number;
-  maps3d?: Omit<IMaps3DLayerOptions, "apiKey" | "base">;
-  /** @deprecated Оставлена для совместимости, на поведение не влияет. */
-  engine?: "legacy" | "3d";
-  /** @deprecated Оставлена для совместимости, на поведение не влияет. */
-  autoAddVectorSource?: boolean;
-}
-```
-| Параметр      | Тип                                    | Описание                                                                                                                                                                            |
-| ------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `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: без него тонкая геометрия (перила, мачты, ряды сидений) на отдалении рассыпается в рябь.                                  |
-| `workerCheck` | `boolean \| number`                    | Диагностика неработающего веб-воркера MapLibre через 8 с после создания карты. `false` отключает, число задаёт свою задержку в мс. См. [Веб-воркер MapLibre](#веб-воркер-maplibre). |
-| `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
-// Навигаторная тёмная тема
-MahalMap.create(
-  { container: "map", family: "navigator", theme: "dark" },
-  maplibregl,
-  Maps3D,
-);
-// Смена темы внутри того же семейства
-map.setStyle("light"); // → navigator-light
-```
-> **Миграция с 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,
-> );
-> ```
-### Без `@grammaps/maps3d-web`
-Библиотека не установлена и в `window.Maps3D` ничего нет — карта всё равно поднимется: используется запасной векторный стиль `mtile.gram.tj` с подписью `?token=`, в консоль уходит предупреждение. На такой карте нет объёма, объектов, пробок, рельефа и реестра слоёв; `setStyle()` и `setLanguage()` стиль не меняют, методы реестра возвращают пустые значения (`false`, `null`, `[]`).
-Этот путь — единственный, где ещё проверяется подписка JSApi: `createAsync()` не создаст карту, если подписки нет. С переданным `Maps3D` проверка пропускается — доступ гейтит сама платформа по `?key=`.
-### Опции `maps3d` (расширенные)
-Передаются в `MahalMap.create({ maps3d: {...} })` и уходят в `Maps3D` как есть:
-| Опция              | Тип                                                                 | По умолч. | Описание                                                             |
-| ------------------ | ------------------------------------------------------------------- | --------- | -------------------------------------------------------------------- |
-| `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`, `fillOpacity` (0.10.0+). |
-| `minZoom`          | `number`                                                            | `16`      | Зум появления объёма.                                                |
-| `lodBias`          | `number`                                                            | `1`       | `0` — всегда детальная геометрия, `1` — упрощённая вдали.            |
-| `memoryBudget`     | `number`                                                            | `30`      | Сколько 3D-моделей держать в памяти.                                 |
-| `maskReplaced`     | `boolean`                                                           | `true`    | Прятать заменённые OSM-объекты (`anchor=replace`).                   |
-| `typeReplacements` | `boolean`                                                           | `true`    | Рисовать замены по типу (`natural=tree` → 3D-дерево и т.п.).         |
-`apiKey` и `base` в `maps3d` передавать не нужно — их подставляет сам `MahalMap` из сохранённого ключа и `options.base`.
-### Реестр слоёв
-Единая дверь ко всем слоям платформы. Идентификаторы и параметры типизированы: опечатка в имени слоя или в значении параметра — ошибка компиляции, а не тихий `false` в рантайме.
-```ts
-map.setLayer("terrain", true, { mode: "on" });
-map.setLayer("traffic", true);
-map.setLayer("indoor", true, { level: 2 });
-map.setLayer("buildings", true, { detail: "facade" });
-map.getLayerState("terrain"); // снимок одного слоя или null
-map.getLayers(); // снимок всех — по нему рисуется панель слоёв
-```
-| Слой               | Параметры                                  | По умолчанию                                                           | Откуда умолчание        |
-| ------------------ | ------------------------------------------ | ---------------------------------------------------------------------- | ----------------------- |
-| `buildings`        | `detail: footprint\|volume\|roofs\|facade` | включён                                                                | зашито                  |
-| `objects`          | —                                          | включён                                                                | зашито                  |
-| `terrain`          | `mode: auto\|on\|off`                      | включён, `mode: "auto"`                                                | зашито                  |
-| `parking`          | `highlight`, `paid`, `free`, `unknown`     | включён, `{ highlight: false, paid: true, free: true, unknown: true }` | зашито                  |
-| `fuel`, `charging` | —                                          | включены                                                               | зашито                  |
-| `traffic`          | —                                          | выключен                                                               | `maps3d.traffic`        |
-| `trafficRaster`    | —                                          | выключен                                                               | `maps3d.traffic.raster` |
-| `indoor`           | `level`                                    | выключен                                                               | `maps3d.indoor`         |
-| `closures`         | —                                          | выключен                                                               | `maps3d.closures`       |
-У нижних четырёх умолчание не зашито — реестр берёт его из опций `maps3d`, переданных при создании карты. Поэтому «выключен» в таблице значит «выключен, пока вы не передали опцию», а не «выключен всегда».
-Стартовое состояние можно задать сразу при создании карты — тогда первый кадр уже правильный, без моргания:
-```ts
-MahalMap.create(
-  { container: "map", maps3d: { traffic: true, closures: true } },
-  maplibregl,
-  Maps3D,
-);
-```
-Полный список — в разделе [Опции `maps3d`](#опции-maps3d-расширенные).
-#### `wanted`, `available`, `active` — три разных вопроса
-Поля независимы, и это главная ловушка реестра:
-| Поле        | Вопрос                                            |
-| ----------- | ------------------------------------------------- |
-| `wanted`    | чего хочет приложение                             |
-| `available` | что позволяют стиль и данные                      |
-| `active`    | что нарисовано прямо сейчас (память SDK)          |
-| `rendered`  | факт со стороны карты: слой есть в стиле и не погашен |
-`rendered` появилось в Maps3D 0.8.0; у сборок постарше его нет (`undefined`). Расхождение `active !== rendered` означает, что внутренний признак SDK разошёлся с картой — это видно одной проверкой, без чтения минифицированной сборки. Сравнивать поля можно только когда `rendered` есть — иначе на старой сборке любой активный слой покажется расхождением:
-```ts
-const state = map.getLayerState("terrain");
-// rendered === undefined — Maps3D < 0.8.0, проверка недоступна
-if (state?.rendered !== undefined && state.active !== state.rendered) {
-  reportLayerMismatch(state);
-}
-```
-Слой может быть включён и при этом не нарисован — и это не ошибка:
-```ts
-map.setLayer("terrain", true); // wanted: true
-const state = map.getLayerState("terrain");
-state?.available; // false — в стиле нет ключа maps3d:terrain
-state?.active; // false — либо режим auto, а зум слишком близкий
-```
-Поэтому галочку в интерфейсе рисуют по `wanted`, а пометку «сейчас не видно» — по `active`. Проверять сразу после `setLayer()` бесполезно: тайлы ещё едут. Правильный способ — подписка.
-#### Панель слоёв: подписка и отписка
-`onLayers()` возвращает функцию отписки. Звать её обязательно — иначе колбэк переживёт компонент и будет дёргать размонтированное состояние:
-```ts
-const unsubscribe = map.onLayers((state) => {
-  console.log(state.id, state.wanted, state.available, state.active);
-});
-// при размонтировании компонента
-unsubscribe();
-```
-`map.destroy()` снимает слой Maps3D целиком, так что после него подписка всё равно мертва — но до него отписываться нужно самим.
-#### Парковки, заправки, зарядки
-`Maps3D` рисует их сам, забирая эти классы у POI-слоёв стиля. Поэтому выключение слоя убирает объекты с карты полностью, а не оставляет значок стиля.
-Подтип парковки берётся из атрибута `fee`:
-| Параметр  | Условие      |
-| --------- | ------------ |
-| `paid`    | `fee=yes`    |
-| `free`    | `fee=no`     |
-| `unknown` | атрибута нет |
-```ts
-// только платные, с подсветкой
-map.setLayer("parking", true, {
-  paid: true,
-  free: false,
-  unknown: false,
-  highlight: true,
-});
-```
-Площадные парковки рисуются тремя слоями по одной геометрии: заливка в цвете подтипа, мягкая внутренняя кромка (с z14) и волосяной кант. Цвета: янтарь — платно, зелёный — бесплатно, сланцевый — неизвестно. Размеры заданы в экранных пикселях и от зума плитки не зависят.
-Заливку включает только режим поиска — `highlight: true`. Без него подключение Maps3D облик карты не меняет. Постоянную плотность заливки вместо кривой по зуму задаёт `maps3d.places.fillOpacity`.
-Наведение, клик и справка по участку — в разделе [Парковки: наведение, клик, справка](#парковки-наведение-клик-справка).
-#### Рельеф
-`auto` показывает рельеф на обзорных зумах, `on` — всегда. Режим `on` заметно дороже по трафику и времени кадра, чем `auto`.
-```ts
-map.setLayer("terrain", true, { mode: "auto" });
-```
-#### Планы этажей
-Слой включается реестром, но одного этого мало — без переключения этажа он бесполезен:
-```ts
-map.setLayer("indoor", true);
-const levels = map.getIndoorLevels(); // этажи в текущем виде карты, [] — данных нет
-map.setIndoorLevel(1); // нумерация OSM: 0 — первый наземный
-map.refreshIndoor(); // перечитать после правки картографом
-```
-После поиска показать найденный объект вместе с его этажом:
-```ts
-// level приходит у объектов внутри зданий; без него откроется первый этаж
-// и метка окажется в чужом зале
-map.showPlace(68.787, 38.573, place.level, 18);
-```
-#### Слой, которого нет в списке
-`setLayer()` принимает только известные идентификаторы. Если в новой сборке Maps3D появится слой, которого ещё нет в типах, — он доступен напрямую через слой, там `id` остаётся строкой:
-```ts
-map.getMaps3DLayer()?.setLayer?.("новый-слой", true);
-```
-`setLayer()` возвращает `false`, если такого слоя в подключённой сборке Maps3D нет или Maps3D не передан вовсе. После полной смены стиля волю клиента возвращает `map.refreshLayers()` — при `setStyle()` библиотека вызывает его сама.
-### 3D-здания
-`Maps3D` рисует процедурные 3D-здания (three.js) вместо плоской `fill-extrusion` стиля: фаска кромок, вертикальный градиент и базовый цвет берутся из стиля, окна — из `metadata` темы. Слой создаётся и подключается автоматически (`enable3D` по умолчанию `true`) — вручную поднимать `new Maps3D(...)` не нужно.
-Тонкая настройка облика — через сам слой, после готовности:
-```ts
-const layer = await map.whenMaps3DReady();
-const b = layer?.buildings;
-b?.setWindowStyle(7); // тип окна 0..9 (сетка, лента, curtain wall, ...)
-b?.setWindowDepth(0.85); // глубина ниши окна 0..1 (реальная геометрия вблизи)
-b?.setWindowColor("#6b9ed1");
-b?.setWindowFrameColor("#f2f2f4");
-b?.setEdgeRadius(1.2); // скругление кромок, м
-// Свет обычно НЕ задают руками — его несёт metadata стиля, сеттеры её перебивают
-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
-```
-### Выделение зданий и клик по дорогам
-Клик по зданию и клик по дороге приходят независимо: одна точка может попасть и туда, и туда — что важнее, решает приложение.
-```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()` — даже когда слой ещё не поднят (`enable3D: false`). Подписка и облик выделения запоминаются и переигрываются, как только слой появится:
-```ts
-const map = MahalMap.create({ container: "map", enable3D: false }, maplibregl, Maps3D);
-map.onBuildingClick((b) => console.log(b?.props.osm_id));
-map.setSelectionStyle({ color: "#e23b2f" });
-map.toggle3DBuildings(true); // подписка и стиль выделения уже применены к новому слою
-```
-### Наведение на здание
-Требует `@grammaps/maps3d-web` **0.8.0** и старше. Подсветку и курсор рисует сам SDK — приложение задаёт облик и получает уведомления.
-```ts
-map.setHoverStyle({ color: "#6b9ed1", opacity: 0.3, cursor: "pointer" });
-map.onBuildingHover((building) => {
-  if (!building) return; // курсор ушёл с домов
-  console.log(building.props.osm_id, building.height);
-});
-```
-Колбэк приходит **только в момент смены** дома под курсором, а не на каждое движение мыши.
-Слежение включается самой подпиской: пока `onBuildingHover` не вызван, SDK курсор не трогает и сцену не разбирает. `onBuildingHover(null)` отписывает и гасит подсветку.
-| Метод | Описание |
-| --- | --- |
-| `onBuildingHover(cb \| null)` | Подписка на наведение; `null` отписывает и гасит подсветку. |
-| `setHoverStyle(s)` | Облик: `color`, `opacity`, `glow`, `durationMs`, `easing`, `cursor`. `cursor: null` — не трогать курсор. |
-| `setHoverEnabled(on)` | Вкл/выкл наведение, не трогая подписку. |
-| `hoverEnabled` | Включено ли наведение сейчас. |
-| `hoverBuilding(id \| null)` | Навести программно — например, с наведения на строку списка. `false` — дома нет на карте. |
-| `hoveredBuilding()` | Идентификатор дома под наведением или `null`. |
-Слот наведения свой, отдельный от выделения: **выбор всегда главнее**, и на выбранном доме наведение не рисуется. Занимать `setSelectionStyle` ради подсветки под курсором, как приходилось до 0.8.0, больше не нужно.
-#### Наведение с элементов интерфейса
-Курсор стоит на строке списка, а не на карте:
-```ts
-row.addEventListener("mouseenter", () => map.hoverBuilding(row.dataset.osmId!));
-row.addEventListener("mouseleave", () => map.hoverBuilding(null));
-```
-Следующее движение мыши по карте перебивает программное наведение — слежение владеет слотом, пока включено.
-#### Где наведение выключают
-Там, где подсветка мешает: режим рисования на карте, открытая карточка объекта, тач-устройство без курсора.
-```ts
-map.setHoverEnabled(false); // подписка сохраняется
-```
-Цену ограничивает сам SDK: разбор не чаще раза в кадр, пропускается во время движения карты и не трогает сцену, пока курсор на том же доме. Но разбор — это чтение пикселя обратно из GPU, поэтому на слабых устройствах наведение лучше не включать.
-### Парковки: наведение, клик, справка
-> Нужен `@grammaps/maps3d-web` **0.10.0+**. На более старой сборке методы ничего не делают и возвращают пустые значения (`false`, `null`).
-Устроено как у зданий: приложение задаёт облик и получает уведомления, подсветку и курсор рисует SDK.
-```ts
-// Режим поиска: заливка по подтипу
-map.setLayer("parking", true, { highlight: true });
-map.setParkingHoverStyle({ opacity: 0.6, outlineWidth: 2.4, cursor: "pointer" });
-map.onParkingHover((p) => {
-  tooltip.textContent = p ? p.subtype : "";
-});
-map.onParkingClick((p) => {
-  if (!p) return;
-  openCard(p); // { id, subtype, fee, access, kind, capacity, props }
-});
-// Подсветить со строки списка и погасить
-row.onmouseenter = () => map.hoverParking(osmId);
-row.onmouseleave = () => map.hoverParking(null);
-// Справка по точке холста (e.point события карты), допуск 4 px
-map.getMap().on("contextmenu", (e) => console.log(map.parkingAt(e.point, 4)));
-```
-| Метод                              | Описание                                                                                          |
-| ---------------------------------- | ------------------------------------------------------------------------------------------------- |
-| `onParkingHover(callback \| null)` | Участок под курсором либо `null`. Зовётся **только при смене участка**. `null` — отписаться и погасить. |
-| `setParkingHoverStyle(style)`      | Облик подсветки: `color`, `opacity`, `outlineColor`, `outlineWidth`, `cursor`.                    |
-| `setParkingHoverEnabled(enabled)`  | Выключить/включить наведение, не теряя подписку.                                                  |
-| `parkingHoverEnabled`              | Геттер: включено ли наведение.                                                                    |
-| `hoverParking(id \| null)`         | Подсветить участок программно по `osm_id`; `null` — погасить. `false` — участка нет в данных.     |
-| `hoveredParking()`                 | `osm_id` подсвеченного участка или `null`.                                                        |
-| `onParkingClick(callback \| null)` | Клик по участку: справка либо `null`. `null` вместо колбэка — отписаться.                         |
-| `parkingAt(point, tolPx?)`         | Справка по точке холста. Допуск по умолчанию `0` — строго внутрь участка.                         |
-Облик подсветки (`IMaps3DParkingHoverStyle`):
-| Поле           | По умолч.    | Описание                                                                                   |
-| -------------- | ------------ | ------------------------------------------------------------------------------------------ |
-| `color`        | цвет подтипа | Цвет заливки под курсором. По умолчанию не меняется намеренно — подтип уже покрашен смыслом. |
-| `opacity`      | `0.55`       | Непрозрачность заливки под курсором.                                                       |
-| `outlineColor` | кант подтипа | Цвет канта под курсором.                                                                   |
-| `outlineWidth` | `2.2`        | Во сколько раз толще кант под курсором.                                                    |
-| `cursor`       | `"pointer"`  | CSS-курсор над парковкой; `null` — не трогать.                                             |
-Справка (`IMaps3DParkingInfo`) — ровно то, что лежит в тайле. Отсутствующий атрибут — `null`.
-| Поле       | Тип                              | Описание                                                              |
-| ---------- | -------------------------------- | --------------------------------------------------------------------- |
-| `id`       | `number \| string`               | `osm_id` участка — тот же, что принимает `hoverParking()`.            |
-| `subtype`  | `"paid" \| "free" \| "unknown"`  | Платность. `unknown` значит «не указано», а **не** «бесплатно».       |
-| `fee`      | `string \| null`                 | Исходное `fee` (`yes`/`no`).                                          |
-| `access`   | `string \| null`                 | Кому можно: `residents`, `private`, `customers`, `permissive`…        |
-| `kind`     | `string \| null`                 | OSM `parking=*`: `surface`, `multi-storey`, `underground`, `rooftop`… |
-| `capacity` | `number \| null`                 | Число мест.                                                           |
-| `props`    | `Record<string, unknown>`        | Все свойства фичи как есть.                                           |
-Поведение:
-- Попадание определяется по границе полигона, а не по расстоянию до центра.
-- Колбэк наведения вызывается при смене участка, не на каждое движение мыши. Разбор идёт не чаще раза в кадр и пропускается, пока карта движется.
-- Подписка на наведение или клик поднимает слой заливки, даже когда режим поиска выключен, — по нему идёт опрос. Красить в этом случае слой ничего не будет.
-Ограничения:
-- Графика работы нет: `opening_hours` в слое `landuse` отсутствует.
-- Названия у площадных парковок нет — оно бывает только у точек POI.
-#### Вкл/выкл 3D-здания на лету
-Переключение объём ⇄ штатные здания стиля, без пересоздания карты. Умеет поднять слой, если его не было (`enable3D: false` при создании):
-```ts
-const map = MahalMap.getInstance("map");
-map.toggle3DBuildings(false); // выкл
-map.toggle3DBuildings(true); // вкл обратно
-// статик-версия и SDK-фасад (mahal_map/sdk) работают так же
-MahalMap.toggle3DBuildings(map, false);
-```
-Штатные здания стиля прячет и возвращает сам `Maps3D` — `mahal_map` их видимость не трогает, поэтому спорить за один слой некому.
-Для переключения пользуйтесь именно `toggle3DBuildings()`: он поднимет слой, если его ещё не было (`enable3D: false` при создании), а на сборках Maps3D без реестра слоёв откатится на `setBuildingsEnabled()`.
-```ts
-map.toggle3DBuildings(false); // совместимо со всеми сборками
-```
-`map.setLayer("buildings", false)` — не замена: он ходит только в реестр и ничего не создаёт. Годится, когда вы точно знаете, что на странице Maps3D с реестром слоёв (0.7.x), и слой уже подключён.
-#### `map.whenMaps3DReady()`
-Подключение слоя асинхронное: сразу после `create()` слой уже есть, но `layer.buildings` (окна, свет, кромки) появляется только после него. Чтобы не гадать — дождитесь готовности:
-```ts
-const layer = await map.whenMaps3DReady();
-layer?.buildings?.setWindowStyle(4);
-```
-Промис резолвится в `undefined`, если `Maps3D` не передан, слой выключен (`enable3D: false`) или подключение упало — ошибка при этом уходит в `console.error`, а карта остаётся живой на штатных зданиях стиля.
-### Подключение и выключение 3D-слоя: полный пример (Vue 3)
-Кнопка-переключатель «3D ⇄ контуры», панель слоёв на живом состоянии реестра и корректная очистка при размонтировании. Слой `Maps3D` поднимает и цепляет сама библиотека — вручную `Maps3D.enhance(...)`, `transformRequest` и `attach()` писать не нужно.
-```vue
-<script setup lang="ts">
-import { computed, onBeforeUnmount, onMounted, ref, shallowRef } from "vue";
-import * as maplibregl from "maplibre-gl";
-import "maplibre-gl/dist/maplibre-gl.css";
-import { Maps3D } from "@grammaps/maps3d-web";
-import { MahalMap, keyUtils } from "mahal_map";
-import type { IMaps3DLayerState, Maps3DLayerId } from "mahal_map";
-const API_KEY = "YOUR_MAP_API_KEY";
-const mahalMap = shallowRef<MahalMap | null>(null);
-const is3dEnabled = ref(true);
-const isLayerReady = ref(false);
-// Панель слоёв рисуется по живому снимку реестра
-const layers = ref<IMaps3DLayerState[]>([]);
-let unsubscribeLayers: (() => void) | null = null;
-function toggleLayer(id: Maps3DLayerId, on: boolean) {
-  // Опечатка в id или в параметрах не скомпилируется
-  mahalMap.value?.setLayer(id, on);
-}
-const buildingModeText = computed(() =>
-  is3dEnabled.value ? "3D включено" : "Контуры",
-);
-const buildingToggleText = computed(() =>
-  is3dEnabled.value ? "Выключить 3D" : "Включить 3D",
-);
-function toggle3dBuildings() {
-  is3dEnabled.value = !is3dEnabled.value;
-  // Вкл/выкл детальных 3D-зданий: библиотека сама вернёт/спрячет плоские здания стиля.
-  mahalMap.value?.toggle3DBuildings(is3dEnabled.value);
-}
-onMounted(async () => {
-  // Токен — один на всё (стиль, тайлы, Maps3D). Отдельный apiKey слою передавать не нужно.
-  keyUtils.saveKey(API_KEY);
-  const map = MahalMap.create(
-    {
-      container: "map",
-      theme: "dark", // тема dark; "light" → тема light
-      center: [68.787, 38.573],
-      zoom: 16.6,
-      pitch: 58, // без наклона объём не виден
-      bearing: -20,
-      enable3D: true, // значение по умолчанию, когда Maps3D передан
-      maps3d: { minZoom: 16, lodBias: 0 },
-    },
-    maplibregl,
-    Maps3D,
-  );
-  mahalMap.value = map;
-  // Дожидаемся attach(): до него layer.buildings ещё нет.
-  const layer = await map.whenMaps3DReady();
-  const buildings = layer?.buildings;
-  if (!buildings) {
-    return;
-  }
-  buildings.setWindowMinZoom?.(16);
-  buildings.setWindowStyle(4);
-  buildings.setWindowDepth(0.85);
-  buildings.setWindowColor("#6b9ed1");
-  buildings.setWindowFrameColor("#f2f2f4");
-  buildings.setWindowGlow?.(0.22);
-  buildings.setEdgeRadius(1.2);
-  // Слои: стартовый снимок плюс подписка на изменения.
-  // Состояние приходит асинхронно — сразу после setLayer() проверять бесполезно.
-  layers.value = map.getLayers();
-  unsubscribeLayers = map.onLayers(() => {
-    layers.value = map.getLayers();
-  });
-  isLayerReady.value = true;
-});
-onBeforeUnmount(() => {
-  isLayerReady.value = false;
-  // Отписку снимаем сами: иначе колбэк переживёт компонент.
-  unsubscribeLayers?.();
-  unsubscribeLayers = null;
-  // destroy() сам снимает слой Maps3D и удаляет карту MapLibre.
-  mahalMap.value?.destroy();
-  mahalMap.value = null;
-});
-</script>
-<template>
-  <main class="map-page">
-    <div id="map" class="map" />
-    <section class="panel" aria-label="GramMaps 3D">
-      <span class="mode-label">{{ buildingModeText }}</span>
-      <button
-        type="button"
-        :aria-pressed="is3dEnabled"
-        :disabled="!isLayerReady"
-        @click="toggle3dBuildings"
-      >
-        {{ buildingToggleText }}
-      </button>
-      <ul class="layers">
-        <li v-for="layer in layers" :key="layer.id">
-          <label>
-            <!-- галочка по wanted: это воля приложения -->
-            <input
-              type="checkbox"
-              :checked="layer.wanted"
-              :disabled="!layer.available"
-              @change="toggleLayer(layer.id as Maps3DLayerId, !layer.wanted)"
-            />
-            {{ layer.id }}
-          </label>
-          <!-- слой включён, но не нарисован — это норма, а не ошибка -->
-          <small v-if="layer.wanted && !layer.active">сейчас не видно</small>
-          <small v-else-if="!layer.available">нет в стиле</small>
-        </li>
-      </ul>
-    </section>
-  </main>
-</template>
-<style>
-.map-page,
-.map {
-  position: absolute;
-  inset: 0;
-}
-.panel {
-  position: absolute;
-  top: 12px;
-  left: 12px;
-  z-index: 2;
-}
-</style>
-```
-Что библиотека делает за вас против ручного подключения `@grammaps/maps3d-web`:
-| Ручной код                                      | Через `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)
-Библиотеку карты проще взять у платформы: версия согласована с Maps3D, веб-воркер приезжает вместе с ней, про ESM-сборку думать не нужно.
-```html
-<script src="https://cdn.jsdelivr.net/npm/@grammaps/maps3d-web/dist/maps3d.global.js"></script>
-<script src="https://cp.mahal.tj/sdk/mahal_map.sdk.js?apikey=YOUR_MAP_API_KEY"></script>
-<div id="map" style="width: 100%; height: 500px"></div>
-<button id="toggle3d" type="button">Выключить 3D</button>
-<script type="module">
-  const maplibregl = await Maps3D.maplibre({ base: "https://navi.gram.tj" });
-  // maplibregl обязателен вторым аргументом: window.maplibregl здесь не появляется.
-  // Maps3D третьим можно не передавать — SDK возьмёт его из window.Maps3D.
-  const map = MahalMap.create(
-    {
-      container: "map",
-      theme: "dark",
-      center: [68.787, 38.573],
-      zoom: 16.6,
-      pitch: 58,
-    },
-    maplibregl,
-  );
-  let enabled = true;
-  document.getElementById("toggle3d").addEventListener("click", () => {
-    enabled = !enabled;
-    MahalMap.toggle3DBuildings(map, enabled);
-    document.getElementById("toggle3d").textContent = enabled
-      ? "Выключить 3D"
-      : "Включить 3D";
-  });
-  MahalMap.whenMaps3DReady(map).then((layer) => {
-    layer?.buildings?.setWindowStyle(4);
-  });
-</script>
-```
-### Пробки
-Через реестр слоёв:
-```ts
-map.setLayer("traffic", true);
-map.setLayer("trafficRaster", true); // растровый вариант, без клика по дороге
-```
-Тонкие настройки — через сам слой:
-```ts
-const layer = map.getMaps3DLayer();
-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?.diagnostics?.(); // рельеф, потеря контекста WebGL, счётчики зданий
-```
-Для полной остановки карты используйте только `map.destroy()` / `MahalMap.destroy(map)` — они сами вызывают `destroy()`/`remove()` у Maps3D слоя. **Не вызывайте `layer.destroy()`/`layer.remove()` напрямую**: `MahalMap` не узнает об этом и продолжит считать слой активным (внутренний `maps3dLayer` и `buildingsEnabled` разойдутся с реальностью). Нужно временно выключить только 3D-здания — используйте `map.toggle3DBuildings(false)` (см. выше).
-## MahalMap
-`MahalMap` - основной класс карты. Конструктор закрыт, карту нужно создавать через `MahalMap.create()`.
-### `MahalMap.create(options, maplibreObject?, maps3dCtor?)`
-Создает новый инстанс карты и сохраняет его по ключу `container`. Для стандартных стилей перед созданием карты должен быть сохранен map token через `keyUtils.saveKey()`. В browser SDK token читается из обязательного URL-параметра `apikey`. Третий аргумент — необязательный конструктор `Maps3D`; без него SDK использует `window.Maps3D`.
-```ts
-const map = MahalMap.create(
-  {
-    container: "map",
-    center: [69.624024, 40.279687],
-    zoom: 12,
-    theme: "light",
-    lang: "tj",
-  },
-  maplibregl,
-);
-```
-В 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 * as 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 завершил загрузку.
-```ts
-MahalMap.onReady("map", (maplibreMap) => {
-  maplibreMap.resize();
-});
-```
-`callback` получает нативный `Map` объект из MapLibre GL JS.
-### `MahalMap.getInstance(container)`
-Возвращает ранее созданный инстанс карты по ключу контейнера.
-```ts
-const map = MahalMap.getInstance("map");
-map.setZoom(14);
-```
-Если инстанс не найден, будет выброшена ошибка.
-### `MahalMap.hasInstance(container)`
-Проверяет, существует ли карта с таким ключом контейнера.
-```ts
-if (MahalMap.hasInstance("map")) {
-  const map = MahalMap.getInstance("map");
-}
-```
-### `MahalMap.removeInstance(container)`
-Удаляет инстанс из внутреннего реестра и возвращает `boolean`.
-```ts
-const removed = MahalMap.removeInstance("map");
-```
-Метод удаляет только запись из реестра. Для полного удаления карты используйте `destroy()`.
-### `MahalMap.setDefaultLanguage(lang)`
-Задает язык по умолчанию для новых карт.
-```ts
-MahalMap.setDefaultLanguage("ru");
-keyUtils.saveKey("YOUR_MAP_API_KEY");
-const map = MahalMap.create({ container: "map" }, maplibregl);
-```
-После этого новые карты без `options.lang` будут использовать русский стандартный стиль. Для `tj` или пустого значения стандартные стили будут только с `token`.
-## Методы инстанса карты
-### `map.getMap()`
-Возвращает нативный MapLibre `Map`.
-```ts
-const maplibreMap = map.getMap();
-maplibreMap.resize();
-```
-Используйте этот метод, если нужна функция MapLibre, которой нет в Mahal Map SDK.
-### `map.getCamera()`
-Возвращает `CameraController` для управления камерой.
-```ts
-const camera = map.getCamera();
-camera.flyTo({
-  center: [69.624024, 40.279687],
-  zoom: 14,
-});
-```
-### `map.setStyle(theme)`
-Переключает светлую/тёмную тему внутри выбранного `family`.
-```ts
-map.setStyle("dark"); // family: "navigator" → navigator-dark
-map.setStyle("light"); // → navigator-light
-```
-Адрес стиля строит `Maps3D.styleUrl()`. После загрузки нового стиля библиотека сама зовёт `refreshLayers()` — состояние слоёв переживает смену темы.
-Метод ничего не делает, если карта создана с явным `style` или `preset` (стиль зафиксирован), либо если `Maps3D` не передан — у запасного стиля вариантов по теме нет.
-### `map.setLanguage(lang)`
-Запоминает язык для поиска и роутинга.
-```ts
-map.setLanguage("ru");
-map.setLanguage("tj");
-```
-Стиль метод не трогает: подписи приходят из самого стиля платформы, отдельных URL по языкам больше нет.
-### `map.setCenter(center)`
-Меняет центр карты.
-```ts
-map.setCenter([69.624024, 40.279687]);
-```
-Формат координат: `[lng, lat]`.
-### `map.setZoom(zoom)`
-Меняет zoom карты.
-```ts
-map.setZoom(13);
-```
-### `map.addMarker(marker)`
-Добавляет маркер на карту.
-```ts
-import { MahalMapDefaultMarker } from "mahal_map";
-const marker = new MahalMapDefaultMarker({
-  coordinates: [69.624024, 40.279687],
-  color: "#278960",
-});
-map.addMarker(marker);
-```
-Маркер должен реализовать интерфейс:
-```ts
-interface IMapMarker {
-  getElement(): HTMLElement;
-  getCoordinates(): [number, number];
-  isDraggable?(): boolean;
-  getAnchor?():
-    | "center"
-    | "top"
-    | "bottom"
-    | "left"
-    | "right"
-    | "top-left"
-    | "top-right"
-    | "bottom-left"
-    | "bottom-right";
-}
-```
-### `map.destroy()`
-Удаляет логотип SDK, вызывает `remove()` у MapLibre карты и удаляет инстанс из внутреннего реестра.
-```ts
-map.destroy();
-```
-Используйте при размонтировании страницы или компонента.
-## Статические методы-обертки
-Для browser SDK и случаев, когда удобнее работать с функциями, доступны статические методы:
-```ts
-MahalMap.getMap(map);
-MahalMap.getCamera(map);
-MahalMap.setStyle(map, "dark");
-MahalMap.setLanguage(map, "ru");
-MahalMap.setCenter(map, [69.624024, 40.279687]);
-MahalMap.setZoom(map, 14);
-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.getIndoorLevels(map);
-MahalMap.setIndoorLevel(map, 1);
-MahalMap.refreshIndoor(map);
-MahalMap.showPlace(map, 68.787, 38.573, 2, 18);
-// Выделение зданий и клики
-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.setParkingHoverStyle(map, { opacity: 0.6, outlineWidth: 2.4 });
-MahalMap.onParkingHover(map, (p) => console.log(p?.subtype));
-MahalMap.setParkingHoverEnabled(map, false);
-MahalMap.hoverParking(map, 123456789);
-MahalMap.hoveredParking(map);
-MahalMap.onParkingClick(map, (p) => console.log(p?.id));
-MahalMap.parkingAt(map, { x: 320, y: 240 }, 4);
-// Наведение на здание (Maps3D 0.8.0)
-MahalMap.onBuildingHover(map, (b) => console.log(b?.id));
-MahalMap.setHoverStyle(map, { color: "#6b9ed1", cursor: "pointer" });
-MahalMap.setHoverEnabled(map, false);
-MahalMap.hoverBuilding(map, 123456789);
-MahalMap.hoveredBuilding(map);
-MahalMap.destroy(map);
-```
-Эти методы вызывают соответствующие методы переданного инстанса.
-## Browser SDK функции
-При подключении `mahal_map.sdk.js` функции доступны на глобальном объекте `MahalMap`.
-```js
-const map = MahalMap.create({
-  container: "map",
-  center: [69.624024, 40.279687],
-  zoom: 12,
-});
-MahalMap.setStyle(map, "dark");
-MahalMap.setLanguage(map, "ru");
-MahalMap.setZoom(map, 14);
-```
-Доступные функции карты в browser SDK:
-| Функция                                        | Описание                                                              |
-| ---------------------------------------------- | --------------------------------------------------------------------- |
-| `create(options)`                              | Создает карту. Требует `apikey` в URL SDK скрипта.                    |
-| `createAsync(options)`                         | Создает карту после проверки подписки JSApi (только без Maps3D).      |
-| `onReady(container, callback)`                 | Выполняет callback после загрузки карты.                              |
-| `getInstance(container)`                       | Возвращает инстанс карты.                                             |
-| `hasInstance(container)`                       | Проверяет наличие инстанса.                                           |
-| `removeInstance(container)`                    | Удаляет инстанс из реестра.                                           |
-| `getMap(instance)`                             | Возвращает нативный MapLibre Map.                                     |
-| `getCamera(instance)`                          | Возвращает CameraController.                                          |
-| `setStyle(instance, theme)`                    | Переключает тему стандартного стиля.                                  |
-| `setLanguage(instance, lang)`                  | Переключает язык стандартного стиля.                                  |
-| `setCenter(instance, center)`                  | Меняет центр карты.                                                   |
-| `setZoom(instance, zoom)`                      | Меняет zoom карты.                                                    |
-| `addMarker(instance, marker)`                  | Добавляет маркер.                                                     |
-| `getMaps3DLayer(instance)`                     | Возвращает инстанс слоя Maps3D (`undefined`, если Maps3D не передан). |
-| `whenMaps3DReady(instance)`                    | Промис слоя Maps3D после `attach()` (готов `layer.buildings`).        |
-| `toggle3DBuildings(instance, enabled)`         | Вкл/выкл объёмные здания на лету.                                     |
-| `setLayer(instance, id, on, params?)`          | Включить/выключить слой платформы.                                    |
-| `getLayerState(instance, id)`                  | Снимок состояния одного слоя.                                         |
-| `getLayers(instance)`                          | Снимок всех слоёв.                                                    |
-| `onLayers(instance, callback)`                 | Подписка на изменения слоёв; возвращает отписку.                      |
-| `refreshLayers(instance)`                      | Пере-применить волю клиента ко всем слоям.                            |
-| `getIndoorLevels(instance)`                    | Этажи, найденные в текущем виде карты.                                |
-| `setIndoorLevel(instance, level)`              | Переключить этаж (0 — первый наземный).                               |
-| `refreshIndoor(instance)`                      | Перечитать планы этажей.                                              |
-| `showPlace(instance, lon, lat, level?, zoom?)` | Показать объект и открыть его этаж.                                   |
-| `onBuildingClick(instance, callback)`          | Клик по зданию.                                                       |
-| `selectBuilding(instance, id, style?)`         | Выделить здание по `osm_id`.                                          |
-| `clearSelection(instance)`                     | Снять выделение.                                                      |
-| `selectedBuilding(instance)`                   | Идентификатор выделенного здания или `null`.                          |
-| `setSelectionStyle(instance, style)`           | Облик выделения.                                                      |
-| `onRoadClick(instance, callback)`              | Клик по дороге.                                                       |
-| `roadAt(instance, point, tolPx?)`              | Дорога под точкой холста.                                             |
-| `onParkingHover(instance, callback \| null)`   | Парковка под курсором (только при смене участка).                     |
-| `setParkingHoverStyle(instance, style)`        | Облик подсветки парковки.                                             |
-| `setParkingHoverEnabled(instance, enabled)`    | Вкл/выкл наведение на парковки, не теряя подписку.                    |
-| `hoverParking(instance, id \| null)`           | Подсветить парковку программно по `osm_id`.                           |
-| `hoveredParking(instance)`                     | `osm_id` подсвеченной парковки или `null`.                            |
-| `onParkingClick(instance, callback \| null)`   | Клик по парковке.                                                     |
-| `parkingAt(instance, point, tolPx?)`           | Справка о парковке под точкой холста.                                 |
-| `onBuildingHover(instance, cb)`               | Подписка на наведение (Maps3D 0.8.0); `null` отписывает.              |
-| `setHoverStyle(instance, style)`              | Облик наведения, включая CSS-курсор.                                  |
-| `setHoverEnabled(instance, on)`               | Вкл/выкл наведение, не трогая подписку.                               |
-| `hoverBuilding(instance, id)`                 | Навести на здание программно; `null` снимает.                         |
-| `hoveredBuilding(instance)`                   | Дом под наведением или `null`.                                        |
-| `destroy(instance)`                            | Полностью удаляет карту.                                              |
-| `loadKeyFromScriptUrl()`                       | Читает `apikey` из URL SDK скрипта.                                   |
-| `loadLanguageFromScriptUrl()`                  | Читает `lang` из URL SDK скрипта.                                     |
-## CameraController
-`CameraController` доступен через `map.getCamera()` или `MahalMap.getCamera(map)`.
-### `camera.setZoom(zoom, smooth?)`
-Меняет zoom. Если `smooth` не передан, используется плавная анимация.
-```ts
-camera.setZoom(14);
-camera.setZoom(10, false);
-```
-### `camera.setBearing(bearing, smooth?)`
-Меняет поворот карты.
-```ts
-camera.setBearing(45);
-camera.setBearing(0, false);
-```
-### `camera.setPitch(pitch, smooth?)`
-Меняет наклон карты.
-```ts
-camera.setPitch(60);
-camera.setPitch(0, false);
-```
-### `camera.toggle3D(is3D)`
-Включает или выключает 3D-вид.
-```ts
-camera.toggle3D(true);
-camera.toggle3D(false);
-```
-При включении задается `pitch: 60`, при выключении `pitch: 0` и `bearing: 0`.
-### `camera.resetNorth()`
-Возвращает карту на север и сбрасывает наклон.
-```ts
-camera.resetNorth();
-```
-### `camera.flyTo(options)`
-Выполняет плавный перелет камеры. Принимает `FlyToOptions` из MapLibre GL JS.
-```ts
-camera.flyTo({
-  center: [69.624024, 40.279687],
-  zoom: 15,
-});
-```
-SDK добавляет стандартные значения `speed`, `curve` и `essential`, но переданные значения могут их переопределить.
-### `camera.getPitch()`
-Возвращает текущий наклон карты.
-```ts
-const pitch = camera.getPitch();
-```
-## MahalMapDefaultMarker
-`MahalMapDefaultMarker` - готовый маркер, который можно использовать с `map.addMarker()`.
-```ts
-import { MahalMapDefaultMarker } from "mahal_map";
-const marker = new MahalMapDefaultMarker({
-  coordinates: [69.624024, 40.279687],
-  color: "#278960",
-  draggable: true,
-  anchor: "bottom",
-});
-map.addMarker(marker);
-```
-Параметры:
-| Параметр      | Тип                | Описание                                                                |
-| ------------- | ------------------ | ----------------------------------------------------------------------- |
-| `coordinates` | `[number, number]` | Координаты маркера в формате `[lng, lat]`.                              |
-| `draggable`   | `boolean`          | Делает HTML-элемент маркера draggable.                                  |
-| `anchor`      | `string`           | Anchor MapLibre маркера.                                                |
-| `color`       | `string`           | Цвет стандартного SVG маркера или замена `fill` в пользовательском SVG. |
-| `svg`         | `string`           | Полностью пользовательский SVG.                                         |
-| `innerSvg`    | `string`           | SVG внутри стандартного маркера.                                        |
-| `innerUrl`    | `string`           | URL изображения внутри стандартного маркера.                            |
-Методы маркера:
-```ts
-marker.getElement();
-marker.getCoordinates();
-marker.isDraggable();
-marker.getAnchor();
-```
-## Несколько карт
-Каждая карта сохраняется по ключу `container`.
-```ts
-const mainMap = MahalMap.create({ container: "main" }, maplibregl);
-const miniMap = MahalMap.create({ container: "mini" }, maplibregl);
-MahalMap.getInstance("main").setZoom(14);
-MahalMap.getInstance("mini").setStyle("dark");
-```
-Если `container` не передан, ключом будет `"map"`. Для нескольких карт всегда указывайте разные контейнеры.
-## Пользовательский стиль
-Можно передать любой MapLibre style URL:
-```ts
-const map = MahalMap.create(
-  {
-    container: "map",
-    style: "https://example.com/custom-style.json",
-  },
-  maplibregl,
-);
-```
-Стиль при этом считается зафиксированным: `setStyle()` и `setLanguage()` его не подменяют.
-С переданным `Maps3D` URL всё равно проходит через `Maps3D.mapOptions()`, поэтому `transformRequest` с ключом на месте — тайлы и шрифты платформы внутри своего стиля продолжают работать.
-## Жизненный цикл
-Рекомендуемый порядок работы:
-1. Создать DOM-контейнер.
-2. Сохранить map token через `keyUtils.saveKey()` или передать `apikey` в URL browser SDK.
-3. Создать карту через `MahalMap.create()`.
-4. Дождаться загрузки через `MahalMap.onReady()`, если нужен доступ к загруженной MapLibre карте.
-5. Добавлять маркеры, менять камеру, тему или язык.
-6. Вызвать `destroy()` при удалении страницы или компонента.
-```ts
-const map = MahalMap.create({ container: "map" }, maplibregl);
-MahalMap.onReady("map", () => {
-  map.setZoom(13);
-});
-// При размонтировании:
-map.destroy();
-```
-## MeasureTool (линейка и планиметр)
-`MeasureTool` — инструмент измерения расстояния и площади прямо на карте (линейка + планиметр, как в Яндекс.Картах). Полностью самодостаточен: сам рисует точки, линии, полигон и подписи поверх MapLibre, сам обрабатывает клики/drag/удаление точек. Приложение только передает стили (цвета, иконки, подписи единиц) и слушает `onChange`.
-```ts
-import { MeasureTool } from "mahal_map";
-const map = MahalMap.getInstance("map").getMap();
-const measureTool = new MeasureTool(map, {
-  mode: "distance",
-  style: {
-    lineColor: "#278960",
-    pointColor: "#FFFFFF",
-    pointStrokeColor: "#278960",
-    fillColor: "#278960",
-    fillOpacity: 0.15,
-  },
-  labels: {
-    meters: "м",
-    kilometers: "км",
-    squareMeters: "м²",
-    squareKilometers: "км²",
-  },
-  onChange: (state) => {
-    console.log(state.mode, state.draft, state.shapes);
-  },
-  onCloseRequest: () => {
-    measureTool.stop();
-  },
-});
-measureTool.start("distance");
-```
-### Важно: цвета — реальные, не CSS-переменные
-MapLibre GL проверяет `paint`-свойства слоя и не понимает `var(--primary)` — только hex/rgb. Если в приложении цвета живут в CSS-переменных (тема light/dark), резолвьте их в реальное значение перед передачей в `style`:
-```ts
-const primary =
-  getComputedStyle(document.documentElement)
-    .getPropertyValue("--primary")
-    .trim() || "#278960";
-const measureTool = new MeasureTool(map, {
-  style: { lineColor: primary, pointStrokeColor: primary, fillColor: primary },
-});
-```
-Значения `badgeBackground`, `badgeTextColor` и другие DOM-стили бейджа — обычный CSS, туда `var(--x)` передавать можно.
-### Конструктор: `new MeasureTool(map, options?)`
-| Опция            | Тип                             | Описание                                                                                                                                                                                                                      |
-| ---------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `mode`           | `"distance" \| "area"`          | Режим по умолчанию. По умолчанию `"distance"`.                                                                                                                                                                                |
-| `sourceIdPrefix` | `string`                        | Префикс id source/layer на карте. По умолчанию генерируется уникальный (`"mahal-measure-1"`, `"mahal-measure-2"`, ...) — так несколько инструментов на одной карте не конфликтуют. Задайте явно, если нужен предсказуемый id. |
-| `style`          | `MeasureStyleOptions`           | Цвета и размеры точек/линий/заливки/бейджа.                                                                                                                                                                                   |
-| `icons`          | `MeasureIcons`                  | SVG-иконки `trash` / `close` / `check` для бейджей.                                                                                                                                                                           |
-| `labels`         | `MeasureLabels`                 | Подписи единиц: `meters`, `kilometers`, `squareMeters`, `squareKilometers`.                                                                                                                                                   |
-| `onChange`       | `(state: MeasureState) => void` | Вызывается при любом изменении: новая точка, drag, смена режима и т.д.                                                                                                                                                        |
-| `onCloseRequest` | `() => void`                    | Вызывается по клику на ✕ в бейджике активной фигуры — решение "выключить инструмент" остается за приложением.                                                                                                                 |
-### Методы
-| Метод                           | Описание                                                                                                                                                         |
-| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `start(mode?)`                  | Включает инструмент и начинает/продолжает рисование в указанном режиме.                                                                                          |
-| `stop()`                        | Выключает инструмент, прячет активный бейдж. Сохраненные фигуры остаются на карте.                                                                               |
-| `setMode(mode)`                 | Переключает режим. Если фигура уже рисуется — её точки сохраняются, меняется только тип (линия ⇄ полигон), как в Яндекс.Картах.                                  |
-| `finishDraft()`                 | Завершает текущую фигуру (если валидна — от 2 точек для линии, от 3 для полигона) и начинает новую.                                                              |
-| `removeShape(shapeId)`          | Удаляет фигуру (черновик или уже сохраненную) целиком.                                                                                                           |
-| `removePoint(shapeId, pointId)` | Удаляет одну точку фигуры.                                                                                                                                       |
-| `clearAll()`                    | Удаляет все фигуры и черновик.                                                                                                                                   |
-| `getState()`                    | Возвращает текущий `MeasureState` (снимок, без подписки).                                                                                                        |
-| `setStyleOptions(style)`        | Обновляет палитру (частично, `Partial<MeasureStyleOptions>`) без пересоздания инструмента: перекрашивает существующие слои и бейджи. Нужен при смене темы карты. |
-| `refresh()`                     | Пересоздает источники/слои и перерисовывает фигуры. Инструмент делает это сам после `setStyle()`; метод оставлен как страховка.                                  |
-| `destroy()`                     | Полностью снимает слои, обработчики и DOM-бейджи. Вызывать при размонтировании. Повторный вызов безопасен.                                                       |
-### Смена стиля карты (тема, язык)
-`map.setStyle()` — а значит и `mahalMap.setStyle('dark')`, и смена языка — применяется MapLibre диффом: все слои, добавленные в рантайме, удаляются как отсутствующие в новом стиле, и событие `style.load` при этом не эмитится. `MeasureTool` переживает это сам: он слушает `styledata` и восстанавливает источники/слои с теми же id, а `render()` создает недостающие слои при каждой отрисовке. Фигуры, черновик и `getState()` не меняются, лишних `onChange` не будет.
-Хосту делать ничего не нужно — обходы вида `map.fire('style.load')` после `setStyle()` можно убирать. Цвета за темой карты не следуют автоматически: после переключения вызовите `setStyleOptions()` с новой палитрой.
-```ts
-mahalMap.setStyle("dark");
-measureTool.setStyleOptions({
-  lineColor: "#4ADE80",
-  pointStrokeColor: "#4ADE80",
-  fillColor: "#4ADE80",
-  badgeBackground: "#19191A",
-  badgeTextColor: "#FFFFFF",
-});
-```
-### Взаимодействие на карте
-- клик по карте — добавляет точку в текущую фигуру;
-- перетаскивание существующей точки — двигает её, расстояние/площадь пересчитываются на лету;
-- правый клик по точке — удаляет её;
-- наведение на линию/ребро полигона — показывает точку-призрак прямо под курсором; зажатие мыши вставляет в этом месте новую точку и сразу тянет её (как вставка узла в Яндекс.Картах);
-- бейдж активной (незавершенной) фигуры — показывает значение и три кнопки: ✓ (завершить фигуру), 🗑 (удалить), ✕ (вызывает `onCloseRequest`);
-- у уже сохраненных фигур — постоянный мини-бейдж: только значение и 🗑 (удалить), не пропадает при рисовании следующей фигуры.
-### `MeasureState`
-```ts
-interface MeasureState {
-  active: boolean;
-  mode: "distance" | "area";
-  draft: MeasureShape | null;
-  shapes: MeasureShape[];
-}
-interface MeasureShape {
-  id: string;
-  mode: "distance" | "area";
-  points: { id: string; lngLat: [number, number] }[];
-  closed: boolean;
-  distance: number; // метры
-  area: number; // квадратные метры, 0 для линии
-}
-```
-## Сервисы поиска и маршрутов
-Сервисы работают независимо от карты: их можно вызывать без `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
+# Mahal Map
+Mahal Map - JavaScript/TypeScript SDK для работы с картой Mahal поверх MapLibre GL JS.
+Документация ниже описывает только открытые функции карты: создание карты, управление инстансами, стили, язык, камера, маркеры и browser SDK.
+## Установка
+```sh
+npm install mahal_map maplibre-gl @grammaps/maps3d-web
+```
+Обе зависимости — `peerDependencies`, в бандл `mahal_map` они не входят. Библиотека их не импортирует: MapLibre и `Maps3D` приходят снаружи, аргументами `create()` либо через `window`.
+- `maplibre-gl` (`^6.10.0`) — обязателен всегда.
+- `@grammaps/maps3d-web` (>=0.11.0 — в ней отписки у подписок, `selectedBuildingKind()`, этажи в состоянии слоя и починенный клик по зданию сверху; на сборках постарше карта работает через запасные пути, но отписка и `selectedBuildingKind` не гарантированы) — даёт стили, тайлы, объём, пробки, рельеф, планы этажей, клик по объектам. Помечен `optional`: без него карта поднимется на запасном векторном стиле, но 3D и слоёв платформы на ней не будет.
+MapLibre можно не класть в свою сборку вовсе — платформа отдаёт согласованную версию вместе с веб-воркером:
+```ts
+const maplibregl = await Maps3D.maplibre({ base: "https://navi.gram.tj" });
+```
+## Веб-воркер MapLibre
+MapLibre разбирает векторные тайлы в веб-воркере и ищет его файл рядом со своим модулем. Сборщик складывает библиотеку в общий бандл, рядом файла не оказывается, и вместо скрипта сервер отдаёт `index.html`.
+Симптом обманчивый: **карта показывает пустой фон, ошибок про карту нет**. В консоли лежит только `Uncaught SyntaxError: Unexpected token '<'` — ни слова ни про MapLibre, ни про воркер, ни про тайлы.
+`mahal_map` это распознаёт сам. Если через 8 с после создания карты не разобран ни один векторный тайл, в консоль уходит предупреждение с причиной и обоими решениями:
+```
+[MahalMap SDK] Карта пуста: ни один векторный тайл не разобран — похоже, не запустился веб-воркер MapLibre.
+```
+Проверка молчит на растровых стилях (им воркер не нужен), в фоновой вкладке (там MapLibre приостановлен) и когда фичи отрисованы. Отключается через `workerCheck: false`, своя задержка — `workerCheck: 12000`.
+### Решение 1 — взять библиотеку у платформы
+Версия согласована с Maps3D, веб-воркер приезжает вместе с ней, настраивать нечего:
+```ts
+const maplibregl = await Maps3D.maplibre({ base: "https://navi.gram.tj" });
+const map = MahalMap.create({ container: "map" }, maplibregl, Maps3D);
+```
+### Решение 2 — оставить свою сборку
+Тогда адрес воркера нужно свести с реальным файлом — и в разработке, и в собранной версии:
+```ts
+// vite.config.ts — чтобы адрес воркера совпал с файлом во время разработки
+export default defineConfig({ optimizeDeps: { exclude: ["maplibre-gl"] } });
+```
+```ts
+// в приложении — чтобы адрес совпал и в собранной версии
+import * as maplibregl from "maplibre-gl";
+import "maplibre-gl/dist/maplibre-gl.css";
+maplibregl.setWorkerUrl("/maplibre-gl-worker.mjs"); // файл скопирован в public/ из maplibre-gl/dist
+```
+> `import * as maplibregl` — не случайность: в MapLibre 6 default-экспорта нет, `import maplibregl from "maplibre-gl"` даёт `undefined`.
+## Миграция с 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
+```ts
+import * as 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");
+const map = MahalMap.create(
+  {
+    container: "map",
+    center: [68.787, 38.573],
+    zoom: 16.6,
+    theme: "light",
+  },
+  maplibregl,
+  Maps3D,
+);
+```
+Контейнер должен существовать в HTML:
+```html
+<div id="map" style="width: 100%; height: 500px"></div>
+```
+`Maps3D` — третий, необязательный аргумент: не передан — SDK возьмёт его из `window.Maps3D`. Стиль, `transformRequest` с ключом, сглаживание и подключение 3D библиотека делает сама.
+## Быстрый старт через Browser SDK
+Для browser SDK параметр `apikey` обязателен: без него карта не инициализируется.
+**MapLibre 6 поставляется только как ESM** — классической сборки `dist/maplibre-gl.js` для `<script src>` в ней больше нет. Поэтому библиотеку карты подключают модульным скриптом и передают в `create()` вторым аргументом:
+```html
+<link
+  rel="stylesheet"
+  href="https://cdn.jsdelivr.net/npm/maplibre-gl@6.10.0/dist/maplibre-gl.css"
+/>
+<script src="https://cp.mahal.tj/sdk/mahal_map.sdk.js?apikey=YOUR_MAP_API_KEY"></script>
+<div id="map" style="width: 100%; height: 500px"></div>
+<script type="module">
+  import * as maplibregl from "https://cdn.jsdelivr.net/npm/maplibre-gl@6.10.0/+esm";
+  const map = MahalMap.create(
+    {
+      container: "map",
+      center: [69.624024, 40.279687],
+      zoom: 12,
+    },
+    maplibregl,
+  );
+</script>
+```
+Через NPM язык можно передать при создании карты:
+```ts
+const map = MahalMap.create(
+  {
+    container: "map",
+    lang: "ru",
+    theme: "dark",
+  },
+  maplibregl,
+);
+```
+Через browser SDK язык можно передать в URL скрипта:
+```html
+<script src="https://cp.mahal.tj/sdk/mahal_map.sdk.js?apikey=YOUR_MAP_API_KEY&lang=ru"></script>
+```
+`lang` влияет на поиск и роутинг, но не на стиль: подписи на карте приходят из самого стиля платформы.
+## Параметры создания карты
+`MahalMap.create(options, maplibreObject?, maps3dCtor?)`
+`maps3dCtor` — импортированный конструктор `Maps3D` (третий, необязательный аргумент). Если не передан, SDK ищет его в `window.Maps3D`.
+```ts
+import type { IMaps3DLayerOptions, Maps3DThemeName } from "mahal_map";
+interface IMahalMapOptions {
+  container?: string | HTMLElement;
+  style?: string;
+  theme?: "dark" | "light";
+  lang?: "tj" | "ru";
+  center?: [number, number];
+  zoom?: number;
+  pitch?: number;
+  bearing?: number;
+  enable3D?: boolean;
+  base?: string;
+  family?: "default" | "navigator" | "mobile";
+  preset?: Maps3DThemeName | string;
+  antialias?: boolean;
+  workerCheck?: boolean | number;
+  maps3d?: Omit<IMaps3DLayerOptions, "apiKey" | "base">;
+  /** @deprecated Оставлена для совместимости, на поведение не влияет. */
+  engine?: "legacy" | "3d";
+  /** @deprecated Оставлена для совместимости, на поведение не влияет. */
+  autoAddVectorSource?: boolean;
+}
+```
+| Параметр      | Тип                                    | Описание                                                                                                                                                                            |
+| ------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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: без него тонкая геометрия (перила, мачты, ряды сидений) на отдалении рассыпается в рябь.                                  |
+| `workerCheck` | `boolean \| number`                    | Диагностика неработающего веб-воркера MapLibre через 8 с после создания карты. `false` отключает, число задаёт свою задержку в мс. См. [Веб-воркер MapLibre](#веб-воркер-maplibre). |
+| `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
+// Навигаторная тёмная тема
+MahalMap.create(
+  { container: "map", family: "navigator", theme: "dark" },
+  maplibregl,
+  Maps3D,
+);
+// Смена темы внутри того же семейства
+map.setStyle("light"); // → navigator-light
+```
+> **Миграция с 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,
+> );
+> ```
+### Без `@grammaps/maps3d-web`
+Библиотека не установлена и в `window.Maps3D` ничего нет — карта всё равно поднимется: используется запасной векторный стиль `mtile.gram.tj` с подписью `?token=`, в консоль уходит предупреждение. На такой карте нет объёма, объектов, пробок, рельефа и реестра слоёв; `setStyle()` и `setLanguage()` стиль не меняют, методы реестра возвращают пустые значения (`false`, `null`, `[]`).
+Этот путь — единственный, где ещё проверяется подписка JSApi: `createAsync()` не создаст карту, если подписки нет. С переданным `Maps3D` проверка пропускается — доступ гейтит сама платформа по `?key=`.
+### Опции `maps3d` (расширенные)
+Передаются в `MahalMap.create({ maps3d: {...} })` и уходят в `Maps3D` как есть:
+| Опция              | Тип                                                                 | По умолч. | Описание                                                             |
+| ------------------ | ------------------------------------------------------------------- | --------- | -------------------------------------------------------------------- |
+| `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`, `fillOpacity` (0.10.0+). |
+| `minZoom`          | `number`                                                            | `16`      | Зум появления объёма.                                                |
+| `lodBias`          | `number`                                                            | `1`       | `0` — всегда детальная геометрия, `1` — упрощённая вдали.            |
+| `memoryBudget`     | `number`                                                            | `30`      | Сколько 3D-моделей держать в памяти.                                 |
+| `maskReplaced`     | `boolean`                                                           | `true`    | Прятать заменённые OSM-объекты (`anchor=replace`).                   |
+| `typeReplacements` | `boolean`                                                           | `true`    | Рисовать замены по типу (`natural=tree` → 3D-дерево и т.п.).         |
+`apiKey` и `base` в `maps3d` передавать не нужно — их подставляет сам `MahalMap` из сохранённого ключа и `options.base`.
+### Реестр слоёв
+Единая дверь ко всем слоям платформы. Идентификаторы и параметры типизированы: опечатка в имени слоя или в значении параметра — ошибка компиляции, а не тихий `false` в рантайме.
+```ts
+map.setLayer("terrain", true, { mode: "on" });
+map.setLayer("traffic", true);
+map.setLayer("indoor", true, { level: 2 });
+map.setLayer("buildings", true, { detail: "facade" });
+map.getLayerState("terrain"); // снимок одного слоя или null
+map.getLayers(); // снимок всех — по нему рисуется панель слоёв
+```
+| Слой               | Параметры                                  | По умолчанию                                                           | Откуда умолчание        |
+| ------------------ | ------------------------------------------ | ---------------------------------------------------------------------- | ----------------------- |
+| `buildings`        | `detail: footprint\|volume\|roofs\|facade` | включён                                                                | зашито                  |
+| `objects`          | —                                          | включён                                                                | зашито                  |
+| `terrain`          | `mode: auto\|on\|off`                      | включён, `mode: "auto"`                                                | зашито                  |
+| `parking`          | `highlight`, `paid`, `free`, `unknown`     | включён, `{ highlight: false, paid: true, free: true, unknown: true }` | зашито                  |
+| `fuel`, `charging` | —                                          | включены                                                               | зашито                  |
+| `traffic`          | —                                          | выключен                                                               | `maps3d.traffic`        |
+| `trafficRaster`    | —                                          | выключен                                                               | `maps3d.traffic.raster` |
+| `indoor`           | `level`                                    | выключен                                                               | `maps3d.indoor`         |
+| `closures`         | —                                          | выключен                                                               | `maps3d.closures`       |
+У нижних четырёх умолчание не зашито — реестр берёт его из опций `maps3d`, переданных при создании карты. Поэтому «выключен» в таблице значит «выключен, пока вы не передали опцию», а не «выключен всегда».
+Стартовое состояние можно задать сразу при создании карты — тогда первый кадр уже правильный, без моргания:
+```ts
+MahalMap.create(
+  { container: "map", maps3d: { traffic: true, closures: true } },
+  maplibregl,
+  Maps3D,
+);
+```
+Полный список — в разделе [Опции `maps3d`](#опции-maps3d-расширенные).
+#### `wanted`, `available`, `active` — три разных вопроса
+Поля независимы, и это главная ловушка реестра:
+| Поле        | Вопрос                                            |
+| ----------- | ------------------------------------------------- |
+| `wanted`    | чего хочет приложение                             |
+| `available` | что позволяют стиль и данные                      |
+| `active`    | что нарисовано прямо сейчас (память SDK)          |
+| `rendered`  | факт со стороны карты: слой есть в стиле и не погашен |
+`rendered` появилось в Maps3D 0.8.0; у сборок постарше его нет (`undefined`). Расхождение `active !== rendered` означает, что внутренний признак SDK разошёлся с картой — это видно одной проверкой, без чтения минифицированной сборки. Сравнивать поля можно только когда `rendered` есть — иначе на старой сборке любой активный слой покажется расхождением:
+```ts
+const state = map.getLayerState("terrain");
+// rendered === undefined — Maps3D < 0.8.0, проверка недоступна
+if (state?.rendered !== undefined && state.active !== state.rendered) {
+  reportLayerMismatch(state);
+}
+```
+Слой может быть включён и при этом не нарисован — и это не ошибка:
+```ts
+map.setLayer("terrain", true); // wanted: true
+const state = map.getLayerState("terrain");
+state?.available; // false — в стиле нет ключа maps3d:terrain
+state?.active; // false — либо режим auto, а зум слишком близкий
+```
+Поэтому галочку в интерфейсе рисуют по `wanted`, а пометку «сейчас не видно» — по `active`. Проверять сразу после `setLayer()` бесполезно: тайлы ещё едут. Правильный способ — подписка.
+#### Панель слоёв: подписка и отписка
+`onLayers()` возвращает функцию отписки. Звать её обязательно — иначе колбэк переживёт компонент и будет дёргать размонтированное состояние:
+```ts
+const unsubscribe = map.onLayers((state) => {
+  console.log(state.id, state.wanted, state.available, state.active);
+});
+// при размонтировании компонента
+unsubscribe();
+```
+`map.destroy()` снимает слой Maps3D целиком, так что после него подписка всё равно мертва — но до него отписываться нужно самим.
+#### Парковки, заправки, зарядки
+`Maps3D` рисует их сам, забирая эти классы у POI-слоёв стиля. Поэтому выключение слоя убирает объекты с карты полностью, а не оставляет значок стиля.
+Подтип парковки берётся из атрибута `fee`:
+| Параметр  | Условие      |
+| --------- | ------------ |
+| `paid`    | `fee=yes`    |
+| `free`    | `fee=no`     |
+| `unknown` | атрибута нет |
+```ts
+// только платные, с подсветкой
+map.setLayer("parking", true, {
+  paid: true,
+  free: false,
+  unknown: false,
+  highlight: true,
+});
+```
+Площадные парковки рисуются тремя слоями по одной геометрии: заливка в цвете подтипа, мягкая внутренняя кромка (с z14) и волосяной кант. Цвета: янтарь — платно, зелёный — бесплатно, сланцевый — неизвестно. Размеры заданы в экранных пикселях и от зума плитки не зависят.
+Заливку включает только режим поиска — `highlight: true`. Без него подключение Maps3D облик карты не меняет. Постоянную плотность заливки вместо кривой по зуму задаёт `maps3d.places.fillOpacity`.
+Наведение, клик и справка по участку — в разделе [Парковки: наведение, клик, справка](#парковки-наведение-клик-справка).
+#### Рельеф
+`auto` показывает рельеф на обзорных зумах, `on` — всегда. Режим `on` заметно дороже по трафику и времени кадра, чем `auto`.
+```ts
+map.setLayer("terrain", true, { mode: "auto" });
+```
+#### Планы этажей
+Слой включается реестром, но одного этого мало — без переключения этажа он бесполезен:
+```ts
+map.setLayer("indoor", true);
+const levels = map.getIndoorLevels(); // этажи в текущем виде карты, [] — данных нет
+map.setIndoorLevel(1); // нумерация OSM: 0 — первый наземный
+map.refreshIndoor(); // перечитать после правки картографом
+```
+С Maps3D 0.11.0 список этажей приходит в состоянии слоя — опрашивать `getIndoorLevels()` на `idle`/`moveend` не нужно:
+```ts
+map.onLayers((state) => {
+  if (state.id !== "indoor") return;
+  renderLevelPicker(state.params.levels ?? [], state.params.level);
+});
+```
+После поиска показать найденный объект вместе с его этажом:
+```ts
+// level приходит у объектов внутри зданий; без него откроется первый этаж
+// и метка окажется в чужом зале
+map.showPlace(68.787, 38.573, place.level, 18);
+```
+#### Слой, которого нет в списке
+`setLayer()` принимает только известные идентификаторы. Если в новой сборке Maps3D появится слой, которого ещё нет в типах, — он доступен напрямую через слой, там `id` остаётся строкой:
+```ts
+map.getMaps3DLayer()?.setLayer?.("новый-слой", true);
+```
+`setLayer()` возвращает `false`, если такого слоя в подключённой сборке Maps3D нет или Maps3D не передан вовсе. После полной смены стиля волю клиента возвращает `map.refreshLayers()` — при `setStyle()` библиотека вызывает его сама.
+### 3D-здания
+`Maps3D` рисует процедурные 3D-здания (three.js) вместо плоской `fill-extrusion` стиля: фаска кромок, вертикальный градиент и базовый цвет берутся из стиля, окна — из `metadata` темы. Слой создаётся и подключается автоматически (`enable3D` по умолчанию `true`) — вручную поднимать `new Maps3D(...)` не нужно.
+Тонкая настройка облика — через сам слой, после готовности:
+```ts
+const layer = await map.whenMaps3DReady();
+const b = layer?.buildings;
+b?.setWindowStyle(7); // тип окна 0..9 (сетка, лента, curtain wall, ...)
+b?.setWindowDepth(0.85); // глубина ниши окна 0..1 (реальная геометрия вблизи)
+b?.setWindowColor("#6b9ed1");
+b?.setWindowFrameColor("#f2f2f4");
+b?.setEdgeRadius(1.2); // скругление кромок, м
+// Свет обычно НЕ задают руками — его несёт metadata стиля, сеттеры её перебивают
+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
+```
+### Выделение зданий и клик по дорогам
+Клик по зданию и клик по дороге приходят независимо: одна точка может попасть и туда, и туда — что важнее, решает приложение.
+```ts
+map.setSelectionStyle({ color: "#e23b2f", opacity: 0.55, durationMs: 300 });
+const stopBuildingClick = map.onBuildingClick((building) => {
+  if (!building) return;
+  // SDK уже подсветил его. index >= 0 — объёмный дом сцены, -1 — дом из слоя стиля
+  console.log(building.props?.osm_id, building.height, building.index);
+});
+const stopRoadClick = 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.selectedBuildingKind(); // 'scene' — объём, 'flat' — слой стиля, null — выделения нет
+map.clearSelection();
+// При размонтировании
+stopBuildingClick();
+stopRoadClick();
+// Дорога под точкой холста, допуск по умолчанию 12 px
+map.roadAt({ x: 320, y: 240 });
+map.roadsNamed; // есть ли в текущем стиле названия дорог
+```
+Подписываться можно сразу после `create()` — даже когда слой ещё не поднят (`enable3D: false`). Подписка и облик выделения запоминаются и переигрываются, как только слой появится:
+```ts
+const map = MahalMap.create({ container: "map", enable3D: false }, maplibregl, Maps3D);
+map.onBuildingClick((b) => console.log(b?.props.osm_id));
+map.setSelectionStyle({ color: "#e23b2f" });
+map.toggle3DBuildings(true); // подписка и стиль выделения уже применены к новому слою
+```
+#### Отписка
+`onBuildingClick`, `onBuildingHover`, `onRoadClick`, `onParkingHover` и `onParkingClick` возвращают функцию отписки и принимают `null`. Повторный вызов заменяет обработчик. Отписка снимает **только свою** подписку: если обработчик уже заменён следующим вызовом, она ничего не делает — отложенный вызов прежнего владельца (например, cleanup размонтированного компонента) не погасит обработчик нового. Работает и для подписки, сделанной до подъёма слоя: снятая до подъёма, она на слой не попадёт.
+```ts
+useEffect(() => map.onBuildingClick(openCard), [map]); // отписка уходит в cleanup
+```
+#### Порог зума объёма
+`getBuildingsMinZoom()` — зум, с которого поднимается объём: `maps3d.minZoom`, который `mahal_map` передал в Maps3D, либо умолчание Maps3D (`16`). В отличие от `rendered` в состоянии слоя, ответ не зависит от текущего зума.
+```ts
+const willBe3D = targetZoom >= map.getBuildingsMinZoom();
+```
+### Наведение на здание
+Требует `@grammaps/maps3d-web` **0.8.0** и старше. Подсветку и курсор рисует сам SDK — приложение задаёт облик и получает уведомления.
+```ts
+map.setHoverStyle({ color: "#6b9ed1", opacity: 0.3, cursor: "pointer" });
+map.onBuildingHover((building) => {
+  if (!building) return; // курсор ушёл с домов
+  console.log(building.props.osm_id, building.height);
+});
+```
+Колбэк приходит **только в момент смены** дома под курсором, а не на каждое движение мыши.
+Слежение включается самой подпиской: пока `onBuildingHover` не вызван, SDK курсор не трогает и сцену не разбирает. `onBuildingHover(null)` или возвращённая отписка снимает подписку и гасит подсветку.
+| Метод | Описание |
+| --- | --- |
+| `onBuildingHover(cb \| null)` | Подписка на наведение; возвращает отписку, `null` отписывает и гасит подсветку. |
+| `setHoverStyle(s)` | Облик: `color`, `opacity`, `glow`, `durationMs`, `easing`, `cursor`. `cursor: null` — не трогать курсор. |
+| `setHoverEnabled(on)` | Вкл/выкл наведение, не трогая подписку. |
+| `hoverEnabled` | Включено ли наведение сейчас. |
+| `hoverBuilding(id \| null)` | Навести программно — например, с наведения на строку списка. `false` — дома нет на карте. |
+| `hoveredBuilding()` | Идентификатор дома под наведением или `null`. |
+Слот наведения свой, отдельный от выделения: **выбор всегда главнее**, и на выбранном доме наведение не рисуется. Занимать `setSelectionStyle` ради подсветки под курсором, как приходилось до 0.8.0, больше не нужно.
+#### Наведение с элементов интерфейса
+Курсор стоит на строке списка, а не на карте:
+```ts
+row.addEventListener("mouseenter", () => map.hoverBuilding(row.dataset.osmId!));
+row.addEventListener("mouseleave", () => map.hoverBuilding(null));
+```
+Следующее движение мыши по карте перебивает программное наведение — слежение владеет слотом, пока включено.
+#### Где наведение выключают
+Там, где подсветка мешает: режим рисования на карте, открытая карточка объекта, тач-устройство без курсора.
+```ts
+map.setHoverEnabled(false); // подписка сохраняется
+```
+Цену ограничивает сам SDK: разбор не чаще раза в кадр, пропускается во время движения камеры — и от жестов, и от `jumpTo`/`easeTo` из приложения (с 0.11.0) — и не трогает сцену, пока курсор на том же доме. С 0.11.0 наведение читает пиксель из GPU асинхронно и главный поток не держит; гасить наведение на время движения карты снаружи больше не нужно.
+### Парковки: наведение, клик, справка
+> Нужен `@grammaps/maps3d-web` **0.10.0+**. На более старой сборке методы ничего не делают и возвращают пустые значения (`false`, `null`).
+>
+> Подписки `onParkingHover`/`onParkingClick` можно делать до подъёма слоя — они запоминаются и переигрываются, как у зданий. Обе возвращают отписку.
+Устроено как у зданий: приложение задаёт облик и получает уведомления, подсветку и курсор рисует SDK.
+```ts
+// Режим поиска: заливка по подтипу
+map.setLayer("parking", true, { highlight: true });
+map.setParkingHoverStyle({ opacity: 0.6, outlineWidth: 2.4, cursor: "pointer" });
+map.onParkingHover((p) => {
+  tooltip.textContent = p ? p.subtype : "";
+});
+map.onParkingClick((p) => {
+  if (!p) return;
+  openCard(p); // { id, subtype, fee, access, kind, capacity, props }
+});
+// Подсветить со строки списка и погасить
+row.onmouseenter = () => map.hoverParking(osmId);
+row.onmouseleave = () => map.hoverParking(null);
+// Справка по точке холста (e.point события карты), допуск 4 px
+map.getMap().on("contextmenu", (e) => console.log(map.parkingAt(e.point, 4)));
+```
+| Метод                              | Описание                                                                                          |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `onParkingHover(callback \| null)` | Участок под курсором либо `null`. Зовётся **только при смене участка**. Возвращает отписку; `null` — отписаться и погасить. |
+| `setParkingHoverStyle(style)`      | Облик подсветки: `color`, `opacity`, `outlineColor`, `outlineWidth`, `cursor`.                    |
+| `setParkingHoverEnabled(enabled)`  | Выключить/включить наведение, не теряя подписку.                                                  |
+| `parkingHoverEnabled`              | Геттер: включено ли наведение.                                                                    |
+| `hoverParking(id \| null)`         | Подсветить участок программно по `osm_id`; `null` — погасить. `false` — участка нет в данных.     |
+| `hoveredParking()`                 | `osm_id` подсвеченного участка или `null`.                                                        |
+| `onParkingClick(callback \| null)` | Клик по участку: справка либо `null`. Возвращает отписку; `null` вместо колбэка — отписаться.     |
+| `parkingAt(point, tolPx?)`         | Справка по точке холста. Допуск по умолчанию `0` — строго внутрь участка.                         |
+Облик подсветки (`IMaps3DParkingHoverStyle`):
+| Поле           | По умолч.    | Описание                                                                                   |
+| -------------- | ------------ | ------------------------------------------------------------------------------------------ |
+| `color`        | цвет подтипа | Цвет заливки под курсором. По умолчанию не меняется намеренно — подтип уже покрашен смыслом. |
+| `opacity`      | `0.55`       | Непрозрачность заливки под курсором.                                                       |
+| `outlineColor` | кант подтипа | Цвет канта под курсором.                                                                   |
+| `outlineWidth` | `2.2`        | Во сколько раз толще кант под курсором.                                                    |
+| `cursor`       | `"pointer"`  | CSS-курсор над парковкой; `null` — не трогать.                                             |
+Справка (`IMaps3DParkingInfo`) — ровно то, что лежит в тайле. Отсутствующий атрибут — `null`.
+| Поле       | Тип                              | Описание                                                              |
+| ---------- | -------------------------------- | --------------------------------------------------------------------- |
+| `id`       | `number \| string`               | `osm_id` участка — тот же, что принимает `hoverParking()`.            |
+| `subtype`  | `"paid" \| "free" \| "unknown"`  | Платность. `unknown` значит «не указано», а **не** «бесплатно».       |
+| `fee`      | `string \| null`                 | Исходное `fee` (`yes`/`no`).                                          |
+| `access`   | `string \| null`                 | Кому можно: `residents`, `private`, `customers`, `permissive`…        |
+| `kind`     | `string \| null`                 | OSM `parking=*`: `surface`, `multi-storey`, `underground`, `rooftop`… |
+| `capacity` | `number \| null`                 | Число мест.                                                           |
+| `props`    | `Record<string, unknown>`        | Все свойства фичи как есть.                                           |
+Поведение:
+- Попадание определяется по границе полигона, а не по расстоянию до центра.
+- Колбэк наведения вызывается при смене участка, не на каждое движение мыши. Разбор идёт не чаще раза в кадр и пропускается, пока карта движется.
+- Подписка на наведение или клик поднимает слой заливки, даже когда режим поиска выключен, — по нему идёт опрос. Красить в этом случае слой ничего не будет.
+Ограничения:
+- Графика работы нет: `opening_hours` в слое `landuse` отсутствует.
+- Названия у площадных парковок нет — оно бывает только у точек POI.
+#### Вкл/выкл 3D-здания на лету
+Переключение объём ⇄ штатные здания стиля, без пересоздания карты. Умеет поднять слой, если его не было (`enable3D: false` при создании):
+```ts
+const map = MahalMap.getInstance("map");
+map.toggle3DBuildings(false); // выкл
+map.toggle3DBuildings(true); // вкл обратно
+// статик-версия и SDK-фасад (mahal_map/sdk) работают так же
+MahalMap.toggle3DBuildings(map, false);
+```
+Штатные здания стиля прячет и возвращает сам `Maps3D` — `mahal_map` их видимость не трогает, поэтому спорить за один слой некому.
+Для переключения пользуйтесь именно `toggle3DBuildings()`: он поднимет слой, если его ещё не было (`enable3D: false` при создании), а на сборках Maps3D без реестра слоёв откатится на `setBuildingsEnabled()`.
+```ts
+map.toggle3DBuildings(false); // совместимо со всеми сборками
+```
+`map.setLayer("buildings", false)` — не замена: он ходит только в реестр и ничего не создаёт. Годится, когда вы точно знаете, что на странице Maps3D с реестром слоёв (0.7.x), и слой уже подключён.
+#### `map.whenMaps3DReady()`
+Подключение слоя асинхронное: сразу после `create()` слой уже есть, но `layer.buildings` (окна, свет, кромки) появляется только после него. Чтобы не гадать — дождитесь готовности:
+```ts
+const layer = await map.whenMaps3DReady();
+layer?.buildings?.setWindowStyle(4);
+```
+Промис резолвится в `undefined`, если `Maps3D` не передан, слой выключен (`enable3D: false`) или подключение упало — ошибка при этом уходит в `console.error`, а карта остаётся живой на штатных зданиях стиля.
+### Подключение и выключение 3D-слоя: полный пример (Vue 3)
+Кнопка-переключатель «3D ⇄ контуры», панель слоёв на живом состоянии реестра и корректная очистка при размонтировании. Слой `Maps3D` поднимает и цепляет сама библиотека — вручную `Maps3D.enhance(...)`, `transformRequest` и `attach()` писать не нужно.
+```vue
+<script setup lang="ts">
+import { computed, onBeforeUnmount, onMounted, ref, shallowRef } from "vue";
+import * as maplibregl from "maplibre-gl";
+import "maplibre-gl/dist/maplibre-gl.css";
+import { Maps3D } from "@grammaps/maps3d-web";
+import { MahalMap, keyUtils } from "mahal_map";
+import type { IMaps3DLayerState, Maps3DLayerId } from "mahal_map";
+const API_KEY = "YOUR_MAP_API_KEY";
+const mahalMap = shallowRef<MahalMap | null>(null);
+const is3dEnabled = ref(true);
+const isLayerReady = ref(false);
+// Панель слоёв рисуется по живому снимку реестра
+const layers = ref<IMaps3DLayerState[]>([]);
+let unsubscribeLayers: (() => void) | null = null;
+function toggleLayer(id: Maps3DLayerId, on: boolean) {
+  // Опечатка в id или в параметрах не скомпилируется
+  mahalMap.value?.setLayer(id, on);
+}
+const buildingModeText = computed(() =>
+  is3dEnabled.value ? "3D включено" : "Контуры",
+);
+const buildingToggleText = computed(() =>
+  is3dEnabled.value ? "Выключить 3D" : "Включить 3D",
+);
+function toggle3dBuildings() {
+  is3dEnabled.value = !is3dEnabled.value;
+  // Вкл/выкл детальных 3D-зданий: библиотека сама вернёт/спрячет плоские здания стиля.
+  mahalMap.value?.toggle3DBuildings(is3dEnabled.value);
+}
+onMounted(async () => {
+  // Токен — один на всё (стиль, тайлы, Maps3D). Отдельный apiKey слою передавать не нужно.
+  keyUtils.saveKey(API_KEY);
+  const map = MahalMap.create(
+    {
+      container: "map",
+      theme: "dark", // тема dark; "light" → тема light
+      center: [68.787, 38.573],
+      zoom: 16.6,
+      pitch: 58, // без наклона объём не виден
+      bearing: -20,
+      enable3D: true, // значение по умолчанию, когда Maps3D передан
+      maps3d: { minZoom: 16, lodBias: 0 },
+    },
+    maplibregl,
+    Maps3D,
+  );
+  mahalMap.value = map;
+  // Дожидаемся attach(): до него layer.buildings ещё нет.
+  const layer = await map.whenMaps3DReady();
+  const buildings = layer?.buildings;
+  if (!buildings) {
+    return;
+  }
+  buildings.setWindowMinZoom?.(16);
+  buildings.setWindowStyle(4);
+  buildings.setWindowDepth(0.85);
+  buildings.setWindowColor("#6b9ed1");
+  buildings.setWindowFrameColor("#f2f2f4");
+  buildings.setWindowGlow?.(0.22);
+  buildings.setEdgeRadius(1.2);
+  // Слои: стартовый снимок плюс подписка на изменения.
+  // Состояние приходит асинхронно — сразу после setLayer() проверять бесполезно.
+  layers.value = map.getLayers();
+  unsubscribeLayers = map.onLayers(() => {
+    layers.value = map.getLayers();
+  });
+  isLayerReady.value = true;
+});
+onBeforeUnmount(() => {
+  isLayerReady.value = false;
+  // Отписку снимаем сами: иначе колбэк переживёт компонент.
+  unsubscribeLayers?.();
+  unsubscribeLayers = null;
+  // destroy() сам снимает слой Maps3D и удаляет карту MapLibre.
+  mahalMap.value?.destroy();
+  mahalMap.value = null;
+});
+</script>
+<template>
+  <main class="map-page">
+    <div id="map" class="map" />
+    <section class="panel" aria-label="GramMaps 3D">
+      <span class="mode-label">{{ buildingModeText }}</span>
+      <button
+        type="button"
+        :aria-pressed="is3dEnabled"
+        :disabled="!isLayerReady"
+        @click="toggle3dBuildings"
+      >
+        {{ buildingToggleText }}
+      </button>
+      <ul class="layers">
+        <li v-for="layer in layers" :key="layer.id">
+          <label>
+            <!-- галочка по wanted: это воля приложения -->
+            <input
+              type="checkbox"
+              :checked="layer.wanted"
+              :disabled="!layer.available"
+              @change="toggleLayer(layer.id as Maps3DLayerId, !layer.wanted)"
+            />
+            {{ layer.id }}
+          </label>
+          <!-- слой включён, но не нарисован — это норма, а не ошибка -->
+          <small v-if="layer.wanted && !layer.active">сейчас не видно</small>
+          <small v-else-if="!layer.available">нет в стиле</small>
+        </li>
+      </ul>
+    </section>
+  </main>
+</template>
+<style>
+.map-page,
+.map {
+  position: absolute;
+  inset: 0;
+}
+.panel {
+  position: absolute;
+  top: 12px;
+  left: 12px;
+  z-index: 2;
+}
+</style>
+```
+Что библиотека делает за вас против ручного подключения `@grammaps/maps3d-web`:
+| Ручной код                                      | Через `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)
+Библиотеку карты проще взять у платформы: версия согласована с Maps3D, веб-воркер приезжает вместе с ней, про ESM-сборку думать не нужно.
+```html
+<script src="https://cdn.jsdelivr.net/npm/@grammaps/maps3d-web/dist/maps3d.global.js"></script>
+<script src="https://cp.mahal.tj/sdk/mahal_map.sdk.js?apikey=YOUR_MAP_API_KEY"></script>
+<div id="map" style="width: 100%; height: 500px"></div>
+<button id="toggle3d" type="button">Выключить 3D</button>
+<script type="module">
+  const maplibregl = await Maps3D.maplibre({ base: "https://navi.gram.tj" });
+  // maplibregl обязателен вторым аргументом: window.maplibregl здесь не появляется.
+  // Maps3D третьим можно не передавать — SDK возьмёт его из window.Maps3D.
+  const map = MahalMap.create(
+    {
+      container: "map",
+      theme: "dark",
+      center: [68.787, 38.573],
+      zoom: 16.6,
+      pitch: 58,
+    },
+    maplibregl,
+  );
+  let enabled = true;
+  document.getElementById("toggle3d").addEventListener("click", () => {
+    enabled = !enabled;
+    MahalMap.toggle3DBuildings(map, enabled);
+    document.getElementById("toggle3d").textContent = enabled
+      ? "Выключить 3D"
+      : "Включить 3D";
+  });
+  MahalMap.whenMaps3DReady(map).then((layer) => {
+    layer?.buildings?.setWindowStyle(4);
+  });
+</script>
+```
+### Пробки
+Через реестр слоёв:
+```ts
+map.setLayer("traffic", true);
+map.setLayer("trafficRaster", true); // растровый вариант, без клика по дороге
+```
+Тонкие настройки — через сам слой:
+```ts
+const layer = map.getMaps3DLayer();
+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?.diagnostics?.(); // рельеф, потеря контекста WebGL, счётчики зданий
+```
+Для полной остановки карты используйте только `map.destroy()` / `MahalMap.destroy(map)` — они сами вызывают `destroy()`/`remove()` у Maps3D слоя. **Не вызывайте `layer.destroy()`/`layer.remove()` напрямую**: `MahalMap` не узнает об этом и продолжит считать слой активным (внутренний `maps3dLayer` и `buildingsEnabled` разойдутся с реальностью). Нужно временно выключить только 3D-здания — используйте `map.toggle3DBuildings(false)` (см. выше).
+## MahalMap
+`MahalMap` - основной класс карты. Конструктор закрыт, карту нужно создавать через `MahalMap.create()`.
+### `MahalMap.create(options, maplibreObject?, maps3dCtor?)`
+Создает новый инстанс карты и сохраняет его по ключу `container`. Для стандартных стилей перед созданием карты должен быть сохранен map token через `keyUtils.saveKey()`. В browser SDK token читается из обязательного URL-параметра `apikey`. Третий аргумент — необязательный конструктор `Maps3D`; без него SDK использует `window.Maps3D`.
+```ts
+const map = MahalMap.create(
+  {
+    container: "map",
+    center: [69.624024, 40.279687],
+    zoom: 12,
+    theme: "light",
+    lang: "tj",
+  },
+  maplibregl,
+);
+```
+В 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 * as 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 завершил загрузку.
+```ts
+MahalMap.onReady("map", (maplibreMap) => {
+  maplibreMap.resize();
+});
+```
+`callback` получает нативный `Map` объект из MapLibre GL JS.
+### `MahalMap.getInstance(container)`
+Возвращает ранее созданный инстанс карты по ключу контейнера.
+```ts
+const map = MahalMap.getInstance("map");
+map.setZoom(14);
+```
+Если инстанс не найден, будет выброшена ошибка.
+### `MahalMap.hasInstance(container)`
+Проверяет, существует ли карта с таким ключом контейнера.
+```ts
+if (MahalMap.hasInstance("map")) {
+  const map = MahalMap.getInstance("map");
+}
+```
+### `MahalMap.removeInstance(container)`
+Удаляет инстанс из внутреннего реестра и возвращает `boolean`.
+```ts
+const removed = MahalMap.removeInstance("map");
+```
+Метод удаляет только запись из реестра. Для полного удаления карты используйте `destroy()`.
+### `MahalMap.setDefaultLanguage(lang)`
+Задает язык по умолчанию для новых карт.
+```ts
+MahalMap.setDefaultLanguage("ru");
+keyUtils.saveKey("YOUR_MAP_API_KEY");
+const map = MahalMap.create({ container: "map" }, maplibregl);
+```
+После этого новые карты без `options.lang` будут использовать русский стандартный стиль. Для `tj` или пустого значения стандартные стили будут только с `token`.
+## Методы инстанса карты
+### `map.getMap()`
+Возвращает нативный MapLibre `Map`.
+```ts
+const maplibreMap = map.getMap();
+maplibreMap.resize();
+```
+Используйте этот метод, если нужна функция MapLibre, которой нет в Mahal Map SDK.
+### `map.getCamera()`
+Возвращает `CameraController` для управления камерой.
+```ts
+const camera = map.getCamera();
+camera.flyTo({
+  center: [69.624024, 40.279687],
+  zoom: 14,
+});
+```
+### `map.setStyle(theme)`
+Переключает светлую/тёмную тему внутри выбранного `family`.
+```ts
+map.setStyle("dark"); // family: "navigator" → navigator-dark
+map.setStyle("light"); // → navigator-light
+```
+Адрес стиля строит `Maps3D.styleUrl()`. После загрузки нового стиля библиотека сама зовёт `refreshLayers()` — состояние слоёв переживает смену темы.
+Метод ничего не делает, если карта создана с явным `style` или `preset` (стиль зафиксирован), либо если `Maps3D` не передан — у запасного стиля вариантов по теме нет.
+### `map.setLanguage(lang)`
+Запоминает язык для поиска и роутинга.
+```ts
+map.setLanguage("ru");
+map.setLanguage("tj");
+```
+Стиль метод не трогает: подписи приходят из самого стиля платформы, отдельных URL по языкам больше нет.
+### `map.setCenter(center)`
+Меняет центр карты.
+```ts
+map.setCenter([69.624024, 40.279687]);
+```
+Формат координат: `[lng, lat]`.
+### `map.setZoom(zoom)`
+Меняет zoom карты.
+```ts
+map.setZoom(13);
+```
+### `map.addMarker(marker)`
+Добавляет маркер на карту.
+```ts
+import { MahalMapDefaultMarker } from "mahal_map";
+const marker = new MahalMapDefaultMarker({
+  coordinates: [69.624024, 40.279687],
+  color: "#278960",
+});
+map.addMarker(marker);
+```
+Маркер должен реализовать интерфейс:
+```ts
+interface IMapMarker {
+  getElement(): HTMLElement;
+  getCoordinates(): [number, number];
+  isDraggable?(): boolean;
+  getAnchor?():
+    | "center"
+    | "top"
+    | "bottom"
+    | "left"
+    | "right"
+    | "top-left"
+    | "top-right"
+    | "bottom-left"
+    | "bottom-right";
+}
+```
+### `map.destroy()`
+Удаляет логотип SDK, вызывает `remove()` у MapLibre карты и удаляет инстанс из внутреннего реестра.
+```ts
+map.destroy();
+```
+Используйте при размонтировании страницы или компонента.
+## Статические методы-обертки
+Для browser SDK и случаев, когда удобнее работать с функциями, доступны статические методы:
+```ts
+MahalMap.getMap(map);
+MahalMap.getCamera(map);
+MahalMap.setStyle(map, "dark");
+MahalMap.setLanguage(map, "ru");
+MahalMap.setCenter(map, [69.624024, 40.279687]);
+MahalMap.setZoom(map, 14);
+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.getIndoorLevels(map);
+MahalMap.setIndoorLevel(map, 1);
+MahalMap.refreshIndoor(map);
+MahalMap.showPlace(map, 68.787, 38.573, 2, 18);
+// Выделение зданий и клики
+MahalMap.onBuildingClick(map, (building) => console.log(building?.id));
+MahalMap.selectBuilding(map, 123456789);
+MahalMap.selectedBuilding(map);
+MahalMap.selectedBuildingKind(map);
+MahalMap.getBuildingsMinZoom(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.setParkingHoverStyle(map, { opacity: 0.6, outlineWidth: 2.4 });
+MahalMap.onParkingHover(map, (p) => console.log(p?.subtype));
+MahalMap.setParkingHoverEnabled(map, false);
+MahalMap.hoverParking(map, 123456789);
+MahalMap.hoveredParking(map);
+MahalMap.onParkingClick(map, (p) => console.log(p?.id));
+MahalMap.parkingAt(map, { x: 320, y: 240 }, 4);
+// Наведение на здание (Maps3D 0.8.0)
+MahalMap.onBuildingHover(map, (b) => console.log(b?.id));
+MahalMap.setHoverStyle(map, { color: "#6b9ed1", cursor: "pointer" });
+MahalMap.setHoverEnabled(map, false);
+MahalMap.hoverBuilding(map, 123456789);
+MahalMap.hoveredBuilding(map);
+MahalMap.destroy(map);
+```
+Эти методы вызывают соответствующие методы переданного инстанса.
+## Browser SDK функции
+При подключении `mahal_map.sdk.js` функции доступны на глобальном объекте `MahalMap`.
+```js
+const map = MahalMap.create({
+  container: "map",
+  center: [69.624024, 40.279687],
+  zoom: 12,
+});
+MahalMap.setStyle(map, "dark");
+MahalMap.setLanguage(map, "ru");
+MahalMap.setZoom(map, 14);
+```
+Доступные функции карты в browser SDK:
+| Функция                                        | Описание                                                              |
+| ---------------------------------------------- | --------------------------------------------------------------------- |
+| `create(options)`                              | Создает карту. Требует `apikey` в URL SDK скрипта.                    |
+| `createAsync(options)`                         | Создает карту после проверки подписки JSApi (только без Maps3D).      |
+| `onReady(container, callback)`                 | Выполняет callback после загрузки карты.                              |
+| `getInstance(container)`                       | Возвращает инстанс карты.                                             |
+| `hasInstance(container)`                       | Проверяет наличие инстанса.                                           |
+| `removeInstance(container)`                    | Удаляет инстанс из реестра.                                           |
+| `getMap(instance)`                             | Возвращает нативный MapLibre Map.                                     |
+| `getCamera(instance)`                          | Возвращает CameraController.                                          |
+| `setStyle(instance, theme)`                    | Переключает тему стандартного стиля.                                  |
+| `setLanguage(instance, lang)`                  | Переключает язык стандартного стиля.                                  |
+| `setCenter(instance, center)`                  | Меняет центр карты.                                                   |
+| `setZoom(instance, zoom)`                      | Меняет zoom карты.                                                    |
+| `addMarker(instance, marker)`                  | Добавляет маркер.                                                     |
+| `getMaps3DLayer(instance)`                     | Возвращает инстанс слоя Maps3D (`undefined`, если Maps3D не передан). |
+| `whenMaps3DReady(instance)`                    | Промис слоя Maps3D после `attach()` (готов `layer.buildings`).        |
+| `toggle3DBuildings(instance, enabled)`         | Вкл/выкл объёмные здания на лету.                                     |
+| `setLayer(instance, id, on, params?)`          | Включить/выключить слой платформы.                                    |
+| `getLayerState(instance, id)`                  | Снимок состояния одного слоя.                                         |
+| `getLayers(instance)`                          | Снимок всех слоёв.                                                    |
+| `onLayers(instance, callback)`                 | Подписка на изменения слоёв; возвращает отписку.                      |
+| `refreshLayers(instance)`                      | Пере-применить волю клиента ко всем слоям.                            |
+| `getIndoorLevels(instance)`                    | Этажи в текущем виде карты (с 0.11.0 — из `params.levels` слоя).      |
+| `setIndoorLevel(instance, level)`              | Переключить этаж (0 — первый наземный).                               |
+| `refreshIndoor(instance)`                      | Перечитать планы этажей.                                              |
+| `showPlace(instance, lon, lat, level?, zoom?)` | Показать объект и открыть его этаж.                                   |
+| `onBuildingClick(instance, callback \| null)`  | Клик по зданию; возвращает отписку.                                   |
+| `selectBuilding(instance, id, style?)`         | Выделить здание по `osm_id`.                                          |
+| `clearSelection(instance)`                     | Снять выделение.                                                      |
+| `selectedBuilding(instance)`                   | Идентификатор выделенного здания или `null`.                          |
+| `selectedBuildingKind(instance)`               | `'scene'` / `'flat'` / `null` — чем нарисовано выделение.             |
+| `getBuildingsMinZoom(instance)`                | Зум появления объёма, переданный в Maps3D (по умолчанию `16`).        |
+| `setSelectionStyle(instance, style)`           | Облик выделения.                                                      |
+| `onRoadClick(instance, callback \| null)`      | Клик по дороге; возвращает отписку.                                   |
+| `roadAt(instance, point, tolPx?)`              | Дорога под точкой холста.                                             |
+| `onParkingHover(instance, callback \| null)`   | Парковка под курсором (только при смене участка).                     |
+| `setParkingHoverStyle(instance, style)`        | Облик подсветки парковки.                                             |
+| `setParkingHoverEnabled(instance, enabled)`    | Вкл/выкл наведение на парковки, не теряя подписку.                    |
+| `hoverParking(instance, id \| null)`           | Подсветить парковку программно по `osm_id`.                           |
+| `hoveredParking(instance)`                     | `osm_id` подсвеченной парковки или `null`.                            |
+| `onParkingClick(instance, callback \| null)`   | Клик по парковке.                                                     |
+| `parkingAt(instance, point, tolPx?)`           | Справка о парковке под точкой холста.                                 |
+| `onBuildingHover(instance, cb)`               | Подписка на наведение (Maps3D 0.8.0); `null` отписывает.              |
+| `setHoverStyle(instance, style)`              | Облик наведения, включая CSS-курсор.                                  |
+| `setHoverEnabled(instance, on)`               | Вкл/выкл наведение, не трогая подписку.                               |
+| `hoverBuilding(instance, id)`                 | Навести на здание программно; `null` снимает.                         |
+| `hoveredBuilding(instance)`                   | Дом под наведением или `null`.                                        |
+| `destroy(instance)`                            | Полностью удаляет карту.                                              |
+| `loadKeyFromScriptUrl()`                       | Читает `apikey` из URL SDK скрипта.                                   |
+| `loadLanguageFromScriptUrl()`                  | Читает `lang` из URL SDK скрипта.                                     |
+## CameraController
+`CameraController` доступен через `map.getCamera()` или `MahalMap.getCamera(map)`.
+### `camera.setZoom(zoom, smooth?)`
+Меняет zoom. Если `smooth` не передан, используется плавная анимация.
+```ts
+camera.setZoom(14);
+camera.setZoom(10, false);
+```
+### `camera.setBearing(bearing, smooth?)`
+Меняет поворот карты.
+```ts
+camera.setBearing(45);
+camera.setBearing(0, false);
+```
+### `camera.setPitch(pitch, smooth?)`
+Меняет наклон карты.
+```ts
+camera.setPitch(60);
+camera.setPitch(0, false);
+```
+### `camera.toggle3D(is3D)`
+Включает или выключает 3D-вид.
+```ts
+camera.toggle3D(true);
+camera.toggle3D(false);
+```
+При включении задается `pitch: 60`, при выключении `pitch: 0` и `bearing: 0`.
+### `camera.resetNorth()`
+Возвращает карту на север и сбрасывает наклон.
+```ts
+camera.resetNorth();
+```
+### `camera.flyTo(options)`
+Выполняет плавный перелет камеры. Принимает `FlyToOptions` из MapLibre GL JS.
+```ts
+camera.flyTo({
+  center: [69.624024, 40.279687],
+  zoom: 15,
+});
+```
+SDK добавляет стандартные значения `speed`, `curve` и `essential`, но переданные значения могут их переопределить.
+### `camera.getPitch()`
+Возвращает текущий наклон карты.
+```ts
+const pitch = camera.getPitch();
+```
+## MahalMapDefaultMarker
+`MahalMapDefaultMarker` - готовый маркер, который можно использовать с `map.addMarker()`.
+```ts
+import { MahalMapDefaultMarker } from "mahal_map";
+const marker = new MahalMapDefaultMarker({
+  coordinates: [69.624024, 40.279687],
+  color: "#278960",
+  draggable: true,
+  anchor: "bottom",
+});
+map.addMarker(marker);
+```
+Параметры:
+| Параметр      | Тип                | Описание                                                                |
+| ------------- | ------------------ | ----------------------------------------------------------------------- |
+| `coordinates` | `[number, number]` | Координаты маркера в формате `[lng, lat]`.                              |
+| `draggable`   | `boolean`          | Маркер можно перетаскивать на карте (слушайте `dragend` у результата `addMarker()`). |
+| `anchor`      | `string`           | Anchor MapLibre маркера.                                                |
+| `color`       | `string`           | Цвет стандартного SVG маркера или замена `fill` в пользовательском SVG. |
+| `svg`         | `string`           | Полностью пользовательский SVG.                                         |
+| `innerSvg`    | `string`           | SVG внутри стандартного маркера.                                        |
+| `innerUrl`    | `string`           | URL изображения внутри стандартного маркера.                            |
+Методы маркера:
+```ts
+marker.getElement();
+marker.getCoordinates();
+marker.isDraggable();
+marker.getAnchor();
+```
+## Несколько карт
+Каждая карта сохраняется по ключу `container`.
+```ts
+const mainMap = MahalMap.create({ container: "main" }, maplibregl);
+const miniMap = MahalMap.create({ container: "mini" }, maplibregl);
+MahalMap.getInstance("main").setZoom(14);
+MahalMap.getInstance("mini").setStyle("dark");
+```
+Если `container` не передан, ключом будет `"map"`. Для нескольких карт всегда указывайте разные контейнеры.
+## Пользовательский стиль
+Можно передать любой MapLibre style URL:
+```ts
+const map = MahalMap.create(
+  {
+    container: "map",
+    style: "https://example.com/custom-style.json",
+  },
+  maplibregl,
+);
+```
+Стиль при этом считается зафиксированным: `setStyle()` и `setLanguage()` его не подменяют.
+С переданным `Maps3D` URL всё равно проходит через `Maps3D.mapOptions()`, поэтому `transformRequest` с ключом на месте — тайлы и шрифты платформы внутри своего стиля продолжают работать.
+## Жизненный цикл
+Рекомендуемый порядок работы:
+1. Создать DOM-контейнер.
+2. Сохранить map token через `keyUtils.saveKey()` или передать `apikey` в URL browser SDK.
+3. Создать карту через `MahalMap.create()`.
+4. Дождаться загрузки через `MahalMap.onReady()`, если нужен доступ к загруженной MapLibre карте.
+5. Добавлять маркеры, менять камеру, тему или язык.
+6. Вызвать `destroy()` при удалении страницы или компонента.
+```ts
+const map = MahalMap.create({ container: "map" }, maplibregl);
+MahalMap.onReady("map", () => {
+  map.setZoom(13);
+});
+// При размонтировании:
+map.destroy();
+```
+## MeasureTool (линейка и планиметр)
+`MeasureTool` — инструмент измерения расстояния и площади прямо на карте (линейка + планиметр, как в Яндекс.Картах). Полностью самодостаточен: сам рисует точки, линии, полигон и подписи поверх MapLibre, сам обрабатывает клики/drag/удаление точек. Приложение только передает стили (цвета, иконки, подписи единиц) и слушает `onChange`.
+```ts
+import { MeasureTool } from "mahal_map";
+const map = MahalMap.getInstance("map").getMap();
+const measureTool = new MeasureTool(map, {
+  mode: "distance",
+  style: {
+    lineColor: "#278960",
+    pointColor: "#FFFFFF",
+    pointStrokeColor: "#278960",
+    fillColor: "#278960",
+    fillOpacity: 0.15,
+  },
+  labels: {
+    meters: "м",
+    kilometers: "км",
+    squareMeters: "м²",
+    squareKilometers: "км²",
+  },
+  onChange: (state) => {
+    console.log(state.mode, state.draft, state.shapes);
+  },
+  onCloseRequest: () => {
+    measureTool.stop();
+  },
+});
+measureTool.start("distance");
+```
+### Важно: цвета — реальные, не CSS-переменные
+MapLibre GL проверяет `paint`-свойства слоя и не понимает `var(--primary)` — только hex/rgb. Если в приложении цвета живут в CSS-переменных (тема light/dark), резолвьте их в реальное значение перед передачей в `style`:
+```ts
+const primary =
+  getComputedStyle(document.documentElement)
+    .getPropertyValue("--primary")
+    .trim() || "#278960";
+const measureTool = new MeasureTool(map, {
+  style: { lineColor: primary, pointStrokeColor: primary, fillColor: primary },
+});
+```
+Значения `badgeBackground`, `badgeTextColor` и другие DOM-стили бейджа — обычный CSS, туда `var(--x)` передавать можно.
+### Конструктор: `new MeasureTool(map, options?)`
+| Опция            | Тип                             | Описание                                                                                                                                                                                                                      |
+| ---------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mode`           | `"distance" \| "area"`          | Режим по умолчанию. По умолчанию `"distance"`.                                                                                                                                                                                |
+| `sourceIdPrefix` | `string`                        | Префикс id source/layer на карте. По умолчанию генерируется уникальный (`"mahal-measure-1"`, `"mahal-measure-2"`, ...) — так несколько инструментов на одной карте не конфликтуют. Задайте явно, если нужен предсказуемый id. |
+| `style`          | `MeasureStyleOptions`           | Цвета и размеры точек/линий/заливки/бейджа.                                                                                                                                                                                   |
+| `icons`          | `MeasureIcons`                  | SVG-иконки `trash` / `close` / `check` для бейджей.                                                                                                                                                                           |
+| `labels`         | `MeasureLabels`                 | Подписи единиц: `meters`, `kilometers`, `squareMeters`, `squareKilometers`.                                                                                                                                                   |
+| `onChange`       | `(state: MeasureState) => void` | Вызывается при любом изменении: новая точка, drag, смена режима и т.д.                                                                                                                                                        |
+| `onCloseRequest` | `() => void`                    | Вызывается по клику на ✕ в бейджике активной фигуры — решение "выключить инструмент" остается за приложением.                                                                                                                 |
+### Методы
+| Метод                           | Описание                                                                                                                                                         |
+| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `start(mode?)`                  | Включает инструмент и начинает/продолжает рисование в указанном режиме.                                                                                          |
+| `stop()`                        | Выключает инструмент, прячет активный бейдж. Сохраненные фигуры остаются на карте.                                                                               |
+| `setMode(mode)`                 | Переключает режим. Если фигура уже рисуется — её точки сохраняются, меняется только тип (линия ⇄ полигон), как в Яндекс.Картах.                                  |
+| `finishDraft()`                 | Завершает текущую фигуру (если валидна — от 2 точек для линии, от 3 для полигона) и начинает новую.                                                              |
+| `removeShape(shapeId)`          | Удаляет фигуру (черновик или уже сохраненную) целиком.                                                                                                           |
+| `removePoint(shapeId, pointId)` | Удаляет одну точку фигуры.                                                                                                                                       |
+| `clearAll()`                    | Удаляет все фигуры и черновик.                                                                                                                                   |
+| `getState()`                    | Возвращает текущий `MeasureState` (снимок, без подписки).                                                                                                        |
+| `setStyleOptions(style)`        | Обновляет палитру (частично, `Partial<MeasureStyleOptions>`) без пересоздания инструмента: перекрашивает существующие слои и бейджи. Нужен при смене темы карты. |
+| `refresh()`                     | Пересоздает источники/слои и перерисовывает фигуры. Инструмент делает это сам после `setStyle()`; метод оставлен как страховка.                                  |
+| `destroy()`                     | Полностью снимает слои, обработчики и DOM-бейджи. Вызывать при размонтировании. Повторный вызов безопасен.                                                       |
+### Смена стиля карты (тема, язык)
+`map.setStyle()` — а значит и `mahalMap.setStyle('dark')`, и смена языка — применяется MapLibre диффом: все слои, добавленные в рантайме, удаляются как отсутствующие в новом стиле, и событие `style.load` при этом не эмитится. `MeasureTool` переживает это сам: он слушает `styledata` и восстанавливает источники/слои с теми же id, а `render()` создает недостающие слои при каждой отрисовке. Фигуры, черновик и `getState()` не меняются, лишних `onChange` не будет.
+Хосту делать ничего не нужно — обходы вида `map.fire('style.load')` после `setStyle()` можно убирать. Цвета за темой карты не следуют автоматически: после переключения вызовите `setStyleOptions()` с новой палитрой.
+```ts
+mahalMap.setStyle("dark");
+measureTool.setStyleOptions({
+  lineColor: "#4ADE80",
+  pointStrokeColor: "#4ADE80",
+  fillColor: "#4ADE80",
+  badgeBackground: "#19191A",
+  badgeTextColor: "#FFFFFF",
+});
+```
+### Взаимодействие на карте
+- клик по карте — добавляет точку в текущую фигуру;
+- перетаскивание существующей точки — двигает её, расстояние/площадь пересчитываются на лету;
+- правый клик по точке — удаляет её;
+- наведение на линию/ребро полигона — показывает точку-призрак прямо под курсором; зажатие мыши вставляет в этом месте новую точку и сразу тянет её (как вставка узла в Яндекс.Картах);
+- бейдж активной (незавершенной) фигуры — показывает значение и три кнопки: ✓ (завершить фигуру), 🗑 (удалить), ✕ (вызывает `onCloseRequest`);
+- у уже сохраненных фигур — постоянный мини-бейдж: только значение и 🗑 (удалить), не пропадает при рисовании следующей фигуры.
+### `MeasureState`
+```ts
+interface MeasureState {
+  active: boolean;
+  mode: "distance" | "area";
+  draft: MeasureShape | null;
+  shapes: MeasureShape[];
+}
+interface MeasureShape {
+  id: string;
+  mode: "distance" | "area";
+  points: { id: string; lngLat: [number, number] }[];
+  closed: boolean;
+  distance: number; // метры
+  area: number; // квадратные метры, 0 для линии
+}
+```
+## Сервисы поиска и маршрутов
+Сервисы работают независимо от карты: их можно вызывать без `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`           | нет          |
+Возвращает тело ответа целиком — `IResponse<ISearchResponse[]>`: объекты рядом с точкой
+(адреса и POI), по возрастанию `distance` в метрах.
+```ts
+const { data } = await SearchByLocation({ lat: 40.2808, lng: 69.6248, token });
+const house = data.find((item) => item.type.toLowerCase() === "address");
+if (house && !Array.isArray(house.detailAddress)) {
+  const { city, street_type, street_name, number } = house.detailAddress;
+  // "Хуҷанд", "кӯчаи", "Камоли Хуҷандӣ", "162/1"
+}
+```
+- `type` приходит в разном регистре (`"Address"`, `"poi"`) — сравнивайте через `toLowerCase()`.
+- Город — в `detailAddress.city` (`city_type`: `шаҳр`). Района в ответе обратного геокодинга нет.
+- Любое поле `detailAddress` может отсутствовать, в том числе `number`.
+- Пустой `detailAddress` приходит массивом `[]`.
+### `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