@oceanmetrics/engine 0.0.0-stage → 0.1.1

package/dist/preview.js

@@ -0,0 +1,205 @@
+// the live preview: a series for any polygon x ERDDAP grid, in the browser, with the precompute's own chunking. a long
+// window is a chain of griddap requests (at most 90 steps and 100,000 values each, `chunkDaysFor`), and each chunk's
+// statistics are handed to the caller as they land, oldest first, so a chart draws while the rest is still coming.
+// the per-lobe masking (the 0..360 shift included) is the precompute's `maskLobe` and the App's run(); the slab of a
+// chunk is `(SELECT DISTINCT * FROM read_parquet([...one file per lobe]))` and the SQL is `stats_daily` or
+// `stats_categorical`, exactly as `precompute/src/stats.ts` `computeOne` runs them. `sliceSource` is the map's half: one
+// step's `last_step` rows for `@oceanmetrics/map`'s grid slot.
+import { chunkDaysFor, chunks } from './chunks.js';
+import { lobeLonSpan, statsTemplate, toDatasetLon, valueExpr } from './dataset.js';
+import { AXIS_TIMEOUT_MS, SLICE_TIMEOUT_MS, fetchAxis, fetchSlab, griddapSliceUrl, griddapUrl, isParquet, noonZ } from './erddap.js';
+import { timeInstant } from './extent.js';
+import { gridMask } from './mask.js';
+// ---- the chunk rule ----
+/**
+ * Days per request for a window over `cells` axis cells per step (the largest lobe's lon x lat) of a grid whose step
+ * is `stepDays`: the precompute's `chunkDaysFor`, at most `maxDays` steps and `maxValues` values a request.
+ */
+export function previewWindow(cells, stepDays = 1, { maxValues = 100_000, maxDays = 90 } = {}) {
+    return chunkDaysFor(cells, stepDays, { maxValues, maxDays });
+}
+// ---- the mask ----
+/**
+ * The mask of every lobe on its axes, in the dataset's own longitude frame (a 0..360 grid's axis goes to the polygon's
+ * -180..180 for the mask and its cells come back to 0..360, so they join the slab), and the cells per step of the
+ * largest lobe (what sets the chunk size).
+ */
+export function lobeMasks(dataset, lobes, axes) {
+    if (lobes.length !== axes.length)
+        throw new Error(`lobeMasks: ${lobes.length} lobe(s) but ${axes.length} axis pair(s)`);
+    const shifted = dataset.lonRange[1] > 180;
+    const toPoly = (x) => (shifted && x > 180 ? x - 360 : x);
+    const cells = [];
+    for (const [i, lobe] of lobes.entries()) {
+        const m = gridMask(lobe.geojson, axes[i].lon.map(toPoly), axes[i].lat);
+        for (const c of m.cells)
+            cells.push(shifted ? { ...c, lon: toDatasetLon(c.lon, dataset.lonRange) } : c);
+    }
+    return { cells, cellsPerStep: Math.max(0, ...axes.map((a) => a.lon.length * a.lat.length)) };
+}
+/** each lobe's axis vectors from the server (`fetchAxis`, the lobe's longitude span in the dataset's frame) */
+export async function lobeAxes(dataset, lobes, { fetch: fetchFn, signal, retry = {} } = {}) {
+    const r = { timeoutMs: AXIS_TIMEOUT_MS, ...retry, ...(fetchFn ? { fetchFn } : {}) };
+    return Promise.all(lobes.map(async (lobe) => {
+        const [lo, hi] = lobeLonSpan(lobe.bbox, dataset.lonRange);
+        const [lon, lat] = await Promise.all([
+            fetchAxis(dataset.baseUrl, dataset.datasetId, 'longitude', lo, hi, false, signal, r),
+            fetchAxis(dataset.baseUrl, dataset.datasetId, 'latitude', lobe.bbox[1], lobe.bbox[3], dataset.latDescending, signal, r),
+        ]);
+        return { lon, lat };
+    }));
+}
+// ---- shared ----
+let seq = 0;
+const uid = (what) => `${what}_${++seq}`;
+const aborted = (signal) => { if (signal?.aborted)
+    throw signal.reason ?? new DOMException('aborted', 'AbortError'); };
+/** a yyyy-mm-dd UTC day from what DuckDB-WASM hands back for a DATE (epoch ms, a Date, or a string) */
+export function isoDay(v) {
+    if (v instanceof Date)
+        return v.toISOString().slice(0, 10);
+    if (typeof v === 'number' || typeof v === 'bigint')
+        return new Date(Number(v)).toISOString().slice(0, 10);
+    return String(v).slice(0, 10);
+}
+function slabUrl(dataset, variable, ax, time) {
+    const grid = {
+        base: dataset.baseUrl, datasetId: dataset.datasetId, variable,
+        lat: [ax.lat[ax.lat.length - 1], ax.lat[0]], lon: [ax.lon[0], ax.lon[ax.lon.length - 1]],
+        latDescending: dataset.latDescending, depth: dataset.depth, format: dataset.format ?? 'parquet',
+    };
+    return Array.isArray(time) ? griddapUrl({ ...grid, time }) : griddapSliceUrl({ ...grid, at: time.at });
+}
+function parquetFormat(dataset) {
+    if (dataset.protocol === 'tabledap')
+        throw new Error(`${dataset.datasetId}: the preview is for griddap datasets (tabledap has no lattice)`);
+    const f = dataset.format ?? 'parquet';
+    if (!isParquet(f))
+        throw new Error(`${dataset.datasetId}: the preview reads Parquet slabs, and this server offers .${f}`);
+    return f;
+}
+/** fetch every lobe's slab for one request, register each under a fresh name; the read_parquet() list of them */
+async function loadSlabs(engine, urls, format, signal, retry) {
+    const slabs = await Promise.all(urls.map((u) => fetchSlab(u, format, undefined, signal, retry)));
+    aborted(signal);
+    const files = [];
+    for (const s of slabs) {
+        const f = `${uid('slab')}.parquet`;
+        await engine.registerBuffer(f, s.buffer);
+        files.push(f);
+    }
+    return files;
+}
+const readList = (files) => `read_parquet([${files.map((f) => `'${f}'`).join(', ')}])`;
+// the lobes' slabs as one relation without a row twice: where two places' boxes overlap (Channel Islands and Chumash)
+// both slabs hold the cells of the overlap, and the join over the mask would return each of them twice
+const distinctSlab = (files) => `(SELECT DISTINCT * FROM ${readList(files)})`;
+/**
+ * The statistics of `variable` over the place for [t0, t1], chunk by chunk. Each chunk's slab (one Parquet request per
+ * lobe) is registered, aggregated with the template over the mask and dropped; `onChunk` gets its rows as soon as they
+ * are computed, in time order. `signal` stops the chain: the in-flight requests are cancelled, nothing after the abort
+ * reaches `onChunk`, and the promise rejects with the abort reason. The mask table and the slabs are dropped either way.
+ */
+export async function runPreview(o) {
+    const { dataset, variable, axes, engine, signal } = o;
+    const format = parquetFormat(dataset);
+    aborted(signal);
+    const masked = o.mask
+        ? { cells: o.mask, cellsPerStep: Math.max(0, ...axes.map((a) => a.lon.length * a.lat.length)) }
+        : lobeMasks(dataset, o.lobes ?? [], axes);
+    const name = statsTemplate(variable);
+    const chunkDays = previewWindow(masked.cellsPerStep, o.stepDays ?? o.extent?.stepDays ?? 1, o.limits);
+    const at = (d) => timeInstant(d, o.extent ?? null, noonZ);
+    const list = chunks(o.t0, o.t1, chunkDays).map(([s, e], index, all) => ({
+        index, count: all.length, start: s, end: e,
+        urls: axes.map((ax) => slabUrl(dataset, variable.name, ax, [at(s), at(e)])),
+    }));
+    const result = { rows: [], chunks: list, chunkDays, template: name, maskCells: masked.cells.length };
+    if (!masked.cells.length || !list.length)
+        return result;
+    const retry = { ...o.retry, ...(o.fetch ? { fetchFn: o.fetch } : {}) };
+    const mask = uid('preview_mask');
+    const expr = valueExpr(variable);
+    const seen = new Set();
+    const inFlight = [];
+    // the fetch half of a chunk: started up to `concurrency` chunks ahead, consumed in order
+    const start = (k) => {
+        if (k < list.length && !inFlight[k]) {
+            inFlight[k] = Promise.all(list[k].urls.map((u) => fetchSlab(u, format, undefined, signal, retry)));
+            inFlight[k].catch(() => { }); // a later chunk's failure surfaces when it is awaited, or never (after an abort)
+        }
+    };
+    const ahead = Math.max(1, o.concurrency ?? 2);
+    try {
+        await engine.insertMask(masked.cells, mask);
+        for (const chunk of list) {
+            for (let k = chunk.index; k < chunk.index + ahead; k++)
+                start(k);
+            const slabs = await inFlight[chunk.index];
+            aborted(signal);
+            const files = [];
+            try {
+                for (const s of slabs) {
+                    const f = `${uid('slab')}.parquet`;
+                    await engine.registerBuffer(f, s.buffer);
+                    files.push(f);
+                }
+                // DISTINCT: a coarse axis (the 8-day grid) can snap a chunk's two endpoints onto one step
+                const slab = distinctSlab(files);
+                const out = await engine.runTemplate(name, { expr, slab, mask });
+                aborted(signal);
+                // two chunks snapped onto the same step of a coarse axis give that step twice, identical: keep the first
+                const rows = out.map((r) => ({ ...r, date: isoDay(r.date) })).filter((r) => !seen.has(r.date));
+                for (const r of rows)
+                    seen.add(r.date);
+                result.rows.push(...rows);
+                o.onChunk?.(rows, chunk);
+            }
+            finally {
+                for (const f of files)
+                    await engine.dropFile(f).catch(() => { });
+            }
+        }
+    }
+    finally {
+        await engine.exec(`DROP TABLE IF EXISTS ${mask}`, 'drop').catch(() => { });
+    }
+    return result;
+}
+/**
+ * A `SliceSource` for the grid slot: `slice(t)` fetches the one step `t` (a yyyy-mm-dd day or an ISO instant; null for
+ * the newest) of every lobe and runs `last_step` over the mask: the masked cells with their own lat/lon, the area
+ * weight and the value (null where the step has no data). The mask goes into the engine once, at the first slice.
+ */
+export function sliceSource(o) {
+    const format = parquetFormat(o.dataset);
+    const cells = o.mask ?? lobeMasks(o.dataset, o.lobes ?? [], o.axes).cells;
+    const mask = uid('slice_mask');
+    let inserted = null;
+    const retry = { timeoutMs: SLICE_TIMEOUT_MS, ...o.retry, ...(o.fetch ? { fetchFn: o.fetch } : {}) };
+    return {
+        async slice(t, signal) {
+            aborted(signal);
+            if (!cells.length)
+                return [];
+            const at = t === null ? (o.extent ? o.extent.end : 'last')
+                : t.length <= 10 ? timeInstant(t, o.extent ?? null, noonZ) : t;
+            inserted ??= o.engine.insertMask(cells, mask).catch((e) => { inserted = null; throw e; });
+            const urls = o.axes.map((ax) => slabUrl(o.dataset, o.variable.name, ax, { at }));
+            const files = await loadSlabs(o.engine, urls, format, signal, retry);
+            try {
+                await inserted;
+                aborted(signal);
+                const rows = await o.engine.runTemplate('last_step', { expr: valueExpr(o.variable), slab: distinctSlab(files), mask });
+                return rows.map((r) => ({
+                    lat: Number(r.latitude), lon: Number(r.longitude), weight: Number(r.weight),
+                    value: r.value === null || r.value === undefined ? null : Number(r.value),
+                }));
+            }
+            finally {
+                for (const f of files)
+                    await o.engine.dropFile(f).catch(() => { });
+            }
+        },
+    };
+}

