mahal_map 2.0.2 → 2.1.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) — даёт стили, тайлы, объём, пробки, рельеф, планы этажей, клик по объектам. Помечен `optional`: без него карта поднимется на запасном векторном стиле, но 3D и слоёв платформы на ней не будет.
+- `@grammaps/maps3d-web` (>=0.5.0; рекомендуется 0.8.0 — в ней наведение на здание и починенный пикинг клика) — даёт стили, тайлы, объём, пробки, рельеф, планы этажей, клик по объектам. Помечен `optional`: без него карта поднимется на запасном векторном стиле, но 3D и слоёв платформы на ней не будет.
 
 MapLibre можно не класть в свою сборку вовсе — платформа отдаёт согласованную версию вместе с веб-воркером:
 
@@ -334,11 +334,14 @@ MahalMap.create(
 
 Поля независимы, и это главная ловушка реестра:
 
-| Поле        | Вопрос                       |
-| ----------- | ---------------------------- |
-| `wanted`    | чего хочет приложение        |
-| `available` | что позволяют стиль и данные |
-| `active`    | что нарисовано прямо сейчас  |
+| Поле        | Вопрос                                            |
+| ----------- | ------------------------------------------------- |
+| `wanted`    | чего хочет приложение                             |
+| `available` | что позволяют стиль и данные                      |
+| `active`    | что нарисовано прямо сейчас (память SDK)          |
+| `rendered`  | факт со стороны карты: слой есть в стиле и не погашен |
+
+`rendered` появилось в Maps3D 0.8.0; у сборок постарше его нет (`undefined`). Расхождение `active !== rendered` означает, что внутренний признак SDK разошёлся с картой — это видно одной проверкой, без чтения минифицированной сборки.
 
 Слой может быть включён и при этом не нарисован — и это не ошибка:
 
@@ -495,7 +498,65 @@ map.roadAt({ x: 320, y: 240 });
 map.roadsNamed; // есть ли в текущем стиле названия дорог
 ```
 
-Подписываться можно сразу после `create()`, до готовности карты.
+Подписываться можно сразу после `create()` — даже когда слой ещё не поднят (`enable3D: false`). Подписка и облик выделения запоминаются и переигрываются, как только слой появится:
+
+```ts
+const map = MahalMap.create({ container: "map", enable3D: false }, maplibregl, Maps3D);
+
+map.onBuildingClick((b) => console.log(b?.props.osm_id));
+map.setSelectionStyle({ color: "#e23b2f" });
+
+map.toggle3DBuildings(true); // подписка и стиль выделения уже применены к новому слою
+```
+
+### Наведение на здание
+
+Требует `@grammaps/maps3d-web` **0.8.0** и старше. Подсветку и курсор рисует сам SDK — приложение задаёт облик и получает уведомления.
+
+```ts
+map.setHoverStyle({ color: "#6b9ed1", opacity: 0.3, cursor: "pointer" });
+
+map.onBuildingHover((building) => {
+  if (!building) return; // курсор ушёл с домов
+  console.log(building.props.osm_id, building.height);
+});
+```
+
+Колбэк приходит **только в момент смены** дома под курсором, а не на каждое движение мыши.
+
+Слежение включается самой подпиской: пока `onBuildingHover` не вызван, SDK курсор не трогает и сцену не разбирает. `onBuildingHover(null)` отписывает и гасит подсветку.
+
+| Метод | Описание |
+| --- | --- |
+| `onBuildingHover(cb \| null)` | Подписка на наведение; `null` отписывает и гасит подсветку. |
+| `setHoverStyle(s)` | Облик: `color`, `opacity`, `glow`, `durationMs`, `easing`, `cursor`. `cursor: null` — не трогать курсор. |
+| `setHoverEnabled(on)` | Вкл/выкл наведение, не трогая подписку. |
+| `hoverEnabled` | Включено ли наведение сейчас. |
+| `hoverBuilding(id \| null)` | Навести программно — например, с наведения на строку списка. `false` — дома нет на карте. |
+| `hoveredBuilding()` | Идентификатор дома под наведением или `null`. |
+
+Слот наведения свой, отдельный от выделения: **выбор всегда главнее**, и на выбранном доме наведение не рисуется. Занимать `setSelectionStyle` ради подсветки под курсором, как приходилось до 0.8.0, больше не нужно.
+
+#### Наведение с элементов интерфейса
+
+Курсор стоит на строке списка, а не на карте:
+
+```ts
+row.addEventListener("mouseenter", () => map.hoverBuilding(row.dataset.osmId!));
+row.addEventListener("mouseleave", () => map.hoverBuilding(null));
+```
+
+Следующее движение мыши по карте перебивает программное наведение — слежение владеет слотом, пока включено.
+
+#### Где наведение выключают
+
+Там, где подсветка мешает: режим рисования на карте, открытая карточка объекта, тач-устройство без курсора.
+
+```ts
+map.setHoverEnabled(false); // подписка сохраняется
+```
+
+Цену ограничивает сам SDK: разбор не чаще раза в кадр, пропускается во время движения карты и не трогает сцену, пока курсор на том же доме. Но разбор — это чтение пикселя обратно из GPU, поэтому на слабых устройствах наведение лучше не включать.
 
 #### Вкл/выкл 3D-здания на лету
 
@@ -1114,6 +1175,13 @@ MahalMap.clearSelection(map);
 MahalMap.onRoadClick(map, (road) => console.log(road?.name));
 MahalMap.roadAt(map, { x: 320, y: 240 });
 
+// Наведение на здание (Maps3D 0.8.0)
+MahalMap.onBuildingHover(map, (b) => console.log(b?.id));
+MahalMap.setHoverStyle(map, { color: "#6b9ed1", cursor: "pointer" });
+MahalMap.setHoverEnabled(map, false);
+MahalMap.hoverBuilding(map, 123456789);
+MahalMap.hoveredBuilding(map);
+
 MahalMap.destroy(map);
 ```
 
@@ -1171,6 +1239,11 @@ MahalMap.setZoom(map, 14);
 | `setSelectionStyle(instance, style)`           | Облик выделения.                                                      |
 | `onRoadClick(instance, callback)`              | Клик по дороге.                                                       |
 | `roadAt(instance, point, tolPx?)`              | Дорога под точкой холста.                                             |
+| `onBuildingHover(instance, cb)`               | Подписка на наведение (Maps3D 0.8.0); `null` отписывает.              |
+| `setHoverStyle(instance, style)`              | Облик наведения, включая CSS-курсор.                                  |
+| `setHoverEnabled(instance, on)`               | Вкл/выкл наведение, не трогая подписку.                               |
+| `hoverBuilding(instance, id)`                 | Навести на здание программно; `null` снимает.                         |
+| `hoveredBuilding(instance)`                   | Дом под наведением или `null`.                                        |
 | `destroy(instance)`                            | Полностью удаляет карту.                                              |
 | `loadKeyFromScriptUrl()`                       | Читает `apikey` из URL SDK скрипта.                                   |
 | `loadLanguageFromScriptUrl()`                  | Читает `lang` из URL SDK скрипта.                                     |

package/dist/index.d.mts

@@ -91,6 +91,12 @@ interface IMaps3DLayerState {
     available: boolean;
     /** Что нарисовано прямо сейчас. Именно это поле показывает, включён слой на деле или нет. */
     active: boolean;
+    /**
+     * Факт со стороны карты: слой есть в стиле и не погашен. Появилось в 0.8.0.
+     * `active !== rendered` — расхождение внутреннего признака SDK с картой.
+     * У слоя, который не умеет ответить фактом, повторяет `active`; у сборок до 0.8.0 — undefined.
+     */
+    rendered?: boolean;
     /** Параметры слоя: у зданий — detail, у этажей — level, у рельефа — mode. */
     params: Record<string, unknown>;
 }
@@ -101,6 +107,15 @@ interface IMaps3DSelectionStyle {
     durationMs?: number;
     easing?: "ease-out" | "linear";
 }
+/**
+ * Облик наведения. Появился в 0.8.0: до него подсветить дом под курсором можно было,
+ * только заняв единственный слот выделения. Теперь слот свой, и выбор всегда главнее —
+ * на выбранном доме наведение не рисуется.
+ */
+interface IMaps3DHoverStyle extends IMaps3DSelectionStyle {
+    /** CSS-курсор над зданием. По умолчанию "pointer"; `null` — не трогать курсор вовсе. */
+    cursor?: string | null;
+}
 interface IMaps3DRoadHit {
     name: string;
     nameRu?: string;
@@ -175,9 +190,12 @@ interface IMaps3DBuildingsController {
 }
 interface IMaps3DBuildingClickInfo {
     id: string | number;
+    /** Атрибуты объекта; `props.osm_id` — идентификатор, который не меняется. */
+    props: Record<string, unknown>;
+    /** Высота здания в метрах. */
+    height: number;
+    /** Порядковый номер внутри сцены. Живёт до ближайшей пересборки геометрии. */
     index?: number;
-    height?: number;
-    props?: Record<string, unknown>;
     [key: string]: unknown;
 }
 interface IMaps3DObjectsLightOptions {
@@ -210,6 +228,12 @@ interface IMaps3DLayer {
     clearSelection?(): void;
     selectedBuilding?(): number | string | null;
     setSelectionStyle?(style: IMaps3DSelectionStyle): void;
+    onBuildingHover?(callback: ((info: IMaps3DBuildingClickInfo | null) => void) | null): 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;
     roadAt?(point: {
         x: number;
@@ -461,6 +485,13 @@ declare class MahalMap {
     private buildingsEnabled;
     private workerCheckTimer?;
     private styleChangeHandler?;
+    private pendingBuildingClick?;
+    private pendingRoadClick?;
+    private pendingSelectionStyle?;
+    private pendingLayerSubscribers;
+    private pendingBuildingHover?;
+    private pendingHoverStyle?;
+    private pendingHoverEnabled?;
     private constructor();
     private static getInstanceKey;
     private static normalizeLanguage;
@@ -533,6 +564,11 @@ declare class MahalMap {
         x: number;
         y: number;
     }, tolerancePx?: number): IMaps3DRoadHit | null;
+    static onBuildingHover(instance: MahalMap, callback: ((info: IMaps3DBuildingClickInfo | null) => void) | null): void;
+    static setHoverEnabled(instance: MahalMap, enabled: boolean): void;
+    static setHoverStyle(instance: MahalMap, style: IMaps3DHoverStyle): void;
+    static hoverBuilding(instance: MahalMap, id: number | string | null): boolean;
+    static hoveredBuilding(instance: MahalMap): string | number | null;
     static setLanguage(instance: MahalMap, lang: MapLanguage): void;
     static setCenter(instance: MahalMap, center: [number, number]): void;
     static setZoom(instance: MahalMap, zoom: number): void;
@@ -592,7 +628,10 @@ declare class MahalMap {
     getLayerState(id: Maps3DLayerId): IMaps3DLayerState | null;
     /** Снимок всех слоёв — по нему приложение рисует свою панель. */
     getLayers(): IMaps3DLayerState[];
-    /** Подписка на изменения слоёв. Возвращает отписку (no-op, если слоя нет). */
+    /**
+     * Подписка на изменения слоёв. Возвращает отписку. Работает и до появления слоя:
+     * подписка переиграется при его подключении, а отписка снимет её в любом случае.
+     */
     onLayers(callback: (state: IMaps3DLayerState) => void): () => void;
     /** Пере-применить волю клиента ко всем слоям — после полной смены стиля. */
     refreshLayers(): void;
@@ -608,14 +647,21 @@ declare class MahalMap {
      * и метка окажется в чужом зале.
      */
     showPlace(lon: number, lat: number, level?: number | null, zoom?: number): void;
-    /** Клик по зданию: { id, height, props } либо null. Повторный вызов заменяет обработчик. */
+    /**
+     * Клик по зданию: { id, height, props } либо null. Повторный вызов заменяет обработчик.
+     * Подписываться можно сразу после create(), даже когда слой ещё не поднят
+     * (`enable3D: false`) — подписка переиграется, как только слой появится.
+     */
     onBuildingClick(callback: (info: IMaps3DBuildingClickInfo | null) => void): void;
     /** Выделить здание по osm_id. `false` — здания сейчас нет в загруженных данных. */
     selectBuilding(id: number | string | null, style?: IMaps3DSelectionStyle): boolean;
     clearSelection(): void;
     selectedBuilding(): number | string | null;
     setSelectionStyle(style: IMaps3DSelectionStyle): void;
-    /** Клик по дороге. Приходит независимо от клика по зданию — приоритет решает приложение. */
+    /**
+     * Клик по дороге. Приходит независимо от клика по зданию — приоритет решает приложение.
+     * Как и onBuildingClick, переживает отсутствие слоя на момент подписки.
+     */
     onRoadClick(callback: (hit: IMaps3DRoadHit | null) => void): void;
     /** Дорога под точкой холста. Допуск по умолчанию — 12 px. */
     roadAt(point: {
@@ -624,11 +670,45 @@ declare class MahalMap {
     }, tolerancePx?: number): IMaps3DRoadHit | null;
     /** Есть ли в текущем стиле названия дорог. Нет — roadAt() всегда вернёт null. */
     get roadsNamed(): boolean;
+    /**
+     * Подписаться на наведение. Колбэк приходит только в момент смены дома под курсором,
+     * а не на каждое движение мыши. `null` отписывает и гасит подсветку.
+     *
+     * Слежение за мышью включается самой подпиской: без неё SDK курсор не трогает и
+     * разбор сцены не делает.
+     */
+    onBuildingHover(callback: ((info: IMaps3DBuildingClickInfo | null) => void) | null): void;
+    /**
+     * Включить/выключить наведение, не трогая подписку. Нужно там, где подсветка мешает:
+     * режим рисования, открытая карточка объекта, тач-устройство без курсора.
+     */
+    setHoverEnabled(enabled: boolean): void;
+    /** Включено ли наведение прямо сейчас. */
+    get hoverEnabled(): boolean;
+    /** Облик наведения: цвет, плотность, свечение, длительность и CSS-курсор. */
+    setHoverStyle(style: IMaps3DHoverStyle): void;
+    /**
+     * Навести на здание программно — например, когда курсор стоит на строке списка.
+     * Идентификатор тот же, что у selectBuilding. `null` снимает наведение.
+     *
+     * Следующее движение мыши по карте перебивает программное наведение.
+     *
+     * @returns `false`, если такого дома сейчас на карте нет.
+     */
+    hoverBuilding(id: number | string | null): boolean;
+    /** Идентификатор дома под наведением или `null`. */
+    hoveredBuilding(): number | string | null;
     /**
      * Создаёт слой Maps3D. `buildings` не форсируем в `true`: с 0.7.x видимостью объёма
      * заведует реестр слоёв, а опции облика зданий приходят из options.maps3d как есть.
      */
     private createMaps3DLayer;
+    /**
+     * Переигрывает волю клиента на только что подключённом слое: подписки на клики,
+     * облик выделения и подписчиков реестра. Нужно, когда карта создана без слоя
+     * (`enable3D: false`) — тогда всё это было сказано до его появления.
+     */
+    private applyPendingSubscriptions;
     private attachMaps3DLayer;
     /**
      * Освобождает слой Maps3D одним доступным методом (destroy(), иначе remove()) и ровно один
@@ -936,4 +1016,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 IMaps3DIndoorOptions, type IMaps3DLayer, type IMaps3DLayerOptions, type IMaps3DLayerParams, type IMaps3DLayerState, type IMaps3DMapOptionsInput, type IMaps3DMapOptionsResult, type IMaps3DObjectsLightOptions, type IMaps3DPlacesOptions, type IMaps3DRoadHit, type IMaps3DSelectionStyle, type IMaps3DTrafficOptions, type IMaps3DTransformRequestOptions, type IResponse, type IRoute, type ISearchByLocationParam, type ISearchParam, type ISearchResponse, MahalMap, MahalMapDefaultMarker, type MahalMapDefaultMarkerProps, type MapEngine, type MapLanguage, type MapStyleFamily, type Maps3DBuildingDetail, type Maps3DCtor, type Maps3DLayerId, 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 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 IMaps3DMapOptionsInput, type IMaps3DMapOptionsResult, type IMaps3DObjectsLightOptions, type IMaps3DPlacesOptions, type IMaps3DRoadHit, type IMaps3DSelectionStyle, type IMaps3DTrafficOptions, type IMaps3DTransformRequestOptions, type IResponse, type IRoute, type ISearchByLocationParam, type ISearchParam, type ISearchResponse, MahalMap, MahalMapDefaultMarker, type MahalMapDefaultMarkerProps, type MapEngine, type MapLanguage, type MapStyleFamily, type Maps3DBuildingDetail, type Maps3DCtor, type Maps3DLayerId, 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 Theme, index$2 as keyUtils, index$1 as measureUtils, index as utils };

package/dist/index.d.ts

@@ -91,6 +91,12 @@ interface IMaps3DLayerState {
     available: boolean;
     /** Что нарисовано прямо сейчас. Именно это поле показывает, включён слой на деле или нет. */
     active: boolean;
+    /**
+     * Факт со стороны карты: слой есть в стиле и не погашен. Появилось в 0.8.0.
+     * `active !== rendered` — расхождение внутреннего признака SDK с картой.
+     * У слоя, который не умеет ответить фактом, повторяет `active`; у сборок до 0.8.0 — undefined.
+     */
+    rendered?: boolean;
     /** Параметры слоя: у зданий — detail, у этажей — level, у рельефа — mode. */
     params: Record<string, unknown>;
 }
@@ -101,6 +107,15 @@ interface IMaps3DSelectionStyle {
     durationMs?: number;
     easing?: "ease-out" | "linear";
 }
+/**
+ * Облик наведения. Появился в 0.8.0: до него подсветить дом под курсором можно было,
+ * только заняв единственный слот выделения. Теперь слот свой, и выбор всегда главнее —
+ * на выбранном доме наведение не рисуется.
+ */
+interface IMaps3DHoverStyle extends IMaps3DSelectionStyle {
+    /** CSS-курсор над зданием. По умолчанию "pointer"; `null` — не трогать курсор вовсе. */
+    cursor?: string | null;
+}
 interface IMaps3DRoadHit {
     name: string;
     nameRu?: string;
@@ -175,9 +190,12 @@ interface IMaps3DBuildingsController {
 }
 interface IMaps3DBuildingClickInfo {
     id: string | number;
+    /** Атрибуты объекта; `props.osm_id` — идентификатор, который не меняется. */
+    props: Record<string, unknown>;
+    /** Высота здания в метрах. */
+    height: number;
+    /** Порядковый номер внутри сцены. Живёт до ближайшей пересборки геометрии. */
     index?: number;
-    height?: number;
-    props?: Record<string, unknown>;
     [key: string]: unknown;
 }
 interface IMaps3DObjectsLightOptions {
@@ -210,6 +228,12 @@ interface IMaps3DLayer {
     clearSelection?(): void;
     selectedBuilding?(): number | string | null;
     setSelectionStyle?(style: IMaps3DSelectionStyle): void;
+    onBuildingHover?(callback: ((info: IMaps3DBuildingClickInfo | null) => void) | null): 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;
     roadAt?(point: {
         x: number;
@@ -461,6 +485,13 @@ declare class MahalMap {
     private buildingsEnabled;
     private workerCheckTimer?;
     private styleChangeHandler?;
+    private pendingBuildingClick?;
+    private pendingRoadClick?;
+    private pendingSelectionStyle?;
+    private pendingLayerSubscribers;
+    private pendingBuildingHover?;
+    private pendingHoverStyle?;
+    private pendingHoverEnabled?;
     private constructor();
     private static getInstanceKey;
     private static normalizeLanguage;
@@ -533,6 +564,11 @@ declare class MahalMap {
         x: number;
         y: number;
     }, tolerancePx?: number): IMaps3DRoadHit | null;
+    static onBuildingHover(instance: MahalMap, callback: ((info: IMaps3DBuildingClickInfo | null) => void) | null): void;
+    static setHoverEnabled(instance: MahalMap, enabled: boolean): void;
+    static setHoverStyle(instance: MahalMap, style: IMaps3DHoverStyle): void;
+    static hoverBuilding(instance: MahalMap, id: number | string | null): boolean;
+    static hoveredBuilding(instance: MahalMap): string | number | null;
     static setLanguage(instance: MahalMap, lang: MapLanguage): void;
     static setCenter(instance: MahalMap, center: [number, number]): void;
     static setZoom(instance: MahalMap, zoom: number): void;
@@ -592,7 +628,10 @@ declare class MahalMap {
     getLayerState(id: Maps3DLayerId): IMaps3DLayerState | null;
     /** Снимок всех слоёв — по нему приложение рисует свою панель. */
     getLayers(): IMaps3DLayerState[];
-    /** Подписка на изменения слоёв. Возвращает отписку (no-op, если слоя нет). */
+    /**
+     * Подписка на изменения слоёв. Возвращает отписку. Работает и до появления слоя:
+     * подписка переиграется при его подключении, а отписка снимет её в любом случае.
+     */
     onLayers(callback: (state: IMaps3DLayerState) => void): () => void;
     /** Пере-применить волю клиента ко всем слоям — после полной смены стиля. */
     refreshLayers(): void;
@@ -608,14 +647,21 @@ declare class MahalMap {
      * и метка окажется в чужом зале.
      */
     showPlace(lon: number, lat: number, level?: number | null, zoom?: number): void;
-    /** Клик по зданию: { id, height, props } либо null. Повторный вызов заменяет обработчик. */
+    /**
+     * Клик по зданию: { id, height, props } либо null. Повторный вызов заменяет обработчик.
+     * Подписываться можно сразу после create(), даже когда слой ещё не поднят
+     * (`enable3D: false`) — подписка переиграется, как только слой появится.
+     */
     onBuildingClick(callback: (info: IMaps3DBuildingClickInfo | null) => void): void;
     /** Выделить здание по osm_id. `false` — здания сейчас нет в загруженных данных. */
     selectBuilding(id: number | string | null, style?: IMaps3DSelectionStyle): boolean;
     clearSelection(): void;
     selectedBuilding(): number | string | null;
     setSelectionStyle(style: IMaps3DSelectionStyle): void;
-    /** Клик по дороге. Приходит независимо от клика по зданию — приоритет решает приложение. */
+    /**
+     * Клик по дороге. Приходит независимо от клика по зданию — приоритет решает приложение.
+     * Как и onBuildingClick, переживает отсутствие слоя на момент подписки.
+     */
     onRoadClick(callback: (hit: IMaps3DRoadHit | null) => void): void;
     /** Дорога под точкой холста. Допуск по умолчанию — 12 px. */
     roadAt(point: {
@@ -624,11 +670,45 @@ declare class MahalMap {
     }, tolerancePx?: number): IMaps3DRoadHit | null;
     /** Есть ли в текущем стиле названия дорог. Нет — roadAt() всегда вернёт null. */
     get roadsNamed(): boolean;
+    /**
+     * Подписаться на наведение. Колбэк приходит только в момент смены дома под курсором,
+     * а не на каждое движение мыши. `null` отписывает и гасит подсветку.
+     *
+     * Слежение за мышью включается самой подпиской: без неё SDK курсор не трогает и
+     * разбор сцены не делает.
+     */
+    onBuildingHover(callback: ((info: IMaps3DBuildingClickInfo | null) => void) | null): void;
+    /**
+     * Включить/выключить наведение, не трогая подписку. Нужно там, где подсветка мешает:
+     * режим рисования, открытая карточка объекта, тач-устройство без курсора.
+     */
+    setHoverEnabled(enabled: boolean): void;
+    /** Включено ли наведение прямо сейчас. */
+    get hoverEnabled(): boolean;
+    /** Облик наведения: цвет, плотность, свечение, длительность и CSS-курсор. */
+    setHoverStyle(style: IMaps3DHoverStyle): void;
+    /**
+     * Навести на здание программно — например, когда курсор стоит на строке списка.
+     * Идентификатор тот же, что у selectBuilding. `null` снимает наведение.
+     *
+     * Следующее движение мыши по карте перебивает программное наведение.
+     *
+     * @returns `false`, если такого дома сейчас на карте нет.
+     */
+    hoverBuilding(id: number | string | null): boolean;
+    /** Идентификатор дома под наведением или `null`. */
+    hoveredBuilding(): number | string | null;
     /**
      * Создаёт слой Maps3D. `buildings` не форсируем в `true`: с 0.7.x видимостью объёма
      * заведует реестр слоёв, а опции облика зданий приходят из options.maps3d как есть.
      */
     private createMaps3DLayer;
+    /**
+     * Переигрывает волю клиента на только что подключённом слое: подписки на клики,
+     * облик выделения и подписчиков реестра. Нужно, когда карта создана без слоя
+     * (`enable3D: false`) — тогда всё это было сказано до его появления.
+     */
+    private applyPendingSubscriptions;
     private attachMaps3DLayer;
     /**
      * Освобождает слой Maps3D одним доступным методом (destroy(), иначе remove()) и ровно один
@@ -936,4 +1016,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 IMaps3DIndoorOptions, type IMaps3DLayer, type IMaps3DLayerOptions, type IMaps3DLayerParams, type IMaps3DLayerState, type IMaps3DMapOptionsInput, type IMaps3DMapOptionsResult, type IMaps3DObjectsLightOptions, type IMaps3DPlacesOptions, type IMaps3DRoadHit, type IMaps3DSelectionStyle, type IMaps3DTrafficOptions, type IMaps3DTransformRequestOptions, type IResponse, type IRoute, type ISearchByLocationParam, type ISearchParam, type ISearchResponse, MahalMap, MahalMapDefaultMarker, type MahalMapDefaultMarkerProps, type MapEngine, type MapLanguage, type MapStyleFamily, type Maps3DBuildingDetail, type Maps3DCtor, type Maps3DLayerId, 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 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 IMaps3DMapOptionsInput, type IMaps3DMapOptionsResult, type IMaps3DObjectsLightOptions, type IMaps3DPlacesOptions, type IMaps3DRoadHit, type IMaps3DSelectionStyle, type IMaps3DTrafficOptions, type IMaps3DTransformRequestOptions, type IResponse, type IRoute, type ISearchByLocationParam, type ISearchParam, type ISearchResponse, MahalMap, MahalMapDefaultMarker, type MahalMapDefaultMarkerProps, type MapEngine, type MapLanguage, type MapStyleFamily, type Maps3DBuildingDetail, type Maps3DCtor, type Maps3DLayerId, 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 Theme, index$2 as keyUtils, index$1 as measureUtils, index as utils };