@autobusal/providers 1.27.0 → 1.28.1

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # Changelog
 
+## 1.28.1
+
+### Fixed
+
+- **The stale-chunk guard budgeted two reloads instead of one.** Measured: a
+  failure at `/operators` reloaded, the server answered with its canonical
+  `/operators/`, the same chunk failed again — and the raw path no longer
+  matched the one already spent, so it reloaded a second time. Bounded, but
+  twice what was intended, and on a genuinely broken deploy the user watched
+  the page flash twice before the error appeared. The budget key now strips a
+  trailing slash, so one journey gets one reload.
+
+  Only visible because the retest ran against a chunk that was *permanently*
+  missing rather than replaced — the ordinary stale-bundle case recovers on
+  the first reload and never reaches the second.
+
+## 1.28.0
+
+### Added
+
+- **`registerStaleChunkRecovery()`** — a tab left running a bundle that no
+  longer exists now reloads itself onto the page it was asked for, instead of
+  freezing.
+
+  Every route is `lazy(() => import(...))`, the build emits content-hashed
+  chunks, and it **empties the output directory** — so a new build deletes the
+  old chunk names outright (watched `index-DFPpSljG.js` disappear across one).
+  A tab still holding the previous `index.html` goes on asking for those names,
+  so the next navigation fetches a chunk that no longer resolves, the import
+  rejects, and the routed component never mounts — while the URL has *already*
+  changed. The address bar says one page and the screen shows the last one.
+  From the outside: "the page does not react at all, but the url seems to
+  change."
+
+  One listener on Vite's `vite:preloadError` covers all 141 lazy routes, which
+  is why this is a small module rather than a change to 141 call sites.
+
+  **Silent, not a prompt.** Every lazy chunk in both apps is a *route* —
+  checked, there is no lazily-loaded in-page component — so a chunk is only
+  ever fetched while navigating, which means the user has already left the page
+  they were on. Reloading to the destination costs them nothing the click was
+  not already costing them, and a "new version available?" dialog would be
+  asking permission to do the thing they just asked for.
+
+  **It cannot loop.** A missing chunk is usually a stale bundle but might be a
+  broken deploy, and reloading into a repeating failure would be far worse than
+  the bug. Each path gets at most one reload per tab; after that the error is
+  left to surface. `sessionStorage`, so the budget is per tab.
+
+  Verified by reproducing it: a tab pinned to an older bundle, its chunk
+  orphaned by a rebuild, then a client-side click — `vite:preloadError` fired,
+  the document was replaced, and the tab landed on `/operators` running the new
+  bundle.
+
 ## 1.27.0
 
 ### Added

package/Setup/staleChunk.ts

