@nika-js/onlymap 0.1.1 → 0.2.1

package/docs/testing.md

@@ -0,0 +1,165 @@
+# Testing pages built with OnlyMapJS
+
+Maps built on raw deck.gl are famously hard to test: deck.gl needs a real WebGL2 context, jsdom is ruled out entirely, and most teams end up with a handful of slow, flaky browser tests — or nothing. OnlyMapJS is designed so that **almost everything about your map page is testable in your ordinary test runner, in milliseconds, with no browser and no GPU.**
+
+This guide is the complete workflow. It assumes a page like this (a manifest in an HTML file you deploy):
+
+```html
+<!-- public/dashboard.html -->
+<om-map center="[-122.42, 37.77]" zoom="11">
+  <om-layer id="quakes" type="ScatterplotLayer" data="./quakes.json"
+              get-position="[$lon, $lat]"
+              get-fill-color="scale($magnitude, sequential, ['#fee8c8','#b30000'], domain=[0,7])"
+              filter-field="magnitude" filter-range="[0, 10]" pickable></om-layer>
+  <om-overlay id="detail" anchor-from="selection" visible="false">
+    <div><b>{{place}}</b> — M {{magnitude}}</div>
+  </om-overlay>
+  <om-behavior on="click" layer="quakes" action="show-overlay" target="detail"></om-behavior>
+  <om-widget id="stats" position="top-left"> ... </om-widget>
+</om-map>
+```
+
+## The three tiers
+
+What decides where a test belongs is the heaviest thing the code under test needs: **nothing**, **a DOM**, or **a GPU**.
+
+| Tier | Question | Needs | Speed | Rough share of your tests |
+|---|---|---|---|---|
+| 1 | Is my surrounding logic right? | bare Node | ms | as much as you have |
+| 2a | Is my manifest valid, and did its *meaning* change? | fake DOM (happy-dom/jsdom) | ms | 2–3 tests |
+| 2b | Does my page *behave* right? | fake DOM | ms | **the bulk** |
+| 3 | Does it actually render and pick? | real browser (Playwright) | seconds | 2–5 tests |
+
+## Setup (once)
+
+```bash
+npm i -D vitest happy-dom @playwright/test
+```
+
+```jsonc
+// package.json
+"scripts": {
+  "test": "vitest run",          // tiers 1–2: every commit
+  "test:e2e": "playwright test"  // tier 3: PR / nightly
+}
+```
+
+**Test the real page file, not a copy.** Read the deployed HTML into your tests so there is one source of truth:
+
+```ts
+// test/manifest.ts
+import { readFileSync } from "node:fs";
+export const PAGE = readFileSync("public/dashboard.html", "utf8");
+```
+
+## Tier 1 — your own logic (bare Node)
+
+Whatever surrounds the map — data transforms, URL builders, config generation. Nothing OnlyMapJS-specific, except one inherited guarantee: `import "@nika-js/onlymap"` is **side-effect-safe in Node** (element registration no-ops outside a browser), so shared modules that import the library never break your test runner.
+
+## Tier 2a — static: validate + lock the meaning
+
+```ts
+// test/manifest.test.ts
+// @vitest-environment happy-dom
+import { OmMap } from "@nika-js/onlymap";
+import { PAGE } from "./manifest";
+
+it("manifest is valid", () => {
+  const result = OmMap.validate(PAGE);
+  expect(result.errors).toEqual([]); // on failure: structured entries, each with a `fix` instruction
+});
+
+it("manifest meaning is locked", () => {
+  expect(OmMap.snapshotIR(PAGE)).toMatchSnapshot();
+});
+```
+
+`snapshotIR` resolves the manifest through the real pipeline (schema, attribute resolution, accessor compilation) into JSON-safe descriptors where **accessors appear as behavioral fingerprints**. Any edit that changes what the map *means* — an expression, a filter range, layer order — shows up as a snapshot diff in code review. Refactors that don't change meaning produce no diff.
+
+## Tier 2b — behavioral: `mountForTest`
+
+This is where most of your tests should live. The harness mounts your real page **headlessly**: no deck.gl instance, no canvas — but everything else runs for real, including the projection math (deck.gl's `WebMercatorViewport` is pure math, no WebGL).
+
+```ts
+// test/dashboard.test.ts
+// @vitest-environment happy-dom
+import "@nika-js/onlymap";
+import { mountForTest, type TestHarness } from "@nika-js/onlymap";
+import { PAGE } from "./manifest";
+
+let h: TestHarness;
+afterEach(() => h?.unmount());
+
+it("clicking a quake opens the detail popup", async () => {
+  h = await mountForTest(PAGE);
+  await h.pick({ layer: "quakes", featureId: "us7000abcd" });   // or { index: 3 }; type: "click" | "hover" | "drag"
+  const popup = h.map.querySelector("#detail")!;
+  expect(popup.getAttribute("visible")).toBe("true");
+  expect(popup.shadowRoot!.textContent).toContain("M 6.5");     // open shadow roots — plain DOM assertions
+});
+
+it("the magnitude filter narrows what widgets see", async () => {
+  h = await mountForTest(PAGE);
+  await h.emit("filter-layer", { layer: "quakes", field: "magnitude", range: [5, 10] });
+  expect(h.map.querySelector("#stats")!.shadowRoot!.textContent).toContain("12 events");
+});
+
+it("panning away empties viewport-scoped widgets", async () => {
+  h = await mountForTest(PAGE);
+  await h.setView({ center: [30, 30], zoom: 4 });               // pitch/bearing supported too
+  expect(h.map.querySelector("#histogram")!.shadowRoot!.textContent).toContain("0");
+});
+```
+
+The harness API: `pick` (synthetic picks fed through the exact code path real deck.gl picks take — columnar layers pick object-less by index, exactly like live), `clearSelection` (hover-off; runs the tooltip auto-hide path), `emit` (any action, same payload contract as `ctx.emit`/`data-emit`), `setView`, `layers()` (the live IR), `flush`, `unmount`. Every verb settles the library's internal batching before resolving — **you never write a sleep**.
+
+**Remote data:** mock `fetch` and the harness waits for it via the readiness signal:
+
+```ts
+vi.stubGlobal("fetch", vi.fn(async () => ({ ok: true, json: async () => rows })));
+h = await mountForTest(PAGE);                 // resolves after the mocked fetch settles
+```
+
+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).
+
+## Tier 3 — visual: Playwright
+
+Keep this thin — two to five tests — because the logic is already covered below. The library gives you three tools that remove the usual flakiness:
+
+1. **`await mapEl.ready`** — resolves when the renderer initialized *and* the first reconcile ran *and* every declared `data` URL settled. Never `waitForTimeout`.
+2. **`mapEl.projectInternal([lng, lat])`** — derive click/hover pixels from the map's own projection instead of hardcoding coordinates.
+3. **Typed lookups** — `document.querySelector("om-map")` is fully typed (no casts) once the library is imported anywhere in your typechecked graph.
+
+```ts
+// tier-3 Playwright spec (see package.json test:e2e)
+import { test, expect } from "@playwright/test";
+
+test("dashboard renders and real picking works", async ({ page }) => {
+  await page.goto("/dashboard.html");
+  await page.evaluate(() => document.querySelector("om-map")!.ready);
+
+  // Derive the pixel from data the page actually loaded — datasets change.
+  const target = await page.evaluate(() => {
+    const map = document.querySelector("om-map")!;
+    const quake = (map.getLayers().find((l) => l.id === "quakes")!.data as { lon: number; lat: number }[])[0];
+    return map.projectInternal([quake.lon, quake.lat]);
+  });
+  const box = (await page.locator("om-map").boundingBox())!;
+  await page.mouse.click(box.x + target![0], box.y + target![1]);
+
+  await expect(page.locator("#detail").getByText(/M \d/)).toBeVisible(); // locators pierce open shadow roots
+});
+```
+
+For more patterns — settle-by-observation screenshot polling for repaint assertions, hover-candidate loops for overlapping geometry, paint-order probes — the library's own end-to-end suite is written as the reference recipe for exactly these.
+
+## The one rule about distribution
+
+**Don't re-test tier-2 facts at tier 3.** If the popup's content is asserted in the harness, the e2e test only needs to prove the click-through-real-pixels path works once. Teams that ignore this end up with a slow suite that duplicates a fast one — and then stop running the slow one.
+
+## Agents
+
+Everything above applies to AI agents generating map pages, with one addition: the loop is `OmMap.validate(html)` (is it well-formed? each error carries a `fix`), then `OmMap.snapshotIR(html)` (what does it *mean*? diff against intent), then optionally `mountForTest` to verify interactions — all headless, all deterministic. See [`llms.txt`](../llms.txt).

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="...">`.
@@ -29,10 +29,14 @@ OnlyMapJS is NOT raw deck.gl and NOT generic HTML/JSX. The rules below are the d
 
 UI panel (legend, chart, stats) → `<om-widget>`. Rich HTML at one map location (click popup) → `<om-overlay>`. Labels/badges on many features → `<om-layer type="PopupLayer">`.
 
+## React projects
+
+In a React codebase, do NOT render om-* elements from JSX (React and the library would contend over the same DOM). Use the first-party adapter instead: `import { OmMap, OmLayer, OmWidget, OmOverlay, useOmMap } from "@nika-js/onlymap/react"` — camelCase deck.gl props, accessors as plain JS functions (`getFillColor={d => ...}`, no expression language), interactions as `onClick`/`onHover` handlers, widget state via the `useOmMap(watchTokens)` hook. Guide: [docs/react.md](docs/react.md).
+
 ## Docs
 
 - [README](README.md): thesis, authoring overview, build/run commands
-- [Docs](docs/): consumer guides for testing, live data, stories, and 3D assets
+- [Docs](docs/): consumer guides for testing, live data, stories, React, and 3D assets
 - [Examples](examples/index.html): complete reviewed manifests covering widgets, overlays, basemaps, columnar data, drawing, 3D, stories, and live-data patterns
 
 ## Verification loop

package/onlymapjs.html-data.json

@@ -23,10 +23,53 @@
         },
         {
           "name": "basemap",
-          "description": "Basemap renderer.",
+          "description": "Basemap: a registered preset name, \"maplibre\" (demo style), a style URL, or \"none\" (standalone canvas).",
           "values": [
             {
               "name": "maplibre"
+            },
+            {
+              "name": "none"
+            },
+            {
+              "name": "liberty"
+            },
+            {
+              "name": "bright"
+            },
+            {
+              "name": "positron"
+            },
+            {
+              "name": "dark-matter"
+            },
+            {
+              "name": "voyager"
+            },
+            {
+              "name": "osm"
+            },
+            {
+              "name": "maptiler-streets"
+            },
+            {
+              "name": "maptiler-dataviz"
+            },
+            {
+              "name": "maptiler-satellite"
+            }
+          ]
+        },
+        {
+          "name": "basemap-key",
+          "description": "Provider API key for keyed basemap presets (maptiler-*) — publishable origin-restricted key; or call OmMap.configureBasemap once."
+        },
+        {
+          "name": "attribution",
+          "description": "Set \"false\" to opt out of the compact attribution control shown with basemaps.",
+          "values": [
+            {
+              "name": "false"
             }
           ]
         },
@@ -1358,6 +1401,9 @@
             },
             {
               "name": "draw-save"
+            },
+            {
+              "name": "set-basemap"
             }
           ]
         },
@@ -1405,6 +1451,9 @@
             },
             {
               "name": "draw"
+            },
+            {
+              "name": "basemap-switcher"
             }
           ]
         },
@@ -1483,6 +1532,10 @@
           "name": "autosave",
           "description": "Draw widget: localStorage key — mirrors the sketch and restores it on reload."
         },
+        {
+          "name": "options",
+          "description": "Basemap-switcher: space-separated preset names to offer (default: every keyless registered preset)."
+        },
         {
           "name": "title",
           "description": "Widget heading."
@@ -1613,6 +1666,9 @@
             },
             {
               "name": "draw-save"
+            },
+            {
+              "name": "set-basemap"
             }
           ]
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nika-js/onlymap",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "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": {
@@ -45,24 +45,42 @@
       "require": "./dist/onlymapjs.umd.cjs",
       "default": "./dist/onlymapjs.js"
     },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react.js",
+      "default": "./dist/react.js"
+    },
     "./onlymapjs.css": "./dist/onlymapjs.css",
     "./onlymapjs.html-data.json": "./onlymapjs.html-data.json",
     "./onlymap.code-snippets": "./.vscode/onlymap.code-snippets",
     "./package.json": "./package.json"
   },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
   "files": [
     ".vscode/onlymap.code-snippets",
     "bin/onlymapjs.mjs",
     "dist",
     "README.md",
     "LICENSE.md",
+    "docs",
     "llms.txt",
     "onlymapjs.html-data.json",
     "skills/onlymapjs"
   ],
   "scripts": {
     "dev": "vite",
-    "build": "npm run typecheck && vite build && npm run build:types",
+    "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",
     "test": "vitest run",
@@ -91,6 +109,8 @@
     "@types/d3-interpolate": "^3.0.4",
     "@types/d3-scale": "^4.0.9",
     "@types/estree": "^1.0.9",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
     "@types/ws": "^8.18.1",
     "acorn": "^8.17.0",
     "apache-arrow": "^21.1.0",
@@ -102,6 +122,8 @@
     "happy-dom": "^20.10.6",
     "maplibre-gl": "^5.24.0",
     "playwright": "^1.61.1",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
     "typescript": "^5.6.0",
     "vite": "^6.0.0",
     "vite-node": "^6.0.0",

package/skills/onlymapjs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: onlymapjs
-description: Build, edit, debug, or review OnlyMapJS declarative HTML maps and dashboards. 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, 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, or help with OnlyMapJS syntax, validation, widgets, data formats, testing, or publishing examples.
 ---
 
 # OnlyMapJS
@@ -19,11 +19,21 @@ Use OnlyMapJS as a declarative HTML map library. Write custom elements such as `
 ```html
 <script type="module">
   import "@nika-js/onlymap";
-  import "onlymapjs/onlymapjs.css";
+  import "@nika-js/onlymap/onlymapjs.css";
 </script>
 ```
 
