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

package/README.md

@@ -28,6 +28,60 @@ 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, calls `showLoadingUI(nextAttempt)` to render the loading UI immediately (before the timer fires), sets a timer for `reloadDelays[currentAttempt]`, encodes `retryId` and attempt count into the reload URL, then navigates. Requires `options.html.loading.content` to be configured; if absent, `showLoadingUI` returns silently and the retry still proceeds.
+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)
+
+### Loading UI during retry delay
+
+When `options.html.loading.content` is configured, `showLoadingUI(attempt)` is called before the reload timer fires. It injects the loading HTML into the target element (selector from `options.html.fallback.selector`, defaulting to `body`), reveals the `data-spa-guard-section="retrying"` element, fills attempt numbers into `[data-spa-guard-content="attempt"]` elements, applies i18n via `applyI18n`/`getI18n`, and optionally hides or replaces the spinner based on `options.html.spinner`. If loading content is not configured or the target element is not found, `showLoadingUI` returns silently — the retry still proceeds normally.
+
+### Unhandledrejection serialization
+
+`serializeError` handles `PromiseRejectionEvent` with strict redaction guardrails. For HTTP-like errors it extracts only safe metadata: `status`, `statusText`, `url`, `method`, `response.type`, and `X-Request-ID` from response headers when present. Response body, request/response payload, and the full headers object are **never** included in serialized output. For request wrappers (`reason.request` / `reason.config`) only `method`, `url`, and `baseURL` are extracted. Deep object traversal is bounded by `MAX_DEPTH=4`, `MAX_KEYS=20`, and `MAX_STRING_LEN=500` to prevent oversized beacons. Circular references are handled via a `WeakSet` visited tracker. The output also includes `isTrusted`, `timeStamp` from the event, and runtime context (`pageUrl`, `constructorName`).
+
+### 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 +95,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 +138,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-QDYSBRW2.js";
+import {
+  createLogger,
+  isChunkError,
+  listenInternal,
+  serializeError
+} from "./chunk-YTH35AWC.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-ALPGMLNW.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-X6IW7S2K.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-3LAQJKWC.js → chunk-ALPGMLNW.js}

@@ -1,12 +1,10 @@
-import {
-  showFallbackUI
-} from "./chunk-2BUEJXDB.js";
 import {
   ForceRetryError,
   debugSyncErrorEventType,
   emitEvent,
-  getOptions
-} from "./chunk-LBHLKYQS.js";
+  getOptions,
+  setFallbackStateForDebug
+} from "./chunk-X6IW7S2K.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-5546JVQV.js → chunk-QDYSBRW2.js}

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

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

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