# vue-error-boundary-kit — AI Reference

Production-ready error boundaries for Vue 3: a declarative `<ErrorBoundary>`
component (`onErrorCaptured`-based) + `useErrorBoundary()` composable for
errors Vue's own lifecycle can't see, adapter-based error reporting
(Sentry/Bugsnag/LogRocket/OTel/HTTP/console — all structurally-typed, none
are real dependencies), retry with exponential backoff, an in-memory error
history/debug panel, breadcrumbs, rate-limiting/dedup, a Nuxt module, and
integrations for vue-router and @tanstack/vue-query. Version 0.3.4. Vue-only
(no React/vanilla build) — unscoped package name (not `@macrulez/...`).

This document is hand-written for AI agents and other tools that generate
code against this package: every signature, default, and behavior note
below is verified directly against the TypeScript source (not summarized
from prose docs). For human-readable narrative docs, see the interactive
site instead:

- Full docs (EN): https://npm.vuecraft.ru/en/packages/vue-error-boundary-kit/guide/overview
- Full docs (RU): https://npm.vuecraft.ru/packages/vue-error-boundary-kit/guide/overview
- GitHub: https://github.com/macrulezru/vue-error-boundary-kit
- npm: https://www.npmjs.com/package/vue-error-boundary-kit

Links below starting with "/" are relative to https://npm.vuecraft.ru.

---

## 1. Package map

| Import path | Contains |
|---|---|
| `vue-error-boundary-kit` | `ErrorBoundary`, `useErrorBoundary`, every shared type (section 2–4). |
| `vue-error-boundary-kit/global-capture` | `useGlobalErrorCapture()` — window `error`/`unhandledrejection` (section 6). |
| `vue-error-boundary-kit/async-boundary` | `AsyncBoundary` — `ErrorBoundary` + `Suspense` composed (section 5). |
| `vue-error-boundary-kit/router` | `useRouterErrorBoundary()` — vue-router `onError()` (section 7). |
| `vue-error-boundary-kit/tanstack-query` | `useQueryErrorReset()` — resets errored `@tanstack/vue-query` queries (section 8). |
| `vue-error-boundary-kit/retry-backoff` | `createBackoffRetry()` — exponential-backoff wrapper around a boundary's `retry()` (section 9). |
| `vue-error-boundary-kit/devtools` | `createErrorHistory()`, `ErrorHistoryPanel` — in-memory debug log (section 10). |
| `vue-error-boundary-kit/testing` | Throw-fixture components + test doubles, framework-agnostic (section 11). |
| `vue-error-boundary-kit/adapters/console` | `createConsoleReporter`, `consoleReporter` singleton (section 12.1). |
| `vue-error-boundary-kit/adapters/http` | `createHttpReporter()` — batched POST + `sendBeacon` on pagehide (12.2). |
| `vue-error-boundary-kit/adapters/sentry` | `createSentryReporter()` — wraps an already-initialized Sentry client (12.3). |
| `vue-error-boundary-kit/adapters/bugsnag` | `createBugsnagReporter()` (12.4). |
| `vue-error-boundary-kit/adapters/logrocket` | `createLogRocketReporter()` (12.5). |
| `vue-error-boundary-kit/adapters/otel` | `createOtelReporter()` (12.6). |
| `vue-error-boundary-kit/adapters/rate-limit` | `createRateLimitedReporter()` — dedup + rate-limit wrapper around any reporter(s) (section 13). |
| `vue-error-boundary-kit/adapters/breadcrumbs` | `createBreadcrumbTrail()`, `withBreadcrumbs()` (section 14). |
| `vue-error-boundary-kit/nuxt` | Nuxt module default export (section 15). |
| `vue-error-boundary-kit/nuxt/runtime` | `useNuxtErrorBoundary()` — catches what escapes every boundary (`vue:error`/`app:error`) (15.3). |

**No app-level plugin/install step exists or is needed** — every export
above is a plain component/composable/factory function; import what you
use directly. `peerDependencies`: only `vue: ^3.4.0` is required.
`@nuxt/kit`, `@tanstack/vue-query`, and `vue-router` are all
`peerDependenciesMeta.optional: true` — the core (`.` entry) has **zero**
runtime dependencies beyond Vue itself.

---

## 2. Core architecture — how capture, isolation, and retry actually work

### 2.1 `CapturedError` — the shape every capture path normalizes to

```ts
type CapturedErrorSource = 'render' | 'async' | 'event' | 'unhandledrejection' | 'manual'

interface CapturedError {
  error: unknown        // the raw thrown value, untouched
  message: string        // err.message if `err instanceof Error`, else String(err)
  stack?: string          // err.stack if Error, else undefined
  componentName?: string  // type.name ?? type.__name (the latter: <script setup>'s SFC-compiler-assigned name)
  lifecycleHook?: string  // Vue's raw onErrorCaptured `info` string, verbatim
  source: CapturedErrorSource
  timestamp: number       // Date.now() at capture time
}
```

