@nika-js/onlymap 0.2.2 → 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.

package/docs/react.md

@@ -116,5 +116,6 @@ React ≥ 18 is an optional peer dependency — it's only loaded if you import `
 
 - **Stories** as React components (a `<Story>`/timeline hook is on the roadmap) — an HTML `<om-story>` needs the HTML front-end.
 - **The draw widget** — HTML front-end only for now.
+- **Undo/redo** — manifest history is a DOM-front-end feature; in React your state (and its undo) belongs to the app. `ctx.history` reads `{ canUndo: false, canRedo: false }` here.
 - Per-feature `trace` (it animates via runtime manifest elements) — whole-layer `trace` on a TripsLayer works.
 - A `scale()` helper mirroring the expression language — use `d3-scale` or plain functions.

package/docs/telemetry.md

@@ -0,0 +1,78 @@
+# Telemetry
+
+OnlyMapJS reports **one usage snapshot per map, per page load** — sent when a map reaches `ready` — and, separately, **errors caused by the library's own code**. This page documents exactly what is (and is not) collected, and how to turn it off.
+
+> **Status: active.** Reports go to the first-party endpoint `https://om-api.nika.eco/v1/t` (never to a third-party domain from your pages). Disclosure lives in the license (LICENSE.md §11). Both opt-outs below are always honored.
+
+## What a snapshot contains
+
+The payload is **deployment-scoped**: it describes the page's use of the library, never the visitor.
+
+```jsonc
+{
+  "event": "map_ready",
+  "pageLoadId": "…",            // random UUID per page load — dedups retries; dies with the page
+  "mapId": "…" | null,           // the authored map-id attribute (see below)
+  "version": "0.2.3",
+  "plan": "free", "keyId": null,
+  "origin": "dashboard.example.com",   // hostname ONLY — never the path or query
+  "frontend": "html",                  // html | react | programmatic
+  "renderer": "maplibre" | "standalone",
+  "dev": false,                        // true on localhost / *.local
+  "layers": [ { "type": "ScatterplotLayer", "rows": 1200, "streaming": false, "refresh": false } ],
+  "story": { "steps": 7 } | null,
+  "widgets": ["legend", "basemap-switcher"],  // widget types only
+  "draw": false, "undoRedo": false
+}
+```
+
+What is **never** collected: page paths or URLs, your data or its contents, coordinates, IP addresses in the payload, cookies, or any persistent visitor identifier. `pageLoadId` is regenerated on every page load and cannot link visits. Snapshots are also never sent from `headless` maps, so test suites stay silent.
+
+## Library-error reporting
+
+Unexpected exceptions **from the library's own code** — never your page scripts, never other libraries (the stack must point into OnlyMapJS's own bundle), and never manifest/validation mistakes (those are surfaced to you in the dev error panel instead) — are reported so bugs get fixed:
+
+```jsonc
+{
+  "event": "library_error",
+  "pageLoadId": "…", "version": "0.2.3",
+  "origin": "dashboard.example.com",       // hostname only
+  "dev": false,
+  "signature": "…",                         // hash of message + top frame — the grouping key
+  "message": "…",                           // truncated; query strings stripped
+  "frames": ["…"],                          // top library-code stack lines; query strings stripped
+  "ua": "…"                                 // browser user-agent string
+}
+```
+
+Stacks are scrubbed before sending: query strings are stripped from every URL (they can carry keys), and no manifest content, layer data, or accessor source is ever included. At most one report per distinct error per page load, capped at five per page. The same opt-outs below disable error reporting — one switch, no fine print.
+
+## `map-id` — identifying the map, not the visitor
+
+An optional authored attribute:
+
+```html
+<om-map map-id="0f2c6a1e-88f7-4c3e-9d41-7b1f3f9f2ab7" ...>
+```
+
+It identifies the **map artifact** — the same id on every visit by every visitor — so usage can distinguish "one popular dashboard" from "many different maps". It is the same category as an analytics measurement id in page source: author-controlled, nothing stored on the visitor's device. **Opt out by deleting or changing it**; it is never required, and validation never asks for it. The VS Code `!map` snippet generates one automatically.
+
+## Opting out
+
+```ts
+OmMap.configureTelemetry({ disabled: true });   // global — kills usage snapshots AND error reports
+```
+
+```html
+<om-map telemetry="off" ...>                    <!-- per map -->
+```
+
+Clearing the endpoint (`OmMap.configureTelemetry({ endpoint: undefined })`) is a third, equivalent switch: no endpoint, no network.
+
+## The binding rules
+
+These are design constraints, not promises of restraint:
+
+1. **Telemetry never affects function.** Nothing in the library waits on, retries, or reacts to a report; sends are fire-and-forget (`navigator.sendBeacon`) and silent on failure. Error reporting can never itself throw into your page.
+2. **No endpoint, no network.** The send layer is a no-op when the endpoint is cleared.
+3. **Dev-context geography only.** Only `dev: true` reports (a developer's own localhost) are GeoIP-resolved at the server — to a country code, with the IP discarded unwritten. Production reports are never GeoIP'd and visitor IPs are never stored.

package/docs/testing.md

@@ -122,8 +122,8 @@ h = await mountForTest(PAGE);                 // resolves after the mocked fetch
 
 A *failing* fetch also settles readiness (the layer is just empty) — `mountForTest` never hangs on a bad URL.
 
-**What's real at this tier:** validation, accessor execution, `ctx.stats`/`data`/`dataInViewport`, declarative + viewport filtering, behaviors → actions, overlay anchoring/culling/interpolation (real Mercator math), widget reactivity, XSS escaping, columnar row materialization.
-**What isn't:** pixels, GPU attribute recompute, basemap compositing, and CDN-loaded widgets (`vega-lite` is browser-only — assert its *data* here via `ctx.stats`, its rendering at tier 3 if at all).
+**What's real at this tier:** validation, accessor execution, `ctx.stats`/`data`/`dataInViewport`, declarative + viewport filtering, behaviors → actions, overlay anchoring/culling/interpolation (real Mercator math), widget reactivity, XSS escaping, columnar row materialization — **and the free-plan license gates** (5 layers / 25k rows per layer), which apply in headless tests exactly as in production so a passing suite can't hide a gated page. If your page legitimately exceeds the free limits, configure your license key in test setup — keys are publishable and verify **offline**, so CI needs no network or secrets vault: `OmMap.configureLicense("om_live_…")`. Gate violations surface as errors on the validation stream (`om-validation-error` / the `validate` attribute), naming the limit.
+**What isn't:** pixels, GPU attribute recompute, basemap compositing, and CDN-loaded widgets (`vega-lite` is browser-only — assert its *data* here via `ctx.stats`, its rendering at tier 3 if at all). Telemetry is also silent here — headless maps never report.
 
 ## Tier 3 — visual: Playwright
 

package/llms.txt

@@ -16,14 +16,15 @@ OnlyMapJS is NOT raw deck.gl and NOT generic HTML/JSX. The rules below are the d
 
 ## Element vocabulary
 
-- `<om-map center="[lng, lat]" zoom="11" pitch="55" bearing="20" basemap="positron">` — the root. `basemap` accepts a free preset (`liberty`, `bright`, `positron`, `dark-matter`, `voyager`, `osm` — no keys; or `maptiler-streets`/`maptiler-dataviz`/`maptiler-satellite` with `basemap-key="…"` or `OmMap.configureBasemap({ maptilerKey })`), `maplibre` (bare demo style), a style URL (e.g. a MapTiler-customized style), or `none` (standalone canvas). The attribute is LIVE — writing it switches the basemap in place (camera + layers survive); the `set-basemap {basemap}` action and `<om-widget type="basemap-switcher" options="positron dark-matter osm">` do the same. Register more via `OmMap.registerBasemap(name, { style })`. Required provider attribution renders automatically (`attribution="false"` opts out). `pitch`/`bearing` tilt the initial camera (use for 3D content). `validate` attribute enables live validation + on-page error panel.
-- `<om-layer id="..." type="ScatterplotLayer" data="./points.json">` — any deck.gl layer class by `type` (all 33 bundled), plus `PopupLayer` (WebGL badges/labels at scale: `layout="badge|pin-label|card"`, `min-zoom`/`max-zoom`). Data: `data` URL (JSON, GeoJSON, CSV/TSV `.csv` — parsed to typed columns — Shapefile `.shp` (+`.dbf` attributes) and KML `.kml` as GeoJSON features, or Arrow IPC `.arrow`/`.feather` — large point datasets stay columnar, GeoArrow line/polygon geometry becomes GeoJSON features, zstd-compressed IPC is handled; other formats plug in via `OmMap.registerFormat({match, parse})`), inline `<script type="application/json">` (row arrays or column-oriented `{"columns": {"lon": [...], "lat": [...]}}`), or `wss://` streaming (`key="mmsi"` upserts entities in place, `flush="250ms"` coalesces bursts, `source="name"` selects a `OmMap.registerSource` decoder plugin), or a polled REST snapshot (`refresh="5s"` re-fetches and replaces — for live endpoints that return the full current state). Authenticated endpoints: call `OmMap.configureData({ headers: {...} })` in a script — never put tokens in attributes. `$field` accessors work identically on all of them — never write column-index code yourself. One columnar restriction: the `js` full-JS opt-in is not allowed on Arrow/columnar layers (validation will tell you; use `$field` accessors instead). For 3D models use `type="ScenegraphLayer"` with `scenegraph="./model.glb"` (required) and `get-orientation="[0, $heading, 90]"` — the roll of 90 stands Y-up glTF models upright; see docs/3d-assets.md.
-- `<om-widget type="legend|layer-switcher|basemap-switcher|zoom-controls|scale-bar|attribution|filter|vega-lite" position="bottom-right">` — static UI panels. No `type` + HTML + `<script type="om/widget">` = custom widget with `ctx` (`ctx.layers`, `ctx.data(id)`, `ctx.dataInViewport(id)`, `ctx.stats(id, field)`, `ctx.viewport`, `ctx.selection`, `ctx.emit(action, payload)`), `this.watch = ['data:<layerId>', 'viewport', 'selection', 'layers']`, `this.$(sel)`, `vegaEmbed`/`d3` as globals.
+- `<om-map center="[lng, lat]" zoom="11" pitch="55" bearing="20" basemap="positron">` — the root. `basemap` accepts a free preset (`liberty`, `bright`, `positron`, `dark-matter`, `voyager`, `osm` — no keys; or `maptiler-streets`/`maptiler-dataviz`/`maptiler-satellite` with `basemap-key="…"` or `OmMap.configureBasemap({ maptilerKey })`), `maplibre` (bare demo style), a style URL (e.g. a MapTiler-customized style; any scheme fetch supports, including desktop asset protocols like Tauri's, query strings fine), or `none` (standalone canvas). The attribute is LIVE — writing it switches the basemap in place (camera + layers survive); the `set-basemap {basemap}` action and `<om-widget type="basemap-switcher" options="positron dark-matter osm">` do the same. Register more via `OmMap.registerBasemap(name, { style })`. Required provider attribution renders automatically (`attribution="false"` opts out). `pitch`/`bearing` tilt the initial camera (use for 3D content). Terrain: `terrain="terrarium"` (keyless AWS DEM; also `maptiler-terrain` with a key, a raw `{z}/{x}/{y}` DEM URL + `terrain-decoder="terrarium|mapbox-rgb|<JSON>"`, or `off`) raises a 3D surface — geographic layers DRAPE onto it automatically (per-layer `terrain="drape|offset|off"` overrides; 3D-model layers sit ON it), `terrain-exaggeration` scales relief, `terrain-texture` drapes imagery; terrain REPLACES an active basemap while on (restored when off); `set-terrain` action, `terrain` watch token, `OmMap.registerTerrain(name, {...})` for more sources. Scene lighting for 3D content: `lighting="daylight|studio|flat|custom"` (absent = deck defaults) with `lighting-ambient`/`lighting-sun`/`lighting-sun-azimuth`/`lighting-sun-elevation`/`lighting-camera` overrides and `lighting-sun-date` (ISO/epoch — solar-position sun computed at the map center, wins over azimuth/elevation); attribute-backed (undoable, live-editable), story-steppable via the `set-lighting {lighting, sunAzimuth, ...}` action (`lighting="default"` removes the attribute set; a bare preset is a clean reset — stale overrides clear), native UI via `<om-widget type="lighting">` (preset radios + tuning sliders), widget watch token `lighting`. GeoJsonLayer extrudes polygons declaratively: `extruded get-elevation="$height"` (+ `wireframe`). `validate` attribute enables live validation + on-page error panel. Include a `map-id="<random UUID>"` on complete pages (identifies the map artifact for usage telemetry — not a visitor id; the page author deletes it to opt out); `telemetry="off"` disables usage telemetry + library-error reporting for the map (global: `OmMap.configureTelemetry({ disabled: true })`; schema: docs/telemetry.md). Free plan limits: 5 layers, 25k rows per layer — layers past a limit don't render and validation says why; a `license-key="om_live_…"` attribute (publishable, origin-restricted) or `OmMap.configureLicense(key)` lifts limits and removes the corner badge. When a user's map exceeds free limits, say so and point at the validation message rather than silently restructuring their data. Events on the element: `om-map-ready` (boot complete; `await mapEl.ready` is the promise twin), `om-validation-error`, `om-view-changed` (camera settled after a move, debounced; `detail = {longitude, latitude, zoom, pitch, bearing}` — the camera-persistence hook). `await mapEl.snapshot()` returns a canvas-only PNG dataURL of the scene (basemap + layers at device pixels; `{as:"blob"}` for files) — DOM widgets/overlays/attribution are NOT captured, so exports must render provider credits themselves.
+- `<om-layer id="..." type="ScatterplotLayer" data="./points.json">` — any deck.gl layer class by `type` (all 33 bundled), plus `PopupLayer` (WebGL badges/labels at scale: `layout="badge|pin-label|card"`, `min-zoom`/`max-zoom`). External layer classes register via `OmMap.registerLayer({type, deckClass, props})` — build them on `@nika-js/onlymap/deck` (the bundled `CompositeLayer`/`TileLayer`/… re-exports), never a separately-installed deck.gl (different class hierarchy, breaks in the renderer); function-valued props ride the subclass's `static defaultProps`; register at module top level BEFORE the manifest mounts (see docs/custom-layers.md). Data: `data` URL (JSON, GeoJSON, CSV/TSV `.csv` — parsed to typed columns — Shapefile `.shp` (+`.dbf` attributes) and KML `.kml` as GeoJSON features, or Arrow IPC `.arrow`/`.feather` — large point datasets stay columnar, GeoArrow line/polygon geometry becomes GeoJSON features, zstd-compressed IPC is handled; other formats plug in via `OmMap.registerFormat({match, parse})`; data URLs accept any scheme the runtime's fetch supports — desktop webviews (Tauri, Electron) pass asset-protocol URLs straight in), inline `<script type="application/json">` (row arrays or column-oriented `{"columns": {"lon": [...], "lat": [...]}}`), or `wss://` streaming (`key="mmsi"` upserts entities in place, `flush="250ms"` coalesces bursts, `source="name"` selects a `OmMap.registerSource` decoder plugin), or a polled REST snapshot (`refresh="5s"` re-fetches and replaces — for live endpoints that return the full current state). Authenticated endpoints: call `OmMap.configureData({ headers: {...} })` in a script — never put tokens in attributes. `$field` accessors work identically on all of them — never write column-index code yourself. One columnar restriction: the `js` full-JS opt-in is not allowed on Arrow/columnar layers (validation will tell you; use `$field` accessors instead). For 3D models use `type="ScenegraphLayer"` with `scenegraph="./model.glb"` (required) and `get-orientation="[0, $heading, 90]"` — the roll of 90 stands Y-up glTF models upright; see docs/3d-assets.md.
+- `<om-widget type="legend|layer-switcher|basemap-switcher|lighting|zoom-controls|undo-redo|scale-bar|attribution|filter|vega-lite" position="bottom-right">` — static UI panels. No `type` + HTML + `<script type="om/widget">` = custom widget with `ctx` (`ctx.layers`, `ctx.data(id)`, `ctx.dataInViewport(id)`, `ctx.stats(id, field)`, `ctx.viewport`, `ctx.selection`, `ctx.emit(action, payload)`), `this.watch = ['data:<layerId>', 'viewport', 'selection', 'layers', 'history', 'basemap']` (`layers` also fires on visibility/filter changes; `basemap` on basemap switches; `history` on undo/redo availability), `this.$(sel)`, `vegaEmbed`/`d3` as globals.
 - `<om-overlay id="..." anchor-from="selection">` — rich geo-anchored HTML (≤ ~20 per map). Anchors: `anchor="[lng, lat]"` (static), `anchor-from="selection"` (follows picks), or `anchor-layer="regions" anchor-feature-id="mission"` (anchored to a feature's own geometry — bbox center — no coordinates in markup; `{{field}}` interpolates that feature's attributes). `{{field}}` interpolates the picked feature HTML-escaped; `{{{field}}}` is raw (avoid). For labels on many features use `PopupLayer`, not overlays.
-- `<om-behavior on="click|hover|drag|load|data-loaded" layer="..." action="...">` — declarative interaction. Built-in actions: `show-overlay`, `hide-overlay`, `show-tooltip`, `hide-tooltip`, `toggle-layer`, `filter-layer`, `highlight-feature`, `zoom-to-feature`, `set-basemap`. One payload contract everywhere: `{ layer, target, feature, featureId, coordinate }`.
+- `<om-behavior on="click|hover|drag|load|data-loaded" layer="..." action="...">` — declarative interaction. Built-in actions: `show-overlay`, `hide-overlay`, `show-tooltip`, `hide-tooltip`, `toggle-layer`, `filter-layer`, `highlight-feature`, `zoom-to-feature`, `set-basemap`, `undo`, `redo`. One payload contract everywhere: `{ layer, target, feature, featureId, coordinate }`.
+- Undo/redo is built in: user-facing manifest changes (layer toggles, filter changes, basemap switches, element add/remove, drawn sketches) are recorded automatically — the manifest is the state. `<om-widget type="undo-redo">` renders the buttons; Cmd/Ctrl-Z, Shift-Cmd/Ctrl-Z, and Ctrl-Y work on any map (text inputs keep their native undo). Camera moves, hover effects, and story playback are deliberately NOT undo steps. Widget scripts: `ctx.history.canUndo/canRedo` with watch token `history`; `ctx.emit("undo")`/`ctx.emit("redo")`.
 - `<om-fallback>` — static no-JS fallback, direct child of `<om-map>` (one per map, no attributes, plain HTML content — links allowed). Shown ONLY where scripts never run (chat-app/email file previews — iOS QuickLook renders HTML attachments with JS off — file managers, sandboxed webviews); hidden automatically once the map boots. GOOD PRACTICE: include one on every complete page, especially pages that may be shared as a file ("This interactive map requires JavaScript — open this file in a web browser", plus a hosted-version link when one exists). Without one, the stylesheet shows a generic text-only banner. The gate is pure CSS (`om-map:not(:defined)` in onlymapjs.css), so the CSS must load without JS — a real `<link rel="stylesheet">` or inlined `<style>` on no-build pages; a bundler-emitted stylesheet is fine in npm projects.
 - Animation: `transition="get-fill-color 800ms, get-radius 400ms"` on a layer GPU-animates prop changes (also smooths streaming updates via `get-position`). Camera: the `fly-to` action takes `center`/`zoom`/`pitch`/`bearing`/`duration` (e.g. `duration="2s"`) — use it in behaviors or `data-emit` buttons; `zoom-to-feature` also accepts `duration`.
-- `<om-story id="tour" autoplay loop interrupt="pause|ignore">` — a storyboard of `<om-step>` children. Each step: `action="..."` + payload attributes (same kebab-case rule as behaviors) + `duration`/`delay`/`parallel` timing. Steps REFERENCE layers/overlays by id (`layer=`/`target=`) — a step must NEVER contain elements (validation error). Control: `<om-widget type="player" story="tour">`, the story-play/story-pause/story-seek actions, or `storyEl.play()/pause()/seek(ms)`. Seeking restores initial state then applies steps before T; use declarative payloads (e.g. `action="toggle-layer" visible="true"`, not bare toggles) so scrubbing is deterministic. Effect verbs as bare step attributes: `<om-step fade layer="regions" duration="1s">` (opacity reveal — start the layer at `opacity="0"`), `pulse` (attention flash), `trace` (progressive draw — whole-layer needs a TripsLayer; add `feature-id="..."` to make ONE polygon/line draw itself on inside any layer, or use it from a click behavior for click-to-trace), `populate` (rows drop in one by one — ordered by the authored filter-field, a payload `field`, or data order).
+- `<om-story id="tour" autoplay loop interrupt="pause|ignore">` — a storyboard of `<om-step>` children. Each step: `action="..."` + payload attributes (same kebab-case rule as behaviors) + `duration`/`delay`/`parallel` timing. Steps REFERENCE layers/overlays by id (`layer=`/`target=`) — a step must NEVER contain elements (validation error). Control: `<om-widget type="player" story="tour">`, the story-play/story-pause/story-seek actions, or `storyEl.play()/pause()/seek(ms)`. Seeking restores initial state then applies steps before T; use declarative payloads (e.g. `action="toggle-layer" visible="true"`, not bare toggles) so scrubbing is deterministic. Scene actions are story-steppable AND scrub-capturable: `set-basemap`, `set-lighting` (a sunset story: steps walking sun-elevation down; a bare preset step is a clean reset), and `set-terrain` all rewind on seek — the story captures the map's scene attributes before first play. Effect verbs as bare step attributes: `<om-step fade layer="regions" duration="1s">` (opacity reveal — start the layer at `opacity="0"`), `pulse` (attention flash), `trace` (progressive draw — whole-layer needs a TripsLayer; add `feature-id="..."` to make ONE polygon/line draw itself on inside any layer, or use it from a click behavior for click-to-trace), `populate` (rows drop in one by one — ordered by the authored filter-field, a payload `field`, or data order).
 - Filtering: `filter-field="magnitude" filter-range="[4, 10]"` on a layer (GPU-side, live-updatable via the `filter-layer` action); pair with `<om-widget type="filter" layer="..." field="...">`.
 
 ## Decision rule for annotations

package/onlymapjs.html-data.json

@@ -73,10 +73,108 @@
             }
           ]
         },