package/dist/sql.d.ts

@@ -0,0 +1,10 @@
+/** the names of the shipped templates */
+export type TemplateName = 'stats_daily' | 'stats_categorical' | 'last_step' | 'stats_tabledap' | 'points_tabledap';
+export declare function template(name: string): string;
+export declare function templateNames(): string[];
+export type Param = string | number | boolean | null;
+export interface Params {
+    [k: string]: Param;
+}
+export declare function lit(v: Param): string;
+export declare function render(name: string, params: Params): string;

package/dist/sql.js

@@ -0,0 +1,33 @@
+// the {{named}}-parameter SQL templates of sql/, rendered without DuckDB. moved from erddap-places `app/src/lib/sql.ts`:
+// the templates come from the generated sqlTemplates.ts (built from sql/*.sql by scripts/sql-templates.mjs) instead of
+// Vite's import.meta.glob; `lit` and `render` are unchanged, so the browser, the precompute and om_extract (which
+// carries byte-identical copies of the same .sql files) run the same text.
+import { TEMPLATES } from './sqlTemplates.js';
+export function template(name) {
+    const t = TEMPLATES[name];
+    if (t === undefined)
+        throw new Error(`no SQL template ${name} (have: ${Object.keys(TEMPLATES).join(', ')})`);
+    return t;
+}
+export function templateNames() {
+    return Object.keys(TEMPLATES).sort();
+}
+/** params spliced literally (identifiers and expressions: table/column names); everything else quoted. */
+const RAW = new Set(['var', 'expr', 'slab', 'mask', 'src']);
+export function lit(v) {
+    if (v === null || v === undefined)
+        return 'NULL';
+    if (typeof v === 'number')
+        return Number.isFinite(v) ? String(v) : 'NULL';
+    if (typeof v === 'boolean')
+        return v ? 'TRUE' : 'FALSE';
+    return `'${String(v).replace(/'/g, "''")}'`;
+}
+export function render(name, params) {
+    const body = template(name);
+    return body.replace(/\{\{(\w+)\}\}/g, (_, k) => {
+        if (!(k in params))
+            throw new Error(`template ${name}: missing param ${k}`);
+        return RAW.has(k) ? String(params[k]) : lit(params[k]);
+    }).trim();
+}

