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

package/README.md

@@ -36,6 +36,8 @@ const cleanup = recommendedSetup({ versionCheck: false });
 - `events` — event type constants
 - `options` — runtime options helpers
 - `disableDefaultRetry` / `enableDefaultRetry` / `isDefaultRetryEnabled` — control default retry behaviour
+- `isInFallbackMode` — returns `true` when fallback UI is active (retries exhausted)
+- `resetFallbackMode` — clears the fallback flag; use in tests or programmatic recovery flows
 - `BeaconError` — error class for beacon failures
 - `ForceRetryError` — error class to force a retry
 
@@ -60,7 +62,19 @@ Built-in translation strings.
 
 ### `@ovineko/spa-guard/runtime/debug`
 
-Debug helpers for testing error scenarios.
+Debug helpers for testing error scenarios. Use `createDebugger()` to mount an in-page panel with buttons for each scenario.
+
+Available error scenarios:
+
+- `dispatchChunkLoadError` — unhandled ChunkLoadError rejection
+- `dispatchNetworkTimeout` — unhandled network timeout after a delay
+- `dispatchSyncRuntimeError` — sync error thrown during React render
+- `dispatchAsyncRuntimeError` — uncaught error via setTimeout
+- `dispatchFinallyError` — unhandled rejection from Promise.finally
+- `dispatchForceRetryError` — ForceRetryError to exercise the force-retry path
+- `dispatchUnhandledRejection` — generic unhandled promise rejection
+- `dispatchRetryExhausted` — simulates retry-exhausted state and renders fallback UI
+- `dispatchStaticAsset404` — appends a hashed `<script>` that 404s, exercising the Resource Timing API-based static asset detection path
 
 ## Related packages
 

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-FRCJOMRP.js";
+} from "./chunk-CBAJOLBG.js";
 import {
   SPINNER_ID,
   defaultSpinnerSvg,
-  extractVersionFromHtml
-} from "./chunk-7PDOUY6W.js";
+  extractVersionFromHtml,
+  sanitizeCssValue
+} from "./chunk-5546JVQV.js";
 import {
   dispatchAsyncRuntimeError,
   dispatchChunkLoadError,
@@ -17,13 +18,13 @@ import {
   dispatchNetworkTimeout,
   dispatchSyncRuntimeError,
   dispatchUnhandledRejection
-} from "./chunk-7KNE2UWX.js";
+} from "./chunk-3LAQJKWC.js";
 import {
   attemptReload,
   sendBeacon,
   shouldForceRetry,
   shouldIgnoreMessages
-} from "./chunk-KAH6PVTJ.js";
+} from "./chunk-2BUEJXDB.js";
 import {
   applyI18n,
   debugSyncErrorEventType,
@@ -38,7 +39,7 @@ import {
   isDefaultRetryEnabled,
   optionsWindowKey,
   subscribe
-} from "./chunk-67WBMNUS.js";
+} from "./chunk-LBHLKYQS.js";
 import "./chunk-MLKGABMK.js";
 
 // src/common/handleErrorWithSpaGuard.ts
@@ -96,7 +97,9 @@ var retryImport = async (importFn, delays, 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 });
+  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");
@@ -160,6 +163,7 @@ export {
   logMessage,
   optionsWindowKey,
   retryImport,
+  sanitizeCssValue,
   serializeError,
   subscribe
 };

package/dist/{chunk-KAH6PVTJ.js → chunk-2BUEJXDB.js}