### 2.2 `<ErrorBoundary>`'s `onErrorCaptured` — exact mechanism

```ts
onErrorCaptured((err, instance, info) => {
  const isAsyncSetup = instance?.$.type?.setup?.constructor?.name === 'AsyncFunction'
  const captured = normalizeError(err, {
    componentName: instance?.$.type?.name ?? instance?.$.type?.__name,
    lifecycleHook: info,
    source: mapCapturedInfoToSource(info, isAsyncSetup),
  })
  if (props.shouldCatch && !props.shouldCatch(captured)) return true   // pass through untouched
  applyCaptured(captured, { report: true })
  return false   // stops Vue's own propagation to an ancestor onErrorCaptured / app.config.errorHandler
})
```

- **Sync `setup()` throws and async `setup()` rejections share Vue's
  identical `"setup function"` info string** — Vue gives no other way to
  tell them apart. The package disambiguates by checking whether
  `instance.$.type.setup` is an `AsyncFunction` (`.constructor.name`),
  classifying the sync case as `source: 'render'` and the async case as
  `source: 'async'`. This exact check is duplicated in three places
  (`ErrorBoundary.vue`, `useNuxtErrorBoundary`) via a shared
  `mapCapturedInfoToSource(info, isAsyncSetup)` helper.
- `shouldCatch` returning `false` is a **complete pass-through**: no
  state change, no report, no fallback render, no `error` event — as if
  the boundary weren't there. The error keeps propagating via Vue's own
  native bubbling to the next ancestor `onErrorCaptured`/
  `app.config.errorHandler`. This is a different mechanism from `isolate`
  (below), which only applies *after* an error has already been fully
  caught.

### 2.3 `isolate` — the custom bubble channel (NOT native Vue propagation)

Every `<ErrorBoundary>` that accepts an error (via `shouldCatch`) always
returns `false` from `onErrorCaptured`, stopping Vue's native propagation
completely — `isolate` never affects that part. Instead, each boundary
also `provide`s a bubble function under a shared `InjectionKey`, and
`inject`s its own parent's:

```ts
const parentBubble = inject(ERROR_BOUNDARY_BUBBLE_KEY, null)

function applyCaptured(captured, { report }) {
  error.value = captured
  emit('error', captured)
  if (report) dispatchReport(toArray(props.reporter), captured, { internalErrorPrefix: props.internalErrorPrefix })
  if (!props.isolate) parentBubble?.(captured)     // custom bubble, only when isolate === false
}

provide(ERROR_BOUNDARY_BUBBLE_KEY, (captured) => applyCaptured(captured, { report: true }))
```

- `isolate` **defaults to `true`** — an error is fully contained at the
  boundary that caught it and never reaches an ancestor.
- With `isolate: false`: the catching boundary **still shows its own
  fallback** (it already applied `captured` to its own state first), and
  *additionally* invokes the parent's bubble function, which runs the
  identical `applyCaptured` on the **parent boundary too** — so both
  boundaries end up in their own error state and show their own fallback
  **simultaneously**. This is "notify an ancestor too," not "delegate
  exclusively to the ancestor."
- **Reporting is deduped exactly once across the whole chain, regardless
  of isolate**: `dispatchReport()` stamps a non-enumerable `Symbol` on
  the `CapturedError` object itself the first time any dispatch sees it
  (`markReported()`); every later `dispatchReport()` call for that same
  object reference (e.g. from a bubbled-to ancestor) is a no-op. So if
  the innermost boundary already has its own reporter, an outer
  boundary's reporter for the same error is **never called at all** —
  not "called once more."

### 2.4 `retry()` vs `reset()`

```ts
function reset() {
  if (!hasError.value) return
  props.beforeReset?.()   // via safeInvoke — see 2.5
  error.value = null
  retryCount.value = 0     // reset() zeroes retryCount
  emit('reset')
}
function retry() {
  if (!hasError.value || !canRetry.value) return
  props.beforeReset?.()
  retryCount.value += 1    // retry() increments retryCount, never resets it
  error.value = null
  emit('reset')            // retry() reuses the SAME 'reset' event — there's no separate 'retry' event
}
```

- `canRetry = maxRetries === undefined || retryCount < maxRetries`.
  `maxRetries` unset (default) → unlimited retries. Once
  `retryCount >= maxRetries`, `retry()` becomes a no-op and `canRetry`
  flips to `false` (exposed to the `fallback` slot as `can-retry`).
  `maxRetries` counts **successful** `retry()` calls, not failures.
- Both functions clear `error.value` (remounting the `default` slot) and
  both call `beforeReset` and emit `reset` — the *only* functional
  difference is what happens to `retryCount`.

### 2.5 `beforeReset` — NOT `onReset`, and why

