@nika-js/onlymap 0.6.20 → 0.6.22

package/CHANGELOG.md

@@ -8,6 +8,25 @@ 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.22 — 2026-08-26
+
+### Added
+- **Scale-dependent visibility on every layer type.** `visible-zoom-range="[8, 14]"` hides a layer outside that zoom span (min inclusive, max exclusive — the standard minzoom/maxzoom convention), the everyday GIS pattern for keeping dense layers from swamping a zoomed-out view. Works on vector layers, not just tile layers; the layer stays in the legend and layer switcher while zoom-hidden. (#38)
+- **A machine-readable attribute contract, `onlymapjs.attributes.json`.** Tools that generate OnlyMapJS markup can now validate attributes per layer type — the editor IntelliSense file is a flat union and could pass attributes the runtime rejects. The new file is generated from the same registry the runtime validates against, so the two can't drift; IntelliSense hovers now also say which layer types accept each attribute. (#38)
+- **A silent-empty-layer class of mistake now warns.** A layer whose required position accessor resolves to nothing for every row — a `TextLayer` fed GeoJSON with no `get-position` being the reported case — previously rendered an empty map with a clean console. It now warns once with the exact fix, on the console and through the `validate` panel. Layers where the default genuinely works are untouched. (#39)
+
+## 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

package/README.md

@@ -83,7 +83,7 @@ A handful of elements, one rule: **attributes are kebab-case versions of deck.gl
 | Element | Role |
 |---|---|
 | `<om-map>` | The map. `center`, `zoom`, `pitch`, `bearing`; `basemap` takes a free preset (`positron`, `liberty`, `dark-matter`, `osm`, …), a style URL, or `"none"` (standalone canvas) — and switches **live**; `validate` for a live on-page error panel. Give it a height: a custom element is `display:inline` by default, so the library injects a `display:block` default (fills a sized parent, else a 400px floor) to keep a bare map visible, but set an explicit height (`om-map { height: 100vh }`) for real layout — any height you set wins outright, including one below the floor. A map that still collapses warns in the console; `hidden` and `display:none` maps stay hidden and stay quiet. |
-| `<om-layer>` | Any of **39 layer types** by name — all of deck.gl's core, geo, aggregation, and mesh layers (Scatterplot, GeoJson, Arc, Path, Heatmap, Hexagon, Trips, Tile, Tile3D, Scenegraph, …) plus the built-in `PopupLayer` for WebGL badges/labels at scale, the native `COGLayer` for GeoTIFF rasters, `ZarrLayer` for chunked Zarr/GeoZarr rasters, `ImageOverlay` for georeferenced drone JPEGs, `BIMLayer` for BIM source files (`.ifc` today) loaded straight in the browser with no pre-conversion step, and `Route`/`Tracking` for styled routes and live position tracking. `id` required; `label`/`color` feed the legend. |
+| `<om-layer>` | Any of **39 layer types** by name — all of deck.gl's core, geo, aggregation, and mesh layers (Scatterplot, GeoJson, Arc, Path, Heatmap, Hexagon, Trips, Tile, Tile3D, Scenegraph, …) plus the built-in `PopupLayer` for WebGL badges/labels at scale, the native `COGLayer` for GeoTIFF rasters, `ZarrLayer` for chunked Zarr/GeoZarr rasters, `ImageOverlay` for georeferenced drone JPEGs, `BIMLayer` for BIM source files (`.ifc` today) loaded straight in the browser with no pre-conversion step, and `Route`/`Tracking` for styled routes and live position tracking. `id` required; `label`/`color` feed the legend. `visible-zoom-range="[8, 14]"` gives any layer scale-dependent visibility (hidden outside min ≤ zoom < max, the standard minzoom/maxzoom convention) — the everyday GIS pattern for keeping a dense layer from swamping a zoomed-out view. |
 | `<om-widget>` | UI panels. Built-ins: `legend` (symbology-aware: color scales render as gradient ramps or class ranges, categorical ternaries as discrete palettes), `layer-switcher`, `basemap-switcher`, `lighting`, `clip-box`, `zoom-controls`, `undo-redo`, `scale-bar` (metric/imperial/nautical `units`), `attribution`, `filter`, `draw` (point/line/polygon sketch capture, GeoJSON save/autosave; lines/polygons complete via double-click, touch double-tap — detected by the library itself, since iOS WebViews never synthesize `dblclick` from taps — Enter, or the toolbar's Finish button; `export-3d` adds an "Export 3D" button that clips loaded `Tile3DLayer`/`BIMLayer` content to the drawn footprint and downloads it as a portable GLB — re-framed to a local coordinate frame at the footprint's own centroid, each triangle carrying its own source color as vertex colors, no textures — or, with `export-3d="b3dm"`, the same mesh wrapped for Cesium/3D-Tiles pipelines; only currently-visible 3D Tiles/BIM layers are included — a layer hidden via `visible="false"` or the `toggle-layer` action is skipped, with a distinct console warning for "nothing loaded" vs. "everything hidden"), `measure` (geodesic distance + area + cut/fill volume — live labels, `units` toggle, an `om-measure` readout event; `modes="distance area volume"` adds a footprint-then-extrude tool: outline a polygon, double-click (double-tap on touch) to close it — it turns solid teal, ready — then drag the double-headed arrow gizmo that appears at its centroid up to fill or down to cut, reading out Cut/Fill/Net (signed, fill−cut)/Total (unsigned, cut+fill) volume plus Area/Perimeter, each labelled with its own sign convention. The math is a REAL per-cell grid integration: closing a footprint bulk-loads its covering DEM tiles, lays a metric grid in a local tangent frame at the ring centroid (cell size = the DEM's ground-sample distance; scanline point-in-polygon; bilinear, tile-seam-correct sampling; worker-offloaded), and integrates terrain-vs-base per cell — mixed cut AND fill within one footprint on undulating ground, with a published ±error (per-cell cellArea × 1.5 × GSD, summed per side), the cell size used, and a no-data warning all carried on the `om-measure` readout (`cellSizeM`/`gsdM`/`cutErrorM3`/`fillErrorM3`/`nodataFraction`). A `base-surface` attribute picks the reference surface: `custom` (default — the gizmo's draggable target plane), or boundary-derived stockpile strategies with no gizmo (`triangulated` boundary TIN, `plane` least-squares fit, `lowest`/`highest`/`average`). On `custom`, the extruded prism's own boundary hugs each corner's real ground elevation by default (so it doesn't visibly float above or sink below sloped terrain) — a "Flat target plane" toggle button appears above the readout once a footprint closes, switching that rendering to a single level plane instead (a rendering choice only; the underlying cut/fill numbers were already computed against one flat target elevation either way). Requires `terrain` on `<om-map>` — validation warns if `volume` is in `modes` with none (without terrain a flat-plane fallback runs, with no error figures — nothing honest to quote). A `profile` attribute alongside `modes` — not a mode of its own — samples elevation around a volume footprint's own perimeter as it's drawn and closed, live, and dispatches it on `om-measure`'s `profileSeries` field for a `dynamic-chart` widget to plot. Each sample is `{x: distance-from-start-m, y: elevation-m}`, and samples that ARE one of the drawn footprint's own corners additionally carry `vertexIndex` (0-based, in draw order) — so a chart can mark the real corners instead of every interpolated sample, and the widget's built-in profile chart marks each corner, labelling the first `1 · Start`. The map badges the first two vertices in draw order (`1 · Start`, `2`), which states the ring's direction outright — a start marker alone leaves clockwise vs counter-clockwise ambiguous, and the two wind to mirror-image profiles. Two badges is the minimum that fixes a direction and a constant cost regardless of how many corners the footprint has. Also volume-only: `deadband` (m³) zeroes out a Cut/Fill figure below the threshold, filtering drag noise near zero height (Cut/Fill/Net/Total are always RAW geometric volumes — deliberately unaffected by `swell`/`shrink`, so they keep answering "does this reach target elevation" regardless of what material's configured); `density` (t/m³ metric, lb/yd³ imperial) and `swell`/`shrink` (multipliers, default 1×) instead populate a separate Material section, standard Bank/Loose/Compacted earthworks convention — Adjusted Cut = raw × swell (loose/haul volume, bigger — excavating adds air voids), Adjusted Fill = raw ÷ shrink (loose/borrow volume needed, also bigger — the raw fill is already the compacted target void), plus Cut/Fill tonnage computed from the raw (not adjusted) volume, since swell/shrink change volume, not mass; the section only appears once at least one of `density`/`swell`/`shrink` is actually configured, no separate toggle. A `stale` field on the `om-measure` readout flags the brief window between a footprint committing and its elevation sample resolving, so a consumer doesn't read numbers left over from a prior footprint as current), `vega-lite` (live charts bound to a layer's data), `dynamic-chart` (the same Vega-Lite rendering, but data-driven by a live DOM event instead of a layer — `on="<event-name>"` + `series-field="<name>"` reads `event.detail[seriesField]` as the chart's `values` on every matching event, redrawing at a fixed `width`; a feature "freezes" it for free by simply omitting that field the next time it fires, no separate pause API needed), and the BIM set `ifc-browser` / `feature-inspector` / `ifc-loader` / `ifc-clash`. Or write your own inline with HTML + a `<script type="om/widget">`. Adjacent compact button widgets (`zoom-controls`, `undo-redo`, `widgets-toggle`) **auto-cluster** into one control group (opt out per widget with `cluster="false"`), and `<om-map widgets-hidden>` / the `set-widgets-visible` action / `<om-widget type="widgets-toggle">` hide all authored chrome without destroying it — provider attribution and the license badge never hide. **Placement is managed**: `position` takes one of 8 logical, RTL-aware slots (`top-start`, `top-center`, `top-end`, `center-start`, `center-end`, `bottom-start`, `bottom-center`, `bottom-end`; legacy corner names alias) — same-slot widgets stack with flush edges and a shared gap, `order` sets in-slot ordering, and `position="manual"` opts out entirely (a plain block you style yourself, even outside the map). At map widths ≤640px, managed widgets automatically move into accessible top/end/bottom/start drawers; `fold="never"` keeps an essential control out, `widgets-fold="off"` disables folding, and `--om-widget-fold-breakpoint` changes the map-width threshold. Provider attribution is an in-flow member of `bottom-end` and the license badge of `bottom-start`, so neither covers a widget. A slot dims automatically while an open popup covers it (`widgets-dim="off"` to disable), except slots containing required chrome. Themeable from plain page CSS via custom properties: `om-map { --om-widget-bg: #111827; --om-widget-fg: #f9fafb; }` (also `-muted`, `-border`, `-hover-bg`, `-accent`), plus layout tokens (`--om-widget-inset-x/-y`, `--om-widget-gap-x/-y`, `--om-widget-opacity`, `--om-widget-radius`) or the no-CSS sugar `<om-map widget-style="gap:10 opacity:0.9">`. |
 | `<om-overlay>` | Rich HTML anchored to a map location — a static `anchor="[lng, lat]"`, the current selection, or a feature's own geometry via `anchor-layer`/`anchor-feature-id`. Selection-anchored overlays scope with `layer` (one layer's picks) and `selection-type="click"`/`"hover"` (one pick type — give a click-opened popup `selection-type="click"` so hovering elsewhere doesn't drag it along). `{{field}}` interpolates the picked feature, HTML-escaped by default; `{{z}}` is a real depth-picked elevation when some layer under the cursor set `pickable="3d"` (terrain does this itself, so hovering the ground always has one) — empty otherwise, never a misleading 0. `clip-to-map` (opt-in) hides the overlay when its own box would spill past the map viewport, not just when its anchor leaves — for small transient tips that track the cursor, where an overhanging box would otherwise inflate the page's scroll overflow and cause visible view jitter. |
 | `<om-behavior>` | Declarative interactions: `on="click|hover|drag|load|data-loaded"` → a named action. |
@@ -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-DiDn51b8.js → LercDecode.es-Cm-Ah1Pr.js}

@@ -19,7 +19,7 @@ async function v(N = {}) {
   if (n) {
     const { createRequire: I } = await import(
       /*webpackIgnore:true*/
-      "./lerc-C3kqqJ1B.js"
+      "./lerc-Dt2MXtZG.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

@@ -1,4 +1,4 @@
-import type { LayerMeta, LayerFilter, LayerCategoryFilter } from "./ir";
+import type { LayerMeta, LayerFilter, LayerCategoryFilter, LayerData } from "./ir";
 import type { LayerSchema, PropDescriptor } from "./layer-registry";
 import type { Shape } from "./expr";
 /** Sweeps the shared caches down to exactly the keys still referenced by the current manifest (Q4). */
@@ -39,8 +39,49 @@ export declare function kebabToCamel(name: string): string;
 export declare const DASH_ATTRS: Set<string>;
 /** Classified symbology (spec: issue #12; src/classify.ts) — universal layer attributes like `filter-*`, resolved where the data is in hand (parse-manifest / descriptorToIR), never per-schema deck props. */
 export declare const CLASSIFY_ATTRS: Set<string>;
+/**
+ * Per-layer zoom visibility (public issue #38) — a universal layer
+ * attribute honoured on EVERY layer type: `visible-zoom-range="[8, 14]"`
+ * hides the layer outside min ≤ zoom < max (the minzoom/maxzoom convention
+ * every web-map stack uses — Mapbox/MapLibre semantics, so translated
+ * manifests behave identically). Scale-dependent visibility is the everyday
+ * GIS concept; deck's own visible-*-zoom props exist only on tile layers.
+ * The gate composes with (never overrides) authored `visible`.
+ */
+export declare const ZOOM_VISIBILITY_ATTR = "visible-zoom-range";
+/** Pure coercion (no console) — validation.ts shares it so validate() reports the same malformed shapes structurally. */
+export declare function coerceVisibleZoomRange(raw: unknown): [number, number] | undefined;
+export declare function parseVisibleZoomRange(raw: unknown, warnLabel: string): [number, number] | undefined;
+/** The gate itself — min inclusive, max exclusive (minzoom/maxzoom convention). */
+export declare function zoomInVisibleRange(range: [number, number], zoom: number): boolean;
 /** Layer types whose deck class strokes a path, so PathStyleExtension's dash takes effect (GeoJsonLayer/PolygonLayer dash their line/stroke sublayers). */
 export declare const DASH_CAPABLE_LAYERS: Set<string>;
+/** A ValidationEntry-compatible shape, structural to avoid the validation.ts import cycle. */
+interface AccessorWarningSink {
+    (entry: {
+        severity: "warning";
+        element: string;
+        attribute: string;
+        message: string;
+        fix: string;
+    }): void;
+}
+/**
+ * Public issue #39: a standalone TextLayer fed GeoJSON with no get-position
+ * renders NOTHING, silently — deck's default accessor (`x => x.position`)
+ * resolves undefined for every feature and the glyphs cull. The identical
+ * mistake THROWS on columnar data, so the silence is an asymmetry, not a
+ * policy. This samples the first row through the deck DEFAULT for every
+ * schema-required accessor the author did not claim: a defined result means
+ * the default genuinely works (flat rows with a `position` field — stay
+ * silent), an undefined one means nothing will draw — warn, with the exact
+ * fix. Columnar is skipped (deck already errors loudly there), as is
+ * URL-backed data that hasn't arrived (rows resolve on the reparse).
+ *
+ * `OmMap.validate()` keeps its stricter unconditional required-accessor
+ * ERROR — this is the runtime twin for authors who never call validate.
+ */
+export declare function warnUnresolvedRequiredAccessors(schema: LayerSchema, props: Record<string, unknown>, data: LayerData, shape: Shape, elementDesc: string, report?: AccessorWarningSink): void;
 /** A dash pattern authored as a JSON array (`[6, 3]`) OR an SVG-style token list (`6 3`, `6,3`) → `[dashLength, gapLength]`; undefined if it isn't two finite positive numbers. */
 export declare function parseDashArray(raw: string): [number, number] | undefined;
 /** Already-coerced dash declaration — attribute strings (DOM) or typed values (programmatic). */
@@ -206,6 +247,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;
@@ -219,3 +272,4 @@ export interface ResolvedAttributes {
     categoryFilter?: LayerCategoryFilter;
 }
 export declare function resolveLayerAttributes(el: Element, schema: LayerSchema, shape: Shape): ResolvedAttributes;
+export {};

package/dist/{basemap-Bvtudw-w.js → basemap-BCZ-MbEU.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-CPthQWzC.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-Ddn4yvyL.js";
 const Cd = Math.PI / 180, gy = 180 / Math.PI;
 function em(Pe, J = 0) {
   const me = Math.min(180, Pe) * Cd;
@@ -25321,7 +25321,7 @@ class Ry {
     Me && me > 0 ? this.map.flyTo(Te) : this.map.easeTo(Te);
   }
   fitBounds(J, me, Me = 0) {
-    this.map.fitBounds(J, { padding: me, duration: Me });
+    this.markBusy(), this.map.fitBounds(J, { padding: me, duration: Me });
   }
   destroy() {
     if (this.pendingCaptureRejects.size > 0) {

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,13 +260,8 @@ 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;
@@ -275,6 +270,12 @@ export declare class OmMapElement extends HTMLElementBase {
     }>;
     /** 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-DFfq6-JJ.js → geoparquet-BaYtod1j.js}

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

package/dist/html-data.d.ts

@@ -22,4 +22,18 @@ export declare function buildHtmlCustomData(): {
     version: number;
     tags: TagData[];
 };
+/**
+ * Machine-readable per-layer-type attribute contract (public issue #38) —
+ * shipped as `onlymapjs.attributes.json`. The html-customData format cannot
+ * scope an attribute to a `type=` value, so a CI check validating emitted
+ * markup against the flat union passes attributes the runtime rejects (the
+ * QGIS2WebMap visible-min-zoom case; #36's dash hid in the same gap).
+ * Generated from the SAME registry the runtime's typo-check validates
+ * against, so the two cannot drift: an attribute is accepted on a type iff
+ * it is in `universal` or in `layers[<type>]`.
+ */
+export declare function buildLayerAttributeContract(): {
+    universal: string[];
+    layers: Record<string, string[]>;
+};
 export {};

package/dist/{index-DIHnIeho.js → index-BlUSpugF.js}

@@ -1,4 +1,4 @@
-import { ak as Bt, ax as Xt, ay as Yt, az as Us } from "./index-CPthQWzC.js";
+import { ak as Bt, ax as Xt, ay as Yt, az as Us } from "./index-Ddn4yvyL.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-Cq0qmoDj.js → index-C2DPJtsQ.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-CPthQWzC.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-CPthQWzC.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-Ddn4yvyL.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-Ddn4yvyL.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 };