@ovineko/spa-guard-react 0.0.2-alpha-1 → 0.0.4

package/README.md

@@ -7,78 +7,47 @@ React hooks, components, and error boundaries for [spa-guard](../spa-guard/READM
 
 ## Install
 
-```sh
-npm install @ovineko/spa-guard-react @ovineko/spa-guard react
-```
+**pnpm** (recommended):
 
-## Usage
-
-### lazyWithRetry
+```bash
+pnpm add @ovineko/spa-guard-react @ovineko/spa-guard react
+```
 
-Wrap `React.lazy` to automatically retry chunk load failures with configurable delays.
+**npm**:
 
-```tsx
-import { Suspense } from "react";
-import { lazyWithRetry } from "@ovineko/spa-guard-react";
+```bash
+npm install @ovineko/spa-guard-react @ovineko/spa-guard react
+```
 
-const LazyHome = lazyWithRetry(() => import("./pages/Home"));
+**yarn**:
 
-// Override retry delays for a specific route
-const LazyCheckout = lazyWithRetry(() => import("./pages/Checkout"), {
-  retryDelays: [500, 1000, 2000, 4000],
-});
-
-export function App() {
-  return (
-    <Suspense fallback={<div>Loading...</div>}>
-      <LazyHome />
-    </Suspense>
-  );
-}
+```bash
+yarn add @ovineko/spa-guard-react @ovineko/spa-guard react
 ```
 
-### ErrorBoundary
-
-Catches errors in child components and integrates with spa-guard retry state.
+**bun**:
 
-```tsx
-import { ErrorBoundary } from "@ovineko/spa-guard-react/error-boundary";
-
-export function App() {
-  return (
-    <ErrorBoundary>
-      <MyApp />
-    </ErrorBoundary>
-  );
-}
+```bash
+bun add @ovineko/spa-guard-react @ovineko/spa-guard react
 ```
 
-## API
+**deno**:
 
-From `@ovineko/spa-guard-react`:
+```bash
+deno add npm:@ovineko/spa-guard-react npm:@ovineko/spa-guard npm:react
+```
 
-- `lazyWithRetry(importFn, options?)` — lazy component with automatic retry
-- `useSpaGuardState()` — reactive hook for current spa-guard state
-- `useSPAGuardChunkError()` — hook to detect chunk load errors
-- `useSPAGuardEvents()` — hook to subscribe to spa-guard events
-- `DefaultErrorFallback` — default fallback UI component
-- `Spinner` — loading spinner component
-- `DebugSyncErrorTrigger` — trigger sync errors for testing
-- `ForceRetryError` — error class to force a retry
-- `LazyRetryOptions` — options type for `lazyWithRetry`
-- `SpaGuardState` — spa-guard state type
+## Usage
 
-From `@ovineko/spa-guard-react/error-boundary`:
+```tsx
+import { lazyWithRetry } from "@ovineko/spa-guard-react";
 
-- `ErrorBoundary` — error boundary with spa-guard integration
-- `ErrorBoundaryProps` — props for `ErrorBoundary`
-- `FallbackProps` — props passed to fallback component
+const LazyHome = lazyWithRetry(() => import("./pages/Home"));
+```
 
-## Related Packages
+## Documentation
 
-- [@ovineko/spa-guard](../spa-guard/README.md) — core package
-- [@ovineko/spa-guard-react-router](../react-router/README.md) — React Router integration
-- [@ovineko/spa-guard-vite](../vite/README.md) — Vite plugin
+Full documentation: [ovineko.com/docs/spa-guard/react](https://ovineko.com/docs/spa-guard/react)
 
 ## License
 

package/dist/index-Xle6BwDr.d.mts

@@ -0,0 +1,133 @@
+import { ComponentProps, ComponentType, LazyExoticComponent } from "react";
+import { SPAGuardEvent, SPAGuardEventChunkError } from "@ovineko/spa-guard/_internal";
+import * as _$_ovineko_spa_guard_runtime0 from "@ovineko/spa-guard/runtime";
+import { SpaGuardState, SpaGuardState as SpaGuardState$1 } from "@ovineko/spa-guard/runtime";
+import { ForceRetryError } from "@ovineko/spa-guard";
+
+//#region src/DefaultErrorFallback.d.ts
+interface DefaultErrorFallbackProps {
+  error: unknown;
+  isChunkError: boolean;
+  isRetrying: boolean;
+  onReset?: () => void;
+  spaGuardState: SpaGuardState;
+}
+/**
+ * Default fallback UI component for error boundaries.
+ *
+ * Uses two separate HTML templates: one for loading/retrying state
+ * and one for error state. Renders via dangerouslySetInnerHTML with
+ * virtual container + data attribute patching for dynamic content.
+ */
+declare const DefaultErrorFallback: React.FC<DefaultErrorFallbackProps>;
+//#endregion
+//#region src/react/DebugSyncErrorTrigger.d.ts
+/**
+ * Renders nothing normally. When a CustomEvent of type debugSyncErrorEventType
+ * is dispatched on window, this component stores the error in state and throws
+ * it during the next render, allowing a parent React Error Boundary to catch it.
+ *
+ * Place this component inside your ErrorBoundary:
+ *
+ *   <ErrorBoundary fallback={<CrashPage />}>
+ *     <DebugSyncErrorTrigger />
+ *     <App />
+ *   </ErrorBoundary>
+ */
+declare function DebugSyncErrorTrigger(): null;
+//#endregion
+//#region src/react/types.d.ts
+/**
+ * Per-import options for lazyWithRetry that override global lazyRetry options.
+ *
+ * @example
+ * // Override retry delays for a critical component
+ * const LazyCheckout = lazyWithRetry(
+ *   () => import('./pages/Checkout'),
+ *   { retryDelays: [500, 1000, 2000, 4000] } satisfies LazyRetryOptions
+ * );
+ */
+interface LazyRetryOptions {
+  /**
+   * If true, triggers a full page reload via triggerRetry() after all retry attempts are exhausted.
+   * If false, only throws the error to the error boundary without reload.
+   * Overrides the global `window.__SPA_GUARD_OPTIONS__.lazyRetry.callReloadOnFailure`.
+   *
+   * @default true (inherited from global options)
+   */
+  callReloadOnFailure?: boolean;
+  /**
+   * Array of delays in milliseconds for retry attempts.
+   * Each element represents one retry attempt with the given delay.
+   * The number of elements determines the number of retry attempts.
+   * Overrides the global `window.__SPA_GUARD_OPTIONS__.lazyRetry.retryDelays`.
+   *
+   * @default [1000, 2000] (inherited from global options)
+   * @example [500, 1500, 3000] // 3 attempts: 500ms, 1.5s, 3s
+   */
+  retryDelays?: number[];
+  /**
+   * AbortSignal to cancel pending retry delays between import attempts.
+   * When the signal fires, any pending setTimeout between retries is cleared
+   * and the import promise rejects with an AbortError.
+   *
+   * Note: cancels only the wait periods between retry attempts, not an in-flight
+   * dynamic import (JavaScript does not support cancelling in-flight module fetches).
+   * Most useful when calling `retryImport` directly rather than through `lazyWithRetry`,
+   * since `lazyWithRetry` captures the signal at module scope (not per component instance).
+   */
+  signal?: AbortSignal;
+}
+//#endregion
+//#region src/react/lazyWithRetry.d.ts
+/**
+ * Creates a lazy-loaded React component with automatic retry on chunk load failures.
+ *
+ * On import failure, retries with configurable delays before falling back to
+ * `triggerRetry()` for a full page reload.
+ *
+ * @param importFn - Function that performs the dynamic import
+ * @param options - Per-import options that override global lazyRetry options
+ * @returns A lazy React component with retry logic
+ *
+ * @example
+ * // Basic usage with global options
+ * const LazyHome = lazyWithRetry(() => import('./pages/Home'));
+ *
+ * @example
+ * // Override retry delays for a critical component
+ * const LazyCheckout = lazyWithRetry(
+ *   () => import('./pages/Checkout'),
+ *   { retryDelays: [500, 1000, 2000, 4000] }
+ * );
+ *
+ * @example
+ * // Disable page reload for a non-critical component
+ * const LazyWidget = lazyWithRetry(
+ *   () => import('./widgets/Optional'),
+ *   { retryDelays: [1000], callReloadOnFailure: false }
+ * );
+ */
+declare const lazyWithRetry: <T extends ComponentType<any>>(importFn: () => Promise<{
+  default: T;
+}>, options?: LazyRetryOptions) => LazyExoticComponent<T>;
+//#endregion
+//#region src/react/Spinner.d.ts
+type SpinnerProps = Omit<ComponentProps<"div">, "children" | "dangerouslySetInnerHTML">;
+/**
+ * Renders the spa-guard spinner inside a div.
+ * Returns null if spinner is disabled or no content available.
+ * All div props forwarded to wrapper element.
+ */
+declare function Spinner(props: SpinnerProps): null | React.ReactElement;
+//#endregion
+//#region src/react/useSPAGuardChunkError.d.ts
+declare const useSPAGuardChunkError: () => null | SPAGuardEventChunkError;
+//#endregion
+//#region src/react/useSPAGuardEvents.d.ts
+declare const useSPAGuardEvents: (callback: (event: SPAGuardEvent) => void) => void;
+//#endregion
+//#region src/react/index.d.ts
+declare const useSpaGuardState: () => _$_ovineko_spa_guard_runtime0.SpaGuardState;
+//#endregion
+export { useSPAGuardChunkError as a, LazyRetryOptions as c, useSPAGuardEvents as i, DebugSyncErrorTrigger as l, SpaGuardState$1 as n, Spinner as o, useSpaGuardState as r, lazyWithRetry as s, ForceRetryError as t, DefaultErrorFallback as u };

package/dist/react/index.d.ts

@@ -1,10 +1,2 @@
-export { DefaultErrorFallback } from "../DefaultErrorFallback";
-export { DebugSyncErrorTrigger } from "./DebugSyncErrorTrigger";
-export { lazyWithRetry } from "./lazyWithRetry";
-export { Spinner } from "./Spinner";
-export type { LazyRetryOptions } from "./types";
-export { useSPAGuardChunkError } from "./useSPAGuardChunkError";
-export { useSPAGuardEvents } from "./useSPAGuardEvents";
-export { ForceRetryError } from "@ovineko/spa-guard";
-export type { SpaGuardState } from "@ovineko/spa-guard/runtime";
-export declare const useSpaGuardState: () => import("@ovineko/spa-guard/runtime").SpaGuardState;
+import { a as useSPAGuardChunkError, c as LazyRetryOptions, i as useSPAGuardEvents, l as DebugSyncErrorTrigger, n as SpaGuardState, o as Spinner, r as useSpaGuardState, s as lazyWithRetry, t as ForceRetryError, u as DefaultErrorFallback } from "../index-Xle6BwDr.mjs";
+export { DebugSyncErrorTrigger, DefaultErrorFallback, ForceRetryError, LazyRetryOptions, SpaGuardState, Spinner, lazyWithRetry, useSPAGuardChunkError, useSPAGuardEvents, useSpaGuardState };

package/dist/react/index.js

@@ -1,20 +1,2 @@
-import {
-  DebugSyncErrorTrigger,
-  DefaultErrorFallback,
-  ForceRetryError,
-  Spinner,
-  lazyWithRetry,
-  useSPAGuardChunkError,
-  useSPAGuardEvents,
-  useSpaGuardState
-} from "../chunk-6VYHMTKS.js";
-export {
-  DebugSyncErrorTrigger,
-  DefaultErrorFallback,
-  ForceRetryError,
-  Spinner,
-  lazyWithRetry,
-  useSPAGuardChunkError,
-  useSPAGuardEvents,
-  useSpaGuardState
-};
+import { a as Spinner, c as DefaultErrorFallback, i as useSPAGuardEvents, n as useSpaGuardState, o as lazyWithRetry, r as useSPAGuardChunkError, s as DebugSyncErrorTrigger, t as ForceRetryError } from "../react-DuyDGIyU.mjs";
+export { DebugSyncErrorTrigger, DefaultErrorFallback, ForceRetryError, Spinner, lazyWithRetry, useSPAGuardChunkError, useSPAGuardEvents, useSpaGuardState };

package/dist/react-DuyDGIyU.mjs

@@ -0,0 +1,218 @@
+import { lazy, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { applyI18n, debugSyncErrorEventType, defaultErrorFallbackHtml, defaultLoadingFallbackHtml, getI18n, getOptions, retryImport, subscribe } from "@ovineko/spa-guard/_internal";
+import { jsx } from "react/jsx-runtime";
+import { getState, subscribeToState } from "@ovineko/spa-guard/runtime";
+import { ForceRetryError } from "@ovineko/spa-guard";
+//#region src/DefaultErrorFallback.tsx
+const escapeHtml = (str) => str.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;");
+const reloadHandler = () => location.reload();
+/**
+* Build final HTML by parsing the template in a virtual container
+* and patching content via data attributes. This is robust against
+* template changes (minification, styling, element order).
+*/
+function buildHtml(template, patches) {
+	const container = document.createElement("div");
+	container.innerHTML = template;
+	if (patches.spinnerHtml) {
+		const spinnerEl = container.querySelector("[data-spa-guard-spinner]");
+		if (spinnerEl) spinnerEl.innerHTML = patches.spinnerHtml;
+	}
+	if (patches.content) for (const [key, value] of Object.entries(patches.content)) {
+		const el = container.querySelector(`[data-spa-guard-content="${key}"]`);
+		if (el) el.innerHTML = value;
+	}
+	if (patches.sections) for (const [key, visible] of Object.entries(patches.sections)) {
+		const el = container.querySelector(`[data-spa-guard-section="${key}"]`);
+		if (el) el.style.display = visible ? "block" : "none";
+	}
+	if (patches.actions) for (const [key, visible] of Object.entries(patches.actions)) {
+		const el = container.querySelector(`[data-spa-guard-action="${key}"]`);
+		if (el) el.style.display = visible ? "inline-block" : "none";
+	}
+	const t = getI18n();
+	if (t) applyI18n(container, t);
+	return container.innerHTML;
+}
+/**
+* Default fallback UI component for error boundaries.
+*
+* Uses two separate HTML templates: one for loading/retrying state
+* and one for error state. Renders via dangerouslySetInnerHTML with
+* virtual container + data attribute patching for dynamic content.
+*/
+const DefaultErrorFallback = ({ error, isChunkError: isChunk, isRetrying, onReset, spaGuardState }) => {
+	const containerRef = useRef(null);
+	const html = useMemo(() => {
+		const opts = getOptions();
+		if (isRetrying) {
+			const loadingTemplate = opts.html?.loading?.content ?? defaultLoadingFallbackHtml;
+			const spinnerContent = opts.html?.spinner?.content;
+			return buildHtml(loadingTemplate, {
+				content: { attempt: String(spaGuardState.currentAttempt) },
+				sections: { retrying: true },
+				...spinnerContent !== void 0 && { spinnerHtml: spinnerContent }
+			});
+		}
+		const heading = isChunk ? "Failed to load module" : "Something went wrong";
+		const message = error instanceof Error ? error.message : String(error);
+		return buildHtml(opts.html?.fallback?.content ?? defaultErrorFallbackHtml, {
+			actions: { "try-again": Boolean(onReset) },
+			content: {
+				heading: escapeHtml(heading),
+				message: escapeHtml(message)
+			}
+		});
+	}, [
+		isRetrying,
+		isChunk,
+		error,
+		onReset,
+		spaGuardState.currentAttempt
+	]);
+	useLayoutEffect(() => {
+		const el = containerRef.current;
+		if (!el) return;
+		const reloadBtn = el.querySelector("[data-spa-guard-action=\"reload\"]");
+		reloadBtn?.addEventListener("click", reloadHandler);
+		const tryAgainHandler = onReset ? () => onReset() : null;
+		const tryAgainBtn = onReset ? el.querySelector("[data-spa-guard-action=\"try-again\"]") : null;
+		if (tryAgainHandler && tryAgainBtn) tryAgainBtn.addEventListener("click", tryAgainHandler);
+		return () => {
+			reloadBtn?.removeEventListener("click", reloadHandler);
+			if (tryAgainHandler && tryAgainBtn) tryAgainBtn.removeEventListener("click", tryAgainHandler);
+		};
+	}, [onReset, html]);
+	return /* @__PURE__ */ jsx("div", {
+		dangerouslySetInnerHTML: useMemo(() => ({ __html: html }), [html]),
+		ref: containerRef
+	});
+};
+//#endregion
+//#region src/react/DebugSyncErrorTrigger.tsx
+/**
+* Renders nothing normally. When a CustomEvent of type debugSyncErrorEventType
+* is dispatched on window, this component stores the error in state and throws
+* it during the next render, allowing a parent React Error Boundary to catch it.
+*
+* Place this component inside your ErrorBoundary:
+*
+*   <ErrorBoundary fallback={<CrashPage />}>
+*     <DebugSyncErrorTrigger />
+*     <App />
+*   </ErrorBoundary>
+*/
+function DebugSyncErrorTrigger() {
+	const [error, setError] = useState(null);
+	useEffect(() => {
+		const handler = (e) => {
+			const detail = e.detail;
+			if (detail?.error instanceof Error) setError(detail.error);
+		};
+		globalThis.addEventListener(debugSyncErrorEventType, handler);
+		return () => {
+			globalThis.removeEventListener(debugSyncErrorEventType, handler);
+		};
+	}, []);
+	if (error) throw error;
+	return null;
+}
+//#endregion
+//#region src/react/lazyWithRetry.tsx
+/**
+* Creates a lazy-loaded React component with automatic retry on chunk load failures.
+*
+* On import failure, retries with configurable delays before falling back to
+* `triggerRetry()` for a full page reload.
+*
+* @param importFn - Function that performs the dynamic import
+* @param options - Per-import options that override global lazyRetry options
+* @returns A lazy React component with retry logic
+*
+* @example
+* // Basic usage with global options
+* const LazyHome = lazyWithRetry(() => import('./pages/Home'));
+*
+* @example
+* // Override retry delays for a critical component
+* const LazyCheckout = lazyWithRetry(
+*   () => import('./pages/Checkout'),
+*   { retryDelays: [500, 1000, 2000, 4000] }
+* );
+*
+* @example
+* // Disable page reload for a non-critical component
+* const LazyWidget = lazyWithRetry(
+*   () => import('./widgets/Optional'),
+*   { retryDelays: [1000], callReloadOnFailure: false }
+* );
+*/
+const lazyWithRetry = (importFn, options) => {
+	return lazy(() => {
+		const globalLazyRetry = getOptions().lazyRetry ?? {};
+		const retryDelays = options?.retryDelays ?? globalLazyRetry.retryDelays ?? [1e3, 2e3];
+		const callReloadOnFailure = options?.callReloadOnFailure ?? globalLazyRetry.callReloadOnFailure ?? true;
+		const signal = options?.signal;
+		return retryImport(importFn, retryDelays, {
+			callReloadOnFailure,
+			...signal !== void 0 && { signal }
+		});
+	});
+};
+//#endregion
+//#region src/react/Spinner.tsx
+/**
+* Renders the spa-guard spinner inside a div.
+* Returns null if spinner is disabled or no content available.
+* All div props forwarded to wrapper element.
+*/
+function Spinner(props) {
+	const opts = getOptions();
+	const content = opts.html?.spinner?.disabled ? void 0 : opts.html?.spinner?.content;
+	const innerHtml = useMemo(() => content ? { __html: content } : null, [content]);
+	if (!innerHtml) return null;
+	return /* @__PURE__ */ jsx("div", {
+		...props,
+		dangerouslySetInnerHTML: innerHtml
+	});
+}
+//#endregion
+//#region src/react/useSPAGuardEvents.ts
+const useSPAGuardEvents = (callback) => {
+	const callbackRef = useRef(callback);
+	useEffect(() => {
+		callbackRef.current = callback;
+	});
+	useEffect(() => {
+		return subscribe((event) => {
+			callbackRef.current(event);
+		});
+	}, []);
+};
+//#endregion
+//#region src/react/useSPAGuardChunkError.ts
+const useSPAGuardChunkError = () => {
+	const [chunkError, setChunkError] = useState(null);
+	useSPAGuardEvents(useCallback((event) => {
+		if (event.name === "chunk-error") setChunkError(event);
+	}, []));
+	return chunkError;
+};
+//#endregion
+//#region src/react/index.tsx
+const useSpaGuardState = () => {
+	const [state, setState] = useState(() => {
+		if (globalThis.window === void 0) return {
+			currentAttempt: 0,
+			isFallbackShown: false,
+			isWaiting: false
+		};
+		return getState();
+	});
+	useEffect(() => {
+		return subscribeToState(setState);
+	}, []);
+	return state;
+};
+//#endregion
+export { Spinner as a, DefaultErrorFallback as c, useSPAGuardEvents as i, useSpaGuardState as n, lazyWithRetry as o, useSPAGuardChunkError as r, DebugSyncErrorTrigger as s, ForceRetryError as t };

package/dist/react-error-boundary/index.d.ts

@@ -1,31 +1,35 @@
-import { type ReactNode } from "react";
-import { type SpaGuardState } from "../react";
+import { n as SpaGuardState } from "../index-Xle6BwDr.mjs";
+import { ReactNode } from "react";
+
+//#region src/react-error-boundary/index.d.ts
 /**
  * Props for the ErrorBoundary component
  */
-export interface ErrorBoundaryProps {
-    autoRetryChunkErrors?: boolean;
-    children: ReactNode;
-    fallback?: ((props: FallbackProps) => React.ReactElement) | React.ComponentType<FallbackProps>;
-    fallbackRender?: (props: FallbackProps) => React.ReactElement;
-    onError?: (error: Error, errorInfo: React.ErrorInfo) => void;
-    resetKeys?: Array<unknown>;
-    sendBeaconOnError?: boolean;
+interface ErrorBoundaryProps {
+  autoRetryChunkErrors?: boolean;
+  children: ReactNode;
+  fallback?: ((props: FallbackProps) => React.ReactElement) | React.ComponentType<FallbackProps>;
+  fallbackRender?: (props: FallbackProps) => React.ReactElement;
+  onError?: (error: Error, errorInfo: React.ErrorInfo) => void;
+  resetKeys?: Array<unknown>;
+  sendBeaconOnError?: boolean;
 }
 /**
  * Props passed to the fallback component when an error is caught
  */
-export interface FallbackProps {
-    error: Error;
-    errorInfo: null | React.ErrorInfo;
-    isChunkError: boolean;
-    isRetrying: boolean;
-    resetError: () => void;
-    spaGuardState: SpaGuardState;
+interface FallbackProps {
+  error: Error;
+  errorInfo: null | React.ErrorInfo;
+  isChunkError: boolean;
+  isRetrying: boolean;
+  resetError: () => void;
+  spaGuardState: SpaGuardState;
 }
 /**
  * Error boundary component with spa-guard integration.
  *
  * Catches errors in child components and automatically retries chunk loading errors.
  */
-export declare const ErrorBoundary: React.FC<ErrorBoundaryProps>;
+declare const ErrorBoundary: React.FC<ErrorBoundaryProps>;
+//#endregion
+export { ErrorBoundary, ErrorBoundaryProps, FallbackProps };

package/dist/react-error-boundary/index.js

@@ -1,83 +1,73 @@
-import {
-  DefaultErrorFallback,
-  useSpaGuardState
-} from "../chunk-6VYHMTKS.js";
-
-// src/react-error-boundary/index.tsx
+import { c as DefaultErrorFallback, n as useSpaGuardState } from "../react-DuyDGIyU.mjs";
 import { Component } from "react";
 import { handleErrorWithSpaGuard, isChunkError } from "@ovineko/spa-guard/_internal";
 import { jsx } from "react/jsx-runtime";
-var DefaultFallback = ({
-  error,
-  isChunkError: isChunk,
-  isRetrying,
-  resetError,
-  spaGuardState
-}) => /* @__PURE__ */ jsx(
-  DefaultErrorFallback,
-  {
-    error,
-    isChunkError: isChunk,
-    isRetrying,
-    onReset: resetError,
-    spaGuardState
-  }
-);
+//#region src/react-error-boundary/index.tsx
+const DefaultFallback = ({ error, isChunkError: isChunk, isRetrying, resetError, spaGuardState }) => /* @__PURE__ */ jsx(DefaultErrorFallback, {
+	error,
+	isChunkError: isChunk,
+	isRetrying,
+	onReset: resetError,
+	spaGuardState
+});
 var ErrorBoundaryImpl = class extends Component {
-  state = { error: null, errorInfo: null };
-  static getDerivedStateFromError(error) {
-    return { error };
-  }
-  componentDidCatch(error, errorInfo) {
-    this.setState({ errorInfo });
-    const { autoRetryChunkErrors, onError, sendBeaconOnError } = this.props;
-    handleErrorWithSpaGuard(error, {
-      autoRetryChunkErrors,
-      errorInfo,
-      eventName: "react-error-boundary",
-      onError: () => onError?.(error, errorInfo),
-      sendBeaconOnError
-    });
-  }
-  componentDidUpdate(prevProps) {
-    const { resetKeys = [] } = this.props;
-    const prevResetKeys = prevProps.resetKeys ?? [];
-    if (this.state.error !== null && (resetKeys.length !== prevResetKeys.length || resetKeys.some((key, i) => key !== prevResetKeys[i]))) {
-      this.resetError();
-    }
-  }
-  render() {
-    const { error, errorInfo } = this.state;
-    if (!error) {
-      return this.props.children;
-    }
-    const { fallback: Fallback, fallbackRender, spaGuardState } = this.props;
-    const isChunk = isChunkError(error);
-    const isRetrying = spaGuardState.isWaiting && spaGuardState.currentAttempt > 0;
-    const fallbackProps = {
-      error,
-      errorInfo,
-      isChunkError: isChunk,
-      isRetrying,
-      resetError: this.resetError,
-      spaGuardState
-    };
-    if (fallbackRender) {
-      return fallbackRender(fallbackProps);
-    }
-    if (Fallback) {
-      return /* @__PURE__ */ jsx(Fallback, { ...fallbackProps });
-    }
-    return /* @__PURE__ */ jsx(DefaultFallback, { ...fallbackProps });
-  }
-  resetError = () => {
-    this.setState({ error: null, errorInfo: null });
-  };
+	state = {
+		error: null,
+		errorInfo: null
+	};
+	static getDerivedStateFromError(error) {
+		return { error };
+	}
+	componentDidCatch(error, errorInfo) {
+		this.setState({ errorInfo });
+		const { autoRetryChunkErrors, onError, sendBeaconOnError } = this.props;
+		handleErrorWithSpaGuard(error, {
+			...autoRetryChunkErrors !== void 0 && { autoRetryChunkErrors },
+			errorInfo,
+			eventName: "react-error-boundary",
+			onError: () => onError?.(error, errorInfo),
+			...sendBeaconOnError !== void 0 && { sendBeaconOnError }
+		});
+	}
+	componentDidUpdate(prevProps) {
+		const { resetKeys = [] } = this.props;
+		const prevResetKeys = prevProps.resetKeys ?? [];
+		if (this.state.error !== null && (resetKeys.length !== prevResetKeys.length || resetKeys.some((key, i) => key !== prevResetKeys[i]))) this.resetError();
+	}
+	render() {
+		const { error, errorInfo } = this.state;
+		if (!error) return this.props.children;
+		const { fallback: Fallback, fallbackRender, spaGuardState } = this.props;
+		const fallbackProps = {
+			error,
+			errorInfo,
+			isChunkError: isChunkError(error),
+			isRetrying: spaGuardState.isWaiting && spaGuardState.currentAttempt > 0,
+			resetError: this.resetError,
+			spaGuardState
+		};
+		if (fallbackRender) return fallbackRender(fallbackProps);
+		if (Fallback) return /* @__PURE__ */ jsx(Fallback, { ...fallbackProps });
+		return /* @__PURE__ */ jsx(DefaultFallback, { ...fallbackProps });
+	}
+	resetError = () => {
+		this.setState({
+			error: null,
+			errorInfo: null
+		});
+	};
 };
-var ErrorBoundary = (props) => {
-  const spaGuardState = useSpaGuardState();
-  return /* @__PURE__ */ jsx(ErrorBoundaryImpl, { ...props, spaGuardState });
-};
-export {
-  ErrorBoundary
+/**
+* Error boundary component with spa-guard integration.
+*
+* Catches errors in child components and automatically retries chunk loading errors.
+*/
+const ErrorBoundary = (props) => {
+	const spaGuardState = useSpaGuardState();
+	return /* @__PURE__ */ jsx(ErrorBoundaryImpl, {
+		...props,
+		spaGuardState
+	});
 };
+//#endregion
+export { ErrorBoundary };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ovineko/spa-guard-react",
-  "version": "0.0.2-alpha-1",
+  "version": "0.0.4",
   "description": "React hooks, components, and error boundaries for spa-guard",
   "keywords": [
     "spa",
@@ -35,11 +35,8 @@
     "dist"
   ],
   "peerDependencies": {
-    "react": "^19",
-    "@ovineko/spa-guard": "0.0.2-alpha-1"
-  },
-  "engines": {
-    "node": ">=22.15.0"
+    "react": ">=18",
+    "@ovineko/spa-guard": "0.0.4"
   },
   "publishConfig": {
     "access": "public"

package/dist/DefaultErrorFallback.d.ts

@@ -1,17 +0,0 @@
-import type { SpaGuardState } from "@ovineko/spa-guard/runtime";
-interface DefaultErrorFallbackProps {
-    error: unknown;
-    isChunkError: boolean;
-    isRetrying: boolean;
-    onReset?: () => void;
-    spaGuardState: SpaGuardState;
-}
-/**
- * Default fallback UI component for error boundaries.
- *
- * Uses two separate HTML templates: one for loading/retrying state
- * and one for error state. Renders via dangerouslySetInnerHTML with
- * virtual container + data attribute patching for dynamic content.
- */
-export declare const DefaultErrorFallback: React.FC<DefaultErrorFallbackProps>;
-export {};

package/dist/chunk-6VYHMTKS.js

@@ -1,223 +0,0 @@
-// src/react/index.tsx
-import { useEffect as useEffect3, useState as useState3 } from "react";
-import { getState, subscribeToState } from "@ovineko/spa-guard/runtime";
-
-// src/DefaultErrorFallback.tsx
-import { useLayoutEffect, useMemo, useRef } from "react";
-import {
-  applyI18n,
-  defaultErrorFallbackHtml,
-  defaultLoadingFallbackHtml,
-  getI18n,
-  getOptions
-} from "@ovineko/spa-guard/_internal";
-import { jsx } from "react/jsx-runtime";
-var escapeHtml = (str) => str.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;");
-var reloadHandler = () => location.reload();
-function buildHtml(template, patches) {
-  const container = document.createElement("div");
-  container.innerHTML = template;
-  if (patches.spinnerHtml) {
-    const spinnerEl = container.querySelector("[data-spa-guard-spinner]");
-    if (spinnerEl) {
-      spinnerEl.innerHTML = patches.spinnerHtml;
-    }
-  }
-  if (patches.content) {
-    for (const [key, value] of Object.entries(patches.content)) {
-      const el = container.querySelector(`[data-spa-guard-content="${key}"]`);
-      if (el) {
-        el.innerHTML = value;
-      }
-    }
-  }
-  if (patches.sections) {
-    for (const [key, visible] of Object.entries(patches.sections)) {
-      const el = container.querySelector(`[data-spa-guard-section="${key}"]`);
-      if (el) {
-        el.style.display = visible ? "block" : "none";
-      }
-    }
-  }
-  if (patches.actions) {
-    for (const [key, visible] of Object.entries(patches.actions)) {
-      const el = container.querySelector(`[data-spa-guard-action="${key}"]`);
-      if (el) {
-        el.style.display = visible ? "inline-block" : "none";
-      }
-    }
-  }
-  const t = getI18n();
-  if (t) {
-    applyI18n(container, t);
-  }
-  return container.innerHTML;
-}
-var DefaultErrorFallback = ({
-  error,
-  isChunkError: isChunk,
-  isRetrying,
-  onReset,
-  spaGuardState
-}) => {
-  const containerRef = useRef(null);
-  const html = useMemo(() => {
-    const opts = getOptions();
-    if (isRetrying) {
-      const loadingTemplate = opts.html?.loading?.content ?? defaultLoadingFallbackHtml;
-      return buildHtml(loadingTemplate, {
-        content: {
-          attempt: String(spaGuardState.currentAttempt)
-        },
-        sections: {
-          retrying: true
-        },
-        spinnerHtml: opts.html?.spinner?.content
-      });
-    }
-    const heading = isChunk ? "Failed to load module" : "Something went wrong";
-    const message = error instanceof Error ? error.message : String(error);
-    const errorTemplate = opts.html?.fallback?.content ?? defaultErrorFallbackHtml;
-    return buildHtml(errorTemplate, {
-      actions: {
-        "try-again": Boolean(onReset)
-      },
-      content: {
-        heading: escapeHtml(heading),
-        message: escapeHtml(message)
-      }
-    });
-  }, [isRetrying, isChunk, error, onReset, spaGuardState.currentAttempt]);
-  useLayoutEffect(() => {
-    const el = containerRef.current;
-    if (!el) {
-      return;
-    }
-    const reloadBtn = el.querySelector('[data-spa-guard-action="reload"]');
-    reloadBtn?.addEventListener("click", reloadHandler);
-    const tryAgainHandler = onReset ? () => onReset() : null;
-    const tryAgainBtn = onReset ? el.querySelector('[data-spa-guard-action="try-again"]') : null;
-    if (tryAgainHandler && tryAgainBtn) {
-      tryAgainBtn.addEventListener("click", tryAgainHandler);
-    }
-    return () => {
-      reloadBtn?.removeEventListener("click", reloadHandler);
-      if (tryAgainHandler && tryAgainBtn) {
-        tryAgainBtn.removeEventListener("click", tryAgainHandler);
-      }
-    };
-  }, [onReset, html]);
-  const innerHtml = useMemo(() => ({ __html: html }), [html]);
-  return /* @__PURE__ */ jsx("div", { dangerouslySetInnerHTML: innerHtml, ref: containerRef });
-};
-
-// src/react/DebugSyncErrorTrigger.tsx
-import { useEffect, useState } from "react";
-import { debugSyncErrorEventType } from "@ovineko/spa-guard/_internal";
-function DebugSyncErrorTrigger() {
-  const [error, setError] = useState(null);
-  useEffect(() => {
-    const handler = (e) => {
-      const detail = e.detail;
-      if (detail?.error instanceof Error) {
-        setError(detail.error);
-      }
-    };
-    globalThis.addEventListener(debugSyncErrorEventType, handler);
-    return () => {
-      globalThis.removeEventListener(debugSyncErrorEventType, handler);
-    };
-  }, []);
-  if (error) {
-    throw error;
-  }
-  return null;
-}
-
-// src/react/lazyWithRetry.tsx
-import { lazy } from "react";
-import { getOptions as getOptions2, retryImport } from "@ovineko/spa-guard/_internal";
-var lazyWithRetry = (importFn, options) => {
-  return lazy(() => {
-    const globalLazyRetry = getOptions2().lazyRetry ?? {};
-    const retryDelays = options?.retryDelays ?? globalLazyRetry.retryDelays ?? [1e3, 2e3];
-    const callReloadOnFailure = options?.callReloadOnFailure ?? globalLazyRetry.callReloadOnFailure ?? true;
-    const signal = options?.signal;
-    return retryImport(importFn, retryDelays, { callReloadOnFailure, signal });
-  });
-};
-
-// src/react/Spinner.tsx
-import { useMemo as useMemo2 } from "react";
-import { getOptions as getOptions3 } from "@ovineko/spa-guard/_internal";
-import { jsx as jsx2 } from "react/jsx-runtime";
-function Spinner(props) {
-  const opts = getOptions3();
-  const content = opts.html?.spinner?.disabled ? void 0 : opts.html?.spinner?.content;
-  const innerHtml = useMemo2(() => content ? { __html: content } : null, [content]);
-  if (!innerHtml) {
-    return null;
-  }
-  return /* @__PURE__ */ jsx2("div", { ...props, dangerouslySetInnerHTML: innerHtml });
-}
-
-// src/react/useSPAGuardChunkError.ts
-import { useCallback, useState as useState2 } from "react";
-
-// src/react/useSPAGuardEvents.ts
-import { useEffect as useEffect2, useRef as useRef2 } from "react";
-import { subscribe } from "@ovineko/spa-guard/_internal";
-var useSPAGuardEvents = (callback) => {
-  const callbackRef = useRef2(callback);
-  useEffect2(() => {
-    callbackRef.current = callback;
-  });
-  useEffect2(() => {
-    return subscribe((event) => {
-      callbackRef.current(event);
-    });
-  }, []);
-};
-
-// src/react/useSPAGuardChunkError.ts
-var useSPAGuardChunkError = () => {
-  const [chunkError, setChunkError] = useState2(null);
-  useSPAGuardEvents(
-    useCallback((event) => {
-      if (event.name === "chunk-error") {
-        setChunkError(event);
-      }
-    }, [])
-  );
-  return chunkError;
-};
-
-// src/react/index.tsx
-import { ForceRetryError } from "@ovineko/spa-guard";
-var useSpaGuardState = () => {
-  const [state, setState] = useState3(() => {
-    if (globalThis.window === void 0) {
-      return {
-        currentAttempt: 0,
-        isFallbackShown: false,
-        isWaiting: false
-      };
-    }
-    return getState();
-  });
-  useEffect3(() => {
-    return subscribeToState(setState);
-  }, []);
-  return state;
-};
-
-export {
-  DefaultErrorFallback,
-  DebugSyncErrorTrigger,
-  lazyWithRetry,
-  Spinner,
-  useSPAGuardEvents,
-  useSPAGuardChunkError,
-  useSpaGuardState,
-  ForceRetryError
-};

package/dist/react/DebugSyncErrorTrigger.d.ts

@@ -1,13 +0,0 @@
-/**
- * Renders nothing normally. When a CustomEvent of type debugSyncErrorEventType
- * is dispatched on window, this component stores the error in state and throws
- * it during the next render, allowing a parent React Error Boundary to catch it.
- *
- * Place this component inside your ErrorBoundary:
- *
- *   <ErrorBoundary fallback={<CrashPage />}>
- *     <DebugSyncErrorTrigger />
- *     <App />
- *   </ErrorBoundary>
- */
-export declare function DebugSyncErrorTrigger(): null;

package/dist/react/Spinner.d.ts

@@ -1,9 +0,0 @@
-import type { ComponentProps } from "react";
-type SpinnerProps = Omit<ComponentProps<"div">, "children" | "dangerouslySetInnerHTML">;
-/**
- * Renders the spa-guard spinner inside a div.
- * Returns null if spinner is disabled or no content available.
- * All div props forwarded to wrapper element.
- */
-export declare function Spinner(props: SpinnerProps): null | React.ReactElement;
-export {};

package/dist/react/lazyWithRetry.d.ts

@@ -1,34 +0,0 @@
-import { type ComponentType, type LazyExoticComponent } from "react";
-import type { LazyRetryOptions } from "./types";
-export type { LazyRetryOptions } from "./types";
-/**
- * Creates a lazy-loaded React component with automatic retry on chunk load failures.
- *
- * On import failure, retries with configurable delays before falling back to
- * `triggerRetry()` for a full page reload.
- *
- * @param importFn - Function that performs the dynamic import
- * @param options - Per-import options that override global lazyRetry options
- * @returns A lazy React component with retry logic
- *
- * @example
- * // Basic usage with global options
- * const LazyHome = lazyWithRetry(() => import('./pages/Home'));
- *
- * @example
- * // Override retry delays for a critical component
- * const LazyCheckout = lazyWithRetry(
- *   () => import('./pages/Checkout'),
- *   { retryDelays: [500, 1000, 2000, 4000] }
- * );
- *
- * @example
- * // Disable page reload for a non-critical component
- * const LazyWidget = lazyWithRetry(
- *   () => import('./widgets/Optional'),
- *   { retryDelays: [1000], callReloadOnFailure: false }
- * );
- */
-export declare const lazyWithRetry: <T extends ComponentType<any>>(importFn: () => Promise<{
-    default: T;
-}>, options?: LazyRetryOptions) => LazyExoticComponent<T>;

package/dist/react/types.d.ts

@@ -1,41 +0,0 @@
-/**
- * Per-import options for lazyWithRetry that override global lazyRetry options.
- *
- * @example
- * // Override retry delays for a critical component
- * const LazyCheckout = lazyWithRetry(
- *   () => import('./pages/Checkout'),
- *   { retryDelays: [500, 1000, 2000, 4000] } satisfies LazyRetryOptions
- * );
- */
-export interface LazyRetryOptions {
-    /**
-     * If true, triggers a full page reload via triggerRetry() after all retry attempts are exhausted.
-     * If false, only throws the error to the error boundary without reload.
-     * Overrides the global `window.__SPA_GUARD_OPTIONS__.lazyRetry.callReloadOnFailure`.
-     *
-     * @default true (inherited from global options)
-     */
-    callReloadOnFailure?: boolean;
-    /**
-     * Array of delays in milliseconds for retry attempts.
-     * Each element represents one retry attempt with the given delay.
-     * The number of elements determines the number of retry attempts.
-     * Overrides the global `window.__SPA_GUARD_OPTIONS__.lazyRetry.retryDelays`.
-     *
-     * @default [1000, 2000] (inherited from global options)
-     * @example [500, 1500, 3000] // 3 attempts: 500ms, 1.5s, 3s
-     */
-    retryDelays?: number[];
-    /**
-     * AbortSignal to cancel pending retry delays between import attempts.
-     * When the signal fires, any pending setTimeout between retries is cleared
-     * and the import promise rejects with an AbortError.
-     *
-     * Note: cancels only the wait periods between retry attempts, not an in-flight
-     * dynamic import (JavaScript does not support cancelling in-flight module fetches).
-     * Most useful when calling `retryImport` directly rather than through `lazyWithRetry`,
-     * since `lazyWithRetry` captures the signal at module scope (not per component instance).
-     */
-    signal?: AbortSignal;
-}

package/dist/react/useSPAGuardChunkError.d.ts

@@ -1,2 +0,0 @@
-import type { SPAGuardEventChunkError } from "@ovineko/spa-guard/_internal";
-export declare const useSPAGuardChunkError: () => null | SPAGuardEventChunkError;

package/dist/react/useSPAGuardEvents.d.ts

@@ -1,2 +0,0 @@
-import type { SPAGuardEvent } from "@ovineko/spa-guard/_internal";
-export declare const useSPAGuardEvents: (callback: (event: SPAGuardEvent) => void) => void;