@ovineko/spa-guard 0.0.1-alpha-24 → 0.0.1-alpha-26

package/README.md

@@ -0,0 +1,76 @@
+# @ovineko/spa-guard
+
+[![npm](https://img.shields.io/npm/v/@ovineko/spa-guard)](https://www.npmjs.com/package/@ovineko/spa-guard)
+[![license](https://img.shields.io/npm/l/@ovineko/spa-guard)](./LICENSE)
+
+Core runtime for spa-guard — chunk load error handling, version checking, spinner, i18n, and event schema for SPAs.
+
+## Install
+
+```sh
+npm install @ovineko/spa-guard
+```
+
+## Usage
+
+Call `recommendedSetup` once when your app boots. It dismisses the loading spinner, starts version checking, and returns a cleanup function.
+
+```ts
+import { recommendedSetup } from "@ovineko/spa-guard/runtime";
+
+const cleanup = recommendedSetup();
+// optionally call cleanup() to stop background checks
+```
+
+Disable version checking:
+
+```ts
+const cleanup = recommendedSetup({ versionCheck: false });
+```
+
+## API
+
+### `@ovineko/spa-guard` (common)
+
+- `listen` — subscribe to spa-guard events
+- `events` — event type constants
+- `options` — runtime options helpers
+- `disableDefaultRetry` / `enableDefaultRetry` / `isDefaultRetryEnabled` — control default retry behaviour
+- `BeaconError` — error class for beacon failures
+- `ForceRetryError` — error class to force a retry
+
+### `@ovineko/spa-guard/runtime`
+
+- `recommendedSetup(options?)` — enable recommended runtime features; returns cleanup function
+- `RecommendedSetupOptions` — `{ versionCheck?: boolean }`
+- `startVersionCheck` / `stopVersionCheck` — manual version check control
+- `getState` / `subscribeToState` — runtime state access
+- `SpaGuardState` — state type
+- `showSpinner` / `dismissSpinner` / `getSpinnerHtml` — spinner helpers
+- `setTranslations` — override i18n strings
+- `ForceRetryError`
+
+### `@ovineko/spa-guard/schema`
+
+Schemas for spa-guard configuration.
+
+### `@ovineko/spa-guard/i18n`
+
+Built-in translation strings.
+
+### `@ovineko/spa-guard/runtime/debug`
+
+Debug helpers for testing error scenarios.
+
+## Related packages
+
+- [@ovineko/spa-guard-react](../react/README.md) — `lazyWithRetry` and React error boundary
+- [@ovineko/spa-guard-react-router](../react-router/README.md) — React Router error boundary
+- [@ovineko/spa-guard-vite](../vite/README.md) — Vite plugin (injects runtime script)
+- [@ovineko/spa-guard-node](../node/README.md) — Node.js cache and builder API
+- [@ovineko/spa-guard-fastify](../fastify/README.md) — Fastify plugin
+- [@ovineko/spa-guard-eslint](../eslint/README.md) — ESLint rules
+
+## License
+
+MIT

package/dist/_internal.js

@@ -1,14 +1,14 @@
-import {
-  SPINNER_ID,
-  defaultSpinnerSvg,
-  extractVersionFromHtml
-} from "./chunk-UF7QAEI7.js";
 import {
   createLogger,
   isChunkError,
   listenInternal,
   serializeError
-} from "./chunk-DUR4QNQE.js";
+} from "./chunk-ZVYB2746.js";
+import {
+  SPINNER_ID,
+  defaultSpinnerSvg,
+  extractVersionFromHtml
+} from "./chunk-Z75UPJWV.js";
 import {
   dispatchAsyncRuntimeError,
   dispatchChunkLoadError,
@@ -17,13 +17,13 @@ import {
   dispatchNetworkTimeout,
   dispatchSyncRuntimeError,
   dispatchUnhandledRejection
-} from "./chunk-H4DWKO5I.js";
+} from "./chunk-XFILAQ7P.js";
 import {
   attemptReload,
   sendBeacon,
   shouldForceRetry,
   shouldIgnoreMessages
-} from "./chunk-VZCUDNEG.js";
+} from "./chunk-CSN7MQGX.js";
 import {
   applyI18n,
   debugSyncErrorEventType,
@@ -38,7 +38,7 @@ import {
   isDefaultRetryEnabled,
   optionsWindowKey,
   subscribe
-} from "./chunk-5DE7AKYB.js";
+} from "./chunk-X6E7KUDK.js";
 import "./chunk-MLKGABMK.js";
 
 // src/common/handleErrorWithSpaGuard.ts

package/dist/{chunk-VZCUDNEG.js → chunk-CSN7MQGX.js}

@@ -18,7 +18,7 @@ import {
   setLastReloadTime,
   setLastRetryResetInfo,
   shouldResetRetryCycle
-} from "./chunk-5DE7AKYB.js";
+} from "./chunk-X6E7KUDK.js";
 
 // src/common/shouldIgnore.ts
 var shouldIgnoreMessages = (messages) => {

package/dist/{chunk-CQ5IVYGC.js → chunk-T72DERME.js}

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

package/dist/{chunk-5DE7AKYB.js → chunk-X6E7KUDK.js}

@@ -13,6 +13,7 @@ var initializedKey = /* @__PURE__ */ Symbol.for(`${name}:initialized`);
 var loggerWindowKey = /* @__PURE__ */ Symbol.for(`${name}:logger`);
 var RETRY_ID_PARAM = "spaGuardRetryId";
 var RETRY_ATTEMPT_PARAM = "spaGuardRetryAttempt";
+var versionCheckStateWindowKey = /* @__PURE__ */ Symbol.for(`${name}:version-check-state`);
 var debugSyncErrorEventType = "spa-guard:debug-sync-error";
 
 // src/common/events/internal.ts
@@ -141,6 +142,7 @@ __export(options_exports, {
 });
 var defaultOptions = {
   checkVersion: {
+    cache: "no-store",
     interval: 3e5,
     mode: "html",
     onUpdate: "reload"
@@ -418,6 +420,7 @@ export {
   optionsWindowKey,
   RETRY_ID_PARAM,
   RETRY_ATTEMPT_PARAM,
+  versionCheckStateWindowKey,
   debugSyncErrorEventType,
   setLogger,
   getLogger,

package/dist/{chunk-H4DWKO5I.js → chunk-XFILAQ7P.js}

@@ -1,12 +1,12 @@
 import {
   showFallbackUI
-} from "./chunk-VZCUDNEG.js";
+} from "./chunk-CSN7MQGX.js";
 import {
   ForceRetryError,
   debugSyncErrorEventType,
   emitEvent,
   getOptions
-} from "./chunk-5DE7AKYB.js";
+} from "./chunk-X6E7KUDK.js";
 
 // src/runtime/debug/errorDispatchers.ts
 function dispatchAsyncRuntimeError() {

package/dist/{chunk-UF7QAEI7.js → chunk-Z75UPJWV.js}

@@ -1,7 +1,7 @@
 import {
   defaultSpinnerHtml,
   getOptions
-} from "./chunk-5DE7AKYB.js";
+} from "./chunk-X6E7KUDK.js";
 
 // src/common/parseVersion.ts
 function extractVersionFromHtml(html) {

package/dist/{chunk-DUR4QNQE.js → chunk-ZVYB2746.js}

@@ -3,7 +3,7 @@ import {
   sendBeacon,
   shouldForceRetry,
   shouldIgnoreMessages
-} from "./chunk-VZCUDNEG.js";
+} from "./chunk-CSN7MQGX.js";
 import {
   getLogger,
   getOptions,
@@ -13,7 +13,7 @@ import {
   markInitialized,
   setLogger,
   updateRetryStateInUrl
-} from "./chunk-5DE7AKYB.js";
+} from "./chunk-X6E7KUDK.js";
 
 // src/common/isChunkError.ts
 var isChunkError = (error) => {

package/dist/common/constants.d.ts

@@ -5,4 +5,5 @@ export declare const initializedKey: unique symbol;
 export declare const loggerWindowKey: unique symbol;
 export declare const RETRY_ID_PARAM = "spaGuardRetryId";
 export declare const RETRY_ATTEMPT_PARAM = "spaGuardRetryAttempt";
+export declare const versionCheckStateWindowKey: unique symbol;
 export declare const debugSyncErrorEventType = "spa-guard:debug-sync-error";

package/dist/common/index.js

@@ -2,8 +2,8 @@ import {
   createLogger,
   listenInternal,
   serializeError
-} from "../chunk-DUR4QNQE.js";
-import "../chunk-VZCUDNEG.js";
+} from "../chunk-ZVYB2746.js";
+import "../chunk-CSN7MQGX.js";
 import {
   ForceRetryError,
   disableDefaultRetry,
@@ -12,7 +12,7 @@ import {
   isDefaultRetryEnabled,
   options_exports,
   subscribe
-} from "../chunk-5DE7AKYB.js";
+} from "../chunk-X6E7KUDK.js";
 import {
   __export
 } from "../chunk-MLKGABMK.js";

package/dist/common/options.d.ts

@@ -11,6 +11,13 @@ export interface Options {
      * and dispatches a `spa-guard:version-change` CustomEvent on the window.
      */
     checkVersion?: {
+        /**
+         * Cache mode for the fetch request used to check the version.
+         * - "no-store": Bypass the HTTP cache entirely (default).
+         * - "no-cache": Revalidate with the server before using cached response.
+         * @default "no-store"
+         */
+        cache?: "no-cache" | "no-store";
         /**
          * Endpoint URL for JSON mode version checking.
          * Required when mode is "json".

package/dist/runtime/debug/index.js

@@ -7,14 +7,14 @@ import {
   dispatchRetryExhausted,
   dispatchSyncRuntimeError,
   dispatchUnhandledRejection
-} from "../../chunk-H4DWKO5I.js";
+} from "../../chunk-XFILAQ7P.js";
+import "../../chunk-CSN7MQGX.js";
 import {
   subscribeToState
-} from "../../chunk-CQ5IVYGC.js";
-import "../../chunk-VZCUDNEG.js";
+} from "../../chunk-T72DERME.js";
 import {
   subscribe
-} from "../../chunk-5DE7AKYB.js";
+} from "../../chunk-X6E7KUDK.js";
 import "../../chunk-MLKGABMK.js";
 
 // src/runtime/debug/index.ts

package/dist/runtime/index.js

@@ -3,29 +3,41 @@ import {
   extractVersionFromHtml,
   getSpinnerHtml,
   showSpinner
-} from "../chunk-UF7QAEI7.js";
+} from "../chunk-Z75UPJWV.js";
 import {
   getState,
   subscribeToState
-} from "../chunk-CQ5IVYGC.js";
+} from "../chunk-T72DERME.js";
 import {
   ForceRetryError,
   getLogger,
   getOptions,
-  setTranslations
-} from "../chunk-5DE7AKYB.js";
+  setTranslations,
+  versionCheckStateWindowKey
+} from "../chunk-X6E7KUDK.js";
 import "../chunk-MLKGABMK.js";
 
 // src/common/checkVersion.ts
-var versionCheckInterval = null;
-var versionCheckTimeout = null;
-var lastKnownVersion = null;
-var lastCheckTimestamp = null;
-var visibilityHandler = null;
-var focusHandler = null;
-var blurHandler = null;
-var checkInProgress = false;
-var runEpoch = 0;
+var createInitialState = () => ({
+  blurHandler: null,
+  checkInProgress: false,
+  focusHandler: null,
+  lastCheckTimestamp: null,
+  lastKnownVersion: null,
+  runEpoch: 0,
+  versionCheckInterval: null,
+  versionCheckTimeout: null,
+  visibilityHandler: null
+});
+if (globalThis.window && !globalThis.window[versionCheckStateWindowKey]) {
+  globalThis.window[versionCheckStateWindowKey] = createInitialState();
+}
+var getState2 = () => {
+  if (globalThis.window === void 0) {
+    return createInitialState();
+  }
+  return globalThis.window[versionCheckStateWindowKey] ?? (globalThis.window[versionCheckStateWindowKey] = createInitialState());
+};
 var fetchJsonVersion = async () => {
   const endpoint = getOptions().checkVersion?.endpoint;
   if (!endpoint) {
@@ -33,7 +45,7 @@ var fetchJsonVersion = async () => {
     return null;
   }
   const response = await fetch(endpoint, {
-    cache: "no-store",
+    cache: getOptions().checkVersion?.cache ?? "no-store",
     headers: { Accept: "application/json" }
   });
   if (!response.ok) {
@@ -51,7 +63,7 @@ var fetchHtmlVersion = async () => {
   url.search = "";
   url.hash = "";
   const response = await fetch(url.toString(), {
-    cache: "no-store",
+    cache: getOptions().checkVersion?.cache ?? "no-store",
     headers: { Accept: "text/html" }
   });
   if (!response.ok) {
@@ -83,44 +95,47 @@ var onVersionChange = (oldVersion, latestVersion) => {
   }
 };
 var checkVersionOnce = async (mode) => {
-  if (checkInProgress) {
+  const s = getState2();
+  if (s.checkInProgress) {
     return;
   }
-  checkInProgress = true;
-  const epochAtStart = runEpoch;
+  s.checkInProgress = true;
+  const epochAtStart = s.runEpoch;
   try {
     const remoteVersion = await fetchRemoteVersion(mode);
-    if (epochAtStart !== runEpoch) {
+    if (epochAtStart !== s.runEpoch) {
       return;
     }
-    if (remoteVersion && remoteVersion !== lastKnownVersion) {
-      const oldVersion = lastKnownVersion;
-      lastKnownVersion = remoteVersion;
+    if (remoteVersion && remoteVersion !== s.lastKnownVersion) {
+      const oldVersion = s.lastKnownVersion;
+      s.lastKnownVersion = remoteVersion;
       onVersionChange(oldVersion, remoteVersion);
     }
   } catch (error) {
     getLogger()?.versionCheckFailed(error);
   } finally {
-    if (epochAtStart === runEpoch) {
-      checkInProgress = false;
+    if (epochAtStart === s.runEpoch) {
+      s.checkInProgress = false;
     }
   }
 };
 var startPolling = (mode, interval) => {
+  const s = getState2();
   clearTimers();
-  versionCheckInterval = setInterval(async () => {
-    lastCheckTimestamp = Date.now();
+  s.versionCheckInterval = setInterval(async () => {
+    s.lastCheckTimestamp = Date.now();
     await checkVersionOnce(mode);
   }, interval);
 };
 var clearTimers = () => {
-  if (versionCheckInterval !== null) {
-    clearInterval(versionCheckInterval);
-    versionCheckInterval = null;
+  const s = getState2();
+  if (s.versionCheckInterval !== null) {
+    clearInterval(s.versionCheckInterval);
+    s.versionCheckInterval = null;
   }
-  if (versionCheckTimeout !== null) {
-    clearTimeout(versionCheckTimeout);
-    versionCheckTimeout = null;
+  if (s.versionCheckTimeout !== null) {
+    clearTimeout(s.versionCheckTimeout);
+    s.versionCheckTimeout = null;
   }
 };
 var handleVisibilityHidden = () => {
@@ -128,22 +143,23 @@ var handleVisibilityHidden = () => {
   getLogger()?.versionCheckPaused();
 };
 var handleResume = (mode, interval) => {
-  if (versionCheckInterval !== null || versionCheckTimeout !== null) {
+  const s = getState2();
+  if (s.versionCheckInterval !== null || s.versionCheckTimeout !== null) {
     return;
   }
-  const elapsed = Date.now() - (lastCheckTimestamp ?? 0);
+  const elapsed = Date.now() - (s.lastCheckTimestamp ?? 0);
   if (elapsed >= interval) {
     getLogger()?.versionCheckResumedImmediate();
-    lastCheckTimestamp = Date.now();
+    s.lastCheckTimestamp = Date.now();
     void checkVersionOnce(mode);
     startPolling(mode, interval);
     return;
   }
   getLogger()?.versionCheckResumed();
   const remaining = interval - elapsed;
-  versionCheckTimeout = setTimeout(() => {
-    versionCheckTimeout = null;
-    lastCheckTimestamp = Date.now();
+  s.versionCheckTimeout = setTimeout(() => {
+    s.versionCheckTimeout = null;
+    s.lastCheckTimestamp = Date.now();
     void checkVersionOnce(mode);
     startPolling(mode, interval);
   }, remaining);
@@ -157,57 +173,62 @@ var startVersionCheck = () => {
     getLogger()?.versionCheckDisabled();
     return;
   }
-  if (versionCheckInterval !== null || visibilityHandler !== null) {
+  const s = getState2();
+  if (s.versionCheckInterval !== null || s.visibilityHandler !== null) {
     getLogger()?.versionCheckAlreadyRunning();
     return;
   }
-  runEpoch++;
-  lastKnownVersion = options.version;
+  s.runEpoch++;
+  s.lastKnownVersion = options.version;
   const interval = options.checkVersion?.interval ?? 3e5;
   const mode = options.checkVersion?.mode ?? "html";
-  getLogger()?.versionCheckStarted(mode, interval, lastKnownVersion);
+  getLogger()?.versionCheckStarted(mode, interval, s.lastKnownVersion);
   const isTabVisible = document.visibilityState === "visible";
   const isWindowFocused = document.hasFocus();
   if (isTabVisible && isWindowFocused) {
-    lastCheckTimestamp = Date.now();
+    s.lastCheckTimestamp = Date.now();
     startPolling(mode, interval);
   } else {
-    lastCheckTimestamp = 0;
+    s.lastCheckTimestamp = 0;
     getLogger()?.versionCheckPaused();
   }
-  visibilityHandler = () => {
+  s.visibilityHandler = () => {
     if (document.visibilityState === "hidden") {
       handleVisibilityHidden();
     } else {
       handleResume(mode, interval);
     }
   };
-  focusHandler = () => {
+  s.focusHandler = () => {
     handleResume(mode, interval);
   };
-  blurHandler = () => {
+  s.blurHandler = () => {
     handleVisibilityHidden();
   };
-  document.addEventListener("visibilitychange", visibilityHandler);
-  globalThis.addEventListener("focus", focusHandler);
-  globalThis.addEventListener("blur", blurHandler);
+  document.addEventListener("visibilitychange", s.visibilityHandler);
+  globalThis.addEventListener("focus", s.focusHandler);
+  globalThis.addEventListener("blur", s.blurHandler);
 };
 var stopVersionCheck = () => {
-  runEpoch++;
-  checkInProgress = false;
-  const wasRunning = versionCheckInterval !== null || versionCheckTimeout !== null || visibilityHandler !== null;
+  if (globalThis.window === void 0) {
+    return;
+  }
+  const s = getState2();
+  s.runEpoch++;
+  s.checkInProgress = false;
+  const wasRunning = s.versionCheckInterval !== null || s.versionCheckTimeout !== null || s.visibilityHandler !== null;
   clearTimers();
-  if (visibilityHandler !== null) {
-    document.removeEventListener("visibilitychange", visibilityHandler);
-    visibilityHandler = null;
+  if (s.visibilityHandler !== null) {
+    document.removeEventListener("visibilitychange", s.visibilityHandler);
+    s.visibilityHandler = null;
   }
-  if (focusHandler !== null) {
-    globalThis.removeEventListener("focus", focusHandler);
-    focusHandler = null;
+  if (s.focusHandler !== null) {
+    globalThis.removeEventListener("focus", s.focusHandler);
+    s.focusHandler = null;
   }
-  if (blurHandler !== null) {
-    globalThis.removeEventListener("blur", blurHandler);
-    blurHandler = null;
+  if (s.blurHandler !== null) {
+    globalThis.removeEventListener("blur", s.blurHandler);
+    s.blurHandler = null;
   }
   if (wasRunning) {
     getLogger()?.versionCheckStopped();

package/package.json

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