@maptiler/sdk 4.0.2-rc.1 → 4.0.3-projection.alpha.1

package/README.md

@@ -1843,6 +1843,131 @@ import { config } from "@maptiler/sdk";
 config.caching = false;
 ```
 
+### Prefetching (experimental)
+
+The SDK can prefetch tiles ahead of camera movements and store them in the browser cache, so they render instantly when the map arrives at the destination. This is an **experimental** feature — the API may change in future releases.
+
+> ⚠️ **API Key Usage**: Every prefetched tile counts against your MapTiler Cloud API key quota. Use narrow zoom ranges and small geographic areas where possible.
+
+#### Enabling
+
+Pass `useExperimentalTilePreloading: true` when creating the map:
+
+```ts
+import { Map } from "@maptiler/sdk";
+
+const map = new Map({
+  container: "map",
+  useExperimentalTilePreloading: true,
+});
+```
+
+#### Prefetching on camera animations
+
+Once enabled, pass `experimental_preload` in the options of any camera animation method. Tiles are fetched before the animation starts, so they are ready when the camera arrives.
+
+**`flyTo`** — prefetches tiles visible at the destination:
+
+```ts
+map.flyTo({
+  center: [-74.006, 40.7128],
+  zoom: 14,
+  experimental_preload: { maxTiles: 256 },
+});
+```
+
+**`panTo`** — prefetches tiles along the pan path:
+
+```ts
+map.panTo([-74.006, 40.7128], {
+  experimental_preload: {},
+});
+```
+
+**`easeTo`** — prefetches tiles along the ease path:
+
+```ts
+map.easeTo({
+  center: [-74.006, 40.7128],
+  zoom: 12,
+  experimental_preload: {},
+});
+```
+
+**`fitBounds`** — prefetches tiles for the destination viewport:
+
+```ts
+map.fitBounds([[-74.1, 40.6], [-73.9, 40.8]], {
+  experimental_preload: { maxTiles: 128 },
+});
+```
+
+**`zoomTo`** — prefetches tiles for the target zoom level:
+
+```ts
+map.zoomTo(15, {
+  experimental_preload: {},
+});
+```
+
+The `experimental_preload` object accepts these options:
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `maxTiles` | `number` | `512` | Maximum tiles to fetch. Tiles beyond this limit are silently dropped. |
+| `onProgress` | `(done, total, tileID?) => void` | — | Called after each tile fetch attempt (success or failure). |
+| `onError` | `(error) => void` | — | Called when a tile fails to load. |
+
+#### Prefetching manually
+
+Three methods let you prefetch tiles independently of camera animations.
+
+**`experimental_preloadTilesForBounds`** — fetches all tiles within a bounding box across a zoom range:
+
+```ts
+await map.experimental_preloadTilesForBounds({
+  bounds: map.getBounds(),
+  minZoom: 8,
+  maxZoom: 12,
+  onProgress: (done, total) => console.log(`${done}/${total}`),
+});
+```
+
+**`experimental_preloadTilesForCameraPositions`** — fetches tiles visible from one or more camera viewpoints:
+
+```ts
+await map.experimental_preloadTilesForCameraPositions({
+  positions: [
+    { lng: -74.006, lat: 40.7128, zoom: 12 },
+    { lng: -73.935, lat: 40.730,  zoom: 14, pitch: 45 },
+  ],
+  maxTiles: 256,
+});
+```
+
+**`experimental_preloadTiles`** — fetches a specific list of tiles by ID (`"z/x/y"` format):
+
+```ts
+await map.experimental_preloadTiles({
+  tileIDs: ["12/1205/1540", "12/1206/1540"],
+  onError: (err) => console.error(err),
+});
+```
+
+#### Global config options
+
+Two `config` properties tune the prefetching behaviour globally:
+
+```ts
+import { config } from "@maptiler/sdk";
+
+// Number of camera positions sampled along a path for panTo/easeTo/fitBounds/zoomTo (default: 4)
+config.experimental_defaultPathSampleSteps = 6;
+
+// Number of concurrent tile fetch workers (default: 4)
+config.experimental_defaultWorkerCount = 8;
+```
+
 ### Easy access to MapTiler API
 
 Our map SDK is not only about maps! We also provide plenty of wrappers to our API calls!

package/dist/Map.d.ts

@@ -1,8 +1,9 @@
-import { default as maplibregl, StyleSpecification, MapOptions as MapOptionsML, ControlPosition, StyleSwapOptions, StyleOptions, RequestTransformFunction, LayerSpecification, SourceSpecification, CustomLayerInterface, FilterSpecification, StyleSetterOptions, ProjectionSpecification } from 'maplibre-gl';
+import { default as maplibregl, StyleSpecification, MapOptions as MapOptionsML, ControlPosition, StyleSwapOptions, StyleOptions, RequestTransformFunction, LayerSpecification, SourceSpecification, CustomLayerInterface, FilterSpecification, StyleSetterOptions, ProjectionSpecification, FlyToOptions, EaseToOptions, FitBoundsOptions, AnimationOptions, LngLatBoundsLike, LngLatLike } from 'maplibre-gl';
 import { ReferenceMapStyle, MapStyleVariant } from '@maptiler/client';
 import { SdkConfig } from './config';
 import { LanguageInfo } from './language';
 import { MinimapOptionsInput } from './controls/Minimap';
+import { PreloadTilesForBoundsOptions, PreloadTilesForCameraPositionsOptions, PreloadTilesOptions, WithTilePreload } from './tile-preloading/types';
 import { Telemetry } from './Telemetry';
 import { CubemapDefinition, CubemapLayer, CubemapLayerConstructorOptions } from './custom-layers/CubemapLayer';
 import { GradientDefinition, RadialGradientLayer, RadialGradientLayerConstructorOptions } from './custom-layers/RadialGradientLayer';
@@ -173,6 +174,14 @@ export type MapOptions = Omit<MapOptionsML, "style" | "maplibreLogo" | "attribut
      * Default is undefined, which means the plugin is enabled by default.
      */
     rtlTextPlugin?: boolean | string;
+    /**
+     * Whether to enable the experimental tile preloading feature.
+     * Default is false.
+     * @experimental
+     * @remarks
+     * **API Key Usage**: Each tile request counts against your MapTiler Cloud API key quota. Use with caution.
+     */
+    useExperimentalTilePreloading?: boolean;
 };
 /**
  * Options to provide to the {@link Map.setProjection} method
@@ -239,6 +248,7 @@ export declare class Map extends maplibregl.Map {
     getHalo(): RadialGradientLayer | undefined;
     setHalo(halo: GradientDefinition): void;
     private options;
+    private tilePreloader?;
     private isTerrainEnabled;
     private terrainExaggeration;
     private primaryLanguage;
@@ -532,4 +542,145 @@ export declare class Map extends maplibregl.Map {
      * and has never been changed.
      */
     isLanguageUpdated(): boolean;
+    /**
+     * Preloads all tiles within a geographic bounds across a range of zoom levels,
+     * storing them in the SDK tile cache so subsequent renders are served instantly.
+     *
+     * @remarks
+     * **API Key Usage**: This method issues one tile request per tile per active source.
+     * Tile count grows exponentially with zoom level — a wide zoom range over a large
+     * area can trigger thousands of requests, each counting against your MapTiler Cloud
+     * API key quota. Use narrow zoom ranges and small bounds wherever possible, and
+     * monitor consumption via the `onProgress` callback.
+     * @experimental
+     * @param {PreloadTilesForBoundsOptions} options - The options for the preload.
+     * @returns A promise that resolves when the preload is complete.
+     * @example
+     * ```ts
+     * await map.experimental_preloadTilesForBounds({
+     *   bounds: map.getBounds(),
+     *   minZoom: 8,
+     *   maxZoom: 12,
+     * });
+     * ```
+     */
+    experimental_preloadTilesForBounds(options: PreloadTilesForBoundsOptions): Promise<void>;
+    /**
+     * Preloads tiles visible from each of the given camera positions, storing them
+     * in the SDK tile cache so renders at those viewpoints are served instantly.
+     *
+     * Use this method before a planned `flyTo` or `panTo` to ensure tiles along
+     * the path are ready when the animation reaches them.
+     * @experimental
+     * @param {PreloadTilesForCameraPositionsOptions} options - The options for the preload.
+     * @returns A promise that resolves when the preload is complete.
+     * @remarks
+     * **API Key Usage**: Each position triggers one request per visible tile per
+     * active source. More positions at higher zoom levels significantly increase
+     * API usage, each request counting against your MapTiler Cloud API key quota.
+     *
+     * @example
+     * ```ts
+     * await map.preloadTilesForCameraPositions({
+     *   positions: [
+     *     { lng: -74.006, lat: 40.7128, zoom: 12 },
+     *     { lng: -73.935, lat: 40.730,  zoom: 14 },
+     *   ],
+     *   onProgress: (done, total, tileID) => console.log(tileID),
+     * });
+     * ```
+     */
+    experimental_preloadTilesForCameraPositions(options: PreloadTilesForCameraPositionsOptions): Promise<void>;
+    /**
+     * Preloads a specific set of tiles identified by their `"z/x/y"` tile IDs,
+     * storing them in the SDK tile cache.
+     *
+     * @experimental
+     * @param {PreloadTilesOptions} options - The options for the preload.
+     * @returns A promise that resolves when the preload is complete.
+     * @remarks
+     * **API Key Usage**: Each tile ID results in one request per active source,
+     * counting against your MapTiler Cloud API key quota.
+     *
+     * @example
+     * ```ts
+     * await map.preloadTiles({
+     *   tileIDs: ["12/1205/1540", "12/1206/1540"],
+     *   onError: (err) => console.error(err),
+     * });
+     * ```
+     */
+    experimental_preloadTiles(options: PreloadTilesOptions): Promise<void>;
+    /**
+     * Changes any combination of center, zoom, bearing, and pitch, animating the
+     * transition along a curve that evokes flight. The animation seamlessly incorporates
+     * zooming and panning to help the user maintain her bearings even after traversing
+     * a great distance.
+     *
+     * If `options.experimental_preload` is provided, tiles along the flight path are fetched and
+     * cached before the animation begins so they are ready when rendered.
+     *
+     * @remarks
+     * **API Key Usage**: When `experimental_preload` is set, tile requests are issued for positions
+     * sampled along the flight path. These count against your MapTiler Cloud API key quota.
+     */
+    flyTo(options: WithTilePreload<FlyToOptions>, eventData?: object): this;
+    /**
+     * Pans the map to the specified location with an animated transition.
+     *
+     * If `options.experimental_preload` is provided, tiles along the pan path are fetched and
+     * cached before the animation begins.
+     *
+     * @remarks
+     * **API Key Usage**: When `experimental_preload` is set, tile requests are issued for positions
+     * sampled along the pan path. These count against your MapTiler Cloud API key quota.
+     */
+    panTo(lnglat: LngLatLike, options?: WithTilePreload<AnimationOptions & {
+        pitch?: number;
+    }>, eventData?: object): this;
+    /**
+     * Changes any combination of center, zoom, bearing, pitch, and roll, with an
+     * animated transition between old and new values.
+     *
+     * If `options.experimental_preload` is provided, tiles along the ease path are fetched and
+     * cached before the animation begins.
+     *
+     * @remarks
+     * **API Key Usage**: When `experimental_preload` is set, tile requests are issued for positions
+     * sampled along the ease path. These count against your MapTiler Cloud API key quota.
+     */
+    easeTo(options: WithTilePreload<EaseToOptions>, eventData?: object): this;
+    /**
+     * Pans and zooms the map to contain its visible area within the specified
+     * geographical bounds. This function will also reset the map's bearing to 0
+     * if options.bearing is not specified.
+     *
+     * If `options.experimental_preload` is provided, tiles for the target view are fetched and
+     * cached before the animation begins.
+     *
+     * @remarks
+     * **API Key Usage**: When `experimental_preload` is set, tile requests are issued for the
+     * destination viewport. These count against your MapTiler Cloud API key quota.
+     */
+    fitBounds(bounds: LngLatBoundsLike, options?: WithTilePreload<FitBoundsOptions>, eventData?: object): this;
+    /**
+     * Zooms the map to the specified zoom level, with an animated transition.
+     *
+     * If `options.experimental_preload` is provided, tiles for the target zoom level are fetched
+     * and cached before the animation begins.
+     *
+     * @remarks
+     * **API Key Usage**: When `experimental_preload` is set, tile requests are issued for the
+     * target zoom. These count against your MapTiler Cloud API key quota.
+     */
+    zoomTo(zoom: number, options?: WithTilePreload<AnimationOptions> | null, eventData?: object): this;
+    /**
+     * Returns the map's current camera state as a {@link CameraPosition}.
+     */
+    private currentCameraPosition;
+    /**
+     * Resolves camera method options into a {@link CameraPosition}, filling in
+     * current map state for any properties not specified in the options.
+     */
+    private resolveCameraPosition;
 }

package/dist/MaptilerAnimation/animation-helpers.d.ts

@@ -1,15 +1,5 @@
 import { Feature, LineString, MultiLineString, MultiPoint, Polygon } from 'geojson';
 import { EasingFunctionName, Keyframe, NumericArrayWithNull } from './types';
-/**
- * Performs simple linear interpolation between two numbers.
- *
- * @param a - The start value
- * @param b - The end value
- * @param alpha - The interpolation factor (typically between 0 and 1):
- *                0 returns a, 1 returns b, and values in between return a proportional mix
- * @returns The interpolated value between a and b
- */
-export declare function lerp(a: number, b: number, alpha: number): number;
 /**
  * Interpolates an array of numbers, replacing null values with interpolated values.
  *

package/dist/MaptilerAnimation/index.d.ts

@@ -3,5 +3,5 @@ export { MaptilerAnimation };
 export type * from './MaptilerAnimation';
 export type * from './types';
 export * from './easing';
-export { type KeyframeableGeometry, type KeyframeableGeoJSONFeature, lerp, lerpArrayValues, parseGeoJSONFeatureToKeyframes, createBezierPathFromCoordinates, getAverageDistance, simplifyPath, resamplePath, stretchNumericalArray, } from './animation-helpers';
+export { type KeyframeableGeometry, type KeyframeableGeoJSONFeature, lerpArrayValues, parseGeoJSONFeatureToKeyframes, createBezierPathFromCoordinates, getAverageDistance, simplifyPath, resamplePath, stretchNumericalArray, } from './animation-helpers';
 export type * from './animation-helpers';

package/dist/caching.d.ts

@@ -1,4 +1,22 @@
 import { ResourceType } from 'maplibre-gl';
 export declare const CACHE_API_AVAILABLE: boolean;
 export declare function localCacheTransformRequest(reqUrl: URL, resourceType?: ResourceType): string;
+/**
+ * Derives a stable cache key from a tile URL by stripping ephemeral params
+ * (`key`, `mtsid`) that vary per-request but do not affect tile content.
+ * Both the prefetch path and the protocol handler must use this function so
+ * cache writes and reads always resolve to the same key.
+ * @internal
+ */
+export declare function getTileCacheKey(url: URL | string): string;
+/**
+ * Fetches a tile URL and stores it in the SDK cache so subsequent MapLibre
+ * requests for the same tile are served from cache without a network round-trip.
+ *
+ * When the Cache API is unavailable, the tile is still fetched so the browser's
+ * own HTTP cache can serve it later.
+ *
+ * @internal
+ */
+export declare function prefetchTileUrl(url: string, signal?: AbortSignal): Promise<void>;
 export declare function registerLocalCacheProtocol(): void;

package/dist/config.d.ts

@@ -80,6 +80,15 @@ declare class SdkConfig extends EventEmitter {
      * Get the fetch fucntion
      */
     get fetch(): FetchFunction | null;
+    /**
+     * The default number of steps to sample for the experimental flyTo path preloading.
+     */
+    private _experimentalDefaultPathSampleSteps;
+    get experimental_defaultPathSampleSteps(): number;
+    set experimental_defaultPathSampleSteps(s: number);
+    private _experimentalDefaultWorkerCount;
+    get experimental_defaultWorkerCount(): number;
+    set experimental_defaultWorkerCount(w: number);
 }
 declare const config: SdkConfig;
 export { config, SdkConfig };

package/dist/index.d.ts

@@ -84,6 +84,7 @@ export { MapTouchEvent } from './MLAdapters/MapTouchEvent';
 export { MapMouseEvent } from './MLAdapters/MapMouseEvent';
 export * from './ml-types';
 export { Map, GeolocationType, type AttributionControlOptions, type MapOptions, type LoadWithTerrainEvent } from './Map';
+export type { CameraPosition, TilePreloadOptions, WithTilePreload, PreloadTilesForBoundsOptions, PreloadTilesForCameraPositionsOptions, PreloadTilesOptions, TilePreloadErrorCallback, TilePreloadProgressCallback, } from './tile-preloading';
 export { type BaseGeocodingOptions, type ByIdGeocodingOptions, type CommonForwardAndReverseGeocodingOptions, type GeocodingOptions, type LanguageGeocodingOptions, type ReverseGeocodingOptions, geocoding, } from './geocoding';
 export * from './controls';
 export { type AutomaticStaticMapOptions, type BoundedStaticMapOptions, type BufferToPixelDataFunction, type CenteredStaticMapOptions, type CoordinateExport, type CoordinateGrid, type CoordinateId, type CoordinateSearch, type CoordinateSearchResult, type CoordinateTransformResult, type CoordinateTransformation, type Coordinates, type CoordinatesSearchOptions, type CoordinatesTransformOptions, type DefaultTransformation, type ElevationAtOptions, type ElevationBatchOptions, type FeatureHierarchy, type FetchFunction, type GeocodingFeature, type GeocodingSearchResult, type GeolocationInfoOptions, type GeolocationResult, type GetDataOptions, MapStyle, type MapStylePreset, type MapStyleType, MapStyleVariant, type PixelData, ReferenceMapStyle, ServiceError, type StaticMapBaseOptions, type StaticMapMarker, type TileJSON, type XYZ, bufferToPixelDataBrowser, circumferenceAtLatitude, coordinates, data, elevation, expandMapStyle, geolocation, getBufferToPixelDataParser, getTileCache, mapStylePresetList, math, misc, staticMaps, styleToStyle, type LanguageInfo, areSameLanguages, toLanguageInfo, isLanguageInfo, getAutoLanguage, getLanguageInfoFromFlag, getLanguageInfoFromCode, getLanguageInfoFromKey, canParsePixelData, } from '@maptiler/client';