@@ -0,0 +1,114 @@
+/**
+ * Recover a tab left running a bundle that no longer exists.
+ *
+ * Ferjolt Ozuni - Date: 2026-08-06
+ *
+ * THE FAILURE. Every route is `lazy(() => import(...))`, the build emits
+ * content-hashed chunks, and it EMPTIES the output directory - so the moment
+ * a new build lands, `index-DFPpSljG.js` and its siblings stop existing.
+ * Confirmed by watching that exact file disappear across a build. Any tab
+ * still holding the previous index.html goes on asking for the old names, so
+ * the next navigation fetches a chunk that 404s, the dynamic import rejects,
+ * the routed component never mounts - and the URL has ALREADY changed. The
+ * address bar says one page, the screen shows the last one, and only a manual
+ * refresh escapes. That is exactly what it looked like from the outside:
+ * "the page does not react at all, but the url seems to change".
+ *
+ * WHY A SILENT RELOAD RATHER THAN A PROMPT. Every lazy chunk in both apps is
+ * a ROUTE - checked, there is not one lazily-loaded in-page component - so a
+ * chunk is only ever fetched while the user is navigating, which means they
+ * have already left the page they were on. Reloading to the destination
+ * therefore costs them nothing that the click was not already costing them.
+ * A "new version available, reload?" dialog would be asking permission to do
+ * the thing they just asked for.
+ *
+ * WHY IT CANNOT LOOP. A missing chunk is usually a stale bundle, but it might
+ * be a broken deploy or a bad cache - and reloading into a failure that
+ * repeats would spin forever, which is far worse than the bug being fixed.
+ * Each URL gets AT MOST ONE reload per tab: if the same route fails again the
+ * error is left to surface. sessionStorage rather than localStorage, so the
+ * budget is per tab and does not follow somebody around for weeks.
+ */
+
+const KEY = 'chunk-reload';
+
+/**
+ * The key a reload is budgeted against.
+ *
+ * Ferjolt Ozuni - Date: 2026-08-06
+ * TRAILING SLASH STRIPPED, and that is not tidiness. Measured: a failure at
+ * `/operators` reloaded, the server answered with its canonical `/operators/`,
+ * the same chunk failed again - and the raw path no longer matched the one
+ * already spent, so it reloaded a SECOND time. Bounded, but twice what was
+ * intended, and on a genuinely broken deploy the user watches the page flash
+ * twice before the error appears. One journey, one budget.
+ */
+const budgetKey = (): string => {
+  const path = window.location.pathname.replace(/\/+$/, '') || '/';
+
+  return path + window.location.search;
+};
+
+/**
+ * Which paths this tab has already spent its reload on.
+ */
+const attempted = (): string[] => {
+  try {
+    const raw = sessionStorage.getItem(KEY);
+
+    return raw ? JSON.parse(raw) : [];
+  } catch {
+    // Storage denied (private mode) or a hand-mangled value. Answering
+    // "nothing attempted" is safe here only because remember() below has to
+    // write before it approves anything, and that write fails for the same
+    // reason - so an unreadable store still ends in a refusal, not a loop.
+    return [];
+  }
+};
+
+const remember = (path: string): boolean => {
+  try {
+    const paths = attempted();
+
+    if (paths.includes(path)) {
+      return false;
+    }
+
+    sessionStorage.setItem(KEY, JSON.stringify([...paths, path]));
+
+    return true;
+  } catch {
+    // Storage unavailable means no way to remember an attempt, and therefore
+    // no way to stop a second one. Refuse rather than risk reloading forever.
+    return false;
+  }
+};
+
+/**
+ * Listen for Vite's dynamic-import failure.
+ *
+ * `vite:preloadError` is emitted by the preload helper the build wraps every
+ * `import()` in, so ONE listener covers all 141 lazy routes - which is the
+ * only reason this is a ten-line module rather than a change to 141 call
+ * sites. Calling preventDefault stops Vite rethrowing, since we are handling
+ * it by replacing the document.
+ */
+const registerStaleChunkRecovery = (): void => {
+  window.addEventListener('vite:preloadError', (event) => {
+    if (!remember(budgetKey())) {
+      // Spent already. Let it throw so the error boundary says something,
+      // rather than reloading into the same wall a second time.
+      return;
+    }
+
+    event.preventDefault();
+
+    // reload() and not assign(): the URL is already the destination - React
+    // Router changes it before rendering the route whose chunk just failed -
+    // so this fetches a fresh index.html and lands on the page that was asked
+    // for, with the current chunk names.
+    window.location.reload();
+  });
+};
+
+export default registerStaleChunkRecovery;

package/index.ts

@@ -4,6 +4,7 @@ import ErrorBoundary from './Errors/ErrorBoundary';
 import Message from './Errors/Message';
 import useMenuStore from './stores/menu';
 import { useUserStore } from './stores/user';
+import registerStaleChunkRecovery from './Setup/staleChunk';
 
 export {
   apiClient,
@@ -11,7 +12,8 @@ export {
   ErrorBoundary,
   Message,
   useMenuStore,
-  useUserStore
+  useUserStore,
+  registerStaleChunkRecovery
 };
 
 export default Providers;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autobusal/providers",
-  "version": "1.27.0",
+  "version": "1.28.1",
   "author": "Ferjolt Ozuni",
   "type": "module",
   "main": "index.ts"