@xweather/mapsgl 1.9.0 → 1.9.1

package/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2023, AerisWeather
+Copyright (c) 2026, AerisWeather
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

package/dist/mapsgl.css

@@ -1,6 +1,6 @@
 /*!
  * 
- * 	@xweather/mapsgl - 1.9.0
+ * 	@xweather/mapsgl - 1.9.1
  * 	(c) 2026 Vaisala Xweather
  * 	License: BSD
  * 	https://www.xweather.com

package/dist/mapsgl.d.ts

@@ -2032,6 +2032,7 @@ declare abstract class DataSource<Spec extends SourceSpecification = SourceSpeci
      * The map layers that are currently using this data source.
      */
     consumingLayers: Array<DataSourceConsumer>;
+    private _consumingLayerIds;
     /**
      * The type of data source and data it manages.
      * @readonly
@@ -2142,6 +2143,12 @@ export declare class DownloadManager<Task extends DownloadTask<any>> extends Eve
      * @returns The cached task data, or undefined if not found.
      */
     get(key: string): TaskData<Task> | undefined;
+    /**
+     * Retrieves an active (pending or in-flight) task by key.
+     * @param key - The unique identifier for the task.
+     * @returns The active task if present, otherwise undefined.
+     */
+    getTask(key: string): Task | undefined;
     /**
      * Sets the task runner function used to execute download tasks.
      * @param runner - The task runner function that handles task execution with retry logic.
@@ -2436,6 +2443,12 @@ export declare interface EncodedSourceSpecification<Dataset extends EncodedRaste
      * to snowfall). The original `datasets` are still used for tile requests.
      */
     effectiveDatasets?: Array<Partial<Dataset>>;
+    /**
+     * ID of a registered tile data transformer to run in the worker thread after tile data is loaded.
+     * Preferred over `transformTileData` because it avoids serializing a function across threads.
+     * @see TransformerId
+     */
+    transformerId?: string;
     /**
      * Optional function to transform tile data after it has been loaded. This allows for custom processing or
      * modification of the tile data before it is used for rendering, such as converting it to other values
@@ -2444,6 +2457,7 @@ export declare interface EncodedSourceSpecification<Dataset extends EncodedRaste
      * @param datasets - An array of dataset objects associated with this source, which contains information about the
      * original encoded data and its value ranges. This array can be modified in-place to update dataMin/dataMax
      * values for transformed data.
+     * @deprecated Use `transformerId` instead to reference a registered transformer by ID.
      */
     transformTileData?: (data: RGBAImage, datasets: Array<Dataset>) => void;
 }