+        {
+          "name": "lighting",
+          "description": "Scene lighting preset for 3D content — seeds ambient/sun/camera values that lighting-* attributes override. Absent = deck.gl default lights.",
+          "values": [
+            {
+              "name": "daylight"
+            },
+            {
+              "name": "studio"
+            },
+            {
+              "name": "flat"
+            },
+            {
+              "name": "custom"
+            }
+          ]
+        },
+        {
+          "name": "lighting-ambient",
+          "description": "Ambient light intensity (always-on fill), e.g. 0.9."
+        },
+        {
+          "name": "lighting-sun",
+          "description": "Sun (directional light) intensity; 0 removes the sun."
+        },
+        {
+          "name": "lighting-sun-azimuth",
+          "description": "Sun compass bearing, degrees clockwise from north [0, 360)."
+        },
+        {
+          "name": "lighting-sun-elevation",
+          "description": "Sun height above the horizon, degrees [0, 90]."
+        },
+        {
+          "name": "lighting-sun-date",
+          "description": "ISO 8601 or epoch ms — computes the sun's azimuth/elevation from solar position at the map center (shadow studies). Overrides azimuth/elevation."
+        },
+        {
+          "name": "lighting-camera",
+          "description": "Camera-following fill light intensity (model inspection); 0 removes it."
+        },
+        {
+          "name": "terrain",
+          "description": "3D elevation surface: a registered terrain preset, a {z}/{x}/{y} DEM URL (needs terrain-decoder), or \"off\". Replaces an active basemap while on. Geographic layers drape by default (per-layer terrain attribute overrides).",
+          "values": [
+            {
+              "name": "off"
+            },
+            {
+              "name": "terrarium"
+            },
+            {
+              "name": "maptiler-terrain"
+            }
+          ]
+        },
+        {
+          "name": "terrain-decoder",
+          "description": "DEM RGB decoder: \"terrarium\", \"mapbox-rgb\", or {rScaler,gScaler,bScaler,offset} JSON. Required for raw DEM URLs; presets carry their own.",
+          "values": [
+            {
+              "name": "terrarium"
+            },
+            {
+              "name": "mapbox-rgb"
+            }
+          ]
+        },
+        {
+          "name": "terrain-exaggeration",
+          "description": "Vertical relief multiplier, applied in the DEM decoder; 1 = true relief."
+        },
+        {
+          "name": "terrain-max-zoom",
+          "description": "DEM tileset zoom cap — the provider's REAL limit (a too-high cap requests 404 tiles and blanks the terrain)."
+        },
+        {
+          "name": "terrain-texture",
+          "description": "Optional {z}/{x}/{y} imagery template draped over the surface (satellite, etc.)."
+        },
         {
           "name": "validate",
           "description": "Run manifest validation and show the on-page error panel."
         },
