@nika-js/onlymap 0.6.20 → 0.6.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nika-js/onlymap",
-  "version": "0.6.20",
+  "version": "0.6.22",
   "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": {
@@ -103,6 +103,7 @@
     "docs",
     "llms.txt",
     "onlymapjs.html-data.json",
+    "onlymapjs.attributes.json",
     "skills/onlymapjs"
   ],
   "scripts": {

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.20` (the bare package URL serves `dist/onlymap.standalone.js`) — plus `<link rel="stylesheet" href="https://unpkg.com/@nika-js/onlymap@0.6.20/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.6.22` (the bare package URL serves `dist/onlymap.standalone.js`) — plus `<link rel="stylesheet" href="https://unpkg.com/@nika-js/onlymap@0.6.22/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.20/dist/onlymapjs.css">
-<script type="module" src="https://unpkg.com/@nika-js/onlymap@0.6.20"></script>
+<link rel="stylesheet" href="https://unpkg.com/@nika-js/onlymap@0.6.22/dist/onlymapjs.css">
+<script type="module" src="https://unpkg.com/@nika-js/onlymap@0.6.22"></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).
@@ -125,6 +125,12 @@ Multi-dimension filtering (up to 4, AND'd together — a row must pass every dim
 
 One `<om-widget type="filter">` per dimension — each moves its own field's range independently; `filter-layer` merges the update onto the matching dimension rather than replacing the whole filter. A dimension can't be added live through the widget/action — the full set of fields a layer filters on must be declared up front in `filter-fields`.
 
+## Zoom visibility (any layer type)
+
+`visible-zoom-range="[8, 14]"` — scale-dependent visibility, the QGIS/ArcGIS/Mapbox everyday pattern: the layer renders only at min ≤ zoom < max (min inclusive, max exclusive — the minzoom/maxzoom convention). Universal: valid on every layer type, unlike the tile-only `visible-min-zoom`/`visible-max-zoom` deck props. Composes with `visible` (both must allow); a zoom-hidden layer stays a full scene member — legend, layer-switcher, and `ctx` still list it. Malformed values are ignored with a warning (`validate` reports them structurally).
+
+Attribute-contract tooling: the package also ships `onlymapjs.attributes.json` — a machine-readable per-layer-type attribute list generated from the same registry the runtime validates against. CI checks that emit `<om-layer>` markup should validate attributes per `type=` against it, NOT against the editor IntelliSense file (`onlymapjs.html-data.json`), which is a flat per-tag union and cannot express "valid on TileLayer, not GeoJsonLayer". An attribute is accepted on a type iff it appears in the contract's `universal` list or `layers[<type>]`.
+
 Categorical filtering is a SEPARATE mechanism from numeric (deck.gl's own `categorySize`, a discrete keep-list test, not a range) — same shape, own attributes, and combines with an active numeric filter (a row must pass both):
 
 ```html
@@ -674,7 +680,7 @@ Add `warm-tiles` on `<om-story>` to pre-load 3D tilesets along the story's fly-t
 
 Add `paced` on `<om-story>` for load-paced playback: the story steps its own clock frame by frame (optionally `paced="60"` story-fps, default 30), drives the camera itself along the fly-to route, and never advances a frame while any 3D tileset is still refining — no frame ever shows unrefined tiles, at the cost of wall-clock time (playback is not real-time; use it for recorded takes or heavy tilesets like Google Photorealistic 3D Tiles, where no amount of pre-warming fits the flight in cache). Emits `om-paced-tick` (`detail = {t, waitedMs}`) on the story per frame; `waitedMs > 0` means that frame paused for tiles. Composes with `warm-tiles` (warm first → far shorter waits). During a paced run only `fly-to` steps steer the camera (data-dependent camera steps like `zoom-to-feature` are skipped with a warning) and user gestures don't pause playback — pause via the player widget or `story-pause`.
 
-To output an actual video: `npx onlymapjs record map.html --out flyby.mp4` (playwright dev-installed; ffmpeg assembles, else you get PNG frames + the command) plays the story paced in isolated headless Chromium and screenshots every frame — widgets, overlays, and attribution included, every frame fully refined. Options: `--story <id>`, `--fps <n>`, `--width/--height/--scale`, `--gpu` (hardware rendering; ~3× shorter tile holds on heavy 3D scenes — recommended), `--keep-frames`, `--timeout <s>` (frames survive a deadline hit in `<out>.frames/`), `--max-hold <s|none>` (per-frame tile-wait cap, default 10s — also authorable as `paced-max-hold` on `<om-story>`; frames that keep hitting the cap may stay slightly blurry — raise it, or `none` makes the gate absolute for guaranteed-sharp takes). It executes the page's scripts — trusted, browser-runnable manifests only. For custom recorders in-page, `storyEl.setPacedCapture(async (tick) => {...})` is awaited per frame before that frame's `om-paced-tick` (capture race-free; the ended-state tick = all frames captured).
+To output an actual video: `npx onlymapjs record map.html --out flyby.mp4` (playwright dev-installed; ffmpeg assembles, else you get PNG frames + the command) plays the story paced in isolated headless Chromium and screenshots every frame — widgets, overlays, and attribution included, every frame fully refined. Options: `--story <id>`, `--fps <n>`, `--width/--height/--scale`, `--gpu` (hardware rendering; ~3× shorter tile holds on heavy 3D scenes — recommended), `--keep-frames`, `--timeout <s>` (frames survive a deadline hit in `<out>.frames/`), `--max-hold <s|none>` (per-frame tile-wait cap, default 10s — also authorable as `paced-max-hold` on `<om-story>`; frames that keep hitting the cap may stay slightly blurry — raise it, or `none` makes the gate absolute for guaranteed-sharp takes). It executes the page's scripts — trusted, browser-runnable manifests only. Effect verbs (fade/pulse/trace/populate) animate on the story clock during paced/recorded runs, so frames capture traces half-drawn and fades mid-flight exactly as authored (`trace follow` is skipped — the paced route owns the camera). For custom recorders in-page, `storyEl.setPacedCapture(async (tick) => {...})` is awaited per frame before that frame's `om-paced-tick` (capture race-free; the ended-state tick = all frames captured).
 
 Use `<om-story>` with `<om-step>` children. Stories are siblings of layers/overlays, not containers.