@nika-js/onlymap 0.2.2 → 0.3.0

package/dist/basemap-registry.d.ts

@@ -23,6 +23,14 @@ export interface BasemapPreset {
 }
 /** MapLibre's own official, freely-hosted demo style — the zero-config `basemap="maplibre"` default (back-compat). */
 export declare const MAPLIBRE_DEMO_STYLE = "https://demotiles.maplibre.org/style.json";
+/**
+ * Is this `basemap` value a bring-your-own style URL rather than a preset
+ * name? Any URL scheme counts, not just http(s) — desktop webviews serve
+ * styles over custom protocols (Tauri `asset://` / `nika-file://`, Electron
+ * equivalents), and a query string must not defeat the `.json` path form
+ * (`nika-file:///styles/dark.json?v=2`).
+ */
+export declare function isStyleUrl(raw: string): boolean;
 export declare function registerBasemap(name: string, preset: BasemapPreset): void;
 export declare function getBasemap(name: string): BasemapPreset | undefined;
 export declare function getAllBasemaps(): ReadonlyMap<string, BasemapPreset>;
@@ -32,6 +40,8 @@ export declare function configureBasemap(config: {
 }): void;
 /** Static-validation support: is a key available for this provider (from configureBasemap)? */
 export declare function hasConfiguredKey(provider: "maptiler"): boolean;
+/** The configured key itself — terrain presets substitute it the way resolveBasemapStyle does (publishable client key, internal use). */
+export declare function getConfiguredKey(provider: "maptiler"): string | undefined;
 export interface ResolvedBasemap {
     style: BasemapStyle;
     attribution?: string;

package/dist/basemap.d.ts

@@ -46,11 +46,34 @@ export declare class MapLibreBasemapAdapter {
         pitch?: number;
         bearing?: number;
     }, deckProps: DeckProps, showAttribution?: boolean);
+    /** 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. */
+    private pendingCaptureRejects;
+    private drainDeckCaptures;
+    /**
+     * Scene snapshot (spec: "Snapshot API") — one composite canvas of the
+     * basemap + deck canvases at device pixels. Neither context keeps its
+     * drawing buffer, so each canvas is copied synchronously inside its own
+     * post-render callback after a forced repaint: the basemap via
+     * `map.once("render")` + triggerRepaint, the deck canvas via the
+     * overlay's onAfterRender (forced through the overlay's internal Deck —
+     * private-by-underscore, but it's OUR bundled deck, `redraw(reason)` is
+     * public Deck API, and the access is optional-chained).
+     */
+    captureComposite(): Promise<HTMLCanvasElement>;
     private markInitialized;
     onLoad(cb: () => void): void;
     /** Fires continuously during pan/zoom/rotate — MapLibre's own camera-change event, standing in for deck's onViewStateChange (which doesn't apply — deck isn't driving the camera). */
     onMove(cb: () => void): void;
     setLayers(layers: DeckProps["layers"]): void;
+    /**
+     * Scene lighting (spec: "Scene Lighting") — MapboxOverlay accepts full
+     * DeckProps, effects included. An effects-only setProps doesn't mark the
+     * basemap frame dirty, so nudge a repaint; the overlay redraws with the
+     * map's render pass.
+     */
+    setEffects(effects: DeckProps["effects"]): void;
     /**
      * Live basemap switch (spec: "Basemap presets & switching"). Deck layers
      * survive BY CONSTRUCTION: the MapboxOverlay is a map control, not style

package/dist/color.d.ts

@@ -0,0 +1,9 @@
+/**
+ * CSS color string → deck.gl RGB(A) array. Shared by attribute coercion
+ * (color-typed scalar attributes, `color` shorthands) and the expression
+ * compiler (color-shaped accessors returning strings — the documented
+ * "hex color string" output form). Extracted from attribute-resolution.ts
+ * so the expr module can use it without an import cycle.
+ */
+export declare function hexToRgb(raw: string): number[] | undefined;
+export declare function cssColorToRgb(raw: string): number[] | undefined;

package/dist/ctx.d.ts

@@ -32,6 +32,11 @@ export interface RuntimeContext {
         project(lngLat: [number, number]): [number, number];
     };
     selection: Selection | null;
+    /** Manifest undo/redo state (spec: "Undo / Redo — Manifest History") — drive it via emit("undo"/"redo"). Always false on the programmatic/React path (the app owns state there). */
+    history: {
+        canUndo: boolean;
+        canRedo: boolean;
+    };
     emit(event: string, payload?: Record<string, unknown>): void;
     data(layerId: string, opts?: DataOpts): Promise<unknown[]>;
     dataInViewport(layerId: string, opts?: DataOpts): Promise<unknown[]>;
