@fxi/zartigl 0.5.0 → 0.7.0

package/dist/engine.d.ts

@@ -0,0 +1,918 @@
+/** Throws unless the index was written for this catalog entry and source. */
+export declare function assertGeoVideoIndexIdentity(source: CatalogGeoVideoArchiveSource, index: GeoVideoIndex, entry: CatalogEntry): void;
+
+/** 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;
+}
+
+/**
+ * `u_solid` uniform: straight RGB in [0, 1] and opacity. Alpha is 0 when the
+ * backdrop is off, which also skips the draw.
+ */
+export declare function backdropVec4(backdrop: BackdropStyle): [number, number, number, number];
+
+declare interface CatalogEntry {
+    id: string;
+    aliases?: string[];
+    title: LocalizedText;
+    description?: LocalizedText;
+    category: string;
+    tags?: string[];
+    kind: "scalar" | "vector";
+    sources: CatalogSource[];
+    /** Default source, plus the layer's base style. */
+    defaults: LayerStyleInput & {
+        sourceId: string;
+        querySourceId?: string;
+    };
+}
+
+/**
+ * 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 CatalogSource = CatalogZarrSource | CatalogWmtsSource | CatalogGeoVideoSource | CatalogGeoVideoArchiveSource;
+
+declare interface CatalogSourceBase {
+    id: string;
+    title: LocalizedText;
+    provenance?: CatalogSourceProvenance;
+    temporal?: CatalogTemporalSummary;
+}
+
+declare interface CatalogSourceProvenance {
+    provider: string;
+    identifiers?: Record<string, string>;
+}
+
+declare interface CatalogTemporalSummary {
+    cadence?: string;
+    mode: "historical" | "near-real-time" | "analysis-forecast" | "fixed";
+    start?: string;
+    end?: string;
+}
+
+declare type CatalogVariables = {
+    kind: "scalar";
+    value: string;
+} | {
+    kind: "vector";
+    u?: string;
+    v?: string;
+    derivation?: CatalogVectorDerivation;
+};
+
+declare interface CatalogVectorDerivation {
+    kind: "direction_magnitude";
+    direction_variable: string;
+    magnitude_variable: string;
+    direction_convention: "from" | "toward";
+    output_direction: "from" | "toward";
+}
+
+declare interface CatalogWmtsSource extends CatalogSourceBase {
+    type: "wmts";
+    capabilitiesUrl: string;
+    baseUrl?: string;
+    layer: string;
+    tileMatrixSet?: string;
+    format?: string;
+    style?: string;
+    tileUrlTemplate?: string;
+}
+
+declare interface CatalogZarrSource extends CatalogSourceBase {
+    type: "zarr";
+    endpoints: {
+        field: string;
+        pointSeries?: string;
+    };
+    variables: CatalogVariables;
+}
+
+/**
+ * `vec3 gradeColor(vec3 c, vec4 g)` of `colorGradeVec4`; GLSL ES 1.0 and
+ * 3.0. It contains VIBRANCE_GLSL: include one or the other, never both.
+ */
+export declare const COLOR_GRADE_GLSL: string;
+
+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;
+
+/** `u_grade` uniform: (exposure, contrast, saturation, highlights). */
+export declare function colorGradeVec4(grade: ColorGrade): [number, number, number, number];
+
+export declare type ColorRampInput = string | string[] | Record<number, string>;
+
+declare interface CoordArrays {
+    time: Float64Array | Float32Array;
+    vertical: Float32Array;
+    latitude: Float32Array;
+    longitude: Float32Array;
+}
+
+export declare function createColorRampTexture(gl: WebGL2RenderingContext, ramp?: ColorRampInput): WebGLTexture;
+
+/** The frame source decoding `manifest`: scalar or vector by its encoding. */
+export declare function createGeoVideoFrameSource(manifest: GeoVideoManifest, options?: {
+    cacheSize?: number;
+}): GeoVideoScalarSource | GeoVideoVectorSource;
+
+export declare function createProgram(gl: WebGL2RenderingContext, vertSource: string, fragSource: string): WebGLProgram;
+
+export declare function createShader(gl: WebGL2RenderingContext, type: number, source: string): WebGLShader;
+
+/** Trail length in frames for a 0–1 `fade`. */
+export declare function fadeToFrames(fade: number): number;
+
+/** Per-frame trail opacity multiplier for a 0–1 `fade`. */
+export declare function fadeToOpacity(fade: number): number;
+
+/**
+ * One immutable chunk of a GeoVideo archive, independent of the catalog: a
+ * manifest and the range of its encoded samples.
+ */
+export declare interface GeoVideoArchiveChunk extends GeoVideoChunkSpan {
+    /** Stable identity of the chunk content (the index chunk key). */
+    key: string;
+    /** Absolute manifest URL. */
+    manifestUrl: string;
+    /** Encoded samples, when the index lists them. */
+    samples?: number;
+    provisional?: boolean;
+}
+
+/** One decoded time step of an archive. */
+export declare interface GeoVideoArchiveFrame<TFrame = GeoVideoFrameData> {
+    /** Stable identity: archive id, chunk key and step. */
+    key: string;
+    chunk: GeoVideoArchiveChunk;
+    /** Step within the chunk. */
+    step: number;
+    time: number;
+    data: TFrame;
+    grid: GeoVideoGrid;
+    manifest: GeoVideoManifest;
+}
+
+/**
+ * The frames bracketing a time, possibly from two chunks: display
+ * a·(1 − mix) + b·mix. `b` is `a` with mix 0 in discrete mode or on a step.
+ */
+export declare interface GeoVideoArchiveSample<TFrame = GeoVideoFrameData> {
+    time: number;
+    a: GeoVideoArchiveFrame<TFrame>;
+    b: GeoVideoArchiveFrame<TFrame>;
+    mix: number;
+}
+
+/**
+ * Several chunks of a GeoVideo archive as one continuous timeline. Every
+ * sample request is independent: aborting one leaves the decodes another
+ * request needs. Manifests are cached; chunk sources are kept open in a
+ * bounded LRU and released when evicted. The archive answers instants; it
+ * neither drives a clock nor picks other archives (see pairChunkSpan).
+ */
+export declare class GeoVideoArchiveSource<TFrame = GeoVideoFrameData> {
+    readonly id: string;
+    /** Chunks sorted by start, without empty ranges. */
+    readonly chunks: readonly GeoVideoArchiveChunk[];
+    private readonly maxOpenChunks;
+    private readonly frameCacheSize;
+    private readonly prefetchAt;
+    private readonly maxGap;
+    private readonly loadManifest;
+    private readonly createFrameSource;
+    private readonly manifests;
+    private readonly open;
+    constructor(options: GeoVideoArchiveSourceOptions<TFrame>);
+    /** First and last sample of the archive, or null without chunks. */
+    get range(): [number, number] | null;
+    /** The chunk whose sample range holds `time`, or null. */
+    chunkAt(time: number): GeoVideoArchiveChunk | null;
+    /** Every step time of the archive; loads all chunk manifests. */
+    steps(request?: GeoVideoFrameRequest): Promise<Float64Array>;
+    /**
+     * The frames bracketing `time`, decoded; null out of coverage (before the
+     * first step, after the last, or in a gap wider than `maxGap`).
+     */
+    sample(time: number, request?: GeoVideoFrameRequest & {
+        mode?: GeoVideoSampleMode;
+    }): Promise<GeoVideoArchiveSample<TFrame> | null>;
+    /** Open `chunk` and decode its first frame ahead of a request. */
+    prefetch(chunk: GeoVideoArchiveChunk): void;
+    /** Release every open chunk source; later requests reopen them. */
+    release(): void;
+    private chunkIndexAt;
+    private gapLimit;
+    private prefetchAfter;
+    private manifest;
+    /** The open chunk, pinned for a running sample listed in `used`. */
+    private acquire;
+    /** The open chunk, opened when needed, most recently used; not pinned. */
+    private touch;
+    private frame;
+    /** Release least recently used chunks beyond the bound, unless in use. */
+    private trim;
+    private close;
+}
+
+export declare interface GeoVideoArchiveSourceOptions<TFrame> {
+    /** Archive identity, the prefix of every frame key. */
+    id: string;
+    chunks: readonly GeoVideoArchiveChunk[];
+    /** Chunk sources kept open (decoder, video element); at least 2. */
+    maxOpenChunks?: number;
+    /** Decoded frames cached per chunk source. */
+    frameCacheSize?: number;
+    /**
+     * Progress through a chunk past which the next chunk is opened and its
+     * first frame decoded; above 1 disables prefetching.
+     */
+    prefetchAt?: number;
+    /**
+     * Longest gap bridged between the last step of a chunk and the first of
+     * the next one, in ms. By default 1.5 times the largest step interval at
+     * that boundary, and no bridge when both neighbouring chunks hold a
+     * single step (no cadence known). Unbridged gaps are out of coverage.
+     */
+    maxGap?: number;
+    loadManifest?: (url: string) => Promise<GeoVideoManifest>;
+    createFrameSource?: (manifest: GeoVideoManifest, options: {
+        cacheSize: number;
+    }) => GeoVideoFrameReader<TFrame>;
+}
+
+export declare type GeoVideoBounds = [
+west: number,
+south: number,
+east: number,
+north: number
+];
+
+/**
+ * Fixed-period GeoVideo sources, one per chunk. They keep the archive source
+ * id, which the chunk manifests carry as their identity.
+ */
+export declare function geoVideoChunkSources(source: CatalogGeoVideoArchiveSource, index: GeoVideoIndex, entry: CatalogEntry): CatalogGeoVideoSource[];
+
+/** First and last encoded sample of a chunk, UTC milliseconds. */
+export declare interface GeoVideoChunkSpan {
+    start: number;
+    end: number;
+}
+
+/** Scalar values (NaN invalid) or u/v components (NaN invalid). */
+export declare type GeoVideoFrameData = Float32Array | GeoVideoVectorFrame;
+
+/** The part of a frame source an archive reads. */
+export declare interface GeoVideoFrameReader<TFrame> {
+    frame(index: number, request?: GeoVideoFrameRequest): Promise<TFrame>;
+    release(): void;
+}
+
+/** Options of one frame request. */
+export declare interface GeoVideoFrameRequest {
+    /** Abandons this request only; the decode stops once no request needs it. */
+    signal?: AbortSignal;
+}
+
+/**
+ * GeoVideo frames read one time step at a time (seek, no playback): video
+ * and static mask loading, luma readback, a serial decode queue, and a small
+ * LRU cache of decoded frames. Requests for the same step share one decode;
+ * each can be abandoned with its own signal, and the decode is dropped once
+ * no request waits for it. cancelAll() aborts every pending decode.
+ * Subclasses turn the luma codes of a frame into values.
+ */
+export declare abstract class GeoVideoFrameSource<TFrame> {
+    /** Grid size; the video stacks `planes` grids vertically. */
+    readonly width: number;
+    readonly height: number;
+    protected readonly manifest: GeoVideoManifest;
+    protected readonly times: Float64Array;
+    private readonly planes;
+    private readonly cacheSize;
+    private readonly reader;
+    private video;
+    private mask;
+    private initPromise;
+    private presented;
+    private primed;
+    /** Serializes seeks: the previous decode, settled or not, runs first. */
+    private queue;
+    /** LRU of decoded and pending steps. */
+    private readonly frames;
+    /** Pending decodes, including those the LRU already evicted. */
+    private readonly pending;
+    constructor(manifest: GeoVideoManifest, planes: number, options?: {
+        cacheSize?: number;
+    });
+    /** Codes of the stacked planes and the per-cell mask to frame values. */
+    protected abstract decodeCodes(codes: Uint8Array, mask: Uint8Array, threshold: number): TFrame;
+    init(): Promise<void>;
+    /** Abort every pending frame decode; frames already decoded stay cached. */
+    cancelAll(): void;
+    /** Release the video element and GL context; a later init() reloads them. */
+    release(): void;
+    /**
+     * One decode per time step, cached and shared by concurrent requests.
+     * Aborting `request.signal` rejects this request with an AbortError; the
+     * decode goes on while another request waits for it.
+     */
+    frame(index: number, request?: GeoVideoFrameRequest): Promise<TFrame>;
+    private enqueue;
+    /** A request left; drop the decode when it was the last one waiting. */
+    private leave;
+    private drop;
+    private load;
+    private loadMask;
+    private loadVideo;
+    /** Seek to a frame and wait until it is presented. */
+    private presentFrame;
+    /**
+     * Some mobile browsers expose no decoded pixels to WebGL until playback
+     * started once. A muted play/pause primes the decoder, only when needed:
+     * playback would otherwise buffer far beyond the requested frame.
+     */
+    private primeDecoder;
+    /**
+     * Seek, read back and decode one step. `signal` aborts it between steps;
+     * a seek already started completes first, keeping the queue serial.
+     */
+    protected decode(index: number, signal: AbortSignal): Promise<TFrame>;
+}
+
+/**
+ * Grid of decoded frame values. `bounds` are the outer cell edges
+ * [west, south, east, north] in degrees, so cell (column i, row j) is
+ * centered at west + (i + 0.5)·dx, north − (j + 0.5)·dy with
+ * dx = (east − west) / width and dy = (north − south) / height; an east
+ * below west crosses the antimeridian (east + 360). Row 0 is the northern
+ * row, values are row-major.
+ */
+export declare interface GeoVideoGrid {
+    width: number;
+    height: number;
+    bounds: GeoVideoBounds;
+    rowOrder: "north-to-south";
+}
+
+export declare function geoVideoGrid(manifest: GeoVideoManifest): GeoVideoGrid;
+
+/** Mutable listing of an archive's published chunks, written by the renderer. */
+export declare interface GeoVideoIndex {
+    schemaVersion: 1;
+    type: "geovideo-index";
+    catalogEntryId: string;
+    sourceId: string;
+    updatedAt: string | null;
+    chunks: GeoVideoIndexChunk[];
+}
+
+/** One immutable, calendar-aligned artifact of a GeoVideo archive. */
+export declare interface GeoVideoIndexChunk {
+    period: {
+        start: string;
+        end: string;
+    };
+    /** First and last encoded sample. */
+    start: string;
+    end: string;
+    samples: number;
+    key: string;
+    /** Relative to the index URL. */
+    manifestUrl: string;
+    provisional?: boolean;
+}
+
+/**
+ * Catalog-free chunk descriptors of an index, manifest URLs resolved
+ * against the index URL, in index order.
+ */
+export declare function geoVideoIndexChunks(index: GeoVideoIndex, indexUrl: string): GeoVideoArchiveChunk[];
+
+export declare interface GeoVideoManifest {
+    schemaVersion: 3;
+    id: string;
+    type: "geovideo";
+    projection: "equirectangular";
+    bounds: GeoVideoBounds;
+    media: {
+        url: string;
+        mimeType: "video/mp4" | string;
+        width: number;
+        height: number;
+        fps: number;
+        durationSeconds: number;
+        codec: "h264" | string;
+    };
+    encoding: GeoVideoScalarEncoding | GeoVideoVectorEncoding;
+    mask: {
+        kind: "static-validity";
+        url: string;
+        mimeType: "image/png" | string;
+        width: number;
+        height: number;
+        threshold: number;
+    };
+    timeline: GeoVideoRangeTimeline | GeoVideoSnapshotLoopTimeline | GeoVideoSampleSequenceTimeline;
+    provenance: {
+        catalogEntryId: string;
+        inputSourceId: string;
+        provider?: string;
+        identifiers?: Record<string, string>;
+        variables: string[];
+        generatedAt: string;
+    };
+    style: {
+        palette: string;
+        colorDomain: [number, number];
+        unit?: string;
+        logScale?: boolean;
+        vibrance?: number;
+    };
+}
+
+declare interface GeoVideoRangeTimeline {
+    kind: "range";
+    dateStart: string;
+    dateEnd: string;
+    interpolation: "linear" | "nearest";
+}
+
+/** Interpolate between bracketing steps, or hold the last step at or before. */
+export declare type GeoVideoSampleMode = "interpolate" | "discrete";
+
+declare interface GeoVideoSampleSequenceTimeline {
+    kind: "sample-sequence";
+    values: string[];
+}
+
+export declare interface GeoVideoScalarEncoding {
+    kind: "scalar-luma";
+    bits: 8;
+    codeMin: number;
+    codeMax: number;
+    valueMin: number;
+    valueMax: number;
+    transfer: "linear";
+    colorSpace: "bt709";
+    colorRange: "limited" | "full";
+}
+
+/**
+ * Scalar-luma GeoVideo read frame by frame (seek, no playback), for values
+ * sampled on the GPU rather than the styled playback of GeoVideoLayer.
+ */
+export declare class GeoVideoScalarSource extends GeoVideoFrameSource<Float32Array> {
+    private readonly encoding;
+    constructor(manifest: GeoVideoManifest, options?: {
+        cacheSize?: number;
+    });
+    protected decodeCodes(codes: Uint8Array, mask: Uint8Array, threshold: number): Float32Array;
+}
+
+declare interface GeoVideoSnapshotLoopTimeline {
+    kind: "snapshot-loop";
+    date: string;
+}
+
+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).
+ */
+export 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";
+}
+
+/** Decoded u/v planes of one frame, NaN where the static mask is invalid. */
+export declare interface GeoVideoVectorFrame {
+    u: Float32Array;
+    v: Float32Array;
+}
+
+/**
+ * VectorLayer field source backed by a vector-luma GeoVideo: each time step is
+ * one video frame, decoded on demand (frame by frame, no playback) into a
+ * single chunk covering the whole grid.
+ */
+export declare class GeoVideoVectorSource extends GeoVideoFrameSource<GeoVideoVectorFrame> implements VectorFieldSource {
+    private readonly encoding;
+    private readonly coords;
+    constructor(manifest: GeoVideoManifest, options?: {
+        cacheSize?: number;
+    });
+    getValueDomain(): number;
+    getCoords(): {
+        time: Float64Array;
+        vertical: Float32Array;
+        latitude: Float32Array;
+        longitude: Float32Array;
+    };
+    getDimensions(): string[];
+    getChunkShape(): number[];
+    findDepthIndex(): number;
+    findTimeIndex(time: string | number): number;
+    getChunksForBounds(_variable: string, timeIdx: number, depthIdx: number): Array<{
+        timeIdx: number;
+        depthIdx: number;
+        latIdx: number;
+        lonIdx: number;
+        latRange: [number, number];
+        lonRange: [number, number];
+        latSize: number;
+        lonSize: number;
+    }>;
+    fetchSpatialChunkResult(variable: string, selection: {
+        timeIndex: number;
+    }): Promise<ZarrChunkFetchResult>;
+    protected decodeCodes(codes: Uint8Array, mask: Uint8Array, threshold: number): GeoVideoVectorFrame;
+}
+
+export declare function getPalettes(): PaletteMeta[];
+
+/** 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;
+}
+
+export declare function isGeoVideoArchiveSource(source: CatalogSource): source is CatalogGeoVideoArchiveSource;
+
+/** A `#rgb` or `#rrggbb` color. */
+export declare const isHexColor: (value: unknown) => value is string;
+
+/** A partial style: any key left out takes the value below it. */
+declare interface LayerStyleInput {
+    palette?: string;
+    renderMode?: StyleRenderMode;
+    particles?: ParticleStyleInput;
+    raster?: Partial<RasterStyle>;
+}
+
+export declare function loadGeoVideoIndex(url: string, signal?: AbortSignal): Promise<GeoVideoIndex>;
+
+export declare function loadGeoVideoManifest(source: string | GeoVideoManifest, signal?: AbortSignal): Promise<GeoVideoManifest>;
+
+declare type LocalizedText = Record<string, string>;
+
+/**
+ * The chunk of `current`'s archive that follows it inside `range`, or with
+ * `loop`, the first one inside it, with the time playback resumes at.
+ */
+export declare function nextChunk<T extends CatalogSource>(chunks: readonly T[], current: CatalogSource, options?: {
+    range?: readonly [number, number] | null;
+    loop?: boolean;
+}): {
+    source: T;
+    time: number;
+} | null;
+
+/**
+ * The chunk following the one that ends at `currentEnd` inside `range`, or
+ * with `loop`, the first one inside it, with the time playback resumes at.
+ */
+export declare function nextChunkSpan<T extends GeoVideoChunkSpan>(chunks: readonly T[], currentEnd: number, options?: {
+    range?: readonly [number, number] | null;
+    loop?: boolean;
+}): {
+    chunk: T;
+    time: number;
+} | null;
+
+/**
+ * The candidate whose sample range overlaps `chunk` the most: archives
+ * sampled at different hours (six-hourly from 00:00, daily at 12:00) still
+ * pair by calendar period. Null when none overlaps.
+ */
+export declare function pairChunk<T extends CatalogSource>(chunk: CatalogSource, candidates: readonly T[]): T | null;
+
+/**
+ * The candidate whose sample range overlaps `span` the most: archives
+ * sampled at different hours (six-hourly from 00:00, daily at 12:00) still
+ * pair by calendar period. Null when none overlaps.
+ */
+export declare function pairChunkSpan<T extends GeoVideoChunkSpan>(span: GeoVideoChunkSpan, candidates: readonly T[]): T | null;
+
+export declare interface PaletteMeta {
+    id: string;
+    label: string;
+    tags: string[];
+    colors: string[];
+}
+
+/** Particle trail color grade: a preset, or the vibrant one tuned. */
+declare type ParticleGrade = "off" | "vibrant" | GradeTuning;
+
+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>;
+};
+
+/** `float random(uvec3 v)`, an integer hash in [0, 1); GLSL ES 3.0. */
+export declare const RANDOM_GLSL: string;
+
+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;
+}
+
+/**
+ * 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;
+
+export declare function resolveColorRamp(input: ColorRampInput, options?: {
+    reverse?: boolean;
+}): Record<number, string>;
+
+export declare type ScalarColorDomain = [number, number];
+
+/**
+ * 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";
+
+/**
+ * Camera-aware per-frame fade opacity: eases toward a short retention while
+ * the camera moves, then back to the configured one. Smoothstep avoids
+ * visible slope changes at both ends.
+ */
+export declare class TrailFade {
+    private base;
+    private moving;
+    private from;
+    private to;
+    private start;
+    private duration;
+    constructor(base: number);
+    /** Configured opacity, applied at once unless the camera moves. */
+    setBase(base: number): void;
+    setMoving(moving: boolean, now: number): void;
+    value(now: number): number;
+}
+
+export declare function validateGeoVideoIndex(value: unknown): GeoVideoIndex;
+
+export declare function validateGeoVideoManifest(value: unknown): GeoVideoManifest;
+
+export declare function validateScalarColorDomain(domain: ScalarColorDomain | null): ScalarColorDomain | null;
+
+/**
+ * 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;
+};
+
+/** `vec3 applyVibrance(vec3 c, float v)`; GLSL ES 1.0 and 3.0. */
+export declare const VIBRANCE_GLSL: string;
+
+declare interface ZarrAttrs {
+    _ARRAY_DIMENSIONS?: string[];
+    units?: string;
+    standard_name?: string;
+    long_name?: string;
+    calendar?: string;
+    positive?: "up" | "down" | string;
+    [key: string]: unknown;
+}
+
+declare interface ZarrChunkFetchResult {
+    data: Float32Array;
+    missing: boolean;
+    status?: number;
+    url: string;
+}
+
+declare interface ZarrPointSample {
+    axisValue: number;
+    time?: number;
+    depth?: number;
+    values: Record<string, number>;
+}
+
+declare interface ZarrPointSeriesResult {
+    longitude: number;
+    latitude: number;
+    depth?: number;
+    time?: number;
+    points: ZarrPointSample[];
+}
+
+declare class ZarrSource {
+    private root;
+    private meta;
+    private coords;
+    private initPromise;
+    private verticalName;
+    private timeUnits;
+    private timeCalendar;
+    private cache;
+    private maxCacheSize;
+    private abortControllers;
+    private bloscCodecCache;
+    constructor(root: string, maxCacheSize?: number);
+    init(): Promise<void>;
+    private getArrayMeta;
+    private getAttrs;
+    getDimensionSeparator(variable: string): string;
+    getShape(variable: string): number[];
+    getChunkShape(variable: string): number[];
+    getCoords(): CoordArrays;
+    getTimeDimension(): ZarrTimeDimension;
+    getVerticalDimension(variable?: string): ZarrVerticalDimension | undefined;
+    hasVariable(variable: string): boolean;
+    getVariableAttrs(variable: string): ZarrAttrs;
+    getDimensions(variable: string): string[];
+    findNearestIndex(array: Float32Array | Float64Array, value: number): number;
+    findTimeIndex(time: string | number): number;
+    /**
+     * Convert a Unix-ms timestamp to the native time units used by this zarr
+     * (read from the time variable's .zattrs "units" field).
+     * Unsupported units are rejected during initialization rather than guessed.
+     */
+    private msToZarrTime;
+    private zarrTimeToMs;
+    private parseTimeEncoding;
+    private findNearestLongitudeIndex;
+    private sampleVariableAt;
+    private getFlatOffset;
+    findDepthIndex(depth: number): number;
+    sampleTimeSeries(options: {
+        variables: string[];
+        longitude: number;
+        latitude: number;
+        depth?: number;
+        timeStartIndex?: number;
+        timeEndIndex?: number;
+        stride?: number;
+        stopAfterMissingSamples?: number;
+    }): Promise<ZarrPointSeriesResult>;
+    sampleVerticalProfile(options: {
+        variables: string[];
+        longitude: number;
+        latitude: number;
+        time: string | number;
+        maxDepths?: number;
+        stride?: number;
+        stopAfterMissingSamples?: number;
+    }): Promise<ZarrPointSeriesResult>;
+    /** Return the actual name of the vertical dimension ("depth" or "elevation"). */
+    getVerticalDimName(): string;
+    /**
+     * Get chunk indices that intersect a geographic bounding box.
+     */
+    getChunksForBounds(variable: string, timeIdx: number, depthIdx: number, bounds: {
+        west: number;
+        south: number;
+        east: number;
+        north: number;
+    }): Array<{
+        timeIdx: number;
+        depthIdx: number;
+        latIdx: number;
+        lonIdx: number;
+        latRange: [number, number];
+        lonRange: [number, number];
+        latSize: number;
+        lonSize: number;
+    }>;
+    fetchChunk(variable: string, indices: number[]): Promise<Float32Array>;
+    /**
+     * Fetch one latitude/longitude chunk and extract the requested time/vertical
+     * plane from it. Logical coordinate indices are converted to physical Zarr
+     * chunk indices before fetching.
+     */
+    fetchSpatialChunkResult(variable: string, selection: {
+        timeIndex: number;
+        verticalIndex: number;
+        latitudeChunkIndex: number;
+        longitudeChunkIndex: number;
+    }): Promise<ZarrChunkFetchResult>;
+    fetchChunkResult(variable: string, indices: number[]): Promise<ZarrChunkFetchResult>;
+    cancelAll(): void;
+    private cacheChunk;
+    private getBloscCodec;
+    private decompress;
+    private loadCoordinates;
+}
+
+declare interface ZarrTimeDimension {
+    min: number;
+    max: number;
+    step?: number;
+    size: number;
+    units: string;
+    values: number[];
+}
+
+declare interface ZarrVerticalDimension {
+    name: string;
+    label: "depth" | "pressure" | string;
+    units?: string;
+    values: number[];
+}
+
+export { }