@@ -2570,6 +2584,7 @@ declare const ExpressionOperator: {
     readonly any: "any";
     readonly toNumber: "to-number";
     readonly toString: "to-string";
+    readonly toDate: "to-date";
     readonly toLocaleString: "to-locale-string";
     readonly toUnit: "to-unit";
     readonly toBoolean: "to-boolean";
@@ -2617,6 +2632,15 @@ declare const ExpressionOperator: {
     readonly case: "case";
     readonly match: "match";
     readonly let: "let";
+    /**
+     * Active map timeline position as **Unix seconds** (from the map controller), not wall clock — use `now` for that.
+     */
+    readonly mapTime: "map-time";
+    /**
+     * @deprecated Prefer `map-time` — same semantics.
+     */
+    readonly time: "time";
+    readonly now: "now";
 };
 
 export declare type ExpressionOperator = ObjectValue<typeof ExpressionOperator>;
@@ -3527,6 +3551,12 @@ export declare interface LayerSpecification {
      * zoom level than the current map zoom level.
      */
     zoomOffset?: number;
+    /**
+     * Whether to preload low-quality tiles when the layer is added or the time range changes,
+     * ensuring fallback data is available immediately when panning or zooming beyond currently
+     * loaded tile bounds. Default is `false`.
+     */
+    preloadLowQuality?: boolean;
     /**
      * Render style configuration.
      * @see PaintStyleSpec
@@ -3968,6 +3998,8 @@ dispose(all?: boolean): void;
 export declare class MapCamera {
     private _transform;
     private _orientation;
+    private readonly _quat;
+    private readonly _vec3;
     get position(): Vector3;
     set position(value: Vector3);
     get orientation(): Quaternion;
@@ -3983,6 +4015,10 @@ export declare class MapCamera {
      * @returns The view matrix
      */
     worldToCameraMatrix(worldSize: number, pixelsPerMeter?: number): Matrix4;
+    /**
+     * Writes world->camera matrix into `out` to avoid per-frame allocations.
+     */
+    worldToCameraMatrixInto(out: Matrix4, worldSize: number, pixelsPerMeter?: number): Matrix4;
     calculateCameraOrientation(bearing: number, pitch: number): Quaternion;
 }
 
@@ -4324,7 +4360,27 @@ get needsViewportUpdate(): boolean;
      */
     setRefreshInterval(minutes: number, advanceToNow?: boolean): void;
     private _triggerPreloadAnimation;
+    private _preloadAnimationRequestId;
+    private _activePreloadAnimationPromise?;
+    private _hasPendingPreloadAnimationRequest;
+    /**
+     * Schedules animation preload work and returns the active drain promise.
+     * Calls are coalesced: if preload is already running, this only marks that another pass should run after the
+     * current one completes.
+     */
     preloadAnimationData(): Promise<void>;
+    /**
+     * Processes queued preload requests until no further requests are pending.
+     * If a newer request arrives during a preload pass, marks animators dirty so the next pass recomputes against
+     * the newest viewport and timeline state.
+     */
+    private _drainPreloadAnimationQueue;
+    /**
+     * Invalidates in-flight preload work.
+     * This does not abort the current async operation directly; it marks the current pass stale and forces the next
+     * queued pass to refresh from latest state.
+     */
+    private cancelPreloadAnimationData;
     private debouncedPreloadAnimationData;
     private setNeedsPreloadAnimationData;
     private preloadAnimationDataIfNeeded;
@@ -5422,6 +5478,7 @@ export declare interface RenderFrameContextTileLayer {
     getDataZoom(): number;
     getVisibleTileCoords(zoom: number): TileCoord[];
     getCurrentInterval?(): TimeInterval | undefined;
+    allowExpiredTilesForRender?: boolean;
 }
 
 declare const resolveMeasurementForUnits: (type: ConversionMeasurement) => Measurement;
@@ -5574,6 +5631,7 @@ export declare class SourceMetadata extends EventDispatcher {
     private _transformer;
     private _hasLoaded;
     private _lastRequestOptions;
+    private _validTimesCache;
     
     /**
      * Creates an instance of SourceMetadata
@@ -5669,6 +5727,7 @@ export declare class SourceMetadata extends EventDispatcher {
      * @returns A promise that resolves with the metadata for the source.
      */
     load(options?: Partial<UrlRequestOptions>): Promise<Partial<SourceMetadataSchema>>;
+    cancel(): void;
     protected processMetadata(json: Record<string, any>): Partial<SourceMetadataSchema>;
 }
 
@@ -6527,6 +6586,7 @@ declare abstract class TileLayer<Data> extends WebGLLayer<TileSource> {
     private upgradeDataQuality;
     private lastHiddenTime;
     private tileLoadProgress;
+    private _preloadLowQuality;
     /**
      * Returns the layer's data render quality.
      * @see DataQuality
@@ -6542,7 +6602,12 @@ declare abstract class TileLayer<Data> extends WebGLLayer<TileSource> {
      * @param id - Unique identifier of the layer.
      * @param config - Config options for the layer.
      */
-    constructor(id: string, { quality, ...config }: Partial<TileLayerConfig>);
+    constructor(id: string, { quality, preloadLowQuality, ...config }: Partial<TileLayerConfig>);
+    /**
+     * Returns whether expired tiles can still be used for rendering/LOD fallback.
+     * Default is disabled so stale tiles are not rendered after data refreshes.
+     */
+    shouldRenderExpiredTiles(): boolean;
     refresh(clear?: boolean): void;
     /**
      * Returns the layer's tile cache so renderers can use it via RenderFrameContext instead of accessing layer.source.tiles.
@@ -6558,11 +6623,21 @@ declare abstract class TileLayer<Data> extends WebGLLayer<TileSource> {
     /**
      * Returns the data zoom level used for the specified map zoom level based on the configured `quality` level.
      * @param zoom - Map zoom level to get the data zoom level for.
-     * @param reduceDataQuality - Whether to reduce the data quality by 1 level.
-     * @returns Data zoom level.
+     * @param scale - Scale to apply to the data quality.
+     * @remarks
+     * The scale parameter is used to reduce the data quality by a factor of the specified scale. For example, if the
+     * scale is 0.5, the data quality will be reduced by half. If the scale is 0.25, the data quality will be reduced
+     * by one-quarter.
+     * @returns Data zoom level, optionally adjusted by the data quality scale and clamped to the source's min/max zoom
+     * levels.
      */
-    getDataZoom(zoom?: number, reduceDataQuality?: boolean): number;
-    preloadWorldTile(): void;
+    getDataZoom(zoom?: number, scale?: number): number;
+    /**
+     * Preloads low-quality tiles for the layer at the specified zoom level. This is used to ensure we can render data
+     * anywhere quickly when zooming in our out beyond partial bounds for tiles not yet loaded.
+     * @param zoom : Zoom level to preload low-quality tiles for.
+     */
+    preloadLowQualityTiles(zoom?: number): void;
     /**
      * Returns the tile at the specified geographic coordinate.
      * @param coord - Geographic coordinate to get the tile for.
@@ -6578,6 +6653,7 @@ declare abstract class TileLayer<Data> extends WebGLLayer<TileSource> {
      * @returns Array of visible tile coordinates.
      */
     getVisibleTileCoords(): Array<TileCoord>;
+    private _alreadyPreloadedLowQualityTiles;
     /**
      * Requests visible tiles from the tile pyramid.
      * @param reload - Whether to reload tiles that have already been requested.
@@ -6597,6 +6673,8 @@ declare abstract class TileLayer<Data> extends WebGLLayer<TileSource> {
     private onLoadProgress;
     private onLoadStart;
     private onLoadComplete;
+    private _shouldRequestTiles;
+    onTimelineRangeChange(e: any): void;
     protected onTimeSeriesDataChange(): void;
     protected onMaskLayerChange(): void;
     protected onMaskStateChange(): void;
@@ -6619,8 +6697,20 @@ export declare interface TileLayerConfig extends WebGLLayerConfig {
      * at a different zoom level than the map's zoom level.
      */
     zoomOffset: number;
+    /**
+     * Whether to preload low-quality tiles when the layer is added or the time range changes,
+     * ensuring fallback data is available immediately when panning or zooming beyond currently
+     * loaded tile bounds. Default is `false`.
+     */
+    preloadLowQuality: boolean;
 }
 
+export declare type TilePositionData = {
+    translation: Vector3;
+    scale: Vector3;
+    matrix: Matrix4;
+};
+
 export declare type TileQuadrant = 'tl' | 'tc' | 'tr' | 'ml' | 'mc' | 'mr' | 'bl' | 'bc' | 'br';
 
 /**
@@ -6705,6 +6795,9 @@ declare abstract class TileSource<Data = any, Source extends TileSourceSpecifica
      * deduplication vs. load-generation guard.
      */
     private _tileLoadRequestId;
+    private _metadataLoadPromise?;
+    private _pendingTaskCountByCoord;
+    private _pendingIntervalsByCoord;
     /**
      * The minimum zoom level for the source.  Defaults to `0`.
      */
@@ -6819,7 +6912,8 @@ constructor(id: string, spec: Partial<Source>);
         headers: Headers | null;
     }>;
     getMetadata(options?: Partial<UrlRequestOptions>): Promise<unknown>;
