@goliapkg/sentori-react 0.1.0 → 0.3.0

package/lib/SentoriErrorBoundary.d.ts

@@ -1,20 +1,26 @@
 import { type ErrorInfo, type ReactNode } from 'react';
+type FallbackRender = (props: {
+    error: Error;
+    reset: () => void;
+}) => ReactNode;
 type Props = {
     children: ReactNode;
-    /** Rendered after an error is caught. Receives the error and a
-     *  `reset` callback that clears the boundary so retries can run. */
-    fallback: (props: {
-        error: Error;
-        reset: () => void;
-    }) => ReactNode;
+    /**
+     * Rendered after an error is caught. Either a plain ReactNode
+     * (most common — a static error screen) or a render-prop that
+     * receives the error and a `reset` callback so the fallback can
+     * offer a retry button.
+     */
+    fallback: FallbackRender | ReactNode;
     /** Optional additional logging hook. Runs after Sentori capture. */
     onError?: (error: Error, info: ErrorInfo) => void;
+    /**
+     * Shallow-compared on update. Any change resets the boundary,
+     * letting parents recover from a caught error by passing fresh
+     * keys (e.g. a route path, a query key, a user id).
+     */
+    resetKeys?: unknown[];
 };
-/**
- * Wraps `<SentoriErrorBoundaryInner>` so we can grab the capture
- * function from context — class components can't use hooks directly,
- * but they CAN receive props from a thin functional wrapper.
- */
 export declare function SentoriErrorBoundary(props: Props): import("react/jsx-runtime").JSX.Element;
 export {};
 //# sourceMappingURL=SentoriErrorBoundary.d.ts.map

package/lib/SentoriErrorBoundary.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SentoriErrorBoundary.d.ts","sourceRoot":"","sources":["../src/SentoriErrorBoundary.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAa,KAAK,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAIjE,KAAK,KAAK,GAAG;IACX,QAAQ,EAAE,SAAS,CAAA;IACnB;wEACoE;IACpE,QAAQ,EAAE,CAAC,KAAK,EAAE;QAAE,KAAK,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,MAAM,IAAI,CAAA;KAAE,KAAK,SAAS,CAAA;IACnE,oEAAoE;IACpE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,KAAK,IAAI,CAAA;CAClD,CAAA;AAID;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,KAAK,2CAWhD"}
+{"version":3,"file":"SentoriErrorBoundary.d.ts","sourceRoot":"","sources":["../src/SentoriErrorBoundary.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAa,KAAK,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAIjE,KAAK,cAAc,GAAG,CAAC,KAAK,EAAE;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,IAAI,CAAA;CAAE,KAAK,SAAS,CAAA;AAE/E,KAAK,KAAK,GAAG;IACX,QAAQ,EAAE,SAAS,CAAA;IACnB;;;;;OAKG;IACH,QAAQ,EAAE,cAAc,GAAG,SAAS,CAAA;IACpC,oEAAoE;IACpE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,KAAK,IAAI,CAAA;IACjD;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,EAAE,CAAA;CACtB,CAAA;AAID,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,KAAK,2CAWhD"}

package/lib/SentoriErrorBoundary.js

@@ -1,11 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Component } from 'react';
 import { useSentoriCtx } from './SentoriProvider.js';