+        {
+          "name": "map-id",
+          "description": "Optional authored UUID identifying this map artifact (telemetry dedup across visits/pages — not a visitor id). Opt-out: delete it."
+        },
+        {
+          "name": "license-key",
+          "description": "OnlyMapJS license token (om_live_…) — lifts the free-tier limits (5 layers / 25k rows per layer) and removes the badge. Publishable, origin-restricted; or call OmMap.configureLicense once."
+        },
+        {
+          "name": "telemetry",
+          "description": "Set \"off\" to disable usage telemetry for this map (global opt-out: OmMap.configureTelemetry).",
+          "values": [
+            {
+              "name": "off"
+            }
+          ]
+        },
         {
           "name": "headless",
           "description": "No renderer — parsing/IR only (tests, SSR)."
@@ -270,6 +368,21 @@
           "name": "highlighted-id",
           "description": "Feature id to highlight (set by the highlight-feature action)."
         },
+        {
+          "name": "terrain",
+          "description": "Behavior under an active map terrain: drape onto the surface, offset (sit on it — the 3D-model default), or off. Absent = the type default.",
+          "values": [
+            {
+              "name": "drape"
+            },
+            {
+              "name": "offset"
+            },
+            {
+              "name": "off"
+            }
+          ]
+        },
         {
           "name": "key",
           "description": "Stream entity identity field — messages upsert by this key (wss data)."
@@ -330,6 +443,34 @@
           "name": "get-line-width",
           "description": "Accessor for deck.gl getLineWidth — expression language: $field, scale(), arithmetic."
         },