-    removeConsumer(consumer: DataSourceConsumer): void;
+
+removeConsumer(consumer: DataSourceConsumer): void;
     /**
      * Aborts a tile request.
      * @param tile - The tile to abort.
@@ -7724,6 +7818,12 @@ export declare type WeatherLayerOptions = {
          * value is `true`.
          */
         cities: boolean;
+        /**
+         * Whether to preload low-quality tiles when the layer is added or the time range changes,
+         * ensuring fallback data is available immediately when panning or zooming beyond currently
+         * loaded tile bounds. Default is `false`.
+         */
+        preloadLowQuality: boolean;
     }>;
     /**
      * Options for configuring the layer's timing behavior, for time-based data only.
@@ -7742,13 +7842,10 @@ export declare type WeatherLayerOptions = {
      */
     legend: Partial<LegendOptions> | false;
     /**
-     * Time range information about the map's current timeline.
+     * The map's live timeline animation instance, used by source generators for both time range
+     * parameters and per-feature animation controllers.
      */
-    timeline: {
-        from: Date;
-        to: Date;
-        current: Date;
-    };
+    timeline: TimeAnimation;
     /**
      * Options for configuring a mask to apply to the layer.
      */
@@ -7839,6 +7936,8 @@ declare abstract class WebGLLayer<Source extends DataSource = DataSource> extend
      * Whether to invert the mask layer's output.
      */
     invertMaskLayer: boolean;
+    
+    private _renderFrameContext;
 
 /**
      * Returns the render paint style configuration for this layer.
@@ -7860,6 +7959,21 @@ get mask(): LayerMask;
      * @readonly
      */
     get visible(): boolean;
+    /**
+     * Registers another layer as depending on this layer (for example it reads this layer via `queryFeatures`
+     * while this layer may be hidden). When the registry is non-empty, time-series data providers may load tiles even
+     * if this layer is not visible.
+     */
+    registerDependentLayer(layer: WebGLLayer): void;
+    /**
+     * Removes a layer from this layer's dependent registry.
+     */
+    unregisterDependentLayer(layer: WebGLLayer): void;
+    /**
+     * Whether any layer has registered as a dependent via
+     * {@link WebGLLayer.registerDependentLayer}.
+     */
+    hasDependentLayers(): boolean;
     /**
      * Returns whether this layer is enabled or not.
      */