package/dist/sqlTemplates.d.ts

@@ -0,0 +1 @@
+export declare const TEMPLATES: Readonly<Record<string, string>>;

package/dist/sqlTemplates.js

@@ -0,0 +1,8 @@
+// generated by scripts/sql-templates.mjs from sql/*.sql: do not edit (edit the .sql, then run the script)
+export const TEMPLATES = {
+    last_step: "-- the masked cells of the **last** time step in the slab, for the map layer.\n--   {{expr}}  the value expression over the slab alias `s` (e.g. s.\"CRW_SST\", or\n--             (s.\"analysed_sst\" - 273.15) to convert Kelvin to Celsius)\n--   {{slab}}  the registered griddap file (parquet) or view\n--   {{mask}}  the mask table: latitude, longitude, weight (0,1]\n-- one row per cell: the mask's own latitude/longitude (so the squares land on the dataset grid), the\n-- area weight and the value. cells with no data on that step are kept with a NULL value, so the map\n-- draws the hole instead of moving the neighbouring squares. the join is the same exact equality on\n-- ROUND(x, 3) as stats_daily.sql (float32 axis vs float64 mask).\nWITH joined AS (\n  SELECT\n    s.\"time\"     AS time,\n    m.latitude   AS latitude,\n    m.longitude  AS longitude,\n    m.weight     AS weight,\n    {{expr}}     AS value\n  FROM {{slab}} s\n  JOIN {{mask}} m\n    ON  ROUND(s.latitude::DOUBLE,  3) = ROUND(m.latitude::DOUBLE,  3)\n    AND ROUND(s.longitude::DOUBLE, 3) = ROUND(m.longitude::DOUBLE, 3)\n)\nSELECT\n  -- utc day; via epoch_ms because duckdb-wasm ships without icu, so TIMESTAMPTZ::DATE is unimplemented there\n  make_timestamp(epoch_ms(time) * 1000)::DATE AS date,\n  latitude,\n  longitude,\n  weight,\n  value\nFROM joined\nWHERE time = (SELECT max(time) FROM joined)\nORDER BY latitude, longitude\n",
+    points_tabledap: "-- one row per masked sampling station, for the map layer of a tabledap run.\n--   {{expr}}  the value expression over the slab alias `s`\n--   {{slab}}  the registered tabledap file (parquet) or view\n--   {{mask}}  the station table: latitude, longitude\n-- a tabledap window holds many casts at the same position and many depths per cast, so the map\n-- shows each **station**: its mean value over the window, the number of measurements behind it and\n-- the last time it was sampled.\nSELECT\n  m.latitude                                             AS latitude,\n  m.longitude                                            AS longitude,\n  1.0                                                    AS weight,\n  avg({{expr}})                                          AS value,\n  count({{expr}})                                        AS n,\n  make_timestamp(epoch_ms(max(s.\"time\")) * 1000)::DATE   AS date\nFROM {{slab}} s\nJOIN {{mask}} m\n  ON  ROUND(s.latitude::DOUBLE,  5) = ROUND(m.latitude::DOUBLE,  5)\n  AND ROUND(s.longitude::DOUBLE, 5) = ROUND(m.longitude::DOUBLE, 5)\nWHERE {{expr}} IS NOT NULL\nGROUP BY 1, 2\nORDER BY 1, 2\n",
+    stats_categorical: "-- per date x class composition for one place from a categorical ERDDAP griddap slab (seascapeR's\n-- sum_ss_grds_to_ts(): how much of the place is in each class on each date).\n--   {{expr}}  the class expression over the slab alias `s` (e.g. s.\"CLASS\"); cast to BIGINT here\n--   {{slab}}  the registered griddap file (parquet) or view\n--   {{mask}}  the mask table: latitude, longitude, weight (0,1]\n-- `fraction` is area-weighted (partial boundary cells count for their overlap) and sums to exactly 1\n-- over the classes of a date; `percent_cells` is the unweighted cell count share.\n-- the join is the same exact equality on ROUND(x, 3) as stats_daily.sql (float32 axis vs float64 mask).\nWITH cells AS (\n  SELECT\n    -- utc day; via epoch_ms because duckdb-wasm ships without icu, so TIMESTAMPTZ::DATE is unimplemented there\n    make_timestamp(epoch_ms(s.\"time\") * 1000)::DATE AS date,\n    CAST({{expr}} AS BIGINT)                        AS class,\n    m.weight                                        AS weight\n  FROM {{slab}} s\n  JOIN {{mask}} m\n    ON  ROUND(s.latitude::DOUBLE,  3) = ROUND(m.latitude::DOUBLE,  3)\n    AND ROUND(s.longitude::DOUBLE, 3) = ROUND(m.longitude::DOUBLE, 3)\n  WHERE {{expr}} IS NOT NULL\n),\ntotals AS (\n  SELECT date, count(*) AS n_total, sum(weight) AS weight_total\n  FROM cells\n  GROUP BY 1\n)\nSELECT\n  c.date                                    AS date,\n  c.class                                   AS class,\n  count(*)                                  AS n,\n  sum(c.weight)                             AS weight,\n  sum(c.weight) / any_value(t.weight_total) AS fraction,\n  100.0 * count(*) / any_value(t.n_total)   AS percent_cells\nFROM cells c\nJOIN totals t USING (date)\nGROUP BY c.date, c.class\nORDER BY 1, 2\n",
+    stats_daily: "-- daily key statistics for one place from an ERDDAP griddap slab.\n--   {{expr}}  the value expression over the slab alias `s` (e.g. s.\"CRW_SST\", or\n--             (s.\"analysed_sst\" - 273.15) to convert Kelvin to Celsius)\n--   {{slab}}  the registered griddap file (parquet) or view\n--   {{mask}}  the mask table: latitude, longitude, weight (0,1]\n-- the join is an exact equality on ROUND(x, 3): the ERDDAP axis is float32 in the parquet and float64\n-- in the JS mask, so 21.375 arrives as 21.374999... on one side; rounding to the grid's 3 decimals\n-- (0.05 spacing) makes the two match without a tolerance join.\nSELECT\n  -- utc day; via epoch_ms because duckdb-wasm ships without icu, so TIMESTAMPTZ::DATE is unimplemented there\n  make_timestamp(epoch_ms(s.\"time\") * 1000)::DATE   AS date,\n  count({{expr}})                                  AS n,\n  avg({{expr}})                                    AS mean,\n  sum({{expr}} * m.weight) / sum(m.weight)         AS mean_wt,\n  stddev_samp({{expr}})                            AS sd,\n  min({{expr}})                                    AS min,\n  max({{expr}})                                    AS max,\n  quantile_cont({{expr}}, 0.10)                    AS p10,\n  quantile_cont({{expr}}, 0.90)                    AS p90,\n  sum(m.weight)                                     AS weight_sum\nFROM {{slab}} s\nJOIN {{mask}} m\n  ON  ROUND(s.latitude::DOUBLE,  3) = ROUND(m.latitude::DOUBLE,  3)\n  AND ROUND(s.longitude::DOUBLE, 3) = ROUND(m.longitude::DOUBLE, 3)\nWHERE {{expr}} IS NOT NULL\nGROUP BY 1\nORDER BY 1\n",
+    stats_tabledap: "-- monthly key statistics for one place from an ERDDAP **tabledap** slab (point samples).\n--   {{expr}}  the value expression over the slab alias `s` (e.g. s.\"measurement_value\")\n--   {{slab}}  the registered tabledap file (parquet) or view\n--   {{mask}}  the station table: latitude, longitude (weight is 1 — a point is in or out)\n-- tabledap points are sparse and irregular, so the roll-up is by **month**, not by day: a CalCOFI\n-- quarterly cruise gives a handful of days a year, and a daily grouping would be mostly empty.\n-- `n_casts` counts the distinct sampling events (time x position) behind the n measurements, since\n-- one cast contributes many depths.\n-- the join is an exact equality on ROUND(x, 5): the station positions come back out of DuckDB, go\n-- through the JS point-in-polygon mask and come back in, so five decimals (~1 m) is exact here.\nWITH pts AS (\n  SELECT\n    -- utc, via epoch_ms because duckdb-wasm ships without icu: TIMESTAMPTZ::DATE is unimplemented there\n    make_timestamp(epoch_ms(s.\"time\") * 1000) AS ts,\n    s.longitude::DOUBLE                       AS longitude,\n    s.latitude::DOUBLE                        AS latitude,\n    {{expr}}                                  AS value\n  FROM {{slab}} s\n  JOIN {{mask}} m\n    ON  ROUND(s.latitude::DOUBLE,  5) = ROUND(m.latitude::DOUBLE,  5)\n    AND ROUND(s.longitude::DOUBLE, 5) = ROUND(m.longitude::DOUBLE, 5)\n  WHERE {{expr}} IS NOT NULL\n)\nSELECT\n  date_trunc('month', ts)::DATE                  AS date,\n  count(value)                                   AS n,\n  count(DISTINCT (ts, longitude, latitude))      AS n_casts,\n  avg(value)                                     AS mean,\n  stddev_samp(value)                             AS sd,\n  min(value)                                     AS min,\n  max(value)                                     AS max,\n  quantile_cont(value, 0.10)                     AS p10,\n  quantile_cont(value, 0.90)                     AS p90\nFROM pts\nGROUP BY 1\nORDER BY 1\n",
+};

