@nika-js/onlymap 0.3.4 → 0.4.0

package/docs/external-stores.md

@@ -0,0 +1,135 @@
+# External stores — Redux, MobX, Zustand, Jotai
+
+OnlyMapJS exposes runtime state as a **framework-free store contract** on `MapController`: per watch-token `{subscribe, getSnapshot}` stores that anything can consume — React's `useSyncExternalStore` (the adapter's own hooks ride it internally), a MobX `autorun`, a Redux listener, a Zustand mirror. There are deliberately **no** `@nika-js/onlymap/redux`-style binding packages: every recipe below is ~20 lines against one contract, and each is covered by an integration test in the library's own suite, run against the real store libraries.
+
+## The contract
+
+```ts
+const viewport = controller.getStore("viewport");
+// { subscribe(cb): unsubscribe, getSnapshot(): Readonly<ViewportSnapshot> }
+
+viewport.getSnapshot();
+// { longitude, latitude, zoom, pitch, bearing,
+//   bounds: [[west, south], [east, north]],
+//   origin: "user" | "programmatic" }
+```
+
+Tokens and snapshot types:
+
+| Token | Snapshot | Fires on |
+|---|---|---|
+| `"viewport"` | `ViewportSnapshot` (above) | every camera change |
+| `"selection"` | `Selection \| null` | hover/click picks |
+| `"layers"` | `LayerMetaSnapshot[]` (same shape as `ctx.layers`) | layer add/remove, visibility, filter, legend meta |
+| `"data:<layerId>"` | `{ version, rows }` | that layer's data load / stream tick / poll |
+
+Three guarantees the recipes rely on:
+
+1. **Cached identity.** `getSnapshot()` returns the *same object* until that token's next event. Safe for `useSyncExternalStore` (a fresh object per call would render-loop) and for identity-based dirty checks in any store.
+2. **Plain data.** Snapshots contain no functions — Redux devtools, `redux-persist`, and structured cloning all work. Rich reads (`project`, `data()`, `stats()`) stay on `ctx` / the controller.
+3. **Version stamps, not rows.** `data:<id>` gives you `{version, rows}` — a change signal. Fetch actual rows with `ctx.data(id)` when the version moves; mirroring a 100k-row array into a store per stream tick is the classic performance anti-pattern.
+
+## Origin tagging & echo suppression
+
+Two-way camera binding creates a feedback loop: store → `flyTo` → map moves → map event → store. Two mechanisms break it:
+
+- **`origin`** — every viewport change is tagged `"user"` (canvas gesture: drag, wheel, keyboard, double-click zoom) or `"programmatic"` (camera APIs, actions, story steps, transition frames). Both the settled signals (`om-view-changed` on `<om-map>`, `onViewChange` on `MapController`) **and** the viewport snapshot's `origin` field report the **burst** origin: if any change since the last settle was a gesture, it's `"user"` — so a drag's inertia tail can't relabel the gesture, and the snapshot can never disagree with the settled callback about the same gesture.
+- **Idempotent setters** — writing an unchanged camera back to the map is a no-op frame, and the React adapter's camera props only call `setView` when values actually differ.
+
+Sync **map → store** on the settled signal with `origin === "user"`; drive **store → map** through the camera APIs. Neither direction can then re-trigger the other.
+
+## Redux Toolkit
+
+```ts
+import { createAction, createSlice, createListenerMiddleware, configureStore } from "@reduxjs/toolkit";
+
+const viewportSynced = createAction<{ longitude: number; latitude: number; zoom: number }>("map/viewportSynced");
+const flyToRequested = createAction<{ center: [number, number]; zoom?: number }>("map/flyToRequested");
+
+// map → redux: settled camera only (never 60fps dispatches), user-originated only.
+const controller = new MapController(el, {
+  onViewChange: (view, origin) => {
+    if (origin !== "user") return; // echo suppression: your own flyTo settles as "programmatic"
+    store.dispatch(viewportSynced({ longitude: view.longitude, latitude: view.latitude, zoom: view.zoom }));
+  },
+});
+
+// redux → map: intents flow through the camera API.
+listener.startListening({
+  actionCreator: flyToRequested,
+  effect: (action) => controller.flyTo(action.payload.center, action.payload.zoom),
+});
+```
+
+Store only the plain camera fields (Redux's serializability rule is why snapshots are plain data), and keep dispatches on the settled signal — Redux's own guidance warns against 60fps viewport dispatch.
+
+## Zustand
+
+A mirror store — Zustand's own `useSyncExternalStore` integration does the React half:
+
+```ts
+import { createStore } from "zustand/vanilla"; // or `create` from "zustand" in React
+
+const useMapState = createStore(() => ({
+  viewport: controller.getStore("viewport").getSnapshot(),
+  selection: null as Selection | null,
+}));
+controller.getStore("viewport").subscribe(() =>
+  useMapState.setState({ viewport: controller.getStore("viewport").getSnapshot() }));
+controller.getStore("selection").subscribe(() =>
+  useMapState.setState({ selection: controller.getStore("selection").getSnapshot() }));
+
+// any component: const zoom = useMapState(s => s.viewport.zoom)
+```
+
+The mirror is read-only, so there is no echo to suppress; write back via `controller.setView`/`flyTo` from your actions.
+
+## MobX (and mobx-keystone)
+
+An observable mirror plus a reaction for write-back — the mirror update never re-fires the reaction because the *intent* observable (`targetCenter`) is separate from the mirrored state:
+
+```ts
+class MapVM {
+  viewport = controller.getStore("viewport").getSnapshot();
+  targetCenter: [number, number] | null = null;
+  constructor() {
+    makeAutoObservable(this, {}, { autoBind: true });
+    controller.getStore("viewport").subscribe(() =>
+      runInAction(() => { this.viewport = controller.getStore("viewport").getSnapshot(); }));
+    reaction(() => this.targetCenter, (c) => c && controller.flyTo(c));
+  }
+}
+```
+
+mobx-keystone is the same bridge with a lifecycle-scoped subscription — return the unsubscribe from `onAttachedToRootStore` and keystone disposes it when the model detaches:
+
+```ts
+@model("app/MapState")
+class MapState extends Model({ viewport: prop<ViewportSnapshot>() }) {
+  onAttachedToRootStore() {
+    return controller.getStore("viewport").subscribe(() =>
+      this.setViewport(controller.getStore("viewport").getSnapshot()));
+  }
+  @modelAction setViewport(v: ViewportSnapshot) { this.viewport = v; }
+}
+```
+
+## Jotai
+
+```ts
+import { atom } from "jotai";
+
+const viewportAtom = atom(controller.getStore("viewport").getSnapshot());
+viewportAtom.onMount = (set) =>
+  controller.getStore("viewport").subscribe(() => set(controller.getStore("viewport").getSnapshot()));
+```
+
+Caveat, documented rather than solved: jotai deliberately avoids `useSyncExternalStore` (uSES updates are always sync-urgent, incompatible with time-slicing). Updates through `set` here are transition-friendly, which also means a jotai read can briefly trail the map during a transition — for camera state that is normally what you want.
+
+## The HTML front-end
+
+`getStore` lives on `MapController` — the programmatic/React lane — by design. The HTML manifest lane's subscription surface is DOM events and widget `watch` tokens: listen for `om-view-changed` (its `detail.origin` carries the same burst-origin signal) and read state from widget `ctx`. If you're embedding `<om-map>` and need full store bridging, drive the map through `MapController` instead — the two front-ends share one core.
+
+## React without a store
+
+You usually don't need any of the above — `useOmMap(["viewport", "selection"])` already rides `useSyncExternalStore` over these same stores, with tearing-safe reads and stable `ctx` identity between events. Reach for an external store when map state must live alongside app state (routing, persistence, devtools, cross-page continuity).

package/docs/react.md

@@ -88,7 +88,9 @@ Anchored HTML at a projected coordinate, culled off-screen/behind-globe, tracked
 
 ### `useOmMap(watch?)`
 
-Returns the typed `RuntimeContext`: `layers`, `viewport` (bounds/zoom/center/project), `selection`, `emit`, `data()`, `dataInViewport()`, `stats()`. The watch list re-renders the component when a token fires: `"viewport"`, `"selection"`, `"layers"`, `"data:<layerId>"`. No list = read-once (still gets fresh state on other re-renders).
+Returns the typed `RuntimeContext`: `layers`, `viewport` (bounds/zoom/center/project), `selection`, `emit`, `data()`, `dataInViewport()`, `stats()`. The watch list re-renders the component when a token fires: `"viewport"`, `"selection"`, `"layers"`, `"data:<layerId>"`. No list = read-once.
+
+Reads ride React's `useSyncExternalStore` over the controller's per-token stores, so they are concurrent-rendering-safe: two components watching the same token can never observe different values in one committed frame, and the returned `ctx` keeps a stable identity until a watched token actually fires (safe to use in dependency arrays). The same stores are public — `controller.getStore(token)` — for syncing map state into Redux, MobX, Zustand, or Jotai: see [external-stores.md](external-stores.md).
 
 ## Testing
 

package/llms.txt

@@ -15,6 +15,7 @@ OnlyMapJS is NOT raw deck.gl and NOT generic HTML/JSX. The rules below are the d
 - Always write explicit closing tags: `<om-layer ...></om-layer>`. NEVER self-close (`<om-layer ... />`) — HTML5 ignores the slash on custom elements and every following sibling silently becomes a child.
 - Attributes are kebab-case, not camelCase: `get-fill-color`, `radius-units`, `line-width-min-pixels`. Every hyphenated attribute maps to the camelCase deck.gl prop.
 - Accessors are expressions in attributes, not JS functions: `get-position="[$lon, $lat]"`, `get-radius="$population * 0.001"`. `$field` reads a datum field; the library resolves flat vs. GeoJSON shape for you — never write `d.properties.x`.
+- ScatterplotLayer points need an explicit size: `radius="6" radius-units="pixels"` (constant), `get-radius="..."` (data-driven), or `radius-min-pixels="..."` (floor). Deck's default is getRadius 1 METER — sub-pixel at city zooms, the layer renders nothing visible — and validation warns when no radius source is present.
 - A literal color inside a `get-*` accessor is a string IN the expression — quote it: `get-line-color="'#ffffff'"` or an RGBA array `get-line-color="[255,255,255,200]"`. Bare `get-line-color="#ffffff"` is an expression parse error (plain attributes like `color="#dc2626"` take bare hex, accessors do not).
 - Inline event handlers (`onclick="..."`) are rejected. Use `data-emit` attributes (`<span data-emit="hide-overlay" data-target="popup1">`) or `addEventListener` inside a `<script type="om/widget">` block where `ctx` is in scope.
 - `scale()` requires an explicit `domain=`: `get-fill-color="scale($depth, sequential, ['#ffffcc','#800026'], domain=[0,700])"`. A missing domain is a validation error.
@@ -23,7 +24,7 @@ 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; any scheme fetch supports, including desktop asset protocols like Tauri's, query strings fine), or `none` (standalone canvas). The attribute is LIVE — writing it switches the basemap in place (camera + layers survive); the `set-basemap {basemap}` action and `<om-widget type="basemap-switcher" options="positron dark-matter osm">` do the same. Register more via `OmMap.registerBasemap(name, { style })`. Required provider attribution renders automatically (`attribution="false"` opts out). `pitch`/`bearing` tilt the initial camera (use for 3D content). Terrain: `terrain="terrarium"` (keyless AWS DEM; also `maptiler-terrain` with a key, a raw `{z}/{x}/{y}` DEM URL + `terrain-decoder="terrarium|mapbox-rgb|<JSON>"`, or `off`) raises a 3D surface — geographic layers DRAPE onto it automatically (per-layer `terrain="drape|offset|off"` overrides; 3D-model layers sit ON it), `terrain-exaggeration` scales relief, `terrain-texture` drapes imagery; terrain REPLACES an active basemap while on (restored when off); `set-terrain` action, `terrain` watch token, `OmMap.registerTerrain(name, {...})` for more sources. Scene lighting for 3D content: `lighting="daylight|studio|flat|custom"` (absent = deck defaults) with `lighting-ambient`/`lighting-sun`/`lighting-sun-azimuth`/`lighting-sun-elevation`/`lighting-camera` overrides and `lighting-sun-date` (ISO/epoch — solar-position sun computed at the map center, wins over azimuth/elevation); attribute-backed (undoable, live-editable), story-steppable via the `set-lighting {lighting, sunAzimuth, ...}` action (`lighting="default"` removes the attribute set; a bare preset is a clean reset — stale overrides clear), native UI via `<om-widget type="lighting">` (preset radios + tuning sliders), widget watch token `lighting`. GeoJsonLayer extrudes polygons declaratively: `extruded get-elevation="$height"` (+ `wireframe`). `validate` attribute enables live validation + on-page error panel. Include a `map-id="<random UUID>"` on complete pages (identifies the map artifact for usage telemetry — not a visitor id; the page author deletes it to opt out); `telemetry="off"` disables usage telemetry + library-error reporting for the map (global: `OmMap.configureTelemetry({ disabled: true })`; schema: docs/telemetry.md). Free plan limits: 5 layers, 25k rows per layer — layers past a limit don't render and validation says why; a `license-key="om_live_…"` attribute (publishable, origin-restricted) or `OmMap.configureLicense(key)` lifts limits and removes the corner badge. When a user's map exceeds free limits, say so and point at the validation message rather than silently restructuring their data. Events on the element: `om-map-ready` (boot complete; `await mapEl.ready` is the promise twin), `om-validation-error`, `om-view-changed` (camera settled after a move, debounced; `detail = {longitude, latitude, zoom, pitch, bearing}` — the camera-persistence hook). `await mapEl.snapshot()` returns a canvas-only PNG dataURL of the scene (basemap + layers at device pixels; `{as:"blob"}` for files) — DOM widgets/overlays/attribution are NOT captured, so exports must render provider credits themselves.
+- `<om-map center="[lng, lat]" zoom="11" pitch="55" bearing="20" basemap="positron">` — the root. `basemap` accepts a free preset (`liberty`, `bright`, `positron`, `dark-matter`, `voyager`, `osm` — no keys; or `maptiler-streets`/`maptiler-dataviz`/`maptiler-satellite` with `basemap-key="…"` or `OmMap.configureBasemap({ maptilerKey })`), `maplibre` (bare demo style), a style URL (e.g. a MapTiler-customized style; any scheme fetch supports, including desktop asset protocols like Tauri's, query strings fine), or `none` (standalone canvas). The attribute is LIVE — writing it switches the basemap in place (camera + layers survive); the `set-basemap {basemap}` action and `<om-widget type="basemap-switcher" options="positron dark-matter osm">` do the same. Register more via `OmMap.registerBasemap(name, { style })`. Required provider attribution renders automatically (`attribution="false"` opts out). `pitch`/`bearing` tilt the initial camera (use for 3D content). Terrain: `terrain="terrarium"` (keyless AWS DEM; also `maptiler-terrain` with a key, a raw `{z}/{x}/{y}` DEM URL + `terrain-decoder="terrarium|mapbox-rgb|<JSON>"`, or `off`) raises a 3D surface — geographic layers DRAPE onto it automatically (per-layer `terrain="drape|offset|off"` overrides; 3D-model layers sit ON it), `terrain-exaggeration` scales relief, `terrain-texture` drapes imagery; terrain REPLACES an active basemap while on (restored when off); `set-terrain` action, `terrain` watch token, `OmMap.registerTerrain(name, {...})` for more sources. Scene lighting for 3D content: `lighting="daylight|studio|flat|custom"` (absent = deck defaults) with `lighting-ambient`/`lighting-sun`/`lighting-sun-azimuth`/`lighting-sun-elevation`/`lighting-camera` overrides and `lighting-sun-date` (ISO/epoch — solar-position sun computed at the map center, wins over azimuth/elevation); attribute-backed (undoable, live-editable), story-steppable via the `set-lighting {lighting, sunAzimuth, ...}` action (`lighting="default"` removes the attribute set; a bare preset is a clean reset — stale overrides clear), native UI via `<om-widget type="lighting">` (preset radios + tuning sliders), widget watch token `lighting`. GeoJsonLayer extrudes polygons declaratively: `extruded get-elevation="$height"` (+ `wireframe`). `validate` attribute enables live validation + on-page error panel. Include a `map-id="<random UUID>"` on complete pages (identifies the map artifact for usage telemetry — not a visitor id; the page author deletes it to opt out); `telemetry="off"` disables usage telemetry + library-error reporting for the map (global: `OmMap.configureTelemetry({ disabled: true })`; schema: docs/telemetry.md). Free plan limits: 5 layers, 25k rows per layer — layers past a limit don't render and validation says why; a `license-key="om_live_…"` attribute (publishable, origin-restricted) or `OmMap.configureLicense(key)` lifts limits and removes the corner badge. When a user's map exceeds free limits, say so and point at the validation message rather than silently restructuring their data. Events on the element: `om-map-ready` (boot complete; `await mapEl.ready` is the promise twin), `om-validation-error`, `om-view-changed` (camera settled after a move, debounced; `detail = {longitude, latitude, zoom, pitch, bearing, origin}` where `origin` is `"user"` for gesture bursts vs `"programmatic"` for API/story moves — the camera-persistence hook, and the echo-suppression signal when syncing camera state to an app store). `await mapEl.snapshot()` returns a canvas-only PNG dataURL of the scene (basemap + layers at device pixels; `{as:"blob"}` for files) — DOM widgets/overlays/attribution are NOT captured, so exports must render provider credits themselves.
 - `<om-layer id="..." type="ScatterplotLayer" data="./points.json">` — any deck.gl layer class by `type` (all 33 bundled, plus the native `COGLayer` raster type), plus `PopupLayer` (WebGL badges/labels at scale: `layout="badge|pin-label|card"`, `min-zoom`/`max-zoom`). Every type's full attribute list ships in the package's `onlymapjs.html-data.json` — consult it instead of guessing attribute names or reading the minified dist. TextLayer's default font atlas covers ASCII only: set `character-set` when label text carries other glyphs (`—`, `·`, accents) or deck warns and renders them blank. External layer classes register via `OmMap.registerLayer({type, deckClass, props})` — build them on `@nika-js/onlymap/deck` (the bundled `CompositeLayer`/`TileLayer`/… re-exports), never a separately-installed deck.gl (different class hierarchy, breaks in the renderer); function-valued props ride the subclass's `static defaultProps`; register at module top level BEFORE the manifest mounts (see docs/custom-layers.md). Data: `data` URL (JSON, GeoJSON, CSV/TSV `.csv` — parsed to typed columns — Shapefile `.shp` (+`.dbf` attributes) and KML `.kml` as GeoJSON features, or Arrow IPC `.arrow`/`.feather` — large point datasets stay columnar, GeoArrow line/polygon geometry becomes GeoJSON features, zstd-compressed IPC is handled; other formats plug in via `OmMap.registerFormat({match, parse})`; data URLs accept any scheme the runtime's fetch supports — desktop webviews (Tauri, Electron) pass asset-protocol URLs straight in), inline `<script type="application/json">` (row arrays or column-oriented `{"columns": {"lon": [...], "lat": [...]}}`; must be a DIRECT child of the `<om-layer>`, and when present it wins — omit the `data` attribute), 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. GeoTIFF/COG rasters use `type="COGLayer"` with `src="./dem.tif"` (NOT `data` — rasters stream tiles by Range request, they are not parsed rows): `min`/`max` set the rescale window (default 0–255; ALWAYS set them for float/16-bit data like DEMs), `colormap` picks a bundled ramp for single-band sources (gray, viridis, plasma, inferno, magma, cividis, rdylgn, rdbu, spectral, terrain, jet, turbo), `nodata` overrides the source sentinel (renders transparent); plain 8-bit RGB COGs need no styling attributes; restretch/recolor are GPU uniforms (no refetch) and the legend ramp derives from colormap+min/max automatically. Sources must be Cloud-Optimized (`gdal_translate -of COG` otherwise).
 - `<om-widget type="legend|layer-switcher|basemap-switcher|lighting|zoom-controls|undo-redo|scale-bar|attribution|filter|vega-lite" position="bottom-right">` — static UI panels. Built-ins are themeable from page CSS via custom properties (they inherit through the shadow root): `om-map { --om-widget-bg: #111827; --om-widget-fg: #f9fafb; }` — full set: `--om-widget-bg/-fg/-muted/-border/-hover-bg/-accent`; scope to a single widget with an `om-widget[type=legend]` selector instead. 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.
@@ -40,7 +41,7 @@ UI panel (legend, chart, stats) → `<om-widget>`. Rich HTML at one map location
 
 ## 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).
+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 (tearing-safe: it rides `useSyncExternalStore` over the controller's per-token stores). To sync map state into Redux/MobX/Zustand/Jotai, use `controller.getStore(token)` — a framework-free `{subscribe, getSnapshot}` per watch token with cached plain-data snapshots and `origin: "user"|"programmatic"` tagging for echo-free two-way camera binding; ~20-line recipes: [docs/external-stores.md](docs/external-stores.md). Guide: [docs/react.md](docs/react.md).
 
 ## Docs
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nika-js/onlymap",
-  "version": "0.3.4",
-  "description": "Declarative deck.gl maps for HTML and React \u2014 interactive WebGL mapping with GeoJSON/CSV/Arrow data, MapLibre basemaps, widgets, popups, and live streams from a custom-element manifest or typed React components. TypeScript, no build step.",
+  "version": "0.4.0",
+  "description": "Declarative deck.gl maps for HTML and React — interactive WebGL mapping with GeoJSON/CSV/Arrow data, MapLibre basemaps, widgets, popups, and live streams from a custom-element manifest or typed React components. TypeScript, no build step.",
   "license": "SEE LICENSE IN LICENSE.md",
   "publishConfig": {
     "access": "public"
@@ -120,7 +120,7 @@
     "dev:telemetry": "wrangler dev --config cloud/workers/telemetry/wrangler.toml",
     "gen:licenses": "node dev/gen-third-party-licenses.mjs"
   },
-  "comment:deps": "This library ships a fully self-contained bundle in dist/ (verified: zero external bare imports), so it has NO runtime dependencies \u2014 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.",
+  "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": {
     "@deck.gl/aggregation-layers": "9.3.5",
     "@deck.gl/core": "9.3.5",
@@ -134,6 +134,7 @@
     "@loaders.gl/kml": "^4.4.3",
     "@loaders.gl/shapefile": "^4.4.3",
     "@playwright/test": "^1.61.1",
+    "@reduxjs/toolkit": "^2.12.0",
     "@types/d3-array": "^3.2.2",
     "@types/d3-color": "^3.1.3",
     "@types/d3-interpolate": "^3.0.4",
@@ -150,7 +151,9 @@
     "d3-scale": "^4.0.2",
     "fzstd": "^0.1.1",
     "happy-dom": "^20.10.6",
+    "jotai": "^2.20.2",
     "maplibre-gl": "^5.24.0",
+    "mobx": "^6.16.1",
     "playwright": "^1.61.1",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
@@ -159,7 +162,8 @@
     "vite-node": "^6.0.0",
     "vitest": "^4.1.9",
     "wrangler": "^4.110.0",
-    "ws": "^8.21.0"
+    "ws": "^8.21.0",
+    "zustand": "^5.0.14"
   },
-  "comment:deck-pin": "deck.gl/luma.gl devDeps are EXACT pins: they get BUNDLED into dist, and both libraries hard-throw on duplicate-version detection \u2014 consumers that also ship their own deck.gl (nika-agent) must match these versions exactly, so bumps are breaking-coordination events, never side effects of a reinstall."
-}
+  "comment:deck-pin": "deck.gl/luma.gl devDeps are EXACT pins: they get BUNDLED into dist, and both libraries hard-throw on duplicate-version detection — consumers that also ship their own deck.gl (nika-agent) must match these versions exactly, so bumps are breaking-coordination events, never side effects of a reinstall."
+}

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, 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.
+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), syncing OnlyMapJS map/camera state into an app state store (Redux, MobX, Zustand, Jotai — the getStore contract), 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 pages, use the single-file standalone bundle from a raw-file CDN — `https://unpkg.com/@nika-js/onlymap@0.3.4` (the bare package URL serves `dist/onlymap.standalone.js`) — plus `<link rel="stylesheet" href="https://unpkg.com/@nika-js/onlymap@0.3.4/dist/onlymapjs.css">`. Never a rebundling CDN (esm.sh, skypack): re-bundling duplicates the deck.gl/luma.gl runtime and every layer fails shader compilation.
+For no-build CDN pages, use the single-file standalone bundle from a raw-file CDN — `https://unpkg.com/@nika-js/onlymap@0.4.0` (the bare package URL serves `dist/onlymap.standalone.js`) — plus `<link rel="stylesheet" href="https://unpkg.com/@nika-js/onlymap@0.4.0/dist/onlymapjs.css">`. Never a rebundling CDN (esm.sh, skypack): re-bundling duplicates the deck.gl/luma.gl runtime and every layer fails shader compilation.
 
 ## React Projects
 
@@ -51,6 +51,7 @@ Load the smallest reference needed for the task:
 - Attribute names are kebab-case: `get-fill-color`, `radius-units`, `line-width-min-pixels`.
 - Accessor values are expressions: `get-position="[$lon, $lat]"`.
 - `scale()` always needs an explicit `domain=`.
+- ScatterplotLayer points need an explicit size — `radius="6" radius-units="pixels"`, `get-radius="..."`, or `radius-min-pixels="..."`: deck's default is 1 METER, sub-pixel at city zooms, and validation warns on layers with no radius source.
 - Prefer canonical color expressions — a `sequential`/`diverging`/`threshold` `scale()` or an equality ternary chain — over hand-rolled arithmetic: the legend widget parses these shapes and renders a matching gradient ramp / class ranges / category palette automatically.
 - Inline handlers such as `onclick` are wrong. Use `data-emit`, `<om-behavior>`, or widget scripts.
 - Full JavaScript accessor blocks require the `js` attribute on `<om-layer>`.

package/skills/onlymapjs/references/react.md

@@ -52,7 +52,8 @@ function StatsPanel({ onToggle }) {
 - **`<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>"`.
+- **`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>"`. Rides `useSyncExternalStore` (tearing-safe; `ctx` identity stable until a watched token fires).
+- **`controller.getStore(token)`** — framework-free `{subscribe, getSnapshot}` per watch token (cached plain-data snapshots; viewport snapshots carry `origin: "user"|"programmatic"` for echo-free two-way binding). Use it to sync map state into Redux/MobX/Zustand/Jotai — recipes in docs/external-stores.md; never mirror row arrays into a store (use the `data:<id>` version stamp + `ctx.data()`).
 
 ## Testing (no browser, no GPU)
 

package/skills/onlymapjs/references/syntax.md

@@ -16,8 +16,8 @@ Vite/npm project:
 Static CDN page (raw-file CDNs only — unpkg/jsDelivr; never esm.sh or another rebundling CDN, which duplicates the WebGL runtime and breaks layer shaders):
 
 ```html
-<link rel="stylesheet" href="https://unpkg.com/@nika-js/onlymap@0.3.4/dist/onlymapjs.css">
-<script type="module" src="https://unpkg.com/@nika-js/onlymap@0.3.4"></script>
+<link rel="stylesheet" href="https://unpkg.com/@nika-js/onlymap@0.3.5/dist/onlymapjs.css">
+<script type="module" src="https://unpkg.com/@nika-js/onlymap@0.3.5"></script>
 ```
 
 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).