@fxi/zartigl 0.5.0 → 0.7.0

package/dist/zartigl.d.ts

@@ -2,6 +2,21 @@ import { CustomLayerInterface } from 'maplibre-gl';
 import { CustomRenderMethodInput } from 'maplibre-gl';
 import { Map as Map_2 } from 'maplibre-gl';
 
+/** Particle backdrop off: see BackdropStyle. */
+export declare const BACKDROP_OFF: Readonly<BackdropStyle>;
+
+/**
+ * Solid color under the particle trails, drawn on valid data cells only: it
+ * keeps particles readable over a light basemap. Off by default; an object
+ * without `enabled` is on.
+ */
+declare interface BackdropStyle {
+    enabled: boolean;
+    /** Hex color, `#rgb` or `#rrggbb`. */
+    color: string;
+    opacity: number;
+}
+
 export declare function buildMapxWidgetSnippet(options: MapxWidgetSnippetOptions): string;
 
 export declare function buildStandaloneDemoHtml(options: StandaloneDemoSnippetOptions): string;
@@ -41,31 +56,31 @@ export declare interface CatalogEntry {
     tags?: string[];
     kind: "scalar" | "vector";
     sources: CatalogSource[];
-    defaults: {
+    /** Default source, plus the layer's base style. */
+    defaults: LayerStyleInput & {
         sourceId: string;
         querySourceId?: string;
-        palette?: string;
-        renderMode?: "particles" | "raster" | "raster+particles";
-        particles?: {
-            density?: number;
-            speed?: number;
-            fade?: number;
-        };
-        raster?: {
-            opacity?: number;
-            logScale?: boolean;
-            vibrance?: number;
-            colorDomain?: [number, number];
-        };
     };
 }
 
+/**
+ * An incremental archive of calendar-aligned artifacts listed by a mutable
+ * index; zartigl resolves it to the chunk covering the requested time.
+ */
+declare interface CatalogGeoVideoArchiveSource extends CatalogSourceBase {
+    type: "geovideo";
+    indexUrl: string;
+    manifestUrl?: never;
+}
+
+/** One published artifact. */
 declare interface CatalogGeoVideoSource extends CatalogSourceBase {
     type: "geovideo";
     manifestUrl: string;
+    indexUrl?: never;
 }
 
-declare type CatalogRenderLayerBackend = "vector-zarr" | "scalar-zarr" | "scalar-geovideo" | "scalar-wmts";
+declare type CatalogRenderLayerBackend = "vector-zarr" | "scalar-zarr" | "scalar-geovideo" | "vector-geovideo" | "scalar-wmts";
 
 declare type CatalogRenderLayerDebugInfo = {
     id: string;
@@ -81,7 +96,7 @@ declare type CatalogRenderLayerDebugInfo = {
     delegate: VectorLayerDebugInfo | ScalarLayerDebugInfo | GeoVideoLayerDebugInfo | null;
 };
 
-export declare type CatalogSource = CatalogZarrSource | CatalogWmtsSource | CatalogGeoVideoSource;
+export declare type CatalogSource = CatalogZarrSource | CatalogWmtsSource | CatalogGeoVideoSource | CatalogGeoVideoArchiveSource;
 
 declare interface CatalogSourceBase {
     id: string;
@@ -144,6 +159,31 @@ declare interface CatalogZarrSource extends CatalogSourceBase {
     variables: CatalogVariables;
 }
 
+export declare const COLOR_GRADE_OFF: Readonly<ColorGrade>;
+
+export declare const COLOR_GRADE_VIBRANT: Readonly<ColorGrade>;
+
+/**
+ * Optional color grade applied when particle trails are composited
+ * (`shaders/color-grade.glsl`): more intense highlights, deeper shadows and
+ * richer colors, without hard clipping. Off by default; when off, the
+ * composite returns the trail colors unchanged.
+ */
+export declare interface ColorGrade {
+    enabled: boolean;
+    /** Mid-tone lift [0, 4]; 0 keeps the tones. */
+    exposure: number;
+    /** S-curve strength [0, 1]. */
+    contrast: number;
+    /** Vibrance-weighted saturation [-1, 1]. */
+    saturation: number;
+    /** Push of the bright half toward white [0, 1]. */
+    highlights: number;
+}
+
+/** Style `particles.grade` of a color grade: a preset when it is one. */
+export declare function colorGradeToGrade(input: Partial<ColorGrade>): ParticleGrade;
+
 export declare type ColorRampInput = string | string[] | Record<number, string>;
 
 declare interface CoordArrays {
@@ -182,7 +222,15 @@ export declare interface FieldMeta {
     depth?: number;
 }
 
-export declare type GeoVideoBounds = [west: number, south: number, east: number, north: number];
+/** GeoVideo playback speeds, in time steps per second. */
+export declare const GEOVIDEO_SPEEDS: readonly number[];
+
+export declare type GeoVideoBounds = [
+west: number,
+south: number,
+east: number,
+north: number
+];
 
 declare type GeoVideoEventMap = {
     loading: () => void;
@@ -191,6 +239,8 @@ declare type GeoVideoEventMap = {
     status: (status: ZartiglStatus) => void;
     timeChange: (time: number) => void;
     playbackChange: (playing: boolean) => void;
+    /** Playback reached the end of the timeline without looping. */
+    playbackEnd: () => void;
 };
 
 export declare class GeoVideoLayer implements CustomLayerInterface {
@@ -198,7 +248,8 @@ export declare class GeoVideoLayer implements CustomLayerInterface {
     readonly type: "custom";
     readonly renderingMode: "3d";
     private readonly source;
-    private readonly autoplay;
+    /** Start playback once ready: autoplay, or a swap that was playing. */
+    private playOnReady;
     private loop;
     private playbackRate;
     private requestedTime;
@@ -213,6 +264,14 @@ export declare class GeoVideoLayer implements CustomLayerInterface {
     private gl;
     private manifest;
     private video;
+    /** Manifest of `video`, which still differs from `manifest` mid-swap. */
+    private videoManifest;
+    /** Incoming media of a swap, shown once its first frame is decodable. */
+    private pendingVideo;
+    private standby;
+    /** Ended on a preloaded artifact: playing until it is swapped in or paused. */
+    private awaitingNext;
+    private maskUrl;
     private colorTexture;
     private maskTexture;
     private colorRampTexture;
@@ -245,12 +304,33 @@ export declare class GeoVideoLayer implements CustomLayerInterface {
     private lastUploadDurationMs;
     private abortController;
     private resumePlayback;
+    private stepTimer;
+    private endEmitted;
     private listeners;
     constructor(options: GeoVideoLayerOptions);
-    onAdd(map: Map_2, gl: WebGLRenderingContext): Promise<void>;
-    render(gl: WebGLRenderingContext, options: CustomRenderMethodInput): void;
+    onAdd(map: Map_2, context: WebGLRenderingContext | WebGL2RenderingContext): Promise<void>;
+    render(context: WebGLRenderingContext | WebGL2RenderingContext, options: CustomRenderMethodInput): void;
     onRemove(): void;
     setTime(time: string | number): void;
+    /**
+     * Switch to another artifact of the same frame size, such as the next
+     * archive chunk, keeping the map layer and GL state. The current frame stays
+     * on screen until the new media can show its first one, at once when it was
+     * preloaded. Returns false when the artifact needs a new layer.
+     */
+    replaceManifest(manifest: GeoVideoManifest, options?: GeoVideoReplaceOptions): boolean;
+    /**
+     * Load the artifact expected next, such as the following archive chunk, so
+     * `replaceManifest` can show it without waiting for the network. Until then,
+     * reaching the end of the current artifact keeps the playing state and
+     * emits `playbackEnd` for the caller to swap it in, or to pause. Returns
+     * false when the artifact cannot replace the current one in place.
+     */
+    preloadManifest(manifest: GeoVideoManifest, options?: GeoVideoReplaceOptions): boolean;
+    /** Clamped time range of a compatible replacement, else null. */
+    private replacementTimeRange;
+    /** The preloaded artifact when it holds this media; any other is dropped. */
+    private takeStandby;
     setTimeAndDepth(time: string | number, _depth: number): void;
     setDepth(_depth: number): void;
     prefetchTime(_ms: number): Promise<void>;
@@ -266,6 +346,24 @@ export declare class GeoVideoLayer implements CustomLayerInterface {
     setOpacity(value: number): void;
     play(): Promise<void>;
     pause(): void;
+    /**
+     * Playback is a request, applied once ready, while the manifest loads,
+     * mid-swap, or at an end waiting for the preloaded artifact.
+     */
+    private deferredPlayback;
+    private isPlaying;
+    /**
+     * Below the slowest media rate browsers accept, keep the video paused and
+     * seek one sample (or frame) at a time.
+     */
+    private startStepping;
+    private stopStepping;
+    private step;
+    /**
+     * The timeline ended without looping. With a preloaded artifact, keep the
+     * playing state for the caller to swap it in; otherwise stop.
+     */
+    private reachEnd;
     setLoop(loop: boolean): void;
     setPlaybackRate(rate: number): void;
     setTimeRange(range: [number, number]): void;
@@ -275,8 +373,28 @@ export declare class GeoVideoLayer implements CustomLayerInterface {
     off<K extends keyof GeoVideoEventMap>(event: K, handler: GeoVideoEventMap[K]): this;
     private initGl;
     private initVideo;
+    /**
+     * Media element for a manifest. Its events drive the layer only while it is
+     * the current video and no swap is pending.
+     */
+    private createVideo;
+    /** Track presented frames of the current video. */
+    private startFrameCallbacks;
+    /**
+     * Time a loading video opens at: its preload target, or the requested time
+     * within the active range.
+     */
+    private startTime;
+    private checkVideoSize;
+    private cancelFrameCallback;
+    /** Stop the current video and free its media resources. */
+    private releaseVideo;
+    private discardStandby;
+    private discardPendingVideo;
     private bufferFrame;
-    private loadStaticMask;
+    private createMaskImage;
+    /** Show the mask of a manifest once its image, possibly preloaded, loads. */
+    private applyMask;
     private emitReady;
     private createVideoTexture;
     private uploadTextureSource;
@@ -296,6 +414,8 @@ export declare interface GeoVideoLayerDebugInfo {
     currentTime: number;
     manifestId?: string;
     mediaUrl?: string;
+    /** Media loaded ahead for the next swap. */
+    preloadedMediaUrl?: string;
     decodedFrames: number;
     bufferedFrames: number;
     skippedFrames: number;
@@ -339,17 +459,7 @@ export declare interface GeoVideoManifest {
         durationSeconds: number;
         codec: "h264" | string;
     };
-    encoding: {
-        kind: "scalar-luma";
-        bits: 8;
-        codeMin: number;
-        codeMax: number;
-        valueMin: number;
-        valueMax: number;
-        transfer: "linear";
-        colorSpace: "bt709";
-        colorRange: "limited" | "full";
-    };
+    encoding: GeoVideoScalarEncoding | GeoVideoVectorEncoding;
     mask: {
         kind: "static-validity";
         url: string;
@@ -379,7 +489,10 @@ export declare interface GeoVideoManifest {
 export declare interface GeoVideoOptions {
     autoplay?: boolean;
     loop?: boolean;
+    /** Media rate multiplier; prefer `stepsPerSecond`, which means the same on every artifact. */
     playbackRate?: number;
+    /** Time steps shown per second; takes precedence over `playbackRate`. */
+    stepsPerSecond?: number;
 }
 
 export declare interface GeoVideoRangeTimeline {
@@ -389,11 +502,34 @@ export declare interface GeoVideoRangeTimeline {
     interpolation: "linear" | "nearest";
 }
 
+/**
+ * Playback state for an artifact swapped in with `replaceManifest`, or
+ * loaded ahead with `preloadManifest`.
+ */
+declare interface GeoVideoReplaceOptions {
+    time?: number;
+    timeRange?: [number, number];
+    loop?: boolean;
+    playbackRate?: number;
+}
+
 export declare interface GeoVideoSampleSequenceTimeline {
     kind: "sample-sequence";
     values: string[];
 }
 
+declare interface GeoVideoScalarEncoding {
+    kind: "scalar-luma";
+    bits: 8;
+    codeMin: number;
+    codeMax: number;
+    valueMin: number;
+    valueMax: number;
+    transfer: "linear";
+    colorSpace: "bt709";
+    colorRange: "limited" | "full";
+}
+
 export declare function geoVideoSecondsForTime(manifest: GeoVideoManifest, timeMs: number): number;
 
 export declare interface GeoVideoSnapshotLoopTimeline {
@@ -405,10 +541,46 @@ export declare function geoVideoTimeForSeconds(manifest: GeoVideoManifest, secon
 
 export declare function geoVideoTimelineValues(manifest: GeoVideoManifest): number[];
 
+/**
+ * u and v stacked vertically in luma (u rows on top). Each component maps
+ * [-valueDomain, valueDomain] to [codeMin, codeMax]; "sqrt" stores
+ * sign(x)·sqrt(|x|/valueDomain) to keep precision on slow flows. The static
+ * mask covers one component (media height / 2).
+ */
+declare interface GeoVideoVectorEncoding {
+    kind: "vector-luma";
+    bits: 8;
+    codeMin: number;
+    codeMax: number;
+    valueDomain: number;
+    transfer: "linear" | "sqrt";
+    layout: "stacked-uv";
+    colorSpace: "bt709";
+    colorRange: "limited" | "full";
+}
+
 export declare function getPalettes(): PaletteMeta[];
 
 export declare function getVectorDerivationVariables(derivation: VectorDerivation): [string, string];
 
+/** Color grade of a style `particles.grade`; an object tunes the vibrant one. */
+export declare function gradeToColorGrade(grade: ParticleGrade | undefined): ColorGrade;
+
+/** Vibrant grade values; each one left out takes the vibrant preset's. */
+declare interface GradeTuning {
+    /** Mid-tone lift [0, 4]. */
+    exposure?: number;
+    /** S-curve strength [0, 1]. */
+    contrast?: number;
+    /** Vibrance-weighted saturation [-1, 1]. */
+    saturation?: number;
+    /** Push of the bright half toward white [0, 1]. */
+    highlights?: number;
+}
+
+/** A `#rgb` or `#rrggbb` color. */
+export declare const isHexColor: (value: unknown) => value is string;
+
 declare type LayerEventMap = {
     loading: () => void;
     loaded: (meta: FieldMeta) => void;
@@ -429,6 +601,25 @@ declare type LayerEventMap_2 = {
     cacheInvalidated: () => void;
 };
 
+declare interface LayerStyle {
+    /** Palette id; undefined lets the engine pick its own. */
+    palette?: string;
+    renderMode: StyleRenderMode;
+    particles: ParticleStyle;
+    raster: RasterStyle;
+}
+
+/** A partial style: any key left out takes the value below it. */
+declare interface LayerStyleInput {
+    palette?: string;
+    renderMode?: StyleRenderMode;
+    particles?: ParticleStyleInput;
+    raster?: Partial<RasterStyle>;
+}
+
+/** Where each deprecated flat style setting moved in the style. */
+export declare const LEGACY_STYLE_SETTINGS: Readonly<Partial<Record<keyof ZartiglSettings, string>>>;
+
 export declare type Legend = {
     type: "gradient";
     palette: string;
@@ -450,12 +641,20 @@ declare type LocalizedText = Record<string, string>;
 export declare interface MapxWidgetSnippetOptions {
     layerId: string;
     layerKind: CatalogEntry["kind"];
+    /**
+     * The layer's own style, the catalog `defaults`: only override keys that
+     * differ from it are written. Unknown, the whole override is written.
+     */
+    layerDefaults?: LayerStyleInput;
     source?: string;
     sourceType?: SnippetSourceType;
     time?: string | number | Date;
     timeRange?: TimeRange;
     geoVideo?: GeoVideoOptions;
     depth?: number;
+    /** Style override; only keys that differ from the layer's own are written. */
+    style?: LayerStyleInput;
+    /** Engine tuning; flat style keys are ignored. */
     settings?: Partial<ZartiglSettings>;
 }
 
@@ -466,12 +665,16 @@ export declare interface PaletteMeta {
     colors: string[];
 }
 
+/** Particle trail color grade: a preset, or the vibrant one tuned. */
+declare type ParticleGrade = "off" | "vibrant" | GradeTuning;
+
 export declare class ParticleSimulation {
     private gl;
     private params;
     private updateProgram;
     private drawProgram;
     private fadeProgram;
+    private compositeProgram;
     private gridProgram;
     private gridGlobeProgram;
     private particleStateTextures;
@@ -482,12 +685,9 @@ export declare class ParticleSimulation {
     private numParticles;
     private prevBounds;
     private redistributionBoost;
-    private cameraMoving;
-    private currentFadeOpacity;
-    private fadeTransitionStartOpacity;
-    private fadeTransitionTargetOpacity;
-    private fadeTransitionStartMs;
-    private fadeTransitionDurationMs;
+    /** Advection counter seeding the update shader random streams. */
+    private frame;
+    private readonly trailFade;
     private webglInfo;
     private stateFormat;
     private lastRgba8ParticlesSuppressed;
@@ -504,10 +704,11 @@ export declare class ParticleSimulation {
     private updateLocs;
     private drawLocs;
     private fadeLocs;
+    private compositeLocs;
     private gridLocs;
     private gridGlobeLocs;
     constructor(params?: Partial<SimulationParams>);
-    init(gl: WebGLRenderingContext): void;
+    init(gl: WebGL2RenderingContext): void;
     private getUniforms;
     /** Random initial particle positions, matching the active state format. */
     private makeStateData;
@@ -539,13 +740,13 @@ export declare class ParticleSimulation {
         south: number;
         east: number;
         north: number;
-    }, opacityScale?: number): void;
+    }, opacityScale?: number, solid?: Vec4): void;
     renderGridGlobe(velocityTexUnit: number, velocityMin: [number, number], velocityMax: [number, number], matrix: Iterable<number>, geoBounds: {
         west: number;
         south: number;
         east: number;
         north: number;
-    }, clippingPlane: [number, number, number, number], opacityScale?: number): void;
+    }, clippingPlane: [number, number, number, number], opacityScale?: number, solid?: Vec4): void;
     private setGridFieldUniforms;
     private bindRasterGrid;
     private unbindRasterGrid;
@@ -564,6 +765,10 @@ export declare class ParticleSimulation {
     setOpacity(v: number): void;
     setLogScale(v: boolean): void;
     setVibrance(v: number): void;
+    /** Partial values take the vibrant preset; see resolveColorGrade. */
+    setColorGrade(grade: Partial<ColorGrade>): void;
+    /** Missing values take the defaults; see resolveBackdrop. */
+    setBackdrop(backdrop: Partial<BackdropStyle>): void;
     setScalarMode(v: boolean): void;
     setRgba8MaxParticleZoom(v: number): void;
     /**
@@ -599,6 +804,8 @@ export declare interface ParticleSimulationDebugInfo {
     opacity: number;
     logScale: boolean;
     vibrance: number;
+    colorGrade: ColorGrade;
+    backdrop: BackdropStyle;
     scalarMode: boolean;
     devicePixelRatio?: number;
     webgl: WebGLRendererInfo | null;
@@ -608,6 +815,35 @@ export declare type ParticleStateKind = StateTextureFormat["kind"];
 
 export declare type ParticleStateMode = "auto" | "rgba8";
 
+declare interface ParticleStyle {
+    /** Particles per device pixel, (0, 0.2]. */
+    density: number;
+    /** Css px per frame for the fastest value of the field, (0, 10]. */
+    speed: number;
+    /** Trail length, [0, 1] (longer when higher). */
+    fade: number;
+    /** Trail color grade; replaced as a whole, not merged. */
+    grade: ParticleGrade;
+    /** Solid color under the trails; replaced as a whole, not merged. */
+    backdrop: BackdropStyle;
+}
+
+/** Partial particle style; a partial backdrop takes the defaults' keys. */
+declare type ParticleStyleInput = Partial<Omit<ParticleStyle, "backdrop">> & {
+    backdrop?: Partial<BackdropStyle>;
+};
+
+export declare interface PlaybackState {
+    /** Whether the active source plays automatically: GeoVideo only. */
+    available: boolean;
+    playing: boolean;
+    loop: boolean;
+    /** Speed applied by the active source; vector stays within `speeds`. */
+    stepsPerSecond: number;
+    /** Speeds offered for the active layer kind. */
+    speeds: readonly number[];
+}
+
 export declare interface QueryDepthProfileOptions {
     longitude: number;
     latitude: number;
@@ -622,7 +858,30 @@ export declare interface QueryPointOptions {
     maxPoints?: number;
 }
 
-export declare type RenderMode = 'raster' | 'particles' | 'raster+particles';
+declare interface RasterStyle {
+    opacity: number;
+    logScale: boolean;
+    /** Vibrance adjustment, [-1, 1]. */
+    vibrance: number;
+    /** Fixed physical-value domain; null follows the data. */
+    colorDomain: [number, number] | null;
+}
+
+export declare type RenderMode = "raster" | "particles" | "raster+particles";
+
+/**
+ * Complete backdrop from partial input. Missing or invalid values take the
+ * defaults, opacity is clamped; `enabled` defaults to true when any input is
+ * given, so `{ opacity: 0.2 }` means "on".
+ */
+export declare function resolveBackdrop(input?: Partial<BackdropStyle>): BackdropStyle;
+
+/**
+ * Complete grade from partial input. Missing or non-finite values take the
+ * vibrant preset, others are clamped to their range; `enabled` defaults to
+ * true when any input is given, so `{}` means "vibrant".
+ */
+export declare function resolveColorGrade(input?: Partial<ColorGrade>): ColorGrade;
 
 /** Resolve a native date/time control value against actual available times. */
 export declare function resolveTimeInputSelection(values: readonly number[], value: string, granularity: TimeGranularity): number | undefined;
@@ -656,10 +915,10 @@ export declare class ScalarLayer implements CustomLayerInterface {
     private colorDomain;
     private textureUnit;
     constructor(options: ScalarLayerOptions);
-    onAdd(map: Map_2, gl: WebGLRenderingContext): Promise<void>;
+    onAdd(map: Map_2, context: WebGLRenderingContext | WebGL2RenderingContext): Promise<void>;
     private moveEndHandler;
     private initAsync;
-    render(gl: WebGLRenderingContext, options: CustomRenderMethodInput): void;
+    render(context: WebGLRenderingContext | WebGL2RenderingContext, options: CustomRenderMethodInput): void;
     onRemove(): void;
     setTime(time: string | number): void;
     setTimeAndDepth(time: string | number, depth: number): void;
@@ -744,6 +1003,10 @@ declare interface SimulationParams {
     opacity: number;
     logScale: boolean;
     vibrance: number;
+    /** Grade of the trail composite; off by default. */
+    colorGrade: ColorGrade;
+    /** Solid color under the trails, on valid cells; off by default. */
+    backdrop: BackdropStyle;
     scalarMode: boolean;
     particleState: ParticleStateMode;
     rgba8MaxParticleZoom: number;
@@ -751,6 +1014,17 @@ declare interface SimulationParams {
 
 declare type SnippetSourceType = "zarr" | "geovideo" | "wmts";
 
+/**
+ * Split flat settings into the style their style keys make and the engine
+ * tuning left. A custom palette ramp, not a palette id, stays in
+ * `settings`. `legacyKeys` lists the style keys found.
+ */
+export declare function splitLegacySettings(settings?: Partial<ZartiglSettings>): {
+    style: LayerStyleInput;
+    settings: Partial<ZartiglSettings>;
+    legacyKeys: (keyof ZartiglSettings)[];
+};
+
 export declare interface StandaloneDemoSnippetOptions extends MapxWidgetSnippetOptions {
     moduleBaseUrl?: string;
     center?: [number, number];
@@ -758,7 +1032,8 @@ export declare interface StandaloneDemoSnippetOptions extends MapxWidgetSnippetO
     bearing?: number;
     pitch?: number;
     projection?: "mercator" | "globe";
-    style?: string;
+    /** MapLibre map style URL; a cloudless imagery style when omitted. */
+    mapStyle?: string;
 }
 
 /**
@@ -798,6 +1073,13 @@ export declare function stitchVelocityChunks(uChunks: Array<{
     north: number;
 }, latDescending?: boolean, scalarMode?: boolean): VelocityData;
 
+/**
+ * Layer style: how a layer looks, with the same keys in the catalog
+ * `defaults`, the engines and story views. Playback (how time moves) is not
+ * part of it, so `particles.speed` is always the particle speed.
+ */
+declare type StyleRenderMode = "particles" | "raster" | "raster+particles";
+
 export declare type TimeGranularity = "year" | "month" | "day" | "hour" | "minute" | "second";
 
 export declare interface TimeMeta {
@@ -829,8 +1111,28 @@ export declare interface VariableMeta {
     units?: string;
 }
 
+declare type Vec4 = [number, number, number, number];
+
+/**
+ * Vector GeoVideo speeds: each step re-seeds the particles, so trails need
+ * time to settle (the projection demo plays 0.2 to 2 steps per second).
+ */
+export declare const VECTOR_GEOVIDEO_SPEEDS: readonly number[];
+
 export declare type VectorDerivation = DirectionMagnitudeVectorDerivation;
 
+/**
+ * Field source contract used by VectorLayer. ZarrSource satisfies it; frame
+ * sources such as GeoVideoVectorSource implement it to feed decoded frames.
+ */
+declare type VectorFieldSource = Pick<ZarrSource, "init" | "cancelAll" | "getCoords" | "getDimensions" | "getChunkShape" | "findTimeIndex" | "findDepthIndex" | "getChunksForBounds" | "fetchSpatialChunkResult"> & {
+    /**
+     * Fixed symmetric component domain [-d, d]. When provided, it replaces the
+     * per-frame min/max so speed and color normalization stay stable in time.
+     */
+    getValueDomain?(): number;
+};
+
 export declare class VectorLayer implements CustomLayerInterface {
     readonly id: string;
     readonly type: "custom";
@@ -864,7 +1166,7 @@ export declare class VectorLayer implements CustomLayerInterface {
     private inflight;
     private listeners;
     constructor(options: VectorLayerOptions);
-    onAdd(map: Map_2, gl: WebGLRenderingContext): Promise<void>;
+    onAdd(map: Map_2, context: WebGLRenderingContext | WebGL2RenderingContext): Promise<void>;
     private initAsync;
     private timeToMs;
     private computeFieldMeta;
@@ -876,14 +1178,15 @@ export declare class VectorLayer implements CustomLayerInterface {
      */
     private fetchVelocityData;
     private loadViewportVelocity;
-    render(gl: WebGLRenderingContext, options: CustomRenderMethodInput): void;
+    render(context: WebGLRenderingContext | WebGL2RenderingContext, options: CustomRenderMethodInput): void;
     onRemove(): void;
     setTime(time: string | number): void;
     setTimeAndDepth(time: string | number, depth: number): void;
     /**
      * Pre-fetch velocity data for a future time step without swapping the active
      * field. Fires `frameBuffered(ms)` when ready so playback can advance
-     * immediately without a loading gap.
+     * immediately without a loading gap. Rejects when the frame cannot be
+     * loaded, so playback can stop instead of waiting for it.
      */
     prefetchTime(ms: number): Promise<void>;
     /** True when the frame for the given time (ms) is already in the cache. */
@@ -902,6 +1205,8 @@ export declare class VectorLayer implements CustomLayerInterface {
     setOpacity(v: number): void;
     setLogScale(v: boolean): void;
     setVibrance(v: number): void;
+    setColorGrade(grade: Partial<ColorGrade>): void;
+    setBackdrop(backdrop: Partial<BackdropStyle>): void;
     getDebugInfo(): VectorLayerDebugInfo;
     on<K extends keyof LayerEventMap_2>(event: K, handler: LayerEventMap_2[K]): this;
     off<K extends keyof LayerEventMap_2>(event: K, handler: LayerEventMap_2[K]): this;
@@ -925,7 +1230,7 @@ export declare interface VectorLayerOptions {
     id: string;
     source: string;
     /** Optional initialized/shared source. When omitted, the layer creates one from `source`. */
-    zarrSource?: ZarrSource;
+    zarrSource?: VectorFieldSource;
     variableU?: string;
     variableV?: string;
     vectorDerivation?: VectorDerivation;
@@ -950,6 +1255,13 @@ export declare interface VectorLayerOptions {
     logScale?: boolean;
     /** Vibrance adjustment [-1, 1]. Default 0.0. */
     vibrance?: number;
+    /**
+     * Particle trail color grade. Omitted: off; missing values take the
+     * vibrant preset (see resolveColorGrade).
+     */
+    colorGrade?: Partial<ColorGrade>;
+    /** Solid color under the trails, on valid cells. Omitted: off. */
+    backdrop?: Partial<BackdropStyle>;
     unit?: string;
 }
 
@@ -995,7 +1307,7 @@ export declare class VelocityField {
     };
     scalarMode: boolean;
     private linearFilter;
-    init(gl: WebGLRenderingContext): void;
+    init(gl: WebGL2RenderingContext): void;
     /**
      * Upload velocity data as a 2-channel (RG) texture.
      * Input: u/v Float32Arrays with real physical values.
@@ -1201,8 +1513,12 @@ export declare class Zartigl {
     private timeRange?;
     private fullTimeMeta;
     private autoplay;
+    /** Autoplay applies to the first layer only: later sources start paused. */
+    private autoplayPending;
+    private playing;
     private loop;
     private playbackRate;
+    private stepsPerSecond;
     private readonly metadata?;
     private readonly before?;
     private visible;
@@ -1211,8 +1527,22 @@ export declare class Zartigl {
     private layer;
     private time;
     private pendingTime;
+    /** Latest time the caller asked for, ahead of the queued update applying it. */
+    private requestedTime;
+    /** Bumped by caller pauses and time requests, which cancel a chunk handoff. */
+    private playbackIntent;
+    /** Order of caller requests: updates and play() calls. */
+    private requestSeq;
+    /** Request that started the current playback; 0 once paused. */
+    private playSeq;
     private depth;
+    /** Depth the caller selected, kept across sources; null shows the surface. */
+    private depthRequest;
+    /** GeoVideo manifests that failed to load; "auto" falls back to Zarr. */
+    private failedGeoVideo;
     private settings;
+    /** Style override over the layer's own, kept across layers. */
+    private style;
     private colorDomainOverridden;
     private paletteOverridden;
     private lastMeta;
@@ -1224,6 +1554,9 @@ export declare class Zartigl {
     private geoVideoManifest;
     private wmtsMetadata;
     private fieldSources;
+    private archiveChunks;
+    /** Manifest of the archive chunk expected next, requested ahead of it. */
+    private nextChunkManifest;
     private activeFieldSource;
     private switchGeneration;
     private destroyed;
@@ -1239,10 +1572,24 @@ export declare class Zartigl {
     private readonly onMapIdle;
     constructor(options: ZartiglOptions);
     init(): Promise<void>;
-    update(change: ZartiglUpdate): Promise<void>;
+    update(input: ZartiglUpdate): Promise<void>;
+    /**
+     * Queue a change after earlier ones. Internal seeks, such as an archive
+     * chunk handoff, come here directly and keep playback going.
+     */
+    private enqueue;
     private applyUpdate;
     private loadLayer;
+    private loadSource;
     private changeSource;
+    /**
+     * Source switch after init: leave the current GeoVideo when it cannot show
+     * the requested time, window, or depth and another source can. A time
+     * change alone never switches back, so scrubbing a Zarr timeline does not
+     * flip sources; in "auto", selecting the surface depth, alone or with a
+     * date GeoVideo covers, returns to GeoVideo.
+     */
+    private needsSourceSwitch;
     private applyVisible;
     /** Pause rendering and abort field requests without discarding layer state. */
     suspend(): void;
@@ -1250,10 +1597,31 @@ export declare class Zartigl {
     resume(): void;
     destroy(): void;
     private applyTime;
+    /** Start GeoVideo playback; does nothing where playback is unavailable. */
     play(): Promise<void>;
+    private startPlayback;
+    /**
+     * Show the previous or next time step, stopping playback. Stays at the
+     * first and last steps: resolves false when there is no step to move to.
+     */
+    stepTime(offset: -1 | 1): Promise<boolean>;
+    /**
+     * Time step before or after the latest requested time, so quick successive
+     * steps add up; undefined past the first or last step.
+     */
+    getSteppedTime(offset: -1 | 1): number | undefined;
     pause(): void;
     private applyLoop;
     private applyPlaybackRate;
+    private applyPlaybackSpeed;
+    /** Media rate for the loaded artifact: steps per second when set, else the raw multiplier. */
+    private effectivePlaybackRate;
+    private playbackSpeeds;
+    /**
+     * Steps per second the active source shows. Vector GeoVideo stays inside
+     * its speeds; scalar media follows the request, or the raw multiplier.
+     */
+    private appliedStepsPerSecond;
     /** Apply or clear a time window without rebuilding source metadata or the map layer. */
     private applyTimeRange;
     private applyDepth;
@@ -1275,20 +1643,93 @@ export declare class Zartigl {
         render: true;
         time: boolean;
         depth: boolean;
+        /** Automatic playback (play, stop, loop, speed): GeoVideo only. */
+        playback: boolean;
         pointQuery: boolean;
         sourceTypes: CatalogSource["type"][];
     };
+    getPlaybackState(): PlaybackState;
+    /** GeoVideo with more than one step, or a scalar looping snapshot, plays. */
+    private hasPlayback;
     /** Whether palette/domain styling is applied to values in the active renderer. */
     supportsDynamicStyle(): boolean;
+    /**
+     * The style drawn: the layer's own, then the override, with what the
+     * source chose, such as a GeoVideo archive's palette.
+     */
+    getStyle(): LayerStyle;
+    /** The style override over the layer's own. */
+    getStyleOverride(): LayerStyleInput;
     getDebugInfo(): ZartiglDebugInfo;
+    /**
+     * Every style key of the shown layer with the override, the palette and
+     * color domain of a GeoVideo archive included, as a load sets them.
+     */
+    private styledSettings;
     private applySettings;
     queryTimeSeries(options: QueryPointOptions): Promise<ZarrPointSeriesResult>;
     queryDepthProfile(options: QueryDepthProfileOptions): Promise<ZarrPointSeriesResult>;
     private attachWhenReady;
+    /** GeoVideo playback options shared by a new layer and an in-place swap. */
+    private geoVideoPlayback;
+    /**
+     * Show another artifact of the same scalar GeoVideo entry, such as the next
+     * archive chunk, in the attached layer. The last frame stays on screen until
+     * the new media is ready, instead of a blank map while a new layer loads.
+     */
+    private replaceGeoVideoInPlace;
     private detach;
+    /**
+     * In "auto", a GeoVideo that fails while it renders (media, mask) yields
+     * to another source, paused, keeping the date and depth.
+     */
+    private fallBackFromGeoVideo;
     private applyMutableSettings;
     private getQuerySource;
     private getFieldSource;
+    /**
+     * Time the caller asked for, so selection skips fixed-period sources (such
+     * as a GeoVideo artifact) that cannot show it. A trailing window targets now.
+     */
+    private sourceTimeRequest;
+    /**
+     * Source for a preference and target. In "auto", a GeoVideo that cannot show
+     * the requested depth (it renders the surface level) yields to Zarr.
+     */
+    private selectSource;
+    private isFailedGeoVideo;
+    /** The entry without GeoVideo artifacts that failed to load. */
+    private withoutFailedGeoVideo;
+    /** Whether `depth` resolves to the surface level that GeoVideo renders. */
+    private geoVideoServesDepth;
+    private isArchiveChunk;
+    /**
+     * The archive chunk that follows the current one inside the active time
+     * range, or with loop on, the first one, with the time playback resumes at.
+     */
+    private nextArchiveChunk;
+    /** A chunk manifest, reusing the one requested ahead for the next chunk. */
+    private loadChunkManifest;
+    /**
+     * While a scalar archive chunk plays, load the next chunk into the layer so
+     * playback moves on without waiting for its manifest and media.
+     */
+    private preloadNextArchiveChunk;
+    /**
+     * Keep playing across an archive: when a chunk ends, play the next chunk
+     * inside the active time range, or with loop on, the first one.
+     */
+    private continueArchivePlayback;
+    /** The entry's initialised field Zarr, or null when it has none. */
+    private entryFieldZarr;
+    /** Zarr time and vertical axes; unavailable metadata leaves the artifact's own timeline. */
+    private zarrAxes;
+    /**
+     * Entry whose archive sources are replaced by one fixed-period source per
+     * published chunk. An unreachable index drops the archive, so selection
+     * falls back to the entry's other sources.
+     */
+    private resolveArchives;
     private resolveSource;
     private querySource;
     private isMapReady;
@@ -1329,7 +1770,9 @@ export declare interface ZartiglDebugInfo {
     depth: number;
     settings: Partial<ZartiglSettings>;
     timeRange?: TimeRange;
-    geoVideo: Required<GeoVideoOptions>;
+    geoVideo: Required<Omit<GeoVideoOptions, "stepsPerSecond">> & {
+        stepsPerSecond: number | null;
+    };
     layer: CatalogRenderLayerDebugInfo | null;
 }
 
@@ -1342,6 +1785,11 @@ declare type ZartiglEventMap = {
     cacheInvalidated: () => void;
     timeChange: (time: number) => void;
     playbackChange: (playing: boolean) => void;
+    /** The active source changed, including an automatic fallback. */
+    sourceChange: (source: {
+        id: string;
+        type: CatalogSource["type"];
+    }) => void;
 };
 
 export declare class ZartiglFrameUnavailableError extends Error {
@@ -1362,6 +1810,12 @@ export declare interface ZartiglOptions {
     depth?: number;
     geoVideo?: GeoVideoOptions;
     visible?: boolean;
+    /** Style override over the layer's own. */
+    style?: LayerStyleInput;
+    /**
+     * Engine tuning (`particleState`, `rgba8MaxParticleZoom`). Flat style
+     * keys are deprecated: they move to `style`, with a warning.
+     */
     settings?: Partial<ZartiglSettings>;
     metadata?: Record<string, unknown>;
     before?: string;
@@ -1376,6 +1830,13 @@ export declare interface ZartiglSettings {
     opacity: number;
     logScale: boolean;
     vibrance: number;
+    /**
+     * Particle trail color grade; off by default. Missing values take the
+     * vibrant preset (see resolveColorGrade).
+     */
+    colorGrade: Partial<ColorGrade>;
+    /** Solid color under particle trails, on valid cells; off by default. */
+    backdrop: Partial<BackdropStyle>;
     /** Fixed physical-value domain for scalar colors. Null uses frame extrema. */
     colorDomain: [number, number] | null;
     particleState: ParticleStateMode;
@@ -1412,6 +1873,17 @@ export declare interface ZartiglUpdate {
     timeRange?: TimeRange | null;
     time?: Date | string | number;
     depth?: number;
+    /**
+     * Replaces the style override: every style key returns to the layer's own,
+     * then this one applies (`{}` clears it). Omitted, the override stays,
+     * across layers too, without the keys a new layer kind cannot draw. Kept
+     * once a layer switch loads.
+     */
+    style?: LayerStyleInput;
+    /**
+     * Engine tuning. Flat style keys are deprecated: they patch the style
+     * override, with a warning.
+     */
     settings?: Partial<ZartiglSettings>;
     geoVideo?: GeoVideoOptions;
     visible?: boolean;