@nika-js/onlymap 0.6.26 → 0.7.1

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.6.26/dist/onlymapjs.css">
-<script type="module" src="https://unpkg.com/@nika-js/onlymap@0.6.26"></script>
+<link rel="stylesheet" href="https://unpkg.com/@nika-js/onlymap@0.7.1/dist/onlymapjs.css">
+<script type="module" src="https://unpkg.com/@nika-js/onlymap@0.7.1"></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).
@@ -193,12 +193,17 @@ Common choices:
 ```
 
 - `src` (required) — the GeoTIFF URL. NOT `data`: rasters stream tiles by HTTP Range request through the layer's own reader; they are never parsed rows (`$field`, `ctx.data()`, `ctx.stats()`, filters do not apply).
-- Sources must be Cloud-Optimized GeoTIFFs (`gdal_translate -of COG` otherwise).
-- `min`/`max` — the rescale window mapped onto the colormap. Defaults to 0–255, so ALWAYS set them for float or 16-bit data (DEMs, NDVI, temperature).
-- `colormap` — single-band ramps from the bundled sprite: `gray` (default), `viridis`, `plasma`, `inferno`, `magma`, `cividis`, `rdylgn`, `rdbu`, `spectral`, `terrain`, `jet`, `turbo`, `ylorrd` (ColorBrewer yellow→orange→red — a gentler sequential ramp than turbo/jet). Sources with 3+ bands composite as RGB and ignore it.
+- Sources should be Cloud-Optimized GeoTIFFs (`gdal_translate -of COG`); a plain GeoTIFF renders with a structured warning (every view re-reads the full image).
+- `bands` — 1-based band selection (GDAL convention): one band (`bands="4"`, colormap-eligible) or an `[r,g,b]` triple (`bands="[8,4,3]"`, false-color composite). Band switches NEVER refetch tiles — every band is decoded once and retained; textures re-upload from memory.
+- `min`/`max` — the rescale window. A number broadcasts to every selected band; with a `bands` triple, each may be an `[r,g,b]` triple for per-band windows (`min="[0,0,0]" max="[3000,8000,3000]"`). Defaults to 0–255 — set them for float/16-bit data, or use `rescale="auto"`.
+- `rescale="auto"` — window(s) from the file's GDAL statistics tags (deterministic per file; per-band for composites); falls back to sampling the coarsest overview with a warning that the window is data-derived. Explicit `min`/`max` always win. Non-8-bit sources with NO styling attributes auto-stretch automatically (a dev notice reports the derived window).
+- `colormap` — single-band ramps from the bundled sprite: `gray` (default), `viridis`, `plasma`, `inferno`, `magma`, `cividis`, `rdylgn`, `rdbu`, `spectral`, `terrain`, `jet`, `turbo`, `ylorrd`. Composites ignore it (validation warns). `reverse` flips the ramp.
+- `stretch="linear|log|sqrt"` + `gamma` (> 0) — display-curve shaping between rescale and colormap; both are uniforms.
 - `nodata` — overrides the source's nodata sentinel; nodata pixels render transparent.
-- Plain 8-bit RGB COGs (satellite truecolor) need no styling attributes at all.
-- Restretch/recolor (min/max/colormap edits) are GPU uniform updates — tiles are not refetched. The legend widget renders the colormap ramp automatically when `colormap` + `min`/`max` are authored.
+- Plain 8-bit RGB COGs (satellite truecolor) need no styling attributes at all; paletted GeoTIFFs render via their embedded color table and emit a classes legend when few entries are used.
+- PIXEL IDENTIFY: a click/hover over the raster (no vector feature hit) produces a selection whose object carries `{ value, values, bands, nodata, band_1..n }` — overlays/tooltips interpolate `{{value}}` etc. with zero extra wiring. `identify="off"` disables it and releases the CPU-retained decode (recommended on memory-tight WebViews); the trade: band switches on that layer refetch tiles instead of re-uploading from memory.
+- Every styling change (bands/min/max/colormap/reverse/stretch/gamma/nodata) is a GPU-side update — tiles are never refetched. The legend renders automatically from the authored OR auto-resolved window.
+- Failure modes are structured (`validate` panel / `om-validation-error`): CORS-refused Range requests, non-COG sources, and out-of-range `bands` each carry an actionable fix string; the map stays alive.
 
 ### ZarrLayer (Zarr / GeoZarr rasters)