@nika-js/onlymap 0.6.19 → 0.6.21

package/CHANGELOG.md

@@ -8,6 +8,24 @@ Note: npm collapsed a few closely-spaced releases — the GPX/FlatGeobuf (0.5.4)
 and GeoParquet (0.5.5) work shipped to npm together as **0.5.6**, so npm's
 version list jumps 0.5.3 → 0.5.6. Each logical version is listed here regardless.
 
+## 0.6.21 — 2026-08-26
+
+### Added
+- **Recordings now capture animations, not just end states.** Fade, pulse, trace, and populate steps animate frame-accurately in `onlymapjs record` output and paced story runs — a 2-second border trace draws itself on across 2 seconds of video instead of appearing fully drawn. Seeking a story under the recording switch lands mid-animation too (a half-drawn trace is just a scene), which external frame renderers rely on. One documented limit: the `trace follow` camera is skipped during recorded runs, since the paced route drives the camera.
+
+### Fixed
+- **On-map labels (`anchor="surface"`) now sit on the landmass they belong to.** Ring selection previously favored densely-digitized slivers and could even pick a hole; features without a usable anchor point no longer draw a stray label at null island.
+- **The `trace follow` camera stays glued to the drawing tip.** It previously sampled the path by distance while the ink advanced by timestamps, so routes with dwells or slow legs pulled the camera away from the head; layers with several separately-timed paths no longer make the camera jump between them.
+- **Blob-format snapshots are byte-stable again.** Stability comparison silently never matched for blob output, so exactly the format video renderers request lost its guarantee.
+- **Seeking a story no longer overwrites fit-bounds or zoom-to poses between camera legs.**
+- **Paid-license render exemption is scoped to real local browser pages** — it no longer applies in environments without a page location at all.
+
+## 0.6.20 — 2026-08-26
+
+### Fixed
+- **Paid licenses now apply when rendering video locally.** A key restricted to your domains couldn't take effect on the local host that `onlymapjs record` (and external frame renderers) serve from, so paid features didn't apply to rendered output. A verified paid key is now honored in local render contexts; unkeyed usage is unchanged.
+- **Rendered frames settle faster and more reliably over basemaps.** `whenSettled()` now keys off the basemap's own idle signal (camera done, tiles loaded, fades complete) instead of a polling approximation, and the recording switch takes effect before the first render (previously a startup race could leave label fade-in enabled during a take).
+
 ## 0.6.19 — 2026-08-26
 
 ### Fixed

package/README.md

