@nika-js/onlymap 0.6.17 → 0.6.18

package/CHANGELOG.md

@@ -8,6 +8,17 @@ 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.18 — 2026-08-25
+
+### Fixed
+- **A warning when a categorical filter can't do what it looks like it does.** deck.gl's GPU category mask holds at most 128 distinct values per dimension — filtering on a higher-cardinality field (e.g. country names over a world dataset) silently made the overflow rows vanish from the map while widget statistics still counted them. The library now warns, once per layer, naming the field and the ceiling, with the fix to use.
+- **Trace animations no longer vanish on some machines.** Layer settings could leak between layers of the same type (a shared internal default was mutated in place), which could push a trace outline's GPU program over its attribute budget — the outline then silently never rendered. Defaults are now copied per layer.
+
+### Added
+- **Drive a story from an external video renderer (Remotion-class).** Three seams for frameworks that own the clock and ask for arbitrary frames: `mapEl.whenSettled()` (also on `MapController`) resolves once the map has genuinely finished drawing — the natural await for tests and screenshots too; `story.seek(t, { interpolateCamera: true })` lands mid-fly-to seeks on the real flight arc instead of snapping to the leg's end (this also fixes scrubbers); and the `data-om-recording` attribute is now a full determinism switch — camera moves land instantly, effect verbs jump to their end state, transitions and gesture interruption turn off, and `snapshot()` returns byte-stable captures. Acceptance-tested: the same frame renders byte-identically across separate page loads and out-of-order.
+- **On-map annotations without popups**: `anchor="surface"` on a `TextLayer` (or any layer) anchors each row inside its own polygon — labels sit on the shapes themselves, no per-row coordinates authored; concave shapes get an always-inside placement.
+- **Travel-map trace animations**: `<om-step action="trace" follow easing="ease-in-out">` — `follow` locks the camera to the line's drawing tip as it traces (the classic animated-travel-map move), and `easing` picks the clock curve (`linear`, `ease-in`, `ease-out`, `ease-in-out`).
+
 ## 0.6.17 — 2026-08-25
 
 ### Added

package/dist/{LercDecode.es-DjPA9zLm.js → LercDecode.es-CFkuAghv.js}

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

package/dist/{basemap-DwN5jPCj.js → basemap-BYsWqrqp.js}

@@ -1,4 +1,4 @@
-import { C as ny, L as sy, M as oy, m as ay, c as ka, a as Sd, z as oc, G as sm, V as ly, W as cy, b as uy, g as hy, d as Vu, f as Ed, e as dy, l as py, u as fy, D as Qf, h as my } from "./index-CX4qxgVT.js";
+import { C as ny, L as sy, M as oy, m as ay, c as ka, a as Sd, z as oc, G as sm, V as ly, W as cy, b as uy, g as hy, d as Vu, f as Ed, e as dy, l as py, u as fy, D as Qf, h as my } from "./index-h5A4LBtR.js";
 const Cd = Math.PI / 180, gy = 180 / Math.PI;
 function em(Pe, Q = 0) {
   const me = Math.min(180, Pe) * Cd;
@@ -25126,6 +25126,14 @@ class Ry {
       }
     }), this.map.addControl(this.overlay);
   }
+  /** The overlay deck's live layers — whenSettled's readiness gate (issue #37). */
+  getDeckLayers() {
+    return this.overlay._deck?.getLayers?.();
+  }
+  /** One forced draw of both canvases (no capture) — whenSettled's "at least one completed render" guarantee (issue #37). */
+  forceRepaint() {
+    this.overlay._deck?.redraw("onlymapjs-settle"), this.map.triggerRepaint();
+  }
   /** Snapshot capture queue for the overlay's deck canvas — see captureComposite. */
   deckCaptures = [];
   /** In-flight captureComposite rejects — destroy() settles them so a caller never hangs on a torn-down renderer. */

package/dist/basemap.d.ts

@@ -49,6 +49,12 @@ export declare class MapLibreBasemapAdapter {
         pitch?: number;
         bearing?: number;
     }, deckProps: DeckProps, showAttribution?: boolean, attributionHost?: HTMLElement);
+    /** The overlay deck's live layers — whenSettled's readiness gate (issue #37). */
+    getDeckLayers(): {
+        isLoaded: boolean;
+    }[] | undefined;
+    /** One forced draw of both canvases (no capture) — whenSettled's "at least one completed render" guarantee (issue #37). */
+    forceRepaint(): void;
     /** Snapshot capture queue for the overlay's deck canvas — see captureComposite. */
     private deckCaptures;
     /** In-flight captureComposite rejects — destroy() settles them so a caller never hangs on a torn-down renderer. */

