feat(web): PWA support with offline area downloads

Lay the groundwork for using OpenMapX as an installed app on a phone.
Touches the manifest, service worker, an offline fallback page, and
adds a Settings surface for downloading map areas to use without a
network. None of this existed before; the existing serwist setup only
ran-time-cached the assets the user happened to fetch.

What's added

- Web app manifest (`app/manifest.ts`) with icons, shortcuts,
  share_target (`/share`), `protocol_handlers` for `geo:`/`web+maps:`,
  and `launch_handler: focus-existing`. Placeholder icon set in
  `public/icons/app/` (replace with branded artwork later).
- Viewport / themeColor / apple-web-app metadata in `layout.tsx` and
  `--omx-safe-*` CSS variables wired into every floating chrome
  element so the UI doesn't get eaten by notches in standalone mode.
- An /offline page served as the SW navigation fallback.
- A /settings/offline page where the user picks a bbox + zoom range
  on an embedded MapLibre instance and downloads the tiles, sprite,
  glyphs, TileJSON, and style JSON for both light and dark variants
  into a per-area Cache Storage entry. Covered styles are deduped
  across variants so theme switches don't double-download.
- A Storage dialog (from the hamburger menu) showing
  `navigator.storage.estimate()` and per-cache sizes, plus a "Clear
  cached tiles" action that preserves user-pinned offline areas.
