@nika-js/onlymap 0.5.1 → 0.5.3

package/dist/onlymapjs.js

@@ -1,82 +1,97 @@
-import { ay as e, az as r, aA as o, aB as t, aC as l, aD as b, an as i, aE as n, aF as S, aG as L, aH as T, aI as E, aJ as g, aK as y, aL as A, aM as d, aN as m, aO as p, aP as c, aQ as I, aR as _, aS as D, aT as u, am as O, aU as M, au as f, aV as F, W as C, aW as N, aX as P, aY as B, aZ as R, a_ as h, a$ as x, b0 as G, b1 as W, b2 as v, b3 as w, b4 as H, b5 as U, b6 as Y, b7 as X, b8 as k, b9 as z, ba as J, bb as K, bc as V, bd as j, be as q, bf as Q, bg as Z, bh as $, bi as aa, bj as sa, bk as ea, bl as ra, bm as oa, bn as ta, bo as la, bp as ba, bq as ia, br as na, bs as Sa, bt as La, bu as Ta, bv as Ea, bw as ga, bx as ya, by as Aa, bz as da, bA as ma, bB as pa, bC as ca, bD as Ia, bE as _a, bF as Da, bG as ua, bH as Oa, bI as Ma } from "./index-ppCRU8Eb.js";
+import { ay as e, az as r, aA as t, aB as o, aC as b, aD as i, an as l, aE as n, aF as S, aG as L, aH as T, aI as E, aJ as g, aK as m, aL as A, aM as d, aN as p, aO as c, aP as _, aQ as y, aR as M, aS as u, aT as I, am as D, aU as O, au as f, aV as N, aW as P, aX as R, W as F, aY as h, aZ as C, a_ as B, a$ as G, b0 as U, b1 as W, b2 as x, b3 as v, b4 as w, b5 as Y, b6 as H, b7 as X, b8 as k, b9 as z, ba as J, bb as K, bc as V, bd as Q, be as j, bf as q, bg as Z, bh as $, bi as aa, bj as sa, bk as ea, bl as ra, bm as ta, bn as oa, bo as ba, bp as ia, bq as la, br as na, bs as Sa, bt as La, bu as Ta, bv as Ea, bw as ga, bx as ma, by as Aa, bz as da, bA as pa, bB as ca, bC as _a, bD as ya, bE as Ma, bF as ua, bG as Ia, bH as Da, bI as Oa, bJ as fa, bK as Na, bL as Pa, bM as Ra, bN as Fa, bO as ha, bP as Ca, bQ as Ba, bR as Ga, bS as Ua, bT as Wa, bU as xa, bV as va, bW as wa, bX as Ya } from "./index-BoAq5XsU.js";
 export {
   e as ALL_POSITION_VALUES,
   r as AUDIT_EXEMPTIONS,
-  o as AccessorCache,
-  t as BitmapLayer,
-  l as COORDINATE_SYSTEM,
-  b as CompileError,
-  i as CompositeLayer,
+  t as AccessorCache,
+  o as BitmapLayer,
+  b as COORDINATE_SYSTEM,
+  i as CompileError,
+  l as CompositeLayer,
   n as DEFAULT_AUDIT_WIDTHS,
   S as DEFAULT_FOLD_BREAKPOINT_PX,
   L as EDGE_TOLERANCE_PX,
   T as FOLD_HYSTERESIS_PX,
   E as FOLD_SIDES,
   g as GeoJsonLayer,
-  y as IconLayer,
+  m as IconLayer,
   A as LEGACY_POSITION_ALIASES,
   d as LIGHTING_PRESET_NAMES,
-  m as Layer,
-  p as LayerExtension,
-  c as MANAGED_SLOTS,
-  I as MapController,
-  _ as OmMap,
-  D as ScatterplotLayer,
-  u as ScenegraphLayer,
-  O as SimpleMeshLayer,
-  M as Tile3DLayer,
+  p as Layer,
+  c as LayerExtension,
+  _ as MANAGED_SLOTS,
+  y as MapController,
+  M as OmMap,
+  u as ScatterplotLayer,
+  I as ScenegraphLayer,
+  D as SimpleMeshLayer,
+  O as Tile3DLayer,
   f as TileLayer,
-  F as WIDGET_STYLE_KEY_NAMES,
-  C as WebMercatorViewport,
-  N as arrowTableToColumnar,
-  P as asRows,
+  N as UNIT_SYSTEMS,
+  P as WGS84_MEAN_RADIUS_M,
+  R as WIDGET_STYLE_KEY_NAMES,
+  F as WebMercatorViewport,
+  h as arrowTableToColumnar,
+  C as asRows,
   B as auditLayout,
-  R as compileExpression,
-  h as compileFullJsAccessorBlockInSandbox,
-  x as computeTimeline,
-  G as configureBasemap,
-  W as configureData,
-  v as configureLicense,
-  w as configureTelemetry,
+  G as compileExpression,
+  U as compileFullJsAccessorBlockInSandbox,
+  W as computeTimeline,
+  x as configureBasemap,
+  v as configureData,
+  w as configureLicense,
+  Y as configureTelemetry,
   H as descriptorToIR,
-  U as destroySandbox,
-  Y as evaluateInSandbox,
-  X as foldDrawerStyle,
-  k as foldPanelStyle,
-  z as foldSideForSlot,
-  J as foldToggleSlot,
-  K as foldToggleStyle,
-  V as getBasemap,
-  j as getEntitlements,
-  q as getLayerSchema,
-  Q as getTerrain,
-  Z as isBrowser,
-  $ as isColumnar,
-  aa as isStoreToken,
-  sa as loadRasterModule,
-  ea as mountForTest,
-  ra as normalizeData,
-  oa as parseDurationMs,
-  ta as parseTerrainAttrs,
-  la as parseWidgetStyle,
-  ba as registerAction,
-  ia as registerBasemap,
-  na as registerFormat,
-  Sa as registerLayer,
-  La as registerSource,
-  Ta as registerTerrain,
-  Ea as registerWidget,
-  ga as resolveFoldBreakpointPx,
-  ya as resolveLighting,
-  Aa as resolveSlot,
-  da as rowAt,
-  ma as sandboxHtml,
-  pa as settleLayout,
-  ca as shouldFoldAtWidth,
-  Ia as slotContainerStyle,
-  _a as slotLayout,
-  Da as snapshotIR,
-  ua as solarAzElDegrees,
-  Oa as validateManifest,
-  Ma as validateManifestString
+  X as destroySandbox,
+  k as distanceMeters,
+  z as evaluateInSandbox,
+  J as foldDrawerStyle,
+  K as foldPanelStyle,
+  V as foldSideForSlot,
+  Q as foldToggleSlot,
+  j as foldToggleStyle,
+  q as formatArea,
+  Z as formatLength,
+  $ as getBasemap,
+  aa as getEntitlements,
+  sa as getLayerSchema,
+  ea as getMeasureRadiusMeters,
+  ra as getTerrain,
+  ta as isBrowser,
+  oa as isColumnar,
+  ba as isStoreToken,
+  ia as loadRasterModule,
+  la as midpoint,
+  na as mountForTest,
+  Sa as niceNumber,
+  La as normalizeData,
+  Ta as parseDurationMs,
+  Ea as parseTerrainAttrs,
+  ga as parseUnitSystem,
+  ma as parseWidgetStyle,
+  Aa as pathLengthMeters,
+  da as registerAction,
+  pa as registerBasemap,
+  ca as registerFormat,
+  _a as registerLayer,
+  ya as registerSource,
+  Ma as registerTerrain,
+  ua as registerWidget,
+  Ia as resolveFoldBreakpointPx,
+  Da as resolveLighting,
+  Oa as resolveSlot,
+  fa as ringAreaMeters2,
+  Na as ringEnclosesPole,
+  Pa as ringPerimeterMeters,
+  Ra as rowAt,
+  Fa as sandboxHtml,
+  ha as scaleBarStep,
+  Ca as setMeasureRadiusMeters,
+  Ba as settleLayout,
+  Ga as shouldFoldAtWidth,
+  Ua as slotContainerStyle,
+  Wa as slotLayout,
+  xa as snapshotIR,
+  va as solarAzElDegrees,
+  wa as validateManifest,
+  Ya as validateManifestString
 };

