@ovineko/spa-guard 0.0.1-alpha-31 → 0.0.2-alpha-0

package/README.md

@@ -22,6 +22,36 @@ const cleanup = recommendedSetup();
 // optionally call cleanup() to stop background checks
 ```
 
+`recommendedSetup` is idempotent. Repeated calls return the same cleanup function and do not re-run setup side effects.
+
+By default, `recommendedSetup` uses `healthyBoot: "auto"`:
+
+- if retry params exist in the URL, it waits a dynamic grace period and calls `markRetryHealthyBoot()` only when the orchestrator phase is still `idle`.
+- if no retry params exist, it does nothing.
+
+Auto grace period formula:
+
+- `max(5000, max(reloadDelays)+1000, sum(lazyRetry.retryDelays)+1000)`
+
+If you want strict control, switch to manual healthy-boot mode and call `markRetryHealthyBoot()` yourself.
+
+```ts
+import { markRetryHealthyBoot } from "@ovineko/spa-guard";
+import { recommendedSetup } from "@ovineko/spa-guard/runtime";
+
+recommendedSetup();
+
+await Promise.all([import("./routes/Home"), import("./routes/Checkout")]);
+
+markRetryHealthyBoot();
+```
+
+Disable auto healthy boot:
+
+```ts
+recommendedSetup({ healthyBoot: "manual" });
+```
+
 Disable version checking:
 
 ```ts
