@maptiler/sdk 4.0.3-rc.1 → 4.1.0-rc.1

package/dist/ml-types.d.ts

@@ -162,7 +162,13 @@ export type SortKeyRange = SymbolBucket["sortKeyRanges"][number];
 /** @deprecated Will be removed from public API in MapTiler SDK v4 */
 export type Entry = GlyphManager["entries"][string];
 /** @deprecated Will be removed from public API in MapTiler SDK v4 */
-export type PoolObject = ReturnType<RenderPool["getObjectForId"]>;
+export type PoolObject = {
+    id: number;
+    fbo: Framebuffer;
+    texture: Texture;
+    stamp: number;
+    inUse: boolean;
+};
 /** @deprecated Will be removed from public API in MapTiler SDK v4 */
 export type RenderPass = "offscreen" | "opaque" | "translucent";
 /** @deprecated Will be removed from public API in MapTiler SDK v4 */
@@ -504,8 +510,6 @@ type GlyphManager = Painter["glyphManager"];
 /** @deprecated Will be removed from public API in MapTiler SDK v4 */
 type RenderToTexture = Painter["renderToTexture"];
 /** @deprecated Will be removed from public API in MapTiler SDK v4 */
-type RenderPool = RenderToTexture["pool"];
-/** @deprecated Will be removed from public API in MapTiler SDK v4 */
 type CollisionIndex = Placement["collisionIndex"];
 /** @deprecated Will be removed from public API in MapTiler SDK v4 */
 type RGBAImage = StyleImageData["data"];

package/dist/tile-preloading/TilePreloader.d.ts

@@ -0,0 +1,96 @@
+import { Map as SDKMap } from '../Map';
+import { PreloadTilesForBoundsOptions, PreloadTilesForCameraPositionsOptions, PreloadTilesForLinearPathOptions, PreloadTilesOptions, TileCoord } from './types';
+/**
+ * Handles tile preloading for a {@link Map} instance.
+ *
+ * Prefetches tiles for every active tile source in the current style and stores
+ * them in the SDK tile cache so MapLibre can render them without a network
+ * round-trip.
+ *
+ * Preload strategies include geographic bounds with a zoom range
+ * (`preloadForBounds`), prefetch a tilePyramid for a LatLngBounds
+ * (`preloadForCameraPositions`), a sampled linear camera path
+ * (`preloadForLinearPath`), and explicit `"z/x/y"` tile IDs (`preloadByTileIDs`).
+ * Each method returns a `Promise` that resolves when the preloading is complete.
+ * Call `abortAll()` to cancel in-flight requests.
+ *
+ * @remarks
+ * **API Key Usage**: Every tile fetched by this class counts against your
+ * MapTiler Cloud API key quota. Prefer narrow zoom ranges and small geographic
+ * areas where possible, and use the `onProgress` callback to monitor consumption.
+ *
+ * If you update the version of the tile preloader, please update the version in the `EXPERIMENTAL_TILE_PRELOADING_VERSION` constant.
+ * @example
+ * ```ts
+ * import { EXPERIMENTAL_TILE_PRELOADING_VERSION } from "./version";
+  
+ * EXPERIMENTAL_TILE_PRELOADING_VERSION = "0.2.0";
+ * ```
+ */
+export declare class TilePreloader {
+    private readonly map;
+    private readonly activeAbortControllers;
+    constructor(map: SDKMap);
+    /**
+     * Cancels all in-flight preload requests. Called automatically when a new
+     * camera movement begins so stale prefetches do not waste quota.
+     */
+    abortAll(): void;
+    /**
+     * Preloads all tiles within a geographic bounds across a range of zoom levels.
+     *
+     * @remarks
+     * **API Key Usage**: Tile count grows exponentially with zoom level. A wide zoom
+     * range over a large area can trigger thousands of requests.
+     * @param {PreloadTilesForBoundsOptions} options Options for preloading tiles for bounds.
+     * @returns A promise that resolves when the preloading is complete.
+     * @example
+     * ```ts
+     * await map.preloadTilesForBounds({
+     *   bounds: map.getBounds(),
+     *   minZoom: 8,
+     *   maxZoom: 12,
+     * });
+     */
+    preloadForBounds({ bounds, minZoom, maxZoom, onProgress, onError }: PreloadTilesForBoundsOptions): Promise<void>;
+    /**
+     * Preloads tiles visible from each of the given camera positions.
+     *
+     * @remarks
+     * **API Key Usage**: Each position triggers requests for all tiles visible from
+     * that viewpoint. More positions at higher zoom levels increase API usage significantly.
+     */
+    preloadForCameraPositions({ positions, onProgress, onError }: PreloadTilesForCameraPositionsOptions): Promise<TileCoord[]>;
+    /**
+     * Preloads a specific set of tiles by their IDs (`"z/x/y"` format).
+     * @param {PreloadTilesOptions} options - The options for preloading tiles by tile IDs.
+     * @returns A promise that resolves when the preloading is complete.
+     * @example
+     * ```ts
+     * await map.preloadByTileIDs({
+     *   tileIDs: ["12/1205/1540", "12/1206/1540"],
+     * });
+     * ```
+     */
+    preloadByTileIDs({ tileIDs, onProgress, onError }: PreloadTilesOptions): Promise<void>;
+    /**
+     * Preloads tiles along a linear camera path (used by panTo and easeTo overrides).
+     * @param {PreloadTilesForLinearPathOptions} options - The options for preloading tiles along a linear camera path.
+     * @returns A promise that resolves when the preloading is complete.
+     * @example
+     * ```ts
+     * await map.preloadForLinearPath({
+     *   start: { lng: -74.006, lat: 40.7128, zoom: 12 },
+     *   end: { lng: -73.935, lat: 40.730, zoom: 14 },
+     * });
+     * ```
+     */
+    preloadForLinearPath({ start, end, onProgress, onError }: PreloadTilesForLinearPathOptions): Promise<TileCoord[]>;
+    /**
+     * Fetches tiles for the given tile coordinates and stores them in the SDK tile cache.
+     * @param tiles - The tile coordinates to fetch.
+     * @param {TilePreloadOptions} callbacks - The callbacks for the preloading.
+     * @returns A promise that resolves when the preloading is complete.
+     */
+    private fetchTiles;
+}