-For no-build CDN examples, use a published module URL such as `https://esm.sh/@nika-js/onlymap@0.1.0`.
+For no-build CDN examples, use a published module URL such as `https://esm.sh/@nika-js/onlymap@0.2.0`.
+
+## React Projects
+
+In a React codebase, do NOT render `om-*` elements from JSX — React and the library would contend over the same DOM. Use the first-party adapter instead:
+
+```tsx
+import { OmMap, OmLayer, OmWidget, OmOverlay, useOmMap } from "@nika-js/onlymap/react";
+```
+
+The adapter inverts several HTML-manifest rules: props are camelCase deck.gl props, accessors are plain JS functions (`getFillColor={d => ...}` — no `$field` expression language, no `js` opt-in), and interactions are `onClick`/`onHover` handlers plus React state, not `<om-behavior>` or state-mutating actions. Load `references/react.md` before writing React map code.
 
 ## Required References
 
@@ -31,6 +41,7 @@ Load the smallest reference needed for the task:
 
 - `references/syntax.md` — element vocabulary, attributes, data formats, accessors, actions, widgets, overlays, drawing, 3D, built-in layer types.
 - `references/patterns.md` — copyable manifest patterns for common map requests.
+- `references/react.md` — the React adapter: components, the useOmMap hook, HTML-vs-React rule differences, testing.
 - `references/testing.md` — validation, snapshot, headless harness, and browser testing workflow.
 
 ## Non-Negotiable Syntax Rules