-/**
- * Wraps `<SentoriErrorBoundaryInner>` so we can grab the capture
- * function from context — class components can't use hooks directly,
- * but they CAN receive props from a thin functional wrapper.
- */
 export function SentoriErrorBoundary(props) {
     const { captureError } = useSentoriCtx();
     return (_jsx(SentoriErrorBoundaryInner, { ...props, capture: (err, info) => {
@@ -21,12 +16,34 @@ class SentoriErrorBoundaryInner extends Component {
     componentDidCatch(error, info) {
         this.props.capture(error, info);
     }
+    componentDidUpdate(prev) {
+        if (this.state.error && resetKeysChanged(prev.resetKeys, this.props.resetKeys)) {
+            this.setState({ error: null });
+        }
+    }
     reset = () => this.setState({ error: null });
     render() {
-        if (this.state.error) {
-            return this.props.fallback({ error: this.state.error, reset: this.reset });
+        const { error } = this.state;
+        if (error) {
+            const { fallback } = this.props;
+            return typeof fallback === 'function'
+                ? fallback({ error, reset: this.reset })
+                : fallback;
         }
         return this.props.children;
     }
 }
+function resetKeysChanged(prev, next) {
+    if (prev === next)
+        return false;
+    if (!prev || !next)
+        return prev !== next;
+    if (prev.length !== next.length)
+        return true;
+    for (let i = 0; i < prev.length; i++) {
+        if (!Object.is(prev[i], next[i]))
+            return true;
+    }
+    return false;
+}
 //# sourceMappingURL=SentoriErrorBoundary.js.map

package/lib/SentoriErrorBoundary.js.map

@@ -1 +1 @@
-{"version":3,"file":"SentoriErrorBoundary.js","sourceRoot":"","sources":["../src/SentoriErrorBoundary.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,SAAS,EAAkC,MAAM,OAAO,CAAA;AAEjE,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAapD;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAY;IAC/C,MAAM,EAAE,YAAY,EAAE,GAAG,aAAa,EAAE,CAAA;IACxC,OAAO,CACL,KAAC,yBAAyB,OACpB,KAAK,EACT,OAAO,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE;YACrB,YAAY,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,qBAAqB,EAAE,EAAE,CAAC,CAAA;YAC9D,KAAK,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;QAC5B,CAAC,GACD,CACH,CAAA;AACH,CAAC;AAED,MAAM,yBAA0B,SAAQ,SAGvC;IACC,KAAK,GAAU,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;IAE9B,MAAM,CAAC,wBAAwB,CAAC,KAAY;QAC1C,OAAO,EAAE,KAAK,EAAE,CAAA;IAClB,CAAC;IAED,iBAAiB,CAAC,KAAY,EAAE,IAAe;QAC7C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAA;IACjC,CAAC;IAED,KAAK,GAAG,GAAS,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;IAElD,MAAM;QACJ,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;YACrB,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAA;QAC5E,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAA;IAC5B,CAAC;CACF"}
+{"version":3,"file":"SentoriErrorBoundary.js","sourceRoot":"","sources":["../src/SentoriErrorBoundary.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,SAAS,EAAkC,MAAM,OAAO,CAAA;AAEjE,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAyBpD,MAAM,UAAU,oBAAoB,CAAC,KAAY;IAC/C,MAAM,EAAE,YAAY,EAAE,GAAG,aAAa,EAAE,CAAA;IACxC,OAAO,CACL,KAAC,yBAAyB,OACpB,KAAK,EACT,OAAO,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE;YACrB,YAAY,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,qBAAqB,EAAE,EAAE,CAAC,CAAA;YAC9D,KAAK,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;QAC5B,CAAC,GACD,CACH,CAAA;AACH,CAAC;AAED,MAAM,yBAA0B,SAAQ,SAGvC;IACC,KAAK,GAAU,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;IAE9B,MAAM,CAAC,wBAAwB,CAAC,KAAY;QAC1C,OAAO,EAAE,KAAK,EAAE,CAAA;IAClB,CAAC;IAED,iBAAiB,CAAC,KAAY,EAAE,IAAe;QAC7C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAA;IACjC,CAAC;IAED,kBAAkB,CAAC,IAAqB;QACtC,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,IAAI,gBAAgB,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC;YAC/E,IAAI,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;QAChC,CAAC;IACH,CAAC;IAED,KAAK,GAAG,GAAS,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;IAElD,MAAM;QACJ,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC,KAAK,CAAA;QAC5B,IAAI,KAAK,EAAE,CAAC;YACV,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC,KAAK,CAAA;YAC/B,OAAO,OAAO,QAAQ,KAAK,UAAU;gBACnC,CAAC,CAAE,QAA2B,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;gBAC5D,CAAC,CAAC,QAAQ,CAAA;QACd,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAA;IAC5B,CAAC;CACF;AAED,SAAS,gBAAgB,CAAC,IAAgB,EAAE,IAAgB;IAC1D,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,KAAK,CAAA;IAC/B,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,KAAK,IAAI,CAAA;IACxC,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAA;IAC5C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;YAAE,OAAO,IAAI,CAAA;IAC/C,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC"}

package/lib/SentoriSuspense.d.ts

@@ -0,0 +1,29 @@
+import { type ReactNode } from 'react';
+type FallbackRender = (props: {
+    error: Error;
+    reset: () => void;
+}) => ReactNode;
+/**
+ * `<Suspense>` + `<SentoriErrorBoundary>` composed together. Any
+ * error thrown during render, whether it's a synchronous throw or a
+ * rejected promise surfaced through Suspense, is caught by the
+ * inner boundary and forwarded to `captureError`.
+ *
+ * Use when you want a one-liner around a data-fetching subtree —
+ * the loading state and the error state share the same fallback by
+ * default; pass `errorFallback` if they need to differ.
+ *
+ *     <SentoriSuspense fallback={<Skeleton />} errorFallback={<ErrorCard />}>
+ *       <UserProfile />
+ *     </SentoriSuspense>
+ */
+export declare function SentoriSuspense({ children, errorFallback, fallback, }: {
+    children: ReactNode;
+    /** Optional separate fallback for caught errors. Falls back to
+     *  `fallback` if not provided. */
+    errorFallback?: FallbackRender | ReactNode;
+    /** Loading state shown by the inner `<Suspense>`. */
+    fallback: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export {};
+//# sourceMappingURL=SentoriSuspense.d.ts.map

package/lib/SentoriSuspense.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SentoriSuspense.d.ts","sourceRoot":"","sources":["../src/SentoriSuspense.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAIhD,KAAK,cAAc,GAAG,CAAC,KAAK,EAAE;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,IAAI,CAAA;CAAE,KAAK,SAAS,CAAA;AAE/E;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,EAC9B,QAAQ,EACR,aAAa,EACb,QAAQ,GACT,EAAE;IACD,QAAQ,EAAE,SAAS,CAAA;IACnB;sCACkC;IAClC,aAAa,CAAC,EAAE,cAAc,GAAG,SAAS,CAAA;IAC1C,qDAAqD;IACrD,QAAQ,EAAE,SAAS,CAAA;CACpB,2CAMA"}

package/lib/SentoriSuspense.js

@@ -0,0 +1,21 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Suspense } from 'react';
+import { SentoriErrorBoundary } from './SentoriErrorBoundary.js';
+/**
+ * `<Suspense>` + `<SentoriErrorBoundary>` composed together. Any
+ * error thrown during render, whether it's a synchronous throw or a
+ * rejected promise surfaced through Suspense, is caught by the
+ * inner boundary and forwarded to `captureError`.
+ *
+ * Use when you want a one-liner around a data-fetching subtree —
+ * the loading state and the error state share the same fallback by
+ * default; pass `errorFallback` if they need to differ.
+ *
+ *     <SentoriSuspense fallback={<Skeleton />} errorFallback={<ErrorCard />}>
+ *       <UserProfile />
+ *     </SentoriSuspense>
+ */
+export function SentoriSuspense({ children, errorFallback, fallback, }) {
+    return (_jsx(SentoriErrorBoundary, { fallback: errorFallback ?? fallback, children: _jsx(Suspense, { fallback: fallback, children: children }) }));
+}
+//# sourceMappingURL=SentoriSuspense.js.map

package/lib/SentoriSuspense.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SentoriSuspense.js","sourceRoot":"","sources":["../src/SentoriSuspense.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,QAAQ,EAAkB,MAAM,OAAO,CAAA;AAEhD,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAA;AAIhE;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,eAAe,CAAC,EAC9B,QAAQ,EACR,aAAa,EACb,QAAQ,GAQT;IACC,OAAO,CACL,KAAC,oBAAoB,IAAC,QAAQ,EAAE,aAAa,IAAI,QAAQ,YACvD,KAAC,QAAQ,IAAC,QAAQ,EAAE,QAAQ,YAAG,QAAQ,GAAY,GAC9B,CACxB,CAAA;AACH,CAAC"}

package/lib/router.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Subscribe to `react-router` navigation and push a `nav` breadcrumb
+ * on every pathname/search/hash change. Mount once high in the tree
+ * (inside the `Router` and inside `SentoriProvider`):
+ *
+ *     function AppShell() {
+ *       useSentoriRouter()
+ *       return <Outlet />
+ *     }
+ *
+ * The first render does NOT emit a breadcrumb — only actual
+ * transitions are recorded.
+ *
+ * Peer dependency: `react-router >= 7`. This hook is in a separate
+ * entry point so apps not using react-router don't pay the import
+ * cost or trip a missing-module error.
+ */
+export declare function useSentoriRouter(): void;
+//# sourceMappingURL=router.d.ts.map

package/lib/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAcvC"}

package/lib/router.js

@@ -0,0 +1,34 @@
+import { useEffect, useRef } from 'react';
+import { useLocation } from 'react-router';
+import { useSentoriCtx } from './SentoriProvider.js';
+/**
+ * Subscribe to `react-router` navigation and push a `nav` breadcrumb
+ * on every pathname/search/hash change. Mount once high in the tree
+ * (inside the `Router` and inside `SentoriProvider`):
+ *
+ *     function AppShell() {
+ *       useSentoriRouter()
+ *       return <Outlet />
+ *     }
+ *
+ * The first render does NOT emit a breadcrumb — only actual
+ * transitions are recorded.
+ *
+ * Peer dependency: `react-router >= 7`. This hook is in a separate
+ * entry point so apps not using react-router don't pay the import
+ * cost or trip a missing-module error.
+ */
+export function useSentoriRouter() {
+    const { addBreadcrumb } = useSentoriCtx();
+    const location = useLocation();
+    const prevRef = useRef(null);
+    const next = location.pathname + location.search + location.hash;
+    useEffect(() => {
+        const prev = prevRef.current;
+        if (prev !== null && prev !== next) {
+            addBreadcrumb('nav', { from: prev, to: next });
+        }
+        prevRef.current = next;
+    }, [addBreadcrumb, next]);
+}
+//# sourceMappingURL=router.js.map

package/lib/router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.js","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,OAAO,CAAA;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAE1C,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAEpD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,gBAAgB;IAC9B,MAAM,EAAE,aAAa,EAAE,GAAG,aAAa,EAAE,CAAA;IACzC,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAA;IAC9B,MAAM,OAAO,GAAG,MAAM,CAAgB,IAAI,CAAC,CAAA;IAE3C,MAAM,IAAI,GAAG,QAAQ,CAAC,QAAQ,GAAG,QAAQ,CAAC,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAA;IAEhE,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAA;QAC5B,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YACnC,aAAa,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAA;QAChD,CAAC;QACD,OAAO,CAAC,OAAO,GAAG,IAAI,CAAA;IACxB,CAAC,EAAE,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC,CAAA;AAC3B,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@goliapkg/sentori-react",
-  "version": "0.1.0",
-  "description": "React adapter for Sentori — Provider, ErrorBoundary, and hooks built on @goliapkg/sentori-javascript.",
+  "version": "0.3.0",
+  "description": "React adapter for Sentori — Provider, ErrorBoundary (resetKeys + render-prop), Suspense, react-router breadcrumbs, and hooks built on @goliapkg/sentori-javascript.",
   "license": "MIT",
   "homepage": "https://sentori.golia.jp",
   "repository": {
@@ -25,6 +25,10 @@
     ".": {
       "types": "./lib/index.d.ts",
       "default": "./lib/index.js"
+    },
+    "./router": {
+      "types": "./lib/router.d.ts",
+      "default": "./lib/router.js"
     }
   },
   "files": [
@@ -39,7 +43,13 @@
     "prepack": "bun run build"
   },
   "peerDependencies": {
-    "react": ">=18"
+    "react": ">=18",
+    "react-router": ">=7"
+  },
+  "peerDependenciesMeta": {
+    "react-router": {
+      "optional": true
+    }
   },
   "dependencies": {
     "@goliapkg/sentori-core": "0.1.0",
@@ -52,6 +62,7 @@
     "@types/react": "^19",
     "react": "^19",
     "react-dom": "^19",
+    "react-router": "^7",
     "typescript": "^5"
   },
   "publishConfig": {

package/src/SentoriErrorBoundary.tsx

@@ -2,22 +2,29 @@ import { Component, type ErrorInfo, type ReactNode } from 'react'
 
 import { useSentoriCtx } from './SentoriProvider.js'
 
+type FallbackRender = (props: { error: Error; reset: () => void }) => ReactNode
+
 type Props = {
   children: ReactNode
-  /** Rendered after an error is caught. Receives the error and a
-   *  `reset` callback that clears the boundary so retries can run. */
-  fallback: (props: { error: Error; reset: () => void }) => ReactNode
+  /**
+   * Rendered after an error is caught. Either a plain ReactNode
+   * (most common — a static error screen) or a render-prop that
+   * receives the error and a `reset` callback so the fallback can
+   * offer a retry button.
+   */
+  fallback: FallbackRender | ReactNode
   /** Optional additional logging hook. Runs after Sentori capture. */
   onError?: (error: Error, info: ErrorInfo) => void
+  /**
+   * Shallow-compared on update. Any change resets the boundary,
+   * letting parents recover from a caught error by passing fresh
+   * keys (e.g. a route path, a query key, a user id).
+   */
+  resetKeys?: unknown[]
 }
 
 type State = { error: Error | null }
 
-/**
- * Wraps `<SentoriErrorBoundaryInner>` so we can grab the capture
- * function from context — class components can't use hooks directly,
- * but they CAN receive props from a thin functional wrapper.
- */
 export function SentoriErrorBoundary(props: Props) {
   const { captureError } = useSentoriCtx()
   return (
@@ -45,12 +52,32 @@ class SentoriErrorBoundaryInner extends Component<
     this.props.capture(error, info)
   }
 
+  componentDidUpdate(prev: Readonly<Props>): void {
+    if (this.state.error && resetKeysChanged(prev.resetKeys, this.props.resetKeys)) {
+      this.setState({ error: null })
+    }
+  }
+
   reset = (): void => this.setState({ error: null })
 
   render(): ReactNode {
-    if (this.state.error) {
-      return this.props.fallback({ error: this.state.error, reset: this.reset })
+    const { error } = this.state
+    if (error) {
+      const { fallback } = this.props
+      return typeof fallback === 'function'
+        ? (fallback as FallbackRender)({ error, reset: this.reset })
+        : fallback
     }
     return this.props.children
   }
 }
+
+function resetKeysChanged(prev?: unknown[], next?: unknown[]): boolean {
+  if (prev === next) return false
+  if (!prev || !next) return prev !== next
+  if (prev.length !== next.length) return true
+  for (let i = 0; i < prev.length; i++) {
+    if (!Object.is(prev[i], next[i])) return true
+  }
+  return false
+}

package/src/SentoriSuspense.tsx

@@ -0,0 +1,38 @@
+import { Suspense, type ReactNode } from 'react'
+
+import { SentoriErrorBoundary } from './SentoriErrorBoundary.js'
+
+type FallbackRender = (props: { error: Error; reset: () => void }) => ReactNode
+
+/**
+ * `<Suspense>` + `<SentoriErrorBoundary>` composed together. Any
+ * error thrown during render, whether it's a synchronous throw or a
+ * rejected promise surfaced through Suspense, is caught by the
+ * inner boundary and forwarded to `captureError`.
+ *
+ * Use when you want a one-liner around a data-fetching subtree —
+ * the loading state and the error state share the same fallback by
+ * default; pass `errorFallback` if they need to differ.
+ *
+ *     <SentoriSuspense fallback={<Skeleton />} errorFallback={<ErrorCard />}>
+ *       <UserProfile />
+ *     </SentoriSuspense>
+ */
+export function SentoriSuspense({
+  children,
+  errorFallback,
+  fallback,
+}: {
+  children: ReactNode
+  /** Optional separate fallback for caught errors. Falls back to
+   *  `fallback` if not provided. */
+  errorFallback?: FallbackRender | ReactNode
+  /** Loading state shown by the inner `<Suspense>`. */
+  fallback: ReactNode
+}) {
+  return (
+    <SentoriErrorBoundary fallback={errorFallback ?? fallback}>
+      <Suspense fallback={fallback}>{children}</Suspense>
+    </SentoriErrorBoundary>
+  )
+}

package/src/__tests__/SentoriErrorBoundary.test.tsx

@@ -1,5 +1,6 @@
-import { render, screen } from '@testing-library/react'
+import { fireEvent, render, screen } from '@testing-library/react'
 import { describe, expect, test } from 'bun:test'
+import { useState } from 'react'
 
 import { SentoriErrorBoundary } from '../SentoriErrorBoundary.js'
 import { SentoriProvider } from '../SentoriProvider.js'
@@ -17,6 +18,19 @@ const Boom = (): never => {
   throw new Error('boom-from-render')
 }
 
+// React logs an "uncaught error" to console.error when a boundary
+// catches; silence that during render-throw tests so the test output
+// stays readable.
+function silenceConsoleErrorDuring<T>(fn: () => T): T {
+  const original = console.error
+  console.error = () => {}
+  try {
+    return fn()
+  } finally {
+    console.error = original
+  }
+}
+
 describe('SentoriErrorBoundary', () => {
   test('renders children when nothing throws', () => {
     render(
@@ -29,11 +43,8 @@ describe('SentoriErrorBoundary', () => {
     expect(screen.getByText('ok')).toBeDefined()
   })
 
-  test('renders fallback when child throws', () => {
-    // Suppress React's noisy "uncaught error" log in the test output.
-    const original = console.error
-    console.error = () => {}
-    try {
+  test('renders fallback render-prop when child throws', () => {
+    silenceConsoleErrorDuring(() => {
       render(
         <SentoriProvider {...PROVIDER_PROPS}>
           <SentoriErrorBoundary
@@ -43,9 +54,157 @@ describe('SentoriErrorBoundary', () => {
           </SentoriErrorBoundary>
         </SentoriProvider>,
       )
-    } finally {
-      console.error = original
-    }
+    })
     expect(screen.getByText('caught: boom-from-render')).toBeDefined()
   })
+
+  test('accepts a ReactNode fallback (no render-prop)', () => {
+    silenceConsoleErrorDuring(() => {
+      render(
+        <SentoriProvider {...PROVIDER_PROPS}>
+          <SentoriErrorBoundary fallback={<div>static-fallback</div>}>
+            <Boom />
+          </SentoriErrorBoundary>
+        </SentoriProvider>,
+      )
+    })
+    expect(screen.getByText('static-fallback')).toBeDefined()
+  })
+
+  test('reset() callback clears the caught error', () => {
+    // A child that throws on the first render and renders cleanly
+    // once a flag flips. Pressing the fallback's Retry button calls
+    // reset() AND flips the flag, so the boundary re-renders
+    // children without a re-throw.
+    function FlakyChild({ shouldThrow }: { shouldThrow: boolean }) {
+      if (shouldThrow) throw new Error('flaky-boom')
+      return <div>recovered</div>
+    }
+
+    function Harness() {
+      const [throws, setThrows] = useState(true)
+      return (
+        <SentoriErrorBoundary
+          fallback={({ reset }) => (
+            <button
+              onClick={() => {
+                setThrows(false)
+                reset()
+              }}
+              type="button"
+            >
+              Retry
+            </button>
+          )}
+        >
+          <FlakyChild shouldThrow={throws} />
+        </SentoriErrorBoundary>
+      )
+    }
+
+    silenceConsoleErrorDuring(() => {
+      render(
+        <SentoriProvider {...PROVIDER_PROPS}>
+          <Harness />
+        </SentoriProvider>,
+      )
+    })
+    expect(screen.getByText('Retry')).toBeDefined()
+    silenceConsoleErrorDuring(() => fireEvent.click(screen.getByText('Retry')))
+    expect(screen.getByText('recovered')).toBeDefined()
+  })
+
+  test('resetKeys change clears the caught error automatically', () => {
+    function FlakyChild({ shouldThrow }: { shouldThrow: boolean }) {
+      if (shouldThrow) throw new Error('flaky-boom')
+      return <div>recovered-by-keys</div>
+    }
+
+    function Harness() {
+      const [keyA, setKeyA] = useState('one')
+      const [throws, setThrows] = useState(true)
+      return (
+        <>
+          <button
+            onClick={() => {
+              setThrows(false)
+              setKeyA('two')
+            }}
+            type="button"
+          >
+            Switch
+          </button>
+          <SentoriErrorBoundary
+            fallback={<div>error-state</div>}
+            resetKeys={[keyA]}
+          >
+            <FlakyChild shouldThrow={throws} />
+          </SentoriErrorBoundary>
+        </>
+      )
+    }
+
+    silenceConsoleErrorDuring(() => {
+      render(
+        <SentoriProvider {...PROVIDER_PROPS}>
+          <Harness />
+        </SentoriProvider>,
+      )
+    })
+    expect(screen.getByText('error-state')).toBeDefined()
+    silenceConsoleErrorDuring(() => fireEvent.click(screen.getByText('Switch')))
+    expect(screen.getByText('recovered-by-keys')).toBeDefined()
+  })
+
+  test('onError receives the error and React ErrorInfo', () => {
+    let captured: { error: Error | null; info: unknown } = { error: null, info: null }
+
+    silenceConsoleErrorDuring(() => {
+      render(
+        <SentoriProvider {...PROVIDER_PROPS}>
+          <SentoriErrorBoundary
+            fallback={<div>fb</div>}
+            onError={(error, info) => {
+              captured = { error, info }
+            }}
+          >
+            <Boom />
+          </SentoriErrorBoundary>
+        </SentoriProvider>,
+      )
+    })
+
+    expect(captured.error?.message).toBe('boom-from-render')
+    expect(captured.info).toBeDefined()
+    // React 19's ErrorInfo at minimum has componentStack.
+    expect((captured.info as { componentStack?: string }).componentStack).toBeDefined()
+  })
+
+  test('inner boundary catches without bubbling to outer', () => {
+    let outerSawError = false
+
+    silenceConsoleErrorDuring(() => {
+      render(
+        <SentoriProvider {...PROVIDER_PROPS}>
+          <SentoriErrorBoundary
+            fallback={<div>outer-fb</div>}
+            onError={() => {
+              outerSawError = true
+            }}
+          >
+            <SentoriErrorBoundary fallback={<div>inner-fb</div>}>
+              <Boom />
+            </SentoriErrorBoundary>
+            <div>sibling-stays</div>
+          </SentoriErrorBoundary>
+        </SentoriProvider>,
+      )
+    })
+
+    expect(screen.getByText('inner-fb')).toBeDefined()
+    // Sibling next to the inner boundary keeps rendering — the outer
+    // boundary's subtree is intact because the inner caught.
+    expect(screen.getByText('sibling-stays')).toBeDefined()
+    expect(outerSawError).toBe(false)
+  })
 })

package/src/__tests__/SentoriSuspense.test.tsx

@@ -0,0 +1,78 @@
+import { cleanup, render, screen } from '@testing-library/react'
+import { afterEach, describe, expect, test } from 'bun:test'
+
+import { SentoriProvider } from '../SentoriProvider.js'
+import { SentoriSuspense } from '../SentoriSuspense.js'
+
+const PROVIDER_PROPS = {
+  config: {
+    environment: 'test',
+    ingestUrl: 'http://localhost:0',
+    release: 'test@0.0.0',
+    token: 'st_pk_testtesttesttesttesttesttest',
+  },
+}
+
+function silenceConsoleErrorDuring<T>(fn: () => T): T {
+  const original = console.error
+  console.error = () => {}
+  try {
+    return fn()
+  } finally {
+    console.error = original
+  }
+}
+
+describe('SentoriSuspense', () => {
+  afterEach(() => cleanup())
+
+  test('renders children when nothing throws', () => {
+    render(
+      <SentoriProvider {...PROVIDER_PROPS}>
+        <SentoriSuspense fallback={<div>loading</div>}>
+          <div>child-ok</div>
+        </SentoriSuspense>
+      </SentoriProvider>,
+    )
+    expect(screen.getByText('child-ok')).toBeDefined()
+  })
+
+  test('synchronously thrown error inside is caught and renders errorFallback', () => {
+    function Boom(): never {
+      throw new Error('sync-boom')
+    }
+
+    silenceConsoleErrorDuring(() => {
+      render(
+        <SentoriProvider {...PROVIDER_PROPS}>
+          <SentoriSuspense
+            errorFallback={<div>error-fallback</div>}
+            fallback={<div>loading</div>}
+          >
+            <Boom />
+          </SentoriSuspense>
+        </SentoriProvider>,
+      )
+    })
+
+    expect(screen.getByText('error-fallback')).toBeDefined()
+  })
+
+  test('errorFallback defaults to fallback when not provided', () => {
+    function Boom(): never {
+      throw new Error('sync-boom-default')
+    }
+
+    silenceConsoleErrorDuring(() => {
+      render(
+        <SentoriProvider {...PROVIDER_PROPS}>
+          <SentoriSuspense fallback={<div>shared-fallback</div>}>
+            <Boom />
+          </SentoriSuspense>
+        </SentoriProvider>,
+      )
+    })
+
+    expect(screen.getByText('shared-fallback')).toBeDefined()
+  })
+})

package/src/__tests__/router.test.tsx

@@ -0,0 +1,76 @@
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { Link, MemoryRouter, Route, Routes } from 'react-router'
+
+import { clearBreadcrumbs, getBreadcrumbs } from '@goliapkg/sentori-javascript'
+
+import { useSentoriRouter } from '../router.js'
+import { SentoriProvider } from '../SentoriProvider.js'
+
+const PROVIDER_PROPS = {
+  config: {
+    environment: 'test',
+    ingestUrl: 'http://localhost:0',
+    release: 'test@0.0.0',
+    token: 'st_pk_testtesttesttesttesttesttest',
+  },
+}
+
+function Shell() {
+  useSentoriRouter()
+  return (
+    <>
+      <Link to="/orders">orders</Link>
+      <Link to="/billing">billing</Link>
+      <Routes>
+        <Route element={<div>home</div>} path="/" />
+        <Route element={<div>orders-page</div>} path="/orders" />
+        <Route element={<div>billing-page</div>} path="/billing" />
+      </Routes>
+    </>
+  )
+}
+
+describe('useSentoriRouter', () => {
+  beforeEach(() => clearBreadcrumbs())
+  afterEach(() => {
+    cleanup()
+    clearBreadcrumbs()
+  })
+
+  test('initial mount does NOT emit a nav breadcrumb', () => {
+    render(
+      <SentoriProvider {...PROVIDER_PROPS}>
+        <MemoryRouter initialEntries={['/']}>
+          <Shell />
+        </MemoryRouter>
+      </SentoriProvider>,
+    )
+    expect(screen.getByText('home')).toBeDefined()
+    expect(getBreadcrumbs().filter((b) => b.type === 'nav')).toHaveLength(0)
+  })
+
+  test('navigation emits a nav breadcrumb with from/to', () => {
+    render(
+      <SentoriProvider {...PROVIDER_PROPS}>
+        <MemoryRouter initialEntries={['/']}>
+          <Shell />
+        </MemoryRouter>
+      </SentoriProvider>,
+    )
+
+    fireEvent.click(screen.getByText('orders'))
+    expect(screen.getByText('orders-page')).toBeDefined()
+
+    const navs = getBreadcrumbs().filter((b) => b.type === 'nav')
+    expect(navs).toHaveLength(1)
+    expect(navs[0]?.data).toEqual({ from: '/', to: '/orders' })
+
+    fireEvent.click(screen.getByText('billing'))
+    expect(screen.getByText('billing-page')).toBeDefined()
+
+    const navsAfter = getBreadcrumbs().filter((b) => b.type === 'nav')
+    expect(navsAfter).toHaveLength(2)
+    expect(navsAfter[1]?.data).toEqual({ from: '/orders', to: '/billing' })
+  })
+})

package/src/router.ts

@@ -0,0 +1,37 @@
+import { useEffect, useRef } from 'react'
+import { useLocation } from 'react-router'
+
+import { useSentoriCtx } from './SentoriProvider.js'
+
+/**
+ * Subscribe to `react-router` navigation and push a `nav` breadcrumb
+ * on every pathname/search/hash change. Mount once high in the tree
+ * (inside the `Router` and inside `SentoriProvider`):
+ *
+ *     function AppShell() {
+ *       useSentoriRouter()
+ *       return <Outlet />
+ *     }
+ *
+ * The first render does NOT emit a breadcrumb — only actual
+ * transitions are recorded.
+ *
+ * Peer dependency: `react-router >= 7`. This hook is in a separate
+ * entry point so apps not using react-router don't pay the import
+ * cost or trip a missing-module error.
+ */
+export function useSentoriRouter(): void {
+  const { addBreadcrumb } = useSentoriCtx()
+  const location = useLocation()
+  const prevRef = useRef<null | string>(null)
+
+  const next = location.pathname + location.search + location.hash
+
+  useEffect(() => {
+    const prev = prevRef.current
+    if (prev !== null && prev !== next) {
+      addBreadcrumb('nav', { from: prev, to: next })
+    }
+    prevRef.current = next
+  }, [addBreadcrumb, next])
+}