fix(stac): let a vector layer draw above STAC Search imagery (#1727)

A layer added from Add Data > STAC Layer covered every vector layer no matter
where the user put it in the Layers panel. Moving the vector to the top of the
panel changed nothing: its features stayed hidden wherever the imagery covered
them.

The STAC Search control renders its COGs as deck.gl layers through its own
`MapboxOverlay` built with `interleaved: false`. Such an overlay owns a separate
canvas stacked above the entire MapLibre style, so its layers cannot sit at any
depth within it. layer-sync could not help either: the layer has no real style
layer for `moveLayer` to move, and the store layer did not carry
`externalDeckLayer`, so the computed `beforeId` was never forwarded to anyone.

Route these layers through GeoLibre's single shared interleaved overlay instead
(the same one the web COG raster control, Google 3D Tiles and deck-viz already
share), each carrying the `beforeId` derived from the store's layer order. The
control's private overlay is no longer created, so the add / opacity / visibility
/ remove paths all re-render the shared one, and teardown clears the source.

`applyStacSearchLayerOrder` claims only ids the STAC Search control owns; the app
shell asks it first and falls through to the raster control for everything else.
The raster-tile variant of a STAC Search layer is a real MapLibre layer and keeps
reordering through `moveLayer` as before.

Fixes #1718

Author: giswqs

apps/geolibre-desktop/src/components/layout/DesktopShell.tsx

@@ -8,6 +8,7 @@ import {
   addRasterToMap,
   prepareRasterControl,
   applyRasterLayerOrder,
+  applyStacSearchLayerOrder,
   DECK_VIZ_PLUGIN_ID,
   DIRECTIONS_PLUGIN_ID,
   EFFECTS_PLUGIN_ID,
@@ -1158,10 +1159,15 @@ export function DesktopShell({
     // Re-read drag-dropped / Add Data local-file GeoJSON layers from disk
     // (their data was saved as a path, not embedded).
     void restoreLocalFileLayers();
-    // Let layer-sync push the store-derived beforeId into the raster control so
-    // deck.gl COG rasters interleave with vector layers instead of always
-    // drawing on top.
-    setExternalDeckLayerOrderHandler(applyRasterLayerOrder);
+    // Let layer-sync push the store-derived beforeId into the control that owns
+    // each deck.gl COG raster so it interleaves with vector layers instead of
+    // always drawing on top. Two controls render such layers: the raster
+    // control and the STAC Search control (#1718). The STAC one claims only its
+    // own layer ids, so ask it first and fall through for everything else.
+    setExternalDeckLayerOrderHandler((layerId, beforeId) => {
+      if (applyStacSearchLayerOrder(layerId, beforeId)) return;
+      applyRasterLayerOrder(layerId, beforeId);
+    });
     // activeByDefault plugins are marked active without activate() being
     // called, so the effects engine must be kicked explicitly to match the
     // restored active state (idempotent).

packages/plugins/src/index.ts

@@ -87,6 +87,7 @@ export {
   isViewStatePanelVisible,
   COMPONENTS_PLUGIN_ID,
   maplibreComponentsPlugin,
+  applyStacSearchLayerOrder,
   openBookmarkPanel,
   openFlatGeobufAddVectorLayerPanel,
   openColorbarPanel,

packages/plugins/src/plugins/maplibre-components.ts

@@ -74,6 +74,7 @@ import type { GaussianSplatControl, GaussianSplatLayerAdapter } from "maplibre-g
 import type { LidarControlEventHandler, PointCloudInfo } from "maplibre-gl-lidar";
 import type { GeoLibreAppAPI, GeoLibreMapControlPosition, GeoLibrePlugin } from "../types";
 import { ensureMercatorProjection } from "./map-projection-utils";
+import { ensureSharedDeckOverlay, setSharedDeckLayers } from "./shared-deck-overlay";
 import { attachTerrainMeasure, measurePanelElement, type TerrainMapLike } from "./terrain-measure";
 import { INTERNAL_HELPER_LAYER_PATTERNS } from "./internal-layers";
 import {
@@ -732,6 +733,12 @@ let bookmarkControl: BookmarkControl | null = null;
 let minimapControl: MinimapControl | null = null;
 let viewStateControl: ViewStateControl | null = null;
 let stacSearchControl: StacSearchControl | null = null;
+// The host API the STAC Search control was opened with, kept so its deck.gl COG
+// layers can reach the shared interleaved overlay from the patched hooks below.
+let stacSearchApp: GeoLibreAppAPI | null = null;
+// Store-derived `beforeId` per STAC Search deck layer id, pushed in by
+// `applyStacSearchLayerOrder`. See `renderStacSearchDeckLayers`.
+const stacSearchBeforeIds = new Map<string, string | undefined>();
 let zarrControl: ZarrLayerControl | null = null;
 let colorbarControl: ColorbarGuiControl | null = null;
 let legendControl: LegendGuiControl | null = null;
@@ -3124,6 +3131,7 @@ async function openStandaloneViewStateControl(app: GeoLibreAppAPI): Promise<bool
 async function openStandaloneStacSearchControl(app: GeoLibreAppAPI): Promise<boolean> {
   const { StacSearchControl: StacSearchControlClass } = await getComponentsConstructors();
 
+  stacSearchApp = app;
   stacSearchControl ??= createStacSearchControl(StacSearchControlClass);
 
   if (!stacSearchControlMounted) {
@@ -4320,6 +4328,10 @@ function teardownStacSearchControl(app: GeoLibreAppAPI): void {
   }
   stacSearchControl = null;
   stacSearchControlMounted = false;
+  stacSearchApp = null;
+  // Its deck layers live in the shared overlay, which outlives this control.
+  stacSearchBeforeIds.clear();
+  setSharedDeckLayers("stac-search", []);
 }
 
 function hideSearchControl(): void {
@@ -5432,6 +5444,11 @@ function createStacSearchStoreLayer(
     metadata: {
       collectionId,
       customLayerType: "raster",
+      // The COG variant renders as a deck.gl layer with no MapLibre style layer
+      // to move, so layer-sync must hand its computed `beforeId` to the control
+      // instead of calling `moveLayer` (#1718). The raster-tile variant is a
+      // real style layer and reorders normally.
+      ...(rasterLayerInfo ? {} : { externalDeckLayer: true }),
       externalNativeLayer: true,
       identifiable: false,
       nativeLayerIds,
@@ -5597,6 +5614,10 @@ function patchStacSearchRemoveLayer(control: StacSearchControl): void {
   mutableControl._removeLayer = (id?: string) => {
     const layerIds = id ? [id] : Array.from(mutableControl._cogLayers?.keys() ?? []);
     removeLayer(id);
+    // Upstream repaints its own overlay, which GeoLibre bypasses, so drop the
+    // removed layers from the shared interleaved overlay here (#1718).
+    for (const layerId of layerIds) stacSearchBeforeIds.delete(layerId);
+    renderStacSearchDeckLayers();
     const store = useAppStore.getState();
     for (const layerId of layerIds) {
       const layer = store.layers.find((item) => item.id === layerId);
@@ -5628,7 +5649,10 @@ function patchStacSearchCogLayer(control: StacSearchControl): void {
 
   mutableControl._addCogLayer = async (url: string, item: StacSearchItem, assetKey: string) => {
     ensureMercatorProjection(mutableControl._map);
-    await mutableControl._ensureOverlay?.();
+    // Deliberately NOT `_ensureOverlay()`: that builds the control's own
+    // non-interleaved overlay, which can never be ordered against the style.
+    // The shared interleaved overlay renders these layers instead (#1718).
+    if (stacSearchApp) await ensureSharedDeckOverlay(stacSearchApp);
     const selectedAsset = getStacSearchSelectedAsset(mutableControl, item, {
       key: assetKey,
       url,
@@ -5655,9 +5679,7 @@ function patchStacSearchCogLayer(control: StacSearchControl): void {
       ...renderProps,
     });
     mutableControl._cogLayers?.set(id, layer as unknown as Layer);
-    mutableControl._deckOverlay?.setProps({
-      layers: Array.from(mutableControl._cogLayers?.values() ?? []) as Layer[],
-    });
+    renderStacSearchDeckLayers();
     if (mutableControl._state) {
       mutableControl._state.hasLayer = true;
       mutableControl._state.layerCount = mutableControl._cogLayers?.size ?? 0;
@@ -6008,9 +6030,7 @@ function setStacSearchControlLayerState(id: string, visible: boolean, opacity: n
     id,
     layer.clone({ opacity: appliedOpacity }) as StacSearchRenderableLayer,
   );
-  mutableControl?._deckOverlay?.setProps({
-    layers: getStacSearchDeckLayers(mutableControl),
-  });
+  renderStacSearchDeckLayers();
 }
 
 function getStacSearchDeckLayers(control: MutableStacSearchControl): Layer[] {
@@ -6019,6 +6039,50 @@ function getStacSearchDeckLayers(control: MutableStacSearchControl): Layer[] {
   );
 }
 
+/**
+ * Pushes the STAC Search control's deck.gl COG layers into GeoLibre's shared
+ * interleaved overlay, each carrying the `beforeId` derived from the store's
+ * layer order.
+ *
+ * Upstream renders them through the control's own non-interleaved
+ * `MapboxOverlay`, which owns a separate canvas stacked above the entire
+ * MapLibre style — so STAC imagery covered every vector layer no matter where
+ * the user placed it in the Layers panel (opengeos/GeoLibre#1718). Interleaved
+ * layers are drawn inside the style instead, at the depth their `beforeId`
+ * selects, which is what makes panel order mean anything for them.
+ */
+function renderStacSearchDeckLayers(): void {
+  const control = stacSearchControl as unknown as MutableStacSearchControl | null;
+  if (!control) return;
+  const layers = getStacSearchDeckLayers(control).map((layer) => {
+    const beforeId = stacSearchBeforeIds.get(layer.id);
+    if ((layer.props as { beforeId?: string }).beforeId === beforeId) return layer;
+    return layer.clone({ beforeId } as unknown as Partial<Layer["props"]>);
+  });
+  setSharedDeckLayers("stac-search", layers);
+}
+
+/**
+ * Applies a store-derived draw order to a STAC Search deck.gl COG layer.
+ *
+ * Registered by the app shell as part of the external deck-layer order handler:
+ * such a layer is not a real MapLibre style layer, so `moveLayer` cannot reorder
+ * it and layer-sync forwards the computed `beforeId` here instead.
+ *
+ * @param layerId - The store layer id, which doubles as the deck layer id.
+ * @param beforeId - The style layer to draw beneath, or undefined for the top.
+ * @returns True when the id belongs to the STAC Search control.
+ */
+export function applyStacSearchLayerOrder(layerId: string, beforeId: string | undefined): boolean {
+  const control = stacSearchControl as unknown as MutableStacSearchControl | null;
+  const layer = control?._cogLayers?.get(layerId);
+  if (!layer || getStacSearchRasterLayerInfo(layer)) return false;
+  if (stacSearchBeforeIds.get(layerId) === beforeId) return true;
+  stacSearchBeforeIds.set(layerId, beforeId);
+  renderStacSearchDeckLayers();
+  return true;
+}
+
 function getStacSearchRasterLayerInfo(
   layer: StacSearchRenderableLayer,
 ): { layerId: string; sourceId: string; tileUrl?: string } | null {

packages/plugins/src/plugins/shared-deck-overlay.ts

@@ -32,7 +32,13 @@ type DeviceListener = (device: unknown) => void;
  * position stays visible above the 3D track it rides (see #1210).
  * Ordering WITHIN a source is whatever order that source supplies.
  */
-const SOURCE_DRAW_ORDER = ["raster", "google-3d-tiles", "deckviz", "route-anim"] as const;
+const SOURCE_DRAW_ORDER = [
+  "raster",
+  "stac-search",
+  "google-3d-tiles",
+  "deckviz",
+  "route-anim",
+] as const;
 export type SharedDeckSource = (typeof SOURCE_DRAW_ORDER)[number];
 
 let overlay: MapboxOverlay | null = null;

tests/external-deck-order.test.ts

@@ -62,6 +62,28 @@ describe("external deck-layer order handler", () => {
     assert.deepEqual(calls, [["raster-1", undefined]]);
   });
 
+  it("forwards the beforeId for a STAC Search COG layer", () => {
+    const calls: Array<[string, string | undefined]> = [];
+    setExternalDeckLayerOrderHandler((id, beforeId) => calls.push([id, beforeId]));
+
+    // The STAC Search control renders its COGs as deck layers too, so its store
+    // layers must carry the same flag or their imagery would keep drawing above
+    // every vector layer whatever the panel order says (#1718).
+    const layer = rasterDeckLayer();
+    layer.id = "stac-search-item-visual-0";
+    layer.metadata = {
+      customLayerType: "raster",
+      externalDeckLayer: true,
+      externalNativeLayer: true,
+      nativeLayerIds: ["stac-search-item-visual-0"],
+      sourceIds: [],
+      sourceKind: "stac-search-cog",
+    };
+    syncLayer(makeMapStub() as never, layer, "vector-line");
+
+    assert.deepEqual(calls, [["stac-search-item-visual-0", "vector-line"]]);
+  });
+
   it("does not fire for a non-deck external custom layer", () => {
     const calls: unknown[] = [];
     setExternalDeckLayerOrderHandler((id, beforeId) => calls.push([id, beforeId]));

tests/shared-deck-overlay.test.ts

@@ -86,8 +86,18 @@ describe("shared-deck-overlay", () => {
       "raster drawn first (bottom), deckviz last (top)",
     );
 
+    // STAC Search COGs are imagery too, so they sit with the rasters at the
+    // bottom rather than above the 3D tiles / vector overlays (#1718).
+    setSharedDeckLayers("stac-search", [layer("s1")] as never);
+    assert.deepEqual(
+      overlay?.layerIds(),
+      ["r1", "s1", "g1", "d1"],
+      "STAC Search imagery draws with the rasters, under google and deckviz",
+    );
+
     // Cleanup for the next test.
     setSharedDeckLayers("raster", [] as never);
+    setSharedDeckLayers("stac-search", [] as never);
     setSharedDeckLayers("google-3d-tiles", [] as never);
     setSharedDeckLayers("deckviz", [] as never);
     assert.deepEqual(overlay?.layerIds(), []);