@xweather/mapsgl 1.8.5 → 1.9.1-beta.1

package/dist/mapsgl.d.ts

@@ -546,6 +546,8 @@ declare const enum ShaderType {
     FRAGMENT = "fragment"
 }
 
+export declare const sharedFPSMeter: FPSMeter;
+
 export declare type Size = {
     width: number;
     height: number;
@@ -1064,7 +1066,7 @@ export declare class Animation extends EventDispatcher {
     /**
      * Stops the animation and resets it to its original starting position.
      */
-    stop(): void;
+    stop(advanceToStopPosition?: boolean): void;
     /**
      * Restarts the animation from the beginning if it is currently playing.
      */
@@ -1207,6 +1209,8 @@ export declare type AnimationState = ObjectValue<typeof AnimationState>;
 export declare type AnyAuthenticator = Authenticator<any>;
 
 export declare type AnyMapController = MapController<any>;
+
+export declare type AnyTileCache = TileCache<any>;
 
 /**
  * An enumerated value representing an API endpoint action.
@@ -1851,6 +1855,10 @@ export declare interface ColorScaleOptions {
      */
     masks?: Array<ColorMaskOptions>;
 }
+
+export declare class ConstantStyleValue<T> extends StyleValue_2<T> {
+    constructor(value: T | any[] | StyleEvaulatorFunction<T>);
+}
 
 /**
  * Contour style properties control how contoured data gets rendered on a map. Contour layers are rendered by sampling
@@ -1867,7 +1875,13 @@ export declare interface ContourStyleSpec {
      * major contour lines will not be rendered. This value must be in the same units as the data source.
      */
     majorInterval: StyleValue<number>;
+    /**
+     * The width of the contour lines in pixels.
+     */
     width: StyleValue<number>;
+    /**
+     * The width of the major contour lines in pixels.
+     */
     majorWidth: StyleValue<number>;
     scale: StyleValue<number>;
     offset: StyleValue<number>;
@@ -1881,7 +1895,9 @@ export declare interface ControlStore {
     dataInspector: DataInspectorControl;
 }
 
-declare const convert: (type: string, value: number, from: string, to: string) => number;
+export declare type ConversionMeasurement = Measurement | 'temperature-change';
+
+declare const convert: (type: ConversionMeasurement | string, value: number, from: string, to: string) => number;
 
 export declare type Coordinate = {
     lat: number;
@@ -1904,6 +1920,9 @@ declare const CtoF: (c: number) => number;
 
 declare const CtoFUnit: (c: number) => number;
 
+export declare class DataDrivenStyleValue<T> extends StyleValue_2<T> {
+}
+
 export declare interface DataEvaluator {
     title: string | ((data: FeatureQueryResult) => string);
     alwaysShow?: boolean;
@@ -1947,6 +1966,7 @@ export declare class DataInspectorControl {
 export declare interface DataInspectorControlOptions {
     event: 'click' | 'move';
     stream: boolean;
+    showCoordinates: boolean;
     tooltip: any;
 }
 
@@ -2012,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
@@ -2092,6 +2113,7 @@ export declare interface Disposable {
  * @template Task - The download task type that extends DownloadTask
  */
 export declare class DownloadManager<Task extends DownloadTask<any>> extends EventDispatcher {
+    id: string;
 
 /**
      * Gets the progress tracker for download operations.
@@ -2108,7 +2130,7 @@ export declare class DownloadManager<Task extends DownloadTask<any>> extends Eve
      * @param options.defaultConcurrency - Default maximum concurrent downloads. Defaults to 16.
      * @param options.perHostConcurrency - Per-host concurrency limits, keyed by host name.
      */
-    constructor(options?: Partial<DownloadManagerOptions<TaskData<Task>>>);
+    constructor(options?: Partial<DownloadManagerOptions<Task>>);
     /**
      * Checks if a task result exists in the cache.
      * @param key - The unique identifier for the task.
@@ -2121,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.
@@ -2438,11 +2466,16 @@ export declare class EncodedTileSource<Source extends EncodedSourceSpecification
     shouldUseTimesFromMetadata: boolean;
     maxTextureSize: number;
     private _worker;
+    private _aggregateProgress;
     
     get type(): string;
+    get operation(): TimeSeriesOperationType;
     constructor(id: string, spec: Partial<Source>);
-
-/**
+    
+    shouldRequestTile(tile: Tile<EncodedTileData>, reload?: boolean, intervals?: Array<Date>): boolean;
+    abortTileByCoord(coord: TileCoord): void;
+    
+    /**
      * Returns the metadata for the specified band, if available.
      * @param band - The band to get metadata for.
      * @returns
@@ -2456,6 +2489,7 @@ export declare class EncodedTileSource<Source extends EncodedSourceSpecification
      */
     getDataRange(band: SampleChannel): ValueRange;
 
+protected onLoadProgress(e: any): void;
 }
 
 /**
@@ -2466,24 +2500,17 @@ export declare class EncodedTileSource<Source extends EncodedSourceSpecification
  */
 declare const equalUnits: (units1: MapUnits, units2: MapUnits) => boolean;
 
-export declare type ExpressionInputType = string | number | boolean | ExpressionLookupType;
-
-export declare type ExpressionLookupType = [
-'get',
-string,
-...(ExpressionLookupType)[]
-] | [
-'has',
-string,
-...(ExpressionLookupType)[]
-] | [
-'at',
-number,
-Array<any>
-] | [
-'length',
-string | number | Array<any>
-];
+/**
+ * Mapbox-style expression: operator name followed by arguments.
+ * Arguments may be literals or nested expressions (recursive).
+ */
+export declare type Expression = [ExpressionOperator, ...ExpressionValue[]];
+
+/**
+ * Mapbox-style expression array, e.g. ['get', 'opacity'] or ['*', ['get', 'x'], 2].
+ * Allowed in style config; converted to DataDrivenStyleValue in the PaintStyle constructor.
+ */
+export declare type ExpressionArray = any[];
 
 /**
  * Defines a custom expression operation to calculate the result of a custom expression function. The custom expression
@@ -2527,44 +2554,83 @@ export declare interface ExpressionOperation {
     chunk: string;
 }
 
-export declare type ExpressionSpecification = [
-'!',
-ExpressionInputType
-] | [
-'==',
-ExpressionInputType,
-ExpressionInputType
-] | [
-'!=',
-ExpressionInputType,
-ExpressionInputType
-] | [
-'>',
-ExpressionInputType,
-ExpressionInputType
-] | [
-'>=',
-ExpressionInputType,
-ExpressionInputType
-] | [
-'<',
-ExpressionInputType,
-ExpressionInputType
-] | [
-'<=',
-ExpressionInputType,
-ExpressionInputType
-] | [
-'in',
-ExpressionInputType,
-...(ExpressionInputType | ExpressionInputType[])[]
-] | [
-'all',
-...(boolean | ExpressionSpecification)[]
-] | [
-'any',
-...(boolean | ExpressionSpecification)[]
-];
+/**
+ * Supported expression operator names (first element of an expression array).
+ * @see evaluateExpression
+ */
+declare const ExpressionOperator: {
+    readonly literal: "literal";
+    readonly get: "get";
+    readonly has: "has";
+    readonly var: "var";
+    readonly properties: "properties";
+    readonly zoom: "zoom";
+    readonly coalesce: "coalesce";
+    readonly eq: "==";
+    readonly neq: "!=";
+    readonly lt: "<";
+    readonly lte: "<=";
+    readonly gt: ">";
+    readonly gte: ">=";
+    readonly not: "!";
+    readonly all: "all";
+    readonly any: "any";
+    readonly toNumber: "to-number";
+    readonly toString: "to-string";
+    readonly toLocaleString: "to-locale-string";
+    readonly toUnit: "to-unit";
+    readonly toBoolean: "to-boolean";
+    readonly typeOf: "typeof";
+    readonly number: "number";
+    readonly string: "string";
+    readonly boolean: "boolean";
+    readonly object: "object";
+    readonly add: "+";
+    readonly subtract: "-";
+    readonly mod: "%";
+    readonly pow: "^";
+    readonly multiply: "*";
+    readonly divide: "/";
+    readonly abs: "abs";
+    readonly ceil: "ceil";
+    readonly floor: "floor";
+    readonly round: "round";
+    readonly min: "min";
+    readonly max: "max";
+    readonly sqrt: "sqrt";
+    readonly ln: "ln";
+    readonly ln2: "ln2";
+    readonly log2: "log2";
+    readonly log10: "log10";
+    readonly sin: "sin";
+    readonly cos: "cos";
+    readonly tan: "tan";
+    readonly asin: "asin";
+    readonly acos: "acos";
+    readonly atan: "atan";
+    readonly e: "e";
+    readonly pi: "pi";
+    readonly at: "at";
+    readonly in: "in";
+    readonly regex: "regex";
+    readonly indexOf: "index-of";
+    readonly length: "length";
+    readonly slice: "slice";
+    readonly concat: "concat";
+    readonly downcase: "downcase";
+    readonly upcase: "upcase";
+    readonly step: "step";
+    readonly interpolate: "interpolate";
+    readonly case: "case";
+    readonly match: "match";
+    readonly let: "let";
+    readonly time: "time";
+};
+
+export declare type ExpressionOperator = ObjectValue<typeof ExpressionOperator>;
+
+/** Value that can appear as an expression or as an argument (literal or nested expression). */
+export declare type ExpressionValue = string | number | boolean | null | object | Expression;
 
 export declare type FeatureQueryResult = {
     value: number;
@@ -2592,7 +2658,7 @@ export declare interface FillStyleSpec {
     /**
      * Color of the fill.
      */
-    color: StyleValue<string | Color | StyleExpression>;
+    color: StyleValue<string | Color>;
     /**
      * The image to use for the fill pattern. Can be an image identifier string or a {@link RemoteSymbolImage}.
      * @remarks
@@ -2613,6 +2679,14 @@ export declare interface FillStyleSpec {
      */
     sort: string | SortProperty;
 }
+
+/**
+ * Mapbox-style filter expression array. Evaluates to boolean (feature included when truthy).
+ * Use with StyleExpression for evaluation. Supports decision expressions (==, !=, <, <=, >, >=,
+ * all, any, !, in, regex, case, match, etc.) and property lookups (get, has).
+ * @see StyleExpression
+ */
+export declare type FilterExpression = ExpressionValue;
 
 declare const FtoC: (f: number) => number;
 
@@ -2769,8 +2843,14 @@ export declare type GeoJsonProperties = {
 
 /**
  * A subclass of {@link VectorTileSource} that is used to represent GeoJSON data.
+ *
+ * This source tracks a single in-flight data update (`pendingDataUpdate`) to make update
+ * lifecycle events deterministic when remote loads and `setData()` calls overlap. The revision-
+ * based update state prevents duplicate or out-of-order `DATA_UPDATE_*` events, avoids stale
+ * async completions mutating newer state, and reduces no-op update churn during rapid updates.
  */
 export declare class GeoJSONSource extends VectorTileSource {
+    private static readonly DATA_UPDATE_ERROR_MESSAGE;
     /**
      * Whether the GeoJSON data is dynamic, meaning it will be updated frequently. Default is `false`.
      */
@@ -2787,9 +2867,15 @@ export declare class GeoJSONSource extends VectorTileSource {
      * The GeoJSON data associated with the source, either provided statically or from a remote source.
      */
     get data(): GeoJSONFeatureCollection;
-    private pendingLoad;
     private needsUpdate;
+    /**
+     * The revision number of the data.
+     */
     private dataRevision;
+    /**
+     * The pending data update being processed.
+     */
+    private pendingDataUpdate;
     constructor(id: string, spec: Partial<GeoJSONSourceSpecification>);
     /**
      * Sets the URL of the GeoJSON data.
@@ -2811,6 +2897,10 @@ export declare class GeoJSONSource extends VectorTileSource {
     reload(): void;
     private updateWorkerData;
     private processWorkerUpdate;
+    private beginDataUpdate;
+    private flushQueuedDataUpdate;
+    private completeDataUpdate;
+    private failDataUpdate;
 }
 
 /**
@@ -2850,7 +2940,7 @@ export declare type GeoJSONTypes = GeoJSON['type'];
  * @param system - The system to get the default unit for.
  * @returns The default unit for the given measurement and system.
  */
-declare const getDefaultUnit: (type: Measurement, system: UnitSystem) => string;
+declare const getDefaultUnit: (type: ConversionMeasurement, system: UnitSystem) => string;
 
 /**
  * Returns the default units for the given system.
@@ -2868,6 +2958,8 @@ declare const getMeasurementType: (str: string) => Measurement | undefined;
  * @returns The system for the given units.
  */
 declare const getSystemForUnits: (units: MapUnits) => UnitSystem;
+
+declare const getUnitPrecision: (unit: string) => number;
 
 export declare type GoogleMap = google.maps.Map;
 
@@ -2927,7 +3019,7 @@ export declare interface HeatmapStyleSpec {
      * Defines the normalized (`0` to `1`) color scale used to color pixels based on its density value, where `0`
      * is none and `1` being the highest density.
      */
-    color: Array<number | string>;
+    color: StyleValue<Array<number | string>>;
     /**
      * Radius of influence of each data point in screen points.
      */
@@ -3262,7 +3354,7 @@ export declare type LayerMetadata = {
     sourceLayerId: string;
     sourceLayerType: string;
     type: string;
-    filter: ExpressionSpecification;
+    filter: FilterExpression;
     paint: PaintStyle;
     options?: Record<string, unknown>;
 };
@@ -3343,13 +3435,15 @@ export declare interface LayerRenderer {
      * Called before the primary render method to perform any setup or rendering that needs to be done before
      * rendering, such as rendering to a framebuffer or updating compute passes.
      * @param elapsedTime - The render loop's elapsed time.
+     * @param frameContext - Map and layer state for this frame; the renderer must use this instead of reading from the layer or map.
      */
-    prerender(elapsedTime: number): void;
+    prerender(elapsedTime: number, frameContext: RenderFrameContext): void;
     /**
      * Render the layer's data.
      * @param elapsedTime - The render loop's elapsed time.
+     * @param frameContext - Map and layer state for this frame; the renderer must use this instead of reading from the layer or map.
      */
-    draw(elapsedTime: number): void;
+    draw(elapsedTime: number, frameContext: RenderFrameContext): void;
     /**
      * Performs any necessary set up to prepare the renderer for offscreen rendering, such as setting up a framebuffer.
      */
@@ -3410,15 +3504,21 @@ export declare interface LayerSpecification {
      */
     mask?: LayerMaskSpecification;
     /**
-     * Filter expression to use for filtering features from the data source. This is only used for vector tile data
-     * sources whose tiles are in the Mapbox Vector Tile (MVT) format.
-     * @see ExpressionSpecification
+     * Filter expression for vector tile layers. Evaluated with StyleExpression.
+     * @see FilterExpression
      */
-    filter?: ExpressionSpecification;
+    filter?: FilterExpression;
     /**
      * Time series configuration for the layer when time-based.
      */
     timeSeries?: Partial<LayerTiming>;
+    /**
+     * Optional measurement metadata associated with this layer's values.
+     */
+    measurement?: {
+        type: ConversionMeasurement;
+        units: string;
+    };
     /**
      * Data resolution to use, which controls which data zoom level is requested for a specific map zoom level.
      * @remarks
@@ -3876,6 +3976,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;
@@ -3891,6 +3993,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;
 }
 
@@ -4232,7 +4338,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;
@@ -4737,6 +4863,10 @@ declare const Operator: {
 
 export declare type Operator = ObjectValue<typeof Operator>;
 
+export declare interface Opts {
+    capacity: number;
+}
+
 /**
  * The mode for handling symbol overlap.
  */
@@ -4826,7 +4956,7 @@ export declare class PaintStyle {
     iconAnimated(data?: StylableData): boolean;
     iconFactor(data?: StylableData): number;
     iconAtlas(data?: StylableData): SymbolIconAtlas;
-    textValue(data?: StylableData, line?: number): string | PropertyValue;
+    textValue(data?: StylableData, line?: number): string;
     textTransform(data?: StylableData, line?: number): string;
     textFont(data?: StylableData, line?: number): string;
     textSize(data?: StylableData, line?: number): number;
@@ -5097,32 +5227,6 @@ declare const ProjectionType: {
 
 export declare type ProjectionType = ObjectValue<typeof ProjectionType>;
 
-/**
- * Defines a property value that is based on a property name or an array of property names from a JSON object. The
- * property value can also be transformed using a custom function to format the value before rendering.
- */
-export declare interface PropertyValue {
-    /**
-     * Property key path or an array of property key paths from a JSON object. If an array is provided, then the first
-     * property that is not undefined will be used.
-     */
-    property: string | Array<string>;
-    /**
-     * Optional measurement type the value represents. This is used to select the proper units to convert the value to
-     * before rendering. If not provided, then the value will be rendered as is.
-     */
-    measurement?: {
-        type: string;
-        units: string;
-    };
-    /**
-     * Custom function to transform the property value before rendering. This is useful for formatting the value before
-     * rendering, such as converting units, rounding, or applying other transformations.
-     * @param value - The property value to transform.
-     */
-    transform?: (value: string | number, units?: string) => string | number;
-}
-
 /**
  * A `Query` object is a convenience wrapper for setting up and configuring a query string used
  * for API queries.
@@ -5270,7 +5374,92 @@ export declare interface RemoteSymbolImage {
     /** Indicates if the image is a pattern image. */
     pattern?: boolean;
 }
+
+/**
+ * Context built by the layer each frame and passed to prerender() and draw().
+ * Contains all map and layer state needed for the render path so the renderer
+ * does not access the parent layer or the layer's map.
+ */
+export declare interface RenderFrameContext {
+    /** Elapsed time since the start of the render loop. Used by the renderer to animate the layer. */
+    elapsedTime: number;
+    /** Latest calculated FPS of the context. */
+    fps: number;
+    /** Map state snapshot. */
+    map: RenderFrameContextMap;
+    /** Layer id. */
+    layerId: string;
+    /** Scene to render into. */
+    scene: MapScene;
+    /** Whether this layer is used as a mask (stencil). */
+    isLayerMask: boolean;
+    /** Layer mask config if any. */
+    mask?: LayerMask;
+    /** Whether the layer is visible. */
+    visible: boolean;
+    /** Request a redraw on the next frame. */
+    setNeedsUpdate(): void;
+    /** Tile-layer-specific state; set when the layer is a tile layer. */
+    tileLayer?: RenderFrameContextTileLayer;
+    /** Tile cache from the layer's source; set when the layer has a tile source. Used by renderers instead of accessing layer.source.tiles. */
+    tileCache?: AnyTileCache;
+    /** Tile dimensions from the layer's source; set when the layer has a tile source. Used for texture array setup. */
+    tileSize?: {
+        width: number;
+        height: number;
+    };
+    /** Layer paint style (from layer.paint). Set by the layer when building context. */
+    paint?: PaintStyle;
+    /** Map style (map.style). Used by vector/grid passes for fonts, image atlas, etc. */
+    mapStyle?: MapStyle;
+}
+
+/**
+ * Snapshot of map transform state passed into the render path so the renderer
+ * does not read from the map or layer during prerender/draw.
+ */
+export declare interface RenderFrameContextMap {
+    center: Coordinate;
+    zoom: number;
+    bounds: CoordinateBounds;
+    bearing: number;
+    pitch: number;
+    tileSize: number;
+    projection: {
+        type: ProjectionType;
+        subdivisionGranularity: SubdivisionGranularitySetting;
+    };
+    transform: MapTransform;
+    placement: SymbolPlacement;
+    globiness: number;
+    isGlobe: boolean;
+    camera: {
+        position: Vector3;
+    };
+    clippingPlane: Vector4;
+    globeMatrix: Matrix4;
+    mercatorMatrix: Matrix4;
+    projGlobeMatrix: Matrix4;
+    zoomTransition: number;
+    cutoffParams: [number, number, number, number];
+    farZ: number;
+    pixelsPerMercatorPixelRatio: number;
+}
+
+/**
+ * Optional tile-layer-specific state for resolution and LOD. Present when the
+ * layer is a tile layer.
+ */
+export declare interface RenderFrameContextTileLayer {
+    viewport: Viewport;
+    pyramid: TilePyramid<any>;
+    getDataZoom(): number;
+    getVisibleTileCoords(zoom: number): TileCoord[];
+    getCurrentInterval?(): TimeInterval | undefined;
+}
 
+declare const resolveMeasurementForUnits: (type: ConversionMeasurement) => Measurement;
+
 /**
  * RGBAImage represents a 2D grid of image data. Them image data should NOT be premultipled since ImageData is not.
  * Therefore, UNPACK_PREMULTIPLY_ALPHA_WEBGL must be used when uploading the image data to the GPU via a texture.
@@ -5419,6 +5608,7 @@ export declare class SourceMetadata extends EventDispatcher {
     private _transformer;
     private _hasLoaded;
     private _lastRequestOptions;
+    private _validTimesCache;
     
     /**
      * Creates an instance of SourceMetadata
@@ -5463,10 +5653,10 @@ export declare class SourceMetadata extends EventDispatcher {
      */
     get hasLoaded(): boolean;
     /**
-     * Whether the metadata has valid time information.
+     * Whether the data source is a time-series data source.
      * @readonly
      */
-    get hasValidTimes(): boolean;
+    get isTimeSeries(): boolean;
     get validTimeRange(): TimeRange;
     getAllValidTimes(): Array<Date>;
     /**
@@ -5514,6 +5704,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>;
 }
 
@@ -5649,6 +5840,12 @@ export declare class State<T> extends EventDispatcher {
     };
 }
 
+/**
+ * Legacy style value: a static value or a function (data) => value.
+ * Supported for backwards compatibility.
+ */
+export declare type StaticOrFunctionStyleValue<T> = T | ((data: StylableData) => T);
+
 /**
  * Stroke style properties control how one or more polylines get rendered on a map. These properties also control
  * strokes around circles and other vector shapes.
@@ -5657,7 +5854,7 @@ export declare interface StrokeStyleSpec {
     /**
      * Color of the stroke.
      */
-    color: StyleValue<string | Color | StyleExpression>;
+    color: StyleValue<string | Color>;
     /**
      * Opacity of the stroke. Opacity can also be specified by including an alpha channel in the `color` value.
      */
@@ -5761,6 +5958,8 @@ export declare interface StyledImageRenderer {
     dispose?: () => void;
 }
 
+export declare type StyleEvaulatorFunction<T> = (properties: Record<string, any>) => T;
+
 export declare interface StyleExpression {
     property: string;
     type?: 'identity' | 'expression';
@@ -5810,10 +6009,35 @@ export declare const styles: {
 };
 
 /**
- * Defines a style value that can be either a static value or a function that returns a value based on the data for
- * data-driven styling.
+ * Style value accepted by paint specs. Can be:
+ * - A constant (number, string, boolean, object, etc.)
+ * - A function (data) => value
+ * - An expression array (Mapbox-style, e.g. ['get', 'opacity'])
+ * - A {@link ConstantStyleValue} or {@link DataDrivenStyleValue} instance (used as-is)
+ *
+ * Constants, functions, and expression arrays are converted to StyleValue instances in the PaintStyle constructor.
  */
-export declare type StyleValue<T> = T | ((data: StylableData) => T);
+export declare type StyleValue<T> = StaticOrFunctionStyleValue<T> | ExpressionArray | DataDrivenStyleValue<T> | ConstantStyleValue<T>;
+
+declare abstract class StyleValue_2<T> {
+    private constant;
+    private expression;
+    private fn;
+    constructor(value: T | any[] | StyleEvaulatorFunction<T>);
+    /**
+     * Returns whether this value is an expression.
+     */
+    isExpression(): boolean;
+    /**
+     * Resolves the final value based on input properties.
+     * If it's a constant, returns it directly.
+     */
+    resolve(properties?: Record<string, any>): T;
+    /**
+     * Returns the raw constant or expression for debugging or serialization.
+     */
+    getRaw(): T | any[] | StyleEvaulatorFunction<T> | null;
+}
 
 /**
  * Supported color bands.
@@ -6002,10 +6226,9 @@ export declare interface TaskRunnerConfig<Task extends DownloadTask<any>> {
  */
 export declare interface TextStyleSpec {
     /**
-     * Text to render. This can be a static string or a property value that is based on a property name or an array of
-     * property names from a JSON object.
+     * Text to render. This can be a static string or an expression that evaluates to a string.
      */
-    value: StyleValue<string | PropertyValue>;
+    value: StyleValue<string>;
     /**
      * The size of the text in pixels.
      */
@@ -6084,6 +6307,11 @@ export declare class Tile<Data> implements Disposable {
     private _span;
     private _bounds;
     private _state;
+    /**
+     * Monotonically increasing identifier for the most recent request that started loading this tile.
+     * Used by `TileSource` to guard against out-of-order async responses overwriting newer data.
+     */
+    requestId: number;
     private _data;
     /**
      * The tile coordinate of the tile as `x`, `y`, and `z`.
@@ -6166,6 +6394,13 @@ export declare class TileBounds {
     get center(): Point;
     get info(): Rect_2;
     constructor(left: number, right: number, top: number, bottom: number);
+    /**
+     * Expands the bounds by the specified offsets.
+     * @param xOffset - The offset to expand the bounds horizontally.
+     * @param yOffset - The offset to expand the bounds vertically.
+     * @returns The expanded bounds.
+     */
+    expand(xOffset: number, yOffset: number): TileBounds;
     /**
      * Returns whether the bounds equals the specified bounds.
      * @param bounds -
@@ -6312,6 +6547,122 @@ export declare interface TileInfo {
     z: number;
 }
 
+/**
+ * Represents a layer that renders data from a tile-based data source. This is the base class for all tile-based layers
+ * and is not intended to be used directly.
+ * @template Data Type of data stored in the layer's tiles.
+ */
+declare abstract class TileLayer<Data> extends WebGLLayer<TileSource> {
+    /**
+     * Tile pyramid used to calculating and requesting tiles for the layer from the data source.
+     */
+    readonly pyramid: TilePyramid<Data>;
+    readonly zoomOffset: number;
+    private tileBounds;
+    private dataQuality;
+    private upgradeDataQuality;
+    private lastHiddenTime;
+    private tileLoadProgress;
+    /**
+     * Returns the layer's data render quality.
+     * @see DataQuality
+     */
+    get quality(): DataQuality;
+    /**
+     * Sets the layer's data render quality.
+     * @see DataQuality
+     */
+    set quality(value: DataQuality);
+    /**
+     * Creates an instance of TileLayer.
+     * @param id - Unique identifier of the layer.
+     * @param config - Config options for the layer.
+     */
+    constructor(id: string, { quality, ...config }: Partial<TileLayerConfig>);
+    refresh(clear?: boolean): void;
+    /**
+     * Returns the layer's tile cache so renderers can use it via RenderFrameContext instead of accessing layer.source.tiles.
+     */
+    getTileCache(): AnyTileCache;
+    /**
+     * Returns the layer's tile dimensions for texture array setup.
+     */
+    getTileSize(): {
+        width: number;
+        height: number;
+    };
+    /**
+     * 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.
+     */
+    getDataZoom(zoom?: number, reduceDataQuality?: boolean): number;
+    preloadWorldTile(): void;
+    /**
+     * Returns the tile at the specified geographic coordinate.
+     * @param coord - Geographic coordinate to get the tile for.
+     * @param allowPartials - Whether to allow returning a tile that only partially contains the queried coordinate.
+     * @returns Tile and position within the tile for the specified coordinate.
+     */
+    protected getTile(coord: Coordinate, zoom?: number, allowPartials?: boolean): {
+        tile: Tile<Data>;
+        position: Point;
+    } | undefined;
+    /**
+     * Returns the visible tile coordinates based on the map's current viewport.
+     * @returns Array of visible tile coordinates.
+     */
+    getVisibleTileCoords(): Array<TileCoord>;
+    /**
+     * Requests visible tiles from the tile pyramid.
+     * @param reload - Whether to reload tiles that have already been requested.
+     * @returns Promise that resolves when the tiles have been requested.
+     */
+    private requestVisibleTiles;
+    protected requestTiles(coords: Array<TileCoord>, reload?: boolean): Promise<void>;
+    protected shouldReloadTile(coord: TileCoord): boolean;
+    onAdd(context: Context): void;
+    onMove(): void;
+    onVisible(): void;
+    onHidden(): void;
+    private onDataStale;
+    private onDataChange;
+    private onTileLoad;
+    private onTileError;
+    private onLoadProgress;
+    private onLoadStart;
+    private onLoadComplete;
+    protected onTimeSeriesDataChange(): void;
+    protected onMaskLayerChange(): void;
+    protected onMaskStateChange(): void;
+}
+
+/**
+ * Configuration options for a tile-based layer.
+ */
+export declare interface TileLayerConfig extends WebGLLayerConfig {
+    /**
+     * Quality to use when rendering data.
+     */
+    quality: DataQuality;
+    /**
+     * Range of values to use when rendering data.
+     */
+    dataRange: ValueRange;
+    /**
+     * Offset to apply to the map's zoom level when requesting data from the data source. This is useful to render data
+     * at a different zoom level than the map's zoom level.
+     */
+    zoomOffset: number;
+}
+
+export declare type TilePositionData = {
+    translation: Vector3;
+    scale: Vector3;
+    matrix: Matrix4;
+};
+
 export declare type TileQuadrant = 'tl' | 'tc' | 'tr' | 'ml' | 'mc' | 'mr' | 'bl' | 'bc' | 'br';
 
 /**
@@ -6350,10 +6701,6 @@ export declare type TileRequestOptions = {
      * Whether to reload the tile if it has already been loaded.
      */
     reload: boolean;
-    /**
-     * Whether to check if the tile is already pending before loading.
-     */
-    checkPending: boolean;
     /**
      * The time intervals to load for the tile.
      */
@@ -6364,10 +6711,45 @@ export declare type TileRequestOptions = {
  * `TileSource` is an abstract class that provides the primary implementation of a tile-based data source object that
  * loads tiles from a remote source. This class is not intended to be used directly, but rather extended by a concrete
  * implementation of a tile-based data source.
+ *
+ * @remarks
+ * **Tile loading: two complementary mechanisms**
+ *
+ * Network fetches are orchestrated by {@link TileSource.downloadManager} (`DownloadManager`). `requestTile` may run
+ * decode/parse work after bytes arrive. Understanding these two behaviors avoids duplicate work and stale tiles:
+ *
+ * 1. **Download deduplication** — For a given `TileDownloadTask` key (tile coordinate plus optional interval key from
+ *    {@link makeTileKey} / {@link makeTileArrayKey}), the manager ensures at most one in-flight or pending fetch. If
+ *    `requestTile` is called again while that task is still pending or in-flight, callers await the **same** promise
+ *    instead of starting a second HTTP request. This reduces redundant bandwidth and coordinates multiple callers
+ *    (e.g. layers or rapid map updates) that share the exact same request identity.
+ *
+ * 2. **Load generation guard (`tile.requestId` / `task.loadRequestId`)** — Deduping only merges identical
+ *    **keys**. It does **not** decide which result is "current" when the logical request for a tile slot changes:
+ *    different URL parameters (time, style, reload), a new fetch after a previous task finished, or a slow
+ *    {@link parseTile} finishing after a newer `requestTile` has already started. For non-interval loads, each **new**
+ *    enqueued download task gets a monotonically increasing id; callers that shared that task share the same id.
+ *    After `parseTile` resolves, the result is applied only if that id still matches `tile.requestId` (see
+ *    `requestTile` and `loadTile`). Stale completions are dropped so an older response cannot overwrite newer data for
+ *    the same tile instance.
+ *
+ * **Interval-based loads** (time-series tiles with multiple intervals on one tile) intentionally skip this per-tile
+ * id guard so a single tile can accumulate multiple interval results; ordering for those paths is handled elsewhere
+ * in the data model.
+ *
  * @template Data The type of data stored in a tile.
  * @template Source The type of the source specification.
  */
 declare abstract class TileSource<Data = any, Source extends TileSourceSpecification = TileSourceSpecification> extends DataSource<Source> {
+    /**
+     * Monotonic counter used when assigning {@link TileDownloadTask.loadRequestId} for non-interval loads. Each new
+     * enqueued download task gets the next id; waiters sharing the same task reuse that id. See class-level docs on
+     * deduplication vs. load-generation guard.
+     */
+    private _tileLoadRequestId;
+    private _metadataLoadPromise?;
+    private _pendingTaskCountByCoord;
+    private _pendingIntervalsByCoord;
     /**
      * The minimum zoom level for the source.  Defaults to `0`.
      */
@@ -6431,35 +6813,39 @@ constructor(id: string, spec: Partial<Source>);
      * @returns The URL for the tile.
      */
     getTileUrl(coord: TileCoord, params?: Record<string, any>): string;
-    /**
-     * Returns whether or not the source has a tile for the given tile coordinate.
-     * @param coord - The tile coordinate.
-     * @param layerId -
-     * @returns Whether or not the source has a tile for the given tile coordinate.
-     */
-    hasTile(coord: TileCoord, layerId?: string): boolean;
     /**
      * Checks if tile data exists for the given coordinate.
+     * For time-series sources, pass `intervals` to require data for those intervals; otherwise
+     * only the coord is checked and a single cached tile counts as "has data".
      * @param coord - The tile coordinate.
-     * @param layerId - Optional layer ID for per-layer data (unused but retained for API compatibility).
+     * @param layerId - Optional layer ID for per-layer data (unused but retained for API compatibility). If provided,
+     *   the tile data must have data for the given layer ID. This is only used for vector tile sources.
      * @param allowExpired - If true, allows expired tiles to be considered as having data.
-     * @returns Whether tile data exists (optionally including expired/stale).
+     * @param intervals - Optional time intervals (e.g. from request options). When provided, the tile must have
+     *   data for all of these intervals (used for time-series / multi-interval requests). The base implementation
+     *   only checks for data for the given intervals if the tile data is a time series data object.
+     * @returns Whether tile data exists (optionally including expired/stale and/or for the given intervals).
      */
-    hasTileData(coord: TileCoord, layerId?: string, allowExpired?: boolean): boolean;
+    hasTileData(coord: TileCoord, layerId?: string, allowExpired?: boolean, intervals?: Array<Date>): boolean;
     /**
-     * Returns the data for the given tile coordinate.
+     * Returns whether there is already a pending or in-flight request for the given coordinate
+     * (and optionally for the given intervals). Used to avoid duplicate requests when the
+     * same tile+intervals are requested multiple times.
      * @param coord - The tile coordinate.
-     * @returns The data for the given tile coordinate.
+     * @param intervals - Optional time intervals. When provided, only a task for the same coord and
+     *   these intervals is considered; when omitted, any task for this coord is considered.
+     * @returns True if a matching request is pending or in-flight.
      */
-    getTileData(coord: TileCoord): Data;
+    isPending(coord: TileCoord, intervals?: Array<Date>): boolean;
     getTileDataSize(data?: Data): Size;
     /**
-     * Returns whether or not the source should request a tile.
+     * Returns whether the source should request a tile.
      * @param tile - The tile to check.
-     * @param reload - Whether or not the tile should be reloaded.
-     * @returns Whether or not the source should request a tile.
+     * @param options - Optional request options (reload, intervals for time-series, etc.). Subclasses may use
+     *   this to request a tile when cached data does not satisfy the request (e.g. missing interval).
+     * @returns Whether the source should request a tile.
      */
-    shouldRequestTile(tile: Tile<Data>, reload?: boolean): boolean;
+    shouldRequestTile(tile: Tile<Data>, reload?: boolean, intervals?: Array<Date>): boolean;
     /**
      * Reloads all cached tiles.
      */
@@ -6471,26 +6857,28 @@ constructor(id: string, spec: Partial<Source>);
      * @returns A promise that resolves with the tile data.
      */
     requestTile(coord: TileCoord, options?: Partial<TileRequestOptions>): Promise<Data | null>;
-    /**
-     * Returns a tile instance for the given tile coordinate. If the tile does not exist, it will be created and added
-     * to the cache.
-     * @param coord - The tile coordinate.
-     * @returns The tile instance.
-     */
-    protected getOrCreateTile(coord: TileCoord): Tile<Data>;
-    protected loadTile(tile: Tile<Data>, options?: Partial<TileRequestOptions>): Promise<{
-        data: Blob;
-        headers: Headers;
+    protected loadTile(tile: Tile<Data>, options?: Partial<TileRequestOptions>, loadRequestCtx?: {
+        loadRequestId: number;
+    }): Promise<{
+        data: Blob | null;
+        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.
      */
     protected abortTile(tile: Tile<Data>): void;
-
-/**
+    /**
+     * Aborts in-worker requests for a tile by coordinate (e.g. when tile is no longer visible).
+     * Override in subclasses that run work in a worker (e.g. encoded operation layers).
+     * @param coord - The tile coordinate to abort.
+     */
+    abortTileByCoord(_coord: TileCoord): void;
+    
+    /**
      * Cancels all active tile requests.
      */
     cancelAllRequests(): void;
@@ -6633,6 +7021,7 @@ export declare class TimeAnimation extends Animation {
     private _endDate;
     private _endOffset;
     private _now;
+    private _rangeChangeAnchorDate?;
     constructor({ start, end, alwaysStopAtStart, ...animationOpts }: Partial<TimeAnimationOptions>);
     /**
      * Sets the start date of the animation using an offset from a reference date.
@@ -6685,6 +7074,14 @@ export declare class TimeAnimation extends Animation {
     protected eventPayload(): Record<string, any>;
     protected advanceToStopPosition(): void;
     private _debouncedRangeChangeEvent;
+    /**
+     * Captures the current date as an anchor date for the range change event.
+     */
+    private _captureRangeChangeAnchorDate;
+    /**
+     * Restores the anchor date for the range change event.
+     */
+    private _restoreRangeChangeAnchorDate;
 }
 
 export declare type TimeAnimationInfo = {
@@ -7023,11 +7420,12 @@ export declare const units: {
             readonly percent: "%";
         };
     };
+    resolveMeasurementForUnits: (type: _units.ConversionMeasurement) => _units.Measurement;
     defaultUnits: Record<"metric" | "imperial", MapUnits>;
-    getDefaultUnit: (type: _units.Measurement, system: "custom" | "metric" | "imperial") => string;
-    getDefaultUnitsForSystem: (system: "custom" | "metric" | "imperial") => MapUnits;
+    getDefaultUnit: (type: _units.ConversionMeasurement, system: "metric" | "imperial" | "custom") => string;
+    getDefaultUnitsForSystem: (system: "metric" | "imperial" | "custom") => MapUnits;
     equalUnits: (units1: MapUnits, units2: MapUnits) => boolean;
-    getSystemForUnits: (units: MapUnits) => "custom" | "metric" | "imperial";
+    getSystemForUnits: (units: MapUnits) => "metric" | "imperial" | "custom";
     FtoC: (f: number) => number;
     CtoF: (c: number) => number;
     mphToKph: (mph: number) => number;
@@ -7059,6 +7457,7 @@ export declare const units: {
     msToMphUnit: (ms: number) => number;
     dbzToMMRate: (dbz: number, perSecond?: boolean) => number;
     degToDir: (d: number) => string;
+    getUnitPrecision: (unit: string) => number;
     convert: (type: string, value: number, from: string, to: string) => number;
     getMeasurementType: (str: string) => _units.Measurement;
 };
@@ -7068,6 +7467,8 @@ declare namespace _units {
         UnitSystem,
         Units,
         Measurement,
+        ConversionMeasurement,
+        resolveMeasurementForUnits,
         defaultUnits,
         getDefaultUnit,
         getDefaultUnitsForSystem,
@@ -7104,6 +7505,7 @@ declare namespace _units {
         msToMphUnit,
         dbzToMMRate,
         degToDir,
+        getUnitPrecision,
         convert,
         getMeasurementType
     }
@@ -7161,6 +7563,9 @@ export declare const VectorSourceType: {
 
 export declare type VectorSourceType = ObjectValue<typeof VectorSourceType>;
 
+/** Static vector tile data or time-series container for animated vector tiles. */
+export declare type VectorTileData = VectorData | VectorTimeSeriesData;
+
 /**
  * A {@link TileSource} for vector tile data.
  * Vector tiles are a compact representation of geographic data. They are typically used to render map data in a vector
@@ -7168,25 +7573,32 @@ export declare type VectorSourceType = ObjectValue<typeof VectorSourceType>;
  * Vector tiles are typically served as a compressed binary format, such as
  * Mapbox's [MVT](https://docs.mapbox.com/vector-tiles/reference/mapbox-vector-tile-spec/).
  */
-export declare class VectorTileSource extends TileSource<VectorData, VectorSourceSpecification> {
+export declare class VectorTileSource extends TileSource<VectorTileData, VectorSourceSpecification> {
     
+    /**
+     * Tracks deferred tile refresh requests while a tile is still loading.
+     * Map key: tile coord hash.
+     * Map value: layer ids to refresh once parsing completes (`*` means refresh all consumers).
+     */
+    private readonly _pendingRefreshByTile;
     get type(): string;
     
     constructor(id: string, spec: Partial<VectorSourceSpecification>);
-    hasTile(coord: TileCoord, layerId?: string): boolean;
-    hasTileData(coord: TileCoord, layerId?: string, allowExpired?: boolean): boolean;
+    hasTileData(coord: TileCoord, layerId?: string, allowExpired?: boolean, _intervals?: Array<Date>): boolean;
     expireAllTiles(): void;
-    expireTile(tile: Tile<VectorData>): void;
+    expireTile(tile: Tile<VectorTileData>): void;
+    addConsumer(consumer: DataSourceConsumer): void;
     /**
      * Refreshes the data for all tiles in the source.
+     * @param layerId - The layer ID to refresh. If not provided, all layers will be refreshed.
      */
     refreshAllTileData(layerId?: string): void;
     /**
-     * Refreshes the data for a single tile in the source by re-parsing the existing data. This is useful when the
-     * filter expression has changed for a consuming layer.
+     * Refreshes the data for a single tile in the source by re-parsing the existing data. This is useful when a new
+     * consumer is added or the filter expression has changed for a consuming layer.
      * @param tile - The tile to refresh.
      */
-    refreshTileData(tile: Tile<VectorData>, layerId?: string): Promise<void>;
+    refreshTileData(tile: Tile<VectorTileData>, layerId?: string): Promise<void>;
     
 }
 
@@ -7364,10 +7776,9 @@ export declare type WeatherLayerOptions = {
      */
     timing: Partial<Omit<LayerTiming, 'mode'>>;
     /**
-     * Filter expression to use for filtering features from the data source. This is only used for vector tile data
-     * sources whose tiles are in the Mapbox Vector Tile (MVT) format.
+     * Filter expression for vector tile layers. Evaluated with StyleExpression.
      */
-    filter: ExpressionSpecification;
+    filter: FilterExpression;
     /**
      * Paint style overrides for the layer.
      */
@@ -7377,13 +7788,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.
      */
@@ -7474,6 +7882,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.
@@ -7513,7 +7923,14 @@ get mask(): LayerMask;
      * @readonly
      */
     get isDirty(): boolean;
-    constructor(id: string, { source, renderer }: Partial<WebGLLayerConfig>);
+    /**
+     * Optional measurement metadata associated with this layer's values.
+     */
+    measurement: {
+        type: ConversionMeasurement;
+        units: string;
+    } | undefined;
+    constructor(id: string, { source, renderer, measurement }: Partial<WebGLLayerConfig>);
     /**
      * Shows the layer if it is hidden.
      */
@@ -7542,9 +7959,11 @@ get mask(): LayerMask;
      * GeoJSON layer style will return the model properties associated with the feature at that location.
      * @param coord - Geographic coordinate to query for features.
      * @param zoom - Zoom level to query for features. If not provided, the map's current zoom level will be used.
+     * @param allowPartials - Whether to use partial data (ancestor or descendant) if the exact tile is not loaded.
+     * @param requestIfMissing - Whether to request the tile if it is missing.
      * @returns The features found at the specified coordinate and zoom level.
      */
-    queryFeatures(coord: Coordinate, zoom: number, allowPartials: boolean): FeatureQueryResult;
+    queryFeatures(coord: Coordinate, zoom: number, allowPartials: boolean, requestIfMissing?: boolean): FeatureQueryResult;
     /**
      * Returns a Promise that will query the layer for all features at the specified coordinate and zoom level
      * (optional). If a value for `zoom` is not provided, then the map's current zoom level will be used.
@@ -7605,5 +8024,12 @@ export declare interface WebGLLayerConfig {
      * Animation instance that controls the animation of this layer if time-based.
      */
     animation: Animation;
+    /**
+     * Optional measurement metadata associated with this layer's values.
+     */
+    measurement: {
+        type: ConversionMeasurement;
+        units: string;
+    };
 }