package/dist/wkb.d.ts

@@ -0,0 +1,5 @@
+import type { Geometry } from 'geojson';
+/** decode one WKB (or EWKB) geometry to GeoJSON, 2-D. */
+export declare function wkbToGeoJSON(bytes: Uint8Array | ArrayBuffer): Geometry;
+/** every Polygon of a geometry, as a MultiPolygon-style coordinate array. */
+export declare function polygonCoordinates(g: Geometry): number[][][][];

package/dist/wkb.js

@@ -0,0 +1,80 @@
+const u32 = (c) => { const v = c.view.getUint32(c.off, c.le); c.off += 4; return v; };
+const f64 = (c) => { const v = c.view.getFloat64(c.off, c.le); c.off += 8; return v; };
+/** byte order + type code of the geometry at the cursor; leaves the cursor after the header. */
+function header(c) {
+    const order = c.view.getUint8(c.off);
+    c.off += 1;
+    if (order !== 0 && order !== 1)
+        throw new Error(`WKB: bad byte order ${order} at ${c.off - 1}`);
+    c.le = order === 1;
+    const raw = u32(c);
+    const ewkbZ = (raw & 0x80000000) !== 0;
+    const ewkbM = (raw & 0x40000000) !== 0;
+    const srid = (raw & 0x20000000) !== 0;
+    const base = raw & 0x0fffffff;
+    const iso = Math.floor(base / 1000); // 0 = XY, 1 = Z, 2 = M, 3 = ZM
+    const type = base % 1000;
+    if (srid)
+        u32(c); // skip the SRID
+    const dims = 2 + (ewkbZ ? 1 : 0) + (ewkbM ? 1 : 0) + (iso === 1 || iso === 2 ? 1 : iso === 3 ? 2 : 0);
+    return { type, dims };
+}
+const point = (c, dims) => {
+    const xy = [f64(c), f64(c)];
+    for (let i = 2; i < dims; i++)
+        f64(c); // drop Z / M
+    return xy;
+};
+const ring = (c, dims) => {
+    const n = u32(c), out = new Array(n);
+    for (let i = 0; i < n; i++)
+        out[i] = point(c, dims);
+    return out;
+};
+const rings = (c, dims) => {
+    const n = u32(c), out = new Array(n);
+    for (let i = 0; i < n; i++)
+        out[i] = ring(c, dims);
+    return out;
+};
+function geometry(c) {
+    const { type, dims } = header(c);
+    switch (type) {
+        case 1: return { type: 'Point', coordinates: point(c, dims) };
+        case 2: return { type: 'LineString', coordinates: ring(c, dims) };
+        case 3: return { type: 'Polygon', coordinates: rings(c, dims) };
+        case 4:
+        case 5:
+        case 6:
+        case 7: {
+            const n = u32(c);
+            const parts = new Array(n);
+            for (let i = 0; i < n; i++)
+                parts[i] = geometry(c); // each part carries its own header
+            if (type === 7)
+                return { type: 'GeometryCollection', geometries: parts };
+            if (type === 4)
+                return { type: 'MultiPoint', coordinates: parts.map((p) => p.coordinates) };
+            if (type === 5)
+                return { type: 'MultiLineString', coordinates: parts.map((p) => p.coordinates) };
+            return { type: 'MultiPolygon', coordinates: parts.map((p) => p.coordinates) };
+        }
+        default: throw new Error(`WKB: unsupported geometry type ${type}`);
+    }
+}
+/** decode one WKB (or EWKB) geometry to GeoJSON, 2-D. */
+export function wkbToGeoJSON(bytes) {
+    const u = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+    const view = new DataView(u.buffer, u.byteOffset, u.byteLength);
+    return geometry({ view, off: 0, le: true });
+}
+/** every Polygon of a geometry, as a MultiPolygon-style coordinate array. */
+export function polygonCoordinates(g) {
+    if (g.type === 'Polygon')
+        return [g.coordinates];
+    if (g.type === 'MultiPolygon')
+        return g.coordinates;
+    if (g.type === 'GeometryCollection')
+        return g.geometries.flatMap(polygonCoordinates);
+    return [];
+}