@@ -147,7 +147,7 @@ Built-in actions wire to picks, widget buttons (`data-emit`), or script (`ctx.em
 
 **Animation:** camera moves accept a duration — `map.flyTo(coords, zoom, { duration: 1200, curve: true })`, or the `fly-to` action (`center`/`zoom`/`pitch`/`bearing`/`duration`) from any behavior or button; `prefers-reduced-motion` is honored (moves become instant, final state identical). Per-prop GPU transitions via the `transition` attribute: `transition="get-fill-color 800ms"` fades color changes; on a streaming layer, `transition="get-position 300ms"` makes entities glide between updates.
 
-**Map stories:** a guided tour as markup — `<om-story>` holds `<om-step>` children that fire the same actions behaviors use, on a timeline (`duration`, `delay`, `parallel`); the built-in `type="player"` widget gives play/pause/scrub, seeking restores the scene's captured initial state, one story is active per map, and grabbing the map pauses playback. Effect verbs — `fade`, `pulse`, `trace` (progressive TripsLayer draw-on; with `feature-id`, a single polygon draws itself on inside its own layer), and `populate` (rows drop in one by one via a GPU filter sweep) — work as step shorthands or plain actions. The story is a sibling that references layers by id — delete it and the map is unchanged. For flybys over 3D tilesets, `warm-tiles` pre-loads the route's tiles in the background before playback, and `paced` goes further: the story steps its own clock and never advances a frame while a tileset is still refining, so no frame ever shows unrefined tiles — wall-clock stretches instead (built for recorded takes; emits `om-paced-tick {t, waitedMs}` per frame, and the two compose — warm first, wait less). `npx @nika-js/onlymap record map.html --out flyby.mp4` turns that guarantee into an actual video: one screenshot per paced frame in headless Chromium (widgets and attribution included), assembled with ffmpeg. Guide: [docs/stories.md](docs/stories.md).
+**Map stories:** a guided tour as markup — `<om-story>` holds `<om-step>` children that fire the same actions behaviors use, on a timeline (`duration`, `delay`, `parallel`); the built-in `type="player"` widget gives play/pause/scrub, seeking restores the scene's captured initial state, one story is active per map, and grabbing the map pauses playback. Effect verbs — `fade`, `pulse`, `trace` (progressive TripsLayer draw-on; with `feature-id`, a single polygon draws itself on inside its own layer), and `populate` (rows drop in one by one via a GPU filter sweep) — work as step shorthands or plain actions. The story is a sibling that references layers by id — delete it and the map is unchanged. For flybys over 3D tilesets, `warm-tiles` pre-loads the route's tiles in the background before playback, and `paced` goes further: the story steps its own clock and never advances a frame while a tileset is still refining, so no frame ever shows unrefined tiles — wall-clock stretches instead (built for recorded takes; emits `om-paced-tick {t, waitedMs}` per frame, and the two compose — warm first, wait less). `npx @nika-js/onlymap record map.html --out flyby.mp4` turns that guarantee into an actual video: one screenshot per paced frame in headless Chromium (widgets and attribution included), assembled with ffmpeg — and effect verbs animate on the story clock, so recorded traces draw on frame by frame exactly as authored. Guide: [docs/stories.md](docs/stories.md).
 
 **Classified symbology:** `classify-by="magnitude" classify-scale="jenks" classify-classes="5" classify-ramp="viridis"` computes class breaks *from the data* (quantile, equal-interval, or Jenks natural breaks), styles the layer with a named ramp, and auto-generates the classes legend — no domains or colors to hand-author; an explicit `get-fill-color`/`color` always wins. **Temporal playback:** `<om-widget type="time-slider" layer="…" field="time" duration="20s" window="86400000" format="date">` is a play/pause/scrub control over a layer's time field, driving the same `filter-layer` mechanics as the filter widget (stats stay coherent; `loop` restarts the sweep).
 

package/dist/{LercDecode.es-Butn4LVX.js → LercDecode.es-B_dD2_mY.js}

@@ -19,7 +19,7 @@ async function v(N = {}) {
   if (n) {
     const { createRequire: I } = await import(
       /*webpackIgnore:true*/
-      "./lerc-cWjnr__g.js"
+      "./lerc-CMJO8KZO.js"
     ).then((g) => g._);
     var O = I(import.meta.url);
   }

package/dist/actions.d.ts

@@ -1,3 +1,13 @@
+/**
+ * The action registry (spec: "Module Breakdown / Behavior Engine" — "Action
+ * payload contract"). One event name maps to one action handler with one
+ * payload schema, honored identically across all three emit surfaces —
+ * `ctx.emit(name, payload)`, `data-emit`, and `<om-behavior>` — an action
+ * reads the same keys regardless of how it was triggered. `registerAction`
+ * is re-exported from the package entry point (index.ts) as the public
+ * `OmMap.registerAction` surface.
+ */
+import { TRACE_TEMP_PREFIX } from "./internal-ids";
 import type { RuntimeCore } from "./runtime-core";
 import type { LayerIR } from "./ir";
 export type ActionHandler = (payload: Record<string, unknown>, mapEl: Element, core: RuntimeCore, layerIRs: ReadonlyMap<string, LayerIR>) => void;
@@ -9,6 +19,16 @@ export declare function dispatchAction(name: string, payload: Record<string, unk
 export { RUNTIME_INTERNAL_PREFIX } from "./internal-ids";
 /** The overlay anchor for a feature: its bbox center for geojson geometry, else its point (flat lon/lat). */
 export declare function featureAnchorPoint(feature: unknown): [number, number] | undefined;
+/**
+ * Animated-camera payload coercion (spec: "Map Stories / Animation
+ * primitives"). Payloads arrive as strings from behavior/step attributes
+ * and data-emit, as real values from ctx.emit — coerce both. Durations
+ * accept "800", "800ms", or "2s".
+ */
+export declare function cameraOpts(payload: Record<string, unknown>): {
+    duration: number;
+    curve: boolean;
+};
 /**
  * `trace` — progressive draw. Real tracing needs per-vertex time, which is
  * TripsLayer's whole purpose: sweep `currentTime` across the data's
@@ -16,6 +36,79 @@ export declare function featureAnchorPoint(feature: unknown): [number, number] |
  * back to `fade` with a warning (deck.gl has no dash-offset to fake a
  * draw-on with — documented in the spec).
  */
-export declare const TRACE_TEMP_PREFIX = "__onlymapjs-trace-";
+export { TRACE_TEMP_PREFIX };
+export declare function tracedHiddenSet(core: RuntimeCore, layerId: string): Set<string>;
+/** Re-derive the source layer's `data` hide from the current hidden set: nothing hidden clears the hide, else data = rows minus the union. Clears ONLY the data key — a concurrent effect's keys on the same layer (a story-time fade hold, a pulse) must survive the reveal. */
+export declare function applyTraceHide(core: RuntimeCore, ir: LayerIR, rows: readonly unknown[]): void;
 /** Story scrub restore — drop all trace hide bookkeeping for this core (the channel props themselves are cleared separately by cancelAllLayerEffects). */
 export declare function resetTraceHides(core: RuntimeCore): void;
+/**
+ * The temp outline layer both trace clocks build (wall-clock traceFeature,
+ * story-time EffectTrack): a real runtime-managed <om-layer type="TripsLayer">
+ * riding the normal parse → IR → reconcile pipeline.
+ */
+export declare function buildTraceTempElement(mapEl: Element, tempId: string, outline: {
+    segments: unknown[];
+    total: number;
+}, color: unknown): Element;
+/** Fraction of a per-feature trace slot spent drawing; the rest reveals the real feature and dissolves the outline. */
+export declare const TRACE_DRAW_FRACTION = 0.75;
+/**
+ * Target resolution both trace clocks share — the two payload shapes
+ * (explicit `{ layer, featureId }`, or the pick-derived `{ feature }` a
+ * click behavior supplies; picked objects are FLATTENED by the selection
+ * path, so the pick only contributes an id and the real row is always
+ * looked up from the layer's own data), the row lookup, the outline, and
+ * the per-feature temp-layer id. Null = no traceable outline — callers
+ * fall back to fade.
+ */
+export interface TraceTarget {
+    featureId: string;
+    rows: readonly unknown[];
+    outline: {
+        segments: unknown[];
+        total: number;
+    };
+    tempId: string;
+    /** Columnar data never hides (its rows carry no geometry, so the outline already failed there). */
+    canHide: boolean;
+}
+export declare function resolveTraceTarget(payload: Record<string, unknown>, ir: LayerIR): TraceTarget | null;
+/**
+ * `populate` (spec: "Effect verbs") — rows drop in one by one, the
+ * "populate" effect. Rides the ALWAYS-MOUNTED DataFilterExtension (see
+ * attribute-resolution): each frame only moves the filterRange upper bound
+ * — a uniform update, zero re-upload, the extension's design purpose.
+ * Appearance order:
+ *   - authored `filter-field`: the sweep runs over the AUTHORED range, so
+ *     rows appear in filter-dimension order and the end state IS the
+ *     authored filter — nothing to restore;
+ *   - payload `field`: a one-shot getFilterValue buffer over that field;
+ *   - neither: data order (ordinal index accessor).
+ * GeoJSON without an authored filter falls back to fade: a live composite
+ * does not forward a patched getFilterValue to its sub-layers (the
+ * per-feature-trace lesson).
+ */
+/** Everything a populate sweep needs, computed once up front — `null` means "no sweepable dimension; fall back to fade" (both clocks share this). */
+export interface PopulateSweep {
+    lo: number;
+    hi: number;
+    accessorPatch?: Record<string, unknown>;
+    /** Authored filter dimensions beyond the swept one — held fixed each frame (see the packed filterRange comment below). */
+    otherDimRanges?: [number, number][];
+}
+export declare function preparePopulateSweep(payload: Record<string, unknown>, ir: LayerIR): PopulateSweep | null;
+/**
+ * The populate sweep's per-frame patch: the accessor patch (same references
+ * every frame — the buffer computes once, keyed by its trigger) plus the
+ * swept upper bound. With other authored dimensions present, `filterRange`
+ * must be the FULL packed array (deck.gl's own multi-dimension shape) — the
+ * swept dimension's range first, matching `ir.filter[0]`'s position, then
+ * the rest fixed at their authored ranges.
+ */
+export declare function populateSweepFrame(sweep: PopulateSweep, t01: number): Record<string, unknown>;
+/** Timestamp range of a TripsLayer's data via its own compiled getTimestamps accessor — the trace sweep's domain (shared by both trace clocks). */
+export declare function tripsTimestampRange(ir: LayerIR): {
+    t0: number;
+    t1: number;
+} | null;

package/dist/attribute-resolution.d.ts

@@ -206,6 +206,18 @@ export declare const FULL_JS_COLUMNAR_RULE: {
 };
 /** Coerce a raw attribute string to a primitive: bare/true/false, JSON array/object, number, or string. */
 export declare function coerceValue(raw: string, hint?: PropDescriptor["type"], attrName?: string): unknown;
+/**
+ * Schema defaults must be assigned BY VALUE: several descriptors carry
+ * deck's own defaultProps objects (e.g. `extensions: []`), and assigning
+ * that array by reference aliases it across EVERY layer of the type — one
+ * layer's extension push then mutates deck's class default and leaks into
+ * all siblings (found via the atlas demo: a trace temp that verifiably
+ * skipped filter wiring still built with a DataFilterExtension, because the
+ * defaults pass handed it the type's shared, already-polluted array).
+ * Shallow clone is exactly right: entries (extension instances) may share,
+ * the CONTAINER must not.
+ */
+export declare function cloneDefault(value: unknown): unknown;
 export interface ResolvedAttributes {
     props: Record<string, unknown>;
     meta: LayerMeta;