@gusnips/react 0.4.6 → 0.5.0

package/README.md

@@ -67,31 +67,59 @@ those codes and they are never retried.
 
 An app with `lazy()` routes serves chunks by hashed filename. Deploy while someone has a tab
 open, and their next click asks for a file that no longer exists — a white screen on a button
-that worked a minute ago.
+that worked a minute ago. The same deploy breaks a second way that looks nothing like the first:
+the old bundle reads a field your API just renamed, and throws a plain `TypeError` with nothing
+in it about a deploy.
 
-Two halves. In your browser entry:
+**Fix the cause in your host config first.** This package cannot do it for you and it is worth
+more than everything below. A static host answers a missing `/assets/x.js` with your SPA
+fallback — `index.html`, at a 200, as `text/html` — and that is what the browser's "MIME type
+text/html" module-script refusal actually is. Hosts then match cache rules against the _request
+path_ rather than the outcome, so the `immutable, max-age=31536000` rule you wrote for hashed
+assets lands on that HTML body: one poisoned asset URL, at the edge and in every browser that
+touched it, for a year. Keep the fallback off `/assets/`, and answer a miss there with a real,
+uncacheable 404.
 
-```ts
-import { installPreloadErrorHandler } from "@gusnips/react";
+Then two detectors, for the two failures:
 
-installPreloadErrorHandler();
+```ts
+if (await isStaleBuild()) reloadOnce();
 ```
 
-And in your error boundary:
+`isStaleBuild` asks the server instead of reading the error — it compares the entry script this
+document loaded against the one the live page names. That is the only thing that catches the
+renamed-field crash, where the message carries no signal at all. It asks for the page, not for
+the asset: a CDN serves assets with a long `s-maxage`, so a bundle retired an hour ago still
+answers 200 from the edge and would report "current" during exactly the window when skew is most
+likely. Anything ambiguous — offline, a non-200, a timeout — answers `false`, because dressing a
+real bug up as an update hides it from you too.
 
 ```ts