@@ -72,7 +102,23 @@ If enough time has passed since the last reload (configurable via `minTimeBetwee
 
 ### 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.
+After a successful app boot following a retry reload, `markRetryHealthyBoot()` clears retry URL params, cancels any pending timer, and resets orchestrator state.
+
+Default behavior in `recommendedSetup`: auto healthy-boot after a grace period (`healthyBoot: "auto"`).
+Manual override: set `healthyBoot: "manual"` and call `markRetryHealthyBoot()` yourself once critical boot is confirmed.
+
+### Avoid false retry loops from app errors
+
+By default, regular `unhandledrejection` events also trigger `triggerRetry()` (`handleUnhandledRejections.retry: true`). If your app has non-chunk unhandled rejections, this can look like retry looping even though chunks are healthy. In that case, disable reload-on-unhandled-rejection:
+
+```ts
+window.__SPA_GUARD_OPTIONS__ = {
+  handleUnhandledRejections: {
+    retry: false,
+    sendBeacon: true,
+  },
+};
+```
 
 ### Static asset burst coalescing
 
@@ -108,8 +154,9 @@ Only `retryOrchestrator.ts` may schedule reloads, advance retry state, or transi
 
 ### `@ovineko/spa-guard/runtime`
 
-- `recommendedSetup(options?)` — enable recommended runtime features; returns cleanup function
-- `RecommendedSetupOptions` — `{ versionCheck?: boolean }`
+- `recommendedSetup(options?)` — enable recommended runtime features; idempotent and returns cleanup function
+- `RecommendedSetupOptions` — `{ versionCheck?: boolean; healthyBoot?: "auto" | "manual" | "off" | false | { mode?: "auto"; graceMs?: number } }`
+  - `healthyBoot.graceMs` acts as a lower bound override for auto mode (`max(computedGraceMs, graceMs)`)
 - `startVersionCheck` / `stopVersionCheck` — manual version check control
 - `getState` / `subscribeToState` — runtime state access
 - `SpaGuardState` — state type

package/dist/_internal.js

@@ -1,15 +1,15 @@
-import {
-  SPINNER_ID,
-  defaultSpinnerSvg,
-  extractVersionFromHtml,
-  sanitizeCssValue
-} from "./chunk-QDYSBRW2.js";
 import {
   createLogger,
   isChunkError,
   listenInternal,
   serializeError
-} from "./chunk-YTH35AWC.js";
+} from "./chunk-4K3AQHLC.js";
+import {
+  SPINNER_ID,
+  defaultSpinnerSvg,
+  extractVersionFromHtml,
+  sanitizeCssValue
+} from "./chunk-T42DLOQP.js";
 import {
   dispatchAsyncRuntimeError,
   dispatchChunkLoadError,
@@ -18,7 +18,7 @@ import {
   dispatchNetworkTimeout,
   dispatchSyncRuntimeError,
   dispatchUnhandledRejection
-} from "./chunk-ALPGMLNW.js";
+} from "./chunk-ORYUDYHU.js";
 import {
   applyI18n,
   debugSyncErrorEventType,
@@ -40,7 +40,7 @@ import {
   shouldIgnoreMessages,
   subscribe,
   triggerRetry
-} from "./chunk-X6IW7S2K.js";
+} from "./chunk-LIKSIU75.js";
 import "./chunk-MLKGABMK.js";
 
 // src/common/handleErrorWithSpaGuard.ts

package/dist/{chunk-YTH35AWC.js → chunk-4K3AQHLC.js}

@@ -11,7 +11,7 @@ import {
   shouldIgnoreMessages,
   staticAssetRecoveryKey,
   triggerRetry
-} from "./chunk-X6IW7S2K.js";
+} from "./chunk-LIKSIU75.js";
 
 // src/common/isChunkError.ts
 var isChunkError = (error) => {
@@ -73,7 +73,7 @@ var serializeErrorInternal = (error) => {
     return {
       message: error.message,
       name: error.name,
-      stack: error.stack,
+      stack: error.stack ? truncate(error.stack) : void 0,
       type: "Error",
       ...extractErrorProperties(error)
     };
@@ -264,12 +264,22 @@ var extractBoundedObject = (obj, visited, depth) => {
 };
 var extractErrorProperties = (error) => {
   const props = {};
+  let keyCount = 0;
   for (const key of Object.getOwnPropertyNames(error)) {
+    if (keyCount >= MAX_KEYS) {
+      break;
+    }
     if (!["message", "name", "stack"].includes(key)) {
       try {
-        props[key] = error[key];
+        const value = error[key];
+        if (value === null || value === void 0 || typeof value !== "object") {
+          props[key] = typeof value === "string" ? truncate(value) : value;
+        } else {
+          props[key] = "[object]";
+        }
       } catch {
       }
+      keyCount++;
     }
   }
   return props;
@@ -291,12 +301,21 @@ var extractEventTarget = (target) => {
 };
 var extractOwnProperties = (obj) => {
   const props = {};
+  let keyCount = 0;
   for (const key of Object.keys(obj)) {
+    if (keyCount >= MAX_KEYS) {
+      break;
+    }
     try {
       const value = obj[key];
-      props[key] = typeof value === "object" ? String(value) : value;
+      if (value === null || value === void 0 || typeof value !== "object") {
+        props[key] = typeof value === "string" ? truncate(value) : value;
+      } else {
+        props[key] = "[object]";
+      }
     } catch {
     }
+    keyCount++;
   }
   return props;
 };

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

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

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

@@ -348,8 +348,9 @@ var showLoadingUI = (attempt) => {
     targetElement.innerHTML = container.innerHTML;
     const retrySection = targetElement.querySelector('[data-spa-guard-section="retrying"]');
     if (retrySection) {
-      retrySection.style.display = "";
-      retrySection.style.visibility = "visible";
+      const retrySectionEl = retrySection;
+      retrySectionEl.style.display = "";
+      retrySectionEl.style.visibility = "visible";
     }
     const attemptElements = targetElement.querySelectorAll('[data-spa-guard-content="attempt"]');
     for (const el of attemptElements) {
@@ -771,7 +772,7 @@ var triggerRetry = (input = {}) => {
         globalThis.window.location.href = reloadUrl;
       } catch (navError) {
         getLogger()?.error("triggerRetry navigation failed", navError);
-        setState({ phase: "idle" });
+        setState({ phase: "idle", timer: null });
       }
     }, delay);
     setState({ timer });

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

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

package/dist/{chunk-QDYSBRW2.js → chunk-T42DLOQP.js}

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

package/dist/common/index.js

@@ -2,7 +2,7 @@ import {
   createLogger,
   listenInternal,
   serializeError
-} from "../chunk-YTH35AWC.js";
+} from "../chunk-4K3AQHLC.js";
 import {
   ForceRetryError,
   disableDefaultRetry,
@@ -16,7 +16,7 @@ import {
   resetFallbackMode,
   subscribe,
   triggerRetry
-} from "../chunk-X6IW7S2K.js";
+} from "../chunk-LIKSIU75.js";
 import {
   __export
 } from "../chunk-MLKGABMK.js";

package/dist/i18n/index.js

@@ -5,7 +5,7 @@ var translations = {
   ar: {
     heading: "\u062D\u062F\u062B \u062E\u0637\u0623 \u0645\u0627",
     loading: "...\u062C\u0627\u0631\u064D \u0627\u0644\u062A\u062D\u0645\u064A\u0644",
-    message: "\u064A\u0631\u062C\u0649 \u062A\u062D\u062F\u064A\u062B \u0627\u0644\u0635\u0641\u062D\u0629 \u0644\u0644\u0645\u062A\u0627\u0628\u0639\u0629.",
+    message: "\u064A\u0631\u062C\u0649 \u062A\u062D\u062F\u064A\u062B \u0627\u0644\u0635\u0641\u062D\u0629 \u0644\u0644\u0645\u062A\u0627\u0628\u0639\u0629",
     reload: "\u0625\u0639\u0627\u062F\u0629 \u062A\u062D\u0645\u064A\u0644",
     retrying: "\u0645\u062D\u0627\u0648\u0644\u0629 \u0625\u0639\u0627\u062F\u0629",
     rtl: true,
@@ -14,7 +14,7 @@ var translations = {
   az: {
     heading: "N\u0259s\u0259 s\u0259hv getdi",
     loading: "Y\xFCkl\u0259nir...",
-    message: "Davam etm\u0259k \xFC\xE7\xFCn s\u0259hif\u0259ni yenil\u0259yin.",
+    message: "Davam etm\u0259k \xFC\xE7\xFCn s\u0259hif\u0259ni yenil\u0259yin",
     reload: "S\u0259hif\u0259ni yenid\u0259n y\xFCkl\u0259",
     retrying: "Yenid\u0259n c\u0259hd",
     tryAgain: "Yenid\u0259n c\u0259r\u0259b edin"
@@ -22,7 +22,7 @@ var translations = {
   ca: {
     heading: "Alguna cosa ha anat malament",
     loading: "Carregant...",
-    message: "Si us plau, actualitzeu la p\xE0gina per continuar.",
+    message: "Si us plau, actualitzeu la p\xE0gina per continuar",
     reload: "Recarrega la p\xE0gina",
     retrying: "Intent de reintent",
     tryAgain: "Torna-ho a provar"
@@ -30,7 +30,7 @@ var translations = {
   cs: {
     heading: "N\u011Bco se pokazilo",
     loading: "Na\u010D\xEDt\xE1n\xED...",
-    message: "Obnovte str\xE1nku pros\xEDm pro pokra\u010Dov\xE1n\xED.",
+    message: "Obnovte str\xE1nku pros\xEDm pro pokra\u010Dov\xE1n\xED",
     reload: "Znovu na\u010D\xEDst str\xE1nku",
     retrying: "Pokus o opakov\xE1n\xED",
     tryAgain: "Zkusit znovu"
@@ -38,7 +38,7 @@ var translations = {
   da: {
     heading: "Noget gik galt",
     loading: "Indl\xE6ser...",
-    message: "Opdater venligst siden for at forts\xE6tte.",
+    message: "Opdater venligst siden for at forts\xE6tte",
     reload: "Genindl\xE6s side",
     retrying: "Fors\xF8g igen",
     tryAgain: "Pr\xF8v igen"
@@ -46,7 +46,7 @@ var translations = {
   de: {
     heading: "Etwas ist schief gelaufen",
     loading: "L\xE4dt...",
-    message: "Bitte aktualisieren Sie die Seite, um fortzufahren.",
+    message: "Bitte aktualisieren Sie die Seite, um fortzufahren",
     reload: "Seite neu laden",
     retrying: "Wiederholungsversuch",
     tryAgain: "Erneut versuchen"
@@ -54,7 +54,7 @@ var translations = {
   el: {
     heading: "\u039A\u03AC\u03C4\u03B9 \u03C0\u03AE\u03B3\u03B5 \u03C3\u03C4\u03C1\u03B1\u03B2\u03AC",
     loading: "\u03A6\u03CC\u03C1\u03C4\u03C9\u03C3\u03B7...",
-    message: "\u03A0\u03B1\u03C1\u03B1\u03BA\u03B1\u03BB\u03CE \u03B1\u03BD\u03B1\u03BD\u03B5\u03CE\u03C3\u03C4\u03B5 \u03C4\u03B7 \u03C3\u03B5\u03BB\u03AF\u03B4\u03B1 \u03B3\u03B9\u03B1 \u03BD\u03B1 \u03C3\u03C5\u03BD\u03B5\u03C7\u03AF\u03C3\u03B5\u03C4\u03B5.",
+    message: "\u03A0\u03B1\u03C1\u03B1\u03BA\u03B1\u03BB\u03CE \u03B1\u03BD\u03B1\u03BD\u03B5\u03CE\u03C3\u03C4\u03B5 \u03C4\u03B7 \u03C3\u03B5\u03BB\u03AF\u03B4\u03B1 \u03B3\u03B9\u03B1 \u03BD\u03B1 \u03C3\u03C5\u03BD\u03B5\u03C7\u03AF\u03C3\u03B5\u03C4\u03B5",
     reload: "\u0395\u03C0\u03B1\u03BD\u03B1\u03C6\u03CC\u03C1\u03C4\u03C9\u03C3\u03B7 \u03C3\u03B5\u03BB\u03AF\u03B4\u03B1\u03C2",
     retrying: "\u03A0\u03C1\u03BF\u03C3\u03C0\u03AC\u03B8\u03B5\u03B9\u03B1 \u03B5\u03C0\u03B1\u03BD\u03AC\u03BB\u03B7\u03C8\u03B7\u03C2",
     tryAgain: "\u0394\u03BF\u03BA\u03B9\u03BC\u03AC\u03C3\u03C4\u03B5 \u03BE\u03B1\u03BD\u03AC"
@@ -62,7 +62,7 @@ var translations = {
   en: {
     heading: "Something went wrong",
     loading: "Loading...",
-    message: "Please refresh the page to continue.",
+    message: "Please refresh the page to continue",
     reload: "Reload page",
     retrying: "Retry attempt",
     tryAgain: "Try again"
@@ -70,7 +70,7 @@ var translations = {
   es: {
     heading: "Algo sali\xF3 mal",
     loading: "Cargando...",
-    message: "Por favor, actualice la p\xE1gina para continuar.",
+    message: "Por favor, actualice la p\xE1gina para continuar",
     reload: "Recargar p\xE1gina",
     retrying: "Intento de reintento",
     tryAgain: "Intentar de nuevo"
@@ -78,7 +78,7 @@ var translations = {
   eu: {
     heading: "Zerbait gaizki joan da",
     loading: "Kargatzen...",
-    message: "Mesedez, freskatu orria jarraitzeko.",
+    message: "Mesedez, freskatu orria jarraitzeko",
     reload: "Orria berritu",
     retrying: "Saiakera berri",
     tryAgain: "Saiatu berriro"
@@ -86,7 +86,7 @@ var translations = {
   fa: {
     heading: "\u0645\u0634\u06A9\u0644\u06CC \u067E\u06CC\u0634 \u0622\u0645\u062F",
     loading: "\u062F\u0631 \u062D\u0627\u0644 \u0628\u0627\u0631\u06AF\u0630\u0627\u0631\u06CC...",
-    message: "\u0644\u0637\u0641\u0627\u064B \u0635\u0641\u062D\u0647 \u0631\u0627 \u0628\u0631\u0627\u06CC \u0627\u062F\u0627\u0645\u0647 \u062A\u0627\u0632\u0647 \u06A9\u0646\u06CC\u062F.",
+    message: "\u0644\u0637\u0641\u0627\u064B \u0635\u0641\u062D\u0647 \u0631\u0627 \u0628\u0631\u0627\u06CC \u0627\u062F\u0627\u0645\u0647 \u062A\u0627\u0632\u0647 \u06A9\u0646\u06CC\u062F",
     reload: "\u0628\u0627\u0631\u06AF\u0630\u0627\u0631\u06CC \u0645\u062C\u062F\u062F",
     retrying: "\u062A\u0644\u0627\u0634 \u062F\u0648\u0628\u0627\u0631\u0647",
     rtl: true,
@@ -95,7 +95,7 @@ var translations = {
   fi: {
     heading: "Jokin meni pieleen",
     loading: "Ladataan...",
-    message: "P\xE4ivit\xE4 sivu jatkaaksesi.",
+    message: "P\xE4ivit\xE4 sivu jatkaaksesi",
     reload: "Lataa sivu uudelleen",
     retrying: "Uudelleenyritys",
     tryAgain: "Yrit\xE4 uudelleen"
@@ -103,7 +103,7 @@ var translations = {
   fr: {
     heading: "Quelque chose s'est mal pass\xE9",
     loading: "Chargement...",
-    message: "Veuillez actualiser la page pour continuer.",
+    message: "Veuillez actualiser la page pour continuer",
     reload: "Recharger la page",
     retrying: "Tentative de nouvel essai",
     tryAgain: "R\xE9essayer"
@@ -111,7 +111,7 @@ var translations = {
   he: {
     heading: "\u05DE\u05E9\u05D4\u05D5 \u05D4\u05E9\u05EA\u05D1\u05E9",
     loading: "...\u05D8\u05D5\u05E2\u05DF",
-    message: "\u05D0\u05E0\u05D0 \u05E8\u05E2\u05E0\u05DF \u05D0\u05EA \u05D4\u05D3\u05E3 \u05DB\u05D3\u05D9 \u05DC\u05D4\u05DE\u05E9\u05D9\u05DA.",
+    message: "\u05D0\u05E0\u05D0 \u05E8\u05E2\u05E0\u05DF \u05D0\u05EA \u05D4\u05D3\u05E3 \u05DB\u05D3\u05D9 \u05DC\u05D4\u05DE\u05E9\u05D9\u05DA",
     reload: "\u05D8\u05E2\u05DF \u05DE\u05D7\u05D3\u05E9",
     retrying: "\u05E0\u05D9\u05E1\u05D9\u05D5\u05DF \u05D7\u05D5\u05D6\u05E8",
     rtl: true,
@@ -120,7 +120,7 @@ var translations = {
   hr: {
     heading: "Ne\u0161to je po\u0161lo po zlu",
     loading: "U\u010Ditavanje...",
-    message: "Molimo osvje\u017Eite stranicu da biste nastavili.",
+    message: "Molimo osvje\u017Eite stranicu da biste nastavili",
     reload: "Ponovno u\u010Ditaj stranicu",
     retrying: "Poku\u0161aj ponovnog poku\u0161aja",
     tryAgain: "Poku\u0161aj ponovo"
@@ -128,7 +128,7 @@ var translations = {
   hu: {
     heading: "Valami hiba t\xF6rt\xE9nt",
     loading: "Bet\xF6lt\xE9s...",
-    message: "K\xE9rj\xFCk, friss\xEDtse az oldalt a folytat\xE1shoz.",
+    message: "K\xE9rj\xFCk, friss\xEDtse az oldalt a folytat\xE1shoz",
     reload: "Oldal \xFAjrat\xF6lt\xE9se",
     retrying: "\xDAjrapr\xF3b\xE1lkoz\xE1si k\xEDs\xE9rlet",
     tryAgain: "Pr\xF3b\xE1lja \xFAjra"
@@ -136,7 +136,7 @@ var translations = {
   id: {
     heading: "Terjadi kesalahan",
     loading: "Memuat...",
-    message: "Silakan segarkan halaman untuk melanjutkan.",
+    message: "Silakan segarkan halaman untuk melanjutkan",
     reload: "Muat ulang halaman",
     retrying: "Percobaan ulang",
     tryAgain: "Coba lagi"
@@ -144,7 +144,7 @@ var translations = {
   it: {
     heading: "Qualcosa \xE8 andato storto",
     loading: "Caricamento...",
-    message: "Aggiorna la pagina per continuare.",
+    message: "Aggiorna la pagina per continuare",
     reload: "Ricarica pagina",
     retrying: "Tentativo di ripetizione",
     tryAgain: "Riprova"
@@ -152,7 +152,7 @@ var translations = {
   ja: {
     heading: "\u554F\u984C\u304C\u767A\u751F\u3057\u307E\u3057\u305F",
     loading: "\u8AAD\u307F\u8FBC\u307F\u4E2D...",
-    message: "\u30DA\u30FC\u30B8\u3092\u66F4\u65B0\u3057\u3066\u304F\u3060\u3055\u3044\u3002",
+    message: "\u30DA\u30FC\u30B8\u3092\u66F4\u65B0\u3057\u3066\u304F\u3060\u3055\u3044",
     reload: "\u518D\u8AAD\u307F\u8FBC\u307F",
     retrying: "\u30EA\u30C8\u30E9\u30A4",
     tryAgain: "\u3082\u3046\u4E00\u5EA6\u8A66\u3059"
@@ -160,7 +160,7 @@ var translations = {
   ka: {
     heading: "\u10E0\u10D0\u10E6\u10D0\u10EA \u10D0\u10E0\u10D0\u10E1\u10EC\u10DD\u10E0\u10D0\u10D3 \u10DB\u10DD\u10EE\u10D3\u10D0",
     loading: "\u10D8\u10E2\u10D5\u10D8\u10E0\u10D7\u10D4\u10D1\u10D0...",
-    message: "\u10D2\u10D7\u10EE\u10DD\u10D5\u10D7 \u10D2\u10D0\u10DC\u10D0\u10D0\u10EE\u10DA\u10DD\u10D7 \u10D2\u10D5\u10D4\u10E0\u10D3\u10D8 \u10D2\u10D0\u10E1\u10D0\u10D2\u10E0\u10EB\u10D4\u10DA\u10D4\u10D1\u10DA\u10D0\u10D3.",
+    message: "\u10D2\u10D7\u10EE\u10DD\u10D5\u10D7 \u10D2\u10D0\u10DC\u10D0\u10D0\u10EE\u10DA\u10DD\u10D7 \u10D2\u10D5\u10D4\u10E0\u10D3\u10D8 \u10D2\u10D0\u10E1\u10D0\u10D2\u10E0\u10EB\u10D4\u10DA\u10D4\u10D1\u10DA\u10D0\u10D3",
     reload: "\u10D2\u10D5\u10D4\u10E0\u10D3\u10D8\u10E1 \u10D2\u10D0\u10D3\u10D0\u10E2\u10D5\u10D8\u10E0\u10D7\u10D5\u10D0",
     retrying: "\u10D2\u10D0\u10DB\u10D4\u10DD\u10E0\u10D4\u10D1\u10D8\u10E1 \u10DB\u10EA\u10D3\u10D4\u10DA\u10DD\u10D1\u10D0",
     tryAgain: "\u10D9\u10D8\u10D3\u10D4\u10D5 \u10E1\u10EA\u10D0\u10D3\u10D4\u10D7"
@@ -168,7 +168,7 @@ var translations = {
   kk: {
     heading: "\u0411\u0456\u0440\u0434\u0435\u04A3\u0435 \u0434\u04B1\u0440\u044B\u0441 \u0431\u043E\u043B\u043C\u0430\u0434\u044B",
     loading: "\u0416\u04AF\u043A\u0442\u0435\u043B\u0443\u0434\u0435...",
-    message: "\u0416\u0430\u043B\u0493\u0430\u0441\u0442\u044B\u0440\u0443 \u04AF\u0448\u0456\u043D \u0431\u0435\u0442\u0442\u0456 \u0436\u0430\u04A3\u0430\u0440\u0442\u044B\u04A3\u044B\u0437.",
+    message: "\u0416\u0430\u043B\u0493\u0430\u0441\u0442\u044B\u0440\u0443 \u04AF\u0448\u0456\u043D \u0431\u0435\u0442\u0442\u0456 \u0436\u0430\u04A3\u0430\u0440\u0442\u044B\u04A3\u044B\u0437",
     reload: "\u0411\u0435\u0442\u0442\u0456 \u049B\u0430\u0439\u0442\u0430 \u0436\u04AF\u043A\u0442\u0435\u0443",
     retrying: "\u049A\u0430\u0439\u0442\u0430\u043B\u0430\u0443 \u04D9\u0440\u0435\u043A\u0435\u0442\u0456",
     tryAgain: "\u049A\u0430\u0439\u0442\u0430\u043B\u0430\u043F \u043A\u04E9\u0440\u0456\u04A3\u0456\u0437"
@@ -176,7 +176,7 @@ var translations = {
   ko: {
     heading: "\uBB38\uC81C\uAC00 \uBC1C\uC0DD\uD588\uC2B5\uB2C8\uB2E4",
     loading: "\uB85C\uB529 \uC911...",
-    message: "\uD398\uC774\uC9C0\uB97C \uC0C8\uB85C\uACE0\uCE68\uD574 \uC8FC\uC138\uC694.",
+    message: "\uD398\uC774\uC9C0\uB97C \uC0C8\uB85C\uACE0\uCE68\uD574 \uC8FC\uC138\uC694",
     reload: "\uC0C8\uB85C\uACE0\uCE68",
     retrying: "\uC7AC\uC2DC\uB3C4",
     tryAgain: "\uB2E4\uC2DC \uC2DC\uB3C4"
@@ -184,7 +184,7 @@ var translations = {
   ky: {
     heading: "\u0411\u0438\u0440 \u043D\u0435\u0440\u0441\u0435 \u0442\u0443\u0443\u0440\u0430 \u044D\u043C\u0435\u0441 \u0431\u043E\u043B\u0434\u0443",
     loading: "\u0416\u04AF\u043A\u0442\u04E9\u043B\u04AF\u04AF\u0434\u04E9...",
-    message: "\u0423\u043B\u0430\u043D\u0442\u0443\u0443 \u04AF\u0447\u04AF\u043D \u0431\u0430\u0440\u0430\u043A\u0442\u044B \u0436\u0430\u04A3\u044B\u0440\u0442\u044B\u04A3\u044B\u0437.",
+    message: "\u0423\u043B\u0430\u043D\u0442\u0443\u0443 \u04AF\u0447\u04AF\u043D \u0431\u0430\u0440\u0430\u043A\u0442\u044B \u0436\u0430\u04A3\u044B\u0440\u0442\u044B\u04A3\u044B\u0437",
     reload: "\u0411\u0430\u0440\u0430\u043A\u0442\u044B \u043A\u0430\u0439\u0440\u0430 \u0436\u04AF\u043A\u0442\u04E9\u04E9",
     retrying: "\u041A\u0430\u0439\u0442\u0430\u043B\u043E\u043E \u0430\u0440\u0430\u043A\u0435\u0442\u0438",
     tryAgain: "\u041A\u0430\u0439\u0440\u0430 \u0430\u0440\u0430\u043A\u0435\u0442 \u043A\u044B\u043B\u044B\u04A3\u044B\u0437"
@@ -192,7 +192,7 @@ var translations = {
   lt: {
     heading: "Ka\u017Ekas nutiko ne taip",
     loading: "\u012Ekeliama...",
-    message: "Pra\u0161ome atnaujinti puslap\u012F, kad t\u0119stum\u0117te.",
+    message: "Pra\u0161ome atnaujinti puslap\u012F, kad t\u0119stum\u0117te",
     reload: "I\u0161 naujo \u012Fkelti puslap\u012F",
     retrying: "Pakartotinis bandymas",
     tryAgain: "Bandyti dar kart\u0105"
@@ -200,7 +200,7 @@ var translations = {
   lv: {
     heading: "Kaut kas nog\u0101ja greizi",
     loading: "Iel\u0101d\u0113...",
-    message: "L\u016Bdzu, atsvaidziniet lapu, lai turpin\u0101tu.",
+    message: "L\u016Bdzu, atsvaidziniet lapu, lai turpin\u0101tu",
     reload: "P\u0101rl\u0101d\u0113t lapu",
     retrying: "Atk\u0101rtots m\u0113\u0123in\u0101jums",
     tryAgain: "M\u0113\u0123iniet v\u0113lreiz"
@@ -208,7 +208,7 @@ var translations = {
   nl: {
     heading: "Er is iets misgegaan",
     loading: "Laden...",
-    message: "Ververs de pagina om door te gaan.",
+    message: "Ververs de pagina om door te gaan",
     reload: "Pagina herladen",
     retrying: "Opnieuw proberen",
     tryAgain: "Probeer opnieuw"
@@ -216,7 +216,7 @@ var translations = {
   no: {
     heading: "Noe gikk galt",
     loading: "Laster...",
-    message: "Vennligst oppdater siden for \xE5 fortsette.",
+    message: "Vennligst oppdater siden for \xE5 fortsette",
     reload: "Last inn siden p\xE5 nytt",
     retrying: "Nytt fors\xF8k",
     tryAgain: "Pr\xF8v igjen"
@@ -224,7 +224,7 @@ var translations = {
   pl: {
     heading: "Co\u015B posz\u0142o nie tak",
     loading: "\u0141adowanie...",
-    message: "Od\u015Bwie\u017C stron\u0119, aby kontynuowa\u0107.",
+    message: "Od\u015Bwie\u017C stron\u0119, aby kontynuowa\u0107",
     reload: "Prze\u0142aduj stron\u0119",
     retrying: "Pr\xF3ba ponowienia",
     tryAgain: "Spr\xF3buj ponownie"
@@ -232,7 +232,7 @@ var translations = {
   pt: {
     heading: "Algo deu errado",
     loading: "Carregando...",
-    message: "Por favor, atualize a p\xE1gina para continuar.",
+    message: "Por favor, atualize a p\xE1gina para continuar",
     reload: "Recarregar p\xE1gina",
     retrying: "Tentativa de nova tentativa",
     tryAgain: "Tentar novamente"
@@ -240,7 +240,7 @@ var translations = {
   ro: {
     heading: "Ceva nu a mers bine",
     loading: "Se \xEEncarc\u0103...",
-    message: "V\u0103 rug\u0103m s\u0103 re\xEEmprosp\u0103ta\u021Bi pagina pentru a continua.",
+    message: "V\u0103 rug\u0103m s\u0103 re\xEEmprosp\u0103ta\u021Bi pagina pentru a continua",
     reload: "Re\xEEncarc\u0103 pagina",
     retrying: "\xCEncercare de re\xEEncercare",
     tryAgain: "\xCEncearc\u0103 din nou"
@@ -248,7 +248,7 @@ var translations = {
   ru: {
     heading: "\u0427\u0442\u043E-\u0442\u043E \u043F\u043E\u0448\u043B\u043E \u043D\u0435 \u0442\u0430\u043A",
     loading: "\u0417\u0430\u0433\u0440\u0443\u0437\u043A\u0430...",
-    message: "\u041F\u043E\u0436\u0430\u043B\u0443\u0439\u0441\u0442\u0430, \u043E\u0431\u043D\u043E\u0432\u0438\u0442\u0435 \u0441\u0442\u0440\u0430\u043D\u0438\u0446\u0443, \u0447\u0442\u043E\u0431\u044B \u043F\u0440\u043E\u0434\u043E\u043B\u0436\u0438\u0442\u044C.",
+    message: "\u041F\u043E\u0436\u0430\u043B\u0443\u0439\u0441\u0442\u0430, \u043E\u0431\u043D\u043E\u0432\u0438\u0442\u0435 \u0441\u0442\u0440\u0430\u043D\u0438\u0446\u0443, \u0447\u0442\u043E\u0431\u044B \u043F\u0440\u043E\u0434\u043E\u043B\u0436\u0438\u0442\u044C",
     reload: "\u041F\u0435\u0440\u0435\u0437\u0430\u0433\u0440\u0443\u0437\u0438\u0442\u044C \u0441\u0442\u0440\u0430\u043D\u0438\u0446\u0443",
     retrying: "\u041F\u043E\u0432\u0442\u043E\u0440\u043D\u0430\u044F \u043F\u043E\u043F\u044B\u0442\u043A\u0430",
     tryAgain: "\u041F\u043E\u043F\u0440\u043E\u0431\u043E\u0432\u0430\u0442\u044C \u0441\u043D\u043E\u0432\u0430"
@@ -256,7 +256,7 @@ var translations = {
   sk: {
     heading: "Nie\u010Do sa pokazilo",
     loading: "Na\u010D\xEDtava sa...",
-    message: "Obnovte str\xE1nku pros\xEDm pre pokra\u010Dovanie.",
+    message: "Obnovte str\xE1nku pros\xEDm pre pokra\u010Dovanie",
     reload: "Znovu na\u010D\xEDta\u0165 str\xE1nku",
     retrying: "Pokus o opakovanie",
     tryAgain: "Sk\xFAsi\u0165 znova"
@@ -264,7 +264,7 @@ var translations = {
   sl: {
     heading: "Nekaj je \u0161lo narobe",
     loading: "Nalaganje...",
-    message: "Prosimo, osve\u017Eite stran za nadaljevanje.",
+    message: "Prosimo, osve\u017Eite stran za nadaljevanje",
     reload: "Ponovno nalo\u017Ei stran",
     retrying: "Poskus ponovnega poskusa",
     tryAgain: "Poskusi znova"
@@ -272,7 +272,7 @@ var translations = {
   sv: {
     heading: "N\xE5got gick fel",
     loading: "Laddar...",
-    message: "Uppdatera sidan f\xF6r att forts\xE4tta.",
+    message: "Uppdatera sidan f\xF6r att forts\xE4tta",
     reload: "Ladda om sidan",
     retrying: "Nytt f\xF6rs\xF6k",
     tryAgain: "F\xF6rs\xF6k igen"
@@ -288,7 +288,7 @@ var translations = {
   tr: {
     heading: "Bir \u015Feyler ters gitti",
     loading: "Y\xFCkleniyor...",
-    message: "Devam etmek i\xE7in l\xFCtfen sayfay\u0131 yenileyin.",
+    message: "Devam etmek i\xE7in l\xFCtfen sayfay\u0131 yenileyin",
     reload: "Sayfay\u0131 yeniden y\xFCkle",
     retrying: "Yeniden deneme giri\u015Fimi",
     tryAgain: "Tekrar dene"
@@ -296,7 +296,7 @@ var translations = {
   uk: {
     heading: "\u0429\u043E\u0441\u044C \u043F\u0456\u0448\u043B\u043E \u043D\u0435 \u0442\u0430\u043A",
     loading: "\u0417\u0430\u0432\u0430\u043D\u0442\u0430\u0436\u0435\u043D\u043D\u044F...",
-    message: "\u0411\u0443\u0434\u044C \u043B\u0430\u0441\u043A\u0430, \u043E\u043D\u043E\u0432\u0456\u0442\u044C \u0441\u0442\u043E\u0440\u0456\u043D\u043A\u0443, \u0449\u043E\u0431 \u043F\u0440\u043E\u0434\u043E\u0432\u0436\u0438\u0442\u0438.",
+    message: "\u0411\u0443\u0434\u044C \u043B\u0430\u0441\u043A\u0430, \u043E\u043D\u043E\u0432\u0456\u0442\u044C \u0441\u0442\u043E\u0440\u0456\u043D\u043A\u0443, \u0449\u043E\u0431 \u043F\u0440\u043E\u0434\u043E\u0432\u0436\u0438\u0442\u0438",
     reload: "\u041F\u0435\u0440\u0435\u0437\u0430\u0432\u0430\u043D\u0442\u0430\u0436\u0438\u0442\u0438 \u0441\u0442\u043E\u0440\u0456\u043D\u043A\u0443",
     retrying: "\u041F\u043E\u0432\u0442\u043E\u0440\u043D\u0430 \u0441\u043F\u0440\u043E\u0431\u0430",
     tryAgain: "\u0421\u043F\u0440\u043E\u0431\u0443\u0432\u0430\u0442\u0438 \u0437\u043D\u043E\u0432\u0443"
@@ -304,7 +304,7 @@ var translations = {
   zh: {
     heading: "\u51FA\u4E86\u70B9\u95EE\u9898",
     loading: "\u52A0\u8F7D\u4E2D...",
-    message: "\u8BF7\u5237\u65B0\u9875\u9762\u4EE5\u7EE7\u7EED\u3002",
+    message: "\u8BF7\u5237\u65B0\u9875\u9762\u4EE5\u7EE7\u7EED",
     reload: "\u91CD\u65B0\u52A0\u8F7D",
     retrying: "\u91CD\u8BD5\u6B21\u6570",
     tryAgain: "\u91CD\u8BD5"

package/dist/runtime/debug/index.js

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

package/dist/runtime/index.js

@@ -3,19 +3,21 @@ import {
   extractVersionFromHtml,
   getSpinnerHtml,
   showSpinner
-} from "../chunk-QDYSBRW2.js";
+} from "../chunk-T42DLOQP.js";
 import {
   getState,
   subscribeToState
-} from "../chunk-SCBBWARW.js";
+} from "../chunk-IZAXNDHZ.js";
 import {
   ForceRetryError,
   getLogger,
   getOptions,
+  getRetryAttemptFromUrl,
+  getRetrySnapshot,
   markRetryHealthyBoot,
   setTranslations,
   versionCheckStateWindowKey
-} from "../chunk-X6IW7S2K.js";
+} from "../chunk-LIKSIU75.js";
 import "../chunk-MLKGABMK.js";
 
 // src/common/checkVersion.ts
@@ -255,18 +257,120 @@ var stopVersionCheck = () => {
 };
 
 // src/runtime/recommendedSetup.ts
+var AUTO_HEALTHY_BOOT_BUFFER_MS = 1e3;
+var MIN_HEALTHY_BOOT_GRACE_MS = 5e3;
+var setupStateWindowKey = "__spa_guard_runtime_recommended_setup_state__";
+var createFreshState = () => ({
+  cleanup: () => {
+  },
+  initialized: false,
+  timer: null,
+  versionCheckEnabled: false
+});
+var getState3 = () => {
+  if (globalThis.window === void 0) {
+    return createFreshState();
+  }
+  const w = globalThis.window;
+  if (!w[setupStateWindowKey]) {
+    w[setupStateWindowKey] = createFreshState();
+  }
+  return w[setupStateWindowKey];
+};
+var resolveOptions = (overrides) => {
+  const healthyBoot = overrides?.healthyBoot;
+  const versionCheck = overrides?.versionCheck ?? true;
+  const computedGraceMs = computeAutoHealthyBootGraceMs();
+  if (healthyBoot === false || healthyBoot === "off") {
+    return {
+      healthyBootGraceMs: computedGraceMs,
+      healthyBootMode: "off",
+      versionCheck
+    };
+  }
+  if (healthyBoot === "manual") {
+    return {
+      healthyBootGraceMs: computedGraceMs,
+      healthyBootMode: "manual",
+      versionCheck
+    };
+  }
+  if (healthyBoot && typeof healthyBoot === "object") {
+    return {
+      healthyBootGraceMs: Math.max(computedGraceMs, healthyBoot.graceMs ?? computedGraceMs),
+      healthyBootMode: "auto",
+      versionCheck
+    };
+  }
+  return {
+    healthyBootGraceMs: computedGraceMs,
+    healthyBootMode: "auto",
+    versionCheck
+  };
+};
+var computeAutoHealthyBootGraceMs = () => {
+  const options = getOptions();
+  const reloadDelays = options.reloadDelays ?? [1e3, 2e3, 5e3];
+  const lazyRetryDelays = options.lazyRetry?.retryDelays ?? [1e3, 2e3];
+  const maxReloadDelay = Math.max(...reloadDelays, 0);
+  const lazyRetryTotalDelay = lazyRetryDelays.reduce((acc, delay) => acc + delay, 0);
+  return Math.max(
+    MIN_HEALTHY_BOOT_GRACE_MS,
+    maxReloadDelay + AUTO_HEALTHY_BOOT_BUFFER_MS,
+    lazyRetryTotalDelay + AUTO_HEALTHY_BOOT_BUFFER_MS
+  );
+};
+var scheduleAutoHealthyBoot = (graceMs) => {
+  if (globalThis.window === void 0) {
+    return null;
+  }
+  if (getRetryAttemptFromUrl() === null) {
+    return null;
+  }
+  return setTimeout(() => {
+    if (getRetryAttemptFromUrl() === null) {
+      return;
+    }
+    const snapshot = getRetrySnapshot();
+    if (snapshot.phase !== "idle") {
+      return;
+    }
+    markRetryHealthyBoot();
+  }, graceMs);
+};
 var recommendedSetup = (overrides) => {
+  const state = getState3();
+  if (state.initialized) {
+    return state.cleanup;
+  }
   dismissSpinner();
-  markRetryHealthyBoot();
-  const options = { versionCheck: true, ...overrides };
+  const options = resolveOptions(overrides);
   if (options.versionCheck) {
     startVersionCheck();
   }
-  return () => {
-    if (options.versionCheck) {
+  const timer = options.healthyBootMode === "auto" ? scheduleAutoHealthyBoot(options.healthyBootGraceMs) : null;
+  const cleanup = () => {
+    const currentState = getState3();
+    if (!currentState.initialized) {
+      return;
+    }
+    if (currentState.timer !== null) {
+      clearTimeout(currentState.timer);
+    }
+    if (currentState.versionCheckEnabled) {
       stopVersionCheck();
     }
+    if (globalThis.window !== void 0) {
+      globalThis.window[setupStateWindowKey] = createFreshState();
+    }
   };
+  Object.assign(state, {
+    cleanup,
+    initialized: true,
+    timer,
+    versionCheckEnabled: options.versionCheck
+  });
+  return cleanup;
 };
 export {
   ForceRetryError,

package/dist/runtime/recommendedSetup.d.ts

@@ -1,12 +1,36 @@
 export interface RecommendedSetupOptions {
+    /**
+     * Healthy boot handling strategy.
+     *
+     * - `"auto"` (default): if retry URL params are present, mark healthy boot
+     *   after a grace period and only when orchestrator is still idle.
+     * - `"manual"`: never auto-mark; call `markRetryHealthyBoot()` yourself.
+     * - `"off"` / `false`: disable healthy boot handling.
+     */
+    healthyBoot?: RecommendedSetupHealthyBoot;
     /**
      * Whether to start version checking.
      * @default true
      */
     versionCheck?: boolean;
 }
+interface HealthyBootAutoConfig {
+    /**
+     * Delay before auto-marking healthy boot when retry params are present in URL.
+     * @default dynamic:
+     * max(5000, max(reloadDelays)+1000, sum(lazyRetry.retryDelays)+1000)
+     */
+    graceMs?: number;
+    /**
+     * Explicit mode for object config.
+     * @default "auto"
+     */
+    mode?: "auto";
+}
+type RecommendedSetupHealthyBoot = "auto" | "manual" | "off" | false | HealthyBootAutoConfig;
 /**
  * Enable recommended runtime features with sensible defaults.
  * Returns a cleanup function that tears down all started features.
  */
 export declare const recommendedSetup: (overrides?: RecommendedSetupOptions) => (() => void);
+export {};

package/package.json

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