+        {
+          "name": "get-point-radius",
+          "description": "Accessor for deck.gl getPointRadius — expression language: $field, scale(), arithmetic."
+        },
+        {
+          "name": "point-radius-units",
+          "description": "deck.gl pointRadiusUnits."
+        },
+        {
+          "name": "point-radius-min-pixels",
+          "description": "deck.gl pointRadiusMinPixels."
+        },
+        {
+          "name": "line-width-units",
+          "description": "deck.gl lineWidthUnits."
+        },
+        {
+          "name": "get-elevation",
+          "description": "Accessor for deck.gl getElevation — expression language: $field, scale(), arithmetic."
+        },
+        {
+          "name": "extruded",
+          "description": "deck.gl extruded."
+        },
+        {
+          "name": "wireframe",
+          "description": "deck.gl wireframe."
+        },
         {
           "name": "get-text",
           "description": "Accessor for deck.gl getText — expression language: $field, scale(), arithmetic."
@@ -578,10 +719,6 @@
           "name": "elevation-scale",
           "description": "deck.gl elevationScale."
         },
-        {
-          "name": "line-width-units",
-          "description": "deck.gl lineWidthUnits."
-        },
         {
           "name": "line-width-scale",
           "description": "deck.gl lineWidthScale."
@@ -590,22 +727,10 @@
           "name": "line-width-max-pixels",
           "description": "deck.gl lineWidthMaxPixels."
         },