-if (isChunkLoadError(error) && reloadOnceForChunkError()) return null;
+if (isChunkLoadError(error) && reloadOnce()) return null;
 ```
 
-`reloadOnceForChunkError` reloads at most once a minute, because reloading on a chunk error the
-reload does not fix is an infinite loop with a person inside it. Past that, a genuinely missing
-chunk degrades to your error screen, which can at least say something.
+`isChunkLoadError` matches the message, which is all you have for a failure that never reaches a
+boundary — an `unhandledrejection`, or a listener. Every browser's phrasing is in there.
+
+`reloadOnce` reloads at most once a minute, and there is **one** stamp for every reason to
+reload. A tab can reload because a chunk 404'd, because the server says it is behind, or from a
+guard inlined in `index.html` that runs before any module does. Three detectors, one predicament
+— give each its own key and a broken deploy gets three reloads a minute to take turns with. That
+inline guard cannot import anything, so the key it has to copy is exported as `RELOAD_GUARD_KEY`.
+
+And in your browser entry:
+
+```ts
+import { installPreloadErrorHandler } from "@gusnips/react";
+
+installPreloadErrorHandler();
+```
 
-The handler is the other half, and it is narrower than it looks: it swallows Vite's CSS _preload
-hint_ failure and nothing else. A hint that fails is harmless — the import runs straight after
-and usually works. Taking Vite's `preventDefault()` for every preload error instead resolves the
-dynamic import with `undefined`, `React.lazy` reads `.default` off nothing, and you get a crash
-screen plus a TypeError with only React frames in it, naming no chunk.
+It is narrower than it looks: it swallows Vite's CSS _preload hint_ failure and nothing else. A
+hint that fails is harmless — the import runs straight after and usually works. Taking Vite's
+`preventDefault()` for every preload error instead resolves the dynamic import with `undefined`,
+`React.lazy` reads `.default` off nothing, and you get a crash screen plus a TypeError with only
+React frames in it, naming no chunk.
 
 ## Guards that can tell "no" from "I don't know"
 

package/dist/deploy-recovery.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Surviving a deploy that lands while a tab is open.
+ *
+ * Every app on this stack is a Vite SPA with `lazy()` routes, deployed on push. A build replaces
+ * every hashed asset underneath whatever tabs are already open, and those tabs go on running
+ * yesterday's bundle. It surfaces two ways, and only one of them looks like a missing file:
+ *
+ *   1. The next navigation asks for a chunk whose hashed name is gone. React's lazy boundary
+ *      throws, and the person gets a white screen on a click that worked a minute ago.
+ *   2. The old bundle reads a field the API has since renamed, and throws. That one arrives as a
+ *      plain `TypeError` with nothing in it about a deploy — no file, no hash, no signal.
+ *
+ * So there are two detectors here and they are not interchangeable. {@link isChunkLoadError}
+ * matches the message, which is all you have for a failure that never reaches a boundary.
+ * {@link isStaleBuild} asks the server, which is evidence rather than a guess — and it is the
+ * only one that catches case 2 at all.
+ *
+ * **The deepest fix is not in this file, and it is worth more than everything in it.** A static
+ * host answers a missing `/assets/x.js` with the SPA fallback — `index.html`, at a 200, as
+ * `text/html` — which is what the browser's "MIME type text/html" module-script refusal actually
+ * is. Hosts then match cache rules against the REQUEST PATH rather than the outcome, so the
+ * `immutable, max-age=31536000` rule written for hashed assets gets applied to that HTML body:
+ * one poisoned asset URL, at the edge and in every browser that touched it, for a year. One
+ * adopter removed the cause instead of recovering from it — no blanket fallback over `/assets/`,
+ * and an edge function that refuses to answer an asset path with `text/html` — which turns a
+ * dead chunk into a real, uncacheable 404 and lets everything below be recovery rather than the
+ * plan. A package cannot ship that; it can refuse to let it go unwritten.
+ */
+/**
+ * One stamp for every reason to reload, which is the part that is easy to get wrong.
+ *
+ * A tab can decide to reload because a chunk 404'd, because the server says it is running an old
+ * build, or from a guard inlined in `index.html` that runs before any module does. That is three
+ * detectors for ONE predicament, and giving each its own key hands a broken deploy three reloads
+ * a minute to take turns with. The guard belongs to the tab, not to the reason.
+ *
+ * Exported because of the third caller: an inline `<script>` in `index.html` has to exist for the
+ * case where the bundle holding this file is itself the missing asset, and it cannot import
+ * anything. Copying the string is what it has to do; copying it from here is why the two agree.
+ */
+export declare const RELOAD_GUARD_KEY = "frontkit:reload-at";
+/**
+ * A lazy-chunk fetch failure — recoverable by reloading.
+ *
+ * Matched by message because no browser gives it a shared type. Every phrasing in the wild is
+ * here: Chrome/Edge "Failed to fetch dynamically imported module", Firefox "error loading
+ * dynamically imported module", Safari "Importing a module script failed", webpack's
+ * ChunkLoadError and "Loading chunk N failed", and the SPA-fallback "MIME type" refusal —
+ * which is the one that fires on a static host that has not fixed the cause above, because the
+ * missing `.js` is answered with `index.html`.
+ *
+ * A standalone predicate rather than a method on the boundary, so a global `unhandledrejection`
+ * handler can classify the same failure without importing a component.
+ */
+export declare function isChunkLoadError(error: unknown): boolean;
+/**
+ * Is the build this tab is running still the one being served?
+ *
+ * Asked of the server, so the answer is evidence rather than a guess. Everything ambiguous —
+ * offline, a non-200, a captive portal, a probe that times out — resolves to `false`: dressing a
+ * genuine bug up as an update hides it from the user and from us.
+ *
+ * It asks for the PAGE, not for the asset, and that is not the obvious choice. A missing asset
+ * looks like the direct question, but a CDN commonly serves assets with a long `s-maxage`, so a
+ * bundle a deploy retired an hour ago still answers 200 from the edge — it would report "current"
+ * during exactly the window when skew is most likely. The page is the one URL that cannot lie: it
+ * ships `max-age=0, must-revalidate` and never enters the edge cache.
+ */
+export declare function isStaleBuild(): Promise<boolean>;
+/**
+ * Hard-reload once to pick up the fresh deploy. Returns false when the guard suppressed it,
+ * which is the caller's cue that reloading did not fix it and the person needs the real error UI
+ * rather than watching the same attempt loop.
+ *
+ * The guard is the part that matters. Reloading on a failure is obvious; reloading on a failure
+ * that the reload does not fix is an infinite loop with the user inside it. At most one reload
+ * per minute, so a genuinely broken deploy degrades to the error screen — which can at least say
+ * something — instead of flickering forever.
+ *
+ * `sessionStorage` and not `localStorage`: the guard is about this tab's current predicament, and
+ * a stale stamp in another tab must not suppress a reload this one needs. Wrapped because storage
+ * throws outright when site data is blocked, and a privacy setting must not be the reason
+ * somebody cannot recover.
+ */
+export declare function reloadOnce(): boolean;
+/**
+ * Vite's *hint* failure, which is not the same thing and must not be treated as one.
+ *
+ * Vite injects a speculative `<link rel="stylesheet">` for a chunk's CSS before importing it.
+ * When that link fails, the import itself still runs right after and usually succeeds — so this
+ * one is worth swallowing, where a failure of the import is the real thing
+ * {@link isChunkLoadError} matches. Vite builds this message in exactly one place and only ever
+ * for a stylesheet link; script hints never reject.
+ */
+export declare function isPreloadHintFailure(error: unknown): boolean;
+/**
+ * Install the `vite:preloadError` listener. Call once, from the browser entry.
+ *
+ * Vite offers `preventDefault()` here so an app can own a failed asset itself — but taking that
+ * deal unconditionally resolves the dynamic import with `undefined` (Vite's helper ends in
+ * `baseModule().catch(handlePreloadError)`), and `React.lazy` then reads `.default` off nothing.
+ * The user gets the crash screen and the developer gets a TypeError with only React frames in
+ * it, naming no chunk. So it is taken ONLY for a failed preload hint, where the import still
+ * runs. A real module failure is left to throw, where the error boundary can recognise it.
+ */
+export declare function installPreloadErrorHandler(): void;
+//# sourceMappingURL=deploy-recovery.d.ts.map

package/dist/deploy-recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deploy-recovery.d.ts","sourceRoot":"","sources":["../src/deploy-recovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB,uBAAuB,CAAC;AAQrD;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CASxD;AAqBD;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,OAAO,CAAC,CAarD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,IAAI,OAAO,CAWpC;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE5D;AAED;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,IAAI,IAAI,CAKjD"}

package/dist/deploy-recovery.js

@@ -0,0 +1,174 @@
+/**
+ * Surviving a deploy that lands while a tab is open.
+ *
+ * Every app on this stack is a Vite SPA with `lazy()` routes, deployed on push. A build replaces
+ * every hashed asset underneath whatever tabs are already open, and those tabs go on running
+ * yesterday's bundle. It surfaces two ways, and only one of them looks like a missing file:
+ *
+ *   1. The next navigation asks for a chunk whose hashed name is gone. React's lazy boundary
+ *      throws, and the person gets a white screen on a click that worked a minute ago.
+ *   2. The old bundle reads a field the API has since renamed, and throws. That one arrives as a
+ *      plain `TypeError` with nothing in it about a deploy — no file, no hash, no signal.
+ *
+ * So there are two detectors here and they are not interchangeable. {@link isChunkLoadError}
+ * matches the message, which is all you have for a failure that never reaches a boundary.
+ * {@link isStaleBuild} asks the server, which is evidence rather than a guess — and it is the
+ * only one that catches case 2 at all.
+ *
+ * **The deepest fix is not in this file, and it is worth more than everything in it.** A static
+ * host answers a missing `/assets/x.js` with the SPA fallback — `index.html`, at a 200, as
+ * `text/html` — which is what the browser's "MIME type text/html" module-script refusal actually
+ * is. Hosts then match cache rules against the REQUEST PATH rather than the outcome, so the
+ * `immutable, max-age=31536000` rule written for hashed assets gets applied to that HTML body:
+ * one poisoned asset URL, at the edge and in every browser that touched it, for a year. One
+ * adopter removed the cause instead of recovering from it — no blanket fallback over `/assets/`,
+ * and an edge function that refuses to answer an asset path with `text/html` — which turns a
+ * dead chunk into a real, uncacheable 404 and lets everything below be recovery rather than the
+ * plan. A package cannot ship that; it can refuse to let it go unwritten.
+ */
+/**
+ * One stamp for every reason to reload, which is the part that is easy to get wrong.
+ *
+ * A tab can decide to reload because a chunk 404'd, because the server says it is running an old
+ * build, or from a guard inlined in `index.html` that runs before any module does. That is three
+ * detectors for ONE predicament, and giving each its own key hands a broken deploy three reloads
+ * a minute to take turns with. The guard belongs to the tab, not to the reason.
+ *
+ * Exported because of the third caller: an inline `<script>` in `index.html` has to exist for the
+ * case where the bundle holding this file is itself the missing asset, and it cannot import
+ * anything. Copying the string is what it has to do; copying it from here is why the two agree.
+ */
+export const RELOAD_GUARD_KEY = "frontkit:reload-at";
+const RELOAD_WINDOW_MS = 60_000;
+/** Bounded: a crashed app already shows nothing, and a network that hangs rather than fails must
+ *  land on the real error screen instead of an endless spinner. */
+const PROBE_TIMEOUT_MS = 4_000;
+/**
+ * A lazy-chunk fetch failure — recoverable by reloading.
+ *
+ * Matched by message because no browser gives it a shared type. Every phrasing in the wild is
+ * here: Chrome/Edge "Failed to fetch dynamically imported module", Firefox "error loading
+ * dynamically imported module", Safari "Importing a module script failed", webpack's
+ * ChunkLoadError and "Loading chunk N failed", and the SPA-fallback "MIME type" refusal —
+ * which is the one that fires on a static host that has not fixed the cause above, because the
+ * missing `.js` is answered with `index.html`.
+ *
+ * A standalone predicate rather than a method on the boundary, so a global `unhandledrejection`
+ * handler can classify the same failure without importing a component.
+ */
+export function isChunkLoadError(error) {
+    if (error instanceof Error && error.name === "ChunkLoadError")
+        return true;
+    const message = (error instanceof Error ? error.message : String(error) || "").toLowerCase();
+    return (message.includes("dynamically imported module") ||
+        message.includes("importing a module script failed") ||
+        message.includes("mime type") ||
+        message.includes("loading chunk"));
+}
+/**
+ * The entry script this document loaded, as a path.
+ *
+ * Read from the DOM rather than from `import.meta.url`, so it stays the ENTRY even if this module
+ * is later code-split into some other chunk — and so `vite dev`, which names `/src/main.tsx`,
+ * compares like with like and never reports a real crash as an update.
+ *
+ * A path, compared as a plain substring, rather than the raw attribute matched as `src="…"`. The
+ * two donors split on exactly this and the anchored form is the more precise one — which is also
+ * why it is the one that breaks if anything between the build and the browser rewrites the
+ * markup, where a minifier changing quote style is enough. A missed match resolves to "not
+ * stale", which shows the real error, and that is the direction this whole function is built to
+ * fail in.
+ */
+function runningEntry() {
+    const el = document.querySelector('script[type="module"][src]');
+    return el ? new URL(el.src, window.location.href).pathname : "";
+}
+/**
+ * Is the build this tab is running still the one being served?
+ *
+ * Asked of the server, so the answer is evidence rather than a guess. Everything ambiguous —
+ * offline, a non-200, a captive portal, a probe that times out — resolves to `false`: dressing a
+ * genuine bug up as an update hides it from the user and from us.
+ *
+ * It asks for the PAGE, not for the asset, and that is not the obvious choice. A missing asset
+ * looks like the direct question, but a CDN commonly serves assets with a long `s-maxage`, so a
+ * bundle a deploy retired an hour ago still answers 200 from the edge — it would report "current"
+ * during exactly the window when skew is most likely. The page is the one URL that cannot lie: it
+ * ships `max-age=0, must-revalidate` and never enters the edge cache.
+ */
+export async function isStaleBuild() {
+    const running = runningEntry();
+    if (!running)
+        return false;
+    try {
+        const res = await fetch("/", {
+            cache: "no-store",
+            signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
+        });
+        if (!res.ok)
+            return false;
+        return !(await res.text()).includes(running);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Hard-reload once to pick up the fresh deploy. Returns false when the guard suppressed it,
+ * which is the caller's cue that reloading did not fix it and the person needs the real error UI
+ * rather than watching the same attempt loop.
+ *
+ * The guard is the part that matters. Reloading on a failure is obvious; reloading on a failure
+ * that the reload does not fix is an infinite loop with the user inside it. At most one reload
+ * per minute, so a genuinely broken deploy degrades to the error screen — which can at least say
+ * something — instead of flickering forever.
+ *
+ * `sessionStorage` and not `localStorage`: the guard is about this tab's current predicament, and
+ * a stale stamp in another tab must not suppress a reload this one needs. Wrapped because storage
+ * throws outright when site data is blocked, and a privacy setting must not be the reason
+ * somebody cannot recover.
+ */
+export function reloadOnce() {
+    const now = Date.now();
+    try {
+        const last = Number(sessionStorage.getItem(RELOAD_GUARD_KEY) ?? 0);
+        if (now - last < RELOAD_WINDOW_MS)
+            return false;
+        sessionStorage.setItem(RELOAD_GUARD_KEY, String(now));
+    }
+    catch {
+        // Storage blocked — proceed with the reload rather than refusing to recover.
+    }
+    window.location.reload();
+    return true;
+}
+/**
+ * Vite's *hint* failure, which is not the same thing and must not be treated as one.
+ *
+ * Vite injects a speculative `<link rel="stylesheet">` for a chunk's CSS before importing it.
+ * When that link fails, the import itself still runs right after and usually succeeds — so this
+ * one is worth swallowing, where a failure of the import is the real thing
+ * {@link isChunkLoadError} matches. Vite builds this message in exactly one place and only ever
+ * for a stylesheet link; script hints never reject.
+ */
+export function isPreloadHintFailure(error) {
+    return error instanceof Error && error.message.startsWith("Unable to preload CSS for");
+}
+/**
+ * Install the `vite:preloadError` listener. Call once, from the browser entry.
+ *
+ * Vite offers `preventDefault()` here so an app can own a failed asset itself — but taking that
+ * deal unconditionally resolves the dynamic import with `undefined` (Vite's helper ends in
+ * `baseModule().catch(handlePreloadError)`), and `React.lazy` then reads `.default` off nothing.
+ * The user gets the crash screen and the developer gets a TypeError with only React frames in
+ * it, naming no chunk. So it is taken ONLY for a failed preload hint, where the import still
+ * runs. A real module failure is left to throw, where the error boundary can recognise it.
+ */
+export function installPreloadErrorHandler() {
+    window.addEventListener("vite:preloadError", (event) => {
+        const payload = event.payload;
+        if (isPreloadHintFailure(payload))
+            event.preventDefault();
+    });
+}
+//# sourceMappingURL=deploy-recovery.js.map

package/dist/deploy-recovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deploy-recovery.js","sourceRoot":"","sources":["../src/deploy-recovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,oBAAoB,CAAC;AAErD,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAEhC;mEACmE;AACnE,MAAM,gBAAgB,GAAG,KAAK,CAAC;AAE/B;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,IAAI,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,gBAAgB;QAAE,OAAO,IAAI,CAAC;IAC3E,MAAM,OAAO,GAAG,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IAC7F,OAAO,CACL,OAAO,CAAC,QAAQ,CAAC,6BAA6B,CAAC;QAC/C,OAAO,CAAC,QAAQ,CAAC,kCAAkC,CAAC;QACpD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;QAC7B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAClC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAS,YAAY;IACnB,MAAM,EAAE,GAAG,QAAQ,CAAC,aAAa,CAAoB,4BAA4B,CAAC,CAAC;IACnF,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;AAClE,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY;IAChC,MAAM,OAAO,GAAG,YAAY,EAAE,CAAC;IAC/B,IAAI,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAC3B,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YAC3B,KAAK,EAAE,UAAU;YACjB,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,gBAAgB,CAAC;SAC9C,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,OAAO,KAAK,CAAC;QAC1B,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC/C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,UAAU;IACxB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,CAAC,cAAc,CAAC,OAAO,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC;QACnE,IAAI,GAAG,GAAG,IAAI,GAAG,gBAAgB;YAAE,OAAO,KAAK,CAAC;QAChD,cAAc,CAAC,OAAO,CAAC,gBAAgB,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IACxD,CAAC;IAAC,MAAM,CAAC;QACP,6EAA6E;IAC/E,CAAC;IACD,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;IACzB,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAc;IACjD,OAAO,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,2BAA2B,CAAC,CAAC;AACzF,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,0BAA0B;IACxC,MAAM,CAAC,gBAAgB,CAAC,mBAAmB,EAAE,CAAC,KAAK,EAAE,EAAE;QACrD,MAAM,OAAO,GAAI,KAAuC,CAAC,OAAO,CAAC;QACjE,IAAI,oBAAoB,CAAC,OAAO,CAAC;YAAE,KAAK,CAAC,cAAc,EAAE,CAAC;IAC5D,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/index.d.ts

@@ -5,7 +5,7 @@ export { createSseParser, readSseStream, type SseFrame } from "./sse.ts";
 export { queryDefaults, retryDelayMs, shouldRetry, type QueryDefaultsOptions } from "./query.ts";
 export { ErrorBoundary, type ErrorBoundaryFallbackProps, type ErrorBoundaryProps, } from "./error-boundary.tsx";
 export { createErrorDescriber, humanizeWait, type DescribedError, type ErrorArm, type ErrorContext, type ErrorDescriberOptions, type Translate, } from "./describe-error.ts";
-export { installPreloadErrorHandler, isChunkLoadError, isPreloadHintFailure, reloadOnceForChunkError, } from "./chunk-reload.ts";
+export { installPreloadErrorHandler, isChunkLoadError, isPreloadHintFailure, isStaleBuild, RELOAD_GUARD_KEY, reloadOnce, } from "./deploy-recovery.ts";
 export { PRERENDERED_ROUTE_ATTR, SHELL_ROUTE } from "./prerender-contract.ts";
 export { applyBrandVars, i18nInitOptions, type I18nInitOptions } from "./i18n.ts";
 export type { EmptyStateProps, ErrorStateProps } from "./states.ts";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA6BA,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAE7B,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACxE,OAAO,EACL,eAAe,EACf,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,KAAK,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEjG,OAAO,EACL,aAAa,EACb,KAAK,0BAA0B,EAC/B,KAAK,kBAAkB,GACxB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,YAAY,EACZ,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,SAAS,GACf,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAK3B,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE9E,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AAElF,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA6BA,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAE7B,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACxE,OAAO,EACL,eAAe,EACf,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,KAAK,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEjG,OAAO,EACL,aAAa,EACb,KAAK,0BAA0B,EAC/B,KAAK,kBAAkB,GACxB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,YAAY,EACZ,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,SAAS,GACf,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,oBAAoB,EACpB,YAAY,EACZ,gBAAgB,EAChB,UAAU,GACX,MAAM,sBAAsB,CAAC;AAK9B,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE9E,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AAElF,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -33,7 +33,7 @@ export { createSseParser, readSseStream } from "./sse.js";
 export { queryDefaults, retryDelayMs, shouldRetry } from "./query.js";
 export { ErrorBoundary, } from "./error-boundary.js";
 export { createErrorDescriber, humanizeWait, } from "./describe-error.js";
-export { installPreloadErrorHandler, isChunkLoadError, isPreloadHintFailure, reloadOnceForChunkError, } from "./chunk-reload.js";
+export { installPreloadErrorHandler, isChunkLoadError, isPreloadHintFailure, isStaleBuild, RELOAD_GUARD_KEY, reloadOnce, } from "./deploy-recovery.js";
 // The two constants, but NOT `hydrateOrMount` — that one is at `@gusnips/react/hydrate`, because
 // it is the package's only `react-dom` import. These come from the contract module, which imports
 // nothing at all, so they are free to everyone: a build script, a browser entry, or a phone.

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,EAAE;AACF,2CAA2C;AAC3C,EAAE;AACF,+FAA+F;AAC/F,gGAAgG;AAChG,+FAA+F;AAC/F,iGAAiG;AACjG,0BAA0B;AAC1B,EAAE;AACF,oEAAoE;AACpE,6DAA6D;AAC7D,sEAAsE;AACtE,+DAA+D;AAC/D,EAAE;AACF,2FAA2F;AAC3F,iGAAiG;AACjG,+FAA+F;AAC/F,gGAAgG;AAChG,4EAA4E;AAC5E,EAAE;AACF,2FAA2F;AAC3F,iGAAiG;AACjG,qFAAqF;AACrF,6FAA6F;AAC7F,iGAAiG;AACjG,yFAAyF;AACzF,uBAAuB;AAEvB,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAE7B,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACxE,OAAO,EACL,eAAe,GAMhB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAiB,MAAM,UAAU,CAAC;AAEzE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAA6B,MAAM,YAAY,CAAC;AAEjG,OAAO,EACL,aAAa,GAGd,MAAM,qBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,YAAY,GAMb,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAE3B,iGAAiG;AACjG,kGAAkG;AAClG,6FAA6F;AAC7F,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE9E,OAAO,EAAE,cAAc,EAAE,eAAe,EAAwB,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,EAAE;AACF,2CAA2C;AAC3C,EAAE;AACF,+FAA+F;AAC/F,gGAAgG;AAChG,+FAA+F;AAC/F,iGAAiG;AACjG,0BAA0B;AAC1B,EAAE;AACF,oEAAoE;AACpE,6DAA6D;AAC7D,sEAAsE;AACtE,+DAA+D;AAC/D,EAAE;AACF,2FAA2F;AAC3F,iGAAiG;AACjG,+FAA+F;AAC/F,gGAAgG;AAChG,4EAA4E;AAC5E,EAAE;AACF,2FAA2F;AAC3F,iGAAiG;AACjG,qFAAqF;AACrF,6FAA6F;AAC7F,iGAAiG;AACjG,yFAAyF;AACzF,uBAAuB;AAEvB,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAE7B,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACxE,OAAO,EACL,eAAe,GAMhB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAiB,MAAM,UAAU,CAAC;AAEzE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAA6B,MAAM,YAAY,CAAC;AAEjG,OAAO,EACL,aAAa,GAGd,MAAM,qBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,YAAY,GAMb,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,oBAAoB,EACpB,YAAY,EACZ,gBAAgB,EAChB,UAAU,GACX,MAAM,sBAAsB,CAAC;AAE9B,iGAAiG;AACjG,kGAAkG;AAClG,6FAA6F;AAC7F,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE9E,OAAO,EAAE,cAAc,EAAE,eAAe,EAAwB,MAAM,WAAW,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gusnips/react",
-  "version": "0.4.6",
-  "description": "The headless runtime under a Vite + React SPA: typed fetch client with single-flight refresh, auth store, query defaults, route guards, error boundary, chunk-reload recovery, i18n bootstrap.",
+  "version": "0.5.0",
+  "description": "The headless runtime under a Vite + React SPA: typed fetch client with single-flight refresh, auth store, query defaults, route guards, error boundary, stale-tab recovery, i18n bootstrap.",
   "type": "module",
   "license": "MIT",
   "author": "Gustavo Salomé",

package/src/deploy-recovery.test.ts

@@ -0,0 +1,207 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  isChunkLoadError,
+  isPreloadHintFailure,
+  isStaleBuild,
+  RELOAD_GUARD_KEY,
+  reloadOnce,
+} from "./deploy-recovery.ts";
+
+const ORIGIN = "https://app.example.com";
+
+// No browser gives a failed dynamic import a shared type, so this is matched by message and
+// every phrasing has to be here. A miss is a white screen after a deploy — the exact failure
+// this module exists to catch — and it only reproduces on a real deploy, so the test is the
+// only place these strings get checked.
+describe("isChunkLoadError", () => {
+  it.each([
+    ["Chrome/Edge", "Failed to fetch dynamically imported module: https://x/assets/a.js"],
+    ["Firefox", "error loading dynamically imported module"],
+    ["Safari", "Importing a module script failed."],
+    ["webpack", "Loading chunk 42 failed."],
+    // The one that fires on a static host that still answers a missing asset with its SPA
+    // fallback: the browser refuses the HTML rather than reporting a 404.
+    [
+      "SPA fallback",
+      "Expected a JavaScript module script but the server responded with a MIME type of text/html",
+    ],
+  ])("matches %s", (_browser, message) => {
+    expect(isChunkLoadError(new Error(message))).toBe(true);
+  });
+
+  it("matches a named ChunkLoadError whatever its message", () => {
+    const error = new Error("nothing recognisable");
+    error.name = "ChunkLoadError";
+    expect(isChunkLoadError(error)).toBe(true);
+  });
+
+  it("does not match an ordinary render error", () => {
+    expect(isChunkLoadError(new TypeError("Cannot read properties of undefined"))).toBe(false);
+    expect(isChunkLoadError(null)).toBe(false);
+    // A thrown string reaches the `String(error)` branch, which is the one a non-Error throw
+    // takes — and the one that would blow up if it were written `error.message`.
+    expect(isChunkLoadError("something failed")).toBe(false);
+  });
+});
+
+// The distinction that matters: swallowing a real module failure resolves the import with
+// `undefined`, React.lazy reads `.default` off nothing, and the developer gets a TypeError with
+// only React frames in it — naming no chunk. Only the CSS hint is safe to swallow.
+describe("isPreloadHintFailure", () => {
+  it("matches Vite's CSS preload hint and nothing else", () => {
+    expect(isPreloadHintFailure(new Error("Unable to preload CSS for /assets/a.css"))).toBe(true);
+    expect(isPreloadHintFailure(new Error("Failed to fetch dynamically imported module"))).toBe(
+      false,
+    );
+  });
+});
+
+/**
+ * Two globals, stubbed rather than run under a DOM: `window`, `document`, `sessionStorage` and
+ * `fetch` are the only ones this module touches, and adding jsdom to a package whose whole point
+ * is a small dependency list would cost more than it explains.
+ */
+const reload = vi.fn();
+let store: Record<string, string> = {};
+/** Throws from both methods, the way a browser does when site data is blocked. */
+let blocked = false;
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  reload.mockClear();
+  store = {};
+  blocked = false;
+  vi.stubGlobal("window", { location: { reload, href: `${ORIGIN}/w/anyone` } });
+  vi.stubGlobal("sessionStorage", {
+    getItem: (key: string): string | null => {
+      if (blocked) throw new Error("site data blocked");
+      return store[key] ?? null;
+    },
+    setItem: (key: string, value: string): void => {
+      if (blocked) throw new Error("site data blocked");
+      store[key] = value;
+    },
+  });
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.useRealTimers();
+});
+
+/**
+ * The detector that reads evidence instead of a message. It is the only one that catches a crash
+ * carrying no signal — the old bundle meeting a renamed API field — so every ambiguous answer
+ * has to resolve to "not stale", or a real bug gets dressed up as an update and hidden.
+ */
+describe("isStaleBuild", () => {
+  // What a static host actually serves for `/`: Vite's built page names the entry with double
+  // quotes and a crossorigin attribute, and `vite dev` names the source module.
+  const BUILT = (hash: string) =>
+    `<!doctype html><html><head><script type="module" crossorigin src="/assets/index-${hash}.js"></script></head><body><div id="root"></div></body></html>`;
+  const DEV = `<!doctype html><html><head><script type="module" src="/src/main.tsx"></script></head><body></body></html>`;
+
+  /** Point this document at one entry script and the server at a page naming another. */
+  function serving(page: string, entry: string | null): void {
+    vi.stubGlobal("document", {
+      querySelector: () => (entry === null ? null : { src: `${ORIGIN}${entry}` }),
+    });
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue(new Response(page, { status: 200 })));
+  }
+
+  it("asks the page, never the cache — a cached copy would hide the deploy", async () => {
+    serving(BUILT("AAA"), "/assets/index-AAA.js");
+    await isStaleBuild();
+    expect(fetch).toHaveBeenCalledWith("/", expect.objectContaining({ cache: "no-store" }));
+  });
+
+  it("is stale when the live page has moved to a different bundle", async () => {
+    serving(BUILT("NEW222"), "/assets/index-OLD111.js");
+    await expect(isStaleBuild()).resolves.toBe(true);
+  });
+
+  it("is not stale while the live page still names this bundle", async () => {
+    serving(BUILT("SAME33"), "/assets/index-SAME33.js");
+    await expect(isStaleBuild()).resolves.toBe(false);
+  });
+
+  // The reason this compares a PATH as a substring rather than matching `src="…"` exactly. The
+  // anchored form is more precise and breaks the moment anything rewrites the markup between the
+  // build and the browser — and breaking here would report a healthy tab as stale, which is a
+  // reload the user did not need and cannot refuse.
+  it("survives a host that rewrites the markup on the way out", async () => {
+    serving(
+      `<!doctype html><html><head><script type=module src='/assets/index-AAA.js'></script></head></html>`,
+      "/assets/index-AAA.js",
+    );
+    await expect(isStaleBuild()).resolves.toBe(false);
+  });
+
+  it("is never stale under `vite dev`, where a crash is always a real one", async () => {
+    serving(DEV, "/src/main.tsx");
+    await expect(isStaleBuild()).resolves.toBe(false);
+  });
+
+  it("does not guess when the document has no entry script to compare", async () => {
+    serving(BUILT("AAA"), null);
+    await expect(isStaleBuild()).resolves.toBe(false);
+    expect(fetch).not.toHaveBeenCalled();
+  });
+
+  it("does not call a bad response from the host a deploy", async () => {
+    serving(BUILT("AAA"), "/assets/index-AAA.js");
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue(new Response("nope", { status: 503 })));
+    await expect(isStaleBuild()).resolves.toBe(false);
+  });
+
+  it.each([
+    ["being offline", new TypeError("Failed to fetch")],
+    ["a network that hangs until the probe gives up", new DOMException("Timeout", "TimeoutError")],
+  ])("does not call %s a deploy", async (_label, thrown) => {
+    serving(BUILT("AAA"), "/assets/index-AAA.js");
+    vi.stubGlobal("fetch", vi.fn().mockRejectedValue(thrown));
+    await expect(isStaleBuild()).resolves.toBe(false);
+  });
+});
+
+/**
+ * The guard, which is the whole reason this function exists rather than a bare
+ * `location.reload()` at the call site. Reloading on a failure the reload does not fix is an
+ * infinite loop with a person inside it, and it only reproduces on a real broken deploy — so
+ * this is the only place the rule gets checked.
+ */
+describe("reloadOnce", () => {
+  it("reloads on the first attempt and stamps the shared guard", () => {
+    expect(reloadOnce()).toBe(true);
+    expect(reload).toHaveBeenCalledTimes(1);
+    expect(store[RELOAD_GUARD_KEY]).toBe(String(Date.now()));
+  });
+
+  it("refuses a second reload inside the window, so a broken deploy cannot loop", () => {
+    expect(reloadOnce()).toBe(true);
+    expect(reloadOnce()).toBe(false);
+    expect(reload).toHaveBeenCalledTimes(1);
+  });
+
+  it("allows another one after the window, because the next deploy is a new problem", () => {
+    expect(reloadOnce()).toBe(true);
+    vi.setSystemTime(Date.now() + 61_000);
+    expect(reloadOnce()).toBe(true);
+    expect(reload).toHaveBeenCalledTimes(2);
+  });
+
+  it("still reloads when storage is blocked — a privacy setting is not a reason to strand", () => {
+    blocked = true;
+    expect(reloadOnce()).toBe(true);
+    expect(reload).toHaveBeenCalledTimes(1);
+  });
+
+  // The bug this key was renamed to prevent. An inline guard in index.html cannot import
+  // anything, so it copies the string — and the moment the two names drift, a broken deploy gets
+  // two reloads a minute instead of one, each path politely resetting the other's clock.
+  it("exports the one key an inline guard has to share", () => {
+    expect(RELOAD_GUARD_KEY).toBe("frontkit:reload-at");
+    reloadOnce();
+    expect(Object.keys(store)).toEqual([RELOAD_GUARD_KEY]);
+  });
+});

package/src/deploy-recovery.ts

@@ -0,0 +1,177 @@
+/**
+ * Surviving a deploy that lands while a tab is open.
+ *
+ * Every app on this stack is a Vite SPA with `lazy()` routes, deployed on push. A build replaces
+ * every hashed asset underneath whatever tabs are already open, and those tabs go on running
+ * yesterday's bundle. It surfaces two ways, and only one of them looks like a missing file:
+ *
+ *   1. The next navigation asks for a chunk whose hashed name is gone. React's lazy boundary
+ *      throws, and the person gets a white screen on a click that worked a minute ago.
+ *   2. The old bundle reads a field the API has since renamed, and throws. That one arrives as a
+ *      plain `TypeError` with nothing in it about a deploy — no file, no hash, no signal.
+ *
+ * So there are two detectors here and they are not interchangeable. {@link isChunkLoadError}
+ * matches the message, which is all you have for a failure that never reaches a boundary.
+ * {@link isStaleBuild} asks the server, which is evidence rather than a guess — and it is the
+ * only one that catches case 2 at all.
+ *
+ * **The deepest fix is not in this file, and it is worth more than everything in it.** A static
+ * host answers a missing `/assets/x.js` with the SPA fallback — `index.html`, at a 200, as
+ * `text/html` — which is what the browser's "MIME type text/html" module-script refusal actually
+ * is. Hosts then match cache rules against the REQUEST PATH rather than the outcome, so the
+ * `immutable, max-age=31536000` rule written for hashed assets gets applied to that HTML body:
+ * one poisoned asset URL, at the edge and in every browser that touched it, for a year. One
+ * adopter removed the cause instead of recovering from it — no blanket fallback over `/assets/`,
+ * and an edge function that refuses to answer an asset path with `text/html` — which turns a
+ * dead chunk into a real, uncacheable 404 and lets everything below be recovery rather than the
+ * plan. A package cannot ship that; it can refuse to let it go unwritten.
+ */
+
+/**
+ * One stamp for every reason to reload, which is the part that is easy to get wrong.
+ *
+ * A tab can decide to reload because a chunk 404'd, because the server says it is running an old
+ * build, or from a guard inlined in `index.html` that runs before any module does. That is three
+ * detectors for ONE predicament, and giving each its own key hands a broken deploy three reloads
+ * a minute to take turns with. The guard belongs to the tab, not to the reason.
+ *
+ * Exported because of the third caller: an inline `<script>` in `index.html` has to exist for the
+ * case where the bundle holding this file is itself the missing asset, and it cannot import
+ * anything. Copying the string is what it has to do; copying it from here is why the two agree.
+ */
+export const RELOAD_GUARD_KEY = "frontkit:reload-at";
+
+const RELOAD_WINDOW_MS = 60_000;
+
+/** Bounded: a crashed app already shows nothing, and a network that hangs rather than fails must
+ *  land on the real error screen instead of an endless spinner. */
+const PROBE_TIMEOUT_MS = 4_000;
+
+/**
+ * A lazy-chunk fetch failure — recoverable by reloading.
+ *
+ * Matched by message because no browser gives it a shared type. Every phrasing in the wild is
+ * here: Chrome/Edge "Failed to fetch dynamically imported module", Firefox "error loading
+ * dynamically imported module", Safari "Importing a module script failed", webpack's
+ * ChunkLoadError and "Loading chunk N failed", and the SPA-fallback "MIME type" refusal —
+ * which is the one that fires on a static host that has not fixed the cause above, because the
+ * missing `.js` is answered with `index.html`.
+ *
+ * A standalone predicate rather than a method on the boundary, so a global `unhandledrejection`
+ * handler can classify the same failure without importing a component.
+ */
+export function isChunkLoadError(error: unknown): boolean {
+  if (error instanceof Error && error.name === "ChunkLoadError") return true;
+  const message = (error instanceof Error ? error.message : String(error) || "").toLowerCase();
+  return (
+    message.includes("dynamically imported module") ||
+    message.includes("importing a module script failed") ||
+    message.includes("mime type") ||
+    message.includes("loading chunk")
+  );
+}
+
+/**
+ * The entry script this document loaded, as a path.
+ *
+ * Read from the DOM rather than from `import.meta.url`, so it stays the ENTRY even if this module
+ * is later code-split into some other chunk — and so `vite dev`, which names `/src/main.tsx`,
+ * compares like with like and never reports a real crash as an update.
+ *
+ * A path, compared as a plain substring, rather than the raw attribute matched as `src="…"`. The
+ * two donors split on exactly this and the anchored form is the more precise one — which is also
+ * why it is the one that breaks if anything between the build and the browser rewrites the
+ * markup, where a minifier changing quote style is enough. A missed match resolves to "not
+ * stale", which shows the real error, and that is the direction this whole function is built to
+ * fail in.
+ */
+function runningEntry(): string {
+  const el = document.querySelector<HTMLScriptElement>('script[type="module"][src]');
+  return el ? new URL(el.src, window.location.href).pathname : "";
+}
+
+/**
+ * Is the build this tab is running still the one being served?
+ *
+ * Asked of the server, so the answer is evidence rather than a guess. Everything ambiguous —
+ * offline, a non-200, a captive portal, a probe that times out — resolves to `false`: dressing a
+ * genuine bug up as an update hides it from the user and from us.
+ *
+ * It asks for the PAGE, not for the asset, and that is not the obvious choice. A missing asset
+ * looks like the direct question, but a CDN commonly serves assets with a long `s-maxage`, so a
+ * bundle a deploy retired an hour ago still answers 200 from the edge — it would report "current"
+ * during exactly the window when skew is most likely. The page is the one URL that cannot lie: it
+ * ships `max-age=0, must-revalidate` and never enters the edge cache.
+ */
+export async function isStaleBuild(): Promise<boolean> {
+  const running = runningEntry();
+  if (!running) return false;
+  try {
+    const res = await fetch("/", {
+      cache: "no-store",
+      signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
+    });
+    if (!res.ok) return false;
+    return !(await res.text()).includes(running);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Hard-reload once to pick up the fresh deploy. Returns false when the guard suppressed it,
+ * which is the caller's cue that reloading did not fix it and the person needs the real error UI
+ * rather than watching the same attempt loop.
+ *
+ * The guard is the part that matters. Reloading on a failure is obvious; reloading on a failure
+ * that the reload does not fix is an infinite loop with the user inside it. At most one reload
+ * per minute, so a genuinely broken deploy degrades to the error screen — which can at least say
+ * something — instead of flickering forever.
+ *
+ * `sessionStorage` and not `localStorage`: the guard is about this tab's current predicament, and
+ * a stale stamp in another tab must not suppress a reload this one needs. Wrapped because storage
+ * throws outright when site data is blocked, and a privacy setting must not be the reason
+ * somebody cannot recover.
+ */
+export function reloadOnce(): boolean {
+  const now = Date.now();
+  try {
+    const last = Number(sessionStorage.getItem(RELOAD_GUARD_KEY) ?? 0);
+    if (now - last < RELOAD_WINDOW_MS) return false;
+    sessionStorage.setItem(RELOAD_GUARD_KEY, String(now));
+  } catch {
+    // Storage blocked — proceed with the reload rather than refusing to recover.
+  }
+  window.location.reload();
+  return true;
+}
+
+/**
+ * Vite's *hint* failure, which is not the same thing and must not be treated as one.
+ *
+ * Vite injects a speculative `<link rel="stylesheet">` for a chunk's CSS before importing it.
+ * When that link fails, the import itself still runs right after and usually succeeds — so this
+ * one is worth swallowing, where a failure of the import is the real thing
+ * {@link isChunkLoadError} matches. Vite builds this message in exactly one place and only ever
+ * for a stylesheet link; script hints never reject.
+ */
+export function isPreloadHintFailure(error: unknown): boolean {
+  return error instanceof Error && error.message.startsWith("Unable to preload CSS for");
+}
+
+/**
+ * Install the `vite:preloadError` listener. Call once, from the browser entry.
+ *
+ * Vite offers `preventDefault()` here so an app can own a failed asset itself — but taking that
+ * deal unconditionally resolves the dynamic import with `undefined` (Vite's helper ends in
+ * `baseModule().catch(handlePreloadError)`), and `React.lazy` then reads `.default` off nothing.
+ * The user gets the crash screen and the developer gets a TypeError with only React frames in
+ * it, naming no chunk. So it is taken ONLY for a failed preload hint, where the import still
+ * runs. A real module failure is left to throw, where the error boundary can recognise it.
+ */
+export function installPreloadErrorHandler(): void {
+  window.addEventListener("vite:preloadError", (event) => {
+    const payload = (event as Event & { payload?: unknown }).payload;
+    if (isPreloadHintFailure(payload)) event.preventDefault();
+  });
+}

package/src/index.ts

@@ -61,8 +61,10 @@ export {
   installPreloadErrorHandler,
   isChunkLoadError,
   isPreloadHintFailure,
-  reloadOnceForChunkError,
-} from "./chunk-reload.ts";
+  isStaleBuild,
+  RELOAD_GUARD_KEY,
+  reloadOnce,
+} from "./deploy-recovery.ts";
 
 // The two constants, but NOT `hydrateOrMount` — that one is at `@gusnips/react/hydrate`, because
 // it is the package's only `react-dom` import. These come from the contract module, which imports

package/src/chunk-reload.test.ts

@@ -1,113 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { isChunkLoadError, isPreloadHintFailure, reloadOnceForChunkError } from "./chunk-reload.ts";
-
-// No browser gives a failed dynamic import a shared type, so this is matched by message and
-// every phrasing has to be here. A miss is a white screen after a deploy — the exact failure
-// this module exists to catch — and it only reproduces on a real deploy, so the test is the
-// only place these strings get checked.
-describe("isChunkLoadError", () => {
-  it.each([
-    ["Chrome/Edge", "Failed to fetch dynamically imported module: https://x/assets/a.js"],
-    ["Firefox", "error loading dynamically imported module"],
-    ["Safari", "Importing a module script failed."],
-    ["webpack", "Loading chunk 42 failed."],
-    // The one that actually fires on a static host: the missing .js is answered with the SPA
-    // fallback, so the browser refuses the HTML rather than reporting a 404.
-    [
-      "SPA fallback",
-      "Expected a JavaScript module script but the server responded with a MIME type of text/html",
-    ],
-  ])("matches %s", (_browser, message) => {
-    expect(isChunkLoadError(new Error(message))).toBe(true);
-  });
-
-  it("matches a named ChunkLoadError whatever its message", () => {
-    const error = new Error("nothing recognisable");
-    error.name = "ChunkLoadError";
-    expect(isChunkLoadError(error)).toBe(true);
-  });
-
-  it("does not match an ordinary render error", () => {
-    expect(isChunkLoadError(new TypeError("Cannot read properties of undefined"))).toBe(false);
-    expect(isChunkLoadError(null)).toBe(false);
-    // A thrown string reaches the `String(error)` branch, which is the one a non-Error throw
-    // takes — and the one that would blow up if it were written `error.message`.
-    expect(isChunkLoadError("something failed")).toBe(false);
-  });
-});
-
-// The distinction that matters: swallowing a real module failure resolves the import with
-// `undefined`, React.lazy reads `.default` off nothing, and the developer gets a TypeError with
-// only React frames in it — naming no chunk. Only the CSS hint is safe to swallow.
-describe("isPreloadHintFailure", () => {
-  it("matches Vite's CSS preload hint and nothing else", () => {
-    expect(isPreloadHintFailure(new Error("Unable to preload CSS for /assets/a.css"))).toBe(true);
-    expect(isPreloadHintFailure(new Error("Failed to fetch dynamically imported module"))).toBe(
-      false,
-    );
-  });
-});
-
-/**
- * The guard, which is the whole reason this function exists rather than a bare
- * `location.reload()` at the call site. Reloading on a chunk error the reload does not fix is
- * an infinite loop with a person inside it, and it only reproduces on a real broken deploy —
- * so this is the only place the rule gets checked.
- *
- * Two globals, stubbed rather than run under a DOM: `window` and `sessionStorage` are the only
- * ones this module touches, and adding jsdom to a package whose whole point is a small
- * dependency list would cost more than it explains.
- */
-describe("reloadOnceForChunkError", () => {
-  const reload = vi.fn();
-  let store: Record<string, string> = {};
-  /** Throws from both methods, the way a browser does when site data is blocked. */
-  let blocked = false;
-
-  beforeEach(() => {
-    vi.useFakeTimers();
-    reload.mockClear();
-    store = {};
-    blocked = false;
-    vi.stubGlobal("window", { location: { reload } });
-    vi.stubGlobal("sessionStorage", {
-      getItem: (key: string): string | null => {
-        if (blocked) throw new Error("site data blocked");
-        return store[key] ?? null;
-      },
-      setItem: (key: string, value: string): void => {
-        if (blocked) throw new Error("site data blocked");
-        store[key] = value;
-      },
-    });
-  });
-
-  afterEach(() => {
-    vi.unstubAllGlobals();
-    vi.useRealTimers();
-  });
-
-  it("reloads on the first chunk failure", () => {
-    expect(reloadOnceForChunkError()).toBe(true);
-    expect(reload).toHaveBeenCalledTimes(1);
-  });
-
-  it("refuses a second reload inside the window, so a dead chunk cannot loop", () => {
-    expect(reloadOnceForChunkError()).toBe(true);
-    expect(reloadOnceForChunkError()).toBe(false);
-    expect(reload).toHaveBeenCalledTimes(1);
-  });
-
-  it("allows another one after the window, because the next deploy is a new problem", () => {
-    expect(reloadOnceForChunkError()).toBe(true);
-    vi.setSystemTime(Date.now() + 61_000);
-    expect(reloadOnceForChunkError()).toBe(true);
-    expect(reload).toHaveBeenCalledTimes(2);
-  });
-
-  it("still reloads when storage is blocked — a privacy setting is not a reason to strand", () => {
-    blocked = true;
-    expect(reloadOnceForChunkError()).toBe(true);
-    expect(reload).toHaveBeenCalledTimes(1);
-  });
-});

package/src/chunk-reload.ts

@@ -1,94 +0,0 @@
-/**
- * Surviving a deploy that lands while a tab is open.
- *
- * Every app on this stack is a Vite SPA with `lazy()` routes, deployed on push. When a build
- * replaces the one a tab is running, the next navigation asks for a chunk whose hashed name no
- * longer exists — and a static host answers a missing asset with the SPA fallback, so the
- * import gets HTML where it expected a module. React's lazy boundary throws, and the person
- * gets a white screen on a click that worked a minute ago.
- *
- * One repo in the fleet had all of this. The others had none of it, and none of them knew.
- */
-
-const RELOAD_FLAG_KEY = "frontkit:chunk-reload-at";
-const RELOAD_WINDOW_MS = 60_000;
-
-/**
- * A lazy-chunk fetch failure — recoverable by reloading.
- *
- * Matched by message because no browser gives it a shared type. Every phrasing in the wild is
- * here: Chrome/Edge "Failed to fetch dynamically imported module", Firefox "error loading
- * dynamically imported module", Safari "Importing a module script failed", webpack's
- * ChunkLoadError and "Loading chunk N failed", and the SPA-fallback "MIME type" refusal —
- * which is the one that actually fires on a static host, because the missing `.js` is answered
- * with `index.html`.
- *
- * A standalone predicate rather than a method on the boundary, so a global `unhandledrejection`
- * handler can classify the same failure without importing a component.
- */
-export function isChunkLoadError(error: unknown): boolean {
-  if (error instanceof Error && error.name === "ChunkLoadError") return true;
-  const message = (error instanceof Error ? error.message : String(error) || "").toLowerCase();
-  return (
-    message.includes("dynamically imported module") ||
-    message.includes("importing a module script failed") ||
-    message.includes("mime type") ||
-    message.includes("loading chunk")
-  );
-}
-
-/**
- * Hard-reload once to pick up the fresh deploy. Returns false when the guard suppressed it.
- *
- * The guard is the part that matters. Reloading on a chunk error is obvious; reloading on a
- * chunk error that the reload does not fix is an infinite loop with the user inside it. At most
- * one reload per minute, so a genuinely missing chunk degrades to the error UI — which can at
- * least say something — instead of flickering forever.
- *
- * `sessionStorage` and not `localStorage`: the guard is about this tab's current predicament,
- * and a stale flag in another tab must not suppress a reload this one needs. Wrapped because
- * storage throws outright when site data is blocked, and a privacy setting must not be the
- * reason somebody cannot recover.
- */
-export function reloadOnceForChunkError(): boolean {
-  const now = Date.now();
-  try {
-    const last = Number(sessionStorage.getItem(RELOAD_FLAG_KEY) ?? 0);
-    if (now - last < RELOAD_WINDOW_MS) return false;
-    sessionStorage.setItem(RELOAD_FLAG_KEY, String(now));
-  } catch {
-    // Storage blocked — proceed with the reload rather than refusing to recover.
-  }
-  window.location.reload();
-  return true;
-}
-
-/**
- * Vite's *hint* failure, which is not the same thing and must not be treated as one.
- *
- * Vite injects a speculative `<link rel="stylesheet">` for a chunk's CSS before importing it.
- * When that link fails, the import itself still runs right after and usually succeeds — so this
- * one is worth swallowing, where a failure of the import is the real thing
- * {@link isChunkLoadError} matches. Vite builds this message in exactly one place and only ever
- * for a stylesheet link; script hints never reject.
- */
-export function isPreloadHintFailure(error: unknown): boolean {
-  return error instanceof Error && error.message.startsWith("Unable to preload CSS for");
-}
-
-/**
- * Install the `vite:preloadError` listener. Call once, from the browser entry.
- *
- * Vite offers `preventDefault()` here so an app can own a failed asset itself — but taking that
- * deal unconditionally resolves the dynamic import with `undefined` (Vite's helper ends in
- * `baseModule().catch(handlePreloadError)`), and `React.lazy` then reads `.default` off nothing.
- * The user gets the crash screen and the developer gets a TypeError with only React frames in
- * it, naming no chunk. So it is taken ONLY for a failed preload hint, where the import still
- * runs. A real module failure is left to throw, where the error boundary can recognise it.
- */
-export function installPreloadErrorHandler(): void {
-  window.addEventListener("vite:preloadError", (event) => {
-    const payload = (event as Event & { payload?: unknown }).payload;
-    if (isPreloadHintFailure(payload)) event.preventDefault();
-  });
-}