@nika-js/onlymap 0.2.3 → 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;
@@ -92,6 +94,42 @@ export declare class RuntimeCore {
     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?;
@@ -105,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/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

@@ -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.2.3";
+export declare const LIBRARY_VERSION = "0.3.0";

package/docs/custom-layers.md

@@ -0,0 +1,99 @@
+# Registering an external layer class
+
+`OmMap.registerLayer` makes any deck.gl layer class a first-class manifest
+type: validation, IntelliSense generation, and attribute resolution all read
+the same schema the built-ins use. This page is the recipe for bringing a
+layer class the library doesn't bundle — a community layer, a company shim, a
+composite that wraps a whole data pipeline.
+
+## Rule 1: build on `@nika-js/onlymap/deck`, never on your own deck.gl
+
+OnlyMapJS bundles deck.gl (it has zero runtime dependencies). If your class
+extends a `@deck.gl/*` copy you installed yourself, it belongs to a
+**different class hierarchy** — two `Layer` base classes, two luma.gl
+runtimes — and fails inside the bundled renderer. The `deck` subpath
+re-exports the bundled classes, so your shim extends the exact objects the
+core renders with:
+
+```js
+import { CompositeLayer, TileLayer, BitmapLayer } from "@nika-js/onlymap/deck";
+```
+
+Available: `Layer`, `CompositeLayer`, `LayerExtension`, `WebMercatorViewport`,
+`COORDINATE_SYSTEM`, `GeoJsonLayer`, `ScatterplotLayer`, `IconLayer`,
+`BitmapLayer`, `TileLayer`, `Tile3DLayer`, `SimpleMeshLayer`,
+`ScenegraphLayer` — plus authoring types (`LayerProps`, `DefaultProps`,
+`UpdateParameters`, `PickingInfo`, `LayersList`; typechecking against them
+needs `@deck.gl/core` as a dev dependency).
+
+## Rule 2: functions ride `static defaultProps`, not attributes
+
+HTML attributes are strings — function-valued props (`renderSubLayers`,
+`getTileData`, load callbacks) are inexpressible by design. Put them on a
+thin subclass; deck.gl's own defaultProps merge delivers them to every
+instance:
+
+```js
+class CogLayer extends CompositeLayer {
+  static layerName = "CogLayer";
+  static defaultProps = {
+    renderTile: { type: "function", value: renderTile },
+    onRasterLoad: { type: "function", value: () => {} },
+  };
+  renderLayers() {
+    /* compose TileLayer/BitmapLayer from the subpath here */
+  }
+}
+```
+
+## Rule 3: the schema wires attributes to deck props
+
+```js
+import { OmMap } from "@nika-js/onlymap";
+
+OmMap.registerLayer({
+  type: "CogLayer",
+  deckClass: CogLayer,
+  props: [
+    // deck's URL prop is `data`, but OnlyMapJS reserves the `data` attribute
+    // for its own loader — alias it, and the layer class fetches for itself
+    // (the built-in Tile3DLayer `tileset` attribute uses the same trick).
+    { attr: "src", kind: "scalar", deckProp: "data", type: "string", required: true },
+    // JSON attributes and dot-path descriptors compose: the JSON sets the
+    // object, later dot-paths merge into it.
+    { attr: "load-options", kind: "scalar", deckProp: "loadOptions", type: "json" },
+    { attr: "max-error", kind: "scalar", deckProp: "loadOptions.cog.maxError", type: "number" },
+    { attr: "opacity", kind: "scalar", deckProp: "opacity", type: "number", default: 1 },
+    { attr: "visible", kind: "scalar", deckProp: "visible", type: "boolean", default: true },
+    // accessor-kind props get the full expression language:
+    // { attr: "get-color", kind: "accessor", deckProp: "getColor" },
+  ],
+});
+```
+
+Then the manifest just works:
+
+```html
+<om-layer id="rast" type="CogLayer" src="https://example.com/landcover.tif"
+          max-error="16" opacity="0.9"></om-layer>
+```
+
+## Rule 4: register before the manifest mounts
+
+Registration after mount does not retrigger reconciles — an unknown-type
+layer is warn-skipped until the next DOM mutation. Call `registerLayer` at
+module top level (the `registerSource`/`registerFormat` convention), before
+the `<om-map>` connects.
+
+## Verifying without a GPU
+
+`OmMap.snapshotIR(html)` resolves your registered type through the same
+pipeline the live reconciler runs — assert the aliased URL lands on
+`props.data`, dot-paths nest, functions appear as `[function]` — in plain
+jsdom/happy-dom, no WebGL.
+
+## The programmatic alternative
+
+On the `MapController` front-end (and the React adapter), `props` passes
+function values directly — no subclass needed. The subclass recipe exists so
+the **manifest** front-end can express what attributes can't.