feat: add staleness indicators for sources and vehicles

Show an orange warning icon next to sources that haven't received data
in 30+ minutes, with a tooltip showing how long ago data was last seen.
Hide vehicles from the realtime map if they haven't reported in 2 hours
(down from 24h). The /sources endpoint now includes a last_updated
timestamp derived from the in-memory snapshot.

Author: jackharrhy

CHANGELOG.md

@@ -1,6 +1,16 @@
-<!-- changelog-id: 7 -->
+<!-- changelog-id: 8 -->
 # Changelog
 
+## 2026-02-24 — Stale Data Indicators
+The St. John's data source is currently experiencing technical difficulties on
+the city's end. To make situations like this visible, the map now shows an
+orange warning icon next to any source that hasn't received fresh data in a
+while. Hovering over it tells you how long it's been. Vehicles that haven't
+reported a position recently are also hidden from the realtime view so the map
+only shows what's actually moving.
+
+[View changes](https://github.com/jackharrhy/where-the-plow/compare/e32ec39...HEAD)
+
 ## 2026-02-23 — Ko-fi Support Button
 A "Support me on Ko-fi" button now appears in the sidebar, if you'd like to
 help keep the servers running.

src/where_the_plow/routes.py

@@ -140,22 +140,46 @@ def _rows_to_feature_collection(rows: list[dict], limit: int) -> FeatureCollecti
     )
 
 
+def _source_last_updated(snapshots: dict[str, dict], source_name: str) -> str | None:
+    """Derive the most recent vehicle timestamp from a source's cached snapshot."""
+    fc = snapshots.get(source_name)
+    if not fc:
+        return None
+    features = fc.get("features", [])
+    if not features:
+        return None
+    latest = max(
+        (
+            f["properties"]["timestamp"]
+            for f in features
+            if f.get("properties", {}).get("timestamp")
+        ),
+        default=None,
+    )
+    return latest
+
+
 @router.get(
     "/sources",
     summary="Available data sources",
-    description="Returns metadata about each configured plow data source.",
+    description="Returns metadata about each configured plow data source, "
+    "including the timestamp of the most recent vehicle position per source.",
     tags=["sources"],
 )
-def get_sources():
+def get_sources(request: Request):
     from where_the_plow.config import SOURCES
 
+    store = getattr(request.app.state, "store", {})
+    snapshots = store.get("realtime", {})
+
     return {
         name: {
             "display_name": src.display_name,
             "center": list(src.center),
             "zoom": src.zoom,
             "enabled": src.enabled,
             "min_coverage_zoom": src.min_coverage_zoom,
+            "last_updated": _source_last_updated(snapshots, name),
         }
         for name, src in SOURCES.items()
         if src.enabled

src/where_the_plow/static/app.js

@@ -816,6 +816,8 @@ plowMap.on("moveend", () => {
 /* ── Utilities ─────────────────────────────────────── */
 
 const ONE_DAY_MS = 24 * 60 * 60 * 1000;
+const VEHICLE_STALE_MS = 2 * 60 * 60 * 1000; // hide vehicles not seen in 2 hours
+const SOURCE_STALE_MS = 30 * 60 * 1000; // warn if source has no data in 30 minutes
 
 const VEHICLE_COLORS = {
   "SA PLOW TRUCK": "#2563eb",
@@ -863,6 +865,17 @@ function formatTimestamp(ts) {
   });
 }
 
+function formatDurationAgo(ms) {
+  const minutes = Math.floor(ms / 60000);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  const remainMin = minutes % 60;
+  if (hours < 24) return remainMin > 0 ? `${hours}h ${remainMin}m ago` : `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  const remainHrs = hours % 24;
+  return remainHrs > 0 ? `${days}d ${remainHrs}h ago` : `${days}d ago`;
+}
+
 /** Get padded viewport bounds for coverage culling. */
 function getPaddedBounds(map, padding) {
   const b = map.getBounds();
@@ -917,7 +930,7 @@ function updateVehicleCount(data) {
 }
 
 function filterRecentFeatures(data) {
-  const cutoff = Date.now() - ONE_DAY_MS;
+  const cutoff = Date.now() - VEHICLE_STALE_MS;
   return {
     ...data,
     features: data.features.filter(
@@ -1162,13 +1175,25 @@ class PlowApp {
 
       const text = document.createTextNode(src.display_name);
       label.appendChild(text);
+
+      // Staleness warning indicator
+      const staleIcon = document.createElement("span");
+      staleIcon.className = "source-stale-icon";
+      staleIcon.dataset.source = key;
+      staleIcon.textContent = "!";
+      staleIcon.style.display = "none";
+      label.appendChild(staleIcon);
+
       label.appendChild(cb);
 
       row.appendChild(zoomBtn);
       row.appendChild(label);
       container.appendChild(row);
     }
 
+    // Initial staleness check
+    this.updateSourceStaleness();
+
     // Also add a "Types" section title to the vehicle legend (idempotent)
     const vehicleLegend = document.getElementById("legend-vehicles");
     if (!vehicleLegend.querySelector(".legend-section-title")) {
@@ -1179,6 +1204,25 @@ class PlowApp {
     }
   }
 
+  updateSourceStaleness() {
+    const now = Date.now();
+    for (const [key, src] of Object.entries(this.sources)) {
+      const icon = document.querySelector(`.source-stale-icon[data-source="${key}"]`);
+      if (!icon) continue;
+
+      const lastUpdated = src.last_updated ? new Date(src.last_updated).getTime() : 0;
+      const age = now - lastUpdated;
+
+      if (!src.last_updated || age > SOURCE_STALE_MS) {
+        const agoText = src.last_updated ? formatDurationAgo(age) : "never";
+        icon.title = `No data received (last: ${agoText})`;
+        icon.style.display = "";
+      } else {
+        icon.style.display = "none";
+      }
+    }
+  }
+
   getSourceDisplayName(sourceKey) {
     const src = this.sources[sourceKey];
     return src ? src.display_name : sourceKey;
@@ -1686,6 +1730,7 @@ class PlowApp {
 
   startAutoRefresh() {
     if (this.refreshInterval) return;
+    this._sourceRefreshCounter = 0;
     this.refreshInterval = setInterval(async () => {
       if (this.mode !== "realtime") return;
       try {
@@ -1700,6 +1745,19 @@ class PlowApp {
       } catch (err) {
         console.error("Failed to refresh vehicles:", err);
       }
+
+      // Re-fetch sources every ~60s (10 ticks * 6s) to update staleness info
+      this._sourceRefreshCounter = (this._sourceRefreshCounter || 0) + 1;
+      if (this._sourceRefreshCounter >= 10) {
+        this._sourceRefreshCounter = 0;
+        try {
+          const resp = await fetch("/sources");
+          if (resp.ok) {
+            this.sources = await resp.json();
+          }
+        } catch (_) { /* ignore */ }
+      }
+      this.updateSourceStaleness();
     }, 6000);
   }
 

src/where_the_plow/static/style.css

@@ -512,6 +512,23 @@ body {
     display: none;
 }
 
+.source-stale-icon {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 15px;
+    height: 15px;
+    border-radius: 50%;
+    background: #f59e0b;
+    color: #000;
+    font-size: 10px;
+    font-weight: 700;
+    line-height: 1;
+    flex-shrink: 0;
+    margin-left: 4px;
+    cursor: help;
+}
+
 .legend-section-title {
     font-size: 0.65rem;
     text-transform: uppercase;