mahal_map 1.7.3 → 2.0.0

package/README.md

@@ -1,1200 +1,1342 @@
-# Mahal Map
-
-Mahal Map - JavaScript/TypeScript SDK для работы с картой Mahal поверх MapLibre GL JS.
-
-Документация ниже описывает только открытые функции карты: создание карты, управление инстансами, стили, язык, камера, маркеры и browser SDK.
-
-## Установка
-
-```sh
-npm install mahal_map maplibre-gl
-```
-
-`maplibre-gl` является peer dependency. Его нужно установить в приложении или подключить отдельным browser script перед SDK.
-
-`@grammaps/maps3d-web` объявлен peer dependency пакета (в `package.json` помечен как `optional` — без него `engine: "legacy"` работает как обычно). Для `engine: "3d"` он обязателен в рантайме: установите его явно.
-
-```sh
-npm i mahal_map maplibre-gl @grammaps/maps3d-web
-```
-
-## Быстрый старт через NPM
-
-```ts
-import maplibregl from "maplibre-gl";
-import "maplibre-gl/dist/maplibre-gl.css";
-import { MahalMap, keyUtils } from "mahal_map";
-
-keyUtils.saveKey("YOUR_MAP_API_KEY");
-
-const map = MahalMap.create(
-  {
-    container: "map",
-    center: [69.624024, 40.279687],
-    zoom: 12,
-    theme: "light",
-  },
-  maplibregl,
-);
-```
-
-Контейнер должен существовать в HTML:
-
-```html
-<div id="map" style="width: 100%; height: 500px"></div>
-```
-
-## Быстрый старт через Browser SDK
-
-Сначала подключите MapLibre, затем `mahal_map.sdk.js`. Для browser SDK параметр `apikey` обязателен: без него карта не инициализируется.
-
-```html
-<link
-  rel="stylesheet"
-  href="https://unpkg.com/maplibre-gl@5.3.0/dist/maplibre-gl.css"
-/>
-<script src="https://unpkg.com/maplibre-gl@5.3.0/dist/maplibre-gl.js"></script>
-<script src="https://cp.mahal.tj/sdk/mahal_map.sdk.js?apikey=YOUR_MAP_API_KEY"></script>
-```
-
-После этого глобальный объект `MahalMap` доступен в `window`:
-
-```html
-<div id="map" style="width: 100%; height: 500px"></div>
-
-<script>
-  const map = MahalMap.create({
-    container: "map",
-    center: [69.624024, 40.279687],
-    zoom: 12,
-  });
-</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` не передан или передан `lang=tj`, SDK добавляет только `token`.
-
-## Параметры создания карты
-
-`MahalMap.create(options, maplibreObject?, maps3dCtor?)`
-
-`maps3dCtor` — импортированный конструктор `Maps3D` (третий, необязательный аргумент). Если не передан, SDK ищет его в `window.Maps3D`.
-
-```ts
-import type { IMaps3DLayerOptions } 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;
-  autoAddVectorSource?: boolean;
-  engine?: "legacy" | "3d";
-  enable3D?: boolean;
-  base?: string;
-  preset?: string;
-  maps3d?: Omit<IMaps3DLayerOptions, "apiKey" | "base" | "buildings">;
-}
-```
-
-| Параметр              | Тип                     | Описание                                                                                                                                                              |
-| --------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `container`           | `string \| HTMLElement` | ID контейнера или DOM-элемент. Если не передан, используется `"map"`.                                                                                                 |
-| `style`               | `string`                | Пользовательский URL стиля MapLibre. Если передан, `theme`, `lang` и map token не меняют URL стиля.                                                                   |
-| `theme`               | `"dark" \| "light"`     | Тема стандартного стиля. По умолчанию используется `light`.                                                                                                           |
-| `lang`                | `"tj" \| "ru"`          | Язык стандартного стиля. `tj` оставляет URL только с `token`, `ru` добавляет `lang=ru`.                                                                               |
-| `center`              | `[number, number]`      | Центр карты в формате `[lng, lat]`.                                                                                                                                   |
-| `zoom`                | `number`                | Начальный zoom.                                                                                                                                                       |
-| `pitch`               | `number`                | Начальный наклон камеры (нужен для 3D-вида). Если не задан и `enable3D` включен — авто `58` (при `pitch: 0` экструзия зданий не видна, камера смотрит строго сверху). |
-| `bearing`             | `number`                | Начальный поворот камеры.                                                                                                                                             |
-| `autoAddVectorSource` | `boolean`               | Использует встроенный vector style и блокирует смену стандартного стиля через `setStyle`.                                                                             |
-| `engine`              | `"legacy" \| "3d"`      | Переключатель движка карты. `"legacy"` (по умолчанию) — старые стили mtile.gram.tj. `"3d"` — новая платформа GramMaps (navi.gram.tj) с пресетами стиля и Maps3D.      |
-| `enable3D`            | `boolean`               | Подключает детальные 3D-здания (Maps3D). Работает только при `engine: "3d"`. По умолчанию `true` для `engine: "3d"` — передайте `false`, чтобы отключить.             |
-| `base`                | `string`                | Домен платформы GramMaps для `engine: "3d"`. По умолчанию `https://navi.gram.tj`.                                                                                     |
-| `preset`              | `string`                | Имя пресета стиля GramMaps (напр. `"standard-night"`) для `engine: "3d"`. По умолчанию `road-urban-lab-v2`/`standard-night` в зависимости от `theme`.                 |
-| `maps3d`              | `object`                | Доп. опции Maps3D слоя: `traffic`, `minZoom`, `lodBias`, `memoryBudget`, `maskReplaced`, `typeReplacements`.                                                          |
-
-### Новый 3D-движок (GramMaps / Maps3D)
-
-Токен передается как обычно, через `keyUtils.saveKey()` — отдельно ключ для Maps3D передавать не нужно.
-
-```ts
-import maplibregl from "maplibre-gl";
-import "maplibre-gl/dist/maplibre-gl.css";
-import { Maps3D } from "@grammaps/maps3d-web";
-import { MahalMap, keyUtils } from "mahal_map";
-
-keyUtils.saveKey("YOUR_MAP_API_KEY");
-
-const map = MahalMap.create(
-  {
-    container: "map",
-    center: [68.78, 38.56],
-    zoom: 16.6,
-    pitch: 58,
-    theme: "dark",
-    engine: "3d",
-    enable3D: true,
-  },
-  maplibregl,
-  Maps3D,
-);
-```
-
-`Maps3D` (третий аргумент `create()`) — опционален: если не передан, SDK попробует взять его из `window.Maps3D`. `@grammaps/maps3d-web` — необязательный peer dependency, ставится только если используется `engine: "3d"`.
-
-Получить слой Maps3D после создания карты:
-
-```ts
-const layer = map.getMaps3DLayer();
-// или
-MahalMap.getMaps3DLayer(map);
-```
-
-`getMaps3DLayer()` возвращает реальный инстанс `Maps3D` (не обёртку) — типы `mahal_map` описывают всю его публичную поверхность, так что подключающему сервису не нужно ставить или типизировать `@grammaps/maps3d-web` отдельно.
-
-### Опции `maps3d` (расширенные)
-
-Передаются в `MahalMap.create({ maps3d: {...} })` при `engine: "3d"`:
-
-| Опция              | Тип                                              | По умолч. | Описание                                                                  |
-| ------------------ | ------------------------------------------------ | --------- | ------------------------------------------------------------------------- |
-| `traffic`          | `boolean \| { raster?, rasterMaxZoom?, graph? }` | `false`   | Слой пробок. `raster: true` — картинкой с сервера вместо векторного слоя. |
-| `minZoom`          | `number`                                         | `16`      | Зум появления детальных 3D.                                               |
-| `lodBias`          | `number`                                         | `1`       | `0` — всегда lod0 (детальный), `1` — lod1 на дальних зумах.               |
-| `memoryBudget`     | `number`                                         | `30`      | Сколько моделей держать в сцене одновременно.                             |
-| `maskReplaced`     | `boolean`                                        | `true`    | Прятать заменённые OSM-объекты (`anchor=replace`).                        |
-| `typeReplacements` | `boolean`                                        | `true`    | Рисовать замены по типу (`natural=tree` → 3D-дерево и т.п.).              |
-
-`buildings: true` включается автоматически при `enable3D: true` — переопределять не нужно, если только не требуется передать сам объект опций.
-
-### 3D-здания
-
-`Maps3D` рисует процедурные 3D-здания (three.js) вместо плоской `fill-extrusion` стиля: фаска кромок, вертикальный градиент и базовый цвет берутся из стиля, окна — из `metadata` пресета. При `engine: "3d"` слой создаётся и `attach`-ится к карте автоматически (`enable3D` по умолчанию `true`) — вручную поднимать `new Maps3D(...)` не нужно, только если требуется отдельный кастомный инстанс.
-
-**Ручной `new Maps3D(...)` — отдельный сценарий.** Карту при этом создавайте с `enable3D: false`, иначе на неё повиснут два слоя Maps3D сразу (автоматический от `MahalMap` + ваш ручной) — дублирование зданий и лишний расход ресурсов:
-
-```ts
-const apiKey = "YOUR_MAP_API_KEY";
-const base = "https://navi.gram.tj";
-
-const map = MahalMap.create(
-  { container: "map", engine: "3d", enable3D: false },
-  maplibregl,
-);
-
-const layer = new Maps3D({ apiKey, base, buildings: true });
-await layer.attach(map.getMap()); // attach ждёт нативную карту MapLibre, не обёртку MahalMap
-```
-
-Тема (окна/свет) приходит из `metadata` пресета стиля и применяется автоматически при `map.setStyle()` — пересоздавать слой не нужно. Ручные сеттеры перебивают её.
-
-Это работает только для встроенных пресетов **без** явного `options.preset`: `setStyle()` меняет пресет по теме (`light`/`dark` → `GRAM_PRESETS`), а при заданном `preset` считает стиль зафиксированным и ничего не делает (см. [`MahalMap.ts`](src/core/MahalMap.ts:363)). Чтобы сменить пресет/тему в этом случае — пересоздайте карту с другим `preset` или вызовите `map.getMap().setStyle(...)` напрямую.
-
-```ts
-const layer = map.getMaps3DLayer();
-
-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);
-
-layer?.onBuildingClick((info) => {
-  if (!info) return;
-  console.log(info.id, info.height, info.props);
-});
-```
-
-#### Вкл/выкл 3D-здания на лету
-
-Переключение 3D-здания ⇄ штатные здания стиля, без пересоздания карты — через обёртку `MahalMap`. Она же умеет пересоздать слой, если его не было (`enable3D: false` при создании):
-
-```ts
-const map = MahalMap.getInstance("map");
-
-map.toggle3DBuildings(false); // выкл
-map.toggle3DBuildings(true); // вкл обратно
-
-// статик-версия и SDK-фасад (mahal_map/sdk) работают так же
-MahalMap.toggle3DBuildings(map, false);
-```
-
-`layer?.setBuildingsEnabled(false)` напрямую через слой **не используйте** — он не знает про штатный слой стиля `building-3d`, который `MahalMap` прячет при включённом 3D. Вызов только слоя оставит эти штатные здания скрытыми и одновременно выключит процедурные — в итоге зданий не будет видно вообще, до следующей перезагрузки стиля.
-
-#### `map.whenMaps3DReady()`
-
-`attach()` слоя асинхронный: сразу после `create()` слой уже есть, но `layer.buildings` (окна, свет, кромки) появляется только после attach. Чтобы не гадать — дождитесь готовности:
-
-```ts
-const layer = await map.whenMaps3DReady();
-
-layer?.buildings?.setWindowStyle(4);
-```
-
-Промис резолвится в `undefined`, если движок не `"3d"`, слой выключен (`enable3D: false`) или attach упал — ошибка при этом уходит в `console.error`, а карта остаётся живой со штатными зданиями стиля.
-
-### Подключение и выключение 3D-слоя: полный пример (Vue 3)
-
-Кнопка-переключатель «3D ⇄ контуры», тонкая настройка окон и корректная очистка при размонтировании. Слой `Maps3D` поднимает и цепляет сама библиотека — вручную `new Maps3D(...)`, `transformRequest` и `attach()` писать не нужно.
-
-```vue
-<script setup lang="ts">
-import { computed, onBeforeUnmount, onMounted, ref, shallowRef } from "vue";
-import maplibregl from "maplibre-gl";
-import "maplibre-gl/dist/maplibre-gl.css";
-import { Maps3D } from "@grammaps/maps3d-web";
-import { MahalMap, keyUtils } 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 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",
-      engine: "3d", // платформа GramMaps вместо legacy-стилей
-      theme: "dark", // preset standard-night; "light" → road-urban-lab-v2
-      center: [68.787, 38.573],
-      zoom: 16.6,
-      pitch: 58, // без наклона экструзия не видна
-      bearing: -20,
-      enable3D: true, // значение по умолчанию для engine: "3d"
-      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);
-
-  isLayerReady.value = true;
-});
-
-onBeforeUnmount(() => {
-  isLayerReady.value = false;
-  // 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>
-    </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`                                                 |
-| ----------------------------------------------- | ----------------------------------------------------------------- |
-| `style: base + "/maps/standard-night.json"`     | `engine: "3d"` + `theme` (или `preset` / `base` явно)             |
-| `transformRequest: Maps3D.transformRequest(..)` | ставится автоматически (и без Maps3D — своим фолбэком с `?key=`)  |
-| `new Maps3D({...}); await layer.attach(map)`    | `enable3D: true` + `maps3d: {...}`, `await map.whenMaps3DReady()` |
-| `setBuildingsEnabled` + `buildings.setWindows`  | `map.toggle3DBuildings(enabled)` — оба вызова разом               |
-| Плоские здания стиля поверх 3D после `setStyle` | скрываются сами на каждой загрузке стиля                          |
-| `layer.destroy(); map.remove()`                 | `map.destroy()`                                                    |
-
-#### То же самое без сборщика (browser SDK)
-
-```html
-<script src="https://unpkg.com/maplibre-gl@5.3.0/dist/maplibre-gl.js"></script>
-<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>
-  // Maps3D берётся из window.Maps3D — третий аргумент передавать не нужно.
-  const map = MahalMap.create({
-    container: "map",
-    engine: "3d",
-    theme: "dark",
-    center: [68.787, 38.573],
-    zoom: 16.6,
-    pitch: 58,
-  });
-
-  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
-const layer = map.getMaps3DLayer();
-
-layer?.setTraffic(true);
-layer?.setTrafficOpacity(0.85);
-layer?.setTrafficClicks(true); // попап скорости по клику
-layer?.refreshTraffic();
-
-// растровый вариант (картинка с сервера, без клика по дороге)
-layer?.setTrafficRaster(true);
-```
-
-### Жизненный цикл слоя
-
-```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-кеш ассетов
-```
-
-Для полной остановки карты используйте только `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);
-}
-```
-
-Правила проверки:
-
-| Условие | Поведение |
-| ------- | --------- |
-| `engine: "legacy"` (по умолчанию), сервис ответил `success: true` | Карта создаётся. |
-| `engine: "legacy"`, сервис ответил `success: false` | Карта **не** создаётся, промис отклоняется: `[MahalMap SDK] JSApi subscription is not active for this key: <message>`. |
-| `engine: "legacy"`, проверка не дошла (сеть, CORS, таймаут) | Fail-open: `console.warn` и карта создаётся. Падение сервиса проверки не гасит карты. |
-| `engine: "3d"` (GramMaps) | Проверка **пропускается**, запрос не отправляется. |
-| Map token не сохранён | Проверка пропускается, дальше срабатывает обычная ошибка про `apikey`. |
-
-`engine: "3d"` через `createAsync()` ведёт себя ровно как `create()` — доступ к платформе GramMaps контролируется параметром `?key=` на стороне самой платформы, отдельная подписка JSApi к ней отношения не имеет.
-
-Синхронный `MahalMap.create()` проверку не выполняет и работает как раньше.
-
-### Vue / Nuxt (ClientOnly, container как ref элемента)
-
-`container` принимает и `id` строкой, и сам DOM-элемент. Ниже рабочий вариант с проверкой подписки: карта строится только после `createAsync()`, поэтому при отсутствии подписки в контейнере не останется пустой карты.
-
-```vue
-<template>
-  <ClientOnly>
-    <div class="overflow-hidden rounded-2xl border">
-      <div ref="mapElement" class="h-[360px] w-full" />
-    </div>
-    <template #fallback>
-      <div class="flex h-[360px] items-center justify-center">{{ loadingLabel }}</div>
-    </template>
-  </ClientOnly>
-</template>
-
-<script setup lang="ts">
-import maplibregl from "maplibre-gl";
-import "maplibre-gl/dist/maplibre-gl.css";
-import type { MahalMap as MahalMapInstance } from "mahal_map";
-import { onBeforeUnmount, onMounted, ref } from "vue";
-
-const DUSHANBE_CENTER: [number, number] = [68.759965, 38.572419];
-
-const mapElement = ref<HTMLElement | null>(null);
-let map: MahalMapInstance | null = null;
-// onMounted асинхронный: компонент может размонтироваться, пока идёт проверка подписки.
-// Без флага карта создастся уже после unmount и останется висеть в памяти.
-let disposed = false;
-
-onMounted(async () => {
-  const { MahalMap, keyUtils } = await import("mahal_map");
-
-  keyUtils.saveKey(import.meta.env.VITE_MAHAL_API_KEY_TILE);
-
-  try {
-    const instance = await MahalMap.createAsync(
-      {
-        container: mapElement.value,
-        center: DUSHANBE_CENTER,
-        zoom: 11,
-      },
-      maplibregl,
-    );
-
-    if (disposed) {
-      instance.destroy();
-      return;
-    }
-
-    map = instance;
-  } catch (error) {
-    // подписки JSApi нет — показать своё сообщение вместо карты
-    console.error(error);
-  }
-});
-
-onBeforeUnmount(() => {
-  disposed = true;
-  map?.destroy();
-  map = null;
-});
-</script>
-```
-
-Замечания по этому паттерну:
-
-- Импорт `mahal_map` внутри `onMounted` обязателен в SSR-окружении: пакет работает с `window`/`document`.
-- `ClientOnly` (Nuxt) или эквивалент нужен по той же причине.
-- Для карты с `container` в виде элемента инстанс регистрируется под ключом по умолчанию `"map"`. Для нескольких карт на странице передавайте `container` строкой с разными `id`, иначе `getInstance()` вернёт не тот инстанс.
-- `map.destroy()` снимает карту, логотип и запись из реестра инстансов.
-- Синхронный `MahalMap.create()` в этом же коде работает без изменений — если проверка подписки не нужна, замените `await MahalMap.createAsync(...)` на `MahalMap.create(...)`.
-
-### `MahalMap.onReady(container, callback)`
-
-Вызывает `callback`, когда карта создана и MapLibre завершил загрузку.
-
-```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)`
-
-Переключает стандартную тему карты.
-
-```ts
-map.setStyle("dark");
-map.setStyle("light");
-```
-
-Если текущий язык `ru`, при переключении темы стиль будет загружен с `token=...&lang=ru`. Если язык `tj`, URL будет только с `token=...`.
-
-Метод не меняет стиль, если карта создана с `autoAddVectorSource: true`. Если карта создана с пользовательским `style`, SDK не переписывает этот URL.
-
-### `map.setLanguage(lang)`
-
-Переключает язык стандартного стиля карты.
-
-```ts
-map.setLanguage("ru");
-map.setLanguage("tj");
-```
-
-`ru` добавляет `lang=ru`, `tj` возвращает стандартный URL только с `token=...`. Метод не переписывает пользовательский `options.style` и не меняет vector style при `autoAddVectorSource: true`.
-
-### `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.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 (только legacy).  |
-| `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 (только `engine: "3d"`).       |
-| `whenMaps3DReady(instance)`            | Промис слоя Maps3D после `attach()` (готов `layer.buildings`). |
-| `toggle3DBuildings(instance, enabled)` | Вкл/выкл детальные 3D-здания на лету (только `engine: "3d"`). |
-| `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,
-);
-```
-
-Когда передан `style`, SDK не добавляет `token` или `lang=ru` и не подменяет URL при `setStyle()` или `setLanguage()`.
-
-## Жизненный цикл
-
-Рекомендуемый порядок работы:
-
-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) для legacy-карты.
-
-### `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` (3–6) — обязателен всегда.
+- `@grammaps/maps3d-web` (>=0.5.0) — даёт стили, тайлы, объём, пробки, рельеф, планы этажей, клик по объектам. Помечен `optional`: без него карта поднимется на запасном векторном стиле, но 3D и слоёв платформы на ней не будет.
+
+MapLibre можно не класть в свою сборку вовсе — платформа отдаёт согласованную версию вместе с веб-воркером:
+
+```ts
+const maplibregl = await Maps3D.maplibre({ base: "https://navi.gram.tj" });
+```
+
+## Миграция с 1.x на 2.0
+
+Собственных URL стилей у `mahal_map` больше нет — их целиком отдаёт `@grammaps/maps3d-web`.
+
+| 1.x                                            | 2.0                                                            |
+| ---------------------------------------------- | -------------------------------------------------------------- |
+| `engine: "legacy"` (по умолчанию)              | Удалён. Единственный путь — платформа через `Maps3D`.           |
+| `engine: "3d"`                                 | Больше не нужен, опция игнорируется.                            |
+| `autoAddVectorSource: true`                    | Удалён. Тот же векторный стиль применяется сам, когда нет `Maps3D`. |
+| `preset: "standard-night"`                     | `theme: "dark"`, либо полный URL в `style`.                     |
+| `preset: "road-urban-lab-v2"`                  | `theme: "light"`, либо полный URL в `style`.                    |
+| `lang` менял URL стиля                          | Стиль не трогает — язык подписей приходит из самого стиля.      |
+| `layer.setBuildingsEnabled(...)` напрямую      | `map.toggle3DBuildings(...)` или `map.setLayer("buildings", ...)`. |
+
+`engine` и `autoAddVectorSource` оставлены в типах как `@deprecated`, чтобы не ломать компиляцию, но на поведение не влияют.
+
+Что появилось: реестр слоёв (`setLayer`/`getLayers`/`onLayers`), выделение зданий, клик по дорогам, рельеф, планы этажей, перекрытия, семейства стилей `navigator`/`mobile` и автоматический `antialias`.
+
+Минимальный диф:
+
+```diff
+ const map = MahalMap.create(
+   {
+     container: "map",
+-    engine: "3d",
+     theme: "dark",
+-    preset: "standard-night",
+     enable3D: true,
+   },
+   maplibregl,
+   Maps3D,
+ );
+```
+
+## Быстрый старт через NPM
+
+```ts
+import maplibregl from "maplibre-gl";
+import "maplibre-gl/dist/maplibre-gl.css";
+import { Maps3D } from "@grammaps/maps3d-web";
+import { MahalMap, keyUtils } from "mahal_map";
+
+keyUtils.saveKey("YOUR_MAP_API_KEY");
+
+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
+
+Сначала подключите MapLibre, затем `mahal_map.sdk.js`. Для browser SDK параметр `apikey` обязателен: без него карта не инициализируется.
+
+```html
+<link
+  rel="stylesheet"
+  href="https://unpkg.com/maplibre-gl@5.3.0/dist/maplibre-gl.css"
+/>
+<script src="https://unpkg.com/maplibre-gl@5.3.0/dist/maplibre-gl.js"></script>
+<script src="https://cp.mahal.tj/sdk/mahal_map.sdk.js?apikey=YOUR_MAP_API_KEY"></script>
+```
+
+После этого глобальный объект `MahalMap` доступен в `window`:
+
+```html
+<div id="map" style="width: 100%; height: 500px"></div>
+
+<script>
+  const map = MahalMap.create({
+    container: "map",
+    center: [69.624024, 40.279687],
+    zoom: 12,
+  });
+</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` не передан или передан `lang=tj`, SDK добавляет только `token`.
+
+## Параметры создания карты
+
+`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;
+  maps3d?: Omit<IMaps3DLayerOptions, "apiKey" | "base">;
+}
+```
+
+| Параметр    | Тип                                   | Описание                                                                                                                                                  |
+| ----------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `container` | `string \| HTMLElement`               | ID контейнера или DOM-элемент. Не передан — берётся `"map"`.                                                                                              |
+| `style`     | `string`                              | Полный URL своего стиля. Задан — стиль зафиксирован, `setStyle()` его не меняет.                                                                          |
+| `theme`     | `"dark" \| "light"`                   | Светлая/тёмная внутри выбранного `family`. По умолчанию `light`.                                                                                          |
+| `lang`      | `"tj" \| "ru"`                        | Язык для поиска и роутинга. На стиль не влияет — подписи приходят из самого стиля платформы.                                                              |
+| `center`    | `[number, number]`                    | Центр карты в формате `[lng, lat]`.                                                                                                                       |
+| `zoom`      | `number`                              | Начальный zoom.                                                                                                                                           |
+| `pitch`     | `number`                              | Начальный наклон камеры. Не задан и 3D включено — авто `58`: при `pitch: 0` объём зданий не виден, камера смотрит строго сверху.                          |
+| `bearing`   | `number`                              | Начальный поворот камеры.                                                                                                                                 |
+| `enable3D`  | `boolean`                             | Подключает Maps3D. По умолчанию `true`, когда `Maps3D` доступен.                                                                                          |
+| `base`      | `string`                              | Домен платформы. По умолчанию `https://navi.gram.tj`.                                                                                                     |
+| `family`    | `"default" \| "navigator" \| "mobile"` | Семейство стилей. `theme` выбирает внутри него: `default` → `light`/`dark`, `navigator` → `navigator-light`/`navigator-dark`, `mobile` → `mobile-*`.   |
+| `preset`    | `Maps3DThemeName \| string`           | Явное имя темы платформы или полный URL стиля вместо пары `family` + `theme`. Задан — стиль зафиксирован.                                                 |
+| `antialias` | `boolean`                             | Сглаживание сцены. По умолчанию `true` при включённом 3D: без него тонкая геометрия (перила, мачты, ряды сидений) на отдалении рассыпается в рябь.        |
+| `maps3d`    | `object`                              | Опции Maps3D: `buildings`, `traffic`, `indoor`, `closures`, `places`, `minZoom`, `lodBias`, `memoryBudget`, `maskReplaced`, `typeReplacements`.           |
+
+### Стили и темы
+
+Стили целиком приходят из `@grammaps/maps3d-web` — своего списка URL у `mahal_map` больше нет. Словарь тем один и тот же у SDK и у библиотеки:
+
+| `family`      | `theme: "light"`   | `theme: "dark"`   |
+| ------------- | ------------------ | ----------------- |
+| `"default"`   | `light`            | `dark`            |
+| `"navigator"` | `navigator-light`  | `navigator-dark`  |
+| `"mobile"`    | `mobile-light`     | `mobile-dark`     |
+
+Имя темы уходит в `Maps3D.styleUrl()`, адрес строит сам SDK. Неизвестное имя — явная ошибка с префиксом `[MahalMap SDK]`, а не пустая карта.
+
+```ts
+// Навигаторная тёмная тема
+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`. |
+| `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`.
+
+### Реестр слоёв
+
+Единая дверь ко всем слоям платформы. Состояние слоя — три независимых поля: `wanted` (чего хочет приложение), `available` (что позволяют стиль и данные), `active` (что нарисовано сейчас).
+
+```ts
+map.setLayer("terrain", true, { mode: "on" });
+map.setLayer("traffic", true);
+map.setLayer("indoor", true, { level: 2 });
+
+const unsubscribe = map.onLayers((state) => {
+  console.log(state.id, state.wanted, state.available, state.active);
+});
+
+map.getLayerState("terrain"); // снимок одного слоя или null
+map.getLayers(); // снимок всех — по нему рисуется панель слоёв
+```
+
+| Слой               | Параметры                                | По умолчанию |
+| ------------------ | ---------------------------------------- | ------------ |
+| `buildings`        | `detail: footprint\|volume\|roofs\|facade` | включён    |
+| `objects`          | —                                        | включён      |
+| `traffic`          | —                                        | выключен     |
+| `trafficRaster`    | —                                        | выключен     |
+| `parking`          | `highlight`, `paid`, `free`, `unknown`   | включён      |
+| `fuel`, `charging` | —                                        | включены     |
+| `closures`         | —                                        | выключен     |
+| `indoor`           | `level`                                  | выключен     |
+| `terrain`          | `mode: auto\|on\|off`                     | `auto`       |
+
+Слой может быть включён и при этом не нарисован: рельеф в режиме `auto` появляется на обзорных зумах, перекрытия требуют своего тайлсета, планы этажей — данных по зданию. Рельеф в режиме `on` заметно дороже по трафику и времени кадра.
+
+Парковки, заправки и зарядки `Maps3D` рисует сам, забирая эти классы у POI-слоёв стиля, — поэтому выключение слоя убирает объекты с карты полностью, а не оставляет значок стиля.
+
+`setLayer()` возвращает `false`, если такого слоя в подключённой сборке Maps3D нет (или Maps3D не передан вовсе). После полной смены стиля волю клиента возвращает `map.refreshLayers()` — при `setStyle()` библиотека вызывает его сама.
+
+### 3D-здания
+
+`Maps3D` рисует процедурные 3D-здания (three.js) вместо плоской `fill-extrusion` стиля: фаска кромок, вертикальный градиент и базовый цвет берутся из стиля, окна — из `metadata` темы. Слой создаётся и подключается автоматически (`enable3D` по умолчанию `true`) — вручную поднимать `new Maps3D(...)` не нужно.
+
+Тонкая настройка облика — через сам слой, после готовности:
+
+```ts
+const layer = 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()`, до готовности карты.
+
+#### Вкл/выкл 3D-здания на лету
+
+Переключение объём ⇄ штатные здания стиля, без пересоздания карты. Умеет поднять слой, если его не было (`enable3D: false` при создании):
+
+```ts
+const map = MahalMap.getInstance("map");
+
+map.toggle3DBuildings(false); // выкл
+map.toggle3DBuildings(true); // вкл обратно
+
+// статик-версия и SDK-фасад (mahal_map/sdk) работают так же
+MahalMap.toggle3DBuildings(map, false);
+```
+
+Под капотом это `setLayer("buildings", enabled)`. Штатные здания стиля прячет и возвращает сам `Maps3D` — `mahal_map` их видимость не трогает, поэтому спорить за один слой некому. Эквивалентная запись: `map.setLayer("buildings", false)`.
+
+#### `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` поднимает и цепляет сама библиотека — вручную `new Maps3D(...)`, `transformRequest` и `attach()` писать не нужно.
+
+```vue
+<script setup lang="ts">
+import { computed, onBeforeUnmount, onMounted, ref, shallowRef } from "vue";
+import maplibregl from "maplibre-gl";
+import "maplibre-gl/dist/maplibre-gl.css";
+import { Maps3D } from "@grammaps/maps3d-web";
+import { MahalMap, keyUtils } 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 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);
+
+  isLayerReady.value = true;
+});
+
+onBeforeUnmount(() => {
+  isLayerReady.value = false;
+  // 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>
+    </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)
+
+```html
+<script src="https://unpkg.com/maplibre-gl@5.3.0/dist/maplibre-gl.js"></script>
+<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>
+  // Maps3D берётся из window.Maps3D — третий аргумент передавать не нужно.
+  const map = MahalMap.create({
+    container: "map",
+    theme: "dark",
+    center: [68.787, 38.573],
+    zoom: 16.6,
+    pitch: 58,
+  });
+
+  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 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.onBuildingClick(map, (building) => console.log(building?.id));
+MahalMap.selectBuilding(map, 123456789);
+MahalMap.selectedBuilding(map);
+MahalMap.setSelectionStyle(map, { color: "#e23b2f" });
+MahalMap.clearSelection(map);
+MahalMap.onRoadClick(map, (road) => console.log(road?.name));
+MahalMap.roadAt(map, { x: 320, y: 240 });
+
+MahalMap.destroy(map);
+```
+
+Эти методы вызывают соответствующие методы переданного инстанса.
+
+## 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)`              | Пере-применить волю клиента ко всем слоям.                    |
+| `onBuildingClick(instance, callback)`  | Клик по зданию.                                               |
+| `selectBuilding(instance, id, style?)` | Выделить здание по `osm_id`.                                  |
+| `clearSelection(instance)`             | Снять выделение.                                              |
+| `selectedBuilding(instance)`           | Идентификатор выделенного здания или `null`.                  |
+| `setSelectionStyle(instance, style)`   | Облик выделения.                                              |
+| `onRoadClick(instance, callback)`      | Клик по дороге.                                               |
+| `roadAt(instance, point, tolPx?)`      | Дорога под точкой холста.                                     |
+| `destroy(instance)`                    | Полностью удаляет карту.                                      |
+| `loadKeyFromScriptUrl()`               | Читает `apikey` из URL SDK скрипта.                           |
+| `loadLanguageFromScriptUrl()`          | Читает `lang` из URL SDK скрипта.                             |
+
+## 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