@trackunit/react-map-adapter-google 0.0.148-alpha-7afddbbe4cc.0 → 0.0.149-alpha-3bf54986a78.0

package/buildDeckGlHeatmapLayer.cjs.js

@@ -7,9 +7,13 @@ var aggregationLayers = require('@deck.gl/aggregation-layers');
  *
  * Invoked from {@link DeckGlGoogleMapsLifecycle} after dynamic import.
  */
-const buildDeckGlHeatmapLayer = (config) => {
+const buildDeckGlHeatmapLayer = ({ config, onError, }) => {
     return new aggregationLayers.HeatmapLayer({
         id: `heatmap-${config.id}`,
+        onError: (error) => {
+            onError(error);
+            return true;
+        },
         data: config.features.features,
         getPosition: feature => {
             if (feature.geometry?.type !== "Point")

package/buildDeckGlHeatmapLayer.esm.js

@@ -5,9 +5,13 @@ import { HeatmapLayer } from '@deck.gl/aggregation-layers';
  *
  * Invoked from {@link DeckGlGoogleMapsLifecycle} after dynamic import.
  */
-const buildDeckGlHeatmapLayer = (config) => {
+const buildDeckGlHeatmapLayer = ({ config, onError, }) => {
     return new HeatmapLayer({
         id: `heatmap-${config.id}`,
+        onError: (error) => {
+            onError(error);
+            return true;
+        },
         data: config.features.features,
         getPosition: feature => {
             if (feature.geometry?.type !== "Point")

package/createDeckGlGoogleMapsOverlayRuntime.cjs.js

@@ -8,12 +8,14 @@ var googleMaps = require('@deck.gl/google-maps');
  * See https://deck.gl/docs/api-reference/google-maps/google-maps-overlay
  */
 const createDeckGlGoogleMapsOverlayRuntime = () => ({
-    createOverlay: map => {
+    createOverlay: ({ map, onLoad, onError }) => {
         const overlay = new googleMaps.GoogleMapsOverlay({
             layers: [],
             // deck.gl 9.4.0 races in interleaved mode on vector maps: when the positioning overlay is added
             // before Google's WebGL context, deck keeps its own 1×1 canvas and the heatmap never shows.
             interleaved: false,
+            onLoad,
+            onError,
         });
         overlay.setMap(map);
         return {

package/createDeckGlGoogleMapsOverlayRuntime.esm.js

@@ -6,12 +6,14 @@ import { GoogleMapsOverlay } from '@deck.gl/google-maps';
  * See https://deck.gl/docs/api-reference/google-maps/google-maps-overlay
  */
 const createDeckGlGoogleMapsOverlayRuntime = () => ({
-    createOverlay: map => {
+    createOverlay: ({ map, onLoad, onError }) => {
         const overlay = new GoogleMapsOverlay({
             layers: [],
             // deck.gl 9.4.0 races in interleaved mode on vector maps: when the positioning overlay is added
             // before Google's WebGL context, deck keeps its own 1×1 canvas and the heatmap never shows.
             interleaved: false,
+            onLoad,
+            onError,
         });
         overlay.setMap(map);
         return {

package/index.cjs.js

@@ -84,6 +84,7 @@ class DeckGlGoogleMapsOverlayCoordinator {
         this.runtime = null;
         this.loading = null;
         this.overlayCreation = null;
+        this.statusHandlers = null;
     }
     /** Associates the coordinator with a map and applies any pending layers. */
     connect(map) {
@@ -94,6 +95,10 @@ class DeckGlGoogleMapsOverlayCoordinator {
         }
         void this.syncOverlay();
     }
+    /** Receives async overlay readiness and failures, which callers cannot observe themselves. */
+    setStatusHandlers(handlers) {
+        this.statusHandlers = handlers;
+    }
     /** Starts loading the deck.gl overlay runtime without creating an overlay. */
     prepare() {
         return this.loadRuntime().then(() => undefined);
@@ -133,14 +138,32 @@ class DeckGlGoogleMapsOverlayCoordinator {
             .then(runtime => {
             if (this.map === null || this.pendingLayers.length === 0)
                 return;
-            this.overlay = runtime.createOverlay(this.map);
-            this.overlay.setLayers(this.pendingLayers);
+            const overlay = runtime.createOverlay({
+                map: this.map,
+                onLoad: () => {
+                    if (this.overlay === overlay)
+                        this.statusHandlers?.onReady();
+                },
+                onError: cause => this.handleOverlayError(overlay, cause),
+            });
+            this.overlay = overlay;
+            overlay.setLayers(this.pendingLayers);
+        })
+            .catch((cause) => {
+            this.statusHandlers?.onError(cause);
         })
-            .catch(() => undefined)
             .finally(() => {
             this.overlayCreation = null;
         });
     }
+    handleOverlayError(overlay, cause) {
+        if (this.overlay !== overlay)
+            return;
+        // deck.gl can raise this mid render frame (e.g. picking); finalizing there tears down a running Deck.
+        queueMicrotask(() => overlay.finalize());
+        this.overlay = null;
+        this.statusHandlers?.onError(cause);
+    }
     loadRuntime() {
         if (this.runtime !== null)
             return Promise.resolve(this.runtime);
@@ -174,10 +197,16 @@ class DeckGlGoogleMapsLifecycle {
         this.heatmapLayers = new Map();
         this.heatmapLayerBuilderModule = null;
         this.syncing = null;
+        /** Load failures retry on every snapshot; each heatmap is reported once until the module loads. */
+        this.reportedLoadFailureIds = new Set();
     }
     /** Binds to the map and syncs if snapshot state is already held. */
     connect(map) {
         this.map = map;
+        this.overlayCoordinator.setStatusHandlers({
+            onReady: () => this.reportedLoadFailureIds.clear(),
+            onError: cause => this.handleOverlayError(cause),
+        });
         this.overlayCoordinator.connect(map);
         void this.sync();
     }
@@ -196,7 +225,9 @@ class DeckGlGoogleMapsLifecycle {
         this.map = null;
         this.heatmapConfigs = [];
         this.heatmapLayers.clear();
+        this.reportedLoadFailureIds.clear();
         this.syncing = null;
+        this.overlayCoordinator.setStatusHandlers(null);
         this.overlayCoordinator.destroy();
     }
     sync() {
@@ -217,25 +248,26 @@ class DeckGlGoogleMapsLifecycle {
             .then(([module]) => {
             this.heatmapLayerBuilderModule = module;
             this.syncing = null;
+            this.reportedLoadFailureIds.clear();
             if (this.map === null)
                 return;
             this.applyCurrentLayers(module);
         })
-            .catch(() => {
+            .catch((cause) => {
             this.syncing = null;
+            if (this.map === null)
+                return;
+            this.reportLoadFailure(cause);
         });
     }
     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;
-        });
+        const layers = [];
+        for (const config of this.heatmapConfigs) {
+            const layer = this.resolveLayer(module, config);
+            if (layer !== null)
+                layers.push(layer);
+        }
         for (const id of this.heatmapLayers.keys()) {
             if (!currentIds.has(id)) {
                 this.heatmapLayers.delete(id);
@@ -243,6 +275,61 @@ class DeckGlGoogleMapsLifecycle {
         }
         this.overlayCoordinator.setLayers(layers);
     }
+    resolveLayer(module, config) {
+        const tracked = this.heatmapLayers.get(config.id);
+        if (tracked !== undefined && esToolkit.isEqual(tracked.config, config)) {
+            return tracked.layer;
+        }
+        try {
+            const layer = module.buildDeckGlHeatmapLayer({
+                config,
+                onError: cause => this.handleLayerError({ module, config, layer, cause }),
+            });
+            this.heatmapLayers.set(config.id, { config, layer });
+            return layer;
+        }
+        catch (cause) {
+            this.heatmapLayers.set(config.id, { config, layer: null });
+            this.reportError([config], "renderer-update-failed", cause);
+            return null;
+        }
+    }
+    handleLayerError({ module, config, layer, cause, }) {
+        if (this.heatmapLayers.get(config.id)?.layer !== layer)
+            return;
+        const failed = { config, layer: null };
+        this.heatmapLayers.set(config.id, failed);
+        this.reportError([config], "renderer-update-failed", cause);
+        // deck.gl raises layer errors mid update/draw; finalizing the overlay there tears down a running Deck.
+        queueMicrotask(() => {
+            if (this.heatmapLayers.get(config.id) !== failed)
+                return;
+            this.applyCurrentLayers(module);
+        });
+    }
+    /** deck.gl cannot reuse layers of a finalized overlay; failed builds stay tracked so they are not re-reported. */
+    handleOverlayError(cause) {
+        for (const [id, tracked] of this.heatmapLayers) {
+            if (tracked.layer !== null)
+                this.heatmapLayers.delete(id);
+        }
+        this.reportLoadFailure(cause);
+    }
+    reportLoadFailure(cause) {
+        this.reportOnce(this.reportedLoadFailureIds, this.heatmapConfigs, "renderer-load-failed", cause);
+    }
+    reportOnce(reportedIds, configs, code, cause) {
+        const unreported = configs.filter(config => !reportedIds.has(config.id));
+        for (const config of unreported) {
+            reportedIds.add(config.id);
+        }
+        this.reportError(unreported, code, cause);
+    }
+    reportError(configs, code, cause) {
+        for (const config of configs) {
+            config.onError?.({ layerId: config.id, code, cause });
+        }
+    }
 }
 
 /**

package/index.esm.js

@@ -83,6 +83,7 @@ class DeckGlGoogleMapsOverlayCoordinator {
         this.runtime = null;
         this.loading = null;
         this.overlayCreation = null;
+        this.statusHandlers = null;
     }
     /** Associates the coordinator with a map and applies any pending layers. */
     connect(map) {
@@ -93,6 +94,10 @@ class DeckGlGoogleMapsOverlayCoordinator {
         }
         void this.syncOverlay();
     }
+    /** Receives async overlay readiness and failures, which callers cannot observe themselves. */
+    setStatusHandlers(handlers) {
+        this.statusHandlers = handlers;
+    }
     /** Starts loading the deck.gl overlay runtime without creating an overlay. */
     prepare() {
         return this.loadRuntime().then(() => undefined);
@@ -132,14 +137,32 @@ class DeckGlGoogleMapsOverlayCoordinator {
             .then(runtime => {
             if (this.map === null || this.pendingLayers.length === 0)
                 return;
-            this.overlay = runtime.createOverlay(this.map);
-            this.overlay.setLayers(this.pendingLayers);
+            const overlay = runtime.createOverlay({
+                map: this.map,
+                onLoad: () => {
+                    if (this.overlay === overlay)
+                        this.statusHandlers?.onReady();
+                },
+                onError: cause => this.handleOverlayError(overlay, cause),
+            });
+            this.overlay = overlay;
+            overlay.setLayers(this.pendingLayers);
+        })
+            .catch((cause) => {
+            this.statusHandlers?.onError(cause);
         })
-            .catch(() => undefined)
             .finally(() => {
             this.overlayCreation = null;
         });
     }
+    handleOverlayError(overlay, cause) {
+        if (this.overlay !== overlay)
+            return;
+        // deck.gl can raise this mid render frame (e.g. picking); finalizing there tears down a running Deck.
+        queueMicrotask(() => overlay.finalize());
+        this.overlay = null;
+        this.statusHandlers?.onError(cause);
+    }
     loadRuntime() {
         if (this.runtime !== null)
             return Promise.resolve(this.runtime);
@@ -173,10 +196,16 @@ class DeckGlGoogleMapsLifecycle {
         this.heatmapLayers = new Map();
         this.heatmapLayerBuilderModule = null;
         this.syncing = null;
+        /** Load failures retry on every snapshot; each heatmap is reported once until the module loads. */
+        this.reportedLoadFailureIds = new Set();
     }
     /** Binds to the map and syncs if snapshot state is already held. */
     connect(map) {
         this.map = map;
+        this.overlayCoordinator.setStatusHandlers({
+            onReady: () => this.reportedLoadFailureIds.clear(),
+            onError: cause => this.handleOverlayError(cause),
+        });
         this.overlayCoordinator.connect(map);
         void this.sync();
     }
@@ -195,7 +224,9 @@ class DeckGlGoogleMapsLifecycle {
         this.map = null;
         this.heatmapConfigs = [];
         this.heatmapLayers.clear();
+        this.reportedLoadFailureIds.clear();
         this.syncing = null;
+        this.overlayCoordinator.setStatusHandlers(null);
         this.overlayCoordinator.destroy();
     }
     sync() {
@@ -216,25 +247,26 @@ class DeckGlGoogleMapsLifecycle {
             .then(([module]) => {
             this.heatmapLayerBuilderModule = module;
             this.syncing = null;
+            this.reportedLoadFailureIds.clear();
             if (this.map === null)
                 return;
             this.applyCurrentLayers(module);
         })
-            .catch(() => {
+            .catch((cause) => {
             this.syncing = null;
+            if (this.map === null)
+                return;
+            this.reportLoadFailure(cause);
         });
     }
     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;
-        });
+        const layers = [];
+        for (const config of this.heatmapConfigs) {
+            const layer = this.resolveLayer(module, config);
+            if (layer !== null)
+                layers.push(layer);
+        }
         for (const id of this.heatmapLayers.keys()) {
             if (!currentIds.has(id)) {
                 this.heatmapLayers.delete(id);
@@ -242,6 +274,61 @@ class DeckGlGoogleMapsLifecycle {
         }
         this.overlayCoordinator.setLayers(layers);
     }
+    resolveLayer(module, config) {
+        const tracked = this.heatmapLayers.get(config.id);
+        if (tracked !== undefined && isEqual(tracked.config, config)) {
+            return tracked.layer;
+        }
+        try {
+            const layer = module.buildDeckGlHeatmapLayer({
+                config,
+                onError: cause => this.handleLayerError({ module, config, layer, cause }),
+            });
+            this.heatmapLayers.set(config.id, { config, layer });
+            return layer;
+        }
+        catch (cause) {
+            this.heatmapLayers.set(config.id, { config, layer: null });
+            this.reportError([config], "renderer-update-failed", cause);
+            return null;
+        }
+    }
+    handleLayerError({ module, config, layer, cause, }) {
+        if (this.heatmapLayers.get(config.id)?.layer !== layer)
+            return;
+        const failed = { config, layer: null };
+        this.heatmapLayers.set(config.id, failed);
+        this.reportError([config], "renderer-update-failed", cause);
+        // deck.gl raises layer errors mid update/draw; finalizing the overlay there tears down a running Deck.
+        queueMicrotask(() => {
+            if (this.heatmapLayers.get(config.id) !== failed)
+                return;
+            this.applyCurrentLayers(module);
+        });
+    }
+    /** deck.gl cannot reuse layers of a finalized overlay; failed builds stay tracked so they are not re-reported. */
+    handleOverlayError(cause) {
+        for (const [id, tracked] of this.heatmapLayers) {
+            if (tracked.layer !== null)
+                this.heatmapLayers.delete(id);
+        }
+        this.reportLoadFailure(cause);
+    }
+    reportLoadFailure(cause) {
+        this.reportOnce(this.reportedLoadFailureIds, this.heatmapConfigs, "renderer-load-failed", cause);
+    }
+    reportOnce(reportedIds, configs, code, cause) {
+        const unreported = configs.filter(config => !reportedIds.has(config.id));
+        for (const config of unreported) {
+            reportedIds.add(config.id);
+        }
+        this.reportError(unreported, code, cause);
+    }
+    reportError(configs, code, cause) {
+        for (const config of configs) {
+            config.onError?.({ layerId: config.id, code, cause });
+        }
+    }
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-map-adapter-google",
-  "version": "0.0.148-alpha-7afddbbe4cc.0",
+  "version": "0.0.149-alpha-3bf54986a78.0",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
@@ -14,9 +14,9 @@
     "@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.158-alpha-7afddbbe4cc.0",
-    "@trackunit/react-map-color-utils": "0.0.133-alpha-7afddbbe4cc.0",
-    "@trackunit/geo-json-utils": "1.18.7-alpha-7afddbbe4cc.0",
+    "@trackunit/react-map-adapter-shared": "0.0.159-alpha-3bf54986a78.0",
+    "@trackunit/react-map-color-utils": "0.0.133-alpha-3bf54986a78.0",
+    "@trackunit/geo-json-utils": "1.18.7-alpha-3bf54986a78.0",
     "@googlemaps/markerclusterer": "^2.6.2",
     "@vis.gl/react-google-maps": "^1.7.1",
     "es-toolkit": "^1.52.0",

package/src/deckGl/DeckGlGoogleMapsLifecycle.d.ts

@@ -1,8 +1,9 @@
 import type { Layer } from "@deck.gl/core";
-import type { HeatmapSourceConfig, LayerSnapshot } from "@trackunit/react-map-adapter-shared";
+import type { LayerSnapshot } from "@trackunit/react-map-adapter-shared";
+import type { BuildDeckGlHeatmapLayerOptions } from "../heatmap/buildDeckGlHeatmapLayer";
 import { DeckGlGoogleMapsOverlayCoordinator } from "./DeckGlGoogleMapsOverlayCoordinator";
 type HeatmapLayerBuilderModule = Readonly<{
-    buildDeckGlHeatmapLayer: (config: HeatmapSourceConfig) => Layer;
+    buildDeckGlHeatmapLayer: (options: BuildDeckGlHeatmapLayerOptions) => Layer;
 }>;
 type LoadHeatmapLayerBuilder = () => Promise<HeatmapLayerBuilderModule>;
 /**
@@ -20,6 +21,8 @@ export declare class DeckGlGoogleMapsLifecycle {
     private readonly heatmapLayers;
     private heatmapLayerBuilderModule;
     private syncing;
+    /** Load failures retry on every snapshot; each heatmap is reported once until the module loads. */
+    private readonly reportedLoadFailureIds;
     constructor(overlayCoordinator?: DeckGlGoogleMapsOverlayCoordinator, loadHeatmapLayerBuilder?: LoadHeatmapLayerBuilder);
     /** Binds to the map and syncs if snapshot state is already held. */
     connect(map: google.maps.Map): void;
@@ -34,5 +37,12 @@ export declare class DeckGlGoogleMapsLifecycle {
     destroy(): void;
     private sync;
     private applyCurrentLayers;
+    private resolveLayer;
+    private handleLayerError;
+    /** deck.gl cannot reuse layers of a finalized overlay; failed builds stay tracked so they are not re-reported. */
+    private handleOverlayError;
+    private reportLoadFailure;
+    private reportOnce;
+    private reportError;
 }
 export {};

package/src/deckGl/DeckGlGoogleMapsOverlayCoordinator.d.ts

@@ -1,6 +1,12 @@
 import type { Layer } from "@deck.gl/core";
 import type { DeckGlGoogleMapsOverlayRuntime } from "./createDeckGlGoogleMapsOverlayRuntime";
 export type LoadDeckGlGoogleMapsOverlayRuntime = () => Promise<DeckGlGoogleMapsOverlayRuntime>;
+export type DeckGlGoogleMapsOverlayStatusHandlers = Readonly<{
+    /** The overlay's WebGL device is ready. */
+    onReady: () => void;
+    /** Overlay creation failed, or deck.gl reported an overlay error (the overlay is then discarded). */
+    onError: (cause: unknown) => void;
+}>;
 /**
  * Owns a single deck.gl `GoogleMapsOverlay` on a Google map.
  *
@@ -15,9 +21,12 @@ export declare class DeckGlGoogleMapsOverlayCoordinator {
     private runtime;
     private loading;
     private overlayCreation;
+    private statusHandlers;
     constructor(loadOverlayRuntime?: LoadDeckGlGoogleMapsOverlayRuntime);
     /** Associates the coordinator with a map and applies any pending layers. */
     connect(map: google.maps.Map): void;
+    /** Receives async overlay readiness and failures, which callers cannot observe themselves. */
+    setStatusHandlers(handlers: DeckGlGoogleMapsOverlayStatusHandlers | null): void;
     /** Starts loading the deck.gl overlay runtime without creating an overlay. */
     prepare(): Promise<void>;
     /**
@@ -29,5 +38,6 @@ export declare class DeckGlGoogleMapsOverlayCoordinator {
     /** Finalizes the overlay and clears coordinator state. */
     destroy(): void;
     private syncOverlay;
+    private handleOverlayError;
     private loadRuntime;
 }

package/src/deckGl/createDeckGlGoogleMapsOverlayRuntime.d.ts

@@ -5,9 +5,16 @@ export type DeckGlGoogleMapsOverlayHandle = Readonly<{
     setLayers: (layers: ReadonlyArray<Layer>) => void;
     finalize: () => void;
 }>;
+export type CreateDeckGlGoogleMapsOverlayOptions = Readonly<{
+    map: google.maps.Map;
+    /** Called once deck.gl's WebGL device is ready. */
+    onLoad: () => void;
+    /** Receives deck.gl's async overlay errors, such as WebGL device creation failure or context loss. */
+    onError: (cause: unknown) => void;
+}>;
 /** Factory after lazy-loading `@deck.gl/google-maps`. */
 export type DeckGlGoogleMapsOverlayRuntime = Readonly<{
-    createOverlay: (map: google.maps.Map) => DeckGlGoogleMapsOverlayHandle;
+    createOverlay: (options: CreateDeckGlGoogleMapsOverlayOptions) => DeckGlGoogleMapsOverlayHandle;
 }>;
 /**
  * Creates one `GoogleMapsOverlay` per map.

package/src/heatmap/buildDeckGlHeatmapLayer.d.ts

@@ -1,8 +1,13 @@
 import { HeatmapLayer } from "@deck.gl/aggregation-layers";
 import type { GeoJsonFeature, HeatmapSourceConfig } from "@trackunit/react-map-adapter-shared";
+export type BuildDeckGlHeatmapLayerOptions = Readonly<{
+    config: HeatmapSourceConfig;
+    /** Receives deck.gl's async layer errors (setup and draw); draw errors repeat every frame. */
+    onError: (cause: unknown) => void;
+}>;
 /**
  * Maps {@link HeatmapSourceConfig} → deck.gl `HeatmapLayer` on Google Maps.
  *
  * Invoked from {@link DeckGlGoogleMapsLifecycle} after dynamic import.
  */
-export declare const buildDeckGlHeatmapLayer: (config: HeatmapSourceConfig) => HeatmapLayer<GeoJsonFeature>;
+export declare const buildDeckGlHeatmapLayer: ({ config, onError, }: BuildDeckGlHeatmapLayerOptions) => HeatmapLayer<GeoJsonFeature>;