@nika-js/onlymap 0.6.4 → 0.6.11

package/CHANGELOG.md

@@ -8,6 +8,51 @@ Note: npm collapsed a few closely-spaced releases — the GPX/FlatGeobuf (0.5.4)
 and GeoParquet (0.5.5) work shipped to npm together as **0.5.6**, so npm's
 version list jumps 0.5.3 → 0.5.6. Each logical version is listed here regardless.
 
+## 0.6.11 — 2026-08-18
+
+### Fixed
+- **Tracking markers tween smoothly instead of jittering.** Two causes, both fixed: inline-JSON layer data is now reference-stable across reconciles (it was re-parsed into a fresh array every pass, so any unrelated manifest edit — another rider's fix, a story step — looked like a new position fix to every Tracking layer and snapped its glide to the endpoint; this also stops spurious `data:<id>` watch-token fires for every inline layer on every reconcile), and a glide interrupted by a genuinely new fix now resumes from the marker's **current animated position** rather than the previous fix's endpoint, keeping motion continuous under any fix cadence.
+
+## 0.6.10 — 2026-08-18
+
+### Added
+- **`om-route-resolved` consumer event** — whenever a `Route` layer resolves (direct `geometry` or a `RoutingProvider` round-trip), the map dispatches `om-route-resolved` with `detail = { layerId, route }`, where `route` carries the normalized `geometry`, `distanceMeters`, `durationSec`, `legs`, and fitted `bounds`; re-fired on every re-resolve. `MapController` mirrors it as `onRouteResolved(layerId, route)`. This closes the "route metadata has no consumer surface" gap natively: the Delivery Riders simulation and the Compute a Route readout now run entirely on this event, with no page-side fetching or adapter-to-UI plumbing.
+
+## 0.6.9 — 2026-08-18
+
+### Added
+- **Tracking marker shapes** — `icon="arrow|car|motorcycle"` on a `Tracking` layer picks the marker (default arrow, unchanged). All shapes are drawn nose-up and baked in the layer's `color`, so bearing rotation and per-rider tinting apply to every shape identically; unknown names fall back to the arrow with a validation warning. The Delivery Riders example now rides color-matched motorcycles.
+
+## 0.6.8 — 2026-08-18
+
+### Added
+- **Route tail modes** — link a `Route` layer to its `Tracking` layer with `progress-from="<tracking-layer-id>"` and choose how the traveled portion renders: `tail="none"` (client view — only current position → destination renders, and the origin pin drops with the traveled line) or `tail="dim"` (operator view — the traveled portion darkens, `tail-color` overrides the default derivation, while current position → destination keeps the live color). The split point is the tracking marker's interpolated position projected onto the nearest point of the route line, advancing smoothly per frame with the marker's glide — not stepping per GPS fix. Default (`tail="full"`) keeps 0.6.7 behavior exactly. Validation warns on partial wiring: `tail` without `progress-from`, `progress-from` without a tail mode, `tail-color` outside `dim`, and a `progress-from` naming no layer.
+- The **Delivery Riders** example shows the operator view (three dimmed trails growing behind the riders); the **Routing & Tracking** example shows the client view (the route line shrinks to what's ahead of the rider).
+
+## 0.6.7 — 2026-08-17
+
+### Added
+- **Routing & tracking layer types** — `<om-layer type="Route" geometry='{"type":"LineString","coordinates":[...]}'>` draws a styled route (casing, colored line, origin/destination markers) from geometry you already have, resolving synchronously with no network call; `origin`/`destination` (+ `provider`, default `"nika"`, + optional `waypoints`/`profile`) resolve one asynchronously instead via a registered `RoutingProvider` (`OmMap.registerRoutingProvider`). `follow="fit-route"` auto-fits the camera once the route resolves. `<om-layer type="Tracking" get-position="[$lng,$lat]">` renders one moving entity with bearing-derived icon rotation (`bearing-field`, default `"bearing"`) that glides smoothly between position updates (`interpolate-ms`, default `1000`) instead of jumping; `follow="follow"` eases the camera along with it. Live position data arrives through the ordinary `data`/`source` mechanism — no separate tracking-subscription API. `Route`/`Tracking` expand into ordinary `PathLayer`/`IconLayer` instances internally, the same pattern `BIMLayer` already uses for `Tile3DLayer`.
+- The bundled `nika` routing provider is registered by default so `type="Route"` works out of the box once NIKA's routing service exists — its endpoint is currently an **unverified placeholder** (no such backend is live yet); register a working provider with `OmMap.registerRoutingProvider(name, provider)` for anything that needs to resolve routes today, or author `geometry` directly.
+- Two gallery examples: **Routing & Tracking** (direct-geometry route + a simulated live GPS feed gliding a tracking marker) and **Compute a Route** (click two points anywhere and a ~15-line page-script `RoutingProvider` adapter over OSRM's keyless public demo server computes the street-following drive — the click handler only writes `origin`/`destination` attributes; reconcile, the provider round-trip, and the camera re-fit are all library machinery). The OSRM adapter recipe also ships in the skill's syntax reference.
+
+## 0.6.6 — 2026-08-14
+
+### Added
+- **Multi-dimension categorical GPU filtering** — `filter-category-fields='[{"field":"fuel","categories":["Coal","Gas"]},{"field":"region","categories":["West"]}]'` filters on up to 4 categorical fields at once, AND'd together and combinable with an active numeric filter (a row must pass every dimension of both kinds). `filter-category`/`filter-categories` (single dimension) keep working unchanged. The built-in `<om-widget type="filter">` now auto-renders a checkbox list (one per distinct value present in the data, with its row count) instead of a slider when its `field` is declared categorically — the mode is inferred from the layer's own filter, never a separate widget attribute. The React/programmatic front-ends get the equivalent `filterCategoryFields` prop.
+
+### Fixed
+- `ctx.stats`/`ctx.dataInViewport` now respect an active categorical filter (`filter-category`/`filter-categories`) — previously only numeric filters were coherence-rule-aware, so a chart could silently disagree with a categorically-filtered map.
+- Story scrubbing and undo/redo now correctly restore an active categorical filter — previously `filter-category`/`filter-categories` weren't captured at all, so rewinding past a categorical `filter-layer` step silently dropped it.
+
+## 0.6.5 — 2026-08-13
+
+### Added
+- **Multi-dimension GPU filtering** — `filter-fields='[{"field":"magnitude","range":[4,10]},{"field":"time","range":[…]}]'` filters on up to 4 fields at once (`DataFilterExtension`'s own ceiling), AND'd together (a row must pass every dimension). `filter-field`/`filter-range` (single dimension) keep working unchanged — `filter-fields` is additive, not a replacement. Place one `<om-widget type="filter" layer="…" field="…">` per dimension; the `filter-layer` action merges range updates onto the matching dimension instead of replacing the whole filter, so independent widgets never clobber each other. `ctx.stats`/`ctx.dataInViewport`'s filter-aware coherence rule applies the same AND-across-dimensions test CPU-side. The React/programmatic front-ends get the equivalent `filterFields` prop.
+
+### Fixed
+- `populate` on a layer with more than one authored filter dimension now sweeps the first and holds the rest at their authored range, instead of a type error.
+
 ## 0.6.4 — 2026-08-12
 
 React Native core prerequisites. 0.6.3 was already tagged for release when this

package/README.md

@@ -72,7 +72,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 1,083 unit/behavioral tests and 62 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 1,208 unit/behavioral tests and 64 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.
 
@@ -83,7 +83,7 @@ A handful of elements, one rule: **attributes are kebab-case versions of deck.gl
 | Element | Role |
 |---|---|
 | `<om-map>` | The map. `center`, `zoom`, `pitch`, `bearing`; `basemap` takes a free preset (`positron`, `liberty`, `dark-matter`, `osm`, …), a style URL, or `"none"` (standalone canvas) — and switches **live**; `validate` for a live on-page error panel. Give it a height: a custom element is `display:inline` by default, so the library injects a `display:block` default (fills a sized parent, else a 400px floor) to keep a bare map visible, but set an explicit height (`om-map { height: 100vh }`) for real layout — any height you set wins outright, including one below the floor. A map that still collapses warns in the console; `hidden` and `display:none` maps stay hidden and stay quiet. |
-| `<om-layer>` | Any of **37 layer types** by name — all of deck.gl's core, geo, aggregation, and mesh layers (Scatterplot, GeoJson, Arc, Path, Heatmap, Hexagon, Trips, Tile, Tile3D, Scenegraph, …) plus the built-in `PopupLayer` for WebGL badges/labels at scale, the native `COGLayer` for GeoTIFF rasters, `ZarrLayer` for chunked Zarr/GeoZarr rasters, `ImageOverlay` for georeferenced drone JPEGs, and `BIMLayer` for BIM source files (`.ifc` today) loaded straight in the browser, no pre-conversion step. `id` required; `label`/`color` feed the legend. |
+| `<om-layer>` | Any of **39 layer types** by name — all of deck.gl's core, geo, aggregation, and mesh layers (Scatterplot, GeoJson, Arc, Path, Heatmap, Hexagon, Trips, Tile, Tile3D, Scenegraph, …) plus the built-in `PopupLayer` for WebGL badges/labels at scale, the native `COGLayer` for GeoTIFF rasters, `ZarrLayer` for chunked Zarr/GeoZarr rasters, `ImageOverlay` for georeferenced drone JPEGs, `BIMLayer` for BIM source files (`.ifc` today) loaded straight in the browser with no pre-conversion step, and `Route`/`Tracking` for styled routes and live position tracking. `id` required; `label`/`color` feed the legend. |
 | `<om-widget>` | UI panels. Built-ins: `legend` (symbology-aware: color scales render as gradient ramps or class ranges, categorical ternaries as discrete palettes), `layer-switcher`, `basemap-switcher`, `lighting`, `clip-box`, `zoom-controls`, `undo-redo`, `scale-bar` (metric/imperial/nautical `units`), `attribution`, `filter`, `draw` (point/line/polygon sketch capture, GeoJSON save/autosave; `export-3d` adds an "Export 3D" button that clips loaded `Tile3DLayer`/`BIMLayer` content to the drawn footprint and downloads it as a portable GLB — re-framed to a local coordinate frame at the footprint's own centroid, each triangle carrying its own source color as vertex colors, no textures — or, with `export-3d="b3dm"`, the same mesh wrapped for Cesium/3D-Tiles pipelines; only currently-visible 3D Tiles/BIM layers are included — a layer hidden via `visible="false"` or the `toggle-layer` action is skipped, with a distinct console warning for "nothing loaded" vs. "everything hidden"), `measure` (geodesic distance + area + cut/fill volume — live labels, `units` toggle, an `om-measure` readout event; `modes="distance area volume"` adds a footprint-then-extrude tool: outline a polygon, double-click to close it — it turns solid teal, ready — then drag the double-headed arrow gizmo that appears at its centroid up to fill or down to cut, reading out Cut/Fill/Net (signed, fill−cut)/Total (unsigned, cut+fill) volume plus Area/Perimeter, each labelled with its own sign convention. The math is a REAL per-cell grid integration: closing a footprint bulk-loads its covering DEM tiles, lays a metric grid in a local tangent frame at the ring centroid (cell size = the DEM's ground-sample distance; scanline point-in-polygon; bilinear, tile-seam-correct sampling; worker-offloaded), and integrates terrain-vs-base per cell — mixed cut AND fill within one footprint on undulating ground, with a published ±error (per-cell cellArea × 1.5 × GSD, summed per side), the cell size used, and a no-data warning all carried on the `om-measure` readout (`cellSizeM`/`gsdM`/`cutErrorM3`/`fillErrorM3`/`nodataFraction`). A `base-surface` attribute picks the reference surface: `custom` (default — the gizmo's draggable target plane), or boundary-derived stockpile strategies with no gizmo (`triangulated` boundary TIN, `plane` least-squares fit, `lowest`/`highest`/`average`). On `custom`, the extruded prism's own boundary hugs each corner's real ground elevation by default (so it doesn't visibly float above or sink below sloped terrain) — a "Flat target plane" toggle button appears above the readout once a footprint closes, switching that rendering to a single level plane instead (a rendering choice only; the underlying cut/fill numbers were already computed against one flat target elevation either way). Requires `terrain` on `<om-map>` — validation warns if `volume` is in `modes` with none (without terrain a flat-plane fallback runs, with no error figures — nothing honest to quote). A `profile` attribute alongside `modes` — not a mode of its own — samples elevation around a volume footprint's own perimeter as it's drawn and closed, live, and dispatches it on `om-measure`'s `profileSeries` field for a `dynamic-chart` widget to plot. Each sample is `{x: distance-from-start-m, y: elevation-m}`, and samples that ARE one of the drawn footprint's own corners additionally carry `vertexIndex` (0-based, in draw order) — so a chart can mark the real corners instead of every interpolated sample, and the widget's built-in profile chart marks each corner, labelling the first `1 · Start`. The map badges the first two vertices in draw order (`1 · Start`, `2`), which states the ring's direction outright — a start marker alone leaves clockwise vs counter-clockwise ambiguous, and the two wind to mirror-image profiles. Two badges is the minimum that fixes a direction and a constant cost regardless of how many corners the footprint has. Also volume-only: `deadband` (m³) zeroes out a Cut/Fill figure below the threshold, filtering drag noise near zero height (Cut/Fill/Net/Total are always RAW geometric volumes — deliberately unaffected by `swell`/`shrink`, so they keep answering "does this reach target elevation" regardless of what material's configured); `density` (t/m³ metric, lb/yd³ imperial) and `swell`/`shrink` (multipliers, default 1×) instead populate a separate Material section, standard Bank/Loose/Compacted earthworks convention — Adjusted Cut = raw × swell (loose/haul volume, bigger — excavating adds air voids), Adjusted Fill = raw ÷ shrink (loose/borrow volume needed, also bigger — the raw fill is already the compacted target void), plus Cut/Fill tonnage computed from the raw (not adjusted) volume, since swell/shrink change volume, not mass; the section only appears once at least one of `density`/`swell`/`shrink` is actually configured, no separate toggle. A `stale` field on the `om-measure` readout flags the brief window between a footprint committing and its elevation sample resolving, so a consumer doesn't read numbers left over from a prior footprint as current), `vega-lite` (live charts bound to a layer's data), `dynamic-chart` (the same Vega-Lite rendering, but data-driven by a live DOM event instead of a layer — `on="<event-name>"` + `series-field="<name>"` reads `event.detail[seriesField]` as the chart's `values` on every matching event, redrawing at a fixed `width`; a feature "freezes" it for free by simply omitting that field the next time it fires, no separate pause API needed), and the BIM set `ifc-browser` / `feature-inspector` / `ifc-loader` / `ifc-clash`. Or write your own inline with HTML + a `<script type="om/widget">`. Adjacent compact button widgets (`zoom-controls`, `undo-redo`, `widgets-toggle`) **auto-cluster** into one control group (opt out per widget with `cluster="false"`), and `<om-map widgets-hidden>` / the `set-widgets-visible` action / `<om-widget type="widgets-toggle">` hide all authored chrome without destroying it — provider attribution and the license badge never hide. **Placement is managed**: `position` takes one of 8 logical, RTL-aware slots (`top-start`, `top-center`, `top-end`, `center-start`, `center-end`, `bottom-start`, `bottom-center`, `bottom-end`; legacy corner names alias) — same-slot widgets stack with flush edges and a shared gap, `order` sets in-slot ordering, and `position="manual"` opts out entirely (a plain block you style yourself, even outside the map). At map widths ≤640px, managed widgets automatically move into accessible top/end/bottom/start drawers; `fold="never"` keeps an essential control out, `widgets-fold="off"` disables folding, and `--om-widget-fold-breakpoint` changes the map-width threshold. Provider attribution is an in-flow member of `bottom-end` and the license badge of `bottom-start`, so neither covers a widget. A slot dims automatically while an open popup covers it (`widgets-dim="off"` to disable), except slots containing required chrome. Themeable from plain page CSS via custom properties: `om-map { --om-widget-bg: #111827; --om-widget-fg: #f9fafb; }` (also `-muted`, `-border`, `-hover-bg`, `-accent`), plus layout tokens (`--om-widget-inset-x/-y`, `--om-widget-gap-x/-y`, `--om-widget-opacity`, `--om-widget-radius`) or the no-CSS sugar `<om-map widget-style="gap:10 opacity:0.9">`. |
 | `<om-overlay>` | Rich HTML anchored to a map location — a static `anchor="[lng, lat]"`, the current selection, or a feature's own geometry via `anchor-layer`/`anchor-feature-id`. Selection-anchored overlays scope with `layer` (one layer's picks) and `selection-type="click"`/`"hover"` (one pick type — give a click-opened popup `selection-type="click"` so hovering elsewhere doesn't drag it along). `{{field}}` interpolates the picked feature, HTML-escaped by default; `{{z}}` is a real depth-picked elevation when some layer under the cursor set `pickable="3d"` (terrain does this itself, so hovering the ground always has one) — empty otherwise, never a misleading 0. `clip-to-map` (opt-in) hides the overlay when its own box would spill past the map viewport, not just when its anchor leaves — for small transient tips that track the cursor, where an overhanging box would otherwise inflate the page's scroll overflow and cause visible view jitter. |
 | `<om-behavior>` | Declarative interactions: `on="click|hover|drag|load|data-loaded"` → a named action. |
@@ -149,10 +149,12 @@ Built-in actions wire to picks, widget buttons (`data-emit`), or script (`ctx.em
 
 **Map stories:** a guided tour as markup — `<om-story>` holds `<om-step>` children that fire the same actions behaviors use, on a timeline (`duration`, `delay`, `parallel`); the built-in `type="player"` widget gives play/pause/scrub, seeking restores the scene's captured initial state, one story is active per map, and grabbing the map pauses playback. Effect verbs — `fade`, `pulse`, `trace` (progressive TripsLayer draw-on; with `feature-id`, a single polygon draws itself on inside its own layer), and `populate` (rows drop in one by one via a GPU filter sweep) — work as step shorthands or plain actions. The story is a sibling that references layers by id — delete it and the map is unchanged. Guide: [docs/stories.md](docs/stories.md).
 
-GPU filtering is declarative — `filter-field="magnitude" filter-range="[4,10]"` — updates live from the built-in `filter` slider widget, and widget statistics stay coherent with what the map shows (`ctx.stats` respects the active filter unless you opt out).
+GPU filtering is declarative — `filter-field="magnitude" filter-range="[4,10]"` — updates live from the built-in `filter` widget (a slider), and widget statistics stay coherent with what the map shows (`ctx.stats` respects the active filter unless you opt out). Up to 4 numeric dimensions at once via `filter-fields='[{"field":"magnitude","range":[4,10]},{"field":"time","range":[…]}]'` — a widget per field, each moved independently; a row must pass every active dimension. Categorical filtering is the same shape, a separate mechanism — `filter-category="fuel" filter-categories="[...]"` (or `filter-category-fields` for up to 4) renders the same `filter` widget as a checkbox list instead of a slider, and combines with any active numeric filter (a row must pass both).
 
 Dashed lines are one attribute — `dash="[6, 3]"` (or `dash="6 3"`, plus optional `dash-justified`) on a `PathLayer`/`GeoJsonLayer`/`PolygonLayer`/`TripsLayer` — wired through deck's `PathStyleExtension` under the hood.
 
+**Routing & tracking:** `<om-layer type="Route" geometry='{"type":"LineString","coordinates":[...]}'>` draws a styled route (casing + line + origin/destination markers) from geometry you already have; `origin`/`destination` (+ `provider`, default `"nika"`) resolve one asynchronously instead via `OmMap.registerRoutingProvider`. `follow="fit-route"` auto-fits the camera once it resolves. `<om-layer type="Tracking" get-position="[$lng,$lat]">` renders one moving entity with bearing-derived rotation (`bearing-field`, default `"bearing"`; `icon="arrow|car|motorcycle"` picks the marker shape, tinted by `color`) and glides smoothly between position updates (`interpolate-ms`, default `1000`) rather than jumping — `follow="follow"` eases the camera along with it. Live position data arrives through the ordinary `data`/`source` mechanism, same as any layer — no separate tracking subscription API to learn. Link a route to its rider with `progress-from` and pick a tail mode: `tail="none"` (client view — only current position to destination renders) or `tail="dim"` (operator view — the traveled portion darkens), split at the marker's interpolated position per frame. Guide (incl. a keyless OSRM adapter recipe and per-engine notes): [docs/routing.md](docs/routing.md).
+
 ### Widgets get a real runtime API
 
 Custom widget scripts receive `ctx`: layer metadata, `viewport` (bounds/zoom/project), the current `selection`, `emit()`, and data access — `ctx.data(id)`, `ctx.dataInViewport(id)`, `ctx.stats(id, field)` (count/min/max/mean/stddev/percentiles/histogram, viewport-scoped on request). Declare `watch` tokens (`data:quakes viewport selection layers`) and the runtime re-renders you only when relevant state changes. `vegaEmbed` and `d3` are available as globals for charts.
@@ -325,13 +327,13 @@ The library reports one **deployment-scoped** usage snapshot per map per page lo
 
 ## Not implemented yet (honestly)
 
-Mapbox GL basemaps, depth-interleaved 3D compositing, globe projection, SSE transport, multi-field filters, `dblclick` behaviors, the `transform` data pipeline, the typed fluent builder, and stories/draw as React components (both work via the HTML manifest). On `pick-features`: instanced (i3dm) tiles keep tile-granularity picking, and `feature-styles`' `opacity` below 1 is still being validated. On BIM: clash detection is bounding-box only (no mesh-level test, and it cannot tell a resolved penetration from a collision), there is no BCF export, no equivalent of Navisworks' Auto Reveal, and prepared tilesets converted before the `bbox*` columns existed cannot take part in a clash pass — `strength` tinting and `opacity: 0` (hide, a shader discard) work. On the measure widget's `volume` mode: the per-cell grid integration measures against the map's active terrain DEM only — measuring against an imported design surface or a previous survey (period-over-period reconciliation) and a cut/fill heat-map overlay are not implemented yet, and a snapped footprint vertex takes the matched feature's horizontal position only — its exact elevation is not threaded through (see **XY snapping** above).
+Mapbox GL basemaps, depth-interleaved 3D compositing, globe projection, SSE transport, `dblclick` behaviors, the `transform` data pipeline, the typed fluent builder, and stories/draw as React components (both work via the HTML manifest). On `pick-features`: instanced (i3dm) tiles keep tile-granularity picking, and `feature-styles`' `opacity` below 1 is still being validated. On BIM: clash detection is bounding-box only (no mesh-level test, and it cannot tell a resolved penetration from a collision), there is no BCF export, no equivalent of Navisworks' Auto Reveal, and prepared tilesets converted before the `bbox*` columns existed cannot take part in a clash pass — `strength` tinting and `opacity: 0` (hide, a shader discard) work. On the measure widget's `volume` mode: the per-cell grid integration measures against the map's active terrain DEM only — measuring against an imported design surface or a previous survey (period-over-period reconciliation) and a cut/fill heat-map overlay are not implemented yet, and a snapped footprint vertex takes the matched feature's horizontal position only — its exact elevation is not threaded through (see **XY snapping** above).
 
 ## Going deeper
 
 | | |
 |---|---|
-| [docs/react.md](docs/react.md) · [docs/basemaps.md](docs/basemaps.md) · [docs/testing.md](docs/testing.md) · [docs/live-data.md](docs/live-data.md) · [docs/image-overlays.md](docs/image-overlays.md) · [docs/3d-assets.md](docs/3d-assets.md) · [docs/stories.md](docs/stories.md) · [docs/telemetry.md](docs/telemetry.md) | Consumer guides |
+| [docs/react.md](docs/react.md) · [docs/basemaps.md](docs/basemaps.md) · [docs/testing.md](docs/testing.md) · [docs/live-data.md](docs/live-data.md) · [docs/image-overlays.md](docs/image-overlays.md) · [docs/3d-assets.md](docs/3d-assets.md) · [docs/stories.md](docs/stories.md) · [docs/routing.md](docs/routing.md) · [docs/telemetry.md](docs/telemetry.md) | Consumer guides |
 | [CHANGELOG.md](CHANGELOG.md) | Version-by-version release notes |
 | [llms.txt](llms.txt) | The agent-facing quick reference |
 | `skills/onlymapjs` | Installable LLM skill for OnlyMapJS authoring |

package/dist/{LercDecode.es-D5in29tf.js → LercDecode.es-C331HMjV.js}

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

package/dist/attribute-resolution.d.ts

@@ -1,4 +1,4 @@
-import type { LayerMeta, LayerFilter } from "./ir";
+import type { LayerMeta, LayerFilter, LayerCategoryFilter } from "./ir";
 import type { LayerSchema, PropDescriptor } from "./layer-registry";
 import type { Shape } from "./expr";
 /** Sweeps the shared caches down to exactly the keys still referenced by the current manifest (Q4). */
@@ -19,9 +19,12 @@ export declare const RESERVED_ATTRS: Set<string>;
  * Filtering (spec: "Filtering") is universal across every layer type — not
  * tied to one schema's props like `pickable` — so it's resolved directly
  * here rather than via `schema.props`, and excluded from the typo-check the
- * same way `RESERVED_ATTRS` is. Single-field only (`filterSize`/`categorySize`
- * fixed at 1); the spec's own example is single-field, and the "up to 4
- * dimensions" case is a documented future extension.
+ * same way `RESERVED_ATTRS` is. `filter-field`/`filter-range`/
+ * `filter-soft-range` are the single-dimension surface; `filter-fields` is
+ * the multi-dimension one (up to 4 — `DataFilterExtension`'s own ceiling),
+ * a JSON array of `{field, range, softRange?}` objects. Categorical
+ * filtering (`filter-category`/`filter-categories`) is a separate slot,
+ * unrelated to the numeric dimension count.
  */
 export declare const FILTER_ATTRS: Set<string>;
 /**
@@ -51,14 +54,51 @@ export interface LayerDashSpec {
  * ignore it otherwise — the invisible-attribute class of confusion).
  */
 export declare function applyDashWiring(props: Record<string, unknown>, spec: LayerDashSpec, layerType: string, warnLabel: string): void;
-/** Already-coerced filter declaration — attribute strings (DOM front-end) or typed values (programmatic front-end). */
+/** One numeric filter dimension, already-coerced (attribute strings or typed programmatic values). */
+export interface LayerFilterFieldSpec {
+    field: string;
+    range?: [number, number];
+    softRange?: [number, number];
+}
+/**
+ * Already-coerced filter declaration — attribute strings (DOM front-end) or
+ * typed values (programmatic front-end). `filterField`/`filterRange`/
+ * `filterSoftRange` are the original single-dimension surface (still fully
+ * supported, zero migration needed); `filterFields` is the multi-dimension
+ * one. If both are present `filterFields` wins outright (validation warns
+ * separately about the ambiguity) — `applyFilterWiring` never merges them
+ * into a combined set, since which slot the singular field would occupy is
+ * not a well-defined question.
+ */
 export interface LayerFilterSpec {
     filterField?: string;
     filterRange?: [number, number];
     filterSoftRange?: [number, number];
+    filterFields?: LayerFilterFieldSpec[];
     filterCategoryField?: string;
     filterCategories?: unknown[];
+    filterCategoryFields?: LayerCategoryFilterFieldSpec[];
 }
+/** One categorical filter dimension, already-coerced. `categories` absent = declared but not yet ranged, mirroring the numeric case — dropped from the active filter with a warning, since deck.gl's category mechanism has no "wide open" value to fall back to (unlike a numeric [-Infinity, Infinity] range). */
+export interface LayerCategoryFilterFieldSpec {
+    field: string;
+    categories?: (string | number)[];
+}
+/**
+ * Parses the DOM front-end's `filter-fields` JSON attribute — an array of
+ * `{field, range, softRange?}` objects — dropping (with a warning, never a
+ * throw) any entry that isn't shaped like one, so a single malformed entry
+ * degrades to "that dimension is missing" rather than breaking the whole
+ * layer's filter or crashing the reconcile.
+ */
+export declare function parseFilterFieldsAttr(raw: string, warnLabel: string): LayerFilterFieldSpec[] | undefined;
+/**
+ * Parses the DOM front-end's `filter-category-fields` JSON attribute — an
+ * array of `{field, categories}` objects — same defensive shape as
+ * `parseFilterFieldsAttr`: a malformed entry is dropped with a warning, never
+ * a throw.
+ */
+export declare function parseFilterCategoryFieldsAttr(raw: string, warnLabel: string): LayerCategoryFilterFieldSpec[] | undefined;
 /**
  * GPU filter wiring (spec: "Filtering"), shared by both front-ends (HU2).
  * `filterRange` is a plain prop (not an accessor): the filter-layer action
@@ -78,6 +118,23 @@ export interface LayerFilterSpec {
  * category filter re-mounts the extension — churn accepted for the rare
  * case, never for the common numeric one.
  *
+ * `filterSize` (1-4, the count of numeric dimensions) is a deck.gl
+ * *constructor* option that compiles straight into a GLSL define
+ * (`DATAFILTER_TYPE float|vec2|vec3|vec4` — verified against
+ * `@deck.gl/extensions`' own source, not assumed), the same category of
+ * shader-recompile-on-change as `categorySize` above — and empirically
+ * confirmed safe to change on an already-mounted layer the same way
+ * categorySize already is (a `DataFilterExtension` config-value change,
+ * NOT an `extensions` array composition change — the latter is the
+ * documented-elsewhere case that corrupts state, e.g. adding a
+ * `ClipBoxExtension` alongside an already-mounted one; this isn't that).
+ * So `filterSize` is simply `min(dims.length, 4)`, recomputed fresh every
+ * reconcile, no special remount handling needed. The one thing v1
+ * deliberately does NOT support is an author changing the number of
+ * *declared* dimensions through the `filter-layer` action's merge path —
+ * that's a `filter-layer` contract choice (see `actions.ts`), not a
+ * limitation of this function.
+ *
  * The unfiltered baseline is a FUNCTION accessor (a buffer of zeros, 4
  * bytes/row) plus a baseline trigger — never deck's constant-0 default.
  * Two empirically-found deck behaviors force this: trigger keys absent
@@ -88,8 +145,27 @@ export interface LayerFilterSpec {
  * one transition that recomputes reliably, so every state a layer can
  * reach — unfiltered, authored filter, runtime populate sweep — is
  * buffer-backed.
+ *
+ * `categorySize` (0-4) mirrors `filterSize` structurally — same packed
+ * single-value-at-1/array-at->1 accessor and prop shape, same truncate-past-4
+ * behavior — but is a GENUINELY different mechanism (deck.gl's discrete
+ * bitmask membership test, `FilterCategory = number | string`, NOT a range
+ * comparison), so it's wired independently and returned separately: a layer
+ * can have an active numeric filter, an active categorical filter, both, or
+ * neither, and `ctx`'s coherence rule ANDs whichever are present. Unlike
+ * `filterSize` there is no floor of 1 — 0 (unmounted) is category's true
+ * idle state, so introducing or clearing categorical filtering re-mounts the
+ * extension (see the doc comment above); a category dimension with no
+ * `categories` list is dropped from the active set entirely (warned), since
+ * there's no "wide open" value the way a numeric range has [-Infinity,
+ * Infinity] — an empty/absent keep-list has no honest non-excluding meaning
+ * in a membership test.
  */
-export declare function applyFilterWiring(props: Record<string, unknown>, updateTriggers: Record<string, string>, shape: Shape, spec: LayerFilterSpec, warnLabel: string): LayerFilter | undefined;
+export interface LayerFilterResult {
+    filter?: LayerFilter;
+    categoryFilter?: LayerCategoryFilter;
+}
+export declare function applyFilterWiring(props: Record<string, unknown>, updateTriggers: Record<string, string>, shape: Shape, spec: LayerFilterSpec, warnLabel: string): LayerFilterResult;
 /**
  * Standard global HTML attributes an author (or the library itself, e.g.
  * OmLayerElement setting `style.display = "none"`) may set for reasons
@@ -135,5 +211,7 @@ export interface ResolvedAttributes {
     liveKeys: Set<string>;
     /** The layer's active declarative filter, if `filter-field`/`filter-range` are present. */
     filter?: LayerFilter;
+    /** The layer's active categorical filter, if `filter-category`/`filter-category-fields` are present. */
+    categoryFilter?: LayerCategoryFilter;
 }
 export declare function resolveLayerAttributes(el: Element, schema: LayerSchema, shape: Shape): ResolvedAttributes;

package/dist/{basemap-C0pFT3AO.js → basemap-NN5SYEaS.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-Cxo9mCw_.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-BUp4hR6r.js";
 const Cd = Math.PI / 180, gy = 180 / Math.PI;
 function em(Pe, Q = 0) {
   const me = Math.min(180, Pe) * Cd;

package/dist/ctx.d.ts

@@ -5,7 +5,7 @@
  * viewport (for projection) crosses that boundary, per the spec's own
  * rationale.
  */
-import type { LayerIR, LayerFilter } from "./ir";
+import type { LayerIR, LayerFilter, LayerCategoryFilter } from "./ir";
 import type { RuntimeCore } from "./runtime-core";
 import type { Selection } from "./selection";
 import { type Stats } from "./stats";
@@ -21,6 +21,8 @@ export interface LayerMetaSnapshot {
     dataUrl?: string;
     /** The layer's active declarative filter, if any (spec: "Filtering") — read by the built-in `filter` widget. */
     filter?: LayerFilter;
+    /** The layer's active categorical filter, if any — independent of `filter`, read by the built-in `filter` widget's categorical mode. */
+    categoryFilter?: LayerCategoryFilter;
 }
 export interface DataOpts {
     /** Set `false` to bypass the layer's active declarative filter (spec: "Filter-aware stats & data (the coherence rule)"). Default `true`. */

package/dist/declarative-filter.d.ts

@@ -1,12 +1,21 @@
 /**
  * CPU-side mirror of the GPU `DataFilterExtension` test (spec: "Filter-aware
  * stats & data (the coherence rule)") — `ctx.stats`/`ctx.dataInViewport`
- * apply the SAME field+range test by default, so a chart/stat reflects what
- * the map visibly shows. A row whose field isn't a finite number is treated
- * as filtered-out, matching the GPU path (a non-numeric `getFilterValue`
- * result can't land inside any finite `filterRange`).
+ * apply the SAME field+range/category test(s) by default, so a chart/stat
+ * reflects what the map visibly shows. A row whose field isn't a finite
+ * number (numeric) or isn't in the keep-list (categorical) is treated as
+ * filtered-out, matching the GPU path. With more than one dimension of
+ * EITHER kind a row passes only if every dimension's test passes (AND
+ * across dimensions) — the same semantics deck.gl's own packed
+ * `filterRange`/`filterCategories` arrays apply GPU-side. Numeric and
+ * categorical are independent mechanisms (see `applyFilterWiring`'s doc
+ * comment) but combine the same way: a row must pass BOTH kinds when both
+ * are active on a layer.
  */
-import type { Shape, LayerFilter } from "./ir";
+import type { Shape, LayerFilter, LayerCategoryFilter } from "./ir";
 export declare function applyDeclarativeFilter(rows: readonly unknown[], shape: Shape, filter: LayerFilter): unknown[];
 /** The same test as a reusable predicate — the columnar viewport filter runs it inside its index-aligned loop. */
 export declare function declarativeFilterPredicate(shape: Shape, filter: LayerFilter): (row: unknown) => boolean;
+export declare function applyDeclarativeCategoryFilter(rows: readonly unknown[], shape: Shape, categoryFilter: LayerCategoryFilter): unknown[];
+/** Categorical twin of `declarativeFilterPredicate` — set membership instead of a range test. */
+export declare function declarativeCategoryFilterPredicate(shape: Shape, categoryFilter: LayerCategoryFilter): (row: unknown) => boolean;

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

@@ -416,6 +416,26 @@ declare global {
             layerId: string;
             tileset: unknown;
         }>;
+        /** A Route layer finished resolving its route (direct geometry or a
+         *  RoutingProvider round-trip) — detail carries the authored layer id and
+         *  the normalized route (geometry/distanceMeters/durationSec/legs/bounds),
+         *  so a page can read a provider-resolved route without re-fetching it. */
+        "om-route-resolved": CustomEvent<{
+            layerId: string;
+            route: {
+                geometry?: {
+                    type: "LineString";
+                    coordinates: [number, number][];
+                };
+                distanceMeters?: number;
+                durationSec?: number;
+                legs?: {
+                    distanceMeters: number;
+                    durationSec: number;
+                }[];
+                bounds?: [[number, number], [number, number]];
+            };
+        }>;
     }
 }
 export {};

package/dist/{geoparquet-By98JVB0.js → geoparquet-Dmyu5Oou.js}

@@ -1,4 +1,4 @@
-import { r as p, n as d } from "./index-Cxo9mCw_.js";
+import { r as p, n as d } from "./index-BUp4hR6r.js";
 function g(t) {
   if (t == null) return !0;
   const e = t, n = e.id?.code;