-        {
-          "name": "extruded",
-          "description": "deck.gl extruded."
-        },
-        {
-          "name": "wireframe",
-          "description": "deck.gl wireframe."
-        },
         {
           "name": "flat-shading",
           "description": "deck.gl flatShading."
         },
-        {
-          "name": "get-elevation",
-          "description": "Accessor for deck.gl getElevation — expression language: $field, scale(), arithmetic."
-        },
         {
           "name": "material",
           "description": "deck.gl material."
@@ -850,18 +975,10 @@
           "name": "point-radius-max-pixels",
           "description": "deck.gl pointRadiusMaxPixels."
         },
-        {
-          "name": "point-radius-min-pixels",
-          "description": "deck.gl pointRadiusMinPixels."
-        },
         {
           "name": "point-radius-scale",
           "description": "deck.gl pointRadiusScale."
         },
-        {
-          "name": "point-radius-units",
-          "description": "deck.gl pointRadiusUnits."
-        },
         {
           "name": "point-antialiasing",
           "description": "deck.gl pointAntialiasing."
@@ -870,10 +987,6 @@
           "name": "point-billboard",
           "description": "deck.gl pointBillboard."
         },
-        {
-          "name": "get-point-radius",
-          "description": "Accessor for deck.gl getPointRadius — expression language: $field, scale(), arithmetic."
-        },
         {
           "name": "icon-size-max-pixels",
           "description": "deck.gl iconSizeMaxPixels."
@@ -1415,6 +1528,18 @@
             },
             {
               "name": "set-basemap"
+            },
+            {
+              "name": "set-lighting"
+            },
+            {
+              "name": "set-terrain"
+            },
+            {
+              "name": "undo"
+            },
+            {
+              "name": "redo"
             }
           ]
         },
