@nika-js/onlymap 0.5.3 → 0.5.7

package/dist/onlymapjs.js

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

package/dist/{raster-DO-Ex2Lb.js → raster-5jEwGISN.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-BoAq5XsU.js";
+import { am as Mt, an as Rt, ao as tt, ap as nt, aq as zt, b as Ft, ar as Dt, l as Ee, as as Nt, d as Ut, at as Bt, au as Gt, av as Kt, aw as rt } from "./index-CUKgoX_E.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-n0GaWEmL.js").then((e) => e.l).then((e) => e.decode));
+D.set(P.Lerc, () => import("./lerc-DWbkmLYR.js").then((e) => e.l).then((e) => e.decode));
 async function je(e, t, n) {
   const r = D.get(t);
   if (!r)

package/dist/validation.d.ts

@@ -15,7 +15,7 @@ export interface ValidationResult {
 /**
  * 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
+ * `colorRamp()`/`formatDate()` 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

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

package/docs/3d-assets.md

@@ -127,7 +127,7 @@ This convention (a `defaultExpr` on the `get-fill-color` `PropDescriptor`, resol
 
 ### Row budget (surfaces mode)
 
-Surfaces mode multiplies the row count by however many faces a building has: the 3DBAG tile in `dev/examples/cityjson.html` decodes to 120 rows as footprints and **3,940 rows** as surfaces — roughly 33×. That lands against the free tier's 25,000-row cap (see [Monetization Gates](../agent-map-library-architecture.md)) at around 750 buildings, where the footprint mode would still be nowhere near it. Past the cap the layer renders its first 25,000 rows — an arbitrary subset in source order, with a dismissible on-map notice — rather than going blank, so a slightly-too-big scene still draws. Because faces are emitted per building, the cut lands mid-building. To show a whole scene rather than part of one: pin a lower LoD with `?om-lod=` (1.3 is ~15× instead of ~33×), tile the source, or extrude footprints instead.
+Surfaces mode multiplies the row count by however many faces a building has: the 3DBAG tile in `dev/examples/cityjson.html` decodes to 120 rows as footprints and **3,940 rows** as surfaces — roughly 33×. That lands against the [free tier's](../README.md#free-tier--licensing) 25,000-row cap at around 750 buildings, where the footprint mode would still be nowhere near it. Past the cap the layer renders its first 25,000 rows — an arbitrary subset in source order, with a dismissible on-map notice — rather than going blank, so a slightly-too-big scene still draws. Because faces are emitted per building, the cut lands mid-building. To show a whole scene rather than part of one: pin a lower LoD with `?om-lod=` (1.3 is ~15× instead of ~33×), tile the source, or extrude footprints instead.
 
 Face counts are long-tailed, so the building count you can fit is not predictable from the average: in that same tile the median building is 17 faces but the largest is 963 — one building, 24% of the tile's rows.
 

package/docs/image-overlays.md

@@ -0,0 +1,75 @@
+# Georeferenced image overlays
+
+`ImageOverlay` places a geotagged drone JPEG on the map. It is the OnlyMapJS-owned preprocessing path over deck.gl's `BitmapLayer`: the browser reads EXIF/XMP, computes an axis-aligned WGS84 footprint, bakes the camera yaw and upside-down roll correction into the pixels, then renders the processed image at those bounds.
+
+## Direct manifest use
+
+```html
+<om-map center="[103.85, 1.29]" zoom="18" pitch="45">
+  <om-layer id="survey-photo"
+            type="ImageOverlay"
+            src="./DJI_0123.jpg"
+            georeference="exif"
+            opacity="0.8"></om-layer>
+</om-map>
+```
+
+The JPEG must contain finite GPS latitude/longitude, positive `RelativeAltitude`, image dimensions, `GimbalYawDegree`, and `GimbalPitchDegree`. `GimbalRollDegree` defaults to zero. Focal length comes from EXIF; it is never guessed.
+
+Known DJI/Parrot cameras use the bundled sensor database. The release path has been verified in Chromium against original DJI FC300S and M30T photos, including M30T files carrying the 180° roll correction. For another camera, supply the physical sensor dimensions and, if EXIF lacks it, focal length:
+
+```html
+<om-layer id="survey-photo"
+          type="ImageOverlay"
+          src="./survey.jpg"
+          georeference="exif"
+          sensor-width-mm="13.2"
+          sensor-height-mm="8.8"
+          focal-length-mm="8.8"></om-layer>
+```
+
+The source follows `OmMap.configureData({ headers, credentials, fetch })`, so authenticated image endpoints use the same request policy as data URLs. `map.ready` waits for EXIF resolution. A failed image is omitted and logged with an actionable error rather than constructing an invalid `BitmapLayer`.
+
+## Persist once, reconstruct cheaply
+
+For collaborative maps or saved manifests, preprocess once and upload the returned image. Store its bounds and metadata beside the new URL:
+
+```js
+const resolved = await OmMap.resolveImageOverlay(file);
+const imageUrl = await upload(resolved.image);
+
+const savedLayer = {
+  src: imageUrl,
+  bounds: resolved.bounds,
+  metadata: resolved.metadata
+};
+```
+
+Reconstruct with explicit bounds:
+
+```html
+<om-layer id="survey-photo"
+          type="ImageOverlay"
+          src="./processed/0123.png"
+          bounds="[103.841,1.286,103.845,1.290]"
+          metadata='{"cameraAssetId":"0123"}'></om-layer>
+```
+
+Explicit bounds bypass fetching and EXIF parsing. The source may therefore be the processed PNG returned when rotation was required, or an unchanged JPEG when it was not. Do not also set `georeference="exif"`; validation warns because bounds win.
+
+The React/programmatic twin uses the same camel-case props:
+
+```tsx
+<OmLayer
+  id="survey-photo"
+  type="ImageOverlay"
+  src="./survey.jpg"
+  georeference="exif"
+  sensorWidthMm={13.2}
+  sensorHeightMm={8.8}
+/>
+```
+
+## Accuracy boundary
+
+This patch intentionally matches the proven PlanetGPT stage-1 approach: a flat-ground pinhole-camera estimate, a pitch-adjusted center approximation, baked yaw/roll, and an axis-aligned bounding box. It is suitable for visualization, not surveying or measurement. Terrain relief, lens distortion, camera calibration, antimeridian-crossing footprints, and a perspective-correct four-corner projective footprint are not modeled. Pre-orthorectified imagery should use explicit bounds, while large orthomosaics belong in a Cloud-Optimized GeoTIFF through `COGLayer`.

package/llms.txt

@@ -2,7 +2,7 @@
 
 > Agent-first map library: a declarative HTML manifest drives deck.gl. You write `<om-map>` / `<om-layer>` / `<om-widget>` / `<om-overlay>` / `<om-behavior>` elements; the library owns reconciliation, accessor compilation, basemap/view sync, overlays, and validation. No build step, no imperative deck.gl code.
 
-OnlyMapJS is NOT raw deck.gl and NOT generic HTML/JSX. The rules below are the delta from what you already assume — following them produces correct manifests on the first pass. Validate with `OmMap.validate(htmlString)` (structured errors, each with a `fix` instruction) and inspect resolved output with `OmMap.snapshotIR(htmlString)` before finalizing.
+OnlyMapJS is NOT raw deck.gl and NOT generic HTML/JSX. The rules below are the delta from what you already assume — following them produces correct manifests on the first pass. Validate with `OmMap.validate(htmlString)` (structured errors AND warnings, each with a `fix` instruction — heed both; an "unknown attribute" warning means a prop is silently dropped) and inspect resolved output with `OmMap.snapshotIR(htmlString)` before finalizing.
 
 ## Loading the library
 
@@ -19,6 +19,7 @@ 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.
+- Readable date/time labels use the safe built-in `formatDate($time, 'datetime', 'UTC')`. Input may be epoch milliseconds (NEVER seconds; multiply seconds by 1000 first) or an ISO string. Styles: `date|datetime|time|iso`; default style `datetime`, default zone `UTC`; zone may be `local` or an IANA name such as `Asia/Singapore`. Do NOT use `new Date()`, `Intl`, or instance methods in restricted expressions.
 - `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.
@@ -27,15 +28,17 @@ OnlyMapJS is NOT raw deck.gl and NOT generic HTML/JSX. The rules below are the d
 ## 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-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, GPX `.gpx` (waypoints/tracks/routes → features tagged `_gpxKind`; a `#waypoints`/`#tracks`/`#routes` URL fragment selects one part), FlatGeobuf `.fgb` (cloud-native binary vector, whole-file decode), GeoParquet `.parquet`/`.geoparquet` (cloud-native columnar vector — all-Point files stay columnar like Arrow, lines/polygons become GeoJSON features; requires the file's `geo` metadata with WKB geometry, and CRS84/EPSG:4326 — a projected CRS is a loud error telling you to reproject, not a silent misplacement; snappy/gzip/zstd row-group compression handled), 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).
+- Geotagged drone JPEGs are the library-owned `ImageOverlay` type, not row `data` and not a raw `BitmapLayer`: `<om-layer type="ImageOverlay" src="./photo.jpg" georeference="exif">`. It reads GPS/relative altitude/camera/focal length plus DJI gimbal metadata through the configured fetch policy, waits before `ready`, bakes yaw/roll, and computes visualization-grade flat-ground bounds. Unknown cameras need `sensor-width-mm` + `sensor-height-mm` (and `focal-length-mm` when EXIF lacks it). For collaborative/saved maps call `OmMap.resolveImageOverlay(fileOrUrl)`, upload its returned `image`, then reconstruct using `src` + the returned explicit `bounds` (no EXIF fetch). Use `COGLayer` for large orthomosaics; see docs/image-overlays.md.
 - `<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.
+- Custom-widget event emission (the #1 custom-widget bug — a widget that renders but does nothing): a widget DRIVES the map ONLY by EMITTING a registered action; it never mutates the map or dispatches its own `CustomEvent`. Two ways: (1) declarative `data-emit="<action>"` + `data-*` payload keys on an element (fires on click, or change for form controls whose `.value` is auto-added; `data-*` values are STRINGS — use `ctx.emit` for numeric/array payloads like a slider's range); (2) `ctx.emit(action, payload)` for typed payloads, wired INSIDE `render` (so `ctx` is in scope) by assigning `.oninput`/`.onclick` — e.g. a day slider: `this.render = (ctx) => { this.$("#day").oninput = e => ctx.emit("filter-layer", { layer: "quakes", field: "day", range: [+e.target.value, +e.target.value] }); }`. Actions + payloads: `filter-layer {layer, field?, range:[min,max]}`, `toggle-layer {layer, visible?}`, `fly-to {center:[lng,lat], zoom?, duration?}`, `zoom-to-feature {layer, featureId}`, `set-basemap {basemap}`, `highlight-feature {layer, featureId}`, `show-overlay`/`hide-overlay {target}`, `story-play`/`story-pause`/`story-seek {story, t?}`, `undo`/`redo`, `zoom-in`/`zoom-out`, `set-widgets-visible {visible}`; register more with `OmMap.registerAction(name, handler)`. NEVER inline `onclick=`/`oninput=` — `ctx` isn't a global and CSP blocks them, so it silently fires nothing (validation errors on it). For a plain value/time slider prefer the built-in `<om-widget type="filter" layer=… field=…>` — it wires `filter-layer` for you; hand-author only for bespoke UI.
 - `<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")`.
 - `<om-fallback>` — static no-JS fallback, direct child of `<om-map>` (one per map, no attributes, plain HTML content — links allowed). Shown ONLY where scripts never run (chat-app/email file previews — iOS QuickLook renders HTML attachments with JS off — file managers, sandboxed webviews); hidden automatically once the map boots. GOOD PRACTICE: include one on every complete page, especially pages that may be shared as a file ("This interactive map requires JavaScript — open this file in a web browser", plus a hosted-version link when one exists). Without one, the stylesheet shows a generic text-only banner. The gate is pure CSS (`om-map:not(:defined)` in onlymapjs.css), so the CSS must load without JS — a real `<link rel="stylesheet">` or inlined `<style>` on no-build pages; a bundler-emitted stylesheet is fine in npm projects.
 - Animation: `transition="get-fill-color 800ms, get-radius 400ms"` on a layer GPU-animates prop changes (also smooths streaming updates via `get-position`). Camera: the `fly-to` action takes `center`/`zoom`/`pitch`/`bearing`/`duration` (e.g. `duration="2s"`) — use it in behaviors or `data-emit` buttons; `zoom-to-feature` also accepts `duration`.
 - `<om-story id="tour" autoplay loop interrupt="pause|ignore">` — a storyboard of `<om-step>` children. Each step: `action="..."` + payload attributes (same kebab-case rule as behaviors) + `duration`/`delay`/`parallel` timing. Steps REFERENCE layers/overlays by id (`layer=`/`target=`) — a step must NEVER contain elements (validation error). Control: `<om-widget type="player" story="tour">`, the story-play/story-pause/story-seek actions, or `storyEl.play()/pause()/seek(ms)`. Seeking restores initial state then applies steps before T; use declarative payloads (e.g. `action="toggle-layer" visible="true"`, not bare toggles) so scrubbing is deterministic. Scene actions are story-steppable AND scrub-capturable: `set-basemap`, `set-lighting` (a sunset story: steps walking sun-elevation down; a bare preset step is a clean reset), and `set-terrain` all rewind on seek — the story captures the map's scene attributes before first play. Effect verbs as bare step attributes: `<om-step fade layer="regions" duration="1s">` (opacity reveal — start the layer at `opacity="0"`), `pulse` (attention flash), `trace` (progressive draw — whole-layer needs a TripsLayer; add `feature-id="..."` to make ONE polygon/line draw itself on inside any layer, or use it from a click behavior for click-to-trace), `populate` (rows drop in one by one — ordered by the authored filter-field, a payload `field`, or data order).
-- Filtering: `filter-field="magnitude" filter-range="[4, 10]"` on a layer (GPU-side, live-updatable via the `filter-layer` action); pair with `<om-widget type="filter" layer="..." field="...">`.
+- Filtering: `filter-field="magnitude" filter-range="[4, 10]"` on a layer (GPU-side, live-updatable via the `filter-layer` action); pair with `<om-widget type="filter" layer="..." field="...">`. For an epoch-millisecond field, make the slider labels readable with `<om-widget type="filter" layer="quakes" field="time" format="date" date-style="datetime" time-zone="UTC"></om-widget>`.
 
 ## Decision rule for annotations
 
@@ -54,6 +57,6 @@ In a React codebase, do NOT render om-* elements from JSX (React and the library
 ## Verification loop
 
 1. Write the manifest (or edit the live DOM — changes reconcile automatically).
-2. `OmMap.validate(html)` → `{ valid, errors: [{ severity, element, attribute, message, fix }] }`. Apply each `fix` verbatim; it is an instruction, not a diagnosis.
+2. `OmMap.validate(html)` → `{ valid, errors, warnings }`, each entry `{ severity, element, attribute, message, fix }`. Apply every `fix` verbatim — from BOTH lists; it is an instruction, not a diagnosis. `valid` reflects ERRORS ONLY, so never stop at `valid: true` — clear the warnings too. A warning is not cosmetic: an `Unknown attribute "…" — likely a typo` warning means a prop you wrote is being silently dropped and the layer renders wrong-but-valid (classic: `get-radius`/`radius-units` on a `GeoJsonLayer`, whose point size is `get-point-radius`/`point-radius-units` — `get-radius` is a `ScatterplotLayer` prop). Consult `onlymapjs.html-data.json` for the layer's real attribute set rather than guessing.
 3. `OmMap.snapshotIR(html)` → resolved layer descriptors (JSON-safe; accessors appear as behavioural fingerprints) — diff against intent, assert in tests (works headless in jsdom/happy-dom, no WebGL needed).
 4. For interaction tests: `mountForTest(html)` mounts the page headlessly (no WebGL) — `await h.pick({ layer, featureId })` then assert overlay/widget DOM via `el.shadowRoot`. Full guide: [docs/testing.md](docs/testing.md).