@ovineko/spa-guard 0.0.1-alpha-1 → 0.0.1-alpha-2

package/README.md

@@ -14,13 +14,18 @@ Peer dependencies vary by integration - see sections below for specific requirem
 
 - ✅ **Automatic chunk load error detection** - Handles `vite:preloadError`, dynamic imports, and chunk failures across Chrome, Firefox, and Safari
 - ✅ **Intelligent retry with cache busting** - Uses query parameters with UUID to bypass HTML cache after deployments
+- ✅ **Smart retry cycle reset** - Automatically resets retry cycle when enough time has passed since last reload
 - ✅ **Configurable retry delays** - Flexible delay arrays (e.g., `[1000, 2000, 5000]`) instead of simple max attempts
+- ✅ **Infinite loop protection** - Prevents rapid retry resets with configurable minimum time between resets
 - ✅ **Graceful fallback UI** - Shows user-friendly error screen after all retry attempts are exhausted
+- ✅ **Configurable injection target** - Inject fallback UI into any element via CSS selector (default: `body`)
+- ✅ **Error filtering** - Filter out specific errors from logging and reporting via `ignoredErrors` option
 - ✅ **Deep error serialization** - Captures detailed error information for server-side analysis
 - ✅ **Smart beacon reporting** - Sends error reports only after retry exhaustion to prevent spam
-- ✅ **Dual build system** - Production minified (5KB) and trace verbose (10KB) builds for different environments
+- ✅ **Dual build system** - Production minified (~5.9 KB) and trace minified (~7.3 KB) builds for different environments
 - ✅ **Global error listeners** - Captures `error`, `unhandledrejection`, and `securitypolicyviolation` events
 - ✅ **Vite plugin for inline script injection** - Runs before all chunks to catch early errors
+- ✅ **HTML minification** - Automatically minifies fallback HTML to reduce bundle size
 - ✅ **Fastify server integration** - Ready-to-use plugin for handling error reports
 - ✅ **React Router v7 integration** - Works seamlessly with React Router error boundaries
 - ✅ **TypeScript support** - Full type definitions with all exports
