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

package/README.md

@@ -28,6 +28,52 @@ Disable version checking:
 const cleanup = recommendedSetup({ versionCheck: false });
 ```
 
+## Retry behavior and event flow
+
+spa-guard uses a single retry orchestrator (`retryOrchestrator.ts`) as the sole owner of retry lifecycle. All reload scheduling, deduplication, and fallback transitions run through `triggerRetry()`.
+
+### Retry state machine
+
+The orchestrator maintains an explicit phase:
+
+- `idle` — no retry in progress
+- `scheduled` — a reload has been scheduled (timer running); concurrent triggers are deduplicated
+- `fallback` — retries exhausted, fallback UI is shown; further triggers are ignored
+
+### Retry progression
+
+When a recoverable error occurs (chunk load error, unhandled rejection, `vite:preloadError`, or static asset 404):
+
+1. Event listener classifies the event and calls `triggerRetry({ source, error })`.
+2. Orchestrator checks phase — if already `scheduled` or `fallback`, returns immediately without scheduling another reload.
+3. On first trigger: reads `RETRY_ATTEMPT_PARAM` from URL to restore attempt count after a reload.
+4. If attempts remain: increments attempt, sets a timer for `reloadDelays[currentAttempt]`, encodes `retryId` and attempt count into the reload URL, then navigates.
+5. If attempts are exhausted: transitions to `fallback`, calls `setFallbackMode()`, sends a beacon, and renders fallback UI.
+
+### URL params
+
+The orchestrator serializes state into URL params for cross-reload continuity:
+
+- `RETRY_ATTEMPT_PARAM` — current attempt count (strict non-negative integer; malformed values are ignored)
+- `RETRY_ID_PARAM` — unique ID for this retry session
+- `CACHE_BUST_PARAM` — timestamp for cache busting (set when `cacheBust: true` is passed, e.g. for static asset errors)
+
+### Retry reset
+
+If enough time has passed since the last reload (configurable via `minTimeBetweenResets`, default 5000 ms), the orchestrator resets the attempt counter and starts a fresh retry cycle instead of continuing to fallback. This prevents stale URL params from triggering fallback on a clean page load.
+
+### Healthy boot
+
+After a successful app boot following a retry reload, call `markRetryHealthyBoot()`. This clears retry URL params, cancels any pending timer, and resets orchestrator state.
+
+### Static asset burst coalescing
+
+Multiple 404'd asset errors within a short window (default 500 ms) are coalesced into a single `triggerRetry({ cacheBust: true, source: "static-asset-error" })`. The orchestrator's deduplication ensures only one reload is scheduled.
+
+### Retry ownership rule
+
+Only `retryOrchestrator.ts` may schedule reloads, advance retry state, or transition to fallback. Listeners, renderers, and other modules must not schedule their own retry timers or set fallback state directly.
+
 ## API
 
 ### `@ovineko/spa-guard` (common)
@@ -36,9 +82,22 @@ 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
 
+**Retry orchestrator (single owner of retry lifecycle):**
+
+- `triggerRetry(input?)` — trigger a retry from any source; returns `TriggerResult`:
+  - `{ status: "accepted" }` — reload scheduled
+  - `{ status: "deduped", reason: string }` — ignored because another retry is already scheduled or an internal error occurred
+  - `{ status: "fallback" }` — already in fallback mode; no retry scheduled
+  - `{ status: "retry-disabled" }` — retry is disabled via `disableDefaultRetry()`
+- `markRetryHealthyBoot()` — call after a successful boot following a retry reload; clears URL params, cancels timers, resets orchestrator state and fallback flag
+- `getRetrySnapshot()` — returns current orchestrator state: `{ phase, attempt, retryId, lastSource, lastTriggerTime }`
+- `resetRetryOrchestratorForTests()` — resets all orchestrator state including fallback flag; use in test teardown
+
 ### `@ovineko/spa-guard/runtime`
 
 - `recommendedSetup(options?)` — enable recommended runtime features; returns cleanup function
@@ -60,7 +119,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` — renders fallback UI directly (bypasses orchestrator; orchestrator phase remains `idle`)
+- `dispatchStaticAsset404` — appends a hashed `<script>` that 404s, exercising the Resource Timing API-based static asset detection path
 
 ## Related packages
 

