@nika-js/onlymap 0.2.2 → 0.3.0

package/dist/programmatic.d.ts

@@ -15,6 +15,9 @@
  * runtime state through the same RuntimeContext contract widgets get (HU5).
  */
 import { type CameraOptions } from "./runtime-core";
+import { type LightingIR, type LightingOptions } from "./scene-lighting";
+import type { TerrainIR } from "./terrain";
+import { type SnapshotOptions } from "./snapshot";
 import type { LayerIR } from "./ir";
 import { type RuntimeContext } from "./ctx";
 import type { Selection } from "./selection";
@@ -61,6 +64,8 @@ export interface LayerDescriptor {
     updateTriggers?: Record<string, unknown>;
     /** deck.gl props (camelCase), accessors as plain functions — passed through. */
     props?: Record<string, unknown>;
+    /** Per-layer terrain mode (spec: "Terrain") — the `terrain` attribute's twin; absent = the type default. */
+    terrain?: "drape" | "offset" | "off";
 }
 /** Camera state, both an input (options/setView) and an output (getViewState). */
 export interface CameraState {
@@ -88,6 +93,14 @@ export interface MapControllerOptions {
     };
     /** Runtime error boundary — deck.gl-level failures in the structured validation shape. */
     onRuntimeError?: (entry: ValidationEntry) => void;
+    /**
+     * Camera settled (trailing-debounced, the `om-view-changed` twin) — for
+     * camera persistence. Per-frame viewport churn goes to `watch(["viewport"])`;
+     * this fires once with the destination.
+     */
+    onViewChange?: (view: CameraState) => void;
+    /** Scene lighting (spec: "Scene Lighting") — the lighting* attributes' programmatic twin; omit for deck's default lights. */
+    lighting?: LightingOptions;
 }
 /** Descriptor → layer IR: the programmatic counterpart of one parse-manifest.ts loop iteration. */
 export declare function descriptorToIR(desc: LayerDescriptor, onDataLoaded: () => void): LayerIR | null;
