@nika-js/onlymap 0.1.0 → 0.2.0

package/docs/3d-assets.md

@@ -0,0 +1,74 @@
+# 3D assets on the map — the GLB pipeline
+
+OnlyMapJS renders 3D models **in geographic context**: buildings, equipment, vehicles — anything you can place at a longitude/latitude. The architecture rule that makes this simple is the same one the library applies to data everywhere:
+
+> **Domain 3D formats stay upstream; the manifest ingests web standards.**
+> IFC, CAD, mesh formats → convert on your server to GLB. GLB (binary glTF) and 3D Tiles → the manifest renders directly. (2D vector formats — GeoJSON, CSV, Shapefile, KML, GeoArrow — load directly too; see the README's data-formats table.)
+
+## The manifest half (this library)
+
+`ScenegraphLayer` instances a glTF/GLB model at each data row — the model loads and parses automatically (no loader wiring, no three.js, no scene setup):
+
+```html
+<om-map center="[-122.399, 37.79]" zoom="15.5" pitch="55" bearing="20" basemap="maplibre">
+  <om-layer id="towers" type="ScenegraphLayer"
+              scenegraph="./building.glb"
+              data="./sites.json"
+              get-position="[$lon, $lat]"
+              get-orientation="[0, $heading, 90]"
+              get-scale="[$width, $height, $depth]"
+              lighting="pbr" pickable></om-layer>
+  <om-behavior on="hover" layer="towers" action="show-tooltip" template="#site-tooltip"></om-behavior>
+</om-map>
+```
+
+Everything else composes as usual: picking works on models (the hover tooltip above), so do filters, widgets, behaviors, and the [testing story](testing.md).
+
+Things worth knowing:
+
+- **glTF is Y-up; the map is Z-up.** The roll of `90` in `get-orientation="[pitch, yaw, roll]"` stands a Y-up model upright — the standard idiom. Yaw is your heading field.
+- **`get-scale` is in model space** `[x, y, z]` — for an upright Y-up model that's `[width, height, depth]` in meters (if the model is unit-sized).
+- **`lighting="pbr"`** shades models by their glTF materials; the default is flat.
+- **One model, many instances.** `ScenegraphLayer` draws the *same* GLB at every row. Different models per row means one layer per model — or, at city scale, 3D Tiles (below).
+- Runnable example: [`dev/examples/scenegraph.html`](../dev/examples/scenegraph.html) (its `box.glb` is a placeholder — a stand-in for the pipeline below).
+
+## The pipeline half (your server)
+
+A proven Python stack for BIM/CAD sources — convert once, serve the GLB as a static asset:
+
+```python
+# IFC (BIM) → GLB, e.g. behind a Flask endpoint or as a batch job
+import ifcopenshell, ifcopenshell.geom   # parse IFC, extract geometry
+import trimesh                            # mesh cleanup: merge, decimate, reorient
+# assemble + write GLB via trimesh.exports or pygltflib
+```
+
+- **`ifcopenshell`** parses IFC and — importantly — can extract **geo-referencing** (`IfcMapConversion` / `IfcSite` coordinates), which is how a building lands at its real longitude/latitude instead of floating in local model space. Carry that lon/lat into your `data` rows.
+- **`trimesh`** handles mesh processing: merging elements, decimation (web budgets: aim for well under ~1M triangles per model), re-centering the origin at the model's base so `get-position` anchors the ground point.
+- **`pygltflib`** (or `trimesh`'s own exporter) writes the GLB.
+
+Keep the conversion out of the browser: IFC parsing is heavy, and GLB is the interoperable boundary — the same asset works in three.js, Blender, or any glTF viewer, so the pipeline isn't coupled to this library.
+
+## At city scale: 3D Tiles
+
+Hundreds of unique buildings or full city models shouldn't ship as one GLB. The OGC **3D Tiles** spec (streamed, LOD-managed) is the format to target — `Tile3DLayer` is bundled and consumes it directly:
+
+```html
+<om-layer id="city" type="Tile3DLayer" tileset="https://example.com/tileset.json"></om-layer>
+```
+
+For LOD experiments, common loaders.gl tileset options have first-class attributes:
+
+```html
+<om-layer id="city" type="Tile3DLayer"
+            tileset="https://example.com/tileset.json"
+            maximum-screen-space-error="2"
+            maximum-memory-usage="256"
+            view-distance-scale="0.85"></om-layer>
+```
+
+Upstream converters exist for IFC/CityGML → 3D Tiles (e.g. Cesium ion, `py3dtiles`, FME). Same rule: convert upstream, ingest the standard.
+
+## Scope boundary, stated honestly
+
+OnlyMapJS is for assets **in geographic context** — models on a map, camera pitching down at the world. It is not a model *inspector*: orbiting freely around a single non-geo-referenced model (the classic three.js/CAD-viewer use case) is a different product with a different camera. If your models have no real-world coordinates and never will, a plain glTF viewer is the right tool; the moment they belong somewhere on Earth, this pipeline is.

package/docs/live-data.md

@@ -0,0 +1,83 @@
+# Live data — streams, polling, and authenticated endpoints
+
+A live map is a layer whose `data` keeps changing. OnlyMapJS supports the two transports real fleet/telemetry backends actually expose, behind the same manifest surface — accessors, widgets, filters, and tooltips work identically on both, and **accessors never recompile when data updates** (only the `data` reference changes; the reconciler's fingerprints stay put).
+
+## Choosing a transport
+
+| Your backend exposes… | Use | Semantics |
+|---|---|---|
+| A WebSocket pushing per-entity updates | `data="wss://…"` | **upsert by key** — entities move in place |
+| A REST endpoint returning current state | `data="/api/…" refresh="5s"` | **snapshot replace** — each poll is the new truth |
+
+Rule of thumb: delta/event feeds → WebSocket; materialized "where is everyone right now" endpoints → polling. (SSE is not supported yet — ask if you need it.)
+
+## WebSocket streams
+
+```html
+<om-layer id="ships" type="IconLayer"
+            data="wss://stream.example/feed" source="ais" key="mmsi" flush="250ms"
+            get-position="[$lon, $lat]" get-angle="-$cog" ...></om-layer>
+```
+
+- **`key`** declares entity identity: each message *moves* its entity rather than appending a new one. Without a key, an **array** message replaces the whole snapshot (full-snapshot feeds); keyless object messages are dropped with a warning.
+- **`flush`** (default `250ms`) coalesces message bursts into one snapshot push per interval — widgets and the GPU see one update per flush, not one per message.
+- **Reconnects** are automatic, with exponential backoff (1s → 15s).
+- **Host-relative URLs** (`wss:/feed`) resolve host *and* scheme from the page — handy for same-origin bridges.
+
+### Decoding your message format — `registerSource`
+
+The transport is generic; your domain format lives in a plugin:
+
+```js
+import { OmMap } from "@nika-js/onlymap";
+OmMap.registerSource("ais", {
+  // optional: sent on every (re)connect — subscription/auth handshakes
+  onOpen: (send) => send(JSON.stringify({ APIKey: "...", BoundingBoxes: [...] })),
+  // raw message (JSON-parsed when parseable) → entity object(s), or null to ignore
+  decode: (m) => m?.MessageType === "PositionReport"
+    ? { mmsi: m.MetaData.MMSI, lon: m.Message.PositionReport.Longitude, /* … */ }
+    : null,
+});
+```
+
+Register the plugin in the same module script that imports the library (registration is also tolerated late — plugins resolve lazily — but same-task is the tidy order). Runnable example: [`dev/examples/ais.html`](../dev/examples/ais.html), which speaks aisstream.io's real message format against a simulated feed.
+
+## Polling (`refresh`)
+
+```html
+<om-layer id="drivers" type="IconLayer"
+            data="/api/fleet.json" refresh="5s"
+            get-position="[$lon, $lat]" ...></om-layer>
+```
+
+- Each poll **replaces the snapshot** — the endpoint's response is the new truth. If your endpoint returns deltas, you want the WebSocket path instead (validation warns if you combine `refresh` with a `wss:` URL).
+- **Failures don't blank the map**: a failing refresh keeps the last good snapshot and keeps polling, warning once per outage and once on recovery. The *initial* load settles `om-map-ready` even on error.
+- Interval floor is 250ms. Works for Arrow (`.arrow`) URLs too — re-fetched and re-parsed per poll.
+
+Runnable example: [`dev/examples/fleet.html`](../dev/examples/fleet.html) — 20 drivers polled at 1s from an **auth-protected** endpoint.
+
+## Authenticated endpoints — `configureData`
+
+Private APIs need credentials, and credentials must never appear in manifest markup (the manifest may be agent-generated, and attributes are visible DOM). Configure requests programmatically instead:
+
+```js
+import { OmMap } from "@nika-js/onlymap";
+
+OmMap.configureData({ headers: { Authorization: `Bearer ${token}` } });
+// or per-URL:
+OmMap.configureData({ headers: (url) => url.startsWith("/api/") ? { Authorization: `Bearer ${token}` } : undefined });
+// or take over entirely (signing, retries, proxies):
+OmMap.configureData({ fetch: myFetch, credentials: "include" });
+```
+
+This applies to **every** Data Layer request: initial loads, polling refreshes, and Arrow files. WebSocket auth needs no equivalent — put the token in the URL or send it from the plugin's `onOpen`.
+
+## How updates propagate (both transports)
+
+Every flush/poll takes the same path a resolved fetch takes: a **new data reference** enters the layer IR → the reconciler hands it to deck.gl, which re-uploads geometry without recompiling any accessor → `data:<layerId>` watch tokens fire, so widgets (stats panels, charts) re-render once per update. `om-map-ready` resolves after the *first* load for polling; for streams it resolves immediately (a stream never "finishes" — don't wait for a first message to consider the map ready).
+
+Known limitation: sockets and poll loops are keyed by URL and live for the page — removing the layer stops the data being *read*, not the connection.
+
+## Testing live layers
+
+In the [headless harness](testing.md), mock the transport: `vi.stubGlobal("fetch", ...)` for polling (readiness waits for your mock), or `vi.stubGlobal("WebSocket", ...)` for streams. The library's own test suites are the reference patterns — including asserting *movement* (fixed entity count, changing coordinates) rather than just presence.

package/docs/react.md

@@ -0,0 +1,120 @@
+# React
+
+OnlyMapJS ships a first-party React adapter: **`@nika-js/onlymap/react`**. It gives you real components and a typed hook — no HTML strings, no `<om-*>` elements, no expression language:
+
+```tsx
+import { OmMap, OmLayer, OmWidget, OmOverlay, useOmMap } from "@nika-js/onlymap/react";
+
+function Quakes() {
+  const [visible, setVisible] = useState(true);
+  return (
+    <OmMap center={[-119, 36]} zoom={5} basemap="maplibre">
+      <OmLayer id="quakes" type="ScatterplotLayer" data={features} visible={visible} pickable
+               getPosition={d => [d.lon, d.lat]}
+               getFillColor={d => (d.mag >= 6 ? [214, 40, 40] : [252, 191, 73])}
+               onClick={sel => console.log(sel.object)} />
+      <OmWidget position="top-left"><StatsPanel /></OmWidget>
+      <OmOverlay anchorFrom="selection" layer="quakes">
+        {sel => sel && <QuakeCard feature={sel.object} />}
+      </OmOverlay>
+    </OmMap>
+  );
+}
+
+function StatsPanel() {
+  const { stats, viewport, emit } = useOmMap(["viewport", "data:quakes"]);
+  return <div>{stats("quakes", "mag").count} quakes at z{viewport.zoom.toFixed(1)}</div>;
+}
+```
+
+## How it works (and why it can't fight React)
+
+The core is one IR-centered reconcile engine with two front-ends. The HTML manifest (`<om-map>` + MutationObserver) is one; the React adapter rides the other — a **programmatic front-end** that turns typed descriptors into the same layer IR with no DOM manifest in between. React components never render `om-*` elements, so React's virtual-DOM ownership and the library's MutationObserver never meet. `<OmMap>` renders a wrapper `div` and hands the renderer a dedicated leaf `div` React never puts children in.
+
+The same architecture means the two authoring surfaces share every contract: layer semantics, the action payload contract (`emit`), and the `ctx` shape (`useOmMap()` returns exactly what an HTML widget script receives as `ctx` — typed).
+
+## The React way vs. the HTML way
+
+| Intent | HTML manifest | React |
+|---|---|---|
+| Accessors | `get-fill-color="scale($mag, …)"` | `getFillColor={d => …}` — plain functions, no trust step |
+| Interactions | `<om-behavior on="click" …>` | `onClick={…}` on `<OmLayer>` |
+| Toggle / filter a layer | `toggle-layer` / `filter-layer` actions | state → `visible` / `filterRange` props |
+| Widgets | `<om-widget type="legend">` / `<script type="om/widget">` | `<OmWidget>` + your JSX + `useOmMap()` |
+| Popups/tooltips | `<om-overlay>` + `show-overlay` | `<OmOverlay>` (projection, rAF tracking, culling managed) |
+| Highlight a feature | `highlight-feature` action | `highlightedObjectIndex` prop (deck.gl-idiomatic) |
+| Stories / draw widget | `<om-story>` / `<om-widget type="draw">` | HTML-manifest only for now |
+
+Actions that mutate manifest attributes (`toggle-layer`, `show-overlay`, `fade`, story/draw actions…) are deliberately **not dispatched** on the React path — you'll get a console warning pointing you at props/state instead. Camera actions (`fly-to`, `zoom-in`/`-out`, `zoom-to-feature`), channel effects (`pulse`, `populate`), and your own `OmMap.registerAction` handlers all work.
+
+## Component reference
+
+### `<OmMap>`
+
+| Prop | Notes |
+|---|---|
+| `center` `zoom` `pitch` `bearing` | Initial camera; later prop changes move the camera (instant). While they're unchanged, user panning is never fought. |
+| `basemap` | Same contract as the attribute — `"maplibre"`, a style URL, or omit for standalone deck.gl. |
+| `headless` | `true` or `{ width, height }` — no renderer, real projection math (tests under jsdom/happy-dom). |
+| `onReady` | Renderer up + first commit + no data URL still loading. |
+| `onViewStateChange` | Every camera change, with the current `CameraState`. |
+| `onRuntimeError` | deck.gl-level failures in the structured validation shape. |
+| `ref` | The imperative handle — a `MapController`: `flyTo`, `setView`, `emit`, `getLayers`, `injectPick`, `ready`. |
+
+Give it a size (`style`/`className`) — it renders a `position: relative` div.
+
+### `<OmLayer>`
+
+`id` and `type` (any registered deck.gl layer type), plus:
+
+- `data` — inline rows / GeoJSON / columnar **by stable reference** (memoize it — `data:<id>` reactivity diffs by reference), or a URL string. URLs get the full Data Layer: format detection (CSV, Arrow, Shapefile, KML…), `ws(s)://` streams (`source`, `streamKey`, `flush`), `refresh` polling.
+- Any deck.gl prop in camelCase — accessors as plain functions. deck.gl ignores accessor *identity*, so pass `updateTriggers={{ getFillColor: theme }}` when an accessor's output changes.
+- `label` / `color` — legend metadata (`ctx.layers`).
+- `filterField` / `filterRange` (+ soft range, category) — GPU filtering, same wiring as the HTML attributes.
+- `onClick` / `onHover` — picks on this layer, object already flattened/materialized. `onHover(null)` = pointer left.
+
+### `<OmWidget>`
+
+A positioning shell: `position="top-left|top-right|bottom-left|bottom-right"` + your JSX. Widgets sharing a corner stack; the shell re-enables pointer events over the map.
+
+### `<OmOverlay>`
+
+Anchored HTML at a projected coordinate, culled off-screen/behind-globe, tracked per frame outside React renders:
+
+- `anchor={[lng, lat]}` — static, or `anchorFrom="selection"` (+ `layer="id"` to scope which picks move it).
+- Children: static JSX, or `(selection) => JSX` to render the picked feature.
+- `anchorOffset` — attachment point (default `bottom-center`).
+- `interactive={false}` for hover-following tooltips (lets the pointer reach the canvas underneath).
+
+### `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).
+
+## Testing
+
+The headless mode works under React exactly like the HTML harness (no WebGL, real projection):
+
+```tsx
+const ref = createRef<OmMapHandle>();
+render(<OmMap ref={ref} headless><OmLayer id="pts" type="ScatterplotLayer" data={rows} getPosition={p} /></OmMap>);
+await ref.current!.ready;
+expect(ref.current!.getLayers()).toHaveLength(1);
+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 deck.gl picks — `onClick`, `useOmMap(["selection"])`, and `<OmOverlay anchorFrom="selection">` all react to it.
+
+## Install
+
+```bash
+npm install @nika-js/onlymap react react-dom
+```
+
+React ≥ 18 is an optional peer dependency — it's only loaded if you import `@nika-js/onlymap/react`. The adapter is a few KB of glue; the core is shared with the HTML entry, so using both surfaces on one page costs one core.
+
+## Not in the adapter (yet)
+
+- **Stories** as React components (a `<Story>`/timeline hook is on the roadmap) — an HTML `<om-story>` needs the HTML front-end.
+- **The draw widget** — HTML front-end only for now.
+- Per-feature `trace` (it animates via runtime manifest elements) — whole-layer `trace` on a TripsLayer works.
+- A `scale()` helper mirroring the expression language — use `d3-scale` or plain functions.

package/docs/stories.md

@@ -0,0 +1,134 @@
+# Map stories — guided tours as markup
+
+A story turns a map into a narrated sequence: fly here, reveal this, highlight that — authored declaratively, played back with a scrubber, and testable like everything else. Runnable example: [`dev/examples/story.html`](../dev/examples/story.html).
+
+## The one rule
+
+**The map describes a scene; the story describes intent over time about that scene.** `<om-story>` is a *sibling* of your layers, never a container — steps reference elements by id, and a step that contains an element is a validation **error**. Delete the story and the map is byte-for-byte the same map.
+
+```html
+<om-map center="[-122.35, 37.85]" zoom="10" basemap="maplibre">
+  <om-layer id="regions" ...></om-layer>             <!-- a complete, ordinary map -->
+  <om-overlay id="chapter" visible="false">…</om-overlay>
+
+  <om-story id="tour" interrupt="pause">
+    <om-step duration="3s" action="fly-to" center="[-122.44, 37.78]" zoom="12" curve></om-step>
+    <om-step duration="4s" action="show-overlay" target="chapter" parallel delay="1500ms"></om-step>
+    <om-step duration="2s" action="hide-overlay" target="chapter" delay="1s"></om-step>
+    <om-step duration="2s" action="toggle-layer" layer="bikes" visible="true"></om-step>
+  </om-story>
+
+  <om-widget type="player" story="tour" position="bottom-left"></om-widget>
+</om-map>
+```
+
+## Steps
+
+A step is `action="…"` plus payload attributes — the **same actions, same kebab-case payload rule** as `<om-behavior>` and `data-emit` buttons. Anything an action can do, a step can do, including your own `OmMap.registerAction` actions.
+
+Timing attributes (everything else rides into the payload):
+
+| Attribute | Meaning |
+|---|---|
+| `duration` | How long the step's animation runs (`"3s"`, `"800ms"`). Also passed to the action — so a `fly-to` step's camera ease matches its slot. `0`/omitted = instantaneous. |
+| `delay` | Stagger before the step starts. |
+| `parallel` | Start with the *previous step* instead of after everything so far (concurrent camera + reveal is the classic use). |
+
+Sequential steps wait for **everything** before them to finish — a short `parallel` step never drags the next step into the middle of a longer one.
+
+**Write declarative payloads.** Seeking replays steps, so a step should *set* state, not flip it: `action="toggle-layer" layer="bikes" visible="true"` (sets), not a bare toggle. Custom actions replay on seek but can't be rewound — the library warns once.
+
+## Playback control
+
+Playback is three actions — `story-play`, `story-pause`, `story-seek {story, t}` — so every dispatch surface works:
+
+- **Attributes:** `autoplay` (starts after `om-map-ready`), `loop`.
+- **The built-in player:** `<om-widget type="player" story="tour">` — play/pause, seek bar, elapsed/total. It's dumb chrome: it emits the three actions and re-renders off the story's `om-story-tick` events, so replacing it is just your own `data-emit` buttons: `<button data-emit="story-play" data-story="tour">▶</button>`.
+- **Behaviors:** `<om-behavior on="click" layer="regions" action="story-play" story="tour">` — click to start a tour.
+- **Script:** `storyEl.play() / pause() / seek(ms)`, plus `state`, `currentTime`, `duration` properties and the `om-story-tick` event.
+
+**One active story per map** — playing story B pauses story A. **`interrupt="pause"`** (the default) pauses playback when the user grabs the map (pointer-down or wheel); `interrupt="ignore"` opts out.
+
+## Seeking (the scrub model)
+
+`seek(T)` restores the story's captured initial state, then applies the *final* state of every step starting **before** T, instantly. `seek(0)` therefore means "pristine start"; seeking to the very end applies everything. Scrubbing is step-granular — a seek into the middle of a 3s camera flight lands at the flight's end state, not 40% along it.
+
+Initial-state capture happens on first play, from the attributes the built-in-action steps will touch (layer visibility, overlay visibility, highlights, filter ranges) plus the camera. That's why declarative payloads matter: the library can know what to snapshot by reading them.
+
+## Testing stories
+
+Deterministic, headless, no timers to race ([testing guide](testing.md)):
+
+```js
+const h = await mountForTest(myPageHtml);
+const story = h.story("tour");
+await story.advance(2100);                          // manual clock — exact, rAF never runs
+expect(overlay.getAttribute("visible")).toBe("true");
+await story.seek(0);
+expect(overlay.getAttribute("visible")).toBe("false");
+```
+
+`h.story(id).advance(ms)` drives the clock manually; `play/pause/seek/state/currentTime/duration` mirror the element API.
+
+## Effect verbs
+
+Three intent-level verbs, usable as step shorthands (`<om-step fade layer="regions" duration="1s">`) or as plain actions from behaviors and buttons (`data-emit="pulse" data-layer="quakes"`):
+
+| Verb | What it does | Mechanics |
+|---|---|---|
+| `fade` | Animate the layer's opacity to `to` (default 1) over `duration`. Start a reveal layer at `opacity="0"`. | attribute + GPU transition — fully scrub-restorable |
+| `pulse` | Attention oscillation (opacity 1 → 0.3 → 1, `cycles` ≈ duration/600ms) | per-frame channel, cleared cleanly at the end |
+| `trace` | Progressive draw along a `TripsLayer`'s timestamps; the finished trail holds | per-frame `currentTime` sweep |
+| `trace` + `feature-id` | **One feature draws itself on** — inside its own multi-feature layer (Polygon/MultiPolygon outline, or LineString) | see below |
+| `populate` | **Rows drop in one by one** — the layer fills up over `duration` | filterRange sweep on the always-mounted GPU filter |
+
+Whole-layer `trace` needs per-vertex time, which is TripsLayer's purpose — give it `get-path`/`get-timestamps` data and start `current-time` below the first timestamp. All verbs honor `prefers-reduced-motion` by jumping to the final state.
+
+### Per-feature trace: `trace layer="regions" feature-id="mission"`
+
+```html
+<om-step duration="3s" trace layer="regions" feature-id="mission"></om-step>
+```
+
+The Mission polygon's outline draws itself around the perimeter (75% of the slot, at uniform speed — timestamps are synthesized from cumulative distance), then the real feature reappears as the outline dissolves. Everything underneath is runtime-managed and removed afterward: the target feature is hidden by swapping the layer's data to "everyone else" through the per-frame channel (the other features are untouched, and your markup never changes), and the outline is a temporary `TripsLayer` element the runtime appends and deletes — it never appears in the legend or `ctx.layers`. Optional `color="[255, 120, 40]"` styles the outline.
+
+**Parallel traces compose.** Fire a trace for every feature in the same beat and they all draw at once — the hides accumulate (the layer shows the union of "everyone else", i.e. nothing, while all outlines draw) and each feature reveals independently as its own trace finishes:
+
+```html
+<om-step duration="3s" trace layer="regions" feature-id="north-beach" parallel></om-step>
+<om-step duration="3s" trace layer="regions" feature-id="mission" parallel></om-step>
+<om-step duration="3s" trace layer="regions" feature-id="sunset" parallel></om-step>
+```
+
+Start the layer at `visible="false"` and turn it on in the same beat for a "draws itself onto an empty map" opening.
+
+It's also a plain action, so **click-to-trace** is one line — clicking any polygon in the layer makes it draw itself:
+
+```html
+<om-behavior on="click" layer="regions" action="trace" duration="2s"></om-behavior>
+```
+
+One honest limit: point features have no outline to trace, so they fall back to `fade`. Scrubbing a story mid-trace cleans up the temp layer and every patch.
+
+### Populate: `populate layer="bikes"`
+
+```html
+<om-step duration="2500ms" populate layer="bikes"></om-step>
+```
+
+The layer's rows appear one by one until it's fully populated — each frame only moves the GPU filter's range bound (a uniform update, no data re-upload), and the patch clears itself so the layer ends on its authored props. Appearance **order**:
+
+- the layer's own `filter-field`, if it has one — the sweep runs over the *authored* range, so rows appear in filter order and the end state *is* the authored filter (racks with `filter-field="size" filter-range="[0, 5]"` populate small-to-large, and anything outside the range stays correctly hidden);
+- `field="capacity"` in the payload — order by any numeric field without authoring a filter;
+- neither — data order.
+
+Works from every dispatch surface, e.g. populate on load: `<om-behavior on="load" action="populate" layer="bikes" duration="3s">`. GeoJSON layers need an authored `filter-field` to populate (a live composite can't take a runtime filter accessor); without one it warns and falls back to `fade`.
+
+## Animation primitives (usable without stories)
+
+- **Camera:** `map.flyTo(coords, zoom, { duration, curve })`, or the `fly-to` action (`center`/`zoom`/`pitch`/`bearing`/`duration`/`curve`) from any behavior or button; `zoom-to-feature` accepts `duration` too. `prefers-reduced-motion` is honored in both renderer modes — moves become instant, final state identical.
+- **Layer props:** `transition="get-fill-color 800ms, get-radius 400ms"` GPU-animates prop changes; on a live layer, `transition="get-position 300ms"` makes entities glide between updates.
+
+## Not yet (honestly)
+
+Mid-step scrub interpolation; simultaneous multi-story playback; video export (app-level — use screen capture).

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

@@ -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