fix: graceful fallback when indicator has no grid overlay

The overlay was disappearing completely when clicking between
indicators if any of them hit the raster→grid fallback path — the
frontend fell through to _renderStatusOverlay() which (after the AOI
rectangle was removed) did nothing visible, leaving a blank map with
no feedback.

Backend:
- raster_to_grid_dict() now handles all-NaN rasters by emitting an
empty grid so the legend still renders instead of returning None
- _save_spatial_json() logs the raster path + band + existence when
serializing, and writes a richer raster-unavailable payload (with
label, colormap, vmin, vmax) so the frontend can still show a
meaningful legend

Frontend:
- renderSpatialOverlay() no longer falls through to the old status
overlay — unknown/fallback payloads render the legend in its new
"overlay not available" mode with the product name + color hint
- new _activeProductId tracking drops stale spatial responses when
the user clicks through indicators rapidly
- addSource/addLayer calls are wrapped in try/catch with console
logging so silent MapLibre failures stop being invisible

CSS:
- .map-legend-unavailable block styled in warm ember tones matching
the MERLx "caution" palette

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

app/outputs/spatial_web.py

@@ -7,6 +7,7 @@ of just a tinted AOI rectangle.
 """
 from __future__ import annotations
 
+import logging
 import math
 from typing import Any
 
@@ -14,6 +15,8 @@ import numpy as np
 
 from app.eo_products.base import SpatialData
 
+logger = logging.getLogger(__name__)
+
 # Target grid size for the web overlay. Small enough that MapLibre can
 # render as GeoJSON polygons without lagging, large enough to still
 # look like a heatmap rather than a mosaic.
@@ -41,6 +44,7 @@ def raster_to_grid_dict(
     try:
         import rasterio
     except ImportError:
+        logger.warning("raster_to_grid_dict: rasterio not available")
         return None
 
     try:
@@ -49,10 +53,12 @@ def raster_to_grid_dict(
             data = src.read(band).astype(np.float32)
             nodata = src.nodata
             bounds = src.bounds
-    except Exception:
+    except Exception as exc:
+        logger.warning("raster_to_grid_dict: cannot open %s (%s)", raster_path, exc)
         return None
 
     if data.size == 0:
+        logger.warning("raster_to_grid_dict: empty data array for %s", raster_path)
         return None
 
     if nodata is not None:
@@ -74,17 +80,31 @@ def raster_to_grid_dict(
     lats = np.linspace(bounds.bottom, bounds.top, ny + 1)
 
     # Determine value range, preferring product-supplied vmin/vmax.
-    vmin = spatial.vmin if spatial.vmin is not None else float(np.nanmin(data))
-    vmax = spatial.vmax if spatial.vmax is not None else float(np.nanmax(data))
-    if not math.isfinite(vmin) or not math.isfinite(vmax) or vmin == vmax:
+    vmin: float
+    vmax: float
+    if spatial.vmin is not None:
+        vmin = float(spatial.vmin)
+    else:
+        valid = data[np.isfinite(data)]
+        vmin = float(np.nanmin(valid)) if valid.size else float("nan")
+    if spatial.vmax is not None:
+        vmax = float(spatial.vmax)
+    else:
         valid = data[np.isfinite(data)]
-        if valid.size == 0:
-            return None
-        vmin = float(np.nanmin(valid))
-        vmax = float(np.nanmax(valid))
-        if vmin == vmax:
-            vmin -= 0.5
-            vmax += 0.5
+        vmax = float(np.nanmax(valid)) if valid.size else float("nan")
+
+    if not math.isfinite(vmin) or not math.isfinite(vmax):
+        # All values were NaN — still render an empty grid rather than
+        # dropping the indicator entirely, so the frontend can at least
+        # show the legend and the user knows the indicator was processed.
+        logger.warning(
+            "raster_to_grid_dict: all values NaN for %s; rendering empty grid",
+            raster_path,
+        )
+        vmin, vmax = 0.0, 1.0
+    elif vmin == vmax:
+        vmin -= 0.5
+        vmax += 0.5
 
     stops = _colormap_stops(spatial.colormap or "RdYlGn", vmin, vmax, n=5)
 

app/worker.py

@@ -45,8 +45,15 @@ def _save_spatial_json(spatial, status_value: str, path: str, product_obj=None)
         from app.outputs.spatial_web import raster_to_grid_dict
         raster_path = getattr(product_obj, "_product_raster_path", None)
         render_band = getattr(product_obj, "_render_band", 1)
+        logger.info(
+            "Serializing raster spatial for %s: path=%s band=%s exists=%s",
+            getattr(product_obj, "id", "?"),
+            raster_path,
+            render_band,
+            os.path.exists(raster_path) if raster_path else False,
+        )
         grid = None
-        if raster_path:
+        if raster_path and os.path.exists(raster_path):
             grid = raster_to_grid_dict(
                 raster_path,
                 band=render_band,
@@ -56,8 +63,20 @@ def _save_spatial_json(spatial, status_value: str, path: str, product_obj=None)
         if grid is not None:
             obj = grid
         else:
-            # Fall back to a status-only overlay so the frontend still renders.
-            obj = {"map_type": "status", "status": status_value, "label": spatial.label}
+            # Fall back to a descriptive payload so the frontend can still
+            # show the legend + color hint instead of blanking the map.
+            logger.warning(
+                "No grid spatial for %s — falling back to no-overlay payload",
+                getattr(product_obj, "id", "?"),
+            )
+            obj = {
+                "map_type": "raster-unavailable",
+                "status": status_value,
+                "label": spatial.label,
+                "colormap": spatial.colormap,
+                "vmin": spatial.vmin,
+                "vmax": spatial.vmax,
+            }
     elif spatial.map_type == "grid":
         obj = {
             "map_type": "grid",

frontend/css/merlx.css

@@ -1055,6 +1055,16 @@ h1, h2, h3, h4, h5, h6 {
   line-height: 1.45;
 }
 
+.map-legend-unavailable {
+  font-size: var(--text-micro);
+  color: var(--ember);
+  line-height: 1.45;
+  background: var(--ember-dim);
+  border-radius: var(--radius-sm);
+  padding: var(--space-3) var(--space-4);
+  margin-bottom: var(--space-3);
+}
+
 .results-panel {
   flex: 0 0 35%;
   background-color: var(--surface);

frontend/js/map.js

@@ -282,7 +282,20 @@ export function renderSpatialOverlay(spatialData) {
   } else if (mapType === 'grid' && spatialData.data) {
     _renderGrid(spatialData);
   } else {
-    _renderStatusOverlay(status);
+    // Raster was not convertible to a grid (old pre-fix job, or the
+    // backend couldn't read the raster file). Show the legend with a
+    // plain-language explanation so clicking indicators doesn't just
+    // blank the map with no feedback.
+    _showLegend({
+      label: spatialData.label || '',
+      productId: spatialData.product_id,
+      stops: Array.isArray(spatialData.stops) && spatialData.stops.length
+        ? spatialData.stops
+        : null,
+      vmin: spatialData.vmin,
+      vmax: spatialData.vmax,
+      unavailable: true,
+    });
   }
 }
 
@@ -390,17 +403,22 @@ function _renderGrid(spatialData) {
     );
   }
 
-  _resultsMap.addSource('spatial-grid', { type: 'geojson', data: geojson });
-  _resultsMap.addLayer({
-    id: 'spatial-grid',
-    type: 'fill',
-    source: 'spatial-grid',
-    paint: {
-      'fill-color': colorExpr,
-      'fill-opacity': 0.55,
-      'fill-outline-color': 'rgba(0,0,0,0)',
-    },
-  });
+  try {
+    _resultsMap.addSource('spatial-grid', { type: 'geojson', data: geojson });
+    _resultsMap.addLayer({
+      id: 'spatial-grid',
+      type: 'fill',
+      source: 'spatial-grid',
+      paint: {
+        'fill-color': colorExpr,
+        'fill-opacity': 0.55,
+        'fill-outline-color': 'rgba(0,0,0,0)',
+      },
+    });
+  } catch (err) {
+    console.error('spatial-grid render failed', err);
+    return;
+  }
 
   // Fit the map to the grid extent so the overlay is always visible.
   const bounds = [
@@ -451,10 +469,26 @@ const COLOR_HINTS = {
   buildup: 'Magenta = likely built-up. Green = vegetated / non-built-up. The classification uses a persistence filter.',
 };
 
-function _showLegend({ label, productId, stops, vmin, vmax }) {
+function _showLegend({ label, productId, stops, vmin, vmax, unavailable }) {
   const el = _ensureLegend();
   if (!el) return;
 
+  const hint = COLOR_HINTS[productId] || '';
+  const productName = PRODUCT_NAMES[productId] || label || 'Indicator';
+
+  if (unavailable) {
+    el.innerHTML = `
+      <div class="map-legend-title">${_escHtml(productName)}</div>
+      <div class="map-legend-unavailable">
+        Map overlay not available for this indicator in this job.
+        Re-run the analysis to see the pixel-level layer.
+      </div>
+      ${hint ? `<div class="map-legend-hint">${_escHtml(hint)}</div>` : ''}
+    `;
+    el.style.display = 'block';
+    return;
+  }
+
   let gradientCss = '';
   if (Array.isArray(stops) && stops.length >= 2) {
     const parts = stops.map((s, i) => {
@@ -466,12 +500,11 @@ function _showLegend({ label, productId, stops, vmin, vmax }) {
     gradientCss = 'linear-gradient(to right, #e6e6e6, #6e6e6e)';
   }
 
-  const hint = COLOR_HINTS[productId] || '';
   const lo = Number.isFinite(vmin) ? _fmtNum(vmin) : '';
   const hi = Number.isFinite(vmax) ? _fmtNum(vmax) : '';
 
   el.innerHTML = `
-    <div class="map-legend-title">${_escHtml(label || 'Indicator')}</div>
+    <div class="map-legend-title">${_escHtml(productName)}</div>
     <div class="map-legend-bar" style="background: ${gradientCss}"></div>
     <div class="map-legend-scale">
       <span>${_escHtml(lo)}</span>
@@ -482,6 +515,13 @@ function _showLegend({ label, productId, stops, vmin, vmax }) {
   el.style.display = 'block';
 }
 
+const PRODUCT_NAMES = {
+  ndvi:    'Vegetation health',
+  water:   'Water bodies',
+  sar:     'Ground surface change',
+  buildup: 'Built-up areas',
+};
+
 function _hideLegend() {
   if (_legendEl) _legendEl.style.display = 'none';
 }

frontend/js/results.js

@@ -515,21 +515,32 @@ function _esc(str) {
     .replace(/"/g, '"');
 }
 
+let _activeProductId = null;
+
 function _showMapForProduct(productId) {
   if (!_currentJobId || !_currentBbox) return;
+  _activeProductId = productId;
   const url = spatialUrl(_currentJobId, productId);
   fetch(url, { headers: authHeaders() })
     .then(res => {
       if (res.ok) return res.json();
-      clearSpatialOverlay();
       return null;
     })
     .then(data => {
+      // Drop any stale response that arrived after the user clicked
+      // through — keeps the visible overlay in sync with the active card.
+      if (productId !== _activeProductId) return;
       if (data) {
-        // Tag the payload so the map legend knows which color hint to show.
         data.product_id = productId;
         renderSpatialOverlay(data);
+      } else {
+        renderSpatialOverlay({ map_type: 'raster-unavailable', product_id: productId });
       }
     })
-    .catch(() => clearSpatialOverlay());
+    .catch(err => {
+      console.error('spatial fetch failed', err);
+      if (productId === _activeProductId) {
+        renderSpatialOverlay({ map_type: 'raster-unavailable', product_id: productId });
+      }
+    });
 }