@@ -1,4 +1,5 @@
 import {
+  CACHE_BUST_PARAM,
   FORCE_RETRY_MAGIC,
   RETRY_ATTEMPT_PARAM,
   RETRY_ID_PARAM,
@@ -7,6 +8,7 @@ import {
   clearRetryAttemptFromUrl,
   clearRetryStateFromUrl,
   emitEvent,
+  fallbackModeKey,
   generateRetryId,
   getI18n,
   getLastReloadTime,
@@ -19,7 +21,27 @@ import {
   setLastReloadTime,
   setLastRetryResetInfo,
   shouldResetRetryCycle
-} from "./chunk-67WBMNUS.js";
+} from "./chunk-LBHLKYQS.js";
+
+// src/common/fallbackState.ts
+var isInFallbackMode = () => {
+  if (globalThis.window === void 0) {
+    return false;
+  }
+  return globalThis.window[fallbackModeKey] === true;
+};
+var setFallbackMode = () => {
+  if (globalThis.window === void 0) {
+    return;
+  }
+  globalThis.window[fallbackModeKey] = true;
+};
+var resetFallbackMode = () => {
+  if (globalThis.window === void 0) {
+    return;
+  }
+  globalThis.window[fallbackModeKey] = false;
+};
 
 // src/common/shouldIgnore.ts
 var shouldIgnoreMessages = (messages) => {
@@ -92,6 +114,10 @@ var getReloadState = () => {
   return globalThis.window[reloadScheduledKey] ?? (globalThis.window[reloadScheduledKey] = { scheduled: false });
 };
 var attemptReload = (error, opts) => {
+  if (isInFallbackMode()) {
+    getLogger()?.fallbackAlreadyShown(error);
+    return;
+  }
   const reloadState = getReloadState();
   if (reloadState.scheduled) {
     getLogger()?.reloadAlreadyScheduled(error);
@@ -202,7 +228,7 @@ var attemptReload = (error, opts) => {
       reloadUrl = useRetryId ? buildReloadUrl(retryId, nextAttempt) : buildReloadUrlAttemptOnly(nextAttempt);
       if (opts?.cacheBust) {
         const url = new URL(reloadUrl);
-        url.searchParams.set("spaGuardCacheBust", String(Date.now()));
+        url.searchParams.set(CACHE_BUST_PARAM, String(Date.now()));
         reloadUrl = url.toString();
       }
       globalThis.window.location.href = reloadUrl;
@@ -252,6 +278,10 @@ var showLoadingUI = (attempt) => {
   }
 };
 var showFallbackUI = () => {
+  if (isInFallbackMode()) {
+    return;
+  }
+  setFallbackMode();
   const options = getOptions();
   const fallbackHtml = options.html?.fallback?.content;
   const selector = options.html?.fallback?.selector ?? "body";
@@ -299,6 +329,8 @@ var showFallbackUI = () => {
 };
 
 export {
+  isInFallbackMode,
+  resetFallbackMode,
   shouldIgnoreMessages,
   shouldForceRetry,
   sendBeacon,

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

@@ -1,12 +1,12 @@
 import {
   showFallbackUI
-} from "./chunk-KAH6PVTJ.js";
+} from "./chunk-2BUEJXDB.js";
 import {
   ForceRetryError,
   debugSyncErrorEventType,
   emitEvent,
   getOptions
-} from "./chunk-67WBMNUS.js";
+} from "./chunk-LBHLKYQS.js";
 
 // src/runtime/debug/errorDispatchers.ts
 function dispatchAsyncRuntimeError() {
@@ -36,7 +36,7 @@ function dispatchNetworkTimeout(delayMs = 3e3) {
 }
 function dispatchRetryExhausted() {
   const options = getOptions();
-  const reloadDelays = options.reloadDelays ?? [1e3, 2e3, 5e3];
+  const reloadDelays = options.reloadDelays ?? [];
   emitEvent({
     finalAttempt: reloadDelays.length,
     name: "retry-exhausted",
@@ -44,6 +44,15 @@ function dispatchRetryExhausted() {
   });
   showFallbackUI();
 }
+function dispatchStaticAsset404() {
+  const hash = crypto.randomUUID().slice(0, 8);
+  const script = document.createElement("script");
+  script.src = `/assets/index-${hash}.js`;
+  script.addEventListener("error", () => {
+    script.remove();
+  });
+  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 +70,7 @@ export {
   dispatchForceRetryError,
   dispatchNetworkTimeout,
   dispatchRetryExhausted,
+  dispatchStaticAsset404,
   dispatchSyncRuntimeError,
   dispatchUnhandledRejection
 };

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

@@ -1,7 +1,8 @@
 import {
   defaultSpinnerHtml,
-  getOptions
-} from "./chunk-67WBMNUS.js";
+  getOptions,
+  spinnerStateWindowKey
+} from "./chunk-LBHLKYQS.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.html?.spinner?.disabled) {
     return "";
   }
   const spinnerContent = opts.html?.spinner?.content ?? defaultSpinnerSvg;
-  const bg = backgroundOverride ?? opts.html?.spinner?.background ?? "#fff";
+  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) {
@@ -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-FRCJOMRP.js → chunk-CBAJOLBG.js}

@@ -1,10 +1,12 @@
 import {
   attemptReload,
+  isInFallbackMode,
   sendBeacon,
   shouldForceRetry,
   shouldIgnoreMessages
-} from "./chunk-KAH6PVTJ.js";
+} from "./chunk-2BUEJXDB.js";
 import {
+  clearRetryStateFromUrl,
   emitEvent,
   getLogger,
   getOptions,
@@ -13,8 +15,9 @@ import {
   isInitialized,
   markInitialized,
   setLogger,
+  staticAssetRecoveryKey,
   updateRetryStateInUrl
-} from "./chunk-67WBMNUS.js";
+} from "./chunk-LBHLKYQS.js";
 
 // src/common/isChunkError.ts
 var isChunkError = (error) => {
@@ -179,8 +182,29 @@ var isStaticAssetError = (event) => {
   }
   return false;
 };
-var isLikely404 = (timeSinceNavMs = typeof performance === "undefined" ? 0 : performance.now()) => {
-  return timeSinceNavMs > 3e4;
+var checkResourceStatus = (url) => {
+  if (typeof performance === "undefined" || typeof performance.getEntriesByName !== "function") {
+    return true;
+  }
+  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) => {
+  if (url !== void 0) {
+    return checkResourceStatus(url);
+  }
+  const elapsed = timeSinceNavMs ?? (typeof performance === "undefined" ? 0 : performance.now());
+  return elapsed > 3e4;
 };
 var getAssetUrl = (event) => {
   const target = event.target;
@@ -194,19 +218,40 @@ var getAssetUrl = (event) => {
 };
 
 // src/common/staticAssetRecovery.ts
-var recoveryTimer = null;
-var failedAssets = /* @__PURE__ */ new Set();
+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) => {
-  failedAssets.add(url);
-  if (recoveryTimer !== null) {
+  if (globalThis.window === void 0) {
+    return;
+  }
+  if (isInFallbackMode()) {
+    return;
+  }
+  const state = getState();
+  state.failedAssets.add(url);
+  if (state.recoveryTimer !== null) {
     return;
   }
   const options = getOptions();
   const delay = options.staticAssets?.recoveryDelay ?? 500;
-  recoveryTimer = setTimeout(() => {
-    const assets = [...failedAssets];
-    failedAssets = /* @__PURE__ */ new Set();
-    recoveryTimer = null;
+  state.recoveryTimer = setTimeout(() => {
+    const s = getState();
+    s.recoveryTimer = null;
+    const assets = [...s.failedAssets];
+    s.failedAssets = /* @__PURE__ */ new Set();
+    if (isInFallbackMode()) {
+      return;
+    }
     const error = new Error(`Static asset load failed: ${assets.join(", ")}`);
     attemptReload(error, { cacheBust: true });
   }, delay);
@@ -214,12 +259,12 @@ var handleStaticAssetFailure = (url) => {
 
 // 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 ?? [];
@@ -228,10 +273,35 @@ var listenInternal = (serializeError2, logger) => {
     getLogger()?.retryLimitExceeded(retryState.retryAttempt, reloadDelays.length);
     updateRetryStateInUrl(retryState.retryId, -1);
   }
+  if (retryState && (retryState.retryAttempt >= reloadDelays.length || retryState.retryAttempt === -1)) {
+    const cleanupSentinel = () => {
+      const current = getRetryStateFromUrl();
+      if (current?.retryAttempt === -1) {
+        clearRetryStateFromUrl();
+      }
+    };
+    if (globalThis.window.document?.readyState === "complete") {
+      cleanupSentinel();
+    } else {
+      globalThis.window.addEventListener("load", cleanupSentinel, { 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;
       }
@@ -246,15 +316,6 @@ 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,

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

@@ -13,10 +13,14 @@ 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`);
+var fallbackModeKey = /* @__PURE__ */ Symbol.for(`${name}:fallback-mode`);
 
 // src/common/events/internal.ts
 if (globalThis.window && !globalThis.window[eventSubscribersWindowKey]) {
@@ -368,7 +372,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 {
@@ -386,6 +390,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 {
   }
@@ -416,7 +421,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;
@@ -449,9 +454,13 @@ export {
   optionsWindowKey,
   RETRY_ID_PARAM,
   RETRY_ATTEMPT_PARAM,
+  CACHE_BUST_PARAM,
   versionCheckStateWindowKey,
   reloadScheduledKey,
+  staticAssetRecoveryKey,
   debugSyncErrorEventType,
+  spinnerStateWindowKey,
+  fallbackModeKey,
   setLogger,
   getLogger,
   emitEvent,

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

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

package/dist/common/constants.d.ts

@@ -5,7 +5,11 @@ 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;
+export declare const fallbackModeKey: unique symbol;

package/dist/common/fallbackState.d.ts

@@ -0,0 +1,3 @@
+export declare const isInFallbackMode: () => boolean;
+export declare const setFallbackMode: () => void;
+export declare const resetFallbackMode: () => void;

package/dist/common/index.d.ts

@@ -2,5 +2,6 @@ export { BeaconError } from "./errors/BeaconError";
 export { ForceRetryError } from "./errors/ForceRetryError";
 export * as events from "./events";
 export { disableDefaultRetry, enableDefaultRetry, isDefaultRetryEnabled } from "./events/internal";
+export { isInFallbackMode, resetFallbackMode } from "./fallbackState";
 export { listen } from "./listen";
 export * as options from "./options";

package/dist/common/index.js

@@ -2,8 +2,11 @@ import {
   createLogger,
   listenInternal,
   serializeError
-} from "../chunk-FRCJOMRP.js";
-import "../chunk-KAH6PVTJ.js";
+} from "../chunk-CBAJOLBG.js";
+import {
+  isInFallbackMode,
+  resetFallbackMode
+} from "../chunk-2BUEJXDB.js";
 import {
   ForceRetryError,
   disableDefaultRetry,
@@ -12,7 +15,7 @@ import {
   isDefaultRetryEnabled,
   options_exports,
   subscribe
-} from "../chunk-67WBMNUS.js";
+} from "../chunk-LBHLKYQS.js";
 import {
   __export
 } from "../chunk-MLKGABMK.js";
@@ -73,6 +76,8 @@ export {
   enableDefaultRetry,
   events_exports as events,
   isDefaultRetryEnabled,
+  isInFallbackMode,
   listen,
-  options_exports as options
+  options_exports as options,
+  resetFallbackMode
 };

package/dist/common/isStaticAssetError.d.ts

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

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/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-7KNE2UWX.js";
-import "../../chunk-KAH6PVTJ.js";
+} from "../../chunk-3LAQJKWC.js";
+import "../../chunk-2BUEJXDB.js";
 import {
   subscribeToState
-} from "../../chunk-V2OOMVZK.js";
+} from "../../chunk-W3TOHCEW.js";
 import {
   subscribe
-} from "../../chunk-67WBMNUS.js";
+} from "../../chunk-LBHLKYQS.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-7PDOUY6W.js";
+} from "../chunk-5546JVQV.js";
 import {
   getState,
   subscribeToState
-} from "../chunk-V2OOMVZK.js";
+} from "../chunk-W3TOHCEW.js";
 import {
   ForceRetryError,
   getLogger,
   getOptions,
   setTranslations,
   versionCheckStateWindowKey
-} from "../chunk-67WBMNUS.js";
+} from "../chunk-LBHLKYQS.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/parse.js

@@ -3,12 +3,17 @@ import "../chunk-MLKGABMK.js";
 // src/schema/parse.ts
 var STRING_FIELDS = [
   "appName",
+  "errorContext",
   "errorMessage",
+  "errorType",
   "eventMessage",
   "eventName",
   "retryId",
-  "serialized"
+  "serialized",
+  "url"
 ];
+var MAX_STRING_FIELD_LENGTH = 500;
+var MAX_SERIALIZED_LENGTH = 1e4;
 function parseBeacon(data) {
   if (!data || typeof data !== "object" || Array.isArray(data)) {
     throw new Error("Invalid beacon");
@@ -20,14 +25,20 @@ function parseBeacon(data) {
       if (typeof d[field] !== "string") {
         throw new TypeError(`Beacon validation failed: ${field} must be a string`);
       }
+      const maxLen = field === "serialized" ? MAX_SERIALIZED_LENGTH : MAX_STRING_FIELD_LENGTH;
+      if (d[field].length > maxLen) {
+        throw new TypeError(`Beacon validation failed: ${field} exceeds maximum length`);
+      }
       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" || !Number.isFinite(d[field])) {
+        throw new TypeError(`Beacon validation failed: ${field} must be a finite 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-27",
+  "version": "0.0.1-alpha-29",
   "description": "Chunk load error handling for SPAs — core runtime, error handling, schema, i18n",
   "keywords": [
     "spa",