@goliapkg/sentori-react 0.1.0 → 0.4.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/SentoriTrace.d.ts

@@ -0,0 +1,39 @@
+import { type ReactNode } from 'react';
+/**
+ * Wrap a subtree so its mount-to-unmount lifespan becomes a
+ * `react.render` span. Useful for measuring how long a heavy
+ * component sat on screen — a data table, a chart, a Suspense'd
+ * data fetch:
+ *
+ *     <TraceRender op="react.render" name="OrdersTable">
+ *       <OrdersTable />
+ *     </TraceRender>
+ *
+ * Implementation notes:
+ *
+ * - The span opens when the component renders for the first time
+ *   (in the body of the function, before children render — so child
+ *   spans pick this one up as their parent via `activeSpan()` if
+ *   they're synchronous; React renders top-down but yields between
+ *   commits, so async children won't necessarily attribute to this
+ *   span unless they wrap with `withSpan`).
+ * - The span closes in a `useEffect` cleanup. That runs at unmount
+ *   in normal mode, or twice in StrictMode (mount-unmount-mount).
+ *   StrictMode double-invocation just emits the span twice; this is
+ *   a known dev-mode artifact and matches how React's profiler
+ *   accounts for it.
+ * - Re-renders due to prop / state change do NOT restart the span.
+ *   The mount/unmount boundary is the lifespan. Callers wanting
+ *   per-render timing should use `useRenderTrace` instead (TODO).
+ */
+export declare function TraceRender({ children, data, name, op, tags, }: {
+    children: ReactNode;
+    /** Span data, attached at finish time. */
+    data?: Record<string, unknown>;
+    /** Defaults to `op`. */
+    name?: string;
+    /** Defaults to `react.render`. */
+    op?: string;
+    tags?: Record<string, string>;
+}): ReactNode;
+//# sourceMappingURL=SentoriTrace.d.ts.map

package/lib/SentoriTrace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SentoriTrace.d.ts","sourceRoot":"","sources":["../src/SentoriTrace.tsx"],"names":[],"mappings":"AAAA,OAAO,EAA8B,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAIlE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,WAAW,CAAC,EAC1B,QAAQ,EACR,IAAI,EACJ,IAAI,EACJ,EAAmB,EACnB,IAAI,GACL,EAAE;IACD,QAAQ,EAAE,SAAS,CAAA;IACnB,0CAA0C;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC9B,wBAAwB;IACxB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,kCAAkC;IAClC,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC9B,GAAG,SAAS,CA6BZ"}

package/lib/SentoriTrace.js

@@ -0,0 +1,55 @@
+import { useEffect, useMemo, useRef } from 'react';
+import { startSpan } from '@goliapkg/sentori-core';
+/**
+ * Wrap a subtree so its mount-to-unmount lifespan becomes a
+ * `react.render` span. Useful for measuring how long a heavy
+ * component sat on screen — a data table, a chart, a Suspense'd
+ * data fetch:
+ *
+ *     <TraceRender op="react.render" name="OrdersTable">
+ *       <OrdersTable />
+ *     </TraceRender>
+ *
+ * Implementation notes:
+ *
+ * - The span opens when the component renders for the first time
+ *   (in the body of the function, before children render — so child
+ *   spans pick this one up as their parent via `activeSpan()` if
+ *   they're synchronous; React renders top-down but yields between
+ *   commits, so async children won't necessarily attribute to this
+ *   span unless they wrap with `withSpan`).
+ * - The span closes in a `useEffect` cleanup. That runs at unmount
+ *   in normal mode, or twice in StrictMode (mount-unmount-mount).
+ *   StrictMode double-invocation just emits the span twice; this is
+ *   a known dev-mode artifact and matches how React's profiler
+ *   accounts for it.
+ * - Re-renders due to prop / state change do NOT restart the span.
+ *   The mount/unmount boundary is the lifespan. Callers wanting
+ *   per-render timing should use `useRenderTrace` instead (TODO).
+ */
+export function TraceRender({ children, data, name, op = 'react.render', tags, }) {
+    // Lazy-init via useMemo so the span is created exactly once across
+    // re-renders. Returning the handle from useMemo also means the
+    // effect cleanup captures the same reference.
+    const span = useMemo(() => startSpan(op, { data, name: name ?? op, tags }), 
+    // We deliberately do NOT include op/name/data/tags in deps —
+    // changing them after first render shouldn't reopen the span;
+    // the lifespan is "this component instance", not "these props".
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    []);
+    // The handle is alive across renders but should not be exposed to
+    // child components (they make their own spans). We hold it via ref
+    // so React's strict-mode-friendly invariants are preserved.
+    const spanRef = useRef(span);
+    spanRef.current = span;
+    useEffect(() => {
+        return () => {
+            // Finish on unmount. Second call is a no-op (SpanHandle's
+            // own contract), so StrictMode double-effects don't double-push.
+            spanRef.current?.finish({ status: 'ok' });
+            spanRef.current = null;
+        };
+    }, []);
+    return children;
+}
+//# sourceMappingURL=SentoriTrace.js.map

