@fxi/zartigl 0.4.2 → 0.6.0

package/dist/zartigl.d.ts

@@ -60,12 +60,24 @@ export declare interface CatalogEntry {
     };
 }
 
+/**
+ * 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 +93,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 +156,28 @@ 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;
+}
+
 export declare type ColorRampInput = string | string[] | Record<number, string>;
 
 declare interface CoordArrays {
@@ -182,7 +216,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 +233,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 +242,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 +258,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 +298,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 +340,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 +367,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 +408,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 +453,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 +483,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 +496,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,6 +535,24 @@ 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];
@@ -472,6 +620,7 @@ export declare class ParticleSimulation {
     private updateProgram;
     private drawProgram;
     private fadeProgram;
+    private compositeProgram;
     private gridProgram;
     private gridGlobeProgram;
     private particleStateTextures;
@@ -482,12 +631,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 +650,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;
@@ -564,6 +711,8 @@ 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;
     setScalarMode(v: boolean): void;
     setRgba8MaxParticleZoom(v: number): void;
     /**
@@ -599,6 +748,7 @@ export declare interface ParticleSimulationDebugInfo {
     opacity: number;
     logScale: boolean;
     vibrance: number;
+    colorGrade: ColorGrade;
     scalarMode: boolean;
     devicePixelRatio?: number;
     webgl: WebGLRendererInfo | null;
@@ -608,6 +758,17 @@ export declare type ParticleStateKind = StateTextureFormat["kind"];
 
 export declare type ParticleStateMode = "auto" | "rgba8";
 
+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 +783,14 @@ export declare interface QueryPointOptions {
     maxPoints?: number;
 }
 
-export declare type RenderMode = 'raster' | 'particles' | 'raster+particles';
+export declare type RenderMode = "raster" | "particles" | "raster+particles";
+
+/**
+ * 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 +824,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 +912,8 @@ declare interface SimulationParams {
     opacity: number;
     logScale: boolean;
     vibrance: number;
+    /** Grade of the trail composite; off by default. */
+    colorGrade: ColorGrade;
     scalarMode: boolean;
     particleState: ParticleStateMode;
     rgba8MaxParticleZoom: number;
@@ -829,8 +999,26 @@ export declare interface VariableMeta {
     units?: string;
 }
 
+/**
+ * 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 +1052,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 +1064,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 +1091,7 @@ export declare class VectorLayer implements CustomLayerInterface {
     setOpacity(v: number): void;
     setLogScale(v: boolean): void;
     setVibrance(v: number): void;
+    setColorGrade(grade: Partial<ColorGrade>): 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 +1115,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 +1140,11 @@ 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>;
     unit?: string;
 }
 
@@ -995,7 +1190,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 +1396,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,7 +1410,19 @@ 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;
     private colorDomainOverridden;
     private paletteOverridden;
@@ -1224,6 +1435,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;
@@ -1240,9 +1454,23 @@ export declare class Zartigl {
     constructor(options: ZartiglOptions);
     init(): Promise<void>;
     update(change: 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 +1478,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,9 +1524,14 @@ 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;
     getDebugInfo(): ZartiglDebugInfo;
@@ -1285,10 +1539,66 @@ export declare class Zartigl {
     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 +1639,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 +1654,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 {
@@ -1376,6 +1693,11 @@ 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>;
     /** Fixed physical-value domain for scalar colors. Null uses frame extrema. */
     colorDomain: [number, number] | null;
     particleState: ParticleStateMode;