@yappkit/front-module-map 0.2.0 → 0.2.1

package/lib/types/main.d.ts

@@ -19,9 +19,103 @@ export declare const mapProviders: {
     deckgl: typeof DeckGL;
     'deck-gl': typeof DeckGL;
 };
+export type GoogleMapsConfig = {
+    /**
+     * - Provider discriminant.
+     */
+    type: 'google' | 'google-maps';
+    /**
+     * - Google Maps API key. Required: without it the entry is warn+skipped (#255).
+     */
+    apiKey: string;
+    /**
+     * - Google Maps libraries, all loaded in a single loader call (e.g.
+     * 'maps', 'maps3d', 'elevation'); each becomes available through getSDK(name).
+     */
+    libraries?: string[];
+    /**
+     * - Google Maps JS API version channel — Map3D requires 'alpha'
+     * (plus a pre-authorized key).
+     */
+    version?: string;
+};
+export type MapboxConfig = {
+    /**
+     * - Provider discriminant.
+     */
+    type: 'mapbox';
+    /**
+     * - Mapbox public access token. Required: without it the entry is warn+skipped (#255).
+     */
+    apiKey: string;
+    /**
+     * - Mapbox REST SDK services to preload; each becomes available through getSDK(name).
+     */
+    services?: Array<'datasets' | 'directions' | 'geocoding' | 'geocodingV6' | 'mapMatching' | 'matrix' | 'optimization' | 'static' | 'styles' | 'tilequery' | 'tilesets' | 'tokens' | 'uploads' | 'isochrone'>;
+};
+export type MaplibreConfig = {
+    /**
+     * - Provider discriminant.
+     */
+    type: 'maplibre' | 'maplibre-gl';
+};
+export type DeckGLConfig = {
+    /**
+     * - Provider discriminant.
+     */
+    type: 'deckgl' | 'deck-gl';
+};
+export type MapConfig = GoogleMapsConfig | MapboxConfig | MaplibreConfig | DeckGLConfig;
+export type MapsConfig = Record<string, MapConfig>;
+/**
+ * Google Maps provider config (`type: 'google'` / `'google-maps'`).
+ * @typedef {object} GoogleMapsConfig
+ * @property {'google'|'google-maps'} type - Provider discriminant.
+ * @property {string} apiKey - Google Maps API key. Required: without it the entry is warn+skipped (#255).
+ * @property {string[]} [libraries] - Google Maps libraries, all loaded in a single loader call (e.g.
+ * 'maps', 'maps3d', 'elevation'); each becomes available through getSDK(name).
+ * @property {string} [version='weekly'] - Google Maps JS API version channel — Map3D requires 'alpha'
+ * (plus a pre-authorized key).
+ */
+/**
+ * Mapbox provider config (`type: 'mapbox'`), rendering on the mapbox-gl peer.
+ * @typedef {object} MapboxConfig
+ * @property {'mapbox'} type - Provider discriminant.
+ * @property {string} apiKey - Mapbox public access token. Required: without it the entry is warn+skipped (#255).
+ * @property {Array<'datasets'|'directions'|'geocoding'|'geocodingV6'|'mapMatching'|'matrix'|'optimization'|'static'|'styles'|'tilequery'|'tilesets'|'tokens'|'uploads'|'isochrone'>} [services]
+ * - Mapbox REST SDK services to preload; each becomes available through getSDK(name).
+ */
+/**
+ * MapLibre provider config (`type: 'maplibre'` / `'maplibre-gl'`) — the token-less mapbox-gl fork
+ * (#154): no apiKey, and no Mapbox REST services (getSDK refuses them).
+ * @typedef {object} MaplibreConfig
+ * @property {'maplibre'|'maplibre-gl'} type - Provider discriminant.
+ */
+/**
+ * DeckGL provider config (`type: 'deckgl'` / `'deck-gl'`) — no key: composes over the other providers.
+ * @typedef {object} DeckGLConfig
+ * @property {'deckgl'|'deck-gl'} type - Provider discriminant.
+ */
+/**
+ * One entry of the `maps` config: a per-instance provider config, discriminated by `type`.
+ * @typedef {GoogleMapsConfig|MapboxConfig|MaplibreConfig|DeckGLConfig} MapConfig
+ */
+/**
+ * The `maps` config key: instance key → provider config. Each valid entry becomes
+ * `yAppKit.maps.<key>`; a faulty one is warn+skipped (#166/#255/#351).
+ * @typedef {Record<string, MapConfig>} MapsConfig
+ */
 export default class MapModule {
-    install(yAppKit: any): {
+    /** Builds `yAppKit.maps` — one provider instance per entry of the `maps` config key ({@link MapsConfig}).
+     * @param {object} yAppKit - The yAppKit instance (untyped: @yappkit/front exports no types).
+     * @returns {{onAfterSetup: () => void}} The module's yAppKit lifecycle hooks.
+     */
+    install(yAppKit: object): {
         onAfterSetup: () => void;
     };
 }
+/**
+ * Module factory for createYAppKit's `modules` list.
+ * @returns {MapModule} A fresh module instance.
+ */
 export declare const loadMapModule: () => MapModule;

package/lib/types/providers/DeckGL.d.ts

@@ -1,10 +1,102 @@
+export type DeckGLMapWrapperOptions = {
+    /**
+     * - Vue watcher options for the options watcher (defaults: `immediate: true, deep: true`).
+     */
+    watchOptionsOptions?: import('vue').WatchOptions;
+    /**
+     * - Vue watcher options for the layers watcher (default: `immediate: true`; intentionally not deep — layers are shallow-compared, swap array/layer identity to update).
+     */
+    watchLayersOptions?: import('vue').WatchOptions;
+    /**
+     * - Defers map creation: called on mount with the create function instead of creating right away — call `loadMap()` when ready.
+     */
+    onMounted?: (loadMap: () => void) => void;
+};
+export type DeckGLMapOptions = import('@deck.gl/core').DeckProps & DeckGLMapWrapperOptions;
+/**
+ * Wrapper-specific keys of the map options bag — every other key is handed verbatim to the
+ * deck.gl `Deck` constructor (and re-applied through `setProps` on change).
+ * @typedef {object} DeckGLMapWrapperOptions
+ * @property {import('vue').WatchOptions} [watchOptionsOptions] - Vue watcher options for the options watcher (defaults: `immediate: true, deep: true`).
+ * @property {import('vue').WatchOptions} [watchLayersOptions] - Vue watcher options for the layers watcher (default: `immediate: true`; intentionally not deep — layers are shallow-compared, swap array/layer identity to update).
+ * @property {(loadMap: () => void) => void} [onMounted] - Defers map creation: called on mount with the create function instead of creating right away — call `loadMap()` when ready.
+ */
+/**
+ * Options accepted by the deckGL `Map` component's `:options` prop and by `createMap`: the
+ * deck.gl `Deck` constructor props plus the wrapper keys.
+ * @typedef {import('@deck.gl/core').DeckProps & DeckGLMapWrapperOptions} DeckGLMapOptions
+ */
+/**
+ * Resolved map wrapper — `createMap`'s resolution and the `Map` component's `@loaded` payload:
+ * the raw `Deck` instance on `.map`, plus reactive watchers taking Vue refs.
+ */
+declare class DeckGLMap {
+    /**
+     * The raw deck.gl instance (e.g. `pickObject`, `redraw`); null until created and after unmount.
+     * @type {import('@deck.gl/core').Deck | null}
+     */
+    map: import('@deck.gl/core').Deck | null;
+    watching: {
+        options: boolean;
+        layers: boolean;
+    };
+    /**
+     * Stop handles of the active watchers, called on unmount.
+     * @type {import('vue').WatchHandle[]}
+     */
+    unwatchFn: import('vue').WatchHandle[];
+    constructor();
+    /**
+     * Keep the map's props in sync with the ref: re-applies its value through `Deck.setProps` on
+     * change (immediate + deep by default). One shot per wrapper: further calls warn and no-op.
+     * @param {import('vue').Ref<DeckGLMapOptions>} opts - Ref to the options bag applied to the map.
+     * @param {import('vue').WatchOptions} [options] - Overrides for the underlying Vue watcher.
+     * @returns {void}
+     */
+    watchOptions(opts: import('vue').Ref<DeckGLMapOptions>, options?: import('vue').WatchOptions): void;
+    /**
+     * Keep the map's `layers` prop in sync with the ref (immediate, NOT deep: layers are
+     * shallow-compared — swap array/layer identity to update). One shot per wrapper: further calls
+     * warn and no-op.
+     * @param {import('vue').Ref<import('@deck.gl/core').LayersList>} layers - Ref to the deck.gl layers array.
+     * @param {import('vue').WatchOptions} [options] - Overrides for the underlying Vue watcher.
+     * @returns {void}
+     */
+    watchLayers(layers: import('vue').Ref<import('@deck.gl/core').LayersList>, options?: import('vue').WatchOptions): void;
+}
 export default class DeckGL {
     deckgl: {
         Deck: typeof import("@deck.gl/core").Deck;
     } | null;
-    _MapComponent: any;
+    /**
+     * Memoized component definition (#139), see the `get Map` comment.
+     * @type {import('vue').Component | null}
+     */
+    _MapComponent: import('vue').Component | null;
     constructor();
-    get Map(): any;
+    /**
+     * The deckGL `Map` component. Props: `options` ({@link DeckGLMapOptions}, watched deep) and
+     * `layers` (deck.gl layers, shallow-compared). Emits `loaded` with the {@link DeckGLMap}
+     * wrapper, and `error`. Provides to descendants: `deckGLMap` (ShallowRef<DeckGLMap | null>,
+     * set once loaded), `deckGLPrependLayers` (ShallowRef<LayersList> — layers rendered UNDER the
+     * `layers` prop's, e.g. the google-maps DeckGL3DTileLayer's tiles) and `deckGLAppendVNodeFn`
+     * (Ref<Array<() => VNodeChild>> — vnode factories rendered after the map's div, e.g. a child's
+     * #appendMap credits slot).
+     * @returns {import('vue').Component} The map component definition.
+     */
+    get Map(): import('vue').Component;
+    /**
+     * Lazy-load and memoize the deck.gl `Deck` class (one dynamic import per provider instance).
+     * @returns {Promise<void>}
+     */
     loadDeckGL(): Promise<void>;
-    createMap(elemRef: any, options?: {}): Promise<any>;
+    /**
+     * Imperative SDK entry — must run during a component's `setup()` (it registers the
+     * onMounted/onUnmounted hooks that create and destroy the map).
+     * @param {import('vue').Ref<HTMLElement | null>} elemRef - Template ref of the element the map renders into (becomes `Deck`'s `parent`).
+     * @param {DeckGLMapOptions} [options] - `Deck` constructor props plus the wrapper keys.
+     * @returns {Promise<DeckGLMap>} Resolves with the map wrapper once created; rejects with `error.code === 'MAP_UNMOUNTED'` when the component unmounts before the map loads (#148).
+     */
+    createMap(elemRef: import('vue').Ref<HTMLElement | null>, options?: DeckGLMapOptions): Promise<DeckGLMap>;
 }
+export {};

package/lib/types/providers/DeckGLOverlay.d.ts

@@ -1,3 +1,27 @@
+export type DeckGLOverlayWrapperOptions = {
+    /**
+     * - Vue watcher options for the options watcher (defaults: `immediate: true, deep: true`).
+     */
+    watchOptionsOptions?: import('vue').WatchOptions;
+    /**
+     * - Vue watcher options for the layers watcher (default: `immediate: true`; intentionally not deep — layers are shallow-compared, swap array/layer identity to update).
+     */
+    watchLayersOptions?: import('vue').WatchOptions;
+};
+export type DeckGLOverlayOptions = (import('@deck.gl/mapbox').MapboxOverlayProps | import('@deck.gl/google-maps').GoogleMapsOverlayProps) & DeckGLOverlayWrapperOptions;
+/**
+ * Wrapper-specific keys of the overlay options bag — every other key is handed verbatim to the
+ * provider overlay's constructor (and re-applied through `setProps` on change).
+ * @typedef {object} DeckGLOverlayWrapperOptions
+ * @property {import('vue').WatchOptions} [watchOptionsOptions] - Vue watcher options for the options watcher (defaults: `immediate: true, deep: true`).
+ * @property {import('vue').WatchOptions} [watchLayersOptions] - Vue watcher options for the layers watcher (default: `immediate: true`; intentionally not deep — layers are shallow-compared, swap array/layer identity to update).
+ */
+/**
+ * Options accepted by the provider `DeckGLOverlay` components' `:options` prop and by
+ * `setDeckGLOverlay()`: the raw overlay's constructor props (`MapboxOverlayProps` on
+ * mapbox/maplibre maps, `GoogleMapsOverlayProps` on google maps) plus the wrapper keys.
+ * @typedef {(import('@deck.gl/mapbox').MapboxOverlayProps | import('@deck.gl/google-maps').GoogleMapsOverlayProps) & DeckGLOverlayWrapperOptions} DeckGLOverlayOptions
+ */
 /**
  * Shared deck.gl overlay wiring (#174): the class and the component below used to be duplicated
  * verbatim in Mapbox.js and GoogleMaps.js — every fix (#151, #156, #165) had to be applied twice.
@@ -5,25 +29,55 @@
  * makeDeckGLOverlayComponent with their inject key.
  */
 export declare class DeckGLOverlay {
-    overlay: any;
+    /**
+     * The raw deck.gl overlay (a @deck.gl/mapbox MapboxOverlay on mapbox/maplibre maps, a
+     * @deck.gl/google-maps GoogleMapsOverlay on google maps), attached by the provider subclass;
+     * null until then and after destroy.
+     * @type {import('@deck.gl/mapbox').MapboxOverlay | import('@deck.gl/google-maps').GoogleMapsOverlay | null}
+     */
+    overlay: import('@deck.gl/mapbox').MapboxOverlay | import('@deck.gl/google-maps').GoogleMapsOverlay | null;
     watching: {
         options: boolean;
         layers: boolean;
     };
-    unwatchFn: any;
-    trackedIn: any;
+    unwatchFn: import("vue").WatchHandle[];
+    trackedIn: DeckGLOverlay[] | null;
+    /**
+     * Built by the provider's `setDeckGLOverlay()`, not by consumers directly.
+     * @param {object} config - Wiring handed over by the provider subclass.
+     * @param {import('vue').WatchHandle[]} config.unwatchFn - List collecting the overlay's watcher stop handles (all called and emptied on destroy).
+     * @param {DeckGLOverlay[] | null} [config.trackedIn] - The map wrapper's overlays list this instance is tracked in.
+     */
     constructor({ unwatchFn, trackedIn }: {
-        trackedIn?: null | undefined;
-        unwatchFn: any;
+        unwatchFn: import('vue').WatchHandle[];
+        trackedIn?: DeckGLOverlay[] | null;
     });
     /** Stop the watchers, leave the map's tracking list and detach the overlay from the map (#151).
      * @returns {void}
      */
     destroy(): void;
-    watchOptions(opts: any, options?: {}): void;
-    watchLayers(layers: any, options?: {}): void;
+    /**
+     * Keep the overlay's props in sync with the ref: re-applies its value through `setProps` on
+     * change (immediate + deep by default). One shot per wrapper: further calls warn and no-op.
+     * @param {import('vue').Ref<DeckGLOverlayOptions>} opts - Ref to the options bag applied to the overlay.
+     * @param {import('vue').WatchOptions} [options] - Overrides for the underlying Vue watcher.
+     * @returns {void}
+     */
+    watchOptions(opts: import('vue').Ref<DeckGLOverlayOptions>, options?: import('vue').WatchOptions): void;
+    /**
+     * Keep the overlay's `layers` prop in sync with the ref (immediate, NOT deep: layers are
+     * shallow-compared — swap array/layer identity to update). One shot per wrapper: further calls
+     * warn and no-op.
+     * @param {import('vue').Ref<import('@deck.gl/core').LayersList>} layers - Ref to the deck.gl layers array.
+     * @param {import('vue').WatchOptions} [options] - Overrides for the underlying Vue watcher.
+     * @returns {void}
+     */
+    watchLayers(layers: import('vue').Ref<import('@deck.gl/core').LayersList>, options?: import('vue').WatchOptions): void;
 }
-/** Build the provider's DeckGLOverlay component, bound to its injected map key (#174).
+/** Build the provider's DeckGLOverlay component, bound to its injected map key (#174) — it must
+ * nest inside that provider's Map. Props: `options` ({@link DeckGLOverlayOptions}, watched deep)
+ * and `layers` (deck.gl layers, shallow-compared). Emits `loaded` with the {@link DeckGLOverlay}
+ * wrapper, and `error` (#194). Renders nothing itself.
  * @param {string} mapInjectKey - The provide/inject key of the provider's map ref.
  * @returns {import('vue').Component} The overlay component definition.
  */

package/lib/types/providers/GoogleMaps.d.ts

@@ -1,41 +1,321 @@
+import { DeckGLOverlay } from './DeckGLOverlay.js';
+declare class GoogleMapsDeckGLOverlay extends DeckGLOverlay {
+    /** setMap(null) only detaches: finalize() is deck.gl's full GL-resource release (#156).
+     * @returns {void}
+     */
+    _detach(): void;
+}
+/**
+ * 2D map wrapper, resolved by createMap and emitted by the Map component's `loaded` event. Its
+ * public surface is ONLY setDeckGLOverlay() and the raw `.map` — the Google 2D map has no
+ * watchOptions/watchLayers (imperative updates go through Google's own setters on `.map`).
+ */
+declare class GoogleMapsMap {
+    /** @type {object|null} The raw google.maps.Map (runtime-loaded API — untyped here). */
+    map: object | null;
+    /** @type {import('vue').WatchStopHandle[]} Stopped by createMap's unmount (#148/#165). */
+    unwatchFn: import('vue').WatchStopHandle[];
+    /** @type {GoogleMapsDeckGLOverlay[]} Overlays attached via setDeckGLOverlay. */
+    overlays: GoogleMapsDeckGLOverlay[];
+    constructor();
+    /** Create a deck.gl GoogleMapsOverlay (lazy-imported) and attach it to the map.
+     * @param {import('@deck.gl/google-maps').GoogleMapsOverlayProps} [options] - GoogleMapsOverlay constructor props (deck props plus `interleaved`).
+     * @returns {Promise<GoogleMapsDeckGLOverlay>} The overlay wrapper: watchOptions/watchLayers/destroy.
+     */
+    setDeckGLOverlay(options?: import('@deck.gl/google-maps').GoogleMapsOverlayProps): Promise<GoogleMapsDeckGLOverlay>;
+}
+export type GoogleMapsMap3DLayer = {
+    /**
+     * - Unique layer id: written to the element's `name` attribute and used by the by-id diff.
+     */
+    id: string;
+    /**
+     * - The layer's DOM element (a gmp-* Maps 3D element), inserted into the <gmp-map-3d> at its array position (array order = z-order).
+     */
+    element: Element;
+};
+/**
+ * A Map3D layer entry (the Map3D component's `layers` items / watchLayers input): a pre-built
+ * layer element keyed for the by-id diff (#195).
+ * @typedef {object} GoogleMapsMap3DLayer
+ * @property {string} id - Unique layer id: written to the element's `name` attribute and used by the by-id diff.
+ * @property {Element} element - The layer's DOM element (a gmp-* Maps 3D element), inserted into the <gmp-map-3d> at its array position (array order = z-order).
+ */
+/**
+ * 3D map wrapper, resolved by createMap3D and emitted by the Map3D component's `loaded` event,
+ * around the runtime-loaded <gmp-map-3d> Map3DElement.
+ */
+declare class GoogleMapsMap3D {
+    /** @type {HTMLElement|null} The <gmp-map-3d> Map3DElement — a DOM element whose Maps-specific API is runtime-loaded and untyped here. */
+    map: HTMLElement | null;
+    watching: {
+        options: boolean;
+        layers: boolean;
+    };
+    /** @type {import('vue').WatchStopHandle[]} Stopped by createMap3D's unmount (#148/#165). */
+    unwatchFn: import('vue').WatchStopHandle[];
+    constructor();
+    /** Collect the element's Web IDL attribute names: enumerable ACCESSOR descriptors on its prototype.
+     * @param {object} obj - The element (or nested element state) to inspect.
+     * @returns {string[]} The accessor property names.
+     */
+    _getSetters(obj: object): string[];
+    /** Snapshot the element's Web IDL attributes into a plain options object.
+     * @param {object} obj - The element (or nested element state) to snapshot.
+     * @param {WeakSet<object>} [seen] - Guards accessor cycles across the recursion.
+     * @returns {Record<string, any>} Attribute name → current value (nested element state recursed into plain objects).
+     */
+    _getOptions(obj: object, seen?: WeakSet<object>): Record<string, any>;
+    /** Assign a bag of Map3DElement attributes — the imperative sibling of watchOptions.
+     * @param {Record<string, any>} [props] - Attribute name → value, assigned onto the element (runtime-loaded API — untyped here).
+     * @returns {void}
+     */
+    setProps(props?: Record<string, any>): void;
+    /** Snapshot the map's current Web IDL attributes — the imperative sibling of getProps-less reads.
+     * @returns {Record<string, any>} Attribute name → current value.
+     */
+    getProps(): Record<string, any>;
+    /** Get a layer element added under the <gmp-map-3d> by its id (the element's `name` attribute).
+     * @param {string} id - The layer id.
+     * @returns {Element|null} The layer's element, or null when absent.
+     */
+    getLayer(id: string): Element | null;
+    /** Keep the Map3DElement in sync with a reactive options object (per-key JSON diff). One
+     * watcher per wrapper: further calls warn and return.
+     * @param {import('vue').Ref<Record<string, any>>} opts - Reactive options bag; every changed key is assigned onto the element.
+     * @param {import('vue').WatchOptions} [options] - Extra vue watch options, merged over `{ immediate: true, deep: true }`.
+     * @returns {void}
+     */
+    watchOptions(opts: import('vue').Ref<Record<string, any>>, options?: import('vue').WatchOptions): void;
+    /** Keep the <gmp-map-3d> children in sync with a reactive layers array: by-id diff (#195),
+     * array order = z-order via insertBefore. One watcher per wrapper: further calls warn and return.
+     * @param {import('vue').Ref<GoogleMapsMap3DLayer[]>} layers - Reactive layers; shallow-compared — swap array/layer identity (shallowRef) to update.
+     * @param {import('vue').WatchOptions} [options] - Extra vue watch options, merged over `{ immediate: true }`.
+     * @returns {void}
+     */
+    watchLayers(layers: import('vue').Ref<GoogleMapsMap3DLayer[]>, options?: import('vue').WatchOptions): void;
+}
+export type GoogleMapsMountHook = {
+    /**
+     * - Defers map creation: called at component mount with `loadMap` instead of an immediate load — the map exists only once you invoke it.
+     */
+    onMounted?: (loadMap: () => void) => void;
+};
+export type GoogleMapsMapOptions = GoogleMapsMountHook & Record<string, any>;
+export type GoogleMapsWatcherOptions = {
+    /**
+     * - Vue watch options for the internal options watcher.
+     */
+    watchOptionsOptions?: import('vue').WatchOptions;
+    /**
+     * - Vue watch options for the internal layers watcher.
+     */
+    watchLayersOptions?: import('vue').WatchOptions;
+};
+export type GoogleMapsMap3DOptions = GoogleMapsMountHook & GoogleMapsWatcherOptions & Record<string, any>;
+export type GoogleMapsMapProps = {
+    /**
+     * - Passed once to google.maps.Map — NOT reactive (an update logs an error; drive the loaded wrapper's `.map` through Google's own setters instead).
+     */
+    options?: GoogleMapsMapOptions;
+};
+export type GoogleMapsMap3DProps = {
+    /**
+     * - Watched (per-key JSON diff) and assigned onto the Map3DElement.
+     */
+    options?: GoogleMapsMap3DOptions;
+    /**
+     * - Watched with a by-id diff (#195); shallow-compared — swap array/layer identity (shallowRef) to update.
+     */
+    layers?: GoogleMapsMap3DLayer[];
+};
+export type GoogleMapsDeckGLOverlayProps = {
+    /**
+     * - GoogleMapsOverlay props, watched deep → overlay.setProps().
+     */
+    options?: import('@deck.gl/google-maps').GoogleMapsOverlayProps & GoogleMapsWatcherOptions;
+    /**
+     * - deck.gl layers, watched → setProps({ layers }); shallow-compared — swap identity to update.
+     */
+    layers?: import('@deck.gl/core').LayersList;
+};
+export type GoogleMapsDeckGL3DTileLayerProps = {
+    /**
+     * - Tile3DLayer prop overrides (over the Google 3D Tiles defaults) — NOT reactive: replace the component to change them.
+     */
+    options?: Partial<import('@deck.gl/geo-layers').Tile3DLayerProps>;
+};
+export type GoogleMapsMapComponent = import('vue').DefineSetupFnComponent<GoogleMapsMapProps, {
+    loaded: (map: GoogleMapsMap) => void;
+    error: (error: Error) => void;
+}>;
+export type GoogleMapsMap3DComponent = import('vue').DefineSetupFnComponent<GoogleMapsMap3DProps, {
+    loaded: (map: GoogleMapsMap3D) => void;
+    error: (error: Error) => void;
+}>;
+export type GoogleMapsDeckGLOverlayComponent = import('vue').DefineSetupFnComponent<GoogleMapsDeckGLOverlayProps, {
+    loaded: (overlay: GoogleMapsDeckGLOverlay) => void;
+    error: (error: Error) => void;
+}>;
+export type GoogleMapsDeckGL3DTileLayerComponent = import('vue').DefineSetupFnComponent<GoogleMapsDeckGL3DTileLayerProps, {
+    error: (error: Error) => void;
+}, import('vue').SlotsType<{
+    appendMap?: {
+        credits: string;
+    };
+}>>;
+/**
+ * Module-side mount hook recognised by createMap/createMap3D (every other option key is forwarded
+ * to Google untouched).
+ * @typedef {object} GoogleMapsMountHook
+ * @property {(loadMap: () => void) => void} [onMounted] - Defers map creation: called at component mount with `loadMap` instead of an immediate load — the map exists only once you invoke it.
+ */
+/**
+ * Options for createMap / the 2D Map component's `options` prop: google.maps.MapOptions
+ * (runtime-loaded API — untyped here: center/zoom/mapId/…) plus {@link GoogleMapsMountHook}.
+ * @typedef {GoogleMapsMountHook & Record<string, any>} GoogleMapsMapOptions
+ */
+/**
+ * Per-watcher tuning read by the Map3D and DeckGLOverlay components from their `options` prop.
+ * @typedef {object} GoogleMapsWatcherOptions
+ * @property {import('vue').WatchOptions} [watchOptionsOptions] - Vue watch options for the internal options watcher.
+ * @property {import('vue').WatchOptions} [watchLayersOptions] - Vue watch options for the internal layers watcher.
+ */
+/**
+ * Options for createMap3D / the Map3D component's `options` prop: Map3DElement attributes
+ * (runtime-loaded API — untyped here: center/range/tilt/…) plus the module-side keys.
+ * @typedef {GoogleMapsMountHook & GoogleMapsWatcherOptions & Record<string, any>} GoogleMapsMap3DOptions
+ */
+/**
+ * Props of the 2D Map component. NO `layers` prop: deck.gl layers on a Google 2D map go through
+ * DeckGLOverlay only.
+ * @typedef {object} GoogleMapsMapProps
+ * @property {GoogleMapsMapOptions} [options] - Passed once to google.maps.Map — NOT reactive (an update logs an error; drive the loaded wrapper's `.map` through Google's own setters instead).
+ */
+/**
+ * Props of the Map3D component.
+ * @typedef {object} GoogleMapsMap3DProps
+ * @property {GoogleMapsMap3DOptions} [options] - Watched (per-key JSON diff) and assigned onto the Map3DElement.
+ * @property {GoogleMapsMap3DLayer[]} [layers] - Watched with a by-id diff (#195); shallow-compared — swap array/layer identity (shallowRef) to update.
+ */
+/**
+ * Props of the DeckGLOverlay component (nests inside the 2D Map).
+ * @typedef {object} GoogleMapsDeckGLOverlayProps
+ * @property {import('@deck.gl/google-maps').GoogleMapsOverlayProps & GoogleMapsWatcherOptions} [options] - GoogleMapsOverlay props, watched deep → overlay.setProps().
+ * @property {import('@deck.gl/core').LayersList} [layers] - deck.gl layers, watched → setProps({ layers }); shallow-compared — swap identity to update.
+ */
+/**
+ * Props of the DeckGL3DTileLayer component (nests inside the deckGL provider's Map).
+ * @typedef {object} GoogleMapsDeckGL3DTileLayerProps
+ * @property {Partial<import('@deck.gl/geo-layers').Tile3DLayerProps>} [options] - Tile3DLayer prop overrides (over the Google 3D Tiles defaults) — NOT reactive: replace the component to change them.
+ */
+/**
+ * The 2D Map component type: `loaded` emits the {@link GoogleMapsMap} wrapper, `error` every load failure (#148/#378).
+ * @typedef {import('vue').DefineSetupFnComponent<GoogleMapsMapProps, { loaded: (map: GoogleMapsMap) => void, error: (error: Error) => void }>} GoogleMapsMapComponent
+ */
+/**
+ * The Map3D component type: `loaded` emits the {@link GoogleMapsMap3D} wrapper, `error` every load failure (#148/#378).
+ * @typedef {import('vue').DefineSetupFnComponent<GoogleMapsMap3DProps, { loaded: (map: GoogleMapsMap3D) => void, error: (error: Error) => void }>} GoogleMapsMap3DComponent
+ */
+/**
+ * The DeckGLOverlay component type: `loaded` emits the {@link GoogleMapsDeckGLOverlay} wrapper, `error` every load failure (#194).
+ * @typedef {import('vue').DefineSetupFnComponent<GoogleMapsDeckGLOverlayProps, { loaded: (overlay: GoogleMapsDeckGLOverlay) => void, error: (error: Error) => void }>} GoogleMapsDeckGLOverlayComponent
+ */
+/**
+ * The DeckGL3DTileLayer component type: `error` on load failure (#194); the #appendMap slot
+ * receives `{ credits }` — Google's 3D Tiles attribution, which must stay visible.
+ * @typedef {import('vue').DefineSetupFnComponent<GoogleMapsDeckGL3DTileLayerProps, { error: (error: Error) => void }, import('vue').SlotsType<{ appendMap?: { credits: string } }>>} GoogleMapsDeckGL3DTileLayerComponent
+ */
+/**
+ * Google Maps provider: one instance per `maps` config entry with `type: 'google'`/`'google-maps'`,
+ * exposed as `yAppKit.maps.<key>` — Vue components (Map, Map3D, DeckGLOverlay, DeckGL3DTileLayer)
+ * plus the imperative SDK (getSDK, createMap, createMap3D, createDeckGL3DTileLayer).
+ */
 export default class GoogleMaps {
-    apiKey: any;
-    libraries: any[];
-    version: any;
+    apiKey: string;
+    libraries: string[];
+    version: string;
     _mapsApiConfigured: boolean;
     authFailed: boolean;
-    sdk: {};
+    /** @type {Record<string, object>} Loaded google library namespaces by name (runtime-loaded API — untyped here), filled by getSDK. */
+    sdk: Record<string, object>;
     deckgl: {
         Tile3DLayer: typeof import("@deck.gl/geo-layers").Tile3DLayer;
     } | null;
-    _MapComponent: any;
-    _Map3DComponent: any;
-    _DeckGLOverlayComponent: any;
-    _DeckGL3DTileLayerComponent: any;
-    ready: Promise<any>;
-    constructor(mapConfig: any);
-    get Map(): any;
-    get Map3D(): any;
-    get DeckGLOverlay(): any;
-    get DeckGL3DTileLayer(): any;
+    /** @type {GoogleMapsMapComponent|null} 2D Map memo. */
+    _MapComponent: GoogleMapsMapComponent | null;
+    /** @type {GoogleMapsMap3DComponent|null} Map3D memo. */
+    _Map3DComponent: GoogleMapsMap3DComponent | null;
+    /** @type {GoogleMapsDeckGLOverlayComponent|null} DeckGLOverlay memo. */
+    _DeckGLOverlayComponent: GoogleMapsDeckGLOverlayComponent | null;
+    /** @type {GoogleMapsDeckGL3DTileLayerComponent|null} DeckGL3DTileLayer memo. */
+    _DeckGL3DTileLayerComponent: GoogleMapsDeckGL3DTileLayerComponent | null;
+    /** @type {Promise<Record<string, object>>} The initial libraries preload: resolves with the `sdk` map, rejects like getSDK(). */
+    ready: Promise<Record<string, object>>;
+    /** Validates the config and starts the SDK preload (`this.ready`, #149).
+     * @param {import('../main.js').GoogleMapsConfig} mapConfig - The provider's `maps` config entry (apiKey/libraries/version; `type` is consumed by the module loader).
+     */
+    constructor(mapConfig: import('../main.js').GoogleMapsConfig);
+    /** The 2D Map component (memoized per provider instance, #139): `options` prop only — nest
+     * DeckGLOverlay inside for deck.gl layers; `@loaded` emits the {@link GoogleMapsMap} wrapper.
+     * @returns {GoogleMapsMapComponent} The memoized component definition.
+     */
+    get Map(): GoogleMapsMapComponent;
+    /** The Map3D component (memoized, #139): `options` + `layers` props, both watched; `@loaded`
+     * emits the {@link GoogleMapsMap3D} wrapper.
+     * @returns {GoogleMapsMap3DComponent} The memoized component definition.
+     */
+    get Map3D(): GoogleMapsMap3DComponent;
+    /** The DeckGLOverlay component (memoized, #139; shared wiring #174): nests inside the 2D Map;
+     * `options`/`layers` props, `@loaded` emits the {@link GoogleMapsDeckGLOverlay} wrapper.
+     * @returns {GoogleMapsDeckGLOverlayComponent} The memoized component definition.
+     */
+    get DeckGLOverlay(): GoogleMapsDeckGLOverlayComponent;
+    /** The DeckGL3DTileLayer component (memoized, #139): nests inside the deckGL provider's Map and
+     * prepends the Google 3D Tiles layer; its #appendMap slot receives `{ credits }` (attribution
+     * that must stay visible).
+     * @returns {GoogleMapsDeckGL3DTileLayerComponent} The memoized component definition.
+     */
+    get DeckGL3DTileLayer(): GoogleMapsDeckGL3DTileLayerComponent;
+    /** Configure the js-api-loader once (page-level, #188) and import every wanted library into
+     * `this.sdk` (already-loaded ones are reused).
+     * @param {object} [options] - Load options.
+     * @param {string[]} [options.libraries] - Extra libraries to load on top of the config's.
+     * @returns {Promise<void>} Resolves once every wanted library is in `this.sdk`.
+     */
     loadGoogleMapsSDK({ libraries }?: {
-        libraries?: never[] | undefined;
+        libraries?: string[];
     }): Promise<void>;
-    getSDK(options: any): Promise<any>;
-    createMap(elemRef: any, options?: {}): Promise<any>;
-    createMap3D(elemRef: any, options?: {}): Promise<any>;
+    getSDK(options: string): Promise<object>;
+    getSDK(options?: {
+        libraries?: string[];
+    }): Promise<Record<string, object>>;
+    /** Create a google.maps.Map into `elemRef` and resolve with its wrapper. Must run during a
+     * component's setup(): it registers onMounted/onUnmounted (teardown, #148/#156).
+     * @param {import('vue').Ref<HTMLElement|null>} elemRef - Template ref of the map's container element.
+     * @param {GoogleMapsMapOptions} [options] - google.maps.MapOptions plus the module's mount hook.
+     * @returns {Promise<GoogleMapsMap>} The 2D wrapper (setDeckGLOverlay/.map); rejects on unmount-before-load (error.code 'MAP_UNMOUNTED'), SDK failure, or page-level auth failure (#378).
+     */
+    createMap(elemRef: import('vue').Ref<HTMLElement | null>, options?: GoogleMapsMapOptions): Promise<GoogleMapsMap>;
+    /** Create a <gmp-map-3d> Map3DElement into `elemRef` and resolve with its wrapper. Must run
+     * during a component's setup(): it registers onMounted/onUnmounted (teardown, #148/#156).
+     * Requires the 'maps3d' library — `version: 'alpha'` plus a pre-authorized key.
+     * @param {import('vue').Ref<HTMLElement|null>} elemRef - Template ref of the map's container element.
+     * @param {GoogleMapsMap3DOptions} [options] - Map3DElement attributes plus the module-side keys.
+     * @returns {Promise<GoogleMapsMap3D>} The 3D wrapper (watchOptions/watchLayers/setProps/…); rejects on unmount-before-load (error.code 'MAP_UNMOUNTED'), SDK failure, or page-level auth failure (#378).
+     */
+    createMap3D(elemRef: import('vue').Ref<HTMLElement | null>, options?: GoogleMapsMap3DOptions): Promise<GoogleMapsMap3D>;
+    /** Lazy-import Tile3DLayer into `this.deckgl`.
+     * @returns {Promise<void>} Resolves once Tile3DLayer is available.
+     */
     loadDeckGL(): Promise<void>;
-    createDeckGL3DTileLayer(credits: any, options?: {}): Promise<import("@deck.gl/geo-layers").Tile3DLayer<any, {
-        id: "google-3d-tiles";
-        data: "https://tile.googleapis.com/v1/3dtiles/root.json";
-        loadOptions: {
-            fetch: {
-                headers: {
-                    'X-GOOG-API-KEY': any;
-                };
-            };
-        };
-        onTilesetLoad: (tileset3d: import("@loaders.gl/tiles").Tileset3D) => void;
-        operation: "terrain+draw";
-    }>>;
+    /** Build a Tile3DLayer preconfigured for Google's photorealistic 3D Tiles (keyed with this
+     * provider's apiKey), wiring the tileset copyrights into `credits` — Google's terms require
+     * showing them (the DeckGL3DTileLayer component's #appendMap slot).
+     * @param {import('vue').Ref<string>} credits - Written on every tileset traversal with the '; '-joined copyrights (#328).
+     * @param {Partial<import('@deck.gl/geo-layers').Tile3DLayerProps>} [options] - Tile3DLayer prop overrides; a consumer `onTilesetLoad` is composed after the credits wiring, not clobbering it (#391).
+     * @returns {Promise<import('@deck.gl/geo-layers').Tile3DLayer>} The layer, for the deckGL provider Map's `layers`.
+     */
+    createDeckGL3DTileLayer(credits: import('vue').Ref<string>, options?: Partial<import('@deck.gl/geo-layers').Tile3DLayerProps>): Promise<import('@deck.gl/geo-layers').Tile3DLayer>;
 }
+export {};

package/lib/types/providers/Mapbox.d.ts

@@ -1,114 +1,210 @@
+import { DeckGLOverlay } from './DeckGLOverlay.js';
+/** Shared wiring lives in DeckGLOverlay.js (#174); only the detach mode is provider-specific. */
+declare class MapboxDeckGLOverlay extends DeckGLOverlay {
+    /** @type {import('mapbox-gl').Map|import('maplibre-gl').Map|null} The host map; released by destroy (#284). */
+    map: import('mapbox-gl').Map | import('maplibre-gl').Map | null;
+    /** Wire the shared overlay state and keep the host map for `_detach` (#151).
+     * @param {object} args - Constructor args.
+     * @param {import('vue').WatchStopHandle[]} args.unwatchFn - The overlay's own watcher stop handles (#151).
+     * @param {import('mapbox-gl').Map|import('maplibre-gl').Map} args.map - The host map (maplibre-gl's on the Maplibre provider).
+     * @param {MapboxDeckGLOverlay[]} [args.trackedIn] - The owning map wrapper's overlays list (#156).
+     */
+    constructor({ unwatchFn, map, trackedIn }: {
+        unwatchFn: import('vue').WatchStopHandle[];
+        map: import('mapbox-gl').Map | import('maplibre-gl').Map;
+        trackedIn?: MapboxDeckGLOverlay[];
+    });
+    /** mapbox-gl's removeControl triggers MapboxOverlay's onRemove, which finalizes the
+     * underlying deck instance (#151).
+     * @returns {void}
+     */
+    _detach(): void;
+    /** Release the provider-specific Map reference after the base cleanup: a destroyed wrapper still
+     * held by the consumer (setDeckGLOverlay return, @loaded payload) retained the whole mapbox-gl
+     * Map graph — the base destroy only clears what IT owns (#212 covered the list→wrapper side). (#284)
+     * @returns {void}
+     */
+    destroy(): void;
+}
+export type MapSourceDef = (Parameters<import('mapbox-gl').Map['addSource']>[1] | Parameters<import('maplibre-gl').Map['addSource']>[1]) & {
+    id: string;
+};
+export type MapLayerDef = Parameters<import('mapbox-gl').Map['addLayer']>[0] | Parameters<import('maplibre-gl').Map['addLayer']>[0];
+/**
+ * One entry of the `sources` array/prop: whatever the underlying map's `addSource` accepts (a source
+ * specification — GeoJSON, vector, raster… — or a custom source), plus the `id` the wrapper diffs by (#143).
+ * @typedef {(Parameters<import('mapbox-gl').Map['addSource']>[1]|Parameters<import('maplibre-gl').Map['addSource']>[1]) & { id: string }} MapSourceDef
+ */
+/**
+ * One entry of the `layers` array/prop: whatever the underlying map's `addLayer` accepts — a layer
+ * specification (whose `source` may be an inline source object, see the #9135 workaround in
+ * watchLayers) or a custom layer.
+ * @typedef {Parameters<import('mapbox-gl').Map['addLayer']>[0]|Parameters<import('maplibre-gl').Map['addLayer']>[0]} MapLayerDef
+ */
+/**
+ * The resolved map wrapper: the raw map on `.map`, the reactive watchers, and setDeckGLOverlay.
+ * Shared by the Mapbox and Maplibre providers (createMap is not overridden, #154).
+ */
+declare class MapboxMap {
+    /** @type {import('mapbox-gl').Map|import('maplibre-gl').Map|null} The raw underlying map (maplibre-gl's on the Maplibre provider), set by createMap. */
+    map: import('mapbox-gl').Map | import('maplibre-gl').Map | null;
+    watching: {
+        sources: boolean;
+        layers: boolean;
+    };
+    /** @type {import('vue').WatchStopHandle[]} Stop handles of every watcher owned by the map, run on unmount. */
+    unwatchFn: import('vue').WatchStopHandle[];
+    /** @type {MapboxDeckGLOverlay[]} */
+    overlays: MapboxDeckGLOverlay[];
+    /** @type {WeakMap<object, string>} */
+    _propsIds: WeakMap<object, string>;
+    constructor();
+    /** Signature of a source's non-data props, cached per object identity (#158).
+     * @param {MapSourceDef} source - A source object from the `sources` prop.
+     * @returns {string} The JSON signature of the source without its `data`.
+     */
+    _propsIdOf(source: MapSourceDef): string;
+    /** Keep the map's sources in sync with the reactive array, diffed by source id (#143): sources are
+     * shallow-compared — swap array/object identity to update — except a data-only change (same
+     * propsId), applied in place through setData.
+     * @template {MapSourceDef[]|undefined} T
+     * @param {import('vue').Ref<T>} sources - The reactive sources array.
+     * @param {import('vue').WatchOptions} [options] - Extra vue watch options, merged over `{ immediate: true }`.
+     * @returns {void}
+     */
+    watchSources<T extends MapSourceDef[] | undefined>(sources: import('vue').Ref<T>, options?: import('vue').WatchOptions): void;
+    /** Keep the map's layers in sync with the reactive array, diffed by layer id (#144): layers are
+     * shallow-compared — swap array/layer identity to update; added/changed layers land at their array
+     * position in the z-order (#301).
+     * @template {MapLayerDef[]|undefined} T
+     * @param {import('vue').Ref<T>} layers - The reactive layers array.
+     * @param {import('vue').WatchOptions} [options] - Extra vue watch options, merged over `{ immediate: true }`.
+     * @returns {void}
+     */
+    watchLayers<T extends MapLayerDef[] | undefined>(layers: import('vue').Ref<T>, options?: import('vue').WatchOptions): void;
+    /** Attach a deck.gl overlay (lazy-loaded MapboxOverlay) to the map.
+     * @param {import('@deck.gl/mapbox').MapboxOverlayProps} [options] - The overlay's constructor props (deck.gl layers, interleaved, …).
+     * @returns {Promise<MapboxDeckGLOverlay>} The overlay wrapper: its own watchOptions/watchLayers/destroy.
+     */
+    setDeckGLOverlay(options?: import('@deck.gl/mapbox').MapboxOverlayProps): Promise<MapboxDeckGLOverlay>;
+}
+export type MapboxServiceName = NonNullable<import('../main.js').MapboxConfig['services']>[number];
+export type MapboxMapExtraOptions = {
+    /**
+     * - Take over map creation timing: receives the
+     * `loadMap` thunk and decides when to call it.
+     */
+    onMounted?: (loadMap: () => void) => void;
+    /**
+     * - Vue watch options for the component's sources watcher.
+     */
+    watchSourcesOptions?: import('vue').WatchOptions;
+    /**
+     * - Vue watch options for the component's layers watcher.
+     */
+    watchLayersOptions?: import('vue').WatchOptions;
+};
+export type MapboxMapOptions = Omit<import('mapbox-gl').MapOptions, 'container'> & MapboxMapExtraOptions;
+/**
+ * A Mapbox REST SDK service name (the keys of `servicesLoader`).
+ * @typedef {NonNullable<import('../main.js').MapboxConfig['services']>[number]} MapboxServiceName
+ */
+/**
+ * Wrapper-specific options riding along the map constructor options.
+ * @typedef {object} MapboxMapExtraOptions
+ * @property {(loadMap: () => void) => void} [onMounted] - Take over map creation timing: receives the
+ * `loadMap` thunk and decides when to call it.
+ * @property {import('vue').WatchOptions} [watchSourcesOptions] - Vue watch options for the component's sources watcher.
+ * @property {import('vue').WatchOptions} [watchLayersOptions] - Vue watch options for the component's layers watcher.
+ */
+/**
+ * Options of the Mapbox `Map` component / `createMap`: mapbox-gl's `MapOptions` minus `container`
+ * (the component's element / `elemRef` provides it) — `accessToken` defaults to the config `apiKey` —
+ * plus the wrapper extras.
+ * @typedef {Omit<import('mapbox-gl').MapOptions, 'container'> & MapboxMapExtraOptions} MapboxMapOptions
+ */
+/** Mapbox provider (`type: 'mapbox'`): the `Map`/`DeckGLOverlay` components, `createMap` and the REST SDK. */
 export default class Mapbox {
-    apiKey: any;
-    services: any[];
-    sdk: {};
-    mapboxgl: {
-        AttributionControl: typeof import("mapbox-gl/esm").AttributionControl;
-        CanvasSource: typeof import("mapbox-gl/esm").CanvasSource;
-        CustomSource: typeof import("mapbox-gl/esm").CustomSource;
-        ErrorEvent: typeof import("mapbox-gl/esm").ErrorEvent;
-        Event: typeof import("mapbox-gl/esm").Event;
-        Evented: typeof import("mapbox-gl/esm").Evented;
-        FreeCameraOptions: typeof import("mapbox-gl/esm").FreeCameraOptions;
-        FullscreenControl: typeof import("mapbox-gl/esm").FullscreenControl;
-        GeoJSONSource: typeof import("mapbox-gl/esm").GeoJSONSource;
-        GeolocateControl: typeof import("mapbox-gl/esm").GeolocateControl;
-        ImageSource: typeof import("mapbox-gl/esm").ImageSource;
-        IndoorControl: typeof import("mapbox-gl/esm").IndoorControl;
-        InteractionEvent: typeof import("mapbox-gl/esm").InteractionEvent;
-        LngLat: typeof import("mapbox-gl/esm").LngLat;
-        LngLatBounds: typeof import("mapbox-gl/esm").LngLatBounds;
-        Map: typeof import("mapbox-gl/esm").Map;
-        MapMouseEvent: typeof import("mapbox-gl/esm").MapMouseEvent;
-        MapTouchEvent: typeof import("mapbox-gl/esm").MapTouchEvent;
-        MapWheelEvent: typeof import("mapbox-gl/esm").MapWheelEvent;
-        Marker: typeof import("mapbox-gl/esm").Marker;
-        MercatorCoordinate: typeof import("mapbox-gl/esm").MercatorCoordinate;
-        ModelSource: typeof import("mapbox-gl/esm").ModelSource;
-        NavigationControl: typeof import("mapbox-gl/esm").NavigationControl;
-        Point: typeof import("mapbox-gl/esm").Point;
-        Popup: typeof import("mapbox-gl/esm").Popup;
-        RasterArrayTileSource: typeof import("mapbox-gl/esm").RasterArrayTileSource;
-        RasterDemTileSource: typeof import("mapbox-gl/esm").RasterDemTileSource;
-        RasterTileSource: typeof import("mapbox-gl/esm").RasterTileSource;
-        ResourceType: {
-            readonly Unknown: "Unknown";
-            readonly Style: "Style";
-            readonly Source: "Source";
-            readonly Tile: "Tile";
-            readonly Glyphs: "Glyphs";
-            readonly SpriteImage: "SpriteImage";
-            readonly SpriteJSON: "SpriteJSON";
-            readonly Iconset: "Iconset";
-            readonly Image: "Image";
-            readonly Model: "Model";
-        };
-        ScaleControl: typeof import("mapbox-gl/esm").ScaleControl;
-        Style: typeof import("mapbox-gl/esm").Style;
-        TargetFeature: typeof import("mapbox-gl/esm").TargetFeature;
-        Tiled3DModelSource: typeof import("mapbox-gl/esm").Tiled3DModelSource;
-        VectorTileSource: typeof import("mapbox-gl/esm").VectorTileSource;
-        VideoSource: typeof import("mapbox-gl/esm").VideoSource;
-        addTileProvider: typeof import("mapbox-gl/esm").addTileProvider;
-        clearPrewarmedResources: typeof import("mapbox-gl/esm").clearPrewarmedResources;
-        clearStorage: typeof import("mapbox-gl/esm").clearStorage;
-        getBuildingGenUrl: typeof import("mapbox-gl/esm").getBuildingGenUrl;
-        getDracoUrl: typeof import("mapbox-gl/esm").getDracoUrl;
-        getMeshoptUrl: typeof import("mapbox-gl/esm").getMeshoptUrl;
-        getRTLTextPluginStatus: () => import("mapbox-gl/esm").PluginStatus;
-        getWorkerCount: typeof import("mapbox-gl/esm").getWorkerCount;
-        prewarm: typeof import("mapbox-gl/esm").prewarm;
-        restoreNow: () => void;
-        setAccessToken: typeof import("mapbox-gl/esm").setAccessToken;
-        setBaseApiUrl: typeof import("mapbox-gl/esm").setBaseApiUrl;
-        setBuildingGenUrl: typeof import("mapbox-gl/esm").setBuildingGenUrl;
-        setDracoUrl: typeof import("mapbox-gl/esm").setDracoUrl;
-        setMaxParallelImageRequests: typeof import("mapbox-gl/esm").setMaxParallelImageRequests;
-        setMeshoptUrl: typeof import("mapbox-gl/esm").setMeshoptUrl;
-        setNow: (time: number) => void;
-        setRTLTextPlugin: (url: string, callback?: ((error?: Error | null, result?: {
-            err: Error | null | undefined;
-        } | null | undefined) => void) | null, deferred?: boolean) => void;
-        setSdkInfo: typeof import("mapbox-gl/esm").setSdkInfo;
-        setWorkerCount: typeof import("mapbox-gl/esm").setWorkerCount;
-        setWorkerUrl: typeof import("mapbox-gl/esm").setWorkerUrl;
-        supported: typeof import("mapbox-gl/esm").supported;
-        version: string;
-        default: typeof import("mapbox-gl/esm");
-    } | null;
-    _MapComponent: any;
-    _DeckGLOverlayComponent: any;
-    ready: Promise<any>;
+    /** @type {string|undefined} The configured access token (undefined on the token-less Maplibre subclass, #154). */
+    apiKey: string | undefined;
+    /** @type {MapboxServiceName[]} The REST SDK services to (pre)load. */
+    services: MapboxServiceName[];
+    /** @type {Partial<Record<MapboxServiceName, object>>} The loaded REST service clients by name (plain objects: the mapbox SDK ships no types). */
+    sdk: Partial<Record<MapboxServiceName, object>>;
+    /** @type {typeof import('mapbox-gl/esm')|typeof import('maplibre-gl')|null} The lazily loaded gl namespace (maplibre-gl's on the Maplibre subclass). */
+    mapboxgl: typeof import('mapbox-gl/esm') | typeof import('maplibre-gl') | null;
+    /** @type {import('vue').Component|null} */
+    _MapComponent: import('vue').Component | null;
+    /** @type {import('vue').Component|null} */
+    _DeckGLOverlayComponent: import('vue').Component | null;
+    /** @type {Promise<object>} The SDK preload: resolves with the `sdk` registry, rejects like getSDK(). */
+    ready: Promise<object>;
+    /** Subclasses can opt out of the token requirement (#154): MapLibre works without any key.
+     * @returns {boolean} Whether the constructor requires an apiKey.
+     */
     get requiresApiKey(): boolean;
-    constructor(mapConfig: any);
-    get Map(): any;
-    get DeckGLOverlay(): any;
+    /** Build the provider from its `maps` config entry and kick off the SDK preload (#149).
+     * @param {import('../main.js').MapboxConfig|import('../main.js').MaplibreConfig} mapConfig - The
+     * `maps.<key>` config entry (the token-less MaplibreConfig on the Maplibre subclass, #154).
+     */
+    constructor(mapConfig: import('../main.js').MapboxConfig | import('../main.js').MaplibreConfig);
+    /** The map Vue component: `:options` ({@link MapboxMapOptions}), `:layers` ({@link MapLayerDef}
+     * array), `:sources` ({@link MapSourceDef} array); emits `loaded` with the {@link MapboxMap}
+     * wrapper, and `error`.
+     * @returns {import('vue').Component} The memoized component definition (#139).
+     */
+    get Map(): import('vue').Component;
+    /** The deck.gl overlay Vue component (nests inside `Map`): `:options`, `:layers`; emits `loaded`
+     * with the overlay wrapper, and `error`.
+     * @returns {import('vue').Component} The memoized component definition (#139).
+     */
+    get DeckGLOverlay(): import('vue').Component;
+    /** Lazy-load the gl namespace (and its css) into `this.mapboxgl`, once.
+     * @returns {Promise<void>}
+     */
     loadMapbox(): Promise<void>;
-    get servicesLoader(): {
-        datasets: () => Promise<any>;
-        directions: () => Promise<any>;
-        geocoding: () => Promise<any>;
-        geocodingV6: () => Promise<any>;
-        mapMatching: () => Promise<any>;
-        matrix: () => Promise<any>;
-        optimization: () => Promise<any>;
-        static: () => Promise<any>;
-        styles: () => Promise<any>;
-        tilequery: () => Promise<any>;
-        tilesets: () => Promise<any>;
-        tokens: () => Promise<any>;
-        uploads: () => Promise<any>;
-        isochrone: () => Promise<any>;
-    };
+    /** The lazy REST SDK service loaders — one dynamic import per service, so only the requested
+     * services are fetched; its keys are the valid {@link MapboxServiceName}s.
+     * @returns {Record<MapboxServiceName, () => Promise<{ default: (client: object) => object }>>} Service
+     * name → loader of the service module, whose `default` builds the client-bound service.
+     */
+    get servicesLoader(): Record<MapboxServiceName, () => Promise<{
+        default: (client: object) => object;
+    }>>;
+    /** Build the token-bound SDK client and load the wanted services into `this.sdk` (#150).
+     * @param {object} [options] - Options.
+     * @param {MapboxServiceName[]} [options.services] - Services to load on top of the configured ones.
+     * @returns {Promise<void>}
+     */
     loadMapboxSDK({ services }?: {
-        services?: never[] | undefined;
+        services?: MapboxServiceName[];
     }): Promise<void>;
-    getSDK(options: any): Promise<any>;
+    /** Load and return Mapbox REST SDK services (the config `services` plus the requested ones).
+     * @param {MapboxServiceName|{services?: MapboxServiceName[]}} [options] - A single service name, or
+     * `{ services }` to load several at once.
+     * @returns {Promise<object>} The named service client for a string argument, the whole `sdk`
+     * registry otherwise (plain objects: the mapbox SDK ships no types).
+     * @throws {Error} When a service name is unknown (#150) or its client is not loaded.
+     */
+    getSDK(options?: MapboxServiceName | {
+        services?: MapboxServiceName[];
+    }): Promise<object>;
     /** Map constructor options, overridable per subclass (maplibre-gl has no accessToken option, #154).
      * @param {HTMLElement} container - The map container element.
-     * @param {object} options - Consumer-provided map options.
-     * @returns {object} The options passed to `new mapboxgl.Map()`.
+     * @param {MapboxMapOptions} options - Consumer-provided map options.
+     * @returns {import('mapbox-gl').MapOptions} The options passed to `new mapboxgl.Map()`.
+     */
+    _getMapOptions(container: HTMLElement, options: MapboxMapOptions): import('mapbox-gl').MapOptions;
+    /** Create the map imperatively (must run in a component's setup(): the lifecycle hooks drive it):
+     * resolves the wrapper once the map emits 'load', rejects on ANY failure (#148/#228) — with
+     * `error.code === 'MAP_UNMOUNTED'` when the component unmounted first — and tears the map, its
+     * watchers and its overlays down on unmount.
+     * @template {HTMLElement|null|undefined} TEl
+     * @param {import('vue').Ref<TEl>} elemRef - Template ref to the map's container element.
+     * @param {MapboxMapOptions} [options] - Map constructor options plus the wrapper extras
+     * (maplibre-gl's own options on the Maplibre subclass).
+     * @returns {Promise<MapboxMap>} The map wrapper.
      */
-    _getMapOptions(container: HTMLElement, options: object): object;
-    createMap(elemRef: any, options?: {}): Promise<any>;
+    createMap<TEl extends HTMLElement | null | undefined>(elemRef: import('vue').Ref<TEl>, options?: MapboxMapOptions): Promise<MapboxMap>;
 }
+export {};

package/lib/types/providers/Maplibre.d.ts

@@ -1,13 +1,37 @@
 import Mapbox from './Mapbox.js';
+export type MaplibreMapOptions = Omit<import('maplibre-gl').MapOptions, 'container'> & import('./Mapbox.js').MapboxMapExtraOptions;
+/**
+ * Options of the Maplibre `Map` component / `createMap`: maplibre-gl's `MapOptions` minus `container`
+ * (the component's element / `elemRef` provides it), plus the wrapper extras shared with Mapbox.
+ * @typedef {Omit<import('maplibre-gl').MapOptions, 'container'> & import('./Mapbox.js').MapboxMapExtraOptions} MaplibreMapOptions
+ */
+/**
+ * Maplibre provider (`type: 'maplibre'`/`'maplibre-gl'`): the token-less mapbox-gl fork — same
+ * Map/DeckGLOverlay/createMap surface as Mapbox, minus the REST SDK (#154).
+ */
 export default class Maplibre extends Mapbox {
+    /** MapLibre is the token-less mapbox-gl fork (#154).
+     * @returns {boolean} Always false: no apiKey needed.
+     */
     get requiresApiKey(): boolean;
+    /** Lazy-load the maplibre-gl namespace (and its css) into `this.mapboxgl`, once, pinning its web
+     * worker — the whole story below.
+     * @returns {Promise<void>}
+     */
     loadMapbox(): Promise<void>;
     /** No Mapbox REST SDK on maplibre (#154): the constructor preload resolves to an empty sdk,
      * and requesting a service (argument or configured `services`) is a consumer error.
-     * @param {string|object} [options] - Service name or `{ services }` object, like Mapbox's getSDK.
+     * @param {string|{services?: string[]}} [options] - Service name or `{ services }` object, like Mapbox's getSDK.
      * @returns {Promise<object>} The (empty) sdk registry.
      * @throws {Error} When a service is requested.
      */
-    getSDK(options?: string | object): Promise<object>;
-    _getMapOptions(container: any, options: any): any;
+    getSDK(options?: string | {
+        services?: string[];
+    }): Promise<object>;
+    /** maplibre-gl has no accessToken option (#154): container + consumer options only.
+     * @param {HTMLElement} container - The map container element.
+     * @param {MaplibreMapOptions} options - Consumer-provided map options.
+     * @returns {import('maplibre-gl').MapOptions} The options passed to `new maplibregl.Map()`.
+     */
+    _getMapOptions(container: HTMLElement, options: MaplibreMapOptions): import('maplibre-gl').MapOptions;
 }

package/lib/types/searoute/searoute.d.ts

@@ -1 +1,45 @@
-export default function searoute(origin: any, destination: any, units?: string): import("geojson").Feature<import("geojson").LineString, import("geojson").GeoJsonProperties> | null;
+export type SeaRouteFeature = {
+    /**
+     * - GeoJSON object type.
+     */
+    type: 'Feature';
+    /**
+     * - The `[lng, lat]` network
+     * path, from origin's snap to destination's snap.
+     */
+    geometry: {
+        type: 'LineString';
+        coordinates: number[][];
+    };
+    /**
+     * - The route
+     * length, expressed in `units`.
+     */
+    properties: {
+        units: 'nm' | import('@turf/turf').Units;
+        length: number;
+    };
+};
+/**
+ * The returned route: the GeoJSON LineString Feature built by turf's lineString() over the snapped
+ * network path, with the measured length stamped on `properties` (#138, same contract as the air
+ * twin, #257).
+ * @typedef {object} SeaRouteFeature
+ * @property {'Feature'} type - GeoJSON object type.
+ * @property {{type: 'LineString', coordinates: number[][]}} geometry - The `[lng, lat]` network
+ * path, from origin's snap to destination's snap.
+ * @property {{units: 'nm'|import('@turf/turf').Units, length: number}} properties - The route
+ * length, expressed in `units`.
+ */
+/**
+ * Shortest sea route between two points, each snapped to the Marnet network first, via
+ * geojson-path-finder (weight() bridges the anti-meridian edges).
+ * @param {import('@turf/turf').Coord} origin - Start point: a turf point() Feature, a bare Point
+ * geometry, or a `[lng, lat]` position.
+ * @param {import('@turf/turf').Coord} destination - End point, same accepted shapes.
+ * @param {'nm'|import('@turf/turf').Units} [units='nm'] - Unit of `properties.length`; 'nm' is the
+ * module's alias for turf's 'nauticalmiles' (#138).
+ * @returns {SeaRouteFeature|null} The snapped route — null when no path exists (reachable on valid
+ * inputs, the network is fragmented, #141).
+ */
+export default function searoute(origin: import('@turf/turf').Coord, destination: import('@turf/turf').Coord, units?: 'nm' | import('@turf/turf').Units): SeaRouteFeature | null;

package/lib/types/utils/getAirRoute.d.ts

@@ -1,6 +1,71 @@
-export default function getAirRoute({ origin, destination, step, units }: {
-    destination: any;
-    origin: any;
-    step?: number | undefined;
-    units?: string | undefined;
-}): import("geojson").Feature<import("geojson").LineString, import("geojson").GeoJsonProperties>;
+export type AirRouteOptions = {
+    /**
+     * - Start position, `[lng, lat]`.
+     */
+    origin: number[];
+    /**
+     * - End position, `[lng, lat]`.
+     */
+    destination: number[];
+    /**
+     * - Number of arc segments (the geometry holds `step` interpolated
+     * positions plus the destination, before dedupe); a non-integer or non-positive value falls back
+     * to 100 (#157).
+     */
+    step?: number;
+    /**
+     * - Unit of `properties.length`; 'nm' is
+     * the module's alias for turf's 'nauticalmiles' (#138).
+     */
+    units?: 'nm' | import('@turf/turf').Units;
+};
+export type AirRouteFeature = {
+    /**
+     * - GeoJSON object type.
+     */
+    type: 'Feature';
+    /**
+     * - The arc's `[lng, lat]`
+     * positions; longitudes are unfolded by normalizeRoute and may run past ±180 (#159).
+     */
+    geometry: {
+        type: 'LineString';
+        coordinates: number[][];
+    };
+    /**
+     * - The route
+     * length, expressed in `units`.
+     */
+    properties: {
+        units: 'nm' | import('@turf/turf').Units;
+        length: number;
+    };
+};
+/**
+ * Arguments of getAirRoute.
+ * @typedef {object} AirRouteOptions
+ * @property {number[]} origin - Start position, `[lng, lat]`.
+ * @property {number[]} destination - End position, `[lng, lat]`.
+ * @property {number} [step=100] - Number of arc segments (the geometry holds `step` interpolated
+ * positions plus the destination, before dedupe); a non-integer or non-positive value falls back
+ * to 100 (#157).
+ * @property {'nm'|import('@turf/turf').Units} [units='nm'] - Unit of `properties.length`; 'nm' is
+ * the module's alias for turf's 'nauticalmiles' (#138).
+ */
+/**
+ * The returned route: the GeoJSON LineString Feature built by turf's lineString(), with the
+ * measured length stamped on `properties` (#257).
+ * @typedef {object} AirRouteFeature
+ * @property {'Feature'} type - GeoJSON object type.
+ * @property {{type: 'LineString', coordinates: number[][]}} geometry - The arc's `[lng, lat]`
+ * positions; longitudes are unfolded by normalizeRoute and may run past ±180 (#159).
+ * @property {{units: 'nm'|import('@turf/turf').Units, length: number}} properties - The route
+ * length, expressed in `units`.
+ */
+/**
+ * Great-circle ("air") route between origin and destination: a geodesic arc interpolated with
+ * turf's along(), then unfolded across the anti-meridian and measured on the final geometry.
+ * @param {AirRouteOptions} options - Route endpoints and arc options.
+ * @returns {AirRouteFeature} The arc as a GeoJSON LineString Feature.
+ */
+export default function getAirRoute({ origin, destination, step, units }: AirRouteOptions): AirRouteFeature;

package/lib/types/utils/getWaterRoute.d.ts

@@ -1,6 +1,40 @@
-export default function getWaterRoute({ origin, destination, includeBoundaries, units }: {
-    destination: any;
-    includeBoundaries?: boolean | undefined;
-    origin: any;
-    units?: string | undefined;
-}): Promise<import("geojson").Feature<import("geojson").LineString, import("geojson").GeoJsonProperties> | null>;
+export type WaterRouteOptions = {
+    /**
+     * - Start position, `[lng, lat]`.
+     */
+    origin: number[];
+    /**
+     * - End position, `[lng, lat]`.
+     */
+    destination: number[];
+    /**
+     * - Prepend/append the REAL origin/destination to the
+     * snapped network path (boundary legs), and recompute `properties.length` over the extended
+     * geometry (#159).
+     */
+    includeBoundaries?: boolean;
+    /**
+     * - Unit of `properties.length`; 'nm' is
+     * the module's alias for turf's 'nauticalmiles' (#138).
+     */
+    units?: 'nm' | import('@turf/turf').Units;
+};
+/**
+ * Arguments of getWaterRoute.
+ * @typedef {object} WaterRouteOptions
+ * @property {number[]} origin - Start position, `[lng, lat]`.
+ * @property {number[]} destination - End position, `[lng, lat]`.
+ * @property {boolean} [includeBoundaries=false] - Prepend/append the REAL origin/destination to the
+ * snapped network path (boundary legs), and recompute `properties.length` over the extended
+ * geometry (#159).
+ * @property {'nm'|import('@turf/turf').Units} [units='nm'] - Unit of `properties.length`; 'nm' is
+ * the module's alias for turf's 'nauticalmiles' (#138).
+ */
+/**
+ * Sea ("water") route between origin and destination over the Marnet network, computed by the
+ * dynamically-imported searoute engine, then unfolded across the anti-meridian.
+ * @param {WaterRouteOptions} options - Route endpoints and options.
+ * @returns {Promise<import('../searoute/searoute.js').SeaRouteFeature|null>} The route as a GeoJSON
+ * LineString Feature (`properties.units`/`length` set) — null when no path exists (#141).
+ */
+export default function getWaterRoute({ origin, destination, includeBoundaries, units }: WaterRouteOptions): Promise<import('../searoute/searoute.js').SeaRouteFeature | null>;

package/lib/types/utils/normalizeRoute.d.ts

@@ -1 +1,8 @@
-export default function normalizeRoute(coords: any): any;
+/**
+ * Unfold a route's longitudes across anti-meridian crossings: whenever two consecutive longitudes
+ * jump by more than 180°, shift by ±360 so the line never wraps — the unfolded longitudes may run
+ * past ±180 (turf's haversine handles them, #159). Drops any altitude member on the way.
+ * @param {number[][]} coords - The route positions, `[lng, lat]` first.
+ * @returns {Array<[number, number]>} The unfolded `[lng, lat]` pairs, consecutive duplicates removed.
+ */
+export default function normalizeRoute(coords: number[][]): Array<[number, number]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yappkit/front-module-map",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "@yappkit/front module for map",
   "module": "./lib/yappkit-map.js",
   "main": "./lib/yappkit-map.js",