`ErrorBoundaryProps` deliberately has no `onReset` field. Naming it that
would collide with Vue's own auto-derived listener prop for the `reset`
emit: `emit('reset')` independently looks up and calls `props.onReset` if
present, **regardless of whether it's a declared prop** — a same-named
user callback would then fire **twice** (once via this package's own
`safeInvoke`-wrapped call, once via Vue's internals, **outside** any
try/catch — a throwing `onReset` would then escape as an unhandled
error, defeating the whole safety-net design). This was a real bug fixed
before first publish.

Every `beforeReset` / `onError` / reporter invocation across the whole
package goes through `safeInvoke`/`safeInvokeAsync` (`internal.ts`),
which catches synchronous throws and rejected promises and logs them via
`console.error` with a configurable `internalErrorPrefix` — default
`'[vue-error-boundary-kit]'`, pass `''` to omit it. This prefix option
appears independently on 6+ different option interfaces throughout the
package (`ErrorBoundaryProps`, `UseErrorBoundaryOptions`,
`UseGlobalErrorCaptureOptions`, `RateLimitOptions`,
`WithBreadcrumbsOptions`, `UseQueryErrorResetOptions`) — each is its own
knob, not shared global state.

### 2.6 `resetKeys` / `resetOnPropsChange`

- **`resetKeys?: unknown[]`** — a `watch` on `[...props.resetKeys]` (a
  spread copy), only fires `reset()` if the boundary currently
  `hasError`, comparing element-by-element via `Object.is` (a length
  change or any changed element triggers it). Leaving it `undefined`
  (default) makes the watch source `null`, disabling the watcher
  entirely. Mirrors `react-error-boundary`'s `resetKeys`.
- **`resetOnPropsChange?: boolean`** (default `false`) — a **separate**
  watch on a full shallow-spread of **every** declared prop
  (`{ ...props }`), reset whenever that snapshot changes while
  `resetOnPropsChange` is (still) `true` and the boundary `hasError`.
  Gotcha: toggling `resetOnPropsChange` itself from `false` → `true`
  changes the watch source from `null` to an object on that render, so
  the *next* change to **any** prop (including `resetKeys` or `reporter`
  changing reference) triggers a reset too — it's not scoped to
  "meaningful" props.

### 2.7 `defineExpose` — imperative access outside the fallback slot

```ts
defineExpose({ error, hasError, retryCount, canRetry, reset, retry })
```
For driving a boundary via a template `ref` from outside its own
`fallback` slot — necessary in particular with `isolate: false`, where an
*outer* boundary's fallback can replace the entire render (including the
inner boundary and any surrounding UI), leaving no slot for a
locally-placed retry control to live in.

---

## 3. `<ErrorBoundary>` — full API

```ts
interface ErrorBoundaryProps {
  resetKeys?: unknown[]
  resetOnPropsChange?: boolean          // default false
  beforeReset?: () => void
  isolate?: boolean                      // default true
  maxRetries?: number                    // default undefined (unlimited)
  reporter?: ErrorReporter | ErrorReporter[]
  shouldCatch?: (error: CapturedError) => boolean
  internalErrorPrefix?: string           // default '[vue-error-boundary-kit]'
}
// Emits: error[error: CapturedError], reset[]
// Slots:
//   default(): unknown
//   fallback(props: { error: CapturedError; reset(): void; retry(): void; retryCount: number; canRetry: boolean }): unknown
// Exposed (via template ref): error, hasError, retryCount, canRetry, reset(), retry()
```

Template logic is exactly: render `default` while `!hasError`, else
render `fallback` with the slot props above. `hasError = error.value !== null`.

---

## 4. `useErrorBoundary(options?)` — programmatic, non-`onErrorCaptured` primitive

```ts
interface UseErrorBoundaryOptions {
  onError?: (error: CapturedError) => void
  beforeReset?: () => void
  reporter?: ErrorReporter | ErrorReporter[]
  reportContext?: Record<string, unknown>
  internalErrorPrefix?: string
}
interface UseErrorBoundaryReturn {
  error: ShallowRef<CapturedError | null>   // shallowRef deliberately — `.error` may hold an arbitrary thrown value
  hasError: ComputedRef<boolean>
  reset(): void
  captureError(err: unknown, info?: { componentName?: string; lifecycleHook?: string; source?: CapturedErrorSource }): CapturedError
}
function useErrorBoundary(options?: UseErrorBoundaryOptions): UseErrorBoundaryReturn
```

- **Not wired to `onErrorCaptured` at all** — a flat "did an error
  happen / clear it" primitive you drive manually via `captureError()`.
  It's what `useGlobalErrorCapture`, `useRouterErrorBoundary`, and
  `useNuxtErrorBoundary` are all built on top of (each just plugs a
  different external hook source into `captureError`).