package/package.json

@@ -1,6 +1,73 @@
 {
   "name": "@oceanmetrics/engine",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "the browser engine of Ocean Metrics: the place mask, ERDDAP requests, the SQL shared with the Python engine, DuckDB-WASM statistics and the chunked live preview",
+  "keywords": [
+    "ocean",
+    "erddap",
+    "griddap",
+    "duckdb-wasm",
+    "zonal-statistics",
+    "mask"
+  ],
+  "homepage": "https://github.com/oceanmetrics/platform/tree/main/packages/engine#readme",
+  "bugs": {
+    "url": "https://github.com/oceanmetrics/platform/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oceanmetrics/platform.git",
+    "directory": "packages/engine"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "sql",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "node scripts/sql-templates.mjs && tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --root ../.. packages/engine"
+  },
+  "dependencies": {
+    "@turf/area": "7.4.0",
+    "@turf/bbox-clip": "7.4.0",
+    "@turf/boolean-point-in-polygon": "7.4.0",
+    "@turf/helpers": "7.4.0"
+  },
+  "peerDependencies": {
+    "@duckdb/duckdb-wasm": ">=1.29.0 <2",
+    "apache-arrow": ">=17"
+  },
+  "devDependencies": {
+    "@duckdb/duckdb-wasm": "1.29.0",
+    "@types/geojson": "^7946.0.16",
+    "@types/node": "^24.13.3",
+    "apache-arrow": "^17.0.0",
+    "typescript": "~5.9.0",
+    "vitest": "^5.0.1"
+  }
+}

