@mapvx/web-js 1.4.0 → 1.5.0

package/dist/umd/index.js

@@ -6814,7 +6814,7 @@ var rollbar_umd_min_default = /*#__PURE__*/__webpack_require__.n(rollbar_umd_min
 // version placeholder is replaced with the package version by
 // scripts/inject-build-defines.js. The access token falls back to the MapVX
 // SDK-web Rollbar project token when none is injected at build time.
-var SDK_VERSION =  true ? "1.4.0" : 0;
+var SDK_VERSION =  true ? "1.5.0" : 0;
 var ACCESS_TOKEN =  false ? 0 : "28279d52df43411ebd138c2bee0ab1df";
 var _rollbarConfig = {
   accessToken: ACCESS_TOKEN,
@@ -6861,7 +6861,7 @@ function logger_toPrimitive(t, r) { if ("object" != logger_typeof(t) || !t) retu
 // by scripts/inject-build-defines.js. The Countly key falls back to the
 // MapVX key when none is injected at build time.
 var IS_DEBUG =  true ? false : 0;
-var logger_SDK_VERSION =  true ? "1.4.0" : 0;
+var logger_SDK_VERSION =  true ? "1.5.0" : 0;
 var COUNTLY_API_KEY =  false ? 0 : "f0c8d3b96d336e857a8628f49dd1baf7d7add0e9";
 var logger_countly = {
   apiKey: COUNTLY_API_KEY,
@@ -9550,6 +9550,16 @@ function InternalDrawRouteConfiguration(config) {
 /**
  * Interface that represent a place with their id.
  * @group Routes
+ * @example
+ * ```typescript
+ * // Resolve an internal alias that is reused across several malls by
+ * // pinning the building (and, optionally, the floor) it belongs to.
+ * const origin: IdLocation = {
+ *   id: "store-204",      // integrator alias, may repeat across buildings
+ *   buildingId: "mall-santiago",
+ *   floorId: "level-2",   // takes precedence over `level`
+ * }
+ * ```
  */
 
 /**
@@ -9641,208 +9651,6 @@ var InternalAnimationDrawingConfig = /*#__PURE__*/function () {
     }
   }]);
 }();
-;// ./src/utils/error.ts
-/**
- * Convert an unknown error to an Error object.
- * @group Utils
- * @param error - The unknown error.
- * @returns An Error object.
- */
-function convertToError(error) {
-  if (error instanceof Error) {
-    return error;
-  } else {
-    var text = String(error);
-    return new Error(text);
-  }
-}
-;// ./src/domain/models/loggeable.ts
-function loggeable_typeof(o) { "@babel/helpers - typeof"; return loggeable_typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, loggeable_typeof(o); }
-function loggeable_classCallCheck(a, n) { if (!(a instanceof n)) throw new TypeError("Cannot call a class as a function"); }
-function loggeable_defineProperties(e, r) { for (var t = 0; t < r.length; t++) { var o = r[t]; o.enumerable = o.enumerable || !1, o.configurable = !0, "value" in o && (o.writable = !0), Object.defineProperty(e, loggeable_toPropertyKey(o.key), o); } }
-function loggeable_createClass(e, r, t) { return r && loggeable_defineProperties(e.prototype, r), t && loggeable_defineProperties(e, t), Object.defineProperty(e, "prototype", { writable: !1 }), e; }
-function loggeable_toPropertyKey(t) { var i = loggeable_toPrimitive(t, "string"); return "symbol" == loggeable_typeof(i) ? i : i + ""; }
-function loggeable_toPrimitive(t, r) { if ("object" != loggeable_typeof(t) || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != loggeable_typeof(i)) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
-
-
-
-/**
- * Represents the abstract class for the loggeable.
- * @hidden
- */
-var Loggeable = /*#__PURE__*/function () {
-  /**
-   * The object to log the events and errors.
-   */
-
-  function Loggeable() {
-    loggeable_classCallCheck(this, Loggeable);
-    this.logger = Logger.getInstance();
-  }
-
-  /**
-   * Add values to identify the client.
-   * @param segmentation The pair values to use as segmentation.
-   * @returns The segmentation with the added values.
-   */
-  return loggeable_createClass(Loggeable, [{
-    key: "logEvent",
-    value:
-    /**
-     * To log a event in this class.
-     * @param eventName The event name.
-     * @param eventSegmentation The pair key, value to segment this event count.
-     */
-    function logEvent(eventName) {
-      var eventSegmentation = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
-      this.logger.logEvent(eventName, this.prepareSegmentation(eventSegmentation));
-    }
-
-    /**
-     * To log a captured error in this class.
-     * @param error The captured error
-     * @param args The rest of the arguments.
-     */
-  }, {
-    key: "logError",
-    value: function logError(error) {
-      var _this$logger;
-      var errorTyped = convertToError(error);
-      for (var _len = arguments.length, args = new Array(_len > 1 ? _len - 1 : 0), _key = 1; _key < _len; _key++) {
-        args[_key - 1] = arguments[_key];
-      }
-      (_this$logger = this.logger).logError.apply(_this$logger, [errorTyped].concat(args));
-    }
-
-    /**
-     * To log a captured error as a warning.
-     * @param error The captured error
-     * @param args The rest of the arguments.
-     */
-  }, {
-    key: "logWarning",
-    value: function logWarning(error) {
-      var _this$logger2;
-      var errorTyped = convertToError(error);
-      for (var _len2 = arguments.length, args = new Array(_len2 > 1 ? _len2 - 1 : 0), _key2 = 1; _key2 < _len2; _key2++) {
-        args[_key2 - 1] = arguments[_key2];
-      }
-      (_this$logger2 = this.logger).logWarning.apply(_this$logger2, [errorTyped].concat(args));
-    }
-  }, {
-    key: "logDebug",
-    value: function logDebug() {
-      var _this$logger3;
-      (_this$logger3 = this.logger).logDebug.apply(_this$logger3, arguments);
-    }
-
-    /**
-     * Prints in console any number of given arguments, if and only if, app is running in debug mode.
-     * @param args An array of arguments to log
-     */
-  }, {
-    key: "debugLog",
-    value: function debugLog() {
-      for (var _len3 = arguments.length, args = new Array(_len3), _key3 = 0; _key3 < _len3; _key3++) {
-        args[_key3] = arguments[_key3];
-      }
-      this.logger.debugLog(args);
-    }
-  }]);
-}();
-;// ./src/domain/models/mapConfig.ts
-/**
- * Configuration options for map tile caching.
- * Allows controlling how map tiles are cached in memory and persisted via service worker.
- *
- * @example
- * ```typescript
- * const tileCacheConfig: MapTileCacheConfig = {
- *   enabled: true,
- *   maxTiles: 500,
- *   ttlMs: 60 * 60 * 1000, // 1 hour
- *   persistToServiceWorker: true,
- *   preloadAdjacentZooms: false,
- *   maxConcurrentTileFetches: 6
- * };
- * ```
- *
- * @group Configuration
- */
-
-/**
- * Default values for tile cache configuration
- * @internal
- */
-var DEFAULT_TILE_CACHE_CONFIG = {
-  enabled: true,
-  maxTiles: 400,
-  ttlMs: 30 * 60 * 1000,
-  // 30 minutes
-  persistToServiceWorker: true,
-  preloadAdjacentZooms: false,
-  maxConcurrentTileFetches: 6
-};
-
-/**
- * Hard cap for {@link MapTileCacheConfig.maxTiles}.
- * Configurations above this (e.g. millions) are clamped to avoid memory pressure
- * and excessive interaction with the tile CDN / service worker.
- *
- * @internal
- */
-var MAPLIBRE_MAX_TILE_CACHE_HARD_CAP = 100000;
-
-/**
- * Basic configuration for the map.
- * Provides essential settings for initializing and customizing map behavior.
- *
- * @example
- * ```typescript
- * const mapConfig: MapConfig = {
- *   zoom: 15,
- *   center: { lat: 40.7128, lng: -74.0060 },
- *   parentPlaceId: "building-1",
- *   onMapReady: () => console.log("Map is ready!"),
- *   enableHover: true,
- *   showCompass: true
- * };
- * ```
- *
- * @group Map
- *
- * @property zoom - The initial zoom level of the map.
- * @property center - The initial center coordinates of the map.
- * @property parentPlaceId - (Optional) The ID of the parent place to display.
- * @property otherPotentialParentPlacesIds - (Optional) List of alternative parent place IDs.
- * @property onMapReady - (Optional) Callback invoked when the map is ready.
- * @property onZoomEnd - (Optional) Callback invoked when the zoom operation ends. Receives the new zoom level.
- * @property onRotate - (Optional) Callback invoked when the map is rotated. Receives the rotation in degrees.
- * @property onFloorChange - (Optional) Callback invoked when the floor changes. Receives the new floor ID.
- * @property onParentPlaceChange - (Optional) Callback invoked when the parent place changes. Receives the new parent place ID.
- * @property lang - (Optional) Language code for map labels and UI.
- * @property minZoom - (Optional) Minimum allowed zoom level.
- * @property maxZoom - (Optional) Maximum allowed zoom level.
- * @property pitch - (Optional) The pitch (tilt) of the map in degrees.
- * @property maxBounds - (Optional) Array of coordinates defining the maximum bounds of the map.
- * @property enableHover - (Optional) Whether to enable hover interactions on the map.
- * @property showCompass - (Optional) Whether to display the compass control.
- * @property showZoom - (Optional) Whether to display the zoom control.
- * @property navigationPosition - (Optional) Position of the navigation controls on the map.
- * @property bearingSnap - (Optional) The bearing snap threshold in degrees.
- * @property bearing - (Optional) Initial bearing (rotation) of the map in degrees, clockwise from north.
- * @property interactive - (Optional) Master switch for all user interaction (pan/zoom/rotate).
- * @property rotateEnabled - (Optional) Whether the user can rotate the map; keeps pinch-zoom when disabled.
- * @property dragPan - (Optional) Whether the user can pan by dragging/swiping.
- * @property scrollZoom - (Optional) Whether the scroll wheel/trackpad can zoom the map.
- * @property doubleClickZoom - (Optional) Whether double-click/double-tap zooms the map.
- * @property touchZoomRotate - (Optional) Whether pinch gestures can zoom the map on touch devices.
- * @property keyboard - (Optional) Whether keyboard shortcuts can pan/zoom/rotate the map.
- * @property institutionId - (Optional) The institution identifier for map context. Required for loading map related data from Portal.
- * @property authToken - (Optional) Authentication token for accessing protected map resources. Required for loading map related data from Portal.
- * @property apiUrl - (Optional) Injected by SDK when creating map; base API URL for map requests.
- * @property mapvxRequestContext - (Optional) Injected by SDK when creating map; context sent as headers to public-api.mapvx.com.
- */
 ;// ./src/domain/models/circle.ts
 function circle_typeof(o) { "@babel/helpers - typeof"; return circle_typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, circle_typeof(o); }
 function circle_ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
@@ -10027,101 +9835,303 @@ function isValidCircleConfig(config) {
 }
 
 /**
- * Resolves a {@link CircleConfig} into a {@link CircleRecord}, applying
- * default styling, generating an id when one is not provided, and validating inputs.
- *
- * @param config Circle configuration provided by the SDK consumer.
- * @param hidden Initial hidden state, defaults to visible.
- * @returns The resolved circle record ready to be stored and rendered.
- * @throws {Error} If radiusMeters is ≤ 0, not finite, or coordinates are invalid.
+ * Resolves a {@link CircleConfig} into a {@link CircleRecord}, applying
+ * default styling, generating an id when one is not provided, and validating inputs.
+ *
+ * @param config Circle configuration provided by the SDK consumer.
+ * @param hidden Initial hidden state, defaults to visible.
+ * @returns The resolved circle record ready to be stored and rendered.
+ * @throws {Error} If radiusMeters is ≤ 0, not finite, or coordinates are invalid.
+ *
+ * @group Circles
+ */
+function resolveCircleConfig(config) {
+  var _config$id, _config$fillColor, _config$strokeColor, _config$strokeWidth, _config$renderOrder;
+  var hidden = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : false;
+  validateRadiusMeters(config.radiusMeters);
+  validateCoordinate(config.coordinate);
+  if (config.renderOrder !== undefined && !CIRCLE_RENDER_ORDERS.includes(config.renderOrder)) {
+    throw new Error("Invalid renderOrder: ".concat(String(config.renderOrder), ". ") + "Must be one of: ".concat(CIRCLE_RENDER_ORDERS.join(", "), "."));
+  }
+  return {
+    id: (_config$id = config.id) !== null && _config$id !== void 0 ? _config$id : generateHexadecimalKey(),
+    // Copy the coordinate so later mutations of the caller's object
+    // can't change internal circle state
+    coordinate: {
+      lat: config.coordinate.lat,
+      lng: config.coordinate.lng
+    },
+    radiusMeters: config.radiusMeters,
+    fillColor: (_config$fillColor = config.fillColor) !== null && _config$fillColor !== void 0 ? _config$fillColor : CIRCLE_DEFAULTS.fillColor,
+    fillOpacity: clampOpacity(config.fillOpacity, CIRCLE_DEFAULTS.fillOpacity),
+    strokeColor: (_config$strokeColor = config.strokeColor) !== null && _config$strokeColor !== void 0 ? _config$strokeColor : CIRCLE_DEFAULTS.strokeColor,
+    strokeWidth: (_config$strokeWidth = config.strokeWidth) !== null && _config$strokeWidth !== void 0 ? _config$strokeWidth : CIRCLE_DEFAULTS.strokeWidth,
+    strokeOpacity: clampOpacity(config.strokeOpacity, CIRCLE_DEFAULTS.strokeOpacity),
+    floorId: config.floorId,
+    renderOrder: (_config$renderOrder = config.renderOrder) !== null && _config$renderOrder !== void 0 ? _config$renderOrder : CIRCLE_DEFAULTS.renderOrder,
+    hidden: hidden
+  };
+}
+
+/**
+ * Builds a closed GeoJSON polygon ring approximating a geographic circle.
+ *
+ * The ring is computed with an equirectangular approximation: meters are
+ * converted to degrees independently per axis, with the longitude scale
+ * corrected by the cosine of the latitude. For the radii the SDK works with
+ * (tens to hundreds of meters) the metric error is negligible (≤1%) at any latitude
+ * where the projection is defined. At extreme polar latitudes, the approximation
+ * breaks down, so circles near poles (|lat| > 85°) should be used with caution.
+ *
+ * @param lng Longitude of the circle center in degrees.
+ * @param lat Latitude of the circle center in degrees.
+ * @param radiusMeters Radius of the circle in meters. Must be positive and finite.
+ * @param points Number of segments in the ring. Defaults to 64. Non-integer
+ *               values are floored and the count is clamped to a minimum of 3,
+ *               the smallest valid GeoJSON linear ring; non-finite values fall
+ *               back to the default.
+ * @returns A closed ring of `[lng, lat]` positions (first equals last).
+ *
+ * @example
+ * ```typescript
+ * import { circleRing } from '@mapvx/web-js';
+ *
+ * // Create a 150-meter radius circle ring
+ * const ring = circleRing(-74.0060, 40.7128, 150);
+ * const polygon = { type: "Polygon", coordinates: [ring] };
+ *
+ * // Custom segments (32 instead of 64) for lower resolution
+ * const coarseRing = circleRing(-74.0060, 40.7128, 150, 32);
+ * ```
+ *
+ * @note Equirectangular approximation is accurate for radii up to ~500 km and
+ *       latitudes between approximately ±80°. Beyond these limits, visual
+ *       distortion may occur near the poles.
+ * @note Generated rings do not account for geographic obstacles, walls, or
+ *       buildings. For complex geofencing, consider server-side validation.
+ *
+ * @group Circles
+ */
+function circleRing(lng, lat, radiusMeters) {
+  var points = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : 64;
+  // A linear ring needs at least 3 distinct positions to be valid GeoJSON
+  var segments = Number.isFinite(points) ? Math.max(3, Math.floor(points)) : 64;
+  var ring = [];
+  var latRad = lat * Math.PI / 180;
+  var metersPerDegLat = 110574;
+  var metersPerDegLng = 111320 * Math.cos(latRad || 0.000001);
+  var latR = radiusMeters / metersPerDegLat;
+  var lngR = radiusMeters / (metersPerDegLng || 1);
+  for (var i = 0; i < segments; i += 1) {
+    var a = i / segments * Math.PI * 2;
+    ring.push([lng + lngR * Math.cos(a), lat + latR * Math.sin(a)]);
+  }
+  // Close the ring with an exact copy of the first position, as GeoJSON requires
+  ring.push([ring[0][0], ring[0][1]]);
+  return ring;
+}
+;// ./src/utils/error.ts
+/**
+ * Convert an unknown error to an Error object.
+ * @group Utils
+ * @param error - The unknown error.
+ * @returns An Error object.
+ */
+function convertToError(error) {
+  if (error instanceof Error) {
+    return error;
+  } else {
+    var text = String(error);
+    return new Error(text);
+  }
+}
+;// ./src/domain/models/loggeable.ts
+function loggeable_typeof(o) { "@babel/helpers - typeof"; return loggeable_typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, loggeable_typeof(o); }
+function loggeable_classCallCheck(a, n) { if (!(a instanceof n)) throw new TypeError("Cannot call a class as a function"); }
+function loggeable_defineProperties(e, r) { for (var t = 0; t < r.length; t++) { var o = r[t]; o.enumerable = o.enumerable || !1, o.configurable = !0, "value" in o && (o.writable = !0), Object.defineProperty(e, loggeable_toPropertyKey(o.key), o); } }
+function loggeable_createClass(e, r, t) { return r && loggeable_defineProperties(e.prototype, r), t && loggeable_defineProperties(e, t), Object.defineProperty(e, "prototype", { writable: !1 }), e; }
+function loggeable_toPropertyKey(t) { var i = loggeable_toPrimitive(t, "string"); return "symbol" == loggeable_typeof(i) ? i : i + ""; }
+function loggeable_toPrimitive(t, r) { if ("object" != loggeable_typeof(t) || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != loggeable_typeof(i)) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+
+
+
+/**
+ * Represents the abstract class for the loggeable.
+ * @hidden
+ */
+var Loggeable = /*#__PURE__*/function () {
+  /**
+   * The object to log the events and errors.
+   */
+
+  function Loggeable() {
+    loggeable_classCallCheck(this, Loggeable);
+    this.logger = Logger.getInstance();
+  }
+
+  /**
+   * Add values to identify the client.
+   * @param segmentation The pair values to use as segmentation.
+   * @returns The segmentation with the added values.
+   */
+  return loggeable_createClass(Loggeable, [{
+    key: "logEvent",
+    value:
+    /**
+     * To log a event in this class.
+     * @param eventName The event name.
+     * @param eventSegmentation The pair key, value to segment this event count.
+     */
+    function logEvent(eventName) {
+      var eventSegmentation = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+      this.logger.logEvent(eventName, this.prepareSegmentation(eventSegmentation));
+    }
+
+    /**
+     * To log a captured error in this class.
+     * @param error The captured error
+     * @param args The rest of the arguments.
+     */
+  }, {
+    key: "logError",
+    value: function logError(error) {
+      var _this$logger;
+      var errorTyped = convertToError(error);
+      for (var _len = arguments.length, args = new Array(_len > 1 ? _len - 1 : 0), _key = 1; _key < _len; _key++) {
+        args[_key - 1] = arguments[_key];
+      }
+      (_this$logger = this.logger).logError.apply(_this$logger, [errorTyped].concat(args));
+    }
+
+    /**
+     * To log a captured error as a warning.
+     * @param error The captured error
+     * @param args The rest of the arguments.
+     */
+  }, {
+    key: "logWarning",
+    value: function logWarning(error) {
+      var _this$logger2;
+      var errorTyped = convertToError(error);
+      for (var _len2 = arguments.length, args = new Array(_len2 > 1 ? _len2 - 1 : 0), _key2 = 1; _key2 < _len2; _key2++) {
+        args[_key2 - 1] = arguments[_key2];
+      }
+      (_this$logger2 = this.logger).logWarning.apply(_this$logger2, [errorTyped].concat(args));
+    }
+  }, {
+    key: "logDebug",
+    value: function logDebug() {
+      var _this$logger3;
+      (_this$logger3 = this.logger).logDebug.apply(_this$logger3, arguments);
+    }
+
+    /**
+     * Prints in console any number of given arguments, if and only if, app is running in debug mode.
+     * @param args An array of arguments to log
+     */
+  }, {
+    key: "debugLog",
+    value: function debugLog() {
+      for (var _len3 = arguments.length, args = new Array(_len3), _key3 = 0; _key3 < _len3; _key3++) {
+        args[_key3] = arguments[_key3];
+      }
+      this.logger.debugLog(args);
+    }
+  }]);
+}();
+;// ./src/domain/models/mapConfig.ts
+/**
+ * Configuration options for map tile caching.
+ * Allows controlling how map tiles are cached in memory and persisted via service worker.
+ *
+ * @example
+ * ```typescript
+ * const tileCacheConfig: MapTileCacheConfig = {
+ *   enabled: true,
+ *   maxTiles: 500,
+ *   ttlMs: 60 * 60 * 1000, // 1 hour
+ *   persistToServiceWorker: true,
+ *   preloadAdjacentZooms: false,
+ *   maxConcurrentTileFetches: 6
+ * };
+ * ```
+ *
+ * @group Configuration
+ */
+
+/**
+ * Default values for tile cache configuration
+ * @internal
+ */
+var DEFAULT_TILE_CACHE_CONFIG = {
+  enabled: true,
+  maxTiles: 400,
+  ttlMs: 30 * 60 * 1000,
+  // 30 minutes
+  persistToServiceWorker: true,
+  preloadAdjacentZooms: false,
+  maxConcurrentTileFetches: 6
+};
+
+/**
+ * Hard cap for {@link MapTileCacheConfig.maxTiles}.
+ * Configurations above this (e.g. millions) are clamped to avoid memory pressure
+ * and excessive interaction with the tile CDN / service worker.
  *
- * @group Circles
+ * @internal
  */
-function resolveCircleConfig(config) {
-  var _config$id, _config$fillColor, _config$strokeColor, _config$strokeWidth, _config$renderOrder;
-  var hidden = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : false;
-  validateRadiusMeters(config.radiusMeters);
-  validateCoordinate(config.coordinate);
-  if (config.renderOrder !== undefined && !CIRCLE_RENDER_ORDERS.includes(config.renderOrder)) {
-    throw new Error("Invalid renderOrder: ".concat(String(config.renderOrder), ". ") + "Must be one of: ".concat(CIRCLE_RENDER_ORDERS.join(", "), "."));
-  }
-  return {
-    id: (_config$id = config.id) !== null && _config$id !== void 0 ? _config$id : generateHexadecimalKey(),
-    // Copy the coordinate so later mutations of the caller's object
-    // can't change internal circle state
-    coordinate: {
-      lat: config.coordinate.lat,
-      lng: config.coordinate.lng
-    },
-    radiusMeters: config.radiusMeters,
-    fillColor: (_config$fillColor = config.fillColor) !== null && _config$fillColor !== void 0 ? _config$fillColor : CIRCLE_DEFAULTS.fillColor,
-    fillOpacity: clampOpacity(config.fillOpacity, CIRCLE_DEFAULTS.fillOpacity),
-    strokeColor: (_config$strokeColor = config.strokeColor) !== null && _config$strokeColor !== void 0 ? _config$strokeColor : CIRCLE_DEFAULTS.strokeColor,
-    strokeWidth: (_config$strokeWidth = config.strokeWidth) !== null && _config$strokeWidth !== void 0 ? _config$strokeWidth : CIRCLE_DEFAULTS.strokeWidth,
-    strokeOpacity: clampOpacity(config.strokeOpacity, CIRCLE_DEFAULTS.strokeOpacity),
-    floorId: config.floorId,
-    renderOrder: (_config$renderOrder = config.renderOrder) !== null && _config$renderOrder !== void 0 ? _config$renderOrder : CIRCLE_DEFAULTS.renderOrder,
-    hidden: hidden
-  };
-}
+var MAPLIBRE_MAX_TILE_CACHE_HARD_CAP = 100000;
 
 /**
- * Builds a closed GeoJSON polygon ring approximating a geographic circle.
- *
- * The ring is computed with an equirectangular approximation: meters are
- * converted to degrees independently per axis, with the longitude scale
- * corrected by the cosine of the latitude. For the radii the SDK works with
- * (tens to hundreds of meters) the metric error is negligible (≤1%) at any latitude
- * where the projection is defined. At extreme polar latitudes, the approximation
- * breaks down, so circles near poles (|lat| > 85°) should be used with caution.
- *
- * @param lng Longitude of the circle center in degrees.
- * @param lat Latitude of the circle center in degrees.
- * @param radiusMeters Radius of the circle in meters. Must be positive and finite.
- * @param points Number of segments in the ring. Defaults to 64. Non-integer
- *               values are floored and the count is clamped to a minimum of 3,
- *               the smallest valid GeoJSON linear ring; non-finite values fall
- *               back to the default.
- * @returns A closed ring of `[lng, lat]` positions (first equals last).
+ * Basic configuration for the map.
+ * Provides essential settings for initializing and customizing map behavior.
  *
  * @example
  * ```typescript
- * import { circleRing } from '@mapvx/web-js';
- *
- * // Create a 150-meter radius circle ring
- * const ring = circleRing(-74.0060, 40.7128, 150);
- * const polygon = { type: "Polygon", coordinates: [ring] };
- *
- * // Custom segments (32 instead of 64) for lower resolution
- * const coarseRing = circleRing(-74.0060, 40.7128, 150, 32);
+ * const mapConfig: MapConfig = {
+ *   zoom: 15,
+ *   center: { lat: 40.7128, lng: -74.0060 },
+ *   parentPlaceId: "building-1",
+ *   onMapReady: () => console.log("Map is ready!"),
+ *   enableHover: true,
+ *   showCompass: true
+ * };
  * ```
  *
- * @note Equirectangular approximation is accurate for radii up to ~500 km and
- *       latitudes between approximately ±80°. Beyond these limits, visual
- *       distortion may occur near the poles.
- * @note Generated rings do not account for geographic obstacles, walls, or
- *       buildings. For complex geofencing, consider server-side validation.
+ * @group Map
  *
- * @group Circles
+ * @property zoom - The initial zoom level of the map.
+ * @property center - The initial center coordinates of the map.
+ * @property parentPlaceId - (Optional) The ID of the parent place to display.
+ * @property otherPotentialParentPlacesIds - (Optional) List of alternative parent place IDs.
+ * @property onMapReady - (Optional) Callback invoked when the map is ready.
+ * @property onZoomEnd - (Optional) Callback invoked when the zoom operation ends. Receives the new zoom level.
+ * @property onRotate - (Optional) Callback invoked when the map is rotated. Receives the rotation in degrees.
+ * @property onFloorChange - (Optional) Callback invoked when the floor changes. Receives the new floor ID.
+ * @property onParentPlaceChange - (Optional) Callback invoked when the parent place changes. Receives the new parent place ID.
+ * @property lang - (Optional) Language code for map labels and UI.
+ * @property minZoom - (Optional) Minimum allowed zoom level.
+ * @property maxZoom - (Optional) Maximum allowed zoom level.
+ * @property pitch - (Optional) The pitch (tilt) of the map in degrees.
+ * @property maxBounds - (Optional) Array of coordinates defining the maximum bounds of the map.
+ * @property enableHover - (Optional) Whether to enable hover interactions on the map.
+ * @property showCompass - (Optional) Whether to display the compass control.
+ * @property showZoom - (Optional) Whether to display the zoom control.
+ * @property navigationPosition - (Optional) Position of the navigation controls on the map.
+ * @property bearingSnap - (Optional) The bearing snap threshold in degrees.
+ * @property bearing - (Optional) Initial bearing (rotation) of the map in degrees, clockwise from north.
+ * @property interactive - (Optional) Master switch for all user interaction (pan/zoom/rotate).
+ * @property rotateEnabled - (Optional) Whether the user can rotate the map; keeps pinch-zoom when disabled.
+ * @property dragPan - (Optional) Whether the user can pan by dragging/swiping.
+ * @property scrollZoom - (Optional) Whether the scroll wheel/trackpad can zoom the map.
+ * @property doubleClickZoom - (Optional) Whether double-click/double-tap zooms the map.
+ * @property touchZoomRotate - (Optional) Whether pinch gestures can zoom the map on touch devices.
+ * @property keyboard - (Optional) Whether keyboard shortcuts can pan/zoom/rotate the map.
+ * @property institutionId - (Optional) The institution identifier for map context. Required for loading map related data from Portal.
+ * @property authToken - (Optional) Authentication token for accessing protected map resources. Required for loading map related data from Portal.
+ * @property apiUrl - (Optional) Injected by SDK when creating map; base API URL for map requests.
+ * @property mapvxRequestContext - (Optional) Injected by SDK when creating map; context sent as headers to public-api.mapvx.com.
  */
-function circleRing(lng, lat, radiusMeters) {
-  var points = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : 64;
-  // A linear ring needs at least 3 distinct positions to be valid GeoJSON
-  var segments = Number.isFinite(points) ? Math.max(3, Math.floor(points)) : 64;
-  var ring = [];
-  var latRad = lat * Math.PI / 180;
-  var metersPerDegLat = 110574;
-  var metersPerDegLng = 111320 * Math.cos(latRad || 0.000001);
-  var latR = radiusMeters / metersPerDegLat;
-  var lngR = radiusMeters / (metersPerDegLng || 1);
-  for (var i = 0; i < segments; i += 1) {
-    var a = i / segments * Math.PI * 2;
-    ring.push([lng + lngR * Math.cos(a), lat + latR * Math.sin(a)]);
-  }
-  // Close the ring with an exact copy of the first position, as GeoJSON requires
-  ring.push([ring[0][0], ring[0][1]]);
-  return ring;
-}
 ;// ./node_modules/.pnpm/@googlemaps+polyline-codec@1.0.28/node_modules/@googlemaps/polyline-codec/dist/index.esm.js
 /**
  * Copyright 2020 Google LLC
@@ -11764,17 +11774,107 @@ var Requester = /*#__PURE__*/function () {
       }
       return fetchAnySubPlaces;
     }()
+    /**
+     * Build the cleaned query parameters for a route request.
+     *
+     * Resolves both the origin (`from*`) and destination (`to*`) sides of the route
+     * from the provided configuration. For {@link IdLocation} endpoints this also
+     * forwards the building (`fromBuilding`/`toBuilding`) and floor
+     * (`fromFloor`/`toFloor`) so internal aliases that are reused across buildings
+     * can be disambiguated. Parameters that resolve to `null`/`undefined` are dropped.
+     * @param routeConfig The route configuration to translate into query params.
+     * @returns The cleaned query parameters ready to be appended to the request URL.
+     */
+    )
+  }, {
+    key: "buildRouteParams",
+    value: function buildRouteParams(routeConfig) {
+      var params = {
+        fromLatLng: undefined,
+        fromBuilding: undefined,
+        fromFloor: undefined,
+        toLatLng: undefined,
+        toBuilding: undefined,
+        toFloor: undefined,
+        fromPlaceId: undefined,
+        toPlaceId: undefined,
+        travelMode: TransportationMode.walking,
+        reducedMobility: routeConfig.preferAccessibleRoute ? 1 : 0,
+        announceFormat: routeConfig.announceFormat,
+        userBearing: routeConfig.userBearing,
+        lang: this.lang,
+        unitSystem: routeConfig.unitSystem
+      };
+      if ("id" in routeConfig.initialLocation) {
+        var _routeConfig$initialL = routeConfig.initialLocation,
+          id = _routeConfig$initialL.id,
+          buildingId = _routeConfig$initialL.buildingId,
+          floorId = _routeConfig$initialL.floorId,
+          level = _routeConfig$initialL.level;
+        params.fromPlaceId = id;
+        if (buildingId !== undefined) {
+          params.fromBuilding = buildingId;
+        }
+        if (floorId !== undefined) {
+          params.fromFloor = floorId;
+        } else if (level !== undefined) {
+          params.fromFloor = level;
+        }
+      } else {
+        var _routeConfig$initialL2 = routeConfig.initialLocation,
+          lat = _routeConfig$initialL2.lat,
+          lng = _routeConfig$initialL2.lng,
+          _floorId = _routeConfig$initialL2.floorId,
+          placeId = _routeConfig$initialL2.placeId;
+        params.fromLatLng = "".concat(lat, ",").concat(lng);
+        params.fromFloor = _floorId;
+        params.fromBuilding = placeId;
+      }
+      if ("id" in routeConfig.finalLocation) {
+        var _routeConfig$finalLoc = routeConfig.finalLocation,
+          _id = _routeConfig$finalLoc.id,
+          _buildingId = _routeConfig$finalLoc.buildingId,
+          _floorId2 = _routeConfig$finalLoc.floorId,
+          _level = _routeConfig$finalLoc.level;
+        params.toPlaceId = _id;
+        if (_buildingId !== undefined) {
+          params.toBuilding = _buildingId;
+        }
+        if (_floorId2 !== undefined) {
+          params.toFloor = _floorId2;
+        } else if (_level !== undefined) {
+          params.toFloor = _level;
+        }
+      } else {
+        var _routeConfig$finalLoc2 = routeConfig.finalLocation,
+          _lat = _routeConfig$finalLoc2.lat,
+          _lng = _routeConfig$finalLoc2.lng,
+          _floorId3 = _routeConfig$finalLoc2.floorId,
+          _placeId = _routeConfig$finalLoc2.placeId;
+        params.toLatLng = "".concat(_lat, ",").concat(_lng);
+        params.toFloor = _floorId3;
+        params.toBuilding = _placeId;
+      }
+      var cleanParams = {};
+      for (var key in params) {
+        var value = params[key];
+        if (value != null) {
+          cleanParams[key] = value;
+        }
+      }
+      return cleanParams;
+    }
+
     /**
      * To obtain the route
      * @param routeConfig
      * @returns
      */
-    )
   }, {
     key: "fetchRoute",
     value: (function () {
       var _fetchRoute = requester_asyncToGenerator(/*#__PURE__*/requester_regenerator().m(function _callee10(routeConfig, token) {
-        var options, params, _routeConfig$initialL, lat, lng, floorId, placeId, _routeConfig$finalLoc, _lat, _lng, _floorId, _placeId, cleanParams, key, value;
+        var options, cleanParams;
         return requester_regenerator().w(function (_context10) {
           while (1) switch (_context10.n) {
             case 0:
@@ -11785,51 +11885,7 @@ var Requester = /*#__PURE__*/function () {
                   Authorization: "Bearer ".concat(token)
                 }
               };
-              params = {
-                fromLatLng: undefined,
-                fromBuilding: undefined,
-                fromFloor: undefined,
-                toLatLng: undefined,
-                toBuilding: undefined,
-                toFloor: undefined,
-                fromPlaceId: undefined,
-                toPlaceId: undefined,
-                travelMode: TransportationMode.walking,
-                reducedMobility: routeConfig.preferAccessibleRoute ? 1 : 0,
-                announceFormat: routeConfig.announceFormat,
-                userBearing: routeConfig.userBearing,
-                lang: this.lang,
-                unitSystem: routeConfig.unitSystem
-              };
-              if ("id" in routeConfig.initialLocation) {
-                params.fromPlaceId = routeConfig.initialLocation.id;
-                if (routeConfig.initialLocation.level !== undefined) {
-                  params.fromFloor = routeConfig.initialLocation.level;
-                }
-              } else {
-                _routeConfig$initialL = routeConfig.initialLocation, lat = _routeConfig$initialL.lat, lng = _routeConfig$initialL.lng, floorId = _routeConfig$initialL.floorId, placeId = _routeConfig$initialL.placeId;
-                params.fromLatLng = "".concat(lat, ",").concat(lng);
-                params.fromFloor = floorId;
-                params.fromBuilding = placeId;
-              }
-              if ("id" in routeConfig.finalLocation) {
-                params.toPlaceId = routeConfig.finalLocation.id;
-                if (routeConfig.finalLocation.level !== undefined) {
-                  params.toFloor = routeConfig.finalLocation.level;
-                }
-              } else {
-                _routeConfig$finalLoc = routeConfig.finalLocation, _lat = _routeConfig$finalLoc.lat, _lng = _routeConfig$finalLoc.lng, _floorId = _routeConfig$finalLoc.floorId, _placeId = _routeConfig$finalLoc.placeId;
-                params.toLatLng = "".concat(_lat, ",").concat(_lng);
-                params.toFloor = _floorId;
-                params.toBuilding = _placeId;
-              }
-              cleanParams = {};
-              for (key in params) {
-                value = params[key];
-                if (value != null) {
-                  cleanParams[key] = value;
-                }
-              }
+              cleanParams = this.buildRouteParams(routeConfig);
               return _context10.a(2, this.fetchFromUrl(this.routeBaseUrl + "route", cleanParams, options));
           }
         }, _callee10, this);
@@ -11849,7 +11905,7 @@ var Requester = /*#__PURE__*/function () {
     key: "fetchRouteV2",
     value: (function () {
       var _fetchRouteV = requester_asyncToGenerator(/*#__PURE__*/requester_regenerator().m(function _callee11(routeConfig, token) {
-        var options, params, _routeConfig$initialL2, lat, lng, floorId, placeId, _routeConfig$finalLoc2, _lat2, _lng2, _floorId2, _placeId2, cleanParams, key, value;
+        var options, cleanParams;
         return requester_regenerator().w(function (_context11) {
           while (1) switch (_context11.n) {
             case 0:
@@ -11860,51 +11916,7 @@ var Requester = /*#__PURE__*/function () {
                   Authorization: "Bearer ".concat(token)
                 }
               };
-              params = {
-                fromLatLng: undefined,
-                fromBuilding: undefined,
-                fromFloor: undefined,
-                toLatLng: undefined,
-                toBuilding: undefined,
-                toFloor: undefined,
-                fromPlaceId: undefined,
-                toPlaceId: undefined,
-                travelMode: TransportationMode.walking,
-                reducedMobility: routeConfig.preferAccessibleRoute ? 1 : 0,
-                announceFormat: routeConfig.announceFormat,
-                userBearing: routeConfig.userBearing,
-                lang: this.lang,
-                unitSystem: routeConfig.unitSystem
-              };
-              if ("id" in routeConfig.initialLocation) {
-                params.fromPlaceId = routeConfig.initialLocation.id;
-                if (routeConfig.initialLocation.level !== undefined) {
-                  params.fromFloor = routeConfig.initialLocation.level;
-                }
-              } else {
-                _routeConfig$initialL2 = routeConfig.initialLocation, lat = _routeConfig$initialL2.lat, lng = _routeConfig$initialL2.lng, floorId = _routeConfig$initialL2.floorId, placeId = _routeConfig$initialL2.placeId;
-                params.fromLatLng = "".concat(lat, ",").concat(lng);
-                params.fromFloor = floorId;
-                params.fromBuilding = placeId;
-              }
-              if ("id" in routeConfig.finalLocation) {
-                params.toPlaceId = routeConfig.finalLocation.id;
-                if (routeConfig.finalLocation.level !== undefined) {
-                  params.toFloor = routeConfig.finalLocation.level;
-                }
-              } else {
-                _routeConfig$finalLoc2 = routeConfig.finalLocation, _lat2 = _routeConfig$finalLoc2.lat, _lng2 = _routeConfig$finalLoc2.lng, _floorId2 = _routeConfig$finalLoc2.floorId, _placeId2 = _routeConfig$finalLoc2.placeId;
-                params.toLatLng = "".concat(_lat2, ",").concat(_lng2);
-                params.toFloor = _floorId2;
-                params.toBuilding = _placeId2;
-              }
-              cleanParams = {};
-              for (key in params) {
-                value = params[key];
-                if (value != null) {
-                  cleanParams[key] = value;
-                }
-              }
+              cleanParams = this.buildRouteParams(routeConfig);
               return _context11.a(2, this.fetchFromUrl(this.routeBaseUrl + "v2/route", cleanParams, options));
           }
         }, _callee11, this);
@@ -13670,6 +13682,197 @@ function extractStepCoordinates(step) {
   }
   return coords;
 }
+;// ./src/map/fitCamera.ts
+function fitCamera_createForOfIteratorHelper(r, e) { var t = "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (!t) { if (Array.isArray(r) || (t = fitCamera_unsupportedIterableToArray(r)) || e && r && "number" == typeof r.length) { t && (r = t); var _n = 0, F = function F() {}; return { s: F, n: function n() { return _n >= r.length ? { done: !0 } : { done: !1, value: r[_n++] }; }, e: function e(r) { throw r; }, f: F }; } throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); } var o, a = !0, u = !1; return { s: function s() { t = t.call(r); }, n: function n() { var r = t.next(); return a = r.done, r; }, e: function e(r) { u = !0, o = r; }, f: function f() { try { a || null == t["return"] || t["return"](); } finally { if (u) throw o; } } }; }
+function fitCamera_unsupportedIterableToArray(r, a) { if (r) { if ("string" == typeof r) return fitCamera_arrayLikeToArray(r, a); var t = {}.toString.call(r).slice(8, -1); return "Object" === t && r.constructor && (t = r.constructor.name), "Map" === t || "Set" === t ? Array.from(r) : "Arguments" === t || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(t) ? fitCamera_arrayLikeToArray(r, a) : void 0; } }
+function fitCamera_arrayLikeToArray(r, a) { (null == a || a > r.length) && (a = r.length); for (var e = 0, n = Array(a); e < a; e++) n[e] = r[e]; return n; }
+
+
+/**
+ * Padding, in pixels, already resolved from any unit-based {@link PaddingOptions}.
+ */
+
+/**
+ * A camera target (center + zoom) that fits a set of coordinates.
+ */
+
+/**
+ * Parameters shared by the flat and pitch-aware fit computations.
+ */
+
+/**
+ * Minimal structural view of a maplibre transform clone (`map.transform.clone()`).
+ *
+ * We depend on the shape rather than the (non-exported) `ITransform` interface so
+ * the coupling stays explicit and version changes surface as type errors here.
+ */
+
+/** maplibre world size (px) at zoom 0: tileSize (512) * 2^0. */
+var TILE_SIZE = 512;
+var clamp = function clamp(value, min, max) {
+  return Math.min(Math.max(value, min), max);
+};
+
+/**
+ * Compute the camera (center + zoom) that tightly fits `coordinates` into the
+ * padded viewport for a given bearing, using an ORIENTED bounding box.
+ *
+ * maplibre's `fitBounds` only fits a north-up `LngLatBounds`, which wastes
+ * viewport space for diagonal geometries under a bearing. Instead we rotate the
+ * mercator-projected points by the bearing, measure their axis-aligned extent in
+ * that rotated frame, and derive zoom + center analytically.
+ *
+ * This calculation is orthographic (assumes `pitch: 0`). For a tilted camera use
+ * {@link refineCameraForPitch} to correct for perspective.
+ *
+ * @param coordinates Points to fit (must contain at least one).
+ * @param params Bearing, padding and viewport constraints.
+ * @returns The fitting camera center and zoom.
+ */
+function computeOrientedCamera(coordinates, params) {
+  var bearing = params.bearing,
+    padding = params.padding,
+    containerWidth = params.containerWidth,
+    containerHeight = params.containerHeight,
+    maxZoom = params.maxZoom,
+    minZoom = params.minZoom;
+
+  // Rotate the mercator plane by -bearing so the target bearing becomes axis-aligned.
+  var rad = -bearing * Math.PI / 180;
+  var cos = Math.cos(rad);
+  var sin = Math.sin(rad);
+  var minX = Infinity;
+  var minY = Infinity;
+  var maxX = -Infinity;
+  var maxY = -Infinity;
+  var _iterator = fitCamera_createForOfIteratorHelper(coordinates),
+    _step;
+  try {
+    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+      var coord = _step.value;
+      var m = maplibre_gl.MercatorCoordinate.fromLngLat({
+        lat: coord.lat,
+        lng: coord.lng
+      });
+      var rx = m.x * cos - m.y * sin;
+      var ry = m.x * sin + m.y * cos;
+      minX = Math.min(minX, rx);
+      minY = Math.min(minY, ry);
+      maxX = Math.max(maxX, rx);
+      maxY = Math.max(maxY, ry);
+    }
+  } catch (err) {
+    _iterator.e(err);
+  } finally {
+    _iterator.f();
+  }
+  var boxW = maxX - minX || Number.EPSILON;
+  var boxH = maxY - minY || Number.EPSILON;
+  var availW = Math.max(1, containerWidth - padding.left - padding.right);
+  var availH = Math.max(1, containerHeight - padding.top - padding.bottom);
+
+  // worldSize (px) = TILE_SIZE * 2^zoom
+  var worldSize = Math.min(availW / boxW, availH / boxH);
+  var zoom = clamp(Math.log2(worldSize / TILE_SIZE), minZoom, maxZoom);
+
+  // Center of the oriented box, rotated back to geographic space.
+  var cxr = (minX + maxX) / 2;
+  var cyr = (minY + maxY) / 2;
+  var center = new maplibre_gl.MercatorCoordinate(cxr * cos + cyr * sin, -cxr * sin + cyr * cos, 0).toLngLat();
+  return {
+    center: center,
+    zoom: zoom
+  };
+}
+
+/**
+ * Refine a fit camera for a non-zero pitch.
+ *
+ * With `pitch > 0` the ground-to-screen mapping is non-linear (perspective), so
+ * the orthographic result from {@link computeOrientedCamera} either overshoots
+ * (geometry spills past the padding) or leaves extra space. This iteratively
+ * projects every point through maplibre's real perspective projection on a cloned
+ * transform (no visible camera movement) and adjusts zoom + center until the
+ * projected bounding box fits the padded viewport.
+ *
+ * If any point falls behind the horizon during refinement, it bails out and
+ * returns the best camera computed so far (never worse than the flat input).
+ *
+ * @param transform A `map.transform.clone()` used purely for projection.
+ * @param coordinates Points to fit.
+ * @param initial The orthographic camera to refine.
+ * @param params Bearing, pitch, padding and viewport constraints.
+ * @returns The refined camera center and zoom.
+ */
+function refineCameraForPitch(transform, coordinates, initial, params) {
+  var bearing = params.bearing,
+    pitch = params.pitch,
+    padding = params.padding,
+    containerWidth = params.containerWidth,
+    containerHeight = params.containerHeight,
+    maxZoom = params.maxZoom,
+    minZoom = params.minZoom;
+  transform.setBearing(bearing);
+  transform.setPitch(pitch);
+  transform.setPadding(padding);
+  transform.setCenter(initial.center);
+  transform.setZoom(initial.zoom);
+  var availW = Math.max(1, containerWidth - padding.left - padding.right);
+  var availH = Math.max(1, containerHeight - padding.top - padding.bottom);
+  var MAX_ITERATIONS = 4;
+  var CONVERGENCE_EPSILON = 0.01;
+  var best = {
+    center: initial.center,
+    zoom: initial.zoom
+  };
+  for (var i = 0; i < MAX_ITERATIONS; i++) {
+    var minX = Infinity;
+    var minY = Infinity;
+    var maxX = -Infinity;
+    var maxY = -Infinity;
+    var allOnSurface = true;
+    var _iterator2 = fitCamera_createForOfIteratorHelper(coordinates),
+      _step2;
+    try {
+      for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
+        var coord = _step2.value;
+        var screen = transform.locationToScreenPoint(new maplibre_gl.LngLat(coord.lng, coord.lat));
+        if (!transform.isPointOnMapSurface(screen)) {
+          allOnSurface = false;
+          break;
+        }
+        minX = Math.min(minX, screen.x);
+        minY = Math.min(minY, screen.y);
+        maxX = Math.max(maxX, screen.x);
+        maxY = Math.max(maxY, screen.y);
+      }
+      // A point behind the horizon makes the projected box meaningless; keep the
+      // last valid camera rather than risk an over-zoomed result.
+    } catch (err) {
+      _iterator2.e(err);
+    } finally {
+      _iterator2.f();
+    }
+    if (!allOnSurface) break;
+
+    // Recenter: move the projected box center onto the padded screen center.
+    var boxCenter = new maplibre_gl.Point((minX + maxX) / 2, (minY + maxY) / 2);
+    transform.setCenter(transform.screenPointToLocation(boxCenter));
+
+    // Rescale zoom so the projected box fills the padded viewport.
+    var boxW = Math.max(maxX - minX, 1e-6);
+    var boxH = Math.max(maxY - minY, 1e-6);
+    var scale = Math.min(availW / boxW, availH / boxH);
+    var zoomDelta = Math.log2(scale);
+    transform.setZoom(clamp(transform.zoom + zoomDelta, minZoom, maxZoom));
+    best = {
+      center: transform.center,
+      zoom: transform.zoom
+    };
+    if (Math.abs(zoomDelta) < CONVERGENCE_EPSILON) break;
+  }
+  return best;
+}
 ;// ./src/map/mapInteractionOptions.ts
 /**
  * Subset of MapLibre {@link MapOptions} that can be derived from the interaction
@@ -13920,6 +14123,7 @@ function convertPaddingToPixels(padding, containerWidth, containerHeight) {
 
 
 
+
 /**
  * @group Map
  */
@@ -15141,6 +15345,71 @@ var InternalMapVXMap = /*#__PURE__*/function (_Loggeable) {
         this.map.fitBounds(bounds, fitOptions);
       }
     }
+  }, {
+    key: "easeToCoordinates",
+    value: function easeToCoordinates(coordinates, options) {
+      var _options$maxZoom;
+      if (coordinates.length === 0) {
+        return;
+      }
+      var onComplete = options === null || options === void 0 ? void 0 : options.onComplete;
+
+      // Get container dimensions for percentage-based padding calculations
+      var container = this.map.getContainer();
+      var containerWidth = container.clientWidth;
+      var containerHeight = container.clientHeight;
+
+      // Convert padding values with units to pixels
+      var padding = convertPaddingToPixels(options === null || options === void 0 ? void 0 : options.padding, containerWidth, containerHeight);
+      if (coordinates.length === 1) {
+        var _coordinates2 = map_slicedToArray(coordinates, 1),
+          coord = _coordinates2[0];
+        if (onComplete) {
+          void this.map.once("moveend", onComplete);
+        }
+        this.map.easeTo(map_objectSpread(map_objectSpread({}, options), {}, {
+          center: {
+            lat: coord.lat,
+            lng: coord.lng
+          },
+          padding: padding
+        }));
+        return;
+      }
+      var bearing = (options === null || options === void 0 ? void 0 : options.bearing) !== undefined ? options.bearing : this.map.getBearing();
+      var pitch = (options === null || options === void 0 ? void 0 : options.pitch) !== undefined ? options.pitch : this.map.getPitch();
+      var cameraParams = {
+        bearing: bearing,
+        padding: padding,
+        containerWidth: containerWidth,
+        containerHeight: containerHeight,
+        maxZoom: (_options$maxZoom = options === null || options === void 0 ? void 0 : options.maxZoom) !== null && _options$maxZoom !== void 0 ? _options$maxZoom : this.map.getMaxZoom(),
+        minZoom: this.map.getMinZoom()
+      };
+
+      // Orthographic oriented fit (exact for pitch 0). maplibre's fitBounds only
+      // fits a north-up LngLatBounds, which wastes viewport space for diagonal
+      // geometries under a bearing.
+      var camera = computeOrientedCamera(coordinates, cameraParams);
+
+      // With a tilted camera the orthographic zoom is off due to perspective, so
+      // refine it against maplibre's real projection on a cloned transform.
+      if (pitch > 0) {
+        camera = refineCameraForPitch(this.map.transform.clone(), coordinates, camera, map_objectSpread(map_objectSpread({}, cameraParams), {}, {
+          pitch: pitch
+        }));
+      }
+      if (onComplete) {
+        void this.map.once("moveend", onComplete);
+      }
+      this.map.easeTo(map_objectSpread(map_objectSpread({}, options), {}, {
+        center: camera.center,
+        zoom: camera.zoom,
+        bearing: bearing,
+        pitch: pitch,
+        padding: padding
+      }));
+    }
   }, {
     key: "fitRouteByPlace",
     value: function fitRouteByPlace(route, placeId, options) {