package/dist/tile-preloading/index.d.ts

@@ -0,0 +1,2 @@
+export { TilePreloader } from './TilePreloader';
+export type { CameraPosition, TilePreloadOptions, WithTilePreload, PreloadTilesForBoundsOptions, PreloadTilesForCameraPositionsOptions, PreloadTilesOptions, TilePreloadErrorCallback, TilePreloadProgressCallback, } from './types';

package/dist/tile-preloading/tile-math.d.ts

@@ -0,0 +1,57 @@
+import { LngLatBoundsLike } from 'maplibre-gl';
+import { CameraPosition, TileCoord } from './types';
+/**
+ * Returns all tile coordinates that fall within the given geographic bounds
+ * at each integer zoom level from `minZoom` to `maxZoom` (inclusive).
+ *
+ * @internal
+ */
+export declare function tilesForBounds(bounds: LngLatBoundsLike, minZoom: number, maxZoom: number): TileCoord[];
+/**
+ * Returns all tile coordinates visible from a camera position given the
+ * current map viewport dimensions. Accounts for pitch by extending the
+ * visible area toward the horizon.
+ *
+ * @internal
+ */
+export declare function tilesForCameraPosition(position: CameraPosition, viewportWidth: number, viewportHeight: number): TileCoord[];
+/**
+ * Returns the geographic bounds visible from a camera position at the given
+ * viewport size. Matches the tile footprint used by {@link tilesForCameraPosition}
+ * without the extra padding margin.
+ *
+ * @internal
+ */
+export declare function viewBoundsForCameraPosition(position: CameraPosition, viewportWidth: number, viewportHeight: number): LngLatBoundsLike;
+/**
+ * Samples positions along a linear camera path (panTo, easeTo) at the
+ * given number of steps.
+ *
+ * @internal
+ */
+export declare function sampleLinearPath(start: CameraPosition, end: CameraPosition, steps: number): CameraPosition[];
+/**
+ * Parses a tile ID string in `"z/x/y"` format into a {@link TileCoord}.
+ * Returns `null` if the string is not valid.
+ *
+ * @internal
+ */
+export declare function parseTileID(tileID: string): TileCoord | null;
+/**
+ * Formats a {@link TileCoord} as a `"z/x/y"` string.
+ *
+ * @internal
+ */
+export declare function formatTileID(tile: TileCoord): string;
+/**
+ * Substitutes `{z}`, `{x}`, `{y}` placeholders in a tile URL template.
+ *
+ * @internal
+ */
+export declare function buildTileUrl(urlTemplate: string, tile: TileCoord): string;
+/**
+ * Deduplicates an array of tile coordinates using a string-keyed Set.
+ *
+ * @internal
+ */
+export declare function deduplicateTiles(tiles: TileCoord[]): TileCoord[];

