@nika-js/onlymap 0.6.19 → 0.6.21

package/dist/basemap.d.ts

@@ -49,8 +49,24 @@ export declare class MapLibreBasemapAdapter {
         pitch?: number;
         bearing?: number;
     }, deckProps: DeckProps, showAttribution?: boolean, attributionHost?: HTMLElement, deterministic?: boolean);
-    /** whenSettled's basemap gate (issue #37 follow-up): style + all raster/vector tiles for the current view fully loaded. */
+    /**
+     * whenSettled's basemap gate (issue #37 follow-up), as an EVENT LATCH
+     * rather than a polling predicate: MapLibre's `idle` event is its own
+     * definition of done — camera transitions finished, all requested tiles
+     * loaded, all fades/transitions complete — which is strictly stronger
+     * than `loaded() && areTilesLoaded()` (those say nothing about label
+     * fade/collision animation, the measured source of warm-page frame
+     * nondeterminism). The latch clears on anything that restarts work
+     * (camera writes, a source starting to load, a style change) and sets
+     * again only on the next `idle`, so `isIdle()` stays a synchronous read —
+     * settleOnce's `loaded()` shape — and both lanes plus `onlymapjs record`
+     * inherit it unchanged.
+     */
+    private idleLatch;
+    private wireIdleLatch;
     isIdle(): boolean;
