@trackunit/react-map-adapter-google 0.0.132 → 0.0.133

package/README.md

@@ -58,9 +58,15 @@ const irisAppManifest = {
 
 Use the exported directives instead of copying host lists or using the Manager-only `defaultCspConfig()`. This keeps the CSP requirement versioned with the adapter.
 
+## Heatmaps
+
+- **Renderer:** lazy `@deck.gl/google-maps` overlay + `HeatmapLayer` (Google's own Heatmap Layer is decommissioned - see https://developers.google.com/maps/deprecations#heatmap-layer-js-deprecation).
+- **Integration:** Heatmap layers from `@trackunit/react-map` (`layerType: "heatmap"` on the adapter snapshot) trigger lazy deck.gl inside this adapter — no deck.gl types or APIs are exported here.
+- **Contract:** shared `HeatmapSourceConfig` from `@trackunit/react-map-adapter-shared`.
+
 ## Dependencies
 
-Depends on `@trackunit/react-map-adapter-shared` and Google Maps–related packages (e.g. `@vis.gl/react-google-maps`). It does **not** import `@trackunit/react-map` (adapters are consumed *by* the map package, not the reverse).
+Depends on `@trackunit/react-map-adapter-shared`, `@trackunit/react-map-color-utils`, `@trackunit/geo-json-utils`, Google Maps packages (e.g. `@vis.gl/react-google-maps`, `@googlemaps/markerclusterer`), and `@deck.gl/*` (heatmap on Google — **dynamic import** at runtime when a heatmap is active; still declared npm dependencies). It does **not** import `@trackunit/react-map` (adapters are consumed *by* the map package, not the reverse).
 
 ## Part of the `@trackunit/react-map` family
 

package/buildDeckGlHeatmapLayer.cjs.js

@@ -0,0 +1,30 @@
+'use strict';
+
+var aggregationLayers = require('@deck.gl/aggregation-layers');
+
+/**
+ * Maps {@link HeatmapSourceConfig} → deck.gl `HeatmapLayer` on Google Maps.
+ *
+ * Invoked from {@link DeckGlGoogleMapsLifecycle} after dynamic import.
+ */
+const buildDeckGlHeatmapLayer = (config) => {
+    return new aggregationLayers.HeatmapLayer({
+        id: `heatmap-${config.id}`,
+        data: config.features.features,
+        getPosition: feature => {
+            if (feature.geometry?.type !== "Point")
+                return [0, 0];
+            return [feature.geometry.coordinates[0], feature.geometry.coordinates[1]];
+        },
+        getWeight: feature => {
+            const weight = feature.properties?.weight;
+            return typeof weight === "number" ? weight : 1;
+        },
+        aggregation: "SUM",
+        radiusPixels: config.style.radiusPixels,
+        intensity: config.style.intensity,
+        opacity: config.style.opacity,
+    });
+};
+
+exports.buildDeckGlHeatmapLayer = buildDeckGlHeatmapLayer;

package/buildDeckGlHeatmapLayer.esm.js

@@ -0,0 +1,28 @@
+import { HeatmapLayer } from '@deck.gl/aggregation-layers';
+
+/**
+ * Maps {@link HeatmapSourceConfig} → deck.gl `HeatmapLayer` on Google Maps.
+ *
+ * Invoked from {@link DeckGlGoogleMapsLifecycle} after dynamic import.
+ */
+const buildDeckGlHeatmapLayer = (config) => {
+    return new HeatmapLayer({
+        id: `heatmap-${config.id}`,
+        data: config.features.features,
+        getPosition: feature => {
+            if (feature.geometry?.type !== "Point")
+                return [0, 0];
+            return [feature.geometry.coordinates[0], feature.geometry.coordinates[1]];
+        },
+        getWeight: feature => {
+            const weight = feature.properties?.weight;
+            return typeof weight === "number" ? weight : 1;
+        },
+        aggregation: "SUM",
+        radiusPixels: config.style.radiusPixels,
+        intensity: config.style.intensity,
+        opacity: config.style.opacity,
+    });
+};
+
+export { buildDeckGlHeatmapLayer };

package/createDeckGlGoogleMapsOverlayRuntime.cjs.js

@@ -0,0 +1,26 @@
+'use strict';
+
+var googleMaps = require('@deck.gl/google-maps');
+
+/**
+ * Creates one `GoogleMapsOverlay` per map.
+ *
+ * See https://deck.gl/docs/api-reference/google-maps/google-maps-overlay
+ */
+const createDeckGlGoogleMapsOverlayRuntime = () => ({
+    createOverlay: map => {
+        const overlay = new googleMaps.GoogleMapsOverlay({
+            layers: [],
+        });
+        overlay.setMap(map);
+        return {
+            setMap: nextMap => overlay.setMap(nextMap),
+            setLayers: layers => {
+                overlay.setProps({ layers: [...layers] });
+            },
+            finalize: () => overlay.finalize(),
+        };
+    },
+});
+
+exports.createDeckGlGoogleMapsOverlayRuntime = createDeckGlGoogleMapsOverlayRuntime;

package/createDeckGlGoogleMapsOverlayRuntime.esm.js

@@ -0,0 +1,24 @@
+import { GoogleMapsOverlay } from '@deck.gl/google-maps';
+
+/**
+ * Creates one `GoogleMapsOverlay` per map.
+ *
+ * See https://deck.gl/docs/api-reference/google-maps/google-maps-overlay
+ */
+const createDeckGlGoogleMapsOverlayRuntime = () => ({
+    createOverlay: map => {
+        const overlay = new GoogleMapsOverlay({
+            layers: [],
+        });
+        overlay.setMap(map);
+        return {
+            setMap: nextMap => overlay.setMap(nextMap),
+            setLayers: layers => {
+                overlay.setProps({ layers: [...layers] });
+            },
+            finalize: () => overlay.finalize(),
+        };
+    },
+});
+
+export { createDeckGlGoogleMapsOverlayRuntime };

package/index.cjs.js

@@ -55,6 +55,196 @@ const GoogleApiProvider = ({ apiKey, language, children }) => {
     return (jsxRuntime.jsx(reactGoogleMaps.APIProvider, { apiKey: apiKey, language: language, libraries: libraries, version: GOOGLE_MAPS_API_VERSION, children: children }));
 };
 
+let runtimePromise = null;
+/**
+ * Lazily dynamic-imports {@link createDeckGlGoogleMapsOverlayRuntime} and caches the promise.
+ */
+const loadDeckGlGoogleMapsOverlayRuntime = () => {
+    runtimePromise ?? (runtimePromise = Promise.resolve().then(function () { return require('./createDeckGlGoogleMapsOverlayRuntime.cjs.js'); })
+        .then(module => module.createDeckGlGoogleMapsOverlayRuntime())
+        .catch(error => {
+        runtimePromise = null;
+        throw error;
+    }));
+    return runtimePromise;
+};
+
+/**
+ * Owns a single deck.gl `GoogleMapsOverlay` on a Google map.
+ *
+ * Callers pass deck.gl `Layer` instances via {@link setLayers}; the coordinator merges them
+ * into one overlay. Additional adapter capabilities can contribute layers here later.
+ */
+class DeckGlGoogleMapsOverlayCoordinator {
+    constructor(loadOverlayRuntime = loadDeckGlGoogleMapsOverlayRuntime) {
+        this.loadOverlayRuntime = loadOverlayRuntime;
+        this.map = null;
+        this.overlay = null;
+        this.pendingLayers = [];
+        this.runtime = null;
+        this.loading = null;
+        this.overlayCreation = null;
+    }
+    /** Associates the coordinator with a map and applies any pending layers. */
+    connect(map) {
+        const isReconnection = this.map !== null && this.map !== map;
+        this.map = map;
+        if (isReconnection) {
+            this.overlay?.setMap(map);
+        }
+        void this.syncOverlay();
+    }
+    /** Starts loading the deck.gl overlay runtime without creating an overlay. */
+    prepare() {
+        return this.loadRuntime().then(() => undefined);
+    }
+    /**
+     * Replaces all deck.gl layers on the shared overlay.
+     *
+     * An empty array tears down the overlay until layers are set again.
+     */
+    setLayers(layers) {
+        this.pendingLayers = layers;
+        if (layers.length === 0) {
+            this.overlay?.finalize();
+            this.overlay = null;
+            return;
+        }
+        void this.syncOverlay();
+    }
+    /** Finalizes the overlay and clears coordinator state. */
+    destroy() {
+        this.pendingLayers = [];
+        this.overlay?.finalize();
+        this.overlay = null;
+        this.map = null;
+        this.loading = null;
+    }
+    syncOverlay() {
+        if (this.map === null || this.pendingLayers.length === 0)
+            return;
+        if (this.overlay !== null) {
+            this.overlay.setLayers(this.pendingLayers);
+            return;
+        }
+        if (this.overlayCreation !== null)
+            return;
+        this.overlayCreation = this.loadRuntime()
+            .then(runtime => {
+            if (this.map === null || this.pendingLayers.length === 0)
+                return;
+            this.overlay = runtime.createOverlay(this.map);
+            this.overlay.setLayers(this.pendingLayers);
+        })
+            .catch(() => undefined)
+            .finally(() => {
+            this.overlayCreation = null;
+        });
+    }
+    loadRuntime() {
+        if (this.runtime !== null)
+            return Promise.resolve(this.runtime);
+        if (this.loading !== null)
+            return this.loading;
+        this.loading = this.loadOverlayRuntime().then(runtime => {
+            this.runtime = runtime;
+            this.loading = null;
+            return runtime;
+        }, error => {
+            this.loading = null;
+            throw error;
+        });
+        return this.loading;
+    }
+}
+
+/**
+ * Internal deck.gl lifecycle for the Google adapter (not a {@link LayerPort}).
+ *
+ * Reads deck.gl-relevant layers from a {@link LayerSnapshot}, builds deck.gl `Layer`
+ * instances, and pushes them through {@link DeckGlGoogleMapsOverlayCoordinator}.
+ * Heatmap is supported today; additional layer types can extend `buildDeckGlLayers`.
+ */
+class DeckGlGoogleMapsLifecycle {
+    constructor(overlayCoordinator = new DeckGlGoogleMapsOverlayCoordinator(), loadHeatmapLayerBuilder = () => Promise.resolve().then(function () { return require('./buildDeckGlHeatmapLayer.cjs.js'); })) {
+        this.overlayCoordinator = overlayCoordinator;
+        this.loadHeatmapLayerBuilder = loadHeatmapLayerBuilder;
+        this.map = null;
+        this.heatmapConfigs = [];
+        this.heatmapLayers = new Map();
+        this.heatmapLayerBuilderModule = null;
+        this.syncing = null;
+    }
+    /** Binds to the map and syncs if snapshot state is already held. */
+    connect(map) {
+        this.map = map;
+        this.overlayCoordinator.connect(map);
+        void this.sync();
+    }
+    /**
+     * Applies deck.gl layers derived from the snapshot.
+     *
+     * Only layers rendered via deck.gl are considered; native Google layers stay on
+     * {@link GoogleMapsLayerPort}.
+     */
+    applySnapshot(snapshot) {
+        this.heatmapConfigs = snapshot.layers.filter(layer => layer.layerType === "heatmap");
+        void this.sync();
+    }
+    /** Detaches from the map and releases the shared deck.gl overlay. */
+    destroy() {
+        this.map = null;
+        this.heatmapConfigs = [];
+        this.heatmapLayers.clear();
+        this.syncing = null;
+        this.overlayCoordinator.destroy();
+    }
+    sync() {
+        if (this.map === null)
+            return;
+        if (this.heatmapConfigs.length === 0) {
+            this.heatmapLayers.clear();
+            this.overlayCoordinator.setLayers([]);
+            return;
+        }
+        if (this.heatmapLayerBuilderModule !== null) {
+            this.applyCurrentLayers(this.heatmapLayerBuilderModule);
+            return;
+        }
+        if (this.syncing !== null)
+            return;
+        this.syncing = Promise.all([this.loadHeatmapLayerBuilder(), this.overlayCoordinator.prepare()])
+            .then(([module]) => {
+            this.heatmapLayerBuilderModule = module;
+            this.syncing = null;
+            if (this.map === null)
+                return;
+            this.applyCurrentLayers(module);
+        })
+            .catch(() => {
+            this.syncing = null;
+        });
+    }
+    applyCurrentLayers(module) {
+        const currentIds = new Set(this.heatmapConfigs.map(config => config.id));
+        const layers = this.heatmapConfigs.map(config => {
+            const tracked = this.heatmapLayers.get(config.id);
+            if (tracked !== undefined && esToolkit.isEqual(tracked.config, config)) {
+                return tracked.layer;
+            }
+            const layer = module.buildDeckGlHeatmapLayer(config);
+            this.heatmapLayers.set(config.id, { config, layer });
+            return layer;
+        });
+        for (const id of this.heatmapLayers.keys()) {
+            if (!currentIds.has(id)) {
+                this.heatmapLayers.delete(id);
+            }
+        }
+        this.overlayCoordinator.setLayers(layers);
+    }
+}
+
 /**
  * Zod schema for Google Maps LatLngLiteral
  * A plain object with lat and lng number properties
@@ -163,7 +353,7 @@ const DOM_MARKER_Z_INDEX = 1000;
  * any sources can be rendered. Sources set before connect are queued.
  */
 class GoogleMapsLayerPort {
-    constructor() {
+    constructor(deckGlGoogleMapsLifecycle = new DeckGlGoogleMapsLifecycle()) {
         /**
          * Marker portal subscription compatible with `useSyncExternalStore`.
          * `<Layers>` routes descriptors from this store to `markerRender`. Includes
@@ -269,6 +459,7 @@ class GoogleMapsLayerPort {
         this.mapDblClickListenerCleanup = null;
         // Consumer-injected shape style defaults (set via setShapeStyleDefaults before first snapshot)
         this._shapeStyleDefaults = undefined;
+        this.deckGlGoogleMapsLifecycle = deckGlGoogleMapsLifecycle;
     }
     get shapeStyleDefaults() {
         if (this._shapeStyleDefaults === undefined) {
@@ -290,6 +481,7 @@ class GoogleMapsLayerPort {
         // re-render all existing sources on the new map
         const isReconnection = this.map !== null && this.map !== map;
         this.map = map;
+        this.deckGlGoogleMapsLifecycle.connect(map);
         this.setupMapContainerDblClickListener(map);
         this.setupMapClickListener(map);
         if (isReconnection) {
@@ -389,6 +581,7 @@ class GoogleMapsLayerPort {
         for (const id of [...this.overlaySources.keys()]) {
             this.removeImageOverlayInternal(id);
         }
+        this.deckGlGoogleMapsLifecycle.destroy();
         this.interactionHandlers.clear();
         this.backgroundClickHandlers.clear();
         this.markerPortalDescriptors = [];
@@ -413,6 +606,7 @@ class GoogleMapsLayerPort {
         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));
+        this.deckGlGoogleMapsLifecycle.applySnapshot(snapshot);
         for (const layer of snapshot.layers) {
             switch (layer.layerType) {
                 case "markers":
@@ -427,6 +621,9 @@ class GoogleMapsLayerPort {
                 case "image-overlay":
                     this.syncImageOverlay(layer);
                     break;
+                case "heatmap":
+                    // Rendered by DeckGlGoogleMapsLifecycle (applySnapshot above); ADR-0029.
+                    break;
                 default: {
                     const exhaustiveCheck = layer;
                     throw new Error(`Unknown layer type: ${String(exhaustiveCheck)}`);
@@ -2589,7 +2786,18 @@ class GoogleMapsAdapterInstance {
          * (ADR 0028: attaching it to a vector map silently degrades the renderer).
          */
         this.connectedRenderingType = "VECTOR";
-        this.appearance = { ...reactMapAdapterShared.DEFAULT_MAP_APPEARANCE, theme: config.theme ?? "light" };
+        // Seed the full appearance from config so a persisted preference (via
+        // usePersistedAppearanceSeed in @trackunit/react-map) shapes the FIRST map:
+        // the renderer reads theme and showTraffic from this initial state to pick
+        // mapId and renderingType, so seeding here avoids the construct-then-recreate
+        // blink (and double Dynamic Maps load) on mount.
+        this.appearance = {
+            theme: config.theme ?? reactMapAdapterShared.DEFAULT_MAP_APPEARANCE.theme,
+            mapType: config.mapType ?? reactMapAdapterShared.DEFAULT_MAP_APPEARANCE.mapType,
+            showRoads: config.showRoads ?? reactMapAdapterShared.DEFAULT_MAP_APPEARANCE.showRoads,
+            // Absent = off; the core default keeps the field optional for external compatibility
+            showTraffic: config.showTraffic ?? false,
+        };
         this.layers = new GoogleMapsLayerPort();
         this.layers.setTheme(this.appearance.theme);
         this.state = reactMapAdapterShared.computeInitialState(this.appearance, config.initialViewport);
@@ -2649,11 +2857,17 @@ class GoogleMapsAdapterInstance {
         this.layers.setPointerMoveReporter(position => {
             this.reportPointerMove(position);
         });
-        // Restore previous viewport and map type after map recreation
+        // Restore previous viewport 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));
+        }
+        // Apply the effective map type on every connect: vis.gl creates each map with
+        // Google's default (roadmap), so a seeded satellite/hybrid appearance must be
+        // applied on first connect too, not only restored after recreations.
+        const effectiveMapTypeId = this.mapTypeToGoogleMapTypeId(this.appearance.mapType, this.appearance.showRoads);
+        if (map.getMapTypeId() !== effectiveMapTypeId) {
+            map.setMapTypeId(effectiveMapTypeId);
         }
         if (!this.state.isReady || this.state.initializationFailed) {
             // Successful connect clears a prior init failure so recovery is possible (e.g. API load failed then

package/index.esm.js

@@ -54,6 +54,196 @@ const GoogleApiProvider = ({ apiKey, language, children }) => {
     return (jsx(APIProvider, { apiKey: apiKey, language: language, libraries: libraries, version: GOOGLE_MAPS_API_VERSION, children: children }));
 };
 
+let runtimePromise = null;
+/**
+ * Lazily dynamic-imports {@link createDeckGlGoogleMapsOverlayRuntime} and caches the promise.
+ */
+const loadDeckGlGoogleMapsOverlayRuntime = () => {
+    runtimePromise ?? (runtimePromise = import('./createDeckGlGoogleMapsOverlayRuntime.esm.js')
+        .then(module => module.createDeckGlGoogleMapsOverlayRuntime())
+        .catch(error => {
+        runtimePromise = null;
+        throw error;
+    }));
+    return runtimePromise;
+};
+
+/**
+ * Owns a single deck.gl `GoogleMapsOverlay` on a Google map.
+ *
+ * Callers pass deck.gl `Layer` instances via {@link setLayers}; the coordinator merges them
+ * into one overlay. Additional adapter capabilities can contribute layers here later.
+ */
+class DeckGlGoogleMapsOverlayCoordinator {
+    constructor(loadOverlayRuntime = loadDeckGlGoogleMapsOverlayRuntime) {
+        this.loadOverlayRuntime = loadOverlayRuntime;
+        this.map = null;
+        this.overlay = null;
+        this.pendingLayers = [];
+        this.runtime = null;
+        this.loading = null;
+        this.overlayCreation = null;
+    }
+    /** Associates the coordinator with a map and applies any pending layers. */
+    connect(map) {
+        const isReconnection = this.map !== null && this.map !== map;
+        this.map = map;
+        if (isReconnection) {
+            this.overlay?.setMap(map);
+        }
+        void this.syncOverlay();
+    }
+    /** Starts loading the deck.gl overlay runtime without creating an overlay. */
+    prepare() {
+        return this.loadRuntime().then(() => undefined);
+    }
+    /**
+     * Replaces all deck.gl layers on the shared overlay.
+     *
+     * An empty array tears down the overlay until layers are set again.
+     */
+    setLayers(layers) {
+        this.pendingLayers = layers;
+        if (layers.length === 0) {
+            this.overlay?.finalize();
+            this.overlay = null;
+            return;
+        }
+        void this.syncOverlay();
+    }
+    /** Finalizes the overlay and clears coordinator state. */
+    destroy() {
+        this.pendingLayers = [];
+        this.overlay?.finalize();
+        this.overlay = null;
+        this.map = null;
+        this.loading = null;
+    }
+    syncOverlay() {
+        if (this.map === null || this.pendingLayers.length === 0)
+            return;
+        if (this.overlay !== null) {
+            this.overlay.setLayers(this.pendingLayers);
+            return;
+        }
+        if (this.overlayCreation !== null)
+            return;
+        this.overlayCreation = this.loadRuntime()
+            .then(runtime => {
+            if (this.map === null || this.pendingLayers.length === 0)
+                return;
+            this.overlay = runtime.createOverlay(this.map);
+            this.overlay.setLayers(this.pendingLayers);
+        })
+            .catch(() => undefined)
+            .finally(() => {
+            this.overlayCreation = null;
+        });
+    }
+    loadRuntime() {
+        if (this.runtime !== null)
+            return Promise.resolve(this.runtime);
+        if (this.loading !== null)
+            return this.loading;
+        this.loading = this.loadOverlayRuntime().then(runtime => {
+            this.runtime = runtime;
+            this.loading = null;
+            return runtime;
+        }, error => {
+            this.loading = null;
+            throw error;
+        });
+        return this.loading;
+    }
+}
+
+/**
+ * Internal deck.gl lifecycle for the Google adapter (not a {@link LayerPort}).
+ *
+ * Reads deck.gl-relevant layers from a {@link LayerSnapshot}, builds deck.gl `Layer`
+ * instances, and pushes them through {@link DeckGlGoogleMapsOverlayCoordinator}.
+ * Heatmap is supported today; additional layer types can extend `buildDeckGlLayers`.
+ */
+class DeckGlGoogleMapsLifecycle {
+    constructor(overlayCoordinator = new DeckGlGoogleMapsOverlayCoordinator(), loadHeatmapLayerBuilder = () => import('./buildDeckGlHeatmapLayer.esm.js')) {
+        this.overlayCoordinator = overlayCoordinator;
+        this.loadHeatmapLayerBuilder = loadHeatmapLayerBuilder;
+        this.map = null;
+        this.heatmapConfigs = [];
+        this.heatmapLayers = new Map();
+        this.heatmapLayerBuilderModule = null;
+        this.syncing = null;
+    }
+    /** Binds to the map and syncs if snapshot state is already held. */
+    connect(map) {
+        this.map = map;
+        this.overlayCoordinator.connect(map);
+        void this.sync();
+    }
+    /**
+     * Applies deck.gl layers derived from the snapshot.
+     *
+     * Only layers rendered via deck.gl are considered; native Google layers stay on
+     * {@link GoogleMapsLayerPort}.
+     */
+    applySnapshot(snapshot) {
+        this.heatmapConfigs = snapshot.layers.filter(layer => layer.layerType === "heatmap");
+        void this.sync();
+    }
+    /** Detaches from the map and releases the shared deck.gl overlay. */
+    destroy() {
+        this.map = null;
+        this.heatmapConfigs = [];
+        this.heatmapLayers.clear();
+        this.syncing = null;
+        this.overlayCoordinator.destroy();
+    }
+    sync() {
+        if (this.map === null)
+            return;
+        if (this.heatmapConfigs.length === 0) {
+            this.heatmapLayers.clear();
+            this.overlayCoordinator.setLayers([]);
+            return;
+        }
+        if (this.heatmapLayerBuilderModule !== null) {
+            this.applyCurrentLayers(this.heatmapLayerBuilderModule);
+            return;
+        }
+        if (this.syncing !== null)
+            return;
+        this.syncing = Promise.all([this.loadHeatmapLayerBuilder(), this.overlayCoordinator.prepare()])
+            .then(([module]) => {
+            this.heatmapLayerBuilderModule = module;
+            this.syncing = null;
+            if (this.map === null)
+                return;
+            this.applyCurrentLayers(module);
+        })
+            .catch(() => {
+            this.syncing = null;
+        });
+    }
+    applyCurrentLayers(module) {
+        const currentIds = new Set(this.heatmapConfigs.map(config => config.id));
+        const layers = this.heatmapConfigs.map(config => {
+            const tracked = this.heatmapLayers.get(config.id);
+            if (tracked !== undefined && isEqual(tracked.config, config)) {
+                return tracked.layer;
+            }
+            const layer = module.buildDeckGlHeatmapLayer(config);
+            this.heatmapLayers.set(config.id, { config, layer });
+            return layer;
+        });
+        for (const id of this.heatmapLayers.keys()) {
+            if (!currentIds.has(id)) {
+                this.heatmapLayers.delete(id);
+            }
+        }
+        this.overlayCoordinator.setLayers(layers);
+    }
+}
+
 /**
  * Zod schema for Google Maps LatLngLiteral
  * A plain object with lat and lng number properties
@@ -162,7 +352,7 @@ const DOM_MARKER_Z_INDEX = 1000;
  * any sources can be rendered. Sources set before connect are queued.
  */
 class GoogleMapsLayerPort {
-    constructor() {
+    constructor(deckGlGoogleMapsLifecycle = new DeckGlGoogleMapsLifecycle()) {
         /**
          * Marker portal subscription compatible with `useSyncExternalStore`.
          * `<Layers>` routes descriptors from this store to `markerRender`. Includes
@@ -268,6 +458,7 @@ class GoogleMapsLayerPort {
         this.mapDblClickListenerCleanup = null;
         // Consumer-injected shape style defaults (set via setShapeStyleDefaults before first snapshot)
         this._shapeStyleDefaults = undefined;
+        this.deckGlGoogleMapsLifecycle = deckGlGoogleMapsLifecycle;
     }
     get shapeStyleDefaults() {
         if (this._shapeStyleDefaults === undefined) {
@@ -289,6 +480,7 @@ class GoogleMapsLayerPort {
         // re-render all existing sources on the new map
         const isReconnection = this.map !== null && this.map !== map;
         this.map = map;
+        this.deckGlGoogleMapsLifecycle.connect(map);
         this.setupMapContainerDblClickListener(map);
         this.setupMapClickListener(map);
         if (isReconnection) {
@@ -388,6 +580,7 @@ class GoogleMapsLayerPort {
         for (const id of [...this.overlaySources.keys()]) {
             this.removeImageOverlayInternal(id);
         }
+        this.deckGlGoogleMapsLifecycle.destroy();
         this.interactionHandlers.clear();
         this.backgroundClickHandlers.clear();
         this.markerPortalDescriptors = [];
@@ -412,6 +605,7 @@ class GoogleMapsLayerPort {
         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));
+        this.deckGlGoogleMapsLifecycle.applySnapshot(snapshot);
         for (const layer of snapshot.layers) {
             switch (layer.layerType) {
                 case "markers":
@@ -426,6 +620,9 @@ class GoogleMapsLayerPort {
                 case "image-overlay":
                     this.syncImageOverlay(layer);
                     break;
+                case "heatmap":
+                    // Rendered by DeckGlGoogleMapsLifecycle (applySnapshot above); ADR-0029.
+                    break;
                 default: {
                     const exhaustiveCheck = layer;
                     throw new Error(`Unknown layer type: ${String(exhaustiveCheck)}`);
@@ -2588,7 +2785,18 @@ class GoogleMapsAdapterInstance {
          * (ADR 0028: attaching it to a vector map silently degrades the renderer).
          */
         this.connectedRenderingType = "VECTOR";
-        this.appearance = { ...DEFAULT_MAP_APPEARANCE, theme: config.theme ?? "light" };
+        // Seed the full appearance from config so a persisted preference (via
+        // usePersistedAppearanceSeed in @trackunit/react-map) shapes the FIRST map:
+        // the renderer reads theme and showTraffic from this initial state to pick
+        // mapId and renderingType, so seeding here avoids the construct-then-recreate
+        // blink (and double Dynamic Maps load) on mount.
+        this.appearance = {
+            theme: config.theme ?? DEFAULT_MAP_APPEARANCE.theme,
+            mapType: config.mapType ?? DEFAULT_MAP_APPEARANCE.mapType,
+            showRoads: config.showRoads ?? DEFAULT_MAP_APPEARANCE.showRoads,
+            // Absent = off; the core default keeps the field optional for external compatibility
+            showTraffic: config.showTraffic ?? false,
+        };
         this.layers = new GoogleMapsLayerPort();
         this.layers.setTheme(this.appearance.theme);
         this.state = computeInitialState(this.appearance, config.initialViewport);
@@ -2648,11 +2856,17 @@ class GoogleMapsAdapterInstance {
         this.layers.setPointerMoveReporter(position => {
             this.reportPointerMove(position);
         });
-        // Restore previous viewport and map type after map recreation
+        // Restore previous viewport 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));
+        }
+        // Apply the effective map type on every connect: vis.gl creates each map with
+        // Google's default (roadmap), so a seeded satellite/hybrid appearance must be
+        // applied on first connect too, not only restored after recreations.
+        const effectiveMapTypeId = this.mapTypeToGoogleMapTypeId(this.appearance.mapType, this.appearance.showRoads);
+        if (map.getMapTypeId() !== effectiveMapTypeId) {
+            map.setMapTypeId(effectiveMapTypeId);
         }
         if (!this.state.isReady || this.state.initializationFailed) {
             // Successful connect clears a prior init failure so recovery is possible (e.g. API load failed then

package/package.json

@@ -1,15 +1,22 @@
 {
   "name": "@trackunit/react-map-adapter-google",
-  "version": "0.0.132",
+  "version": "0.0.133",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
     "node": ">=24.x"
   },
   "dependencies": {
-    "@trackunit/react-map-adapter-shared": "0.0.143",
-    "@trackunit/react-map-color-utils": "0.0.118",
-    "@trackunit/geo-json-utils": "1.16.2",
+    "@deck.gl/aggregation-layers": "^9.4.0",
+    "@deck.gl/core": "^9.4.0",
+    "@deck.gl/google-maps": "^9.4.0",
+    "@deck.gl/layers": "^9.4.0",
+    "@loaders.gl/core": "~4.5.2",
+    "@luma.gl/core": "^9.4.1",
+    "@luma.gl/engine": "^9.4.1",
+    "@trackunit/react-map-adapter-shared": "0.0.144",
+    "@trackunit/react-map-color-utils": "0.0.119",
+    "@trackunit/geo-json-utils": "1.16.3",
     "@googlemaps/markerclusterer": "^2.6.2",
     "@vis.gl/react-google-maps": "^1.7.1",
     "es-toolkit": "^1.39.10",

package/src/GoogleMapsLayerPort.d.ts

@@ -1,5 +1,6 @@
 import { type GeoJsonPosition } from "@trackunit/geo-json-utils";
 import { type DomPortalStore, type EntityInteractionHandler, type LayerPort, type LayerSnapshot, type MapTheme, type ShapeStyleDefaults } from "@trackunit/react-map-adapter-shared";
+import { DeckGlGoogleMapsLifecycle } from "./deckGl/DeckGlGoogleMapsLifecycle";
 /**
  * Google Maps implementation of the LayerPort interface.
  *
@@ -77,6 +78,8 @@ export declare class GoogleMapsLayerPort implements LayerPort {
     private holdNativeZoomTimer;
     private mapDblClickListenerCleanup;
     private _shapeStyleDefaults;
+    private readonly deckGlGoogleMapsLifecycle;
+    constructor(deckGlGoogleMapsLifecycle?: DeckGlGoogleMapsLifecycle);
     private get shapeStyleDefaults();
     setShapeStyleDefaults(defaults: ShapeStyleDefaults): void;
     /**

package/src/deckGl/DeckGlGoogleMapsLifecycle.d.ts

@@ -0,0 +1,38 @@
+import type { Layer } from "@deck.gl/core";
+import type { HeatmapSourceConfig, LayerSnapshot } from "@trackunit/react-map-adapter-shared";
+import { DeckGlGoogleMapsOverlayCoordinator } from "./DeckGlGoogleMapsOverlayCoordinator";
+type HeatmapLayerBuilderModule = Readonly<{
+    buildDeckGlHeatmapLayer: (config: HeatmapSourceConfig) => Layer;
+}>;
+type LoadHeatmapLayerBuilder = () => Promise<HeatmapLayerBuilderModule>;
+/**
+ * Internal deck.gl lifecycle for the Google adapter (not a {@link LayerPort}).
+ *
+ * Reads deck.gl-relevant layers from a {@link LayerSnapshot}, builds deck.gl `Layer`
+ * instances, and pushes them through {@link DeckGlGoogleMapsOverlayCoordinator}.
+ * Heatmap is supported today; additional layer types can extend `buildDeckGlLayers`.
+ */
+export declare class DeckGlGoogleMapsLifecycle {
+    private readonly overlayCoordinator;
+    private readonly loadHeatmapLayerBuilder;
+    private map;
+    private heatmapConfigs;
+    private readonly heatmapLayers;
+    private heatmapLayerBuilderModule;
+    private syncing;
+    constructor(overlayCoordinator?: DeckGlGoogleMapsOverlayCoordinator, loadHeatmapLayerBuilder?: LoadHeatmapLayerBuilder);
+    /** Binds to the map and syncs if snapshot state is already held. */
+    connect(map: google.maps.Map): void;
+    /**
+     * Applies deck.gl layers derived from the snapshot.
+     *
+     * Only layers rendered via deck.gl are considered; native Google layers stay on
+     * {@link GoogleMapsLayerPort}.
+     */
+    applySnapshot(snapshot: LayerSnapshot): void;
+    /** Detaches from the map and releases the shared deck.gl overlay. */
+    destroy(): void;
+    private sync;
+    private applyCurrentLayers;
+}
+export {};

package/src/deckGl/DeckGlGoogleMapsOverlayCoordinator.d.ts

@@ -0,0 +1,33 @@
+import type { Layer } from "@deck.gl/core";
+import type { DeckGlGoogleMapsOverlayRuntime } from "./createDeckGlGoogleMapsOverlayRuntime";
+export type LoadDeckGlGoogleMapsOverlayRuntime = () => Promise<DeckGlGoogleMapsOverlayRuntime>;
+/**
+ * Owns a single deck.gl `GoogleMapsOverlay` on a Google map.
+ *
+ * Callers pass deck.gl `Layer` instances via {@link setLayers}; the coordinator merges them
+ * into one overlay. Additional adapter capabilities can contribute layers here later.
+ */
+export declare class DeckGlGoogleMapsOverlayCoordinator {
+    private readonly loadOverlayRuntime;
+    private map;
+    private overlay;
+    private pendingLayers;
+    private runtime;
+    private loading;
+    private overlayCreation;
+    constructor(loadOverlayRuntime?: LoadDeckGlGoogleMapsOverlayRuntime);
+    /** Associates the coordinator with a map and applies any pending layers. */
+    connect(map: google.maps.Map): void;
+    /** Starts loading the deck.gl overlay runtime without creating an overlay. */
+    prepare(): Promise<void>;
+    /**
+     * Replaces all deck.gl layers on the shared overlay.
+     *
+     * An empty array tears down the overlay until layers are set again.
+     */
+    setLayers(layers: ReadonlyArray<Layer>): void;
+    /** Finalizes the overlay and clears coordinator state. */
+    destroy(): void;
+    private syncOverlay;
+    private loadRuntime;
+}

package/src/deckGl/createDeckGlGoogleMapsOverlayRuntime.d.ts

@@ -0,0 +1,17 @@
+import type { Layer } from "@deck.gl/core";
+/** Mutable deck.gl overlay bound to one {@link google.maps.Map}. */
+export type DeckGlGoogleMapsOverlayHandle = Readonly<{
+    setMap: (map: google.maps.Map) => void;
+    setLayers: (layers: ReadonlyArray<Layer>) => void;
+    finalize: () => void;
+}>;
+/** Factory after lazy-loading `@deck.gl/google-maps`. */
+export type DeckGlGoogleMapsOverlayRuntime = Readonly<{
+    createOverlay: (map: google.maps.Map) => DeckGlGoogleMapsOverlayHandle;
+}>;
+/**
+ * Creates one `GoogleMapsOverlay` per map.
+ *
+ * See https://deck.gl/docs/api-reference/google-maps/google-maps-overlay
+ */
+export declare const createDeckGlGoogleMapsOverlayRuntime: () => DeckGlGoogleMapsOverlayRuntime;

package/src/deckGl/loadDeckGlGoogleMapsOverlayRuntime.d.ts

@@ -0,0 +1,5 @@
+import type { DeckGlGoogleMapsOverlayRuntime } from "./createDeckGlGoogleMapsOverlayRuntime";
+/**
+ * Lazily dynamic-imports {@link createDeckGlGoogleMapsOverlayRuntime} and caches the promise.
+ */
+export declare const loadDeckGlGoogleMapsOverlayRuntime: () => Promise<DeckGlGoogleMapsOverlayRuntime>;

package/src/googleMapsAdapter.d.ts

@@ -21,6 +21,9 @@ export declare const googleMapsAdapter: (config: Readonly<Readonly<{
     language?: string;
     region?: string;
     theme?: import("@trackunit/react-map-adapter-shared").MapTheme;
+    mapType?: import("@trackunit/react-map-adapter-shared").MapType;
+    showRoads?: boolean;
+    showTraffic?: boolean;
     initialViewport?: import("@trackunit/react-map-adapter-shared").InitialViewport;
     restrictBounds?: import("@trackunit/geo-json-utils").GeoJsonBbox | null;
 }> & {
@@ -30,6 +33,9 @@ export declare const googleMapsAdapter: (config: Readonly<Readonly<{
     language?: string;
     region?: string;
     theme?: import("@trackunit/react-map-adapter-shared").MapTheme;
+    mapType?: import("@trackunit/react-map-adapter-shared").MapType;
+    showRoads?: boolean;
+    showTraffic?: boolean;
     initialViewport?: import("@trackunit/react-map-adapter-shared").InitialViewport;
     restrictBounds?: import("@trackunit/geo-json-utils").GeoJsonBbox | null;
 }> & {

package/src/heatmap/buildDeckGlHeatmapLayer.d.ts

@@ -0,0 +1,8 @@
+import { HeatmapLayer } from "@deck.gl/aggregation-layers";
+import type { GeoJsonFeature, HeatmapSourceConfig } from "@trackunit/react-map-adapter-shared";
+/**
+ * Maps {@link HeatmapSourceConfig} → deck.gl `HeatmapLayer` on Google Maps.
+ *
+ * Invoked from {@link DeckGlGoogleMapsLifecycle} after dynamic import.
+ */
+export declare const buildDeckGlHeatmapLayer: (config: HeatmapSourceConfig) => HeatmapLayer<GeoJsonFeature>;