@ovineko/spa-guard 0.0.1-alpha-26 → 0.0.1-alpha-28

package/dist/_internal.d.ts

@@ -15,5 +15,5 @@ export { extractVersionFromHtml } from "./common/parseVersion";
 export { attemptReload } from "./common/reload";
 export { retryImport } from "./common/retryImport";
 export { serializeError } from "./common/serializeError";
-export { defaultSpinnerSvg, SPINNER_ID } from "./common/spinner";
+export { defaultSpinnerSvg, sanitizeCssValue, SPINNER_ID } from "./common/spinner";
 export { dispatchAsyncRuntimeError, dispatchChunkLoadError, dispatchFinallyError, dispatchForceRetryError, dispatchNetworkTimeout, dispatchSyncRuntimeError, dispatchUnhandledRejection, } from "./runtime/debug/errorDispatchers";

package/dist/_internal.js

@@ -3,12 +3,13 @@ import {
   isChunkError,
   listenInternal,
   serializeError
-} from "./chunk-ZVYB2746.js";
+} from "./chunk-5ANASVKX.js";
 import {
   SPINNER_ID,
   defaultSpinnerSvg,
-  extractVersionFromHtml
-} from "./chunk-Z75UPJWV.js";
+  extractVersionFromHtml,
+  sanitizeCssValue
+} from "./chunk-BA5VUNSU.js";
 import {
   dispatchAsyncRuntimeError,
   dispatchChunkLoadError,
@@ -17,13 +18,13 @@ import {
   dispatchNetworkTimeout,
   dispatchSyncRuntimeError,
   dispatchUnhandledRejection
-} from "./chunk-XFILAQ7P.js";
+} from "./chunk-62AC5565.js";
 import {
   attemptReload,
   sendBeacon,
   shouldForceRetry,
   shouldIgnoreMessages
-} from "./chunk-CSN7MQGX.js";
+} from "./chunk-4EXCHJBE.js";
 import {
   applyI18n,
   debugSyncErrorEventType,
@@ -38,7 +39,7 @@ import {
   isDefaultRetryEnabled,
   optionsWindowKey,
   subscribe
-} from "./chunk-X6E7KUDK.js";
+} from "./chunk-PE5QPP5Y.js";
 import "./chunk-MLKGABMK.js";
 
 // src/common/handleErrorWithSpaGuard.ts
@@ -95,6 +96,10 @@ 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();
+  if (delays.length > 0) {
+    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 +107,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 +120,7 @@ var retryImport = async (importFn, delays, options) => {
       emitEvent({
         attempt: attempt + 1,
         delay: currentDelay,
+        error: lastError,
         name: "lazy-retry-attempt",
         totalAttempts
       });
@@ -122,7 +128,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);
   }
@@ -157,6 +163,7 @@ export {
   logMessage,
   optionsWindowKey,
   retryImport,
+  sanitizeCssValue,
   serializeError,
   subscribe
 };

package/dist/{chunk-CSN7MQGX.js → chunk-4EXCHJBE.js}

@@ -1,4 +1,5 @@
 import {
+  CACHE_BUST_PARAM,
   FORCE_RETRY_MAGIC,
   RETRY_ATTEMPT_PARAM,
   RETRY_ID_PARAM,
@@ -15,10 +16,11 @@ import {
   getRetryAttemptFromUrl,
   getRetryStateFromUrl,
   isDefaultRetryEnabled,
+  reloadScheduledKey,
   setLastReloadTime,
   setLastRetryResetInfo,
   shouldResetRetryCycle
-} from "./chunk-X6E7KUDK.js";
+} from "./chunk-PE5QPP5Y.js";
 
 // src/common/shouldIgnore.ts
 var shouldIgnoreMessages = (messages) => {
@@ -81,13 +83,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 +122,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 +149,7 @@ var attemptReload = (error) => {
       if (!shouldIgnoreMessages([errorMsg2])) {
         getLogger()?.fallbackAlreadyShown(error);
       }
-      reloadScheduled = false;
+      reloadState.scheduled = false;
       showFallbackUI();
       return;
     }
@@ -166,7 +177,7 @@ var attemptReload = (error) => {
       if (!useRetryId) {
         clearRetryAttemptFromUrl();
       }
-      reloadScheduled = false;
+      reloadState.scheduled = false;
       showFallbackUI();
       return;
     }
@@ -188,15 +199,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(CACHE_BUST_PARAM, String(Date.now()));
+        reloadUrl = url.toString();
       }
