mahal_map 2.2.3 → 2.3.0

package/README.md

@@ -13,7 +13,7 @@ npm install mahal_map maplibre-gl @grammaps/maps3d-web
 Обе зависимости — `peerDependencies`, в бандл `mahal_map` они не входят. Библиотека их не импортирует: MapLibre и `Maps3D` приходят снаружи, аргументами `create()` либо через `window`.
 
 - `maplibre-gl` (`^6.10.0`) — обязателен всегда.
-- `@grammaps/maps3d-web` (>=0.5.0; рекомендуется 0.8.0 — в ней наведение на здание и починенный пикинг клика) — даёт стили, тайлы, объём, пробки, рельеф, планы этажей, клик по объектам. Помечен `optional`: без него карта поднимется на запасном векторном стиле, но 3D и слоёв платформы на ней не будет.
+- `@grammaps/maps3d-web` (>=0.11.0 — в ней отписки у подписок, `selectedBuildingKind()`, этажи в состоянии слоя и починенный клик по зданию сверху; на сборках постарше карта работает через запасные пути, но отписка и `selectedBuildingKind` не гарантированы) — даёт стили, тайлы, объём, пробки, рельеф, планы этажей, клик по объектам. Помечен `optional`: без него карта поднимется на запасном векторном стиле, но 3D и слоёв платформы на ней не будет.
 
 MapLibre можно не класть в свою сборку вовсе — платформа отдаёт согласованную версию вместе с веб-воркером:
 
@@ -427,6 +427,15 @@ map.setIndoorLevel(1); // нумерация OSM: 0 — первый назем
 map.refreshIndoor(); // перечитать после правки картографом
 ```
 
+С Maps3D 0.11.0 список этажей приходит в состоянии слоя — опрашивать `getIndoorLevels()` на `idle`/`moveend` не нужно:
+
+```ts
+map.onLayers((state) => {
+  if (state.id !== "indoor") return;
+  renderLevelPicker(state.params.levels ?? [], state.params.level);
+});
+```
+
 После поиска показать найденный объект вместе с его этажом:
 
 ```ts
@@ -492,13 +501,13 @@ await maps3d.ready; // enhance() ждёт нативную карту MapLibre,
 ```ts
 map.setSelectionStyle({ color: "#e23b2f", opacity: 0.55, durationMs: 300 });
 
-map.onBuildingClick((building) => {
+const stopBuildingClick = map.onBuildingClick((building) => {
   if (!building) return;
-  // SDK уже подсветил его
-  console.log(building.props?.osm_id, building.height);
+  // SDK уже подсветил его. index >= 0 — объёмный дом сцены, -1 — дом из слоя стиля
+  console.log(building.props?.osm_id, building.height, building.index);
 });
 
-map.onRoadClick((road) => {
+const stopRoadClick = map.onRoadClick((road) => {
   if (!road) return;
   console.log(road.nameRu ?? road.name, road.class);
 });
@@ -506,8 +515,13 @@ map.onRoadClick((road) => {
 // Выделить здание по osm_id — например, после поиска
 map.selectBuilding(123456789); // false, если здания нет в загруженных данных
 map.selectedBuilding(); // текущий id или null
+map.selectedBuildingKind(); // 'scene' — объём, 'flat' — слой стиля, null — выделения нет
 map.clearSelection();
 
+// При размонтировании
+stopBuildingClick();
+stopRoadClick();
+
 // Дорога под точкой холста, допуск по умолчанию 12 px
 map.roadAt({ x: 320, y: 240 });
 map.roadsNamed; // есть ли в текущем стиле названия дорог
@@ -524,6 +538,22 @@ map.setSelectionStyle({ color: "#e23b2f" });
 map.toggle3DBuildings(true); // подписка и стиль выделения уже применены к новому слою
 ```
 