package/lib/SentoriTrace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SentoriTrace.js","sourceRoot":"","sources":["../src/SentoriTrace.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAkB,MAAM,OAAO,CAAA;AAElE,OAAO,EAAE,SAAS,EAAmB,MAAM,wBAAwB,CAAA;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,WAAW,CAAC,EAC1B,QAAQ,EACR,IAAI,EACJ,IAAI,EACJ,EAAE,GAAG,cAAc,EACnB,IAAI,GAUL;IACC,mEAAmE;IACnE,+DAA+D;IAC/D,8CAA8C;IAC9C,MAAM,IAAI,GAAG,OAAO,CAClB,GAAG,EAAE,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,IAAI,EAAE,EAAE,IAAI,EAAE,CAAC;IACrD,6DAA6D;IAC7D,8DAA8D;IAC9D,gEAAgE;IAChE,uDAAuD;IACvD,EAAE,CACH,CAAA;IAED,kEAAkE;IAClE,mEAAmE;IACnE,4DAA4D;IAC5D,MAAM,OAAO,GAAG,MAAM,CAAoB,IAAI,CAAC,CAAA;IAC/C,OAAO,CAAC,OAAO,GAAG,IAAI,CAAA;IAEtB,SAAS,CAAC,GAAG,EAAE;QACb,OAAO,GAAG,EAAE;YACV,0DAA0D;YAC1D,iEAAiE;YACjE,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAA;YACzC,OAAO,CAAC,OAAO,GAAG,IAAI,CAAA;QACxB,CAAC,CAAA;IACH,CAAC,EAAE,EAAE,CAAC,CAAA;IAEN,OAAO,QAAQ,CAAA;AACjB,CAAC"}

package/lib/index.d.ts

@@ -1,5 +1,7 @@
 export { SentoriProvider } from './SentoriProvider.js';
 export { SentoriErrorBoundary } from './SentoriErrorBoundary.js';
