@nika-js/onlymap 0.6.16 → 0.6.18

package/onlymapjs.html-data.json

@@ -546,6 +546,15 @@
           "name": "site-scale",
           "description": "Georeferencing: uniform scale multiplier (default 1)."
         },
+        {
+          "name": "anchor",
+          "description": "anchor=\"surface\": anchor each row INSIDE its own polygon (point-on-surface) — on-map labels/annotations with no authored coordinates. An authored get-position wins.",
+          "values": [
+            {
+              "name": "surface"
+            }
+          ]
+        },
         {
           "name": "get-position",
           "description": "Accessor for deck.gl getPosition — expression language: $field, scale(), formatDate(), arithmetic."
@@ -1916,6 +1925,9 @@
             },
             {
               "name": "redo"
+            },
+            {
+              "name": "warm-tiles"
             }
           ]
         },
@@ -2357,6 +2369,18 @@
           "name": "id",
           "description": "Story id — referenced by the player widget and story-* actions."
         },
+        {
+          "name": "warm-tiles",
+          "description": "Pre-load every 3D tileset along this story's camera route in the background as soon as the story connects — flyby pop-in / LOD refinement blur becomes a sub-frame re-upload. Completion announced via the om-tiles-warmed event on <om-map>."
+        },
+        {
+          "name": "paced",
+          "description": "Load-paced playback: the story steps its own clock frame by frame (optionally paced=\"60\" story-fps, default 30), owns the camera along the fly-to route, and never advances while a 3D tileset is still refining — no frame ever shows unrefined tiles. Wall-clock stretches; emits om-paced-tick {t, waitedMs} per frame. Composes with warm-tiles (warm first → far shorter waits)."
+        },
+        {
+          "name": "paced-max-hold",
+          "description": "Per-frame tile-wait cap for paced playback (duration grammar, default 10s): a frame still waiting past the cap advances anyway, so a dead tile server degrades to ordinary pop-in instead of freezing the story. Heavy tilesets (Google Photorealistic 3D Tiles) can be tile-bound longer than 10s per frame — raise it (e.g. \"30s\"), or set \"none\" to wait unconditionally for full refinement (guaranteed-sharp recorded takes; only pause can then unstick a dead server)."
+        },
         {
           "name": "autoplay",
           "description": "Start after om-map-ready."
@@ -2503,6 +2527,9 @@
             },
             {
               "name": "redo"
+            },
+            {
+              "name": "warm-tiles"
             }
           ]
         },
@@ -2514,6 +2541,28 @@
           "name": "delay",
           "description": "Stagger before the step starts."
         },
+        {
+          "name": "follow",
+          "description": "trace steps: lock the camera to the line's drawing tip for the step's duration (the travel-map move)."
+        },
+        {
+          "name": "easing",
+          "description": "trace steps: clock curve for the draw.",
+          "values": [
+            {
+              "name": "linear"
+            },
+            {
+              "name": "ease-in"
+            },
+            {
+              "name": "ease-out"
+            },
+            {
+              "name": "ease-in-out"
+            }
+          ]
+        },
         {
           "name": "parallel",
           "description": "Start with the previous step instead of after everything before it."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nika-js/onlymap",
-  "version": "0.6.16",
+  "version": "0.6.18",
   "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.6.16` (the bare package URL serves `dist/onlymap.standalone.js`) — plus `<link rel="stylesheet" href="https://unpkg.com/@nika-js/onlymap@0.6.16/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.18` (the bare package URL serves `dist/onlymap.standalone.js`) — plus `<link rel="stylesheet" href="https://unpkg.com/@nika-js/onlymap@0.6.18/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.16/dist/onlymapjs.css">
-<script type="module" src="https://unpkg.com/@nika-js/onlymap@0.6.16"></script>
+<link rel="stylesheet" href="https://unpkg.com/@nika-js/onlymap@0.6.18/dist/onlymapjs.css">
+<script type="module" src="https://unpkg.com/@nika-js/onlymap@0.6.18"></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).
@@ -573,6 +573,10 @@ duration?}`, `zoom-to-feature` `{layer, featureId, duration?}`, `set-basemap`
 
 Rich sparse HTML anchored to the map.
 
+**Styling — overlay content renders inside a shadow root (style isolation, same as widgets), so page stylesheets and their classes DO NOT reach it.** Style overlay content with inline `style="…"` attributes, or put a `<style>` element INSIDE the overlay (children are moved into the shadow root wholesale, so it applies there). Inheritable properties and CSS custom properties set on `om-overlay`/`om-map` do pierce the boundary. A `.card` class defined in the page's `<head>` will silently not apply — the content renders unstyled.
+
+Also note for story "cards": an overlay is geo-anchored, and by default it HIDES whenever its anchor leaves the viewport — on a moving story camera an anchored card can vanish mid-step. Pin narrative cards that must persist across camera motion in a widget slot (custom `<om-widget position="bottom-center">`) instead; use anchored overlays for cards that belong to a place (they track it and legitimately go away when it leaves frame).
+
 Anchors:
 
 - `anchor="[lng, lat]"`
@@ -664,6 +668,14 @@ Example:
 
 ### Stories
 
+Trace steps take `follow` (camera rides the line's drawing tip — the travel-map move) and `easing="linear|ease-in|ease-out|ease-in-out"`. On-map annotations without popups: `anchor="surface"` on a `TextLayer` over polygon GeoJSON anchors each row's text inside its own shape (`get-text="$name"`); pair with `font-settings='{"sdf":true}' outline-width="4" outline-color="..."` for a legible halo.
+
+Add `warm-tiles` on `<om-story>` to pre-load 3D tilesets along the story's fly-to route in the background at load — flybys play sharp instead of refining from blurry. Manual form: the `warm-tiles` action (`{story?, samples?, budget?}`); completion fires `om-tiles-warmed` on `<om-map>`. Persistent knob: `load-options='{"tileset":{"maximumMemoryUsage":512}}'` on the tiles layer.
+
+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).
+
 Use `<om-story>` with `<om-step>` children. Stories are siblings of layers/overlays, not containers.
 
 ```html