+#### Отписка
+
+`onBuildingClick`, `onBuildingHover`, `onRoadClick`, `onParkingHover` и `onParkingClick` возвращают функцию отписки и принимают `null`. Повторный вызов заменяет обработчик. Отписка снимает **только свою** подписку: если обработчик уже заменён следующим вызовом, она ничего не делает — отложенный вызов прежнего владельца (например, cleanup размонтированного компонента) не погасит обработчик нового. Работает и для подписки, сделанной до подъёма слоя: снятая до подъёма, она на слой не попадёт.
+
+```ts
+useEffect(() => map.onBuildingClick(openCard), [map]); // отписка уходит в cleanup
+```
+
+#### Порог зума объёма
+
+`getBuildingsMinZoom()` — зум, с которого поднимается объём: `maps3d.minZoom`, который `mahal_map` передал в Maps3D, либо умолчание Maps3D (`16`). В отличие от `rendered` в состоянии слоя, ответ не зависит от текущего зума.
+
+```ts
+const willBe3D = targetZoom >= map.getBuildingsMinZoom();
+```
+
 ### Наведение на здание
 
 Требует `@grammaps/maps3d-web` **0.8.0** и старше. Подсветку и курсор рисует сам SDK — приложение задаёт облик и получает уведомления.
@@ -539,11 +569,11 @@ map.onBuildingHover((building) => {
 
 Колбэк приходит **только в момент смены** дома под курсором, а не на каждое движение мыши.
 
-Слежение включается самой подпиской: пока `onBuildingHover` не вызван, SDK курсор не трогает и сцену не разбирает. `onBuildingHover(null)` отписывает и гасит подсветку.
+Слежение включается самой подпиской: пока `onBuildingHover` не вызван, SDK курсор не трогает и сцену не разбирает. `onBuildingHover(null)` или возвращённая отписка снимает подписку и гасит подсветку.
 
 | Метод | Описание |
 | --- | --- |
-| `onBuildingHover(cb \| null)` | Подписка на наведение; `null` отписывает и гасит подсветку. |
+| `onBuildingHover(cb \| null)` | Подписка на наведение; возвращает отписку, `null` отписывает и гасит подсветку. |
 | `setHoverStyle(s)` | Облик: `color`, `opacity`, `glow`, `durationMs`, `easing`, `cursor`. `cursor: null` — не трогать курсор. |
 | `setHoverEnabled(on)` | Вкл/выкл наведение, не трогая подписку. |
 | `hoverEnabled` | Включено ли наведение сейчас. |
@@ -571,11 +601,13 @@ row.addEventListener("mouseleave", () => map.hoverBuilding(null));
 map.setHoverEnabled(false); // подписка сохраняется
 ```
 
-Цену ограничивает сам SDK: разбор не чаще раза в кадр, пропускается во время движения карты и не трогает сцену, пока курсор на том же доме. Но разбор — это чтение пикселя обратно из GPU, поэтому на слабых устройствах наведение лучше не включать.
+Цену ограничивает сам SDK: разбор не чаще раза в кадр, пропускается во время движения камеры — и от жестов, и от `jumpTo`/`easeTo` из приложения (с 0.11.0) — и не трогает сцену, пока курсор на том же доме. С 0.11.0 наведение читает пиксель из GPU асинхронно и главный поток не держит; гасить наведение на время движения карты снаружи больше не нужно.
 
 ### Парковки: наведение, клик, справка
 
 > Нужен `@grammaps/maps3d-web` **0.10.0+**. На более старой сборке методы ничего не делают и возвращают пустые значения (`false`, `null`).
+>
+> Подписки `onParkingHover`/`onParkingClick` можно делать до подъёма слоя — они запоминаются и переигрываются, как у зданий. Обе возвращают отписку.
 
 Устроено как у зданий: приложение задаёт облик и получает уведомления, подсветку и курсор рисует SDK.
 
@@ -604,13 +636,13 @@ map.getMap().on("contextmenu", (e) => console.log(map.parkingAt(e.point, 4)));
 
 | Метод                              | Описание                                                                                          |
 | ---------------------------------- | ------------------------------------------------------------------------------------------------- |
-| `onParkingHover(callback \| null)` | Участок под курсором либо `null`. Зовётся **только при смене участка**. `null` — отписаться и погасить. |
+| `onParkingHover(callback \| null)` | Участок под курсором либо `null`. Зовётся **только при смене участка**. Возвращает отписку; `null` — отписаться и погасить. |
 | `setParkingHoverStyle(style)`      | Облик подсветки: `color`, `opacity`, `outlineColor`, `outlineWidth`, `cursor`.                    |
 | `setParkingHoverEnabled(enabled)`  | Выключить/включить наведение, не теряя подписку.                                                  |
 | `parkingHoverEnabled`              | Геттер: включено ли наведение.                                                                    |
 | `hoverParking(id \| null)`         | Подсветить участок программно по `osm_id`; `null` — погасить. `false` — участка нет в данных.     |
 | `hoveredParking()`                 | `osm_id` подсвеченного участка или `null`.                                                        |
-| `onParkingClick(callback \| null)` | Клик по участку: справка либо `null`. `null` вместо колбэка — отписаться.                         |
+| `onParkingClick(callback \| null)` | Клик по участку: справка либо `null`. Возвращает отписку; `null` вместо колбэка — отписаться.     |
 | `parkingAt(point, tolPx?)`         | Справка по точке холста. Допуск по умолчанию `0` — строго внутрь участка.                         |
 
 Облик подсветки (`IMaps3DParkingHoverStyle`):
@@ -1258,6 +1290,8 @@ MahalMap.showPlace(map, 68.787, 38.573, 2, 18);
 MahalMap.onBuildingClick(map, (building) => console.log(building?.id));
 MahalMap.selectBuilding(map, 123456789);
 MahalMap.selectedBuilding(map);
+MahalMap.selectedBuildingKind(map);
+MahalMap.getBuildingsMinZoom(map);
 MahalMap.setSelectionStyle(map, { color: "#e23b2f" });
 MahalMap.clearSelection(map);
 MahalMap.onRoadClick(map, (road) => console.log(road?.name));
@@ -1325,16 +1359,18 @@ MahalMap.setZoom(map, 14);
 | `getLayers(instance)`                          | Снимок всех слоёв.                                                    |
 | `onLayers(instance, callback)`                 | Подписка на изменения слоёв; возвращает отписку.                      |
 | `refreshLayers(instance)`                      | Пере-применить волю клиента ко всем слоям.                            |
-| `getIndoorLevels(instance)`                    | Этажи, найденные в текущем виде карты.                                |
+| `getIndoorLevels(instance)`                    | Этажи в текущем виде карты (с 0.11.0 — из `params.levels` слоя).      |
 | `setIndoorLevel(instance, level)`              | Переключить этаж (0 — первый наземный).                               |
 | `refreshIndoor(instance)`                      | Перечитать планы этажей.                                              |
 | `showPlace(instance, lon, lat, level?, zoom?)` | Показать объект и открыть его этаж.                                   |
-| `onBuildingClick(instance, callback)`          | Клик по зданию.                                                       |
+| `onBuildingClick(instance, callback \| null)`  | Клик по зданию; возвращает отписку.                                   |
 | `selectBuilding(instance, id, style?)`         | Выделить здание по `osm_id`.                                          |
 | `clearSelection(instance)`                     | Снять выделение.                                                      |
 | `selectedBuilding(instance)`                   | Идентификатор выделенного здания или `null`.                          |
+| `selectedBuildingKind(instance)`               | `'scene'` / `'flat'` / `null` — чем нарисовано выделение.             |
+| `getBuildingsMinZoom(instance)`                | Зум появления объёма, переданный в Maps3D (по умолчанию `16`).        |
 | `setSelectionStyle(instance, style)`           | Облик выделения.                                                      |
-| `onRoadClick(instance, callback)`              | Клик по дороге.                                                       |
+| `onRoadClick(instance, callback \| null)`      | Клик по дороге; возвращает отписку.                                   |
 | `roadAt(instance, point, tolPx?)`              | Дорога под точкой холста.                                             |
 | `onParkingHover(instance, callback \| null)`   | Парковка под курсором (только при смене участка).                     |
 | `setParkingHoverStyle(instance, style)`        | Облик подсветки парковки.                                             |

package/dist/index.d.mts

@@ -23,7 +23,7 @@ interface IAdditionalParamType {
 /**
  * Поверхность @grammaps/maps3d-web, описанная локально. Пакет в зависимости не ставится —
  * он приходит снаружи, как и maplibre-gl, поэтому импортировать его типы нельзя. Здесь
- * повторена публичная часть .d.ts версии 0.10.0; всё необязательное помечено `?`, чтобы
+ * повторена публичная часть .d.ts версии 0.11.0; всё необязательное помечено `?`, чтобы
  * более старая сборка на странице не ломала типы у потребителя.
  */
 type Maps3DThemeName = "light" | "dark" | "navigator-light" | "navigator-dark" | "mobile-light" | "mobile-dark";
@@ -97,8 +97,26 @@ interface IMaps3DLayerState {
      * У слоя, который не умеет ответить фактом, повторяет `active`; у сборок до 0.8.0 — undefined.
      */
     rendered?: boolean;
-    /** Параметры слоя: у зданий — detail, у этажей — level, у рельефа — mode. */
-    params: Record<string, unknown>;
+    /** Параметры слоя: у зданий — detail, у этажей — level и levels, у рельефа — mode. */
+    params: IMaps3DLayerStateParams;
+}
+/**
+ * Параметры в снимке слоя. Каждое поле есть только у своего слоя; неизвестные ключи
+ * сборки Maps3D проходят через индексную сигнатуру.
+ */
+interface IMaps3DLayerStateParams {
+    /** `buildings`: уровень детализации. */
+    detail?: Maps3DBuildingDetail;
+    /** `indoor`: открытый этаж. */
+    level?: number;
+    /**
+     * `indoor`: этажи, найденные в текущем виде карты; `[]` — данных по зданию нет.
+     * Меняется при движении карты и приходит через onLayers(). С 0.11.0, раньше — undefined.
+     */
+    levels?: number[];
+    /** `terrain`: режим рельефа. */
+    mode?: Maps3DTerrainMode;
+    [key: string]: unknown;
 }
 interface IMaps3DSelectionStyle {
     color?: string | number;
@@ -232,12 +250,16 @@ interface IMaps3DBuildingClickInfo {
     id: string | number;
     /**
      * Атрибуты объекта; `props.osm_id` — идентификатор, который не меняется.
-     * Необязательно: peerDependency допускает сборки Maps3D от 0.5.0, где поля может не быть.
+     * Необязательно: запасные пути держат сборки Maps3D от 0.5.0, где поля может не быть.
      */
     props?: Record<string, unknown>;
     /** Высота здания в метрах. Необязательно по той же причине, что и `props`. */
     height?: number;
-    /** Порядковый номер внутри сцены. Живёт до ближайшей пересборки геометрии. */
+    /**
+     * Порядковый номер внутри сцены. Живёт до ближайшей пересборки геометрии.
+     * `>= 0` — объёмный дом сцены, `-1` — дом из слоя стиля (объёма под ним нет).
+     * Тот же признак, что selectedBuildingKind(): `'scene'` / `'flat'`.
+     */
     index?: number;
     [key: string]: unknown;
 }
@@ -247,6 +269,10 @@ interface IMaps3DObjectsLightOptions {
     sky?: number;
     exposure?: number;
 }
+/** Чем нарисовано выделение: объёмный дом сцены или слой стиля. С 0.11.0. */
+type Maps3DSelectionKind = "scene" | "flat";
+/** Колбэк подписки Maps3D: `null` вместо функции — отписаться. */
+type Maps3DListener<T> = ((info: T | null) => void) | null;
 interface IMaps3DDiagnostics {
     terrainActive: boolean;
     drapeRefreshes: number;
@@ -266,18 +292,20 @@ interface IMaps3DLayer {
     refreshLayers?(): void;
     buildings?: IMaps3DBuildingsController | null;
     setBuildingsEnabled?(enabled: boolean): void;
-    onBuildingClick?(callback: (info: IMaps3DBuildingClickInfo | null) => void): void;
+    onBuildingClick?(callback: Maps3DListener<IMaps3DBuildingClickInfo>): (() => void) | void;
     selectBuilding?(id: number | string | null, style?: IMaps3DSelectionStyle): boolean;
     clearSelection?(): void;
     selectedBuilding?(): number | string | null;
+    /** С 0.11.0. */
+    selectedBuildingKind?(): Maps3DSelectionKind | null;
     setSelectionStyle?(style: IMaps3DSelectionStyle): void;
-    onBuildingHover?(callback: ((info: IMaps3DBuildingClickInfo | null) => void) | null): void;
+    onBuildingHover?(callback: Maps3DListener<IMaps3DBuildingClickInfo>): (() => void) | void;
     setHoverEnabled?(enabled: boolean): void;
     readonly hoverEnabled?: boolean;
     setHoverStyle?(style: IMaps3DHoverStyle): void;
     hoverBuilding?(id: number | string | null): boolean;
     hoveredBuilding?(): number | string | null;
-    onRoadClick?(callback: (hit: IMaps3DRoadHit | null) => void): void;
+    onRoadClick?(callback: Maps3DListener<IMaps3DRoadHit>): (() => void) | void;
     roadAt?(point: {
         x: number;
         y: number;
@@ -287,13 +315,13 @@ interface IMaps3DLayer {
         x: number;
         y: number;
     }, tolerancePx?: number): IMaps3DParkingInfo | null;
-    onParkingHover?(callback: ((info: IMaps3DParkingInfo | null) => void) | null): void;
+    onParkingHover?(callback: Maps3DListener<IMaps3DParkingInfo>): (() => void) | void;
     setParkingHoverStyle?(style: IMaps3DParkingHoverStyle): void;
     setParkingHoverEnabled?(enabled: boolean): void;
     readonly parkingHoverEnabled?: boolean;
     hoverParking?(id: number | string | null): boolean;
     hoveredParking?(): number | string | null;
-    onParkingClick?(callback: ((info: IMaps3DParkingInfo | null) => void) | null): void;
+    onParkingClick?(callback: Maps3DListener<IMaps3DParkingInfo>): (() => void) | void;
     traffic?: boolean;
     trafficRaster?: boolean;
     setTraffic?(enabled: boolean): void;
@@ -304,6 +332,7 @@ interface IMaps3DLayer {
     refreshTraffic?(): void;
     setIndoor?(enabled: boolean): void;
     setIndoorLevel?(level: number): void;
+    /** Запасной путь для сборок до 0.11.0 — там этажей нет в `layer("indoor").params.levels`. */
     readonly indoorLevels?: number[];
     refreshIndoor?(): void;
     showPlace?(lon: number, lat: number, level?: number | null, zoom?: number): void;
@@ -560,11 +589,9 @@ declare class MahalMap {
     private buildingsEnabled;
     private workerCheckTimer?;
     private styleChangeHandler?;
-    private pendingBuildingClick?;
-    private pendingRoadClick?;
+    private subscriptions;
     private pendingSelectionStyle?;
     private pendingLayerSubscribers;
-    private pendingBuildingHover?;
     private pendingHoverStyle?;
     private pendingHoverEnabled?;
     private constructor();
@@ -629,27 +656,29 @@ declare class MahalMap {
     static setIndoorLevel(instance: MahalMap, level: number): void;
     static refreshIndoor(instance: MahalMap): void;
     static showPlace(instance: MahalMap, lon: number, lat: number, level?: number | null, zoom?: number): void;
-    static onBuildingClick(instance: MahalMap, callback: (info: IMaps3DBuildingClickInfo | null) => void): void;
+    static onBuildingClick(instance: MahalMap, callback: Maps3DListener<IMaps3DBuildingClickInfo>): () => void;
     static selectBuilding(instance: MahalMap, id: number | string | null, style?: IMaps3DSelectionStyle): boolean;
     static clearSelection(instance: MahalMap): void;
     static selectedBuilding(instance: MahalMap): string | number | null;
+    static selectedBuildingKind(instance: MahalMap): Maps3DSelectionKind | null;
+    static getBuildingsMinZoom(instance: MahalMap): number;
     static setSelectionStyle(instance: MahalMap, style: IMaps3DSelectionStyle): void;
-    static onRoadClick(instance: MahalMap, callback: (hit: IMaps3DRoadHit | null) => void): void;
+    static onRoadClick(instance: MahalMap, callback: Maps3DListener<IMaps3DRoadHit>): () => void;
     static roadAt(instance: MahalMap, point: {
         x: number;
         y: number;
     }, tolerancePx?: number): IMaps3DRoadHit | null;
-    static onParkingHover(instance: MahalMap, callback: ((info: IMaps3DParkingInfo | null) => void) | null): void;
+    static onParkingHover(instance: MahalMap, callback: Maps3DListener<IMaps3DParkingInfo>): () => void;
     static setParkingHoverStyle(instance: MahalMap, style: IMaps3DParkingHoverStyle): void;
     static setParkingHoverEnabled(instance: MahalMap, enabled: boolean): void;
     static hoverParking(instance: MahalMap, id: number | string | null): boolean;
     static hoveredParking(instance: MahalMap): string | number | null;
-    static onParkingClick(instance: MahalMap, callback: ((info: IMaps3DParkingInfo | null) => void) | null): void;
+    static onParkingClick(instance: MahalMap, callback: Maps3DListener<IMaps3DParkingInfo>): () => void;
     static parkingAt(instance: MahalMap, point: {
         x: number;
         y: number;
     }, tolerancePx?: number): IMaps3DParkingInfo | null;
-    static onBuildingHover(instance: MahalMap, callback: ((info: IMaps3DBuildingClickInfo | null) => void) | null): void;
+    static onBuildingHover(instance: MahalMap, callback: Maps3DListener<IMaps3DBuildingClickInfo>): () => void;
     static setHoverEnabled(instance: MahalMap, enabled: boolean): void;
     static setHoverStyle(instance: MahalMap, style: IMaps3DHoverStyle): void;
     static hoverBuilding(instance: MahalMap, id: number | string | null): boolean;
@@ -720,7 +749,11 @@ declare class MahalMap {
     onLayers(callback: (state: IMaps3DLayerState) => void): () => void;
     /** Пере-применить волю клиента ко всем слоям — после полной смены стиля. */
     refreshLayers(): void;
-    /** Этажи, найденные в текущем виде карты. Пусто — данных по зданию нет. */
+    /**
+     * Этажи, найденные в текущем виде карты. Пусто — данных по зданию нет.
+     * С 0.11.0 они же приходят в onLayers() у слоя `indoor` (`params.levels`) — опрашивать
+     * этот метод на движении карты больше не нужно.
+     */
     getIndoorLevels(): number[];
     /** Переключить этаж. Нумерация OSM: 0 — первый наземный. */
     setIndoorLevel(level: number): void;
@@ -733,21 +766,32 @@ declare class MahalMap {
      */
     showPlace(lon: number, lat: number, level?: number | null, zoom?: number): void;
     /**
-     * Клик по зданию: { id, height, props } либо null. Повторный вызов заменяет обработчик.
+     * Клик по зданию: { id, height, props, index } либо null. `index >= 0` — объёмный дом
+     * сцены, `-1` — дом из слоя стиля. Повторный вызов заменяет обработчик, `null` — отписка.
+     *
      * Подписываться можно сразу после create(), даже когда слой ещё не поднят
      * (`enable3D: false`) — подписка переиграется, как только слой появится.
+     *
+     * @returns Отписка. Снимает только эту подписку: если обработчик уже заменён
+     * следующим вызовом, ничего не делает.
      */
-    onBuildingClick(callback: (info: IMaps3DBuildingClickInfo | null) => void): void;
+    onBuildingClick(callback: Maps3DListener<IMaps3DBuildingClickInfo>): () => void;
     /** Выделить здание по osm_id. `false` — здания сейчас нет в загруженных данных. */
     selectBuilding(id: number | string | null, style?: IMaps3DSelectionStyle): boolean;
     clearSelection(): void;
     selectedBuilding(): number | string | null;
+    /**
+     * Чем нарисовано выделение: `'scene'` — объёмный дом сцены, `'flat'` — слой стиля,
+     * `null` — выделения нет. На сборке Maps3D до 0.11.0 всегда `null`.
+     */
+    selectedBuildingKind(): Maps3DSelectionKind | null;
     setSelectionStyle(style: IMaps3DSelectionStyle): void;
     /**
      * Клик по дороге. Приходит независимо от клика по зданию — приоритет решает приложение.
-     * Как и onBuildingClick, переживает отсутствие слоя на момент подписки.
+     * Как и onBuildingClick, переживает отсутствие слоя на момент подписки, принимает `null`
+     * и возвращает отписку.
      */
-    onRoadClick(callback: (hit: IMaps3DRoadHit | null) => void): void;
+    onRoadClick(callback: Maps3DListener<IMaps3DRoadHit>): () => void;
     /** Дорога под точкой холста. Допуск по умолчанию — 12 px. */
     roadAt(point: {
         x: number;
@@ -758,8 +802,9 @@ declare class MahalMap {
     /**
      * Участок под курсором либо null. Зовётся ТОЛЬКО при смене участка, не на каждое
      * движение мыши. `null` вместо колбэка — отписаться и погасить подсветку.
+     * Переживает отсутствие слоя на момент подписки; возвращает отписку.
      */
-    onParkingHover(callback: ((info: IMaps3DParkingInfo | null) => void) | null): void;
+    onParkingHover(callback: Maps3DListener<IMaps3DParkingInfo>): () => void;
     /** Облик подсветки: color, opacity, outlineColor, outlineWidth, cursor. */
     setParkingHoverStyle(style: IMaps3DParkingHoverStyle): void;
     /** Вкл/выкл наведение, не теряя подписку. */
@@ -770,8 +815,11 @@ declare class MahalMap {
     hoverParking(id: number | string | null): boolean;
     /** `osm_id` подсвеченного участка или null. */
     hoveredParking(): number | string | null;
-    /** Клик по участку: справка либо null. `null` вместо колбэка — отписаться. */
-    onParkingClick(callback: ((info: IMaps3DParkingInfo | null) => void) | null): void;
+    /**
+     * Клик по участку: справка либо null. `null` вместо колбэка — отписаться.
+     * Переживает отсутствие слоя на момент подписки; возвращает отписку.
+     */
+    onParkingClick(callback: Maps3DListener<IMaps3DParkingInfo>): () => void;
     /**
      * Парковка под точкой холста (`e.point` события карты). Попадание — по границе полигона;
      * допуск по умолчанию 0 — строго внутрь участка.
@@ -786,8 +834,10 @@ declare class MahalMap {
      *
      * Слежение за мышью включается самой подпиской: без неё SDK курсор не трогает и
      * разбор сцены не делает.
+     *
+     * @returns Отписка; снимает только эту подписку.
      */
-    onBuildingHover(callback: ((info: IMaps3DBuildingClickInfo | null) => void) | null): void;
+    onBuildingHover(callback: Maps3DListener<IMaps3DBuildingClickInfo>): () => void;
     /**
      * Включить/выключить наведение, не трогая подписку. Нужно там, где подсветка мешает:
      * режим рисования, открытая карточка объекта, тач-устройство без курсора.
@@ -808,6 +858,20 @@ declare class MahalMap {
     hoverBuilding(id: number | string | null): boolean;
     /** Идентификатор дома под наведением или `null`. */
     hoveredBuilding(): number | string | null;
+    /**
+     * Зум, с которого поднимается объём: `maps3d.minZoom` из опций create() — ровно то, что
+     * уходит в Maps3D, — либо умолчание самой Maps3D (16). Ответ не зависит от текущего
+     * зума, в отличие от `rendered` в состоянии слоя.
+     */
+    getBuildingsMinZoom(): number;
+    /**
+     * Занимает слот подписки. Запись живёт до подъёма слоя и переигрывается на нём;
+     * отписка снимает слот, только если он всё ещё её.
+     */
+    private subscribe;
+    private bindSubscription;
+    /** Снимает подписку со слоя: её же отпиской, а у сборок до 0.11.0 — через null. */
+    private unbindSubscription;
     /**
      * Создаёт слой Maps3D. `buildings` не форсируем в `true`: с 0.7.x видимостью объёма
      * заведует реестр слоёв, а опции облика зданий приходят из options.maps3d как есть.
@@ -1130,4 +1194,4 @@ declare namespace index {
   export { index_checkCoordinates as checkCoordinates, index_debounce as debounce, index_geojsonPolyline as geojsonPolyline, index_geometryPolyline as geometryPolyline, index_trimValue as trimValue };
 }
 
-export { CheckJSApi, type IAdditionalParamType, type ICheckJSApiParam, type ICheckJSApiResponse, type IMahalMapOptions, type IMapMarker, type IMaps3DBuildingClickInfo, type IMaps3DBuildingsController, type IMaps3DBuildingsOptions, type IMaps3DClosuresOptions, type IMaps3DDiagnostics, type IMaps3DHoverStyle, type IMaps3DIndoorOptions, type IMaps3DLayer, type IMaps3DLayerOptions, type IMaps3DLayerParams, type IMaps3DLayerState, type IMaps3DMapOptionsInput, type IMaps3DMapOptionsResult, type IMaps3DObjectsLightOptions, type IMaps3DParkingHoverStyle, type IMaps3DParkingInfo, type IMaps3DPlacesOptions, type IMaps3DRoadHit, type IMaps3DSelectionStyle, type IMaps3DTrafficOptions, type IMaps3DTransformRequestOptions, type IResponse, type IRoute, type ISearchByLocationParam, type ISearchDetailAddress, type ISearchDetailInfo, type ISearchParam, type ISearchResponse, MahalMap, MahalMapDefaultMarker, type MahalMapDefaultMarkerProps, type MapEngine, type MapLanguage, type MapStyleFamily, type Maps3DBuildingDetail, type Maps3DCtor, type Maps3DLayerId, type Maps3DParkingSubtype, type Maps3DTerrainMode, type Maps3DThemeName, type Maps3DTransformRequest, type MeasureIcons, type MeasureLabels, type MeasureMode, type MeasurePoint, type MeasureShape, type MeasureState, type MeasureStyleOptions, MeasureTool, type MeasureToolOptions, Router, Search, SearchByLocation, SearchPoi, type SearchResultType, type Theme, index$2 as keyUtils, index$1 as measureUtils, index as utils };
+export { CheckJSApi, type IAdditionalParamType, type ICheckJSApiParam, type ICheckJSApiResponse, type IMahalMapOptions, type IMapMarker, type IMaps3DBuildingClickInfo, type IMaps3DBuildingsController, type IMaps3DBuildingsOptions, type IMaps3DClosuresOptions, type IMaps3DDiagnostics, type IMaps3DHoverStyle, type IMaps3DIndoorOptions, type IMaps3DLayer, type IMaps3DLayerOptions, type IMaps3DLayerParams, type IMaps3DLayerState, type IMaps3DLayerStateParams, type IMaps3DMapOptionsInput, type IMaps3DMapOptionsResult, type IMaps3DObjectsLightOptions, type IMaps3DParkingHoverStyle, type IMaps3DParkingInfo, type IMaps3DPlacesOptions, type IMaps3DRoadHit, type IMaps3DSelectionStyle, type IMaps3DTrafficOptions, type IMaps3DTransformRequestOptions, type IResponse, type IRoute, type ISearchByLocationParam, type ISearchDetailAddress, type ISearchDetailInfo, type ISearchParam, type ISearchResponse, MahalMap, MahalMapDefaultMarker, type MahalMapDefaultMarkerProps, type MapEngine, type MapLanguage, type MapStyleFamily, type Maps3DBuildingDetail, type Maps3DCtor, type Maps3DLayerId, type Maps3DListener, type Maps3DParkingSubtype, type Maps3DSelectionKind, type Maps3DTerrainMode, type Maps3DThemeName, type Maps3DTransformRequest, type MeasureIcons, type MeasureLabels, type MeasureMode, type MeasurePoint, type MeasureShape, type MeasureState, type MeasureStyleOptions, MeasureTool, type MeasureToolOptions, Router, Search, SearchByLocation, SearchPoi, type SearchResultType, type Theme, index$2 as keyUtils, index$1 as measureUtils, index as utils };