@ovineko/spa-guard 0.0.1-alpha-25 → 0.0.1-alpha-27

package/README.md

@@ -0,0 +1,76 @@
+# @ovineko/spa-guard
+
+[![npm](https://img.shields.io/npm/v/@ovineko/spa-guard)](https://www.npmjs.com/package/@ovineko/spa-guard)
+[![license](https://img.shields.io/npm/l/@ovineko/spa-guard)](./LICENSE)
+
+Core runtime for spa-guard — chunk load error handling, version checking, spinner, i18n, and event schema for SPAs.
+
+## Install
+
+```sh
+npm install @ovineko/spa-guard
+```
+
+## Usage
+
+Call `recommendedSetup` once when your app boots. It dismisses the loading spinner, starts version checking, and returns a cleanup function.
+
+```ts
+import { recommendedSetup } from "@ovineko/spa-guard/runtime";
+
+const cleanup = recommendedSetup();
+// optionally call cleanup() to stop background checks
+```
+
+Disable version checking:
+
+```ts
+const cleanup = recommendedSetup({ versionCheck: false });
+```
+
+## API
+
+### `@ovineko/spa-guard` (common)
+
+- `listen` — subscribe to spa-guard events
+- `events` — event type constants
+- `options` — runtime options helpers
+- `disableDefaultRetry` / `enableDefaultRetry` / `isDefaultRetryEnabled` — control default retry behaviour
+- `BeaconError` — error class for beacon failures
+- `ForceRetryError` — error class to force a retry
+
+### `@ovineko/spa-guard/runtime`
+
+- `recommendedSetup(options?)` — enable recommended runtime features; returns cleanup function
+- `RecommendedSetupOptions` — `{ versionCheck?: boolean }`
+- `startVersionCheck` / `stopVersionCheck` — manual version check control
+- `getState` / `subscribeToState` — runtime state access
+- `SpaGuardState` — state type
+- `showSpinner` / `dismissSpinner` / `getSpinnerHtml` — spinner helpers
+- `setTranslations` — override i18n strings
+- `ForceRetryError`
+
+### `@ovineko/spa-guard/schema`
+
+Schemas for spa-guard configuration.
+
+### `@ovineko/spa-guard/i18n`
+
+Built-in translation strings.
+
+### `@ovineko/spa-guard/runtime/debug`
+
+Debug helpers for testing error scenarios.
+
+## Related packages
+
+- [@ovineko/spa-guard-react](../react/README.md) — `lazyWithRetry` and React error boundary
+- [@ovineko/spa-guard-react-router](../react-router/README.md) — React Router error boundary
+- [@ovineko/spa-guard-vite](../vite/README.md) — Vite plugin (injects runtime script)
+- [@ovineko/spa-guard-node](../node/README.md) — Node.js cache and builder API
+- [@ovineko/spa-guard-fastify](../fastify/README.md) — Fastify plugin
+- [@ovineko/spa-guard-eslint](../eslint/README.md) — ESLint rules
+
+## License
+
+MIT

package/dist/_internal.js

@@ -3,12 +3,12 @@ import {
   isChunkError,
   listenInternal,
   serializeError
-} from "./chunk-ZVYB2746.js";
+} from "./chunk-FRCJOMRP.js";
 import {
   SPINNER_ID,
   defaultSpinnerSvg,
   extractVersionFromHtml
-} from "./chunk-Z75UPJWV.js";
+} from "./chunk-7PDOUY6W.js";
 import {
   dispatchAsyncRuntimeError,
   dispatchChunkLoadError,
@@ -17,13 +17,13 @@ import {
   dispatchNetworkTimeout,
   dispatchSyncRuntimeError,
   dispatchUnhandledRejection
-} from "./chunk-XFILAQ7P.js";
+} from "./chunk-7KNE2UWX.js";
 import {
   attemptReload,
   sendBeacon,
   shouldForceRetry,
   shouldIgnoreMessages
-} from "./chunk-CSN7MQGX.js";
+} from "./chunk-KAH6PVTJ.js";
 import {
   applyI18n,
   debugSyncErrorEventType,
@@ -38,7 +38,7 @@ import {
   isDefaultRetryEnabled,
   optionsWindowKey,
   subscribe
-} from "./chunk-X6E7KUDK.js";
+} from "./chunk-67WBMNUS.js";
 import "./chunk-MLKGABMK.js";
 
 // src/common/handleErrorWithSpaGuard.ts
@@ -95,6 +95,8 @@ var retryImport = async (importFn, delays, options) => {
   const { callReloadOnFailure, onRetry, signal } = options ?? {};
   let lastError = new Error("Import failed after all retry attempts");
   const totalAttempts = delays.length + 1;
+  const startTime = Date.now();
+  emitEvent({ name: "lazy-retry-start", totalAttempts });
   for (let attempt = 0; attempt < totalAttempts; attempt++) {
     if (signal?.aborted) {
       throw signal.reason ?? new DOMException("Aborted", "AbortError");
@@ -102,7 +104,7 @@ var retryImport = async (importFn, delays, options) => {
     try {
       const result = await importFn();
       if (attempt > 0) {
-        emitEvent({ attempt, name: "lazy-retry-success" });
+        emitEvent({ attempt, name: "lazy-retry-success", totalTime: Date.now() - startTime });
       }
       return result;
     } catch (error) {
@@ -115,6 +117,7 @@ var retryImport = async (importFn, delays, options) => {
       emitEvent({
         attempt: attempt + 1,
         delay: currentDelay,
+        error: lastError,
         name: "lazy-retry-attempt",
         totalAttempts
       });
@@ -122,7 +125,7 @@ var retryImport = async (importFn, delays, options) => {
     }
   }
   const willReload = callReloadOnFailure === true && isChunkError(lastError) && isDefaultRetryEnabled();
-  emitEvent({ name: "lazy-retry-exhausted", totalAttempts, willReload });
+  emitEvent({ error: lastError, name: "lazy-retry-exhausted", totalAttempts, willReload });
   if (willReload) {
     attemptReload(lastError);
   }

package/dist/{chunk-X6E7KUDK.js → chunk-67WBMNUS.js}

@@ -14,6 +14,8 @@ var loggerWindowKey = /* @__PURE__ */ Symbol.for(`${name}:logger`);
 var RETRY_ID_PARAM = "spaGuardRetryId";
 var RETRY_ATTEMPT_PARAM = "spaGuardRetryAttempt";
 var versionCheckStateWindowKey = /* @__PURE__ */ Symbol.for(`${name}:version-check-state`);
+var reloadScheduledKey = /* @__PURE__ */ Symbol.for(`${name}:reload-scheduled`);
+var inMemoryLastReloadKey = /* @__PURE__ */ Symbol.for(`${name}:in-memory-last-reload`);
 var debugSyncErrorEventType = "spa-guard:debug-sync-error";
 
 // src/common/events/internal.ts
@@ -163,6 +165,10 @@ var defaultOptions = {
     },
     loading: {
       content: defaultLoadingFallbackHtml
+    },
+    spinner: {
+      background: "#fff",
+      disabled: false
     }
   },
   lazyRetry: {
@@ -171,9 +177,9 @@ var defaultOptions = {
   },
   minTimeBetweenResets: 5e3,
   reloadDelays: [1e3, 2e3, 5e3],
-  spinner: {
-    background: "#fff",
-    disabled: false
+  staticAssets: {
+    autoRecover: true,
+    recoveryDelay: 500
   },
   useRetryId: true
 };
@@ -202,6 +208,10 @@ var getOptions = () => {
       loading: {
         ...defaultOptions.html?.loading,
         ...windowOptions?.html?.loading
+      },
+      spinner: {
+        ...defaultOptions.html?.spinner,
+        ...windowOptions?.html?.spinner
       }
     },
     lazyRetry: {
@@ -212,9 +222,9 @@ var getOptions = () => {
       ...defaultOptions.reportBeacon,
       ...windowOptions?.reportBeacon
     },
-    spinner: {
-      ...defaultOptions.spinner,
-      ...windowOptions?.spinner
+    staticAssets: {
+      ...defaultOptions.staticAssets,
+      ...windowOptions?.staticAssets
     }
   };
 };
@@ -231,8 +241,19 @@ var ForceRetryError = class extends Error {
 // src/common/lastReloadTime.ts
 var STORAGE_KEY = "__spa_guard_last_reload_timestamp__";
 var RESET_INFO_KEY = "__spa_guard_last_retry_reset__";
-var inMemoryStorage = null;
-var inMemoryResetInfo = null;
+if (globalThis.window && !globalThis.window[inMemoryLastReloadKey]) {
+  globalThis.window[inMemoryLastReloadKey] = {
+    resetInfo: null,
+    storage: null
+  };
+}
+var getInMemoryState = () => {
+  const w = globalThis.window;
+  if (!w) {
+    return { resetInfo: null, storage: null };
+  }
+  return w[inMemoryLastReloadKey] ?? (w[inMemoryLastReloadKey] = { resetInfo: null, storage: null });
+};
 var hasSessionStorage = () => {
   try {
     return globalThis.window !== void 0 && typeof sessionStorage !== "undefined";
@@ -250,10 +271,10 @@ var setLastReloadTime = (retryId, attemptNumber) => {
     try {
       sessionStorage.setItem(STORAGE_KEY, JSON.stringify(data));
     } catch {
-      inMemoryStorage = data;
+      getInMemoryState().storage = data;
     }
   } else {
-    inMemoryStorage = data;
+    getInMemoryState().storage = data;
   }
 };
 var getLastReloadTime = () => {
@@ -264,10 +285,14 @@ var getLastReloadTime = () => {
         return JSON.parse(stored);
       }
     } catch {
-      return inMemoryStorage;
+      try {
+        sessionStorage.removeItem(STORAGE_KEY);
+      } catch {
+      }
+      return getInMemoryState().storage;
     }
   }
-  return inMemoryStorage;
+  return getInMemoryState().storage;
 };
 var clearLastReloadTime = () => {
   if (hasSessionStorage()) {
@@ -276,7 +301,7 @@ var clearLastReloadTime = () => {
     } catch {
     }
   }
-  inMemoryStorage = null;
+  getInMemoryState().storage = null;
 };
 var shouldResetRetryCycle = (retryState, reloadDelays, minTimeBetweenResets = 5e3) => {
   if (retryState.retryAttempt === 0) {
@@ -311,10 +336,10 @@ var setLastRetryResetInfo = (previousRetryId) => {
     try {
       sessionStorage.setItem(RESET_INFO_KEY, JSON.stringify(data));
     } catch {
-      inMemoryResetInfo = data;
+      getInMemoryState().resetInfo = data;
     }
   } else {
-    inMemoryResetInfo = data;
+    getInMemoryState().resetInfo = data;
   }
 };
 var getLastRetryResetInfo = () => {
@@ -325,10 +350,14 @@ var getLastRetryResetInfo = () => {
         return JSON.parse(stored);
       }
     } catch {
-      return inMemoryResetInfo;
+      try {
+        sessionStorage.removeItem(RESET_INFO_KEY);
+      } catch {
+      }
+      return getInMemoryState().resetInfo;
     }
   }
-  return inMemoryResetInfo;
+  return getInMemoryState().resetInfo;
 };
 
 // src/common/retryState.ts
@@ -421,6 +450,7 @@ export {
   RETRY_ID_PARAM,
   RETRY_ATTEMPT_PARAM,
   versionCheckStateWindowKey,
+  reloadScheduledKey,
   debugSyncErrorEventType,
   setLogger,
   getLogger,

package/dist/{chunk-XFILAQ7P.js → chunk-7KNE2UWX.js}

@@ -1,12 +1,12 @@
 import {
   showFallbackUI
-} from "./chunk-CSN7MQGX.js";
+} from "./chunk-KAH6PVTJ.js";
 import {
   ForceRetryError,
   debugSyncErrorEventType,
   emitEvent,
   getOptions
-} from "./chunk-X6E7KUDK.js";
+} from "./chunk-67WBMNUS.js";
 
 // src/runtime/debug/errorDispatchers.ts
 function dispatchAsyncRuntimeError() {

package/dist/{chunk-Z75UPJWV.js → chunk-7PDOUY6W.js}

@@ -1,7 +1,7 @@
 import {
   defaultSpinnerHtml,
   getOptions
-} from "./chunk-X6E7KUDK.js";
+} from "./chunk-67WBMNUS.js";
 
 // src/common/parseVersion.ts
 function extractVersionFromHtml(html) {
@@ -37,11 +37,11 @@ function dismissSpinner() {
 }
 function getSpinnerHtml(backgroundOverride) {
   const opts = getOptions();
-  if (opts.spinner?.disabled) {
+  if (opts.html?.spinner?.disabled) {
     return "";
   }
-  const spinnerContent = opts.spinner?.content ?? defaultSpinnerSvg;
-  const bg = backgroundOverride ?? opts.spinner?.background ?? "#fff";
+  const spinnerContent = opts.html?.spinner?.content ?? defaultSpinnerSvg;
+  const bg = backgroundOverride ?? opts.html?.spinner?.background ?? "#fff";
   return `<div id="${SPINNER_ID}" style="position:fixed;inset:0;z-index:2147483647;display:flex;align-items:center;justify-content:center;background:var(--spa-guard-spinner-bg,${bg})">${spinnerContent}</div>`;
 }
 function showSpinner(options) {
@@ -50,7 +50,7 @@ function showSpinner(options) {
     };
   }
   const opts = getOptions();
-  if (opts.spinner?.disabled) {
+  if (opts.html?.spinner?.disabled) {
     return () => {
     };
   }

package/dist/{chunk-ZVYB2746.js → chunk-FRCJOMRP.js}

@@ -3,8 +3,9 @@ import {
   sendBeacon,
   shouldForceRetry,
   shouldIgnoreMessages
-} from "./chunk-CSN7MQGX.js";
+} from "./chunk-KAH6PVTJ.js";
 import {
+  emitEvent,
   getLogger,
   getOptions,
   getRetryInfoForBeacon,
@@ -13,7 +14,7 @@ import {
   markInitialized,
   setLogger,
   updateRetryStateInUrl
-} from "./chunk-X6E7KUDK.js";
+} from "./chunk-67WBMNUS.js";
 
 // src/common/isChunkError.ts
 var isChunkError = (error) => {
@@ -158,6 +159,59 @@ var extractOwnProperties = (obj) => {
   return props;
 };
 
+// src/common/isStaticAssetError.ts
+var HASHED_ASSET_RE = /[-._][a-zA-Z0-9]{6,}\.(js|mjs|css)$/i;
+var isHashedAssetUrl = (url) => {
+  try {
+    const pathname = new URL(url).pathname;
+    return HASHED_ASSET_RE.test(pathname);
+  } catch {
+    return HASHED_ASSET_RE.test(url);
+  }
+};
+var isStaticAssetError = (event) => {
+  const target = event.target;
+  if (target instanceof HTMLScriptElement) {
+    return isHashedAssetUrl(target.src);
+  }
+  if (target instanceof HTMLLinkElement) {
+    return isHashedAssetUrl(target.href);
+  }
+  return false;
+};
+var isLikely404 = (timeSinceNavMs = typeof performance === "undefined" ? 0 : performance.now()) => {
+  return timeSinceNavMs > 3e4;
+};
+var getAssetUrl = (event) => {
+  const target = event.target;
+  if (target instanceof HTMLScriptElement) {
+    return target.src;
+  }
+  if (target instanceof HTMLLinkElement) {
+    return target.href;
+  }
+  return "";
+};
+
+// src/common/staticAssetRecovery.ts
+var recoveryTimer = null;
+var failedAssets = /* @__PURE__ */ new Set();
+var handleStaticAssetFailure = (url) => {
+  failedAssets.add(url);
+  if (recoveryTimer !== null) {
+    return;
+  }
+  const options = getOptions();
+  const delay = options.staticAssets?.recoveryDelay ?? 500;
+  recoveryTimer = setTimeout(() => {
+    const assets = [...failedAssets];
+    failedAssets = /* @__PURE__ */ new Set();
+    recoveryTimer = null;
+    const error = new Error(`Static asset load failed: ${assets.join(", ")}`);
+    attemptReload(error, { cacheBust: true });
+  }, delay);
+};
+
 // src/common/listen/internal.ts
 var listenInternal = (serializeError2, logger) => {
   if (logger) {
@@ -192,6 +246,15 @@ var listenInternal = (serializeError2, logger) => {
         attemptReload(event.error ?? event);
         return;
       }
+      if (isStaticAssetError(event) && isLikely404()) {
+        const assetUrl = getAssetUrl(event);
+        event.preventDefault();
+        emitEvent({ name: "static-asset-load-failed", url: assetUrl });
+        if (options.staticAssets?.autoRecover !== false) {
+          handleStaticAssetFailure(assetUrl);
+        }
+        return;
+      }
       const serialized = serializeError2(event);
       sendBeacon({
         errorMessage: event.message,
@@ -265,10 +328,12 @@ var eventLogConfig = {
   "fallback-ui-shown": "warn",
   "lazy-retry-attempt": "warn",
   "lazy-retry-exhausted": "error",
+  "lazy-retry-start": "log",
   "lazy-retry-success": "log",
   "retry-attempt": "warn",
   "retry-exhausted": "error",
-  "retry-reset": "log"
+  "retry-reset": "log",
+  "static-asset-load-failed": "error"
 };
 var formatEvent = (event) => {
   switch (event.name) {
@@ -284,8 +349,12 @@ var formatEvent = (event) => {
     case "lazy-retry-exhausted": {
       return `${PREFIX} lazy-retry-exhausted: ${event.totalAttempts} attempts, willReload=${event.willReload}`;
     }
+    case "lazy-retry-start": {
+      return `${PREFIX} lazy-retry-start: totalAttempts=${event.totalAttempts}`;
+    }
     case "lazy-retry-success": {
-      return `${PREFIX} lazy-retry-success: succeeded on attempt ${event.attempt}`;
+      const timePart = event.totalTime === void 0 ? "" : `, totalTime=${event.totalTime}ms`;
+      return `${PREFIX} lazy-retry-success: succeeded on attempt ${event.attempt}${timePart}`;
     }
     case "retry-attempt": {
       return `${PREFIX} retry-attempt: attempt ${event.attempt} in ${event.delay}ms (retryId: ${event.retryId})`;
@@ -296,6 +365,9 @@ var formatEvent = (event) => {
     case "retry-reset": {
       return `${PREFIX} retry-reset: ${event.timeSinceReload}ms since last reload (retryId: ${event.previousRetryId})`;
     }
+    case "static-asset-load-failed": {
+      return `${PREFIX} static-asset-load-failed: ${event.url}`;
+    }
   }
 };
 var createLogger = () => ({
@@ -329,7 +401,7 @@ var createLogger = () => ({
   logEvent(event) {
     const level = eventLogConfig[event.name];
     const message = formatEvent(event);
-    if (event.name === "chunk-error") {
+    if (event.name === "chunk-error" || event.name === "lazy-retry-attempt" || event.name === "lazy-retry-exhausted") {
       console[level](message, event.error);
     } else {
       console[level](message);

package/dist/{chunk-CSN7MQGX.js → chunk-KAH6PVTJ.js}

@@ -15,10 +15,11 @@ import {
   getRetryAttemptFromUrl,
   getRetryStateFromUrl,
   isDefaultRetryEnabled,
+  reloadScheduledKey,
   setLastReloadTime,
   setLastRetryResetInfo,
   shouldResetRetryCycle
-} from "./chunk-X6E7KUDK.js";
+} from "./chunk-67WBMNUS.js";
 
 // src/common/shouldIgnore.ts
 var shouldIgnoreMessages = (messages) => {
@@ -81,13 +82,22 @@ var buildReloadUrlAttemptOnly = (retryAttempt) => {
   url.searchParams.set(RETRY_ATTEMPT_PARAM, String(retryAttempt));
   return url.toString();
 };
-var reloadScheduled = false;
-var attemptReload = (error) => {
-  if (reloadScheduled) {
+if (globalThis.window && !globalThis.window[reloadScheduledKey]) {
+  globalThis.window[reloadScheduledKey] = { scheduled: false };
+}
+var getReloadState = () => {
+  if (globalThis.window === void 0) {
+    return { scheduled: false };
+  }
+  return globalThis.window[reloadScheduledKey] ?? (globalThis.window[reloadScheduledKey] = { scheduled: false });
+};
+var attemptReload = (error, opts) => {
+  const reloadState = getReloadState();
+  if (reloadState.scheduled) {
     getLogger()?.reloadAlreadyScheduled(error);
     return;
   }
-  reloadScheduled = true;
+  reloadState.scheduled = true;
   try {
     const options = getOptions();
     const reloadDelays = options.reloadDelays ?? [1e3, 2e3, 5e3];
@@ -111,7 +121,7 @@ var attemptReload = (error) => {
       name: "chunk-error"
     });
     if (!retryEnabled) {
-      reloadScheduled = false;
+      reloadState.scheduled = false;
       return;
     }
     if (enableRetryReset && retryState && retryState.retryAttempt > 0 && shouldResetRetryCycle(retryState, reloadDelays, minTimeBetweenResets)) {
@@ -138,7 +148,7 @@ var attemptReload = (error) => {
       if (!shouldIgnoreMessages([errorMsg2])) {
         getLogger()?.fallbackAlreadyShown(error);
       }
-      reloadScheduled = false;
+      reloadState.scheduled = false;
       showFallbackUI();
       return;
     }
@@ -166,7 +176,7 @@ var attemptReload = (error) => {
       if (!useRetryId) {
         clearRetryAttemptFromUrl();
       }
-      reloadScheduled = false;
+      reloadState.scheduled = false;
       showFallbackUI();
       return;
     }
@@ -188,15 +198,17 @@ var attemptReload = (error) => {
       if (useRetryId && enableRetryReset) {
         setLastReloadTime(retryId, nextAttempt);
       }
-      if (useRetryId) {
-        const reloadUrl = buildReloadUrl(retryId, nextAttempt);
-        globalThis.window.location.href = reloadUrl;
-      } else {
-        globalThis.window.location.href = buildReloadUrlAttemptOnly(nextAttempt);
+      let reloadUrl;
+      reloadUrl = useRetryId ? buildReloadUrl(retryId, nextAttempt) : buildReloadUrlAttemptOnly(nextAttempt);
+      if (opts?.cacheBust) {
+        const url = new URL(reloadUrl);
+        url.searchParams.set("spaGuardCacheBust", String(Date.now()));
+        reloadUrl = url.toString();
       }
+      globalThis.window.location.href = reloadUrl;
     }, delay);
   } catch {
-    reloadScheduled = false;
+    reloadState.scheduled = false;
   }
 };
 var showLoadingUI = (attempt) => {
@@ -215,10 +227,10 @@ var showLoadingUI = (attempt) => {
     container.innerHTML = loadingHtml;
     const spinnerEl = container.querySelector("[data-spa-guard-spinner]");
     if (spinnerEl) {
-      if (options.spinner?.disabled) {
+      if (options.html?.spinner?.disabled) {
         spinnerEl.remove();
-      } else if (options.spinner?.content) {
-        spinnerEl.innerHTML = options.spinner.content;
+      } else if (options.html?.spinner?.content) {
+        spinnerEl.innerHTML = options.html.spinner.content;
       }
     }
     const retryingSection = container.querySelector(

package/dist/{chunk-T72DERME.js → chunk-V2OOMVZK.js}

@@ -3,7 +3,7 @@ import {
   getRetryAttemptFromUrl,
   getRetryStateFromUrl,
   subscribe
-} from "./chunk-X6E7KUDK.js";
+} from "./chunk-67WBMNUS.js";
 
 // src/runtime/state.ts
 var getInitialStateFromUrl = () => {

package/dist/common/constants.d.ts

@@ -6,4 +6,6 @@ export declare const loggerWindowKey: unique symbol;
 export declare const RETRY_ID_PARAM = "spaGuardRetryId";
 export declare const RETRY_ATTEMPT_PARAM = "spaGuardRetryAttempt";
 export declare const versionCheckStateWindowKey: unique symbol;
+export declare const reloadScheduledKey: unique symbol;
+export declare const inMemoryLastReloadKey: unique symbol;
 export declare const debugSyncErrorEventType = "spa-guard:debug-sync-error";

package/dist/common/events/types.d.ts

@@ -13,6 +13,8 @@ export type SPAGuardEvent = (SPAGuardEventChunkError & {
     name: "lazy-retry-attempt";
 }) | (SPAGuardEventLazyRetryExhausted & {
     name: "lazy-retry-exhausted";
+}) | (SPAGuardEventLazyRetryStart & {
+    name: "lazy-retry-start";
 }) | (SPAGuardEventLazyRetrySuccess & {
     name: "lazy-retry-success";
 }) | (SPAGuardEventRetryAttempt & {
@@ -21,6 +23,8 @@ export type SPAGuardEvent = (SPAGuardEventChunkError & {
     name: "retry-exhausted";
 }) | (SPAGuardEventRetryReset & {
     name: "retry-reset";
+}) | (SPAGuardEventStaticAssetLoadFailed & {
+    name: "static-asset-load-failed";
 });
 export interface SPAGuardEventChunkError {
     error: unknown;
@@ -36,23 +40,35 @@ export interface SPAGuardEventLazyRetryAttempt {
     attempt: number;
     /** Delay in milliseconds before this retry attempt. */
     delay: number;
+    /** The error that caused the previous attempt to fail. */
+    error?: unknown;
     name: "lazy-retry-attempt";
     /** Total number of attempts including the initial try (delays.length + 1). */
     totalAttempts: number;
 }
 /** Emitted when all module-level retry attempts are exhausted. */
 export interface SPAGuardEventLazyRetryExhausted {
+    /** The final error after all attempts failed. */
+    error: unknown;
     name: "lazy-retry-exhausted";
     /** Total number of attempts that were made (delays.length + 1). */
     totalAttempts: number;
     /** Whether attemptReload() will be called after this event. */
     willReload: boolean;
 }
+/** Emitted once before the first import attempt, when retries are configured. */
+export interface SPAGuardEventLazyRetryStart {
+    name: "lazy-retry-start";
+    /** Total number of attempts that will be made (delays.length + 1). */
+    totalAttempts: number;
+}
 /** Emitted when a module loads successfully after one or more retry attempts. */
 export interface SPAGuardEventLazyRetrySuccess {
     /** 1-based retry number on which the import succeeded (1 = first retry). */
     attempt: number;
     name: "lazy-retry-success";
+    /** Total time in milliseconds from first attempt to success. */
+    totalTime?: number;
 }
 export interface SPAGuardEventRetryAttempt {
     attempt: number;
@@ -71,5 +87,11 @@ export interface SPAGuardEventRetryReset {
     previousRetryId: string;
     timeSinceReload: number;
 }
+/** Emitted when a hashed static asset (script/link) fails to load, likely due to a stale deployment. */
+export interface SPAGuardEventStaticAssetLoadFailed {
+    name: "static-asset-load-failed";
+    /** The URL of the asset that failed to load. */
+    url: string;
+}
 export type SubscribeFn = (event: SPAGuardEvent) => void;
 export type UnsubscribeFn = () => void;

package/dist/common/index.js

@@ -2,8 +2,8 @@ import {
   createLogger,
   listenInternal,
   serializeError
-} from "../chunk-ZVYB2746.js";
-import "../chunk-CSN7MQGX.js";
+} from "../chunk-FRCJOMRP.js";
+import "../chunk-KAH6PVTJ.js";
 import {
   ForceRetryError,
   disableDefaultRetry,
@@ -12,7 +12,7 @@ import {
   isDefaultRetryEnabled,
   options_exports,
   subscribe
-} from "../chunk-X6E7KUDK.js";
+} from "../chunk-67WBMNUS.js";
 import {
   __export
 } from "../chunk-MLKGABMK.js";

package/dist/common/isStaticAssetError.d.ts

@@ -0,0 +1,3 @@
+export declare const isStaticAssetError: (event: Event) => boolean;
+export declare const isLikely404: (timeSinceNavMs?: number) => boolean;
+export declare const getAssetUrl: (event: Event) => string;

package/dist/common/options.d.ts

@@ -95,6 +95,30 @@ export interface Options {
             /** Custom HTML to display during the loading/retrying state */
             content?: string;
         };
+        /**
+         * Spinner overlay configuration.
+         * Controls the full-page loading spinner injected by the Vite plugin
+         * and available via `showSpinner()`/`dismissSpinner()` at runtime.
+         */
+        spinner?: {
+            /**
+             * Overlay background color.
+             * Used as CSS variable fallback: var(--spa-guard-spinner-bg, <this value>).
+             * @default '#fff'
+             */
+            background?: string;
+            /**
+             * Custom spinner HTML (the spinner element only, no container/overlay).
+             * If not provided, uses the default SVG spinner.
+             */
+            content?: string;
+            /**
+             * Disable spinner entirely.
+             * No injection into body, showSpinner() is a no-op, Spinner returns null.
+             * @default false
+             */
+            disabled?: boolean;
+        };
     };
     /**
      * Options for the lazyWithRetry module-level retry logic.
@@ -130,28 +154,22 @@ export interface Options {
         endpoint?: string;
     };
     /**
-     * Spinner overlay configuration.
-     * Controls the full-page loading spinner injected by the Vite plugin
-     * and available via `showSpinner()`/`dismissSpinner()` at runtime.
+     * Configuration for automatic recovery from static asset 404 errors
+     * caused by deployment version mismatches.
      */
-    spinner?: {
+    staticAssets?: {
         /**
-         * Overlay background color.
-         * Used as CSS variable fallback: var(--spa-guard-spinner-bg, <this value>).
-         * @default '#fff'
-         */
-        background?: string;
-        /**
-         * Custom spinner HTML (the spinner element only, no container/overlay).
-         * If not provided, uses the default SVG spinner.
+         * Automatically trigger a cache-busting reload when a hashed static asset
+         * fails to load and the page has been open long enough to suggest a stale deployment.
+         * @default true
          */
-        content?: string;
+        autoRecover?: boolean;
         /**
-         * Disable spinner entirely.
-         * No injection into body, showSpinner() is a no-op, Spinner returns null.
-         * @default false
+         * Milliseconds to wait after the first failed asset before triggering the reload.
+         * Allows collecting multiple concurrent failures into a single reload.
+         * @default 500
          */
-        disabled?: boolean;
+        recoveryDelay?: number;
     };
     /** @default true */
     useRetryId?: boolean;

package/dist/common/reload.d.ts

@@ -1,4 +1,6 @@
 /** @internal */
 export declare const resetReloadScheduled: () => void;
-export declare const attemptReload: (error: unknown) => void;
+export declare const attemptReload: (error: unknown, opts?: {
+    cacheBust?: boolean;
+}) => void;
 export declare const showFallbackUI: () => void;

package/dist/common/staticAssetRecovery.d.ts

@@ -0,0 +1,2 @@
+export declare const handleStaticAssetFailure: (url: string) => void;
+export declare const resetStaticAssetRecovery: () => void;

package/dist/runtime/debug/index.js

@@ -7,14 +7,14 @@ import {
   dispatchRetryExhausted,
   dispatchSyncRuntimeError,
   dispatchUnhandledRejection
-} from "../../chunk-XFILAQ7P.js";
-import "../../chunk-CSN7MQGX.js";
+} from "../../chunk-7KNE2UWX.js";
+import "../../chunk-KAH6PVTJ.js";
 import {
   subscribeToState
-} from "../../chunk-T72DERME.js";
+} from "../../chunk-V2OOMVZK.js";
 import {
   subscribe
-} from "../../chunk-X6E7KUDK.js";
+} from "../../chunk-67WBMNUS.js";
 import "../../chunk-MLKGABMK.js";
 
 // src/runtime/debug/index.ts

package/dist/runtime/index.js

@@ -3,18 +3,18 @@ import {
   extractVersionFromHtml,
   getSpinnerHtml,
   showSpinner
-} from "../chunk-Z75UPJWV.js";
+} from "../chunk-7PDOUY6W.js";
 import {
   getState,
   subscribeToState
-} from "../chunk-T72DERME.js";
+} from "../chunk-V2OOMVZK.js";
 import {
   ForceRetryError,
   getLogger,
   getOptions,
   setTranslations,
   versionCheckStateWindowKey
-} from "../chunk-X6E7KUDK.js";
+} from "../chunk-67WBMNUS.js";
 import "../chunk-MLKGABMK.js";
 
 // src/common/checkVersion.ts
@@ -33,7 +33,10 @@ if (globalThis.window && !globalThis.window[versionCheckStateWindowKey]) {
   globalThis.window[versionCheckStateWindowKey] = createInitialState();
 }
 var getState2 = () => {
-  return globalThis.window?.[versionCheckStateWindowKey] ?? (globalThis.window[versionCheckStateWindowKey] = createInitialState());
+  if (globalThis.window === void 0) {
+    return createInitialState();
+  }
+  return globalThis.window[versionCheckStateWindowKey] ?? (globalThis.window[versionCheckStateWindowKey] = createInitialState());
 };
 var fetchJsonVersion = async () => {
   const endpoint = getOptions().checkVersion?.endpoint;

package/dist/schema/index.d.ts

@@ -1,9 +1,13 @@
 export interface BeaconSchema {
     appName?: string;
+    errorContext?: string;
     errorMessage?: string;
+    errorType?: string;
     eventMessage?: string;
     eventName?: string;
+    httpStatus?: number;
     retryAttempt?: number;
     retryId?: string;
     serialized?: string;
+    url?: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ovineko/spa-guard",
-  "version": "0.0.1-alpha-25",
+  "version": "0.0.1-alpha-27",
   "description": "Chunk load error handling for SPAs — core runtime, error handling, schema, i18n",
   "keywords": [
     "spa",