@@ -50,6 +61,7 @@ Load the smallest reference needed for the task:
 - Sparse rich HTML at one geographic location -> `<om-overlay>`.
 - 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`.
 - 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">`.

package/skills/onlymapjs/references/patterns.md

@@ -12,7 +12,7 @@ Use these patterns as starting points. Replace data URLs, layer ids, fields, cen
   <title>OnlyMapJS map</title>
   <script type="module">
     import "@nika-js/onlymap";
-    import "onlymapjs/onlymapjs.css";
+    import "@nika-js/onlymap/onlymapjs.css";
   </script>
   <style>
     html, body { margin: 0; height: 100%; }
@@ -135,7 +135,7 @@ Use `PopupLayer` instead of many `<om-overlay>` elements for labels/badges at sc
 ```html
 <script type="module">
   import { OmMap } from "@nika-js/onlymap";
-  import "onlymapjs/onlymapjs.css";
+  import "@nika-js/onlymap/onlymapjs.css";
 
   OmMap.registerSource("fleet", {
     decode: (m) => m.type === "position"

package/skills/onlymapjs/references/react.md

@@ -0,0 +1,68 @@
+# React adapter — `@nika-js/onlymap/react`
+
+Real components over the same engine as the HTML manifest. React never renders `om-*` elements — components feed a typed programmatic front-end, so there is no DOM contention with the library's reconciler. React ≥ 18 (`npm install @nika-js/onlymap react react-dom`).
+
+## Rules that INVERT the HTML-manifest rules
+
+- Props are **camelCase deck.gl props** (`getFillColor`, `radiusMinPixels`), not kebab-case attributes.
+- Accessors are **plain JS functions**: `getFillColor={d => d.mag > 6 ? [214,40,40] : [252,191,73]}`. Never use `$field` expressions or `scale()` strings here; never add a `js` attribute (there is none).
+- Interactions are **event handlers + state**, not `<om-behavior>`. Toggle a layer by rendering `visible={false}`; filter by changing `filterRange`. The state-mutating actions (`toggle-layer`, `show-overlay`, `fade`, story/draw actions) are not dispatched on this path — a console warning points back to props. Camera actions (`fly-to`, `zoom-to-feature`, `zoom-in`/`-out`), `pulse`, `populate`, and custom `OmMap.registerAction` handlers work via `emit`.
+- Keep inline `data` references **stable across renders** (`useMemo`/`useState`) — data reactivity diffs by reference. deck.gl ignores accessor function identity; pass `updateTriggers={{ getFillColor: theme }}` when an accessor's *output* changes.
+- Stories and the draw widget are HTML-manifest-only for now.
+
+## Complete example
+
+```tsx
+import { useState } from "react";
+import { OmMap, OmLayer, OmWidget, OmOverlay, useOmMap } from "@nika-js/onlymap/react";
+
+function QuakeMap() {
+  const [visible, setVisible] = useState(true);
+  return (
+    <OmMap center={[-119, 36]} zoom={5} basemap="maplibre" style={{ height: "100vh" }}>
+      <OmLayer id="quakes" type="ScatterplotLayer" data="/quakes.csv" label="Earthquakes"
+               visible={visible} pickable
+               getPosition={(d) => [d.longitude, d.latitude]}
+               getFillColor={(d) => (d.mag >= 6 ? [214, 40, 40] : [252, 191, 73])}
+               radiusMinPixels={3}
+               onClick={(sel) => console.log(sel.object)} />
+      <OmWidget position="top-left"><StatsPanel onToggle={() => setVisible(!visible)} /></OmWidget>
+      <OmOverlay anchorFrom="selection" layer="quakes">
+        {(sel) => sel && <div className="card">M{sel.object.mag} — {sel.object.place}</div>}
+      </OmOverlay>
+    </OmMap>
+  );
+}
+
+function StatsPanel({ onToggle }) {
+  const ctx = useOmMap(["viewport", "data:quakes"]); // watch tokens re-render the component
+  return (
+    <div className="panel">
+      {ctx.stats("quakes", "mag").count} quakes at z{ctx.viewport.zoom.toFixed(1)}
+      <button onClick={onToggle}>Toggle</button>
+      <button onClick={() => ctx.emit("fly-to", { center: [140, 38], zoom: 4, duration: 1200 })}>Japan</button>
+    </div>
+  );
+}
+```
+
+## Component surface
+
+- **`<OmMap>`** — `center`/`zoom`/`pitch`/`bearing` (initial; later changes move the camera, unchanged props never fight user panning), `basemap`, `headless`, `onReady`, `onViewStateChange`, `onRuntimeError`. Give it a size via `style`/`className`. `ref` exposes the imperative `MapController` handle: `flyTo`, `setView`, `emit`, `getLayers`, `getSelection`, `injectPick`, `ready` (promise), `project`.
+- **`<OmLayer>`** — `id` + `type` (any registered deck.gl layer type) + deck props. `data`: stable inline reference or URL string (full Data Layer: CSV/Arrow/Shapefile/KML formats, `ws(s)://` streams via `source`/`streamKey`/`flush`, `refresh` polling). `label`/`color` feed `ctx.layers`; `filterField`/`filterRange` = GPU filter; `onClick`/`onHover` receive the flattened picked object (`onHover(null)` = pointer left).
+- **`<OmWidget>`** — positioning shell: `position="top-left|top-right|bottom-left|bottom-right"` + arbitrary JSX. Widgets sharing a corner stack.
+- **`<OmOverlay>`** — geo-anchored HTML with managed projection/tracking/culling. `anchor={[lng, lat]}` or `anchorFrom="selection"` (+ `layer` to scope which picks move it); children may be `(selection) => JSX`; `anchorOffset` (default `bottom-center`); `interactive={false}` for hover-following tooltips.
+- **`useOmMap(watch?)`** — the same `ctx` contract HTML widget scripts get, typed: `layers`, `viewport`, `selection`, `emit`, `data()`, `dataInViewport()`, `stats()`. Watch tokens: `"viewport"`, `"selection"`, `"layers"`, `"data:<layerId>"`.
+
+## Testing (no browser, no GPU)
+
+`<OmMap headless>` runs real projection math under jsdom/happy-dom:
+
+```tsx
+const ref = createRef<OmMapHandle>();
+render(<OmMap ref={ref} headless><OmLayer id="pts" type="ScatterplotLayer" data={rows} getPosition={p} /></OmMap>);
+await ref.current!.ready;
+ref.current!.injectPick({ layerId: "pts", object: rows[0], index: 0, coordinate: [0, 0], pixel: [0, 0], type: "click" });
+```
+
+`injectPick` rides the same selection path as real GPU picks — `onClick`, `useOmMap(["selection"])`, and selection-anchored overlays all react. For browser e2e, expose the `ref` handle (e.g. on `window`) as the readiness/projection probe — a React page has no `<om-map>` element to await.

