@ovineko/spa-guard 0.0.1-alpha-28 → 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.js

@@ -3,13 +3,13 @@ import {
   isChunkError,
   listenInternal,
   serializeError
-} from "./chunk-5ANASVKX.js";
+} from "./chunk-CBAJOLBG.js";
 import {
   SPINNER_ID,
   defaultSpinnerSvg,
   extractVersionFromHtml,
   sanitizeCssValue
-} from "./chunk-BA5VUNSU.js";
+} from "./chunk-5546JVQV.js";
 import {
   dispatchAsyncRuntimeError,
   dispatchChunkLoadError,
@@ -18,13 +18,13 @@ import {
   dispatchNetworkTimeout,
   dispatchSyncRuntimeError,
   dispatchUnhandledRejection
-} from "./chunk-62AC5565.js";
+} from "./chunk-3LAQJKWC.js";
 import {
   attemptReload,
   sendBeacon,
   shouldForceRetry,
   shouldIgnoreMessages
-} from "./chunk-4EXCHJBE.js";
+} from "./chunk-2BUEJXDB.js";
 import {
   applyI18n,
   debugSyncErrorEventType,
@@ -39,7 +39,7 @@ import {
   isDefaultRetryEnabled,
   optionsWindowKey,
   subscribe
-} from "./chunk-PE5QPP5Y.js";
+} from "./chunk-LBHLKYQS.js";
 import "./chunk-MLKGABMK.js";
 
 // src/common/handleErrorWithSpaGuard.ts

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

