@nika-js/onlymap 0.6.1 → 0.6.4

package/dist/region-export.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Region 3D export (spec: issue #34 §"Technical Implementation Steps" —
+ * region export; ported from a sibling project's proven implementation
+ * rather than rebuilt from scratch, per direct instruction). Draw a 2D
+ * footprint over loaded 3D Tiles content (BIM/`BIMLayer`, `Tile3DLayer`)
+ * and export exactly the triangles inside it as a portable GLB — or a
+ * b3dm-wrapped GLB for pipelines (Cesium, 3D Tiles tooling) that expect
+ * that container.
+ *
+ * Deliberately simpler than the source implementation in one respect: tile
+ * selection is a plain bbox prefilter (`tileGeoBounds` vs. the ring's own
+ * bbox) rather than the source's mesh-sampling/loose-footprint heuristics —
+ * those exist there to avoid walking every triangle of city-scale national
+ * tilesets before an exact clip; at this library's current single-tileset
+ * (BIM model) scale, bbox-prefilter-then-exact-clip is both simpler and
+ * already correct (a tile outside the ring exact-clips to zero triangles
+ * regardless), and the same geometric pipeline this module already needs
+ * is reused straightforwardly if the heuristic layer becomes worth adding.
+ *
+ * No textures: BIM/IFC materials are flat colors, not textured meshes, so
+ * the UV/image plumbing the source implementation carries is dead weight
+ * here — dropped rather than kept for a case this library doesn't have.
+ * Each triangle's own source color IS carried through, though — baked as
+ * per-vertex `COLOR_0` (see `resolvePrimitiveColor`/`buildGlb`), not left
+ * as an undifferentiated flat gray.
+ *
+ * PURE geometry/binary-writing core (this file) + a thin DOM-touching
+ * driver (`region-export-run.ts`) that resolves the live tileset registry
+ * and triggers the browser download — same split as terrain-sample.ts /
+ * terrain-heightfield.ts.
+ */
+export type LngLatRing = Array<[number, number]>;
+/** Closed (first === last) + CCW — committed draw rings arrive closed, previews open; both normalize the same way. */
+export declare function normalizeRing(ring: LngLatRing): LngLatRing;
+export interface B3dmBatchTable {
+    /** batchLength: number of features encoded in the glb's `_BATCHID`; each property array below must have this length. */
+    batchLength: number;
+    /** Plain-JSON per-feature properties — entry i is feature i's value. Omit for a structurally-valid b3dm with no property data. */
+    properties?: Record<string, unknown[]>;
+}
+export interface RegionExportResult {
+    bytes: Uint8Array;
+    triangleCount: number;
+    format: "glb" | "b3dm";
+}
+/**
+ * Clip every loaded tile's triangles across ALL given tilesets against
+ * `ring`, re-frame the clipped result to a local ENU frame at the ring's
+ * own centroid (portable — most viewers can't display ECEF-scale
+ * coordinates), and pack it as GLB or b3dm. `null` when the ring or the
+ * clip produces nothing (an empty region, or a ring drawn where nothing is
+ * loaded) — the caller reports that distinctly from a thrown error.
+ */
+export declare function computeRegionExport(ring: LngLatRing, tilesets: Map<string, unknown>, options?: {
+    format?: "glb" | "b3dm";
+}): RegionExportResult | null;

package/dist/runtime-core.d.ts

@@ -1,5 +1,8 @@
+import type { PickingInfo } from "@deck.gl/core";
 import { type LightingIR } from "./scene-lighting";
 import { type TerrainIR } from "./terrain";
+import { type ClipBoxIR } from "./clip-box";
+import { type SnapAgent, type SnapConfig } from "./snapping";
 import type { ViewOrigin } from "./external-store";
 import type { LayerIR } from "./ir";
 import { type Selection } from "./selection";