+    /** Camera writes from OUR side must clear the latch immediately — the map's own movestart fires a tick later, and a settle read in that gap would see stale idle. */
+    private markBusy;
     /** The overlay deck's live layers — whenSettled's readiness gate (issue #37). */
     getDeckLayers(): {
         isLoaded: boolean;

package/dist/declarative-filter.d.ts

@@ -1,22 +1,8 @@
-/**
- * CPU-side mirror of the GPU `DataFilterExtension` test (spec: "Filter-aware
- * stats & data (the coherence rule)") — `ctx.stats`/`ctx.dataInViewport`
- * apply the SAME field+range/category test(s) by default, so a chart/stat
- * reflects what the map visibly shows. A row whose field isn't a finite
- * number (numeric) or isn't in the keep-list (categorical) is treated as
- * filtered-out, matching the GPU path. With more than one dimension of
- * EITHER kind a row passes only if every dimension's test passes (AND
- * across dimensions) — the same semantics deck.gl's own packed
- * `filterRange`/`filterCategories` arrays apply GPU-side. Numeric and
- * categorical are independent mechanisms (see `applyFilterWiring`'s doc
- * comment) but combine the same way: a row must pass BOTH kinds when both
- * are active on a layer.
- */
-import type { Shape, LayerFilter, LayerCategoryFilter } from "./ir";
+import type { Shape, LayerFilter, LayerCategoryFilter, LayerData } from "./ir";
 export declare function applyDeclarativeFilter(rows: readonly unknown[], shape: Shape, filter: LayerFilter): unknown[];
 /** The same test as a reusable predicate — the columnar viewport filter runs it inside its index-aligned loop. */
 export declare function declarativeFilterPredicate(shape: Shape, filter: LayerFilter): (row: unknown) => boolean;
 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;
+export declare function warnCategoryCardinality(categoryFilter: LayerCategoryFilter | undefined, data: LayerData, shape: Shape, warnLabel: string): void;

package/dist/effect-track.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Story-time effect evaluation (spec: "Map Stories" / issue #37's pull
+ * model, completed for layer effects). `buildCameraLegs`/`cameraAtTime`
+ * already make the camera a pure function of story time; this module does
+ * the same for the animated verbs (fade / pulse / trace / populate). When
+ * the story owns the clock — a paced story (the recorder) or the
+ * determinism switch (frame renderers seeking) — those steps are NOT
+ * dispatched as actions: the story builds one EffectTrack from its timeline
+ * and evaluates every leg at the current story time on each tick or seek.
+ * A trace 40% drawn is then just a scene, reproducible at any t, instead
+ * of a wall-clock rAF loop racing the capture.
+ *
+ * Interactive wall-clock playback is untouched: it keeps dispatching the
+ * verbs through actions.ts, whose rAF path (effects.ts) remains the clock
+ * for anything without a timeline (click-to-trace behaviors, ctx.emit).
+ * Both clocks share the same underlying builders — the pure math
+ * (traceProgress, pulseOpacity, EASINGS), the populate sweep, the trace
+ * target/temp element — so a verb renders identically whichever clock
+ * drives it.
+ *
+ * Evaluation contract: legs are stateless functions of t, EXCEPT the
+ * documented enter/exit hooks (temp-layer DOM, trace hide sets), which the
+ * evaluator invokes on phase transitions. Seek resets are handled by the
+ * story's existing scrub model — restore-initial clears every channel patch
+ * and temp layer, then resetState() forgets all phases and applyAt(t)
+ * rebuilds the scene from pristine. Follow cameras are the one exception:
+ * during a paced run the driver owns the camera, so `follow` is skipped
+ * (warned once per track).
+ */
+import type { RuntimeCore } from "./runtime-core";
+import type { LayerIR } from "./ir";
+import type { StepInterval } from "./timeline";
+/** The verbs the track owns — fireDueSteps suppresses exactly these while the story clock drives effects. */
+export declare const EFFECT_TRACK_ACTIONS: Set<string>;
+export interface EffectTrackDeps {
+    core: RuntimeCore;
+    mapEl: Element;
+    /**
+     * LIVE accessor, never a snapshot: om-map REASSIGNS its IR map on every
+     * reconcile (`this.layerIRs = next`), so a captured reference goes stale
+     * after the first reconcile of a run — which is guaranteed (the trace
+     * leg's own temp-element append triggers one). Legs re-init when a
+     * layer's data identity changes (URL arrival), which only works read
+     * through here.
+     */
+    getLayerIRs(): ReadonlyMap<string, LayerIR>;
+}
+/** A leg's resolved behavior — chosen lazily on first need, when the layer's data is in hand. */
+interface LegImpl {
+    /** Eased t01 → per-layer patches (the same shapes the wall-clock path writes through patchAnimatedProps). */
+    frame(t01: number): Record<string, Record<string, unknown>>;
+    /** "hold": past the leg, keep frame(1) applied. "clear": past the leg, the authored state IS the end state. */
+    end: "hold" | "clear";
+    /** Phase-entry hook (idempotent per activation): temp layers, trace hides. */
+    enter?(): void;
+    /** Phase-exit hook: teardown of whatever enter() built. */
+    exit?(): void;
+}
+interface Leg {
+    layerId: string;
+    start: number;
+    duration: number;
+    easing?: (t: number) => number;
+    init(deps: EffectTrackDeps): LegImpl | null;
+}
+export declare class EffectTrack {
+    private readonly legs;
+    private readonly deps;
+    private states;
+    /** Set by deactivate() (including ensureImpl's re-init teardown) — the heal pass re-applies what a removeEffectKeys may have stripped from a shared layer. */
+    private keysRemoved;
+    constructor(legs: Leg[], deps: EffectTrackDeps);
+    /** Forget all phase state WITHOUT teardown — call only after the story's restore-initial has already cleared patches and temp layers. */
+    resetState(): void;
+    /**
+     * Evaluate every leg at story time t. CONTRACT: t is monotonically
+     * non-decreasing between resetState() calls — every caller guarantees it
+     * (advanceBy is monotone; seek and the loop restart reset first), so
+     * phases only ever move forward here and no backward transition exists.
+     * Legs are pre-sorted by start, so cross-leg chains resolve in timeline
+     * order.
+     */
+    applyAt(t: number): void;
+    /** Re-applies leg i's current value: frame(1) for a settled hold, the eased frame at t for an active leg, nothing otherwise. Idempotent. */
+    private applyLegFrame;
+    private ensureImpl;
+    private apply;
+    private deactivate;
+}
+export declare function buildEffectTrack(steps: readonly {
+    action: string;
+    payload: Record<string, unknown>;
+}[], intervals: readonly StepInterval[], deps: EffectTrackDeps): EffectTrack;
+export {};

package/dist/effects.d.ts

@@ -18,6 +18,8 @@ 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;
+/** Removes exactly one effect's keys from the layer's channel entry, preserving keys other writers own. (Exported for the story-time EffectTrack, which manages its own written-key sets.) */
+export declare function removeEffectKeys(core: RuntimeCore, layerId: string, keys: Set<string>): void;
 export declare function prefersReducedMotion(): boolean;
 export interface LayerEffect {
     /** t01 ∈ [0, 1] → the plain-prop patch for this frame. */

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

@@ -1,4 +1,5 @@
 import { HTMLElementBase } from "../env";
+import { RuntimeCore } from "../runtime-core";
 import { type RuntimeContext } from "../ctx";
 import { type LightingIR } from "../scene-lighting";
 import { type ClipBoxIR } from "../clip-box";
@@ -54,7 +55,6 @@ 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;
@@ -260,19 +260,22 @@ export declare class OmMapElement extends HTMLElementBase {
      *  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.
+     * The map's "done drawing" promise (issue #37) — delegates to
+     * RuntimeCore.whenSettled, the single owner of the settle contract.
      */
     whenSettled(opts?: {
         timeout?: number;
     }): Promise<{
         settled: boolean;
     }>;
+    /** Test surface: is the determinism switch active on the core (issue #37 — must be true BEFORE the first render when data-om-recording is authored; the basemap adapter reads it in its constructor). */
+    isDeterministicInternal(): boolean;
+    /** What the story-time EffectTrack needs to evaluate legs (om-story builds one when the story clock owns effects — paced stories, determinism). getLayerIRs is a LIVE accessor: reconcile REASSIGNS this.layerIRs, so a captured map reference would go stale after the first reconcile of a run. */
+    getEffectDepsInternal(): {
+        core: RuntimeCore;
+        mapEl: Element;
+        getLayerIRs(): ReadonlyMap<string, LayerIR>;
+    } | null;
     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

@@ -15,6 +15,8 @@ export declare class OmStoryElement extends HTMLElementBase {
     private pacedGen;
     /** True while the paced driver owns the camera — fireDueSteps must not dispatch camera actions against it. */
     private pacedDriving;
+    /** Story-time effect evaluation (effect-track.ts) — built lazily when the story clock owns effects, invalidated whenever steps rebuild. */
+    private effectTrack;
     private warnedPacedCameraSkip;
     private pacedCapture;
     private captured;
@@ -64,6 +66,22 @@ export declare class OmStoryElement extends HTMLElementBase {
      */
     private startPaced;
     private advanceBy;
+    /**
+     * The story clock owns effects when playback is pull-model: a PACED STORY
+     * (the recorder — wall-clock rAF effects would race the capture clock) or
+     * the determinism switch (frame renderers seek; runLayerEffect snaps
+     * there). Keyed on the `paced` ATTRIBUTE, deliberately not the transient
+     * pacedDriving flag: the flag drops asynchronously on pause, and a
+     * scrubber seek in that window would otherwise dispatch the verbs
+     * wall-clock (stamping end-state attributes, starting real rAF runners)
+     * that the resumed track then double-drives. The clock authority must be
+     * stable for a whole playback; flipping it mid-story is out of contract
+     * (the next seek re-evaluates cleanly). Interactive wall-clock playback
+     * keeps dispatching the verbs as actions — the rAF path in effects.ts is
+     * untouched.
+     */
+    private storyClockOwnsEffects;
+    private ensureEffectTrack;
     private fireDueSteps;
     /** Steps and the timeline are (re)built lazily when idle — mid-play DOM edits apply on the next play/seek. */
     private ensureBuilt;

package/dist/{geoparquet-DWQCUg6N.js → geoparquet-fc2daxMh.js}

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

package/dist/{index-CeeQ7CH4.js → index-9EEyGbU1.js}

@@ -1,4 +1,4 @@
-import { ae as _t, af as Ct } from "./index-CagRqDDL.js";
+import { ae as _t, af as Ct } from "./index-CuBGRyG-.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);

package/dist/{index-4St6BumW.js → index-BNZFF535.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-CagRqDDL.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-CagRqDDL.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-CuBGRyG-.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-CuBGRyG-.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-BTM6Mblt.js → index-BwoceNAo.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-CagRqDDL.js";
+import { ag as Be, ah as le, ai as ce, aj as De, ak as Oe, al as ke } from "./index-CuBGRyG-.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";