@@ -8,6 +8,7 @@ import {
   clearRetryAttemptFromUrl,
   clearRetryStateFromUrl,
   emitEvent,
+  fallbackModeKey,
   generateRetryId,
   getI18n,
   getLastReloadTime,
@@ -20,7 +21,27 @@ import {
   setLastReloadTime,
   setLastRetryResetInfo,
   shouldResetRetryCycle
-} from "./chunk-PE5QPP5Y.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) => {
@@ -93,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);
@@ -253,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";
@@ -300,6 +329,8 @@ var showFallbackUI = () => {
 };
 
 export {
+  isInFallbackMode,
+  resetFallbackMode,
   shouldIgnoreMessages,
   shouldForceRetry,
   sendBeacon,

package/dist/{chunk-62AC5565.js → chunk-3LAQJKWC.js}

@@ -1,12 +1,12 @@
 import {
   showFallbackUI
-} from "./chunk-4EXCHJBE.js";
+} from "./chunk-2BUEJXDB.js";
 import {
   ForceRetryError,
   debugSyncErrorEventType,
   emitEvent,
   getOptions
-} from "./chunk-PE5QPP5Y.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",
@@ -45,9 +45,12 @@ function dispatchRetryExhausted() {
   showFallbackUI();
 }
 function dispatchStaticAsset404() {
-  const hash = crypto.randomUUID().replaceAll("-", "").slice(0, 8);
+  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() {

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

@@ -2,7 +2,7 @@ import {
   defaultSpinnerHtml,
   getOptions,
   spinnerStateWindowKey
-} from "./chunk-PE5QPP5Y.js";
+} from "./chunk-LBHLKYQS.js";
 
 // src/common/parseVersion.ts
 function extractVersionFromHtml(html) {

package/dist/{chunk-5ANASVKX.js → chunk-CBAJOLBG.js}

@@ -1,9 +1,10 @@
 import {
   attemptReload,
+  isInFallbackMode,
   sendBeacon,
   shouldForceRetry,
   shouldIgnoreMessages
-} from "./chunk-4EXCHJBE.js";
+} from "./chunk-2BUEJXDB.js";
 import {
   clearRetryStateFromUrl,
   emitEvent,
@@ -16,7 +17,7 @@ import {
   setLogger,
   staticAssetRecoveryKey,
   updateRetryStateInUrl
-} from "./chunk-PE5QPP5Y.js";
+} from "./chunk-LBHLKYQS.js";
 
 // src/common/isChunkError.ts
 var isChunkError = (error) => {
@@ -182,6 +183,9 @@ var isStaticAssetError = (event) => {
   return false;
 };
 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;
@@ -195,11 +199,12 @@ var checkResourceStatus = (url) => {
   }
   return false;
 };
-var isLikely404 = (url, timeSinceNavMs = typeof performance === "undefined" ? 0 : performance.now()) => {
+var isLikely404 = (url, timeSinceNavMs) => {
   if (url !== void 0) {
     return checkResourceStatus(url);
   }
-  return timeSinceNavMs > 3e4;
+  const elapsed = timeSinceNavMs ?? (typeof performance === "undefined" ? 0 : performance.now());
+  return elapsed > 3e4;
 };
 var getAssetUrl = (event) => {
   const target = event.target;
@@ -226,6 +231,12 @@ var getState = () => {
   return globalThis.window[staticAssetRecoveryKey];
 };
 var handleStaticAssetFailure = (url) => {
+  if (globalThis.window === void 0) {
+    return;
+  }
+  if (isInFallbackMode()) {
+    return;
+  }
   const state = getState();
   state.failedAssets.add(url);
   if (state.recoveryTimer !== null) {
@@ -235,9 +246,12 @@ var handleStaticAssetFailure = (url) => {
   const delay = options.staticAssets?.recoveryDelay ?? 500;
   state.recoveryTimer = setTimeout(() => {
     const s = getState();
+    s.recoveryTimer = null;
     const assets = [...s.failedAssets];
     s.failedAssets = /* @__PURE__ */ new Set();
-    s.recoveryTimer = null;
+    if (isInFallbackMode()) {
+      return;
+    }
     const error = new Error(`Static asset load failed: ${assets.join(", ")}`);
     attemptReload(error, { cacheBust: true });
   }, delay);
@@ -260,16 +274,17 @@ var listenInternal = (serializeError2, logger) => {
     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 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(

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

@@ -20,6 +20,7 @@ var inMemoryLastReloadKey = /* @__PURE__ */ Symbol.for(`${name}:in-memory-last-r
 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]) {
@@ -459,6 +460,7 @@ export {
   staticAssetRecoveryKey,
   debugSyncErrorEventType,
   spinnerStateWindowKey,
+  fallbackModeKey,
   setLogger,
   getLogger,
   emitEvent,

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

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

package/dist/common/constants.d.ts

@@ -12,3 +12,4 @@ 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-5ANASVKX.js";
-import "../chunk-4EXCHJBE.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-PE5QPP5Y.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/runtime/debug/index.js

@@ -8,14 +8,14 @@ import {
   dispatchStaticAsset404,
   dispatchSyncRuntimeError,
   dispatchUnhandledRejection
-} from "../../chunk-62AC5565.js";
-import "../../chunk-4EXCHJBE.js";
+} from "../../chunk-3LAQJKWC.js";
+import "../../chunk-2BUEJXDB.js";
 import {
   subscribeToState
-} from "../../chunk-B7C3LV2W.js";
+} from "../../chunk-W3TOHCEW.js";
 import {
   subscribe
-} from "../../chunk-PE5QPP5Y.js";
+} from "../../chunk-LBHLKYQS.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-BA5VUNSU.js";
+} from "../chunk-5546JVQV.js";
 import {
   getState,
   subscribeToState
-} from "../chunk-B7C3LV2W.js";
+} from "../chunk-W3TOHCEW.js";
 import {
   ForceRetryError,
   getLogger,
   getOptions,
   setTranslations,
   versionCheckStateWindowKey
-} from "../chunk-PE5QPP5Y.js";
+} from "../chunk-LBHLKYQS.js";
 import "../chunk-MLKGABMK.js";
 
 // src/common/checkVersion.ts

package/dist/schema/parse.js

@@ -12,6 +12,8 @@ var STRING_FIELDS = [
   "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");
@@ -23,13 +25,17 @@ 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];
     }
   }
   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`);
+      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];
     }

package/package.json

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