@nika-js/onlymap 0.6.25 → 0.7.0

package/onlymapjs.html-data.json

@@ -64,6 +64,33 @@
           "name": "basemap-key",
           "description": "Provider API key for keyed basemap presets (maptiler-*) — publishable origin-restricted key; or call OmMap.configureBasemap once."
         },
+        {
+          "name": "hover-pick",
+          "description": "Hover-pick cadence: \"rest\" (default — one GPU pick when the pointer stops, none while it sweeps; kills the per-mousemove ReadPixels stall on integrated graphics), \"continuous\" (deck-native, per frame), \"off\" (click picking only), or a throttle interval in ms (leading + trailing).",
+          "values": [
+            {
+              "name": "rest"
+            },
+            {
+              "name": "continuous"
+            },
+            {
+              "name": "off"
+            }
+          ]
+        },
+        {
+          "name": "pick-cursor",
+          "description": "CSS cursor shown while the pointer is over a pickable feature (default \"pointer\" — the is-this-interactive affordance). \"none\" disables.",
+          "values": [
+            {
+              "name": "pointer"
+            },
+            {
+              "name": "none"
+            }
+          ]
+        },
         {
           "name": "attribution",
           "description": "Set \"false\" to opt out of the compact attribution control shown with basemaps.",
@@ -1175,6 +1202,18 @@
           "name": "texture-parameters",
           "description": "deck.gl textureParameters. Valid on: BitmapLayer, IconLayer, ImageOverlay, SimpleMeshLayer."
         },
+        {
+          "name": "bands",
+          "description": "deck.gl bands. Valid on: COGLayer."
+        },
+        {
+          "name": "rescale",
+          "description": "deck.gl rescale. Valid on: COGLayer."
+        },
+        {
+          "name": "identify",
+          "description": "deck.gl identify. Valid on: COGLayer."
+        },
         {
           "name": "min",
           "description": "deck.gl rescaleMin. Valid on: COGLayer, ZarrLayer."
@@ -1187,6 +1226,18 @@
           "name": "colormap",
           "description": "deck.gl colormap. Valid on: COGLayer, ZarrLayer."
         },
+        {
+          "name": "reverse",
+          "description": "deck.gl reverse. Valid on: COGLayer, ZarrLayer."
+        },
+        {
+          "name": "stretch",
+          "description": "deck.gl stretch. Valid on: COGLayer, ZarrLayer."
+        },
+        {
+          "name": "gamma",
+          "description": "deck.gl gamma. Valid on: COGLayer, ZarrLayer."
+        },
         {
           "name": "nodata",
           "description": "deck.gl nodataOverride. Valid on: COGLayer, ZarrLayer."
@@ -1822,6 +1873,9 @@
             {
               "name": "toggle-layer"
             },
+            {
+              "name": "set-pickable"
+            },
             {
               "name": "zoom-in"
             },
@@ -2424,6 +2478,9 @@
             {
               "name": "toggle-layer"
             },
+            {
+              "name": "set-pickable"
+            },
             {
               "name": "zoom-in"
             },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nika-js/onlymap",
-  "version": "0.6.25",
+  "version": "0.7.0",
   "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": {
@@ -112,7 +112,9 @@
     "build:types": "tsc -p tsconfig.build.json --emitDeclarationOnly",
     "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.e2e.json --noEmit && tsc -p cloud/workers/telemetry/tsconfig.json && tsc -p cloud/workers/examples/tsconfig.json",
     "test": "vitest run",
-    "prepublishOnly": "node dev/tools/announce-release.mjs --check && npm run build",
+    "comment:e2e-smoke": "Release gate for rendered-pixel guarantees the unit suite can't see: the license-condition badge chrome (a red badge e2e shipped across 0.6.24 AND 0.6.25 because only vitest gated publish) and frame determinism. Deliberately tiny — the full e2e suite stays a manual/CI concern.",
+    "test:e2e:smoke": "playwright test e2e/deterministic-frames.spec.ts && playwright test e2e/examples.spec.ts -g \"attribution badge\"",
+    "prepublishOnly": "node dev/tools/announce-release.mjs --check && npm run build && npm run test:e2e:smoke",
     "postpublish": "node dev/tools/announce-release.mjs",
     "try": "vite-node dev/expr-repl.mjs",
     "test:e2e": "playwright test",

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.6.25` (the bare package URL serves `dist/onlymap.standalone.js`) — plus `<link rel="stylesheet" href="https://unpkg.com/@nika-js/onlymap@0.6.25/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.7.0` (the bare package URL serves `dist/onlymap.standalone.js`) — plus `<link rel="stylesheet" href="https://unpkg.com/@nika-js/onlymap@0.7.0/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
 

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.25/dist/onlymapjs.css">
-<script type="module" src="https://unpkg.com/@nika-js/onlymap@0.6.25"></script>
+<link rel="stylesheet" href="https://unpkg.com/@nika-js/onlymap@0.7.0/dist/onlymapjs.css">
+<script type="module" src="https://unpkg.com/@nika-js/onlymap@0.7.0"></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).
+- 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)
 
@@ -648,6 +653,7 @@ Common built-in actions:
 - `show-overlay`, `hide-overlay`
 - `show-tooltip`, `hide-tooltip`
 - `toggle-layer`
+- `set-pickable` — payload `{ layer, pickable: true|false|"3d" }`; writes/removes the layer's `pickable` attribute at runtime (turns popups/tooltips/hover behaviors on or off per layer — the viewer-facing popup toggle), story-capturable and undoable
 - `highlight-feature` — sets the layer's `highlighted-id`; style the selection with `highlight-color="[220, 38, 38, 255]"` (or hex) on the `<om-layer>` — a constant color, not a `get-*` accessor
 - `zoom-to-feature`
 - `filter-layer`
@@ -664,6 +670,10 @@ Common built-in actions:
 
 Payload attributes are kebab-case and become camelCase payload keys.
 
+## Hover picking & the pointer cursor
+
+Hovering a pickable feature shows `cursor: pointer` automatically — the "is this map interactive?" affordance; `pick-cursor` on `<om-map>` overrides the cursor value and `pick-cursor="none"` disables it. Hover GPU picks are REST-DEBOUNCED by default: one pick when the pointer stops, none while it sweeps — this eliminates the per-mousemove GPU ReadPixels stall that froze hover-popup maps on integrated graphics. `hover-pick` on `<om-map>` tunes the cadence: `"rest"` (default), `"continuous"` (deck-native per-frame, for hover-follow UIs on capable hardware), `"off"` (click picking only), or a throttle interval in ms (leading + trailing picks). Click picking is never gated. `MapController` twins: `setHoverPicking(mode)` / `setPickCursor(value)`.
+
 Example:
 
 ```html