@@ -1465,6 +1590,12 @@
             },
             {
               "name": "basemap-switcher"
+            },
+            {
+              "name": "lighting"
+            },
+            {
+              "name": "undo-redo"
             }
           ]
         },
@@ -1488,7 +1619,7 @@
         },
         {
           "name": "watch",
-          "description": "Space-separated watch tokens: viewport, selection, layers, data:<layerId>."
+          "description": "Space-separated watch tokens: viewport, selection, layers, history, basemap, lighting, terrain, data:<layerId>."
         },
         {
           "name": "layer",
@@ -1680,6 +1811,18 @@
             },
             {
               "name": "set-basemap"
+            },
+            {
+              "name": "set-lighting"
+            },
+            {
+              "name": "set-terrain"
+            },
+            {
+              "name": "undo"
+            },
+            {
+              "name": "redo"
             }
           ]
         },

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nika-js/onlymap",
-  "version": "0.2.2",
-  "description": "Interactive WebGL maps from declarative HTML — a custom-element manifest drives deck.gl: rendering, data loading, live updates, picking, widgets, and validation. No build step.",
+  "version": "0.3.0",
+  "description": "Declarative deck.gl maps for HTML and React — interactive WebGL mapping with GeoJSON/CSV/Arrow data, MapLibre basemaps, widgets, popups, and live streams from a custom-element manifest or typed React components. TypeScript, no build step.",
   "license": "SEE LICENSE IN LICENSE.md",
   "publishConfig": {
     "access": "public"
@@ -17,16 +17,28 @@
   },
   "keywords": [
     "deck.gl",
+    "deckgl",
+    "map",
     "maps",
+    "mapping",
     "webgl",
     "geospatial",
     "gis",
+    "geojson",
+    "react",
+    "typescript",
     "declarative",
     "custom-elements",
     "web-components",
     "maplibre",
+    "cartography",
     "dataviz",
+    "data-visualization",
     "visualization",
+    "visualisation",
+    "heatmap",
+    "layers",
+    "geoarrow",
     "llm",
     "agent"
   ],
