@oceanmetrics/engine 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+## 0.1.1 (2026-10-23)
+
+- Fix: `sliceSource().slice()` read the lobes' slabs without the `SELECT DISTINCT` that `runPreview` applies, so where two
+  places' boxes overlap (Channel Islands and Chumash) every cell of the overlap came back twice. Regression test with two
+  overlapping synthetic slabs.
+
+## 0.1.0 (2026-10-23)
+
+The browser engine, build week 2 step 2b: erddap-places' engine as a platform package, so the indicators Map's `grid`
+slot and the live preview run the same SQL as the Python engine (`om_extract`).
+
+- **Moved from erddap-places** (app 0.3.12): `gridMask` as `mask.ts` and `wkb.ts` byte for byte; `placeLobes` (now
+  `lobes.ts`, reading a `LobePlace`); `erddap.ts` (`griddapUrl`, `griddapSliceUrl`, `tabledapUrl`, `pickFormat`,
+  `fetchAxis`, `fetchSlab`, the constraint rules), `extent.ts`, `fetchRetry.ts` and `cells.ts` unchanged but for `.js`
+  specifiers; `catalog.ts`'s pure functions as `dataset.ts` (`toDataset`, `valueExpr`, `statsTemplate`, `lobeLonSpan`,
+  `resolveDataset` ...); the precompute's `window`, `chunks` and `chunkDaysFor` as `chunks.ts`, the two limits now options.
+- **The SQL templates** in `sql/` (`stats_daily`, `stats_categorical`, `last_step`, `stats_tabledap`,
+  `points_tabledap`), shipped as strings (`TEMPLATES`, generated by `scripts/sql-templates.mjs`), rendered by `render`.
+- **`Engine`** over DuckDB-WASM (a peer, >= 1.29): `registerBuffer`, `insertMask` (Arrow IPC), `insertRows`, `exec`,
+  `runTemplate`, `toParquet`, `dropFile`; the app passes `connect()`, and `connectBrowser(duckdb, bundles)` is the
+  browser boot. `toRows` scales DECIMAL columns (DuckDB-WASM returns them unscaled).
+- **The live preview**: `previewWindow`, `lobeAxes`, `lobeMasks`, `runPreview` (a chain of chunked griddap Parquet
+  requests, `onChunk` in time order, abortable) and `sliceSource` (a `SliceSource` for `@oceanmetrics/map`'s `gridSlot`).
+- Dependencies: turf 7.4.0 pinned (the parity fixtures record it); `@duckdb/duckdb-wasm` and `apache-arrow` as peers.
+- Size budget set from a measurement: 26 794 B gzip, budget 40 000 B.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ocean Metrics LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,195 @@
-# Temporary Holding Version
+# @oceanmetrics/engine
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The browser engine of Ocean Metrics: a live series for any polygon × ERDDAP grid. The place mask (which grid cells a
+polygon covers, with partial-area weights), the lobe split at ±180, the ERDDAP request URLs, the SQL templates shared
+with the Python engine (`om_extract`), DuckDB-WASM as the statistics engine, the chunked live preview and the map's grid
+slice. TypeScript, ESM.
+
+```ts
+import { Engine, connectBrowser, placeLobes, lobeAxes, runPreview, sliceSource, toDataset } from '@oceanmetrics/engine'
+```
+
+**One rule, two engines.** The browser (this package, DuckDB-WASM) and the precompute and extractions (`om_extract`,
+native DuckDB in Python) run the same mask arithmetic and the same SQL text, and the tests hold them to it: the mask
+reproduces the fixtures in `extract/tests/fixtures/mask/` row for row with `===`, and `sql/*.sql` are byte-identical to
+`om_extract/sql/` (see "Tests").
+
+**Consumers.** `indicators` is the first (build week 2 step 2c): its Map's `grid` slot reads `sliceSource()` and its
+live preview runs `runPreview()`. erddap-places' code is the frozen original: the app keeps its own copies of these
+modules until its redirect to indicators at the end of build week 2, and nothing here edits it.
+
+## What moved
+
+From `oceanmetrics/erddap-places` on 2026-10-23 (app 0.3.12, commit 3b1868a):
+
+| here | from | what changed |
+|---|---|---|
+| `src/mask.ts` | `app/src/lib/gridMask.ts` | nothing: byte for byte (its sha256 is the one the parity fixtures record) |
+| `src/wkb.ts` | `app/src/lib/wkb.ts` | nothing: byte for byte |
+| `src/lobes.ts` | `app/src/lib/gazetteer.ts` `placeLobes`, `Lobe` | `placeLobes()` word for word; it reads `LobePlace` (`place_id`, `geometry`), the slice of the gazetteer's `Place` it uses |
+| `src/erddap.ts` | `app/src/lib/erddap.ts` | `.js` import specifiers only |
+| `src/extent.ts` | `app/src/lib/extent.ts` | `.js` import specifiers only |
+| `src/fetchRetry.ts` | `app/src/lib/fetchRetry.ts` | `.js` import specifiers only |
+| `src/cells.ts` | `app/src/lib/cells.ts` | nothing (`@oceanmetrics/map` `grid.ts` has its own port of `cellSquares`; `cellPoints` and `placeMapBounds` live here) |
+| `src/dataset.ts` | `app/src/lib/catalog.ts` | the pure functions word for word (`toDataset`, `valueExpr`, `statsTemplate`, `lobeLonSpan`, `resolveDataset` ...); `loadDatasets` (reads the gazetteer's catalog.json) and `linkMismatch` (the app's wording) stay in the app |
+| `src/chunks.ts` | `precompute/src/stats.ts` `window`, `chunks`, `chunkDaysFor`; `precompute/src/targets.ts` `MAX_CHUNK_DAYS`, `MAX_REQUEST_VALUES` | `chunks()` word for word; `chunkDaysFor()` takes the two limits as options (defaulting to 90 and 100,000); `window()` defaults to `'all'` (the precompute's `DAYS`) |
+| `src/sql.ts`, `sql/*.sql` | `app/src/lib/sql.ts`, the repo-root `sql/` | the templates come from `src/sqlTemplates.ts`, generated from `sql/*.sql` by `scripts/sql-templates.mjs` (run by `npm run build`), instead of Vite's `import.meta.glob`; `lit` and `render` unchanged |
+| `src/engine.ts` | `app/src/lib/engine.ts` | the app boots DuckDB, not the package: `new Engine(connect)` with `connect() -> { db, conn }`, and `connectBrowser(duckdb, bundles)` for a browser; no `engine` singleton; `toRows` scales DECIMAL columns (below) |
+| `src/preview.ts` | new: the precompute's `maskLobe` and `computeOne` chunk loop, for the browser | |
+
+The moved tests came with them (`gridMask`, `wkb`, the lobe cases of `gazetteer`, `erddap`, `tabledap`, `extent`,
+`sql`, `cells`, `catalog`, `maskPerf`, `fetchRetry`, and the precompute's `window`/`chunks`/`chunkDaysFor` cases), with
+the fixtures `fixtures/{CINMS,FKNMS,HIHWNMS,PMNM}.geojson` (NOAA sanctuary boundaries), the Seascapes info table and ten
+published STAC Collections (`fixtures/stac/`).
+
+Not moved, and why:
+
+- the live-network halves of `erddap.test.ts`, `extent.test.ts`, `catalog.test.ts`, `gazetteer.test.ts` and
+  `maskPerf.test.ts` (PacIOOS, the gazetteer bucket): this package's tests run offline;
+- `maskPerf.test.ts`'s Svelte-proxy case (`plainPlace` unwrapping `$state`): a Svelte concern, it stays in the app;
+- the lobe cases on the gazetteer's `places.parquet` run here on the GeoJSON fixtures instead (the same PMNM and FKNMS);
+- the gazetteer readers (`loadPlaces`, `placeGeometry`, `unionBbox`, `placeBbox`): they read the places gazetteer
+  (`@oceanmetrics/places`), not a grid;
+- the precompute's disk cache (`planChunks`, `computeOne`, `maskKey`, the provenance): Node only, they belong to the
+  precompute (now `om_extract`);
+- the tabledap run (`pointMask` and `tabledapUrl` moved; the preview is griddap only, as the vision's row is).
+
+## The SQL contract shared with Python
+
+Five templates in `sql/`, rendered by `render(name, params)` (`{{expr}}`, `{{slab}}` and `{{mask}}` spliced as they
+are, any other param quoted as a literal by `lit`):
+
+| template | over | one row per | columns |
+|---|---|---|---|
+| `stats_daily` | a griddap slab | UTC day | `date, n, mean, mean_wt, sd, min, max, p10, p90, weight_sum` |
+| `stats_categorical` | a categorical griddap slab | day × class | `date, class, n, weight, fraction, percent_cells` |
+| `last_step` | a griddap slab | masked cell of the last step | `date, latitude, longitude, weight, value` (value NULL where the step has no data) |
+| `stats_tabledap` | a tabledap slab | month | `date, n, n_casts, mean, sd, min, max, p10, p90` |
+| `points_tabledap` | a tabledap slab | station | `latitude, longitude, weight, value, n, date` |
+
+- `{{expr}}` is the value expression over the slab alias `s` (`valueExpr()`: `s."CRW_SST"`, or `(s."analysed_sst" -
+  273.15)` for Kelvin); `{{slab}}` a registered Parquet file or a subquery; `{{mask}}` a table of `latitude, longitude,
+  weight` (0, 1].
+- The join is an exact equality on `ROUND(x, 3)` (grids) or `ROUND(x, 5)` (stations): ERDDAP's axis is float32 in the
+  Parquet, the mask float64.
+- Days come from `epoch_ms(time)`, because DuckDB-WASM ships without ICU (`TIMESTAMPTZ::DATE` is unimplemented there).
+- `om_extract/sql/` carries byte-identical copies of `stats_daily`, `stats_categorical` and `last_step` (the tabledap
+  two have no Python reader yet); `test/sql.test.ts` compares the bytes when the extract and erddap-places checkouts sit
+  beside platform. A change to a template is a change in all three repos.
+
+## The preview rule
+
+```ts
+const ds    = toDataset(collection)                         // a STAC erddap/* Collection
+const v     = ds.variables[0]
+const lobes = placeLobes(place)                             // one griddap request per lobe
+const axes  = await lobeAxes(ds, lobes, { signal })         // each lobe's axis vectors from the server
+const { cells } = lobeMasks(ds, lobes, axes)                // mask once, share it with the slice
+const run = await runPreview({
+  dataset: ds, variable: v, axes, mask: cells, t0: '2016-01-01', t1: '2026-10-20', engine, extent, signal,
+  onChunk: (rows, chunk) => chart.append(rows),             // oldest first, as each lands
+})
+```
+
+- **The chunk rule is the precompute's.** `previewWindow(cells, stepDays, { maxValues = 100_000, maxDays = 90 })` is
+  `chunkDaysFor`: at most 90 time steps a request (a coarser grid counts its own steps: 90 months of a monthly product),
+  shrunk so one request (one lobe) stays under 100,000 values (extractr's `n_max_vals_per_req`), never under one step.
+  `cells` is the largest lobe's lon × lat axis cells. A long window is `chunks(t0, t1, days)`, consecutive and
+  non-overlapping.
+- **Each chunk is the precompute's chunk.** One griddap Parquet request per lobe (`griddapUrl`, the lobe's axes as the
+  bounds, the extent's own instants at the window's two ends via `timeInstant`), registered in DuckDB-WASM, read as
+  `(SELECT DISTINCT * FROM read_parquet([...]))`, aggregated with `stats_daily` or `stats_categorical`
+  (`statsTemplate(v)`), then dropped.
+- **Drawn as they land, in time order.** Up to `concurrency` (default 2, the precompute's) requests are in flight, the
+  next chunk fetched while this one aggregates, and `onChunk` is called strictly in time order. A step that two chunks
+  snap onto (a coarse axis) is given once, as the precompute's DISTINCT merge does. `date` comes back as `yyyy-mm-dd`.
+- **Abortable.** `signal` cancels the in-flight requests, nothing after the abort reaches `onChunk`, and the promise
+  rejects with the signal's reason. The run's mask table (`preview_mask_<n>`) and slabs are dropped either way.
+- Griddap and Parquet only: a tabledap dataset or a server without Parquet (`pickFormat` gave `csvp` or `jsonp`) is
+  refused with a message. A mask with no cells asks the server nothing.
+
+**The map's slice.** `sliceSource({ dataset, variable, lobes | mask, axes, engine, extent })` is a `SliceSource` for
+`@oceanmetrics/map`'s `gridSlot(spec, source)`: `slice(t)` fetches the one step `t` (a day or an ISO instant;
+`null` is the extent's end, or ERDDAP's `last` without an extent) of every lobe and returns `last_step`'s rows as
+`{ lat, lon, value, weight }`, the mask's own centres, a cell without data kept with `value: null`. The mask goes into
+the engine once, at the first slice. The slabs of the lobes are read as `SELECT DISTINCT *` (as `runPreview` does), so a
+cell inside two overlapping boxes (Channel Islands and Chumash) comes back once, not twice (0.1.1); the mask you pass is
+the places' union and must hold each cell once.
+
+## DuckDB-WASM: the peer and the worker setup
+
+`@duckdb/duckdb-wasm` (>= 1.29, < 2; the apps pin 1.29 or 1.32) and `apache-arrow` (>= 17, which DuckDB-WASM itself
+depends on) are peer dependencies: the package imports only `apache-arrow` at run time (the mask's Arrow IPC insert)
+and never loads DuckDB itself. The app owns the bundles and the Web Worker, and hands the engine a `connect()`:
+
+```ts
+// a Vite app: the wasm and worker files served from the app's own origin
+import * as duckdb from '@duckdb/duckdb-wasm'
+import ehWasm from '@duckdb/duckdb-wasm/dist/duckdb-eh.wasm?url'
+import ehWorker from '@duckdb/duckdb-wasm/dist/duckdb-browser-eh.worker.js?url'
+import mvpWasm from '@duckdb/duckdb-wasm/dist/duckdb-mvp.wasm?url'
+import mvpWorker from '@duckdb/duckdb-wasm/dist/duckdb-browser-mvp.worker.js?url'
+import { Engine, connectBrowser } from '@oceanmetrics/engine'
+
+export const engine = new Engine(() => connectBrowser(duckdb, {
+  mvp: { mainModule: mvpWasm, mainWorker: mvpWorker },
+  eh : { mainModule: ehWasm,  mainWorker: ehWorker  },
+}))
+```
+
+`connectBrowser` is erddap-places' boot: `selectBundle` (eh where the browser has exceptions, else mvp), a `Worker` on
+the bundle's worker script, `AsyncDuckDB.instantiate`, one connection. `new Engine()` connects at once, so construct
+it (or `import()` the module that does) when the app first needs it, keeping the 7 MB of WASM off the first paint. One
+connection, and every call queued on one promise chain: a query never runs before an earlier insert has finished. Any
+`{ db, conn }` with the methods `DuckDbLike` and `DuckConnLike` name works; the tests use the node-blocking bundle
+(`test/helpers/nodeDb.ts`).
+
+`toRows` scales DECIMAL columns: DuckDB-WASM hands a DECIMAL back as its unscaled integer, so erddap-places' engine
+would have read `points_tabledap`'s `1.0 AS weight` as 10 (the app reads `n` there, so nothing on screen was wrong).
+
+## Size
+
+`npm run size` measures the gzipped sum of `dist/**/*.js` (comments included, before an app minifies): 26 794 B on
+2026-10-23 at 0.1.0, budget 40 000 B (about 1.5×). Only this package's own modules count: DuckDB-WASM and Apache
+Arrow are peers, and turf is a dependency the app's bundler adds (as `@oceanmetrics/map`'s geotiff is). The five SQL
+templates do count (`sqlTemplates.js`, 2 285 B on their own).
+
+What an app pays, bundled and minified with its dependencies (rolldown, gzip -9, `apache-arrow` and
+`@duckdb/duckdb-wasm` external, 2026-10-23):
+
+| entry | gzip |
+|---|--:|
+| the URLs and the dataset (`griddapUrl`, `tabledapUrl`, `pickFormat`, `fetchTimeExtent`, `toDataset`, `chunks`) | 2.6 kB |
+| the mask (`gridMask`, `placeLobes`, `wkbToGeoJSON`, with turf) | 5.7 kB |
+| the preview and the slice (`Engine`, `connectBrowser`, `placeLobes`, `lobeAxes`, `runPreview`, `sliceSource`, `toDataset`) | 12.7 kB |
+| everything | 16.2 kB |
+
+## Tests
+
+`npm test` from the repo root. One test per rule with synthetic fixtures and no network:
+
+- **Parity with Python** (`test/parity.test.ts`): the 15 cases of `extract/tests/fixtures/mask/*.json.gz` (written by
+  erddap-places' TypeScript through `make_expected.mjs`, and reproduced by `om_extract.mask`): the same WKB through
+  `wkbToGeoJSON`, `placeLobes` and `gridMask` gives the same lobes and every row (76,774 in 18 lobes) in order, weights
+  by `===`. The fixtures' recorded sha256 of `gridMask.ts`, `wkb.ts` and `placeLobes()` must be those of this package's
+  sources, and turf's version theirs. Skipped, with the reason, when the extract checkout is not beside platform
+  (`OM_EXTRACT_DIR` overrides) or when this CPU's `Math.sin` differs from the fixtures' arm64 generator
+  (`v8_sin.json.gz`).
+- **The originals** (`test/moved.test.ts`): the modules against erddap-places, byte for byte or function for function,
+  when that checkout is beside platform (`OM_ERDDAP_PLACES_DIR` overrides).
+- **The SQL** (`test/sql.test.ts`): `sqlTemplates.ts` is current, `sql/` is byte-identical to erddap-places' `sql/` and
+  `om_extract/sql/`, and erddap-places' `sql.test.ts` cases (they ran the native duckdb CLI) run in DuckDB-WASM.
+- **The engine** (`test/engine.test.ts`): on `fixtures/slabs/stats_3x3x2.parquet` (extract's `test_stats.py` slab,
+  written by pyarrow with float32 axes: `python fixtures/slabs/make_slabs.py`) and its diagonal mask, `stats_daily`,
+  `stats_categorical` and `last_step` give that test's hand-computed rows exactly; the queue survives a failed query;
+  DECIMAL is scaled; `connectBrowser` boots in order.
+- **The preview** (`test/preview.test.ts`): an injected fetch serves the slabs cut by a second DuckDB-WASM: the chunk
+  boundaries (90 days, the value cap), `onChunk` in time order when a later chunk lands first, two lobes unioned
+  DISTINCT, a snapped step given once, the Python numbers through the whole chain, abort mid-chain and during a hung
+  request, the slice rows, `slice(null)`.
+- the moved unit tests beside each module in `src/`.
+
+## Licence
+
+MIT, Copyright (c) 2026 Ocean Metrics LLC. The sanctuary boundary fixtures are NOAA Office of National Marine
+Sanctuaries data (public domain).

package/dist/cells.d.ts

@@ -0,0 +1,84 @@
+import type { FeatureCollection, Point, Polygon } from 'geojson';
+/** a mask cell with the value of one time step (null when the grid has no data there). */
+export interface ValueCell {
+    lon: number;
+    lat: number;
+    weight: number;
+    value?: number | null;
+}
+/** what each square carries into the map (hover shows `value` and `weight`). */
+export interface CellProps {
+    lon: number;
+    lat: number;
+    weight: number;
+    value: number | null;
+}
+export type LonCenter = 0 | 180;
+export interface CellSquaresOptions {
+    /** cell width in degrees; inferred from the distinct cell longitudes when omitted. */
+    lonSpacing?: number;
+    /** cell height in degrees; inferred from the distinct cell latitudes when omitted. */
+    latSpacing?: number;
+    /** longitude frame: (-180, 180] for 0, [0, 360) for 180, or 'auto' by the cells' own span. */
+    center?: LonCenter | 'auto';
+}
+export interface CellSquares {
+    geojson: FeatureCollection<Polygon, CellProps>;
+    lonSpacing: number;
+    latSpacing: number;
+    center: LonCenter;
+    /** [west, south, east, north] of the squares, in the chosen frame (east may exceed 180). */
+    bbox: [number, number, number, number];
+    /** value range over the cells that have one, for the colour ramp ([0, 0] when there are none). */
+    range: [number, number];
+}
+/** a longitude in the frame `center` names: (-180, 180] for 0, [0, 360) for 180. */
+export declare function normalizeLon(lon: number, center?: LonCenter): number;
+/**
+ * The step of an axis given only the values that were used: the **median** positive gap between
+ * distinct sorted values, so gaps left by cells outside the mask (2x, 3x the step) cannot inflate
+ * it. Returns 0 when there is nothing to measure (fewer than two distinct values).
+ */
+export declare function axisSpacing(values: number[]): number;
+/** the frame the cells fit in without wrapping: 180 when they span more than half the globe. */
+export declare function pickCenter(lons: number[]): LonCenter;
+/**
+ * One square per mask cell: `lon +- lonSpacing/2`, `lat +- latSpacing/2` (latitude clamped to the
+ * poles), in a single continuous longitude frame, with `value`, `weight`, `lon` and `lat` as
+ * properties. Cells whose value is missing are kept (drawn as a gap) with `value: null`.
+ */
+export declare function cellSquares(cells: ValueCell[], opts?: CellSquaresOptions): CellSquares;
+/**
+ * Map bounds for a place, antimeridian-aware.
+ *
+ * The gazetteer splits geometry at +-180, so a place that straddles the line (PMNM) has the useless
+ * stored bbox `[-180, .., 180, ..]`. Only in that case — width > 180 — is the geometry walked, in
+ * the [0, 360) frame, giving bounds like `[177.8, 19.2, 210.0, 31.8]` that MapLibre fits across the
+ * seam. Every other place returns its stored bbox untouched, so selecting a place still does no
+ * geometry work (the FKNMS/TBNMS vertex counts are the reason that matters).
+ */
+export declare function placeMapBounds(place: {
+    bbox: [number, number, number, number];
+    geometry?: unknown;
+}): [number, number, number, number];
+/**
+ * The box to fit for a place of the gazetteer index. The index unwraps a place cut at the antimeridian
+ * (NMS:PMNM is 177.8..199.0, `centroid_lon` 188), so its bbox fits directly. A few rows still read -180..180
+ * (the geometry is split but the bbox is not unwrapped): those need the geometry, and give null until it is
+ * loaded (the caller fits when it arrives).
+ */
+export declare function indexBounds(bbox: [number, number, number, number], geometry?: unknown): [number, number, number, number] | null;
+export interface CellPoints {
+    geojson: FeatureCollection<Point, CellProps>;
+    center: LonCenter;
+    bbox: [number, number, number, number];
+    range: [number, number];
+}
+/**
+ * One point per sample position, for a **tabledap** run: there is no cell to draw, so the map gets
+ * circles instead of squares. Same longitude framing as `cellSquares()`, so an antimeridian place
+ * stays in one piece, and the same properties, so the hover popup and the colour ramp are shared.
+ */
+export declare function cellPoints(cells: ValueCell[], opts?: {
+    center?: LonCenter | 'auto';
+}): CellPoints;

package/dist/cells.js

@@ -0,0 +1,179 @@
+/** a longitude in the frame `center` names: (-180, 180] for 0, [0, 360) for 180. */
+export function normalizeLon(lon, center = 0) {
+    let x = ((((lon + 180) % 360) + 360) % 360) - 180; // (-180, 180]
+    if (x === -180)
+        x = 180;
+    return center === 180 && x < 0 ? x + 360 : x;
+}
+/**
+ * The step of an axis given only the values that were used: the **median** positive gap between
+ * distinct sorted values, so gaps left by cells outside the mask (2x, 3x the step) cannot inflate
+ * it. Returns 0 when there is nothing to measure (fewer than two distinct values).
+ */
+export function axisSpacing(values) {
+    const v = [...new Set(values.filter((x) => Number.isFinite(x)))].sort((a, b) => a - b);
+    if (v.length < 2)
+        return 0;
+    const gaps = [];
+    for (let i = 1; i < v.length; i++) {
+        const d = v[i] - v[i - 1];
+        if (d > 0)
+            gaps.push(d);
+    }
+    if (!gaps.length)
+        return 0;
+    gaps.sort((a, b) => a - b);
+    const m = gaps.length >> 1;
+    return gaps.length % 2 ? gaps[m] : (gaps[m - 1] + gaps[m]) / 2;
+}
+/** the frame the cells fit in without wrapping: 180 when they span more than half the globe. */
+export function pickCenter(lons) {
+    if (!lons.length)
+        return 0;
+    const x = lons.map((l) => normalizeLon(l, 0));
+    return Math.max(...x) - Math.min(...x) > 180 ? 180 : 0;
+}
+/**
+ * One square per mask cell: `lon +- lonSpacing/2`, `lat +- latSpacing/2` (latitude clamped to the
+ * poles), in a single continuous longitude frame, with `value`, `weight`, `lon` and `lat` as
+ * properties. Cells whose value is missing are kept (drawn as a gap) with `value: null`.
+ */
+export function cellSquares(cells, opts = {}) {
+    const center = opts.center === undefined || opts.center === 'auto'
+        ? pickCenter(cells.map((c) => c.lon))
+        : opts.center;
+    const lons = cells.map((c) => normalizeLon(c.lon, center));
+    let dx = opts.lonSpacing ?? axisSpacing(lons);
+    let dy = opts.latSpacing ?? axisSpacing(cells.map((c) => c.lat));
+    // a single row or column gives that axis no gap to measure: borrow the other axis's step
+    if (!dx)
+        dx = dy;
+    if (!dy)
+        dy = dx;
+    const hx = dx / 2, hy = dy / 2;
+    let w = Infinity, s = Infinity, e = -Infinity, n = -Infinity;
+    let vmin = Infinity, vmax = -Infinity;
+    const features = cells.map((c, i) => {
+        const x = lons[i], y = c.lat;
+        const x0 = x - hx, x1 = x + hx;
+        const y0 = Math.max(-90, y - hy), y1 = Math.min(90, y + hy);
+        const value = typeof c.value === 'number' && Number.isFinite(c.value) ? c.value : null;
+        if (value !== null) {
+            if (value < vmin)
+                vmin = value;
+            if (value > vmax)
+                vmax = value;
+        }
+        if (x0 < w)
+            w = x0;
+        if (x1 > e)
+            e = x1;
+        if (y0 < s)
+            s = y0;
+        if (y1 > n)
+            n = y1;
+        return {
+            type: 'Feature',
+            id: i,
+            properties: { lon: x, lat: y, weight: c.weight, value },
+            geometry: { type: 'Polygon', coordinates: [[[x0, y0], [x1, y0], [x1, y1], [x0, y1], [x0, y0]]] },
+        };
+    });
+    return {
+        geojson: { type: 'FeatureCollection', features },
+        lonSpacing: dx, latSpacing: dy, center,
+        bbox: features.length ? [w, s, e, n] : [0, 0, 0, 0],
+        range: Number.isFinite(vmin) ? [vmin, vmax] : [0, 0],
+    };
+}
+// ── map bounds for a place ────────────────────────────────────────────────────
+/**
+ * Map bounds for a place, antimeridian-aware.
+ *
+ * The gazetteer splits geometry at +-180, so a place that straddles the line (PMNM) has the useless
+ * stored bbox `[-180, .., 180, ..]`. Only in that case — width > 180 — is the geometry walked, in
+ * the [0, 360) frame, giving bounds like `[177.8, 19.2, 210.0, 31.8]` that MapLibre fits across the
+ * seam. Every other place returns its stored bbox untouched, so selecting a place still does no
+ * geometry work (the FKNMS/TBNMS vertex counts are the reason that matters).
+ */
+export function placeMapBounds(place) {
+    const [x0, y0, x1, y1] = place.bbox;
+    if (x1 - x0 <= 180 || !place.geometry)
+        return [x0, y0, x1, y1];
+    let w = Infinity, s = Infinity, e = -Infinity, n = -Infinity;
+    const walk = (c) => {
+        if (typeof c?.[0] === 'number') {
+            const x = normalizeLon(c[0], 180), y = c[1];
+            if (x < w)
+                w = x;
+            if (x > e)
+                e = x;
+            if (y < s)
+                s = y;
+            if (y > n)
+                n = y;
+        }
+        else if (Array.isArray(c))
+            for (const k of c)
+                walk(k);
+    };
+    const g = place.geometry;
+    if (g.type === 'GeometryCollection')
+        for (const sub of g.geometries)
+            walk(sub.coordinates);
+    else
+        walk(g.coordinates);
+    return Number.isFinite(w) ? [w, s, e, n] : [x0, y0, x1, y1];
+}
+/**
+ * The box to fit for a place of the gazetteer index. The index unwraps a place cut at the antimeridian
+ * (NMS:PMNM is 177.8..199.0, `centroid_lon` 188), so its bbox fits directly. A few rows still read -180..180
+ * (the geometry is split but the bbox is not unwrapped): those need the geometry, and give null until it is
+ * loaded (the caller fits when it arrives).
+ */
+export function indexBounds(bbox, geometry) {
+    if (bbox[2] - bbox[0] <= 180)
+        return bbox;
+    return geometry ? placeMapBounds({ bbox, geometry }) : null;
+}
+/**
+ * One point per sample position, for a **tabledap** run: there is no cell to draw, so the map gets
+ * circles instead of squares. Same longitude framing as `cellSquares()`, so an antimeridian place
+ * stays in one piece, and the same properties, so the hover popup and the colour ramp are shared.
+ */
+export function cellPoints(cells, opts = {}) {
+    const center = opts.center === undefined || opts.center === 'auto'
+        ? pickCenter(cells.map((c) => c.lon))
+        : opts.center;
+    let w = Infinity, s = Infinity, e = -Infinity, n = -Infinity;
+    let vmin = Infinity, vmax = -Infinity;
+    const features = cells.map((c, i) => {
+        const x = normalizeLon(c.lon, center), y = c.lat;
+        const value = typeof c.value === 'number' && Number.isFinite(c.value) ? c.value : null;
+        if (value !== null) {
+            if (value < vmin)
+                vmin = value;
+            if (value > vmax)
+                vmax = value;
+        }
+        if (x < w)
+            w = x;
+        if (x > e)
+            e = x;
+        if (y < s)
+            s = y;
+        if (y > n)
+            n = y;
+        return {
+            type: 'Feature', id: i,
+            properties: { lon: x, lat: y, weight: c.weight, value },
+            geometry: { type: 'Point', coordinates: [x, y] },
+        };
+    });
+    return {
+        geojson: { type: 'FeatureCollection', features },
+        center,
+        bbox: features.length ? [w, s, e, n] : [0, 0, 0, 0],
+        range: Number.isFinite(vmin) ? [vmin, vmax] : [0, 0],
+    };
+}

package/dist/chunks.d.ts

@@ -0,0 +1,29 @@
+import { type TimeExtent } from './extent.js';
+/** never ask ERDDAP for more than this many time steps in one request (90 days of a daily grid). */
+export declare const MAX_CHUNK_DAYS = 90;
+/**
+ * and shrink the chunk further so a single request (one lobe) stays under this many values: the
+ * `n_max_vals_per_req = 100000` of marinebon/extractr `ed_extract()`, which keeps an ERDDAP server
+ * responsive with many light requests instead of a few heavy ones.
+ */
+export declare const MAX_REQUEST_VALUES = 100000;
+export interface ChunkLimits {
+    /** values per request (one lobe): time steps x axis cells */
+    maxValues?: number;
+    /** time steps per request */
+    maxDays?: number;
+}
+/** the last `days` days of the dataset, or its full extent when that is shorter (or `days` is 'all'). */
+export declare function window(ext: TimeExtent, days?: number | 'all'): {
+    start: string;
+    end: string;
+};
+/** split [start, end] into consecutive, non-overlapping slices of at most `chunkDays` days. */
+export declare function chunks(start: string, end: string, chunkDays: number): Array<[string, string]>;
+/**
+ * days per request: `maxDays` time steps (90 days of a daily grid; a coarser grid's steps are
+ * counted in its own days, so a monthly product asks for up to 90 months at once), shrunk so one
+ * request stays under `maxValues` values (extractr's n_max_vals_per_req). `cellsPerStep` is the
+ * largest lobe's axis cells: each lobe is its own request. Never below one step.
+ */
+export declare function chunkDaysFor(cellsPerStep: number, stepDays?: number, { maxValues, maxDays }?: ChunkLimits): number;

package/dist/chunks.js

@@ -0,0 +1,49 @@
+// the time chunking of a long window: a window is cut into requests of at most 90 time steps and 100,000 values, so a
+// server is asked many light questions instead of a few heavy ones. moved from erddap-places `precompute/src/stats.ts`
+// (`window`, `chunks`, `chunkDaysFor`) with the two constants of `precompute/src/targets.ts`; the arithmetic is
+// unchanged, and the two limits are now options (defaulting to the precompute's values) so the browser preview runs
+// the same rule.
+import { addDays, day, daysBetween } from './extent.js';
+/** never ask ERDDAP for more than this many time steps in one request (90 days of a daily grid). */
+export const MAX_CHUNK_DAYS = 90;
+/**
+ * and shrink the chunk further so a single request (one lobe) stays under this many values: the
+ * `n_max_vals_per_req = 100000` of marinebon/extractr `ed_extract()`, which keeps an ERDDAP server
+ * responsive with many light requests instead of a few heavy ones.
+ */
+export const MAX_REQUEST_VALUES = 100_000;
+/** the last `days` days of the dataset, or its full extent when that is shorter (or `days` is 'all'). */
+export function window(ext, days = 'all') {
+    const end = day(ext.end);
+    if (days === 'all' || !Number.isFinite(days))
+        return { start: day(ext.start), end };
+    let start = addDays(end, -(days - 1));
+    if (daysBetween(day(ext.start), start) < 0)
+        start = day(ext.start);
+    return { start, end };
+}
+/** split [start, end] into consecutive, non-overlapping slices of at most `chunkDays` days. */
+export function chunks(start, end, chunkDays) {
+    const out = [];
+    let s = start;
+    while (daysBetween(s, end) >= 0) {
+        const e = addDays(s, chunkDays - 1);
+        out.push([s, daysBetween(e, end) < 0 ? end : e]);
+        s = addDays(e, 1);
+    }
+    return out;
+}
+/**
+ * days per request: `maxDays` time steps (90 days of a daily grid; a coarser grid's steps are
+ * counted in its own days, so a monthly product asks for up to 90 months at once), shrunk so one
+ * request stays under `maxValues` values (extractr's n_max_vals_per_req). `cellsPerStep` is the
+ * largest lobe's axis cells: each lobe is its own request. Never below one step.
+ */
+export function chunkDaysFor(cellsPerStep, stepDays = 1, { maxValues = MAX_REQUEST_VALUES, maxDays = MAX_CHUNK_DAYS } = {}) {
+    const sd = Math.max(1, stepDays);
+    const cap = Math.floor(maxDays * sd);
+    if (!(cellsPerStep > 0))
+        return cap;
+    const steps = Math.max(1, Math.floor(maxValues / cellsPerStep));
+    return Math.max(1, Math.min(cap, Math.floor(steps * sd)));
+}