- `captureError()` **returns** the `CapturedError` it built (for
  inspecting/logging further right at the call site) in addition to
  setting `error.value` and dispatching `onError`/reporters.
- `reset()` here has **no retry-count concept** — that's an
  `<ErrorBoundary>`-only feature.

---

## 5. `<AsyncBoundary>` (`/async-boundary`)

```ts
// Same props/emits as ErrorBoundaryProps above, plus one extra slot:
defineSlots<{ default(): unknown; loading(): unknown; fallback(props: ErrorBoundaryFallbackSlotProps): unknown }>()
```

**Pure composition, not a reimplementation**: `<ErrorBoundary v-bind="props">` wrapping a `<Suspense>` around the `default` slot, with `Suspense`'s own `#fallback` becoming the `loading` slot. `defineExpose` forwards every field through computeds reading the inner `ErrorBoundary`'s template ref. All capture/retry/reset logic lives exclusively in `ErrorBoundary.vue` — `AsyncBoundary` adds **zero new catching capability** over manually nesting `<Suspense>` inside `<ErrorBoundary>` yourself; its only value is convenience (one component instead of two nested ones). Shipped as a separate entry point specifically to keep it out of the core bundle for consumers who never use it.

`retry()` on an `AsyncBoundary` fully remounts the `default` slot, so an async `setup()` inside genuinely re-runs from scratch.

**Nuxt-module gap**: the Nuxt module (section 15) auto-registers only `<ErrorBoundary>` as a global component — `<AsyncBoundary>` is not, and must be imported manually even under Nuxt.

---

## 6. `useGlobalErrorCapture(options?)` (`/global-capture`)

```ts
interface UseGlobalErrorCaptureOptions {
  onError?: (error: CapturedError) => void
  reporter?: ErrorReporter | ErrorReporter[]
  reportContext?: Record<string, unknown>
  captureErrors?: boolean       // default true — window 'error' listener
  captureRejections?: boolean   // default true — window 'unhandledrejection' listener
  shouldCatch?: (error: CapturedError) => boolean
  internalErrorPrefix?: string
}
function useGlobalErrorCapture(options?: UseGlobalErrorCaptureOptions): { stop(): void }
```

Catches what `onErrorCaptured`/`<ErrorBoundary>` structurally cannot:
raw `addEventListener` callbacks, `setTimeout`, unrelated promise chains,
and unhandled rejections. **SSR-safe no-op**: returns
`{ stop: () => {} }` immediately if `typeof window === 'undefined'`,
before registering anything. Auto-cleanup via `onScopeDispose(stop)`
**only if called inside an active Vue effect scope** (e.g. `setup()`) —
call it at module top-level and you must call `stop()` yourself. `error`
source is `'event'`; rejection source is `'unhandledrejection'`. Here,
unlike `<ErrorBoundary>`'s `shouldCatch`, a rejected predicate just drops
the error entirely (no ancestor to propagate to). **Not auto-wired by
anything** — importing this module costs nothing until you actually call
it; the Nuxt module only makes it auto-*importable*, it never calls it
for you.

---

## 7. `useRouterErrorBoundary(options?)` (`/router`)

```ts
function useRouterErrorBoundary(options?: UseErrorBoundaryOptions): UseErrorBoundaryReturn
```
`useErrorBoundary()` wired to `vue-router`'s own `router.onError()` —
catches errors thrown in navigation guards, passed to `next()`, or raised
while resolving an async route component (`component: () => import(...)`),
none of which pass through `onErrorCaptured`. Every captured error here
gets `source: 'manual'` unconditionally — no attempt to distinguish
guard vs. async-component-resolution errors. Auto-unsubscribes via
`onScopeDispose` only inside an active effect scope. `peerDependencies`
accepts `vue-router: ^4.0.0 || ^5.0.0`, but only the 5.x `onError()`
surface was directly verified by the author — the 4.x half is reasoned,
not independently confirmed.

---

## 8. `useQueryErrorReset(options?)` (`/tanstack-query`)

```ts
interface UseQueryErrorResetOptions {
  queryClient?: QueryClient      // default: useQueryClient(id)
  id?: string                     // forwarded to useQueryClient() when queryClient isn't given
  internalErrorPrefix?: string
}
function useQueryErrorReset(options?: UseQueryErrorResetOptions): () => void   // synchronous callback
```

Exists because `@tanstack/vue-query` has **no equivalent** to React
Query's `QueryErrorResetBoundary`. Without this, `<ErrorBoundary>`'s
`retry()`/`reset()` only re-renders the tree — a `useQuery()` that
already failed stays in its cached error state and (with
`throwOnError: true`) re-throws **immediately** on the very next render,
defeating retry entirely. The returned callback is deliberately
**synchronous** so it fits `beforeReset`'s `() => void` signature; the
actual `queryClient.resetQueries({ predicate: q => q.state.status === 'error' })`
call (which returns a `Promise`) is fired via `safeInvokeAsync` —
fire-and-forget, with a rejection caught/logged rather than blocking
`reset()`/`retry()`. Usage: `<ErrorBoundary :before-reset="useQueryErrorReset()">`.

