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

package/README.md

@@ -47,7 +47,7 @@ When a recoverable error occurs (chunk load error, unhandled rejection, `vite:pr
 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.
+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
@@ -58,6 +58,14 @@ The orchestrator serializes state into URL params for cross-reload continuity:
 - `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.

package/dist/_internal.js

@@ -3,13 +3,13 @@ import {
   defaultSpinnerSvg,
   extractVersionFromHtml,
   sanitizeCssValue
-} from "./chunk-6TP2S7L6.js";
+} from "./chunk-QDYSBRW2.js";
 import {
   createLogger,
   isChunkError,
   listenInternal,
   serializeError
-} from "./chunk-DINLBER6.js";
+} from "./chunk-YTH35AWC.js";
 import {
   dispatchAsyncRuntimeError,
   dispatchChunkLoadError,
@@ -18,7 +18,7 @@ import {
   dispatchNetworkTimeout,
   dispatchSyncRuntimeError,
   dispatchUnhandledRejection
-} from "./chunk-A5HF6LY6.js";
+} from "./chunk-ALPGMLNW.js";
 import {
   applyI18n,
   debugSyncErrorEventType,
@@ -40,7 +40,7 @@ import {
   shouldIgnoreMessages,
   subscribe,
   triggerRetry
-} from "./chunk-XRBUBTPZ.js";
+} from "./chunk-X6IW7S2K.js";
 import "./chunk-MLKGABMK.js";
 
 // src/common/handleErrorWithSpaGuard.ts

package/dist/{chunk-A5HF6LY6.js → chunk-ALPGMLNW.js}