package/sql/last_step.sql

@@ -0,0 +1,31 @@
+-- the masked cells of the **last** time step in the slab, for the map layer.
+--   {{expr}}  the value expression over the slab alias `s` (e.g. s."CRW_SST", or
+--             (s."analysed_sst" - 273.15) to convert Kelvin to Celsius)
+--   {{slab}}  the registered griddap file (parquet) or view
+--   {{mask}}  the mask table: latitude, longitude, weight (0,1]
+-- one row per cell: the mask's own latitude/longitude (so the squares land on the dataset grid), the
+-- area weight and the value. cells with no data on that step are kept with a NULL value, so the map
+-- draws the hole instead of moving the neighbouring squares. the join is the same exact equality on
+-- ROUND(x, 3) as stats_daily.sql (float32 axis vs float64 mask).
+WITH joined AS (
+  SELECT
+    s."time"     AS time,
+    m.latitude   AS latitude,
+    m.longitude  AS longitude,
+    m.weight     AS weight,
+    {{expr}}     AS value
+  FROM {{slab}} s
+  JOIN {{mask}} m
+    ON  ROUND(s.latitude::DOUBLE,  3) = ROUND(m.latitude::DOUBLE,  3)
+    AND ROUND(s.longitude::DOUBLE, 3) = ROUND(m.longitude::DOUBLE, 3)
+)
+SELECT
+  -- utc day; via epoch_ms because duckdb-wasm ships without icu, so TIMESTAMPTZ::DATE is unimplemented there
+  make_timestamp(epoch_ms(time) * 1000)::DATE AS date,
+  latitude,
+  longitude,
+  weight,
+  value
+FROM joined
+WHERE time = (SELECT max(time) FROM joined)
+ORDER BY latitude, longitude

