@trackunit/react-map-adapter-google 0.0.3

package/index.esm.js

@@ -0,0 +1,3010 @@
+import { jsx } from 'react/jsx-runtime';
+import { APIProvider, APIProviderContext, useMap, useApiLoadingStatus, APILoadingStatus, Map as Map$1 } from '@vis.gl/react-google-maps';
+import { useMemo, useCallback, useSyncExternalStore, useId, useContext, useEffect } from 'react';
+import { canPatchAdaptiveMarker, canPatchAdaptiveViewport, canPatchMarkerInPlace, extractPointCoordinates, mergeAntimeridianFeatures, extractPolygonPaths, extractLineCoordinates, patchPortalDescriptors, collectFeatureIdSet, removeGoneIndexedMarkers, getAdaptiveDomFeatureIds, extractSourceData, buildAdaptiveDomRenderFn, resolveCircleSymbolDefaults, resolveSymbolDescriptor, buildAdaptiveSymbolStyleFn, createSymbolDotElement, anchorFromBottomCenter, createDefaultClusterElement, createClusterPinElement, fadeInElement, buildAdaptiveDomEntries, MAP_CURSORS, resolveSelectedStyle, resolveHoveredStyle, colorWithOpacity, attachSafeAreaHoverListeners, INITIAL_MAP_STATE, DEFAULT_MAP_APPEARANCE, computeInitialState, getEffectiveRestrictBounds, cameraStateEquals, isEventOfType, DEFAULT_ZOOM, DEFAULT_CENTER, defineAdapter } from '@trackunit/react-map-adapter-shared';
+import { validateBbox, validatePosition } from '@trackunit/geo-json-utils';
+import { MarkerClusterer, SuperClusterAlgorithm } from '@googlemaps/markerclusterer';
+import { isEqual } from 'es-toolkit';
+import { z } from 'zod';
+import { isDesktop } from 'react-device-detect';
+
+/**
+ * Shared Google Maps API context for multi-map layouts.
+ *
+ * Wrap multiple `<Map>` instances in a single `GoogleApiProvider` to load the
+ * Google Maps JS API once and prevent zombie `google.maps.Map` instances that
+ * occur when multiple `APIProvider`s initialize concurrently with `mapId`
+ * (vector/cloud-styled maps).
+ *
+ * Each map should have a unique `mapInstanceId` in its adapter config so the
+ * vis.gl registry can distinguish them.
+ *
+ * @example
+ * ```tsx
+ * <GoogleApiProvider apiKey={API_KEY}>
+ *   <Map1 /> // googleMapsAdapter({ apiKey, mapInstanceId: "map-1" })
+ *   <Map2 /> // googleMapsAdapter({ apiKey, mapInstanceId: "map-2" })
+ * </GoogleApiProvider>
+ * ```
+ */
+const GoogleApiProvider = ({ apiKey, language, children }) => {
+    const libraries = useMemo(() => ["marker"], []);
+    return (jsx(APIProvider, { apiKey: apiKey, language: language, libraries: libraries, children: children }));
+};
+
+/**
+ * Zod schema for Google Maps LatLngLiteral
+ * A plain object with lat and lng number properties
+ */
+const latLngLiteralSchema = z.object({
+    lat: z.number(),
+    lng: z.number(),
+});
+/**
+ * Zod schema for Google Maps LatLng class instance
+ * An object with lat() and lng() methods that return numbers
+ */
+const latLngClassSchema = z.object({
+    lat: z.function().returns(z.number()),
+    lng: z.function().returns(z.number()),
+});
+/**
+ * Convert GeoJSON Position [lng, lat] to Google Maps LatLngLiteral
+ */
+const positionToLatLng = (position) => ({
+    lng: position[0],
+    lat: position[1],
+});
+/**
+ * Convert Google Maps LatLng to GeoJSON Position [lng, lat]
+ * Uses Zod to distinguish between LatLngLiteral (plain object) and LatLng (class instance)
+ */
+const latLngToPosition = (latLng) => {
+    const literalResult = latLngLiteralSchema.safeParse(latLng);
+    if (literalResult.success) {
+        // It's a LatLngLiteral - lat and lng are numbers
+        return [literalResult.data.lng, literalResult.data.lat];
+    }
+    const classResult = latLngClassSchema.safeParse(latLng);
+    if (classResult.success) {
+        // It's a LatLng class instance - lat and lng are methods
+        return [classResult.data.lng(), classResult.data.lat()];
+    }
+    // This should never happen if the input type is correct
+    throw new Error("Invalid LatLng value: expected either LatLngLiteral or LatLng class instance");
+};
+/**
+ * Convert GeoJSON Bbox [minLon, minLat, maxLon, maxLat] to Google Maps LatLngBoundsLiteral
+ */
+const bboxToLatLngBounds = (bbox) => ({
+    west: bbox[0],
+    south: bbox[1],
+    east: bbox[2],
+    north: bbox[3],
+});
+/**
+ * Convert Google Maps LatLngBounds to GeoJSON Bbox [minLon, minLat, maxLon, maxLat]
+ */
+const latLngBoundsToBbox = (bounds) => {
+    const sw = bounds.getSouthWest();
+    const ne = bounds.getNorthEast();
+    return [sw.lng(), sw.lat(), ne.lng(), ne.lat()];
+};
+
+// ============================================================================
+// Google-specific helpers
+// ============================================================================
+const collectFeatureIdsFromCluster = (cluster) => {
+    const ids = [];
+    for (const m of cluster.markers) {
+        if ("dataset" in m) {
+            const featureId = m.dataset.featureId;
+            if (featureId !== undefined) {
+                ids.push(featureId);
+            }
+        }
+    }
+    return ids;
+};
+/**
+ * Convert a GeoJSON bbox [minLng, minLat, maxLng, maxLat] to Google Maps LatLngBoundsLiteral.
+ */
+const bboxToGoogleBounds = (bbox) => ({
+    west: bbox[0],
+    south: bbox[1],
+    east: bbox[2],
+    north: bbox[3],
+});
+const CANVAS_VIEWPORT_PADDING = 50;
+/** Outline polylines for tiled polygons must always render above any fill polygon,
+ * including hover-promoted fills (max fill z-index is HOVER_PROMOTION_Z_INDEX = 10_000
+ * in useShapeFillTiling). A value of 1_000_000 keeps strokes visually complete. */
+const TILED_OUTLINE_Z_INDEX = 1000000;
+// AdvancedMarkerElement zIndex for DOM-promoted adaptive markers. Must be high
+// enough to render above the canvas overlay (which has no explicit zIndex).
+const DOM_MARKER_Z_INDEX = 1000;
+// ============================================================================
+// GoogleMapsLayerPort
+// ============================================================================
+/**
+ * Google Maps implementation of the LayerPort interface.
+ *
+ * Manages Google Maps objects to render map content.
+ * Each source type maps to appropriate Google Maps constructs:
+ * - Markers: Canvas OverlayView (symbol/adaptive mode), AdvancedMarkerElement (DOM mode)
+ * - Shapes: google.maps.Polygon / google.maps.Polyline
+ * - Routes: google.maps.Polyline with optional arrow symbols
+ * - Image overlays: google.maps.GroundOverlay
+ *
+ * Requires `connect(map)` to be called (by GoogleMapsAdapterInstance) before
+ * any sources can be rendered. Sources set before connect are queued.
+ */
+class GoogleMapsLayerPort {
+    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
+         * server-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.mapClickListener = null;
+        // Tracked sources, keyed by source ID
+        this.markerSources = new Map();
+        /** featureId → element, keyed by sourceId. Cleared when a source is removed. */
+        this.adaptiveMarkerIndex = new Map();
+        /** cluster featureId → element, 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();
+        // Queue for snapshot set before the map is connected
+        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.
+        // Subscribers (the <Layers> component) are notified when the list changes.
+        this.markerPortalDescriptors = [];
+        this.clusterPortalDescriptors = [];
+        this.markerPortalSubscribers = new Set();
+        this.clusterPortalSubscribers = new Set();
+        this.clusterEntitiesByMarker = new WeakMap();
+        // ---- Adaptive marker pointermove watcher (cross-marker) ----
+        // Each adaptive DOM marker may install a pointermove watcher on document to detect
+        // genuine departure after a spurious mouseleave. These are per-marker closures, so
+        // moving from marker A to marker B would leave A's watcher alive — it fires hover-end
+        // and clears B's hover state. This class-level reference holds the cancel for whichever
+        // watcher is currently active, so any mouseenter on any adaptive marker can cancel it.
+        this.markerHoverState = { activeWatcherCancel: null, activeGuardCancel: null };
+        // ---- Shape interaction tracking ----
+        this.selectedShapeHandleId = null;
+        this.selectedShapeFeatureId = null;
+        this.hoveredShapeHandleId = null;
+        this.hoveredShapeFeatureId = null;
+        this.theme = "light";
+        // ---- Shape dblclick via DOM ----
+        // Google Maps overlays suppress both the second click AND dblclick events
+        // when disableDoubleClickZoom is true, and without it, native zoom moves
+        // the shape away before the second click. So we: (1) suppress native zoom
+        // on mousedown, and (2) catch the browser's own dblclick on the map
+        // container, matching it to the most recent shape click.
+        this.lastShapeClickTime = 0;
+        this.lastShapeClickEntity = null;
+        /** Forwards geographic pointer position to the adapter (fill tiling settle channel). */
+        this.pointerMoveReporter = null;
+        this.holdNativeZoomTimer = null;
+        this.mapDblClickListenerCleanup = null;
+        // Consumer-injected shape style defaults (set via setShapeStyleDefaults before first snapshot)
+        this._shapeStyleDefaults = undefined;
+    }
+    get shapeStyleDefaults() {
+        if (this._shapeStyleDefaults === undefined) {
+            throw new Error("shapeStyleDefaults not injected — call setShapeStyleDefaults before using GoogleMapsLayerPort");
+        }
+        return this._shapeStyleDefaults;
+    }
+    // ---- Connection ----
+    setShapeStyleDefaults(defaults) {
+        this._shapeStyleDefaults = defaults;
+    }
+    /**
+     * Connect to a Google Maps instance.
+     * Called by GoogleMapsAdapterInstance.connect() when the map is ready.
+     * Flushes any sources that were set before the map was available.
+     */
+    connect(map) {
+        // If reconnecting to a new map instance (e.g. after theme change),
+        // re-render all existing sources on the new map
+        const isReconnection = this.map !== null && this.map !== map;
+        this.map = map;
+        this.setupMapContainerDblClickListener(map);
+        this.setupMapClickListener(map);
+        if (isReconnection) {
+            this.reconnectAllSources();
+            return;
+        }
+        // Flush queued snapshot
+        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);
+        }
+    }
+    // ---- Declarative state ----
+    setSnapshot(snapshot) {
+        if (snapshot.layers.length > 0) {
+            this.lastNonEmptySnapshot = snapshot;
+        }
+        if (this.map === null) {
+            this.pendingSnapshot = snapshot;
+            return;
+        }
+        this.applySnapshot(snapshot);
+    }
+    // ---- Pointer position (fill tiling) ----
+    /**
+     * Register a reporter for geographic pointer position. Google Maps does not
+     * emit map-level mousemove while the cursor is over clickable shape overlays;
+     * shape listeners call this so fill-tiling settle gets the correct position.
+     */
+    setPointerMoveReporter(reporter) {
+        this.pointerMoveReporter = reporter;
+    }
+    // ---- 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.hoveredShapeHandleId !== null) {
+            this.applyGoogleShapeInteraction(this.hoveredShapeHandleId);
+        }
+        if (this.selectedShapeHandleId !== null && this.selectedShapeHandleId !== this.hoveredShapeHandleId) {
+            this.applyGoogleShapeInteraction(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(_sourceId, callback) {
+        let cancelled = false;
+        queueMicrotask(() => {
+            if (!cancelled)
+                callback();
+        });
+        return () => {
+            cancelled = true;
+        };
+    }
+    // ---- 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);
+        }
+        this.interactionHandlers.clear();
+        this.backgroundClickHandlers.clear();
+        this.markerPortalDescriptors = [];
+        this.clusterPortalDescriptors = [];
+        this.markerPortalSubscribers.clear();
+        this.clusterPortalSubscribers.clear();
+        this.pendingSnapshot = null;
+        this.selectedShapeHandleId = null;
+        this.selectedShapeFeatureId = null;
+        this.hoveredShapeHandleId = null;
+        this.hoveredShapeFeatureId = null;
+        this.mapDblClickListenerCleanup?.();
+        this.mapDblClickListenerCleanup = null;
+        if (this.mapClickListener !== null) {
+            google.maps.event.removeListener(this.mapClickListener);
+            this.mapClickListener = null;
+        }
+        this.map = null;
+    }
+    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);
+    }
+    // ---- 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. Avoids the
+        // remove-then-add cycle (and its cascading mouseleave → hover-clear → rebuild loop).
+        if (existing !== undefined && 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 && 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 && canPatchMarkerInPlace(existing.config, config)) {
+            if (config.markerRender.mode === "dom") {
+                this.patchDomMarkers(existing, config);
+            }
+            const renderChanged = existing.config.markerRender.render !== config.markerRender.render;
+            existing.config = config;
+            if (config.markerRender.mode === "symbol" && renderChanged) {
+                this.updateSymbolCanvasMarkers(config, existing);
+            }
+            return;
+        }
+        // Remove existing markers for this source (update case)
+        this.removeMarkerSourceInternal(config.id);
+        const tracked = { markers: [], listeners: [], config };
+        const currentMap = this.map;
+        // ---- Client-side clustering path (interactive markers only) ----
+        if (config.kind === "marker" && config.clusterConfig !== null && 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 useCanvasOverlay = markerRender.mode === "symbol" || markerRender.mode === "adaptive";
+        if (useCanvasOverlay) {
+            this.setupCanvasSymbolOverlay(config, currentMap, tracked);
+            if (markerRender.mode === "adaptive") {
+                this.createAdaptiveDomOverlays(config, currentMap, tracked);
+            }
+        }
+        else {
+            // DOM marker path (mode === "dom")
+            for (const feature of config.features.features) {
+                const coords = 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, tracked);
+                    }
+                }
+                else if (marker.content instanceof HTMLElement) {
+                    marker.content.style.pointerEvents = "none";
+                }
+            }
+        }
+        // Render server-side cluster features if present (interactive markers only)
+        if (config.kind === "marker" && config.clusterFeatures !== null) {
+            for (const feature of config.clusterFeatures.features) {
+                const coords = extractPointCoordinates(feature);
+                if (coords === null)
+                    continue;
+                const marker = this.createClusterMarkerForFeature(feature, coords, config, currentMap);
+                tracked.markers.push(marker);
+                // Set up interaction listeners for cluster markers
+                const featureId = feature.id !== undefined ? String(feature.id) : undefined;
+                if (featureId !== undefined) {
+                    const props = feature.properties;
+                    const rawMarkerIds = props !== null ? props.markerIds : undefined;
+                    const markerIds = Array.isArray(rawMarkerIds) ? rawMarkerIds : [];
+                    const clusterBbox = props && props.bbox !== null ? validateBbox(props.bbox) : null;
+                    this.attachClusterInteractionListeners(marker, featureId, { lng: coords.lng, lat: coords.lat }, markerIds, clusterBbox, tracked);
+                    let clusterIndex = this.clusterMarkerIndex.get(config.id);
+                    if (clusterIndex === undefined) {
+                        clusterIndex = new Map();
+                        this.clusterMarkerIndex.set(config.id, clusterIndex);
+                    }
+                    clusterIndex.set(featureId, marker);
+                }
+            }
+        }
+        this.markerSources.set(config.id, tracked);
+    }
+    removeMarkerSourceInternal(id) {
+        const tracked = this.markerSources.get(id);
+        if (tracked === undefined)
+            return;
+        // Clean up MarkerClusterer if present (client-side clustering)
+        if (tracked.clusterer !== undefined) {
+            tracked.clusterer.setMap(null);
+            tracked.clusterer.clearMarkers();
+        }
+        // Clean up canvas overlay if present (symbol/adaptive rendering)
+        if (tracked.canvasOverlay !== undefined) {
+            tracked.canvasOverlay.setMap(null);
+        }
+        for (const listener of tracked.listeners) {
+            google.maps.event.removeListener(listener);
+        }
+        for (const marker of tracked.markers) {
+            marker.map = null;
+        }
+        // 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 existingShape = this.shapeSources.get(config.id);
+        if (existingShape !== undefined) {
+            const prev = existingShape.config;
+            if (prev.features === config.features &&
+                prev.style === config.style &&
+                prev.featureStyles === config.featureStyles &&
+                prev.featureFillGeometries === config.featureFillGeometries &&
+                prev.featureZIndexOverrides === config.featureZIndexOverrides &&
+                prev.interactive === config.interactive) {
+                return;
+            }
+            const coreUnchanged = prev.features === config.features &&
+                prev.style === config.style &&
+                prev.featureStyles === config.featureStyles &&
+                prev.interactive === config.interactive;
+            // Path B promotion: only clipped-fill / z-index overrides changed — patch
+            // affected features in place instead of rebuilding the entire source (~180 sites).
+            if (coreUnchanged &&
+                (prev.featureFillGeometries !== config.featureFillGeometries ||
+                    prev.featureZIndexOverrides !== config.featureZIndexOverrides)) {
+                this.syncShapeTilingOverrides(existingShape, prev, config);
+                existingShape.config = config;
+                if ((this.selectedShapeHandleId === config.id && this.selectedShapeFeatureId !== null) ||
+                    (this.hoveredShapeHandleId === config.id && this.hoveredShapeFeatureId !== null)) {
+                    this.applyGoogleShapeInteraction(config.id);
+                }
+                return;
+            }
+        }
+        // Remove existing shapes for this source (update case)
+        this.removeShapeSourceInternal(config.id);
+        const tracked = {
+            shapes: [],
+            hitPolylines: [],
+            pointMarkers: [],
+            listeners: [],
+            shapeListeners: new WeakMap(),
+            config,
+            featureIdToShapes: new Map(),
+            featureIdToPointMarkers: new Map(),
+            fillOnlyShapes: new Set(),
+        };
+        const currentMap = this.map;
+        const isStrokeOnly = config.interactive === "stroke";
+        const renderFeatures = mergeAntimeridianFeatures(config.features);
+        for (const feature of renderFeatures.features) {
+            const geometry = feature.geometry;
+            if (geometry === null)
+                continue;
+            const { type } = geometry;
+            const fid = feature.id !== undefined ? String(feature.id) : undefined;
+            const featureStyle = (fid !== undefined ? config.featureStyles?.get(fid) : undefined) ?? config.style;
+            // ADR-0021 fill tiling: when a clipped fill geometry is present, draw the
+            // outline from the full geometry and the fill from the clipped geometry.
+            const fillOverride = (type === "Polygon" || type === "MultiPolygon") && fid !== undefined
+                ? config.featureFillGeometries?.get(fid)
+                : undefined;
+            if (fillOverride !== undefined && fid !== undefined) {
+                this.renderTiledPolygonFeature(geometry, fillOverride, featureStyle, fid, isStrokeOnly, config, tracked, currentMap);
+                continue;
+            }
+            if (type === "Polygon") {
+                const paths = extractPolygonPaths(geometry.coordinates);
+                if (paths === null)
+                    continue;
+                const fillVisible = (featureStyle.fillOpacity ?? this.shapeStyleDefaults.polygon.fillOpacity) > 0;
+                const polygonZIndex = fid !== undefined ? config.featureZIndexOverrides?.get(fid) : undefined;
+                const polygon = this.createPolygon(paths, featureStyle, currentMap, !isStrokeOnly && fillVisible, polygonZIndex);
+                tracked.shapes.push(polygon);
+                if (fid !== undefined) {
+                    this.pushToFeatureMap(tracked.featureIdToShapes, fid, polygon);
+                }
+                if (config.interactive !== "none" && fid !== undefined) {
+                    if (isStrokeOnly) {
+                        const hitPls = this.createStrokeHitPolylines(paths, featureStyle.strokeWidth ?? this.shapeStyleDefaults.polygon.strokeWidth, currentMap);
+                        for (const pl of hitPls) {
+                            tracked.hitPolylines.push(pl);
+                            this.pushToFeatureMap(tracked.featureIdToShapes, fid, pl);
+                            this.attachShapeInteractionListeners(pl, fid, "polygon", tracked, config.id);
+                        }
+                    }
+                    else {
+                        this.attachShapeInteractionListeners(polygon, fid, "polygon", tracked, config.id);
+                    }
+                }
+            }
+            else if (type === "MultiPolygon") {
+                const multiCoords = geometry.coordinates;
+                if (!Array.isArray(multiCoords))
+                    continue;
+                for (const polygonCoords of multiCoords) {
+                    const paths = extractPolygonPaths(polygonCoords);
+                    if (paths === null)
+                        continue;
+                    const fillVisible = (featureStyle.fillOpacity ?? this.shapeStyleDefaults.polygon.fillOpacity) > 0;
+                    const polygonZIndex = fid !== undefined ? config.featureZIndexOverrides?.get(fid) : undefined;
+                    const polygon = this.createPolygon(paths, featureStyle, currentMap, !isStrokeOnly && fillVisible, polygonZIndex);
+                    tracked.shapes.push(polygon);
+                    if (fid !== undefined) {
+                        this.pushToFeatureMap(tracked.featureIdToShapes, fid, polygon);
+                    }
+                    if (config.interactive !== "none" && fid !== undefined) {
+                        if (isStrokeOnly) {
+                            const hitPls = this.createStrokeHitPolylines(paths, featureStyle.strokeWidth ?? this.shapeStyleDefaults.polygon.strokeWidth, currentMap);
+                            for (const pl of hitPls) {
+                                tracked.hitPolylines.push(pl);
+                                this.pushToFeatureMap(tracked.featureIdToShapes, fid, pl);
+                                this.attachShapeInteractionListeners(pl, fid, "polygon", tracked, config.id);
+                            }
+                        }
+                        else {
+                            this.attachShapeInteractionListeners(polygon, fid, "polygon", tracked, config.id);
+                        }
+                    }
+                }
+            }
+            else if (type === "LineString") {
+                const path = extractLineCoordinates(feature);
+                if (path === null)
+                    continue;
+                const polyline = this.createPolyline(path, featureStyle, currentMap);
+                tracked.shapes.push(polyline);
+                if (fid !== undefined) {
+                    this.pushToFeatureMap(tracked.featureIdToShapes, fid, polyline);
+                }
+                if (config.interactive !== "none" && fid !== undefined) {
+                    this.attachShapeInteractionListeners(polyline, fid, "line", tracked, config.id);
+                }
+            }
+            else if (type === "MultiLineString") {
+                for (const lineCoords of geometry.coordinates) {
+                    const path = lineCoords.map(([lng, lat]) => ({ lng, lat }));
+                    if (path.length === 0)
+                        continue;
+                    const polyline = this.createPolyline(path, featureStyle, currentMap);
+                    tracked.shapes.push(polyline);
+                    if (fid !== undefined) {
+                        this.pushToFeatureMap(tracked.featureIdToShapes, fid, polyline);
+                    }
+                    if (config.interactive !== "none" && fid !== undefined) {
+                        this.attachShapeInteractionListeners(polyline, fid, "line", tracked, config.id);
+                    }
+                }
+            }
+            else if (type === "Point") {
+                const [lng, lat] = geometry.coordinates;
+                const marker = this.createShapePointMarker({ lng, lat }, featureStyle, currentMap);
+                tracked.pointMarkers.push(marker);
+                if (fid !== undefined) {
+                    this.pushToFeatureMap(tracked.featureIdToPointMarkers, fid, marker);
+                }
+                if (config.interactive !== "none" && fid !== undefined) {
+                    this.attachShapePointInteractionListeners(marker, fid, "point", config.id);
+                }
+            }
+            else if (type === "MultiPoint") {
+                for (const coords of geometry.coordinates) {
+                    const [lng, lat] = coords;
+                    const marker = this.createShapePointMarker({ lng, lat }, featureStyle, currentMap);
+                    tracked.pointMarkers.push(marker);
+                    if (fid !== undefined) {
+                        this.pushToFeatureMap(tracked.featureIdToPointMarkers, fid, marker);
+                    }
+                    if (config.interactive !== "none" && fid !== undefined) {
+                        this.attachShapePointInteractionListeners(marker, fid, "point", config.id);
+                    }
+                }
+            }
+        }
+        this.shapeSources.set(config.id, tracked);
+        // Re-apply interaction styles if this source is currently hovered or selected
+        if ((this.selectedShapeHandleId === config.id && this.selectedShapeFeatureId !== null) ||
+            (this.hoveredShapeHandleId === config.id && this.hoveredShapeFeatureId !== null)) {
+            this.applyGoogleShapeInteraction(config.id);
+        }
+    }
+    /** Deep equality for clipped fill overrides — map emissions create new Map refs every time. */
+    fillOverrideEqual(prev, next) {
+        if (prev === next)
+            return true;
+        if (prev === undefined || next === undefined)
+            return false;
+        return isEqual(prev, next);
+    }
+    /**
+     * Patch only features whose fill-override or z-index changed (ADR-0021 Path B).
+     * Returns the number of features that were updated or re-rendered.
+     */
+    syncShapeTilingOverrides(tracked, prevConfig, config) {
+        if (this.map === null)
+            return 0;
+        const currentMap = this.map;
+        const isStrokeOnly = config.interactive === "stroke";
+        const renderFeatures = mergeAntimeridianFeatures(config.features);
+        let changedCount = 0;
+        for (const feature of renderFeatures.features) {
+            if (feature.id === undefined)
+                continue;
+            const fid = String(feature.id);
+            const geometry = feature.geometry;
+            if (geometry === null)
+                continue;
+            const { type } = geometry;
+            if (type !== "Polygon" && type !== "MultiPolygon")
+                continue;
+            const prevFill = prevConfig.featureFillGeometries?.get(fid);
+            const nextFill = config.featureFillGeometries?.get(fid);
+            const prevZ = prevConfig.featureZIndexOverrides?.get(fid);
+            const nextZ = config.featureZIndexOverrides?.get(fid);
+            const fillChanged = !this.fillOverrideEqual(prevFill, nextFill);
+            const zChanged = prevZ !== nextZ;
+            if (!fillChanged && !zChanged)
+                continue;
+            changedCount += 1;
+            if (!fillChanged) {
+                this.updateFeatureShapeZIndex(tracked, fid, nextZ);
+                continue;
+            }
+            this.removeFeatureShapes(tracked, fid);
+            const featureStyle = config.featureStyles?.get(fid) ?? config.style;
+            const fillOverride = config.featureFillGeometries?.get(fid);
+            if (fillOverride !== undefined) {
+                this.renderTiledPolygonFeature(geometry, fillOverride, featureStyle, fid, isStrokeOnly, config, tracked, currentMap);
+                continue;
+            }
+            if (type === "Polygon") {
+                const paths = extractPolygonPaths(geometry.coordinates);
+                if (paths === null)
+                    continue;
+                const fillVisible = (featureStyle.fillOpacity ?? this.shapeStyleDefaults.polygon.fillOpacity) > 0;
+                const polygon = this.createPolygon(paths, featureStyle, currentMap, !isStrokeOnly && fillVisible, nextZ);
+                tracked.shapes.push(polygon);
+                this.pushToFeatureMap(tracked.featureIdToShapes, fid, polygon);
+                if (config.interactive !== "none") {
+                    if (isStrokeOnly) {
+                        const hitPls = this.createStrokeHitPolylines(paths, featureStyle.strokeWidth ?? 1, currentMap);
+                        for (const pl of hitPls) {
+                            tracked.hitPolylines.push(pl);
+                            this.pushToFeatureMap(tracked.featureIdToShapes, fid, pl);
+                            this.attachShapeInteractionListeners(pl, fid, "polygon", tracked, config.id);
+                        }
+                    }
+                    else {
+                        this.attachShapeInteractionListeners(polygon, fid, "polygon", tracked, config.id);
+                    }
+                }
+            }
+            else {
+                const multiCoords = geometry.coordinates;
+                if (!Array.isArray(multiCoords))
+                    continue;
+                for (const polygonCoords of multiCoords) {
+                    const paths = extractPolygonPaths(polygonCoords);
+                    if (paths === null)
+                        continue;
+                    const fillVisible = (featureStyle.fillOpacity ?? this.shapeStyleDefaults.polygon.fillOpacity) > 0;
+                    const polygon = this.createPolygon(paths, featureStyle, currentMap, !isStrokeOnly && fillVisible, nextZ);
+                    tracked.shapes.push(polygon);
+                    this.pushToFeatureMap(tracked.featureIdToShapes, fid, polygon);
+                    if (config.interactive !== "none") {
+                        if (isStrokeOnly) {
+                            const hitPls = this.createStrokeHitPolylines(paths, featureStyle.strokeWidth ?? 1, currentMap);
+                            for (const pl of hitPls) {
+                                tracked.hitPolylines.push(pl);
+                                this.pushToFeatureMap(tracked.featureIdToShapes, fid, pl);
+                                this.attachShapeInteractionListeners(pl, fid, "polygon", tracked, config.id);
+                            }
+                        }
+                        else {
+                            this.attachShapeInteractionListeners(polygon, fid, "polygon", tracked, config.id);
+                        }
+                    }
+                }
+            }
+        }
+        return changedCount;
+    }
+    /** Remove all map shapes (and their listeners) for a single feature id. */
+    removeFeatureShapes(tracked, featureId) {
+        const shapes = tracked.featureIdToShapes.get(featureId);
+        if (shapes === undefined)
+            return;
+        for (const shape of shapes) {
+            const listeners = tracked.shapeListeners.get(shape) ?? [];
+            const listenersToRemove = new Set(listeners);
+            for (const listener of listeners) {
+                google.maps.event.removeListener(listener);
+            }
+            tracked.listeners = tracked.listeners.filter(listener => !listenersToRemove.has(listener));
+            tracked.shapeListeners.delete(shape);
+            google.maps.event.clearInstanceListeners(shape);
+            shape.setMap(null);
+            if ("getPaths" in shape) {
+                tracked.fillOnlyShapes.delete(shape);
+            }
+            const shapeIndex = tracked.shapes.indexOf(shape);
+            if (shapeIndex >= 0) {
+                tracked.shapes.splice(shapeIndex, 1);
+            }
+            const hitIndex = tracked.hitPolylines.indexOf(shape);
+            if (hitIndex >= 0) {
+                tracked.hitPolylines.splice(hitIndex, 1);
+            }
+        }
+        tracked.featureIdToShapes.delete(featureId);
+    }
+    /** Update z-index on fill-bearing polygons for one feature without a geometry rebuild. */
+    updateFeatureShapeZIndex(tracked, featureId, zIndex) {
+        const shapes = tracked.featureIdToShapes.get(featureId);
+        if (shapes === undefined)
+            return;
+        for (const shape of shapes) {
+            if (!("getPaths" in shape))
+                continue;
+            const isFillOnly = tracked.fillOnlyShapes.has(shape);
+            if (isFillOnly || zIndex !== undefined) {
+                shape.setOptions(zIndex !== undefined ? { zIndex } : {});
+            }
+        }
+    }
+    removeShapeSourceInternal(id) {
+        const tracked = this.shapeSources.get(id);
+        if (tracked === undefined)
+            return;
+        for (const listener of tracked.listeners) {
+            google.maps.event.removeListener(listener);
+        }
+        for (const shape of tracked.shapes) {
+            shape.setMap(null);
+        }
+        for (const pl of tracked.hitPolylines) {
+            pl.setMap(null);
+        }
+        for (const marker of tracked.pointMarkers) {
+            marker.map = null;
+        }
+        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 (prevHandleId !== null) {
+            this.applyGoogleShapeInteraction(prevHandleId);
+        }
+        if (handleId !== null && handleId !== prevHandleId) {
+            this.applyGoogleShapeInteraction(handleId);
+        }
+    }
+    applyShapeHoverState(handleId, featureId) {
+        if (this.hoveredShapeHandleId === handleId && this.hoveredShapeFeatureId === featureId)
+            return;
+        const prevHandleId = this.hoveredShapeHandleId;
+        this.hoveredShapeHandleId = handleId;
+        this.hoveredShapeFeatureId = featureId;
+        if (prevHandleId !== null) {
+            this.applyGoogleShapeInteraction(prevHandleId);
+        }
+        if (handleId !== null && handleId !== prevHandleId) {
+            this.applyGoogleShapeInteraction(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 && isEqual(existing.config, config)) {
+            return;
+        }
+        // Remove existing route for this source (update case)
+        this.removeRouteSourceInternal(config.id);
+        const currentMap = this.map;
+        // Extract the first LineString feature
+        for (const feature of config.features.features) {
+            const path = extractLineCoordinates(feature);
+            if (path === null)
+                continue;
+            const polyline = this.createRoutePolyline(path, config.style, currentMap, config.interactive);
+            const tracked = { polyline, listeners: [], config };
+            if (config.interactive) {
+                const fid = feature.id !== undefined ? String(feature.id) : undefined;
+                if (fid !== undefined) {
+                    this.attachRouteInteractionListeners(polyline, fid, feature, tracked);
+                }
+            }
+            this.routeSources.set(config.id, tracked);
+            // Only use the first LineString feature for the route
+            break;
+        }
+    }
+    removeRouteSourceInternal(id) {
+        const tracked = this.routeSources.get(id);
+        if (tracked === undefined)
+            return;
+        for (const listener of tracked.listeners) {
+            google.maps.event.removeListener(listener);
+        }
+        tracked.polyline.setMap(null);
+        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 && isEqual(existing.config, config)) {
+            return;
+        }
+        // Remove existing overlay for this source (update case)
+        this.removeImageOverlayInternal(config.id);
+        const currentMap = this.map;
+        const bounds = bboxToGoogleBounds(config.imageBounds);
+        const overlay = new google.maps.GroundOverlay(config.url, bounds, {
+            opacity: config.opacity,
+            map: currentMap,
+            clickable: false,
+        });
+        this.overlaySources.set(config.id, { overlay, config });
+    }
+    removeImageOverlayInternal(id) {
+        const tracked = this.overlaySources.get(id);
+        if (tracked === undefined)
+            return;
+        tracked.overlay.setMap(null);
+        this.overlaySources.delete(id);
+    }
+    // ============================================================================
+    // 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 and refresh portal
+     * descriptors so React re-renders with the latest render function.
+     * Avoids the remove-then-add cycle that causes a brief flash.
+     */
+    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 ? extractPointCoordinates(oldFeature) : null;
+            const newCoords = extractPointCoordinates(newFeature);
+            if (newCoords !== null &&
+                (oldCoords === null || oldCoords.lng !== newCoords.lng || oldCoords.lat !== newCoords.lat)) {
+                marker.position = { lng: newCoords.lng, lat: newCoords.lat };
+            }
+        }
+        if (config.markerRender.mode === "dom") {
+            const result = patchPortalDescriptors(this.markerPortalDescriptors, config.id, newFeatures, config.markerRender.render);
+            if (result.changed) {
+                this.markerPortalDescriptors = result.descriptors;
+                this.notifyMarkerPortalSubscribers();
+            }
+        }
+    }
+    /**
+     * 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);
+        if (existing.canvasMarkers !== undefined && existing.canvasOverlay !== undefined) {
+            this.updateAdaptiveCanvasMarkers(config, existing);
+        }
+    }
+    removeGoneAdaptiveAssetMarkers(existing, config) {
+        const incomingMarkerIds = collectFeatureIdSet(config.features);
+        const adaptiveDomMarkers = this.adaptiveMarkerIndex.get(config.id) ?? new Map();
+        const result = removeGoneIndexedMarkers({
+            incomingFeatureIds: incomingMarkerIds,
+            markerIndex: adaptiveDomMarkers,
+            markers: existing.markers,
+            portalDescriptors: this.markerPortalDescriptors,
+            sourceId: config.id,
+            detachMarker: marker => {
+                marker.map = null;
+                this.clusterEntitiesByMarker.delete(marker);
+            },
+        });
+        existing.markers = result.markers;
+        if (result.portalDescriptorsChanged) {
+            this.markerPortalDescriptors = result.portalDescriptors;
+            this.notifyMarkerPortalSubscribers();
+        }
+        this.adaptiveMarkerIndex.set(config.id, result.markerIndex);
+    }
+    removeGoneServerClusterMarkers(existing, config) {
+        if (config.kind !== "marker")
+            return;
+        const incomingClusterIds = collectFeatureIdSet(config.clusterFeatures);
+        const clusterMarkers = this.clusterMarkerIndex.get(config.id) ?? new Map();
+        const result = removeGoneIndexedMarkers({
+            incomingFeatureIds: incomingClusterIds,
+            markerIndex: clusterMarkers,
+            markers: existing.markers,
+            portalDescriptors: this.clusterPortalDescriptors,
+            sourceId: config.id,
+            detachMarker: marker => {
+                marker.map = null;
+                this.clusterEntitiesByMarker.delete(marker);
+            },
+        });
+        existing.markers = result.markers;
+        if (result.portalDescriptorsChanged) {
+            this.clusterPortalDescriptors = result.portalDescriptors;
+            this.notifyClusterPortalSubscribers();
+        }
+        this.clusterMarkerIndex.set(config.id, result.markerIndex);
+    }
+    syncServerClusterMarkers(existing, config) {
+        if (this.map === null)
+            return;
+        if (config.kind !== "marker" || config.clusterFeatures === null)
+            return;
+        const clusterMarkers = this.clusterMarkerIndex.get(config.id) ?? new Map();
+        const clusterRender = config.clusterRender;
+        for (const feature of config.clusterFeatures.features) {
+            if (feature.id === undefined)
+                continue;
+            const featureId = String(feature.id);
+            const coords = extractPointCoordinates(feature);
+            if (coords === null)
+                continue;
+            const props = feature.properties;
+            const rawMarkerIds = props !== null ? props.markerIds : undefined;
+            const markerIds = Array.isArray(rawMarkerIds) ? rawMarkerIds : [];
+            const clusterBbox = props && props.bbox !== null ? validateBbox(props.bbox) : null;
+            const existingMarker = clusterMarkers.get(featureId);
+            if (existingMarker === undefined) {
+                const marker = this.createClusterMarkerForFeature(feature, coords, config, this.map);
+                existing.markers.push(marker);
+                clusterMarkers.set(featureId, marker);
+                this.attachClusterInteractionListeners(marker, featureId, { lng: coords.lng, lat: coords.lat }, markerIds, clusterBbox, existing);
+                continue;
+            }
+            existingMarker.position = { lng: coords.lng, lat: coords.lat };
+            this.updateClusterMarkerEntity(existingMarker, featureId, coords, markerIds, clusterBbox);
+            if (clusterRender !== null && clusterRender.mode === "dom") {
+                const result = patchPortalDescriptors(this.clusterPortalDescriptors, config.id, [feature], clusterRender.render);
+                if (result.changed) {
+                    this.clusterPortalDescriptors = result.descriptors;
+                    this.notifyClusterPortalSubscribers();
+                }
+            }
+        }
+        this.clusterMarkerIndex.set(config.id, clusterMarkers);
+    }
+    /**
+     * Incrementally update adaptive DOM markers and the canvas symbol overlay
+     * when `adaptiveResolution` (or callbacks) changed but feature IDs are the same.
+     *
+     * Three phases:
+     * 1. DOM → symbol: detach DOM marker + remove portal for features leaving DOM mode.
+     * 2. Symbol → DOM: add DOM marker + portal for features entering DOM mode.
+     * 3. DOM → DOM: update portal renderFn (so the consumer's latest closure runs).
+     * 4. Update canvas symbol overlay 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 = getAdaptiveDomFeatureIds(existing.config);
+        const incomingDomIds = getAdaptiveDomFeatureIds(config);
+        const incomingResolution = config.adaptiveResolution;
+        const adaptiveDomMarkers = this.adaptiveMarkerIndex.get(config.id) ?? new Map();
+        // Canvas only needs a repaint when the render function changed (e.g. activeState flip),
+        // features data changed (new poll), or the DOM/symbol split changes (phases 1 or 2 below).
+        // Skipping when only adaptiveResolution is a new-but-equal Map (pan frame) prevents
+        // double-painting at 60 fps on top of Google Maps' own draw calls.
+        let canvasNeedsUpdate = existing.config.markerRender.render !== config.markerRender.render ||
+            existing.config.features !== config.features;
+        // ---- Phase 1: DOM → symbol — detach DOM marker + remove portal ----
+        for (const featureId of existingDomIds) {
+            if (incomingDomIds.has(featureId))
+                continue;
+            canvasNeedsUpdate = true;
+            const marker = adaptiveDomMarkers.get(featureId);
+            if (marker !== undefined) {
+                marker.map = null;
+                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 = extractPointCoordinates(feature);
+            if (coords === null)
+                continue;
+            const data = extractSourceData(feature.properties);
+            const renderFn = buildAdaptiveDomRenderFn(markerRender.render);
+            const domMarker = this.createDomMarker(featureId, coords, config.id, data, renderFn, this.map, "marker", markerRender.anchor, markerRender.pixelOffset, DOM_MARKER_Z_INDEX);
+            domMarker.zIndex = DOM_MARKER_Z_INDEX;
+            existing.markers.push(domMarker);
+            adaptiveDomMarkers.set(featureId, domMarker);
+            if (featureId !== "")
+                phase2DomCreated.add(featureId);
+            canvasNeedsUpdate = true;
+            this.attachMarkerInteractionListeners(domMarker, featureId, coords, existing);
+        }
+        // ---- Phase 3: DOM → DOM — update portal renderFn ----
+        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 = extractPointCoordinates(feature);
+                if (coords !== null) {
+                    const oldFeature = existing.config.features.features.find(f => f.id !== undefined && String(f.id) === featureId);
+                    const oldCoords = oldFeature !== undefined ? extractPointCoordinates(oldFeature) : null;
+                    if (oldCoords === null || oldCoords.lng !== coords.lng || oldCoords.lat !== coords.lat) {
+                        marker.position = { lng: coords.lng, lat: coords.lat };
+                    }
+                }
+            }
+            const renderFn = 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: extractSourceData(feature.properties) };
+                    portalsChanged = true;
+                }
+            }
+        }
+        if (portalsChanged) {
+            this.markerPortalDescriptors = updatedPortals;
+            this.notifyMarkerPortalSubscribers();
+        }
+        this.adaptiveMarkerIndex.set(config.id, adaptiveDomMarkers);
+        // ---- Phase 4: Update canvas symbol overlay ----
+        if (canvasNeedsUpdate) {
+            this.updateAdaptiveCanvasMarkers(config, existing);
+        }
+    }
+    /**
+     * Repaint the canvas symbol overlay for a `mode: "symbol"` layer after the
+     * render function changed (e.g. activeState flip). Rebuilds `canvasMarkers`
+     * in-place so the draw closure reflects the new style, then triggers draw().
+     */
+    updateSymbolCanvasMarkers(config, tracked) {
+        const { markerRender } = config;
+        if (markerRender.mode !== "symbol")
+            return;
+        if (tracked.canvasMarkers === undefined || tracked.canvasOverlay === undefined)
+            return;
+        const symbolState = {
+            medium: "symbol",
+            selected: false,
+            hovered: false,
+            theme: this.theme,
+        };
+        const styleFn = (item) => markerRender.render(item, symbolState);
+        const canvasMarkers = tracked.canvasMarkers;
+        canvasMarkers.length = 0;
+        for (const feature of config.features.features) {
+            const coords = extractPointCoordinates(feature);
+            if (coords === null)
+                continue;
+            const featureId = feature.id !== undefined ? String(feature.id) : undefined;
+            const resolved = resolveCircleSymbolDefaults(resolveSymbolDescriptor(styleFn, feature.properties));
+            canvasMarkers.push({
+                lat: coords.lat,
+                lng: coords.lng,
+                featureId: featureId ?? "",
+                resolved,
+            });
+        }
+        tracked.canvasOverlay.draw();
+    }
+    /**
+     * Update the canvas symbol overlay for an adaptive marker layer by mutating
+     * the `canvasMarkers` array in-place (the canvas `draw()` closure captures
+     * the same array reference) and triggering an immediate redraw.
+     */
+    updateAdaptiveCanvasMarkers(config, tracked) {
+        const { markerRender } = config;
+        if (markerRender.mode !== "adaptive")
+            return;
+        if (tracked.canvasMarkers === undefined || tracked.canvasOverlay === undefined)
+            return;
+        const promotedIds = getAdaptiveDomFeatureIds(config);
+        const symbolState = {
+            medium: "symbol",
+            selected: false,
+            hovered: false,
+            theme: this.theme,
+        };
+        const styleFn = buildAdaptiveSymbolStyleFn(markerRender.render, symbolState);
+        // Mutate in-place so the canvas closure's captured reference reflects the update
+        const canvasMarkers = tracked.canvasMarkers;
+        canvasMarkers.length = 0;
+        for (const feature of config.features.features) {
+            const coords = extractPointCoordinates(feature);
+            if (coords === null)
+                continue;
+            const featureId = feature.id !== undefined ? String(feature.id) : undefined;
+            if (featureId !== undefined && promotedIds.has(featureId))
+                continue;
+            const resolved = resolveCircleSymbolDefaults(resolveSymbolDescriptor(styleFn, feature.properties));
+            canvasMarkers.push({
+                lat: coords.lat,
+                lng: coords.lng,
+                featureId: featureId ?? "",
+                resolved,
+            });
+        }
+        tracked.canvasOverlay.draw();
+    }
+    // ============================================================================
+    // 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 = resolveCircleSymbolDefaults(resolveSymbolDescriptor(item => markerRender.render(item, symbolState), feature.properties));
+                const el = createSymbolDotElement(resolved);
+                el.style.transform = anchorFromBottomCenter("center");
+                return new google.maps.marker.AdvancedMarkerElement({
+                    map,
+                    position: coords,
+                    content: el,
+                });
+            }
+            case "dom": {
+                return this.createDomMarker(featureId, coords, config.id, 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 = buildAdaptiveSymbolStyleFn(markerRender.render, symbolState);
+                const resolved = resolveCircleSymbolDefaults(resolveSymbolDescriptor(styleFn, feature.properties));
+                const el = createSymbolDotElement(resolved);
+                el.style.transform = anchorFromBottomCenter("center");
+                return new google.maps.marker.AdvancedMarkerElement({
+                    map,
+                    position: coords,
+                    content: el,
+                });
+            }
+            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) {
+            return new google.maps.marker.AdvancedMarkerElement({
+                map,
+                position: coords,
+                content: createDefaultClusterElement(clusterCount),
+            });
+        }
+        switch (clusterRender.mode) {
+            case "symbol": {
+                const clusterState = {
+                    selected: false,
+                    hovered: false,
+                    theme: this.theme,
+                    memberItems: null,
+                };
+                const descriptor = resolveSymbolDescriptor(item => clusterRender.render(item, clusterState), feature.properties);
+                return new google.maps.marker.AdvancedMarkerElement({
+                    map,
+                    position: coords,
+                    content: createClusterPinElement(descriptor, clusterCount),
+                });
+            }
+            case "dom": {
+                return this.createDomMarker(featureId, coords, config.id, extractSourceData(feature.properties), clusterRender.render, map, "cluster", clusterRender.anchor, clusterRender.pixelOffset);
+            }
+            default: {
+                throw new Error(`${clusterRender} is not known`);
+            }
+        }
+    }
+    /**
+     * Create an AdvancedMarkerElement 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, nativeZIndexOffset = 0) {
+        const container = document.createElement("div");
+        container.style.pointerEvents = "auto";
+        fadeInElement(container);
+        const transforms = [anchorFromBottomCenter(anchor)];
+        if (pixelOffset !== undefined)
+            transforms.push(`translate(${pixelOffset.x}px, ${pixelOffset.y}px)`);
+        container.style.transform = transforms.join(" ");
+        const marker = new google.maps.marker.AdvancedMarkerElement({
+            map,
+            position: coords,
+            content: container,
+        });
+        const descriptor = {
+            key: `${sourceId}:${featureId}`,
+            sourceId,
+            container,
+            setZIndex: zIndex => {
+                marker.zIndex = nativeZIndexOffset + zIndex;
+            },
+            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 buildAdaptiveDomEntries(config, (fId, c, sourceId, data, renderFn) => this.createDomMarker(fId, c, sourceId, data, renderFn, map, "marker", adaptiveAnchor, adaptivePixelOffset, DOM_MARKER_Z_INDEX))) {
+            domMarker.zIndex = DOM_MARKER_Z_INDEX;
+            tracked.markers.push(domMarker);
+            if (featureId !== "") {
+                this.attachMarkerInteractionListeners(domMarker, featureId, coords, tracked);
+                adaptiveDomMarkers.set(featureId, domMarker);
+            }
+        }
+        this.adaptiveMarkerIndex.set(config.id, adaptiveDomMarkers);
+    }
+    // ============================================================================
+    // Private: Canvas overlay for symbol/adaptive rendering
+    // ============================================================================
+    /**
+     * Set up a canvas-based OverlayView that draws all symbol markers in a
+     * single pass, replacing the per-element Data layer approach.
+     * For adaptive mode, DOM-rendered features are excluded (rendered as DOM overlays).
+     */
+    setupCanvasSymbolOverlay(config, map, tracked) {
+        const { markerRender } = config;
+        if (markerRender.mode !== "symbol" && markerRender.mode !== "adaptive")
+            return;
+        const promotedIds = getAdaptiveDomFeatureIds(config);
+        const symbolState = {
+            medium: "symbol",
+            selected: false,
+            hovered: false,
+            theme: this.theme,
+        };
+        const styleFn = markerRender.mode === "symbol"
+            ? item => markerRender.render(item, symbolState)
+            : buildAdaptiveSymbolStyleFn(markerRender.render, symbolState);
+        const canvasMarkers = [];
+        for (const feature of config.features.features) {
+            const coords = extractPointCoordinates(feature);
+            if (coords === null)
+                continue;
+            const featureId = feature.id !== undefined ? String(feature.id) : undefined;
+            if (featureId !== undefined && promotedIds.has(featureId))
+                continue;
+            const resolved = resolveCircleSymbolDefaults(resolveSymbolDescriptor(styleFn, feature.properties));
+            canvasMarkers.push({
+                lat: coords.lat,
+                lng: coords.lng,
+                featureId: featureId ?? "",
+                resolved,
+            });
+        }
+        tracked.canvasMarkers = canvasMarkers;
+        const layerPort = this;
+        let lastHoveredFeatureId = null;
+        let drawnMarkers = [];
+        class CanvasSymbolOverlay extends google.maps.OverlayView {
+            constructor() {
+                super(...arguments);
+                this.boundsDeferScheduled = false;
+                this.canvas = null;
+                this.handleClick = (event) => {
+                    const hit = this.findHit(event);
+                    if (hit === null)
+                        return;
+                    layerPort.emitEntityInteraction("click", {
+                        type: "marker",
+                        id: hit.featureId,
+                        position: [hit.lng, hit.lat],
+                        clusterId: null,
+                    });
+                };
+                this.handleDblClick = (event) => {
+                    event.stopPropagation();
+                    const hit = this.findHit(event);
+                    if (hit === null)
+                        return;
+                    layerPort.suppressNativeZoom();
+                    layerPort.emitEntityInteraction("dblclick", {
+                        type: "marker",
+                        id: hit.featureId,
+                        position: [hit.lng, hit.lat],
+                        clusterId: null,
+                    });
+                };
+                this.handleMouseMove = (event) => {
+                    const hit = this.findHit(event);
+                    const hitId = hit !== null ? hit.featureId : null;
+                    if (hitId === lastHoveredFeatureId)
+                        return;
+                    if (lastHoveredFeatureId !== null) {
+                        layerPort.emitEntityInteraction("hover-end", {
+                            type: "marker",
+                            id: lastHoveredFeatureId,
+                            position: [0, 0],
+                            clusterId: null,
+                        });
+                    }
+                    lastHoveredFeatureId = hitId;
+                    if (hit !== null) {
+                        layerPort.emitEntityInteraction("hover-start", {
+                            type: "marker",
+                            id: hit.featureId,
+                            position: [hit.lng, hit.lat],
+                            clusterId: null,
+                        });
+                    }
+                    if (this.canvas !== null) {
+                        this.canvas.style.cursor = hit !== null ? MAP_CURSORS.interactive : MAP_CURSORS.default;
+                    }
+                };
+                this.handleMouseLeave = () => {
+                    if (lastHoveredFeatureId !== null) {
+                        layerPort.emitEntityInteraction("hover-end", {
+                            type: "marker",
+                            id: lastHoveredFeatureId,
+                            position: [0, 0],
+                            clusterId: null,
+                        });
+                        lastHoveredFeatureId = null;
+                    }
+                    if (this.canvas !== null) {
+                        this.canvas.style.cursor = MAP_CURSORS.default;
+                    }
+                };
+            }
+            onAdd() {
+                const canvas = document.createElement("canvas");
+                canvas.style.position = "absolute";
+                canvas.style.pointerEvents = "auto";
+                const panes = this.getPanes();
+                if (panes !== null) {
+                    panes.overlayMouseTarget.appendChild(canvas);
+                }
+                this.canvas = canvas;
+                canvas.addEventListener("click", this.handleClick);
+                canvas.addEventListener("dblclick", this.handleDblClick);
+                canvas.addEventListener("mousemove", this.handleMouseMove);
+                canvas.addEventListener("mouseleave", this.handleMouseLeave);
+            }
+            draw() {
+                const canvas = this.canvas;
+                if (canvas === null)
+                    return;
+                const projection = this.getProjection();
+                const bounds = map.getBounds();
+                const pad = CANVAS_VIEWPORT_PADDING;
+                const dpr = window.devicePixelRatio || 1;
+                let originX;
+                let originY;
+                let width;
+                let height;
+                if (bounds) {
+                    const ne = projection.fromLatLngToDivPixel(bounds.getNorthEast());
+                    const sw = projection.fromLatLngToDivPixel(bounds.getSouthWest());
+                    if (ne !== null && sw !== null && ne.x - sw.x > 1 && sw.y - ne.y > 1) {
+                        width = ne.x - sw.x + pad * 2;
+                        height = sw.y - ne.y + pad * 2;
+                        originX = sw.x - pad;
+                        originY = ne.y - pad;
+                    }
+                }
+                // When multiple <Map> components coexist on one page with mapId
+                // (vector maps), some google.maps.Map instances end up with a
+                // detached getDiv() (0×0, no parentElement), causing getBounds()
+                // to return undefined permanently. Fall back to sizing the canvas
+                // from the actual marker positions so rendering still works.
+                if (width === undefined) {
+                    let minX = Infinity;
+                    let minY = Infinity;
+                    let maxX = -Infinity;
+                    let maxY = -Infinity;
+                    for (const entry of canvasMarkers) {
+                        const pt = projection.fromLatLngToDivPixel(new google.maps.LatLng(entry.lat, entry.lng));
+                        if (pt === null)
+                            continue;
+                        if (pt.x < minX)
+                            minX = pt.x;
+                        if (pt.y < minY)
+                            minY = pt.y;
+                        if (pt.x > maxX)
+                            maxX = pt.x;
+                        if (pt.y > maxY)
+                            maxY = pt.y;
+                    }
+                    if (!isFinite(minX)) {
+                        if (!this.boundsDeferScheduled) {
+                            this.boundsDeferScheduled = true;
+                            requestAnimationFrame(() => {
+                                if (this.getMap() !== null)
+                                    this.draw();
+                            });
+                        }
+                        return;
+                    }
+                    originX = minX - pad;
+                    originY = minY - pad;
+                    width = maxX - minX + pad * 2;
+                    height = maxY - minY + pad * 2;
+                }
+                if (originX === undefined || originY === undefined || height === undefined)
+                    return;
+                this.boundsDeferScheduled = false;
+                canvas.style.left = `${originX}px`;
+                canvas.style.top = `${originY}px`;
+                canvas.style.width = `${width}px`;
+                canvas.style.height = `${height}px`;
+                canvas.width = width * dpr;
+                canvas.height = height * dpr;
+                const ctx = canvas.getContext("2d");
+                if (ctx === null)
+                    return;
+                ctx.scale(dpr, dpr);
+                ctx.clearRect(0, 0, width, height);
+                const nextDrawnMarkers = [];
+                for (const entry of canvasMarkers) {
+                    const point = projection.fromLatLngToDivPixel(new google.maps.LatLng(entry.lat, entry.lng));
+                    if (point === null)
+                        continue;
+                    const x = point.x - originX;
+                    const y = point.y - originY;
+                    const { resolved } = entry;
+                    const radius = resolved.radiusPx;
+                    ctx.globalAlpha = resolved.opacity;
+                    ctx.beginPath();
+                    ctx.arc(x, y, radius, 0, Math.PI * 2);
+                    ctx.fillStyle = resolved.color;
+                    ctx.fill();
+                    if (resolved.hasBorder && resolved.borderColor !== null) {
+                        ctx.strokeStyle = resolved.borderColor;
+                        ctx.lineWidth = resolved.borderWidthPx;
+                        ctx.stroke();
+                    }
+                    nextDrawnMarkers.push({ x, y, radius, entry });
+                }
+                ctx.globalAlpha = 1;
+                drawnMarkers = nextDrawnMarkers;
+            }
+            onRemove() {
+                if (this.canvas !== null) {
+                    this.canvas.removeEventListener("click", this.handleClick);
+                    this.canvas.removeEventListener("dblclick", this.handleDblClick);
+                    this.canvas.removeEventListener("mousemove", this.handleMouseMove);
+                    this.canvas.removeEventListener("mouseleave", this.handleMouseLeave);
+                    this.canvas.remove();
+                    this.canvas = null;
+                }
+                drawnMarkers = [];
+            }
+            findHit(event) {
+                const canvas = this.canvas;
+                if (canvas === null)
+                    return null;
+                const rect = canvas.getBoundingClientRect();
+                const mouseX = event.clientX - rect.left;
+                const mouseY = event.clientY - rect.top;
+                let closestEntry = null;
+                let closestDist = Infinity;
+                for (const drawn of drawnMarkers) {
+                    const dx = mouseX - drawn.x;
+                    const dy = mouseY - drawn.y;
+                    const dist = Math.sqrt(dx * dx + dy * dy);
+                    if (dist <= drawn.radius && dist < closestDist) {
+                        closestDist = dist;
+                        closestEntry = drawn.entry;
+                    }
+                }
+                return closestEntry;
+            }
+        }
+        const overlay = new CanvasSymbolOverlay();
+        overlay.setMap(map);
+        tracked.canvasOverlay = overlay;
+    }
+    // ============================================================================
+    // Private: Client-side clustering
+    // ============================================================================
+    /**
+     * Set up client-side clustering using @googlemaps/markerclusterer.
+     * Creates AdvancedMarkerElement instances for all point features and
+     * hands them to a MarkerClusterer which manages their visibility
+     * based on zoom level.
+     */
+    setupClientClustering(config, map, tracked) {
+        const { clusterConfig, clusterRender } = config;
+        if (clusterConfig === null || clusterConfig.mode !== "client")
+            return;
+        // Create individual markers (the clusterer manages adding/removing from map)
+        const clusterableMarkers = [];
+        for (const feature of config.features.features) {
+            const coords = extractPointCoordinates(feature);
+            if (coords === null)
+                continue;
+            const marker = this.createMarkerForFeature(feature, coords, config, map);
+            // Store feature ID on the marker element for cluster interaction lookup
+            const featureId = feature.id !== undefined ? String(feature.id) : undefined;
+            if (featureId !== undefined) {
+                marker.dataset.featureId = featureId;
+            }
+            clusterableMarkers.push(marker);
+            tracked.markers.push(marker);
+            // Interaction listeners for individual markers
+            if (featureId !== undefined) {
+                this.attachMarkerInteractionListeners(marker, featureId, coords, tracked);
+            }
+        }
+        // Build the custom cluster renderer
+        const layerPort = this;
+        const sourceId = config.id;
+        const renderer = {
+            render(cluster, _stats, _map) {
+                const count = cluster.count;
+                const position = cluster.position;
+                // Collect marker IDs from the cluster's markers
+                const markerIds = collectFeatureIdsFromCluster(cluster);
+                let content;
+                if (clusterRender !== null && clusterRender.mode === "symbol") {
+                    const clusterState = {
+                        selected: false,
+                        hovered: false,
+                        theme: layerPort.theme,
+                        memberItems: null,
+                    };
+                    const style = clusterRender.render({ id: "", position: [position.lng(), position.lat()], markerIds, count, bbox: null }, clusterState);
+                    content = createClusterPinElement(style, count);
+                }
+                else if (clusterRender !== null) {
+                    // DOM cluster rendering via portals (mode === "dom" by elimination —
+                    // ClusterRenderConfig has no other variants per ADR-0016).
+                    const container = document.createElement("div");
+                    container.style.pointerEvents = "auto";
+                    const clusterId = `cluster-${position.lat().toFixed(6)}-${position.lng().toFixed(6)}`;
+                    layerPort.addClusterPortalDescriptor({
+                        key: `${sourceId}:${clusterId}`,
+                        sourceId,
+                        container,
+                        featureId: clusterId,
+                        sourceData: {
+                            id: clusterId,
+                            position: [position.lng(), position.lat()],
+                            markerIds,
+                            count,
+                            bbox: null,
+                        },
+                        renderFn: clusterRender.render,
+                    });
+                    content = container;
+                }
+                else {
+                    content = createDefaultClusterElement(count);
+                }
+                const clusterMarker = new google.maps.marker.AdvancedMarkerElement({
+                    position,
+                    content,
+                    zIndex: 1000 + count,
+                });
+                // Cluster interaction listeners
+                const entity = {
+                    type: "cluster",
+                    id: `cluster-${position.lat().toFixed(6)}-${position.lng().toFixed(6)}`,
+                    position: [position.lng(), position.lat()],
+                    markerIds,
+                    bbox: null,
+                };
+                const hoverTarget = clusterMarker.element;
+                hoverTarget.addEventListener("mouseenter", () => {
+                    layerPort.emitEntityInteraction("hover-start", entity);
+                });
+                hoverTarget.addEventListener("mouseleave", () => {
+                    layerPort.emitEntityInteraction("hover-end", entity);
+                });
+                return clusterMarker;
+            },
+        };
+        // Handle cluster click at the MarkerClusterer level
+        const onClusterClick = (_event, cluster, _clusterMap) => {
+            const position = cluster.position;
+            const markerIds = collectFeatureIdsFromCluster(cluster);
+            this.emitEntityInteraction("click", {
+                type: "cluster",
+                id: `cluster-${position.lat().toFixed(6)}-${position.lng().toFixed(6)}`,
+                position: [position.lng(), position.lat()],
+                markerIds,
+                bbox: null,
+            });
+        };
+        const clusterer = new MarkerClusterer({
+            map,
+            markers: clusterableMarkers,
+            algorithm: new SuperClusterAlgorithm({
+                radius: clusterConfig.radius ?? 50,
+                maxZoom: clusterConfig.maxZoom ?? 14,
+            }),
+            renderer,
+            onClusterClick,
+        });
+        tracked.clusterer = clusterer;
+    }
+    // ============================================================================
+    // Private: Feature-to-shape mapping
+    // ============================================================================
+    pushToFeatureMap(map, featureId, value) {
+        const existing = map.get(featureId);
+        if (existing !== undefined) {
+            existing.push(value);
+        }
+        else {
+            map.set(featureId, [value]);
+        }
+    }
+    // ============================================================================
+    // Private: Unified shape interaction styling
+    // ============================================================================
+    /**
+     * Re-apply all interaction-sensitive styles for every feature in the given
+     * shape source. Priority: selected > hovered > base.
+     *
+     * Called whenever hover, selection, or theme changes on the given handleId.
+     * When neither hover nor selection targets a feature, it reverts to its base style.
+     */
+    applyGoogleShapeInteraction(handleId) {
+        const tracked = this.shapeSources.get(handleId);
+        if (tracked === undefined)
+            return;
+        const { style, featureStyles } = tracked.config;
+        const selId = this.selectedShapeHandleId === handleId ? this.selectedShapeFeatureId : null;
+        const hovId = this.hoveredShapeHandleId === handleId ? this.hoveredShapeFeatureId : null;
+        let selectedOverrides = null;
+        if (selId !== null) {
+            const fs = featureStyles?.get(selId) ?? style;
+            selectedOverrides = resolveSelectedStyle(fs, "polygon", this.theme);
+        }
+        let hoveredOverrides = null;
+        if (hovId !== null) {
+            const fs = featureStyles?.get(hovId) ?? style;
+            hoveredOverrides = resolveHoveredStyle(fs, "polygon", this.theme);
+        }
+        const resolveForFeature = (featureId) => {
+            if (featureId === selId)
+                return selectedOverrides;
+            if (featureId === hovId)
+                return hoveredOverrides;
+            return null;
+        };
+        for (const [featureId, shapes] of tracked.featureIdToShapes) {
+            const overrides = resolveForFeature(featureId);
+            const base = featureStyles?.get(featureId) ?? style;
+            for (const shape of shapes) {
+                if ("getPaths" in shape) {
+                    // Fill-only tiled polygons (ADR-0021) carry no stroke — their outline is a
+                    // separate polyline. Restyle only the fill so hover/select never paints a
+                    // stroke back onto them.
+                    if (tracked.fillOnlyShapes.has(shape)) {
+                        shape.setOptions({
+                            fillColor: overrides?.fill ?? base.fill ?? "rgba(0,0,0,0.1)",
+                            fillOpacity: overrides?.fillOpacity ?? base.fillOpacity ?? this.shapeStyleDefaults.polygon.fillOpacity,
+                        });
+                        continue;
+                    }
+                    shape.setOptions({
+                        fillColor: overrides?.fill ?? base.fill ?? "rgba(0,0,0,0.1)",
+                        fillOpacity: overrides?.fillOpacity ?? base.fillOpacity ?? this.shapeStyleDefaults.polygon.fillOpacity,
+                        strokeColor: overrides?.stroke ?? base.stroke ?? "#000000",
+                        strokeWeight: overrides?.strokeWidth ?? base.strokeWidth ?? this.shapeStyleDefaults.polygon.strokeWidth,
+                        strokeOpacity: overrides?.strokeOpacity ?? base.strokeOpacity ?? this.shapeStyleDefaults.polygon.strokeOpacity,
+                    });
+                }
+                else {
+                    shape.setOptions({
+                        strokeColor: overrides?.stroke ?? base.stroke ?? "#000000",
+                        strokeWeight: overrides?.strokeWidth ?? base.strokeWidth ?? this.shapeStyleDefaults.line.strokeWidth,
+                        strokeOpacity: overrides?.strokeOpacity ?? base.strokeOpacity ?? this.shapeStyleDefaults.line.strokeOpacity,
+                    });
+                }
+            }
+        }
+        for (const [featureId, pointMarkers] of tracked.featureIdToPointMarkers) {
+            const overrides = resolveForFeature(featureId);
+            const base = featureStyles?.get(featureId) ?? style;
+            for (const marker of pointMarkers) {
+                const el = marker.content;
+                if (!(el instanceof HTMLElement))
+                    continue;
+                const fillOpacity = overrides?.fillOpacity ?? base.fillOpacity ?? this.shapeStyleDefaults.point.fillOpacity;
+                const strokeOpacity = overrides?.strokeOpacity ?? base.strokeOpacity ?? this.shapeStyleDefaults.point.strokeOpacity;
+                el.style.backgroundColor = colorWithOpacity(overrides?.fill ?? base.fill ?? "rgba(0,0,0,0.1)", fillOpacity);
+                el.style.borderColor = colorWithOpacity(overrides?.stroke ?? base.stroke ?? "#000", strokeOpacity);
+                el.style.borderWidth = `${overrides?.strokeWidth ?? base.strokeWidth ?? this.shapeStyleDefaults.point.strokeWidth}px`;
+            }
+        }
+    }
+    // ============================================================================
+    // Private: Shape creation
+    // ============================================================================
+    createPolygon(paths, style, map, clickable = true, zIndex) {
+        return new google.maps.Polygon({
+            paths,
+            map,
+            fillColor: style.fill ?? "rgba(0,0,0,0.1)",
+            fillOpacity: style.fillOpacity ?? this.shapeStyleDefaults.polygon.fillOpacity,
+            strokeColor: style.stroke ?? "#000000",
+            strokeWeight: style.strokeWidth ?? this.shapeStyleDefaults.polygon.strokeWidth,
+            strokeOpacity: style.strokeOpacity ?? this.shapeStyleDefaults.polygon.strokeOpacity,
+            clickable,
+            ...(zIndex !== undefined ? { zIndex } : {}),
+        });
+    }
+    createPolyline(path, style, map, zIndex) {
+        return new google.maps.Polyline({
+            path,
+            map,
+            strokeColor: style.stroke ?? "#000000",
+            strokeWeight: style.strokeWidth ?? this.shapeStyleDefaults.line.strokeWidth,
+            strokeOpacity: style.strokeOpacity ?? this.shapeStyleDefaults.line.strokeOpacity,
+            clickable: true,
+            ...(zIndex !== undefined ? { zIndex } : {}),
+        });
+    }
+    /**
+     * Fill-only polygon (no stroke) for ADR-0021 fill tiling: the fill comes from
+     * clipped geometry while the full outline is drawn separately as polylines.
+     * An optional `zIndex` controls the Google Maps rendering order for hover promotion.
+     */
+    createFillOnlyPolygon(paths, style, map, clickable, zIndex) {
+        return new google.maps.Polygon({
+            paths,
+            map,
+            fillColor: style.fill ?? "rgba(0,0,0,0.1)",
+            fillOpacity: style.fillOpacity ?? this.shapeStyleDefaults.polygon.fillOpacity,
+            strokeWeight: 0,
+            strokeOpacity: 0,
+            clickable,
+            ...(zIndex !== undefined ? { zIndex } : {}),
+        });
+    }
+    /**
+     * Render a polygonal feature whose fill is tiled (ADR-0021): the visible
+     * outline is drawn from the feature's full geometry as polylines (so it stays
+     * complete through covering neighbours), and the fill is drawn from the
+     * clipped geometry as fill-only polygons. A fully covered loser yields no fill
+     * polygon — just its outline.
+     */
+    renderTiledPolygonFeature(fullGeometry, fillGeometry, style, fid, isStrokeOnly, config, tracked, map) {
+        const polygonParts = (geometry) => {
+            if (geometry.type === "Polygon")
+                return [geometry.coordinates];
+            if (geometry.type === "MultiPolygon")
+                return geometry.coordinates;
+            return [];
+        };
+        // Outline polylines from the full geometry — one per ring, closed.
+        for (const partCoords of polygonParts(fullGeometry)) {
+            const paths = extractPolygonPaths(partCoords);
+            if (paths === null)
+                continue;
+            for (const ring of paths) {
+                if (ring.length < 2)
+                    continue;
+                const first = ring[0];
+                if (first === undefined)
+                    continue;
+                const outline = this.createPolyline([...ring, first], style, map, TILED_OUTLINE_Z_INDEX);
+                tracked.shapes.push(outline);
+                this.pushToFeatureMap(tracked.featureIdToShapes, fid, outline);
+                if (config.interactive !== "none") {
+                    this.attachShapeInteractionListeners(outline, fid, "polygon", tracked, config.id);
+                }
+            }
+        }
+        // Fill-only polygons from the clipped geometry.
+        const fillVisible = (style.fillOpacity ?? this.shapeStyleDefaults.polygon.fillOpacity) > 0;
+        const fillClickable = !isStrokeOnly && fillVisible && config.interactive !== "none";
+        const fillZIndex = config.featureZIndexOverrides?.get(fid);
+        for (const partCoords of polygonParts(fillGeometry)) {
+            const paths = extractPolygonPaths(partCoords);
+            if (paths === null)
+                continue;
+            const fillPolygon = this.createFillOnlyPolygon(paths, style, map, fillClickable, fillZIndex);
+            tracked.shapes.push(fillPolygon);
+            tracked.fillOnlyShapes.add(fillPolygon);
+            this.pushToFeatureMap(tracked.featureIdToShapes, fid, fillPolygon);
+            if (fillClickable) {
+                this.attachShapeInteractionListeners(fillPolygon, fid, "polygon", tracked, config.id);
+            }
+        }
+    }
+    /**
+     * Create invisible polylines tracing each ring of a polygon's paths.
+     * Used as hit targets for stroke-only interaction mode — Google natively
+     * shows pointer cursor on clickable polylines, giving correct cursor
+     * behaviour without manual hit-testing.
+     *
+     * `geodesic` must match the parent polygon so hit areas align with the
+     * visible stroke.
+     */
+    createStrokeHitPolylines(paths, strokeWeight, map, geodesic = true) {
+        const hitWeight = Math.max(strokeWeight, 3);
+        const polylines = [];
+        for (const ring of paths) {
+            if (ring.length < 2)
+                continue;
+            const first = ring[0];
+            if (first === undefined)
+                continue;
+            const closedPath = [...ring, first];
+            polylines.push(new google.maps.Polyline({
+                path: closedPath,
+                map,
+                strokeOpacity: 0,
+                strokeWeight: hitWeight,
+                geodesic,
+                clickable: true,
+            }));
+        }
+        return polylines;
+    }
+    createShapePointMarker(position, style, map) {
+        const diameter = (style.pointRadius ?? this.shapeStyleDefaults.point.pointRadius) * 2;
+        const el = document.createElement("div");
+        el.style.boxSizing = "content-box";
+        el.style.pointerEvents = "auto";
+        el.style.width = `${diameter}px`;
+        el.style.height = `${diameter}px`;
+        el.style.borderRadius = "50%";
+        const fillOpacity = style.fillOpacity ?? this.shapeStyleDefaults.point.fillOpacity;
+        const strokeOpacity = style.strokeOpacity ?? this.shapeStyleDefaults.point.strokeOpacity;
+        el.style.backgroundColor = colorWithOpacity(style.fill ?? "rgba(0,0,0,0.1)", fillOpacity);
+        el.style.borderWidth = `${style.strokeWidth ?? this.shapeStyleDefaults.point.strokeWidth}px`;
+        el.style.borderStyle = "solid";
+        el.style.borderColor = colorWithOpacity(style.stroke ?? "#000", strokeOpacity);
+        el.style.transform = anchorFromBottomCenter("center");
+        return new google.maps.marker.AdvancedMarkerElement({ map, position, content: el });
+    }
+    // ============================================================================
+    // Private: Route creation
+    // ============================================================================
+    createRoutePolyline(path, style, map, interactive = false) {
+        const icons = [];
+        // Direction arrows
+        if (style.showDirectionArrows === true) {
+            icons.push({
+                icon: {
+                    path: google.maps.SymbolPath.FORWARD_CLOSED_ARROW,
+                    scale: 3,
+                    strokeColor: style.color ?? "#000000",
+                    strokeWeight: 2,
+                    fillColor: style.color ?? "#000000",
+                    fillOpacity: 1,
+                },
+                offset: "0",
+                repeat: "100px",
+            });
+        }
+        // Dash pattern via icon sequence
+        const { dashArray } = style;
+        const hasDash = dashArray !== undefined && dashArray.length > 0;
+        if (hasDash) {
+            const dashOn = dashArray[0] ?? 10;
+            const dashOff = dashArray[1] ?? 10;
+            icons.push({
+                icon: {
+                    path: "M 0,-1 0,1",
+                    strokeOpacity: style.opacity ?? 1,
+                    strokeColor: style.color ?? "#000000",
+                    strokeWeight: style.width ?? 3,
+                    scale: 1,
+                },
+                offset: "0",
+                repeat: `${dashOn + dashOff}px`,
+            });
+        }
+        return new google.maps.Polyline({
+            path,
+            map,
+            strokeColor: style.color ?? "#000000",
+            strokeWeight: style.width ?? 3,
+            strokeOpacity: hasDash ? 0 : (style.opacity ?? 1),
+            icons: icons.length > 0 ? icons : undefined,
+            clickable: interactive,
+        });
+    }
+    // ============================================================================
+    // Private: Interaction listeners
+    // ============================================================================
+    attachMarkerInteractionListeners(marker, featureId, coords, tracked) {
+        const entity = {
+            type: "marker",
+            id: featureId,
+            position: [coords.lng, coords.lat],
+            clusterId: null,
+        };
+        // Click
+        const clickListener = marker.addListener("gmp-click", () => {
+            this.emitEntityInteraction("click", entity);
+        });
+        tracked.listeners.push(clickListener);
+        // Hover and dblclick via DOM events on the marker's outer element.
+        // marker.element is the outer <gmp-advanced-marker> wrapper that
+        // supports standard DOM events.
+        const hoverTarget = marker.element;
+        hoverTarget.addEventListener("dblclick", (e) => {
+            e.stopPropagation();
+            this.suppressNativeZoom();
+            this.emitEntityInteraction("dblclick", entity);
+        });
+        // Hover — spurious-mouseleave-safe implementation via attachSafeAreaHoverListeners.
+        // See layerPortHelpers.ts for the full contract.
+        attachSafeAreaHoverListeners(hoverTarget, () => this.emitEntityInteraction("hover-start", entity), () => this.emitEntityInteraction("hover-end", entity), this.markerHoverState);
+    }
+    attachClusterInteractionListeners(marker, featureId, coords, markerIds, clusterBbox, tracked) {
+        this.updateClusterMarkerEntity(marker, featureId, coords, markerIds, clusterBbox);
+        const emitClusterInteraction = (type) => {
+            const entity = this.clusterEntitiesByMarker.get(marker);
+            if (entity !== undefined) {
+                this.emitEntityInteraction(type, entity);
+            }
+        };
+        const clickListener = marker.addListener("gmp-click", () => {
+            emitClusterInteraction("click");
+        });
+        tracked.listeners.push(clickListener);
+        const clusterHoverTarget = marker.element;
+        clusterHoverTarget.addEventListener("dblclick", (e) => {
+            e.stopPropagation();
+            this.suppressNativeZoom();
+            emitClusterInteraction("dblclick");
+        });
+        clusterHoverTarget.addEventListener("mouseenter", () => {
+            emitClusterInteraction("hover-start");
+        });
+        clusterHoverTarget.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);
+    }
+    attachShapeInteractionListeners(shape, featureId, shapeType, tracked, handleId) {
+        const entity = {
+            type: "shape",
+            id: featureId,
+            shapeType,
+            handleId,
+        };
+        const listeners = [
+            shape.addListener("mousedown", () => {
+                this.holdNativeZoomForDblClick();
+            }),
+            shape.addListener("click", () => {
+                this.lastShapeClickTime = Date.now();
+                this.lastShapeClickEntity = entity;
+                this.emitEntityInteraction("click", entity);
+            }),
+            shape.addListener("mouseover", () => {
+                this.emitEntityInteraction("hover-start", entity);
+            }),
+            shape.addListener("mousemove", (e) => {
+                const latLng = e.latLng;
+                if (latLng === null)
+                    return;
+                this.pointerMoveReporter?.(latLngToPosition(latLng));
+            }),
+            shape.addListener("mouseout", () => {
+                this.emitEntityInteraction("hover-end", entity);
+            }),
+        ];
+        tracked.listeners.push(...listeners);
+        tracked.shapeListeners.set(shape, listeners);
+    }
+    attachShapePointInteractionListeners(marker, featureId, shapeType, handleId) {
+        const entity = {
+            type: "shape",
+            id: featureId,
+            shapeType,
+            handleId,
+        };
+        const content = marker.content;
+        if (!(content instanceof HTMLElement))
+            return;
+        content.style.cursor = MAP_CURSORS.interactive;
+        content.addEventListener("click", () => {
+            this.emitEntityInteraction("click", entity);
+        });
+        content.addEventListener("dblclick", (e) => {
+            e.stopPropagation();
+            this.suppressNativeZoom();
+            this.emitEntityInteraction("dblclick", entity);
+        });
+        content.addEventListener("mouseenter", () => {
+            this.emitEntityInteraction("hover-start", entity);
+        });
+        content.addEventListener("mouseleave", () => {
+            this.emitEntityInteraction("hover-end", entity);
+        });
+    }
+    attachRouteInteractionListeners(polyline, featureId, feature, tracked) {
+        const waypoints = feature.geometry !== null && feature.geometry.type === "LineString"
+            ? feature.geometry.coordinates.map(c => [c[0], c[1]])
+            : [];
+        const entity = { type: "route", id: featureId, waypoints };
+        tracked.listeners.push(polyline.addListener("click", () => {
+            this.emitEntityInteraction("click", entity);
+        }));
+        tracked.listeners.push(polyline.addListener("dblclick", () => {
+            this.suppressNativeZoom();
+            this.emitEntityInteraction("dblclick", entity);
+        }));
+        tracked.listeners.push(polyline.addListener("mouseover", () => {
+            this.emitEntityInteraction("hover-start", entity);
+        }));
+        tracked.listeners.push(polyline.addListener("mouseout", () => {
+            this.emitEntityInteraction("hover-end", entity);
+        }));
+    }
+    /**
+     * Attach a DOM-level dblclick listener on the map container.
+     * Google Maps overlay events suppress the second click and dblclick when
+     * disableDoubleClickZoom is true, so we rely on the browser's own dblclick
+     * on the container instead.
+     */
+    setupMapClickListener(map) {
+        if (this.mapClickListener !== null) {
+            google.maps.event.removeListener(this.mapClickListener);
+        }
+        this.mapClickListener = map.addListener("click", () => {
+            if (!this.entityClickedInTick) {
+                this.backgroundClickHandlers.forEach(handler => handler());
+            }
+        });
+    }
+    setupMapContainerDblClickListener(map) {
+        this.mapDblClickListenerCleanup?.();
+        const container = map.getDiv();
+        const handler = () => {
+            const elapsed = Date.now() - this.lastShapeClickTime;
+            const entity = this.lastShapeClickEntity;
+            if (entity !== null && elapsed < GoogleMapsLayerPort.DBLCLICK_THRESHOLD_MS) {
+                if (this.holdNativeZoomTimer !== null) {
+                    clearTimeout(this.holdNativeZoomTimer);
+                    this.holdNativeZoomTimer = null;
+                }
+                this.suppressNativeZoom();
+                this.emitEntityInteraction("dblclick", entity);
+                this.lastShapeClickEntity = null;
+            }
+        };
+        container.addEventListener("dblclick", handler, true);
+        this.mapDblClickListenerCleanup = () => {
+            container.removeEventListener("dblclick", handler, true);
+        };
+    }
+    /**
+     * On shape mousedown, temporarily hold native zoom disabled so the browser
+     * can complete its dblclick detection without the map moving the shape.
+     * Re-enables after the dblclick threshold elapses.
+     */
+    holdNativeZoomForDblClick() {
+        if (this.map === null)
+            return;
+        const m = this.map;
+        m.set("disableDoubleClickZoom", true);
+        if (this.holdNativeZoomTimer !== null) {
+            clearTimeout(this.holdNativeZoomTimer);
+        }
+        this.holdNativeZoomTimer = setTimeout(() => {
+            m.set("disableDoubleClickZoom", false);
+            this.holdNativeZoomTimer = null;
+        }, GoogleMapsLayerPort.DBLCLICK_THRESHOLD_MS);
+    }
+    /**
+     * 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.set("disableDoubleClickZoom", true);
+        setTimeout(() => {
+            m.set("disableDoubleClickZoom", false);
+        }, 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: Reconnection (theme change creates a new map instance)
+    // ============================================================================
+    /**
+     * When the Google Maps instance is recreated (e.g. theme change), all
+     * existing Google Maps objects lose their reference to the old map.
+     * We need to re-create them on the new map.
+     *
+     * We collect the current source configs from tracked state and re-apply
+     * them. Since set*Source calls removeSource first, this cleanly replaces.
+     */
+    reconnectAllSources() {
+        // Re-assign existing markers to the new map
+        for (const tracked of this.markerSources.values()) {
+            // If there's a clusterer, re-assign its map reference
+            if (tracked.clusterer !== undefined && this.map !== null) {
+                tracked.clusterer.setMap(this.map);
+            }
+            // Re-assign canvas overlay to the new map
+            if (tracked.canvasOverlay !== undefined) {
+                tracked.canvasOverlay.setMap(this.map);
+            }
+            for (const marker of tracked.markers) {
+                marker.map = this.map;
+            }
+        }
+        // Re-assign existing shapes and hit polylines
+        for (const tracked of this.shapeSources.values()) {
+            for (const shape of tracked.shapes) {
+                shape.setMap(this.map);
+            }
+            for (const pl of tracked.hitPolylines) {
+                pl.setMap(this.map);
+            }
+            for (const marker of tracked.pointMarkers) {
+                marker.map = this.map;
+            }
+        }
+        // Re-assign existing routes
+        for (const tracked of this.routeSources.values()) {
+            tracked.polyline.setMap(this.map);
+        }
+        // Re-assign existing overlays
+        for (const tracked of this.overlaySources.values()) {
+            tracked.overlay.setMap(this.map);
+        }
+    }
+}
+GoogleMapsLayerPort.DBLCLICK_THRESHOLD_MS = 400;
+
+/**
+ * Google Maps adapter instance implementation
+ * Manages the connection between our abstract interface and Google Maps API
+ */
+class GoogleMapsAdapterInstance {
+    constructor(config) {
+        this.config = config;
+        this.map = null;
+        this.isDestroyedFlag = false;
+        this.state = INITIAL_MAP_STATE;
+        this.cachedCameraState = {
+            center: INITIAL_MAP_STATE.center,
+            zoom: INITIAL_MAP_STATE.zoom,
+            bounds: INITIAL_MAP_STATE.bounds,
+            isIdle: INITIAL_MAP_STATE.isIdle,
+        };
+        this.cachedStatus = {
+            isReady: INITIAL_MAP_STATE.isReady,
+            initializationFailed: INITIAL_MAP_STATE.initializationFailed,
+            appearance: INITIAL_MAP_STATE.appearance,
+            tileSize: INITIAL_MAP_STATE.tileSize,
+        };
+        this.cameraListeners = new Set();
+        this.statusListeners = new Set();
+        this.eventListeners = new Map();
+        this.googleEventListeners = [];
+        /** Throttled pointermove channel shared by map mousemove and shape overlay mousemove. */
+        this.pointerMoveRaf = null;
+        this.lastPointerPosition = null;
+        this.appearance = { ...DEFAULT_MAP_APPEARANCE, theme: config.theme ?? "light" };
+        this.layers = new GoogleMapsLayerPort();
+        this.layers.setTheme(this.appearance.theme);
+        this.state = computeInitialState(this.appearance, config.initialViewport);
+        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 Google Maps instance - called by GoogleMapsRenderer.
+     *
+     * Handles both first connection and reconnection (e.g. after a theme change
+     * causes vis.gl to create a new google.maps.Map instance for the new mapId).
+     * On reconnection the previous center, zoom, and map type are restored so
+     * the user doesn't see the viewport jump.
+     */
+    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;
+        }
+        // Already connected to this exact instance — nothing to do
+        if (this.map === map)
+            return;
+        const isReconnection = this.map !== null;
+        // Save viewport state before switching so we can restore it on the new map
+        const previousState = isReconnection ? { ...this.state } : null;
+        // Tear down listeners on the old map (if any)
+        if (isReconnection) {
+            this.removeGoogleEventListeners();
+        }
+        this.map = map;
+        this.layers.connect(map);
+        this.setupEventListeners();
+        this.layers.setPointerMoveReporter(position => {
+            this.reportPointerMove(position);
+        });
+        // Restore previous viewport and map type after map recreation
+        if (previousState !== null) {
+            map.setCenter(positionToLatLng(previousState.center));
+            map.setZoom(previousState.zoom);
+            map.setMapTypeId(this.mapTypeToGoogleMapTypeId(this.appearance.mapType, this.appearance.showRoads));
+        }
+        if (!this.state.isReady || this.state.initializationFailed) {
+            // Successful connect clears a prior init failure so recovery is possible (e.g. API load failed then
+            // a later script retry / new Map instance from vis.gl). Idempotent when already ready and not failed.
+            this.state = { ...this.state, isReady: true, initializationFailed: false };
+            this.updateStatusCache();
+            this.notifyStatusListeners();
+        }
+        // Sync adapter state from the (possibly new) map
+        this.updateState(true);
+    }
+    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);
+        };
+    }
+    /**
+     * Returns the current theme.
+     * Used by GoogleMapsRenderer (via useSyncExternalStore) to reactively
+     * update the mapId prop on the <GoogleMap> component.
+     */
+    getTheme() {
+        return this.appearance.theme;
+    }
+    async setCenter(center) {
+        const validCenter = validatePosition(center, "[setCenter]");
+        if (validCenter === null)
+            return;
+        const currentMap = this.map;
+        if (currentMap === null)
+            return;
+        return new Promise(resolve => {
+            currentMap.setCenter(positionToLatLng(validCenter));
+            google.maps.event.addListenerOnce(currentMap, "idle", () => resolve());
+        });
+    }
+    async setZoom(zoomLevel) {
+        const currentMap = this.map;
+        if (currentMap === null)
+            return;
+        return new Promise(resolve => {
+            currentMap.setZoom(zoomLevel);
+            google.maps.event.addListenerOnce(currentMap, "idle", () => resolve());
+        });
+    }
+    async zoomBy(delta) {
+        const currentMap = this.map;
+        if (currentMap === null)
+            return;
+        const currentZoom = currentMap.getZoom();
+        if (currentZoom === undefined)
+            return;
+        return this.setZoom(currentZoom + delta);
+    }
+    async fitBounds(bounds, options) {
+        const validBounds = validateBbox(bounds, "[fitBounds]");
+        if (validBounds === null)
+            return;
+        const currentMap = this.map;
+        if (currentMap === null)
+            return;
+        const effectiveBounds = getEffectiveRestrictBounds(this.config.restrictBounds);
+        return new Promise(resolve => {
+            if (effectiveBounds !== null) {
+                // Temporarily remove restriction to allow fitBounds to work fully
+                currentMap.setOptions({ restriction: undefined });
+            }
+            currentMap.fitBounds(bboxToLatLngBounds(validBounds), options?.padding ?? 0);
+            const maxZoom = options?.maxZoom;
+            if (maxZoom !== undefined) {
+                const currentZoom = currentMap.getZoom();
+                if (currentZoom !== undefined && currentZoom > maxZoom) {
+                    currentMap.setZoom(maxZoom);
+                }
+            }
+            google.maps.event.addListenerOnce(currentMap, "idle", () => {
+                if (effectiveBounds !== null) {
+                    currentMap.setOptions({
+                        restriction: { latLngBounds: bboxToLatLngBounds(effectiveBounds), strictBounds: true },
+                    });
+                }
+                resolve();
+            });
+        });
+    }
+    async panTo(center) {
+        const validCenter = validatePosition(center, "[panTo]");
+        if (validCenter === null)
+            return;
+        const currentMap = this.map;
+        if (currentMap === null)
+            return;
+        return new Promise(resolve => {
+            currentMap.panTo(positionToLatLng(validCenter));
+            google.maps.event.addListenerOnce(currentMap, "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;
+        currentMap.setMapTypeId(this.mapTypeToGoogleMapTypeId(type, this.appearance.showRoads));
+    }
+    async setTheme(theme) {
+        if (this.appearance.theme === theme)
+            return;
+        // Google Maps does NOT support changing mapId on an existing map instance.
+        // Instead we update our tracked theme and notify subscribers so the
+        // GoogleMapsRenderer re-renders with the new mapId prop, which causes
+        // @vis.gl/react-google-maps to create a fresh map instance.
+        this.appearance = { ...this.appearance, theme };
+        this.state = { ...this.state, appearance: this.appearance };
+        this.layers.setTheme(theme);
+        this.updateStatusCache();
+        this.notifyStatusListeners();
+    }
+    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 the effective map type (satellite vs hybrid) if on satellite/hybrid
+        const currentMap = this.map;
+        if (currentMap === null)
+            return;
+        if (this.appearance.mapType === "satellite" || this.appearance.mapType === "hybrid") {
+            currentMap.setMapTypeId(this.mapTypeToGoogleMapTypeId(this.appearance.mapType, showRoads));
+        }
+    }
+    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 (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() {
+        if (this.isDestroyedFlag) {
+            return;
+        }
+        this.isDestroyedFlag = true;
+        this.removeGoogleEventListeners();
+        this.layers.setPointerMoveReporter(null);
+        this.layers.destroy();
+        // 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 = { ...INITIAL_MAP_STATE, isReady: false };
+        this.updateCameraCache();
+        this.updateStatusCache();
+    }
+    // ============================================================================
+    // Private methods
+    // ============================================================================
+    /** Detach all Google Maps native event listeners without clearing our own subscribers */
+    removeGoogleEventListeners() {
+        this.googleEventListeners.forEach(listener => {
+            google.maps.event.removeListener(listener);
+        });
+        this.googleEventListeners = [];
+        if (this.pointerMoveRaf !== null) {
+            cancelAnimationFrame(this.pointerMoveRaf);
+            this.pointerMoveRaf = null;
+        }
+    }
+    /** Emit a throttled pointermove event (map canvas + shape overlays). */
+    reportPointerMove(position) {
+        this.lastPointerPosition = position;
+        if (this.pointerMoveRaf !== null)
+            return;
+        this.pointerMoveRaf = requestAnimationFrame(() => {
+            this.pointerMoveRaf = null;
+            if (this.lastPointerPosition !== null) {
+                this.emitEvent({ type: "pointermove", position: this.lastPointerPosition });
+            }
+        });
+    }
+    setupEventListeners() {
+        const currentMap = this.map;
+        if (currentMap === null)
+            return;
+        // Idle event — camera has settled after pan/zoom
+        this.googleEventListeners.push(currentMap.addListener("idle", () => {
+            this.updateState(true);
+            this.emitEvent({ type: "idle" });
+        }));
+        const markCameraActive = () => {
+            if (this.state.isIdle) {
+                this.state = { ...this.state, isIdle: false };
+                this.updateCameraCache();
+                this.notifyCameraListeners();
+            }
+        };
+        // Move start
+        this.googleEventListeners.push(currentMap.addListener("dragstart", () => {
+            markCameraActive();
+            this.emitEvent({ type: "movestart" });
+        }));
+        // Wheel / control zoom also fires bounds_changed but not dragstart
+        this.googleEventListeners.push(currentMap.addListener("zoom_changed", () => {
+            markCameraActive();
+        }));
+        // Bounds changed (during move) — keep isIdle false until the idle event
+        this.googleEventListeners.push(currentMap.addListener("bounds_changed", () => {
+            this.updateState(false);
+        }));
+        // Click event
+        this.googleEventListeners.push(currentMap.addListener("click", (e) => {
+            const latLng = e.latLng;
+            if (latLng === null)
+                return;
+            this.emitEvent({
+                type: "click",
+                position: latLngToPosition(latLng),
+                originalEvent: e.domEvent instanceof MouseEvent ? e.domEvent : new MouseEvent("click"),
+            });
+        }));
+        // Pointer move (ADR-0021 fill tiling) — throttled to one emit per frame.
+        // Shape overlays also report via setPointerMoveReporter; map mousemove alone
+        // does not fire while the cursor is over clickable polygons/polylines.
+        this.googleEventListeners.push(currentMap.addListener("mousemove", (e) => {
+            const latLng = e.latLng;
+            if (latLng === null)
+                return;
+            this.reportPointerMove(latLngToPosition(latLng));
+        }));
+    }
+    updateState(isIdle) {
+        const currentMap = this.map;
+        if (currentMap === null)
+            return;
+        const center = currentMap.getCenter();
+        const zoom = currentMap.getZoom();
+        if (center === undefined || zoom === undefined)
+            return;
+        const bounds = currentMap.getBounds();
+        const boundsValue = bounds ? latLngBoundsToBbox(bounds) : null;
+        const newCamera = {
+            center: latLngToPosition(center),
+            zoom,
+            bounds: boundsValue,
+            isIdle,
+        };
+        // Only notify camera subscribers if camera fields actually changed
+        if (!cameraStateEquals(this.state, newCamera)) {
+            this.state = { ...this.state, ...newCamera };
+            this.updateCameraCache();
+            this.notifyCameraListeners();
+        }
+    }
+    mapTypeToGoogleMapTypeId(type, showRoads) {
+        switch (type) {
+            case "roadmap":
+                return google.maps.MapTypeId.ROADMAP;
+            case "satellite":
+                // If showRoads is true, use HYBRID to show roads over satellite imagery
+                return showRoads === true ? google.maps.MapTypeId.HYBRID : google.maps.MapTypeId.SATELLITE;
+            case "hybrid":
+                return google.maps.MapTypeId.HYBRID;
+            default: {
+                const exhaustiveCheck = type;
+                throw new Error(`Unknown map type: ${exhaustiveCheck}`);
+            }
+        }
+    }
+    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 createGoogleMapsInstance = (config) => {
+    return new GoogleMapsAdapterInstance(config);
+};
+
+/**
+ * Google Cloud Map IDs for different themes
+ * These are configured in Google Cloud Console for custom styling
+ */
+const GOOGLE_MAP_IDS = {
+    light: "462dc96a2b3709ee",
+    dark: "8676e1fb4a115a8a",
+};
+
+/**
+ * Internal component that renders the actual Google Map
+ * Must be inside APIProvider
+ */
+const GoogleMapInternal = ({ adapterInstance, children, className, style, theme, mapInstanceId, initialViewport, restrictBounds, }) => {
+    const map = useMap(mapInstanceId);
+    const loadingStatus = useApiLoadingStatus();
+    const restrictionBbox = useMemo(() => getEffectiveRestrictBounds(restrictBounds), [restrictBounds]);
+    const mapProps = useMemo(() => {
+        return initialViewport?.type === "bounds"
+            ? {
+                defaultBounds: {
+                    ...bboxToLatLngBounds(initialViewport.bounds),
+                    padding: initialViewport.padding ?? 0,
+                },
+            }
+            : {
+                defaultCenter: initialViewport?.type === "center"
+                    ? { lat: initialViewport.center[1], lng: initialViewport.center[0] }
+                    : DEFAULT_CENTER,
+                defaultZoom: initialViewport?.type === "center" && initialViewport.zoom !== undefined
+                    ? initialViewport.zoom
+                    : DEFAULT_ZOOM,
+            };
+    }, [initialViewport]);
+    // Connect only after the Maps JS API reports loaded — avoids marking the adapter ready while
+    // vis.gl is still in LOADING (if `useMap` ever yields a handle early).
+    useEffect(() => {
+        if (loadingStatus !== APILoadingStatus.LOADED) {
+            return;
+        }
+        if (map !== null && adapterInstance instanceof GoogleMapsAdapterInstance) {
+            adapterInstance.connect(map);
+        }
+    }, [loadingStatus, map, adapterInstance]);
+    useEffect(() => {
+        if (loadingStatus !== APILoadingStatus.FAILED) {
+            return;
+        }
+        if (adapterInstance instanceof GoogleMapsAdapterInstance) {
+            adapterInstance.notifyInitializationFailed();
+        }
+    }, [loadingStatus, adapterInstance]);
+    /** Adapter readiness overlay is owned by `createMapComponent` (@trackunit/react-map). */
+    if (loadingStatus === APILoadingStatus.LOADING || loadingStatus === APILoadingStatus.FAILED) {
+        return null;
+    }
+    const restrictionProps = restrictionBbox !== null
+        ? {
+            restriction: {
+                latLngBounds: bboxToLatLngBounds(restrictionBbox),
+                strictBounds: true,
+            },
+        }
+        : {};
+    return (jsx(Map$1, { className: className, clickableIcons: false, disableDefaultUI: true, draggableCursor: MAP_CURSORS.default, gestureHandling: isDesktop ? "greedy" : "cooperative", id: mapInstanceId, isFractionalZoomEnabled: true, mapId: GOOGLE_MAP_IDS[theme], style: { width: "100%", height: "100%", ...style }, ...restrictionProps, ...mapProps, children: children }));
+};
+/**
+ * Google Maps Renderer component
+ * Wraps the map with APIProvider. Loading/error UI is owned by `@trackunit/react-map` (`createMapComponent`);
+ * this module reports API load failure on the adapter and returns `null` until the script is loaded.
+ *
+ * Subscribes to the adapter's current theme via `useSyncExternalStore` so
+ * that when `setTheme()` is called, the component re-renders with the new
+ * `mapId` prop, causing `@vis.gl/react-google-maps` to create a fresh
+ * `google.maps.Map` instance styled with the correct cloud-based map style.
+ *
+ * When rendered inside an existing `APIProvider` (e.g. via `GoogleApiProvider`),
+ * the renderer skips creating its own `APIProvider`, sharing the Google Maps
+ * JS API context. Each map gets a unique `id` prop to avoid registry conflicts.
+ */
+const GoogleMapsRenderer = (props) => {
+    const { adapterInstance } = props;
+    // Narrow adapter instance to GoogleMapsAdapterInstance for config and theme access
+    if (!(adapterInstance instanceof GoogleMapsAdapterInstance)) {
+        throw new Error("GoogleMapsRenderer requires a GoogleMapsAdapterInstance");
+    }
+    const config = adapterInstance.getConfig();
+    const { apiKey, language, region, initialViewport, restrictBounds } = config;
+    // Subscribe to the adapter's current theme reactively.
+    // When setTheme() updates currentTheme and notifies listeners, this
+    // causes a re-render so the <GoogleMap> receives the updated mapId.
+    const subscribeToTheme = useCallback((onStoreChange) => adapterInstance.subscribeStatus(onStoreChange), [adapterInstance]);
+    const getThemeSnapshot = useCallback(() => adapterInstance.getTheme(), [adapterInstance]);
+    const currentTheme = useSyncExternalStore(subscribeToTheme, getThemeSnapshot, getThemeSnapshot);
+    // "marker" is required for AdvancedMarkerElement used by the layer port.
+    // using satisfies to avoid type errors from the library while maintaining type safety
+    const libraries = useMemo(() => ["marker"], []);
+    // Unique instance ID so vis.gl's internal map registry can distinguish
+    // multiple maps within the same APIProvider context.
+    const autoId = useId();
+    const mapInstanceId = config.mapInstanceId ?? autoId;
+    // Detect if we're already inside an APIProvider (e.g. a shared GoogleApiProvider).
+    // If so, skip creating our own — this prevents multiple concurrent API script
+    // initializations that cause zombie google.maps.Map instances.
+    const existingContext = useContext(APIProviderContext);
+    const hasExternalProvider = existingContext !== null;
+    const internalContent = (jsx(GoogleMapInternal, { ...props, initialViewport: initialViewport, mapInstanceId: mapInstanceId, restrictBounds: restrictBounds, theme: currentTheme }));
+    if (hasExternalProvider) {
+        return internalContent;
+    }
+    return (jsx(APIProvider, { apiKey: apiKey, language: language, libraries: libraries, region: region, children: internalContent }));
+};
+
+/** Stable reference — inline objects break `useMap` Map memo equality and recreate the map every render. */
+const GOOGLE_MAPS_ADAPTER_SAFE_AREA_INSETS = {
+    top: 0,
+    right: 0,
+    bottom: 24,
+    left: 0,
+};
+/**
+ * Google Maps adapter factory
+ *
+ * Creates an adapter configuration for Google Maps that can be passed to useMap.
+ *
+ * @example
+ * ```tsx
+ * const map = useMap(googleMapsAdapter({
+ *   apiKey: process.env.GOOGLE_MAPS_API_KEY,
+ *   theme: "light",
+ *   language: "en",
+ * }));
+ *
+ * <map.Map className="h-full w-full">
+ *   {children}
+ * </map.Map>
+ * ```
+ */
+const googleMapsAdapter = defineAdapter((config) => ({
+    name: "google",
+    config,
+    safeAreaInsets: GOOGLE_MAPS_ADAPTER_SAFE_AREA_INSETS,
+    createInstance: () => createGoogleMapsInstance(config),
+    Renderer: GoogleMapsRenderer,
+}));
+
+export { GoogleApiProvider, GoogleMapsAdapterInstance, GoogleMapsRenderer, googleMapsAdapter };