@@ -118,6 +131,7 @@ export declare class MapController {
     private commitPending;
     private destroyed;
     private firstCommitDone;
+    private viewChangeTimer;
     private readyFired;
     private resolveReady;
     readonly ready: Promise<void>;
@@ -176,6 +190,25 @@ export declare class MapController {
      * (none ↔ maplibre) remount seeded with the current camera.
      */
     setBasemap(basemap: string | null): void;
+    /** Scene lighting (spec: "Scene Lighting") — swap the LightingEffect live; null restores deck's default lights. */
+    setLighting(options: LightingOptions | null): void;
+    /** Resolved scene-lighting IR (test inspection) — null = deck default lights. */
+    getLighting(): LightingIR | null;
+    /**
+     * Terrain (spec: "Terrain") — a resolved TerrainIR, or null to turn the
+     * surface off. Note: terrain suppresses an active basemap while on
+     * (restored on null) — the flat-canvas desync rule.
+     */
+    setTerrain(ir: TerrainIR | null): void;
+    /** Resolved terrain IR (test inspection) — null = no surface. */
+    getTerrain(): TerrainIR | null;
+    /**
+     * Canvas-only scene snapshot (spec: "Snapshot API") — basemap + deck
+     * composited at device pixels; framework-rendered widgets/overlays are
+     * NOT captured (render provider credits yourself on exports). Await
+     * `ready` first; headless controllers reject.
+     */
+    snapshot(opts?: SnapshotOptions): Promise<string | Blob>;
     flyTo(center: [number, number], zoom?: number, opts?: CameraOptions): void;
     flyToBounds(bounds: [[number, number], [number, number]], padding?: number, opts?: CameraOptions): void;
     setView(partial: Partial<CameraState>, opts?: CameraOptions): void;
@@ -183,4 +216,6 @@ export declare class MapController {
     /** Projects a lng/lat through the current viewport — undefined before the viewport resolves. */
     project(lngLat: [number, number]): [number, number] | undefined;
     destroy(): void;
+    /** Trailing-debounced onViewChange — see MapControllerOptions.onViewChange. */
+    private scheduleViewChange;
 }

package/dist/react/om-layer.d.ts

@@ -26,6 +26,8 @@ export interface OmLayerProps {
     flush?: string;
     /** Polling interval for REST snapshot URLs, e.g. "5s". */
     refresh?: string;
+    /** Behavior under active map terrain; absent uses the layer type's default. */
+    terrain?: "drape" | "offset" | "off";
     /** deck.gl updateTriggers — supply a changing value when an accessor's OUTPUT changes (deck ignores function identity). */
     updateTriggers?: Record<string, unknown>;
     /** Click pick on this layer (object flattened/materialized, same as ctx.selection). */

package/dist/react.js

@@ -1,7 +1,7 @@
 var J = Object.defineProperty;
 var Q = (e, t, n) => t in e ? J(e, t, { enumerable: !0, configurable: !0, writable: !0, value: n }) : e[t] = n;
 var A = (e, t, n) => Q(e, typeof t != "symbol" ? t + "" : t, n);
-import { jsxs as U, jsx as x } from "react/jsx-runtime";
+import { jsxs as U, jsx as C } from "react/jsx-runtime";
 import { createContext as X, useContext as Y, forwardRef as Z, useRef as f, useState as k, useCallback as ee, useMemo as I, useLayoutEffect as te, useEffect as g, useImperativeHandle as re } from "react";
 import { MapController as ne } from "@nika-js/onlymap";
 import { createPortal as B } from "react-dom";
@@ -53,7 +53,7 @@ function ie(e, t) {
   return Object.entries(t).some(([n, r]) => r !== void 0 && e[n] !== r);
 }
 const he = Z(function(t, n) {
-  const { center: r, zoom: l, pitch: a, bearing: u, basemap: i, basemapKey: c, attribution: y, headless: m, className: O, style: z, children: R } = t, d = f(null), [o, T] = k(null), [C, M] = k(null), [j, L] = k({
+  const { center: r, zoom: l, pitch: a, bearing: u, basemap: i, basemapKey: c, attribution: y, headless: m, className: O, style: z, children: R } = t, d = f(null), [o, T] = k(null), [p, M] = k(null), [j, L] = k({
     "top-left": null,
     "top-right": null,
     "bottom-left": null,
@@ -65,7 +65,7 @@ const he = Z(function(t, n) {
       q.map((s) => [
         s,
         (h) => {
-          L((p) => p[s] === h ? p : { ...p, [s]: h });
+          L((x) => x[s] === h ? x : { ...x, [s]: h });
         }
       ])
     ),
@@ -100,12 +100,12 @@ const he = Z(function(t, n) {
       }
     });
     T(h);
-    let p = !0;
+    let x = !0;
     return h.ready.then(() => {
       var F;
-      p && ((F = b.current) == null || F.call(b));
+      x && ((F = b.current) == null || F.call(b));
     }), () => {
-      p = !1, T(null), h.destroy();
+      x = !1, T(null), h.destroy();
     };
   }, [G]), g(() => {
     !o || V.current === i || (V.current = i, o.setBasemap(i ?? null));
@@ -121,19 +121,19 @@ const he = Z(function(t, n) {
       });
   }, [o]);
   const W = I(() => o ? new se(o) : null, [o]), _ = I(
-    () => o && W && C ? { controller: o, layers: W, overlayPane: C, corners: j } : null,
-    [o, W, C, j]
+    () => o && W && p ? { controller: o, layers: W, overlayPane: p, corners: j } : null,
+    [o, W, p, j]
   );
   return /* @__PURE__ */ U("div", { className: O, style: { position: "relative", overflow: "hidden", ...z }, children: [
-    /* @__PURE__ */ x("div", { ref: d, style: { position: "absolute", inset: 0 } }),
-    /* @__PURE__ */ x(
+    /* @__PURE__ */ C("div", { ref: d, style: { position: "absolute", inset: 0 } }),
+    /* @__PURE__ */ C(
       "div",
       {
         ref: v,
         style: { position: "absolute", top: 0, left: 0, zIndex: 10, pointerEvents: "none" }
       }
     ),
-    q.map((s) => /* @__PURE__ */ x(
+    q.map((s) => /* @__PURE__ */ C(
       "div",
       {
         "data-om-widget-corner": s,
@@ -142,7 +142,7 @@ const he = Z(function(t, n) {
       },
       s
     )),
-    _ && /* @__PURE__ */ x(H.Provider, { value: _, children: R })
+    _ && /* @__PURE__ */ C(H.Provider, { value: _, children: R })
   ] });
 }), ae = /* @__PURE__ */ new Set([
   "id",
@@ -159,6 +159,7 @@ const he = Z(function(t, n) {
   "streamKey",
   "flush",
   "refresh",
+  "terrain",
   "updateTriggers",
   "onClick",
   "onHover"
@@ -182,6 +183,7 @@ function ge(e) {
     key: e.streamKey,
     flush: e.flush,
     refresh: e.refresh,
+    terrain: e.terrain,
     updateTriggers: e.updateTriggers,
     props: l
   };
@@ -206,7 +208,7 @@ function ge(e) {
 function ve({ position: e = "top-left", className: t, style: n, children: r }) {
   const { corners: l } = K("OmWidget"), a = l[e];
   return a ? B(
-    /* @__PURE__ */ x("div", { className: t, style: { pointerEvents: "auto", ...n }, children: r }),
+    /* @__PURE__ */ C("div", { className: t, style: { pointerEvents: "auto", ...n }, children: r }),
     a
   ) : null;
 }
@@ -227,9 +229,9 @@ function be(e) {
     () => t.registerOverlay((R, d) => {
       const o = r.current;
       if (!o) return;
-      const { anchor: T, anchorFrom: C, layer: M, visible: j = !0, anchorOffset: L } = i.current;
+      const { anchor: T, anchorFrom: p, layer: M, visible: j = !0, anchorOffset: L } = i.current;
       let v;
-      if (C === "selection" ? ((!M || (d == null ? void 0 : d.layerId) === M) && (l.current = (d == null ? void 0 : d.coordinate) ?? void 0, u(d)), v = l.current) : v = T, !j || !v || !R) {
+      if (p === "selection" ? ((!M || (d == null ? void 0 : d.layerId) === M) && (l.current = (d == null ? void 0 : d.coordinate) ?? void 0, u(d)), v = l.current) : v = T, !j || !v || !R) {
         o.style.visibility = "hidden";
         return;
       }
@@ -246,7 +248,7 @@ function be(e) {
   });
   const { children: c, className: y, style: m, interactive: O = !0 } = e, z = typeof c == "function" ? c(a) : c;
   return B(
-    /* @__PURE__ */ x(
+    /* @__PURE__ */ C(
       "div",
       {
         ref: r,

package/dist/runtime-core.d.ts

@@ -1,8 +1,10 @@
+import { type LightingIR } from "./scene-lighting";
+import { type TerrainIR } from "./terrain";
 import type { LayerIR } from "./ir";
 import { type Selection } from "./selection";
 import type { ValidationEntry } from "./validation";
 import type { MapViewport } from "./basemap";
-/** `basemap="mapbox-*"` isn't implemented — kept maplibre-free so validation/runtime can check without loading the chunk. */
+/** Mapbox presets/protocol URLs aren't implemented — kept maplibre-free so validation/runtime can check without loading the chunk. */
 export declare function isMapboxBasemap(raw: string): boolean;
 export interface InitialView {
     longitude: number;
@@ -90,6 +92,48 @@ export declare class RuntimeCore {
     private basemapOptions?;
     /** Bumped on every renderer (re)init — a superseded lazy chunk load must not install its adapter over a newer renderer. */
     private rendererGeneration;
+    /** Pre-gate descriptors — what a license settle re-reconciles from (lastIRs holds the GATED set the renderer sees). */
+    private pregateIRs;
+    /**
+     * Scene lighting (spec: "Scene Lighting") — the retained IR, rebuilt into
+     * a LightingEffect on apply. Survives renderer remounts (initRenderer
+     * reads it, the lastIRs contract) and the lazy basemap-chunk window (the
+     * adapter constructor reads it on arrival). null = deck default lights.
+     */
+    private lighting;
+    /**
+     * Terrain (spec: "Terrain") — the retained surface IR. Non-null appends
+     * the internal terrain layer and patches drape/offset layers in
+     * buildLayers. `terrainGeneration` bumps on every terrain state change:
+     * extension sets must be BIRTH-stable, so patched layers get
+     * `#t<generation>`-based deck ids (fresh instances per flip — see
+     * applyTerrain); an explicit renderer-id map restores authored pick ids.
+     */
+    private terrain;
+    private terrainGeneration;
+    /** Rendered deck layer id → authored manifest/controller id (terrain uses fresh renderer ids). */
+    private renderedLayerIds;
+    /**
+     * The basemap attribute suppressed while terrain is active — a flat
+     * MapLibre canvas at sea level visibly desyncs from a raised surface
+     * (true coexistence is the interleaved-compositing TODO), so terrain
+     * forces standalone rendering and restores the basemap when it turns off.
+     */
+    private suppressedBasemapAttr?;
+    /**
+     * Snapshot capture queue (spec: "Snapshot API") — the WebGL context has
+     * no preserveDrawingBuffer, so pixels are only readable synchronously
+     * inside a post-render callback. snapshot() enqueues a capture and forces
+     * a redraw; the permanent onAfterRender (standalone Deck constructor)
+     * drains the queue while the drawing buffer is valid. `cancel` settles the
+     * promise when the renderer goes away before that frame renders (teardown/
+     * destroy) — a queued capture must never leave its caller hanging.
+     */
+    private snapshotCaptures;
+    /** (layer, reason) pairs already reported — gate errors fire once per violation, not per reconcile. */
+    private readonly gateWarned;
+    private badge?;
+    private unsubscribeLicense?;
     constructor(parent: HTMLElement, initialView: InitialView, callbacks?: RuntimeCoreCallbacks, basemapAttr?: string, headless?: HeadlessOptions, basemapOptions?: BasemapRuntimeOptions);
     /** `basemap` attribute → concrete style, logging resolution problems (unknown preset / missing key) — the demo-style fallback still renders. */
     private resolveBasemap;
@@ -99,6 +143,40 @@ export declare class RuntimeCore {
      * (none ↔ maplibre). Reads/seeds the camera from `this.viewState`.
      */
     private initRenderer;
+    /** The current lighting as a deck `effects` array — [] restores deck's default lights. */
+    private buildEffects;
+    /**
+     * Scene lighting (spec: "Scene Lighting") — swap the LightingEffect on
+     * the live renderer. null restores deck's default lights. Headless stores
+     * the IR (inspectable via the map's internal getter) with no renderer to
+     * drive; a change during the lazy basemap-chunk window is picked up by
+     * the adapter constructor (which reads `this.lighting` on arrival). A
+     * sunDate-driven sun resolves az/el HERE, against the current map center
+     * — deterministic per apply, not tracked per frame.
+     */
+    setLighting(ir: LightingIR | null): void;
+    getLightingInternal(): LightingIR | null;
+    /**
+     * Terrain on/off/source change (spec: "Terrain"). Bumps the generation
+     * (fresh deck ids for extension-carrying layers — birth-stable extension
+     * sets), swaps the renderer mode when needed (terrain suppresses an
+     * active basemap; turning it off restores the suppressed one), and
+     * re-applies layers. Headless stores the IR for inspection.
+     */
+    setTerrain(ir: TerrainIR | null): void;
+    getTerrainInternal(): TerrainIR | null;
+    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;
+    /**
+     * Canvas-only scene snapshot (spec: "Snapshot API") — the composite of
+     * basemap + deck canvases at device pixels, captured right after a forced
+     * repaint (no preserveDrawingBuffer in either context). DOM widgets,
+     * overlays, the badge, and the attribution control are NOT captured —
+     * consumers rendering exports must add provider credits themselves.
+     * Headless rejects (no renderer); pre-ready rejects (await map.ready).
+     */
+    snapshot(): Promise<HTMLCanvasElement>;
     /**
      * Live basemap change (spec: "Basemap presets & switching"), both paths:
      * - maplibre → maplibre: `map.setStyle()` — deck layers survive (the

package/dist/scene-lighting.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Scene lighting (spec: "Scene Lighting") — the manifest surface over
+ * deck.gl's LightingEffect, resolving the backlog TODO ("Lighting/effects
+ * manifest surface"). Attributes on <om-map>, the basemap= precedent:
+ * singleton scene state as attributes gets undo/redo for free (attribute
+ * history) and live switching through the same MutationObserver path.
+ *
+ *   <om-map lighting="daylight">
+ *   <om-map lighting="custom" lighting-ambient="0.6" lighting-sun="1.5"
+ *           lighting-sun-azimuth="135" lighting-sun-elevation="45">
+ *   <om-map lighting="daylight" lighting-sun-date="2026-07-15T14:00:00Z">
+ *
+ * The sun is ALWAYS a DirectionalLight driven by azimuth/elevation;
+ * `lighting-sun-date` is sugar that computes az/el from solar position at
+ * the map center when lighting is applied (deliberately NOT deck's
+ * experimental `_SunLight`, which recomputes per frame from the viewport —
+ * an attribute-declared scene should be deterministic, and the underscore
+ * API is upgrade churn). Absent `lighting` = deck's default lights —
+ * today's behavior, so the whole surface is additive.
+ */
+import { AmbientLight, _CameraLight as CameraLight, DirectionalLight, LightingEffect } from "@deck.gl/core";
+export interface LightingIR {
+    /** Preset the values were seeded from (validation/UI echo; "custom" for a fully hand-tuned scene). */
+    preset: LightingPresetName;
+    /** Ambient intensity — always-on fill. */
+    ambient: number;
+    /** Sun (directional) intensity; 0 omits the sun light entirely. */
+    sun: number;
+    /** Sun compass bearing, ° clockwise from north. */
+    sunAzimuth: number;
+    /** Sun height above the horizon, ° (0 = horizon, 90 = zenith). */
+    sunElevation: number;
+    /** Camera-following fill intensity (model inspection); 0 omits it. */
+    camera: number;
+    /** Epoch ms — when set, az/el are recomputed from solar position at apply time. */
+    sunDate?: number;
+}
+export type LightingPresetName = "daylight" | "studio" | "flat" | "custom";
+export declare const LIGHTING_PRESET_NAMES: readonly ["daylight", "studio", "flat", "custom"];
+export declare function isLightingPreset(name: string): name is LightingPresetName;
+/** Programmatic twin of the lighting-* attributes (MapControllerOptions.lighting / setLighting). */
+export interface LightingOptions {
+    preset?: LightingPresetName;
+    ambient?: number;
+    sun?: number;
+    sunAzimuth?: number;
+    sunElevation?: number;
+    camera?: number;
+    /** Epoch ms or ISO 8601 — the lighting-sun-date twin. */
+    sunDate?: number | string;
+}
+/** Preset seeds values; explicit fields override individual seeds; sunDate (resolved at apply time) wins over az/el. */
+export declare function resolveLighting(options: LightingOptions): LightingIR;
+/**
+ * `lighting*` attributes → IR. Returns null when `lighting` itself is
+ * absent (deck default lights; stray lighting-* overrides without it are
+ * inert — validation warns). Malformed numbers fall back to the preset seed
+ * (validation flags them; the live path must still render something).
+ */
+export declare function parseLightingAttrs(getAttr: (name: string) => string | null): LightingIR | null;
+/**
+ * Solar azimuth/elevation at a timestamp + location, in the manual-sun
+ * convention (azimuth ° CW from north, elevation ° above horizon). The
+ * standard suncalc derivation (the same math deck's `_SunLight` uses via
+ * @math.gl/sun): solar azimuth measured south→west, so matching the
+ * DirectionalLight convention is `azimuth = solar + 180°`. Below-horizon
+ * sun clamps to the horizon — a flat scene can't render a sun beneath it.
+ */
+export declare function solarAzElDegrees(timestamp: number, latitude: number, longitude: number): {
+    azimuth: number;
+    elevation: number;
+};
+/**
+ * IR → the named lights map a LightingEffect is constructed from —
+ * separated so tests can assert composition without reaching into
+ * LightingEffect's private fields. The ambient light is always present;
+ * sun and camera lights only at intensity > 0 (deck renders a 0-intensity
+ * light as subtle noise, not nothing). `center` (current map center) feeds
+ * the sunDate → az/el resolution.
+ */
+export declare function buildLights(ir: LightingIR, center?: [longitude: number, latitude: number]): Record<string, AmbientLight | DirectionalLight | CameraLight>;
+/** IR → deck.gl LightingEffect (see buildLights for the composition rules). */
+export declare function buildLightingEffect(ir: LightingIR, center?: [longitude: number, latitude: number]): LightingEffect;

package/dist/selection.d.ts

@@ -27,5 +27,5 @@ interface PickingInfoLike {
     x: number;
     y: number;
 }
-export declare function toSelection(info: PickingInfoLike, type: "hover" | "click"): Selection | null;
+export declare function toSelection(info: PickingInfoLike, type: "hover" | "click", resolveLayerId?: (renderedId: string) => string): Selection | null;
 export {};

package/dist/snapshot.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Snapshot serialization (spec: "Snapshot API") — shared by OmMapElement
+ * and MapController: the composite canvas RuntimeCore.snapshot() produces,
+ * serialized to the consumer's preferred shape.
+ */
+export interface SnapshotOptions {
+    /** Image MIME type — default "image/png". */
+    type?: "image/png" | "image/jpeg" | "image/webp";
+    /** Lossy-format quality 0–1 (jpeg/webp). */
+    quality?: number;
+    /** Output shape — default "dataURL" (what print/export pipelines embed directly); "blob" for uploads/files. */
+    as?: "dataURL" | "blob";
+}
+export declare function serializeSnapshot(canvas: HTMLCanvasElement, opts: SnapshotOptions): Promise<string | Blob>;

package/dist/telemetry-schema.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The telemetry WIRE SCHEMA (spec: "Monetization Gates / Usage telemetry";
+ * public doc: docs/telemetry.md — keep all three in sync). Deliberately a
+ * types-only module with zero DOM/browser references: the ingestion Worker
+ * (cloud/workers/telemetry, WebWorker lib) type-imports this same file, so
+ * client and server can never drift apart silently — a schema change breaks
+ * the other side's typecheck in the same commit.
+ */
+export interface TelemetryLayerSnapshot {
+    type: string;
+    rows: number;
+    streaming: boolean;
+    refresh: boolean;
+}
+/** Library-caused error report (spec: "Monetization Gates / Usage telemetry" — library-error reporting). Scrubbed: no manifest content, no layer data, no page paths. */
+export interface TelemetryErrorReport {
+    event: "library_error";
+    pageLoadId: string;
+    version: string;
+    /** Hostname only — never the path. */
+    origin: string;
+    dev: boolean;
+    /** Hash of message + top own-code frame — the dedup/grouping key. */
+    signature: string;
+    message: string;
+    /** Top stack lines from the library's own code, query strings stripped. */
+    frames: string[];
+    ua: string;
+}
+export interface TelemetrySnapshot {
+    event: "map_ready";
+    /** Random per page load — dedups beacon retries & multi-map pages. NOT persistent, NOT a visitor id. */
+    pageLoadId: string;
+    /** The authored `map-id` attribute — identifies the map artifact, not the visitor. */
+    mapId: string | null;
+    version: string;
+    /** "free" until the license module (monetization M1) exists. */
+    plan: string;
+    keyId: string | null;
+    /** Hostname only — never the path. */
+    origin: string;
+    frontend: "html" | "react" | "programmatic";
+    renderer: "maplibre" | "standalone";
+    /** Dev context (localhost et al.) — the only beacons the server may GeoIP (country code, IP discarded). */
+    dev: boolean;
+    layers: TelemetryLayerSnapshot[];
+    story: {
+        steps: number;
+    } | null;
+    widgets: string[];
+    draw: boolean;
+    undoRedo: boolean;
+}

package/dist/telemetry.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Usage telemetry — client side (spec: "Monetization Gates / Usage
+ * telemetry", phase M3 client half). One snapshot per <om-map> instance per
+ * page load, built when that map reaches `ready` (manifest fully parsed —
+ * late mutations go uncounted, by design). Deployment-scoped, never
+ * visitor-scoped: the payload describes the page's use of the library.
+ *
+ * LIVE by default since the ingestion Worker deployment (2026-07-14): the
+ * default endpoint is the first-party Worker at om-api.nika.eco (spec's
+ * "beacon must not ship before something is listening" — it is listening).
+ * Disable with `configureTelemetry({ disabled: true })`, per map with
+ * `telemetry="off"`, or clear the endpoint (`{ endpoint: undefined }`).
+ * Disclosure: LICENSE.md §11; public schema: docs/telemetry.md.
+ *
+ * Non-negotiables (spec, binding):
+ *  - telemetry never affects function: everything is wrapped, fire-and-
+ *    forget, no retry, silent on failure; nothing awaits it;
+ *  - no PII, no page URLs (hostname only), no visitor identifiers —
+ *    `pageLoadId` dies with the page; `map-id` identifies the map ARTIFACT;
+ *  - opt-out: `OmMap.configureTelemetry({ disabled: true })` or
+ *    `telemetry="off"` on the map element;
+ *  - headless maps (consumer test suites) never report.
+ */
+import type { LayerIR } from "./ir";
+import type { TelemetrySnapshot, TelemetryErrorReport } from "./telemetry-schema";
+export type { TelemetrySnapshot, TelemetryLayerSnapshot } from "./telemetry-schema";
+export interface TelemetryConfig {
+    /** Kill switch — disables the map-ready beacon and library-error reports globally. */
+    disabled?: boolean;
+    /** Ingestion endpoint — the first-party Worker by default; explicitly set `undefined` to silence all sends. */
+    endpoint?: string;
+}
+/** The first-party ingestion Worker (cloud/workers/telemetry) — a domain we control, never a vendor's. */
+export declare const DEFAULT_TELEMETRY_ENDPOINT = "https://om-api.nika.eco/v1/t";
+/** Merge-assign: only keys present in `partial` change (so `{ endpoint: undefined }` explicitly clears). */
+export declare function configureTelemetry(partial: TelemetryConfig): void;
+/** Read-only view for the error-reporting module (same gates, same switch). */
+export declare function getTelemetryConfig(): Readonly<TelemetryConfig>;
+/** One id per page load, shared by every map on the page. */
+export declare const pageLoadId: string;
+/** Hostname-only origin + dev flag — shared with error reporting. */
+export declare function hostContext(): {
+    origin: string;
+    dev: boolean;
+};
+export declare function buildMapSnapshot(mapEl: Element, layerIRs: ReadonlyMap<string, LayerIR>, frontend?: TelemetrySnapshot["frontend"]): TelemetrySnapshot;
+/**
+ * Fire-and-forget POST. `text/plain` is deliberate: it keeps the request
+ * CORS-simple (no preflight from every customer origin) — the Worker parses
+ * the body as JSON regardless of the content type. sendBeacon survives page
+ * unload; `fetch keepalive` is the fallback where sendBeacon is missing.
+ * Never throws, never retries, nothing observes the result.
+ */
+export declare function postPayload(payload: TelemetrySnapshot | TelemetryErrorReport): void;
+/**
+ * The om-map `ready` hook — one call per map instance per page load
+ * (guarded by the caller's readyFired latch). All gates checked here so the
+ * call site stays a single unconditional line.
+ */
+export declare function reportMapReady(mapEl: Element, layerIRs: ReadonlyMap<string, LayerIR>): void;

package/dist/terrain.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Terrain (spec: "Terrain") — 3D elevation surface + per-layer draping,
+ * declared as `terrain*` attributes on <om-map> (the basemap=/lighting=
+ * scene-attribute precedent: free undo/redo, live MutationObserver
+ * switching).
+ *
+ *   <om-map terrain="terrarium" terrain-exaggeration="1.5" pitch="55">
+ *   <om-map terrain="https://tiles.example.com/dem/{z}/{x}/{y}.png"
+ *           terrain-decoder="terrarium" terrain-max-zoom="14"
+ *           terrain-texture="https://…/satellite/{z}/{x}/{y}.jpg">
+ *
+ * The seventh plugin registry (`OmMap.registerTerrain`) resolves preset
+ * names; a `{z}/{x}/{y}` URL is bring-your-own DEM (requires
+ * terrain-decoder). Geographic layers DRAPE onto the surface by default;
+ * a per-layer `terrain="drape|offset|off"` attribute overrides (3D-model
+ * layers default to `offset` — models sit ON terrain, not painted onto
+ * it).
+ *
+ * Terrain REPLACES an active basemap: a flat MapLibre canvas sits at sea
+ * level and visibly desyncs from a raised surface (true coexistence is
+ * the interleaved-compositing TODO). RuntimeCore suppresses the basemap
+ * while terrain is active and restores it when terrain turns off.
+ *
+ * `applyTerrain` is PURE (unit-testable without a GPU — headless never
+ * reaches the deck handoff): it computes each layer's terrain patches and
+ * the terrain-surface layer props; RuntimeCore feeds them to buildLayers.
+ */
+import type { Layer } from "@deck.gl/core";
+import type { LayerIR } from "./ir";
+/** RGB DEM decoder: height = offset + R·rScaler + G·gScaler + B·bScaler. */
+export interface ElevationDecoder {
+    rScaler: number;
+    gScaler: number;
+    bScaler: number;
+    offset: number;
+}
+export declare const DECODERS: Readonly<Record<string, ElevationDecoder>>;
+export interface TerrainPreset {
+    /** `{z}/{x}/{y}` DEM tile URL template (may carry a `{key}` placeholder for keyed providers). */
+    elevationData: string;
+    /** Decoder name ("terrarium" / "mapbox-rgb") or explicit scalers. */
+    decoder: keyof typeof DECODERS | ElevationDecoder;
+    /**
+     * The provider's REAL tileset cap — deck over-samples past it for closer
+     * cameras; a too-high cap requests tiles that 404 and blanks the terrain.
+     */
+    maxZoom: number;
+    /** Optional draped imagery `{z}/{x}/{y}` URL template. */
+    texture?: string;
+    /** Display name (switcher UIs). */
+    label?: string;
+    /** Which key `{key}` substitutes — the basemap-registry convention. */
+    requiresKey?: "maptiler";
+}
+export declare function registerTerrain(name: string, preset: TerrainPreset): void;
+export declare function getTerrain(name: string): TerrainPreset | undefined;
+export declare function getAllTerrains(): ReadonlyMap<string, TerrainPreset>;
+export interface TerrainIR {
+    elevationData: string;
+    elevationDecoder: ElevationDecoder;
+    maxZoom: number;
+    /** Multiplies decoded DEM heights (1 = true relief). */
+    exaggeration: number;
+    texture?: string;
+}
+export interface ResolvedTerrain {
+    ir: TerrainIR | null;
+    /** Resolution problem (unknown preset / missing key / missing decoder) — the caller decides how loudly to fail; `ir` is null when unresolvable. */
+    error?: string;
+}
+/** Is this `terrain` value a bring-your-own DEM URL rather than a preset name? (The basemap isStyleUrl convention.) */
+export declare function isDemUrl(raw: string): boolean;
+/**
+ * `terrain*` attributes → TerrainIR. Returns `{ir: null}` when `terrain`
+ * is absent/"off"; `{ir: null, error}` when set but unresolvable (unknown
+ * preset, keyless keyed preset, raw URL without a decoder) — terrain
+ * renders NOTHING in that case rather than a wrong surface, and validation
+ * carries the loud version of the same message.
+ */
+export declare function parseTerrainAttrs(getAttr: (name: string) => string | null, maptilerKey?: string): ResolvedTerrain;
+export declare const TERRAIN_LAYER_ID = "__onlymapjs-terrain";
+export type LayerTerrainMode = "drape" | "offset" | "off";
+export declare const LAYER_TERRAIN_MODES: readonly ["drape", "offset", "off"];
+export declare function defaultTerrainMode(type: string): LayerTerrainMode;
+export interface TerrainLayerPatch {
+    /**
+     * The deck-layer id to construct with. Suffixed `#t<generation>` while
+     * terrain is active: adding/removing an extension on a LIVE layer
+     * recompiles shaders and corrupts attribute state (the DataFilterExtension
+     * birth-mount rule), and a stale TerrainExtension vertical offset survives
+     * a terrain toggle on a stable id — a fresh id forces clean teardown +
+     * rebuild. RuntimeCore maps these generated ids back to authored ids for
+     * picks without guessing from the string shape.
+     */
+    deckId: string;
+    /** Extra constructor props: extensions (APPENDED to existing — DataFilterExtension stays mounted) + terrainDrawMode. Empty for mode "off". */
+    extraProps: Record<string, unknown>;
+}
+/**
+ * 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.
+ */
+export declare function applyTerrain(irs: readonly LayerIR[], terrainActive: boolean, generation: number): Map<string, TerrainLayerPatch>;
+/**
+ * The terrain-surface layer itself. `operation: "terrain+draw"` makes it
+ * double as the elevation surface extension-carrying layers drape onto;
+ * `pickable: "3d"` runs the depth pick pass so click/hover coordinates
+ * unproject at the SURFACE's depth instead of z=0 sea level (without it,
+ * tilted-view picks/drawn vertices land behind the cursor). Exempt from
+ * license gates by the `__onlymapjs-` prefix.
+ */
+export declare function buildTerrainLayer(ir: TerrainIR): Layer;

package/dist/version.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The library version, as a compile-time constant (telemetry payloads,
+ * future diagnostics). Kept in sync with package.json by a drift test
+ * (telemetry.test.ts) rather than a JSON import — package.json sits outside
+ * the build rootDir, and a `define` would need repeating across vite/vitest/
+ * vite-node configs.
+ */
+export declare const LIBRARY_VERSION = "0.3.0";