@nika-js/onlymap 0.3.4 → 0.4.0

package/.vscode/onlymap.code-snippets

@@ -28,6 +28,7 @@
       "                data=\"${4:../data/bikes.json}\"",
       "                label=\"${5:Points}\" color=\"${6:#e63946}\"",
       "                get-position=\"[\\$lon, \\$lat]\"",
+      "                radius=\"${7:6}\" radius-units=\"pixels\"",
       "                pickable></om-layer>",
       "",
       "    <!-- Rich HTML popup — follows the last click via anchor-from=\"selection\" -->",
@@ -110,6 +111,7 @@
       "            data=\"${2:../data/bikes.json}\"",
       "            label=\"${3:Points}\" color=\"${4:#e63946}\"",
       "            get-position=\"[\\$lon, \\$lat]\"",
+      "            radius=\"${5:6}\" radius-units=\"pixels\"",
       "            pickable></om-layer>$0"
     ]
   },

package/README.md

@@ -69,7 +69,7 @@ Or with no build step at all, straight from a CDN:
 
 The bare package URL serves `dist/onlymap.standalone.js`, a single-file bundle built for exactly this (jsDelivr too). Use a CDN that serves the package's raw files — **not** a rebundling CDN like esm.sh, which re-splits the bundle into duplicate copies of the deck.gl/luma.gl runtime and breaks every layer's shader compilation.
 