package/dist/_internal.d.ts

@@ -12,8 +12,9 @@ export { createLogger } from "./common/logger";
 export { getOptions, optionsWindowKey } from "./common/options";
 export type { Options } from "./common/options";
 export { extractVersionFromHtml } from "./common/parseVersion";
-export { attemptReload } from "./common/reload";
 export { retryImport } from "./common/retryImport";
+export { getRetrySnapshot, markRetryHealthyBoot, resetRetryOrchestratorForTests, triggerRetry, } from "./common/retryOrchestrator";
+export type { RetryPhase, RetrySnapshot, TriggerInput, TriggerResult, } from "./common/retryOrchestrator";
 export { serializeError } from "./common/serializeError";
 export { defaultSpinnerSvg, sanitizeCssValue, SPINNER_ID } from "./common/spinner";
 export { dispatchAsyncRuntimeError, dispatchChunkLoadError, dispatchFinallyError, dispatchForceRetryError, dispatchNetworkTimeout, dispatchSyncRuntimeError, dispatchUnhandledRejection, } from "./runtime/debug/errorDispatchers";

package/dist/_internal.js

@@ -1,15 +1,15 @@
-import {
-  createLogger,
-  isChunkError,
-  listenInternal,
-  serializeError
-} from "./chunk-5ANASVKX.js";
 import {
   SPINNER_ID,
   defaultSpinnerSvg,
   extractVersionFromHtml,
   sanitizeCssValue
-} from "./chunk-BA5VUNSU.js";
+} from "./chunk-6TP2S7L6.js";
+import {
+  createLogger,
+  isChunkError,
+  listenInternal,
+  serializeError
+} from "./chunk-DINLBER6.js";
 import {
   dispatchAsyncRuntimeError,
   dispatchChunkLoadError,
@@ -18,13 +18,7 @@ import {
   dispatchNetworkTimeout,
   dispatchSyncRuntimeError,
   dispatchUnhandledRejection
-} from "./chunk-62AC5565.js";
-import {
-  attemptReload,
-  sendBeacon,
-  shouldForceRetry,
-  shouldIgnoreMessages
-} from "./chunk-4EXCHJBE.js";
+} from "./chunk-A5HF6LY6.js";
 import {
   applyI18n,
   debugSyncErrorEventType,
@@ -36,10 +30,17 @@ import {
   getI18n,
   getOptions,
   getRetryInfoForBeacon,
+  getRetrySnapshot,
   isDefaultRetryEnabled,
+  markRetryHealthyBoot,
   optionsWindowKey,
-  subscribe
-} from "./chunk-PE5QPP5Y.js";
+  resetRetryOrchestratorForTests,
+  sendBeacon,
+  shouldForceRetry,
+  shouldIgnoreMessages,
+  subscribe,
+  triggerRetry
+} from "./chunk-XRBUBTPZ.js";
 import "./chunk-MLKGABMK.js";
 
 // src/common/handleErrorWithSpaGuard.ts
