@mappedin/mappedin-js 6.19.0 → 6.21.0

package/lib/esm/index.d.ts

@@ -2,7 +2,7 @@ import * as _mappedin_mvf_v22 from "@mappedin/mvf-v2";
 import { AnnotationCollection, AnnotationSymbol, AreaCollection, AreaId, BaseTextAreaProperties, Category, CategoryId, Connection as Connection$1, Details, EnterpriseCategory as EnterpriseCategory$1, EnterpriseCategoryId, EnterpriseLocation as EnterpriseLocation$1, EnterpriseLocationId, EnterpriseLocationInstance, EnterpriseTexture, EnterpriseVenue as EnterpriseVenue$1, EnterpriseVenueType, EntranceCollection, EntranceFeature, Facade as Facade$1, Feature as Feature$1, FeatureCollection as FeatureCollection$1, FloatingFloorTextProperties, FloorCollection, FloorId, FloorProperties, FloorStack as FloorStack$1, FloorTextCommonProperties, Geometry as Geometry$1, Hyperlink as Hyperlink$1, Image, Language, LineStringStyle, LineStringStyle as TMVFLineStringStyle, Location, LocationId, LocationLink, LocationSocial, LocationSocial as LocationSocial$1, LocationState, LocationState as LocationState$1, MVFv2_STANDARD_MVFv3, MultiPolygon as MultiPolygon$1, NavigationFlagDeclarations, NodeCollection, NodeId, ObstructionCollection, ObstructionCollection as ObstructionCollection$1, ObstructionFeature, ObstructionId, OpeningHoursSpecification, OperationHours, OperationHours as OperationHours$1, ParsedMVF, ParsedMVF as TMVF, ParsedMVFLocalePack, Point as Point$1, PointStyle, PointStyle as TMVFPointStyle, Polygon as Polygon$1, PolygonStyle, PolygonStyle as TMVFPolygonStyle, SiblingGroup, SiblingGroup as SiblingGroup$1, SpaceCollection, SpaceCollection as SpaceCollection$1, SpaceFeature, SpaceId, SpaceProperties, Style as TMVFStyle, StyleCollection, StyleCollection as TMVFStyleCollection, TilesetStyle } from "@mappedin/mvf-v2";
 import { MVFv2_STANDARD_MVFv3 as MVFv2_STANDARD_MVFv3$1, ParsedMVF as ParsedMVF$1, RawMVF } from "@mappedin/mvf-v2/no-validator-lite";
 import * as _mappedin_renderer_three0 from "@mappedin/renderer-three";
-import { AddLabelOptionsInternal, AddText3DOptions, AddText3DOptions as AddText3DOptions$1, AddText3DPointOptions, CameraSystemState, ColorString, DebugState, DebugState as DebugState$1, EntityId, EnvMapOptions, EnvMapOptions as EnvMapOptions$1, GLTFExportOptions as GLTFExportOptions$1, GroupContainerState, ISystemPlugin, ISystemPlugin as ISystemPlugin$1, ImagePlacementOptions, InitializeModelState, InitializeModelState as InitializeModelState$1, InitializeText3DState, InsetPadding, InsetPadding as InsetPadding$1, InsetPaddingOption, InsetPaddingOption as InsetPaddingOption$1, InterpolateOn, Interpolation, LabelAppearance as LabelAppearance$1, LabelRenderedState, LabelTextPlacement as LabelTextPlacement$1, LineStyle, LineStyle as LineStyle$1, MapViewState, MarkerState, OutlinesOptions, PaintStyle, PaintStyle as PaintStyle$1, PathState, PathWidth, PathWidth as PathWidth$1, PixelWidth, Position as Position$1, RendererCore, RendererCoreOptions, RendererCoreOptions as RendererCoreOptions$1, Shading, Text3DState, WatermarkUpdateOptions } from "@mappedin/renderer-three";
+import { AddLabelOptionsInternal, AddText3DOptions, AddText3DOptions as AddText3DOptions$1, AddText3DPointOptions, CameraSystemState, ColorString, DebugState, DebugState as DebugState$1, EntityId, EnvMapOptions, EnvMapOptions as EnvMapOptions$1, GLTFExportOptions as GLTFExportOptions$1, GroupContainerState, ISystemPlugin, ISystemPlugin as ISystemPlugin$1, ImagePlacementOptions, InitializeModelState, InitializeModelState as InitializeModelState$1, InitializeText3DState, InsetPadding, InsetPadding as InsetPadding$1, InsetPaddingOption, InsetPaddingOption as InsetPaddingOption$1, InterpolateOn, Interpolation, LabelRenderedState, LineStyle, LineStyle as LineStyle$1, MapViewState, MarkerState, OutlinesOptions, PaintStyle, PaintStyle as PaintStyle$1, PathState, PathWidth, PathWidth as PathWidth$1, PixelWidth, Position as Position$1, RendererCore, RendererCoreOptions, RendererCoreOptions as RendererCoreOptions$1, Shading, Text3DState, WatermarkUpdateOptions } from "@mappedin/renderer-three";
 import * as _tweenjs_tween_js0 from "@tweenjs/tween.js";
 import { Group, Tween } from "@tweenjs/tween.js";
 import { CustomLayerInterface, IControl, Map as Map$1, MapEventType } from "@mappedin/outdoor-context";
@@ -209,6 +209,11 @@ type TSearchOptions = {
    */
   enabled: boolean;
 };