package/dist/declarative-filter.d.ts

@@ -19,3 +19,4 @@ export declare function declarativeFilterPredicate(shape: Shape, filter: LayerFi
 export declare function applyDeclarativeCategoryFilter(rows: readonly unknown[], shape: Shape, categoryFilter: LayerCategoryFilter): unknown[];
 /** Categorical twin of `declarativeFilterPredicate` — set membership instead of a range test. */
 export declare function declarativeCategoryFilterPredicate(shape: Shape, categoryFilter: LayerCategoryFilter): (row: unknown) => boolean;
+export declare function warnCategoryCardinality(categoryFilter: LayerCategoryFilter | undefined, rows: readonly unknown[], shape: Shape, warnLabel: string): void;

package/dist/effects.d.ts

@@ -10,6 +10,11 @@
  */
 import type { RuntimeCore } from "./runtime-core";
 /** Pure easing/oscillation math — unit-testable without a clock. */
+/**
+ * Named easing curves for effect verbs (`<om-step action="trace" easing="ease-in-out">`).
+ * Applied to the effect clock BEFORE the frame callback — one place, every verb.
+ */
+export declare const EASINGS: Record<string, (t: number) => number>;
 export declare function traceProgress(t01: number, t0: number, t1: number): number;
 /** Oscillates 1 → low → 1 per cycle (cosine), ending exactly at 1 for whole cycles. */
 export declare function pulseOpacity(t01: number, cycles: number, low?: number): number;
@@ -19,6 +24,8 @@ export interface LayerEffect {
     frame(t01: number): Record<string, unknown>;
     /** What to do at the end: hold the final frame's patch, or clear it. */
     end: "hold" | "clear";
+    /** Optional clock easing (see EASINGS) — applied before `frame`. */
+    easing?: (t: number) => number;
     /** Runs after the end state is applied — phase chaining (trace: draw → reveal → dissolve). */
     onDone?(): void;
 }
@@ -27,12 +34,17 @@ export interface LayerEffect {
  * pure: a GeoJSON-ish feature (or bare geometry / flat row) → the outline
  * path with CUMULATIVE-DISTANCE timestamps, so the draw speed is uniform
  * around the perimeter regardless of vertex spacing. Polygon → outer ring;
- * MultiPolygon → first polygon's outer ring; LineString → the line itself.
+ * MultiPolygon → EVERY part's outer ring, drawn in sequence longest-first
+ * (one currentTime sweep, ring timestamps offset by the running total);
+ * LineString → the line itself.
  * Returns null for untraceable geometry (points, missing geometry).
  */
-export declare function buildTraceOutline(feature: unknown): {
+export interface TraceSegment {
     path: [number, number][];
     timestamps: number[];
+}
+export declare function buildTraceOutline(feature: unknown): {
+    segments: TraceSegment[];
     total: number;
 } | null;
 export declare function cancelLayerEffect(core: RuntimeCore, layerId: string): void;

package/dist/elements/om-map.d.ts

@@ -54,6 +54,7 @@ export declare class OmMapElement extends HTMLElementBase {
     /** Dedup guard for the no-terrain-for-elevation error — same shape as `warnedApproximatePlacement`. */
     private erroredNoTerrainForElevation;
     private readyFired;
+    private firstSettleDrawDone;
     /** Custom-state holder for the `om-collapsed` height-floor marker — see applyHeightFloor. */
     private internals;
     private resolveReady;
@@ -258,6 +259,20 @@ export declare class OmMapElement extends HTMLElementBase {
     /** Harness map-point injection (spec: "Consumer Testing Surface") — the
      *  same path a real deck click/hover coordinate takes, so the om-map-point
      *  event and custom capture tools are testable without a GPU. */
+    /**
+     * The map's "done drawing" promise (issue #37): resolves once every live
+     * 3D tileset has refined for the CURRENT view and one further animation
+     * frame has been painted — the await a pull-model frame renderer (or a
+     * consumer Playwright test) needs before screenshotting. Resolves
+     * `{settled:false}` with a console warning on timeout rather than
+     * rejecting (a late frame is ordinary pop-in, not an error). v1 gates 3D
+     * tilesets only — basemap raster tiles are not yet awaited.
+     */
+    whenSettled(opts?: {
+        timeout?: number;
+    }): Promise<{
+        settled: boolean;
+    }>;
     injectMapPointInternal(coordinate: [number, number] | null, kind?: "click" | "hover", pointerType?: string): void;
     /** Harness setView (spec: "Consumer Testing Surface") — the one path that reaches pitch/bearing. */
     setViewInternal(partial: {

package/dist/elements/om-story.d.ts

@@ -28,7 +28,9 @@ export declare class OmStoryElement extends HTMLElementBase {
     get duration(): number;
     play(): void;
     pause(): void;
-    seek(ms: number): void;
+    seek(ms: number, opts?: {
+        interpolateCamera?: boolean;
+    }): void;
     /**
      * Per-frame capture hook for paced runs (the recorder seam, issue #16):
      * called after each paced frame is fully refined and BEFORE the frame's

package/dist/{geoparquet-DG3VtNgs.js → geoparquet-C5ezOpDN.js}

@@ -1,4 +1,4 @@
-import { r as p, n as d } from "./index-CX4qxgVT.js";
+import { r as p, n as d } from "./index-h5A4LBtR.js";
 function g(t) {
   if (t == null) return !0;
   const e = t, n = e.id?.code;

package/dist/{index-DlXIfdhF.js → index-B0qtzfOX.js}

@@ -1,4 +1,4 @@
-import { ak as Bt, ax as Xt, ay as Yt, az as Us } from "./index-CX4qxgVT.js";
+import { ak as Bt, ax as Xt, ay as Yt, az as Us } from "./index-h5A4LBtR.js";
 import { w as gs, t as Hs, f as Ws, m as Qs } from "./mgrs-BY9bIvp4.js";
 import { c as Xs } from "./convert-arrow-schema-DrAihRf9.js";
 import { y as Ys, A as bt, a as Ks, z as Vs, R as Zs } from "./recordbatch-Bpc0uxFn.js";

package/dist/{index-DceORL-v.js → index-C7pRTBjN.js}

@@ -1,5 +1,5 @@
-import { i as E, j as S, k as R, o as N, p as h, q as w, s as O, t as W, v as x, w as I, x as B, y as _, A as P, B as k, E as $, F as z, H as v, I as F, J as C, K as U, N as p, O as M } from "./index-CX4qxgVT.js";
-import { P as $e, R as ze, _ as ve, Q as Ce, S as Ue, T as Me, U as je, X as De, Y as Je, Z as qe, $ as He, a0 as Ve, a1 as Ge, a2 as Ke, a3 as Qe, a4 as Xe, a5 as Ye, a6 as Ze, a7 as et, a8 as tt, a9 as nt, aa as rt, ab as at, ac as st, ad as ot } from "./index-CX4qxgVT.js";
+import { i as E, j as S, k as R, o as N, p as h, q as w, s as O, t as W, v as x, w as I, x as B, y as _, A as P, B as k, E as $, F as z, H as v, I as F, J as C, K as U, N as p, O as M } from "./index-h5A4LBtR.js";
+import { P as $e, R as ze, _ as ve, Q as Ce, S as Ue, T as Me, U as je, X as De, Y as Je, Z as qe, $ as He, a0 as Ve, a1 as Ge, a2 as Ke, a3 as Qe, a4 as Xe, a5 as Ye, a6 as Ze, a7 as et, a8 as tt, a9 as nt, aa as rt, ab as at, ac as st, ad as ot } from "./index-h5A4LBtR.js";
 import { g as j, i as D } from "./table-accessors-CYWTzpQI.js";
 async function J(t, e, n = {}, r = {}) {
   const a = E(t), s = S.getWorkerFarm(n), { source: o } = n, c = { name: a, source: o };

package/dist/{index-Yl9rVUWh.js → index-PHDt5jos.js}

@@ -1,4 +1,4 @@
-import { ag as Be, ah as le, ai as ce, aj as De, ak as Oe, al as ke } from "./index-CX4qxgVT.js";
+import { ag as Be, ah as le, ai as ce, aj as De, ak as Oe, al as ke } from "./index-h5A4LBtR.js";
 import { y as ve, a as he, z as G, R as J, A as ue, C as Fe, F as je, n as xe, S as Ie, E as Ne } from "./recordbatch-Bpc0uxFn.js";
 import { g as V, a as fe, b as Le, c as Ue, d as Me, e as qe, m as Ve } from "./table-accessors-CYWTzpQI.js";
 import { c as $e } from "./convert-arrow-schema-DrAihRf9.js";

package/dist/{index-BM-txQRw.js → index-T1jT84TY.js}

@@ -1,4 +1,4 @@
-import { ae as _t, af as Ct } from "./index-CX4qxgVT.js";
+import { ae as _t, af as Ct } from "./index-h5A4LBtR.js";
 function Yt(e, r, t = 2, i, o = "xy") {
   const s = r && r.length, l = s ? r[0] * t : e.length;
   let c = Ut(e, 0, l, t, !0, i && i[0], o);