package/sql/points_tabledap.sql

@@ -0,0 +1,21 @@
+-- one row per masked sampling station, for the map layer of a tabledap run.
+--   {{expr}}  the value expression over the slab alias `s`
+--   {{slab}}  the registered tabledap file (parquet) or view
+--   {{mask}}  the station table: latitude, longitude
+-- a tabledap window holds many casts at the same position and many depths per cast, so the map
+-- shows each **station**: its mean value over the window, the number of measurements behind it and
+-- the last time it was sampled.
+SELECT
+  m.latitude                                             AS latitude,
+  m.longitude                                            AS longitude,
+  1.0                                                    AS weight,
+  avg({{expr}})                                          AS value,
+  count({{expr}})                                        AS n,
+  make_timestamp(epoch_ms(max(s."time")) * 1000)::DATE   AS date
+FROM {{slab}} s
+JOIN {{mask}} m
+  ON  ROUND(s.latitude::DOUBLE,  5) = ROUND(m.latitude::DOUBLE,  5)
+  AND ROUND(s.longitude::DOUBLE, 5) = ROUND(m.longitude::DOUBLE, 5)
+WHERE {{expr}} IS NOT NULL
+GROUP BY 1, 2
+ORDER BY 1, 2

package/sql/stats_categorical.sql

@@ -0,0 +1,36 @@
+-- per date x class composition for one place from a categorical ERDDAP griddap slab (seascapeR's
+-- sum_ss_grds_to_ts(): how much of the place is in each class on each date).
+--   {{expr}}  the class expression over the slab alias `s` (e.g. s."CLASS"); cast to BIGINT here
+--   {{slab}}  the registered griddap file (parquet) or view
+--   {{mask}}  the mask table: latitude, longitude, weight (0,1]
+-- `fraction` is area-weighted (partial boundary cells count for their overlap) and sums to exactly 1
+-- over the classes of a date; `percent_cells` is the unweighted cell count share.
+-- the join is the same exact equality on ROUND(x, 3) as stats_daily.sql (float32 axis vs float64 mask).
+WITH cells AS (
+  SELECT
+    -- utc day; via epoch_ms because duckdb-wasm ships without icu, so TIMESTAMPTZ::DATE is unimplemented there
+    make_timestamp(epoch_ms(s."time") * 1000)::DATE AS date,
+    CAST({{expr}} AS BIGINT)                        AS class,
+    m.weight                                        AS weight
+  FROM {{slab}} s
+  JOIN {{mask}} m
+    ON  ROUND(s.latitude::DOUBLE,  3) = ROUND(m.latitude::DOUBLE,  3)
+    AND ROUND(s.longitude::DOUBLE, 3) = ROUND(m.longitude::DOUBLE, 3)
+  WHERE {{expr}} IS NOT NULL
+),
+totals AS (
+  SELECT date, count(*) AS n_total, sum(weight) AS weight_total
+  FROM cells
+  GROUP BY 1
+)
+SELECT
+  c.date                                    AS date,
+  c.class                                   AS class,
+  count(*)                                  AS n,
+  sum(c.weight)                             AS weight,
+  sum(c.weight) / any_value(t.weight_total) AS fraction,
+  100.0 * count(*) / any_value(t.n_total)   AS percent_cells
+FROM cells c
+JOIN totals t USING (date)
+GROUP BY c.date, c.class
+ORDER BY 1, 2