+      globalThis.window.location.href = reloadUrl;
     }, delay);
   } catch {
-    reloadScheduled = false;
+    reloadState.scheduled = false;
   }
 };
 var showLoadingUI = (attempt) => {
@@ -215,10 +228,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-ZVYB2746.js → chunk-5ANASVKX.js}

@@ -3,8 +3,10 @@ import {
   sendBeacon,
   shouldForceRetry,
   shouldIgnoreMessages
-} from "./chunk-CSN7MQGX.js";
+} from "./chunk-4EXCHJBE.js";
 import {
+  clearRetryStateFromUrl,
+  emitEvent,
   getLogger,
   getOptions,
   getRetryInfoForBeacon,
@@ -12,8 +14,9 @@ import {
   isInitialized,
   markInitialized,
   setLogger,
+  staticAssetRecoveryKey,
   updateRetryStateInUrl
-} from "./chunk-X6E7KUDK.js";
+} from "./chunk-PE5QPP5Y.js";
 
 // src/common/isChunkError.ts
 var isChunkError = (error) => {
@@ -158,14 +161,96 @@ 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 checkResourceStatus = (url) => {
+  const entries = performance.getEntriesByName(url, "resource");
+  if (entries.length === 0) {
+    return true;
+  }
+  const entry = entries.at(-1);
+  if (entry.responseStatus >= 400) {
+    return true;
+  }
+  if (entry.transferSize === 0 && entry.decodedBodySize === 0) {
+    return true;
+  }
+  return false;
+};
+var isLikely404 = (url, timeSinceNavMs = typeof performance === "undefined" ? 0 : performance.now()) => {
+  if (url !== void 0) {
+    return checkResourceStatus(url);
+  }
+  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 getState = () => {
+  if (globalThis.window === void 0) {
+    return { failedAssets: /* @__PURE__ */ new Set(), recoveryTimer: null };
+  }
+  if (!globalThis.window[staticAssetRecoveryKey]) {
+    globalThis.window[staticAssetRecoveryKey] = {
+      failedAssets: /* @__PURE__ */ new Set(),
+      recoveryTimer: null
+    };
+  }
+  return globalThis.window[staticAssetRecoveryKey];
+};
+var handleStaticAssetFailure = (url) => {
+  const state = getState();
+  state.failedAssets.add(url);
+  if (state.recoveryTimer !== null) {
+    return;
+  }
+  const options = getOptions();
+  const delay = options.staticAssets?.recoveryDelay ?? 500;
+  state.recoveryTimer = setTimeout(() => {
+    const s = getState();
+    const assets = [...s.failedAssets];
+    s.failedAssets = /* @__PURE__ */ new Set();
+    s.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) {
-    setLogger(logger);
-  }
   if (isInitialized()) {
     return;
   }
+  if (logger) {
+    setLogger(logger);
+  }
   markInitialized();
   const options = getOptions();
   const reloadDelays = options.reloadDelays ?? [];
@@ -174,10 +259,34 @@ var listenInternal = (serializeError2, logger) => {
     getLogger()?.retryLimitExceeded(retryState.retryAttempt, reloadDelays.length);
     updateRetryStateInUrl(retryState.retryId, -1);
   }
+  if (retryState && (retryState.retryAttempt >= reloadDelays.length || retryState.retryAttempt === -1)) {
+    globalThis.window.addEventListener(
+      "load",
+      () => {
+        const current = getRetryStateFromUrl();
+        if (current?.retryAttempt === -1) {
+          clearRetryStateFromUrl();
+        }
+      },
+      { once: true }
+    );
+  }
   const wa = globalThis.window.addEventListener.bind(globalThis.window);
   wa(
     "error",
     (event) => {
+      const assetUrl = getAssetUrl(event);
+      if (isStaticAssetError(event) && isLikely404(assetUrl)) {
+        if (shouldIgnoreMessages([assetUrl, event.message])) {
+          return;
+        }
+        event.preventDefault();
+        emitEvent({ name: "static-asset-load-failed", url: assetUrl });
+        if (options.staticAssets?.autoRecover !== false) {
+          handleStaticAssetFailure(assetUrl);
+        }
+        return;
+      }
       if (shouldIgnoreMessages([event.message])) {
         return;
       }
@@ -265,10 +374,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 +395,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 +411,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 +447,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-XFILAQ7P.js → chunk-62AC5565.js}

@@ -1,12 +1,12 @@
 import {
   showFallbackUI
-} from "./chunk-CSN7MQGX.js";
+} from "./chunk-4EXCHJBE.js";
 import {
   ForceRetryError,
   debugSyncErrorEventType,
   emitEvent,
   getOptions
-} from "./chunk-X6E7KUDK.js";
+} from "./chunk-PE5QPP5Y.js";
 
 // src/runtime/debug/errorDispatchers.ts
 function dispatchAsyncRuntimeError() {
@@ -44,6 +44,12 @@ function dispatchRetryExhausted() {
   });
   showFallbackUI();
 }
+function dispatchStaticAsset404() {
+  const hash = crypto.randomUUID().replaceAll("-", "").slice(0, 8);
+  const script = document.createElement("script");
+  script.src = `/assets/index-${hash}.js`;
+  document.head.append(script);
+}
 function dispatchSyncRuntimeError() {
   const error = new Error("Simulated sync runtime error from spa-guard debug panel");
   globalThis.dispatchEvent(new CustomEvent(debugSyncErrorEventType, { detail: { error } }));
@@ -61,6 +67,7 @@ export {
   dispatchForceRetryError,
   dispatchNetworkTimeout,
   dispatchRetryExhausted,
+  dispatchStaticAsset404,
   dispatchSyncRuntimeError,
   dispatchUnhandledRejection
 };

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

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

package/dist/{chunk-Z75UPJWV.js → chunk-BA5VUNSU.js}

@@ -1,7 +1,8 @@
 import {
   defaultSpinnerHtml,
-  getOptions
-} from "./chunk-X6E7KUDK.js";
+  getOptions,
+  spinnerStateWindowKey
+} from "./chunk-PE5QPP5Y.js";
 
 // src/common/parseVersion.ts
 function extractVersionFromHtml(html) {
@@ -10,7 +11,12 @@ function extractVersionFromHtml(html) {
   if (versionMatch?.[1]) {
     return versionMatch[1];
   }
-  const optionsMatch = collapsed.match(
+  const markerIdx = collapsed.indexOf("__SPA_GUARD_OPTIONS__");
+  if (markerIdx === -1) {
+    return null;
+  }
+  const segment = collapsed.slice(markerIdx, markerIdx + 1e3);
+  const optionsMatch = segment.match(
     /__SPA_GUARD_OPTIONS__\s*=\s*\{.*?"?version"?\s*:\s*"([^"]+)"/
   );
   return optionsMatch?.[1] ?? null;
@@ -19,7 +25,12 @@ function extractVersionFromHtml(html) {
 // src/common/spinner.ts
 var SPINNER_ID = "__spa-guard-spinner";
 var defaultSpinnerSvg = defaultSpinnerHtml;
-var savedOverflow = null;
+var getState = () => {
+  if (!globalThis.window[spinnerStateWindowKey]) {
+    globalThis.window[spinnerStateWindowKey] = { savedOverflow: null };
+  }
+  return globalThis.window[spinnerStateWindowKey];
+};
 function dismissSpinner() {
   if (typeof document === "undefined") {
     return;
@@ -28,20 +39,22 @@ function dismissSpinner() {
   if (el) {
     el.remove();
   }
-  if (savedOverflow !== null) {
-    document.body.style.overflow = savedOverflow;
-    savedOverflow = null;
+  const state = getState();
+  if (state.savedOverflow !== null) {
+    document.body.style.overflow = state.savedOverflow;
+    state.savedOverflow = null;
   } else if (el) {
     document.body.style.overflow = "";
   }
 }
+var sanitizeCssValue = (value) => value.replaceAll(/["'<>\\{};\n]/g, "");
 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 = sanitizeCssValue(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 +63,7 @@ function showSpinner(options) {
     };
   }
   const opts = getOptions();
-  if (opts.spinner?.disabled) {
+  if (opts.html?.spinner?.disabled) {
     return () => {
     };
   }
@@ -67,7 +80,7 @@ function showSpinner(options) {
   wrapper.innerHTML = html;
   const overlay = wrapper.firstElementChild;
   if (!existing) {
-    savedOverflow = document.body.style.overflow;
+    getState().savedOverflow = document.body.style.overflow;
   }
   document.body.style.overflow = "hidden";
   document.body.append(overlay);
@@ -79,6 +92,7 @@ export {
   SPINNER_ID,
   defaultSpinnerSvg,
   dismissSpinner,
+  sanitizeCssValue,
   getSpinnerHtml,
   showSpinner
 };

package/dist/{chunk-X6E7KUDK.js → chunk-PE5QPP5Y.js}

@@ -13,8 +13,13 @@ var initializedKey = /* @__PURE__ */ Symbol.for(`${name}:initialized`);
 var loggerWindowKey = /* @__PURE__ */ Symbol.for(`${name}:logger`);
 var RETRY_ID_PARAM = "spaGuardRetryId";
 var RETRY_ATTEMPT_PARAM = "spaGuardRetryAttempt";
+var CACHE_BUST_PARAM = "spaGuardCacheBust";
 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 staticAssetRecoveryKey = /* @__PURE__ */ Symbol.for(`${name}:static-asset-recovery`);
 var debugSyncErrorEventType = "spa-guard:debug-sync-error";
+var spinnerStateWindowKey = /* @__PURE__ */ Symbol.for(`${name}:spinner-state`);
 
 // src/common/events/internal.ts
 if (globalThis.window && !globalThis.window[eventSubscribersWindowKey]) {
@@ -163,6 +168,10 @@ var defaultOptions = {
     },
     loading: {
       content: defaultLoadingFallbackHtml
+    },
+    spinner: {
+      background: "#fff",
+      disabled: false
     }
   },
   lazyRetry: {
@@ -171,9 +180,9 @@ var defaultOptions = {
   },
   minTimeBetweenResets: 5e3,
   reloadDelays: [1e3, 2e3, 5e3],
-  spinner: {
-    background: "#fff",
-    disabled: false
+  staticAssets: {
+    autoRecover: true,
+    recoveryDelay: 500
   },
   useRetryId: true
 };
@@ -202,6 +211,10 @@ var getOptions = () => {
       loading: {
         ...defaultOptions.html?.loading,
         ...windowOptions?.html?.loading
+      },
+      spinner: {
+        ...defaultOptions.html?.spinner,
+        ...windowOptions?.html?.spinner
       }
     },
     lazyRetry: {
@@ -212,9 +225,9 @@ var getOptions = () => {
       ...defaultOptions.reportBeacon,
       ...windowOptions?.reportBeacon
     },
-    spinner: {
-      ...defaultOptions.spinner,
-      ...windowOptions?.spinner
+    staticAssets: {
+      ...defaultOptions.staticAssets,
+      ...windowOptions?.staticAssets
     }
   };
 };
@@ -231,8 +244,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 +274,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 +288,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 +304,7 @@ var clearLastReloadTime = () => {
     } catch {
     }
   }
-  inMemoryStorage = null;
+  getInMemoryState().storage = null;
 };
 var shouldResetRetryCycle = (retryState, reloadDelays, minTimeBetweenResets = 5e3) => {
   if (retryState.retryAttempt === 0) {
@@ -311,10 +339,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 +353,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
@@ -339,7 +371,7 @@ var getRetryStateFromUrl = () => {
     const retryAttempt = params.get(RETRY_ATTEMPT_PARAM);
     if (retryId && retryAttempt) {
       const parsed = parseInt(retryAttempt, 10);
-      if (Number.isNaN(parsed)) {
+      if (Number.isNaN(parsed) || parsed < -1) {
         return null;
       }
       return {
@@ -357,6 +389,7 @@ var clearRetryStateFromUrl = () => {
     const url = new URL(globalThis.window.location.href);
     url.searchParams.delete(RETRY_ID_PARAM);
     url.searchParams.delete(RETRY_ATTEMPT_PARAM);
+    url.searchParams.delete(CACHE_BUST_PARAM);
     globalThis.window.history.replaceState(null, "", url.toString());
   } catch {
   }
@@ -387,7 +420,7 @@ var getRetryAttemptFromUrl = () => {
     const retryAttempt = params.get(RETRY_ATTEMPT_PARAM);
     if (retryAttempt) {
       const parsed = parseInt(retryAttempt, 10);
-      if (Number.isNaN(parsed)) {
+      if (Number.isNaN(parsed) || parsed < -1) {
         return null;
       }
       return parsed;
@@ -420,8 +453,12 @@ export {
   optionsWindowKey,
   RETRY_ID_PARAM,
   RETRY_ATTEMPT_PARAM,
+  CACHE_BUST_PARAM,
   versionCheckStateWindowKey,
+  reloadScheduledKey,
+  staticAssetRecoveryKey,
   debugSyncErrorEventType,
+  spinnerStateWindowKey,
   setLogger,
   getLogger,
   emitEvent,

package/dist/common/constants.d.ts

@@ -5,5 +5,10 @@ export declare const initializedKey: unique symbol;
 export declare const loggerWindowKey: unique symbol;
 export declare const RETRY_ID_PARAM = "spaGuardRetryId";
 export declare const RETRY_ATTEMPT_PARAM = "spaGuardRetryAttempt";
+export declare const CACHE_BUST_PARAM = "spaGuardCacheBust";
 export declare const versionCheckStateWindowKey: unique symbol;
+export declare const reloadScheduledKey: unique symbol;
+export declare const inMemoryLastReloadKey: unique symbol;
+export declare const staticAssetRecoveryKey: unique symbol;
 export declare const debugSyncErrorEventType = "spa-guard:debug-sync-error";
+export declare const spinnerStateWindowKey: unique symbol;

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-5ANASVKX.js";
+import "../chunk-4EXCHJBE.js";
 import {
   ForceRetryError,
   disableDefaultRetry,
@@ -12,7 +12,7 @@ import {
   isDefaultRetryEnabled,
   options_exports,
   subscribe
-} from "../chunk-X6E7KUDK.js";
+} from "../chunk-PE5QPP5Y.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: (url?: string, 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/spinner.d.ts

@@ -1,6 +1,7 @@
 export declare const SPINNER_ID = "__spa-guard-spinner";
 export declare const defaultSpinnerSvg = "<svg width=\"40\" height=\"40\" viewBox=\"0 0 40 40\" style=\"animation:spa-guard-spin .8s linear infinite\"><circle cx=\"20\" cy=\"20\" r=\"16\" fill=\"none\" stroke=\"#e8e8e8\" stroke-width=\"3\"/><circle cx=\"20\" cy=\"20\" r=\"16\" fill=\"none\" stroke=\"#666\" stroke-width=\"3\" stroke-dasharray=\"80\" stroke-dashoffset=\"60\" stroke-linecap=\"round\"/></svg><style>@keyframes spa-guard-spin{to{transform:rotate(360deg)}}</style>";
 export declare function dismissSpinner(): void;
+export declare const sanitizeCssValue: (value: string) => string;
 export declare function getSpinnerHtml(backgroundOverride?: string): string;
 export declare function showSpinner(options?: {
     background?: string;

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/errorDispatchers.d.ts

@@ -41,6 +41,13 @@ export declare function dispatchNetworkTimeout(delayMs?: number): void;
  * the fallback UI into the DOM.
  */
 export declare function dispatchRetryExhausted(): void;
+/**
+ * Simulates a static asset 404 by appending a <script> element with a
+ * nonexistent hashed URL to document.head. The browser fires an "error"
+ * event on the element, which spa-guard's listenInternal() detects via
+ * the Resource Timing API-based isLikely404 check.
+ */
+export declare function dispatchStaticAsset404(): void;
 /**
  * Dispatches a sync runtime error via CustomEvent.
  * DebugSyncErrorTrigger (a React component) listens for this event,

package/dist/runtime/debug/index.js

@@ -5,16 +5,17 @@ import {
   dispatchForceRetryError,
   dispatchNetworkTimeout,
   dispatchRetryExhausted,
+  dispatchStaticAsset404,
   dispatchSyncRuntimeError,
   dispatchUnhandledRejection
-} from "../../chunk-XFILAQ7P.js";
-import "../../chunk-CSN7MQGX.js";
+} from "../../chunk-62AC5565.js";
+import "../../chunk-4EXCHJBE.js";
 import {
   subscribeToState
-} from "../../chunk-T72DERME.js";
+} from "../../chunk-B7C3LV2W.js";
 import {
   subscribe
-} from "../../chunk-X6E7KUDK.js";
+} from "../../chunk-PE5QPP5Y.js";
 import "../../chunk-MLKGABMK.js";
 
 // src/runtime/debug/index.ts
@@ -30,7 +31,8 @@ var SCENARIOS = [
     key: "unhandled-rejection",
     label: "Unhandled Rejection"
   },
-  { dispatch: dispatchRetryExhausted, key: "exhaust-retries", label: "Exhaust Retries" }
+  { dispatch: dispatchRetryExhausted, key: "exhaust-retries", label: "Exhaust Retries" },
+  { dispatch: dispatchStaticAsset404, key: "static-asset-404", label: "Static Asset 404" }
 ];
 var POSITION_MAP = {
   "bottom-left": "bottom:16px;left:16px;",

package/dist/runtime/index.js

@@ -3,18 +3,18 @@ import {
   extractVersionFromHtml,
   getSpinnerHtml,
   showSpinner
-} from "../chunk-Z75UPJWV.js";
+} from "../chunk-BA5VUNSU.js";
 import {
   getState,
   subscribeToState
-} from "../chunk-T72DERME.js";
+} from "../chunk-B7C3LV2W.js";
 import {
   ForceRetryError,
   getLogger,
   getOptions,
   setTranslations,
   versionCheckStateWindowKey
-} from "../chunk-X6E7KUDK.js";
+} from "../chunk-PE5QPP5Y.js";
 import "../chunk-MLKGABMK.js";
 
 // src/common/checkVersion.ts
@@ -38,45 +38,60 @@ var getState2 = () => {
   }
   return globalThis.window[versionCheckStateWindowKey] ?? (globalThis.window[versionCheckStateWindowKey] = createInitialState());
 };
+var FETCH_TIMEOUT_MS = 3e4;
 var fetchJsonVersion = async () => {
   const endpoint = getOptions().checkVersion?.endpoint;
   if (!endpoint) {
     getLogger()?.versionCheckRequiresEndpoint();
     return null;
   }
-  const response = await fetch(endpoint, {
-    cache: getOptions().checkVersion?.cache ?? "no-store",
-    headers: { Accept: "application/json" }
-  });
-  if (!response.ok) {
-    getLogger()?.versionCheckHttpError(response.status);
-    return null;
-  }
-  const data = await response.json();
-  if (typeof data !== "object" || data === null) {
-    return null;
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  try {
+    const response = await fetch(endpoint, {
+      cache: getOptions().checkVersion?.cache ?? "no-store",
+      headers: { Accept: "application/json" },
+      signal: controller.signal
+    });
+    if (!response.ok) {
+      getLogger()?.versionCheckHttpError(response.status);
+      return null;
+    }
+    const data = await response.json();
+    if (typeof data !== "object" || data === null) {
+      return null;
+    }
+    return "version" in data && typeof data.version === "string" ? data.version : null;
+  } finally {
+    clearTimeout(timeoutId);
   }
-  return "version" in data && typeof data.version === "string" ? data.version : null;
 };
 var fetchHtmlVersion = async () => {
   const url = new URL(globalThis.location.href);
   url.search = "";
   url.hash = "";
-  const response = await fetch(url.toString(), {
-    cache: getOptions().checkVersion?.cache ?? "no-store",
-    headers: { Accept: "text/html" }
-  });
-  if (!response.ok) {
-    getLogger()?.versionCheckHttpError(response.status);
-    return null;
-  }
-  const html = await response.text();
-  const version = extractVersionFromHtml(html);
-  if (!version) {
-    getLogger()?.versionCheckParseError();
-    return null;
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  try {
+    const response = await fetch(url.toString(), {
+      cache: getOptions().checkVersion?.cache ?? "no-store",
+      headers: { Accept: "text/html" },
+      signal: controller.signal
+    });
+    if (!response.ok) {
+      getLogger()?.versionCheckHttpError(response.status);
+      return null;
+    }
+    const html = await response.text();
+    const version = extractVersionFromHtml(html);
+    if (!version) {
+      getLogger()?.versionCheckParseError();
+      return null;
+    }
+    return version;
+  } finally {
+    clearTimeout(timeoutId);
   }
-  return version;
 };
 var fetchRemoteVersion = async (mode) => {
   return mode === "json" ? fetchJsonVersion() : fetchHtmlVersion();
@@ -143,6 +158,9 @@ var handleVisibilityHidden = () => {
   getLogger()?.versionCheckPaused();
 };
 var handleResume = (mode, interval) => {
+  if (document.visibilityState !== "visible" || !document.hasFocus()) {
+    return;
+  }
   const s = getState2();
   if (s.versionCheckInterval !== null || s.versionCheckTimeout !== null) {
     return;
@@ -243,7 +261,9 @@ var recommendedSetup = (overrides) => {
     startVersionCheck();
   }
   return () => {
-    stopVersionCheck();
+    if (options.versionCheck) {
+      stopVersionCheck();
+    }
   };
 };
 export {

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/dist/schema/parse.js

@@ -3,11 +3,14 @@ import "../chunk-MLKGABMK.js";
 // src/schema/parse.ts
 var STRING_FIELDS = [
   "appName",
+  "errorContext",
   "errorMessage",
+  "errorType",
   "eventMessage",
   "eventName",
   "retryId",
-  "serialized"
+  "serialized",
+  "url"
 ];
 function parseBeacon(data) {
   if (!data || typeof data !== "object" || Array.isArray(data)) {
@@ -23,11 +26,13 @@ function parseBeacon(data) {
       result[field] = d[field];
     }
   }
-  if ("retryAttempt" in d) {
-    if (typeof d.retryAttempt !== "number") {
-      throw new TypeError("Beacon validation failed: retryAttempt must be a number");
+  for (const field of ["retryAttempt", "httpStatus"]) {
+    if (field in d) {
+      if (typeof d[field] !== "number") {
+        throw new TypeError(`Beacon validation failed: ${field} must be a number`);
+      }
+      result[field] = d[field];
     }
-    result.retryAttempt = d.retryAttempt;
   }
   return result;
 }

package/package.json

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