@fxi/zartigl 0.10.0 → 0.10.2

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

package/dist/catalog.d.ts

@@ -21,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[];
@@ -129,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;
 
@@ -174,6 +180,29 @@ export declare interface LayerStyleInput {
     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>;
 
 /**
@@ -206,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. */
@@ -246,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 {