fix(map): patch Popup.prototype instead of the maplibre namespace (#1509)

Globe popup occlusion was installed by replacing `maplibregl.Popup` with a
subclass. That relies on the namespace being a mutable object, which is only
true of MapLibre v5's CJS/UMD default export. A v6 ESM module namespace is
sealed, so the assignment throws at map construction:

    TypeError: Cannot assign to property 'Popup' of [object Module]

and the map canvas never mounts (#1489, blocker 3).

Patch `Popup.prototype.addTo` instead. The namespace binding is frozen but the
`Popup` class it exposes is an ordinary mutable object, and `addTo` is the one
prototype method every popup passes through on its way onto a map
(`Marker#togglePopup` routes through it too). The wrap runs before MapLibre's
own `_update()`/`_updateOpacity()`, so the first painted frame is correct.
`_updateOpacity` is assigned as an instance arrow inside the Popup constructor,
so it shadows the prototype and still has to be wrapped per instance.

This keeps the behavior identical and widens coverage, since the namespace swap
never reached:

- plugins that `import { Popup } from "maplibre-gl"` by name and call
  `new Popup()` — `maplibre-gl-raster` and our own reverse-geocode plugin both
  do, so their popups had no occlusion at all
- popups or `extends maplibregl.Popup` subclasses created before install ran

Also fix a second v6 break in the same file that fails silently. v6 stopped
having `Map extend Camera`, so `map.transform` is gone and its own Popup reads
`_map._camera.transform`. The occlusion mirror read `_map.transform`, which is
`undefined` under v6 — optional-chained, so no error, the check just never runs
and back-of-globe popups stay visible. Both locations are now resolved in one
documented helper.

Verified against real maplibre-gl 5.24.0 and 6.0.0 module objects, and in a
browser on the running app: a popup at [180, 0] with the camera at [0, 0] under
the globe projection is hidden and restores when the globe is rotated to face
it.

Author: giswqs

packages/map/src/globe-popup-occlusion.ts

@@ -1,34 +1,54 @@
-import type maplibregl from "maplibre-gl";
+import type { Popup, PopupOptions } from "maplibre-gl";
 
 /** JS-observable marker for occluded popups; visual hiding is applied inline. */
 export const GLOBE_POPUP_OCCLUDED_CLASS = "geolibre-globe-popup-occluded";
 
-const PATCHED_POPUP_MARKER = "__geolibreGlobePopupOcclusionPatched";
 const DEFAULT_OCCLUDED_OPACITY = 0;
 const ZERO_OPACITY_STRING = /^[+-]?(?:0+(?:\.0*)?|\.(?:0+))$/;
 
-type PopupConstructor = new (options?: maplibregl.PopupOptions) => maplibregl.Popup;
+// Registered with Symbol.for so a second copy of this module (a duplicated
+// @geolibre/map inside a plugin bundle) recognizes the first copy's work and
+// does not wrap `addTo` — or a popup's `_updateOpacity` — twice.
+const PATCHED_PROTOTYPE = Symbol.for("geolibre.globePopupOcclusion.patchedPrototype");
+const INSTRUMENTED_POPUP = Symbol.for("geolibre.globePopupOcclusion.instrumentedPopup");
+
+type PopupConstructor = new (options?: PopupOptions) => Popup;
+
+/**
+ * The slice of the MapLibre entry point this module touches.
+ *
+ * Typed structurally instead of as `typeof maplibregl` so it accepts both v5's
+ * mutable default-export object and v6's ESM module namespace object.
+ */
+export interface MapLibrePopupNamespace {
+  Popup: PopupConstructor;
+}
+
+interface PatchablePopupPrototype {
+  addTo: (this: unknown, map: unknown) => unknown;
+  [PATCHED_PROTOTYPE]?: true;
+}
 
-type PatchablePopupConstructor = PopupConstructor & {
-  [PATCHED_POPUP_MARKER]?: true;
-};
+interface OccludableTransform {
+  isLocationOccluded?: (lngLat: unknown) => boolean;
+}
 
-interface PatchableMapLibre {
-  Popup: PatchablePopupConstructor;
+interface PopupHostMap {
+  /** MapLibre v6: `Map` no longer extends `Camera`, so the transform moved here. */
+  _camera?: { transform?: OccludableTransform };
+  /** MapLibre v5: `Map extends Camera`, so the transform is on the map itself. */
+  transform?: OccludableTransform;
 }
 
 interface PopupInternals {
   _container?: HTMLElement;
-  _map?: {
-    transform?: {
-      isLocationOccluded?: (lngLat: unknown) => boolean;
-    };
-  };
-  _updateOpacity?: () => void;
+  _map?: PopupHostMap;
+  _updateOpacity?: (...args: unknown[]) => void;
   getLngLat: () => unknown;
   options?: {
     locationOccludedOpacity?: number | string | null;
   };
+  [INSTRUMENTED_POPUP]?: true;
 }
 
 interface InteractiveStyles {
@@ -38,6 +58,20 @@ interface InteractiveStyles {
 
 const hiddenPopupStyles = new WeakMap<HTMLElement, InteractiveStyles>();
 
+/**
+ * Resolve the transform MapLibre computes globe occlusion against.
+ *
+ * v6 split `Camera` out of `Map` and its own `Popup` reads
+ * `_map._camera.transform`; v5 exposes `_map.transform` directly. Both are
+ * checked because this module ships against either. Getting this wrong fails
+ * silently — the occlusion check just never runs — so it stays in one place.
+ */
+function resolveOccludableTransform(
+  map: PopupHostMap | undefined,
+): OccludableTransform | undefined {
+  return map?._camera?.transform ?? map?.transform;
+}
+
 function shouldSuppressInteraction(popup: PopupInternals): boolean {
   const opacity = popup.options?.locationOccludedOpacity;
   if (typeof opacity === "string") {
@@ -74,11 +108,11 @@ function setPopupOccluded(container: HTMLElement, occluded: boolean): void {
   container.style.visibility = "hidden";
 }
 
-export function syncPopupGlobeOcclusion(popup: maplibregl.Popup): boolean {
+export function syncPopupGlobeOcclusion(popup: Popup): boolean {
   const popupInternals = popup as unknown as PopupInternals;
   const container = popupInternals._container;
   const opacity = popupInternals.options?.locationOccludedOpacity;
-  const transform = popupInternals._map?.transform;
+  const transform = resolveOccludableTransform(popupInternals._map);
   const isLocationOccluded = transform?.isLocationOccluded;
 
   if (!container || opacity === undefined || opacity === null) {
@@ -93,27 +127,57 @@ export function syncPopupGlobeOcclusion(popup: maplibregl.Popup): boolean {
   return occluded;
 }
 
-export function installGlobePopupOcclusion(maplibre: typeof maplibregl): void {
-  const api = maplibre as unknown as PatchableMapLibre;
-  const OriginalPopup = api.Popup;
-  if (OriginalPopup[PATCHED_POPUP_MARKER]) return;
-
-  class GeoLibrePopup extends OriginalPopup {
-    constructor(options: maplibregl.PopupOptions = {}) {
-      super({
-        ...options,
-        locationOccludedOpacity: options.locationOccludedOpacity ?? DEFAULT_OCCLUDED_OPACITY,
-      });
-
-      const popup = this as unknown as PopupInternals;
-      const updateOpacity = popup._updateOpacity;
-      popup._updateOpacity = () => {
-        if (popup.getLngLat()) updateOpacity?.call(this);
-        syncPopupGlobeOcclusion(this);
-      };
-    }
+/**
+ * Give one popup instance the occlusion behavior: opt it into MapLibre's own
+ * occlusion math, then wrap the opacity update so the interaction suppression
+ * and marker class ride along.
+ *
+ * MapLibre assigns `_updateOpacity` as an instance arrow inside the `Popup`
+ * constructor, so it shadows anything installed on the prototype — the wrap has
+ * to happen per instance rather than once on `Popup.prototype`.
+ */
+function instrumentPopup(popup: PopupInternals): void {
+  if (popup[INSTRUMENTED_POPUP]) return;
+  popup[INSTRUMENTED_POPUP] = true;
+
+  // MapLibre skips the occlusion check entirely unless this option is set, so
+  // default it on every popup — including ones a plugin constructed itself.
+  if (popup.options) {
+    popup.options.locationOccludedOpacity ??= DEFAULT_OCCLUDED_OPACITY;
   }
 
-  GeoLibrePopup[PATCHED_POPUP_MARKER] = true;
-  api.Popup = GeoLibrePopup;
+  const updateOpacity = popup._updateOpacity;
+  popup._updateOpacity = (...args: unknown[]) => {
+    if (popup.getLngLat()) updateOpacity?.apply(popup, args);
+    syncPopupGlobeOcclusion(popup as unknown as Popup);
+  };
+}
+
+/**
+ * Install globe-occlusion behavior on every MapLibre popup, including ones
+ * constructed by third-party plugins.
+ *
+ * This patches `Popup.prototype.addTo` rather than replacing `maplibre.Popup`.
+ * A v6 module namespace object is sealed and rejects assignment
+ * (`TypeError: Cannot assign to property 'Popup' of [object Module]`), while
+ * the `Popup` class it exposes is an ordinary mutable object. Patching the
+ * prototype also reaches consumers a namespace swap never could: plugins that
+ * `import { Popup } from "maplibre-gl"` by name, and popups (or subclasses)
+ * created before this runs.
+ *
+ * `addTo` is the hook because it is the one prototype method every popup goes
+ * through on its way onto a map — `Marker#togglePopup` routes through it too —
+ * and it wraps before MapLibre's own `_update()`/`_updateOpacity()` runs, so
+ * the first painted frame is already correct.
+ */
+export function installGlobePopupOcclusion(maplibre: MapLibrePopupNamespace): void {
+  const prototype = maplibre.Popup.prototype as unknown as PatchablePopupPrototype;
+  if (prototype[PATCHED_PROTOTYPE]) return;
+
+  const originalAddTo = prototype.addTo;
+  prototype.addTo = function (this: unknown, map: unknown) {
+    instrumentPopup(this as PopupInternals);
+    return originalAddTo.call(this, map);
+  };
+  prototype[PATCHED_PROTOTYPE] = true;
 }