-Then `npx @nika-js/onlymap init` wires up VS Code IntelliSense and `!`-prefixed manifest snippets for your project. The library ships with 451 unit/behavioral tests and 27 Playwright GPU tests.
+Then `npx @nika-js/onlymap init` wires up VS Code IntelliSense and `!`-prefixed manifest snippets for your project. The library ships with 503 unit/behavioral tests and 30 Playwright GPU tests.
 
 The [examples](https://github.com/NikaGeospatial/onlymapjs/tree/main/examples) are the best tour: widgets, behaviors & overlays, basemaps, columnar/Arrow data, manual drawing, 3D models, scene lighting (with the native lighting widget), DEM terrain, a live WebSocket ship feed, and a polled driver fleet.
 
@@ -223,8 +223,9 @@ Plus `OmMap.snapshotIR(html)` to lock down what a manifest *means* in a snapshot
 
 - **`OmMap.*`** — `validate`, `snapshotIR`, `registerLayer`, `registerWidget`, `registerAction`, `registerSource`, `registerFormat`, `registerBasemap`, `configureBasemap`, `configureData`, `configureTelemetry`, `configureLicense`, `getLayerSchema`
 - **`@nika-js/onlymap/deck`** — the bundled deck.gl classes (`CompositeLayer`, `TileLayer`, …) for building custom layer types: shims must extend the same class hierarchy the core renders with, not a second installed deck.gl copy. Recipe: [docs/custom-layers.md](docs/custom-layers.md)
-- **On a `<om-map>` element** — `ready` (promise), `flyTo(coords, zoom?)`, `setLayerVisible(id, bool)`, `getLayers()`, `emit(action, payload)`, `snapshot(opts?)` (canvas-only PNG of basemap + layers at device pixels — DOM widgets/overlays and provider attribution are NOT captured, so exports must render credits themselves; `{as: "blob"}` for files, default dataURL); the `om-view-changed` event fires once the camera settles (debounced; `detail` = `{longitude, latitude, zoom, pitch, bearing}`) — the camera-persistence hook; `document.querySelector("om-map")` is fully typed
-- **`MapController`** — the framework-grade programmatic front-end (typed `LayerDescriptor`s → the same reconcile core, no DOM manifest): `setLayers`, `watch`, `emit`, camera methods, `injectPick`, `ready`, `snapshot`, an `onViewChange` option (the `om-view-changed` twin). The React adapter rides it; usable directly from vanilla TS or other frameworks
+- **On a `<om-map>` element** — `ready` (promise), `flyTo(coords, zoom?)`, `setLayerVisible(id, bool)`, `getLayers()`, `emit(action, payload)`, `snapshot(opts?)` (canvas-only PNG of basemap + layers at device pixels — DOM widgets/overlays and provider attribution are NOT captured, so exports must render credits themselves; `{as: "blob"}` for files, default dataURL); the `om-view-changed` event fires once the camera settles (debounced; `detail` = `{longitude, latitude, zoom, pitch, bearing, origin}`, where `origin` is `"user"` for gesture-driven bursts vs `"programmatic"` for API/story moves — the echo-suppression signal for state sync) — the camera-persistence hook; `document.querySelector("om-map")` is fully typed
+- **`MapController`** — the framework-grade programmatic front-end (typed `LayerDescriptor`s → the same reconcile core, no DOM manifest): `setLayers`, `watch`, `emit`, camera methods, `injectPick`, `ready`, `snapshot`, an `onViewChange(view, origin)` option (the `om-view-changed` twin). The React adapter rides it; usable directly from vanilla TS or other frameworks
+- **`getStore(token)`** — the external-store contract: per-token `{subscribe, getSnapshot}` stores (`viewport`/`selection`/`layers`/`data:<id>`) with cached immutable plain-data snapshots and `origin` tagging — directly consumable by `useSyncExternalStore` (the React adapter's own hooks ride it), MobX autoruns, Redux listeners, Zustand mirrors. ~20-line integration-tested recipes for Redux Toolkit, MobX/mobx-keystone, Zustand, and Jotai: [docs/external-stores.md](docs/external-stores.md)
 - **Testing** — `mountForTest`, and imports are SSR-safe (importing in Node/jsdom never touches browser globals)
 
 ## Free tier & licensing

package/dist/{LercDecode.es-D6eXA5jP.js → LercDecode.es-CWLcQT4F.js}

@@ -19,7 +19,7 @@ async function v(N = {}) {
   if (n) {
     const { createRequire: I } = await import(
       /*webpackIgnore:true*/
-      "./lerc-vBCRLD5s.js"
+      "./lerc-CSc9BX_F.js"
     ).then((g) => g._);
     var O = I(import.meta.url);
   }

package/dist/{basemap-BRh_zvzt.js → basemap-CZupn0P2.js}

@@ -1,4 +1,4 @@
-import { C as ny, L as sy, M as oy, m as ay, c as ka, z as oc, a as Sd, G as sm, V as ly, W as cy, b as uy, g as hy, d as Vu, f as Ed, e as dy, l as py, u as fy, D as Qf, h as my } from "./index-BR1HjJoE.js";
+import { C as ny, L as sy, M as oy, m as ay, c as ka, z as oc, a as Sd, G as sm, V as ly, W as cy, b as uy, g as hy, d as Vu, f as Ed, e as dy, l as py, u as fy, D as Qf, h as my } from "./index-BoxZ3Mec.js";
 const Cd = Math.PI / 180, gy = 180 / Math.PI;
 function em(Pe, Q = 0) {
   const ge = Math.min(180, Pe) * Cd;
@@ -25177,8 +25177,14 @@ class Ry {
     this.initialized ? Q() : this.loadCallbacks.push(Q);
   }
   /** Fires continuously during pan/zoom/rotate — MapLibre's own camera-change event, standing in for deck's onViewStateChange (which doesn't apply — deck isn't driving the camera). */
+  /**
+   * Viewport-change stream with origin tagging (spec: "External-Store
+   * Contract") — MapLibre attaches `originalEvent` (the DOM pointer/wheel
+   * event) to gesture-driven move events; our own easeTo/jumpTo/fitBounds
+   * fire without one. The ecosystem's standard user-vs-programmatic signal.
+   */
   onMove(Q) {
-    this.map.on("move", Q);
+    this.map.on("move", (ge) => Q(ge.originalEvent ? "user" : "programmatic"));
   }
   setLayers(Q) {
     this.overlay.setProps({ layers: Q });

package/dist/basemap.d.ts

@@ -1,6 +1,7 @@
 import "maplibre-gl/dist/maplibre-gl.css";
 import type { DeckProps, Viewport } from "@deck.gl/core";
 import type { ResolvedBasemap } from "./basemap-registry";
+import type { ViewOrigin } from "./external-store";
 export interface ViewportLike {
     project(xyz: number[]): number[];
     getBounds(): [number, number, number, number];
@@ -65,7 +66,13 @@ export declare class MapLibreBasemapAdapter {
     private markInitialized;
     onLoad(cb: () => void): void;
     /** Fires continuously during pan/zoom/rotate — MapLibre's own camera-change event, standing in for deck's onViewStateChange (which doesn't apply — deck isn't driving the camera). */
-    onMove(cb: () => void): void;
+    /**
+     * Viewport-change stream with origin tagging (spec: "External-Store
+     * Contract") — MapLibre attaches `originalEvent` (the DOM pointer/wheel
+     * event) to gesture-driven move events; our own easeTo/jumpTo/fitBounds
+     * fire without one. The ecosystem's standard user-vs-programmatic signal.
+     */
+    onMove(cb: (origin: ViewOrigin) => void): void;
     setLayers(layers: DeckProps["layers"]): void;
     /**
      * Scene lighting (spec: "Scene Lighting") — MapboxOverlay accepts full

package/dist/ctx.d.ts

@@ -57,5 +57,9 @@ export interface BuildCtxDeps {
         canRedo: boolean;
     };
 }
+/** `ctx.viewport.bounds` / the `viewport` external-store snapshot — one bounds derivation (incl. the world-extent fallback) for both (spec: "External-Store Contract"). */
+export declare function viewportBounds(viewport: ReturnType<RuntimeCore["getViewport"]>): [[number, number], [number, number]];
+/** `ctx.layers` / the `layers` external store — one builder for both (spec: "External-Store Contract"). */
+export declare function buildLayerMetas(layerIRs: ReadonlyMap<string, LayerIR>): LayerMetaSnapshot[];
 /** Built fresh on every widget-render invocation — never mutated, never reused. */
 export declare function buildCtx({ layerIRs, core, mapEl, selection, history }: BuildCtxDeps): RuntimeContext;

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

@@ -47,14 +47,12 @@ export declare class OmMapElement extends HTMLElementBase {
     private readyFired;
     private resolveReady;
     readonly ready: Promise<void>;
-    private viewChangedTimer;
+    private readonly viewSettle;
     private firstReconcileDone;
     private rendererLoadPending;
     private loadDispatched;
     connectedCallback(): void;
     disconnectedCallback(): void;
-    /** Trailing-debounced `om-view-changed` dispatch — see the field's doc comment. */
-    private scheduleViewChangedEvent;
     registerWidgetInternal(el: Element, watch: string[], notify: (ctx: RuntimeContext) => void): void;
     unregisterWidgetInternal(el: Element): void;
     registerOverlayInternal(overlay: OverlayHost): void;
@@ -192,6 +190,8 @@ declare global {
             zoom: number;
             pitch: number;
             bearing: number;
+            /** "user" if any change in the settled burst came from a canvas gesture; "programmatic" for pure API/action/story moves. */
+            origin: "user" | "programmatic";
         }>;
     }
 }

package/dist/external-store.d.ts

@@ -0,0 +1,95 @@
+/**
+ * External-store contract (spec: "External-Store Contract — `getStore` &
+ * `useSyncExternalStore`") — the framework-free `{subscribe, getSnapshot}`
+ * surface `MapController.getStore(token)` hands to React's
+ * `useSyncExternalStore`, MobX autoruns, Redux listeners, Zustand mirrors,
+ * and any future framework adapter. One contract, N consumers. Also home to
+ * the shared settle/burst-origin tracker both front-ends' "camera settled"
+ * signals ride — one settle contract, two front-ends, one implementation.
+ *
+ * The load-bearing rule is CACHED IDENTITY: `getSnapshot()` returns the
+ * SAME reference until that token's event fires (a fresh object per call
+ * makes `useSyncExternalStore` loop forever — zustand v5's headline
+ * breaking change was exactly this fix). Invalidation only marks dirty;
+ * the next read rebuilds — a 60fps camera stream with no subscribers
+ * builds nothing.
+ *
+ * Snapshots are PLAIN SERIALIZABLE DATA — no closures — so Redux devtools
+ * and persistence middleware never choke on them. Rich reads (`project`,
+ * `data()`, `stats()`) stay on `ctx`; `data:<id>` exposes a VERSION STAMP,
+ * not the rows (mirroring a 100k-row array into a store per tick is the
+ * anti-pattern the Redux performance guidance warns about).
+ */
+/**
+ * Who moved the camera: a pointer/wheel gesture on the canvas ("user") or
+ * a camera API / action / transition frame ("programmatic"). The echo-loop
+ * half of two-way store binding — a bridge writes back only user-originated
+ * changes; the map's idempotent setters are the other half.
+ */
+export type ViewOrigin = "user" | "programmatic";
+/** The per-token store — directly consumable by `useSyncExternalStore(store.subscribe, store.getSnapshot)`. */
+export interface TokenStore<T = unknown> {
+    /** `cb` fires after this token's state changed (read the new snapshot inside it). Returns the unsubscribe function. */
+    subscribe(cb: () => void): () => void;
+    /** Cached immutable snapshot — the SAME reference until the next change event for this token. */
+    getSnapshot(): T;
+}
+/** `viewport` store snapshot — CameraState plus bounds and the origin of the current settle burst. */
+export interface ViewportSnapshot {
+    longitude: number;
+    latitude: number;
+    zoom: number;
+    pitch: number;
+    bearing: number;
+    /** [[west, south], [east, north]] — same shape as `ctx.viewport.bounds`. */
+    bounds: [[number, number], [number, number]];
+    /**
+     * Burst-latched origin: "user" if any change since the last settle was a
+     * gesture — so a drag's inertia tail (MapLibre inertial moves carry no
+     * `originalEvent`) can't relabel the gesture mid-burst. Matches what the
+     * settled signals (`om-view-changed`, `onViewChange`) report.
+     */
+    origin: ViewOrigin;
+}
+/** `data:<layerId>` store snapshot — a version stamp, not the rows (fetch rows via `ctx.data()`). */
+export interface DataVersionSnapshot {
+    /** Bumps on every data change for the layer (load, stream tick, poll refresh). 0 = never loaded / unknown layer. */
+    version: number;
+    /** Current row count (0 for unknown layers). */
+    rows: number;
+}
+/**
+ * The store-token roster — ONE source of truth shared by
+ * `MapController.getStore` (throws otherwise) and the React adapter's
+ * warn-skip, so the two can never disagree about which tokens are stores.
+ */
+export declare function isStoreToken(token: string): boolean;
+/** The per-token store table — memoized store objects (calling `get` twice for one token returns the identical store). */
+export declare class TokenStoreRegistry {
+    private readonly entries;
+    /** Memoized per token — `build` is captured on first call and reused. */
+    get<T>(token: string, build: () => T): TokenStore<T>;
+    /** Marks the token dirty and notifies its subscribers. Unknown/never-requested tokens no-op (nothing to invalidate). */
+    invalidate(token: string): void;
+    /** Drop every entry and subscriber — controller teardown: a consumer that never unsubscribed must not pin the controller in memory. */
+    clear(): void;
+}
+/** Trailing debounce for the settled-camera signals — long enough to coalesce a pan/flight's per-frame churn, short enough that camera persistence feels immediate. */
+export declare const VIEW_SETTLE_DEBOUNCE_MS = 150;
+/**
+ * The settle/burst tracker behind `om-view-changed` and `onViewChange` —
+ * shared by both front-ends so the debounce window and the burst-origin
+ * rule ("user" if ANY change since the last settle was a gesture; an
+ * inertia tail can't relabel the gesture) can never drift apart.
+ */
+export declare class ViewSettleTracker {
+    private readonly onSettle;
+    private timer;
+    private burstHadUser;
+    constructor(onSettle: (origin: ViewOrigin) => void);
+    /** Record one viewport change and (re)arm the trailing settle timer. */
+    bump(origin: ViewOrigin): void;
+    /** Burst-latched origin for snapshots taken mid-burst: the gesture wins over a trailing programmatic frame. */
+    latchedOrigin(lastFrameOrigin: ViewOrigin): ViewOrigin;
+    cancel(): void;
+}