@@ -41,18 +46,22 @@ export default defineConfig({
     spaGuardVitePlugin({
       // Production configuration
       reloadDelays: [1000, 2000, 5000], // 3 attempts with increasing delays
-      fallbackHtml: `
-        <div style="display:flex;align-items:center;justify-content:center;height:100vh;font-family:sans-serif">
-          <div style="text-align:center">
-            <h1>Something went wrong</h1>
-            <p>Please refresh the page to continue.</p>
-            <button onclick="location.reload()">Refresh Page</button>
+      fallback: {
+        html: `
+          <div style="display:flex;align-items:center;justify-content:center;height:100vh;font-family:sans-serif">
+            <div style="text-align:center">
+              <h1>Something went wrong</h1>
+              <p>Please refresh the page to continue.</p>
+              <button onclick="location.reload()">Refresh Page</button>
+            </div>
           </div>
-        </div>
-      `,
+        `,
+        selector: "body", // CSS selector where to inject fallback UI (default: "body")
+      },
       reportBeacon: {
         endpoint: "/api/beacon",
       },
+      ignoredErrors: [], // Filter out specific error messages from reporting
       useRetryId: true, // Use query parameters for cache busting (default: true)
     }),
     react(),
@@ -131,6 +140,48 @@ reloadDelays: [1000, 2000, 5000]; // Default
 - **Attempt 3**: Wait 5000ms (5s) → reload with `?spaGuardRetryAttempt=3`
 - **Exhausted**: Show fallback UI, send beacon to server
 
+### Smart Retry Cycle Reset
+
+When `enableRetryReset: true` (default), spa-guard automatically resets the retry cycle if enough time has passed since the last reload. This prevents retry attempts from accumulating unnecessarily.
+
+**How it works:**
+
+1. User is on `?spaGuardRetryAttempt=2` after waiting 2 seconds for a reload
+2. User successfully uses the app for 5 seconds (longer than the retry delay)
+3. A new error occurs
+4. Instead of continuing to attempt 3, spa-guard:
+   - Clears retry parameters from URL (without page reload)
+   - Starts a fresh retry cycle from attempt 0
+   - Generates a new retry ID
+
+**Benefits:**
+
+- Clean URLs when retries are successful
+- Each error context gets its own independent retry cycle
+- Better user experience for long-running sessions
+
+**Infinite loop protection:**
+
+The `minTimeBetweenResets` option (default: 5000ms) prevents infinite reset loops by ensuring a reset can only happen if the previous reset was at least this many milliseconds ago.
+
+**Example:**
+
+```typescript
+spaGuardVitePlugin({
+  enableRetryReset: true, // Enable smart reset (default)
+  minTimeBetweenResets: 5000, // Minimum 5s between resets (default)
+  reloadDelays: [1000, 2000, 5000],
+});
+```
+
+**Disable if needed:**
+
+```typescript
+spaGuardVitePlugin({
+  enableRetryReset: false, // Keep old behavior - retry params persist
+});
+```
+
 ### Secure Random ID Generation
 
 Three-tier fallback chain for maximum compatibility:
@@ -152,14 +203,22 @@ spaGuardVitePlugin({
   // Retry configuration
   reloadDelays: [1000, 2000, 5000], // Array of delays in milliseconds
   useRetryId: true, // Use query parameters for cache busting (default: true)
+  enableRetryReset: true, // Auto-reset retry cycle when enough time passes (default: true)
+  minTimeBetweenResets: 5000, // Min time between retry resets in ms (default: 5000)
 
   // Fallback UI configuration
-  fallbackHtml: `
-    <div style="...">
-      <h1>Something went wrong</h1>
-      <button onclick="location.reload()">Refresh</button>
-    </div>
-  `,
+  fallback: {
+    html: `
+      <div style="...">
+        <h1>Something went wrong</h1>
+        <button onclick="location.reload()">Refresh</button>
+      </div>
+    `,
+    selector: "body", // CSS selector for injection target (default: "body")
+  },
+
+  // Error filtering
+  ignoredErrors: [], // Array of error message substrings to ignore
 
   // Beacon reporting
   reportBeacon: {
@@ -185,7 +244,16 @@ spaGuardVitePlugin({
 interface Options {
   reloadDelays?: number[]; // Array of retry delays in ms (default: [1000, 2000, 5000])
   useRetryId?: boolean; // Use query params for cache busting (default: true)
-  fallbackHtml?: string; // Custom error UI HTML (default: basic error screen)
+  enableRetryReset?: boolean; // Auto-reset retry cycle when enough time passes (default: true)
+  minTimeBetweenResets?: number; // Min time between retry resets to prevent loops (default: 5000)
+
+  fallback?: {
+    html?: string; // Custom error UI HTML (default: basic error screen)
+    selector?: string; // CSS selector for injection target (default: "body")
+  };
+
+  ignoredErrors?: string[]; // Error message substrings to filter out (default: [])
+
   reportBeacon?: {
     endpoint?: string; // Server endpoint for beacon reports
   };
@@ -202,15 +270,21 @@ interface VitePluginOptions extends Options {
 {
   reloadDelays: [1000, 2000, 5000],
   useRetryId: true,
-  fallbackHtml: `
-    <div style="display:flex;align-items:center;justify-content:center;height:100vh;font-family:sans-serif">
-      <div style="text-align:center">
-        <h1>Something went wrong</h1>
-        <p>Please refresh the page to continue.</p>
-        <button onclick="location.reload()">Refresh Page</button>
+  enableRetryReset: true,
+  minTimeBetweenResets: 5000,
+  fallback: {
+    html: `
+      <div style="display:flex;align-items:center;justify-content:center;height:100vh;font-family:sans-serif">
+        <div style="text-align:center">
+          <h1>Something went wrong</h1>
+          <p>Please refresh the page to continue.</p>
+          <button onclick="location.reload()">Refresh Page</button>
+        </div>
       </div>
-    </div>
-  `,
+    `,
+    selector: "body",
+  },
+  ignoredErrors: [],
 }
 ```
 
@@ -479,12 +553,21 @@ interface FastifySPAGuardOptions {
 
 ```typescript
 interface Options {
-  fallbackHtml?: string; // Custom error UI HTML
   reloadDelays?: number[]; // Retry delays in ms (default: [1000, 2000, 5000])
+  useRetryId?: boolean; // Use query params for cache busting (default: true)
+  enableRetryReset?: boolean; // Auto-reset retry cycle when enough time passes (default: true)
+  minTimeBetweenResets?: number; // Min time between retry resets in ms (default: 5000)
+
+  fallback?: {
+    html?: string; // Custom error UI HTML
+    selector?: string; // CSS selector for injection target (default: "body")
+  };
+
+  ignoredErrors?: string[]; // Error message substrings to filter out (default: [])
+
   reportBeacon?: {
     endpoint?: string; // Error reporting endpoint
   };
-  useRetryId?: boolean; // Use query params for cache busting (default: true)
 }
 ```
 
@@ -528,15 +611,46 @@ From `@ovineko/spa-guard/schema/parse`:
 
 - `parseBeacon(data)` - Parse and validate beacon data
 
+### Runtime Exports
+
+From `@ovineko/spa-guard/runtime`:
+
+- `getState()` - Get current spa-guard state (currentAttempt, isFallbackShown, isWaiting, lastRetryResetTime, lastResetRetryId)
+- `subscribeToState(callback)` - Subscribe to state changes, returns unsubscribe function
+- `SpaGuardState` - TypeScript type for state object
+
+**Example:**
+
+```typescript
+import { getState, subscribeToState } from "@ovineko/spa-guard/runtime";
+
+// Get current state
+const state = getState();
+console.log("Current attempt:", state.currentAttempt);
+console.log("Is fallback shown:", state.isFallbackShown);
+console.log("Is waiting for retry:", state.isWaiting);
+console.log("Last retry reset time:", state.lastRetryResetTime);
+console.log("Last reset retry ID:", state.lastResetRetryId);
+
+// Subscribe to state changes
+const unsubscribe = subscribeToState((state) => {
+  console.log("State changed:", state);
+});
+
+// Later: unsubscribe
+unsubscribe();
+```
+
 ## Module Exports
 
-spa-guard provides 8 export entry points:
+spa-guard provides 9 export entry points:
 
 | Export                   | Description                                  | Peer Dependencies                      |
 | ------------------------ | -------------------------------------------- | -------------------------------------- |
 | `.`                      | Core functionality (events, listen, options) | None                                   |
 | `./schema`               | BeaconSchema type definitions                | `typebox@^1`                           |
 | `./schema/parse`         | Beacon parsing utilities                     | `typebox@^1`                           |
+| `./runtime`              | Runtime state management and subscriptions   | None                                   |
 | `./react`                | React integration (placeholder)              | `react@^19`                            |
 | `./react-router`         | React Router integration                     | `react@^19`, `react-router@^7`         |
 | `./fastify`              | Fastify server plugin                        | None                                   |
@@ -561,8 +675,8 @@ import { fastifySPAGuard } from "@ovineko/spa-guard/fastify";
 
 ## Build Sizes
 
-- **Production:** `dist-inline/index.js` ~5KB minified (Terser)
-- **Trace:** `dist-inline-trace/index.js` ~10KB unminified (debug)
+- **Production:** `dist-inline/index.js` ~5.9 KB minified (Terser)
+- **Trace:** `dist-inline-trace/index.js` ~7.3 KB minified (Terser)
 - **Main library:** `dist/` varies by export
 
 ## Advanced Usage
@@ -582,58 +696,98 @@ spaGuardVitePlugin({
 
 ### Custom Fallback UI
 
-Provide fully custom HTML for error screen (injected into `document.body`):
+Provide fully custom HTML for error screen:
 
 ```typescript
 spaGuardVitePlugin({
-  fallbackHtml: `
-    <style>
-      .spa-guard-error {
-        font-family: system-ui, -apple-system, sans-serif;
-        background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
-        color: white;
-        display: flex;
-        align-items: center;
-        justify-content: center;
-        height: 100vh;
-        margin: 0;
-        padding: 20px;
-        box-sizing: border-box;
-      }
-      .spa-guard-container {
-        max-width: 500px;
-        text-align: center;
-        background: rgba(255, 255, 255, 0.1);
-        backdrop-filter: blur(10px);
-        padding: 40px;
-        border-radius: 20px;
-      }
-      .spa-guard-button {
-        background: white;
-        color: #667eea;
-        border: none;
-        padding: 12px 24px;
-        font-size: 16px;
-        font-weight: 600;
-        border-radius: 8px;
-        cursor: pointer;
-        margin-top: 20px;
-      }
-      .spa-guard-button:hover {
-        transform: scale(1.05);
-      }
-    </style>
-    <div class="spa-guard-error">
-      <div class="spa-guard-container">
-        <h1>⚠️ Application Error</h1>
-        <p>We're experiencing technical difficulties. Please try reloading the page.</p>
-        <button class="spa-guard-button" onclick="location.reload()">Reload Application</button>
+  fallback: {
+    html: `
+      <style>
+        .spa-guard-error {
+          font-family: system-ui, -apple-system, sans-serif;
+          background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+          color: white;
+          display: flex;
+          align-items: center;
+          justify-content: center;
+          height: 100vh;
+          margin: 0;
+          padding: 20px;
+          box-sizing: border-box;
+        }
+        .spa-guard-container {
+          max-width: 500px;
+          text-align: center;
+          background: rgba(255, 255, 255, 0.1);
+          backdrop-filter: blur(10px);
+          padding: 40px;
+          border-radius: 20px;
+        }
+        .spa-guard-button {
+          background: white;
+          color: #667eea;
+          border: none;
+          padding: 12px 24px;
+          font-size: 16px;
+          font-weight: 600;
+          border-radius: 8px;
+          cursor: pointer;
+          margin-top: 20px;
+        }
+        .spa-guard-button:hover {
+          transform: scale(1.05);
+        }
+      </style>
+      <div class="spa-guard-error">
+        <div class="spa-guard-container">
+          <h1>⚠️ Application Error</h1>
+          <p>We're experiencing technical difficulties. Please try reloading the page.</p>
+          <button class="spa-guard-button" onclick="location.reload()">Reload Application</button>
+        </div>
       </div>
-    </div>
-  `,
+    `,
+    selector: "body", // Inject into document.body
+  },
+});
+```
+
+### Custom Injection Target
+
+Inject fallback UI into a specific element instead of `<body>`:
+
+```typescript
+spaGuardVitePlugin({
+  fallback: {
+    html: `<div>Error occurred. <button onclick="location.reload()">Retry</button></div>`,
+    selector: "#app", // Inject into <div id="app">
+  },
 });
 ```
 
+### Error Filtering
+
+Filter out specific errors from being logged or reported:
+
+```typescript
+spaGuardVitePlugin({
+  ignoredErrors: [
+    "ResizeObserver loop", // Ignore benign ResizeObserver errors
+    "Non-Error promise rejection", // Ignore specific promise rejections
+    "Script error", // Ignore generic script errors from third-party scripts
+  ],
+  reportBeacon: {
+    endpoint: "/api/beacon",
+  },
+});
+```
+
+**How it works:**
+
+- Errors containing any of the `ignoredErrors` substrings will not be logged to console
+- Beacons for filtered errors will not be sent to the server
+- Useful for filtering out known benign errors or third-party script noise
+- Case-sensitive substring matching
+
 ### Custom Retry Strategy
 
 Adjust retry delays for different environments:

package/dist/chunk-66I6YML2.js

@@ -0,0 +1,17 @@
+import {
+  name
+} from "./chunk-RP52SPBK.js";
+
+// src/common/constants.ts
+var optionsWindowKey = "__SPA_GUARD_OPTIONS__";
+var eventSubscribersWindowKey = /* @__PURE__ */ Symbol.for(`${name}:event-subscribers`);
+var internalConfigWindowKey = /* @__PURE__ */ Symbol.for(`${name}:internal-config`);
+var RETRY_ID_PARAM = "spaGuardRetryId";
+var RETRY_ATTEMPT_PARAM = "spaGuardRetryAttempt";
+
+export {
+  optionsWindowKey,
+  eventSubscribersWindowKey,
+  RETRY_ID_PARAM,
+  RETRY_ATTEMPT_PARAM
+};

package/dist/chunk-7HWVSDJZ.js

@@ -0,0 +1,17 @@
+// src/schema/index.ts
+import { Type } from "typebox";
+var beaconSchema = Type.Object(
+  {
+    errorMessage: Type.Optional(Type.String()),
+    eventMessage: Type.Optional(Type.String()),
+    eventName: Type.Optional(Type.String()),
+    retryAttempt: Type.Optional(Type.Number()),
+    retryId: Type.Optional(Type.String()),
+    serialized: Type.Optional(Type.String())
+  },
+  { additionalProperties: false }
+);
+
+export {
+  beaconSchema
+};

package/dist/chunk-AB733L4R.js

@@ -0,0 +1,19 @@
+import {
+  beaconSchema
+} from "./chunk-7HWVSDJZ.js";
+
+// src/schema/parse.ts
+import { Value } from "typebox/value";
+var parseBeacon = (value) => {
+  const cleaned = Value.Clean(beaconSchema, value);
+  const isValid = Value.Check(beaconSchema, cleaned);
+  if (!isValid) {
+    const errors = [...Value.Errors(beaconSchema, cleaned)];
+    throw new Error(`Beacon validation failed: ${JSON.stringify(errors)}`);
+  }
+  return cleaned;
+};
+
+export {
+  parseBeacon
+};

package/dist/{chunk-VWV6L4Q2.js → chunk-FQCDQYOP.js}

@@ -1,17 +1,10 @@
+import {
+  optionsWindowKey
+} from "./chunk-66I6YML2.js";
 import {
   __export
 } from "./chunk-MLKGABMK.js";
 
-// package.json
-var name = "@ovineko/spa-guard";
-
-// src/common/constants.ts
-var optionsWindowKey = "__SPA_GUARD_OPTIONS__";
-var eventSubscribersWindowKey = /* @__PURE__ */ Symbol.for(`${name}:event-subscribers`);
-var internalConfigWindowKey = /* @__PURE__ */ Symbol.for(`${name}:internal-config`);
-var RETRY_ID_PARAM = "spaGuardRetryId";
-var RETRY_ATTEMPT_PARAM = "spaGuardRetryAttempt";
-
 // src/common/options.ts
 var options_exports = {};
 __export(options_exports, {
@@ -20,11 +13,17 @@ __export(options_exports, {
 });
 
 // src/common/fallbackHtml.generated.ts
-var defaultFallbackHtml = `<div style="display:flex;align-items:center;justify-content:center;height:100vh;font-family:sans-serif"><div style="text-align:center"><h1>Something went wrong</h1><p>Please refresh the page to continue.</p><button onclick="location.reload()">Refresh Page</button></div></div>`;
+var defaultFallbackHtml = `<div style="display:flex;align-items:center;justify-content:center;height:100vh;font-family:sans-serif"><div style="text-align:center"><h1>Something went wrong</h1><p>Please refresh the page to continue.</p><button onclick="location.reload()">Refresh Page</button><p style="margin-top:20px;font-size:12px;color:#999">Error ID: <span class="spa-guard-retry-id"></span></p></div></div>`;
 
 // src/common/options.ts
 var defaultOptions = {
-  fallbackHtml: defaultFallbackHtml,
+  enableRetryReset: true,
+  fallback: {
+    html: defaultFallbackHtml,
+    selector: "body"
+  },
+  ignoredErrors: [],
+  minTimeBetweenResets: 5e3,
   reloadDelays: [1e3, 2e3, 5e3],
   useRetryId: true
 };
@@ -33,6 +32,10 @@ var getOptions = () => {
   return {
     ...defaultOptions,
     ...windowOptions,
+    fallback: {
+      ...defaultOptions.fallback,
+      ...windowOptions?.fallback
+    },
     reportBeacon: {
       ...defaultOptions.reportBeacon,
       ...windowOptions?.reportBeacon
@@ -41,11 +44,6 @@ var getOptions = () => {
 };
 
 export {
-  name,
-  optionsWindowKey,
-  eventSubscribersWindowKey,
-  RETRY_ID_PARAM,
-  RETRY_ATTEMPT_PARAM,
   getOptions,
   options_exports
 };

package/dist/chunk-KHXP4ZNT.js

@@ -0,0 +1,104 @@
+import {
+  getLastRetryResetInfo,
+  getRetryStateFromUrl,
+  subscribe
+} from "./chunk-Z3Y4C3HZ.js";
+
+// src/runtime/state.ts
+var getInitialStateFromUrl = () => {
+  const resetInfo = getLastRetryResetInfo();
+  if (globalThis.window === void 0) {
+    return {
+      currentAttempt: 0,
+      isFallbackShown: false,
+      isWaiting: false,
+      lastResetRetryId: resetInfo?.previousRetryId,
+      lastRetryResetTime: resetInfo?.timestamp
+    };
+  }
+  const retryState = getRetryStateFromUrl();
+  if (!retryState) {
+    return {
+      currentAttempt: 0,
+      isFallbackShown: false,
+      isWaiting: false,
+      lastResetRetryId: resetInfo?.previousRetryId,
+      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,
+    isWaiting: false,
+    lastResetRetryId: resetInfo?.previousRetryId,
+    lastRetryResetTime: resetInfo?.timestamp
+  };
+};
+var currentState = getInitialStateFromUrl();
+var stateSubscribers = /* @__PURE__ */ new Set();
+var updateState = (nextState) => {
+  currentState = nextState;
+  stateSubscribers.forEach((cb) => cb(currentState));
+};
+subscribe((event) => {
+  switch (event.name) {
+    case "fallback-ui-shown": {
+      updateState({
+        ...currentState,
+        isFallbackShown: true
+      });
+      break;
+    }
+    case "retry-attempt": {
+      updateState({
+        ...currentState,
+        currentAttempt: event.attempt,
+        isFallbackShown: false,
+        isWaiting: true
+      });
+      break;
+    }
+    case "retry-exhausted": {
+      updateState({
+        ...currentState,
+        currentAttempt: event.finalAttempt,
+        isFallbackShown: false,
+        isWaiting: false
+      });
+      break;
+    }
+    case "retry-reset": {
+      updateState({
+        ...currentState,
+        currentAttempt: 0,
+        isFallbackShown: false,
+        isWaiting: false,
+        lastResetRetryId: event.previousRetryId,
+        lastRetryResetTime: Date.now()
+      });
+      break;
+    }
+  }
+});
+var getState = () => currentState;
+var subscribeToState = (cb) => {
+  cb(currentState);
+  stateSubscribers.add(cb);
+  return () => {
+    stateSubscribers.delete(cb);
+  };
+};
+
+export {
+  getState,
+  subscribeToState
+};

package/dist/chunk-RP52SPBK.js

@@ -0,0 +1,6 @@
+// package.json
+var name = "@ovineko/spa-guard";
+
+export {
+  name
+};