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

package/README.md

@@ -10,6 +10,8 @@ pnpm add @ovineko/spa-guard
 
 Peer dependencies vary by integration - see sections below for specific requirements.
 
+> **Alpha software:** This package is in active development (`0.0.1-alpha`). The public API may change between versions without migration guides. This README always reflects the current state.
+
 ## Features
 
 - ✅ **Automatic chunk load error detection** - Handles `vite:preloadError`, dynamic imports, and chunk failures across Chrome, Firefox, and Safari
@@ -19,10 +21,10 @@ Peer dependencies vary by integration - see sections below for specific requirem
 - ✅ **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
+- ✅ **Error filtering** - Filter out specific errors via `errors.ignore`, or force retry/reload via `errors.forceRetry`
 - ✅ **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 (~5.9 KB) and trace minified (~7.3 KB) builds for different environments
+- ✅ **Dual build system** - Production minified (~8.3 KB) and trace minified (~13.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
@@ -30,6 +32,11 @@ Peer dependencies vary by integration - see sections below for specific requirem
 - ✅ **React Router v7 integration** - Works seamlessly with React Router error boundaries
 - ✅ **TypeScript support** - Full type definitions with all exports
 - ✅ **Framework-agnostic core** - Works with or without React
+- ✅ **lazyWithRetry** - Drop-in React.lazy replacement with automatic module-level retry before page reload
+- ✅ **Version checker** - Proactive new-deployment detection via HTML or JSON polling
+- ✅ **Event hooks** - React hooks for subscribing to spa-guard events (`useSPAGuardEvents`, `useSPAGuardChunkError`)
+- ✅ **Retry control** - Programmatic control over default retry behavior (`disableDefaultRetry`, `enableDefaultRetry`)
+- ✅ **ESLint plugin** - Enforces usage of spa-guard wrappers instead of direct React imports
 
 ## Quick Start
 
@@ -46,22 +53,27 @@ export default defineConfig({
     spaGuardVitePlugin({
       // Production configuration
       reloadDelays: [1000, 2000, 5000], // 3 attempts with increasing delays
-      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>
+      html: {
+        fallback: {
+          content: `
+            <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")
+          `,
+          selector: "body", // CSS selector where to inject fallback UI (default: "body")
+        },
       },
       reportBeacon: {
         endpoint: "/api/beacon",
       },
-      ignoredErrors: [], // Filter out specific error messages from reporting
+      errors: {
+        ignore: [], // Filter out specific error messages from reporting
+        forceRetry: [], // Custom error messages that trigger retry/reload (like chunk errors)
+      },
       useRetryId: true, // Use query parameters for cache busting (default: true)
     }),
     react(),
@@ -76,7 +88,7 @@ export default defineConfig({
 export default defineConfig({
   plugins: [
     spaGuardVitePlugin({
-      trace: true, // Enable verbose logging (10KB instead of 5KB)
+      trace: true, // Enable verbose logging (~13KB instead of ~8KB)
       reloadDelays: [1000, 2000],
       reportBeacon: { endpoint: "/api/beacon" },
     }),
@@ -85,6 +97,39 @@ export default defineConfig({
 });
 ```
 
+### Testing
+
+Console logs are suppressed by default during tests to keep the output clean and readable. This makes it easier to identify which tests passed or failed.
+
+To run tests with console output visible (useful for debugging):
+
+```bash
+# Run tests with console logs enabled
+DEBUG=true pnpm test
+
+# Or use the convenience script
+pnpm test:debug
+
+# Watch mode with console logs
+pnpm test:debug:watch
+```
+
+Other test commands:
+
+```bash
+# Run tests (clean output, no console logs)
+pnpm test
+
+# Watch mode (clean output)
+pnpm test:watch
+
+# Coverage report
+pnpm test:coverage
+
+# Interactive UI
+pnpm test:ui
+```
+
 ### Fastify Server
 
 ```typescript
@@ -96,7 +141,7 @@ const app = Fastify();
 
 app.register(fastifySPAGuard, {
   path: "/api/beacon",
-  onBeacon: async (beacon, request) => {
+  onBeacon: async (beacon, request, reply) => {
     // Log to Sentry, DataDog, or your monitoring service
     request.log.error(beacon, "Client error received");
 
@@ -207,18 +252,23 @@ spaGuardVitePlugin({
   minTimeBetweenResets: 5000, // Min time between retry resets in ms (default: 5000)
 
   // Fallback UI configuration
-  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")
+  html: {
+    fallback: {
+      content: `
+        <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
+  // Error filtering and retry
+  errors: {
+    ignore: [], // Array of error message substrings to ignore
+    forceRetry: [], // Array of error message substrings that trigger retry/reload
+  },
 
   // Beacon reporting
   reportBeacon: {
@@ -226,7 +276,7 @@ spaGuardVitePlugin({
   },
 
   // Build mode
-  trace: false, // Set to true for verbose debug build (10KB vs 5KB)
+  trace: false, // Set to true for verbose debug build (~13KB vs ~8KB)
 });
 ```
 
@@ -247,16 +297,38 @@ interface Options {
   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")
+  version?: string; // App version (auto-generated UUID if not specified)
+
+  checkVersion?: {
+    mode?: "html" | "json"; // Detection mode (default: "html")
+    interval?: number; // Polling interval in ms (default: 300000)
+    endpoint?: string; // JSON endpoint URL (required for "json" mode)
+    onUpdate?: "reload" | "event"; // Behavior on version change (default: "reload")
+  };
+
+  errors?: {
+    ignore?: string[]; // Error message substrings to filter out (default: [])
+    forceRetry?: string[]; // Error message substrings that trigger retry/reload (default: [])
   };
 
-  ignoredErrors?: string[]; // Error message substrings to filter out (default: [])
+  html?: {
+    fallback?: {
+      content?: string; // Custom error UI HTML (default: minimal error screen)
+      selector?: string; // CSS selector for injection target (default: "body")
+    };
+    loading?: {
+      content?: string; // Custom loading/retrying UI HTML (default: minimal loading screen)
+    };
+  };
 
   reportBeacon?: {
     endpoint?: string; // Server endpoint for beacon reports
   };
+
+  lazyRetry?: {
+    retryDelays?: number[]; // Delays in ms for module-level retries (default: [1000, 2000])
+    callReloadOnFailure?: boolean; // Trigger page reload after all retries fail (default: true)
+  };
 }
 
 interface VitePluginOptions extends Options {
@@ -272,19 +344,24 @@ interface VitePluginOptions extends Options {
   useRetryId: true,
   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>
-    `,
-    selector: "body",
+  checkVersion: {
+    mode: "html",
+    interval: 300_000,
+    onUpdate: "reload",
+  },
+  errors: {
+    ignore: [],
+    forceRetry: [],
+  },
+  html: {
+    fallback: {
+      content: defaultErrorFallbackHtml, // minimal error screen (auto-generated)
+      selector: "body",
+    },
+    loading: {
+      content: defaultLoadingFallbackHtml, // minimal loading screen (auto-generated)
+    },
   },
-  ignoredErrors: [],
 }
 ```
 
@@ -299,7 +376,7 @@ app.register(fastifySPAGuard, {
   path: "/api/beacon",
 
   // Custom beacon handler
-  onBeacon: async (beacon, request) => {
+  onBeacon: async (beacon, request, reply) => {
     const error = new Error(beacon.errorMessage || "Unknown client error");
 
     // Log structured data
@@ -318,7 +395,7 @@ app.register(fastifySPAGuard, {
   },
 
   // Handle unknown/invalid beacon formats
-  onUnknownBeacon: async (body, request) => {
+  onUnknownBeacon: async (body, request, reply) => {
     request.log.warn({ body }, "Received unknown beacon format");
   },
 });
@@ -331,6 +408,8 @@ interface BeaconSchema {
   errorMessage?: string; // Error message
   eventMessage?: string; // Event-specific message
   eventName?: string; // Event type (e.g., 'chunk_error_max_reloads', 'error', 'unhandledrejection')
+  retryAttempt?: number; // Current retry attempt at time of beacon
+  retryId?: string; // ID of the retry cycle
   serialized?: string; // Serialized error details (JSON string)
 }
 ```
@@ -340,22 +419,47 @@ interface BeaconSchema {
 - `chunk_error_max_reloads` - All reload attempts exhausted for chunk error
 - `error` - Non-chunk global error
 - `unhandledrejection` - Non-chunk promise rejection
-- `uncaughtException` - Uncaught exception
 - `securitypolicyviolation` - CSP violation
 
-### React Router Integration
+### React Integration
+
+spa-guard provides two React error boundary components with automatic chunk error recovery.
 
-spa-guard works seamlessly with React Router v7 error boundaries:
+#### ErrorBoundary (Class-based)
+
+Standard React error boundary with spa-guard integration:
+
+```tsx
+import { ErrorBoundary } from "@ovineko/spa-guard/react-error-boundary";
+
+function App() {
+  return (
+    <ErrorBoundary
+      autoRetryChunkErrors={true}
+      sendBeaconOnError={true}
+      onError={(error, errorInfo) => {
+        console.error("Error caught:", error, errorInfo);
+      }}
+    >
+      <YourApp />
+    </ErrorBoundary>
+  );
+}
+```
+
+#### ErrorBoundaryReactRouter (React Router)
+
+For React Router v7 route-level error handling:
 
 ```tsx
 import { createBrowserRouter, RouterProvider } from "react-router";
-import { ErrorBoundaryReloadPage } from "@ovineko/react-error-boundary";
+import { ErrorBoundaryReactRouter } from "@ovineko/spa-guard/react-router";
 
 const router = createBrowserRouter([
   {
     path: "/",
     element: <App />,
-    errorElement: <ErrorBoundaryReloadPage />,
+    errorElement: <ErrorBoundaryReactRouter />,
     children: [
       {
         path: "users/:id",
@@ -370,21 +474,365 @@ function Root() {
 }
 ```
 
+#### DebugSyncErrorTrigger
+
+A React component that bridges the vanilla debug panel's "Sync Runtime Error" button with React Error Boundaries. It listens for a CustomEvent dispatched by the debug panel, stores the error in state, and throws it during render so that a parent Error Boundary catches it.
+
+Place this component inside your ErrorBoundary:
+
+```tsx
+import { ErrorBoundary } from "@ovineko/spa-guard/react-error-boundary";
+import { DebugSyncErrorTrigger } from "@ovineko/spa-guard/react";
+
+function App() {
+  return (
+    <ErrorBoundary>
+      <DebugSyncErrorTrigger />
+      <YourApp />
+    </ErrorBoundary>
+  );
+}
+```
+
+This component renders nothing under normal conditions. It only throws when triggered by the debug panel's "Sync Runtime Error" button.
+
+**Props:**
+
+```typescript
+interface ErrorBoundaryProps {
+  autoRetryChunkErrors?: boolean; // Auto-reload on chunk errors (default: true)
+  sendBeaconOnError?: boolean; // Send error reports to server (default: true)
+  fallback?: ((props: FallbackProps) => React.ReactElement) | React.ComponentType<FallbackProps>; // Custom fallback component or render function
+  fallbackRender?: (props: FallbackProps) => React.ReactElement; // Render prop alternative
+  onError?: (error: Error, errorInfo: React.ErrorInfo) => void; // Error callback
+  resetKeys?: Array<unknown>; // Keys that trigger error reset when changed
+  children: ReactNode;
+}
+```
+
+**Custom Fallback UI:**
+
+```tsx
+import { ErrorBoundary, type FallbackProps } from "@ovineko/spa-guard/react-error-boundary";
+
+const CustomFallback = ({
+  error,
+  errorInfo,
+  resetError,
+  isChunkError,
+  isRetrying,
+  spaGuardState,
+}: FallbackProps) => (
+  <div>
+    <h1>{isChunkError ? "Failed to load" : "Something went wrong"}</h1>
+    <p>{error.message}</p>
+    {isRetrying ? <p>Retrying...</p> : <button onClick={resetError}>Try Again</button>}
+  </div>
+);
+
+function App() {
+  return (
+    <ErrorBoundary fallback={CustomFallback}>
+      <YourApp />
+    </ErrorBoundary>
+  );
+}
+```
+
+**Default Fallback Component:**
+
+Both error boundaries use `DefaultErrorFallback` by default, which uses two minimal HTML templates:
+
+- **Error state:** Heading, message paragraph, "Try again" button (non-chunk errors), "Reload page" button, error ID. No colors, no custom fonts, no animations - plain default browser styling.
+- **Loading/retrying state:** Centered "Loading..." text with retry attempt counter. No spinner, no animation.
+
+These templates are auto-generated as TypeScript string constants (`defaultErrorFallbackHtml` and `defaultLoadingFallbackHtml`) and can be imported for use in custom integrations.
+
 **Error flow:**
 
 1. Chunk load error occurs (e.g., after deployment)
 2. spa-guard inline script detects error
 3. Attempts automatic reload with query parameters (up to `reloadDelays.length` times)
-4. If all reloads fail, sends beacon to server and shows fallback UI
-5. React Router error boundary catches error (if no fallback UI configured)
-6. `ErrorBoundaryReloadPage` displays fallback UI
+4. React error boundary catches error and shows loading spinner during retries
+5. If all reloads fail, sends beacon to server and shows error UI
+6. User can manually retry or reload the page
+
+### React Hooks
+
+spa-guard provides React hooks to access retry state in your components.
+
+#### useSpaGuardState()
+
+Subscribe to spa-guard state changes:
+
+```tsx
+import { useSpaGuardState } from "@ovineko/spa-guard/react";
+
+function RetryIndicator() {
+  const state = useSpaGuardState();
+
+  if (!state.isWaiting) {
+    return null;
+  }
+
+  return <div className="retry-banner">Retrying... (Attempt {state.currentAttempt})</div>;
+}
+```
+
+**State properties:**
+
+```typescript
+interface SpaGuardState {
+  currentAttempt: number; // Current retry attempt (0-based)
+  isFallbackShown: boolean; // Whether fallback UI is displayed
+  isWaiting: boolean; // Whether waiting for a retry
+  lastRetryResetTime?: number; // Timestamp of last retry reset (undefined if no reset has occurred)
+  lastResetRetryId?: string; // Retry ID of last reset cycle (undefined if no reset has occurred)
+}
+```
+
+**Example - Global retry indicator:**
+
+```tsx
+import { useSpaGuardState } from "@ovineko/spa-guard/react";
+
+function App() {
+  const spaGuardState = useSpaGuardState();
+
+  return (
+    <>
+      {spaGuardState.isWaiting && (
+        <div className="fixed top-0 left-0 right-0 bg-yellow-500 text-white p-4 text-center">
+          Loading updated version... (Attempt {spaGuardState.currentAttempt})
+        </div>
+      )}
+      <YourApp />
+    </>
+  );
+}
+```
+
+#### useSPAGuardEvents(callback)
+
+Subscribe to all spa-guard events (chunk errors, retries, fallback UI, etc.):
+
+```tsx
+import { useSPAGuardEvents } from "@ovineko/spa-guard/react";
+
+function EventLogger() {
+  useSPAGuardEvents((event) => {
+    if (event.name === "chunk-error") {
+      console.log("Chunk error:", event.error, "retrying:", event.isRetrying);
+    }
+    if (event.name === "retry-attempt") {
+      console.log(`Retry ${event.attempt} (delay: ${event.delay}ms)`);
+    }
+  });
+
+  return null;
+}
+```
+
+The callback ref is kept up-to-date without resubscribing, so you can safely reference component state or props inside the callback.
+
+#### useSPAGuardChunkError()
+
+Convenience hook that tracks the latest chunk error event:
+
+```tsx
+import { useSPAGuardChunkError } from "@ovineko/spa-guard/react";
+
+function ChunkErrorBanner() {
+  const chunkError = useSPAGuardChunkError();
+
+  if (!chunkError) return null;
+
+  return (
+    <div className="error-banner">
+      A chunk error occurred. {chunkError.isRetrying ? "Retrying..." : "Please reload the page."}
+    </div>
+  );
+}
+```
+
+### Debug Panel
+
+spa-guard provides a framework-agnostic `createDebugger()` function for development and testing. It creates a vanilla JS debug panel that lets you simulate error scenarios and observe how spa-guard handles them in real time. Works with any SPA framework.
+
+```typescript
+import { createDebugger } from "@ovineko/spa-guard/runtime/debug";
+
+// Create the debug panel - returns a cleanup function
+const destroy = createDebugger();
+
+// Later: remove the panel and clean up all subscriptions
+destroy();
+```
+
+**React usage:**
+
+```tsx
+import { useEffect } from "react";
+import { createDebugger } from "@ovineko/spa-guard/runtime/debug";
+
+function App() {
+  useEffect(() => createDebugger(), []);
+
+  return <YourApp />;
+}
+```
+
+Since `createDebugger()` returns a cleanup function directly, the arrow shorthand implicitly returns it as the `useEffect` cleanup. No wrapper needed.
+
+**Options:**
+
+```typescript
+function createDebugger(options?: {
+  position?: "bottom-left" | "bottom-right" | "top-left" | "top-right"; // default: "bottom-right"
+  defaultOpen?: boolean; // default: true
+}): () => void;
+```
+
+**Features:**
+
+- Framework-agnostic vanilla JS (no React dependency)
+- Fixed-position overlay panel with toggle open/close
+- Error scenario buttons: ChunkLoadError, Network Timeout, Sync Runtime Error, Async Runtime Error, Finally Error
+- Button visual states (default, loading, triggered)
+- Live spa-guard state display (attempt, isWaiting, isFallbackShown)
+- Scrollable event history with timestamps
+- Clear history button
+- Single-instance deduplication (second call returns existing cleanup function with a warning)
+- Errors use fire-and-forget dispatch (reach spa-guard's window event listeners instead of being caught)
+
+### Version Checker
+
+spa-guard can proactively detect new deployments by periodically polling for version changes. This helps notify users before chunk errors occur.
+
+The version is automatically generated by the Vite plugin using `crypto.randomUUID()` if not explicitly provided. Each build gets a unique version, so version checking works with zero configuration.
+
+#### Setup
+
+The simplest way to enable version checking is with `recommendedSetup()`:
+
+```tsx
+import { useEffect } from "react";
+import { recommendedSetup } from "@ovineko/spa-guard/runtime";
+
+function App() {
+  useEffect(() => {
+    const cleanup = recommendedSetup();
+    return cleanup;
+  }, []);
+
+  return <YourApp />;
+}
+```
+
+For more control, use `startVersionCheck()` directly:
+
+```tsx
+import { useEffect } from "react";
+import { startVersionCheck } from "@ovineko/spa-guard/runtime";
+
+function App() {
+  useEffect(() => {
+    startVersionCheck();
+  }, []);
+
+  useEffect(() => {
+    const handleVersionChange = (event: CustomEvent) => {
+      const { oldVersion, latestVersion } = event.detail;
+      console.log(`New version detected: ${oldVersion} → ${latestVersion}`);
+      // Show a toast, banner, etc.
+    };
+
+    window.addEventListener("spa-guard:version-change", handleVersionChange as EventListener);
+    return () => {
+      window.removeEventListener("spa-guard:version-change", handleVersionChange as EventListener);
+    };
+  }, []);
+
+  return <YourApp />;
+}
+```
+
+#### Configuration
+
+Configure version checking via the Vite plugin options:
+
+```typescript
+spaGuardVitePlugin({
+  // version is auto-generated if not specified
+  checkVersion: {
+    mode: "html", // "html" (default) or "json"
+    interval: 300_000, // polling interval in ms (default: 5min)
+    endpoint: "/api/version", // required for "json" mode
+    onUpdate: "reload", // "reload" (default) or "event"
+  },
+});
+```
+
+**Two modes:**
+
+- **HTML mode** (default): Re-fetches the current page and parses the version from the injected `__SPA_GUARD_OPTIONS__`. No extra server endpoint needed.
+- **JSON mode**: Fetches a dedicated JSON endpoint that returns `{ "version": "1.2.3" }`. Lower bandwidth, but requires a server endpoint.
+
+**Auto-reload on version change:**
+
+By default (`onUpdate: "reload"`), when a new version is detected, spa-guard dispatches a `spa-guard:version-change` CustomEvent and then automatically calls `location.reload()`. Set `onUpdate: "event"` to only dispatch the event without reloading, allowing your app to handle the update notification (e.g., show a banner prompting the user to refresh).
+
+```typescript
+spaGuardVitePlugin({
+  checkVersion: {
+    onUpdate: "event", // Don't auto-reload, just dispatch the event
+  },
+});
+```
+
+#### API
+
+- `recommendedSetup(overrides?)` - Enable recommended runtime features (version checking, etc.) with sensible defaults. Returns a cleanup function.
+- `startVersionCheck()` - Start periodic version polling. No-op if no version is configured or already running.
+- `stopVersionCheck()` - Stop version polling and clear the interval.
+
+#### Tab Visibility and Focus
+
+Version polling automatically pauses when the browser tab is hidden (Page Visibility API) or the window loses focus, and resumes when the tab becomes visible or the window regains focus. When resuming:
+
+- If enough time has passed (>= polling interval), a check runs immediately and polling resumes
+- If less time has passed, polling resumes after the remaining interval
+
+Additionally, if the tab is hidden or the window is unfocused when `startVersionCheck()` is called, polling is deferred until the tab/window becomes active. Concurrent version checks are deduplicated - overlapping visibility and focus events won't trigger multiple fetches.
+
+This is handled transparently - no configuration needed.
+
+### Retry Control
+
+spa-guard allows your SPA to take over error handling from the inline script by disabling the default retry behavior:
+
+```typescript
+import { disableDefaultRetry, enableDefaultRetry, isDefaultRetryEnabled } from "@ovineko/spa-guard";
+
+// Disable the inline script's automatic page reload on chunk errors
+disableDefaultRetry();
+
+// Check current state
+console.log(isDefaultRetryEnabled()); // false
+
+// Re-enable if needed
+enableDefaultRetry();
+```
+
+When default retry is disabled, chunk errors will still emit events (via `subscribe` or `useSPAGuardEvents`), but the inline script will not trigger automatic page reloads. Your SPA can then implement custom error UI and retry logic.
 
 ### Core API (Framework-agnostic)
 
 The core module provides low-level APIs for custom integrations:
 
 ```typescript
-import { events, listen, options } from "@ovineko/spa-guard";
+import { events, listen, options, disableDefaultRetry } from "@ovineko/spa-guard";
+import { startVersionCheck } from "@ovineko/spa-guard/runtime";
 
 // Subscribe to spa-guard events
 events.subscribe((event) => {
@@ -392,7 +840,7 @@ events.subscribe((event) => {
 });
 
 // Emit custom event
-events.emit({ type: "custom", data: "..." });
+events.emitEvent({ name: "chunk-error", error: new Error("test"), isRetrying: false });
 
 // Initialize error listeners (automatically called by inline script)
 listen();
@@ -400,12 +848,18 @@ listen();
 // Get merged options
 const opts = options.getOptions();
 console.log("Reload delays:", opts.reloadDelays);
+
+// Start version checking
+startVersionCheck();
+
+// Take over retry behavior
+disableDefaultRetry();
 ```
 
 **Event system:**
 
 - `events.subscribe(listener)` - Subscribe to all spa-guard events
-- `events.emit(event)` - Emit event to all subscribers
+- `events.emitEvent(event)` - Emit event to all subscribers
 - Uses Symbol-based storage for isolation
 - Safe for server-side rendering (checks for `globalThis.window` availability)
 
@@ -448,7 +902,6 @@ const patterns = [
   /Loading chunk \d+ failed/i, // Webpack
   /Loading CSS chunk \d+ failed/i, // Webpack CSS
   /ChunkLoadError/i, // Generic
-  /Failed to fetch/i, // Network failures
 ];
 ```
 
@@ -528,25 +981,38 @@ export default defineConfig({
 
 ### Fastify Plugin
 
-#### `fastifySPAGuard(fastify, options: FastifySPAGuardOptions): Promise<void>`
-
-Registers a POST endpoint to receive beacon data from clients.
+#### `fastifySPAGuard: FastifyPluginAsync<FastifySPAGuardOptions>`
 
-**Parameters:**
-
-- `fastify` - Fastify instance
-- `options: FastifySPAGuardOptions` - Configuration object
+Fastify plugin that registers a POST endpoint to receive beacon data from clients. Use with `app.register()`.
 
 **FastifySPAGuardOptions:**
 
 ```typescript
 interface FastifySPAGuardOptions {
   path: string; // Route path (e.g., "/api/beacon")
-  onBeacon?: (beacon: BeaconSchema, request: any) => Promise<void> | void;
-  onUnknownBeacon?: (body: unknown, request: any) => Promise<void> | void;
+  onBeacon?: (
+    beacon: BeaconSchema,
+    request: FastifyRequest,
+    reply: FastifyReply,
+  ) => BeaconHandlerResult | Promise<BeaconHandlerResult | void> | void;
+  onUnknownBeacon?: (
+    body: unknown,
+    request: FastifyRequest,
+    reply: FastifyReply,
+  ) => BeaconHandlerResult | Promise<BeaconHandlerResult | void> | void;
 }
 ```
 
+**BeaconHandlerResult:**
+
+```typescript
+interface BeaconHandlerResult {
+  skipDefaultLog?: boolean; // If true, skips default logging behavior
+}
+```
+
+Return `{ skipDefaultLog: true }` from `onBeacon` or `onUnknownBeacon` to suppress the default Fastify request log entry (useful when you handle logging yourself).
+
 ### Types
 
 #### `Options`
@@ -558,16 +1024,38 @@ interface Options {
   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")
+  version?: string; // App version (auto-generated UUID if not specified)
+
+  checkVersion?: {
+    mode?: "html" | "json"; // Detection mode (default: "html")
+    interval?: number; // Polling interval in ms (default: 300000)
+    endpoint?: string; // JSON endpoint URL (required for "json" mode)
+    onUpdate?: "reload" | "event"; // Behavior on version change (default: "reload")
+  };
+
+  errors?: {
+    ignore?: string[]; // Error message substrings to filter out (default: [])
+    forceRetry?: string[]; // Error message substrings that trigger retry/reload (default: [])
   };
 
-  ignoredErrors?: string[]; // Error message substrings to filter out (default: [])
+  html?: {
+    fallback?: {
+      content?: string; // Custom error UI HTML
+      selector?: string; // CSS selector for injection target (default: "body")
+    };
+    loading?: {
+      content?: string; // Custom loading/retrying UI HTML
+    };
+  };
 
   reportBeacon?: {
     endpoint?: string; // Error reporting endpoint
   };
+
+  lazyRetry?: {
+    retryDelays?: number[]; // Delays in ms for lazy import retries (default: [1000, 2000])
+    callReloadOnFailure?: boolean; // Trigger page reload after all retries fail (default: true)
+  };
 }
 ```
 
@@ -586,6 +1074,8 @@ interface BeaconSchema {
   errorMessage?: string;
   eventMessage?: string;
   eventName?: string;
+  retryAttempt?: number; // Current retry attempt at time of beacon
+  retryId?: string; // ID of the retry cycle
   serialized?: string; // JSON stringified error details
 }
 ```
@@ -595,10 +1085,13 @@ interface BeaconSchema {
 From `@ovineko/spa-guard`:
 
 - `events.subscribe(listener)` - Subscribe to spa-guard events
-- `events.emit(event)` - Emit event to subscribers
+- `events.emitEvent(event)` - Emit event to subscribers
 - `listen()` - Initialize error listeners
 - `options.getOptions()` - Get merged options from globalThis.window
 - `options.optionsWindowKey` - Window storage key constant
+- `disableDefaultRetry()` - Disable inline script's automatic retry
+- `enableDefaultRetry()` - Re-enable automatic retry
+- `isDefaultRetryEnabled()` - Check if default retry is enabled
 
 ### Schema Exports
 
@@ -615,9 +1108,13 @@ From `@ovineko/spa-guard/schema/parse`:
 
 From `@ovineko/spa-guard/runtime`:
 
+- `recommendedSetup(overrides?)` - Enable recommended runtime features with sensible defaults, returns cleanup function
 - `getState()` - Get current spa-guard state (currentAttempt, isFallbackShown, isWaiting, lastRetryResetTime, lastResetRetryId)
 - `subscribeToState(callback)` - Subscribe to state changes, returns unsubscribe function
+- `startVersionCheck()` - Start periodic version polling
+- `stopVersionCheck()` - Stop version polling
 - `SpaGuardState` - TypeScript type for state object
+- `RecommendedSetupOptions` - TypeScript type for recommendedSetup overrides
 
 **Example:**
 
@@ -641,27 +1138,250 @@ const unsubscribe = subscribeToState((state) => {
 unsubscribe();
 ```
 
-## Module Exports
+### lazyWithRetry
+
+`lazyWithRetry` is a drop-in replacement for `React.lazy` that adds automatic retry logic for dynamic imports. Instead of immediately failing on a chunk load error, it retries the import with configurable delays and only falls back to a full page reload via `attemptReload()` if all retries are exhausted.
+
+#### Basic Usage
+
+```tsx
+import { lazyWithRetry } from "@ovineko/spa-guard/react";
+import { Suspense } from "react";
+import { ErrorBoundary } from "@ovineko/spa-guard/react-error-boundary";
+
+// Uses global options from window.__SPA_GUARD_OPTIONS__.lazyRetry
+const LazyHome = lazyWithRetry(() => import("./pages/Home"));
+
+function App() {
+  return (
+    <ErrorBoundary>
+      <Suspense fallback={<div>Loading...</div>}>
+        <LazyHome />
+      </Suspense>
+    </ErrorBoundary>
+  );
+}
+```
+
+#### Global Configuration
+
+Configure default retry behavior via `window.__SPA_GUARD_OPTIONS__`:
+
+```typescript
+window.__SPA_GUARD_OPTIONS__ = {
+  lazyRetry: {
+    retryDelays: [1000, 2000], // 2 retry attempts: 1s then 2s (default)
+    callReloadOnFailure: true, // Fall back to page reload after all retries (default)
+  },
+};
+```
+
+These global options are used by all `lazyWithRetry` calls unless overridden per-import.
+
+#### Per-Import Override
+
+Override global options for individual components:
+
+```tsx
+// More retries for a critical checkout flow
+const LazyCheckout = lazyWithRetry(
+  () => import("./pages/Checkout"),
+  { retryDelays: [500, 1000, 2000, 4000] }, // 4 attempts
+);
+
+// Disable page reload for a non-critical widget
+const LazyWidget = lazyWithRetry(() => import("./widgets/Optional"), {
+  retryDelays: [1000], // 1 retry attempt
+  callReloadOnFailure: false, // just throw to error boundary, no reload
+});
+```
+
+Per-import options always take priority over global options.
+
+#### Cancelling Retries with AbortSignal
+
+Use an `AbortSignal` to cancel in-progress retries and prevent memory leaks (e.g., when a component unmounts before the import resolves):
+
+```tsx
+const controller = new AbortController();
+
+const LazyPage = lazyWithRetry(() => import("./pages/Page"), { signal: controller.signal });
+
+// Cancel retries when no longer needed
+controller.abort();
+```
+
+Aborting clears any pending `setTimeout` timers immediately and rejects the import promise with an `AbortError`.
+
+#### Integration with attemptReload
+
+`lazyWithRetry` integrates with spa-guard's existing page reload logic:
+
+1. Component renders inside `<Suspense>`
+2. `React.lazy` calls the import function through `retryImport`
+3. On import failure, `retryImport` checks if it is a chunk load error
+4. If yes: retries with delays from `retryDelays` array, emitting `lazy-retry-attempt` events
+5. If all retries fail: emits `lazy-retry-exhausted` event, then calls `attemptReload()` (if `callReloadOnFailure: true`) before throwing to the error boundary
+6. `attemptReload()` adds `?spaGuardRetryId=...&spaGuardRetryAttempt=N` to the URL and reloads the page
+
+This means `lazyWithRetry` provides a two-level retry strategy:
+
+- Level 1 (new): Retry the individual module import with delays — no page disruption
+- Level 2 (existing): If all module retries fail, trigger the full page reload cycle
 
-spa-guard provides 9 export entry points:
+#### Events
 
-| 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                                   |
-| `./vite-plugin`          | Vite build plugin                            | `vite@^7 \|\| ^8`                      |
-| `./react-error-boundary` | Error boundary re-export                     | `react@^19`, `react-error-boundary@^6` |
+Subscribe to lazy retry events via the event system:
+
+```typescript
+import { events } from "@ovineko/spa-guard";
+
+events.subscribe((event) => {
+  if (event.name === "lazy-retry-attempt") {
+    console.log(`Retry ${event.attempt}/${event.totalAttempts} after ${event.delay}ms`);
+  }
+  if (event.name === "lazy-retry-success") {
+    console.log(`Succeeded on attempt ${event.attempt}`);
+  }
+  if (event.name === "lazy-retry-exhausted") {
+    console.log(`All retries exhausted. Will reload: ${event.willReload}`);
+  }
+});
+```
+
+**Event payload types:**
+
+```typescript
+type LazyRetryAttempt = {
+  name: "lazy-retry-attempt";
+  attempt: number; // current attempt number (1-based)
+  delay: number; // delay in ms before this attempt
+  totalAttempts: number; // total number of retry attempts
+};
+
+type LazyRetrySuccess = {
+  name: "lazy-retry-success";
+  attempt: number; // 1-based retry number on which import succeeded (1 = first retry)
+};
+
+type LazyRetryExhausted = {
+  name: "lazy-retry-exhausted";
+  totalAttempts: number; // number of attempts made
+  willReload: boolean; // whether attemptReload() will be called
+};
+```
+
+#### API Reference
+
+##### `lazyWithRetry<T>(importFn, options?)`
+
+Creates a lazy React component with retry logic.
+
+```typescript
+import { lazyWithRetry } from "@ovineko/spa-guard/react";
+import type { LazyRetryOptions } from "@ovineko/spa-guard/react";
+```
+
+**Parameters:**
+
+- `importFn: () => Promise<{ default: T }>` - Dynamic import function
+- `options?: LazyRetryOptions` - Per-import options (override global)
+
+**Returns:** `LazyExoticComponent<T>` - Same type as `React.lazy()`
+
+##### `LazyRetryOptions`
+
+```typescript
+interface LazyRetryOptions {
+  /**
+   * Array of delays in milliseconds for retry attempts.
+   * Each element = one retry attempt with that delay.
+   * Overrides window.__SPA_GUARD_OPTIONS__.lazyRetry.retryDelays.
+   * @default [1000, 2000]
+   */
+  retryDelays?: number[];
+
+  /**
+   * Call attemptReload() after all retries are exhausted.
+   * Overrides window.__SPA_GUARD_OPTIONS__.lazyRetry.callReloadOnFailure.
+   * @default true
+   */
+  callReloadOnFailure?: boolean;
+
+  /**
+   * AbortSignal to cancel in-progress retries and clear pending timers.
+   */
+  signal?: AbortSignal;
+}
+```
+
+##### Global `lazyRetry` Options
+
+```typescript
+interface Options {
+  // ... existing options ...
+
+  lazyRetry?: {
+    /**
+     * Array of retry delays in ms for dynamic imports.
+     * @default [1000, 2000]
+     */
+    retryDelays?: number[];
+
+    /**
+     * Call attemptReload() after all lazy import retries fail.
+     * @default true
+     */
+    callReloadOnFailure?: boolean;
+  };
+}
+```
+
+## Module Exports
+
+spa-guard provides 11 export entry points:
+
+| Export                   | Description                                                                                                                   | Peer Dependencies                                 |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| `.`                      | Core functionality (events, listen, options, retry control)                                                                   | None                                              |
+| `./schema`               | BeaconSchema type definitions                                                                                                 | `typebox@^1`                                      |
+| `./schema/parse`         | Beacon parsing utilities                                                                                                      | `typebox@^1`                                      |
+| `./runtime`              | Runtime state management and subscriptions                                                                                    | None                                              |
+| `./react`                | React hooks and components (useSpaGuardState, useSPAGuardEvents, useSPAGuardChunkError, lazyWithRetry, DebugSyncErrorTrigger) | `react@^19`                                       |
+| `./runtime/debug`        | Debug panel factory (`createDebugger`) - framework-agnostic vanilla JS                                                        | None                                              |
+| `./react-router`         | React Router error boundary (ErrorBoundaryReactRouter)                                                                        | `react@^19`, `react-router@^7`                    |
+| `./fastify`              | Fastify server plugin                                                                                                         | `fastify@^5 \|\| ^4`, `fastify-plugin@^5 \|\| ^4` |
+| `./vite-plugin`          | Vite build plugin                                                                                                             | `vite@^8 \|\| ^7`                                 |
+| `./react-error-boundary` | React error boundary component (ErrorBoundary)                                                                                | `react@^19`                                       |
+| `./eslint`               | ESLint plugin with `configs.recommended` preset (`no-direct-error-boundary`, `no-direct-lazy`)                                | `eslint@^9 \|\| ^10` (optional)                   |
 
 **Import examples:**
 
 ```typescript
 // Core
-import { events, listen } from "@ovineko/spa-guard";
+import { events, listen, disableDefaultRetry } from "@ovineko/spa-guard";
+
+// Runtime state + version check
+import { getState, subscribeToState, startVersionCheck } from "@ovineko/spa-guard/runtime";
+
+// React hooks and components
+import {
+  useSpaGuardState,
+  useSPAGuardEvents,
+  useSPAGuardChunkError,
+  DebugSyncErrorTrigger,
+} from "@ovineko/spa-guard/react";
+
+// Lazy imports with retry
+import { lazyWithRetry } from "@ovineko/spa-guard/react";
+import type { LazyRetryOptions } from "@ovineko/spa-guard/react";
+
+// Debug panel (framework-agnostic)
+import { createDebugger } from "@ovineko/spa-guard/runtime/debug";
+
+// React error boundaries
+import { ErrorBoundary } from "@ovineko/spa-guard/react-error-boundary";
+import { ErrorBoundaryReactRouter } from "@ovineko/spa-guard/react-router";
 
 // Schema
 import type { BeaconSchema } from "@ovineko/spa-guard/schema";
@@ -671,28 +1391,40 @@ import { spaGuardVitePlugin } from "@ovineko/spa-guard/vite-plugin";
 
 // Fastify
 import { fastifySPAGuard } from "@ovineko/spa-guard/fastify";
+
+// ESLint plugin
+import spaGuardEslint from "@ovineko/spa-guard/eslint";
 ```
 
 ## Build Sizes
 
-- **Production:** `dist-inline/index.js` ~5.9 KB minified (Terser)
-- **Trace:** `dist-inline-trace/index.js` ~7.3 KB minified (Terser)
+- **Production:** `dist-inline/index.js` ~8.3 KB minified (Terser)
+- **Trace:** `dist-inline-trace/index.js` ~13.3 KB minified (Terser)
 - **Main library:** `dist/` varies by export
 
 ## Advanced Usage
 
-### Disable Query Parameters (PII Concerns)
+### Disable Retry ID Query Parameter (PII Concerns)
 
-If query parameters are problematic for your use case:
+If the `spaGuardRetryId` query parameter is problematic for your use case (e.g., URL logging policies):
 
 ```typescript
 spaGuardVitePlugin({
-  useRetryId: false, // Disable query parameters
-  reloadDelays: [1000, 2000], // Still retries, but without cache busting
+  useRetryId: false, // Disable spaGuardRetryId in URL (default: true)
+  reloadDelays: [1000, 2000], // Still retries, but without cache-busting UUID
 });
 ```
 
-**Note:** Without `useRetryId`, retries use `globalThis.window.location.reload()` which may not bypass aggressive HTML cache.
+**Behavior with `useRetryId: false`:**
+
+- The `spaGuardRetryAttempt` param is still written to the URL to track retry progress across reloads
+- Only the `spaGuardRetryId` UUID param is omitted
+- Retries still work correctly (attempt counter persists in URL)
+- The attempt param is cleaned up from the URL after retry exhaustion
+- The "Error ID" line in the default fallback UI is automatically hidden (no retry ID to display)
+- `enableRetryReset` (smart retry cycle reset) has no effect — retry cycles cannot auto-reset without a persisted retry ID
+
+**Note:** Without `useRetryId`, the retry URL won't include a unique UUID, so aggressive HTML cache may not be bypassed. However, retry counting still works correctly.
 
 ### Custom Fallback UI
 
@@ -700,53 +1432,55 @@ Provide fully custom HTML for error screen:
 
 ```typescript
 spaGuardVitePlugin({
-  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>
+  html: {
+    fallback: {
+      content: `
+        <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
+      `,
+      selector: "body", // Inject into document.body
+    },
   },
 });
 ```
@@ -757,36 +1491,41 @@ 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">
+  html: {
+    fallback: {
+      content: `<div>Error occurred. <button onclick="location.reload()">Retry</button></div>`,
+      selector: "#app", // Inject into <div id="app">
+    },
   },
 });
 ```
 
-### Error Filtering
+### Error Filtering and Force Retry
 
-Filter out specific errors from being logged or reported:
+Filter out specific errors from reporting, or force certain errors to trigger the retry/reload process:
 
 ```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
-  ],
+  errors: {
+    ignore: [
+      "ResizeObserver loop", // Ignore benign ResizeObserver errors
+      "Non-Error promise rejection", // Ignore specific promise rejections
+      "Script error", // Ignore generic script errors from third-party scripts
+    ],
+    forceRetry: [
+      "STALE_DEPLOYMENT", // Custom errors that should trigger retry like chunk errors
+      "MODULE_NOT_FOUND", // Framework-specific stale module errors
+    ],
+  },
   reportBeacon: {
     endpoint: "/api/beacon",
   },
 });
 ```
 
-**How it works:**
+**`errors.ignore`** - Errors containing any of these substrings will not be logged to console and beacons will not be sent. Case-sensitive substring matching.
 
-- 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
+**`errors.forceRetry`** - Errors containing any of these substrings will trigger the same retry/reload process as chunk load errors (calls `attemptReload()`). Useful for custom error patterns that indicate a stale deployment. Case-sensitive substring matching.
 
 ### Custom Retry Strategy
 
@@ -835,14 +1574,51 @@ const handleBeacon = (beacon: BeaconSchema) => {
 - Fastify plugin types for type-safe integration
 - Options interface with optional fields
 
-## Future Enhancements
+## ESLint Plugin
+
+spa-guard includes an ESLint plugin (`@ovineko/spa-guard/eslint`) that enforces usage of spa-guard wrappers instead of direct React imports. This ensures all error boundaries and lazy loading are properly integrated with spa-guard's retry logic.
+
+### Setup
+
+```javascript
+// eslint.config.js (flat config)
+import spaGuardEslint from "@ovineko/spa-guard/eslint";
+
+export default [spaGuardEslint.configs.recommended];
+```
+
+### Rules
+
+#### `no-direct-error-boundary`
+
+Disallows importing `ErrorBoundary` from `react-error-boundary`. Auto-fixes to import from `@ovineko/spa-guard/react-error-boundary` instead.
 
-Detailed specifications for planned features are documented in [TODO.md](TODO.md):
+```typescript
+// Bad
+import { ErrorBoundary } from "react-error-boundary";
+
+// Good (auto-fixed)
+import { ErrorBoundary } from "@ovineko/spa-guard/react-error-boundary";
+```
 
-- **Version Checker Module** - Detect new deployments via HTML or JSON polling
-- **Enhanced Event Emitter Architecture** - Rich event system for SPA integration with React hooks
+#### `no-direct-lazy`
 
-These features are designed to extend spa-guard's capabilities while maintaining the minimal inline script footprint.
+Disallows importing `lazy` from `react`. Auto-fixes to import `lazyWithRetry` from `@ovineko/spa-guard/react` instead. Handles split-import cases where other specifiers (e.g., `Suspense`) remain on the original `react` import.
+
+```typescript
+// Bad
+import { lazy } from "react";
+
+// Good (auto-fixed)
+import { lazyWithRetry } from "@ovineko/spa-guard/react";
+
+// Bad (split import)
+import { lazy, Suspense } from "react";
+
+// Good (auto-fixed)
+import { Suspense } from "react";
+import { lazyWithRetry } from "@ovineko/spa-guard/react";
+```
 
 ## License