package/dist/tile-preloading/types.d.ts

@@ -0,0 +1,144 @@
+import { LngLatBoundsLike } from 'maplibre-gl';
+/**
+ * Called after each tile fetch attempt during preloading.
+ *
+ * @param done - Number of tiles attempted so far (loaded or failed)
+ * @param total - Total number of tiles to preload
+ * @param tileID - ID of the tile just attempted, in `"z/x/y"` format
+ *
+ * @remarks
+ * **API Key Usage**: Each tile fetch counts against your MapTiler Cloud API key quota.
+ */
+export type TilePreloadProgressCallback = (done: number, total: number, tileID?: string | null) => void;
+/**
+ * Called when a tile fails to load during preloading.
+ *
+ * @param error - The error that occurred
+ */
+export type TilePreloadErrorCallback = (error: unknown) => void;
+/**
+ * Options shared by all tile preloading APIs.
+ *
+ * @remarks
+ * **API Key Usage**: Tile preloading issues one network request per tile per active source.
+ * These requests count against your MapTiler Cloud API key quota. Use `onProgress` to
+ * monitor consumption and prefer narrow zoom ranges and small bounds where possible.
+ */
+export type TilePreloadOptions = {
+    /**
+     * Called after each tile fetch attempt, whether it succeeded or failed.
+     */
+    onProgress?: TilePreloadProgressCallback;
+    /**
+     * Called when a tile fails to load.
+     */
+    onError?: TilePreloadErrorCallback;
+    /**
+     * Maximum number of tiles to fetch across all sources. Tiles beyond this
+     * limit are silently dropped. Defaults to `512`.
+     *
+     * @remarks
+     * **API Key Usage**: Each tile counts against your MapTiler Cloud API key quota.
+     * Keep this value conservative, especially across wide zoom ranges.
+     *
+     * @defaultValue 512
+     */
+    maxTiles?: number;
+};
+/**
+ * Adds optional experimental tile preloading to camera animation method options.
+ */
+export type WithTilePreload<T> = T & {
+    /**
+     * Experimental tile preloading options. This will only work if `useExperimentalTilePreloading` is set to `true` on the map options.
+     */
+    experimental_preload?: TilePreloadOptions;
+};
+/**
+ * Options for preloading all tiles within a geographic bounds across a range of zoom levels.
+ *
+ * @remarks
+ * **API Key Usage**: The number of tiles grows exponentially with zoom level. For example,
+ * a city-scale area at zoom 12–15 can result in thousands of tile requests per source.
+ * Each request counts against your MapTiler Cloud API key quota.
+ */
+export type PreloadTilesForBoundsOptions = TilePreloadOptions & {
+    /**
+     * The geographic bounds to preload tiles for.
+     */
+    bounds: LngLatBoundsLike;
+    /**
+     * Minimum zoom level to preload (inclusive).
+     */
+    minZoom: number;
+    /**
+     * Maximum zoom level to preload (inclusive).
+     */
+    maxZoom: number;
+};
+/**
+ * A camera viewpoint used to determine which tiles are visible from that position.
+ */
+export type CameraPosition = {
+    /** Longitude of the camera center */
+    lng: number;
+    /** Latitude of the camera center */
+    lat: number;
+    /** Zoom level */
+    zoom: number;
+    /** Camera pitch in degrees (default: 0) */
+    pitch?: number;
+    /** Camera bearing in degrees (default: 0) */
+    bearing?: number;
+};
+/**
+ * Options for preloading tiles visible from one or more camera positions.
+ *
+ * @remarks
+ * **API Key Usage**: Each position triggers tile requests for all tiles visible
+ * from that viewpoint. More positions and higher zoom levels result in more
+ * requests, each counting against your MapTiler Cloud API key quota.
+ */
+export type PreloadTilesForCameraPositionsOptions = TilePreloadOptions & {
+    /**
+     * Camera positions to preload tiles for. Tiles visible from each position
+     * will be fetched and cached.
+     */
+    positions: CameraPosition[];
+};
+/**
+ * Options for preloading tiles along a linear camera path.
+ */
+export type PreloadTilesForLinearPathOptions = TilePreloadOptions & {
+    /**
+     * Start camera position.
+     */
+    start: CameraPosition;
+    /**
+     * End camera position.
+     */
+    end: CameraPosition;
+    /**
+     * Number of steps to sample along the path.
+     */
+    steps?: number;
+};
+/**
+ * Options for preloading a specific set of tiles by their IDs.
+ *
+ * @remarks
+ * **API Key Usage**: Each tile ID results in one fetch per active map source.
+ * Each request counts against your MapTiler Cloud API key quota.
+ */
+export type PreloadTilesOptions = TilePreloadOptions & {
+    /**
+     * Tile IDs to preload, in `"z/x/y"` format.
+     */
+    tileIDs: string[];
+};
+/** @internal */
+export type TileCoord = {
+    z: number;
+    x: number;
+    y: number;
+};