@@ -60,6 +63,18 @@ export interface FeatureTableEntry {
  * feature IDs are tile-local. Returns the (possibly new) entry.
  */
 export declare function accumulateFeatureRows(tables: Map<string, FeatureTableEntry>, layerId: string, sourceKey: string, tileKey: string, rows: Record<string, unknown>[]): FeatureTableEntry;
+/**
+ * The subset of deck.gl's MjolnirGestureEvent a gizmo drag-claim needs (spec:
+ * "Cut/fill volume measurement"). `stopPropagation()` sets the underlying
+ * event's `handled` flag, which `Controller.isPointInBounds` checks before
+ * starting a camera pan — calling it from `onGizmoDragStart` when the gizmo
+ * is the picked layer is what lets a LEFT-button drag on the gizmo win over
+ * the map's own drag-to-pan (deck dispatches its root onDragStart before the
+ * controller's own pan handling for the same gesture, so this is in time).
+ */
+export interface GizmoDragEvent {
+    stopPropagation(): void;
+}
 export interface RuntimeCoreCallbacks {
     /**
      * Fired whenever the view state changes (pan/zoom/pitch/bearing) — a
@@ -86,6 +101,17 @@ export interface RuntimeCoreCallbacks {
      * re-render on every drag-move.
      */
     onDragPick?: (selection: Selection) => void;
+    /**
+     * Raw deck.gl drag lifecycle (spec: "Cut/fill volume measurement"),
+     * forwarded verbatim alongside `onDragPick` — for a controller that owns a
+     * pickable internal layer (the volume tool's height gizmo) and needs the
+     * real `x`/`y`/`viewport`, not a resolved `Selection`. `onDragPick` stays
+     * the mechanism for declarative `on="drag"` behaviors; this is the
+     * mechanism for a controller driving its own layer via patchAnimatedProps.
+     */
+    onGizmoDragStart?: (info: PickingInfo, event: GizmoDragEvent) => void;
+    onGizmoDrag?: (info: PickingInfo) => void;
+    onGizmoDragEnd?: (info: PickingInfo) => void;
     /**
      * Every click/hover's map coordinate (spec: "Manual Drawing"), fired
      * ALONGSIDE onSelectionChange but INCLUDING empty-map events — which
@@ -94,6 +120,23 @@ export interface RuntimeCoreCallbacks {
      * deck reports none (e.g. off-globe).
      */
     onMapPoint?: (coordinate: [number, number] | null, kind: "click" | "hover") => void;
+    /**
+     * XY snapping (spec: issue #34 Part A) — fires ALONGSIDE onMapPoint on
+     * every click/hover, `null` whenever that point ISN'T a snap (no config,
+     * no candidate within tolerance, an opted-out/unsupported layer) — the
+     * snap-tip UI's entire "show only while actually snapped" contract reads
+     * off this being null vs. set, not off onMapPoint's own coordinate.
+     * Carries `position` itself (not just agent/layer) so a consumer never
+     * has to correlate this against a SEPARATE onMapPoint firing in the same
+     * tick to know where to anchor a tip — both already come from the one
+     * `resolveMapPoint` call.
+     */
+    onSnapPoint?: (result: {
+        position: [number, number];
+        agent: SnapAgent;
+        layerId: string;
+        elevation?: number;
+    } | null) => void;
     /**
      * A `pick-features` layer decoded its EXT_structural_metadata property
      * table — the whole table, indexed by feature ID. Fires once per layer, on
@@ -177,6 +220,10 @@ export declare class RuntimeCore {
     private mode;
     /** Layers reconciled while the basemap chunk is still loading — applied on adapter arrival. */
     private pendingLayers?;
+    /** setDrawCapture's last value — composed with dragPanSuppressed by standaloneControllerOverrides. */
+    private drawCaptureActive;
+    /** setDragPan's last value, inverted — see standaloneControllerOverrides. */
+    private dragPanSuppressed;
     /** Retained descriptors — what the per-frame channel re-applies against. */
     private lastIRs;
     /** layerId → effect-driven plain-prop patches (the per-frame channel). */
@@ -210,6 +257,29 @@ export declare class RuntimeCore {
      */
     private terrain;
     private terrainGeneration;
+    /**
+     * Clip box (spec: issue #34 §"Cutting / Clipping") — the retained box IR.
+     * Non-null patches every opted-in layer with `ClipBoxExtension` in
+     * buildLayers (see `applyClipBox`'s own doc comment for the default-
+     * applied, `clip="off"`-to-exclude posture). `clipBoxGeneration` bumps on
+     * every active-state flip, same reason and same fix as terrain's own
+     * generation counter: extension sets must be BIRTH-stable (verified
+     * empirically — a box present from the first render works, toggling one
+     * onto an already-mounted DataFilterExtension-carrying layer silently
+     * blanks it), so patched layers get `#c<generation>`-based deck ids.
+     */
+    private clipBox;
+    private clipBoxGeneration;
+    /** XY snapping (spec: issue #34 Part A) — `null` is the free/common case (no pickingRadius change, resolveMapPoint short-circuits to the plain pick). */
+    private snapConfig;
+    /** See resolveMapPoint's memo comment — the last picked object's derived snap geometry. */
+    private snapGeometryMemo;
+    /** See pickForSnap's memo comment — the non-terrain layer-id list, keyed by the deck layer array's own identity. */
+    private snapLayerIdsMemo;
+    /** Spacebar-held suppression (spec: issue #34 Part A) — deliberately leaves `pickingRadius`/`snapConfig` untouched, only gates `resolveMapPoint`'s refinement step, since the underlying pick tolerance isn't what a user means by "hold to disable snapping momentarily." */
+    private snapSuppressed;
+    /** Per-BIMLayer lonLat/heading/scale, captured off `onGeoreference` (see `BimGeoreferenceInfo`) — `resolveMapPoint`'s only way to convert a picked EdgeRow's raw local vertices back to real `[lng, lat]` for snapping, since that georeference otherwise lives entirely inside BIMLayer's own async load state. */
+    private bimGeoreference;
     /** Rendered deck layer id → authored manifest/controller id (terrain uses fresh renderer ids). */
     private renderedLayerIds;
     /** The decoded property table for a pick-features layer, or undefined before its first tile. */
@@ -300,6 +370,72 @@ export declare class RuntimeCore {
      */
     setTerrain(ir: TerrainIR | null): void;
     getTerrainInternal(): TerrainIR | null;
+    /** Clip box on/off/extent change (spec: issue #34) — no basemap-replacement dance like terrain's (a clip box never changes render mode), just a straight re-apply. Bumps the generation on an active-state flip (fresh deck ids — see the `clipBoxGeneration` field doc). */
+    setClipBox(ir: ClipBoxIR | null): void;
+    getClipBoxInternal(): ClipBoxIR | null;
+    /**
+     * XY snapping on/off + tolerance change (spec: issue #34 Part A). Unlike
+     * clip box/terrain, this never touches the layer list — only deck's
+     * `pickingRadius` (0 by default and never otherwise set in this
+     * codebase; without it a cursor has to land EXACTLY on rendered pixels
+     * to pick anything, which defeats snapping's own point of "near enough
+     * counts") and `resolveMapPoint`'s own read of `this.snapConfig` on the
+     * next pick — no `applyLayers()` needed.
+     */
+    /** Spacebar held/released (spec: issue #34 Part A) — no-op when snapping isn't configured at all. */
+    setSnapSuppressed(suppressed: boolean): void;
+    /**
+     * Whether a snap resolver is actually configured — the ONLY condition under
+     * which om-map's window-level keydown listener may `preventDefault()` the
+     * spacebar. Without this gate, every page embedding an `<om-map>` lost
+     * space-to-scroll and space-to-activate-a-focused-button, snapping
+     * configured or not (`setSnapSuppressed` no-ops in that case, but
+     * `preventDefault` does not).
+     */
+    hasSnapConfig(): boolean;
+    setSnapConfig(config: SnapConfig | null): void;
+    /**
+     * `coordOf` plus snap refinement — the two-stage resolver (see
+     * src/snapping.ts's own header comment): a pick (stage 1) tells us which
+     * feature + viewport are under the cursor; `resolveSnap` (stage 2)
+     * refines that to the nearest vertex/edge/midpoint. Falls back to the
+     * plain pick on no config, no layer/viewport (an empty-map pick), a
+     * `snap="off"` layer, or no candidate within tolerance — `resolveSnap`'s
+     * own `null` covers the last case AND "geometry shape this module
+     * doesn't understand" (e.g. a raw meter-offsets PathLayer row)
+     * identically, which is the right behavior either way: nothing to add,
+     * use the raw pick.
+     *
+     * Stage 1 does NOT simply reuse `info` (deck's own top-level pick that
+     * already drove `onMapPoint`/`onSelectionChange`) whenever terrain is
+     * active — confirmed live, terrain wins deck's pick-buffer resolution
+     * against ANY co-located pickable content, vector or BIM mesh alike,
+     * even where that content visibly, correctly renders on top of it (the
+     * SAME finding already documented on this session's z-tooltip work, one
+     * layer up: there it was worked around with an unscoped hover behavior;
+     * here, where snapping specifically needs to know WHICH non-terrain
+     * feature is under the cursor, that workaround doesn't apply). Instead,
+     * re-picks explicitly via `deck.pickObject`, `layerIds`-restricted to
+     * everything EXCEPT the terrain layer — deliberately narrow (standalone
+     * mode only, terrain's own required mode) rather than a general-purpose
+     * picking API this codebase otherwise avoids.
+     */
+    private resolveMapPoint;
+    /**
+     * See `resolveMapPoint`'s own doc comment for why this re-picks rather than
+     * reusing deck's own top-level `info`. `radius` mirrors the configured
+     * tolerance — a vertex sitting outside the tolerance couldn't win anyway,
+     * and this keeps the explicit re-pick's own search window consistent with
+     * the resolver's.
+     *
+     * The `layerIds` list is memoized against the layer ARRAY's identity: this
+     * runs on every pointer move while snapping is on, and deck only hands out
+     * a new array when the layer set actually changes, so the filter+map runs
+     * per layer-set change instead of per mousemove. (The `pickObject` call
+     * itself is a synchronous GPU readback and remains the real cost here —
+     * this just stops adding avoidable per-move allocation on top of it.)
+     */
+    private pickForSnap;
     private drainSnapshotCaptures;
     /** Settle queued snapshot promises when the renderer they were waiting on goes away (mode flip / destroy) — never leave a caller hanging. */
     private cancelSnapshotCaptures;
@@ -377,6 +513,20 @@ export declare class RuntimeCore {
      * fight drag-pan, so pan stays live.
      */
     setDrawCapture(active: boolean): void;
+    /**
+     * Suspend/restore drag-to-pan while a gizmo is grabbed — otherwise a drag
+     * on the gizmo also pans the camera underneath it. Originally standalone-
+     * only (the volume tool's own height gizmo requires terrain, which always
+     * forces standalone mode — see setTerrain — so it never hit basemap mode
+     * in practice); the clip-box face-handle gizmo (issue #34) has no such
+     * precondition and runs fine with a plain basemap, which surfaced the gap
+     * for real (reported: dragging a handle panned the map underneath it and
+     * the two fighting over every mousemove read as the whole page hanging).
+     * `basemap.setInteractive` is the SAME mechanism setDrawCapture already
+     * uses for doubleClickZoom, just a different MapLibre gesture handler.
+     */
+    setDragPan(active: boolean): void;
+    private standaloneControllerOverrides;
     /**
      * Used by the built-in `zoom-controls` widget's emitted zoom-in/zoom-out
      * intents. Programmatic, so — unlike a user drag/scroll — standalone mode

package/dist/selection.d.ts

@@ -14,7 +14,17 @@ export interface Selection {
      * onSelectionChange), so downstream consumers still always see an object.
      */
     index: number;
-    coordinate: [number, number] | null;
+    /**
+     * `[lng, lat]`, or `[lng, lat, z]` when deck actually ran the depth-pick
+     * pass for this pick (some pickable layer in the scene has `pickable:
+     * '3d'` — see terrain.ts and BIMLayer's own hover picking). Without that
+     * pass deck's `info.coordinate` is the ray∩z=0-plane intersection, not a
+     * real surface point, so a 2-length coordinate here is not "z=0 at this
+     * point" — it's "no z was ever computed," and callers (the hover-tooltip
+     * z field, this session's own concrete use) must treat it as absent, not
+     * zero.
+     */
+    coordinate: [number, number] | [number, number, number] | null;
     pixel: [number, number];
     type: "hover" | "click";
     /**

package/dist/site-placement.d.ts

@@ -68,6 +68,28 @@ export declare function enuMatrix(lonDeg: number, latDeg: number, height?: numbe
  * function rather than an inline `rotateZ`.
  */
 export declare function localPlacementMatrix(p: SitePlacement): Matrix4;
+/**
+ * Companion to `localPlacementMatrix` + `coordinateOrigin` (the outline
+ * overlay's own placement, see this file's header comment) — converts ONE
+ * RAW local vertex (an `EdgeRow.path` point, in the model's own pre-
+ * transform local frame — the exact same value `getPath` hands the
+ * PathLayer) to real `[lng, lat]`, the SAME two steps deck.gl itself
+ * applies to render that vertex on screen: `localPlacementMatrix`'s
+ * `scale * Rz(-heading)` first, THEN interpret the result as an east/north
+ * metre offset from `coordinateOrigin`. Needed for XY snapping (spec:
+ * issue #34 Part A) against the BIM edges overlay specifically: its picked
+ * rows carry this raw local form, not GeoJSON, so `snapping.ts`'s
+ * resolver — which only understands `[lng, lat]` — cannot search them
+ * directly without this.
+ *
+ * The metres-to-degrees step is the standard small-area linear
+ * approximation (matches `getDistanceScales` inside
+ * `@math.gl/web-mercator`, which is what ACTUALLY renders this exact
+ * vertex on screen today — deliberately consistent with that real
+ * projection rather than a more "correct" ellipsoidal model that would
+ * silently disagree with it).
+ */
+export declare function localOffsetToLngLat(local: readonly [number, number], origin: readonly [number, number], heading: number, scale: number): [number, number];
 /**
  * The `Tileset3D.modelMatrix` that moves a tileset anchored at `baked` onto `p`.
  *

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/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.1";
+export declare const LIBRARY_VERSION = "0.6.4";

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 {};