@@ -62,7 +63,7 @@ var handleErrorWithSpaGuard = (error, options) => {
   const isChunk = isChunkError(error);
   const isForceRetry = shouldForceRetry([errorMessage]);
   if ((isChunk || isForceRetry) && autoRetryChunkErrors) {
-    attemptReload(error);
+    triggerRetry({ error, source: "error-boundary" });
   } else if (sendBeaconOnError) {
     sendBeacon({
       errorMessage: error instanceof Error ? error.message : String(error),
@@ -130,14 +131,13 @@ var retryImport = async (importFn, delays, options) => {
   const willReload = callReloadOnFailure === true && isChunkError(lastError) && isDefaultRetryEnabled();
   emitEvent({ error: lastError, name: "lazy-retry-exhausted", totalAttempts, willReload });
   if (willReload) {
-    attemptReload(lastError);
+    triggerRetry({ error: lastError, source: "lazy-import-failure" });
   }
   throw lastError;
 };
 export {
   SPINNER_ID,
   applyI18n,
-  attemptReload,
   createLogger,
   debugSyncErrorEventType,
   defaultErrorFallbackHtml,
@@ -156,14 +156,18 @@ export {
   extractVersionFromHtml,
   getI18n,
   getOptions,
+  getRetrySnapshot,
   handleErrorWithSpaGuard,
   isChunkError,
   isDefaultRetryEnabled,
   listenInternal,
   logMessage,
+  markRetryHealthyBoot,
   optionsWindowKey,
+  resetRetryOrchestratorForTests,
   retryImport,
   sanitizeCssValue,
   serializeError,
-  subscribe
+  subscribe,
+  triggerRetry
 };

package/dist/{chunk-BA5VUNSU.js → chunk-6TP2S7L6.js}

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

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

@@ -1,12 +1,10 @@
-import {
-  showFallbackUI
-} from "./chunk-4EXCHJBE.js";
 import {
   ForceRetryError,
   debugSyncErrorEventType,
   emitEvent,
-  getOptions
-} from "./chunk-PE5QPP5Y.js";
+  getOptions,
+  setFallbackStateForDebug
+} from "./chunk-XRBUBTPZ.js";
 
 // src/runtime/debug/errorDispatchers.ts
 function dispatchAsyncRuntimeError() {
@@ -36,18 +34,21 @@ 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",
     retryId: ""
   });
-  showFallbackUI();
+  setFallbackStateForDebug();
 }
 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-5ANASVKX.js → chunk-DINLBER6.js}

@@ -1,22 +1,17 @@
 import {
-  attemptReload,
-  sendBeacon,
-  shouldForceRetry,
-  shouldIgnoreMessages
-} from "./chunk-4EXCHJBE.js";
-import {
-  clearRetryStateFromUrl,
   emitEvent,
   getLogger,
   getOptions,
   getRetryInfoForBeacon,
-  getRetryStateFromUrl,
   isInitialized,
   markInitialized,
+  sendBeacon,
   setLogger,
+  shouldForceRetry,
+  shouldIgnoreMessages,
   staticAssetRecoveryKey,
-  updateRetryStateInUrl
-} from "./chunk-PE5QPP5Y.js";
+  triggerRetry
+} from "./chunk-XRBUBTPZ.js";
 
 // src/common/isChunkError.ts
 var isChunkError = (error) => {
@@ -182,6 +177,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 +193,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 +225,9 @@ var getState = () => {
   return globalThis.window[staticAssetRecoveryKey];
 };
 var handleStaticAssetFailure = (url) => {
+  if (globalThis.window === void 0) {
+    return;
+  }
   const state = getState();
   state.failedAssets.add(url);
   if (state.recoveryTimer !== null) {
@@ -235,11 +237,11 @@ 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;
     const error = new Error(`Static asset load failed: ${assets.join(", ")}`);
-    attemptReload(error, { cacheBust: true });
+    triggerRetry({ cacheBust: true, error, source: "static-asset-error" });
   }, delay);
 };
 
@@ -253,24 +255,6 @@ var listenInternal = (serializeError2, logger) => {
   }
   markInitialized();
   const options = getOptions();
