@nika-js/onlymap 0.2.0 → 0.2.1

package/dist/programmatic.d.ts

@@ -75,8 +75,12 @@ export interface MapControllerOptions {
     zoom?: number;
     pitch?: number;
     bearing?: number;
-    /** Same contract as the `basemap` attribute — "maplibre", a style URL, or omit for standalone deck.gl. */
+    /** Same contract as the `basemap` attribute — a preset name, "maplibre", a style URL, or omit for standalone deck.gl. */
     basemap?: string;
+    /** Publishable provider key for keyed presets (`maptiler-*`) — the `basemap-key` attribute's programmatic twin (configureBasemap covers the global case). */
+    basemapKey?: string;
+    /** Set false to opt out of the compact attribution control (render your own credits). */
+    attribution?: boolean;
     /** Headless mode (spec: "Consumer Testing Surface") — no renderer, real projection math; for jsdom/happy-dom tests. */
     headless?: {
         width?: number;
@@ -166,6 +170,12 @@ export declare class MapController {
     private scheduleOverlayFlush;
     /** Dispatches an action (spec: "Action payload contract") — camera moves, pulse/populate effects, custom registered actions. */
     emit(event: string, payload?: Record<string, unknown>): void;
+    /**
+     * Live basemap change — a preset name, style URL, or "none". Style-only
+     * switches keep the renderer, camera, and layers; renderer-mode changes
+     * (none ↔ maplibre) remount seeded with the current camera.
+     */
+    setBasemap(basemap: string | null): void;
     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;

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

@@ -7,8 +7,12 @@ export interface OmMapProps {
     zoom?: number;
     pitch?: number;
     bearing?: number;
-    /** Same contract as the `basemap` attribute — "maplibre", a style URL, or omit for standalone deck.gl. Changing it remounts the renderer. */
+    /** Same contract as the `basemap` attribute — a preset name ("positron", "dark-matter", …), "maplibre", a style URL, or omit for standalone deck.gl. Changing it switches live (style-only changes keep camera + layers; none ↔ maplibre remounts the renderer inside the controller). */
     basemap?: string;
+    /** Publishable provider key for keyed presets (maptiler-*) — or call configureBasemap once instead. */
+    basemapKey?: string;
+    /** Set false to opt out of the compact attribution control. */
+    attribution?: boolean;
     /** Headless mode for tests (spec: "Consumer Testing Surface") — no renderer, real projection math under jsdom/happy-dom. */
     headless?: boolean | {
         width?: number;

package/dist/react.js

@@ -1,40 +1,40 @@
-var q = Object.defineProperty;
-var H = (e, t, n) => t in e ? q(e, t, { enumerable: !0, configurable: !0, writable: !0, value: n }) : e[t] = n;
-var D = (e, t, n) => H(e, typeof t != "symbol" ? t + "" : t, n);
-import { jsxs as G, jsx as w } from "react/jsx-runtime";
-import { createContext as J, useContext as B, forwardRef as Q, useRef as d, useState as p, useCallback as U, useMemo as j, useLayoutEffect as X, useImperativeHandle as Y, useEffect as O } from "react";
-import { MapController as Z } from "@nika-js/onlymap";
-import { createPortal as $ } from "react-dom";
-const A = J(null);
-function F(e) {
-  const t = B(A);
+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 { 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";
+const H = X(null);
+function K(e) {
+  const t = Y(H);
   if (!t) throw new Error(`[onlymapjs] ${e} must be rendered inside <OmMap>.`);
   return t;
 }
-function L(e, t) {
+function D(e, t) {
   if (e === t) return !0;
   const n = Object.keys(e ?? {}), r = Object.keys(t ?? {});
   return n.length !== r.length ? !1 : n.every((l) => e[l] === t[l]);
 }
-function ee(e, t) {
-  const { props: n, updateTriggers: r, ...l } = e, { props: a, updateTriggers: u, ...c } = t;
-  return L(l, c) && L(n, a) && L(r, u);
+function oe(e, t) {
+  const { props: n, updateTriggers: r, ...l } = e, { props: a, updateTriggers: u, ...i } = t;
+  return D(l, i) && D(n, a) && D(r, u);
 }
-class te {
+class se {
   constructor(t) {
-    D(this, "descriptors", /* @__PURE__ */ new Map());
+    A(this, "descriptors", /* @__PURE__ */ new Map());
     this.controller = t;
   }
   upsert(t) {
     const n = this.descriptors.get(t.id);
-    n && ee(n, t) || (this.descriptors.set(t.id, t), this.controller.setLayers([...this.descriptors.values()]));
+    n && oe(n, t) || (this.descriptors.set(t.id, t), this.controller.setLayers([...this.descriptors.values()]));
   }
   remove(t) {
     this.descriptors.delete(t) && this.controller.setLayers([...this.descriptors.values()]);
   }
 }
-const _ = ["top-left", "top-right", "bottom-left", "bottom-right"];
-function re(e) {
+const q = ["top-left", "top-right", "bottom-left", "bottom-right"];
+function le(e) {
   return {
     position: "absolute",
     [e.startsWith("top") ? "top" : "bottom"]: 10,
@@ -49,94 +49,102 @@ function re(e) {
     pointerEvents: "none"
   };
 }
-function ne(e, t) {
+function ie(e, t) {
   return Object.entries(t).some(([n, r]) => r !== void 0 && e[n] !== r);
 }
-const fe = Q(function(t, n) {
-  const { center: r, zoom: l, pitch: a, bearing: u, basemap: c, headless: i, className: y, style: x, children: C } = t, E = d(null), [s, f] = p(null), [h, I] = p(null), [P, k] = p({
+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({
     "top-left": null,
     "top-right": null,
     "bottom-left": null,
     "bottom-right": null
-  }), z = U((o) => {
-    I((m) => m === o ? m : o);
-  }, []), K = j(
+  }), v = ee((s) => {
+    M((h) => h === s ? h : s);
+  }, []), w = I(
     () => Object.fromEntries(
-      _.map((o) => [
-        o,
-        (m) => {
-          k((R) => R[o] === m ? R : { ...R, [o]: m });
+      q.map((s) => [
+        s,
+        (h) => {
+          L((p) => p[s] === h ? p : { ...p, [s]: h });
         }
       ])
     ),
     []
-  ), g = d({ center: r, zoom: l, pitch: a, bearing: u });
-  g.current = { center: r, zoom: l, pitch: a, bearing: u };
-  const v = d(t.onReady);
-  v.current = t.onReady;
-  const b = d(t.onViewStateChange);
-  b.current = t.onViewStateChange;
-  const S = d(t.onRuntimeError);
-  S.current = t.onRuntimeError;
-  const N = i ? JSON.stringify(i) : "";
-  X(() => {
-    if (!E.current) return;
-    const o = g.current, m = new Z(E.current, {
-      center: o.center,
-      zoom: o.zoom,
-      pitch: o.pitch,
-      bearing: o.bearing,
-      basemap: c,
-      headless: i ? i === !0 ? {} : i : void 0,
-      onRuntimeError: (M) => {
-        var W;
-        return (W = S.current) == null ? void 0 : W.call(S, M);
+  ), S = f({ center: r, zoom: l, pitch: a, bearing: u });
+  S.current = { center: r, zoom: l, pitch: a, bearing: u };
+  const b = f(t.onReady);
+  b.current = t.onReady;
+  const E = f(t.onViewStateChange);
+  E.current = t.onViewStateChange;
+  const P = f(t.onRuntimeError);
+  P.current = t.onRuntimeError;
+  const N = f(i);
+  N.current = i;
+  const V = f(void 0), G = m ? JSON.stringify(m) : "";
+  te(() => {
+    if (!d.current) return;
+    const s = S.current;
+    V.current = N.current;
+    const h = new ne(d.current, {
+      center: s.center,
+      zoom: s.zoom,
+      pitch: s.pitch,
+      bearing: s.bearing,
+      basemap: N.current,
+      basemapKey: c,
+      attribution: y,
+      headless: m ? m === !0 ? {} : m : void 0,
+      onRuntimeError: (F) => {
+        var $;
+        return ($ = P.current) == null ? void 0 : $.call(P, F);
       }
     });
-    f(m);
-    let R = !0;
-    return m.ready.then(() => {
-      var M;
-      R && ((M = v.current) == null || M.call(v));
+    T(h);
+    let p = !0;
+    return h.ready.then(() => {
+      var F;
+      p && ((F = b.current) == null || F.call(b));
     }), () => {
-      R = !1, f(null), m.destroy();
+      p = !1, T(null), h.destroy();
     };
-  }, [c, N]), Y(n, () => s, [s]), O(() => {
-    if (!s) return;
-    const o = { longitude: r == null ? void 0 : r[0], latitude: r == null ? void 0 : r[1], zoom: l, pitch: a, bearing: u };
-    ne(s.getViewState(), o) && s.setView(o);
-  }, [s, r == null ? void 0 : r[0], r == null ? void 0 : r[1], l, a, u]), O(() => {
-    if (s)
-      return s.watch(["viewport"], () => {
-        var o;
-        return (o = b.current) == null ? void 0 : o.call(b, s.getViewState());
+  }, [G]), g(() => {
+    !o || V.current === i || (V.current = i, o.setBasemap(i ?? null));
+  }, [o, i]), re(n, () => o, [o]), g(() => {
+    if (!o) return;
+    const s = { longitude: r == null ? void 0 : r[0], latitude: r == null ? void 0 : r[1], zoom: l, pitch: a, bearing: u };
+    ie(o.getViewState(), s) && o.setView(s);
+  }, [o, r == null ? void 0 : r[0], r == null ? void 0 : r[1], l, a, u]), g(() => {
+    if (o)
+      return o.watch(["viewport"], () => {
+        var s;
+        return (s = E.current) == null ? void 0 : s.call(E, o.getViewState());
       });
-  }, [s]);
-  const T = j(() => s ? new te(s) : null, [s]), V = j(
-    () => s && T && h ? { controller: s, layers: T, overlayPane: h, corners: P } : null,
-    [s, T, h, P]
+  }, [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]
   );
-  return /* @__PURE__ */ G("div", { className: y, style: { position: "relative", overflow: "hidden", ...x }, children: [
-    /* @__PURE__ */ w("div", { ref: E, style: { position: "absolute", inset: 0 } }),
-    /* @__PURE__ */ w(
+  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(
       "div",
       {
-        ref: z,
+        ref: v,
         style: { position: "absolute", top: 0, left: 0, zIndex: 10, pointerEvents: "none" }
       }
     ),
-    _.map((o) => /* @__PURE__ */ w(
+    q.map((s) => /* @__PURE__ */ x(
       "div",
       {
-        "data-om-widget-corner": o,
-        ref: K[o],
-        style: re(o)
+        "data-om-widget-corner": s,
+        ref: w[s],
+        style: le(s)
       },
-      o
+      s
     )),
-    V && /* @__PURE__ */ w(A.Provider, { value: V, children: C })
+    _ && /* @__PURE__ */ x(H.Provider, { value: _, children: R })
   ] });
-}), oe = /* @__PURE__ */ new Set([
+}), ae = /* @__PURE__ */ new Set([
   "id",
   "type",
   "data",
@@ -155,10 +163,10 @@ const fe = Q(function(t, n) {
   "onClick",
   "onHover"
 ]);
-function de(e) {
-  const { controller: t, layers: n } = F("OmLayer"), { id: r } = e, l = {};
-  for (const [i, y] of Object.entries(e))
-    !oe.has(i) && y !== void 0 && (l[i] = y);
+function ge(e) {
+  const { controller: t, layers: n } = K("OmLayer"), { id: r } = e, l = {};
+  for (const [c, y] of Object.entries(e))
+    !ae.has(c) && y !== void 0 && (l[c] = y);
   const a = {
     id: r,
     type: e.type,
@@ -177,32 +185,32 @@ function de(e) {
     updateTriggers: e.updateTriggers,
     props: l
   };
-  O(() => {
+  g(() => {
     n.upsert(a);
-  }), O(() => () => n.remove(r), [n, r]);
-  const u = d(e.onClick);
+  }), g(() => () => n.remove(r), [n, r]);
+  const u = f(e.onClick);
   u.current = e.onClick;
-  const c = d(e.onHover);
-  return c.current = e.onHover, O(
-    () => t.watchPicks((i) => {
-      var y, x, C;
-      if (i === null) {
-        (y = c.current) == null || y.call(c, null);
+  const i = f(e.onHover);
+  return i.current = e.onHover, g(
+    () => t.watchPicks((c) => {
+      var y, m, O;
+      if (c === null) {
+        (y = i.current) == null || y.call(i, null);
         return;
       }
-      i.layerId === r && (i.type === "click" ? (x = u.current) == null || x.call(u, i) : (C = c.current) == null || C.call(c, i));
+      c.layerId === r && (c.type === "click" ? (m = u.current) == null || m.call(u, c) : (O = i.current) == null || O.call(i, c));
     }),
     [t, r]
   ), null;
 }
-function ye({ position: e = "top-left", className: t, style: n, children: r }) {
-  const { corners: l } = F("OmWidget"), a = l[e];
-  return a ? $(
-    /* @__PURE__ */ w("div", { className: t, style: { pointerEvents: "auto", ...n }, children: r }),
+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 }),
     a
   ) : null;
 }
-const se = {
+const ce = {
   "top-left": "translate(0, 0)",
   "top-center": "translate(-50%, 0)",
   "top-right": "translate(-100%, 0)",
@@ -213,32 +221,32 @@ const se = {
   "bottom-center": "translate(-50%, -100%)",
   "bottom-right": "translate(-100%, -100%)"
 };
-function he(e) {
-  const { controller: t, overlayPane: n } = F("OmOverlay"), r = d(null), l = d(void 0), [a, u] = p(null), c = d(e);
-  c.current = e, O(
-    () => t.registerOverlay((s, f) => {
-      const h = r.current;
-      if (!h) return;
-      const { anchor: I, anchorFrom: P, layer: k, visible: z = !0, anchorOffset: K } = c.current;
-      let g;
-      if (P === "selection" ? ((!k || (f == null ? void 0 : f.layerId) === k) && (l.current = (f == null ? void 0 : f.coordinate) ?? void 0, u(f)), g = l.current) : g = I, !z || !g || !s) {
-        h.style.visibility = "hidden";
+function be(e) {
+  const { controller: t, overlayPane: n } = K("OmOverlay"), r = f(null), l = f(void 0), [a, u] = k(null), i = f(e);
+  i.current = e, g(
+    () => 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;
+      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) {
+        o.style.visibility = "hidden";
         return;
       }
-      const [v, b, S] = s.project([g[0], g[1], 0]);
-      if (!(v >= 0 && v <= s.width && b >= 0 && b <= s.height) || S !== void 0 && S < 0) {
-        h.style.visibility = "hidden";
+      const [w, S, b] = R.project([v[0], v[1], 0]);
+      if (!(w >= 0 && w <= R.width && S >= 0 && S <= R.height) || b !== void 0 && b < 0) {
+        o.style.visibility = "hidden";
         return;
       }
-      h.style.visibility = "visible", h.style.transform = `translate(${v}px, ${b}px) ${se[K ?? "bottom-center"]}`;
+      o.style.visibility = "visible", o.style.transform = `translate(${w}px, ${S}px) ${ce[L ?? "bottom-center"]}`;
     }),
     [t]
-  ), O(() => {
+  ), g(() => {
     t.refreshOverlays();
   });
-  const { children: i, className: y, style: x, interactive: C = !0 } = e, E = typeof i == "function" ? i(a) : i;
-  return $(
-    /* @__PURE__ */ w(
+  const { children: c, className: y, style: m, interactive: O = !0 } = e, z = typeof c == "function" ? c(a) : c;
+  return B(
+    /* @__PURE__ */ x(
       "div",
       {
         ref: r,
@@ -250,23 +258,23 @@ function he(e) {
           visibility: "hidden",
           // hidden until the first flush positions it — never flashes at the origin
           willChange: "transform",
-          pointerEvents: C ? "auto" : "none",
-          ...x
+          pointerEvents: O ? "auto" : "none",
+          ...m
         },
-        children: E
+        children: z
       }
     ),
     n
   );
 }
-function me(e = []) {
-  const { controller: t } = F("useOmMap"), n = e.join(" "), r = j(() => n ? n.split(" ") : [], [n]), [l, a] = p(() => t.buildCtx());
-  return O(() => t.watch(r, a), [t, r]), l;
+function Oe(e = []) {
+  const { controller: t } = K("useOmMap"), n = e.join(" "), r = I(() => n ? n.split(" ") : [], [n]), [l, a] = k(() => t.buildCtx());
+  return g(() => t.watch(r, a), [t, r]), l;
 }
 export {
-  de as OmLayer,
-  fe as OmMap,
-  he as OmOverlay,
-  ye as OmWidget,
-  me as useOmMap
+  ge as OmLayer,
+  he as OmMap,
+  be as OmOverlay,
+  ve as OmWidget,
+  Oe as useOmMap
 };

package/dist/runtime-core.d.ts

@@ -56,6 +56,13 @@ export interface HeadlessOptions {
     width: number;
     height: number;
 }
+/** Basemap-preset options (spec: "Basemap presets & switching") — the publishable provider key and the attribution opt-out. */
+export interface BasemapRuntimeOptions {
+    /** `basemap-key` — substituted into keyed presets' `{key}` placeholder (falls back to configureBasemap). */
+    key?: string;
+    /** `attribution="false"` opt-out — default true: the compact attribution control renders whenever a basemap is active. */
+    attribution?: boolean;
+}
 export declare class RuntimeCore {
     private deck?;
     private basemap?;
@@ -77,7 +84,33 @@ export declare class RuntimeCore {
     private destroyed;
     private viewState;
     private callbacks;
-    constructor(parent: HTMLElement, initialView: InitialView, callbacks?: RuntimeCoreCallbacks, basemapAttr?: string, headless?: HeadlessOptions);
+    private parent;
+    /** The live `basemap` attribute value — re-read by the lazy adapter chunk so a switch during its load lands the LATEST style. */
+    private basemapAttr?;
+    private basemapOptions?;
+    /** Bumped on every renderer (re)init — a superseded lazy chunk load must not install its adapter over a newer renderer. */
+    private rendererGeneration;
+    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;
+    /**
+     * Constructs the renderer for the requested mode — the constructor's
+     * body, extracted so setBasemap() can remount on a renderer-MODE change
+     * (none ↔ maplibre). Reads/seeds the camera from `this.viewState`.
+     */
+    private initRenderer;
+    /**
+     * Live basemap change (spec: "Basemap presets & switching"), both paths:
+     * - maplibre → maplibre: `map.setStyle()` — deck layers survive (the
+     *   overlay is a control, not style layers) and the camera is untouched.
+     * - renderer-MODE change (none ↔ maplibre, or a mapbox fallback): full
+     *   remount seeded with the current camera; the retained IRs are re-handed
+     *   to the new renderer, so the scene carries over.
+     * Headless ignores it (no renderer to switch); `om-map-ready` semantics
+     * are unaffected (readiness settles once, at initial load).
+     */
+    setBasemap(attr: string | null): void;
+    private teardownRenderer;
     /**
      * Rebuilds every deck.gl Layer instance from the current IR and hands the
      * full array to deck.gl (or the basemap's MapboxOverlay) on every

package/dist/widget-registry.d.ts

@@ -11,6 +11,8 @@ export interface WidgetHost {
     $$(sel: string): NodeListOf<Element>;
     getAttribute(name: string): string | null;
     hasAttribute(name: string): boolean;
+    /** Element.closest — satisfied structurally by the widget element itself; widgets needing owning-map attributes use closest("om-map") (e.g. basemap-switcher's current selection). */
+    closest(selector: string): Element | null;
     /** Per-instance mutable stash for state that must survive across renders (e.g. a Vega view to `.finalize()` before re-embedding). */
     state: Record<string, unknown>;
 }

package/docs/basemaps.md

@@ -0,0 +1,89 @@
+# Basemaps
+
+The `basemap` attribute on `<om-map>` selects what renders under your data layers. It accepts a **preset name**, a **MapLibre style URL**, `"maplibre"` (the demo style), or `"none"` (standalone deck.gl canvas). No preset needs a token except the MapTiler ones.
+
+```html
+<om-map center="[-122.42, 37.77]" zoom="12" basemap="positron">
+  …layers, widgets…
+  <om-widget type="basemap-switcher" position="top-right"></om-widget>
+</om-map>
+```
+
+## Built-in presets
+
+| Name | Provider | Key | Notes |
+|---|---|---|---|
+| `liberty` | [OpenFreeMap](https://openfreemap.org) | none | Full-detail OSM vector style. No registration, no limits — production use invited. |
+| `bright` | OpenFreeMap | none | High-contrast OSM vector style. |
+| `positron` | OpenFreeMap | none | Ultra-clean light style — the classic dataviz backdrop. |
+| `dark-matter` | [CARTO](https://github.com/CartoDB/basemap-styles) | none | Dark dataviz style. Attribution required (rendered automatically). |
+| `voyager` | CARTO | none | Balanced light style with labels. |
+| `osm` | [openstreetmap.org](https://operations.osmfoundation.org/policies/tiles/) | none | The classic raster look. **Policy-constrained**: donation-funded, no uptime guarantee; commercial apps should prefer a vector preset or a paid provider. |
+| `maptiler-streets` / `maptiler-dataviz` / `maptiler-satellite` | [MapTiler](https://docs.maptiler.com/cloud/api/maps/) | **required** | Free tier available; the satellite preset is the one imagery option here. |
+| `maplibre` | MapLibre demo tiles | none | Country-level outlines only — fine for smoke tests, not production. |
+
+## Switching at runtime
+
+The `basemap` attribute is **live** — write it and the map switches in place, keeping the camera and every deck.gl layer:
+
+```js
+document.querySelector("om-map").setAttribute("basemap", "dark-matter");
+```
+
+Three equivalent surfaces, same as every action:
+
+```html
+<om-widget type="basemap-switcher" options="positron dark-matter liberty osm"></om-widget>
+<button data-emit="set-basemap" data-basemap="dark-matter">Dark</button>
+<om-behavior on="load" action="set-basemap" basemap="voyager"></om-behavior>
+```
+
+Omit `options` and the switcher lists every registered keyless preset. Switching between `none` and a basemap changes the renderer, so it remounts under the hood — still seamless (camera and layers carry over), just heavier than a style swap.
+
+## MapTiler: keys and custom-edited styles
+
+MapTiler keys are **publishable, origin-restricted client keys** — they belong in page source (restrict them to your domains in the MapTiler dashboard). Two ways to supply one:
+
+```html
+<om-map basemap="maptiler-dataviz" basemap-key="YOUR_KEY">
+```
+```js
+OmMap.configureBasemap({ maptilerKey: "YOUR_KEY" });   // once, covers every maptiler-* preset
+```
+
+To **customize a basemap visually**, use MapTiler's Customize editor: pick a base style, edit colors/fonts/labels in the browser (it's editing MapLibre style JSON under the hood), save — you get a style URL for your edited style. Use it directly, or give it a name:
+
+```html
+<om-map basemap="https://api.maptiler.com/maps/YOUR_STYLE_ID/style.json?key=YOUR_KEY">
+```
+```js
+OmMap.registerBasemap("brand", {
+  style: "https://api.maptiler.com/maps/YOUR_STYLE_ID/style.json?key={key}",
+  label: "Brand",
+  requiresKey: "maptiler",
+});
+```
+
+## Register your own
+
+`OmMap.registerBasemap(name, preset)` takes any MapLibre style URL **or inline style object** — self-hosted styles, other providers, or JSON-level edits of a preset:
+
+```js
+const style = await (await fetch("https://tiles.openfreemap.org/styles/positron")).json();
+style.layers.find((l) => l.id === "background").paint["background-color"] = "#f4efe9";
+OmMap.registerBasemap("warm-positron", { style, label: "Warm Positron" });
+```
+
+Registered names show up in the switcher widget, validation, and (after `npx @nika-js/onlymap init` regeneration in your own tooling) autocomplete.
+
+## Attribution
+
+Map data providers require attribution — OSM, OpenFreeMap, and CARTO all carry it in their style sources, and OnlyMapJS renders MapLibre's compact attribution control automatically whenever a basemap is active. Preset-level `attribution` text is appended. If you render your own credits, opt out with `attribution="false"` on `<om-map>` — but make sure your replacement satisfies the provider's terms.
+
+## Validation
+
+A typo'd preset name or a keyed preset without a key is a **validation error** (the live map falls back to the demo style so it still renders): `OmMap.validate(html)` lists the registered names or the two key routes in the `fix`.
+
+## React
+
+Same contract on the adapter: `<OmMap basemap="positron" basemapKey="…">` — changing the `basemap` prop switches live (style-only changes keep camera + layers). There's no switcher widget in React; it's a `useState` + the prop. `set-basemap` is not dispatched on the programmatic front-end — use the prop or `controller.setBasemap(name)`.

package/docs/react.md

@@ -54,7 +54,7 @@ Actions that mutate manifest attributes (`toggle-layer`, `show-overlay`, `fade`,
 | Prop | Notes |
 |---|---|
 | `center` `zoom` `pitch` `bearing` | Initial camera; later prop changes move the camera (instant). While they're unchanged, user panning is never fought. |
-| `basemap` | Same contract as the attribute — `"maplibre"`, a style URL, or omit for standalone deck.gl. |
+| `basemap` | Same contract as the attribute — a preset name (`"positron"`, `"dark-matter"`, `"osm"`, …), a style URL, or omit for standalone deck.gl. Changing the prop switches live (camera + layers survive); `basemapKey` supplies the MapTiler key. See [docs/basemaps.md](basemaps.md). |
 | `headless` | `true` or `{ width, height }` — no renderer, real projection math (tests under jsdom/happy-dom). |
 | `onReady` | Renderer up + first commit + no data URL still loading. |
 | `onViewStateChange` | Every camera change, with the current `CameraState`. |

package/llms.txt

@@ -16,11 +16,11 @@ 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="maplibre">` — the root. `basemap` accepts `maplibre` (default style, no token), a style URL, or `none` (standalone canvas). `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.
 - `<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|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|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-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`. 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`. One payload contract everywhere: `{ layer, target, feature, featureId, coordinate }`.
 - 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="...">`.