---

## 9. `createBackoffRetry(boundaryRef, options?)` (`/retry-backoff`)

```ts
interface RetryWithBackoffOptions {
  baseDelayMs?: number   // default 1000
  factor?: number         // default 2 (exponential); use 1 for a constant delay
  maxDelayMs?: number     // default 30_000
}
interface BackoffRetryControls { retry(): void; cancel(): void; isPending: Ref<boolean> }
function createBackoffRetry(
  boundaryRef: Ref<{ retry(): void; retryCount: number } | null | undefined>,
  options?: RetryWithBackoffOptions
): BackoffRetryControls
```

Framework-agnostic beyond the `Ref` shape — accepts anything shaped like
`{ retry, retryCount }`, exactly what `<ErrorBoundary>`/`<AsyncBoundary>`'s
`defineExpose` produces via a template ref. Delay formula:
`Math.min(baseDelayMs * factor ** boundary.retryCount, maxDelayMs)` —
reads the **boundary's own** `retryCount` at the moment `retry()` is
called (delay grows with the boundary's retry history, not an internal
counter of its own). `retry()` is a no-op while a timer is already
pending. **The scheduled callback re-reads `boundaryRef.value` at fire
time**, not a snapshot from when `retry()` was called — if the boundary
unmounts while the delay is pending, the scheduled retry silently no-ops
instead of erroring on a stale ref. Not wired into `<ErrorBoundary>`
itself (no `retryDelay` prop) — deliberately kept external.

---

## 10. `createErrorHistory(options?)` + `<ErrorHistoryPanel>` (`/devtools`)

```ts
interface ErrorHistoryEntry extends CapturedError { id: number }   // monotonically increasing
interface ErrorHistoryOptions { limit?: number }   // default 50
interface ErrorHistory {
  entries: ShallowRef<ErrorHistoryEntry[]>   // MOST-RECENT-FIRST
  record: ErrorReporter                       // plug into any `reporter` option to feed this
  clear(): void
}
function createErrorHistory(options?: ErrorHistoryOptions): ErrorHistory
```
```vue
<ErrorHistoryPanel :history="history" />   <!-- history: ErrorHistory -->
```

**Not** a real Vue Devtools browser-extension integration — deliberately
rejected (would've cost ~20 kB gzip for `@vue/devtools-api`, over 10× the
package's core bundle budget). Works purely by riding the `ErrorReporter`
mechanism: `record` is just another reporter, no core code changes
needed to wire it in. `<ErrorHistoryPanel>` uses **inline styles**, not
`<style scoped>`, specifically so Vite doesn't extract a separate
stylesheet a consumer would have to remember to import.

**`entries` order is most-recent-first — the opposite of
`createBreadcrumbTrail()`'s chronological (oldest-first) `entries`.**
Different, deliberate conventions for two similarly-shaped APIs.

---

## 11. `testing.ts` (`/testing`)

Framework-agnostic fixtures, generalized from the package's own internal
test helpers — useful for testing your own boundaries/reporters:

```ts
ThrowInRender    // props { message = 'test error', shouldThrow = true } — throws in render() while shouldThrow
ThrowInSetup     // props { message }; throws synchronously in setup() — same info string as a render throw
ThrowInAsyncSetup // props { message }; async setup(), awaits, then throws — MUST be inside <Suspense>/<AsyncBoundary>
ThrowAbortError   // throws DOMException('...', 'AbortError') matching a cancelled fetch() — for testing shouldCatch filters

function makeCapturedError(overrides?: Partial<CapturedError>): CapturedError
// defaults: message 'test error', error new Error(message), source 'manual', timestamp Date.now()

interface RecordedReport { error: CapturedError; context: Record<string, unknown> | undefined }
interface RecordingReporter extends ErrorReporter { calls: RecordedReport[]; reset(): void }
function createRecordingReporter(): RecordingReporter
// A plain-array test double — not vi.fn()/jest.fn()-dependent, works under any test runner.
```

**Test-writing gotcha**: after mounting a component that throws
synchronously, `error.value` updates *synchronously* inside
`onErrorCaptured`, but the DOM re-render is batched to the next tick —
querying for fallback markup immediately after `mount()` finds nothing;
`await nextTick()` (or `flushPromises()`) first.

---

## 12. Reporting adapters — all structurally-typed, none are real dependencies

Every adapter accepts an **already-initialized** client of the real SDK
and calls it through a minimal "-Like" interface matching just the
methods used — none of `@sentry/vue`, `@bugsnag/js`, `logrocket`, or
`@opentelemetry/api` are actual dependencies of this package; they're
peers you initialize yourself and hand in.

```ts
interface ErrorReporter { report(error: CapturedError, context?: Record<string, unknown>): void | Promise<void> }
```

### 12.1 `createConsoleReporter(options?)` / `consoleReporter`
```ts
interface ConsoleReporterOptions { logger?: Pick<Console, 'error'>; prefix?: string }   // prefix default '[vue-error-boundary-kit]', '' to omit
```
Logs `` `${prefix} (${error.source}) ${error.message}` `` plus `{ error, context }` as a second arg. `consoleReporter` is a pre-built `createConsoleReporter()` singleton.

### 12.2 `createHttpReporter(options)`
```ts
interface HttpReporterOptions {
  endpoint: string                                              // required
  batchInterval?: number   // default 0 = send immediately
  maxBatchSize?: number    // default 10 — flushes early even if batchInterval hasn't elapsed
  headers?: Record<string, string>
  serialize?: (error: CapturedError, context?: Record<string, unknown>) => unknown   // default { ...corePayloadFields(error), context }
}
```
POSTs via `fetch(..., { keepalive: true })` normally. Registers a
`document`'s `pagehide` listener (once, at reporter-creation time,
**permanently — no cleanup/`stop()` exists**) that force-flushes any
pending batch via `navigator.sendBeacon` instead, since an in-flight
`fetch` can be aborted when the page is actually closing; falls back to
`fetch` if `sendBeacon` is unavailable or returns `false`.

