@nika-js/onlymap 0.3.4 → 0.4.0

package/dist/onlymapjs.js

@@ -1,4 +1,4 @@
-import { ay as e, az as r, aA as o, aB as t, aq as i, aC as n, aD as b, aE as l, aF as c, aG as g, aH as m, aI as p, aJ as L, aK as y, ap as T, aL as S, ax as u, W as d, aM as E, aN as M, aO as A, aP as I, aQ as f, aR as x, aS as C, aT as h, aU as B, aV as D, aW as R, aX as w, aY as v, aZ as F, a_ as G, a$ as N, b0 as O, b1 as W, b2 as _, b3 as z, b4 as H, b5 as J, b6 as k, b7 as P, b8 as V, b9 as Y, ba as j, bb as q, bc as K, bd as Q, be as U, bf as X, bg as Z, bh as $, bi as aa, bj as sa, bk as ea } from "./index-BR1HjJoE.js";
+import { ay as e, az as r, aA as o, aB as t, aq as i, aC as n, aD as b, aE as l, aF as c, aG as g, aH as m, aI as p, aJ as L, aK as T, ap as y, aL as S, ax as u, W as d, aM as E, aN as M, aO as A, aP as I, aQ as f, aR as x, aS as C, aT as h, aU as B, aV as D, aW as R, aX as w, aY as v, aZ as F, a_ as G, a$ as N, b0 as O, b1 as W, b2 as _, b3 as k, b4 as z, b5 as H, b6 as J, b7 as P, b8 as V, b9 as Y, ba as j, bb as q, bc as K, bd as Q, be as U, bf as X, bg as Z, bh as $, bi as aa, bj as sa, bk as ea, bl as ra } from "./index-BoxZ3Mec.js";
 export {
   e as AccessorCache,
   r as BitmapLayer,
@@ -13,8 +13,8 @@ export {
   m as MapController,
   p as OmMap,
   L as ScatterplotLayer,
-  y as ScenegraphLayer,
-  T as SimpleMeshLayer,
+  T as ScenegraphLayer,
+  y as SimpleMeshLayer,
   S as Tile3DLayer,
   u as TileLayer,
   d as WebMercatorViewport,
@@ -36,23 +36,24 @@ export {
   N as getTerrain,
   O as isBrowser,
   W as isColumnar,
-  _ as loadRasterModule,
+  _ as isStoreToken,
+  k as loadRasterModule,
   z as mountForTest,
   H as normalizeData,
   J as parseDurationMs,
-  k as parseTerrainAttrs,
-  P as registerAction,
-  V as registerBasemap,
-  Y as registerFormat,
-  j as registerLayer,
-  q as registerSource,
-  K as registerTerrain,
-  Q as registerWidget,
-  U as resolveLighting,
-  X as rowAt,
-  Z as sandboxHtml,
-  $ as snapshotIR,
-  aa as solarAzElDegrees,
-  sa as validateManifest,
-  ea as validateManifestString
+  P as parseTerrainAttrs,
+  V as registerAction,
+  Y as registerBasemap,
+  j as registerFormat,
+  q as registerLayer,
+  K as registerSource,
+  Q as registerTerrain,
+  U as registerWidget,
+  X as resolveLighting,
+  Z as rowAt,
+  $ as sandboxHtml,
+  aa as snapshotIR,
+  sa as solarAzElDegrees,
+  ea as validateManifest,
+  ra as validateManifestString
 };

package/dist/programmatic.d.ts

@@ -18,8 +18,10 @@ import { type CameraOptions } from "./runtime-core";
 import { type LightingIR, type LightingOptions } from "./scene-lighting";
 import type { TerrainIR } from "./terrain";
 import { type SnapshotOptions } from "./snapshot";
+import { type TokenStore, type ViewOrigin, type ViewportSnapshot, type DataVersionSnapshot } from "./external-store";
 import type { LayerIR } from "./ir";
 import { type RuntimeContext } from "./ctx";
+import type { LayerMetaSnapshot } from "./ctx";
 import type { Selection } from "./selection";
 import type { ValidationEntry } from "./validation";
 import type { MapViewport } from "./basemap";
@@ -96,9 +98,12 @@ export interface MapControllerOptions {
     /**
      * Camera settled (trailing-debounced, the `om-view-changed` twin) — for
      * camera persistence. Per-frame viewport churn goes to `watch(["viewport"])`;
-     * this fires once with the destination.
+     * this fires once with the destination. `origin` is "user" when ANY change
+     * in the settled burst came from a canvas gesture (a drag's inertia tail
+     * alone must not relabel the gesture), "programmatic" for pure API/story
+     * moves — the echo-suppression signal for store bridges.
      */
-    onViewChange?: (view: CameraState) => void;
+    onViewChange?: (view: CameraState, origin: ViewOrigin) => void;
     /** Scene lighting (spec: "Scene Lighting") — the lighting* attributes' programmatic twin; omit for deck's default lights. */
     lighting?: LightingOptions;
 }
@@ -131,7 +136,18 @@ export declare class MapController {
     private commitPending;
     private destroyed;
     private firstCommitDone;
-    private viewChangeTimer;
+    private readonly stores;
+    /** Origin of the most recent viewport change FRAME — latched through the settle tracker for snapshot reads. */
+    private lastViewOrigin;
+    /**
+     * Shared settle/burst tracker (the `om-view-changed` twin) — ALWAYS armed,
+     * onViewChange or not: the burst latch also feeds the viewport snapshot's
+     * `origin`, so it must reset on settle even for store-only consumers.
+     */
+    private readonly viewSettle;
+    private onViewChange?;
+    /** Per-layer data version counters (`data:<id>` snapshots) — bumped on every data change, monotonic for the controller's lifetime. */
+    private readonly dataVersions;
     private readyFired;
     private resolveReady;
     readonly ready: Promise<void>;
@@ -153,6 +169,29 @@ export declare class MapController {
      */
     watch(tokens: readonly string[], notify: (ctx: RuntimeContext) => void): () => void;
     private notifyWatchers;
+    /**
+     * Per-token `{subscribe, getSnapshot}` store — the framework-free surface
+     * for `useSyncExternalStore`, MobX autoruns, Redux listeners, Zustand
+     * mirrors (recipes: docs/external-stores.md). Snapshots are cached
+     * immutable PLAIN DATA: `getSnapshot()` returns the SAME reference until
+     * this token's next change event, and never contains closures — rich
+     * reads (`project`, `data()`, `stats()`) stay on `ctx`. Tokens:
+     *   - "viewport"      → ViewportSnapshot (camera + bounds + origin)
+     *   - "selection"     → Selection | null
+     *   - "layers"        → LayerMetaSnapshot[] (what ctx.layers builds)
+     *   - "data:<layerId>" → {version, rows} — a VERSION STAMP, not the rows
+     *     (mirroring row arrays into a store per tick is the anti-pattern the
+     *     Redux performance guidance warns about; fetch rows via ctx.data()).
+     * `history` is deliberately NOT a store here — the app owns state on the
+     * programmatic front-end. Calling twice for one token returns the
+     * identical store object.
+     */
+    getStore(token: "viewport"): TokenStore<ViewportSnapshot>;
+    getStore(token: "selection"): TokenStore<Selection | null>;
+    getStore(token: "layers"): TokenStore<LayerMetaSnapshot[]>;
+    getStore(token: `data:${string}`): TokenStore<DataVersionSnapshot>;
+    getStore(token: string): TokenStore<unknown>;
+    private buildViewportSnapshot;
     /** The RuntimeContext contract (HU5) — identical to what HTML widget scripts receive as `ctx`. */
     buildCtx(): RuntimeContext;
     /** Picked object, normalized to flat — same path as OmMapElement (GeoJSON properties lifted; columnar rows materialized). */
@@ -216,6 +255,4 @@ export declare class MapController {
     /** Projects a lng/lat through the current viewport — undefined before the viewport resolves. */
     project(lngLat: [number, number]): [number, number] | undefined;
     destroy(): void;
-    /** Trailing-debounced onViewChange — see MapControllerOptions.onViewChange. */
-    private scheduleViewChange;
 }

package/dist/{raster-BwULn87I.js → raster-DDi9gXqf.js}

@@ -1,5 +1,5 @@
 import { w as kt, t as Ni, f as Oi, m as Ri } from "./mgrs-BY9bIvp4.js";
-import { an as Fi, ao as zi, ap as Ks, aq as Ws, ar as Di, b as Bi, as as Ui, l as es, at as ki, d as qi, au as Ki, av as Wi, aw as Xi, ax as Xs } from "./index-BR1HjJoE.js";
+import { an as Fi, ao as zi, ap as Ks, aq as Ws, ar as Di, b as Bi, as as Ui, l as es, at as ki, d as qi, au as Ki, av as Wi, aw as Xi, ax as Xs } from "./index-BoxZ3Mec.js";
 function Hi(t, e, s) {
   const { projectedCorners: i } = e, { topLeft: a, topRight: r, bottomRight: o, bottomLeft: n } = i, h = s(a[0], a[1]), l = s(r[0], r[1]), c = s(o[0], o[1]), u = s(n[0], n[1]), d = [
     h,
@@ -2377,7 +2377,7 @@ it.set(G.Zstd, () => import("./zstd-jXobGRcq.js").then((t) => t.decode));
 it.set(G.Jpeg, () => Promise.resolve(ke));
 it.set(G.Jpeg6, () => Promise.resolve(ke));
 it.set(G.Webp, () => Promise.resolve(ke));
-it.set(G.Lerc, () => import("./lerc-vBCRLD5s.js").then((t) => t.l).then((t) => t.decode));
+it.set(G.Lerc, () => import("./lerc-CSc9BX_F.js").then((t) => t.l).then((t) => t.decode));
 async function qe(t, e, s) {
   const i = it.get(e);
   if (!i)

package/dist/react.js

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

package/dist/runtime-core.d.ts

@@ -1,5 +1,6 @@
 import { type LightingIR } from "./scene-lighting";
 import { type TerrainIR } from "./terrain";
+import type { ViewOrigin } from "./external-store";
 import type { LayerIR } from "./ir";
 import { type Selection } from "./selection";
 import type { ValidationEntry } from "./validation";
@@ -25,8 +26,14 @@ export interface CameraOptions {
     curve?: boolean;
 }
 export interface RuntimeCoreCallbacks {
-    /** Fired whenever the view state changes (pan/zoom/pitch/bearing) — a notification, not a value. */
-    onViewportChange?: () => void;
+    /**
+     * Fired whenever the view state changes (pan/zoom/pitch/bearing) — a
+     * notification, not a value. `origin` (spec: "External-Store Contract")
+     * distinguishes canvas gestures ("user") from camera APIs / actions /
+     * transition frames ("programmatic") — the mapbox `originalEvent`
+     * convention, the echo-loop half of two-way store binding.
+     */
+    onViewportChange?: (origin: ViewOrigin) => void;
     onSelectionChange?: (selection: Selection | null) => void;
     /** Fired once the map (deck.gl standalone, or the basemap) has finished its async init (spec: Behavior Engine "load" event). */
     onLoad?: () => void;

package/dist/version.d.ts

@@ -5,4 +5,4 @@
  * the build rootDir, and a `define` would need repeating across vite/vitest/
  * vite-node configs.
  */
-export declare const LIBRARY_VERSION = "0.3.4";
+export declare const LIBRARY_VERSION = "0.4.0";