@nika-js/onlymap 0.6.0 → 0.6.2

package/dist/snapping.d.ts

@@ -0,0 +1,88 @@
+/**
+ * XY snapping (spec: issue #34 Part A). Two-stage, deliberately NOT a
+ * spatial index: deck.gl's own hover/click pick already tells us WHICH
+ * feature is under the cursor (stage 1 — free, runs every frame regardless
+ * of snapping) — this module refines that ONE feature's own geometry to
+ * the nearest vertex/edge/midpoint within a pixel tolerance (stage 2, CPU,
+ * only when snapping is on). OnlyMapJS never calls `pickObject` itself for
+ * this; the resolver runs on the SAME `PickingInfo` runtime-core.ts's
+ * existing `onHover`/`onClick` callbacks already receive every frame, at
+ * the exact point they currently discard everything but a bare
+ * `[lng, lat]` (see `coordOf`'s call sites).
+ *
+ * Agent vocabulary follows ArcGIS (the lingua franca every surveyor
+ * already knows): Vertex, Edge, Midpoint here; Endpoint/Intersection/
+ * Point-cloud/Snap-to-sketch are documented follow-ups (see the module's
+ * own README section on issue #34), Tangent skipped outright (CAD
+ * heritage, no geospatial use). "Closest wins" is NOT the tie-break when
+ * two agents both have a candidate within tolerance — Vertex beats
+ * Midpoint beats Edge (ArcGIS's own conflict order: a midpoint sitting
+ * near an edge should snap to the more specific point, not the general
+ * one), ties WITHIN one agent broken by distance.
+ */
+export type SnapAgent = "vertex" | "edge" | "midpoint";
+export declare const SNAP_AGENTS: readonly SnapAgent[];
+export declare const DEFAULT_SNAP_TOLERANCE_PX = 12;
+export interface SnapConfig {
+    agents: ReadonlySet<SnapAgent>;
+    tolerancePx: number;
+}
+export interface SnapResult {
+    /** The snapped [lng, lat] — interpolated for edge/midpoint, exact for vertex. */
+    position: [number, number];
+    agent: SnapAgent;
+    /** The snapped point's elevation in meters, when the matched geometry carried one — for ANCHORING UI at the visible point (the snap tip); the position contract itself stays XY. */
+    elevation?: number;
+}
+/** Minimal viewport contract this module needs — matches deck.gl's real `Viewport.project`. */
+export interface SnapViewport {
+    project(coordinate: number[]): number[];
+}
+interface GeoJsonGeometryLike {
+    type: string;
+    coordinates: unknown;
+}
+/**
+ * `snap="vertex edge midpoint"` / `snap-tolerance="12"` on `<om-map>` →
+ * `SnapConfig`, or `null` when `snap` is absent/empty (the common case,
+ * must stay free — no pickingRadius change, no per-pick resolver call).
+ * Unrecognized tokens (a typo, or a future agent not implemented yet) are
+ * silently dropped rather than rejecting the whole attribute — validation.ts's
+ * `validateSnap` carries the loud version of that same check.
+ */
+export declare function parseSnapAttrs(getAttr: (name: string) => string | null): SnapConfig | null;
+/**
+ * The geometry a picked object can be snapped against. GeoJSON-shaped
+ * objects (GeoJsonLayer, MVT, draw features) carry it directly — but MOST
+ * OnlyMapJS data is flat rows (CSV/JSON + `get-position` accessors), whose
+ * picked object is just the row, with no `.geometry` at all: snapping
+ * silently found nothing on them (reported: "doesn't detect the vertices in
+ * most of my data"). For those, the layer's own resolved accessors ARE the
+ * geometry — evaluate them against the picked row exactly the way the
+ * layer's shader binding did: `get-polygon` → Polygon, `get-path` →
+ * LineString, `get-source-position`+`get-target-position` → a two-point
+ * LineString, `get-position` → Point.
+ *
+ * Guarded to geographic layers: a layer in an offset/cartesian coordinate
+ * system (a BIM mesh sublayer, a local-frame point cloud) yields raw local
+ * meters from these accessors, not lng/lat — callers handle those through
+ * their own conversion branches (see resolveMapPoint's BIM-edges path).
+ */
+export declare function geometryFromPick(layerProps: Record<string, unknown>, object: unknown): GeoJsonGeometryLike | null;
+/**
+ * Resolves a hover/click's cursor against ONE already-picked feature's
+ * geometry. `cursorPx`/`viewport` project every candidate to screen for
+ * pixel-accurate proximity; the winning MAP-space position is derived by
+ * interpolating the geometry's own [lng, lat] vertices with the SAME
+ * fraction found in screen space (an approximation for edge/midpoint on a
+ * long, steeply-projected segment, but exact for the vertex agent, and
+ * consistent with this codebase's own documented sphere-vs-ellipsoid,
+ * screen-space-drag-math tradeoffs elsewhere — e.g. geodesy.ts, the
+ * clip-box gizmo). Returns `null` when nothing is within tolerance, or the
+ * geometry type isn't one `extractRings` understands (e.g. a raw
+ * meter-offsets row, which this module does not attempt to project itself
+ * — see this file's own header comment on BIM/PathLayer content being a
+ * documented follow-up).
+ */
+export declare function resolveSnap(geometry: GeoJsonGeometryLike | null | undefined, cursorPx: readonly number[], viewport: SnapViewport, config: SnapConfig): SnapResult | null;
+export {};

