# OpenSpec Change: enterprise-react-error-boundary

- **Change ID**: enterprise-react-error-boundary
- **Package**: `@suaveplan/react-error-boundary`
- **Category**: react
- **Target path**: `react/ui/react-error-boundary`
- **Status**: PROPOSED
- **Date**: 2026-04-24
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/react-error-boundary.md`

---

## Summary

Deliver `@suaveplan/react-error-boundary` on genesis from scratch at enterprise quality. A React class-component error boundary: `ErrorBoundary` (fallback/FallbackComponent/onError/onReset/resetKeys), `DefaultFallback`, and `useErrorBoundary` hook. Genesis adds `@suaveplan/error` integration, OTel span-event capture on catch, i18n for default fallback copy, Storybook stories, and Playwright E2E.

---

## Current-state audit (genesis)

Package does not exist on genesis — fresh build.

---

## Available workspace deps on genesis

| Package | Role |
|---|---|
| `@suaveplan/error` (`workspace:^`) | `SuaveplanError` type narrowing in `onError` |
| `@suaveplan/react-translate` (`workspace:^`) | i18n for `DefaultFallback` copy |
| `@opentelemetry/api` (`catalog:observability`) | Span event `error_boundary.caught` |

External: `tslib catalog:build`. React 18 peer.

---

## Preserved public API surface

```ts
ErrorBoundary         — getDerivedStateFromError + componentDidCatch, resetKeys, onError, onReset
DefaultFallback       — minimal error UI with "Try again" button
useErrorBoundary      — programmatic throw into nearest boundary

// Types
ErrorBoundaryProps, ErrorBoundaryState, FallbackProps, UseErrorBoundaryReturn
```

---

## New additions for genesis

1. **OTel `error_boundary.caught` span event** — attributes: `error.message`, `error.code` (if `SuaveplanError`), `error.type`.
2. **i18n `DefaultFallback`** — "Something went wrong", "Try again" via `useTranslation`.
3. **Storybook** — `ErrorBoundary` default (forced throw), `useErrorBoundary` playground, `DefaultFallback` standalone, custom `FallbackComponent`.
4. **Playwright E2E** — render a component that throws; verify fallback shown; click "Try again"; verify reset.

---

## File layout

```text
react/ui/react-error-boundary/
  package.json
  tsconfig.json
  vitest.config.ts
  src/
    index.ts
    components/
      error-boundary/ (tsx + types + md + test + stories + index)
      default-fallback/ (tsx + types + md + test + stories + index)
    hooks/
      use-error-boundary/ (ts + types + md + test + stories + index)
  e2e/
    error-boundary.spec.ts
```