- An "Install OpenMapX" entry that captures `beforeinstallprompt`
  (listener attached at module load, not in the Drawer subtree, so
  the event isn't lost). On iOS the entry opens an Add-to-Home-Screen
  hint dialog rendered as a sibling of the Drawer so the dialog
  survives the drawer's unmount.
- A `SwUpdateNotice` Snackbar wired to serwist's `waiting` event;
  reload only fires on `controlling` events whose `isUpdate` is true,
  so first installs don't surprise the user with a reload.
- A Web Share Target endpoint (`/share`) that extracts a query from
  `text` / `url` / `title` (treating blanks as missing) and 303's
  back to `/?q=…`. ShareIntentHandler consumes `?q`, `?geo`, and
  `?action`, then strips them from the URL. Re-share of the same URL
  is processed correctly — the dedup signature is reset whenever the
  params disappear.

Service worker

- `withOfflineFirst(strategy)` wrapper: any handler that opted in
  consults user-downloaded `offline-area-*` caches before falling
  through to the runtime strategy. Applied to MapTiler tiles,
  self-hosted vector tiles (.pbf), and a new `/styles/*` rule that
  also covers self-hosted style JSON / sprite / TileJSON for
  `NEXT_PUBLIC_MAP_STYLE_URL` deployments.
- Auth deny rule (`/api/auth/*` → `fetch(request)` passthrough) so
  the SW never caches credential-bearing responses.
- The app-shell cache (`app-shell-v1`) now precaches `/`, `/offline`,
  and `/manifest.webmanifest`. The navigation handler tries the
  exact URL in app-shell before falling back to /offline, so users
  with downloaded areas reach the map even after the runtime `pages`
  cache has expired.
- `setLocaleAndReload` refreshes the cached `/` and `/offline`
  responses in-place after a language switch (the cookie is set
  first, so the responses are localized) instead of wiping the cache.
- `skipWaiting: false`; the page posts a `SKIP_WAITING` message when
  the user accepts the update Snackbar.
- The downloader bails on `QuotaExceededError` and `TypeError`
  (network drop) instead of swallowing them, so a half-downloaded
  area no longer falsely reports "ready".

Build / deploy

- Custom esbuild path for `src/sw.ts` is kept and documented
  inline. `tsconfig.sw.json` adds the `webworker` lib for that file
  only; `pnpm check-types` runs both projects.
- Traefik gets two dynamic middlewares: `sw-no-cache@file` for
  `/sw.js` and `manifest-short-cache@file` for
  `/manifest.webmanifest`, applied via `additionalRoutes` on the
  `app-web` service so an upstream CDN can't pin a stale worker
  through a deploy.

Persistence

- TanStack Query cache is persisted to localStorage via
  `@tanstack/query-sync-storage-persister` with an allowlist of
  query roots (`place`, `weather`, `nearby`, `isochrone`,
  `sun-times`, `directions`, `route`, `geocode`). Admin / live data
  re-fetches from network as before.

Author: Medformatik

apps/web/package.json

@@ -9,7 +9,7 @@
     "build:sw": "esbuild src/sw.ts --bundle --outfile=public/sw.js --format=iife --platform=browser --define:process.env.NODE_ENV='\"production\"'",
     "build:copy-assets": "mkdir -p .next/standalone/apps/web/public .next/standalone/apps/web/.next/static && cp -R public/. .next/standalone/apps/web/public/ && cp -R .next/static/. .next/standalone/apps/web/.next/static/",
     "start": "node .next/standalone/apps/web/server.js",
-    "check-types": "tsc --noEmit",
+    "check-types": "tsc --noEmit && tsc --noEmit -p tsconfig.sw.json",
     "icons:sync": "node scripts/copy-preset-icons.mjs"
   },
   "dependencies": {
@@ -31,7 +31,9 @@
     "@openmapx/i18n": "workspace:*",
     "@serwist/next": "^9.5.10",
     "@serwist/window": "^9.5.10",
+    "@tanstack/query-sync-storage-persister": "^5.100.9",
     "@tanstack/react-query": "^5.100.7",
+    "@tanstack/react-query-persist-client": "^5.100.9",
     "@turf/area": "^7.3.5",
     "@turf/helpers": "^7.3.5",
     "@turf/length": "^7.3.5",

apps/web/public/icons/app/apple-touch-icon.png

@@ -1,10 +1,3 @@
-import { OfflineNotice } from "@/components/OfflineNotice";
-
 export default function MapLayout({ children }: { children: React.ReactNode }) {
-  return (
-    <div className="relative w-full h-full overflow-hidden">
-      {children}
-      <OfflineNotice />
-    </div>
-  );
+  return <div className="relative w-full h-full overflow-hidden">{children}</div>;
 }

apps/web/public/icons/app/favicon-32.png

@@ -14,6 +14,10 @@
   --omx-shadow-soft: rgba(0, 0, 0, 0.15);
   --omx-overlay-bg: #fff;
   --omx-overlay-text: #000;
+  --omx-safe-top: env(safe-area-inset-top, 0px);
+  --omx-safe-bottom: env(safe-area-inset-bottom, 0px);
+  --omx-safe-left: env(safe-area-inset-left, 0px);
+  --omx-safe-right: env(safe-area-inset-right, 0px);
 }
 
 .dark {

apps/web/public/icons/app/icon-192.png

@@ -1,13 +1,16 @@
 import InitColorSchemeScript from "@mui/material/InitColorSchemeScript";
 import { AppRouterCacheProvider } from "@mui/material-nextjs/v16-appRouter";
-import type { Metadata } from "next";
+import type { Metadata, Viewport } from "next";
 import { Plus_Jakarta_Sans } from "next/font/google";
 import { NextIntlClientProvider } from "next-intl";
 import { getLocale, getMessages } from "next-intl/server";
 import "mapillary-js/dist/mapillary.css";
 import "maplibre-theme/icons.default.css";
 import "maplibre-theme/classic.css";
 import "./globals.css";
+import { OfflineNotice } from "@/components/OfflineNotice";
+import { SwUpdateNotice } from "@/components/pwa/SwUpdateNotice";
+import { InstallPromptCapture } from "@/components/pwa/useInstallPrompt";
 import { EnvProvider } from "@/lib/EnvProvider";
 import { buildClientEnv } from "@/lib/env";
 import { Providers } from "./providers";
@@ -22,6 +25,34 @@ const plusJakartaSans = Plus_Jakarta_Sans({
 export const metadata: Metadata = {
   title: "OpenMapX",
   description: "Open-data maps — a Google Maps alternative",
+  applicationName: "OpenMapX",
+  appleWebApp: {
+    capable: true,
+    title: "OpenMapX",
+    statusBarStyle: "black-translucent",
+  },
+  formatDetection: {
+    telephone: false,
+  },
+  icons: {
+    icon: [
+      { url: "/icons/app/favicon-32.png", sizes: "32x32", type: "image/png" },
+      { url: "/icons/app/icon-192.png", sizes: "192x192", type: "image/png" },
+      { url: "/icons/app/icon-512.png", sizes: "512x512", type: "image/png" },
+    ],
+    apple: [{ url: "/icons/app/apple-touch-icon.png", sizes: "180x180", type: "image/png" }],
+  },
+};
+
+export const viewport: Viewport = {
+  width: "device-width",
+  initialScale: 1,
+  maximumScale: 5,
+  viewportFit: "cover",
+  themeColor: [
+    { media: "(prefers-color-scheme: light)", color: "#007b8b" },
+    { media: "(prefers-color-scheme: dark)", color: "#1c1c1c" },
+  ],
 };
 
 export default async function RootLayout({ children }: Readonly<{ children: React.ReactNode }>) {
@@ -39,7 +70,18 @@ export default async function RootLayout({ children }: Readonly<{ children: Reac
         <AppRouterCacheProvider>
           <NextIntlClientProvider locale={locale} messages={messages}>
             <EnvProvider config={clientEnv}>
-              <Providers>{children}</Providers>
+              <Providers>
+                {children}
+                {/* Mounted at the root so the SW registers, the offline
+                    notice surfaces on every route, and the install-prompt
+                    listener attaches before `beforeinstallprompt` fires (it
+                    would be missed if it lived inside the HamburgerMenu's
+                    temporary Drawer subtree). Each component is a client
+                    island with its own production / serviceWorker guards. */}
+                <OfflineNotice />
+                <SwUpdateNotice />
+                <InstallPromptCapture />
+              </Providers>
             </EnvProvider>
           </NextIntlClientProvider>
         </AppRouterCacheProvider>