@@ -44,6 +49,10 @@ export interface BuildCtxDeps {
     core: RuntimeCore;
     mapEl: Element;
     selection: Selection | null;
+    history?: {
+        canUndo: boolean;
+        canRedo: boolean;
+    };
 }
 /** Built fresh on every widget-render invocation — never mutated, never reused. */
-export declare function buildCtx({ layerIRs, core, mapEl, selection }: BuildCtxDeps): RuntimeContext;
+export declare function buildCtx({ layerIRs, core, mapEl, selection, history }: BuildCtxDeps): RuntimeContext;

package/dist/deck.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @nika-js/onlymap/deck — the bundled deck.gl escape hatch.
+ *
+ * OnlyMapJS bundles deck.gl (zero runtime deps). A custom layer registered
+ * with `OmMap.registerLayer({ deckClass })` is constructed by the BUNDLED
+ * Deck — if that class extends a consumer-installed `@deck.gl/*` copy, it
+ * belongs to a different class hierarchy (two `Layer` base classes, two
+ * luma.gl runtimes) and breaks inside the core's LayerManager. Build shims
+ * on THESE re-exports instead: they are the same class objects the core
+ * renders with.
+ *
+ * The values come from the root entry through a package self-reference
+ * (external in the dist build, the react-subpath pattern), so the consumer's
+ * bundler shares one core instance between both entries — class identity is
+ * structural, not luck. Types re-exported from @deck.gl/core are erased at
+ * build; consumers who typecheck against them need @deck.gl/core installed
+ * (dev-only), same as the core's own published .d.ts files.
+ *
+ *   import { CompositeLayer, TileLayer, BitmapLayer } from "@nika-js/onlymap/deck";
+ *   class MyRasterLayer extends CompositeLayer { ... }
+ *   OmMap.registerLayer({ type: "MyRasterLayer", deckClass: MyRasterLayer, props: [...] });
+ *
+ * Register before inserting the manifest (module top level): registering a
+ * type after mount does not retrigger reconciles — an unknown-type layer is
+ * warn-skipped until the next DOM mutation.
+ */
+export { Layer, CompositeLayer, LayerExtension, WebMercatorViewport, COORDINATE_SYSTEM, GeoJsonLayer, ScatterplotLayer, IconLayer, BitmapLayer, TileLayer, Tile3DLayer, SimpleMeshLayer, ScenegraphLayer, } from "@nika-js/onlymap";
+export type { LayerProps, CompositeLayerProps, DefaultProps, UpdateParameters, PickingInfo, LayersList } from "@deck.gl/core";

package/dist/deck.js

@@ -0,0 +1,16 @@
+import { BitmapLayer as a, COORDINATE_SYSTEM as o, CompositeLayer as y, GeoJsonLayer as L, IconLayer as t, Layer as i, LayerExtension as p, ScatterplotLayer as n, ScenegraphLayer as S, SimpleMeshLayer as c, Tile3DLayer as l, TileLayer as m, WebMercatorViewport as s } from "@nika-js/onlymap";
+export {
+  a as BitmapLayer,
+  o as COORDINATE_SYSTEM,
+  y as CompositeLayer,
+  L as GeoJsonLayer,
+  t as IconLayer,
+  i as Layer,
+  p as LayerExtension,
+  n as ScatterplotLayer,
+  S as ScenegraphLayer,
+  c as SimpleMeshLayer,
+  l as Tile3DLayer,
+  m as TileLayer,
+  s as WebMercatorViewport
+};

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

@@ -19,6 +19,9 @@
  */
 import { HTMLElementBase } from "../env";
 import { type RuntimeContext } from "../ctx";
+import { type LightingIR } from "../scene-lighting";
+import { type TerrainIR } from "../terrain";
+import { type SnapshotOptions } from "../snapshot";
 import type { LayerIR } from "../ir";
 import type { Selection } from "../selection";
 import type { MapViewport } from "../basemap";
