@ovineko/spa-guard 0.0.1-alpha-29 → 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)
@@ -41,6 +87,17 @@ const cleanup = recommendedSetup({ versionCheck: false });
 - `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
@@ -73,7 +130,7 @@ Available error scenarios:
 - `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
+- `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-CBAJOLBG.js";
 import {
   SPINNER_ID,
   defaultSpinnerSvg,
   extractVersionFromHtml,
   sanitizeCssValue
-} from "./chunk-5546JVQV.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-3LAQJKWC.js";
-import {
-  attemptReload,
-  sendBeacon,
-  shouldForceRetry,
-  shouldIgnoreMessages
-} from "./chunk-2BUEJXDB.js";
+} from "./chunk-A5HF6LY6.js";
 import {
   applyI18n,
   debugSyncErrorEventType,
@@ -36,10 +30,17 @@ import {
   getI18n,
   getOptions,
   getRetryInfoForBeacon,
+  getRetrySnapshot,
   isDefaultRetryEnabled,
+  markRetryHealthyBoot,
   optionsWindowKey,
-  subscribe
-} from "./chunk-LBHLKYQS.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-5546JVQV.js → chunk-6TP2S7L6.js}

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

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

@@ -1,12 +1,10 @@
-import {
-  showFallbackUI
-} from "./chunk-2BUEJXDB.js";
 import {
   ForceRetryError,
   debugSyncErrorEventType,
   emitEvent,
-  getOptions
-} from "./chunk-LBHLKYQS.js";
+  getOptions,
+  setFallbackStateForDebug
+} from "./chunk-XRBUBTPZ.js";
 
 // src/runtime/debug/errorDispatchers.ts
 function dispatchAsyncRuntimeError() {
@@ -42,7 +40,7 @@ function dispatchRetryExhausted() {
     name: "retry-exhausted",
     retryId: ""
   });
-  showFallbackUI();
+  setFallbackStateForDebug();
 }
 function dispatchStaticAsset404() {
   const hash = crypto.randomUUID().slice(0, 8);

package/dist/{chunk-CBAJOLBG.js → chunk-DINLBER6.js}

@@ -1,23 +1,17 @@
 import {
-  attemptReload,
-  isInFallbackMode,
-  sendBeacon,
-  shouldForceRetry,
-  shouldIgnoreMessages
-} from "./chunk-2BUEJXDB.js";
-import {
-  clearRetryStateFromUrl,
   emitEvent,
   getLogger,
   getOptions,
   getRetryInfoForBeacon,
-  getRetryStateFromUrl,
   isInitialized,
   markInitialized,
+  sendBeacon,
   setLogger,
+  shouldForceRetry,
+  shouldIgnoreMessages,
   staticAssetRecoveryKey,
-  updateRetryStateInUrl
-} from "./chunk-LBHLKYQS.js";
+  triggerRetry
+} from "./chunk-XRBUBTPZ.js";
 
 // src/common/isChunkError.ts
 var isChunkError = (error) => {
@@ -234,9 +228,6 @@ var handleStaticAssetFailure = (url) => {
   if (globalThis.window === void 0) {
     return;
   }
-  if (isInFallbackMode()) {
-    return;
-  }
   const state = getState();
   state.failedAssets.add(url);
   if (state.recoveryTimer !== null) {
@@ -249,11 +240,8 @@ var handleStaticAssetFailure = (url) => {
     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 });
+    triggerRetry({ cacheBust: true, error, source: "static-asset-error" });
   }, delay);
 };
 
@@ -267,25 +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)) {
-    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",
@@ -308,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);
@@ -334,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;
@@ -354,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) => {
@@ -372,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" });
   });
 };
 
@@ -386,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",
@@ -401,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-W3TOHCEW.js → chunk-EFWD2I2Y.js}

@@ -3,7 +3,7 @@ import {
   getRetryAttemptFromUrl,
   getRetryStateFromUrl,
   subscribe
-} from "./chunk-LBHLKYQS.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) {