### 12.3 `createSentryReporter({ client, tags? })`
```ts
interface SentryReporterOptions { client: { captureException(error: unknown, hint?: Record<string, unknown>): string | undefined }; tags?: Record<string, string> }
```
Calls `client.captureException(error.error, { contexts: { errorBoundary: {message, componentName, lifecycleHook, source, timestamp} }, tags, extra: context })` — passes the **raw original error**, not the normalized message/stack, as Sentry's first arg.

### 12.4 `createBugsnagReporter({ client, severity? })`
```ts
interface BugsnagReporterOptions { client: { notify(error: unknown, onError?: (event) => void): void }; severity?: 'info' | 'warning' | 'error' }
```
`client.notify(error.error, event => { if (severity) event.severity = severity; if (componentName) event.context = componentName; event.addMetadata('errorBoundary', {...corePayloadFields, ...context}) })`. `severity` only overwrites the event when explicitly passed (Bugsnag itself defaults to `'warning'`).

### 12.5 `createLogRocketReporter({ client, tags? })`
```ts
interface LogRocketReporterOptions { client: { captureException(error: unknown, options?: {tags?; extra?}): void }; tags?: Record<string, string> }
```
`extra` is passed through `toScalarRecord()` first — LogRocket requires scalar (`string|number|boolean`) values only; anything else is `JSON.stringify`'d.

### 12.6 `createOtelReporter({ tracer, spanName?, attributes? })`
```ts
interface OtelReporterOptions { tracer: { startSpan(name: string): OtelSpanLike }; spanName?: string /* default 'error-boundary-kit.error' */; attributes?: Record<string, string|number|boolean> }
```
Starts a **fresh span per error** (not attached to any "current" span by
default — pass `{ startSpan: () => trace.getActiveSpan() ?? realTracer.startSpan(name) }`
if you want that). Calls `recordException({message, stack})` +
`setStatus({code: 2, message})` — **`2` is `SpanStatusCode.ERROR`,
hardcoded as a literal** (not imported from `@opentelemetry/api`, to
avoid the dependency), verified against `@opentelemetry/api@1.9.1`'s enum
(`UNSET=0, OK=1, ERROR=2`) — version-fragile if OTel ever renumbers it.
Attaches `corePayloadFields(error)` + scalar-coerced `context` +
`attributes` as span attributes (skipping `undefined` values), then
`span.end()`.

---

## 13. `createRateLimitedReporter(reporter, options?)` (`/adapters/rate-limit`)

```ts
interface RateLimitOptions {
  maxPerWindow?: number       // default 10 — across ALL signatures combined
  windowMs?: number            // default 10_000
  dedupWindowMs?: number       // default = windowMs
  onSuppressed?: (error: CapturedError, info: { reason: 'dedup' | 'rate-limit'; count: number }) => void
  internalErrorPrefix?: string
}
function createRateLimitedReporter(reporter: ErrorReporter | ErrorReporter[], options?: RateLimitOptions): ErrorReporter
```

Wraps one or more reporters with **two independent gates**, checked in
this order:
1. **Dedup**: key = `` `${source}:${componentName ?? ''}:${message}` ``.
   A repeat of the same key within `dedupWindowMs` of its first
   occurrence is suppressed (only `onSuppressed` fires, with a running
   `count`); the first occurrence of any key always passes this gate.
2. **Rate limit**: a rolling window (reset once
   `now - windowStart >= windowMs`) caps total reports **across all
   distinct signatures combined** at `maxPerWindow` — this applies even
   to a first-time-seen signature that already passed dedup.

