@nika-js/onlymap 0.2.1 → 0.2.3

package/dist/runtime-core.d.ts

@@ -90,6 +90,12 @@ 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;
+    /** (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;

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/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.2.3";

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,11 +16,13 @@ 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-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. 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.
 - `<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-widget type="legend|layer-switcher|basemap-switcher|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).
 - 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="...">`.

package/onlymapjs.html-data.json

@@ -77,6 +77,23 @@
           "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)."
@@ -93,7 +110,7 @@
       "references": [
         {
           "name": "README",
-          "url": "https://github.com/NikaGeospatial/onlymapjs/blob/main/docs/../README.md"
+          "url": "https://github.com/NikaGeospatial/onlymapjs/blob/main/README.md"
         }
       ]
     },
@@ -1294,6 +1311,17 @@
         }
       ]
     },
+    {
+      "name": "om-fallback",
+      "description": "Static fallback shown only when the library never boots — JS-disabled contexts like chat-app/email file previews (iOS QuickLook), file managers, sandboxed webviews. Direct child of <om-map>; hidden automatically once the map upgrades. Good practice on any page that may be shared as a file. Without one, the stylesheet shows a text-only default banner. Requires onlymapjs.css to load without JS (link tag / bundled / inlined).",
+      "attributes": [],
+      "references": [
+        {
+          "name": "README",
+          "url": "https://github.com/NikaGeospatial/onlymapjs/blob/main/README.md"
+        }
+      ]
+    },
     {
       "name": "om-behavior",
       "description": "Declarative event → action wiring. Every other attribute becomes a payload key (kebab→camel).",
@@ -1404,6 +1432,12 @@
             },
             {
               "name": "set-basemap"
+            },
+            {
+              "name": "undo"
+            },
+            {
+              "name": "redo"
             }
           ]
         },
@@ -1454,6 +1488,9 @@
             },
             {
               "name": "basemap-switcher"
+            },
+            {
+              "name": "undo-redo"
             }
           ]
         },
@@ -1669,6 +1706,12 @@
             },
             {
               "name": "set-basemap"
+            },
+            {
+              "name": "undo"
+            },
+            {
+              "name": "redo"
             }
           ]
         },

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@nika-js/onlymap",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "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.",
   "license": "SEE LICENSE IN LICENSE.md",
   "publishConfig": {
     "access": "public"
   },
   "author": "NikaGeospatial",
-  "homepage": "https://github.com/NikaGeospatial/onlymapjs#readme",
+  "homepage": "https://www.nikaplanet.com/onlymap",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/NikaGeospatial/onlymapjs.git"
@@ -82,14 +82,16 @@
     "dev": "vite",
     "build": "npm run typecheck && vite build && vite build --config vite.react.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 +130,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

@@ -1,6 +1,6 @@
 ---
 name: onlymapjs
-description: Build, edit, debug, or review OnlyMapJS declarative HTML maps and dashboards, or React maps via the @nika-js/onlymap/react adapter. Use when a user asks for an interactive map, deck.gl-style visualization, geospatial dashboard, live fleet/telemetry map, choropleth, popup/tooltip map, map story/tour, manual drawing/sketch map, 3D map assets, a React map component, or help with OnlyMapJS syntax, validation, widgets, data formats, testing, or publishing examples.
+description: Build, edit, debug, or review OnlyMapJS declarative HTML maps and dashboards, or React maps via the @nika-js/onlymap/react adapter. Use when a user asks for an interactive map, deck.gl-style visualization, geospatial dashboard, live fleet/telemetry map, choropleth, popup/tooltip map, map story/tour, manual drawing/sketch map, 3D map assets, a React map component, a map page shared as a single HTML file (incl. no-JS fallbacks for chat/email previews), or help with OnlyMapJS syntax, validation, widgets, data formats, testing, or publishing examples.
 ---
 
 # OnlyMapJS
@@ -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.2.3`.
 
 ## React Projects
 
@@ -62,12 +62,18 @@ 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">`.
+- Page may travel as a file (shared, emailed, downloaded) or be embedded -> add an `<om-fallback>` child to `<om-map>`. Chat-app and email previews render HTML with JavaScript disabled (iOS QuickLook), so the map cannot boot there; the fallback is what recipients see instead. It is hidden automatically once the map boots. Good practice on every complete page — without one, the stylesheet shows a generic text-only banner.
 
 ## Output Expectations
 
 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.

package/skills/onlymapjs/references/patterns.md

@@ -29,11 +29,17 @@ Use these patterns as starting points. Replace data URLs, layer ids, fields, cen
                 pickable></om-layer>
     <om-widget type="legend" position="bottom-right" title="Layers"></om-widget>
     <om-widget type="zoom-controls" position="top-right"></om-widget>
+    <!-- Shown only where scripts never run (chat-app/email file previews) -->
+    <om-fallback>
+      <p>This interactive map requires JavaScript — open this file in a web browser.</p>
+    </om-fallback>
   </om-map>
 </body>
 </html>
 ```
 
+Every complete-page pattern below should also carry an `<om-fallback>` (omitted for brevity) — see the good-practice rule in SKILL.md.
+
 ## Click Popup
 
 ```html

package/skills/onlymapjs/references/syntax.md

@@ -19,13 +19,13 @@ Static CDN page:
 <script type="module" src="https://esm.sh/@nika-js/onlymap@0.1.0"></script>
 ```
 
-If using MapLibre basemaps from a built package, include the CSS import or stylesheet. Standalone `basemap="none"` maps do not need the CSS.
+Always include `onlymapjs.css` — it carries the MapLibre basemap styles and the no-JS fallback rules (`<om-fallback>` / default banner). For the fallback to work in script-disabled previews it must load without JavaScript: a real `<link rel="stylesheet">` or inlined `<style>` on no-build pages (a bundler-emitted stylesheet is fine in npm projects).
 
 ## Elements
 
 ### `<om-map>`
 
-Root element. Children are layers, widgets, overlays, behaviors, and stories.
+Root element. Children are layers, widgets, overlays, behaviors, stories, and an optional fallback.
 
 Common attributes:
 
@@ -36,6 +36,9 @@ Common attributes:
 - `basemap` — a free preset (`liberty`, `bright`, `positron`, `dark-matter`, `voyager`, `osm`; keyed `maptiler-streets|dataviz|satellite` with `basemap-key="…"` or `OmMap.configureBasemap({ maptilerKey })`), `maplibre` (bare demo style), a MapLibre style URL, or `none` (standalone canvas). The attribute is live: writing it switches the basemap in place (camera and layers survive). Register more with `OmMap.registerBasemap(name, { style })`.
 - `attribution="false"` to opt out of the automatic provider-attribution control (only if you render equivalent credits yourself)
 - `validate` to show live validation errors during authoring
+- `map-id="<random UUID>"` — identifies the map artifact for usage telemetry (not a visitor id). Include one on new complete pages, freshly generated — never copied from an example; deleting it is the opt-out.
+- `telemetry="off"` disables usage telemetry for this map (global: `OmMap.configureTelemetry({ disabled: true })`)
+- `license-key="om_live_…"` — lifts the free-plan limits (5 layers, 25k rows per layer) and removes the corner badge; publishable origin-restricted token, safe in page source (or `OmMap.configureLicense(key)` once). Free-plan violations don't break the map: the offending layer isn't rendered and validation names the limit.
 - `headless width="800" height="600"` for test harness use
 
 Example:
@@ -180,6 +183,7 @@ Built-ins:
 - `vega-lite`
 - `player`
 - `basemap-switcher` — radio list of presets; `options="positron dark-matter osm"` (default: every keyless registered preset)
+- `undo-redo` — undo/redo buttons over the manifest history (layer toggles, filters, basemap switches, element edits, drawn sketches). Keyboard works without the widget: Cmd/Ctrl-Z, Shift-Cmd/Ctrl-Z, Ctrl-Y. Camera moves, hover effects, and story playback are not undo steps.
 
 Positions: `top-left`, `top-right`, `bottom-left`, `bottom-right`.
 
@@ -215,8 +219,11 @@ Widget context:
 - `ctx.stats(id, field, { scope: "viewport" })`
 - `ctx.selection`
 - `ctx.viewport`
+- `ctx.history` — `{ canUndo, canRedo }`; re-render on changes via the `history` watch token
 - `ctx.emit(action, payload)`
 
+Watch tokens: `data:<layerId>`, `viewport`, `selection`, `layers` (fires on layer add/remove, visibility, and filter changes), `basemap`, `history`.
+
 Use `this.$()` and `this.root`; widgets render in shadow DOM.
 
 ### `<om-overlay>`
@@ -243,6 +250,26 @@ Example:
 <om-behavior on="click" layer="quakes" action="show-overlay" target="detail"></om-behavior>
 ```
 
+### `<om-fallback>`
+
+Static content shown only where scripts never run — chat-app/email file previews (iOS QuickLook), file managers, sandboxed webviews. Hidden automatically once the map boots. Good practice on every complete page, especially one that may be shared as a file.
+
+Rules:
+
+- Direct child of `<om-map>` (validation warns elsewhere), one per map.
+- No attributes; plain HTML content — links work, so include a hosted-version URL when one exists.
+- Without an `<om-fallback>`, the stylesheet shows a generic text-only banner instead.
+- Requires `onlymapjs.css` to load without JavaScript (see Import Patterns above).
+
+Example:
+
+```html
+<om-fallback>
+  <p><strong>This interactive map requires JavaScript.</strong><br />
+     Open this file in a web browser, or visit <a href="https://example.com/map">the hosted version</a>.</p>
+</om-fallback>
+```
+
 ### `<om-behavior>`
 
 Declarative event to action binding.
@@ -258,6 +285,7 @@ Common built-in actions:
 - `zoom-to-feature`
 - `filter-layer`
 - `set-basemap` — payload `{ basemap }`; writes the `<om-map basemap>` attribute
+- `undo`, `redo` — step the manifest history (no payload)
 - `zoom-in`, `zoom-out`
 - `fly-to`
 - story actions: `story-play`, `story-pause`, `story-seek`

package/skills/onlymapjs/references/testing.md

@@ -92,6 +92,8 @@ Harness operations:
 
 Use `vi.stubGlobal("fetch", ...)` for URL data and `vi.stubGlobal("WebSocket", ...)` for streams.
 
+Free-plan license gates (5 layers, 25k rows per layer) apply in headless tests exactly as in production — gated layers emit errors on the validation stream instead of rendering. If the page under test legitimately exceeds the limits, call `OmMap.configureLicense("om_live_…")` in test setup; keys verify offline, so CI needs no network. Telemetry never fires from headless maps.
+
 ## Browser/E2E Testing
 
 Use Playwright only for pixels, real GPU picking, basemap composition, or asset rendering.