+/**
+ * Options shared by every {@link getMapData} call regardless of authentication mode.
+ * Carries the target `mapId` and optional overrides such as environment, base URL,
+ * and language preferences.
+ */
 type TGetMapDataSharedOptions = {
   /**
    * Mappedin map ID.
@@ -304,8 +309,12 @@ type TGetMapDataSharedOptions = {
    */
   prefetchTokens?: boolean;
   /**
-   * @hidden
-   * @internal
+   * Load draft (unpublished) enterprise map instead of the live version.
+   * Set to `"draft"` to fetch the latest unpublished changes.
+   * Leave unspecified to load the published live data.
+   *
+   * Requires an Enterprise API key. Only applicable to maps made in Mappedin CMS.
+   * @default undefined
    */
   layoutId?: 'draft';
   /**
@@ -344,6 +353,8 @@ type TGetMapDataWithCredentialsOptions = {
   secret: string;
 } & TGetMapDataSharedOptions;
 /**
+ * {@link getMapData} options that authenticate with a pre-issued access token,
+ * as opposed to a `key`/`secret` pair.
  * @interface
  */
 type TGetMapDataWithAccessTokenOptions = {
@@ -352,6 +363,10 @@ type TGetMapDataWithAccessTokenOptions = {
    */
   accessToken: string;
 } & TGetMapDataSharedOptions;
+/**
+ * Options accepted by {@link getMapData}. Either credentials (`key`/`secret`) or an
+ * `accessToken` may be supplied alongside the shared options.
+ */
 type TGetMapDataOptions = TGetMapDataWithCredentialsOptions | TGetMapDataWithAccessTokenOptions;
 /**
  * @internal
@@ -399,9 +414,21 @@ type ParsedMVFResult = {
   mvf2: ParsedMVF$1;
   mvf3?: MVFv2_STANDARD_MVFv3$1;
 };
+/**
+ * Decompress and parse a binary MVF (Mappedin Venue Format) payload into the
+ * structured `ParsedMVFResult` consumed by {@link hydrateMapData}.
+ *
+ * @param data - The gzipped MVF binary payload.
+ * @param inputVersion - The MVF schema version to parse against.
+ */
 declare function unzipAndParseMVFv2(data: Uint8Array, inputVersion?: string): Promise<ParsedMVFResult>;
 //#endregion
 //#region src/hydrate-map-data.d.ts
+/**
+ * Pre-fetched MVF data passed to {@link hydrateMapData} so a map can be constructed
+ * without going to the network. Supports both binary (`Uint8Array`) and JSON forms,
+ * optional language packs, and matches the shape produced by Mappedin's CDN.
+ */
 type THydrateMapDataBundle = {
   type: 'binary';
   options?: {
@@ -599,8 +626,19 @@ type CaptureEventsPayloadMap = {
      * Optional array of result IDs (hits).
      */
     hits?: string[];
+    /**
+     * Total number of results returned for the query across all result categories
+     * (places + enterprise locations + enterprise categories). Useful for identifying
+     * queries that return no results (`resultCount === 0`).
+     */
+    resultCount?: number;
   };
 };
+/**
+ * Sends user interaction analytics events to Mappedin's analytics backend.
+ * Captures map loads, search queries, directions, and custom user events so
+ * usage of an indoor map can be measured and tuned.
+ */
 declare class Analytics {
   #private;
   /**
@@ -635,6 +673,12 @@ declare class Analytics {
     analyticsBaseUrl: string;
     /** Flag to disable authentication. */
     noAuth: boolean;
+    /**
+     * Marks the tenant as an enterprise venue. Only enterprise venues are allowed to send
+     * `x-mappedin-key` / `x-mappedin-secret` headers to the analytics gateway — non-enterprise
+     * tenants must use `accessToken` (Bearer) auth, otherwise the gateway returns 401.
+     */
+    enterprise: boolean;
     /** Flag to enable geolocation mode. */
     geolocationMode: boolean;
     /** The context in which the analytics are being used. */
@@ -689,6 +733,12 @@ type AnalyticState = {
   analyticsBaseUrl: string;
   /** Flag to disable authentication. */
   noAuth: boolean;
+  /**
+   * Marks the tenant as an enterprise venue. Only enterprise venues are allowed to send
+   * `x-mappedin-key` / `x-mappedin-secret` headers to the analytics gateway — non-enterprise
+   * tenants must use `accessToken` (Bearer) auth, otherwise the gateway returns 401.
+   */
+  enterprise: boolean;
   /** Flag to enable geolocation mode. */
   geolocationMode: boolean;
   /** @internal The device ID to be used for analytics. */
@@ -3056,6 +3106,15 @@ declare const LABEL_TEXT_PLACEMENT: {
   readonly CENTER: "center";
 };
 declare const LABEL_LOW_PRIORITY = "low-priority";
+/**
+ * The placement of a label's text relative to its pin.
+ *
+ * - `'right'` — text appears to the right of the pin.
+ * - `'left'` — text appears to the left of the pin.
+ * - `'top'` — text appears above the pin.
+ * - `'hidden'` — text is hidden, only the pin is visible.
+ * - `'center'` — text is centered at the pin location and the pin is hidden.
+ */
 type LabelTextPlacement = (typeof LABEL_TEXT_PLACEMENT)[keyof typeof LABEL_TEXT_PLACEMENT];
 type LabelTextPlacementInternal = LabelTextPlacement | typeof LABEL_LOW_PRIORITY;
 type EasingCurve$1 = string;
@@ -3108,7 +3167,66 @@ declare const labelAppearanceSchemaBase: ZodObject<{
   __EXPERIMENTAL_wrapperShadowOffsetX: ZodDefault<ZodNumber>;
   __EXPERIMENTAL_wrapperShadowOffsetY: ZodDefault<ZodNumber>;
   __EXPERIMENTAL_wrapperShadowBlur: ZodDefault<ZodNumber>;
+  __EXPERIMENTAL_wrapperOpacity: ZodDefault<ZodNumber>;
 }, $strip>;
+/**
+ * Options to control how a label is rendered.
+ *
+ * | Option | Type | Description | Default |
+ * |--------|------|-------------|---------|
+ * | `margin` | `number` | Margin around the label text and pin in pixels. This will affect label density. Minimum is 6px. | 6 |
+ * | `maxLines` | `number` | Number of lines to display when text spans multiple lines. | 2 |
+ * | `textSize` | `number` | Text size in pixels | 11.5 |
+ * | `maxWidth` | `number` | Maximum width of text in pixels. | 150 |
+ * | `lineHeight` | `number` | Line height sets the height of a line box. It's commonly used to set the distance between lines of text. | 1.2 |
+ * | `color` | `string` | A color string for the label text and pin. | `#333` |
+ * | `outlineColor` | `string` | A color string for the outline around the label text and pin. | `white` |
+ * | `textColor` | `string` | A color string representing just the text color. Defaults to the same as `color`. | - |
+ * | `textOutlineColor` | `string` | A color string representing just the text outline. Defaults to the same as `outlineColor`. | - |
+ * | `pinColor` | `string` | A color string representing just the pin color. Defaults to the same as `color`. | - |
+ * | `pinOutlineColor` | `string` | A color string representing just the pin outline. Defaults to the same as `outlineColor`. | - |
+ * | `pinColorInactive` | `string` | A color string representing just the pin color when the label is inactive. Defaults to the same as `pinColor`. | - |
+ * | `pinOutlineColorInactive` | `string` | A color string representing just the pin outline when the label is inactive. Defaults to the same as `pinOutlineColor`. | - |
+ * | `icon` | `string` | An icon to be placed inside the label pin. Can be an SVG string or a path to a PNG or JPEG. | - |
+ * | `iconSize` | `number` | Size of the icon in pixels. Requires `icon` to be set. | 20 |
+ * | `iconScale` | `number` \| {@link Interpolation} | Scale the icon uniformly. Specify a number or an {@link Interpolation} object. | 1 |
+ * | `iconPadding` | `number` | Padding between the icon and the pin's border in pixels. | 2 |
+ * | `iconFit` | `'fill'` \| `'contain'` \| `'cover'` | How the icon should fit inside the pin. Options: `fill` (stretch to fill), `cover` (maintain aspect ratio and fill), `contain` (maintain aspect ratio and fit inside). | `cover` |
+ * | `iconOverflow` | `'visible'` \| `'hidden'` | Whether the icon should overflow the circle of the pin. | `hidden` |
+ * | `iconVisible` | `boolean` \| `number` | Controls icon visibility. If boolean, directly shows/hides the icon. If number, defines the zoom level at which the icon becomes visible. | `true` |
+ * | `opacity` | `number` | The opacity of the Label when it is enabled and visible. | `1` |
+ *
+ * @example Render a label with an SVG icon
+ * ```ts
+ * mapView.Labels.add(space, "Label", {
+ * 	appearance: {
+ * 		icon: `<svg>...</svg>`,
+ * 	},
+ * });
+ * ```
+ *
+ * @example Render a label with an image icon
+ * ```ts
+ * mapView.Labels.add(space, "Label", {
+ * 	appearance: {
+ * 		icon: 'https://example.com/icon.png',
+ * 	},
+ * });
+ * ```
+ *
+ * @example Scale a label's icon with zoom level
+ * ```ts
+ * mapView.Labels.add(space, "Label", {
+ * 	appearance: {
+ * 		iconScale: {
+ * 			on: 'zoom-level',
+ * 			input: [19, 22],
+ * 			output: [1, 3],
+ * 		},
+ * 	},
+ * });
+ * ```
+ */
 type LabelAppearance = Partial<input<typeof labelAppearanceSchemaBase>> & {
   iconScale?: number | Interpolation$2<'zoom-level', number[]>;
 };
@@ -3156,6 +3274,7 @@ declare const labelAppearanceSchema: ZodPipe<ZodObject<{
   __EXPERIMENTAL_wrapperShadowOffsetX: ZodDefault<ZodNumber>;
   __EXPERIMENTAL_wrapperShadowOffsetY: ZodDefault<ZodNumber>;
   __EXPERIMENTAL_wrapperShadowBlur: ZodDefault<ZodNumber>;
+  __EXPERIMENTAL_wrapperOpacity: ZodDefault<ZodNumber>;
 }, $strip>, ZodTransform<Required<LabelAppearance>, {
   margin: number;
   maxLines: number;
@@ -3183,6 +3302,7 @@ declare const labelAppearanceSchema: ZodPipe<ZodObject<{
   __EXPERIMENTAL_wrapperShadowOffsetX: number;
   __EXPERIMENTAL_wrapperShadowOffsetY: number;
   __EXPERIMENTAL_wrapperShadowBlur: number;
+  __EXPERIMENTAL_wrapperOpacity: number;
   textColor?: string | undefined;
   textOutlineColor?: string | undefined;
   pinColor?: string | undefined;
@@ -3252,6 +3372,7 @@ declare class LabelComponent {
   interactive: boolean;
   isOccluded: boolean;
   offscreen: boolean;
+  disposed: boolean;
   /**
    * Whether the label can be shown, which is decided by the collision engine
    */
@@ -4595,6 +4716,11 @@ type TNavigationOptions = {
     animated?: boolean;
   };
 };
+/**
+ * Snapshot of the navigation system's state at a point in time, including the
+ * active floors, paths, and directions. Returned by `Navigation.getState()` and
+ * suitable for serialization or use in undo/redo flows.
+ */
 type NavigationState = {
   isMultiFloor: boolean;
   floorStacks: FloorStack[];
@@ -4790,6 +4916,10 @@ declare class Navigation {
   get travelledFraction(): number | null;
   /**
    * Highlights path section between two coordinates. This can be used to highlight any section of the path or indicated the currently traveled path.
+   *
+   * In multi-destination mode the highlight is scoped to the active path so
+   * that a `from`/`to` pair on the active route doesn't accidentally pull in
+   * (or get matched to) segments from other destinations.
    */
   highlightPathSection(from: Coordinate, to: Coordinate, options?: TPathSectionHighlightOptions): {
     animation: Promise<unknown>;
@@ -4916,7 +5046,7 @@ declare class Footprint {
   /**
    * Builds the basement mask for elevation 0 floors
    */
-  buildBasementMask(): void;
+  buildBasementMask(spacesOpenToBelow?: Feature$1<Polygon$1, SpaceProperties>[]): void;
   /**
    * Updates the state of the footprint geometry (walls and ceiling)
    * @param state Partial state to update
@@ -4954,6 +5084,12 @@ declare class FloorObject implements FloorProperties {
   shortName?: string | undefined;
   subtitle?: string | undefined;
   occluderId?: number;
+  /**
+   * Entity id of the per-floor geometry group container created in {@link load}.
+   * Used to parent ancillary content (e.g. the focusable footprint) so visibility
+   * is driven by the same container as the rest of the floor geometry.
+   */
+  geometryContainer?: EntityId<GroupContainerState>;
   private loaded;
   private styleMap;
   private obstructions?;
@@ -5002,6 +5138,14 @@ declare class FloorObject implements FloorProperties {
    * Add an occluder to the floor if it has a footprint.
    */
   addOccluder(): void;
+  /**
+   * Adds an invisible extruded footprint geometry to the floor that participates
+   * in dynamic focus. Using a single merged feature gives the geometry-in-focus
+   * system a stable bounding volume per floor without scanning every interior
+   * space, and the resulting entity id `${FOCUSABLE_FOOTPRINT_PREFIX}${floorId}-merged`
+   * is the canonical id resolved back to the floor by `getFacadeFromEntityId`.
+   */
+  addFocusFootprint(): void;
   /**
    * Whether the floor contains facade geometry.
    */
@@ -5332,6 +5476,7 @@ declare class Shapes {
    * ```ts
    * const shape = mapView.Shapes.add(geometry, {
    *   color: 'green',
+   *   hoverColor: 'blue',
    *   opacity: 0.7,
    *   height: 2,
    *   interactive: true
@@ -5369,6 +5514,11 @@ type InspectorState = {
 type InspectorOption = Partial<InspectorState>;
 //#endregion
 //#region src/debug.d.ts
+/**
+ * Diagnostic utilities exposed at `MapView.Debug`. Provides toggles for
+ * debug visualizations, snapshots of the current camera state, and other
+ * inspection helpers useful while developing against Mappedin JS.
+ */
 declare class Debug {
   #private;
   state: DebugState$1;
@@ -6290,6 +6440,10 @@ type PartialExcept<T$1, K$1 extends string> = { [P in keyof T$1 as P extends K$1
 type ExtractDeep<T$1, U$1, Depth extends readonly number[] = []> = Depth['length'] extends 3 ? any : { [K in keyof T$1 as T$1[K] extends U$1 ? K : T$1[K] extends object | undefined ? ExtractDeep<NonNullable<T$1[K]>, U$1, [...Depth, 0]> extends never ? never : K : never]: T$1[K] extends object | undefined ? undefined extends T$1[K] ? ExtractDeep<NonNullable<T$1[K]>, U$1, [...Depth, 0]> | undefined : ExtractDeep<NonNullable<T$1[K]>, U$1, [...Depth, 0]> : T$1[K] extends U$1 ? T$1[K] : never };
 //#endregion
 //#region src/api-geojson/auto/index.d.ts
+/**
+ * Map view objects automatically created by `MapView.auto()` — typically labels
+ * and markers generated from venue data for common element types.
+ */
 type AutoElements = {
   labels: Label[];
   markers: Marker[];
@@ -7126,6 +7280,11 @@ declare class MapView {
   /**
    * Get the X and Y of a {@link Coordinate} measured from the top left corner of the map canvas.
    *
+   * The projected altitude is derived from the floor's live state (via `coordinate.floorId`)
+   * plus `coordinate.verticalOffset`. For coordinates without a `floorId`, `verticalOffset`
+   * is used directly as an absolute scene altitude — useful for "what if" projections at
+   * arbitrary altitudes without mutating the scene.
+   *
    * @experimental
    */
   getScreenCoordinateFromCoordinate(coordinate: Coordinate): {
@@ -7634,6 +7793,24 @@ declare class Camera {
    * The current elevation of the camera in meters.
    */
   get elevation(): number;
+  /**
+   * The maximum elevation (in meters) the camera is allowed to reach.
+   * @default Infinity
+   */
+  get maxElevation(): number;
+  /**
+   * Cap the camera's elevation in meters. Useful when `panMode` is
+   * `'elevation'` (vertical drag) to prevent the camera from rising above a
+   * building or floor stack. Pass `Infinity` to remove the cap.
+   *
+   * Applies to user pedestal drag, `setElevation`, and `animateElevation`.
+   * If the current elevation is above the new cap it is snapped down to it.
+   *
+   * @experimental
+   * @param maxElevation The new maximum elevation in meters.
+   * @default Infinity
+   */
+  setMaxElevation(maxElevation: number): void;
   /**
    * Animate the camera's elevation to a specified elevation.
    * @experimental
@@ -8389,6 +8566,11 @@ declare class Paths {
 type CurrentMapGetter$2 = () => GeojsonApiMapObject | undefined;
 //#endregion
 //#region src/api-geojson/style.d.ts
+/**
+ * Applies named visual style presets to the current map. Accessible from
+ * {@link MapView.Style}, it supports loading a {@link StyleCollection} or
+ * setting an individual style by id.
+ */
 declare class Style {
   #private;
   /**
@@ -8416,9 +8598,11 @@ type HiddenOutdoorGeometry = [polygons: GeoJSON.Feature<GeoJSON.Polygon | GeoJSO
  * [MapLibre GL JS](https://maplibre.org/maplibre-gl-js/docs/) is a TypeScript library that uses WebGL to render interactive maps from vector tiles in a browser. The Mappedin SDK makes use of it to display the outdoor map.
  *
  * By providing access to the MapLibre map used to draw the outdoor map, the Mappedin SDK enables developers to draw on and manipulate the outdoor map.
- * Developers can use most capabilities of MapLibre GL JS with key exceptions being Interactivity and Camera, which are not available.
+ * Developers can use most capabilities of MapLibre GL JS. The key exception is Interactivity, which is not available; direct Camera control is discouraged because Mappedin JS owns the outdoor camera (see below).
+ *
+ * User touch and click events are handled by Mappedin JS and are not propagated to the outdoor map layer. Camera movement is also driven by Mappedin JS; moving the MapLibre camera directly is not supported and may be overridden.
  *
- * User touch and click events are handled by Mappedin JS and are not propagated to the outdoor map layer. Camera movement is also handled by Mappedin JS and cannot be manipulated using MapLibre controls.
+ * IMPORTANT: Moving the camera via `Outdoor.map` (for example `Outdoor.map.flyTo` / `easeTo` / `jumpTo` / `setZoom`) is not supported — Mappedin JS controls the outdoor camera and may override these calls. Use {@link MapView.Camera} (for example {@link Camera.animateTo}, {@link Camera.set}, or {@link Camera.focusOn}) instead.
  *
  * Refer to the [Outdoor Map Guide](https://developer.mappedin.com/web-sdk/outdoor-map) for more information and interactive examples.
  */
@@ -8434,11 +8618,30 @@ declare class Outdoor {
    */
   setStyle(style: any): void;
   /**
-   * Returns a Maplibre map for advanced usage.
+   * Returns the underlying MapLibre GL map for **advanced, non-camera** usage,
+   * such as adding custom layers, sources, GeoJSON, or deck.gl overlays.
    *
-   * @returns {object} Maplibre map instance
+   * IMPORTANT: Moving the camera through this object is not supported. Camera
+   * control (center, zoom, bearing, pitch, elevation) is owned by Mappedin JS,
+   * so MapLibre camera methods such as `flyTo`, `easeTo`, `jumpTo`, `panTo`,
+   * `zoomTo`, `setZoom`, `setCenter`, `setBearing`, or `setPitch` may be
+   * overridden. Use the {@link Camera} API instead — it is the supported,
+   * fully-featured path (animation promises, collision-aware framing).
+   *
+   * To move the camera, use the {@link Camera} API instead:
+   * - {@link Camera.animateTo} — smoothly move to a center / zoom / bearing / pitch
+   * - {@link Camera.set} — instantly set the camera
+   * - {@link Camera.focusOn} — frame one or more map elements
+   *
+   * @example Move the camera to a coordinate (correct — do NOT use `Outdoor.map.flyTo`)
+   * ```ts
+   * mapView.Camera.animateTo({ center: coordinate, zoomLevel: 19 }, { duration: 600 });
+   * ```
+   *
+   * @returns The MapLibre GL `Map` instance, or `undefined` if the outdoor view is disabled.
    *
    * Limitations:
+   * - Camera methods are not supported (see above) — use {@link MapView.Camera} to move the camera.
    * - Maplibre interaction events are not supported, use Mappedin JS interaction events.
    * - Maplibre markers and labels may overlap as they are not integrated with the Mappedin JS collision engine.
    */
@@ -8659,6 +8862,7 @@ declare class Text3D {
 }
 //#endregion
 //#region src/states/doors-state.d.ts
+/** @internal */
 declare const doorsStateSchemaPartial: ZodObject<{
   type: ZodOptional<ZodDefault<ZodLiteral<"doors">>>;
   color: ZodOptional<ZodDefault<ZodString>>;
@@ -8672,6 +8876,7 @@ declare const doorsStateSchemaPartial: ZodObject<{
   visible: ZodOptional<ZodDefault<ZodBoolean>>;
   opacity: ZodOptional<ZodDefault<ZodNumber>>;
 }, $strip>;
+/** @internal */
 declare const doorsStateSchemaStrict: ZodObject<{
   type: ZodDefault<ZodLiteral<"doors">>;
   color: ZodDefault<ZodString>;
@@ -8685,24 +8890,39 @@ declare const doorsStateSchemaStrict: ZodObject<{
   visible: ZodDefault<ZodBoolean>;
   opacity: ZodDefault<ZodNumber>;
 }, $strict>;
+/**
+ * The serialized state of all doors in the map, including their colors and visibility.
+ */
 type TDoorsState = output<typeof doorsStateSchemaStrict>;
+/**
+ * A partial doors state used to apply incremental updates, where every field is optional.
+ */
 type TDoorsUpdateState = output<typeof doorsStateSchemaPartial>;
 //#endregion
 //#region src/states/facade-state.d.ts
+/** @internal */
 declare const facadeStateSchemaPartial: ZodObject<{
   type: ZodOptional<ZodDefault<ZodLiteral<"facade">>>;
   opacity: ZodOptional<ZodDefault<ZodNumber>>;
   visible: ZodOptional<ZodDefault<ZodBoolean>>;
 }, $strip>;
+/** @internal */
 declare const facadeStateSchemaStrict: ZodObject<{
   type: ZodDefault<ZodLiteral<"facade">>;
   opacity: ZodDefault<ZodNumber>;
   visible: ZodDefault<ZodBoolean>;
 }, $strict>;
+/**
+ * The serialized state of all building facades, including their materials and visibility.
+ */
 type TFacadeState = output<typeof facadeStateSchemaStrict>;
+/**
+ * A partial facades state used to apply incremental updates, where every field is optional.
+ */
 type TFacadeUpdateState = output<typeof facadeStateSchemaPartial>;
 //#endregion
 //#region src/states/floor-state.d.ts
+/** @internal */
 declare const floorStateSchemaPartial: ZodObject<{
   geometry: ZodOptional<ZodObject<{
     type: ZodOptional<ZodDefault<ZodLiteral<"floor.geometry">>>;
@@ -8780,6 +9000,7 @@ declare const floorStateSchemaPartial: ZodObject<{
   visible: ZodOptional<ZodDefault<ZodBoolean>>;
   altitude: ZodOptional<ZodDefault<ZodNumber>>;
 }, $strip>;
+/** @internal */
 declare const floorStateSchemaStrict: ZodObject<{
   geometry: ZodObject<{
     type: ZodDefault<ZodLiteral<"floor.geometry">>;
@@ -8857,17 +9078,24 @@ declare const floorStateSchemaStrict: ZodObject<{
   visible: ZodDefault<ZodBoolean>;
   altitude: ZodDefault<ZodNumber>;
 }, $strict>;
+/**
+ * The serialized state of a floor, including its geometry, labels, markers, paths, and visibility.
+ */
 type TFloorState = output<typeof floorStateSchemaStrict>;
+/**
+ * A partial floor state used to apply incremental updates, where every field is optional.
+ */
 type TFloorUpdateState = output<typeof floorStateSchemaPartial>;
 //#endregion
 //#region src/states/geometry-state.d.ts
+/** @internal */
 declare const geometryStateSchemaPartial: ZodObject<{
   type: ZodOptional<ZodDefault<ZodLiteral<"geometry">>>;
   visible: ZodOptional<ZodDefault<ZodBoolean>>;
   color: ZodOptional<ZodDefault<ZodUnion<readonly [ZodString, ZodLiteral<"initial">]>>>;
   topColor: ZodOptional<ZodOptional<ZodUnion<readonly [ZodString, ZodLiteral<"initial">]>>>;
   hoverColor: ZodOptional<ZodOptional<ZodUnion<readonly [ZodString, ZodLiteral<"initial">]>>>;
-  interactive: ZodOptional<ZodDefault<ZodBoolean>>;
+  interactive: ZodOptional<ZodDefault<ZodUnion<readonly [ZodBoolean, ZodLiteral<"pass-through">]>>>;
   opacity: ZodOptional<ZodDefault<ZodNumber>>;
   height: ZodOptional<ZodDefault<ZodNumber>>;
   altitude: ZodOptional<ZodDefault<ZodNumber>>;
@@ -8883,13 +9111,14 @@ declare const geometryStateSchemaPartial: ZodObject<{
   borderColor: ZodOptional<ZodOptional<ZodString>>;
   borderWidth: ZodOptional<ZodOptional<ZodNumber>>;
 }, $strip>;
+/** @internal */
 declare const geometryStateSchemaStrict: ZodObject<{
   type: ZodDefault<ZodLiteral<"geometry">>;
   visible: ZodDefault<ZodBoolean>;
   color: ZodDefault<ZodUnion<readonly [ZodString, ZodLiteral<"initial">]>>;
   topColor: ZodOptional<ZodUnion<readonly [ZodString, ZodLiteral<"initial">]>>;
   hoverColor: ZodOptional<ZodUnion<readonly [ZodString, ZodLiteral<"initial">]>>;
-  interactive: ZodDefault<ZodBoolean>;
+  interactive: ZodDefault<ZodUnion<readonly [ZodBoolean, ZodLiteral<"pass-through">]>>;
   opacity: ZodDefault<ZodNumber>;
   height: ZodDefault<ZodNumber>;
   altitude: ZodDefault<ZodNumber>;
@@ -8906,12 +9135,17 @@ declare const geometryStateSchemaStrict: ZodObject<{
   borderWidth: ZodOptional<ZodNumber>;
 }, $strict>;
 /**
- * Defines the state for geometry elements like {@link Space} when updated.
+ * The serialized state of a geometry element such as a {@link Space}, including
+ * its style, color, and visibility.
  */
 type TGeometryState = output<typeof geometryStateSchemaStrict>;
+/**
+ * A partial geometry state used to apply incremental updates, where every field is optional.
+ */
 type TGeometryUpdateState = output<typeof geometryStateSchemaPartial>;
 //#endregion
 //#region src/states/label-state.d.ts
+/** @internal */
 declare const labelStateSchema: ZodObject<{
   type: ZodDefault<ZodLiteral<"label">>;
   text: ZodString;
@@ -8934,6 +9168,7 @@ declare const labelStateSchema: ZodObject<{
   }>>]>>;
   occlude: ZodDefault<ZodBoolean>;
 }, $strip>;
+/** @internal */
 declare const labelStateSchemaPartial: ZodObject<{
   type: ZodOptional<ZodDefault<ZodLiteral<"label">>>;
   text: ZodOptional<ZodString>;
@@ -8956,10 +9191,18 @@ declare const labelStateSchemaPartial: ZodObject<{
   }>>]>>>;
   occlude: ZodOptional<ZodDefault<ZodBoolean>>;
 }, $strip>;
+/**
+ * The serialized state of a label, including its position, appearance, and rank.
+ * Returned by state APIs and used by extensions that need to inspect or persist label state.
+ */
 type TLabelState = output<typeof labelStateSchema>;
+/**
+ * A partial label state used to apply incremental updates, where every field is optional.
+ */
 type TLabelUpdateState = output<typeof labelStateSchemaPartial>;
 //#endregion
 //#region src/states/marker-state.d.ts
+/** @internal */
 declare const markerStateSchema: ZodObject<{
   type: ZodDefault<ZodLiteral<"marker">>;
   rank: ZodCustom<"initial" | TCollisionRankingTier, "initial" | TCollisionRankingTier>;
@@ -9000,6 +9243,7 @@ declare const markerStateSchema: ZodObject<{
   occlude: ZodDefault<ZodBoolean>;
   animated: ZodDefault<ZodBoolean>;
 }, $strip>;
+/** @internal */
 declare const markerStateSchemaPartial: ZodObject<{
   type: ZodOptional<ZodDefault<ZodLiteral<"marker">>>;
   enabled: ZodOptional<ZodDefault<ZodBoolean>>;
@@ -9039,12 +9283,23 @@ declare const markerStateSchemaPartial: ZodObject<{
   contentHTML: ZodOptional<ZodString>;
   animated: ZodOptional<ZodDefault<ZodBoolean>>;
 }, $strip>;
+/**
+ * The serialized state of a marker, including its anchor, HTML content, and rank.
+ * Returned by state APIs and used by extensions that need to inspect or persist marker state.
+ */
 type TMarkerState = output<typeof markerStateSchema>;
+/**
+ * A partial marker state used to apply incremental updates, where every field is optional.
+ */
 type TMarkerUpdateState = output<typeof markerStateSchemaPartial>;
 //#endregion
 //#region src/states/path-state.d.ts
-/** Border color - 'darken' auto-darkens main color, or explicit hex color string */
+/**
+ * Border color - 'darken' auto-darkens main color, or explicit hex color string.
+ * @internal
+ */
 type BorderColor = LiteralUnion<'darken', string>;
+/** @internal */
 declare const pathStateSchemaPartial: ZodObject<{
   type: ZodOptional<ZodDefault<ZodLiteral<"path">>>;
   color: ZodOptional<ZodDefault<ZodString>>;
@@ -9057,6 +9312,7 @@ declare const pathStateSchemaPartial: ZodObject<{
   highlightColor: ZodOptional<ZodDefault<ZodString>>;
   highlightWidthMultiplier: ZodOptional<ZodDefault<ZodNumber>>;
   highlightCompleteFraction: ZodOptional<ZodDefault<ZodNumber>>;
+  highlightDisplayArrowsOnPath: ZodOptional<ZodDefault<ZodBoolean>>;
   xrayOpacity: ZodOptional<ZodDefault<ZodNumber>>;
   travelledEndFraction: ZodOptional<ZodDefault<ZodNumber>>;
   travelledColor: ZodOptional<ZodDefault<ZodString>>;
@@ -9095,6 +9351,7 @@ declare const pathStateSchemaPartial: ZodObject<{
     dithering: ZodOptional<ZodNumber>;
   }, $strip>>>;
 }, $strip>;
+/** @internal */
 declare const pathStateSchemaStrict: ZodObject<{
   type: ZodDefault<ZodLiteral<"path">>;
   color: ZodDefault<ZodString>;
@@ -9107,6 +9364,7 @@ declare const pathStateSchemaStrict: ZodObject<{
   highlightColor: ZodDefault<ZodString>;
   highlightWidthMultiplier: ZodDefault<ZodNumber>;
   highlightCompleteFraction: ZodDefault<ZodNumber>;
+  highlightDisplayArrowsOnPath: ZodDefault<ZodBoolean>;
   xrayOpacity: ZodDefault<ZodNumber>;
   travelledEndFraction: ZodDefault<ZodNumber>;
   travelledColor: ZodDefault<ZodString>;
@@ -9145,18 +9403,27 @@ declare const pathStateSchemaStrict: ZodObject<{
     dithering: ZodOptional<ZodNumber>;
   }, $strip>>;
 }, $strict>;
+/**
+ * The serialized state of a path, including its waypoints, style, and animation.
+ * Returned by state APIs and used by extensions that need to inspect or persist path state.
+ */
 type TPathState = output<typeof pathStateSchemaStrict>;
+/**
+ * A partial path state used to apply incremental updates, where every field is optional.
+ */
 type TPathUpdateState = input<typeof pathStateSchemaPartial>;
 //#endregion
 //#region src/states/shape-state.d.ts
+/** @internal */
 declare const shapeStateSchemaPartial: ZodObject<{
   type: ZodOptional<ZodDefault<ZodLiteral<"shape">>>;
   visible: ZodOptional<ZodDefault<ZodBoolean>>;
   altitude: ZodOptional<ZodDefault<ZodNumber>>;
   color: ZodOptional<ZodDefault<ZodString>>;
+  hoverColor: ZodOptional<ZodOptional<ZodString>>;
   height: ZodOptional<ZodDefault<ZodNumber>>;
   opacity: ZodOptional<ZodDefault<ZodNumber>>;
-  interactive: ZodOptional<ZodDefault<ZodBoolean>>;
+  interactive: ZodOptional<ZodDefault<ZodUnion<readonly [ZodBoolean, ZodLiteral<"pass-through">]>>>;
   bevel: ZodOptional<ZodOptional<ZodObject<{
     enabled: ZodOptional<ZodBoolean>;
     thickness: ZodOptional<ZodNumber>;
@@ -9166,14 +9433,16 @@ declare const shapeStateSchemaPartial: ZodObject<{
   }, $strip>>>;
   position: ZodOptional<ZodCustom<Coordinate, Coordinate>>;
 }, $strip>;
+/** @internal */
 declare const shapeStateSchemaStrict: ZodObject<{
   type: ZodDefault<ZodLiteral<"shape">>;
   visible: ZodDefault<ZodBoolean>;
   altitude: ZodDefault<ZodNumber>;
   color: ZodDefault<ZodString>;
+  hoverColor: ZodOptional<ZodString>;
   height: ZodDefault<ZodNumber>;
   opacity: ZodDefault<ZodNumber>;
-  interactive: ZodDefault<ZodBoolean>;
+  interactive: ZodDefault<ZodUnion<readonly [ZodBoolean, ZodLiteral<"pass-through">]>>;
   bevel: ZodOptional<ZodObject<{
     enabled: ZodOptional<ZodBoolean>;
     thickness: ZodOptional<ZodNumber>;
@@ -9184,12 +9453,16 @@ declare const shapeStateSchemaStrict: ZodObject<{
   position: ZodCustom<Coordinate, Coordinate>;
 }, $strict>;
 /**
- * Represents the state of a shape.
+ * The serialized state of a shape feature collection, including its geometry and styling.
  */
 type TShapeState = output<typeof shapeStateSchemaStrict>;
+/**
+ * A partial shape state used to apply incremental updates, where every field is optional.
+ */
 type TShapeUpdateState = output<typeof shapeStateSchemaPartial>;
 //#endregion
 //#region src/states/image-state.d.ts
+/** @internal */
 declare const imageStateSchema: ZodObject<{
   type: ZodDefault<ZodLiteral<"image3d">>;
   visible: ZodDefault<ZodBoolean>;
@@ -9202,6 +9475,7 @@ declare const imageStateSchema: ZodObject<{
   flipImagesToFaceCamera: ZodDefault<ZodBoolean>;
   interactive: ZodDefault<ZodBoolean>;
 }, $strip>;
+/** @internal */
 declare const imageStateSchemaPartial: ZodObject<{
   type: ZodOptional<ZodDefault<ZodLiteral<"image3d">>>;
   visible: ZodOptional<ZodDefault<ZodBoolean>>;
@@ -9214,10 +9488,17 @@ declare const imageStateSchemaPartial: ZodObject<{
   flipImagesToFaceCamera: ZodOptional<ZodDefault<ZodBoolean>>;
   interactive: ZodOptional<ZodDefault<ZodBoolean>>;
 }, $strip>;
+/**
+ * The serialized state of a 3D image overlay, including its coordinate, size, and opacity.
+ */
 type TImage3DState = output<typeof imageStateSchema>;
+/**
+ * A partial 3D image state used to apply incremental updates, where every field is optional.
+ */
 type TImage3DUpdateState = output<typeof imageStateSchemaPartial>;
 //#endregion
 //#region src/states/model-state.d.ts
+/** @internal */
 declare const modelStateUpdateSchema: ZodObject<{
   altitude: ZodOptional<ZodOptional<ZodNumber>>;
   id: ZodOptional<ZodOptional<ZodUnion<readonly [ZodNumber, ZodString]>>>;
@@ -9237,6 +9518,7 @@ declare const modelStateUpdateSchema: ZodObject<{
   scale: ZodOptional<ZodUnion<readonly [ZodNumber, ZodTuple<[ZodNumber, ZodNumber, ZodNumber], null>]>>;
   rotation: ZodOptional<ZodUnion<readonly [ZodNumber, ZodTuple<[ZodNumber, ZodNumber, ZodNumber], null>]>>;
 }, $strip>;
+/** @internal */
 declare const modelStateSchemaStrict: ZodObject<{
   altitude: ZodOptional<ZodNumber>;
   id: ZodOptional<ZodUnion<readonly [ZodNumber, ZodString]>>;
@@ -9257,12 +9539,16 @@ declare const modelStateSchemaStrict: ZodObject<{
   clippingPlaneTopVisible: ZodDefault<ZodBoolean>;
 }, $strict>;
 /**
- * Represents the state of a model.
+ * The serialized state of a 3D model, including its coordinate, rotation, and scale.
  */
 type TModelState = output<typeof modelStateSchemaStrict>;
+/**
+ * A partial 3D model state used to apply incremental updates, where every field is optional.
+ */
 type TModelUpdateState = output<typeof modelStateUpdateSchema>;
 //#endregion
 //#region src/states/text3d-state.d.ts
+/** @internal */
 declare const text3DUpdateStateSchema: ZodObject<{
   visible: ZodOptional<ZodOptional<ZodBoolean>>;
   color: ZodOptional<ZodOptional<ZodString>>;
@@ -9283,6 +9569,7 @@ declare const text3DUpdateStateSchema: ZodObject<{
   type: ZodOptional<ZodDefault<ZodLiteral<"text3d">>>;
   position: ZodOptional<ZodCustom<Coordinate, Coordinate>>;
 }, $strict>;
+/** @internal */
 declare const text3DStateSchemaStrict: ZodObject<{
   visible: ZodBoolean;
   color: ZodString;
@@ -9309,10 +9596,17 @@ declare const text3DStateSchemaStrict: ZodObject<{
   type: ZodDefault<ZodLiteral<"text3d">>;
   position: ZodCustom<Coordinate, Coordinate>;
 }, $strict>;
+/**
+ * The serialized state of a 3D text element, including its coordinate, content, and appearance.
+ */
 type TText3DState = output<typeof text3DStateSchemaStrict>;
+/**
+ * A partial 3D text state used to apply incremental updates, where every field is optional.
+ */
 type TText3DUpdateState = output<typeof text3DUpdateStateSchema>;
 //#endregion
 //#region src/states/walls-state.d.ts
+/** @internal */
 declare const wallsStateSchemaPartial: ZodObject<{
   type: ZodOptional<ZodDefault<ZodLiteral<"walls">>>;
   color: ZodOptional<ZodDefault<ZodString>>;
@@ -9327,6 +9621,7 @@ declare const wallsStateSchemaPartial: ZodObject<{
   height: ZodOptional<ZodDefault<ZodNumber>>;
   opacity: ZodOptional<ZodDefault<ZodNumber>>;
 }, $strip>;
+/** @internal */
 declare const wallsStateSchemaStrict: ZodObject<{
   type: ZodDefault<ZodLiteral<"walls">>;
   color: ZodDefault<ZodString>;
@@ -9341,7 +9636,13 @@ declare const wallsStateSchemaStrict: ZodObject<{
   height: ZodDefault<ZodNumber>;
   opacity: ZodDefault<ZodNumber>;
 }, $strict>;
+/**
+ * The serialized state of all walls in the map, including their colors and visibility.
+ */
 type TWallsState = output<typeof wallsStateSchemaStrict>;
+/**
+ * A partial walls state used to apply incremental updates, where every field is optional.
+ */
 type TWallsUpdateState = output<typeof wallsStateSchemaPartial>;
 //#endregion
 //#region src/states/state-utils.d.ts
@@ -10245,6 +10546,11 @@ declare class MappedinRenderError extends MappedinError {
 }
 //#endregion
 //#region src/events.d.ts
+/**
+ * Free-form context string passed to `MapView.setFloor` (via {@link TSetFloorOptions})
+ * that is forwarded to `floor-change` event listeners as `event.reason`. Useful for
+ * distinguishing user-initiated floor changes from programmatic ones.
+ */
 type TFloorChangeReason = string;
 /**
  * The payload for a user click event on the map.
@@ -10481,9 +10787,17 @@ type TEvents = {
     error: MappedinRenderError;
   };
 };
+/**
+ * Resolves to the payload type for a given {@link TEvents} event name. Use this
+ * to type the parameter of an event handler without depending on the internal
+ * shape of `TEvents`.
+ */
 type TEventPayload<EventName extends keyof TEvents> = TEvents[EventName] extends {
   data: null;
 } ? TEvents[EventName]['data'] : TEvents[EventName];
+/**
+ * Events emitted by {@link MapData}, such as when the active language pack changes.
+ */
 type TMapDataEvents = {
   'language-change': {
     code: string;
@@ -10525,12 +10839,22 @@ interface IGeoJSONData {
 }
 //#endregion
 //#region src/types/index.d.ts
+/**
+ * Result of an animation that may have run to completion or been cancelled before finishing.
+ */
 type TAnimateStateResult = {
   result: 'completed' | 'cancelled';
 };
+/**
+ * A promise extended with a `cancel()` method. Calling `cancel()` aborts the in-flight
+ * operation; the promise still settles, typically with a `'cancelled'` result.
+ */
 type TCancellablePromise<T$1> = Promise<T$1> & {
   cancel: () => void;
 };
+/**
+ * The action a user should take at a step of a {@link Directions} instruction.
+ */
 declare enum ACTION_TYPE {
   Departure = "Departure",
   TakeConnection = "TakeConnection",
@@ -11288,6 +11612,7 @@ type TAddModelOptions = Omit<InitializeModelState$1, 'scale' | 'url'> & {
   scale?: number | [number, number, number];
 };
 /**
+ * Options for adding a 3D text element to the map.
  * @interface
  */
 type TAddText3DOptions = AddText3DOptions$1;
@@ -11444,7 +11769,7 @@ type TAddLabelOptions = {
   /**
    * Customize the appearance of the {@link Label} and its pin
    */
-  appearance?: LabelAppearance$1;
+  appearance?: LabelAppearance;
   /**
    * Whether the Label should be clickable.
    * @default false
@@ -11461,7 +11786,7 @@ type TAddLabelOptions = {
   /**
    * The placement of the text relative to the pin.
    */
-  textPlacement?: LabelTextPlacement$1[];
+  textPlacement?: LabelTextPlacement[];
   /**
    * Whether the label should be occluded by 3D geometry.
    * @default true
@@ -11489,6 +11814,11 @@ type WithState<T$1> = T$1 extends {
 type TUpdateState<T$1 extends MapElementsWithState | string> = T$1 extends {
   __type: infer U;
 } ? U extends keyof MapElementToUpdateState ? MapElementToUpdateState[U] : never : T$1 extends string ? T$1 extends keyof MapElementToUpdateState ? MapElementToUpdateState[T$1] : Record<string, any> : never;
+/**
+ * Maps each map element discriminator (`__type`) to the read-only rendered state
+ * type the element exposes. Used internally by `getRenderedState` to derive a
+ * precise return type from the element passed in.
+ */
 type MapElementToGetRenderedState = {
   [Label.__type]: ReadonlyDeep<LabelRenderedState>;
 };
@@ -11503,6 +11833,11 @@ type MapElementWithRenderedState = WithState<Label>;
 type TGetRenderedState<T$1 extends MapElementWithRenderedState | string> = T$1 extends {
   __type: infer U;
 } ? U extends keyof MapElementToGetRenderedState ? MapElementToGetRenderedState[U] : never : T$1 extends string ? T$1 extends keyof MapElementToGetRenderedState ? MapElementToGetRenderedState[T$1] : Record<string, any> : never;
+/**
+ * Map-wide state applied to all elements, such as the background color, hover
+ * highlight color, and shared visibility flags. Returned by `MapView.getState`
+ * and consumed by extensions that need a snapshot of the global render state.
+ */
 type GlobalState = {
   /**
    * The color of the background, in hex format(#000000).
@@ -11664,6 +11999,10 @@ type TCameraInteractionsSetOptions = {
    */
   bearingAndPitch?: boolean;
 };
+/**
+ * Options passed to `MapView.setFloor` to control how the floor change is performed
+ * and to provide an optional reason that is propagated to `floor-change` event listeners.
+ */
 type TSetFloorOptions = {
   /**
    * Optionally provide the context for the floor change which will be published as the `reason` for the `floor-change` event.
@@ -11873,6 +12212,16 @@ type TPathSectionHighlightOptions = {
    * @default 1500
    */
   animationDuration?: number;
+  /**
+   * Independently controls whether direction arrows are drawn inside the
+   * highlighted section, regardless of the path-level `displayArrowsOnPath`.
+   * If omitted, the highlighted section inherits the path-level setting.
+   *
+   * Animation still follows the path-level `animateArrowsOnPath`, so the
+   * highlighted arrows will animate when the path was created with
+   * `animateArrowsOnPath: true`.
+   */
+  displayArrowsOnPath?: boolean;
 };
 /**
  * Altitude and visual height data for a single floor elevation.
@@ -12391,6 +12740,12 @@ declare abstract class BaseMapData {
 }
 //#endregion
 //#region src/map-data-objects/detailed-map-data.d.ts
+/**
+ * Abstract base class for map data objects that carry rich metadata (images,
+ * hyperlinks, location profiles, and an external ID). Specific classes such as
+ * {@link Space}, {@link PointOfInterest}, and {@link Connection} extend this
+ * to expose typed accessors for their `details` payload.
+ */
 declare abstract class DetailedMapData<MVFData extends Feature$1<Geometry$1, {
   id: string;
   externalId?: string;
@@ -13584,9 +13939,15 @@ declare class FloorStack extends BaseMapData implements IGeoJSONData, IFocusable
    */
   get floors(): [Floor, ...Floor[]];
   /**
-   * Get the default floor for this floor stack
+   * Gets the default floor for this floor stack.
+   *
+   * Resolution order:
+   * 1. The explicitly configured default floor, when it resolves to a known {@link Floor}.
+   * 2. Otherwise, the floor whose elevation is nearest to ground level (zero).
+   *
+   * @returns The default {@link Floor}, or `undefined` when this floor stack has no floors.
    */
-  get defaultFloor(): Floor;
+  get defaultFloor(): Floor | undefined;
   /**
    * Gets the facade ({@link Facade}) representing this floor stack, if it exists.
    */
@@ -14381,6 +14742,11 @@ declare class LocationCategory extends BaseMetaData implements Omit<Category, 'p
 }
 //#endregion
 //#region src/api-geojson/language.d.ts
+/**
+ * Options passed to {@link findPreferredLanguageInVenue} controlling which language is
+ * selected when more than one is available, and whether to fall back to the
+ * browser's preferred language.
+ */
 type TFindPreferredLanguageInVenueOptions = {
   /**
    * Preferred language code to use.
@@ -14736,6 +15102,10 @@ declare class InternalSearch {
   search(term: string, options?: SearchOptions): Promise<SearchResult>;
   suggest(term: string, options?: SuggestOptions): Promise<Suggestion[]>;
 }
+/**
+ * A single search result returned by `MapData.search`. Wraps the matched
+ * map data object along with its match metadata and relevance score.
+ */
 type SearchResultItem<T$1 extends Places | EnterpriseLocation | EnterpriseCategory> = {
   type: T$1['__type'];
   match: SearchResult$1['match'];
@@ -14743,14 +15113,17 @@ type SearchResultItem<T$1 extends Places | EnterpriseLocation | EnterpriseCatego
   item: T$1;
 };
 /**
+ * A search result wrapping a matched {@link EnterpriseCategory}.
  * @interface
  */
 type SearchResultEnterpriseCategory = SearchResultItem<EnterpriseCategory>;
 /**
+ * A search result wrapping a matched {@link EnterpriseLocation}.
  * @interface
  */
 type SearchResultEnterpriseLocations = SearchResultItem<EnterpriseLocation>;
 /**
+ * A search result wrapping a matched place (Space, PointOfInterest, etc.).
  * @interface
  */
 type SearchResultPlaces = SearchResultItem<Places>;
@@ -14805,6 +15178,8 @@ declare const suggestOptionsSchema: ZodObject<{
   }, $strip>>;
 }, $strip>;
 /**
+ * Options passed to `MapData.search` to filter the searchable data sources
+ * (places, enterprise locations, enterprise categories) and tune behavior.
  * @interface
  */
 type SearchOptions = output<typeof searchOptionsSchema>;
@@ -15771,6 +16146,7 @@ type Style$1 = {
   join: LineStyle$2['join'];
   cap: LineStyle$2['cap'];
   topColor?: string;
+  hoverColor?: string;
   showImage: boolean;
   flipImageToFaceCamera: boolean;
   enableImageCollisions: boolean;
@@ -15808,6 +16184,11 @@ declare class StyleComponent implements Style$1 {
   opacity: number;
   width: number;
   height: number;
+  /**
+   * The height the geometry's vertices were baked at; the divisor for instance
+   * height scaling (`height / initialHeight`). Provisional until the deferred bake:
+   * re-anchored to the actual baked height in `BatchedMeshSystem.populateEntityMesh`.
+   */
   initialHeight: number;
   altitude: number;
   join: LineStyle$2['join'];
@@ -16185,6 +16566,11 @@ type FeatureCollectionState = {
    * preserved for now.
    */
   topColor?: string;
+  /**
+   * Per-feature hover color. Setting this cascades to all children, and reads
+   * back through to the first child.
+   */
+  hoverColor?: string;
   /**
    * @deprecated Per-feature property; read-through to the first child is
    * preserved for now.
@@ -16206,10 +16592,18 @@ type FeatureCollectionState = {
    */
   side?: MaterialSide;
   /**
-   * @deprecated Per-feature property; read-through to the first child is
-   * preserved for now.
+   * Controls how the feature collection participates in pointer-event raycasting.
+   * Setting this cascades to every child geometry.
+   *
+   * - `true`: hover and click handlers fire on the child geometries.
+   * - `false` (default): each child geometry captures the raycast — clicks
+   *   land on whichever feature is in front and stop there — but no hover or
+   *   click handler fires. Children still shield anything rendered behind
+   *   them from receiving events.
+   * - `'pass-through'`: raycasts skip every feature in the collection so
+   *   pointer events fall through to whatever is rendered behind.
    */
-  interactive?: boolean;
+  interactive?: InteractiveMode;
   /**
    * Collection-level visibility. Maps directly to `Object3D.visible` on the
    * wrapping `FeatureCollectionObject3D`; toggling cascades to children via
@@ -16416,10 +16810,18 @@ declare class SimpleGeometryMaterial extends MeshLambertMaterial {
 }
 //#endregion
 //#region ../renderer-three/src/components/image.d.ts
-declare class EntityMesh$1 extends Mesh {
-  userData: {
-    entityId: string | number;
-  };
+/** userData carried by an {@link ImageMesh}: the entity id plus per-asset metadata hoisted once at
+ * creation so the per-frame update loop never recomputes it. */
+interface ImageMeshUserData {
+  entityId: string | number;
+  /** Cache key into the LOD controller; hoisted once in createImageMesh, read each frame. */
+  cacheKey: string;
+  /** Whether the asset URL supports server-side resizing; hoisted to avoid per-frame recompute. */
+  isResizable: boolean;
+}
+/** Per-image Three.js mesh. Image-only — distinct from the generic `EntityMesh<T>` in `types/index.ts`. */
+declare class ImageMesh extends Mesh {
+  userData: ImageMeshUserData;
 }
 type ImageStyle = {
   /**
@@ -16484,7 +16886,7 @@ type ImageState = {
 };
 declare class ImageComponent {
   mesh: Geometry3DObject3D;
-  imageMesh?: EntityMesh$1;
+  imageMesh?: ImageMesh;
   outline?: LineSegments;
   readonly type = "image";
   instanceIndex: number;
@@ -16561,14 +16963,21 @@ type GeometryState = {
    */
   hoverColor?: string;
   /**
-   * Whether the geometry is interactive, which means it can be hovered over and clicked on.
+   * Controls how the geometry participates in pointer-event raycasting.
+   *
+   * - `true`: hover and click handlers fire on this geometry.
+   * - `false` (default): the geometry captures the raycast — clicks land on
+   *   it and stop there — but no hover or click handler fires. The geometry
+   *   still shields anything rendered behind it from receiving events.
+   * - `'pass-through'`: raycasts skip this geometry entirely so pointer
+   *   events fall through to whatever is rendered behind it.
    *
    * @example
    * ```javascript
    * 	renderer.on('click', ({ geometry }) => {});
    * ```
    */
-  interactive: boolean;
+  interactive: InteractiveMode;
   /**
    * Whether the geometry is outlined with a 30% darkened color. This effect adds lines around the geometry to make it stand out.
    */
@@ -16656,6 +17065,15 @@ declare class MeshComponent {
   textEntityId?: string;
   readonly type = "geometry";
   dirty: boolean;
+  /**
+   * Single source of truth for `interactive: 'pass-through'`. When true, the
+   * interaction system excludes this mesh from `_hitBoxes` so the raycast
+   * never hits it and pointer events fall through to whatever is rendered
+   * behind. Set via `setState({ interactive: 'pass-through' })`. Distinct
+   * from the presence of `InteractionComponent`, which represents
+   * `interactive: true`.
+   */
+  pointerEventsPassThrough: boolean;
   shouldDetach: boolean;
   detached: boolean;
   instanceIndex: number;
@@ -16860,6 +17278,12 @@ type PathState$1 = {
   highlightColor: string;
   highlightWidthMultiplier: number;
   highlightCompleteFraction: number;
+  /**
+   * Independently controls whether arrows are drawn inside the highlighted
+   * section of the path. When omitted on `addPath` it inherits from
+   * `displayArrowsOnPath`. Animation still follows `animateArrowsOnPath`.
+   */
+  highlightDisplayArrowsOnPath: boolean;
   /**
    * The opacity of the path when it's behind geometry (x-ray effect). Value from 0 to 1.
    * @default 0.25
@@ -17021,6 +17445,12 @@ type AddPathOptions = {
   highlightColor?: string;
   highlightWidthMultiplier?: number;
   highlightCompleteFraction?: number;
+  /**
+   * Independently controls whether arrows are drawn inside the highlighted
+   * section of the path. When omitted, it inherits from `displayArrowsOnPath`.
+   * Animation still follows `animateArrowsOnPath`.
+   */
+  highlightDisplayArrowsOnPath?: boolean;
   /**
    * The opacity of the path when it's behind geometry (x-ray effect). Value from 0 to 1.
    * @default 0.25
@@ -17158,6 +17588,7 @@ declare class PathComponent {
   highlightCompleteFraction: number;
   highlightWidthMultiplier: number;
   highlightColor: string;
+  highlightDisplayArrowsOnPath: boolean;
   xrayOpacity: number;
   xrayStyle?: XrayStyleConfig;
   travelledEndFraction: number;
@@ -17302,6 +17733,9 @@ type Text3DState$1 = {
   readonly rotation: number;
 } & Text3DStyle;
 /**
+ * Initial state for a 3D text element when it is first added to the map.
+ * Mirrors the shape of {@link TText3DState} with all fields optional and
+ * with the auto-managed `id` and `type` fields omitted.
  * @interface
  */
 type InitializeText3DState$1 = Partial<Omit<Text3DState$1, 'id' | 'type'>>;
@@ -17316,7 +17750,7 @@ type Text3DProperties = {
   textArea?: MeshComponentProperties['textArea'];
 };
 /**
- * Options for labeling a geometry with 3D text.
+ * Options accepted when adding a 3D text element (for example to label a space).
  */
 type AddText3DOptions$2 = {
   appearance?: Partial<InitializeText3DState$1>;
@@ -17458,9 +17892,26 @@ type ClippingPlane = {
   verticalOffset: number;
   plane?: Plane;
   holeFillMesh?: Mesh;
+  /**
+   * Group containing the two stencil counting passes (mesh0/mesh1) that toggle
+   * the clipping bit on cross-section pixels. Must be kept in sync with the
+   * cap's visibility: when the cap isn't rendered, it can't clear the clipping
+   * bit, so the counting passes must also be skipped to avoid leaving the bit
+   * set and corrupting other stencil-based features (e.g. underground mask).
+   */
+  holeFillGroup?: Group$1;
   topColor?: string;
   needsRebuild: boolean;
   topVisible?: boolean;
+  /**
+   * World-space XY center of the model's bounding box. Used to size and position
+   * the stencil bias / hole-fill plane to the model's footprint instead of a
+   * giant screen-covering quad (which would corrupt other stencil features).
+   */
+  bboxCenter?: {
+    x: number;
+    y: number;
+  };
 };
 declare class ClippingPlaneComponent implements ClippingPlane {
   readonly type: "clippingPlane";
@@ -17469,8 +17920,13 @@ declare class ClippingPlaneComponent implements ClippingPlane {
   verticalOffset: number;
   plane?: Plane;
   holeFillMesh?: Mesh;
+  holeFillGroup?: Group$1;
   topColor?: string;
   topVisible: boolean;
+  bboxCenter?: {
+    x: number;
+    y: number;
+  };
 }
 //#endregion
 //#region ../renderer-three/src/entities/geometry3d.d.ts
@@ -17651,6 +18107,10 @@ interface PathUniforms {
     type: 'f';
     value: number;
   };
+  highlightDisplayArrowsOnPath: {
+    type: 'b';
+    value: boolean;
+  };
   travelledEndFraction: {
     type: 'f';
     value: number;
@@ -18571,6 +19031,18 @@ declare class CameraSystem extends PubSub<CameraEvents> {
   private createCameraPlane;
   private addEventListeners;
   private addMouseEventListeners;
+  /**
+   * Ends an in-progress drag only when the pointer actually leaves the browser
+   * window. `mouseout` bubbles, so it also fires when the pointer merely moves
+   * from the canvas onto another in-page element rendered above it — for
+   * example an interactive HTML marker or a developer-owned overlay. Treating
+   * those in-page transitions as drag-end froze pan/rotate gestures until the
+   * mouse button was released and pressed again. When the pointer leaves the
+   * window, `relatedTarget` is `null`; in-page transitions always carry a
+   * non-null `relatedTarget`.
+   * @param event - The `mouseout` event from the window listener.
+   */
+  private onWindowMouseOut;
   private addMouseMoveEventListeners;
   private removeMouseMoveEventListeners;
   private removeMouseUpEventListeners;
@@ -18797,6 +19269,21 @@ declare class Camera$2 extends PubSub<{
    * The camera's current elevation in meters from the ground.
    */
   get elevation(): number;
+  /**
+   * The maximum elevation (in meters) the camera is allowed to reach.
+   * @default Infinity
+   */
+  get maxElevation(): number;
+  /**
+   * Cap the camera's elevation in meters. Applies to user pedestal drag (when
+   * `panMode` is `'elevation'`), `setElevation`, and `animateElevation`. The
+   * current elevation is snapped down to the cap if it exceeds the new
+   * maximum.
+   *
+   * @param maxElevation The new maximum elevation in meters.
+   * @default Infinity
+   */
+  setMaxElevation(maxElevation: number): void;
   /**
    * @param elevation The elevation in meters.
    */
@@ -19146,49 +19633,24 @@ declare class ImageSystem extends PubSub<{
   private naturalBearing;
   private imagePlacementOptions;
   private cameraFrustum;
-  private transformImageRequest?;
   private cameraWorldPosition;
   private debug;
   get debugLOD(): boolean;
   set debugLOD(value: boolean);
   /**
-   * Cache for tracking image LOD state. Stores the original image element
-   * and textures at each LOD level for memory-efficient switching.
+   * The overlay LOD controller: owns all per-asset texture state and the download→promote upgrade
+   * pipeline. ImageSystem holds only ECS/mesh/material/visibility and calls this seam
+   * (register / get / requestUpgrade / drainPromotions / effectiveLOD / dispose). Not to be confused
+   * with `TextureSystem`, which paints fixed-resolution surface textures onto polygon materials.
    */
-  private cache;
+  private lod;
   constructor(rendererState: RendererState, convertTo3DMapPosition: Core['convertTo3DMapPosition'], projectToScreen: Core['project'], initialBearing?: number, naturalBearing?: number, imagePlacementOptions?: ImagePlacementOptions$1, transformImageRequest?: TransformImageRequest);
   private createImageMesh;
-  /**
-   * Gets or downloads an image texture. Cache entry must exist before calling.
-   * For resizable URLs (Mappedin CDN): uses server-side resizing with LOD levels.
-   * For non-resizable URLs: caps to the specified size once at load.
-   * @param cacheKey - Cache key (URL or URL|size for non-resizable images)
-   * @param url - The image URL for loading
-   * @param targetSize - Texture dimension in pixels
-   * @returns Promise that resolves to the texture
-   */
-  private getOrDownloadImage;
-  /**
-   * Returns the texture capped to maxSize. Only scales if the image exceeds maxSize.
-   * Used for external images to prevent VRAM exhaustion on mobile.
-   * @param sourceTexture - The loaded texture from TextureLoader
-   * @param maxSize - Maximum dimension in pixels
-   * @returns The original texture if within limits, or a new CanvasTexture if scaled
-   */
-  private createCappedTexture;
-  /**
-   * Updates the LOD for an image mesh based on camera distance.
-   * Only applies to resizable URLs (Mappedin CDN) - server handles the scaling.
-   * Non-resizable URLs use a fixed image size set at load time.
-   * @param url - The image URL
-   * @param imageMesh - The mesh to update
-   * @param position - The world position of the image
-   * @param maxImageSize - Maximum image size for non-resizable images (used for cache key)
-   */
-  private updateLODIfNeeded;
   /**
    * Applies debug LOD colors to all image materials when debug mode is enabled.
-   * Calculates LOD based on current camera position and applies appropriate color tinting.
+   * Colors reflect the ACTUAL decoded resolution of the resident texture (`hi ?? base`), bucketed to
+   * the ladder — not the requested tier (`hiLod`) and not the distance target. So a raster source
+   * smaller than its requested tier (e.g. 666px requested at 2048) tints by what the GPU truly holds.
    */
   private applyDebugLODColors;
   /**
@@ -19199,10 +19661,19 @@ declare class ImageSystem extends PubSub<{
   currentImageScreenBBoxes: Rectangle[];
   private viewProjectionMatrix;
   private lastLODUpdateTime;
+  /**
+   * Reconciles a material's map to the effective resident texture (`hi ?? base`) for an asset.
+   * This is the single per-frame resync point: it swaps in a deferred upgrade once it lands and
+   * keeps materials sharing an asset consistent. Hot path — no allocation. Returns whether a
+   * texture is resident.
+   * @param material - The mesh material to reconcile
+   * @param cacheKey - The asset cache key
+   * @returns True if an effective texture is resident (mesh can be shown)
+   */
+  private reconcileMaterialTexture;
   update(cameraRotationRadians: number, isCameraMoving: boolean, cameraStoppedTime: number): void;
   /**
-   * Disposes all cached textures and clears the cache.
-   * Called when the renderer is destroyed to prevent GPU memory leaks.
+   * Disposes all cached textures and clears state. Called on renderer destroy to prevent GPU leaks.
    */
   destroy(): void;
   updateImageScreenBBoxes(meshComponent: MeshComponent | ImageComponent): void;
@@ -19671,11 +20142,23 @@ declare class ClippingPlaneSystem {
   update(): void;
   private process;
   /**
-   * Creates the stencil geometry for hole fill detection
-   * @param modelGeometry - The merged model geometry for counting passes
-   * @param planeGeometry - The plane geometry for bias pass (covers entire hole fill area)
-   * @param plane - The clipping plane
-   * @param renderOrder - Base render order for the meshes
+   * Creates the stencil counting passes that mark cross-section pixels.
+   *
+   * Two passes operate on a single reserved stencil bit (CLIPPING_BIT = 0x80),
+   * which is guaranteed to be 0 in every mask ID, so the clipping system and the
+   * masking system never overwrite each other's stencil state:
+   *
+   *  - mesh0 (back faces below clip): toggles bit 7 via InvertStencilOp.
+   *  - mesh1 (front faces below clip): toggles bit 7 via InvertStencilOp.
+   *
+   * For closed manifold meshes from a camera outside the model, each balanced
+   * back/front pair toggles bit 7 twice (returning it to 0), while each unpaired
+   * back face above the clip leaves bit 7 = 1. The cap then renders where
+   * bit 7 == 1 and immediately clears bit 7 again with ZeroStencilOp.
+   *
+   * @param modelGeometry - The merged model geometry used for both passes
+   * @param plane - The user-defined clipping plane
+   * @param renderOrder - Base render order for the passes
    */
   private createHoleFillGeometry;
 }
@@ -20309,11 +20792,25 @@ type Systems = {
   pluginSystem: PluginSystem;
   shadowsSystem?: ShadowsSystem;
 };
+/**
+ * Top-level state for the MapView, exposing global hover colors that apply
+ * to all interactive elements. Returned by state APIs and consumed by extensions.
+ */
 type MapViewState$1 = {
   readonly type: 'map-view';
   hoverColor: string;
   text3dHoverColor: string;
 };
+/**
+ * Style accepted by {@link Core.addFeatureCollection}: the GeoJSON-shape-specific
+ * paint/line style plus `focusable`, which enrolls the resulting mesh in the
+ * dynamic-focus system. To set `interactive` (including `'pass-through'`), cascade
+ * it via `setState` on the FC id after creation; that path already handles all
+ * the per-leaf bookkeeping.
+ */
+type FCFeatureStyle<T$1 extends FeatureCollection<Polygon | MultiPolygon | LineString, any>> = (T$1 extends FeatureCollection<LineString, any> ? LineStyle$2 : PaintStyle$2) & {
+  focusable?: boolean;
+};
 declare class Core extends PubSub<MapEvent> {
   #private;
   options: Omit<RendererCoreOptions$2, 'outdoorView'>;
@@ -20367,6 +20864,11 @@ declare class Core extends PubSub<MapEvent> {
   addGroupContainer(id: string, options?: {
     visible?: boolean;
     altitude?: number;
+    /**
+     * Group containers do not accept `'pass-through'` (they have no mesh
+     * of their own to skip). Mark individual descendants as
+     * `interactive: 'pass-through'` instead.
+     */
     interactive?: boolean;
     focusable?: boolean;
     preloadGeometry?: boolean;
@@ -20398,7 +20900,7 @@ declare class Core extends PubSub<MapEvent> {
    * The only collection-level concern honored at creation time is the optional
    * mask — read from `style(features[0])`.
    */
-  addFeatureCollection<T$1 extends FeatureCollection<Polygon | MultiPolygon | LineString, any>>(id: string, geometry: T$1, style?: ((feature: Feature<Polygon | MultiPolygon | LineString, any>) => T$1 extends FeatureCollection<LineString, any> ? LineStyle$2 : PaintStyle$2) | (T$1 extends FeatureCollection<LineString, any> ? LineStyle$2 : PaintStyle$2), fcState?: {
+  addFeatureCollection<T$1 extends FeatureCollection<Polygon | MultiPolygon | LineString, any>>(id: string, geometry: T$1, style?: ((feature: Feature<Polygon | MultiPolygon | LineString, any>) => FCFeatureStyle<T$1>) | FCFeatureStyle<T$1>, fcState?: {
     altitude?: number;
     visible?: boolean;
   }, parent?: EntityId$1<GroupContainerState$1> | string | number | null): EntityId$1<FeatureCollectionState>;
@@ -20705,6 +21207,21 @@ type GroupContainerState$1 = {
    * The altitude of the group container above the ground in meters
    */
   altitude: number;
+  /**
+   * Controls whether the group container itself fires hover and click events.
+   *
+   * - `true`: container-level hover and click handlers fire when the user
+   *   interacts with any descendant. The container appears in the
+   *   `groupContainers` array of the event payload.
+   * - `false` (default): no container-level handler fires. Descendants still
+   *   capture the raycast independently based on their own `interactive`
+   *   state.
+   *
+   * `'pass-through'` is intentionally not supported on group containers —
+   * group containers have no mesh of their own to skip. Mark individual
+   * descendant geometries / shapes / feature collections as
+   * `interactive: 'pass-through'` instead.
+   */
   interactive: boolean;
   /**
    * The opacity of the group container, which sets the opacity of all its children
@@ -20744,6 +21261,7 @@ declare class GroupContainerObject3D extends Object3D {
   setVisible(visible: boolean): void;
   setAltitude(altitude: number): void;
   set2DGeometryChildrenPositionDirty(): void;
+  liftFocusableCaches(dz: number): void;
   get altitude(): number;
   setOpacity(opacity: number): void;
   get opacity(): number;
@@ -20820,7 +21338,16 @@ declare class Geometry2D {
 type Position$2 = [lon: number, lat: number] | [lon: number, lat: number, alt: number];
 //#endregion
 //#region ../renderer-three/src/types/options.d.ts
+/**
+ * Selects which environment map is used for image-based lighting.
+ * `'basic'` enables a default environment map, `false` disables environment lighting.
+ */
 type EnvMapOptions$2 = 'basic' | false;
+/**
+ * Low-level options consumed by `RendererCore` to configure rendering, camera
+ * defaults, outdoor view integration, and visual effects. Most consumers
+ * should use `TShow3DMapOptions` instead, which is converted into this shape internally.
+ */
 type RendererCoreOptions$2 = Partial<{
   center?: Position$2;
   zoomLevel?: number;
@@ -20995,6 +21522,25 @@ declare class EntityMesh<T$1> extends Mesh<any> {
     entity: T$1;
   };
 }
+/**
+ * Controls how an entity participates in pointer-event raycasting.
+ *
+ * In all three modes the geometry is rendered identically — the difference is
+ * purely about how pointer events are routed.
+ *
+ * - `true`: the entity opts in to events. Hover and click handlers registered
+ *   on the map view fire when the user interacts with this entity.
+ * - `false` (default): the entity captures the raycast — pointer events land
+ *   on it and stop there — but no hover or click handler fires. This is the
+ *   right choice for static, non-clickable decoration that should still
+ *   shield whatever is rendered behind it (for example a wall in front of an
+ *   interactive space). Anything behind the entity will not receive events.
+ * - `'pass-through'`: raycasts skip the entity entirely, so pointer events
+ *   fall through to whatever is rendered behind it. Useful for invisible
+ *   helper geometry that must never block clicks on the real content beneath
+ *   it (for example a per-floor focus footprint).
+ */
+type InteractiveMode = boolean | 'pass-through';
 /**
  * Options for configuring bevel effects on extruded geometry.
  */
@@ -21024,9 +21570,14 @@ type BevelState = {
    */
   segments?: number;
 };
+/**
+ * Visual styling for filled (polygon-based) geometry such as spaces and shapes.
+ * Controls color, opacity, height, textures, bevel, shading and outlines.
+ */
 type PaintStyle$2 = {
   color: string;
   topColor?: string;
+  hoverColor?: string;
   height?: number;
   altitude?: number;
   opacity?: number;
@@ -21065,14 +21616,23 @@ type PaintStyle$2 = {
    */
   __EXPERIMENTAL_maskEnabled?: boolean;
 };
+/**
+ * Configures the vertical shading gradient applied to extruded geometry to give
+ * walls and shapes a sense of depth. `start` and `end` are normalized heights.
+ */
 type Shading$1 = {
   start?: number;
   end?: number;
   intensity?: number;
 };
+/**
+ * Visual styling for line-based geometry such as paths and connection lines.
+ * Controls color, width, caps/joins, shading and outlines.
+ */
 type LineStyle$2 = {
   color: string;
   topColor?: string;
+  hoverColor?: string;
   width: number;
   opacity?: number;
   height?: number;
@@ -21111,6 +21671,10 @@ type ModelProperties = {
    */
   visibleThroughGeometry?: boolean;
 };
+/**
+ * Padding applied to the camera's visible area so map content stays clear of
+ * UI overlays such as headers, sidebars and bottom sheets.
+ */
 type InsetPadding$2 = {
   top: number;
   left: number;
@@ -21268,6 +21832,11 @@ type MapEvent = {
  * All entities in 3D
  */
 type All3DTypes = Geometry3DTypes | FeatureCollectionObject3D | GroupContainerObject3D;
+/**
+ * Snapshot of the renderer's internal state passed to {@link ISystemPlugin}
+ * instances on every frame. Exposes the Three.js scene, camera and geometry
+ * registries so plugins can inspect or augment the render pipeline.
+ */
 type RendererState = {
   /**
    * A map of all 3D geometries in the world.
@@ -21483,7 +22052,16 @@ declare class MapLibreOverlay<T$1> extends PubSub<T$1> implements IControl {
   private handleMove;
   private handleMoveEnd;
   private handleError;
+  /**
+   * Called by MapLibre when this overlay is added to a map as an IControl.
+   * @param map - The MapLibre map this overlay is being attached to.
+   * @returns The DOM element rendered by this overlay.
+   */
   onAdd(map: Map$1): HTMLDivElement;
+  /**
+   * Called by MapLibre when this overlay is removed from a map. Detaches all
+   * map listeners, removes the custom layer, and destroys the underlying renderer.
+   */
   onRemove(): void;
 }
 //#endregion
@@ -21498,12 +22076,21 @@ declare const MAPPEDIN_COLORS: {
 };
 //#endregion
 //#region ../packages/common/Mappedin.Logger.d.ts
+/**
+ * SDK logging verbosity. Ordered from most verbose to least — selecting a level
+ * enables that level plus every level after it.
+ */
 declare enum E_SDK_LOG_LEVEL {
   LOG = 0,
   WARN = 1,
   ERROR = 2,
   SILENT = 3,
 }
+/**
+ * Set the SDK's global log verbosity. Lower levels include all higher-numbered levels;
+ * `SILENT` suppresses all output.
+ * @param level - The desired verbosity from {@link E_SDK_LOG_LEVEL}.
+ */
 declare function setLoggerLevel(level: E_SDK_LOG_LEVEL): void;
 //#endregion
 //#region src/utils/convert-renderer-core-options.d.ts
@@ -21515,6 +22102,11 @@ declare function setLoggerLevel(level: E_SDK_LOG_LEVEL): void;
 declare function convertToRendererCoreOptions(options: TShow3DMapOptions | undefined): Partial<RendererCoreOptions$1> | undefined;
 //#endregion
 //#region src/api-geojson/multi-floor.d.ts
+/**
+ * Multi-floor visibility state returned by {@link getMultiFloorState}, describing
+ * the outdoor opacity and per-floor state used when rendering a stacked view of
+ * multiple floors at once.
+ */
 type VisibilityState = {
   outdoorOpacity: number | 'initial';
   floorStates: {
@@ -21522,6 +22114,11 @@ type VisibilityState = {
     state: TFloorState;
   }[];
 };
+/**
+ * Configuration for the footprint rendered beneath stacked floors in multi-floor
+ * view, controlling its color, opacity, outlines, and the visual treatment of
+ * spaces open to the floor below.
+ */
 type FootprintConfig = {
   /**
    * The color of the footprint.
@@ -21981,6 +22578,23 @@ declare const checkWorkerUrls: () => Promise<false | {
   collision: boolean;
   maplibre: boolean;
 }>;
+/**
+ * Render a Mappedin map into the given DOM container and return its {@link MapView}.
+ *
+ * This is the main entry point for Mappedin JS. Combine with {@link getMapData}
+ * to load venue data and render an interactive 3D map.
+ *
+ * @param el - The container element to render the map into. Must be attached to the DOM and have non-zero size.
+ * @param mapData - Venue data, typically obtained from {@link getMapData}.
+ * @param options - Optional {@link TShow3DMapOptions} to customize the initial state, UI, and behavior of the map.
+ * @returns A promise that resolves to a {@link MapView} once the map has been initialized.
+ *
+ * @example
+ * ```ts
+ * const mapData = await getMapData({ key: '...', secret: '...', mapId: '...' });
+ * const mapView = await show3dMap(document.getElementById('mappedin-map')!, mapData);
+ * ```
+ */
 declare const show3dMap: (el: HTMLElement, mapData: MapData, options?: TShow3DMapOptions) => Promise<MapView>;
 /**
  * Returns the package version of the SDK.