@@ -4,7 +4,7 @@ import {
   emitEvent,
   getOptions,
   setFallbackStateForDebug
-} from "./chunk-XRBUBTPZ.js";
+} from "./chunk-X6IW7S2K.js";
 
 // src/runtime/debug/errorDispatchers.ts
 function dispatchAsyncRuntimeError() {

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

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

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

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

package/dist/{chunk-XRBUBTPZ.js → chunk-X6IW7S2K.js}

@@ -327,7 +327,47 @@ var getRetryInfoForBeacon = () => {
 };
 
 // src/common/fallbackRendering.ts
-var showFallbackUI = () => {
+var showLoadingUI = (attempt) => {
+  const options = getOptions();
+  const loadingHtml = options.html?.loading?.content;
+  if (!loadingHtml) {
+    return;
+  }
+  const selector = options.html?.fallback?.selector ?? "body";
+  try {
+    const targetElement = document.querySelector(selector);
+    if (!targetElement) {
+      return;
+    }
+    const container = document.createElement("div");
+    container.innerHTML = loadingHtml;
+    const t = getI18n();
+    if (t) {
+      applyI18n(container, t);
+    }
+    targetElement.innerHTML = container.innerHTML;
+    const retrySection = targetElement.querySelector('[data-spa-guard-section="retrying"]');
+    if (retrySection) {
+      retrySection.style.display = "";
+      retrySection.style.visibility = "visible";
+    }
+    const attemptElements = targetElement.querySelectorAll('[data-spa-guard-content="attempt"]');
+    for (const el of attemptElements) {
+      el.textContent = String(attempt);
+    }
+    const spinnerEl = targetElement.querySelector("[data-spa-guard-spinner]");
+    if (spinnerEl) {
+      const spinnerOptions = options.html?.spinner;
+      if (spinnerOptions?.disabled) {
+        spinnerEl.style.display = "none";
+      } else if (spinnerOptions?.content) {
+        spinnerEl.innerHTML = spinnerOptions.content;
+      }
+    }
+  } catch {
+  }
+};
+var showFallbackUI = (override) => {
   const options = getOptions();
   const fallbackHtml = options.html?.fallback?.content;
   const selector = options.html?.fallback?.selector ?? "body";
@@ -354,11 +394,11 @@ var showFallbackUI = () => {
     if (reloadBtn) {
       reloadBtn.addEventListener("click", () => globalThis.window.location.reload());
     }
-    const retryState = getRetryStateFromUrl();
-    if (retryState) {
+    const retryId = override?.retryId ?? getRetryStateFromUrl()?.retryId;
+    if (retryId) {
       const retryIdElements = document.getElementsByClassName("spa-guard-retry-id");
       for (const element of retryIdElements) {
-        element.textContent = retryState.retryId;
+        element.textContent = retryId;
       }
     }
     emitEvent({
@@ -703,7 +743,8 @@ var triggerRetry = (input = {}) => {
       });
       setState({ attempt: currentAttempt, phase: "fallback", retryId });
       setFallbackMode();
-      showFallbackUI();
+      clearRetryFromUrl();
+      showFallbackUI({ retryId });
       return { status: "fallback" };
     }
     const nextAttempt = currentAttempt + 1;
@@ -720,6 +761,7 @@ var triggerRetry = (input = {}) => {
     );
     getLogger()?.retrySchedulingReload(retryId, nextAttempt, delay);
     setState({ attempt: nextAttempt, retryId });
+    showLoadingUI(nextAttempt);
     const timer = setTimeout(() => {
       try {
         if (useRetryId && enableRetryReset) {
@@ -737,7 +779,7 @@ var triggerRetry = (input = {}) => {
   } catch (error) {
     getLogger()?.error("triggerRetry internal error", error);
     setState({ lastSource: void 0, lastTriggerTime: void 0, phase: "idle" });
-    return { reason: "internal-error", status: "deduped" };
+    return { status: "internal-error" };
   }
 };
 var markRetryHealthyBoot = () => {
@@ -768,7 +810,7 @@ var setFallbackStateForDebug = () => {
   }
   setState({ phase: "fallback", timer: null });
   setFallbackMode();
-  showFallbackUI();
+  showFallbackUI({ retryId: state.retryId ?? void 0 });
 };
 var resetRetryOrchestratorForTests = () => {
   const state = getState();

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

@@ -11,7 +11,7 @@ import {
   shouldIgnoreMessages,
   staticAssetRecoveryKey,
   triggerRetry
-} from "./chunk-XRBUBTPZ.js";
+} from "./chunk-X6IW7S2K.js";
 
 // src/common/isChunkError.ts
 var isChunkError = (error) => {
@@ -58,6 +58,10 @@ var serializeError = (error) => {
     });
   }
 };
+var MAX_DEPTH = 4;
+var MAX_KEYS = 20;
+var MAX_STRING_LEN = 500;
+var truncate = (str) => str.length > MAX_STRING_LEN ? str.slice(0, MAX_STRING_LEN) + "\u2026" : str;
 var serializeErrorInternal = (error) => {
   if (error === null || error === void 0) {
     return { type: "null", value: error };
@@ -75,8 +79,15 @@ var serializeErrorInternal = (error) => {
     };
   }
   if ("reason" in error && "promise" in error) {
+    const evt = error;
+    const reason = evt.reason;
+    const pageUrl = typeof window !== "undefined" && typeof window.location?.href === "string" ? window.location.href : void 0;
     return {
-      reason: serializeErrorInternal(error.reason),
+      constructorName: reason?.constructor?.name,
+      isTrusted: evt.isTrusted,
+      pageUrl,
+      reason: serializeRejectionReason(reason, /* @__PURE__ */ new WeakSet(), 0),
+      timeStamp: evt.timeStamp,
       type: "PromiseRejectionEvent"
     };
   }
@@ -117,6 +128,140 @@ var serializeErrorInternal = (error) => {
     value: extractOwnProperties(error)
   };
 };
+var serializeRejectionReason = (reason, visited, depth) => {
+  if (reason === null || reason === void 0) {
+    return { type: "null", value: reason };
+  }
+  if (typeof reason !== "object") {
+    const val = typeof reason === "string" ? truncate(reason) : reason;
+    return { type: typeof reason, value: val };
+  }
+  if (visited.has(reason)) {
+    return { type: "circular" };
+  }
+  visited.add(reason);
+  if (typeof AggregateError !== "undefined" && reason instanceof AggregateError) {
+    return {
+      errors: reason.errors.slice(0, 3).map((e) => serializeSafeError(e, visited, depth + 1)),
+      message: truncate(reason.message),
+      name: reason.name,
+      stack: reason.stack ? truncate(reason.stack) : void 0,
+      type: "Error"
+    };
+  }
+  if (typeof DOMException !== "undefined" && reason instanceof DOMException) {
+    return {
+      code: reason.code,
+      message: truncate(reason.message),
+      name: reason.name,
+      type: "Error"
+    };
+  }
+  if (reason instanceof Error) {
+    return serializeSafeError(reason, visited, depth);
+  }
+  const reasonObj = reason;
+  if (reasonObj.response != null) {
+    const response = reasonObj.response;
+    const result = {
+      type: "HttpError"
+    };
+    if (response.status !== void 0) {
+      result.status = response.status;
+    }
+    if (response.statusText !== void 0) {
+      result.statusText = typeof response.statusText === "string" ? truncate(response.statusText) : response.statusText;
+    }
+    if (response.url !== void 0) {
+      result.url = typeof response.url === "string" ? truncate(response.url) : response.url;
+    }
+    if (response.method !== void 0) {
+      result.method = response.method;
+    }
+    if (response.type !== void 0) {
+      result.responseType = response.type;
+    }
+    try {
+      const headers = response.headers;
+      if (headers) {
+        let xRequestId;
+        if (typeof headers.get === "function") {
+          xRequestId = headers.get("X-Request-ID") ?? headers.get("x-request-id");
+        } else if (typeof headers === "object") {
+          xRequestId = headers["X-Request-ID"] ?? headers["x-request-id"];
+        }
+        if (xRequestId) {
+          result.xRequestId = truncate(String(xRequestId));
+        }
+      }
+    } catch {
+    }
+    const reqSource = reasonObj.config ?? reasonObj.request;
+    if (reqSource != null) {
+      const req = {};
+      if (reqSource.method !== void 0) {
+        req.method = reqSource.method;
+      }
+      if (reqSource.url !== void 0) {
+        req.url = typeof reqSource.url === "string" ? truncate(reqSource.url) : reqSource.url;
+      }
+      if (reqSource.baseURL !== void 0) {
+        req.baseURL = typeof reqSource.baseURL === "string" ? truncate(reqSource.baseURL) : reqSource.baseURL;
+      }
+      result.request = req;
+    }
+    return result;
+  }
+  return {
+    type: "object",
+    value: extractBoundedObject(reasonObj, visited, depth)
+  };
+};
+var serializeSafeError = (error, visited, depth) => {
+  if (!(error instanceof Error)) {
+    return serializeRejectionReason(error, visited, depth + 1);
+  }
+  const result = {
+    message: truncate(error.message),
+    name: error.name,
+    stack: error.stack ? truncate(error.stack) : void 0,
+    type: "Error"
+  };
+  if (depth < MAX_DEPTH && error.cause !== void 0) {
+    const cause = error.cause;
+    if (typeof cause === "object" && cause !== null) {
+      if (!visited.has(cause)) {
+        result.cause = serializeRejectionReason(cause, visited, depth + 1);
+      }
+    } else {
+      result.cause = cause;
+    }
+  }
+  return result;
+};
+var extractBoundedObject = (obj, visited, depth) => {
+  const result = {};
+  let keyCount = 0;
+  for (const key of Object.keys(obj)) {
+    if (keyCount >= MAX_KEYS) {
+      break;
+    }
+    try {
+      const value = obj[key];
+      if (value === null || value === void 0 || typeof value !== "object") {
+        result[key] = typeof value === "string" ? truncate(value) : value;
+      } else if (depth < MAX_DEPTH && !visited.has(value)) {
+        visited.add(value);
+        result[key] = extractBoundedObject(value, visited, depth + 1);
+      } else {
+        result[key] = "[object]";
+      }
+    } catch {
+    }
+    keyCount++;
+  }
+  return result;
+};
 var extractErrorProperties = (error) => {
   const props = {};
   for (const key of Object.getOwnPropertyNames(error)) {
@@ -247,6 +392,9 @@ var handleStaticAssetFailure = (url) => {
 
 // src/common/listen/internal.ts
 var listenInternal = (serializeError2, logger) => {
+  if (globalThis.window === void 0) {
+    return;
+  }
   if (isInitialized()) {
     return;
   }
@@ -254,7 +402,6 @@ var listenInternal = (serializeError2, logger) => {
     setLogger(logger);
   }
   markInitialized();
-  const options = getOptions();
   const wa = globalThis.window.addEventListener.bind(globalThis.window);
   wa(
     "error",
@@ -266,7 +413,7 @@ var listenInternal = (serializeError2, logger) => {
         }
         event.preventDefault();
         emitEvent({ name: "static-asset-load-failed", url: assetUrl });
-        if (options.staticAssets?.autoRecover !== false) {
+        if (getOptions().staticAssets?.autoRecover !== false) {
           handleStaticAssetFailure(assetUrl);
         }
         return;
@@ -311,7 +458,7 @@ var listenInternal = (serializeError2, logger) => {
       triggerRetry({ error: event.reason, source: "force-retry" });
       return;
     }
-    const rejectionConfig = options.handleUnhandledRejections;
+    const rejectionConfig = getOptions().handleUnhandledRejections;
     if (rejectionConfig?.sendBeacon !== false) {
       const serialized = serializeError2(event);
       sendBeacon({
@@ -413,9 +560,6 @@ var createLogger = () => ({
   capturedError(type, ...args) {
     console.error(`${PREFIX} ${type}:capture:`, ...args);
   },
-  clearingRetryState() {
-    console.log(`${PREFIX} Clearing retry state from URL to allow clean reload attempt`);
-  },
   error(msg, ...args) {
     console.error(`${PREFIX} ${msg}`, ...args);
   },
@@ -455,17 +599,11 @@ var createLogger = () => ({
   retryCycleStarting(retryId, fromAttempt) {
     console.log(`${PREFIX} Retry cycle starting: retryId=${retryId}, fromAttempt=${fromAttempt}`);
   },
-  retryLimitExceeded(attempt, max) {
-    console.log(`${PREFIX} Retry limit exceeded (${attempt}/${max}), marking as fallback shown`);
-  },
   retrySchedulingReload(retryId, attempt, delay) {
     console.log(
       `${PREFIX} Scheduling reload: retryId=${retryId}, attempt=${attempt}, delay=${delay}ms`
     );
   },
-  updatedRetryAttempt(attempt) {
-    console.log(`${PREFIX} Updated retry attempt to ${attempt} in URL for fallback UI`);
-  },
   versionChangeDetected(oldVersion, latestVersion) {
     console.warn(
       `${PREFIX} New version available (${oldVersion ?? "unknown"} \u2192 ${latestVersion}). Please refresh to get the latest version.`

package/dist/common/fallbackRendering.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Renders the loading UI into the DOM during a retry delay before reload.
+ *
+ * Fail-safe: if loading content is not configured or the target element is not
+ * found, returns silently with no log, no event, and no side effects.
+ * All DOM access is wrapped in try/catch.
+ */
+export declare const showLoadingUI: (attempt: number) => void;
 /**
  * Renders the fallback UI into the DOM.
  *
@@ -10,4 +18,6 @@
  * Fails safely: if fallback HTML is not configured or the target element
  * is not found, logs a warning and returns without side effects or errors.
  */
-export declare const showFallbackUI: () => void;
+export declare const showFallbackUI: (override?: {
+    retryId?: string;
+}) => void;

package/dist/common/index.d.ts

@@ -5,3 +5,5 @@ export { disableDefaultRetry, enableDefaultRetry, isDefaultRetryEnabled } from "
 export { isInFallbackMode, resetFallbackMode } from "./fallbackState";
 export { listen } from "./listen";
 export * as options from "./options";
+export { getRetrySnapshot, markRetryHealthyBoot, triggerRetry } from "./retryOrchestrator";
+export type { RetryPhase, RetrySnapshot, TriggerInput, TriggerResult } from "./retryOrchestrator";

package/dist/common/index.js

@@ -2,18 +2,21 @@ import {
   createLogger,
   listenInternal,
   serializeError
-} from "../chunk-DINLBER6.js";
+} from "../chunk-YTH35AWC.js";
 import {
   ForceRetryError,
   disableDefaultRetry,
   emitEvent,
   enableDefaultRetry,
+  getRetrySnapshot,
   isDefaultRetryEnabled,
   isInFallbackMode,
+  markRetryHealthyBoot,
   options_exports,
   resetFallbackMode,
-  subscribe
-} from "../chunk-XRBUBTPZ.js";
+  subscribe,
+  triggerRetry
+} from "../chunk-X6IW7S2K.js";
 import {
   __export
 } from "../chunk-MLKGABMK.js";
@@ -73,9 +76,12 @@ export {
   disableDefaultRetry,
   enableDefaultRetry,
   events_exports as events,
+  getRetrySnapshot,
   isDefaultRetryEnabled,
   isInFallbackMode,
   listen,
+  markRetryHealthyBoot,
   options_exports as options,
-  resetFallbackMode
+  resetFallbackMode,
+  triggerRetry
 };

package/dist/common/logger.d.ts

@@ -2,7 +2,6 @@ import type { SPAGuardEvent } from "./events/types";
 export interface Logger {
     beaconSendFailed(error: unknown): void;
     capturedError(type: string, ...args: unknown[]): void;
-    clearingRetryState(): void;
     error(msg: string, ...args: unknown[]): void;
     fallbackAlreadyShown(error: unknown): void;
     fallbackInjectFailed(error: unknown): void;
@@ -13,9 +12,7 @@ export interface Logger {
     noFallbackConfigured(): void;
     reloadAlreadyScheduled(error: unknown): void;
     retryCycleStarting(retryId: string, fromAttempt: number): void;
-    retryLimitExceeded(attempt: number, max: number): void;
     retrySchedulingReload(retryId: string, attempt: number, delay: number): void;
-    updatedRetryAttempt(attempt: number): void;
     versionChangeDetected(oldVersion: null | string, latestVersion: string): void;
     versionCheckAlreadyRunning(): void;
     versionCheckDisabled(): void;

package/dist/common/retryOrchestrator.d.ts

@@ -18,6 +18,8 @@ export type TriggerResult = {
     status: "accepted";
 } | {
     status: "fallback";
+} | {
+    status: "internal-error";
 } | {
     status: "retry-disabled";
 };

package/dist/runtime/debug/index.js

@@ -8,13 +8,13 @@ import {
   dispatchStaticAsset404,
   dispatchSyncRuntimeError,
   dispatchUnhandledRejection
-} from "../../chunk-A5HF6LY6.js";
+} from "../../chunk-ALPGMLNW.js";
 import {
   subscribeToState
-} from "../../chunk-EFWD2I2Y.js";
+} from "../../chunk-SCBBWARW.js";
 import {
   subscribe
-} from "../../chunk-XRBUBTPZ.js";
+} from "../../chunk-X6IW7S2K.js";
 import "../../chunk-MLKGABMK.js";
 
 // src/runtime/debug/index.ts

package/dist/runtime/index.js

@@ -3,11 +3,11 @@ import {
   extractVersionFromHtml,
   getSpinnerHtml,
   showSpinner
-} from "../chunk-6TP2S7L6.js";
+} from "../chunk-QDYSBRW2.js";
 import {
   getState,
   subscribeToState
-} from "../chunk-EFWD2I2Y.js";
+} from "../chunk-SCBBWARW.js";
 import {
   ForceRetryError,
   getLogger,
@@ -15,7 +15,7 @@ import {
   markRetryHealthyBoot,
   setTranslations,
   versionCheckStateWindowKey
-} from "../chunk-XRBUBTPZ.js";
+} from "../chunk-X6IW7S2K.js";
 import "../chunk-MLKGABMK.js";
 
 // src/common/checkVersion.ts

package/package.json

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