feat(pwa): auto-apply service-worker updates when safe

Detect a waiting service worker and apply it automatically at the next
safe moment instead of only on the manual "update available" banner.
Auto-apply fires only while the page is hidden and a reload would lose
nothing: not navigating/rerouting, no in-flight mutation, no in-page
area download, no unsaved text, online, and outside a loop-guard
cooldown. The banner stays as a foreground fallback (after a 30s grace)
for when no safe moment arrives.

Gate logic lives in apps/web/src/lib/swAutoUpdate.ts (pure + unit
tested); SwUpdateNotice wires it via visibilitychange/online listeners.

Author: Medformatik

apps/web/src/components/pwa/SwUpdateNotice.tsx

@@ -3,28 +3,78 @@
 import Alert from "@mui/material/Alert";
 import Button from "@mui/material/Button";
 import Snackbar from "@mui/material/Snackbar";
+import { useNavigationStore } from "@openmapx/core";
 import type { Serwist } from "@serwist/window";
+import { useQueryClient } from "@tanstack/react-query";
 import { useTranslations } from "next-intl";
 import { useEffect, useRef, useState } from "react";
+import {
+  hasActiveAreaDownload,
+  hasUnsavedTextEntry,
+  isSafeToAutoReload,
+  markAutoReloaded,
+  msSinceLastAutoReload,
+} from "@/lib/swAutoUpdate";
+
+const BANNER_GRACE_MS = 30_000;
 
 export function SwUpdateNotice() {
   const t = useTranslations("pwa");
+  const queryClient = useQueryClient();
   const [updateReady, setUpdateReady] = useState(false);
+  const [visible, setVisible] = useState(true);
+  const [graceElapsed, setGraceElapsed] = useState(false);
   const swRef = useRef<Serwist | null>(null);
+  const updateReadyRef = useRef(false);
+
+  useEffect(() => {
+    setVisible(document.visibilityState === "visible");
+  }, []);
 
   useEffect(() => {
     if (process.env.NODE_ENV !== "production") return;
     if (typeof window === "undefined") return;
     if (!("serviceWorker" in navigator)) return;
 
     let cancelled = false;
+    let graceTimer: ReturnType<typeof setTimeout> | null = null;
+
+    const handleVisibilityChange = () => {
+      setVisible(document.visibilityState === "visible");
+      attemptAutoApply();
+    };
+
+    const handleOnline = () => {
+      attemptAutoApply();
+    };
+
+    const attemptAutoApply = () => {
+      if (!updateReadyRef.current) return;
+      if (document.visibilityState !== "hidden") return;
+      const safe = isSafeToAutoReload({
+        online: navigator.onLine,
+        navStatus: useNavigationStore.getState().status,
+        mutationCount: queryClient.isMutating(),
+        hasActiveDownload: hasActiveAreaDownload(),
+        hasUnsavedText: hasUnsavedTextEntry(),
+        msSinceLastAutoReload: msSinceLastAutoReload(),
+      });
+      if (!safe) return;
+      markAutoReloaded();
+      swRef.current?.messageSkipWaiting();
+    };
 
     void import("@serwist/window").then((mod) => {
       if (cancelled) return;
       const sw = new mod.Serwist("/sw.js", { scope: "/" });
 
       sw.addEventListener("waiting", () => {
+        updateReadyRef.current = true;
         setUpdateReady(true);
+        graceTimer = setTimeout(() => setGraceElapsed(true), BANNER_GRACE_MS);
+        document.addEventListener("visibilitychange", handleVisibilityChange);
+        window.addEventListener("online", handleOnline);
+        attemptAutoApply();
       });
 
       sw.addEventListener("controlling", (event) => {
@@ -45,8 +95,11 @@ export function SwUpdateNotice() {
 
     return () => {
       cancelled = true;
+      document.removeEventListener("visibilitychange", handleVisibilityChange);
+      window.removeEventListener("online", handleOnline);
+      if (graceTimer !== null) clearTimeout(graceTimer);
     };
-  }, []);
+  }, [queryClient]);
 
   const handleReload = () => {
     const sw = swRef.current;
@@ -59,7 +112,7 @@ export function SwUpdateNotice() {
 
   return (
     <Snackbar
-      open={updateReady}
+      open={updateReady && visible && graceElapsed}
       anchorOrigin={{ vertical: "bottom", horizontal: "center" }}
       sx={{ zIndex: 1500, mb: "var(--omx-safe-bottom)" }}
     >
@@ -71,7 +124,12 @@ export function SwUpdateNotice() {
             {t("reload")}
           </Button>
         }
-        sx={{ width: "100%" }}
+        sx={{
+          width: "100%",
+          bgcolor: "primary.main",
+          color: "primary.contrastText",
+          "& .MuiAlert-icon": { color: "inherit" },
+        }}
       >
         {t("updateAvailable")}
       </Alert>

apps/web/src/lib/swAutoUpdate.test.ts

@@ -0,0 +1,96 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  AUTO_RELOAD_COOLDOWN_MS,
+  type AutoUpdateSafetyInputs,
+  hasUnsavedTextEntry,
+  isSafeToAutoReload,
+} from "./swAutoUpdate";
+
+const ALL_CLEAR: AutoUpdateSafetyInputs = {
+  online: true,
+  navStatus: "idle",
+  mutationCount: 0,
+  hasActiveDownload: false,
+  hasUnsavedText: false,
+  msSinceLastAutoReload: Number.POSITIVE_INFINITY,
+};
+
+describe("isSafeToAutoReload", () => {
+  it("returns true when all conditions are clear", () => {
+    expect(isSafeToAutoReload(ALL_CLEAR)).toBe(true);
+  });
+
+  it("returns false when offline", () => {
+    expect(isSafeToAutoReload({ ...ALL_CLEAR, online: false })).toBe(false);
+  });
+
+  it("returns false when navigating", () => {
+    expect(isSafeToAutoReload({ ...ALL_CLEAR, navStatus: "navigating" })).toBe(false);
+  });
+
+  it("returns false when rerouting", () => {
+    expect(isSafeToAutoReload({ ...ALL_CLEAR, navStatus: "rerouting" })).toBe(false);
+  });
+
+  it("returns false when there is an in-flight mutation", () => {
+    expect(isSafeToAutoReload({ ...ALL_CLEAR, mutationCount: 1 })).toBe(false);
+  });
+
+  it("returns false when an area download is active", () => {
+    expect(isSafeToAutoReload({ ...ALL_CLEAR, hasActiveDownload: true })).toBe(false);
+  });
+
+  it("returns false when there is unsaved text", () => {
+    expect(isSafeToAutoReload({ ...ALL_CLEAR, hasUnsavedText: true })).toBe(false);
+  });
+
+  it("returns false when last auto-reload is within the cooldown window", () => {
+    expect(
+      isSafeToAutoReload({
+        ...ALL_CLEAR,
+        msSinceLastAutoReload: AUTO_RELOAD_COOLDOWN_MS - 1,
+      }),
+    ).toBe(false);
+  });
+
+  it("returns true when navStatus is idle (all else clear)", () => {
+    expect(isSafeToAutoReload({ ...ALL_CLEAR, navStatus: "idle" })).toBe(true);
+  });
+
+  it("returns true when navStatus is arrived (all else clear)", () => {
+    expect(isSafeToAutoReload({ ...ALL_CLEAR, navStatus: "arrived" })).toBe(true);
+  });
+});
+
+describe("hasUnsavedTextEntry", () => {
+  let input: HTMLInputElement;
+
+  beforeEach(() => {
+    input = document.createElement("input");
+    document.body.appendChild(input);
+  });
+
+  afterEach(() => {
+    input.blur();
+    document.body.removeChild(input);
+  });
+
+  it("returns false when an input is focused but empty", () => {
+    input.focus();
+    input.value = "";
+    expect(hasUnsavedTextEntry()).toBe(false);
+  });
+
+  it("returns true when a focused input has a non-empty value", () => {
+    input.focus();
+    input.value = "x";
+    expect(hasUnsavedTextEntry()).toBe(true);
+  });
+
+  it("returns false after the input is blurred and removed", () => {
+    input.focus();
+    input.value = "x";
+    input.blur();
+    expect(hasUnsavedTextEntry()).toBe(false);
+  });
+});

apps/web/src/lib/swAutoUpdate.ts

@@ -0,0 +1,59 @@
+import type { NavStatus } from "@openmapx/core";
+import { listAreas } from "@/lib/offlineAreas/storage";
+
+export const AUTO_RELOAD_COOLDOWN_MS = 2 * 60 * 1000;
+const LAST_AUTO_RELOAD_KEY = "omx:sw-last-auto-reload";
+
+export interface AutoUpdateSafetyInputs {
+  online: boolean;
+  navStatus: NavStatus;
+  mutationCount: number;
+  hasActiveDownload: boolean;
+  hasUnsavedText: boolean;
+  msSinceLastAutoReload: number; // Number.POSITIVE_INFINITY if never
+}
+
+export function isSafeToAutoReload(i: AutoUpdateSafetyInputs): boolean {
+  if (!i.online) return false;
+  if (i.navStatus === "navigating" || i.navStatus === "rerouting") return false;
+  if (i.mutationCount > 0) return false;
+  if (i.hasActiveDownload) return false;
+  if (i.hasUnsavedText) return false;
+  if (i.msSinceLastAutoReload < AUTO_RELOAD_COOLDOWN_MS) return false;
+  return true;
+}
+
+export function hasUnsavedTextEntry(): boolean {
+  const el = typeof document === "undefined" ? null : document.activeElement;
+  if (!el) return false;
+  const tag = el.tagName;
+  if (tag === "INPUT" || tag === "TEXTAREA") {
+    return ((el as HTMLInputElement | HTMLTextAreaElement).value ?? "").length > 0;
+  }
+  if ((el as HTMLElement).isContentEditable) {
+    return ((el as HTMLElement).textContent ?? "").length > 0;
+  }
+  return false;
+}
+
+export function hasActiveAreaDownload(): boolean {
+  try {
+    return listAreas().some((a) => a.status === "downloading");
+  } catch {
+    return false;
+  }
+}
+
+export function msSinceLastAutoReload(): number {
+  if (typeof sessionStorage === "undefined") return Number.POSITIVE_INFINITY;
+  const raw = sessionStorage.getItem(LAST_AUTO_RELOAD_KEY);
+  if (!raw) return Number.POSITIVE_INFINITY;
+  const then = Number.parseInt(raw, 10);
+  if (Number.isNaN(then)) return Number.POSITIVE_INFINITY;
+  return Date.now() - then;
+}
+
+export function markAutoReloaded(): void {
+  if (typeof sessionStorage === "undefined") return;
+  sessionStorage.setItem(LAST_AUTO_RELOAD_KEY, String(Date.now()));
+}