@fxi/zartigl 0.14.0 → 0.14.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/explorer/`, `src/demo-story/` | Catalog explorer and narrative story, deployed to GitHub Pages |
+| Demos | `src/explorer/`, `src/demo-story/`, `src/cube/` | Catalog explorer, narrative story and the GODAS thermocline data-cube, deployed to GitHub Pages |
 | MapX integration | `src/mapx/` | Widget and standalone snippet generation for reproducible MapX views |
 
 ## Features
@@ -214,6 +214,22 @@ npm run dev:story
 npm run build:story
 ```
 
+The Pacific Thermocline Data-Cube (`src/cube/`) explores the monthly GODAS
+ocean temperature of the equatorial Pacific (120° E–80° W, 14.5° S–15° N,
+0–300 m) since 1980 as an interactive cube, at
+[`fxi.io/zartigl/cube`](https://fxi.io/zartigl/cube/). It provides:
+- slice planes and 2D sections;
+- the 20 °C isotherm;
+- a Niño 3.4 timeline.
+
+It reads five-year blocks of the catalog entry's point-series store, about
+42 MB each. `#t=YYYY-MM` opens a month.
+
+```bash
+npm run dev:cube
+npm run build:cube
+```
+
 The demos read the built-in catalog, which points to public browser-accessible Zarr, WMTS, and GeoVideo sources. No local data download is needed; data is fetched directly from the selected source.
 
 ## Public API

package/dist/catalog.d.ts

@@ -29,6 +29,8 @@ export declare interface CatalogEntry {
     aliases?: string[];
     title: LocalizedText;
     description?: LocalizedText;
+    /** Methodology and sources: an immutable page published with the catalog. */
+    documentation?: string;
     category: string;
     tags?: string[];
     kind: "scalar" | "vector";
@@ -62,6 +64,21 @@ export declare interface CatalogGeoVideoSource extends CatalogSourceBase {
     indexUrl?: never;
 }
 
+/**
+ * A link of a catalog entry, found by UUID or alias: its methodology page
+ * (`documentation`), its Zarr stores (`field`, `pointSeries`) or its GeoVideo
+ * index or manifest (`geovideo`). Undefined when the entry or the link does
+ * not exist. `pointSeries` comes from the entry's query source first, the
+ * other links from its default source first; then any source of the kind.
+ *
+ * Pass the live catalog (`(await loadCatalog()).catalog`) rather than the
+ * bundled one, so links follow the catalog when objects move.
+ */
+export declare function catalogLink(layer: string, kind: CatalogLinkKind, data?: Catalog): string | undefined;
+
+/** The links a catalog entry can resolve to; see `catalogLink`. */
+export declare type CatalogLinkKind = "documentation" | "field" | "pointSeries" | "geovideo";
+
 export declare interface CatalogSearchOptions {
     locale?: string;
     category?: string;

package/dist/catalog.js

@@ -1,4 +1,4 @@
-import { C as s, L as r, P as t, h as o, R as l, i, j as y, g as L, k as S, l as E, n as c, o as g, q as T, t as d, m, a as n, p as C, e as R, d as _, u as f, v as p, r as A, w as v, c as Y, x as u, b as P, s as k } from "./index-Cd7Nk4ve.js";
+import { C as s, L as r, P as t, h as o, R as l, i, j as y, k as L, g as S, l as E, n as c, o as g, q as n, t as T, u as d, m, a as C, p as R, e as _, d as f, v as p, w as A, r as v, x as Y, c as u, y as P, b as k, s as x } from "./index-B1lj-XR_.js";
 export {
   s as CATALOG_URL,
   r as LAYER_STYLE_DEFAULTS,
@@ -6,25 +6,26 @@ export {
   o as PROVIDER_LABELS,
   l as RASTER_STYLE_KEYS,
   i as catalog,
-  y as compareVersions,
-  L as diffStyle,
-  S as entryHeader,
-  E as findCatalogEntries,
-  c as formatTime,
-  g as formatVertical,
+  y as catalogLink,
+  L as compareVersions,
+  S as diffStyle,
+  E as entryHeader,
+  c as findCatalogEntries,
+  g as formatTime,
+  n as formatVertical,
   T as getCatalogEntry,
   d as loadCatalog,
   m as mergeStyles,
-  n as migrateLegacyStyle,
-  C as parseLayerStyle,
-  R as pickPreferredSource,
-  _ as pickSourceByPriority,
-  f as providerLabel,
-  p as requireCatalogEntry,
-  A as resolveEntryStyle,
-  v as resolveLayerStyle,
-  Y as resolveLocalizedText,
-  u as searchCatalog,
-  P as sourceCoversTime,
-  k as styleForKind
+  C as migrateLegacyStyle,
+  R as parseLayerStyle,
+  _ as pickPreferredSource,
+  f as pickSourceByPriority,
+  p as providerLabel,
+  A as requireCatalogEntry,
+  v as resolveEntryStyle,
+  Y as resolveLayerStyle,
+  u as resolveLocalizedText,
+  P as searchCatalog,
+  k as sourceCoversTime,
+  x as styleForKind
 };

package/dist/{engine-CiDquHYk.js → engine-C8ZNzILO.js}

@@ -1716,7 +1716,7 @@ class Xt {
     if (!e)
       return null;
     const i = this.gl, r = this.gridTexture();
-    return this.options.repeatLongitude === !1 && (i.texParameteri(i.TEXTURE_2D, i.TEXTURE_MIN_FILTER, i.NEAREST), i.texParameteri(i.TEXTURE_2D, i.TEXTURE_MAG_FILTER, i.NEAREST)), i.pixelStorei(i.UNPACK_ALIGNMENT, 1), i.texImage2D(
+    return this.options.nearestMask && (i.texParameteri(i.TEXTURE_2D, i.TEXTURE_MIN_FILTER, i.NEAREST), i.texParameteri(i.TEXTURE_2D, i.TEXTURE_MAG_FILTER, i.NEAREST)), i.pixelStorei(i.UNPACK_ALIGNMENT, 1), i.texImage2D(
       i.TEXTURE_2D,
       0,
       i.R8,
@@ -2015,7 +2015,7 @@ class Si {
   }
   createField(e) {
     const i = new Xt(this.gl, e, {
-      repeatLongitude: !1,
+      nearestMask: !0,
       animateSnapshot: !0,
       onError: (r) => {
         this.field === i && !this.seeking && this.reportError(r);

package/dist/engine.d.ts

@@ -43,6 +43,8 @@ declare interface CatalogEntry {
     aliases?: string[];
     title: LocalizedText;
     description?: LocalizedText;
+    /** Methodology and sources: an immutable page published with the catalog. */
+    documentation?: string;
     category: string;
     tags?: string[];
     kind: "scalar" | "vector";
@@ -130,6 +132,42 @@ declare interface CatalogZarrSource extends CatalogSourceBase {
     variables: CatalogVariables;
 }
 
+/**
+ * A persistent store of Zarr chunks, as the compressed bytes the server sent,
+ * in the browser's Cache Storage. ZarrSource reads it before the network when
+ * given one (opt-in), so an app opens the chunks of a past session at once.
+ *
+ * Chunks of the to_zarr stores never change once written, except those of the
+ * last time chunk, which grows as months are appended. Those carry a revision
+ * (the length of the time axis): a stored chunk of another revision is stale
+ * and is read again, then replaced under the same key. A new store version has
+ * new URLs, so it never meets the chunks of the previous one.
+ */
+/** A stored chunk, without its bytes. */
+declare interface ChunkEntry {
+    url: string;
+    /** Bytes on disk (compressed). */
+    size: number;
+    /** When the chunk was stored, ms since the epoch. */
+    storedAt: number;
+    revision: string;
+}
+
+declare interface ChunkStore {
+    /** The bytes of `url`, or undefined when missing or of another revision. */
+    get(url: string, revision?: string): Promise<Uint8Array | undefined>;
+    put(url: string, bytes: Uint8Array, revision?: string): Promise<void>;
+    /** Every stored chunk whose URL starts with `prefix`. */
+    entries(prefix?: string): Promise<ChunkEntry[]>;
+    /** Removes these chunks. */
+    delete(urls: Iterable<string>): Promise<void>;
+    /** Origin storage use and quota, bytes, when the browser reports them. */
+    estimate(): Promise<{
+        usage: number;
+        quota: number;
+    } | undefined>;
+}
+
 /**
  * `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.
@@ -498,8 +536,13 @@ export declare class GeoVideoField {
 }
 
 export declare interface GeoVideoFieldOptions {
-    /** Repeat global grids in longitude; false for an inset MapLibre grid. */
+    /**
+     * Repeat global grids in longitude, so a mesh closed to a full turn
+     * blends their last column into the first one; false for an inset grid.
+     */
     repeatLongitude?: boolean;
+    /** Sample the validity mask NEAREST, as zartigl's mask threshold expects. */
+    nearestMask?: boolean;
     /** Play the media frames of a single-date snapshot; times then follow its media cadence. */
     animateSnapshot?: boolean;
     onError?: (error: unknown) => void;
@@ -1264,7 +1307,18 @@ declare class ZarrSource {
     private maxCacheSize;
     private abortControllers;
     private bloscCodecCache;
-    constructor(root: string, maxCacheSize?: number);
+    private chunkStore;
+    /**
+     * `options.chunkStore` keeps the compressed chunks across sessions (see
+     * chunkStore.ts); without it, chunks are only kept in memory.
+     */
+    constructor(root: string, maxCacheSize?: number, options?: {
+        chunkStore?: ChunkStore;
+    });
+    /** The URL of a chunk, as fetched and as stored. */
+    chunkUrl(variable: string, indices: number[]): string;
+    /** The revision a stored chunk must carry to be current (see chunkRevision). */
+    chunkRevision(variable: string, indices: number[]): string;
     init(): Promise<void>;
     private getArrayMeta;
     private getAttrs;

package/dist/engine.js

@@ -1,4 +1,4 @@
-import { Q as o, R as s, G as r, S as d, j as i, U as t, V as G, W as c, X as l, Y as V, n, Z as S, _ as L, $ as C, T as u, a0 as m, a1 as O, a2 as _, a3 as p, b as R, a4 as A, c as T, a5 as g, a6 as I, o as h, D as k, M as x, a7 as f, N as v, q as D, z as F, w as E, H as B, L as b, p as N, I as P, a8 as y, a9 as M, aa as W, ab as U, t as H, ac as Y, ad as j, ae as q, J as w, af as z, ag as J, P as K, v as Q, ah as X } from "./engine-CiDquHYk.js";
+import { Q as o, R as s, G as r, S as d, j as i, U as t, V as G, W as c, X as l, Y as V, n, Z as S, _ as L, $ as C, T as u, a0 as m, a1 as O, a2 as _, a3 as p, b as R, a4 as A, c as T, a5 as g, a6 as I, o as h, D as k, M as x, a7 as f, N as v, q as D, z as F, w as E, H as B, L as b, p as N, I as P, a8 as y, a9 as M, aa as W, ab as U, t as H, ac as Y, ad as j, ae as q, J as w, af as z, ag as J, P as K, v as Q, ah as X } from "./engine-C8ZNzILO.js";
 import { B as $, a as aa, f as ea, b as oa, e as sa, c as ra, g as da, i as ia, r as ta, d as Ga } from "./backdrop-Dceb4d8E.js";
 export {
   $ as BACKDROP_OFF,