swarm-ui: make it installable as a PWA

Closes #4282. mara: "scope looks good" — approving the plan posted
there (manifest + icons + minimal shell-only service worker + iOS meta
tags) and both explicit questions (network-first-with-offline-fallback,
never cache /api/*).

docs/web-ui/design-guide.md's "Layout & viewport" section already
asserted swarm-ui is installable as a PWA — this is what actually backs
it.

- manifest.webmanifest: name/icons/start_url/standalone display, theme
  #cba6f7 / background #1e1e2e matching the mocha --purple/--bg values.
- sw.js: plain JS, not TypeScript — the DOM lib swarm-ui's own tsconfig
  uses and the WebWorker lib a service worker's globals need are
  mutually exclusive in one tsc program, not worth a second tsconfig for
  a self-contained ~100-line file. Scoped to the app shell only, never
  touches /api/* at all, network-first with offline-fallback-to-cache
  (not cache-first) since main.js/main.css are unhashed filenames and a
  cache-first SW would risk wedging an operator on stale JS after a
  deploy.
- index.html: manifest link, theme-color meta, iOS
  apple-mobile-web-app-* tags (Safari ignores the manifest spec).
- main.tsx: feature-detected SW registration.
- branding/hyperhive-maskable.svg: hyperhive.svg's own artwork already
  fills nearly its whole canvas, so a maskable icon needs a padded
  variant or an OS mask crops the outer ring/corner brackets — embeds
  the original via a scaled <image> ref rather than duplicating markup.
- nix/packages/swarm-ui.nix: rasterizes icon-192/512/512-maskable.png
  from the branding SVGs at build time via librsvg, rather than
  checking in static PNGs.

Verified for real: typecheck+build green, and a real headless-chromium
tab driven over CDP confirms the service worker registers and becomes
the active controller, and a simulated-offline reload still serves the
full cached shell rather than a browser error page. nix build .#swarm-ui
also verified green, including the rasterized icon output.

frontend/packages/swarm-ui/src/index.html

@@ -5,6 +5,19 @@
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>hyperhive swarm</title>
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <!-- PWA installability — design-guide.md's "Layout & viewport"
+         section already asserted swarm-ui is installable; this is what
+         actually backs it. `manifest.webmanifest` + icons are
+         nix-packaged (nix/packages/swarm-ui.nix), same as favicon.svg
+         above — not part of the plain npm build output. -->
+    <link rel="manifest" href="/manifest.webmanifest" />
+    <meta name="theme-color" content="#cba6f7" />
+    <!-- Safari ignores the manifest spec entirely — these are its own
+         "Add to Home Screen" affordances, same icon/name the manifest
+         already declares for every other browser. -->
+    <meta name="apple-mobile-web-app-capable" content="yes" />
+    <meta name="apple-mobile-web-app-title" content="swarm" />
+    <link rel="apple-touch-icon" href="/icon-192.png" />
     <link rel="stylesheet" href="/static/colors.css" />
     <link rel="stylesheet" href="/static/theme.css" />
     <link rel="stylesheet" href="/static/swarm-ui.css" />

frontend/packages/swarm-ui/src/main.tsx

@@ -5,3 +5,17 @@ const root = document.getElementById("root");
 if (root) {
   render(<App />, root);
 }
+
+// PWA installability — see sw.js's own top comment for
+// what it does and does not cache. Feature-detected: older browsers
+// without service-worker support just don't get the install affordance,
+// nothing here depends on it existing.
+if ("serviceWorker" in navigator) {
+  window.addEventListener("load", () => {
+    navigator.serviceWorker.register("/sw.js").catch((err: unknown) => {
+      // Never surfaces to the operator — a failed SW registration means
+      // "not installable this session," not "the app is broken."
+      console.error("swarm-ui: service worker registration failed", err);
+    });
+  });
+}

frontend/packages/swarm-ui/src/manifest.webmanifest

@@ -0,0 +1,14 @@
+{
+  "name": "hyperhive swarm",
+  "short_name": "swarm",
+  "description": "Swarm-level operator UI — agent roster, hives, jobs, issues across the swarm.",
+  "start_url": "/",
+  "display": "standalone",
+  "background_color": "#1e1e2e",
+  "theme_color": "#cba6f7",
+  "icons": [
+    { "src": "/icon-192.png", "sizes": "192x192", "type": "image/png" },
+    { "src": "/icon-512.png", "sizes": "512x512", "type": "image/png" },
+    { "src": "/icon-512-maskable.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" }
+  ]
+}

frontend/packages/swarm-ui/src/sw.js

@@ -0,0 +1,109 @@
+// Minimal service worker — satisfies PWA installability so swarm-ui can
+// actually be "Add to Home Screen"d (design-guide.md's "Layout &
+// viewport" section already asserted this as fact before this service
+// worker existed to make it true). NOT a data cache: scoped to the app
+// shell only (the SPA's own HTML/JS/CSS/manifest), and explicitly never
+// touches `/api/*` — an ops dashboard silently showing stale status from
+// a cached fetch would be worse than showing nothing (mara: "scope looks
+// good" — approving that as a hard rule, not a short-TTL middle ground).
+//
+// Network-first for the shell, not cache-first: `main.js`/`main.css` are
+// unhashed filenames, so a cache-first strategy would risk wedging an
+// operator on yesterday's JS after a deploy until they manually cleared
+// it (a deploy changes the nix store path serving these but not the URL
+// the browser cached against — a separate, already-filed fix). This SW
+// only ever serves its cache on a FAILED fetch (offline/flaky network),
+// never in preference to a successful network response.
+//
+// Plain JS, not TypeScript, deliberately — the DOM lib swarm-ui's own
+// tsconfig uses and the WebWorker lib a service worker's globals
+// (`self`, `ExtendableEvent`, `FetchEvent`, `caches`, ...) need are
+// mutually exclusive in one tsc program, and this file is small/
+// self-contained enough that a second tsconfig just to typecheck it
+// isn't worth the config surface. Same treatment `build.mjs` already
+// gets in this package.
+//
+// CACHE_VERSION is bumped by hand for now — once the filenames above are
+// content-hashed, the cache name can derive from the build itself and
+// this manual step goes away.
+const CACHE_VERSION = "v1";
+const CACHE_NAME = `swarm-ui-shell-${CACHE_VERSION}`;
+
+// Every navigation (any client-side route wouter handles — /agents,
+// /hives, ...) falls back to this single cached document when offline,
+// same as nginx's own `try_files $uri /index.html` does online: the SPA
+// only ever has one real HTML document regardless of path.
+const SHELL_DOCUMENT = "/";
+const SHELL_ASSETS = [
+  SHELL_DOCUMENT,
+  "/static/main.js",
+  "/static/main.css",
+  "/static/colors.css",
+  "/static/theme.css",
+  "/static/swarm-ui.css",
+  "/manifest.webmanifest",
+];
+
+self.addEventListener("install", (event) => {
+  event.waitUntil(
+    caches.open(CACHE_NAME).then((cache) => cache.addAll(SHELL_ASSETS)),
+  );
+  // Take over from any previous SW as soon as this one's installed — an
+  // operator installing the PWA for the first time (or after a SW
+  // update) shouldn't need a second reload before it's in control.
+  self.skipWaiting();
+});
+
+self.addEventListener("activate", (event) => {
+  event.waitUntil(
+    caches
+      .keys()
+      .then((names) =>
+        Promise.all(
+          names
+            .filter((name) => name !== CACHE_NAME)
+            .map((name) => caches.delete(name)),
+        ),
+      )
+      .then(() => self.clients.claim()),
+  );
+});
+
+self.addEventListener("fetch", (event) => {
+  const url = new URL(event.request.url);
+  // Same-origin only, and never `/api/*` — that's swarm-controller's
+  // live data, not the static shell this SW is scoped to. Letting the
+  // event fall through (no `respondWith`) means the browser handles it
+  // exactly as if this SW didn't exist.
+  if (url.origin !== self.location.origin || url.pathname.startsWith("/api/")) {
+    return;
+  }
+
+  // Any navigation (full-page load or wouter's client-side route change
+  // reaching the network) — network-first, falling back to the cached
+  // shell document on failure regardless of which path was requested,
+  // since every route renders the same SPA shell.
+  if (event.request.mode === "navigate") {
+    event.respondWith(
+      fetch(event.request).catch(() => caches.match(SHELL_DOCUMENT)),
+    );
+    return;
+  }
+
+  // A specific shell asset — network-first, cache the fresh response for
+  // next time, fall back to whatever's cached on failure. Anything not
+  // in this list (a future asset this SW doesn't know about yet) passes
+  // straight through untouched rather than silently going uncached.
+  if (!SHELL_ASSETS.includes(url.pathname)) {
+    return;
+  }
+  event.respondWith(
+    fetch(event.request)
+      .then((response) => {
+        const copy = response.clone();
+        caches.open(CACHE_NAME).then((cache) => cache.put(event.request, copy));
+        return response;
+      })
+      .catch(() => caches.match(event.request)),
+  );
+});