package/dist/tile-preloading/version.d.ts

@@ -0,0 +1,2 @@
+declare const EXPERIMENTAL_TILE_PRELOADING_VERSION = "0.1.0";
+export { EXPERIMENTAL_TILE_PRELOADING_VERSION };

package/dist/utils/index.d.ts

@@ -1 +1,2 @@
 export * from './dom';
+export { lerp } from './math-utils';

package/dist/utils/math-utils.d.ts

@@ -4,5 +4,14 @@ declare function normalize(value: number, min: number, max: number): number;
 declare function diagonalOfSquare(side: number): number;
 type Lerpable = [number, number, number, number] | Vec4;
 declare function lerpVec4(a: Lerpable, b: Lerpable, t: number): Vec4;
-declare function lerp(a: number, b: number, t: number): number;
+/**
+ * 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
+ */
+declare function lerp(a: number, b: number, alpha: number): number;
 export { minMax, normalize, diagonalOfSquare, lerpVec4, lerp };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maptiler/sdk",
-  "version": "4.0.3-rc.1",
+  "version": "4.1.0-rc.1",
   "description": "The Javascript & TypeScript map SDK tailored for MapTiler Cloud",
   "author": "MapTiler",
   "module": "dist/maptiler-sdk.mjs",
@@ -73,7 +73,7 @@
     "@canvas/image-data": "^1.0.0",
     "@eslint/js": "^9.21.0",
     "@maptiler/3d": "^3.1.0",
-    "@playwright/test": "^1.51.0",
+    "@playwright/test": "^1.60.0",
     "@types/color-convert": "^2.0.4",
     "@types/color-name": "^2.0.0",
     "@types/node": "^25.0.0",
@@ -106,7 +106,7 @@
     "events": "^3.3.0",
     "gl-matrix": "^3.4.4",
     "js-base64": "^3.7.7",
-    "maplibre-gl": "~5.21.1",
+    "maplibre-gl": "5.24",
     "uuid": "^14.0.0"
   }
 }