package/skills/onlymapjs/references/syntax.md

@@ -9,7 +9,7 @@ Vite/npm project:
 ```html
 <script type="module">
   import "@nika-js/onlymap";
-  import "onlymapjs/onlymapjs.css";
+  import "@nika-js/onlymap/onlymapjs.css";
 </script>
 ```
 
@@ -33,7 +33,8 @@ Common attributes:
 - `zoom="11"`
 - `pitch="55"`
 - `bearing="20"`
-- `basemap="maplibre"` or `basemap="none"` or a MapLibre style URL
+- `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
 - `headless width="800" height="600"` for test harness use
 
@@ -178,6 +179,7 @@ Built-ins:
 - `draw`
 - `vega-lite`
 - `player`
+- `basemap-switcher` — radio list of presets; `options="positron dark-matter osm"` (default: every keyless registered preset)
 
 Positions: `top-left`, `top-right`, `bottom-left`, `bottom-right`.
 
@@ -187,6 +189,7 @@ Examples:
 <om-widget type="legend" position="bottom-right" title="Layers" interactive></om-widget>
 <om-widget type="filter" layer="quakes" field="magnitude" position="top-left"></om-widget>
 <om-widget type="draw" target="sketch" modes="point line polygon" save="both"></om-widget>
+<om-widget type="basemap-switcher" options="positron dark-matter liberty osm" position="top-right"></om-widget>
 ```
 
 Custom widget:
@@ -254,6 +257,7 @@ Common built-in actions:
 - `highlight-feature`
 - `zoom-to-feature`
 - `filter-layer`
+- `set-basemap` — payload `{ basemap }`; writes the `<om-map basemap>` attribute
 - `zoom-in`, `zoom-out`
 - `fly-to`
 - story actions: `story-play`, `story-pause`, `story-seek`