@@ -50,6 +62,11 @@
       "import": "./dist/react.js",
       "default": "./dist/react.js"
     },
+    "./deck": {
+      "types": "./dist/deck.d.ts",
+      "import": "./dist/deck.js",
+      "default": "./dist/deck.js"
+    },
     "./onlymapjs.css": "./dist/onlymapjs.css",
     "./onlymapjs.html-data.json": "./onlymapjs.html-data.json",
     "./onlymap.code-snippets": "./.vscode/onlymap.code-snippets",
@@ -80,16 +97,18 @@
   ],
   "scripts": {
     "dev": "vite",
-    "build": "npm run typecheck && vite build && vite build --config vite.react.config.ts && npm run build:types",
+    "build": "npm run typecheck && vite build && vite build --config vite.react.config.ts && vite build --config vite.deck.config.ts && npm run build:types",
     "build:types": "tsc -p tsconfig.build.json --emitDeclarationOnly",
-    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.e2e.json --noEmit",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.e2e.json --noEmit && tsc -p cloud/workers/telemetry/tsconfig.json",
     "test": "vitest run",
     "prepublishOnly": "npm run build",
     "try": "vite-node dev/expr-repl.mjs",
     "test:e2e": "playwright test",
     "gen:html-data": "vite-node dev/generate-html-data.ts",
     "gen:public": "npm run gen:html-data && vite-node dev/build-public.ts",
-    "test:public": "npm run gen:public -- --dry-run --strict"
+    "test:public": "npm run gen:public -- --dry-run --strict",
+    "deploy:telemetry": "wrangler deploy --config cloud/workers/telemetry/wrangler.toml",
+    "dev:telemetry": "wrangler dev --config cloud/workers/telemetry/wrangler.toml"
   },
   "comment:deps": "This library ships a fully self-contained bundle in dist/ (verified: zero external bare imports), so it has NO runtime dependencies — deck.gl, loaders.gl, MapLibre, Arrow, d3, acorn, etc. are build-time-only and get bundled by Vite. Keeping them here (not in dependencies) is what stops every consumer install from pulling ~250 MB it never uses.",
   "devDependencies": {
@@ -128,6 +147,7 @@
     "vite": "^6.0.0",
     "vite-node": "^6.0.0",
     "vitest": "^4.1.9",
+    "wrangler": "^4.110.0",
     "ws": "^8.21.0"
   }
 }