Every wrapped reporter runs via `safeInvokeAsync` independently, so one
throwing reporter doesn't block the others. Memory-leak guard: once the
internal dedup `Map` reaches 1000 entries, it sweeps out any entry whose
`dedupWindowMs` has already elapsed before processing the current call.

---

## 14. `createBreadcrumbTrail(options?)` + `withBreadcrumbs()` (`/adapters/breadcrumbs`)

```ts
interface Breadcrumb { category: string; message: string; timestamp: number; data?: Record<string, unknown> }
interface AddBreadcrumbInput { category: string; message: string; timestamp?: number /* default Date.now() */; data?: Record<string, unknown> }
interface BreadcrumbTrailOptions { limit?: number }   // default 20
interface BreadcrumbTrail {
  entries: ShallowRef<Breadcrumb[]>   // CHRONOLOGICAL, oldest-first — entries.value.at(-1) is most recent
  addBreadcrumb(input: AddBreadcrumbInput): void
  record: ErrorReporter                // pass alongside real reporters to auto-record captured errors as breadcrumbs too
  clear(): void
}
function createBreadcrumbTrail(options?: BreadcrumbTrailOptions): BreadcrumbTrail

interface WithBreadcrumbsOptions { trail: BreadcrumbTrail; contextKey?: string /* default 'breadcrumbs' */; internalErrorPrefix?: string }
function withBreadcrumbs(reporter: ErrorReporter | ErrorReporter[], options: WithBreadcrumbsOptions): ErrorReporter
```

**Nothing is auto-instrumented** — no automatic click/navigation
capture; call `addBreadcrumb()` yourself wherever relevant (a router
hook, a click listener, a store action). `entries`' oldest-first order is
the deliberate **opposite** of `createErrorHistory()`'s most-recent-first
— matches Sentry/APM breadcrumb convention (a timeline leading up to the
error) rather than a debug-log convention. `withBreadcrumbs()` merges
`trail.entries.value` into every wrapped `report()` call's `context`
under `contextKey`.

---

## 15. Nuxt module (`/nuxt`, config key `errorBoundaryKit`)

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['vue-error-boundary-kit/nuxt'],
  errorBoundaryKit: {
    component: true,      // default true — auto-registers <ErrorBoundary> globally
    autoImports: true,     // default true — see the exact list below
  },
})
```
```ts
interface ModuleOptions { component?: boolean; autoImports?: boolean }
```

### 15.1 What's actually auto-wired

- `component: true` → `addComponent({ name: 'ErrorBoundary', ... })` —
  **only** `<ErrorBoundary>` is global. `<AsyncBoundary>` and
  `<ErrorHistoryPanel>` are **not** — import them manually even under
  Nuxt.
- `autoImports: true` → exactly three composables auto-imported:
  `useErrorBoundary`, `useGlobalErrorCapture` (from
  `vue-error-boundary-kit/global-capture`), `useNuxtErrorBoundary` (from
  `vue-error-boundary-kit/nuxt/runtime`). **Not** auto-imported:
  `useRouterErrorBoundary`, `useQueryErrorReset`, `createBackoffRetry`,
  `createErrorHistory`, any adapter factory — import those manually.

### 15.2 A real bug that WAS found and fixed (worth knowing, not a live issue)

`@nuxt/kit`'s type-reference machinery (`writeTypes`) resolves a
`modules: [...]` entry to its **nearest `package.json`** regardless of
which subpath was actually imported — meaning it always points at this
package's root `types` field (`dist/index.d.ts`), never
`src/nuxt/types.ts`. Without an explicit fix, the
`declare module '@nuxt/schema' { interface NuxtConfig { errorBoundaryKit?: ModuleOptions } }`
augmentation would silently never reach a consumer's `nuxt.config.ts`
typing. **Fixed**: the module explicitly pushes
`{ types: 'vue-error-boundary-kit/nuxt' }` via the `prepare:types` hook.
`compatibility.nuxt: '>=3.0.0'` is honestly caveated as only directly
verified against Nuxt 4.5.2 — the Nuxt 3 half of the range is reasoned,
not independently confirmed.

### 15.3 `useNuxtErrorBoundary(options?)` (`/nuxt/runtime`)

```ts
function useNuxtErrorBoundary(options?: UseErrorBoundaryOptions): UseErrorBoundaryReturn
```
`useErrorBoundary()` wired to **two** Nuxt app hooks, catching what
escapes every `<ErrorBoundary>` in the tree:
- `nuxtApp.hook('vue:error', ...)` — a Vue render/setup error that
  reached the app root uncaught (same `mapCapturedInfoToSource`/
  `isAsyncSetup` classification logic as `<ErrorBoundary>` itself).
- `nuxtApp.hook('app:error', ...)` — Nuxt's own `showError()`/
  `createError()` fatal-error flow, which never goes through
  `onErrorCaptured` at all; captured with `source: 'manual'`.

Both hooks run isomorphically (SSR + client) — one call (typically in
`app.vue`'s `<script setup>`) covers both environments.

---

## 16. SSR / hydration behavior

- `renderToString` **never throws** because of a failing boundary child
  — sibling content renders normally; `error`/reporter events fire on
  the server exactly as on the client (exactly once per error).
- **Structural limitation, not a bug**: Vue 3's SSR renderer has no
  reactive "second pass" — by the time `onErrorCaptured` sets
  `error.value` during a synchronous throw in `renderToString`, that
  subtree's `render()` output has **already been serialized**. A failed
  subtree's server HTML comes out as an **empty placeholder**, never the
  actual `fallback` slot markup. This is true even for a bare
  `<Suspense>` with no boundary at all whose default branch rejects —
  `Suspense` SSR buffering only waits for *unresolved* async deps, with
  no mechanism to commit the `#fallback` branch on a *rejection*.