@@ -28,6 +31,7 @@ interface OverlayHost {
 export declare class OmMapElement extends HTMLElementBase {
     private core;
     private observer;
+    private history;
     private keydownHandler?;
     private dblclickHandler?;
     private contextmenuHandler?;
@@ -43,11 +47,14 @@ export declare class OmMapElement extends HTMLElementBase {
     private readyFired;
     private resolveReady;
     readonly ready: Promise<void>;
+    private viewChangedTimer;
     private firstReconcileDone;
     private rendererLoadPending;
     private loadDispatched;
     connectedCallback(): void;
     disconnectedCallback(): void;
+    /** Trailing-debounced `om-view-changed` dispatch — see the field's doc comment. */
+    private scheduleViewChangedEvent;
     registerWidgetInternal(el: Element, watch: string[], notify: (ctx: RuntimeContext) => void): void;
     unregisterWidgetInternal(el: Element): void;
     registerOverlayInternal(overlay: OverlayHost): void;
@@ -124,6 +131,19 @@ export declare class OmMapElement extends HTMLElementBase {
         pitch: number;
         bearing: number;
     } | undefined;
+    /** Resolved scene-lighting IR (headless test inspection) — null = deck default lights. */
+    getLightingInternal(): LightingIR | null;
+    /** Resolved terrain IR (headless test inspection) — null = no surface. */
+    getTerrainInternal(): TerrainIR | null;
+    /**
+     * Canvas-only scene snapshot (spec: "Snapshot API") — basemap + deck
+     * composited at device pixels. DOM widgets/overlays/badge/attribution are
+     * NOT captured: consumers exporting imagery must render provider credits
+     * themselves. Await `ready` first; headless maps reject.
+     */
+    snapshot(opts?: SnapshotOptions): Promise<string | Blob>;
+    /** terrain* attributes → IR, key-substituted like basemap presets; resolution problems log once per apply. */
+    private resolveTerrainAttr;
     /** Projects a lng/lat through the current viewport (harness pixel derivation) — undefined before the viewport resolves. */
     projectInternal(lngLat: [number, number]): [number, number] | undefined;
     /** Renderer finished async init — defer to the first reconcile if it hasn't run yet (see the field comment). */
@@ -164,5 +184,15 @@ declare global {
     interface HTMLElementTagNameMap {
         "om-map": OmMapElement;
     }
+    interface HTMLElementEventMap {
+        /** Camera settled (trailing-debounced) — detail is the full camera state. */
+        "om-view-changed": CustomEvent<{
+            longitude: number;
+            latitude: number;
+            zoom: number;
+            pitch: number;
+            bearing: number;
+        }>;
+    }
 }
 export {};

package/dist/error-reporting.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The library's own code location — the directory this module was loaded
+ * from (`dist/` for the published bundle and its lazy chunks, `src/` in
+ * dev). A frame is "ours" iff its URL starts with this prefix; everything
+ * else on the page is not our bug to report.
+ */
+export declare const OWN_CODE_PREFIX: string;
+/**
+ * Report an error IF it is ours: at least one stack frame must come from
+ * the library's own code location. Exported for the window listeners below
+ * and for direct use by future internal catch sites.
+ */
+export declare function reportLibraryError(candidate: unknown, filename?: string): void;
+/** Idempotent page-level install — the first om-map to connect calls this. */
+export declare function installErrorReporting(): void;
+/** Test hook — resets the per-page dedup/cap state. */
+export declare function resetErrorReportingForTests(): void;

package/dist/history.d.ts

@@ -0,0 +1,53 @@
+export interface HistoryOptions {
+    /** The renderer-owned subtree — mutations inside are never manifest changes. */
+    excludeContainer?: () => Node | null;
+    /** Fired whenever canUndo/canRedo may have changed (om-map notifies `history`-watching widgets). */
+    onChange?: () => void;
+    limit?: number;
+}
+export declare class ManifestHistory {
+    private readonly root;
+    private readonly opts;
+    private readonly undoStack;
+    private readonly redoStack;
+    private readonly observer;
+    private applying;
+    private suppressDepth;
+    private readonly limit;
+    constructor(root: Element, opts?: HistoryOptions);
+    get canUndo(): boolean;
+    get canRedo(): boolean;
+    get depth(): number;
+    /**
+     * Push a non-DOM inverse pair onto the same stack (the draw store's
+     * committed-sketch snapshots). Ignored while a replay is applying — a
+     * custom op's own side effects must not re-record — or while suppressed.
+     */
+    record(entry: {
+        undo(): void;
+        redo(): void;
+    }): void;
+    /**
+     * Run `fn` with recording off — story playback/scrub, hover-driven
+     * transients. Pending records from BEFORE the call are ingested first
+     * (they were recordable); records produced BY the call are discarded
+     * synchronously via takeRecords, so suppression needs no async handshake.
+     */
+    suppress<T>(fn: () => T): T;
+    undo(): void;
+    redo(): void;
+    destroy(): void;
+    /** Observer callbacks are microtasks — force pending records through NOW so undo()/canUndo see a current stack. */
+    private settle;
+    private apply;
+    private applyOp;
+    private ingest;
+    private push;
+    private isExcludedNode;
+    private isRecordableAttr;
+}
+export declare function createHistory(mapEl: Element, opts?: HistoryOptions): ManifestHistory;
+export declare function peekHistory(mapEl: Element): ManifestHistory | undefined;
+export declare function destroyHistory(mapEl: Element): void;
+/** Run `fn` with this map's recording suppressed — a no-op passthrough when no history exists (headless React path, early boot). */
+export declare function suppressHistory<T>(mapEl: Element | null, fn: () => T): T;

package/dist/html-data.d.ts

@@ -15,9 +15,9 @@ interface TagData {
     }[];
 }
 /** Hand-authored action list — validated against hasAction() in html-data.test.ts. */
-export declare const BUILTIN_ACTIONS: readonly ["toggle-layer", "zoom-in", "zoom-out", "filter-layer", "highlight-feature", "fade", "pulse", "populate", "trace", "story-play", "story-pause", "story-seek", "fly-to", "zoom-to-feature", "show-overlay", "hide-overlay", "show-tooltip", "hide-tooltip", "draw-mode", "draw-commit", "draw-cancel", "draw-delete", "draw-clear", "draw-config", "draw-save", "set-basemap"];
+export declare const BUILTIN_ACTIONS: readonly ["toggle-layer", "zoom-in", "zoom-out", "filter-layer", "highlight-feature", "fade", "pulse", "populate", "trace", "story-play", "story-pause", "story-seek", "fly-to", "zoom-to-feature", "show-overlay", "hide-overlay", "show-tooltip", "hide-tooltip", "draw-mode", "draw-commit", "draw-cancel", "draw-delete", "draw-clear", "draw-config", "draw-save", "set-basemap", "set-lighting", "set-terrain", "undo", "redo"];
 /** Hand-authored widget types — validated against the widget registry in html-data.test.ts. */
-export declare const BUILTIN_WIDGETS: readonly ["legend", "layer-switcher", "zoom-controls", "scale-bar", "attribution", "filter", "vega-lite", "player", "draw", "basemap-switcher"];
+export declare const BUILTIN_WIDGETS: readonly ["legend", "layer-switcher", "zoom-controls", "scale-bar", "attribution", "filter", "vega-lite", "player", "draw", "basemap-switcher", "lighting", "undo-redo"];
 export declare function buildHtmlCustomData(): {
     version: number;
     tags: TagData[];

package/dist/{index-D2zVsZ79.js → index-C9tgnPNw.js}

@@ -1,4 +1,4 @@
-import { a2 as _t, a3 as Ct } from "./index-oE1Kouy1.js";
+import { a2 as _t, a3 as Ct } from "./index-CsicbycJ.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-BZs_x9Dx.js → index-CiuGqS0i.js}

@@ -1,8 +1,8 @@
 var R = Object.defineProperty;
 var N = (t, e, r) => e in t ? R(t, e, { enumerable: !0, configurable: !0, writable: !0, value: r }) : t[e] = r;
 var u = (t, e, r) => N(t, typeof e != "symbol" ? e + "" : e, r);
-import { c as W, W as x, d as O, e as _, f as m, h as g, j as P, s as z, n as I, k as B, m as k, o as $, p as C, q as F, r as M, u as U, v as D, w as L, x as j, y as v, z as T, A as J } from "./index-oE1Kouy1.js";
-import { F as Ue, R as De, _ as je, B as ve, C as Je, D as qe, E as Ve, G as Ge, H as He, I as Ke, J as Qe, K as Xe, L as Ye, M as Ze, N as er, O as rr, P as tr, Q as nr, S as ar, T as sr, U as cr, V as or, X as ir, Y as ur, Z as fr } from "./index-oE1Kouy1.js";
+import { c as W, W as x, d as O, e as _, f as m, h as g, j as P, s as z, n as I, k as B, m as k, o as $, p as C, q as F, r as M, u as U, v as D, w as L, x as j, y as v, z as T, A as J } from "./index-CsicbycJ.js";
+import { F as Ue, R as De, _ as je, B as ve, C as Je, D as qe, E as Ve, G as Ge, H as He, I as Ke, J as Qe, K as Xe, L as Ye, M as Ze, N as er, O as rr, P as tr, Q as nr, S as ar, T as sr, U as cr, V as or, X as ir, Y as ur, Z as fr } from "./index-CsicbycJ.js";
 import { g as q, i as V } from "./table-accessors-DBjWgN0C.js";
 async function G(t, e, r = {}, n = {}) {
   const a = W(t), s = x.getWorkerFarm(r), { source: c } = r, o = { name: a, source: c };