package/skills/onlymapjs/SKILL.md

@@ -23,7 +23,7 @@ Use OnlyMapJS as a declarative HTML map library. Write custom elements such as `
 </script>
 ```
 
-For no-build CDN examples, use a published module URL such as `https://esm.sh/@nika-js/onlymap@0.2.0`.
+For no-build CDN examples, use a published module URL such as `https://esm.sh/@nika-js/onlymap@0.3.0`.
 
 ## React Projects
 
@@ -62,6 +62,7 @@ Load the smallest reference needed for the task:
 - Many labels/badges -> `<om-layer type="PopupLayer">`.
 - Guided tour or narrative sequence -> `<om-story>` with `<om-step>` siblings that reference existing layers/overlays by id.
 - Basemap choice or user-switchable basemaps -> `basemap` presets (`positron`, `liberty`, `dark-matter`, `osm`, ...) + `<om-widget type="basemap-switcher">`; MapTiler custom styles via a style URL or `basemap-key`.
+- Undoable UI (step back after layer toggles, filter changes, basemap switches, sketch edits) -> `<om-widget type="undo-redo">`; Cmd/Ctrl-Z works even without the widget. Camera moves and story playback are not undo steps.
 - Live entity updates -> `wss://` stream with `key` and optional `source` decoder.
 - REST snapshot that changes over time -> `refresh="5s"`.
 - User sketching -> `data="draw:sketch"` layer plus `<om-widget type="draw" target="sketch">`.
@@ -71,6 +72,8 @@ Load the smallest reference needed for the task:
 
 When creating a map page, output a complete runnable HTML file unless the user asks for a fragment. Include CSS only as needed for page sizing or custom widgets/overlays. Keep the first screen the usable map, not a landing page.
 
+Include a `map-id="<random UUID>"` attribute on `<om-map>` when creating a new complete page (generate a fresh UUID — never copy one from an example). It identifies the map artifact for usage telemetry, not the visitor; the author can delete it to opt out.
+
 Include an `<om-fallback>` element (a short "this map requires JavaScript — open in a browser" message, optionally with a hosted-version link) as a direct child of `<om-map>` on any complete page. For the fallback to render in no-JS previews, `onlymapjs.css` must load without JavaScript — a real `<link rel="stylesheet">` or inlined `<style>`, not only a runtime `import` (bundler-emitted stylesheets are fine).
 
 When modifying an existing page, preserve the user's data URLs, layer ids, and styling unless the request requires changing them.