package/dist/{raster-D43jYSib.js → raster-DO-Ex2Lb.js}

@@ -1,5 +1,5 @@
 import Ae from "./index-CW1n5LdO.js";
-import { ak as Mt, al as Rt, am as tt, an as nt, ao as zt, b as Ft, ap as Dt, l as Ee, aq as Nt, d as Ut, ar as Bt, as as Gt, at as Kt, au as rt } from "./index-ppCRU8Eb.js";
+import { ak as Mt, al as Rt, am as tt, an as nt, ao as zt, b as Ft, ap as Dt, l as Ee, aq as Nt, d as Ut, ar as Bt, as as Gt, at as Kt, au as rt } from "./index-BoAq5XsU.js";
 import { w as _t } from "./mgrs-BY9bIvp4.js";
 function Xt(e, t, n) {
   const { projectedCorners: r } = t, { topLeft: o, topRight: i, bottomRight: s, bottomLeft: a } = r, l = n(o[0], o[1]), c = n(i[0], i[1]), u = n(s[0], s[1]), h = n(a[0], a[1]), p = [
@@ -2378,7 +2378,7 @@ D.set(P.Zstd, () => import("./zstd-jXobGRcq.js").then((e) => e.decode));
 D.set(P.Jpeg, () => Promise.resolve(Ce));
 D.set(P.Jpeg6, () => Promise.resolve(Ce));
 D.set(P.Webp, () => Promise.resolve(Ce));
-D.set(P.Lerc, () => import("./lerc-C-D0ZLmp.js").then((e) => e.l).then((e) => e.decode));
+D.set(P.Lerc, () => import("./lerc-n0GaWEmL.js").then((e) => e.l).then((e) => e.decode));
 async function je(e, t, n) {
   const r = D.get(t);
   if (!r)

package/dist/units.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Units (spec: issue #20 "Measure widget"). The shared length/area unit system
+ * for the measure widget AND the scale-bar (which refactors onto this module
+ * and gains a `units` attribute — it was metric-only with a hardcoded steps
+ * table). Adopts GL's shared scale-units precedent: the exact metric constants
+ * (0.3048 m/ft, 1609.344 m/mi, 1852 m/nmi), denomination crossover (m→km at
+ * 1000, ft→mi at 5280 ft), and the log10-based 1/2/3/5/10 "nice number" — NOT
+ * MapLibre's digit-count trick, which mis-rounds sub-unit spans.
+ */
+export type UnitSystem = "metric" | "imperial" | "nautical";
+export declare const UNIT_SYSTEMS: readonly UnitSystem[];
+export declare const M_PER_FT = 0.3048;
+export declare const M_PER_MI = 1609.344;
+export declare const M_PER_NMI = 1852;
+/** Validate a unit-system string; `null` for anything not in {@link UNIT_SYSTEMS}. */
+export declare function parseUnitSystem(raw: string | null | undefined): UnitSystem | null;
+/** Format a length (meters) for a unit system, with denomination crossover. */
+export declare function formatLength(meters: number, system?: UnitSystem): string;
+/**
+ * Format an area (m²), with denomination crossover. Metric: m²/ha/km².
+ * Imperial: ft²/acres/mi². Nautical falls back to metric for area (open
+ * question 1 — nmi² is not a denomination users read).
+ */
+export declare function formatArea(m2: number, system?: UnitSystem): string;
+/**
+ * The largest 1/2/3/5 ×10ⁿ value ≤ `value` (GL's log10 "nice number"). Used by
+ * the scale bar to snap its bar to a round distance. log10-based, so it is
+ * correct for sub-unit spans (`value < 1`) where a digit-count rule breaks.
+ */
+export declare function niceNumber(value: number): number;
+/**
+ * Scale-bar helper: given the max distance (meters) that fits the bar's pixel
+ * budget, return the nice round distance to actually draw and its label, in the
+ * chosen unit system. Metric snaps in meters/km, imperial in ft/mi, nautical in
+ * nmi — the crossover handled by {@link formatLength}.
+ */
+export declare function scaleBarStep(maxMeters: number, system?: UnitSystem): {
+    meters: number;
+    label: string;
+};

package/dist/validation.d.ts

@@ -12,6 +12,16 @@ export interface ValidationResult {
     errors: ValidationEntry[];
     warnings: ValidationEntry[];
 }
+/**
+ * A scalar/shorthand attribute value that is actually a data-driven accessor
+ * expression — a `$field` reference or a `scale()`/`clamp()`/`lerp()`/
+ * `colorRamp()` call. Scalar props take a CONSTANT; an expression here doesn't
+ * coerce (deck.gl gets a string/NaN and silently falls back to defaults — the
+ * "black squares" / invisible-layer class of bug), and the value belongs in a
+ * `get-*` accessor instead. Word-boundary on the function names so a literal
+ * like "grayscale(" doesn't false-match.
+ */
+export declare function looksLikeAccessorExpression(raw: string): boolean;
 /**
  * Validates a manifest already parsed into a DOM tree — a live `<om-map>`
  * (mounted or not) or a detached `Document`/`DocumentFragment` (what

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.5.1";
+export declare const LIBRARY_VERSION = "0.5.3";

package/llms.txt

@@ -19,14 +19,16 @@ OnlyMapJS is NOT raw deck.gl and NOT generic HTML/JSX. The rules below are the d
 - A literal color inside a `get-*` accessor is a string IN the expression — quote it: `get-line-color="'#ffffff'"` or an RGBA array `get-line-color="[255,255,255,200]"`. Bare `get-line-color="#ffffff"` is an expression parse error (plain attributes like `color="#dc2626"` take bare hex, accessors do not).
 - Inline event handlers (`onclick="..."`) are rejected. Use `data-emit` attributes (`<span data-emit="hide-overlay" data-target="popup1">`) or `addEventListener` inside a `<script type="om/widget">` block where `ctx` is in scope.
 - `scale()` requires an explicit `domain=`: `get-fill-color="scale($depth, sequential, ['#ffffcc','#800026'], domain=[0,700])"`. A missing domain is a validation error.
+- `scale()`/`clamp()`/`lerp()`/`$field` expressions go ONLY in `get-*` accessors — NEVER in a scalar attribute (`radius-min-pixels`, `point-radius-min-pixels`, `opacity`, `line-width-min-pixels`, `color`, …). A data-driven expression in a scalar doesn't coerce, so the layer silently renders defaults (invisible / black points); validation errors on it. Data-driven size/width/opacity/color → the matching `get-*` accessor (`get-radius`, `get-fill-color`, …); scalars take a constant floor/value.
 - `id` is required on every `<om-layer>`. `label` and `color` feed the legend; an explicit `get-fill-color` overrides `color` for rendering (both together is valid and common). The legend widget also reads `get-fill-color` itself: a `sequential`/`diverging` scale renders as a gradient ramp with domain labels, a `threshold` scale as discrete class ranges, and an equality ternary chain (`$f == 'a' ? '#c1' : '#c2'`) as a category palette — write those canonical shapes and the legend describes the symbology automatically.
 - Full JavaScript in accessor blocks needs the `js` attribute on the layer (`<om-layer js>` + `<script type="om/accessors">`). Without it, blocks are restricted to `export const name = d => <expression>` — no statements, no loops, no nested functions.
+- To capture where the user CLICKS on the map (a measure tool, drop-a-pin, a custom rectangle/circle AOI, snap-to-feature), listen for the `om-map-point` event on `<om-map>`: `mapEl.addEventListener('om-map-point', e => { const { coordinate, kind } = e.detail; })` — `coordinate` is `[lng,lat]` (or `null` off-globe), `kind` is `"click"`|`"hover"`, and it fires on every click/hover including empty-map clicks. Do NOT reach for deck.gl internals (`mapEl.getMap()`, `.deckInstance`, `.deck.viewManager`) or unproject canvas pixels — those are not exposed on `<om-map>` and return nothing. The built-in `draw` widget handles polygon/line/point sketching; `om-map-point` is for tools it doesn't cover.
 
 ## Element vocabulary
 
 - `<om-map center="[lng, lat]" zoom="11" pitch="55" bearing="20" basemap="positron">` — the root. Give it a height (`om-map { display:block; height:100vh }` with `html,body{height:100%}`, or a sized container) — a custom element is display:inline by default and collapses to zero size; with none set, the library falls back to display:block + a 400px floor so a bare map still shows (any height you DO set wins over the floor, including one below 400px), and a collapsed map logs a console warning. A map hidden on purpose (`hidden`, or inside a `display:none` panel) stays hidden and does not warn. `basemap` accepts a free preset (`liberty`, `bright`, `positron`, `dark-matter`, `voyager`, `osm` — no keys; or `maptiler-streets`/`maptiler-dataviz`/`maptiler-satellite` with `basemap-key="…"` or `OmMap.configureBasemap({ maptilerKey })`), `maplibre` (bare demo style), a style URL (e.g. a MapTiler-customized style; any scheme fetch supports, including desktop asset protocols like Tauri's, query strings fine), or `none` (standalone canvas). The attribute is LIVE — writing it switches the basemap in place (camera + layers survive); the `set-basemap {basemap}` action and `<om-widget type="basemap-switcher" options="positron dark-matter osm">` do the same. Register more via `OmMap.registerBasemap(name, { style })`. Required provider attribution renders automatically (`attribution="false"` opts out). `pitch`/`bearing` tilt the initial camera (use for 3D content). Terrain: `terrain="terrarium"` (keyless AWS DEM; also `maptiler-terrain` with a key, a raw `{z}/{x}/{y}` DEM URL + `terrain-decoder="terrarium|mapbox-rgb|<JSON>"`, or `off`) raises a 3D surface — geographic layers DRAPE onto it automatically (per-layer `terrain="drape|offset|off"` overrides; 3D-model layers sit ON it), `terrain-exaggeration` scales relief, `terrain-texture` drapes imagery; terrain REPLACES an active basemap while on (restored when off); `set-terrain` action, `terrain` watch token, `OmMap.registerTerrain(name, {...})` for more sources. Scene lighting for 3D content: `lighting="daylight|studio|flat|custom"` (absent = deck defaults) with `lighting-ambient`/`lighting-sun`/`lighting-sun-azimuth`/`lighting-sun-elevation`/`lighting-camera` overrides and `lighting-sun-date` (ISO/epoch — solar-position sun computed at the map center, wins over azimuth/elevation); attribute-backed (undoable, live-editable), story-steppable via the `set-lighting {lighting, sunAzimuth, ...}` action (`lighting="default"` removes the attribute set; a bare preset is a clean reset — stale overrides clear), native UI via `<om-widget type="lighting">` (preset radios + tuning sliders), widget watch token `lighting`. GeoJsonLayer extrudes polygons declaratively: `extruded get-elevation="$height"` (+ `wireframe`). `widgets-hidden` attribute (or the `set-widgets-visible {visible}` action / `<om-widget type="widgets-toggle">` button) hides every widget WITHOUT destroying state — attribution never hides (license); transient (not an undo step) but story-steppable, so a step can clear chrome for a cinematic take. Slots auto-dim while an open `<om-overlay>` popup covers them (position stability over the popup dodging; `widgets-dim="off"` disables). `validate` attribute enables live validation + on-page error panel. Include a `map-id="<random UUID>"` on complete pages (identifies the map artifact for usage telemetry — not a visitor id; the page author deletes it to opt out); `telemetry="off"` disables usage telemetry + library-error reporting for the map (global: `OmMap.configureTelemetry({ disabled: true })`; schema: docs/telemetry.md). Free plan limits: 5 layers, 25k rows per layer — layers past a limit don't render and validation says why; a `license-key="om_live_…"` attribute (publishable, origin-restricted) or `OmMap.configureLicense(key)` lifts limits and removes the corner badge. When a user's map exceeds free limits, say so and point at the validation message rather than silently restructuring their data. Events on the element: `om-map-ready` (boot complete; `await mapEl.ready` is the promise twin), `om-validation-error`, `om-view-changed` (camera settled after a move, debounced; `detail = {longitude, latitude, zoom, pitch, bearing, origin}` where `origin` is `"user"` for gesture bursts vs `"programmatic"` for API/story moves — the camera-persistence hook, and the echo-suppression signal when syncing camera state to an app store), `om-map-point` (`detail = {coordinate: [lng,lat]|null, kind}` — every click/hover map coordinate incl. empty-map clicks, for custom capture tools beyond the draw widget), `om-tileset-load` (`detail = {layerId, tileset}` — a Tile3DLayer's live deck Tileset3D, for tools needing the real tileset like region export). `MapController` mirrors these as `onViewChange`/`onMapPoint`/`onTilesetLoad` options. `await mapEl.snapshot()` returns a canvas-only PNG dataURL of the scene (basemap + layers at device pixels; `{as:"blob"}` for files) — DOM widgets/overlays/attribution are NOT captured, so exports must render provider credits themselves.
 - `<om-layer id="..." type="ScatterplotLayer" data="./points.json">` — any deck.gl layer class by `type` (all 33 bundled, plus the native `COGLayer` raster type), plus `PopupLayer` (WebGL badges/labels at scale: `layout="badge|pin-label|card"`, `min-zoom`/`max-zoom`). Every type's full attribute list ships in the package's `onlymapjs.html-data.json` — consult it instead of guessing attribute names or reading the minified dist. TextLayer's default font atlas covers ASCII only: set `character-set` when label text carries other glyphs (`—`, `·`, accents) or deck warns and renders them blank. External layer classes register via `OmMap.registerLayer({type, deckClass, props})` — build them on `@nika-js/onlymap/deck` (the bundled `CompositeLayer`/`TileLayer`/… re-exports), never a separately-installed deck.gl (different class hierarchy, breaks in the renderer); function-valued props ride the subclass's `static defaultProps`; register at module top level BEFORE the manifest mounts (see docs/custom-layers.md). Data: `data` URL (JSON, GeoJSON, CSV/TSV `.csv` — parsed to typed columns — Shapefile `.shp` (+`.dbf` attributes) and KML `.kml` as GeoJSON features, CityJSON `.city.json` / CityJSONSeq `.city.jsonl` (semantic 3D city models — 3DBAG, PLATEAU — decoded to one of two shapes by the `data` URL, no CityJSON layer type: default → extruded footprints, `type="GeoJsonLayer" extruded get-elevation="$roof_height"`; `?om-surfaces=1` → one row PER FACE at its own real per-vertex height so a pitched LoD2.2 roof actually looks pitched, `type="SolidPolygonLayer" get-polygon="$polygon" full3d` (`extruded` stays at its ordinary `false` default) (flat-shaded — deck.gl only lights the `extruded` shader path — each row also carrying `surface_type`: RoofSurface/WallSurface/GroundSurface, and `fill_color`: a ninja-viewer-style default color per surface_type/cityobject_type, verified against cityjson-threejs-loader's own default palette — `get-fill-color` on `SolidPolygonLayer` reads it automatically when left unauthored, no color attribute required, and an authored `get-fill-color` still overrides it); derived properties (both modes) `roof_height` (area-weighted mean roof height above ground), `eaves_height`, `ridge_height`, `ground_height`, `roof_area`, `surface_count`, `lod`, `cityobject_id`, `cityobject_type`, `parent_id` win over same-named source attributes, plus surfaces-mode-only `polygon`/`outline`/`surface_type`/`fill_color` (`outline` is the face's outer ring flattened and closed — bind a companion `type="PathLayer" get-path="$outline"` layer to it for visible face edges, since surfaces mode is flat-shaded and `SolidPolygonLayer`'s own `wireframe` prop is a no-op when unextruded — always pair one, matching `filter-field`/`filter-range` to the fill layer), and a parent Building's attributes are inherited by its BuildingPart rows; national grids NL/CH/DE/JP/AT/SG reproject automatically including axis order, other EPSG codes fail with an error naming the code; highest LoD wins, pin one with `?om-lod=1.2` (combine as `?om-lod=1.2&om-surfaces=1`, cached independently); `.city.jsonl` fills in as it downloads in either mode — see docs/3d-assets.md), or Arrow IPC `.arrow`/`.feather` — large point datasets stay columnar, GeoArrow line/polygon geometry becomes GeoJSON features, zstd-compressed IPC is handled; other formats plug in via `OmMap.registerFormat({match, parse})`; data URLs accept any scheme the runtime's fetch supports — desktop webviews (Tauri, Electron) pass asset-protocol URLs straight in), inline `<script type="application/json">` (row arrays or column-oriented `{"columns": {"lon": [...], "lat": [...]}}`; must be a DIRECT child of the `<om-layer>`, and when present it wins — omit the `data` attribute), or `wss://` streaming (`key="mmsi"` upserts entities in place, `flush="250ms"` coalesces bursts, `source="name"` selects a `OmMap.registerSource` decoder plugin), or a polled REST snapshot (`refresh="5s"` re-fetches and replaces — for live endpoints that return the full current state). TILED layers: a `{z}/{x}/{y}` `data` template is deck's tile URL for `TileLayer`/`MVTLayer` (NOT rows) — passed through to deck verbatim, never fetched/parsed, so `<om-layer type="TileLayer" data="…/{z}/{x}/{y}.png">` works (raster gets a built-in BitmapLayer sublayer) and `type="MVTLayer" data="…/{z}/{x}/{y}.pbf"` self-renders vector tiles with `get-*` accessors applying to each decoded feature's properties; a tiled layer has no local rows so `ctx.data`/`ctx.stats`/`filter-*` don't apply. Authenticated endpoints: call `OmMap.configureData({ headers: {...} })` in a script — never put tokens in attributes. `$field` accessors work identically on all of them — never write column-index code yourself. One columnar restriction: the `js` full-JS opt-in is not allowed on Arrow/columnar layers (validation will tell you; use `$field` accessors instead). For 3D models use `type="ScenegraphLayer"` with `scenegraph="./model.glb"` (required) and `get-orientation="[0, $heading, 90]"` — the roll of 90 stands Y-up glTF models upright; see docs/3d-assets.md. GeoTIFF/COG rasters use `type="COGLayer"` with `src="./dem.tif"` (NOT `data` — rasters stream tiles by Range request, they are not parsed rows): `min`/`max` set the rescale window (default 0–255; ALWAYS set them for float/16-bit data like DEMs), `colormap` picks a bundled ramp for single-band sources (gray, viridis, plasma, inferno, magma, cividis, rdylgn, rdbu, spectral, terrain, jet, turbo), `nodata` overrides the source sentinel (renders transparent); plain 8-bit RGB COGs need no styling attributes; restretch/recolor are GPU uniforms (no refetch) and the legend ramp derives from colormap+min/max automatically. Sources must be Cloud-Optimized (`gdal_translate -of COG` otherwise).
-- `<om-widget type="legend|layer-switcher|basemap-switcher|lighting|zoom-controls|undo-redo|scale-bar|attribution|filter|vega-lite" position="bottom-end">` — static UI panels. `position` takes one of 8 managed slots (logical, RTL-aware: `top-start|top-center|top-end|center-start|center-end|bottom-start|bottom-center|bottom-end`; legacy corners `top-left` etc. alias) — same-slot widgets stack with flush edges and a shared gap (never overlap); provider attribution joins `bottom-end` and the license badge joins `bottom-start` as in-flow members, so required chrome never covers a widget; `order="1"` orders within a slot; adjacent compact button widgets (zoom-controls, undo-redo, widgets-toggle) auto-merge into ONE control group with dividers (`cluster="false"` opts a widget out); `position="manual"` renders a plain block you place with your own CSS (even outside the map). At map widths ≤640px managed widgets auto-fold into one accessible drawer per map side; `fold="never"` exempts an essential widget, `widgets-fold="off"` opts the map out, `--om-widget-fold-breakpoint` changes the threshold. Layout tokens on `<om-map>`: `widget-style="gap:10 opacity:0.9 inset:16"` (keys inset/gap/inset-x/-y/gap-x/-y/opacity/radius/size, px except opacity) or the `--om-widget-inset-x/-y/-gap-x/-gap-y/-opacity/-radius/-fold-breakpoint` custom properties. Built-ins are themeable from page CSS via custom properties (they inherit through the shadow root): `om-map { --om-widget-bg: #111827; --om-widget-fg: #f9fafb; }` — full set: `--om-widget-bg/-fg/-muted/-border/-hover-bg/-accent`; scope to a single widget with an `om-widget[type=legend]` selector instead. No `type` + HTML + `<script type="om/widget">` = custom widget with `ctx` (`ctx.layers`, `ctx.data(id)`, `ctx.dataInViewport(id)`, `ctx.stats(id, field)`, `ctx.viewport`, `ctx.selection`, `ctx.emit(action, payload)`), `this.watch = ['data:<layerId>', 'viewport', 'selection', 'layers', 'history', 'basemap']` (`layers` also fires on visibility/filter changes; `basemap` on basemap switches; `history` on undo/redo availability), `this.$(sel)`, `vegaEmbed`/`d3` as globals.
+- `<om-widget type="legend|layer-switcher|basemap-switcher|lighting|zoom-controls|undo-redo|scale-bar|attribution|filter|vega-lite|measure" position="bottom-end">` — static UI panels. `position` takes one of 8 managed slots (logical, RTL-aware: `top-start|top-center|top-end|center-start|center-end|bottom-start|bottom-center|bottom-end`; legacy corners `top-left` etc. alias) — same-slot widgets stack with flush edges and a shared gap (never overlap); provider attribution joins `bottom-end` and the license badge joins `bottom-start` as in-flow members, so required chrome never covers a widget; `order="1"` orders within a slot; adjacent compact button widgets (zoom-controls, undo-redo, widgets-toggle) auto-merge into ONE control group with dividers (`cluster="false"` opts a widget out); `position="manual"` renders a plain block you place with your own CSS (even outside the map). At map widths ≤640px managed widgets auto-fold into one accessible drawer per map side; `fold="never"` exempts an essential widget, `widgets-fold="off"` opts the map out, `--om-widget-fold-breakpoint` changes the threshold. Layout tokens on `<om-map>`: `widget-style="gap:10 opacity:0.9 inset:16"` (keys inset/gap/inset-x/-y/gap-x/-y/opacity/radius/size, px except opacity) or the `--om-widget-inset-x/-y/-gap-x/-gap-y/-opacity/-radius/-fold-breakpoint` custom properties. Built-ins are themeable from page CSS via custom properties (they inherit through the shadow root): `om-map { --om-widget-bg: #111827; --om-widget-fg: #f9fafb; }` — full set: `--om-widget-bg/-fg/-muted/-border/-hover-bg/-accent`; scope to a single widget with an `om-widget[type=legend]` selector instead. `measure` is a geodesic ruler: `modes="distance area"` (default both), `units="metric|imperial|nautical"` — click the map to place points, live per-segment + total labels render on the map, and it dispatches an `om-measure` event (`detail = {mode, units, totalMeters, segments, areaMeters2, perimeterMeters, poleWarning}`); it reuses the draw capture stack (measure/draw mutually exclusive) and its geometry is ephemeral (never saved, not an undo step). `scale-bar` now takes the same `units`. No `type` + HTML + `<script type="om/widget">` = custom widget with `ctx` (`ctx.layers`, `ctx.data(id)`, `ctx.dataInViewport(id)`, `ctx.stats(id, field)`, `ctx.viewport`, `ctx.selection`, `ctx.emit(action, payload)`), `this.watch = ['data:<layerId>', 'viewport', 'selection', 'layers', 'history', 'basemap']` (`layers` also fires on visibility/filter changes; `basemap` on basemap switches; `history` on undo/redo availability), `this.$(sel)`, `vegaEmbed`/`d3` as globals.
 - `<om-overlay id="..." anchor-from="selection">` — rich geo-anchored HTML (≤ ~20 per map). Anchors: `anchor="[lng, lat]"` (static), `anchor-from="selection"` (follows picks), or `anchor-layer="regions" anchor-feature-id="mission"` (anchored to a feature's own geometry — bbox center — no coordinates in markup; `{{field}}` interpolates that feature's attributes). `{{field}}` interpolates the picked feature HTML-escaped; `{{{field}}}` is raw (avoid). For labels on many features use `PopupLayer`, not overlays.
 - `<om-behavior on="click|hover|drag|load|data-loaded" layer="..." action="...">` — declarative interaction. Built-in actions: `show-overlay`, `hide-overlay`, `show-tooltip`, `hide-tooltip`, `toggle-layer`, `filter-layer`, `highlight-feature`, `zoom-to-feature`, `set-basemap`, `undo`, `redo`. One payload contract everywhere: `{ layer, target, feature, featureId, coordinate }`.
 - Undo/redo is built in: user-facing manifest changes (layer toggles, filter changes, basemap switches, element add/remove, drawn sketches) are recorded automatically — the manifest is the state. `<om-widget type="undo-redo">` renders the buttons; Cmd/Ctrl-Z, Shift-Cmd/Ctrl-Z, and Ctrl-Y work on any map (text inputs keep their native undo). Camera moves, hover effects, and story playback are deliberately NOT undo steps. Widget scripts: `ctx.history.canUndo/canRedo` with watch token `history`; `ctx.emit("undo")`/`ctx.emit("redo")`.

package/onlymapjs.html-data.json

@@ -1599,6 +1599,15 @@
             {
               "name": "draw-save"
             },
+            {
+              "name": "measure-mode"
+            },
+            {
+              "name": "measure-clear"
+            },
+            {
+              "name": "measure-units"
+            },
             {
               "name": "set-basemap"
             },
@@ -1664,6 +1673,9 @@
             {
               "name": "draw"
             },
+            {
+              "name": "measure"
+            },
             {
               "name": "basemap-switcher"
             },
@@ -1767,7 +1779,7 @@
         },
         {
           "name": "modes",
-          "description": "Draw widget: space-separated tools to show.",
+          "description": "Draw widget: space-separated tools (point line polygon). Measure widget: space-separated modes (distance area).",
           "values": [
             {
               "name": "point line polygon"
@@ -1780,6 +1792,15 @@
             },
             {
               "name": "polygon"
+            },
+            {
+              "name": "distance area"
+            },
+            {
+              "name": "distance"
+            },
+            {
+              "name": "area"
             }
           ]
         },
@@ -1802,6 +1823,21 @@
           "name": "autosave",
           "description": "Draw widget: localStorage key — mirrors the sketch and restores it on reload."
         },
+        {
+          "name": "units",
+          "description": "Measure / scale-bar widget: unit system for length and area.",
+          "values": [
+            {
+              "name": "metric"
+            },
+            {
+              "name": "imperial"
+            },
+            {
+              "name": "nautical"
+            }
+          ]
+        },
         {
           "name": "options",
           "description": "Basemap-switcher: space-separated preset names to offer (default: every keyless registered preset)."
@@ -1937,6 +1973,15 @@
             {
               "name": "draw-save"
             },
+            {
+              "name": "measure-mode"
+            },
+            {
+              "name": "measure-clear"
+            },
+            {
+              "name": "measure-units"
+            },
             {
               "name": "set-basemap"
             },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nika-js/onlymap",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Declarative deck.gl maps for HTML and React — interactive WebGL mapping with GeoJSON/CSV/Arrow data, MapLibre basemaps, widgets, popups, and live streams from a custom-element manifest or typed React components. TypeScript, no build step.",
   "license": "SEE LICENSE IN LICENSE.md",
   "publishConfig": {

package/skills/onlymapjs/SKILL.md

@@ -23,7 +23,7 @@ Use OnlyMapJS as a declarative HTML map library. Write custom elements such as `
 </script>
 ```
 
-For no-build CDN pages, use the single-file standalone bundle from a raw-file CDN — `https://unpkg.com/@nika-js/onlymap@0.5.1` (the bare package URL serves `dist/onlymap.standalone.js`) — plus `<link rel="stylesheet" href="https://unpkg.com/@nika-js/onlymap@0.5.1/dist/onlymapjs.css">`. Never a rebundling CDN (esm.sh, skypack): re-bundling duplicates the deck.gl/luma.gl runtime and every layer fails shader compilation.
+For no-build CDN pages, use the single-file standalone bundle from a raw-file CDN — `https://unpkg.com/@nika-js/onlymap@0.5.3` (the bare package URL serves `dist/onlymap.standalone.js`) — plus `<link rel="stylesheet" href="https://unpkg.com/@nika-js/onlymap@0.5.3/dist/onlymapjs.css">`. Never a rebundling CDN (esm.sh, skypack): re-bundling duplicates the deck.gl/luma.gl runtime and every layer fails shader compilation.
 
 ## React Projects
 
@@ -74,6 +74,8 @@ Load the smallest reference needed for the task:
 - Live entity updates -> `wss://` stream with `key` and optional `source` decoder.
 - REST snapshot that changes over time -> `refresh="5s"`.
 - User sketching -> `data="draw:sketch"` layer plus `<om-widget type="draw" target="sketch">`.
+- Measure geodesic distance or area (a ruler / area tool) -> `<om-widget type="measure" modes="distance area" units="metric|imperial|nautical">`. Click the map to place points; it shows live per-segment + total labels and dispatches an `om-measure` event (`detail` = the readout). Reuses the draw capture stack, so measure and draw are mutually exclusive. Do NOT hand-roll distance math off canvas pixels; the `scale-bar` widget also takes `units` now.
+- Capture raw map clicks/hovers yourself (measure distance, drop a pin where the user clicks, a custom rectangle/circle AOI, snap-to-feature) -> listen for the **`om-map-point`** DOM event on `<om-map>`: `mapEl.addEventListener('om-map-point', e => { const { coordinate, kind } = e.detail; /* [lng,lat] or null; kind is "click"|"hover" */ })`. It fires on EVERY click/hover including empty-map clicks. NEVER read deck.gl internals (`getMap()`, `deckInstance`, `deck.viewManager`) or unproject canvas pixels by hand — those are not on `<om-map>` and will silently return nothing. The built-in `draw` widget covers polygon/line/point sketching; `om-map-point` is for tools it doesn't. (`MapController` twin: the `onMapPoint` option. See patterns.md.)
 - Page may travel as a file (shared, emailed, downloaded) or be embedded -> add an `<om-fallback>` child to `<om-map>`. Chat-app and email previews render HTML with JavaScript disabled (iOS QuickLook), so the map cannot boot there; the fallback is what recipients see instead. It is hidden automatically once the map boots. Good practice on every complete page — without one, the stylesheet shows a generic text-only banner.
 
 ## Output Expectations

package/skills/onlymapjs/references/patterns.md

@@ -192,6 +192,44 @@ Use `PopupLayer` instead of many `<om-overlay>` elements for labels/badges at sc
              autosave="onlymapjs-sketch"></om-widget>
 ```
 
+## Capture Raw Map Clicks (measure tool, drop-a-pin, custom AOI)
+
+For anything the `draw` widget doesn't cover — a distance/area measurer, dropping
+a pin at the clicked coordinate, a custom rectangle/circle AOI — read the
+**`om-map-point`** event. It gives you the map coordinate of every click and
+hover. Do NOT reach into deck.gl (`getMap()`, `deckInstance`, `deck.viewManager`)
+or unproject canvas pixels — none of that is exposed on `<om-map>`.
+
+```html
+<om-map center="[103.8, 1.35]" zoom="11" basemap="positron">
+  <!-- The pins the user drops, driven by a draw store you write into. -->
+  <om-layer id="pins" type="GeoJsonLayer" data="draw:measure"
+              get-fill-color="[239,68,68,220]" point-radius-min-pixels="5"
+              get-line-color="[239,68,68,220]" line-width-min-pixels="2"
+              stroked filled></om-layer>
+</om-map>
+
+<script type="module">
+  import "@nika-js/onlymap";
+  const map = document.querySelector("om-map");
+  const pts = [];
+
+  map.addEventListener("om-map-point", (e) => {
+    const { coordinate, kind } = e.detail;   // [lng, lat] | null ; "click" | "hover"
+    if (!coordinate || kind !== "click") return;
+    pts.push(coordinate);
+    // ...compute distance (haversine), update your own panel, etc.
+    // Push geometry into the "measure" draw store so it renders as a layer:
+    // OmMap.getStore("data:pins") / a draw controller, or your own <om-layer> data.
+  });
+</script>
+```
+
+Notes: `coordinate` is `null` when the click lands off the globe; `kind` is
+`"hover"` for the live pointer (use it for a rubber-band segment) and `"click"`
+for a committed point. The programmatic twin is the `MapController` `onMapPoint`
+option; test it headlessly with `h.mapPoint(coordinate, kind)`.
+
 ## Story/Tour
 
 ```html

package/skills/onlymapjs/references/syntax.md

@@ -16,8 +16,8 @@ Vite/npm project:
 Static CDN page (raw-file CDNs only — unpkg/jsDelivr; never esm.sh or another rebundling CDN, which duplicates the WebGL runtime and breaks layer shaders):
 
 ```html
-<link rel="stylesheet" href="https://unpkg.com/@nika-js/onlymap@0.5.1/dist/onlymapjs.css">
-<script type="module" src="https://unpkg.com/@nika-js/onlymap@0.5.1"></script>
+<link rel="stylesheet" href="https://unpkg.com/@nika-js/onlymap@0.5.3/dist/onlymapjs.css">
+<script type="module" src="https://unpkg.com/@nika-js/onlymap@0.5.3"></script>
 ```
 
 Always include `onlymapjs.css` — it carries the MapLibre basemap styles and the no-JS fallback rules (`<om-fallback>` / default banner). For the fallback to work in script-disabled previews it must load without JavaScript: a real `<link rel="stylesheet">` or inlined `<style>` on no-build pages (a bundler-emitted stylesheet is fine in npm projects).
@@ -266,10 +266,11 @@ Built-ins:
 - `legend` — symbology-aware by default: it parses each layer's `get-fill-color`. A `sequential`/`diverging` `scale()` renders as a gradient ramp with the domain ends labeled; a `threshold` scale as discrete class ranges (`< b1`, `b1 – b2`, `≥ bN`); an equality ternary chain (`$f == 'a' ? '#c1' : $f == 'b' ? '#c2' : '#fallback'`) as a category palette with an "other" row. Any other expression falls back to the single `color` swatch — so writing the canonical shapes buys a self-describing legend for free.
 - `layer-switcher`
 - `zoom-controls`
-- `scale-bar`
+- `scale-bar` — `units="metric|imperial|nautical"` (default metric) picks the length system; snaps to a nice round distance.
 - `attribution`
 - `filter`
 - `draw`
+- `measure` — geodesic ruler: `modes="distance area"` (space-separated; default both), `units="metric|imperial|nautical"`. Click the map to place points; live per-segment + total labels render on the map, and a totals panel + a `units` toggle sit in the widget. Distance is haversine on the WGS84 mean sphere (≤0.56% vs. the true geodesic); area is the spherical-excess integral. Nautical shows nmi for length and falls back to metric for area. Reuses the draw capture stack (measure and draw are mutually exclusive); the geometry is ephemeral (never saved, never an undo step). Consume the reading programmatically via the `om-measure` event on `<om-map>` (`detail = {mode, units, totalMeters, segments, areaMeters2, perimeterMeters, poleWarning}`).
 - `vega-lite`
 - `player`
 - `basemap-switcher` — radio list of presets; `options="positron dark-matter osm"` (default: every keyless registered preset)