@trackunit/react-map-adapter-mapbox 0.0.3

package/index.cjs.js

@@ -0,0 +1,2914 @@
+'use strict';
+
+var reactMapAdapterShared = require('@trackunit/react-map-adapter-shared');
+var geoJsonUtils = require('@trackunit/geo-json-utils');
+var esToolkit = require('es-toolkit');
+var mapboxgl = require('mapbox-gl');
+var Supercluster = require('supercluster');
+var zod = require('zod');
+var jsxRuntime = require('react/jsx-runtime');
+var react = require('react');
+var reactDeviceDetect = require('react-device-detect');
+
+/**
+ * Mapbox style URLs for different map types
+ */
+const MAPBOX_MAP_TYPE_STYLES = {
+    roadmap: {
+        light: "mapbox://styles/mapbox/streets-v12",
+        dark: "mapbox://styles/mapbox/dark-v11",
+    },
+    satellite: {
+        light: "mapbox://styles/mapbox/satellite-v9",
+        dark: "mapbox://styles/mapbox/satellite-v9",
+    },
+    hybrid: {
+        light: "mapbox://styles/mapbox/satellite-streets-v12",
+        dark: "mapbox://styles/mapbox/satellite-streets-v12",
+    },
+};
+
+// ============================================================================
+// Helpers
+// ============================================================================
+/**
+ * Convert our internal readonly GeoJSON FeatureCollection to a mutable
+ * Mapbox-compatible GeoJSON object. Mapbox GL JS expects mutable arrays,
+ * while our internal types use `readonly`.
+ */
+const toMapboxGeoJson = (collection) => JSON.parse(JSON.stringify(collection));
+/**
+ * Convert a GeoJSON FeatureCollection for shape sources, injecting each
+ * feature's top-level `id` into `properties.__featureId`.
+ *
+ * Mapbox GL JS only exposes **numeric** feature IDs via `feature.id` in
+ * query results. Our features use string IDs, so we store the original
+ * ID as a property and read it from `properties.__featureId` in event
+ * handlers and paint expressions.
+ */
+const toMapboxShapeGeoJson = (collection, featureStyles, featureZIndexOverrides) => {
+    const raw = JSON.parse(JSON.stringify(collection));
+    for (const feature of raw.features) {
+        const featureId = feature.id !== undefined ? String(feature.id) : "";
+        const perFeature = featureStyles?.get(featureId);
+        const zIndex = featureZIndexOverrides?.get(featureId);
+        feature.properties = {
+            ...feature.properties,
+            __featureId: featureId,
+            ...(zIndex !== undefined && { _zIndex: zIndex }),
+            ...(perFeature !== undefined && {
+                __fill: perFeature.fill,
+                __fillOpacity: perFeature.fillOpacity,
+                __stroke: perFeature.stroke,
+                __strokeOpacity: perFeature.strokeOpacity,
+                __strokeWidth: perFeature.strokeWidth,
+                __pointRadius: perFeature.pointRadius,
+            }),
+        };
+    }
+    return raw;
+};
+/**
+ * Returns a copy of the collection with each feature's geometry replaced by its
+ * clipped fill geometry (ADR-0021 fill tiling), when present. Features without
+ * an override keep their full geometry. Used to build the dedicated fill source
+ * so polygon fills are clipped while the line source keeps full outlines.
+ */
+const applyFillGeometries = (collection, featureFillGeometries) => {
+    if (featureFillGeometries === undefined || featureFillGeometries.size === 0)
+        return collection;
+    return {
+        ...collection,
+        features: collection.features.map(feature => {
+            const featureId = feature.id !== undefined ? String(feature.id) : "";
+            const override = featureFillGeometries.get(featureId);
+            return override === undefined ? feature : { ...feature, geometry: override };
+        }),
+    };
+};
+/**
+ * Build a Mapbox paint value that is either a static fallback or a data-driven
+ * expression reading from an injected feature property.
+ */
+const shapePaint = (featureStyles, prop, fallback) => (featureStyles !== undefined ? ["coalesce", ["get", prop], fallback] : fallback);
+/**
+ * Filter layer IDs based on the interactive mode, keeping only the layers
+ * that should respond to interaction events.
+ *
+ * Convention: `shape-fill-{id}` = polygon fill, `shape-line-{id}` = stroke,
+ *             `shape-circle-{id}` = point circles (always interactive).
+ */
+const filterLayerIdsByMode = (mode, layerIds, configId) => {
+    const lineId = `shape-line-${configId}`;
+    const circleId = `shape-circle-${configId}`;
+    switch (mode) {
+        case "stroke":
+            return layerIds.filter(id => id === lineId || id === circleId);
+        case "stroke-and-fill":
+            return layerIds;
+        default:
+            throw new Error(`${mode} is not known`);
+    }
+};
+/**
+ * Convert a GeoJSON bbox [minLng, minLat, maxLng, maxLat] to the corner
+ * coordinate format required by Mapbox image sources:
+ * [[topLeft], [topRight], [bottomRight], [bottomLeft]]
+ */
+const bboxToImageCoordinates = (bbox) => {
+    const [minLng, minLat, maxLng, maxLat] = bbox;
+    return [
+        [minLng, maxLat], // top-left
+        [maxLng, maxLat], // top-right
+        [maxLng, minLat], // bottom-right
+        [minLng, minLat], // bottom-left
+    ];
+};
+/**
+ * Safely check if a source exists on the map.
+ */
+const hasSource = (map, sourceId) => {
+    try {
+        return map.getSource(sourceId) !== undefined;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Safely check if a layer exists on the map.
+ */
+const hasLayer = (map, layerId) => {
+    try {
+        return map.getLayer(layerId) !== undefined;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Safely remove a layer then its source from the map.
+ */
+const safeRemoveLayersAndSource = (map, layerIds, sourceId) => {
+    for (const layerId of layerIds) {
+        if (hasLayer(map, layerId)) {
+            map.removeLayer(layerId);
+        }
+    }
+    if (hasSource(map, sourceId)) {
+        map.removeSource(sourceId);
+    }
+};
+// ============================================================================
+// MapboxLayerPort
+// ============================================================================
+/**
+ * Mapbox implementation of the LayerPort interface.
+ *
+ * Manages Mapbox GL JS sources, layers, and Marker overlays to render map content.
+ * Each source type maps to appropriate Mapbox constructs:
+ * - Markers: `mapboxgl.Marker` DOM overlays (symbol: styled div, dom: portal container)
+ * - Shapes: GeoJSON source + fill/line layers
+ * - Routes: GeoJSON source + line layer (+ optional symbol layer for arrows)
+ * - Image overlays: Image source + raster layer
+ *
+ * Client-side clustering uses `supercluster` directly, managing marker
+ * visibility based on viewport and zoom level.
+ *
+ * Requires `connect(map)` to be called (by MapboxAdapterInstance) before
+ * any sources can be rendered. Sources set before connect are queued.
+ */
+class MapboxLayerPort {
+    constructor() {
+        /**
+         * Marker portal subscription compatible with `useSyncExternalStore`.
+         * `<Layers>` routes descriptors from this store to `markerRender`. Includes
+         * static DOM markers and adaptive markers resolved to the DOM medium.
+         */
+        this.markerPortals = {
+            subscribe: (callback) => {
+                this.markerPortalSubscribers.add(callback);
+                return () => {
+                    this.markerPortalSubscribers.delete(callback);
+                };
+            },
+            getSnapshot: () => {
+                return this.markerPortalDescriptors;
+            },
+        };
+        /**
+         * Cluster portal subscription compatible with `useSyncExternalStore`.
+         * `<Layers>` routes descriptors from this store to `clusterRender`. Includes
+         * client-cluster DOM containers and any other cluster-class portals.
+         */
+        this.clusterPortals = {
+            subscribe: (callback) => {
+                this.clusterPortalSubscribers.add(callback);
+                return () => {
+                    this.clusterPortalSubscribers.delete(callback);
+                };
+            },
+            getSnapshot: () => {
+                return this.clusterPortalDescriptors;
+            },
+        };
+        this.map = null;
+        this.interactionHandlers = new Set();
+        this.backgroundClickHandlers = new Set();
+        this.entityClickedInTick = false;
+        this.mapClickHandler = null;
+        // Tracked sources, keyed by source ID
+        this.markerSources = new Map();
+        /** featureId → DOM marker, keyed by sourceId. Cleared when a source is removed. */
+        this.adaptiveMarkerIndex = new Map();
+        /** featureId → cluster DOM marker, keyed by sourceId. Cleared when a source is removed. */
+        this.clusterMarkerIndex = new Map();
+        this.shapeSources = new Map();
+        this.routeSources = new Map();
+        this.overlaySources = new Map();
+        // Snapshot queued before the map is connected / style is ready
+        this.pendingSnapshot = null;
+        // Last non-empty snapshot the consumer pushed. Preserved across `destroy()` so the React 18
+        // StrictMode dev cycle (cleanup pushes EMPTY → adapter destroy → remount → `useWatch` retains
+        // its prev value and does not re-fire) can replay the actual layer state on the next `connect`.
+        this.lastNonEmptySnapshot = null;
+        // ---- DOM portal registry ----
+        // Two typed stores so `<Layers>` derives render-config routing
+        // (markerRender vs clusterRender) structurally from store membership.
+        this.markerPortalDescriptors = [];
+        this.clusterPortalDescriptors = [];
+        this.markerPortalSubscribers = new Set();
+        this.clusterPortalSubscribers = new Set();
+        this.clusterEntitiesByMarker = new WeakMap();
+        // ---- Style change reconnection ----
+        this.styleLoadHandler = null;
+        /**
+         * Tracks whether the Mapbox style has loaded at least once.
+         * `map.isStyleLoaded()` returns false inside `style.load` callbacks,
+         * so we maintain our own flag set synchronously in the handler.
+         */
+        this.styleReady = false;
+        // ---- Direction arrow image tracking ----
+        this.arrowImageAdded = false;
+        // ---- Shape layer interaction handler storage ----
+        this.shapeClickHandlers = new Map();
+        this.shapeDblClickHandlers = new Map();
+        this.shapeMouseEnterHandlers = new Map();
+        this.shapeMouseLeaveHandlers = new Map();
+        // ---- Route layer interaction handler storage ----
+        this.routeClickHandlers = new Map();
+        this.routeDblClickHandlers = new Map();
+        this.routeMouseEnterHandlers = new Map();
+        this.routeMouseLeaveHandlers = new Map();
+        // ---- Marker circle layer interaction handler storage ----
+        this.markerClickHandlers = new Map();
+        this.markerDblClickHandlers = new Map();
+        this.markerMouseMoveHandlers = new Map();
+        this.markerMouseLeaveHandlers = new Map();
+        this.lastHoveredMarkerFeatureId = null;
+        // ---- Adaptive hover watcher (shared across all DOM markers) ----
+        /** Shared state for the active document-level pointermove watcher across all DOM markers. */
+        this.markerHoverState = { activeWatcherCancel: null, activeGuardCancel: null };
+        // ---- Shape interaction tracking ----
+        this.selectedShapeHandleId = null;
+        this.selectedShapeFeatureId = null;
+        this.hoveredShapeHandleId = null;
+        this.hoveredShapeFeatureId = null;
+        this.theme = "light";
+        // ---- Source readiness tracking ----
+        this.sourceReadyCallbacks = new Map();
+        this.sourcedataHandler = null;
+        this._shapeStyleDefaults = undefined;
+    }
+    get shapeStyleDefaults() {
+        if (this._shapeStyleDefaults === undefined) {
+            throw new Error("shapeStyleDefaults not injected — call setShapeStyleDefaults before using MapboxLayerPort");
+        }
+        return this._shapeStyleDefaults;
+    }
+    // ---- Connection ----
+    setShapeStyleDefaults(defaults) {
+        this._shapeStyleDefaults = defaults;
+    }
+    /**
+     * Connect to a Mapbox map instance.
+     * Called by MapboxAdapterInstance.connect() when the map is ready.
+     * Flushes any sources that were set before the map was available.
+     */
+    connect(map) {
+        this.map = map;
+        // Persistent style.load listener: marks the style as ready, flushes any
+        // queued sources, and reconnects GL layers that were lost on style change.
+        this.styleLoadHandler = () => {
+            this.styleReady = true;
+            this.onStyleLoad();
+            this.flushPending();
+        };
+        map.on("style.load", this.styleLoadHandler);
+        this.sourcedataHandler = (e) => {
+            if (e.isSourceLoaded !== true || e.sourceId === undefined)
+                return;
+            const sourceId = e.sourceId;
+            const callbacks = this.sourceReadyCallbacks.get(sourceId);
+            if (callbacks === undefined)
+                return;
+            this.sourceReadyCallbacks.delete(sourceId);
+            callbacks.forEach(cb => cb());
+        };
+        map.on("sourcedata", this.sourcedataHandler);
+        // Background click detection
+        this.mapClickHandler = () => {
+            if (!this.entityClickedInTick) {
+                this.backgroundClickHandlers.forEach(handler => handler());
+            }
+        };
+        map.on("click", this.mapClickHandler);
+        // Reset arrow image flag (new map/style = need to re-add)
+        this.arrowImageAdded = false;
+        // If style is already loaded (reconnection), flush immediately.
+        if (this.styleReady) {
+            this.flushPending();
+        }
+    }
+    // ---- Declarative state ----
+    setSnapshot(snapshot) {
+        if (snapshot.layers.length > 0) {
+            this.lastNonEmptySnapshot = snapshot;
+        }
+        if (this.map === null || !this.styleReady) {
+            this.pendingSnapshot = snapshot;
+            return;
+        }
+        this.applySnapshot(snapshot);
+    }
+    // ---- Theme ----
+    /**
+     * Update the theme used for interaction style resolution (hover color shifts).
+     * Called by the adapter instance when the map theme changes.
+     */
+    setTheme(theme) {
+        if (this.theme === theme)
+            return;
+        this.theme = theme;
+        if (this.map === null)
+            return;
+        if (this.hoveredShapeHandleId !== null) {
+            this.applyShapeInteractionPaint(this.hoveredShapeHandleId);
+        }
+        if (this.selectedShapeHandleId !== null && this.selectedShapeHandleId !== this.hoveredShapeHandleId) {
+            this.applyShapeInteractionPaint(this.selectedShapeHandleId);
+        }
+    }
+    // ---- Entity interaction ----
+    onEntityInteraction(handler) {
+        this.interactionHandlers.add(handler);
+        return () => {
+            this.interactionHandlers.delete(handler);
+        };
+    }
+    onBackgroundClick(handler) {
+        this.backgroundClickHandlers.add(handler);
+        return () => {
+            this.backgroundClickHandlers.delete(handler);
+        };
+    }
+    // ---- Source readiness ----
+    onSourceReady(configId, callback) {
+        const internalId = `shape-source-${configId}`;
+        if (this.map !== null && hasSource(this.map, internalId) && this.map.isSourceLoaded(internalId)) {
+            queueMicrotask(callback);
+            return () => {
+                /* already fired */
+            };
+        }
+        let existing = this.sourceReadyCallbacks.get(internalId);
+        if (existing === undefined) {
+            existing = new Set();
+            this.sourceReadyCallbacks.set(internalId, existing);
+        }
+        existing.add(callback);
+        return () => {
+            existing.delete(callback);
+            if (existing.size === 0) {
+                this.sourceReadyCallbacks.delete(internalId);
+            }
+        };
+    }
+    // ---- Lifecycle ----
+    /** @internal */
+    destroy() {
+        this.markerHoverState.activeWatcherCancel?.();
+        this.markerHoverState.activeWatcherCancel = null;
+        this.markerHoverState.activeGuardCancel?.();
+        this.markerHoverState.activeGuardCancel = null;
+        // Remove all sources
+        for (const id of [...this.markerSources.keys()]) {
+            this.removeMarkerSourceInternal(id);
+        }
+        for (const id of [...this.shapeSources.keys()]) {
+            this.removeShapeSourceInternal(id);
+        }
+        for (const id of [...this.routeSources.keys()]) {
+            this.removeRouteSourceInternal(id);
+        }
+        for (const id of [...this.overlaySources.keys()]) {
+            this.removeImageOverlayInternal(id);
+        }
+        // Remove style.load listener
+        if (this.styleLoadHandler !== null && this.map !== null) {
+            this.map.off("style.load", this.styleLoadHandler);
+            this.styleLoadHandler = null;
+        }
+        // Remove sourcedata listener
+        if (this.sourcedataHandler !== null && this.map !== null) {
+            this.map.off("sourcedata", this.sourcedataHandler);
+            this.sourcedataHandler = null;
+        }
+        this.sourceReadyCallbacks.clear();
+        if (this.mapClickHandler !== null && this.map !== null) {
+            this.map.off("click", this.mapClickHandler);
+            this.mapClickHandler = null;
+        }
+        this.interactionHandlers.clear();
+        this.backgroundClickHandlers.clear();
+        this.markerPortalDescriptors = [];
+        this.clusterPortalDescriptors = [];
+        this.markerPortalSubscribers.clear();
+        this.clusterPortalSubscribers.clear();
+        this.pendingSnapshot = null;
+        this.arrowImageAdded = false;
+        this.styleReady = false;
+        this.lastHoveredMarkerFeatureId = null;
+        this.selectedShapeHandleId = null;
+        this.selectedShapeFeatureId = null;
+        this.hoveredShapeHandleId = null;
+        this.hoveredShapeFeatureId = null;
+        this.map = null;
+    }
+    // ---- Marker sources ----
+    syncMarkerSource(config) {
+        if (this.map === null)
+            return;
+        // Skip full rebuild if config reference hasn't changed (same data, nothing to do)
+        const existing = this.markerSources.get(config.id);
+        if (existing !== undefined && existing.config === config) {
+            return;
+        }
+        // Adaptive mode: incremental patch when only adaptiveResolution (or callbacks) changed
+        // but the feature set and structural config are the same. This avoids the
+        // remove-then-add cycle (and its cascading mouseleave → hover-clear → rebuild loop)
+        // that caused all markers to flash on every hover interaction.
+        if (existing !== undefined && reactMapAdapterShared.canPatchAdaptiveMarker(existing.config, config)) {
+            this.patchAdaptiveMarkers(existing, config);
+            existing.config = config;
+            return;
+        }
+        // Adaptive mode: viewport refetch changed which markers/clusters are visible but
+        // structural config is unchanged. Diff by feature id instead of tearing everything down.
+        if (existing !== undefined && reactMapAdapterShared.canPatchAdaptiveViewport(existing.config, config)) {
+            this.patchAdaptiveViewportData(existing, config);
+            existing.config = config;
+            return;
+        }
+        // Enhanced bail-out: skip full rebuild when only callback references changed
+        // but the actual marker data (feature IDs, render mode, anchor, clustering) is the same.
+        // This prevents visible blinking caused by unstable function references
+        // (e.g. inline style/render callbacks recreated on React re-renders).
+        if (existing !== undefined && reactMapAdapterShared.canPatchMarkerInPlace(existing.config, config)) {
+            if (config.markerRender.mode === "dom") {
+                this.patchDomMarkers(existing, config);
+            }
+            existing.config = config;
+            return;
+        }
+        // Remove existing markers for this source (update case)
+        this.removeMarkerSourceInternal(config.id);
+        const tracked = { markers: [], config };
+        const currentMap = this.map;
+        // ---- Client-side clustering path (interactive markers only) ----
+        if (config.kind === "marker" && config.clusterConfig?.mode === "client") {
+            if (config.markerRender.mode === "adaptive") {
+                throw new Error("react-map: adaptive marker rendering is not supported with client-side clustering");
+            }
+            this.setupClientClustering(config, currentMap, tracked);
+            this.markerSources.set(config.id, tracked);
+            return;
+        }
+        // ---- Standard (no clustering / server-side clustering) path ----
+        const { markerRender } = config;
+        const useCircleLayer = markerRender.mode === "symbol" || markerRender.mode === "adaptive";
+        if (useCircleLayer) {
+            // WebGL circle layer path for symbol/adaptive modes
+            const promotedIds = reactMapAdapterShared.getAdaptiveDomFeatureIds(config);
+            const symbolState = {
+                medium: "symbol",
+                selected: false,
+                hovered: false,
+                theme: this.theme,
+            };
+            const styleFn = markerRender.mode === "symbol"
+                ? item => markerRender.render(item, symbolState)
+                : reactMapAdapterShared.buildAdaptiveSymbolStyleFn(markerRender.render, symbolState);
+            // Build enriched GeoJSON with resolved style properties, filtering out promoted features
+            const enrichedFeatures = [];
+            for (const feature of config.features.features) {
+                const coords = reactMapAdapterShared.extractPointCoordinates(feature);
+                if (coords === null)
+                    continue;
+                const featureId = feature.id !== undefined ? String(feature.id) : undefined;
+                if (featureId !== undefined && promotedIds.has(featureId))
+                    continue;
+                const resolved = reactMapAdapterShared.resolveCircleSymbolDefaults(reactMapAdapterShared.resolveSymbolDescriptor(styleFn, feature.properties));
+                enrichedFeatures.push({
+                    type: "Feature",
+                    id: feature.id !== undefined ? Number(feature.id) || undefined : undefined,
+                    geometry: { type: "Point", coordinates: [coords.lng, coords.lat] },
+                    properties: {
+                        __featureId: featureId ?? "",
+                        __color: resolved.color,
+                        __radius: resolved.radiusPx,
+                        __opacity: resolved.opacity,
+                        __strokeColor: resolved.borderColor ?? "#000000",
+                        __strokeWidth: resolved.hasBorder ? resolved.borderWidthPx : 0,
+                    },
+                });
+            }
+            const sourceId = `marker-source-${config.id}`;
+            const circleLayerId = `marker-circle-${config.id}`;
+            currentMap.addSource(sourceId, {
+                type: "geojson",
+                data: { type: "FeatureCollection", features: enrichedFeatures },
+            });
+            this.addLayerWithFadeIn(currentMap, {
+                id: circleLayerId,
+                type: "circle",
+                source: sourceId,
+                paint: {
+                    "circle-radius": ["coalesce", ["get", "__radius"], 8],
+                    "circle-color": ["coalesce", ["get", "__color"], "#4285F4"],
+                    "circle-opacity": ["coalesce", ["get", "__opacity"], 1],
+                    "circle-stroke-width": ["coalesce", ["get", "__strokeWidth"], 0],
+                    "circle-stroke-color": ["coalesce", ["get", "__strokeColor"], "#000000"],
+                },
+            });
+            tracked.sourceId = sourceId;
+            tracked.layerIds = [circleLayerId];
+            if (config.kind === "marker") {
+                this.attachMarkerCircleLayerListeners(currentMap, circleLayerId);
+            }
+            if (markerRender.mode === "adaptive") {
+                this.createAdaptiveDomOverlays(config, currentMap, tracked);
+            }
+        }
+        else {
+            // DOM marker path (mode === "dom")
+            for (const feature of config.features.features) {
+                const coords = reactMapAdapterShared.extractPointCoordinates(feature);
+                if (coords === null)
+                    continue;
+                const marker = this.createMarkerForFeature(feature, coords, config, currentMap);
+                tracked.markers.push(marker);
+                if (config.kind === "marker") {
+                    const featureId = feature.id !== undefined ? String(feature.id) : undefined;
+                    if (featureId !== undefined) {
+                        this.attachMarkerInteractionListeners(marker, featureId, coords);
+                    }
+                }
+                else if (marker.getElement() instanceof HTMLElement) {
+                    marker.getElement().style.pointerEvents = "none";
+                }
+            }
+        }
+        // Render server-side cluster features if present (interactive markers only)
+        if (config.kind === "marker" && config.clusterFeatures !== null) {
+            const clusterIndex = new Map();
+            for (const feature of config.clusterFeatures.features) {
+                const coords = reactMapAdapterShared.extractPointCoordinates(feature);
+                if (coords === null)
+                    continue;
+                const marker = this.createClusterMarkerForFeature(feature, coords, config, currentMap);
+                tracked.markers.push(marker);
+                const featureId = feature.id !== undefined ? String(feature.id) : undefined;
+                if (featureId !== undefined) {
+                    clusterIndex.set(featureId, marker);
+                    const props = feature.properties;
+                    const rawMarkerIds = props !== null ? props.markerIds : undefined;
+                    const markerIds = Array.isArray(rawMarkerIds) ? rawMarkerIds : [];
+                    const clusterBbox = props && props.bbox !== null ? geoJsonUtils.validateBbox(props.bbox) : null;
+                    this.attachClusterInteractionListeners(marker, featureId, coords, markerIds, clusterBbox);
+                }
+            }
+            this.clusterMarkerIndex.set(config.id, clusterIndex);
+        }
+        this.markerSources.set(config.id, tracked);
+    }
+    removeMarkerSourceInternal(id) {
+        const tracked = this.markerSources.get(id);
+        if (tracked === undefined)
+            return;
+        // Clean up viewport listener for client-side clustering
+        if (tracked.viewportListener !== undefined && this.map !== null) {
+            this.map.off("moveend", tracked.viewportListener);
+        }
+        // Remove cluster markers
+        if (tracked.clusterMarkers !== undefined) {
+            for (const marker of tracked.clusterMarkers) {
+                marker.remove();
+            }
+        }
+        // Remove all individual DOM markers
+        for (const marker of tracked.markers) {
+            marker.remove();
+        }
+        // Remove WebGL circle layer/source if present
+        if (tracked.sourceId !== undefined && tracked.layerIds !== undefined && this.map !== null) {
+            this.detachMarkerCircleLayerListeners(this.map, tracked.layerIds);
+            safeRemoveLayersAndSource(this.map, tracked.layerIds, tracked.sourceId);
+        }
+        // Clean up DOM portal descriptors for this source
+        this.removePortalDescriptorsForSource(id);
+        this.markerSources.delete(id);
+        this.adaptiveMarkerIndex.delete(id);
+        this.clusterMarkerIndex.delete(id);
+    }
+    // ---- Shape sources ----
+    syncShapeSource(config) {
+        if (this.map === null)
+            return;
+        const existing = this.shapeSources.get(config.id);
+        if (existing !== undefined) {
+            const prev = existing.config;
+            const featuresChanged = prev.features !== config.features;
+            const featureStylesChanged = prev.featureStyles !== config.featureStyles;
+            const fillGeometriesChanged = prev.featureFillGeometries !== config.featureFillGeometries;
+            const zIndexOverridesChanged = prev.featureZIndexOverrides !== config.featureZIndexOverrides;
+            const styleChanged = !esToolkit.isEqual(prev.style, config.style);
+            const interactiveChanged = prev.interactive !== config.interactive;
+            if (!featuresChanged &&
+                !styleChanged &&
+                !featureStylesChanged &&
+                !fillGeometriesChanged &&
+                !zIndexOverridesChanged &&
+                !interactiveChanged) {
+                return;
+            }
+            const existingSource = this.map.getSource(existing.sourceId);
+            const existingFillSource = this.map.getSource(existing.fillSourceId);
+            if (existingSource !== undefined && "setData" in existingSource) {
+                // Re-densify whenever features, per-feature styles, or the layer-level geodesic flag changes —
+                // geodesic is a coordinate-transform that lives in the source data, not just a paint property.
+                const geodesicChanged = prev.style.geodesic !== config.style.geodesic;
+                const interactionPaintActive = this.selectedShapeHandleId === config.id || this.hoveredShapeHandleId === config.id;
+                if ((featuresChanged || featureStylesChanged || geodesicChanged) && "setData" in existingSource) {
+                    existingSource.setData(toMapboxShapeGeoJson(reactMapAdapterShared.mergeAntimeridianFeatures(reactMapAdapterShared.densifyGeodesicFeatures(config.features, config.style.geodesic ?? true, config.featureStyles)), config.featureStyles));
+                }
+                if ((featuresChanged ||
+                    featureStylesChanged ||
+                    geodesicChanged ||
+                    fillGeometriesChanged ||
+                    zIndexOverridesChanged) &&
+                    existingFillSource !== undefined &&
+                    "setData" in existingFillSource) {
+                    existingFillSource.setData(toMapboxShapeGeoJson(reactMapAdapterShared.mergeAntimeridianFeatures(reactMapAdapterShared.densifyGeodesicFeatures(applyFillGeometries(config.features, config.featureFillGeometries), config.style.geodesic ?? true, config.featureStyles)), config.featureStyles, config.featureZIndexOverrides));
+                }
+                if (styleChanged || featureStylesChanged) {
+                    const updatedFs = config.featureStyles;
+                    this.map.setPaintProperty(`shape-fill-${config.id}`, "fill-color", shapePaint(updatedFs, "__fill", config.style.fill ?? "rgba(0,0,0,0.1)"));
+                    this.map.setPaintProperty(`shape-fill-${config.id}`, "fill-opacity", shapePaint(updatedFs, "__fillOpacity", config.style.fillOpacity ?? this.shapeStyleDefaults.polygon.fillOpacity));
+                    this.map.setPaintProperty(`shape-line-${config.id}`, "line-color", shapePaint(updatedFs, "__stroke", config.style.stroke ?? "#000000"));
+                    this.map.setPaintProperty(`shape-line-${config.id}`, "line-width", shapePaint(updatedFs, "__strokeWidth", config.style.strokeWidth ?? this.shapeStyleDefaults.line.strokeWidth));
+                    this.map.setPaintProperty(`shape-line-${config.id}`, "line-opacity", shapePaint(updatedFs, "__strokeOpacity", config.style.strokeOpacity ?? this.shapeStyleDefaults.line.strokeOpacity));
+                    this.map.setPaintProperty(`shape-circle-${config.id}`, "circle-radius", shapePaint(updatedFs, "__pointRadius", config.style.pointRadius ?? this.shapeStyleDefaults.point.pointRadius));
+                    this.map.setPaintProperty(`shape-circle-${config.id}`, "circle-color", shapePaint(updatedFs, "__fill", config.style.fill ?? "rgba(0,0,0,0.1)"));
+                    this.map.setPaintProperty(`shape-circle-${config.id}`, "circle-stroke-color", shapePaint(updatedFs, "__stroke", config.style.stroke ?? "#000000"));
+                    this.map.setPaintProperty(`shape-circle-${config.id}`, "circle-stroke-width", shapePaint(updatedFs, "__strokeWidth", config.style.strokeWidth ?? this.shapeStyleDefaults.point.strokeWidth));
+                    this.map.setPaintProperty(`shape-circle-${config.id}`, "circle-opacity", shapePaint(updatedFs, "__fillOpacity", config.style.fillOpacity ?? this.shapeStyleDefaults.point.fillOpacity));
+                }
+                const shouldReapplyInteractionPaint = interactionPaintActive && (styleChanged || featureStylesChanged);
+                if (interactiveChanged) {
+                    this.detachShapeLayerInteractionListeners(this.map, existing.layerIds);
+                    if (config.interactive !== "none") {
+                        const filtered = filterLayerIdsByMode(config.interactive, existing.layerIds, config.id);
+                        this.attachShapeLayerInteractionListeners(this.map, filtered, config.id);
+                    }
+                }
+                existing.config = config;
+                if (shouldReapplyInteractionPaint) {
+                    this.applyShapeInteractionPaint(config.id);
+                }
+                return;
+            }
+        }
+        // Full add: source doesn't exist yet (first add or style reload)
+        this.removeShapeSourceInternal(config.id);
+        const currentMap = this.map;
+        const sourceId = `shape-source-${config.id}`;
+        const fillSourceId = `shape-fill-src-${config.id}`;
+        const fillLayerId = `shape-fill-${config.id}`;
+        const lineLayerId = `shape-line-${config.id}`;
+        const circleLayerId = `shape-circle-${config.id}`;
+        const fs = config.featureStyles;
+        // Geodesic densification: insert great-circle intermediate points so polygon/line
+        // edges curve with the Earth's surface. Mapbox GL has no native geodesic support —
+        // this pre-processes the GeoJSON before it reaches either shape source.
+        // TODO: remove densifyGeodesicFeatures once Mapbox GL ships native geodesic line/fill
+        //       rendering and replace with a layer-level paint/layout property instead.
+        const geoJsonData = toMapboxShapeGeoJson(reactMapAdapterShared.mergeAntimeridianFeatures(reactMapAdapterShared.densifyGeodesicFeatures(config.features, config.style.geodesic ?? true, config.featureStyles)), fs);
+        // Fills read from a dedicated source carrying clipped geometry and z-index
+        // overrides; strokes and circles keep the original full-geometry source so
+        // outlines stay full. The _zIndex property is read by the fill-sort-key layout
+        // property for hover-promotion stacking (ADR-0021 Path B).
+        const fillGeoJsonData = toMapboxShapeGeoJson(reactMapAdapterShared.mergeAntimeridianFeatures(reactMapAdapterShared.densifyGeodesicFeatures(applyFillGeometries(config.features, config.featureFillGeometries), config.style.geodesic ?? true, config.featureStyles)), fs, config.featureZIndexOverrides);
+        currentMap.addSource(sourceId, {
+            type: "geojson",
+            data: geoJsonData,
+        });
+        currentMap.addSource(fillSourceId, {
+            type: "geojson",
+            data: fillGeoJsonData,
+        });
+        const layerIds = [];
+        this.addLayerWithFadeIn(currentMap, {
+            id: fillLayerId,
+            type: "fill",
+            source: fillSourceId,
+            filter: ["any", ["==", ["geometry-type"], "Polygon"], ["==", ["geometry-type"], "MultiPolygon"]],
+            layout: {
+                // _zIndex is injected per-feature by the fill tiling hook (ADR-0021 Path B).
+                // Features without _zIndex (non-overlapping) render at z-order 0.
+                "fill-sort-key": ["coalesce", ["get", "_zIndex"], 0],
+            },
+            paint: {
+                "fill-color": shapePaint(fs, "__fill", config.style.fill ?? "rgba(0,0,0,0.1)"),
+                "fill-opacity": shapePaint(fs, "__fillOpacity", config.style.fillOpacity ?? this.shapeStyleDefaults.polygon.fillOpacity),
+            },
+        });
+        layerIds.push(fillLayerId);
+        this.addLayerWithFadeIn(currentMap, {
+            id: lineLayerId,
+            type: "line",
+            source: sourceId,
+            paint: {
+                "line-color": shapePaint(fs, "__stroke", config.style.stroke ?? "#000000"),
+                "line-width": shapePaint(fs, "__strokeWidth", config.style.strokeWidth ?? this.shapeStyleDefaults.line.strokeWidth),
+                "line-opacity": shapePaint(fs, "__strokeOpacity", config.style.strokeOpacity ?? this.shapeStyleDefaults.line.strokeOpacity),
+            },
+        });
+        layerIds.push(lineLayerId);
+        this.addLayerWithFadeIn(currentMap, {
+            id: circleLayerId,
+            type: "circle",
+            source: sourceId,
+            filter: ["any", ["==", ["geometry-type"], "Point"], ["==", ["geometry-type"], "MultiPoint"]],
+            paint: {
+                "circle-radius": shapePaint(fs, "__pointRadius", config.style.pointRadius ?? this.shapeStyleDefaults.point.pointRadius),
+                "circle-color": shapePaint(fs, "__fill", config.style.fill ?? "rgba(0,0,0,0.1)"),
+                "circle-stroke-color": shapePaint(fs, "__stroke", config.style.stroke ?? "#000000"),
+                "circle-stroke-width": shapePaint(fs, "__strokeWidth", config.style.strokeWidth ?? this.shapeStyleDefaults.point.strokeWidth),
+                "circle-opacity": shapePaint(fs, "__fillOpacity", config.style.fillOpacity ?? this.shapeStyleDefaults.point.fillOpacity),
+            },
+        });
+        layerIds.push(circleLayerId);
+        if (config.interactive !== "none") {
+            const filtered = filterLayerIdsByMode(config.interactive, layerIds, config.id);
+            this.attachShapeLayerInteractionListeners(currentMap, filtered, config.id);
+        }
+        this.shapeSources.set(config.id, { sourceId, fillSourceId, layerIds, config });
+    }
+    removeShapeSourceInternal(id) {
+        const tracked = this.shapeSources.get(id);
+        if (tracked === undefined)
+            return;
+        if (this.map !== null) {
+            // Remove interaction listeners
+            this.detachShapeLayerInteractionListeners(this.map, tracked.layerIds);
+            safeRemoveLayersAndSource(this.map, tracked.layerIds, tracked.sourceId);
+            // The dedicated fill source (ADR-0021) has no remaining layers after the
+            // fill layer above was removed, so it is safe to drop.
+            if (hasSource(this.map, tracked.fillSourceId)) {
+                this.map.removeSource(tracked.fillSourceId);
+            }
+        }
+        if (this.selectedShapeHandleId === id) {
+            this.selectedShapeHandleId = null;
+            this.selectedShapeFeatureId = null;
+        }
+        if (this.hoveredShapeHandleId === id) {
+            this.hoveredShapeHandleId = null;
+            this.hoveredShapeFeatureId = null;
+        }
+        this.shapeSources.delete(id);
+    }
+    // ---- Shape interaction ----
+    applyShapeSelectionState(handleId, featureId) {
+        if (this.selectedShapeHandleId === handleId && this.selectedShapeFeatureId === featureId)
+            return;
+        const prevHandleId = this.selectedShapeHandleId;
+        this.selectedShapeHandleId = handleId;
+        this.selectedShapeFeatureId = featureId;
+        if (this.map === null)
+            return;
+        if (prevHandleId !== null) {
+            this.applyShapeInteractionPaint(prevHandleId);
+        }
+        if (handleId !== null && handleId !== prevHandleId) {
+            this.applyShapeInteractionPaint(handleId);
+        }
+    }
+    applyShapeHoverState(handleId, featureId) {
+        if (this.hoveredShapeHandleId === handleId && this.hoveredShapeFeatureId === featureId)
+            return;
+        const prevHandleId = this.hoveredShapeHandleId;
+        this.hoveredShapeHandleId = handleId;
+        this.hoveredShapeFeatureId = featureId;
+        if (this.map === null)
+            return;
+        if (prevHandleId !== null) {
+            this.applyShapeInteractionPaint(prevHandleId);
+        }
+        if (handleId !== null && handleId !== prevHandleId) {
+            this.applyShapeInteractionPaint(handleId);
+        }
+    }
+    // ---- Route sources ----
+    syncRouteSource(config) {
+        if (this.map === null)
+            return;
+        // Skip full rebuild if config is unchanged (new object reference, same values)
+        const existing = this.routeSources.get(config.id);
+        if (existing !== undefined && esToolkit.isEqual(existing.config, config)) {
+            return;
+        }
+        // Remove existing route for this source (update case)
+        this.removeRouteSourceInternal(config.id);
+        const currentMap = this.map;
+        const sourceId = `route-source-${config.id}`;
+        const lineLayerId = `route-line-${config.id}`;
+        const layerIds = [];
+        // Add GeoJSON source (convert readonly types to mutable for Mapbox)
+        currentMap.addSource(sourceId, {
+            type: "geojson",
+            data: toMapboxGeoJson(config.features),
+        });
+        // Build dash array if needed
+        const { dashArray } = config.style;
+        const hasDash = dashArray !== undefined && dashArray.length > 0;
+        this.addLayerWithFadeIn(currentMap, {
+            id: lineLayerId,
+            type: "line",
+            source: sourceId,
+            filter: ["==", ["geometry-type"], "LineString"],
+            layout: {
+                "line-cap": hasDash ? "butt" : "round",
+                "line-join": "round",
+            },
+            paint: {
+                "line-color": config.style.color ?? "#000000",
+                "line-width": config.style.width ?? 3,
+                "line-opacity": config.style.opacity ?? 1,
+                ...(hasDash ? { "line-dasharray": [...dashArray] } : {}),
+            },
+        });
+        layerIds.push(lineLayerId);
+        if (config.style.showDirectionArrows === true) {
+            const arrowLayerId = `route-arrows-${config.id}`;
+            this.ensureArrowImage(currentMap);
+            this.addLayerWithFadeIn(currentMap, {
+                id: arrowLayerId,
+                type: "symbol",
+                source: sourceId,
+                filter: ["==", ["geometry-type"], "LineString"],
+                layout: {
+                    "symbol-placement": "line",
+                    "symbol-spacing": 100,
+                    "icon-image": "route-arrow",
+                    "icon-size": 0.6,
+                    "icon-rotation-alignment": "map",
+                    "icon-allow-overlap": true,
+                    "icon-ignore-placement": true,
+                },
+            });
+            layerIds.push(arrowLayerId);
+        }
+        if (config.interactive) {
+            this.attachRouteLayerInteractionListeners(currentMap, layerIds, config.id);
+        }
+        this.routeSources.set(config.id, { sourceId, layerIds, config });
+    }
+    removeRouteSourceInternal(id) {
+        const tracked = this.routeSources.get(id);
+        if (tracked === undefined)
+            return;
+        if (this.map !== null) {
+            this.detachRouteLayerInteractionListeners(this.map, tracked.layerIds);
+            safeRemoveLayersAndSource(this.map, tracked.layerIds, tracked.sourceId);
+        }
+        this.routeSources.delete(id);
+    }
+    // ---- Image overlays ----
+    syncImageOverlay(config) {
+        if (this.map === null)
+            return;
+        // Skip full rebuild if config is unchanged (new object reference, same values)
+        const existing = this.overlaySources.get(config.id);
+        if (existing !== undefined && esToolkit.isEqual(existing.config, config)) {
+            return;
+        }
+        // Remove existing overlay for this source (update case)
+        this.removeImageOverlayInternal(config.id);
+        const currentMap = this.map;
+        const sourceId = `image-source-${config.id}`;
+        const layerId = `image-layer-${config.id}`;
+        currentMap.addSource(sourceId, {
+            type: "image",
+            url: config.url,
+            coordinates: bboxToImageCoordinates(config.imageBounds),
+        });
+        this.addLayerWithFadeIn(currentMap, {
+            id: layerId,
+            type: "raster",
+            source: sourceId,
+            paint: {
+                "raster-opacity": config.opacity,
+                "raster-fade-duration": 0,
+            },
+        });
+        this.overlaySources.set(config.id, { sourceId, layerId, config });
+    }
+    removeImageOverlayInternal(id) {
+        const tracked = this.overlaySources.get(id);
+        if (tracked === undefined)
+            return;
+        if (this.map !== null) {
+            safeRemoveLayersAndSource(this.map, [tracked.layerId], tracked.sourceId);
+        }
+        this.overlaySources.delete(id);
+    }
+    // ============================================================================
+    // Private: Layer fade-in
+    // ============================================================================
+    /**
+     * Wrapper around `map.addLayer` that starts the layer at opacity 0 and
+     * animates to the target opacity via Mapbox's native paint transition system.
+     * Layer types without a known opacity key (e.g. `symbol`) are added normally.
+     */
+    addLayerWithFadeIn(map, spec) {
+        const fade = { duration: reactMapAdapterShared.LAYER_FADE_DURATION_MS, delay: 0 };
+        switch (spec.type) {
+            case "fill": {
+                const target = spec.paint?.["fill-opacity"] ?? 1;
+                map.addLayer({ ...spec, paint: { ...spec.paint, "fill-opacity": 0, "fill-opacity-transition": fade } });
+                map.setPaintProperty(spec.id, "fill-opacity", target);
+                return;
+            }
+            case "line": {
+                const target = spec.paint?.["line-opacity"] ?? 1;
+                map.addLayer({ ...spec, paint: { ...spec.paint, "line-opacity": 0, "line-opacity-transition": fade } });
+                map.setPaintProperty(spec.id, "line-opacity", target);
+                return;
+            }
+            case "circle": {
+                const target = spec.paint?.["circle-opacity"] ?? 1;
+                const strokeTarget = spec.paint?.["circle-stroke-opacity"] ?? 1;
+                map.addLayer({
+                    ...spec,
+                    paint: {
+                        ...spec.paint,
+                        "circle-opacity": 0,
+                        "circle-opacity-transition": fade,
+                        "circle-stroke-opacity": 0,
+                        "circle-stroke-opacity-transition": fade,
+                    },
+                });
+                map.setPaintProperty(spec.id, "circle-opacity", target);
+                map.setPaintProperty(spec.id, "circle-stroke-opacity", strokeTarget);
+                return;
+            }
+            case "raster": {
+                const target = spec.paint?.["raster-opacity"] ?? 1;
+                map.addLayer({ ...spec, paint: { ...spec.paint, "raster-opacity": 0, "raster-opacity-transition": fade } });
+                map.setPaintProperty(spec.id, "raster-opacity", target);
+                return;
+            }
+            default:
+                map.addLayer(spec);
+        }
+    }
+    // ============================================================================
+    // Private: Pending source flushing
+    // ============================================================================
+    /**
+     * Process all queued source configurations that arrived before the style
+     * was ready. Idempotent -- clears each queue after processing.
+     */
+    applySnapshot(snapshot) {
+        const markerIds = new Set(snapshot.layers.filter(l => l.layerType === "markers").map(l => l.id));
+        const shapeIds = new Set(snapshot.layers.filter(l => l.layerType === "shapes").map(l => l.id));
+        const routeIds = new Set(snapshot.layers.filter(l => l.layerType === "route").map(l => l.id));
+        const overlayIds = new Set(snapshot.layers.filter(l => l.layerType === "image-overlay").map(l => l.id));
+        for (const layer of snapshot.layers) {
+            switch (layer.layerType) {
+                case "markers":
+                    this.syncMarkerSource(layer);
+                    break;
+                case "shapes":
+                    this.syncShapeSource(layer);
+                    break;
+                case "route":
+                    this.syncRouteSource(layer);
+                    break;
+                case "image-overlay":
+                    this.syncImageOverlay(layer);
+                    break;
+                default: {
+                    const exhaustiveCheck = layer;
+                    throw new Error(`Unknown layer type: ${String(exhaustiveCheck)}`);
+                }
+            }
+        }
+        for (const id of [...this.markerSources.keys()]) {
+            if (!markerIds.has(id))
+                this.removeMarkerSourceInternal(id);
+        }
+        for (const id of [...this.shapeSources.keys()]) {
+            if (!shapeIds.has(id))
+                this.removeShapeSourceInternal(id);
+        }
+        for (const id of [...this.routeSources.keys()]) {
+            if (!routeIds.has(id))
+                this.removeRouteSourceInternal(id);
+        }
+        for (const id of [...this.overlaySources.keys()]) {
+            if (!overlayIds.has(id))
+                this.removeImageOverlayInternal(id);
+        }
+        this.applyShapeSelectionState(snapshot.shapeSelection.handleId, snapshot.shapeSelection.featureId);
+        this.applyShapeHoverState(snapshot.shapeHover.handleId, snapshot.shapeHover.featureId);
+    }
+    flushPending() {
+        if (this.pendingSnapshot !== null) {
+            this.applySnapshot(this.pendingSnapshot);
+            this.pendingSnapshot = null;
+            return;
+        }
+        // Revival path: useLayerHandleSync's cleanup pushed EMPTY before destroy (React 18 StrictMode
+        // dev replay), and useWatch's persisted prev value won't re-fire on remount. Re-apply the
+        // last non-empty snapshot so markers/shapes return after the adapter is connected to a fresh map.
+        if (this.lastNonEmptySnapshot !== null) {
+            this.applySnapshot(this.lastNonEmptySnapshot);
+        }
+    }
+    // ============================================================================
+    // Private: DOM portal management
+    // ============================================================================
+    /** Add a portal descriptor to the marker store and notify subscribers */
+    addMarkerPortalDescriptor(descriptor) {
+        this.markerPortalDescriptors = [...this.markerPortalDescriptors, descriptor];
+        this.notifyMarkerPortalSubscribers();
+    }
+    /** Add a portal descriptor to the cluster store and notify subscribers */
+    addClusterPortalDescriptor(descriptor) {
+        this.clusterPortalDescriptors = [...this.clusterPortalDescriptors, descriptor];
+        this.notifyClusterPortalSubscribers();
+    }
+    /** Remove all portal descriptors for `sourceId` from both stores and notify */
+    removePortalDescriptorsForSource(sourceId) {
+        const prefix = `${sourceId}:`;
+        const filteredMarker = this.markerPortalDescriptors.filter(d => !d.key.startsWith(prefix));
+        if (filteredMarker.length !== this.markerPortalDescriptors.length) {
+            this.markerPortalDescriptors = filteredMarker;
+            this.notifyMarkerPortalSubscribers();
+        }
+        const filteredCluster = this.clusterPortalDescriptors.filter(d => !d.key.startsWith(prefix));
+        if (filteredCluster.length !== this.clusterPortalDescriptors.length) {
+            this.clusterPortalDescriptors = filteredCluster;
+            this.notifyClusterPortalSubscribers();
+        }
+    }
+    notifyMarkerPortalSubscribers() {
+        for (const callback of this.markerPortalSubscribers) {
+            callback();
+        }
+    }
+    notifyClusterPortalSubscribers() {
+        for (const callback of this.clusterPortalSubscribers) {
+            callback();
+        }
+    }
+    /**
+     * Patch existing DOM markers in place: update positions via `setLngLat` and
+     * refresh portal descriptors so React re-renders with the latest render function.
+     * Avoids the remove-then-add cycle that causes a brief flash at (0,0).
+     */
+    patchDomMarkers(existing, config) {
+        const oldFeatures = existing.config.features.features;
+        const newFeatures = config.features.features;
+        for (let i = 0; i < Math.min(existing.markers.length, newFeatures.length); i++) {
+            const oldFeature = oldFeatures[i];
+            const newFeature = newFeatures[i];
+            const marker = existing.markers[i];
+            if (newFeature === undefined || marker === undefined)
+                continue;
+            const oldCoords = oldFeature !== undefined ? reactMapAdapterShared.extractPointCoordinates(oldFeature) : null;
+            const newCoords = reactMapAdapterShared.extractPointCoordinates(newFeature);
+            if (newCoords !== null &&
+                (oldCoords === null || oldCoords.lng !== newCoords.lng || oldCoords.lat !== newCoords.lat)) {
+                marker.setLngLat(newCoords);
+            }
+        }
+        if (config.markerRender.mode === "dom") {
+            const result = reactMapAdapterShared.patchPortalDescriptors(this.markerPortalDescriptors, config.id, newFeatures, config.markerRender.render);
+            if (result.changed) {
+                this.markerPortalDescriptors = result.descriptors;
+                this.notifyMarkerPortalSubscribers();
+            }
+        }
+    }
+    /**
+     * Incrementally update adaptive DOM markers and the WebGL circle source
+     * when `adaptiveResolution` (or callbacks) changed but feature IDs are the same.
+     *
+     * Three phases:
+     * 1. DOM → symbol: remove DOM marker + portal for features leaving DOM mode.
+     * 2. Symbol → DOM: add new DOM marker + portal for features entering DOM mode.
+     * 3. DOM → DOM: update portal renderFn (so the consumer's latest closure runs).
+     * 4. Update WebGL circle source to reflect the new DOM/symbol split.
+     */
+    patchAdaptiveMarkers(existing, config) {
+        if (this.map === null)
+            return;
+        const { markerRender } = config;
+        if (markerRender.mode !== "adaptive" || config.kind !== "marker")
+            return;
+        const existingDomIds = reactMapAdapterShared.getAdaptiveDomFeatureIds(existing.config);
+        const incomingDomIds = reactMapAdapterShared.getAdaptiveDomFeatureIds(config);
+        const incomingResolution = config.adaptiveResolution;
+        const adaptiveDomMarkers = this.adaptiveMarkerIndex.get(config.id) ?? new Map();
+        // ---- Phase 1: DOM → symbol — remove DOM marker + portal ----
+        for (const featureId of existingDomIds) {
+            if (incomingDomIds.has(featureId))
+                continue;
+            const marker = adaptiveDomMarkers.get(featureId);
+            if (marker !== undefined) {
+                marker.remove();
+                adaptiveDomMarkers.delete(featureId);
+                existing.markers = existing.markers.filter(m => m !== marker);
+            }
+            const key = `${config.id}:${featureId}`;
+            const filtered = this.markerPortalDescriptors.filter(d => d.key !== key);
+            if (filtered.length !== this.markerPortalDescriptors.length) {
+                this.markerPortalDescriptors = filtered;
+                this.notifyMarkerPortalSubscribers();
+            }
+        }
+        // ---- Phase 2: Symbol → DOM — add DOM marker + portal ----
+        const phase2DomCreated = new Set();
+        for (const feature of config.features.features) {
+            if (feature.id === undefined)
+                continue;
+            const featureId = String(feature.id);
+            if (!incomingDomIds.has(featureId) || existingDomIds.has(featureId))
+                continue;
+            if (featureId !== "" && phase2DomCreated.has(featureId))
+                continue;
+            const mode = incomingResolution?.modesByFeatureId.get(featureId) ?? "symbol";
+            if (mode !== "dom")
+                continue;
+            const coords = reactMapAdapterShared.extractPointCoordinates(feature);
+            if (coords === null)
+                continue;
+            const renderFn = reactMapAdapterShared.buildAdaptiveDomRenderFn(markerRender.render);
+            const data = reactMapAdapterShared.extractSourceData(feature.properties);
+            const domMarker = this.createDomMarker(featureId, coords, config.id, data, renderFn, this.map, "marker", markerRender.anchor, markerRender.pixelOffset);
+            existing.markers.push(domMarker);
+            adaptiveDomMarkers.set(featureId, domMarker);
+            if (featureId !== "")
+                phase2DomCreated.add(featureId);
+            this.attachMarkerInteractionListeners(domMarker, featureId, coords);
+        }
+        // ---- Phase 3: DOM → DOM — update portal renderFn + position ----
+        let portalsChanged = false;
+        const updatedPortals = Array.from(this.markerPortalDescriptors);
+        for (const feature of config.features.features) {
+            if (feature.id === undefined)
+                continue;
+            const featureId = String(feature.id);
+            if (!incomingDomIds.has(featureId) || !existingDomIds.has(featureId))
+                continue;
+            const mode = incomingResolution?.modesByFeatureId.get(featureId) ?? "symbol";
+            if (mode !== "dom")
+                continue;
+            // Update position if coordinates changed
+            const marker = adaptiveDomMarkers.get(featureId);
+            if (marker !== undefined) {
+                const coords = reactMapAdapterShared.extractPointCoordinates(feature);
+                if (coords !== null) {
+                    const oldFeature = existing.config.features.features.find(f => f.id !== undefined && String(f.id) === featureId);
+                    const oldCoords = oldFeature !== undefined ? reactMapAdapterShared.extractPointCoordinates(oldFeature) : null;
+                    if (oldCoords === null || oldCoords.lng !== coords.lng || oldCoords.lat !== coords.lat) {
+                        marker.setLngLat(coords);
+                    }
+                }
+            }
+            const renderFn = reactMapAdapterShared.buildAdaptiveDomRenderFn(markerRender.render);
+            const key = `${config.id}:${featureId}`;
+            const idx = updatedPortals.findIndex(d => d.key === key);
+            if (idx !== -1) {
+                const desc = updatedPortals[idx];
+                if (desc !== undefined) {
+                    updatedPortals[idx] = { ...desc, renderFn, sourceData: reactMapAdapterShared.extractSourceData(feature.properties) };
+                    portalsChanged = true;
+                }
+            }
+        }
+        if (portalsChanged) {
+            this.markerPortalDescriptors = updatedPortals;
+            this.notifyMarkerPortalSubscribers();
+        }
+        this.adaptiveMarkerIndex.set(config.id, adaptiveDomMarkers);
+        // ---- Phase 4: Update WebGL circle source ----
+        this.updateAdaptiveCircleSource(config, existing);
+    }
+    /**
+     * Incrementally sync adaptive markers and server-side clusters when a viewport
+     * refetch changes which feature IDs are visible, without tearing down unchanged DOM markers.
+     */
+    patchAdaptiveViewportData(existing, config) {
+        if (this.map === null)
+            return;
+        if (config.markerRender.mode !== "adaptive" || config.kind !== "marker")
+            return;
+        this.removeGoneAdaptiveAssetMarkers(existing, config);
+        this.removeGoneServerClusterMarkers(existing, config);
+        this.patchAdaptiveMarkers(existing, config);
+        this.syncServerClusterMarkers(existing, config);
+        this.updateAdaptiveCircleSource(config, existing);
+    }
+    /**
+     * Remove adaptive DOM markers whose feature IDs are no longer in the incoming config.
+     */
+    removeGoneAdaptiveAssetMarkers(existing, config) {
+        const incomingIds = reactMapAdapterShared.collectFeatureIdSet(config.features);
+        const adaptiveDomMarkers = this.adaptiveMarkerIndex.get(config.id) ?? new Map();
+        const result = reactMapAdapterShared.removeGoneIndexedMarkers({
+            incomingFeatureIds: incomingIds,
+            markerIndex: adaptiveDomMarkers,
+            markers: existing.markers,
+            portalDescriptors: this.markerPortalDescriptors,
+            sourceId: config.id,
+            detachMarker: marker => {
+                marker.remove();
+                this.clusterEntitiesByMarker.delete(marker);
+            },
+        });
+        existing.markers = result.markers;
+        if (result.portalDescriptorsChanged) {
+            this.markerPortalDescriptors = result.portalDescriptors;
+            this.notifyMarkerPortalSubscribers();
+        }
+        this.adaptiveMarkerIndex.set(config.id, result.markerIndex);
+    }
+    /**
+     * Remove server-side cluster markers whose feature IDs are no longer in the incoming config.
+     */
+    removeGoneServerClusterMarkers(existing, config) {
+        if (config.kind !== "marker")
+            return;
+        const incomingIds = reactMapAdapterShared.collectFeatureIdSet(config.clusterFeatures);
+        const clusterIndex = this.clusterMarkerIndex.get(config.id) ?? new Map();
+        const result = reactMapAdapterShared.removeGoneIndexedMarkers({
+            incomingFeatureIds: incomingIds,
+            markerIndex: clusterIndex,
+            markers: existing.markers,
+            portalDescriptors: this.clusterPortalDescriptors,
+            sourceId: config.id,
+            detachMarker: marker => {
+                marker.remove();
+                this.clusterEntitiesByMarker.delete(marker);
+            },
+        });
+        existing.markers = result.markers;
+        if (result.portalDescriptorsChanged) {
+            this.clusterPortalDescriptors = result.portalDescriptors;
+            this.notifyClusterPortalSubscribers();
+        }
+        this.clusterMarkerIndex.set(config.id, result.markerIndex);
+    }
+    /**
+     * Add new server-side cluster markers for feature IDs not yet tracked,
+     * and update existing ones with fresh portal data.
+     */
+    syncServerClusterMarkers(existing, config) {
+        if (this.map === null || config.kind !== "marker" || config.clusterFeatures === null)
+            return;
+        const currentMap = this.map;
+        const clusterIndex = this.clusterMarkerIndex.get(config.id) ?? new Map();
+        for (const feature of config.clusterFeatures.features) {
+            const coords = reactMapAdapterShared.extractPointCoordinates(feature);
+            if (coords === null)
+                continue;
+            const featureId = feature.id !== undefined ? String(feature.id) : undefined;
+            if (featureId === undefined)
+                continue;
+            const props = feature.properties;
+            const rawMarkerIds = props !== null ? props.markerIds : undefined;
+            const markerIds = Array.isArray(rawMarkerIds) ? rawMarkerIds : [];
+            const clusterBbox = props !== null && props.bbox !== null ? geoJsonUtils.validateBbox(props.bbox) : null;
+            const existingMarker = clusterIndex.get(featureId);
+            if (existingMarker !== undefined) {
+                // Update position if moved
+                const currentPos = existingMarker.getLngLat();
+                if (currentPos.lng !== coords.lng || currentPos.lat !== coords.lat) {
+                    existingMarker.setLngLat(coords);
+                }
+                this.updateClusterMarkerEntity(existingMarker, featureId, coords, markerIds, clusterBbox);
+                // Update portal descriptor if this cluster uses DOM render
+                if (config.clusterRender !== null && config.clusterRender.mode === "dom") {
+                    const key = `${config.id}:${featureId}`;
+                    const idx = this.clusterPortalDescriptors.findIndex(d => d.key === key);
+                    if (idx !== -1) {
+                        const desc = this.clusterPortalDescriptors[idx];
+                        if (desc !== undefined) {
+                            const updated = [...this.clusterPortalDescriptors];
+                            updated[idx] = {
+                                ...desc,
+                                renderFn: config.clusterRender.render,
+                                sourceData: reactMapAdapterShared.extractSourceData(feature.properties),
+                            };
+                            this.clusterPortalDescriptors = updated;
+                            this.notifyClusterPortalSubscribers();
+                        }
+                    }
+                }
+                continue;
+            }
+            // New cluster — create and register
+            const marker = this.createClusterMarkerForFeature(feature, coords, config, currentMap);
+            existing.markers.push(marker);
+            clusterIndex.set(featureId, marker);
+            this.attachClusterInteractionListeners(marker, featureId, coords, markerIds, clusterBbox);
+        }
+        this.clusterMarkerIndex.set(config.id, clusterIndex);
+    }
+    /**
+     * Update the Mapbox GeoJSON circle source for an adaptive marker layer,
+     * excluding features that are currently rendered as DOM markers.
+     */
+    updateAdaptiveCircleSource(config, tracked) {
+        if (this.map === null || tracked.sourceId === undefined)
+            return;
+        const { markerRender } = config;
+        if (markerRender.mode !== "adaptive")
+            return;
+        const source = this.map.getSource(tracked.sourceId);
+        if (source === undefined || !("setData" in source))
+            return;
+        const promotedIds = reactMapAdapterShared.getAdaptiveDomFeatureIds(config);
+        const symbolState = {
+            medium: "symbol",
+            selected: false,
+            hovered: false,
+            theme: this.theme,
+        };
+        const styleFn = reactMapAdapterShared.buildAdaptiveSymbolStyleFn(markerRender.render, symbolState);
+        const enrichedFeatures = [];
+        for (const feature of config.features.features) {
+            const coords = reactMapAdapterShared.extractPointCoordinates(feature);
+            if (coords === null)
+                continue;
+            const featureId = feature.id !== undefined ? String(feature.id) : undefined;
+            if (featureId !== undefined && promotedIds.has(featureId))
+                continue;
+            const resolved = reactMapAdapterShared.resolveCircleSymbolDefaults(reactMapAdapterShared.resolveSymbolDescriptor(styleFn, feature.properties));
+            enrichedFeatures.push({
+                type: "Feature",
+                id: feature.id !== undefined ? Number(feature.id) || undefined : undefined,
+                geometry: { type: "Point", coordinates: [coords.lng, coords.lat] },
+                properties: {
+                    __featureId: featureId ?? "",
+                    __color: resolved.color,
+                    __radius: resolved.radiusPx,
+                    __opacity: resolved.opacity,
+                    __strokeColor: resolved.borderColor ?? "#000000",
+                    __strokeWidth: resolved.hasBorder ? resolved.borderWidthPx : 0,
+                },
+            });
+        }
+        source.setData({ type: "FeatureCollection", features: enrichedFeatures });
+    }
+    // ============================================================================
+    // Private: Marker creation
+    // ============================================================================
+    createMarkerForFeature(feature, coords, config, map) {
+        const { markerRender } = config;
+        const featureId = feature.id !== undefined ? String(feature.id) : "";
+        switch (markerRender.mode) {
+            case "symbol": {
+                const symbolState = {
+                    medium: "symbol",
+                    selected: false,
+                    hovered: false,
+                    theme: this.theme,
+                };
+                const resolved = reactMapAdapterShared.resolveCircleSymbolDefaults(reactMapAdapterShared.resolveSymbolDescriptor(item => markerRender.render(item, symbolState), feature.properties));
+                const el = reactMapAdapterShared.createSymbolDotElement(resolved);
+                return new mapboxgl.Marker({ element: el }).setLngLat(coords).addTo(map);
+            }
+            case "dom": {
+                return this.createDomMarker(featureId, coords, config.id, reactMapAdapterShared.extractSourceData(feature.properties), markerRender.render, map, "marker", markerRender.anchor, markerRender.pixelOffset);
+            }
+            case "adaptive": {
+                const symbolState = {
+                    medium: "symbol",
+                    selected: false,
+                    hovered: false,
+                    theme: this.theme,
+                };
+                const styleFn = reactMapAdapterShared.buildAdaptiveSymbolStyleFn(markerRender.render, symbolState);
+                const resolved = reactMapAdapterShared.resolveCircleSymbolDefaults(reactMapAdapterShared.resolveSymbolDescriptor(styleFn, feature.properties));
+                const el = reactMapAdapterShared.createSymbolDotElement(resolved);
+                return new mapboxgl.Marker({ element: el }).setLngLat(coords).addTo(map);
+            }
+            default: {
+                throw new Error(`${markerRender} is not known`);
+            }
+        }
+    }
+    createClusterMarkerForFeature(feature, coords, config, map) {
+        const { clusterRender } = config;
+        const featureId = feature.id !== undefined ? String(feature.id) : "";
+        const clusterCount = feature.properties !== null ? feature.properties.count : undefined;
+        if (clusterRender === null) {
+            const el = reactMapAdapterShared.createDefaultClusterElement(clusterCount);
+            return new mapboxgl.Marker({ element: el }).setLngLat(coords).addTo(map);
+        }
+        switch (clusterRender.mode) {
+            case "symbol": {
+                const clusterState = {
+                    selected: false,
+                    hovered: false,
+                    theme: this.theme,
+                    memberItems: null,
+                };
+                const descriptor = reactMapAdapterShared.resolveSymbolDescriptor(item => clusterRender.render(item, clusterState), feature.properties);
+                const el = reactMapAdapterShared.createClusterPinElement(descriptor, clusterCount);
+                return new mapboxgl.Marker({ element: el }).setLngLat(coords).addTo(map);
+            }
+            case "dom": {
+                return this.createDomMarker(featureId, coords, config.id, reactMapAdapterShared.extractSourceData(feature.properties), clusterRender.render, map, "cluster", clusterRender.anchor, clusterRender.pixelOffset);
+            }
+            default: {
+                throw new Error(`${clusterRender} is not known`);
+            }
+        }
+    }
+    /**
+     * Create a mapboxgl.Marker with an empty div as content.
+     * Registers a portal descriptor in the target store (`marker` or `cluster`)
+     * so `<Layers>` renders React content into the container via
+     * `createPortal()` and routes to the matching render config.
+     */
+    createDomMarker(featureId, coords, sourceId, sourceData, renderFn, map, target, anchor, pixelOffset) {
+        const container = document.createElement("div");
+        container.style.pointerEvents = "auto";
+        reactMapAdapterShared.fadeInElement(container);
+        const marker = new mapboxgl.Marker({
+            element: container,
+            anchor,
+            ...(pixelOffset !== undefined ? { offset: [pixelOffset.x, pixelOffset.y] } : {}),
+        })
+            .setLngLat(coords)
+            .addTo(map);
+        const descriptor = {
+            key: `${sourceId}:${featureId}`,
+            sourceId,
+            container,
+            featureId,
+            sourceData,
+            renderFn,
+        };
+        if (target === "marker") {
+            this.addMarkerPortalDescriptor(descriptor);
+        }
+        else {
+            this.addClusterPortalDescriptor(descriptor);
+        }
+        return marker;
+    }
+    /**
+     * Adaptive mode: DOM overlays for features whose resolved mode is not `"symbol"`.
+     */
+    createAdaptiveDomOverlays(config, map, tracked) {
+        const adaptiveDomMarkers = new Map();
+        const { markerRender } = config;
+        if (markerRender.mode !== "adaptive")
+            return;
+        const adaptiveAnchor = markerRender.anchor;
+        const adaptivePixelOffset = markerRender.pixelOffset;
+        for (const { featureId, coords, domMarker } of reactMapAdapterShared.buildAdaptiveDomEntries(config, (fId, c, sourceId, data, renderFn) => this.createDomMarker(fId, c, sourceId, data, renderFn, map, "marker", adaptiveAnchor, adaptivePixelOffset))) {
+            tracked.markers.push(domMarker);
+            adaptiveDomMarkers.set(featureId, domMarker);
+            if (featureId !== "") {
+                this.attachMarkerInteractionListeners(domMarker, featureId, coords);
+            }
+        }
+        this.adaptiveMarkerIndex.set(config.id, adaptiveDomMarkers);
+    }
+    // ============================================================================
+    // Private: Client-side clustering
+    // ============================================================================
+    /**
+     * Set up client-side clustering using supercluster.
+     * Creates mapboxgl.Marker instances and manages their visibility
+     * based on zoom level and viewport.
+     */
+    setupClientClustering(config, map, tracked) {
+        const { clusterConfig } = config;
+        if (clusterConfig === null || clusterConfig.mode !== "client")
+            return;
+        // Build supercluster index from point features
+        const points = [];
+        for (const feature of config.features.features) {
+            const coords = reactMapAdapterShared.extractPointCoordinates(feature);
+            if (coords === null)
+                continue;
+            const featureId = feature.id !== undefined ? String(feature.id) : "";
+            points.push({
+                type: "Feature",
+                geometry: { type: "Point", coordinates: [coords.lng, coords.lat] },
+                properties: { featureId, originalFeature: feature },
+            });
+        }
+        const index = new Supercluster({
+            radius: clusterConfig.radius ?? 50,
+            maxZoom: clusterConfig.maxZoom ?? 14,
+        });
+        index.load(points);
+        tracked.supercluster = index;
+        tracked.clusterMarkers = [];
+        // Render clusters for the current viewport
+        const updateClusters = () => {
+            this.renderClusters(config, map, tracked);
+        };
+        // Listen for viewport changes
+        tracked.viewportListener = updateClusters;
+        map.on("moveend", updateClusters);
+        // Initial render
+        updateClusters();
+    }
+    /**
+     * Re-render cluster markers based on the current viewport.
+     * Called on initial setup and whenever the viewport changes.
+     */
+    renderClusters(config, map, tracked) {
+        const { supercluster, clusterMarkers } = tracked;
+        if (supercluster === undefined || clusterMarkers === undefined)
+            return;
+        // Remove existing cluster and individual markers
+        for (const marker of clusterMarkers) {
+            marker.remove();
+        }
+        for (const marker of tracked.markers) {
+            marker.remove();
+        }
+        tracked.clusterMarkers = [];
+        tracked.markers = [];
+        // Remove old portal descriptors for this source
+        this.removePortalDescriptorsForSource(config.id);
+        const zoom = Math.floor(map.getZoom());
+        const bounds = map.getBounds();
+        if (!bounds)
+            return;
+        const bbox = [
+            bounds.getWest(),
+            bounds.getSouth(),
+            bounds.getEast(),
+            bounds.getNorth(),
+        ];
+        const clusters = supercluster.getClusters(bbox, zoom);
+        for (const cluster of clusters) {
+            const clusterCoords = cluster.geometry.coordinates;
+            const lng = clusterCoords[0];
+            const lat = clusterCoords[1];
+            if (lng === undefined || lat === undefined)
+                continue;
+            const coords = { lng, lat };
+            const props = cluster.properties;
+            const isCluster = "cluster" in props && "cluster_id" in props && "point_count" in props;
+            if (isCluster) {
+                // This is a cluster point -- narrow via property presence checks
+                const numericClusterId = typeof props.cluster_id === "number" ? props.cluster_id : 0;
+                const numericCount = typeof props.point_count === "number" ? props.point_count : 0;
+                const leaves = supercluster.getLeaves(numericClusterId, Infinity);
+                const markerIds = leaves.map(leaf => leaf.properties.featureId);
+                const clusterMarker = this.createClusterMarkerForViewport(config, coords, numericCount, markerIds, String(numericClusterId), map);
+                tracked.clusterMarkers.push(clusterMarker);
+                // Cluster interaction
+                const entity = {
+                    type: "cluster",
+                    id: `cluster-${lat.toFixed(6)}-${lng.toFixed(6)}`,
+                    position: [lng, lat],
+                    markerIds,
+                    bbox: null,
+                };
+                const clusterEl = clusterMarker.getElement();
+                clusterEl.addEventListener("click", (e) => {
+                    // Mapbox fires a click for each of the two rapid clicks that precede a dblclick
+                    // (detail=1, then detail=2). Guard on detail >= 2 to suppress the spurious second
+                    // click so consumers don't see a toggle before the dblclick fires.
+                    // Google Maps adapter does not need this guard — it uses a separate DOM-level
+                    // dblclick listener on the map container and suppresses clicks via pointerdown,
+                    // so the double-click sequence never produces a stray click event.
+                    if (e.detail >= 2)
+                        return;
+                    this.emitEntityInteraction("click", entity);
+                });
+                clusterEl.addEventListener("dblclick", (e) => {
+                    e.stopPropagation();
+                    this.suppressNativeZoom();
+                    this.emitEntityInteraction("dblclick", entity);
+                });
+                clusterEl.addEventListener("mouseenter", () => {
+                    this.emitEntityInteraction("hover-start", entity);
+                });
+                clusterEl.addEventListener("mouseleave", () => {
+                    this.emitEntityInteraction("hover-end", entity);
+                });
+            }
+            else {
+                // This is an individual point
+                const { originalFeature, featureId } = cluster.properties;
+                const marker = this.createMarkerForFeature(originalFeature, coords, config, map);
+                tracked.markers.push(marker);
+                if (featureId !== "") {
+                    this.attachMarkerInteractionListeners(marker, featureId, coords);
+                }
+            }
+        }
+    }
+    /**
+     * Create a cluster marker for the current viewport (client-side clustering).
+     */
+    createClusterMarkerForViewport(config, coords, count, markerIds, clusterId, map) {
+        const { clusterRender } = config;
+        if (clusterRender !== null && clusterRender.mode === "symbol") {
+            const clusterState = {
+                selected: false,
+                hovered: false,
+                theme: this.theme,
+                memberItems: null,
+            };
+            const style = clusterRender.render({ id: clusterId, position: [coords.lng, coords.lat], markerIds, count, bbox: null }, clusterState);
+            const symbolEl = reactMapAdapterShared.createClusterPinElement(style, count);
+            return new mapboxgl.Marker({ element: symbolEl }).setLngLat(coords).addTo(map);
+        }
+        if (clusterRender !== null) {
+            // mode is "dom" by elimination (symbol handled above; ClusterRenderConfig
+            // has no other variants per ADR-0016).
+            const container = document.createElement("div");
+            container.style.pointerEvents = "auto";
+            const portalClusterId = `cluster-${coords.lat.toFixed(6)}-${coords.lng.toFixed(6)}`;
+            this.addClusterPortalDescriptor({
+                key: `${config.id}:${portalClusterId}`,
+                sourceId: config.id,
+                container,
+                featureId: portalClusterId,
+                sourceData: { id: portalClusterId, position: [coords.lng, coords.lat], markerIds, count, bbox: null },
+                renderFn: clusterRender.render,
+            });
+            return new mapboxgl.Marker({ element: container }).setLngLat(coords).addTo(map);
+        }
+        const defaultEl = reactMapAdapterShared.createDefaultClusterElement(count);
+        return new mapboxgl.Marker({ element: defaultEl }).setLngLat(coords).addTo(map);
+    }
+    // ============================================================================
+    // Private: Direction arrow image
+    // ============================================================================
+    /**
+     * Ensure the arrow icon image is registered on the map for route direction arrows.
+     * Uses a simple triangle rendered via canvas and converted to ImageData.
+     */
+    ensureArrowImage(map) {
+        if (this.arrowImageAdded)
+            return;
+        if (map.hasImage("route-arrow")) {
+            this.arrowImageAdded = true;
+            return;
+        }
+        // Create a simple arrow icon using canvas, then extract ImageData
+        const size = 16;
+        const canvas = document.createElement("canvas");
+        canvas.width = size;
+        canvas.height = size;
+        const ctx = canvas.getContext("2d");
+        if (ctx !== null) {
+            ctx.fillStyle = "#000000";
+            ctx.beginPath();
+            ctx.moveTo(size / 2, 0);
+            ctx.lineTo(size, size);
+            ctx.lineTo(size / 2, size * 0.7);
+            ctx.lineTo(0, size);
+            ctx.closePath();
+            ctx.fill();
+            const imageData = ctx.getImageData(0, 0, size, size);
+            map.addImage("route-arrow", imageData, { sdf: true });
+        }
+        this.arrowImageAdded = true;
+    }
+    // ============================================================================
+    // Private: Interaction listeners
+    // ============================================================================
+    attachMarkerInteractionListeners(marker, featureId, coords) {
+        const entity = {
+            type: "marker",
+            id: featureId,
+            position: [coords.lng, coords.lat],
+            clusterId: null,
+        };
+        const el = marker.getElement();
+        el.addEventListener("click", (e) => {
+            e.stopPropagation();
+            // The browser fires click twice before dblclick (detail=1, then detail=2).
+            // Suppress the second click so consumers don't see a spurious toggle.
+            if (e.detail >= 2)
+                return;
+            this.emitEntityInteraction("click", entity);
+        });
+        el.addEventListener("dblclick", (e) => {
+            e.stopPropagation();
+            this.suppressNativeZoom();
+            this.emitEntityInteraction("dblclick", entity);
+        });
+        // Hover — spurious-mouseleave-safe implementation via attachSafeAreaHoverListeners.
+        // See safeArea/ for the full contract.
+        reactMapAdapterShared.attachSafeAreaHoverListeners(el, () => this.emitEntityInteraction("hover-start", entity), () => this.emitEntityInteraction("hover-end", entity), this.markerHoverState);
+    }
+    attachClusterInteractionListeners(marker, featureId, coords, markerIds, clusterBbox) {
+        this.updateClusterMarkerEntity(marker, featureId, coords, markerIds, clusterBbox);
+        const emitClusterInteraction = (type) => {
+            const entity = this.clusterEntitiesByMarker.get(marker);
+            if (entity !== undefined) {
+                this.emitEntityInteraction(type, entity);
+            }
+        };
+        const el = marker.getElement();
+        el.addEventListener("click", (e) => {
+            e.stopPropagation();
+            if (e.detail >= 2)
+                return;
+            emitClusterInteraction("click");
+        });
+        el.addEventListener("dblclick", (e) => {
+            e.stopPropagation();
+            this.suppressNativeZoom();
+            emitClusterInteraction("dblclick");
+        });
+        el.addEventListener("mouseenter", () => {
+            emitClusterInteraction("hover-start");
+        });
+        el.addEventListener("mouseleave", () => {
+            emitClusterInteraction("hover-end");
+        });
+    }
+    updateClusterMarkerEntity(marker, featureId, coords, markerIds, clusterBbox) {
+        const entity = {
+            type: "cluster",
+            id: featureId,
+            position: [coords.lng, coords.lat],
+            markerIds,
+            bbox: clusterBbox,
+        };
+        this.clusterEntitiesByMarker.set(marker, entity);
+    }
+    // ---- Marker circle layer interaction ----
+    attachMarkerCircleLayerListeners(map, circleLayerId) {
+        const clickHandler = (e) => {
+            // Mapbox fires a click for each of the two rapid clicks that precede a dblclick.
+            // Guard on detail >= 2 to suppress the spurious second click so consumers don't
+            // see a toggle before the dblclick fires.
+            if (e.originalEvent.detail >= 2)
+                return;
+            const feature = e.features?.[0];
+            if (feature === undefined)
+                return;
+            const featureId = typeof feature.properties?.__featureId === "string" ? feature.properties.__featureId : undefined;
+            if (featureId === undefined || featureId === "")
+                return;
+            const coords = e.lngLat;
+            const entity = {
+                type: "marker",
+                id: featureId,
+                position: [coords.lng, coords.lat],
+                clusterId: null,
+            };
+            this.emitEntityInteraction("click", entity);
+        };
+        const dblClickHandler = (e) => {
+            this.suppressNativeZoom();
+            const feature = e.features?.[0];
+            if (feature === undefined)
+                return;
+            const featureId = typeof feature.properties?.__featureId === "string" ? feature.properties.__featureId : undefined;
+            if (featureId === undefined || featureId === "")
+                return;
+            const coords = e.lngLat;
+            const entity = {
+                type: "marker",
+                id: featureId,
+                position: [coords.lng, coords.lat],
+                clusterId: null,
+            };
+            this.emitEntityInteraction("dblclick", entity);
+        };
+        const mouseMoveHandler = (e) => {
+            const feature = e.features?.[0];
+            if (feature === undefined)
+                return;
+            const featureId = typeof feature.properties?.__featureId === "string" ? feature.properties.__featureId : undefined;
+            if (featureId === undefined || featureId === "")
+                return;
+            map.getCanvas().style.cursor = reactMapAdapterShared.MAP_CURSORS.interactive;
+            map.getCanvasContainer().style.cursor = reactMapAdapterShared.MAP_CURSORS.interactive;
+            if (this.lastHoveredMarkerFeatureId === featureId)
+                return;
+            // End hover on previous feature
+            if (this.lastHoveredMarkerFeatureId !== null) {
+                this.emitEntityInteraction("hover-end", {
+                    type: "marker",
+                    id: this.lastHoveredMarkerFeatureId,
+                    position: [e.lngLat.lng, e.lngLat.lat],
+                    clusterId: null,
+                });
+            }
+            this.lastHoveredMarkerFeatureId = featureId;
+            const coords = e.lngLat;
+            this.emitEntityInteraction("hover-start", {
+                type: "marker",
+                id: featureId,
+                position: [coords.lng, coords.lat],
+                clusterId: null,
+            });
+        };
+        const mouseLeaveHandler = () => {
+            map.getCanvas().style.cursor = reactMapAdapterShared.MAP_CURSORS.default;
+            map.getCanvasContainer().style.cursor = reactMapAdapterShared.MAP_CURSORS.default;
+            if (this.lastHoveredMarkerFeatureId !== null) {
+                this.emitEntityInteraction("hover-end", {
+                    type: "marker",
+                    id: this.lastHoveredMarkerFeatureId,
+                    position: [0, 0],
+                    clusterId: null,
+                });
+                this.lastHoveredMarkerFeatureId = null;
+            }
+        };
+        map.on("click", circleLayerId, clickHandler);
+        map.on("dblclick", circleLayerId, dblClickHandler);
+        map.on("mousemove", circleLayerId, mouseMoveHandler);
+        map.on("mouseleave", circleLayerId, mouseLeaveHandler);
+        this.markerClickHandlers.set(circleLayerId, clickHandler);
+        this.markerDblClickHandlers.set(circleLayerId, dblClickHandler);
+        this.markerMouseMoveHandlers.set(circleLayerId, mouseMoveHandler);
+        this.markerMouseLeaveHandlers.set(circleLayerId, mouseLeaveHandler);
+    }
+    detachMarkerCircleLayerListeners(map, layerIds) {
+        for (const layerId of layerIds) {
+            const clickHandler = this.markerClickHandlers.get(layerId);
+            if (clickHandler !== undefined) {
+                map.off("click", layerId, clickHandler);
+                this.markerClickHandlers.delete(layerId);
+            }
+            const dblClickHandler = this.markerDblClickHandlers.get(layerId);
+            if (dblClickHandler !== undefined) {
+                map.off("dblclick", layerId, dblClickHandler);
+                this.markerDblClickHandlers.delete(layerId);
+            }
+            const mouseMoveHandler = this.markerMouseMoveHandlers.get(layerId);
+            if (mouseMoveHandler !== undefined) {
+                map.off("mousemove", layerId, mouseMoveHandler);
+                this.markerMouseMoveHandlers.delete(layerId);
+            }
+            const mouseLeaveHandler = this.markerMouseLeaveHandlers.get(layerId);
+            if (mouseLeaveHandler !== undefined) {
+                map.off("mouseleave", layerId, mouseLeaveHandler);
+                this.markerMouseLeaveHandlers.delete(layerId);
+            }
+        }
+    }
+    // ---- Shape layer interaction ----
+    attachShapeLayerInteractionListeners(map, layerIds, handleId) {
+        for (const layerId of layerIds) {
+            const isFillLayer = layerId === `shape-fill-${handleId}`;
+            const clickHandler = (e) => {
+                const feature = e.features?.[0];
+                if (feature === undefined)
+                    return;
+                const featureId = typeof feature.properties?.__featureId === "string" ? feature.properties.__featureId : undefined;
+                if (featureId === undefined || featureId === "")
+                    return;
+                if (feature.geometry.type === "GeometryCollection")
+                    return;
+                if (isFillLayer && feature.properties?.__fillOpacity === 0)
+                    return;
+                const entity = {
+                    type: "shape",
+                    id: featureId,
+                    shapeType: reactMapAdapterShared.geometryTypeToShapeType(feature.geometry.type),
+                    handleId,
+                };
+                this.emitEntityInteraction("click", entity);
+            };
+            const dblClickHandler = (e) => {
+                this.suppressNativeZoom();
+                const feature = e.features?.[0];
+                if (feature === undefined)
+                    return;
+                const featureId = typeof feature.properties?.__featureId === "string" ? feature.properties.__featureId : undefined;
+                if (featureId === undefined || featureId === "")
+                    return;
+                if (feature.geometry.type === "GeometryCollection")
+                    return;
+                if (isFillLayer && feature.properties?.__fillOpacity === 0)
+                    return;
+                const entity = {
+                    type: "shape",
+                    id: featureId,
+                    shapeType: reactMapAdapterShared.geometryTypeToShapeType(feature.geometry.type),
+                    handleId,
+                };
+                this.emitEntityInteraction("dblclick", entity);
+            };
+            const mouseEnterHandler = (e) => {
+                const feature = e.features?.[0];
+                if (feature === undefined)
+                    return;
+                const featureId = typeof feature.properties?.__featureId === "string" ? feature.properties.__featureId : undefined;
+                if (featureId === undefined || featureId === "")
+                    return;
+                if (feature.geometry.type === "GeometryCollection")
+                    return;
+                if (isFillLayer && feature.properties?.__fillOpacity === 0)
+                    return;
+                const entity = {
+                    type: "shape",
+                    id: featureId,
+                    shapeType: reactMapAdapterShared.geometryTypeToShapeType(feature.geometry.type),
+                    handleId,
+                };
+                this.emitEntityInteraction("hover-start", entity);
+                map.getCanvas().style.cursor = reactMapAdapterShared.MAP_CURSORS.interactive;
+                map.getCanvasContainer().style.cursor = reactMapAdapterShared.MAP_CURSORS.interactive;
+            };
+            const mouseLeaveHandler = () => {
+                this.emitEntityInteraction("hover-end", { type: "shape", id: "", shapeType: "polygon", handleId });
+                map.getCanvas().style.cursor = reactMapAdapterShared.MAP_CURSORS.default;
+                map.getCanvasContainer().style.cursor = reactMapAdapterShared.MAP_CURSORS.default;
+            };
+            map.on("click", layerId, clickHandler);
+            map.on("dblclick", layerId, dblClickHandler);
+            map.on("mouseenter", layerId, mouseEnterHandler);
+            map.on("mouseleave", layerId, mouseLeaveHandler);
+            this.shapeClickHandlers.set(layerId, clickHandler);
+            this.shapeDblClickHandlers.set(layerId, dblClickHandler);
+            this.shapeMouseEnterHandlers.set(layerId, mouseEnterHandler);
+            this.shapeMouseLeaveHandlers.set(layerId, mouseLeaveHandler);
+        }
+    }
+    detachShapeLayerInteractionListeners(map, layerIds) {
+        for (const layerId of layerIds) {
+            const clickHandler = this.shapeClickHandlers.get(layerId);
+            if (clickHandler !== undefined) {
+                map.off("click", layerId, clickHandler);
+                this.shapeClickHandlers.delete(layerId);
+            }
+            const dblClickHandler = this.shapeDblClickHandlers.get(layerId);
+            if (dblClickHandler !== undefined) {
+                map.off("dblclick", layerId, dblClickHandler);
+                this.shapeDblClickHandlers.delete(layerId);
+            }
+            const mouseEnterHandler = this.shapeMouseEnterHandlers.get(layerId);
+            if (mouseEnterHandler !== undefined) {
+                map.off("mouseenter", layerId, mouseEnterHandler);
+                this.shapeMouseEnterHandlers.delete(layerId);
+            }
+            const mouseLeaveHandler = this.shapeMouseLeaveHandlers.get(layerId);
+            if (mouseLeaveHandler !== undefined) {
+                map.off("mouseleave", layerId, mouseLeaveHandler);
+                this.shapeMouseLeaveHandlers.delete(layerId);
+            }
+        }
+    }
+    // ---- Route layer interaction ----
+    attachRouteLayerInteractionListeners(map, layerIds, _handleId) {
+        for (const layerId of layerIds) {
+            const buildRouteEntity = (feature) => {
+                const featureId = feature.id !== undefined ? String(feature.id) : undefined;
+                if (featureId === undefined)
+                    return null;
+                const waypoints = feature.geometry.type === "LineString" ? feature.geometry.coordinates.map(c => [c[0] ?? 0, c[1] ?? 0]) : [];
+                return { type: "route", id: featureId, waypoints };
+            };
+            const clickHandler = (e) => {
+                const feature = e.features?.[0];
+                if (feature === undefined)
+                    return;
+                const entity = buildRouteEntity(feature);
+                if (entity !== null)
+                    this.emitEntityInteraction("click", entity);
+            };
+            const dblClickHandler = (e) => {
+                this.suppressNativeZoom();
+                const feature = e.features?.[0];
+                if (feature === undefined)
+                    return;
+                const entity = buildRouteEntity(feature);
+                if (entity !== null)
+                    this.emitEntityInteraction("dblclick", entity);
+            };
+            const mouseEnterHandler = () => {
+                map.getCanvas().style.cursor = reactMapAdapterShared.MAP_CURSORS.interactive;
+                map.getCanvasContainer().style.cursor = reactMapAdapterShared.MAP_CURSORS.interactive;
+            };
+            const mouseLeaveHandler = () => {
+                map.getCanvas().style.cursor = reactMapAdapterShared.MAP_CURSORS.default;
+                map.getCanvasContainer().style.cursor = reactMapAdapterShared.MAP_CURSORS.default;
+            };
+            map.on("click", layerId, clickHandler);
+            map.on("dblclick", layerId, dblClickHandler);
+            map.on("mouseenter", layerId, mouseEnterHandler);
+            map.on("mouseleave", layerId, mouseLeaveHandler);
+            this.routeClickHandlers.set(layerId, clickHandler);
+            this.routeDblClickHandlers.set(layerId, dblClickHandler);
+            this.routeMouseEnterHandlers.set(layerId, mouseEnterHandler);
+            this.routeMouseLeaveHandlers.set(layerId, mouseLeaveHandler);
+        }
+    }
+    detachRouteLayerInteractionListeners(map, layerIds) {
+        for (const layerId of layerIds) {
+            const clickHandler = this.routeClickHandlers.get(layerId);
+            if (clickHandler !== undefined) {
+                map.off("click", layerId, clickHandler);
+                this.routeClickHandlers.delete(layerId);
+            }
+            const dblClickHandler = this.routeDblClickHandlers.get(layerId);
+            if (dblClickHandler !== undefined) {
+                map.off("dblclick", layerId, dblClickHandler);
+                this.routeDblClickHandlers.delete(layerId);
+            }
+            const mouseEnterHandler = this.routeMouseEnterHandlers.get(layerId);
+            if (mouseEnterHandler !== undefined) {
+                map.off("mouseenter", layerId, mouseEnterHandler);
+                this.routeMouseEnterHandlers.delete(layerId);
+            }
+            const mouseLeaveHandler = this.routeMouseLeaveHandlers.get(layerId);
+            if (mouseLeaveHandler !== undefined) {
+                map.off("mouseleave", layerId, mouseLeaveHandler);
+                this.routeMouseLeaveHandlers.delete(layerId);
+            }
+        }
+    }
+    /**
+     * Temporarily disable the map's built-in double-click zoom so that our
+     * custom dblclick handler can call fitBounds without the native zoom
+     * overriding it. Re-enables on the next tick.
+     */
+    suppressNativeZoom() {
+        if (this.map === null)
+            return;
+        const m = this.map;
+        m.doubleClickZoom.disable();
+        setTimeout(() => {
+            m.doubleClickZoom.enable();
+        }, 0);
+    }
+    /** Emit entity interaction event to all subscribed handlers */
+    emitEntityInteraction(type, entity) {
+        if (type === "click") {
+            this.entityClickedInTick = true;
+            setTimeout(() => {
+                this.entityClickedInTick = false;
+            }, 0);
+        }
+        const event = { type, entity };
+        this.interactionHandlers.forEach(handler => handler(event));
+    }
+    // ============================================================================
+    // Private: Unified shape interaction paint
+    // ============================================================================
+    /**
+     * Sets all interaction-sensitive paint properties for a shape source,
+     * building nested `case` expressions with selected > hovered > base priority.
+     *
+     * Called whenever hover, selection, or theme changes on the given handleId.
+     * When neither hover nor selection is active, all properties revert to base.
+     */
+    applyShapeInteractionPaint(handleId) {
+        const tracked = this.shapeSources.get(handleId);
+        if (tracked === undefined || this.map === null)
+            return;
+        const { style, featureStyles: fs } = tracked.config;
+        const hasSelection = this.selectedShapeHandleId === handleId && this.selectedShapeFeatureId !== null;
+        const hasHover = this.hoveredShapeHandleId === handleId && this.hoveredShapeFeatureId !== null;
+        let selectedOverrides = null;
+        if (hasSelection && this.selectedShapeFeatureId !== null) {
+            const featureStyle = fs?.get(this.selectedShapeFeatureId) ?? style;
+            selectedOverrides = reactMapAdapterShared.resolveSelectedStyle(featureStyle, "polygon", this.theme);
+        }
+        let hoveredOverrides = null;
+        if (hasHover && this.hoveredShapeFeatureId !== null) {
+            const featureStyle = fs?.get(this.hoveredShapeFeatureId) ?? style;
+            hoveredOverrides = reactMapAdapterShared.resolveHoveredStyle(featureStyle, "polygon", this.theme);
+        }
+        /**
+         * Wraps a base paint value with case branches for the active interaction
+         * states. Selected is checked first (higher priority), then hovered.
+         * Returns the base paint unchanged when no interaction is active.
+         */
+        const withInteraction = (basePaint, selectedVal, hoveredVal, fallback) => {
+            const selId = hasSelection ? this.selectedShapeFeatureId : null;
+            const hovId = hasHover ? this.hoveredShapeFeatureId : null;
+            if (selId !== null && hovId !== null) {
+                return [
+                    "case",
+                    ["==", ["get", "__featureId"], selId],
+                    selectedVal ?? fallback,
+                    ["==", ["get", "__featureId"], hovId],
+                    hoveredVal ?? fallback,
+                    basePaint,
+                ];
+            }
+            if (selId !== null) {
+                return ["case", ["==", ["get", "__featureId"], selId], selectedVal ?? fallback, basePaint];
+            }
+            if (hovId !== null) {
+                return ["case", ["==", ["get", "__featureId"], hovId], hoveredVal ?? fallback, basePaint];
+            }
+            return basePaint;
+        };
+        const defaultFill = style.fill ?? "rgba(0,0,0,0.1)";
+        const defaultStroke = style.stroke ?? "#000000";
+        const defaultStrokeWidth = style.strokeWidth ?? 1;
+        const defaultStrokeOpacity = style.strokeOpacity ?? 1;
+        const defaultPolyFillOpacity = style.fillOpacity ?? this.shapeStyleDefaults.polygon.fillOpacity;
+        const defaultPointFillOpacity = style.fillOpacity ?? this.shapeStyleDefaults.point.fillOpacity;
+        const baseFill = shapePaint(fs, "__fill", defaultFill);
+        const baseStroke = shapePaint(fs, "__stroke", defaultStroke);
+        const baseStrokeWidth = shapePaint(fs, "__strokeWidth", defaultStrokeWidth);
+        const baseStrokeOpacity = shapePaint(fs, "__strokeOpacity", defaultStrokeOpacity);
+        const basePolyFillOpacity = shapePaint(fs, "__fillOpacity", defaultPolyFillOpacity);
+        const basePointFillOpacity = shapePaint(fs, "__fillOpacity", defaultPointFillOpacity);
+        const fillLayerId = `shape-fill-${handleId}`;
+        const lineLayerId = `shape-line-${handleId}`;
+        const circleLayerId = `shape-circle-${handleId}`;
+        this.map.setPaintProperty(fillLayerId, "fill-color", withInteraction(baseFill, selectedOverrides?.fill, hoveredOverrides?.fill, defaultFill));
+        this.map.setPaintProperty(fillLayerId, "fill-opacity", withInteraction(basePolyFillOpacity, selectedOverrides?.fillOpacity, hoveredOverrides?.fillOpacity, defaultPolyFillOpacity));
+        this.map.setPaintProperty(lineLayerId, "line-color", withInteraction(baseStroke, selectedOverrides?.stroke, hoveredOverrides?.stroke, defaultStroke));
+        this.map.setPaintProperty(lineLayerId, "line-width", withInteraction(baseStrokeWidth, selectedOverrides?.strokeWidth, hoveredOverrides?.strokeWidth, defaultStrokeWidth));
+        this.map.setPaintProperty(lineLayerId, "line-opacity", withInteraction(baseStrokeOpacity, selectedOverrides?.strokeOpacity, hoveredOverrides?.strokeOpacity, defaultStrokeOpacity));
+        this.map.setPaintProperty(circleLayerId, "circle-color", withInteraction(baseFill, selectedOverrides?.fill, hoveredOverrides?.fill, defaultFill));
+        this.map.setPaintProperty(circleLayerId, "circle-stroke-color", withInteraction(baseStroke, selectedOverrides?.stroke, hoveredOverrides?.stroke, defaultStroke));
+        this.map.setPaintProperty(circleLayerId, "circle-stroke-width", withInteraction(baseStrokeWidth, selectedOverrides?.strokeWidth, hoveredOverrides?.strokeWidth, defaultStrokeWidth));
+        this.map.setPaintProperty(circleLayerId, "circle-opacity", withInteraction(basePointFillOpacity, selectedOverrides?.fillOpacity, hoveredOverrides?.fillOpacity, defaultPointFillOpacity));
+    }
+    // ============================================================================
+    // Private: Style change reconnection
+    // ============================================================================
+    /**
+     * Called when the map style reloads (e.g. after setTheme / setMapType).
+     * mapboxgl.Marker objects persist across style changes (they are DOM overlays),
+     * but all GeoJSON sources and layers are removed by the style change.
+     * We need to re-add them.
+     */
+    onStyleLoad() {
+        const currentMap = this.map;
+        if (currentMap === null)
+            return;
+        // Reset arrow image flag -- style change removes custom images
+        this.arrowImageAdded = false;
+        // Snapshot all source maps before iterating. Mutating a Map during
+        // for...of iteration (delete + set with the same key) causes the
+        // iterator to revisit the re-added entry, creating an infinite loop.
+        const shapeEntries = Array.from(this.shapeSources.entries());
+        const routeEntries = Array.from(this.routeSources.entries());
+        const overlayEntries = Array.from(this.overlaySources.entries());
+        const markerEntriesToRestore = Array.from(this.markerSources.entries()).filter(([, tracked]) => tracked.sourceId !== undefined);
+        // Re-add shape sources/layers
+        for (const [id, { config }] of shapeEntries) {
+            this.shapeSources.delete(id);
+            this.syncShapeSource(config);
+        }
+        // Re-apply interaction paint after shape sources are restored
+        const interactionHandleIds = new Set();
+        if (this.selectedShapeHandleId !== null)
+            interactionHandleIds.add(this.selectedShapeHandleId);
+        if (this.hoveredShapeHandleId !== null)
+            interactionHandleIds.add(this.hoveredShapeHandleId);
+        for (const id of interactionHandleIds) {
+            this.applyShapeInteractionPaint(id);
+        }
+        // Re-add route sources/layers
+        for (const [id, { config }] of routeEntries) {
+            this.routeSources.delete(id);
+            this.syncRouteSource(config);
+        }
+        // Re-add image overlay sources/layers
+        for (const [id, { config }] of overlayEntries) {
+            this.overlaySources.delete(id);
+            this.syncImageOverlay(config);
+        }
+        // DOM markers (mapboxgl.Marker) persist across style changes, but
+        // WebGL circle layers/sources are removed. Re-add marker sources
+        // that used circle layers (from pre-snapshot).
+        for (const [id, { config }] of markerEntriesToRestore) {
+            this.markerSources.delete(id);
+            this.syncMarkerSource(config);
+        }
+    }
+}
+
+/**
+ * Zod schema for Mapbox LngLatLike (plain object)
+ * A plain object with lng and lat number properties
+ */
+const lngLatLiteralSchema = zod.z.object({
+    lng: zod.z.number(),
+    lat: zod.z.number(),
+});
+/**
+ * Zod schema for Mapbox LngLat class instance
+ * An object with lng and lat properties that are numbers
+ */
+const lngLatClassSchema = zod.z.object({
+    lng: zod.z.number(),
+    lat: zod.z.number(),
+});
+/**
+ * Convert GeoJSON Position [lng, lat] to Mapbox LngLatLike
+ */
+const positionToLngLat = (position) => ({
+    lng: position[0],
+    lat: position[1],
+});
+/**
+ * Convert Mapbox LngLat to GeoJSON Position [lng, lat]
+ * Uses Zod to validate and extract lng/lat values safely
+ */
+const lngLatToPosition = (lngLat) => {
+    const literalResult = lngLatLiteralSchema.safeParse(lngLat);
+    if (literalResult.success) {
+        // It's a LngLatLike - lng and lat are numbers
+        return [literalResult.data.lng, literalResult.data.lat];
+    }
+    const classResult = lngLatClassSchema.safeParse(lngLat);
+    if (classResult.success) {
+        // It's a LngLat class instance - lng and lat are properties
+        return [classResult.data.lng, classResult.data.lat];
+    }
+    // This should never happen if the input type is correct
+    throw new Error("Invalid LngLat value: expected either LngLatLike or LngLat class instance");
+};
+/**
+ * Convert GeoJSON Bbox [minLng, minLat, maxLng, maxLat] to Mapbox LngLatBoundsLike.
+ *
+ * When the bbox crosses the antimeridian (RFC 7946: minLng > maxLng), the northeast
+ * longitude is unwrapped by +360° so both corners are in a continuous longitude range
+ * (west longitude less than east). Mapbox GL `fitBounds` / initial `bounds` use `cameraForBounds`,
+ * which builds an AABB from NW/SE in Mercator space; raw corners like (170, 10) and
+ * (-170, -10) span almost the whole world in x, while (170, 10) and (190, 10) span the
+ * intended Pacific strip.
+ */
+const bboxToLngLatBounds = (bbox) => {
+    const [minLng, minLat, maxLng, maxLat] = bbox;
+    if (minLng > maxLng) {
+        return [
+            [minLng, minLat],
+            [maxLng + 360, maxLat],
+        ];
+    }
+    return [
+        [minLng, minLat],
+        [maxLng, maxLat],
+    ];
+};
+/**
+ * Convert Mapbox LngLatBounds to GeoJSON Bbox [minLng, minLat, maxLng, maxLat].
+ * Northeast longitudes above 180° (from unwrapped bounds) are converted back to [-180, 180].
+ */
+const lngLatBoundsToBbox = (bounds) => {
+    const sw = bounds.getSouthWest();
+    const ne = bounds.getNorthEast();
+    let east = ne.lng;
+    if (east > 180) {
+        east -= 360;
+    }
+    return [sw.lng, sw.lat, east, ne.lat];
+};
+
+const MAPBOX_TILE_SIZE = 512;
+/**
+ * Mapbox adapter instance implementation
+ * Manages the connection between our abstract interface and Mapbox GL API
+ */
+class MapboxAdapterInstance {
+    constructor(config) {
+        this.config = config;
+        this.map = null;
+        this.state = { ...reactMapAdapterShared.INITIAL_MAP_STATE, tileSize: MAPBOX_TILE_SIZE };
+        this.cachedCameraState = {
+            center: reactMapAdapterShared.INITIAL_MAP_STATE.center,
+            zoom: reactMapAdapterShared.INITIAL_MAP_STATE.zoom,
+            bounds: reactMapAdapterShared.INITIAL_MAP_STATE.bounds,
+            isIdle: reactMapAdapterShared.INITIAL_MAP_STATE.isIdle,
+        };
+        this.cachedStatus = {
+            isReady: reactMapAdapterShared.INITIAL_MAP_STATE.isReady,
+            initializationFailed: reactMapAdapterShared.INITIAL_MAP_STATE.initializationFailed,
+            appearance: reactMapAdapterShared.INITIAL_MAP_STATE.appearance,
+            tileSize: MAPBOX_TILE_SIZE,
+        };
+        this.cameraListeners = new Set();
+        this.statusListeners = new Set();
+        this.eventListeners = new Map();
+        this.mapboxEventCleanups = [];
+        this.isDestroyedFlag = false;
+        this.appearance = { ...reactMapAdapterShared.DEFAULT_MAP_APPEARANCE, theme: config.theme ?? "light" };
+        this.layers = new MapboxLayerPort();
+        this.layers.setTheme(this.appearance.theme);
+        this.state = { ...reactMapAdapterShared.computeInitialState(this.appearance, config.initialViewport), tileSize: MAPBOX_TILE_SIZE };
+        this.cachedCameraState = {
+            center: this.state.center,
+            zoom: this.state.zoom,
+            bounds: this.state.bounds,
+            isIdle: this.state.isIdle,
+        };
+        this.cachedStatus = {
+            isReady: this.state.isReady,
+            initializationFailed: this.state.initializationFailed,
+            appearance: this.state.appearance,
+            tileSize: this.state.tileSize,
+        };
+    }
+    // ============================================================================
+    // Public AdapterInstance implementation
+    // ============================================================================
+    /**
+     * Connect to a Mapbox map instance - called by MapboxRenderer
+     */
+    connect(map) {
+        // React 18 StrictMode (dev) runs effect cleanups between the first and second mount, so
+        // `useMap`'s destroy cleanup fires before the real connect. Allow `connect` to revive a
+        // destroyed adapter so the dev cycle self-heals; production unmounts never re-mount.
+        if (this.isDestroyedFlag) {
+            this.isDestroyedFlag = false;
+        }
+        // Prevent reconnection if already connected
+        if (this.state.isReady)
+            return;
+        this.map = map;
+        this.setupEventListeners();
+        // Connect the layer port so it can render on this map
+        this.layers.connect(map);
+        // Set isReady and notify status listeners before syncing camera state
+        this.state = { ...this.state, isReady: true, initializationFailed: false };
+        this.updateStatusCache();
+        this.notifyStatusListeners();
+        // Sync initial map state
+        this.updateState();
+    }
+    getConfig() {
+        return this.config;
+    }
+    getCameraState() {
+        return this.cachedCameraState;
+    }
+    getStatus() {
+        return this.cachedStatus;
+    }
+    subscribeCamera(listener) {
+        this.cameraListeners.add(listener);
+        return () => {
+            this.cameraListeners.delete(listener);
+        };
+    }
+    subscribeStatus(listener) {
+        this.statusListeners.add(listener);
+        return () => {
+            this.statusListeners.delete(listener);
+        };
+    }
+    async setCenter(center) {
+        const validCenter = geoJsonUtils.validatePosition(center, "[setCenter]");
+        if (validCenter === null)
+            return;
+        const currentMap = this.map;
+        if (currentMap === null)
+            return;
+        return new Promise(resolve => {
+            currentMap.setCenter(positionToLngLat(validCenter));
+            currentMap.once("idle", () => resolve());
+        });
+    }
+    async setZoom(zoom) {
+        const currentMap = this.map;
+        if (currentMap === null)
+            return;
+        return new Promise(resolve => {
+            currentMap.setZoom(zoom);
+            currentMap.once("idle", () => resolve());
+        });
+    }
+    async zoomBy(delta) {
+        const currentMap = this.map;
+        if (currentMap === null)
+            return;
+        const currentZoom = currentMap.getZoom();
+        return this.setZoom(currentZoom + delta);
+    }
+    async fitBounds(bounds, options) {
+        const validBounds = geoJsonUtils.validateBbox(bounds, "[fitBounds]");
+        if (validBounds === null)
+            return;
+        const currentMap = this.map;
+        if (currentMap === null)
+            return;
+        return new Promise(resolve => {
+            const mapboxOptions = {
+                padding: options?.padding ?? 0,
+                ...(options?.maxZoom !== undefined && { maxZoom: options.maxZoom }),
+                animate: options?.animate ?? true,
+            };
+            if (!mapboxOptions.animate) {
+                // animate:false = synchronous camera jump. The camera is already at the target
+                // position when fitBounds() returns, so resolve immediately — no event needed.
+                // Waiting for moveend/idle is wrong here: if the target equals the current
+                // viewport (no-op), neither event fires and the promise hangs forever.
+                currentMap.fitBounds(bboxToLngLatBounds(validBounds), mapboxOptions);
+                resolve();
+                return;
+            }
+            // Animated move: register moveend BEFORE calling fitBounds so we don't miss
+            // a synchronous dispatch, then guard against no-ops (camera already at target).
+            const handleMoveEnd = () => {
+                resolve();
+            };
+            currentMap.once("moveend", handleMoveEnd);
+            currentMap.fitBounds(bboxToLngLatBounds(validBounds), mapboxOptions);
+            if (!currentMap.isMoving()) {
+                // No animation started (no-op: camera already at target). moveend won't fire.
+                currentMap.off("moveend", handleMoveEnd);
+                resolve();
+            }
+        });
+    }
+    async panTo(center) {
+        const validCenter = geoJsonUtils.validatePosition(center, "[panTo]");
+        if (validCenter === null)
+            return;
+        const currentMap = this.map;
+        if (currentMap === null)
+            return;
+        return new Promise(resolve => {
+            currentMap.panTo(positionToLngLat(validCenter));
+            currentMap.once("idle", () => resolve());
+        });
+    }
+    async panBy(deltaX, deltaY) {
+        const currentMap = this.map;
+        if (currentMap === null)
+            return;
+        currentMap.panBy([deltaX, deltaY]);
+    }
+    async setMapType(type) {
+        if (this.appearance.mapType === type)
+            return;
+        this.appearance = { ...this.appearance, mapType: type };
+        this.state = { ...this.state, appearance: this.appearance };
+        this.updateStatusCache();
+        this.notifyStatusListeners();
+        const currentMap = this.map;
+        if (currentMap === null)
+            return;
+        const effectiveType = this.effectiveMapType();
+        const styleUrl = MAPBOX_MAP_TYPE_STYLES[effectiveType][this.appearance.theme];
+        return new Promise(resolve => {
+            currentMap.setStyle(styleUrl);
+            currentMap.once("idle", () => resolve());
+        });
+    }
+    async setTheme(theme) {
+        if (this.appearance.theme === theme)
+            return;
+        this.appearance = { ...this.appearance, theme };
+        this.state = { ...this.state, appearance: this.appearance };
+        this.layers.setTheme(theme);
+        this.updateStatusCache();
+        this.notifyStatusListeners();
+        const currentMap = this.map;
+        if (currentMap === null)
+            return;
+        const effectiveType = this.effectiveMapType();
+        const styleUrl = MAPBOX_MAP_TYPE_STYLES[effectiveType][this.appearance.theme];
+        return new Promise(resolve => {
+            currentMap.setStyle(styleUrl);
+            currentMap.once("idle", () => resolve());
+        });
+    }
+    async setShowRoads(showRoads) {
+        if (this.appearance.showRoads === showRoads)
+            return;
+        this.appearance = { ...this.appearance, showRoads };
+        this.state = { ...this.state, appearance: this.appearance };
+        this.updateStatusCache();
+        this.notifyStatusListeners();
+        // Re-apply style if on satellite (satellite vs hybrid depends on showRoads)
+        const currentMap = this.map;
+        if (currentMap === null)
+            return;
+        if (this.appearance.mapType === "satellite" || this.appearance.mapType === "hybrid") {
+            const effectiveType = this.effectiveMapType();
+            const styleUrl = MAPBOX_MAP_TYPE_STYLES[effectiveType][this.appearance.theme];
+            return new Promise(resolve => {
+                currentMap.setStyle(styleUrl);
+                currentMap.once("idle", () => resolve());
+            });
+        }
+    }
+    on(event, handler) {
+        let listeners = this.eventListeners.get(event);
+        if (listeners === undefined) {
+            listeners = new Set();
+            this.eventListeners.set(event, listeners);
+        }
+        // Store handler as generic event handler
+        const storedHandler = mapEvent => {
+            // Only call handler if event type matches (runtime check + type narrowing)
+            if (reactMapAdapterShared.isEventOfType(mapEvent, event)) {
+                handler(mapEvent);
+            }
+        };
+        listeners.add(storedHandler);
+        return () => {
+            listeners.delete(storedHandler);
+        };
+    }
+    notifyInitializationFailed() {
+        if (this.isDestroyedFlag) {
+            return;
+        }
+        if (this.state.initializationFailed) {
+            return;
+        }
+        this.state = { ...this.state, isReady: false, initializationFailed: true };
+        this.updateStatusCache();
+        this.notifyStatusListeners();
+    }
+    destroy() {
+        this.isDestroyedFlag = true;
+        // Clean up layer port before removing event listeners
+        this.layers.destroy();
+        // Remove all Mapbox event listeners
+        this.mapboxEventCleanups.forEach(cleanup => cleanup());
+        this.mapboxEventCleanups = [];
+        // Clear our listeners
+        this.cameraListeners.clear();
+        this.statusListeners.clear();
+        this.eventListeners.clear();
+        this.map = null;
+        // Set isReady: false in state (listeners already cleared, no need to notify)
+        this.state = { ...reactMapAdapterShared.INITIAL_MAP_STATE, isReady: false, tileSize: MAPBOX_TILE_SIZE };
+        this.updateCameraCache();
+        this.updateStatusCache();
+    }
+    // ============================================================================
+    // Private methods
+    // ============================================================================
+    setupEventListeners() {
+        const currentMap = this.map;
+        if (currentMap === null)
+            return;
+        // Idle event
+        const idleListener = () => {
+            this.updateState();
+            this.emitEvent({ type: "idle" });
+        };
+        currentMap.on("idle", idleListener);
+        this.mapboxEventCleanups.push(() => currentMap.off("idle", idleListener));
+        // Move start — set isIdle=false so adaptive resolution freezes during camera motion
+        const moveStartListener = () => {
+            this.setIdleState(false);
+            this.emitEvent({ type: "movestart" });
+        };
+        currentMap.on("movestart", moveStartListener);
+        this.mapboxEventCleanups.push(() => currentMap.off("movestart", moveStartListener));
+        // Move (during drag/zoom) — update position but preserve isIdle=false set by movestart
+        const moveListener = () => {
+            this.updatePositionOnly();
+        };
+        currentMap.on("move", moveListener);
+        this.mapboxEventCleanups.push(() => currentMap.off("move", moveListener));
+        // Click event
+        const clickListener = (e) => {
+            this.emitEvent({
+                type: "click",
+                position: lngLatToPosition(e.lngLat),
+                originalEvent: e.originalEvent,
+            });
+        };
+        currentMap.on("click", clickListener);
+        this.mapboxEventCleanups.push(() => currentMap.off("click", clickListener));
+        // Pointer move (ADR-0021 fill tiling) — throttled to one emit per frame.
+        let pointerMoveRaf = null;
+        let lastPointerPosition = null;
+        const pointerMoveListener = (e) => {
+            lastPointerPosition = lngLatToPosition(e.lngLat);
+            if (pointerMoveRaf !== null)
+                return;
+            pointerMoveRaf = requestAnimationFrame(() => {
+                pointerMoveRaf = null;
+                if (lastPointerPosition !== null) {
+                    this.emitEvent({ type: "pointermove", position: lastPointerPosition });
+                }
+            });
+        };
+        currentMap.on("mousemove", pointerMoveListener);
+        this.mapboxEventCleanups.push(() => {
+            currentMap.off("mousemove", pointerMoveListener);
+            if (pointerMoveRaf !== null)
+                cancelAnimationFrame(pointerMoveRaf);
+        });
+    }
+    updateState() {
+        const currentMap = this.map;
+        if (currentMap === null)
+            return;
+        const center = currentMap.getCenter();
+        const zoom = currentMap.getZoom();
+        const bounds = currentMap.getBounds();
+        const newCamera = {
+            center: lngLatToPosition(center),
+            zoom,
+            bounds: bounds ? lngLatBoundsToBbox(bounds) : null,
+            isIdle: true,
+        };
+        // Only notify camera subscribers if camera fields actually changed
+        if (!reactMapAdapterShared.cameraStateEquals(this.state, newCamera)) {
+            this.state = { ...this.state, ...newCamera };
+            this.updateCameraCache();
+            this.notifyCameraListeners();
+        }
+    }
+    /**
+     * Update camera position fields (center, zoom, bounds) without touching isIdle.
+     * Called during `move` events so that isIdle=false set by `movestart` is preserved
+     * until the map reaches the `idle` state.
+     */
+    updatePositionOnly() {
+        const currentMap = this.map;
+        if (currentMap === null)
+            return;
+        const center = currentMap.getCenter();
+        const zoom = currentMap.getZoom();
+        const bounds = currentMap.getBounds();
+        const newCamera = {
+            center: lngLatToPosition(center),
+            zoom,
+            bounds: bounds ? lngLatBoundsToBbox(bounds) : null,
+            isIdle: this.state.isIdle,
+        };
+        if (!reactMapAdapterShared.cameraStateEquals(this.state, newCamera)) {
+            this.state = { ...this.state, ...newCamera };
+            this.updateCameraCache();
+            this.notifyCameraListeners();
+        }
+    }
+    /**
+     * Explicitly set isIdle and notify camera subscribers if it changed.
+     * Used by movestart (false) and the idle path already calls updateState (true).
+     */
+    setIdleState(isIdle) {
+        if (this.state.isIdle === isIdle)
+            return;
+        this.state = { ...this.state, isIdle };
+        this.updateCameraCache();
+        this.notifyCameraListeners();
+    }
+    /**
+     * Resolves the effective Mapbox style key: when the user asks for "satellite"
+     * with roads enabled, we use "hybrid" (satellite + road labels).
+     */
+    effectiveMapType() {
+        if (this.appearance.mapType === "satellite" && this.appearance.showRoads) {
+            return "hybrid";
+        }
+        return this.appearance.mapType;
+    }
+    updateCameraCache() {
+        const { center, zoom, bounds, isIdle } = this.state;
+        this.cachedCameraState = { center, zoom, bounds, isIdle };
+    }
+    updateStatusCache() {
+        const { isReady, initializationFailed, appearance, tileSize } = this.state;
+        this.cachedStatus = { isReady, initializationFailed, appearance, tileSize };
+    }
+    notifyCameraListeners() {
+        this.cameraListeners.forEach(listener => listener());
+    }
+    notifyStatusListeners() {
+        this.statusListeners.forEach(listener => listener());
+    }
+    emitEvent(event) {
+        const listeners = this.eventListeners.get(event.type);
+        if (listeners !== undefined) {
+            listeners.forEach(handler => {
+                handler(event);
+            });
+        }
+        // Also emit moveend after idle if it was a move
+        if (event.type === "idle") {
+            const moveEndListeners = this.eventListeners.get("moveend");
+            if (moveEndListeners !== undefined) {
+                const moveEndEvent = { type: "moveend", state: this.state };
+                moveEndListeners.forEach(handler => {
+                    handler(moveEndEvent);
+                });
+            }
+        }
+    }
+}
+const createMapboxInstance = (config) => {
+    return new MapboxAdapterInstance(config);
+};
+
+/**
+ * Internal component that renders the actual Mapbox map
+ */
+const MapboxMapInternal = ({ adapterInstance, children, className, style, theme, accessToken, region, initialViewport, restrictBounds, }) => {
+    const containerRef = react.useRef(null);
+    const mapRef = react.useRef(null);
+    const subscribeAdapter = react.useCallback((onChange) => adapterInstance.subscribeStatus(onChange), [adapterInstance]);
+    const getMapUsableSnapshot = react.useCallback(() => {
+        const s = adapterInstance.getStatus();
+        return s.isReady && !s.initializationFailed;
+    }, [adapterInstance]);
+    const mapUsable = react.useSyncExternalStore(subscribeAdapter, getMapUsableSnapshot, getMapUsableSnapshot);
+    const restrictionBbox = react.useMemo(() => reactMapAdapterShared.getEffectiveRestrictBounds(restrictBounds), [restrictBounds]);
+    // Use ref to capture latest adapter instance without causing re-renders
+    const adapterInstanceRef = react.useRef(adapterInstance);
+    react.useEffect(() => {
+        adapterInstanceRef.current = adapterInstance;
+    });
+    // Initialize Mapbox map ONCE - wait for container to have dimensions before creating map
+    // Mapbox's load event may not fire if container has zero height at init time
+    react.useEffect(() => {
+        const container = containerRef.current;
+        if (container === null || mapRef.current !== null) {
+            return;
+        }
+        let rafId;
+        let map = null;
+        let attempts = 0;
+        const maxAttempts = 60; // ~1 second at 60fps
+        const initMap = () => {
+            if (mapRef.current !== null) {
+                return;
+            }
+            const el = containerRef.current;
+            if (el === null) {
+                return;
+            }
+            const w = el.clientWidth;
+            const h = el.clientHeight;
+            if ((w === 0 || h === 0) && attempts < maxAttempts) {
+                attempts++;
+                rafId = requestAnimationFrame(initMap);
+                return;
+            }
+            mapboxgl.accessToken = accessToken;
+            const worldviewOption = region !== undefined ? { worldview: region } : {};
+            const baseOptions = {
+                interactive: true,
+                projection: "mercator",
+                ...worldviewOption,
+                ...(reactDeviceDetect.isDesktop
+                    ? { dragPan: true, scrollZoom: true }
+                    : { dragPan: true, scrollZoom: true, touchZoomRotate: true, touchPitch: true }),
+            };
+            const maxBoundsOption = restrictionBbox !== null ? { maxBounds: bboxToLngLatBounds(restrictionBbox) } : {};
+            const mapOptions = initialViewport?.type === "bounds"
+                ? {
+                    container: el,
+                    style: MAPBOX_MAP_TYPE_STYLES.roadmap[theme],
+                    bounds: bboxToLngLatBounds(initialViewport.bounds),
+                    fitBoundsOptions: initialViewport.padding !== undefined || initialViewport.maxZoom !== undefined
+                        ? {
+                            ...(initialViewport.padding !== undefined && { padding: initialViewport.padding }),
+                            ...(initialViewport.maxZoom !== undefined && { maxZoom: initialViewport.maxZoom }),
+                        }
+                        : undefined,
+                    ...baseOptions,
+                    ...maxBoundsOption,
+                }
+                : {
+                    container: el,
+                    style: MAPBOX_MAP_TYPE_STYLES.roadmap[theme],
+                    center: initialViewport?.type === "center"
+                        ? { lng: initialViewport.center[0], lat: initialViewport.center[1] }
+                        : { lng: reactMapAdapterShared.DEFAULT_CENTER.lng, lat: reactMapAdapterShared.DEFAULT_CENTER.lat },
+                    zoom: initialViewport?.type === "center" && initialViewport.zoom !== undefined
+                        ? initialViewport.zoom
+                        : reactMapAdapterShared.DEFAULT_ZOOM,
+                    ...baseOptions,
+                    ...maxBoundsOption,
+                };
+            map = new mapboxgl.Map(mapOptions);
+            map.getCanvas().style.cursor = reactMapAdapterShared.MAP_CURSORS.default;
+            map.getCanvasContainer().style.cursor = reactMapAdapterShared.MAP_CURSORS.default;
+            mapRef.current = map;
+            adapterInstanceRef.current.connect(map);
+            // Only treat errors as init failure until the first `load`. Tile/sprite errors after that
+            // are non-fatal — the map is already interactive (parity with not permanently failing the adapter on transient network issues).
+            let hasLoaded = false;
+            map.once("load", () => {
+                hasLoaded = true;
+            });
+            map.on("error", () => {
+                if (!hasLoaded) {
+                    adapterInstanceRef.current.notifyInitializationFailed();
+                }
+            });
+        };
+        rafId = requestAnimationFrame(initMap);
+        return () => {
+            cancelAnimationFrame(rafId);
+            if (mapRef.current !== null) {
+                mapRef.current.remove();
+                mapRef.current = null;
+            }
+        };
+        // Intentionally empty deps: this effect runs once on mount to create the map.
+        // accessToken, theme, initialViewport, restrictionBbox are used for initialization only.
+        // They come from adapterInstance.getConfig(), which is immutable by design (set at adapter
+        // construction). Theme changes are handled by the adapter via map.setStyle(), not by
+        // recreating the map. Adding these to deps would require disconnect/reconnect support in
+        // the adapter for a code path that never executes in practice. See MapboxRenderer docs.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    return (jsxRuntime.jsxs("div", { className: className, style: { width: "100%", height: "100%", position: "relative", ...style }, children: [jsxRuntime.jsx("div", { ref: containerRef, style: {
+                    width: "100%",
+                    height: "100%",
+                    minHeight: 200,
+                } }), mapUsable ? jsxRuntime.jsx("div", { style: { position: "absolute", inset: 0, pointerEvents: "none" }, children: children }) : null] }));
+};
+/**
+ * Mapbox Renderer component — mounts GL JS and connects {@link MapboxAdapterInstance}.
+ * Full-map loading/error UX is owned by `@trackunit/react-map` (`createMapComponent`); this file only
+ * gates layer children on adapter readiness and reports init-time failures via the adapter.
+ */
+const MapboxRenderer = (props) => {
+    const { adapterInstance } = props;
+    // Get config from adapter instance - MapboxRenderer only receives MapboxAdapterInstance
+    if (!(adapterInstance instanceof MapboxAdapterInstance)) {
+        throw new Error("MapboxRenderer requires MapboxAdapterInstance");
+    }
+    const mapboxInstance = adapterInstance;
+    const config = mapboxInstance.getConfig();
+    const { accessToken, theme = "light", region, initialViewport, restrictBounds } = config;
+    return (jsxRuntime.jsx(MapboxMapInternal, { ...props, accessToken: accessToken, adapterInstance: mapboxInstance, initialViewport: initialViewport, region: region, restrictBounds: restrictBounds, theme: theme }));
+};
+
+/** Stable reference — inline objects break `useMap` Map memo equality and recreate the map every render. */
+const MAPBOX_ADAPTER_SAFE_AREA_INSETS = {
+    top: 0,
+    right: 0,
+    bottom: 30,
+    left: 0,
+};
+/**
+ * Mapbox adapter factory
+ *
+ * Creates an adapter configuration for Mapbox GL JS that can be passed to useMap.
+ *
+ * @example
+ * ```tsx
+ * const map = useMap(mapboxAdapter({
+ *   accessToken: process.env.MAPBOX_ACCESS_TOKEN,
+ *   theme: "dark",
+ *   language: "en",
+ * }));
+ *
+ * <map.Map className="h-full w-full">
+ *   {children}
+ * </map.Map>
+ * ```
+ */
+const mapboxAdapter = reactMapAdapterShared.defineAdapter((config) => ({
+    name: "mapbox",
+    config,
+    safeAreaInsets: MAPBOX_ADAPTER_SAFE_AREA_INSETS,
+    createInstance: () => createMapboxInstance(config),
+    Renderer: MapboxRenderer,
+}));
+
+exports.MapboxAdapterInstance = MapboxAdapterInstance;
+exports.MapboxRenderer = MapboxRenderer;
+exports.mapboxAdapter = mapboxAdapter;