-  const reloadDelays = options.reloadDelays ?? [];
-  const retryState = getRetryStateFromUrl();
-  if (retryState && retryState.retryAttempt >= reloadDelays.length) {
-    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",
@@ -293,12 +277,12 @@ var listenInternal = (serializeError2, logger) => {
       getLogger()?.capturedError("error", event);
       if (isChunkError(event)) {
         event.preventDefault();
-        attemptReload(event.error ?? event);
+        triggerRetry({ error: event.error ?? event, source: "chunk-error" });
         return;
       }
       if (shouldForceRetry([event.message])) {
         event.preventDefault();
-        attemptReload(event.error ?? event);
+        triggerRetry({ error: event.error ?? event, source: "force-retry" });
         return;
       }
       const serialized = serializeError2(event);
@@ -319,12 +303,12 @@ var listenInternal = (serializeError2, logger) => {
     getLogger()?.capturedError("unhandledrejection", event);
     if (isChunkError(event.reason)) {
       event.preventDefault();
-      attemptReload(event.reason);
+      triggerRetry({ error: event.reason, source: "chunk-error" });
       return;
     }
     if (shouldForceRetry([errorMessage])) {
       event.preventDefault();
-      attemptReload(event.reason);
+      triggerRetry({ error: event.reason, source: "force-retry" });
       return;
     }
     const rejectionConfig = options.handleUnhandledRejections;
@@ -339,7 +323,7 @@ var listenInternal = (serializeError2, logger) => {
     }
     if (rejectionConfig?.retry !== false) {
       event.preventDefault();
-      attemptReload(event.reason);
+      triggerRetry({ error: event.reason, source: "unhandled-rejection" });
     }
   });
   wa("securitypolicyviolation", (event) => {
@@ -357,13 +341,14 @@ var listenInternal = (serializeError2, logger) => {
     });
   });
   wa("vite:preloadError", (event) => {
-    const errorMsg = event?.payload?.message || event?.message;
+    const payload = event?.payload;
+    const errorMsg = payload?.message || event?.message;
     if (shouldIgnoreMessages([errorMsg])) {
       return;
     }
     getLogger()?.capturedError("vite:preloadError", event);
     event.preventDefault();
-    attemptReload(event?.payload ?? event);
+    triggerRetry({ error: payload ?? event, source: "vite:preloadError" });
   });
 };
 
@@ -371,6 +356,7 @@ var listenInternal = (serializeError2, logger) => {
 var PREFIX = "[spa-guard]";
 var eventLogConfig = {
   "chunk-error": "error",
+  "fallback-ui-not-rendered": "error",
   "fallback-ui-shown": "warn",
   "lazy-retry-attempt": "warn",
   "lazy-retry-exhausted": "error",
@@ -386,6 +372,10 @@ var formatEvent = (event) => {
     case "chunk-error": {
       return `${PREFIX} chunk-error: isRetrying=${event.isRetrying}`;
     }
+    case "fallback-ui-not-rendered": {
+      const selectorPart = event.selector ? ` selector=${event.selector}` : "";
+      return `${PREFIX} fallback-ui-not-rendered: reason=${event.reason}${selectorPart}`;
+    }
     case "fallback-ui-shown": {
       return `${PREFIX} fallback-ui-shown`;
     }

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

@@ -3,7 +3,7 @@ import {
   getRetryAttemptFromUrl,
   getRetryStateFromUrl,
   subscribe
-} from "./chunk-PE5QPP5Y.js";
+} from "./chunk-XRBUBTPZ.js";
 
 // src/runtime/state.ts
 var getInitialStateFromUrl = () => {
@@ -37,15 +37,6 @@ var getInitialStateFromUrl = () => {
       lastRetryResetTime: resetInfo?.timestamp
     };
   }
-  if (retryState.retryAttempt === -1) {
-    return {
-      currentAttempt: 0,
-      isFallbackShown: true,
-      isWaiting: false,
-      lastResetRetryId: resetInfo?.previousRetryId,
-      lastRetryResetTime: resetInfo?.timestamp
-    };
-  }
   return {
     currentAttempt: retryState.retryAttempt,
     isFallbackShown: false,
@@ -58,7 +49,12 @@ var currentState = getInitialStateFromUrl();
 var stateSubscribers = /* @__PURE__ */ new Set();
 var updateState = (nextState) => {
   currentState = nextState;
-  stateSubscribers.forEach((cb) => cb(currentState));
+  stateSubscribers.forEach((cb) => {
+    try {
+      cb(currentState);
+    } catch {
+    }
+  });
 };
 subscribe((event) => {
   switch (event.name) {