- **Hydration always converges to the correct interactive client
  state**, even if server and client disagree about whether the child
  fails — Vue's hydration-mismatch recovery may log a dev-only warning,
  but the client never gets stuck on stale server output and never
  crashes.

---

## 17. Consolidated gotcha list

1. `beforeReset`, not `onReset` — named that way specifically to avoid
   colliding with Vue's auto-derived `props.onReset` listener for the
   `reset` emit (a real bug, fixed pre-publish; see 2.5).
2. `retry()` increments `retryCount`; `reset()` zeroes it. Both
   otherwise do the same thing (clear error, run `beforeReset`, emit
   `reset` — there's no separate `retry` event) (2.4).
3. `isolate: false` does **not** hand off exclusively to the parent —
   both the catching boundary and the bubbled-to ancestor end up in
   their own error/fallback state simultaneously; only the *reporter*
   dispatch is deduped to fire exactly once across the chain (2.3).
4. `shouldCatch` returning `false` is a complete pass-through (no
   state/report/event at all) — different in kind from `isolate: false`,
   which still fully catches locally and additionally notifies upward
   (2.2 vs 2.3).
5. Sync `setup()` throws and async `setup()` rejections share Vue's
   identical `"setup function"` info string; disambiguated by checking
   `setup.constructor.name === 'AsyncFunction'`, duplicated in
   `ErrorBoundary.vue` and `useNuxtErrorBoundary` (2.2).
6. `<AsyncBoundary>` adds zero new catching capability over manually
   nesting `<Suspense>` inside `<ErrorBoundary>` — purely ergonomic —
   and is **not** auto-registered by the Nuxt module (only
   `<ErrorBoundary>` is) (section 5, 15.1).
7. SSR never renders the `fallback` slot's actual markup for a failed
   subtree — always an empty placeholder, a structural Vue 3 SSR
   limitation, not a bug (section 16).
8. `createHttpReporter`'s `pagehide` listener is registered permanently
   at creation time with no way to remove it (12.2).
9. `createOtelReporter` hardcodes OTel's `SpanStatusCode.ERROR` as the
   literal `2` rather than importing the enum, by design (no
   `@opentelemetry/api` dependency) — version-fragile if OTel ever
   renumbers it (12.6).
10. `useQueryErrorReset()`'s returned callback is synchronous by design
    to fit `beforeReset`'s `() => void` signature; the actual
    `resetQueries()` call is fire-and-forget via `safeInvokeAsync`
    (section 8).
11. `internalErrorPrefix` (package-wide safety-net logging prefix) and
    an adapter's own formatting `prefix` (e.g. `createConsoleReporter`)
    are separate, independently configurable knobs that happen to share
    a default string (2.5, 12.1).
12. `createErrorHistory()`'s `entries` is most-recent-first;
    `createBreadcrumbTrail()`'s `entries` is oldest-first (chronological)
    — opposite, deliberate conventions for two similarly-shaped APIs
    (10, 14).
13. `createRateLimitedReporter`'s `maxPerWindow` counts reports across
    **all** distinct error signatures combined, not per-signature — a
    first-time-seen signature can still be suppressed by the rate-limit
    gate even though it passed dedup (13).
14. The Nuxt module's `autoImports` list is exactly three composables
    (`useErrorBoundary`, `useGlobalErrorCapture`, `useNuxtErrorBoundary`)
    — `useRouterErrorBoundary`, `useQueryErrorReset`,
    `createBackoffRetry`, `createErrorHistory`, and every adapter
    factory must be imported manually even under Nuxt (15.1).
15. `package.json`'s `engines.node` (`^20.19.0 || >=22.12.0`) is a
    **build-toolchain-only** constraint (Vite 8/rolldown) — it does not
    restrict what Node version can run the published `dist/` output.