+export { SentoriSuspense } from './SentoriSuspense.js';
+export { TraceRender } from './SentoriTrace.js';
 export { useSentori, useCaptureError } from './hooks.js';
 export type { Breadcrumb, BreadcrumbType, CaptureExtras, SentoriContextValue, SentoriReactConfig, Tags, User, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAA;AAChE,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAExD,YAAY,EACV,UAAU,EACV,cAAc,EACd,aAAa,EACb,mBAAmB,EACnB,kBAAkB,EAClB,IAAI,EACJ,IAAI,GACL,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAA;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAExD,YAAY,EACV,UAAU,EACV,cAAc,EACd,aAAa,EACb,mBAAmB,EACnB,kBAAkB,EAClB,IAAI,EACJ,IAAI,GACL,MAAM,YAAY,CAAA"}

package/lib/index.js

@@ -1,4 +1,6 @@
 export { SentoriProvider } from './SentoriProvider.js';
 export { SentoriErrorBoundary } from './SentoriErrorBoundary.js';
+export { SentoriSuspense } from './SentoriSuspense.js';
+export { TraceRender } from './SentoriTrace.js';
 export { useSentori, useCaptureError } from './hooks.js';
 //# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAA;AAChE,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAA;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA"}

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.4.0",
+  "description": "React adapter for Sentori — Provider, ErrorBoundary (resetKeys + render-prop), Suspense, TraceRender, react-router breadcrumbs + auto-tracing.",
   "license": "MIT",
   "homepage": "https://sentori.golia.jp",
   "repository": {
@@ -25,6 +25,14 @@
     ".": {
       "types": "./lib/index.d.ts",
       "default": "./lib/index.js"
+    },
+    "./router": {
+      "types": "./lib/router.d.ts",
+      "default": "./lib/router.js"
+    },
+    "./trace": {
+      "types": "./lib/SentoriTrace.d.ts",
+      "default": "./lib/SentoriTrace.js"
     }
   },
   "files": [
@@ -39,11 +47,17 @@
     "prepack": "bun run build"
   },
   "peerDependencies": {
-    "react": ">=18"
+    "react": ">=18",
+    "react-router": ">=7"
+  },
+  "peerDependenciesMeta": {
+    "react-router": {
+      "optional": true
+    }
   },
   "dependencies": {
-    "@goliapkg/sentori-core": "0.1.0",
-    "@goliapkg/sentori-javascript": "0.2.0"
+    "@goliapkg/sentori-core": "0.3.0",
+    "@goliapkg/sentori-javascript": "0.3.0"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^17",
@@ -52,6 +66,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/SentoriTrace.tsx

@@ -0,0 +1,76 @@
+import { useEffect, useMemo, useRef, type ReactNode } from 'react'
+
+import { startSpan, type SpanHandle } from '@goliapkg/sentori-core'
+
+/**
+ * Wrap a subtree so its mount-to-unmount lifespan becomes a
+ * `react.render` span. Useful for measuring how long a heavy
+ * component sat on screen — a data table, a chart, a Suspense'd
+ * data fetch:
+ *
+ *     <TraceRender op="react.render" name="OrdersTable">
+ *       <OrdersTable />
+ *     </TraceRender>
+ *
+ * Implementation notes:
+ *
+ * - The span opens when the component renders for the first time
+ *   (in the body of the function, before children render — so child
+ *   spans pick this one up as their parent via `activeSpan()` if
+ *   they're synchronous; React renders top-down but yields between
+ *   commits, so async children won't necessarily attribute to this
+ *   span unless they wrap with `withSpan`).
+ * - The span closes in a `useEffect` cleanup. That runs at unmount
+ *   in normal mode, or twice in StrictMode (mount-unmount-mount).
+ *   StrictMode double-invocation just emits the span twice; this is
+ *   a known dev-mode artifact and matches how React's profiler
+ *   accounts for it.
+ * - Re-renders due to prop / state change do NOT restart the span.
+ *   The mount/unmount boundary is the lifespan. Callers wanting
+ *   per-render timing should use `useRenderTrace` instead (TODO).
+ */
+export function TraceRender({
+  children,
+  data,
+  name,
+  op = 'react.render',
+  tags,
+}: {
+  children: ReactNode
+  /** Span data, attached at finish time. */
+  data?: Record<string, unknown>
+  /** Defaults to `op`. */
+  name?: string
+  /** Defaults to `react.render`. */
+  op?: string
+  tags?: Record<string, string>
+}): ReactNode {
+  // Lazy-init via useMemo so the span is created exactly once across
+  // re-renders. Returning the handle from useMemo also means the
+  // effect cleanup captures the same reference.
+  const span = useMemo(
+    () => startSpan(op, { data, name: name ?? op, tags }),
+    // We deliberately do NOT include op/name/data/tags in deps —
+    // changing them after first render shouldn't reopen the span;
+    // the lifespan is "this component instance", not "these props".
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [],
+  )
+
+  // The handle is alive across renders but should not be exposed to
+  // child components (they make their own spans). We hold it via ref
+  // so React's strict-mode-friendly invariants are preserved.
+  const spanRef = useRef<null | SpanHandle>(span)
+  spanRef.current = span
+
+  useEffect(() => {
+    return () => {
+      // Finish on unmount. Second call is a no-op (SpanHandle's
+      // own contract), so StrictMode double-effects don't double-push.
+      spanRef.current?.finish({ status: 'ok' })
+      spanRef.current = null
+    }
+  }, [])
+
+  return children
+}

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__/SentoriTrace.test.tsx

@@ -0,0 +1,103 @@
+import { clearSpans, drainSpans } from '@goliapkg/sentori-core'
+import { cleanup, render } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+
+import { TraceRender } from '../SentoriTrace.js'
+
+beforeEach(() => clearSpans())
+afterEach(() => {
+  cleanup()
+  clearSpans()
+})
+
+describe('TraceRender', () => {
+  test('renders children', () => {
+    const { getByText } = render(
+      <TraceRender name="page">
+        <span>hello</span>
+      </TraceRender>,
+    )
+    expect(getByText('hello')).toBeDefined()
+  })
+
+  test('opens a react.render span on mount, finishes on unmount', () => {
+    const { unmount } = render(
+      <TraceRender name="OrdersTable">
+        <div>orders</div>
+      </TraceRender>,
+    )
+
+    // Span is open but not yet pushed to buffer.
+    expect(drainSpans()).toHaveLength(0)
+
+    unmount()
+
+    const spans = drainSpans()
+    expect(spans).toHaveLength(1)
+    expect(spans[0]?.op).toBe('react.render')
+    expect(spans[0]?.name).toBe('OrdersTable')
+    expect(spans[0]?.status).toBe('ok')
+    expect(spans[0]?.durationMs).toBeGreaterThanOrEqual(0)
+  })
+
+  test('custom op + tags + data flow through to finished span', () => {
+    const { unmount } = render(
+      <TraceRender
+        data={{ rowCount: 42 }}
+        name="dashboard mount"
+        op="react.mount"
+        tags={{ route: 'dashboard' }}
+      >
+        <div />
+      </TraceRender>,
+    )
+    unmount()
+
+    const sp = drainSpans()[0]!
+    expect(sp.op).toBe('react.mount')
+    expect(sp.name).toBe('dashboard mount')
+    expect(sp.tags).toMatchObject({ route: 'dashboard' })
+    expect(sp.data).toEqual({ rowCount: 42 })
+  })
+
+  test('name defaults to op when omitted', () => {
+    const { unmount } = render(
+      <TraceRender op="react.mount">
+        <div />
+      </TraceRender>,
+    )
+    unmount()
+
+    expect(drainSpans()[0]?.name).toBe('react.mount')
+  })
+
+  test('multiple sequential mounts emit independent spans', () => {
+    const first = render(<TraceRender name="a"><div /></TraceRender>)
+    first.unmount()
+    const second = render(<TraceRender name="b"><div /></TraceRender>)
+    second.unmount()
+
+    const spans = drainSpans()
+    expect(spans).toHaveLength(2)
+    expect(spans.map((s) => s.name).sort()).toEqual(['a', 'b'])
+  })
+
+  test('re-render with new props does NOT restart the span', () => {
+    const { rerender, unmount } = render(
+      <TraceRender name="first">
+        <div />
+      </TraceRender>,
+    )
+    rerender(
+      <TraceRender name="second-name-ignored">
+        <div />
+      </TraceRender>,
+    )
+    unmount()
+
+    const spans = drainSpans()
+    expect(spans).toHaveLength(1)
+    // First-render name wins (lifespan is the component instance).
+    expect(spans[0]?.name).toBe('first')
+  })
+})

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/index.ts

@@ -1,5 +1,7 @@
 export { SentoriProvider } from './SentoriProvider.js'
 export { SentoriErrorBoundary } from './SentoriErrorBoundary.js'
+export { SentoriSuspense } from './SentoriSuspense.js'
+export { TraceRender } from './SentoriTrace.js'
 export { useSentori, useCaptureError } from './hooks.js'
 
 export type {

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])
+}