package/dist/terrain-heightfield.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Bulk terrain heightfield (spec item C2 / "Elevation profile" — the shared
+ * infrastructure both reference, "sampling shares C2's bulk heightfield, not
+ * per-point elevationAt()"). `terrain-sample.ts`'s `sampleTerrainElevation`
+ * is one fetch per point — fine for volume mode's handful of footprint
+ * vertices, but the wrong shape for a profile's tens-to-hundreds of samples
+ * along a line or the volumetrics grid's 10⁵–10⁶ cells: nearby points share
+ * DEM tiles, so fetching (and decoding) each tile once and reading every
+ * point out of it in memory is both fewer round-trips and what the per-cell
+ * volume integrator (volumetrics.ts) builds on.
+ *
+ * This module is the DOM-TOUCHING half (fetch + canvas decode); the pixel
+ * math — bilinear sampling with tile-seam handling — lives in
+ * volumetrics.ts's `sampleBilinear`, which is pure and shared with the
+ * volumetrics worker (decoded tiles postMessage across; canvases don't).
+ */
+import type { LngLat } from "./geodesy";
+import type { TerrainIR } from "./terrain";
+import { type HeightfieldTiles } from "./volumetrics";
+/** A resolved, in-memory set of DEM tiles — `elevationAt` never touches the network. */
+export interface TerrainHeightfield {
+    /** Ground elevation (meters) at `lngLat` — bilinear-interpolated, seam-correct — or `null` if no covering tile loaded/decoded. Ignores `terrain.exaggeration`, same as `sampleTerrainElevation`. */
+    elevationAt(lngLat: LngLat): number | null;
+    /** The raw decoded tile set — the transferable form volumetrics.ts (and its worker) consume directly. */
+    tiles: HeightfieldTiles;
+}
+/**
+ * Resolves every DEM tile `points` touches — INCLUDING the neighbor tiles a
+ * bilinear read at a tile-edge point spills into (the seam case: a point
+ * within half a pixel of a tile border reads up to 3 pixels from adjacent
+ * tiles; without pre-loading those, edge points would silently degrade to
+ * fewer-corner interpolation) — fetches + decodes each ONE TIME
+ * (deduplicated, in parallel), and returns a synchronous bilinear lookup. A
+ * tile that fails to load makes points inside it resolve to `null` (same
+ * "treat as no terrain" contract as `sampleTerrainElevation`) without
+ * affecting other tiles.
+ */
+export declare function loadHeightfield(points: LngLat[], terrain: TerrainIR): Promise<TerrainHeightfield>;
+/**
+ * Resolves the DEM tile set COVERING a lng/lat bounding box — the
+ * volumetrics grid's shape of demand ("every cell inside the polygon's
+ * bbox"), which a point list can't express without enumerating 10⁶ cells.
+ * Starts at the provider's `maxZoom` and steps down until the cover fits
+ * `MAX_BOUNDS_TILES` — the returned `tiles.zoom` records what was actually
+ * used, and the integrator derives its GSD (and error model) from that, so
+ * a coarsened cover is REPORTED coarser, never silently pretended finer.
+ */
+export declare function loadHeightfieldForBounds(bounds: {
+    west: number;
+    south: number;
+    east: number;
+    north: number;
+}, terrain: TerrainIR): Promise<TerrainHeightfield>;

package/dist/terrain-sample.d.ts

@@ -0,0 +1,30 @@
+/**
+ * One-shot terrain elevation sampling (spec: "Cut/fill volume measurement").
+ * Kept separate from terrain.ts, whose header documents it as PURE and
+ * unit-testable without a GPU — this module is deliberately the DOM-touching
+ * half (fetch + canvas), for the one thing nothing else in this codebase
+ * needed before: "what is the real ground height at this lng/lat".
+ *
+ * Fetches the DEM tile as a blob (never an `<img src>`) so the canvas read
+ * below is never tainted regardless of the provider's CORS posture — and
+ * since deck.gl's own TerrainLayer already fetches this exact URL template
+ * cross-origin to RENDER the surface, a caller only ever reaches this with a
+ * URL that's already proven fetchable.
+ */
+import type { LngLat } from "./geodesy";
+import type { TerrainIR } from "./terrain";
+/** Slippy-map tile + fractional pixel covering `lngLat` at `zoom` (256px tiles). Exported for `terrain-heightfield.ts`'s bulk loader — same tile math, no reason to duplicate it. */
+export declare function tilePixel(lngLat: LngLat, zoom: number): {
+    x: number;
+    y: number;
+    px: number;
+    py: number;
+};
+/**
+ * Ground elevation (meters) at `lngLat`, decoded from `terrain`'s DEM at its
+ * configured `maxZoom`. `null` on any fetch/decode failure — the caller
+ * treats that the same as "no terrain": flat ground at 0m, not a thrown error.
+ * Ignores `terrain.exaggeration` deliberately: that scales the RENDERED
+ * surface for legibility, volume math wants the true decoded height.
+ */
+export declare function sampleTerrainElevation(lngLat: LngLat, terrain: TerrainIR): Promise<number | null>;

package/dist/terrain.d.ts

@@ -99,7 +99,12 @@ export interface TerrainLayerPatch {
 /**
  * Per-layer terrain patches, PURE. `terrainActive` false → identity patches
  * (stable ids, no props). Runtime-internal layers (trace temps, draw
- * preview, tooltip plumbing) never drape — they're screen-space/transient.
+ * preview, tooltip plumbing) default OFF — they're screen-space/transient —
+ * but an internal layer that explicitly sets `terrain` (spec: "Cut/fill
+ * volume measurement": the shared draw-preview and measure's committed-
+ * geometry/label layers opt into "drape" so their 2D lng/lat vertices sit ON
+ * the terrain surface instead of at literal sea level, invisible below/
+ * behind a raised mesh) wins over that default, same as an authored layer.
  */
 export declare function applyTerrain(irs: readonly LayerIR[], terrainActive: boolean, generation: number): Map<string, TerrainLayerPatch>;
 /**

package/dist/testing.d.ts

@@ -49,8 +49,12 @@ export interface TestHarness {
      * selection path a real pick takes. Settles before resolving.
      */
     pick(opts: PickOptions): Promise<void>;
-    /** Ends the current selection (a hover-off) — the path that auto-hides tooltips. */
-    clearSelection(): Promise<void>;
+    /**
+     * Ends the current selection with an empty pick. Default kind "hover" — a
+     * hover-off, the path that auto-hides tooltips. Pass "click" for a click on
+     * empty space, which is what dismisses a `selection-type="click"` popup.
+     */
+    clearSelection(kind?: "hover" | "click"): Promise<void>;
     /**
      * Feeds a map coordinate through the same path a real deck click/hover
      * takes — drives the draw controller and fires the `om-map-point` event.

package/dist/tile3d-metadata.d.ts

@@ -0,0 +1,185 @@
+/**
+ * BIM feature-picking epic, Phase 1 (design pending — see
+ * agent-map-library-architecture.md once the design section lands).
+ *
+ * Enriches a Tile3DLayer pick with whatever metadata is CHEAPLY available at
+ * tile granularity — no shader work, no new manifest attribute, no per-tile
+ * caching, no new deck.gl prop injection. Three independent sources merge,
+ * most-content-specific winning when more than one is present:
+ *
+ * 1. glTF `EXT_mesh_features` + `EXT_structural_metadata`, already fully
+ *    decoded by loaders.gl's GLTFLoader by the time a tile is even
+ *    renderable (`Tile3D.content.gltf`, post `postProcessGLTF` — verified
+ *    against node_modules/@loaders.gl/{gltf,3d-tiles} source: primitive
+ *    `.extensions` and the top-level `EXT_structural_metadata` survive the
+ *    postprocess step via object spread, so the same decode this repo's
+ *    Phase-0 spike proved against a real fixture applies here unchanged).
+ *    Only used when the content resolves to exactly ONE feature — Phase 1
+ *    has no per-vertex resolution (that's Phase 2's `pick-features` shader
+ *    work), so a multi-feature content would be misattributing properties
+ *    to whichever vertex the coarse tile-level pick happened to return.
+ * 2. **Legacy 3D Tiles 1.0 batch tables** — b3dm's older per-feature
+ *    mechanism (a JSON `batchTableJson` of `{propertyName: [oneValuePerBatch]}`
+ *    arrays, keyed by a `_BATCHID` vertex attribute never surfaced by this
+ *    layer since Phase 1 doesn't do per-vertex work). Verified directly
+ *    against real production data (NYC DoITT building footprints and Japan's
+ *    PLATEAU CityGML export, both streamed live via Cesium ion): real-world
+ *    3D Tiles datasets overwhelmingly still ship this older mechanism, not
+ *    1.1's `EXT_structural_metadata` — this is the metadata source that
+ *    actually matters for content people can get their hands on today, not
+ *    just synthetic samples. loaders.gl's b3dm parser
+ *    (`parse-3d-tile-tables.js`) sets `tile.featureTableJson.BATCH_LENGTH`
+ *    and `tile.batchTableJson` directly on the SAME parsed-content object
+ *    `.gltf` lives on (confirmed by reading the parser itself — no
+ *    intermediate class wraps it). Same single-feature-only restriction as
+ *    the glTF path, same reasoning: `BATCH_LENGTH === 1` is unambiguous,
+ *    `BATCH_LENGTH > 1` needs per-vertex `_BATCHID` resolution this layer
+ *    doesn't attempt.
+ * 3. 3D Tiles 1.1's OWN (non-glTF) metadata mechanism — tileset/group/tile/
+ *    content-level entities declared directly in tileset.json as plain
+ *    inline JSON (no binary property-table decode needed at this
+ *    granularity, unlike the glTF one — verified against a real tileset.json,
+ *    CesiumGS/3d-tiles-samples 1.1/MetadataGranularities). loaders.gl's
+ *    `Tile3D` retains the raw tile node verbatim on `.header`, and
+ *    `Tileset3D` retains the raw parsed tileset.json on `.tileset`, so this
+ *    reads entirely off already-retained data.
+ */
+interface MetadataEntity {
+    class?: string;
+    properties?: Record<string, unknown>;
+}
+interface GltfPropertyTable {
+    class?: string;
+    count: number;
+    /** Decoded column data. NOT numeric-only — STRING properties decode to `string[]`, which is what most BIM classification fields are. */
+    properties?: Record<string, {
+        data?: ArrayLike<unknown>;
+    }>;
+}
+export interface GltfExtStructuralMetadata {
+    schema?: {
+        classes?: Record<string, {
+            name?: string;
+        }>;
+    };
+    propertyTables?: GltfPropertyTable[];
+}
+interface GltfMeshFeaturesId {
+    attribute?: number;
+    /** Present instead of `attribute` for "feature ID by texture coordinates" sets — see resolvePrimitiveFeatureIdSet. */
+    texture?: {
+        index?: number;
+        texCoord?: number;
+        channels?: number[];
+    };
+    propertyTable?: number;
+    data?: ArrayLike<number>;
+}
+export interface GltfPrimitiveLike {
+    extensions?: {
+        EXT_mesh_features?: {
+            featureIds?: GltfMeshFeaturesId[];
+        };
+    };
+}
+/**
+ * Finds the `EXT_mesh_features` feature-ID set selected by a `_FEATURE_ID_N`
+ * name (the manifest's `feature-id-property`, default `_FEATURE_ID_0`) on one
+ * glTF primitive. Returns null when the primitive carries no usable feature
+ * IDs (a plain, non-BIM mesh — the common case until real IFC-derived content
+ * is loaded).
+ *
+ * `EXT_mesh_features` defines THREE ways to carry feature IDs, and N selects
+ * across all of them:
+ *
+ * - **By vertex** (`attribute: N` -> the `_FEATURE_ID_N` vertex attribute).
+ *   Matched by attribute number first, so an explicitly numbered set always
+ *   wins over its position in the array.
+ * - **By texture** (`texture: {...}`, no `attribute`) — how photogrammetry
+ *   classification datasets carry per-element IDs, since a photogrammetry
+ *   mesh is one triangle soup with the classification painted on. These sets
+ *   have no attribute number to match, so N falls back to selecting the Nth
+ *   entry of the `featureIds` array — the same positional convention the
+ *   extension's own `featureId_N` shader naming uses.
+ * - **By index** (neither field; the vertex's own index is its feature ID).
+ *   loaders.gl leaves `data` empty for these, so they resolve to null here.
+ *
+ * CAVEAT for texture-backed sets: loaders.gl decodes them by sampling the
+ * feature-ID texture once PER VERTEX at that vertex's UV
+ * (`getPrimitiveTextureData`), not per fragment. The resulting IDs are
+ * therefore only as precise as the mesh is dense — a classification boundary
+ * that runs through the middle of a triangle is lost, and that triangle takes
+ * whichever ID its vertices sampled. Good enough to pick an element, not
+ * equivalent to a per-fragment lookup.
+ *
+ * Note both texture and index sets require the glTF to be loaded with
+ * `loadBuffers` (and, for textures, `loadImages`); without them loaders.gl
+ * leaves `data` undefined/empty and this returns null.
+ */
+export declare function resolvePrimitiveFeatureIdSet(primitive: GltfPrimitiveLike | undefined, featureIdProperty: string): {
+    data: ArrayLike<number>;
+    propertyTable?: number;
+    texture?: GltfMeshFeaturesId["texture"];
+    nullFeatureId?: number;
+} | null;
+/**
+ * Reads ONE property of a decoded property table as a column — one entry per
+ * feature ID, indexed by feature ID.
+ *
+ * This is the row-major counterpart to `resolveGltfFeatureRow`: the declarative
+ * `hide-features`/`ghost-features`/`isolate-features` attributes need to test
+ * a single field across EVERY feature at once, and building a full properties
+ * object per row just to read one key would allocate the whole table to answer
+ * a one-column question. Returns null when the table or property is absent.
+ */
+export declare function readPropertyColumn(structuralMetadata: GltfExtStructuralMetadata | undefined, propertyTableIndex: number | undefined, property: string): unknown[] | null;
+/**
+ * The WHOLE property table as row objects, indexed by feature ID.
+ *
+ * Picking resolves one row at a time, which is right for a hover but useless
+ * for anything that needs the set: a legend listing every IfcClass, a category
+ * palette, a model tree. Those previously had to fetch a hand-built sidecar
+ * next to the tileset. This reads the same table the GLB already carries.
+ */
+export declare function extractPropertyTableRows(structuralMetadata: GltfExtStructuralMetadata | undefined, propertyTableIndex: number | undefined): Record<string, unknown>[] | null;
+/**
+ * Resolves one feature's properties out of a specific decoded property
+ * table, by row index — the general case (Phase 2: `rowIndex` is the
+ * per-vertex feature ID; Phase 1's single-feature path below is just this
+ * with `rowIndex = 0` on a `count === 1` table). Returns null for an
+ * out-of-range table/row (defensive — a malformed or partially-loaded tile
+ * should degrade to "no properties," not throw during picking).
+ */
+export declare function resolveGltfFeatureRow(structuralMetadata: GltfExtStructuralMetadata | undefined, propertyTableIndex: number | undefined, rowIndex: number): {
+    properties: Record<string, unknown>;
+    class: string | null;
+} | null;
+export interface Tile3DPickMetadata {
+    /** Merged properties, most-specific source wins: glTF content / legacy batch table > 3D-Tiles content > tile > group > tileset. Empty object if nothing resolved. */
+    properties: Record<string, unknown>;
+    /** The class name of the most specific contributing source, or null if nothing resolved. */
+    class: string | null;
+    /** Best-effort identity (IFC GlobalId / gml:id / guid), or null — see findGuidLike. */
+    guid: string | null;
+    /** Unmerged, per-source view — the escape hatch. Deck.gl/loaders.gl shapes leak here deliberately, unlike `properties`/`class`. */
+    rawMetadata: {
+        tileset?: MetadataEntity;
+        group?: MetadataEntity;
+        tile?: MetadataEntity;
+        content?: MetadataEntity;
+        gltfProperties?: Record<string, unknown>;
+        gltfClass?: string;
+        batchTableProperties?: Record<string, unknown>;
+        batchTableClass?: string;
+    };
+}
+/**
+ * Resolves whatever tile-granularity BIM metadata is available for a
+ * Tile3DLayer pick. `sourceTile` is `PickingInfo.sourceTile` (Tile3DLayer's
+ * own `getPickingInfo` always sets it, undefined for a miss) — callers
+ * should only invoke this once they know the pick landed on a
+ * `carriesTileset` layer. Returns null when nothing resolved (a tileset
+ * with no metadata at all — the common case today, since this is new).
+ */
+export declare function resolveTile3DPickMetadata(sourceTile: unknown): Tile3DPickMetadata | null;
+export {};

package/dist/units.d.ts

@@ -22,6 +22,33 @@ export declare function formatLength(meters: number, system?: UnitSystem): strin
  * question 1 — nmi² is not a denomination users read).
  */
 export declare function formatArea(m2: number, system?: UnitSystem): string;
+/**
+ * Format a volume (m³, spec: "Cut/fill volume measurement"), with denomination
+ * crossover. Metric: m³, crossing to "×10³ m³" past 1000 m³ (the km² crossover
+ * shape). Imperial: cubic yards — the real-world earthworks unit, not ft³ — with
+ * the same ×10³ crossover. Nautical falls back to metric (formatArea's own
+ * documented fallback: nmi³ is not a denomination anyone reads).
+ */
+export declare function formatVolume(m3: number, system?: UnitSystem): string;
+/**
+ * Format a mass (kg, spec item D — "tonnage"), with denomination crossover.
+ * Metric: tonnes ("t"), crossing to "×10³ t" past 1000 t (matching
+ * {@link formatVolume}'s own crossover shape). Imperial: US short tons
+ * ("ton", 2000 lb) — the earthworks-industry convention, not the UK long
+ * ton. Nautical falls back to metric (formatArea/formatVolume's own
+ * documented fallback).
+ */
+export declare function formatMass(kg: number, system?: UnitSystem): string;
+/**
+ * Convert an author-provided density (spec item D — `density` attribute) to
+ * canonical kg/m³, interpreted per the ACTIVE unit system at the moment it's
+ * set: metric authors give t/m³ (tonnes per cubic meter — the earthworks
+ * convention, e.g. 1.6-1.8 for common soil), imperial authors give lb/yd³.
+ * Nautical falls back to the metric (t/m³) reading. Canonicalizing once here
+ * means a later unit-system TOGGLE (the widget's own units buttons) doesn't
+ * need to re-interpret an already-set density — kg/m³ is unit-system-agnostic.
+ */
+export declare function densityToKgM3(raw: number, system: UnitSystem): number;
 /**
  * The largest 1/2/3/5 ×10ⁿ value ≤ `value` (GL's log10 "nice number"). Used by
  * the scale bar to snap its bar to a round distance. log10-based, so it is

package/dist/version.d.ts

@@ -5,4 +5,4 @@
  * the build rootDir, and a `define` would need repeating across vite/vitest/
  * vite-node configs.
  */
-export declare const LIBRARY_VERSION = "0.6.0";
+export declare const LIBRARY_VERSION = "0.6.2";

package/dist/volumetrics-run.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Volumetrics runner — dispatches a `VolumetricsRequest` to the inline-blob
+ * Web Worker (volumetrics-worker.ts) and falls back to a synchronous
+ * main-thread `computeVolumetrics` call when worker construction isn't
+ * possible (no `Worker` global — headless test environments, exotic
+ * embeddings), exactly raster.ts's COG-decode posture: "slower, but never
+ * blank." One fresh worker per run, terminated on completion — integrations
+ * fire once per footprint commit (not per frame; drag frames re-sum the
+ * CACHED grid via `reintegrateCustomBase` without ever coming back here),
+ * so a persistent pool would be state without a workload.
+ */
+import { type VolumetricsRequest, type VolumetricsResult } from "./volumetrics";
+export declare function runVolumetrics(req: VolumetricsRequest): Promise<VolumetricsResult>;

package/dist/volumetrics-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/volumetrics.d.ts

@@ -0,0 +1,201 @@
+/**
+ * Volumetric integration core (spec: issue #35 "Volumetric measurement —
+ * cut/fill against a base surface, with a published error model"; grid
+ * design per §C of the acceptance spec: C1 tangent-plane grid, C2 bulk
+ * heightfield sampling, C3 scanline point-in-polygon).
+ *
+ * PURE by design — no DOM, no fetch, no globals. This module runs both on
+ * the main thread and inside `volumetrics-worker.ts` (the issue's "all of it
+ * in a worker"), so the heightfield arrives as already-decoded pixel buffers
+ * (`HeightfieldTiles`, produced by terrain-heightfield.ts's DOM half) and
+ * everything here is arithmetic over them.
+ *
+ * The three load-bearing choices, per the spec:
+ *
+ * C1 — the grid lives in a LOCAL TANGENT-PLANE metric frame at the ring
+ * centroid (x = R·cos(φ₀)·Δλ, y = R·Δφ, on the same measure sphere as
+ * geodesy.ts), NOT in lng/lat ("cell size 0.25m" is meaningless in degrees)
+ * and NOT in uncorrected Web Mercator (linear scale sec(φ) → area/volume
+ * error sec²(φ), +100% at 45° latitude). Equirectangular error over a
+ * stockpile-sized extent (≤ a few km) is ~10⁻⁵ — far below the DEM's own
+ * z noise.
+ *
+ * C2 — the heightfield is bulk-decoded ONCE upstream and bilinear-sampled
+ * in memory here; never an async per-cell fetch (a fine grid is 10⁵–10⁶
+ * cells — one network call per cell is dead on arrival).
+ *
+ * C3 — point-in-polygon by SCANLINE, not per-cell ray-cast: per grid row,
+ * intersect ring edges with the row's y, sort crossings, fill spans —
+ * O(rows × edges + inside cells) instead of O(cells × edges), and it emits
+ * exactly the inside-cell runs the integrator iterates. Fractional
+ * boundary-cell coverage is deliberately skipped (documented; the market
+ * leader doesn't bother either).
+ */
+import type { LngLat } from "./geodesy";
+export interface ElevationDecoderSpec {
+    rScaler: number;
+    gScaler: number;
+    bScaler: number;
+    offset: number;
+}
+/** One decoded DEM tile — plain buffers so the whole set can postMessage to the worker (Uint8ClampedArray is structured-cloneable, and its ArrayBuffer transferable). */
+export interface HeightfieldTile {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    data: Uint8ClampedArray;
+}
+/** The serializable heightfield: every decoded tile at one zoom + the decoder. Produced by terrain-heightfield.ts, consumed here (main thread or worker). */
+export interface HeightfieldTiles {
+    zoom: number;
+    tiles: HeightfieldTile[];
+    decoder: ElevationDecoderSpec;
+}
+/**
+ * Bilinear heightfield sample at `lngLat`, correct across TILE SEAMS.
+ *
+ * Works in global fractional pixel space at the heightfield's zoom, in each
+ * tile's NATIVE resolution scaled to a common 256-per-tile grid: the four
+ * pixels around the sample point may live in up to four different tiles, and
+ * each is looked up in whichever tile owns it. Corners whose tile is missing
+ * or failed drop out and the remaining weights renormalize — a point right
+ * at the edge of available data degrades gracefully toward nearest-available
+ * rather than snapping to `null`; only a point with NO available corner
+ * returns `null` ("no data", the caller's skip-and-count contract).
+ *
+ * Native-resolution note: tiles can ship at 512px. Sampling positions are
+ * computed in 256-grid units (matching `tilePixel`'s convention) and each
+ * corner reads the native pixel COVERING that 256-grid cell — bilinear over
+ * the 256 grid is slightly coarser than the 512 tile could support, but is
+ * consistent across mixed-resolution tile sets and matches the GSD the error
+ * model reports.
+ */
+export declare function sampleBilinear(hf: HeightfieldTiles, lngLat: LngLat, tileIndex?: Map<string, HeightfieldTile>): number | null;
+/** Key the tile list for O(1) lookup — build once per batch of samples, pass into `sampleBilinear` (it rebuilds per call otherwise). */
+export declare function buildTileIndex(hf: HeightfieldTiles): Map<string, HeightfieldTile>;
+/**
+ * Base-surface strategies (spec: "Multiple Base Surfaces"):
+ * - `custom`: a constant elevation — the interactive gizmo's target plane
+ *   (drag sets `customZ`), and the direct successor of the v1 flat math.
+ * - `plane`: least-squares plane fit to the ring's own boundary elevations —
+ *   the right base for a stockpile on visibly sloped ground.
+ * - `lowest` / `highest` / `average`: constant at the boundary's min/max/mean
+ *   elevation.
+ * - `triangulated`: boundary TIN (Delaunay over densely-resampled boundary
+ *   points, interpolated per cell) — the industry default for stockpiles,
+ *   since it follows the toe of the pile all the way around.
+ */
+export type BaseSurfaceKind = "custom" | "plane" | "lowest" | "highest" | "average" | "triangulated";
+export declare const BASE_SURFACE_KINDS: readonly BaseSurfaceKind[];
+export declare function parseBaseSurface(raw: string | null | undefined): BaseSurfaceKind | null;
+export interface BaseSurfaceSpec {
+    kind: BaseSurfaceKind;
+    /** Required for `kind: "custom"` — the target plane's elevation in meters. */
+    customZ?: number;
+}
+export interface VolumetricsRequest {
+    /** Footprint ring, lng/lat, open or closed (normalized internally). */
+    ring: LngLat[];
+    heightfield: HeightfieldTiles;
+    base: BaseSurfaceSpec;
+    /** The measure sphere radius (pass `getMeasureRadiusMeters()` — a parameter so this module stays free of mutable global state, worker included). */
+    radiusM: number;
+    /**
+     * Boundary elevation samples for the non-custom base surfaces — lng/lat
+     * plus the elevation the caller sampled there (they ride the same
+     * heightfield; the caller already has them for the profile). Converted to
+     * the internal tangent frame here, so the caller never has to reproduce
+     * this module's frame math. Required for `plane`/`lowest`/`highest`/
+     * `average`/`triangulated`; ignored for `custom`.
+     */
+    boundary?: Array<{
+        position: LngLat;
+        z: number;
+    }>;
+    /** Cell-count budget — cell size grows from the DEM's GSD until the grid fits. Default 1.5M. */
+    maxCells?: number;
+    /** Return the per-cell grids (`zTerrain`, `inside`) for cheap re-integration on gizmo drag + the heat map. */
+    includeGrid?: boolean;
+}
+export interface VolumetricsGrid {
+    /** Tangent-frame origin (the ring centroid), lng/lat — for projecting the grid back to the map (heat map bounds). */
+    originLngLat: LngLat;
+    /** Grid extent: cell (i, j) center is at x = x0 + (i + 0.5)·cellSize, y = y0 + (j + 0.5)·cellSize in tangent meters. */
+    x0: number;
+    y0: number;
+    nx: number;
+    ny: number;
+    cellSizeM: number;
+    /** Terrain elevation per cell, row-major (j·nx + i). NaN = no data. */
+    zTerrain: Float32Array;
+    /** Base elevation per cell (same layout). NaN outside the ring. */
+    zBase: Float32Array;
+    /** 1 = inside the ring, 0 = outside. */
+    inside: Uint8Array;
+}
+export interface VolumetricsResult {
+    cutM3: number;
+    fillM3: number;
+    netM3: number;
+    totalM3: number;
+    /** The actual cell size used (≥ the DEM's GSD when the budget forced coarsening). */
+    cellSizeM: number;
+    /** The elevation source's native ground-sample distance at the ring's latitude — what the error model is quoted against. */
+    gsdM: number;
+    insideCells: number;
+    /** Inside cells skipped for lack of DEM data (missing/failed tiles). */
+    nodataCells: number;
+    /** ± one-sided error bounds (spec: per-cell `cellArea × 1.5 × GSD_data`, summed separately per side). */
+    cutErrorM3: number;
+    fillErrorM3: number;
+    /** How the base surface resolved (constant z, plane params) — provenance for the readout. */
+    base: {
+        kind: BaseSurfaceKind;
+        z?: number;
+        plane?: {
+            a: number;
+            b: number;
+            c: number;
+        };
+    };
+    grid?: VolumetricsGrid;
+}
+/**
+ * The grid integrator. Everything in the tangent frame at the ring centroid;
+ * per inside cell: z_terrain from the bilinear heightfield, z_base from the
+ * strategy, signed delta accumulated into cut (terrain ABOVE base — material
+ * to remove) or fill (terrain BELOW base — material to add). Mixed cut+fill
+ * within one polygon is the entire point of the per-cell design — the
+ * v1 flat math this replaces could only ever be one or the other.
+ */
+export declare function computeVolumetrics(req: VolumetricsRequest): VolumetricsResult;
+/**
+ * Re-integration for the DEFAULT (non-flat-target) `custom` semantics: the
+ * target surface is the terrain itself offset by one constant depth/height —
+ * "grade this footprint down/up by N meters from wherever the ground is."
+ * Every valid cell moves by exactly `offsetM`, so the result is pure cut OR
+ * pure fill (a parallel offset can never produce both), each cell
+ * contributing |offset| × cell area — closed-form over the SAME per-cell
+ * counts and GSD error model `reintegrateCustomBase` accumulates, so the two
+ * stay directly comparable when the flat-target toggle switches between
+ * them. `base.z` is deliberately absent: no single plane elevation exists.
+ */
+export declare function reintegrateParallelOffset(grid: VolumetricsGrid, offsetM: number, gsdM: number): Omit<VolumetricsResult, "grid" | "base"> & {
+    base: {
+        kind: "custom";
+    };
+};
+/**
+ * Cheap re-integration for the interactive flat-target case: the gizmo drag
+ * changes ONLY the `custom` base plane's z, so a cached grid re-sums in one
+ * arithmetic pass over the terrain samples — no re-sampling, no scanline, no
+ * worker round-trip needed per drag frame. Everything except the base offset
+ * (cell size, GSD, error basis) is inherited from the original result.
+ */
+export declare function reintegrateCustomBase(grid: VolumetricsGrid, customZ: number, gsdM: number): Omit<VolumetricsResult, "grid" | "base"> & {
+    base: {
+        kind: "custom";
+        z: number;
+    };
+};