fix(pwa): recover from a dead chunk and a broken precache after an update (#2524)

After an update, a tab or a device whose service worker still serves the
previous build asks for chunks the update removed. The server answered those
requests with index.html and a 200, so the import failed with a MIME error,
and everything caching in between was free to keep the HTML as the chunk. A
precache install that met a missing file stored it, and Workbox reuses hashed
entries by URL, so the device showed "A new version is available" on every
load, whatever the reload or the cleared browser cache, and carried the broken
entry into every later release that keeps the file's name.

The SPA fallback now answers a GET for a build file that is not on disk with
a plain 404 (no-store) instead of index.html. A precache install refuses it,
so the worker whose cache is complete stays in charge until the new build is.
index.html is sent relative to the public dir, which also stops an install
living under a dot directory from answering every deep link with a 404.

On the client, the reload after a dead chunk (the automatic one and the
button on the update screen) no longer goes straight back to the worker that
served the broken shell. When that same worker is still in charge and the
server answers, its precache and registration are dropped first, so the
reload reaches the build the server runs now. Offline, and in offline mode,
the shell is kept. Every recovery reload, and the reload of the version
handover, asks for the page under a one-off query parameter, so a proxy or
CDN that keeps index.html against its headers cannot hand back the stale
shell either.

A chunk the entry imports statically fails before any of that code runs.
shell-guard.js, a small classic script loaded ahead of the entry, watches for
exactly that failure and runs the same recovery, once per session.

A stylesheet, font or icon that holds a page raises no error at all, so once
the app has started and the browser is idle, it looks through the precache
for entries that hold a page under a build file's name, fetches each from
the server past every cache and puts it back in place. A repaired stylesheet
is loaded again, and so are the app's stylesheets when a font was repaired,
since the browser does not try a face that failed again in the same
document. Only the headers are read, a precache found sound is not looked at
again until its entries change, nothing is fetched while nothing is broken,
and nothing happens offline, in offline mode or without storage. An answer
that is not the file (an auth wall, its login page, a server error) leaves
the entry for the next launch.

A page the recovery loaded from the network already runs the version the
server reports, so the version handover now records it instead of reloading
it a second time once the new worker takes over. A page loaded past an older
worker that is still in charge, as a hard reload does, still asks for the new
worker and records the version only once that has taken over, so the next
tab or launch cannot get the old shell without a handover.

Dropping the worker ends a Web Push subscription with it, so on such a device
the settings card shows push as off until it is switched on again. A missing
sw-push.js now fails the worker install with a 404 rather than index.html; the
comments that described the old answer say so.

server/src/nest/platform/platform.routes.ts

@@ -20,6 +20,43 @@ import { StorageInvalidKeyError, StorageNotFoundError, type StorageCategory } fr
 
 export const PUBLIC_DIR = path.join(__dirname, '../../../public');
 
+// File types the client build emits. No page of the app ends in one of these.
+const BUILD_FILE_RE = /\.(?:m?js|css|map|wasm|webmanifest|json|png|jpe?g|gif|webp|avif|svg|ico|woff2?|ttf|otf)$/i;
+
+/**
+ * Whether a request asks for a file of the built client rather than a page of it.
+ *
+ * Such a request that the static handler could not answer is a file that does not
+ * exist, and it must end in a 404. It used to get index.html like a page (#2524).
+ * A tab still running the previous build asks for a chunk the update removed and
+ * gets HTML with a 200, which the module loader rejects. Worse, a 200 is a success
+ * to everything that caches: a service worker's precache stores the HTML under the
+ * chunk's name and keeps reusing it in every later version that keeps the name,
+ * and a reverse proxy that caches static files by extension hands it out as the
+ * chunk. A 404 is refused by the precache and never stands in for the file.
+ */
+export function isBuildFilePath(pathname: string): boolean {
+  return pathname.startsWith('/assets/') || BUILD_FILE_RE.test(pathname);
+}
+
+/**
+ * The production answer to a GET that nothing else matched: index.html for a page
+ * of the app, a plain 404 in the TREK envelope for a build file that is not there.
+ * Shared by both fallback forms (applyPlatformSpa and SpaFallbackFilter).
+ */
+export function answerUnmatchedGet(req: Request, res: Response, message = 'Not Found'): void {
+  if (isBuildFilePath(req.path)) {
+    res.setHeader('Cache-Control', 'no-store');
+    res.status(404).json({ error: message });
+    return;
+  }
+  res.setHeader('Cache-Control', 'no-cache, no-store, must-revalidate');
+  // Relative to root, so that send() checks only 'index.html' for dot segments. Given
+  // the absolute path it refused an install living under a dot directory (a
+  // ~/.local checkout, say) and every deep link came back as a 404.
+  res.sendFile('index.html', { root: PUBLIC_DIR });
+}
+
 /**
  * express.static replacement for the four public /uploads mounts (storage
  * slice 3). Parity contract (spec §Serving): identical ETag / Last-Modified /
@@ -172,17 +209,14 @@ export function applyPlatformUploads(app: express.Application, storage: StorageS
  * NOT use this (its router terminates unmatched requests with a 404 before any
  * post-init route runs, and Express 5's path-to-regexp rejects a bare '*'); it serves
  * the SPA via the SpaFallbackFilter instead. Both produce the identical result:
- * unmatched GET → index.html in production.
+ * unmatched GET → index.html in production, or a 404 for a missing build file.
  */
 export function applyPlatformSpa(app: express.Application): void {
   applyPlatformStatic(app);
   // Case-sensitive on purpose (legacy parity).
   if (readEnv().app.nodeEnv !== 'production') return;
   // /.*/ rather than '*' so the helper is Express-4 and Express-5 safe.
-  app.get(/.*/, (_req: Request, res: Response) => {
-    res.setHeader('Cache-Control', 'no-cache, no-store, must-revalidate');
-    res.sendFile(path.join(PUBLIC_DIR, 'index.html'));
-  });
+  app.get(/.*/, (req: Request, res: Response) => answerUnmatchedGet(req, res));
 }
 
 /**

server/src/nest/platform/spa-fallback.filter.ts

@@ -1,8 +1,7 @@
 import { ArgumentsHost, Catch, ExceptionFilter, NotFoundException } from '@nestjs/common';
 import type { Request, Response } from 'express';
-import path from 'node:path';
 import { readEnv } from '../../app-config';
-import { PUBLIC_DIR } from './platform.routes';
+import { answerUnmatchedGet } from './platform.routes';
 
 /**
  * Serves the built SPA (index.html) for any request the NestJS router did not
@@ -17,6 +16,9 @@ import { PUBLIC_DIR } from './platform.routes';
  * client) keeps the standard TREK `{ error }` 404 envelope. The `@Catch(NotFoundException)`
  * is more specific than the global TrekExceptionFilter, so Nest routes 404s here
  * while every other error still flows through TrekExceptionFilter.
+ *
+ * A GET for a build file that is not on disk (a chunk of the previous release,
+ * say) is not a page and gets the 404 envelope too, never index.html (#2524).
  */
 @Catch(NotFoundException)
 export class SpaFallbackFilter implements ExceptionFilter {
@@ -27,8 +29,7 @@ export class SpaFallbackFilter implements ExceptionFilter {
 
     // Case-sensitive on purpose (legacy parity).
     if (readEnv().app.nodeEnv === 'production' && req.method === 'GET') {
-      res.setHeader('Cache-Control', 'no-cache, no-store, must-revalidate');
-      res.sendFile(path.join(PUBLIC_DIR, 'index.html'));
+      answerUnmatchedGet(req, res, exception.message || 'Not Found');
       return;
     }