@fxi/zartigl 0.9.3 → 0.10.1

package/README.md

@@ -24,7 +24,7 @@ ARCO layers of [MapX](https://app.mapx.org).
 | Runtime library | `src/lib/` | `@fxi/zartigl`: the `Zartigl` facade, Zarr/WMTS/GeoVideo layers, shaders, particle simulation, point queries |
 | Catalog | `src/catalog/`, `scripts/catalog_builder/` | `@fxi/zartigl/catalog` presets and the tools that discover, describe, and validate entries |
 | GeoVideo pipeline | `scripts/geovideo/`, `.github/workflows/geovideo.yml` | Single renders and incremental archives published to S3, rendered daily on a self-hosted runner |
-| Demos | `src/demo-prod/`, `src/demo-story/` | Technical demo and narrative story, deployed to GitHub Pages |
+| Demos | `src/explorer/`, `src/demo-story/` | Catalog explorer and narrative story, deployed to GitHub Pages |
 | MapX integration | `src/mapx/` | Widget and standalone snippet generation for reproducible MapX views |
 
 ## Features
@@ -103,6 +103,7 @@ the MapX `ArcoMapLegend` and the snippets the demo exports.
 ```jsonc
 {
   "palette": "thermal",
+  "reversePalette": false,
   "renderMode": "particles", // or "raster", "raster+particles"
   "particles": {
     "density": 0.03,
@@ -111,10 +112,36 @@ the MapX `ArcoMapLegend` and the snippets the demo exports.
     "grade": "vibrant",
     "backdrop": { "enabled": true, "color": "#000000", "opacity": 0.3 }
   },
-  "raster": { "opacity": 0.9, "logScale": false, "vibrance": 0.2, "colorDomain": null }
+  "raster": {
+    "opacity": 0.9, "logScale": false, "vibrance": 0.2, "colorDomain": null,
+    "alphaFadeLow": 0, "alphaFadeHigh": 0, "alphaFadeCurve": "linear"
+  }
 }
 ```
 
+`reversePalette` runs the palette from its last color to its first, for the
+raster and the particles.
+
+`raster.alphaFadeLow` and `alphaFadeHigh` make the ends of the color range
+transparent, with any palette. Each is a fraction of the range as displayed
+(the color domain, after log scale): `alphaFadeLow: 0.25` fades the lowest
+quarter in from transparent, `alphaFadeHigh: 0.5` fades the upper half out,
+and values beyond the domain take its transparent ends. A field that is
+mostly zero, such as fire radiative power or coral heat stress, then shows
+only where something happens. `alphaFadeCurve` shapes both fades, with the
+curves of `logScale`: `"linear"`, `"log"` (`log10(1 + 9x)`, rises fast) or
+`"exp"` (its inverse, stays faint longer, which also hides codec noise at the
+ends of a GeoVideo). The fade is part of the color ramp
+(`resolveColorRamp(palette, { reverse, alphaFade })`), so Zarr, GeoVideo,
+projversor and legends show the same transparency. Neither key changes how
+GeoVideo archives are encoded, so restyling never re-renders them.
+
+`heat-alert`, which faded low values in through transparent palette stops, is
+deprecated: `migrateLegacyStyle` reads it as `heat` with `alphaFadeLow: 0.25`
+(the closest fit of its alpha), wherever a style enters, so old catalogs,
+share links and story views keep working. `getPalettes()` leaves deprecated
+palettes out of pickers.
+
 `particles.grade` is `"off"`, `"vibrant"`, or a tuned vibrant grade
 `{ exposure, contrast, saturation, highlights }`; it is replaced as a whole.
 

package/dist/catalog.d.ts

@@ -1,3 +1,6 @@
+/** Shape of an alpha fade inside its zone; the same curves as `logScale`. */
+export declare type AlphaFadeCurve = "linear" | "log" | "exp";
+
 /**
  * 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
@@ -18,6 +21,9 @@ export declare interface Catalog {
 
 export declare const catalog: Catalog;
 
+/** Live catalog of schema 2; a schema 3 would publish under `v3/`. */
+export declare const CATALOG_URL = "https://sos-ch-gva-2.exo.io/mapx-zartigl/catalog/v2/catalog.json";
+
 export declare interface CatalogEntry {
     id: string;
     aliases?: string[];
@@ -126,6 +132,9 @@ export declare interface CatalogZarrSource extends CatalogSourceBase {
     variables: CatalogVariables;
 }
 
+/** -1, 0 or 1 as `a` is older than, equal to or newer than `b` (x.y.z). */
+export declare function compareVersions(a: string, b: string): number;
+
 /** The keys of `style` whose value differs from `base`'s. */
 export declare function diffStyle(style: LayerStyleInput, base: LayerStyle): LayerStyleInput;
 
@@ -155,6 +164,8 @@ export declare const LAYER_STYLE_DEFAULTS: Readonly<LayerStyle>;
 export declare interface LayerStyle {
     /** Palette id; undefined lets the engine pick its own. */
     palette?: string;
+    /** Run the palette from its last color to its first, for raster and particles. */
+    reversePalette: boolean;
     renderMode: StyleRenderMode;
     particles: ParticleStyle;
     raster: RasterStyle;
@@ -163,11 +174,35 @@ export declare interface LayerStyle {
 /** A partial style: any key left out takes the value below it. */
 export declare interface LayerStyleInput {
     palette?: string;
+    reversePalette?: boolean;
     renderMode?: StyleRenderMode;
     particles?: ParticleStyleInput;
     raster?: Partial<RasterStyle>;
 }
 
+/**
+ * The live catalog, or `fallback` (the bundled catalog) when it cannot be
+ * fetched or is not a schema 2 catalog. A catalog that needs a newer engine
+ * still loads, with a warning: its new style keys degrade, they do not fail.
+ */
+export declare function loadCatalog(url?: string, options?: LoadCatalogOptions): Promise<LoadedCatalog>;
+
+export declare interface LoadCatalogOptions {
+    /** Give up on the live catalog after this delay. */
+    timeoutMs?: number;
+    /** Used when the live catalog cannot be read; the bundled one by default. */
+    fallback?: Catalog;
+    /** Where warnings go; console.warn by default. */
+    warn?: (message: string) => void;
+    /** For tests: the fetch to use. */
+    fetch?: typeof fetch;
+}
+
+export declare interface LoadedCatalog {
+    catalog: Catalog;
+    source: "remote" | "bundled";
+}
+
 export declare type LocalizedText = Record<string, string>;
 
 /**
@@ -176,6 +211,14 @@ export declare type LocalizedText = Record<string, string>;
  */
 export declare function mergeStyles(...inputs: (LayerStyleInput | undefined)[]): LayerStyleInput;
 
+/**
+ * `input` with legacy palettes rewritten, so old catalogs, share links and
+ * story views keep their look. Keys the input sets itself win.
+ */
+export declare function migrateLegacyStyle(input: LayerStyleInput): LayerStyleInput;
+
+export declare function migrateLegacyStyle(input: LayerStyleInput | undefined): LayerStyleInput | undefined;
+
 /**
  * Validate a style, throwing an error that names the offending path, e.g.
  * `views.swell.config.style.particles.density must be a number in (0, 0.2]`.
@@ -192,6 +235,14 @@ export declare interface ParseLayerStyleOptions {
         particles?: readonly (keyof ParticleStyle)[];
         raster?: readonly (keyof RasterStyle)[];
     };
+    /**
+     * Keys that are not style keys at all: "throw" (default), or "drop" them
+     * with a warning, so a style written for a newer engine still renders with
+     * an older one. Invalid values of known keys always throw.
+     */
+    unknownKeys?: "throw" | "drop";
+    /** Where dropped keys are reported; console.warn by default. */
+    warn?: (message: string) => void;
 }
 
 /** Style keys, for checks against other definitions of the same shape. */
@@ -232,6 +283,11 @@ export declare function pickPreferredSource(entry: CatalogEntry, request?: Sourc
  */
 export declare function pickSourceByPriority(entry: CatalogEntry, priority: readonly CatalogSource["type"][], request?: SourceTimeRequest): CatalogSource | undefined;
 
+/** A published catalog: the catalog plus the oldest engine that renders it all. */
+export declare type PublishedCatalog = Catalog & {
+    minEngine?: string;
+};
+
 export declare const RASTER_STYLE_KEYS: (keyof RasterStyle)[];
 
 export declare interface RasterStyle {
@@ -241,6 +297,17 @@ export declare interface RasterStyle {
     vibrance: number;
     /** Fixed physical-value domain; null follows the data. */
     colorDomain: [number, number] | null;
+    /**
+     * Fraction of the color range, from its low end, over which colors fade in
+     * from transparent, [0, 1]: a field that is mostly zero (fires, heat
+     * stress) shows only where something happens. Values below the domain are
+     * transparent too.
+     */
+    alphaFadeLow: number;
+    /** Fraction of the color range, from its high end, fading out, [0, 1]. */
+    alphaFadeHigh: number;
+    /** Shape of both fades: "log" rises fast, "exp" stays faint longer. */
+    alphaFadeCurve: AlphaFadeCurve;
 }
 
 export declare function requireCatalogEntry(id: string, data?: Catalog): CatalogEntry;
@@ -284,11 +351,6 @@ export declare interface StyledEntry {
 /** `style` without the keys a layer of `kind` cannot draw. */
 export declare function styleForKind(style: LayerStyleInput, kind: StyledEntry["kind"] | undefined): LayerStyleInput;
 
-/**
- * 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.
- */
 export declare type StyleRenderMode = "particles" | "raster" | "raster+particles";
 
 export { }