package/sql/stats_daily.sql

@@ -0,0 +1,27 @@
+-- daily key statistics for one place from an ERDDAP griddap slab.
+--   {{expr}}  the value expression over the slab alias `s` (e.g. s."CRW_SST", or
+--             (s."analysed_sst" - 273.15) to convert Kelvin to Celsius)
+--   {{slab}}  the registered griddap file (parquet) or view
+--   {{mask}}  the mask table: latitude, longitude, weight (0,1]
+-- the join is an exact equality on ROUND(x, 3): the ERDDAP axis is float32 in the parquet and float64
+-- in the JS mask, so 21.375 arrives as 21.374999... on one side; rounding to the grid's 3 decimals
+-- (0.05 spacing) makes the two match without a tolerance join.
+SELECT
+  -- utc day; via epoch_ms because duckdb-wasm ships without icu, so TIMESTAMPTZ::DATE is unimplemented there
+  make_timestamp(epoch_ms(s."time") * 1000)::DATE   AS date,
+  count({{expr}})                                  AS n,
+  avg({{expr}})                                    AS mean,
+  sum({{expr}} * m.weight) / sum(m.weight)         AS mean_wt,
+  stddev_samp({{expr}})                            AS sd,
+  min({{expr}})                                    AS min,
+  max({{expr}})                                    AS max,
+  quantile_cont({{expr}}, 0.10)                    AS p10,
+  quantile_cont({{expr}}, 0.90)                    AS p90,
+  sum(m.weight)                                     AS weight_sum
+FROM {{slab}} s
+JOIN {{mask}} m
+  ON  ROUND(s.latitude::DOUBLE,  3) = ROUND(m.latitude::DOUBLE,  3)
+  AND ROUND(s.longitude::DOUBLE, 3) = ROUND(m.longitude::DOUBLE, 3)
+WHERE {{expr}} IS NOT NULL
+GROUP BY 1
+ORDER BY 1

package/sql/stats_tabledap.sql

@@ -0,0 +1,36 @@
+-- monthly key statistics for one place from an ERDDAP **tabledap** slab (point samples).
+--   {{expr}}  the value expression over the slab alias `s` (e.g. s."measurement_value")
+--   {{slab}}  the registered tabledap file (parquet) or view
+--   {{mask}}  the station table: latitude, longitude (weight is 1 — a point is in or out)
+-- tabledap points are sparse and irregular, so the roll-up is by **month**, not by day: a CalCOFI
+-- quarterly cruise gives a handful of days a year, and a daily grouping would be mostly empty.
+-- `n_casts` counts the distinct sampling events (time x position) behind the n measurements, since
+-- one cast contributes many depths.
+-- the join is an exact equality on ROUND(x, 5): the station positions come back out of DuckDB, go
+-- through the JS point-in-polygon mask and come back in, so five decimals (~1 m) is exact here.
+WITH pts AS (
+  SELECT
+    -- utc, via epoch_ms because duckdb-wasm ships without icu: TIMESTAMPTZ::DATE is unimplemented there
+    make_timestamp(epoch_ms(s."time") * 1000) AS ts,
+    s.longitude::DOUBLE                       AS longitude,
+    s.latitude::DOUBLE                        AS latitude,
+    {{expr}}                                  AS value
+  FROM {{slab}} s
+  JOIN {{mask}} m
+    ON  ROUND(s.latitude::DOUBLE,  5) = ROUND(m.latitude::DOUBLE,  5)
+    AND ROUND(s.longitude::DOUBLE, 5) = ROUND(m.longitude::DOUBLE, 5)
+  WHERE {{expr}} IS NOT NULL
+)
+SELECT
+  date_trunc('month', ts)::DATE                  AS date,
+  count(value)                                   AS n,
+  count(DISTINCT (ts, longitude, latitude))      AS n_casts,
+  avg(value)                                     AS mean,
+  stddev_samp(value)                             AS sd,
+  min(value)                                     AS min,
+  max(value)                                     AS max,
+  quantile_cont(value, 0.10)                     AS p10,
+  quantile_cont(value, 0.90)                     AS p90
+FROM pts
+GROUP BY 1
+ORDER BY 1