@backtrack-js/browser 0.4.2 → 0.5.1

package/README.md

@@ -1,364 +1,507 @@
-# Backtrack
-
-A flight recorder for your web app. Replay the exact moments before a bug, privately and offline.
-
-[![npm version](https://img.shields.io/npm/v/@backtrack-js/browser.svg)](https://www.npmjs.com/package/@backtrack-js/browser)
-[![license](https://img.shields.io/badge/license-Free_to_Use-blue.svg)](LICENSE)
-
-<!-- TODO: add a GIF or screenshot of the Incident Viewer here (this is the highest-impact change) -->
-<!-- ![Backtrack Incident Viewer](./docs/viewer.gif) -->
-
-Your users hit a bug you can't reproduce. Error trackers tell you what broke, but not what the user did before it did.
-
-Backtrack keeps the last few minutes of DOM changes, clicks, network calls, console logs and errors in a rolling local buffer. When something breaks (or the user asks for help), it freezes that buffer into a replayable incident file. Open it in the built-in viewer and press play.
-
-- **Private by default.** Passwords, card numbers, CPFs and form inputs are masked. Request and response bodies are off unless you turn them on. Nothing leaves the browser unless you export an incident or configure a transport.
-- **Light on the page.** Recording runs into a ring buffer in IndexedDB with automatic retention, so old events are dropped instead of piling up.
-- **Framework-agnostic.** Pure TypeScript core, no React or other framework in your client bundle. ESM and CommonJS builds.
-- **Replay offline.** An interactive viewer with DOM playback, a synchronized timeline, and console and network panels. No account, no server.
-- **Readable production stack traces.** `backtrack symbolize` maps minified frames like `app.min.js:1:48213` back to your original TypeScript, with the surrounding source lines.
-- **Send it where you want.** `transport` and `beforeSend` let you forward incidents to your own backend or observability stack.
-
----
-
-## Why Backtrack?
-
-| Feature | Error trackers | Hosted session replay | Backtrack |
-| :--- | :---: | :---: | :---: |
-| Shows the error and stack trace | ✅ | ✅ | ✅ |
-| Shows what the user did before it | ⚠️ limited breadcrumbs | ✅ | ✅ |
-| Data stays in the browser by default | ❌ | ❌ | ✅ |
-| Works fully offline | ❌ | ❌ | ✅ |
-| Only records around incidents | n/a | ❌ usually continuous upload | ✅ rolling buffer |
-
-Backtrack doesn't replace your error tracker. It gives you the context your error tracker is missing, and you can correlate the two with `traceId` and `release` (see [Release and trace correlation](#release-and-trace-correlation)).
-
----
-
-## Installation
-
-```bash
-# npm
-npm install @backtrack-js/browser
-
-# yarn
-yarn add @backtrack-js/browser
-
-# pnpm
-pnpm add @backtrack-js/browser
-```
-
----
-
-## Quick Start
-
-```typescript
-import { Backtrack } from '@backtrack-js/browser';
-
-const recorder = new Backtrack({
-  bufferMinutes: 5,       // keep the last 5 minutes in the rolling buffer
-  afterErrorSeconds: 15,  // keep recording 15s after an error
-});
-
-await recorder.start();
-
-// Optional: capture manually, e.g. from a "Report a problem" button
-const incidentId = await recorder.capture('User reported payment bug', 30);
-```
-
-Then inspect it:
-
-```bash
-npx backtrack
-```
-
-Drag an exported incident `.json` into the viewer and hit play.
-
----
-
-## Readable production stack traces (`backtrack symbolize`)
-
-Production bundles are minified, so a stack frame like `app.3f9a1c.js:1:48213` tells you nothing. `backtrack symbolize` reads your source maps and rewrites the incident's errors with the original file, line, column and the surrounding source code.
-
-```bash
-npx backtrack symbolize <incident> --sourcemaps <directory> [options]
-```
-
-| Argument / option | Description |
-| :--- | :--- |
-| `<incident>` | Path to an exported incident: `.json`, `.ffr.json`, `.gz` or `.ffr.json.gz`. Gzip is detected automatically. |
-| `--sourcemaps <directory>` | Directory containing your `.js.map`, `.mjs.map` and `.cjs.map` files. Searched recursively (e.g. `./dist`, `./build`). |
-| `--output <file>` | Custom output path. Defaults to `<name>.symbolicated.ffr.json` next to the original. The output can never overwrite the input file. |
-| `--context-lines <number>` | Lines of original source shown before and after the failing line. Range 0–10, default 3. |
-| `-h, --help` | Show help. |
-
-### Example
-
-```bash
-npx backtrack symbolize ./incidents/checkout-bug.ffr.json --sourcemaps ./dist --context-lines 5
-```
-
-```text
-[Backtrack] Symbolication concluída.
-
-Incidente: inc_1727500000_3f2a
-Erros encontrados: 1
-Frames resolvidos: 4
-Frames não resolvidos: 0
-Saída: /projects/app/incidents/checkout-bug.symbolicated.ffr.json
-```
-
-If some frames have no matching source map, the command reports a partial symbolication with warnings instead of failing.
-
-Open the `.symbolicated.ffr.json` file in the viewer (`npx backtrack`) and the error tab shows the resolved stack trace, with the failing line highlighted:
-
-```text
-applyCoupon  src/cart/coupon.ts:42:18
-
-40 function applyCoupon(cart, coupon) {
-41   // coupon discount might be missing from API
-42   const off = coupon.discount.percent;   <-- highlighted
-43   return cart.total * (1 - off / 100);
-44 }
-```
-
-### What it does (and doesn't do)
-
-- **Validates safely:** Reads the incident (up to 50 MB, gzip supported) and validates its schema with a strict validator. The original file is never modified.
-- **Maps V8 frames:** Finds error events that carry a stack and maps each minified frame with [@jridgewell/trace-mapping](https://github.com/jridgewell/trace-mapping).
-- **Extracts source context:** Extracts the original code from `sourcesContent`, so your source maps must include it.
-- **Doesn't leak local paths:** File paths are normalized (e.g. `C:\Users\alice\...` or `/home/bob/...` become paths starting at `src/`).
-- **Atomic write:** Writes the result atomically (to a `.tmp` file, then renames) and stores it in a new `resolvedStack` field.
-
----
-
-## Privacy & Data Masking
-
-Backtrack is designed with strict security defaults:
-
-- **Inputs & Forms:** All `<input>`, `<textarea>`, and `<select>` values are masked by default (`maskAllInputs: true`).
-- **Network Headers:** Authorization, Cookies, API keys, and Bearer tokens are automatically redacted.
-- **Sensitive Selectors:** Use standard selectors or CSS classes to protect proprietary or personal data:
-
-```typescript
-const recorder = new Backtrack({
-  privacy: {
-    maskAllInputs: true,
-    blockMedia: true,
-    blockSelector: '.backtrack-block, [data-private]',      // Completely hides elements in replay
-    maskTextSelector: '.backtrack-mask, .customer-pII',     // Scrambles text content
-    sanitizeUrl: (url) => {
-      // Remove sensitive query parameters
-      url.searchParams.delete('token');
-      return url.toString();
-    }
-  }
-});
-```
-
----
-
-## Network & Payload Capture
-
-Network requests and responses can be configured using `network` options:
-
-```typescript
-const recorder = new Backtrack({
-  network: {
-    capturePayloads: false, // Bodies are disabled by default for privacy
-    maxPayloadSize: 64 * 1024
-  }
-});
-```
-
-- **Bodies are not captured by default (`capturePayloads: false`):** Request and response bodies are disabled by default to prevent unintentional data leakage. HTTP method, URL, status, timing, and sanitized headers continue to be captured.
-- **Enabling bodies increases the risk of PII:** Enabling `capturePayloads: true` should be done mindfully according to your compliance and privacy requirements.
-- **Sanitization remains active:** Even when payload capture is explicitly enabled, Backtrack continues to sanitize and redact known sensitive keys (passwords, tokens, credentials, etc.) and patterns (Bearer tokens, emails, CPFs, cards).
-- **`maxPayloadSize` is a limit per payload, not per incident:** It bounds each individual request or response body (default is `64 * 1024` bytes). Payloads exceeding this limit are truncated safely with a truncation marker.
-
----
-
-## Capturing Incidents
-
-### Automatic Triggers
-Backtrack automatically triggers and freezes an incident when:
-1. An unhandled window exception occurs (`window.onerror`).
-2. An unhandled promise rejection occurs (`unhandledrejection`).
-3. An HTTP request returns a matching error status (`captureHttpStatus`).
-
-### Manual Capture
-You can trigger incident recording manually anywhere in your code (e.g. from an error boundary or user feedback modal):
-
-```typescript
-// Capture the last 60 seconds of context
-const incidentId = await recorder.capture('Checkout error', 60);
-
-// Export the complete incident artifact as a JSON object
-const artifact = await recorder.exportIncident(incidentId);
-
-// Download or send artifact to your support/logging service
-const jsonBlob = new Blob([JSON.stringify(artifact, null, 2)], { type: 'application/json' });
-```
-
-### Exception Capture
-In React Error Boundaries or try/catch blocks:
-
-```typescript
-recorder.captureException(error, {
-  source: 'react',
-  componentStack: errorInfo.componentStack
-});
-```
-
----
-
-## Remote Transport & beforeSend
-
-Backtrack allows applications to automatically dispatch finalized incidents to any remote endpoint or telemetry backend using `transport` and `beforeSend`:
-
-```typescript
-const recorder = new Backtrack({
-  transport: {
-    async send(artifact) {
-      const response = await fetch('/api/backtrack/incidents', {
-        method: 'POST',
-        headers: {
-          'content-type': 'application/json'
-        },
-        body: JSON.stringify(artifact)
-      });
-
-      if (!response.ok) {
-        throw new Error(`Upload failed: ${response.status}`);
-      }
-    }
-  },
-
-  beforeSend(artifact) {
-    if (artifact.environment.url.includes('/healthcheck')) {
-      return null;
-    }
-
-    return artifact;
-  }
-});
-```
-
-### Dispatch Flow & Semantics
-
-- **Sent Only When Finalized:** Incidents are dispatched only after they have been completely finalized and safely written to IndexedDB.
-  ```text
-  incident finalized
-          ↓
-    build artifact
-          ↓
-      beforeSend
-          ↓
-  null? cancel upload
-          ↓
-    transport.send
-  ```
-- **Role of `beforeSend`:**
-  - Affects **only** the automated transmission via `transport.send`.
-  - Does **not** mutate the artifact stored in local IndexedDB.
-  - Does **not** affect `getArtifact()` or explicit file downloads via `exportIncident()`.
-  - Returning `null` cancels the upload.
-  - If `beforeSend` throws an error, the upload is aborted cleanly without affecting the application or the recorded incident.
-- **Fault Isolation:** Network or transport errors will never break the host application, reject user captures, delete local incidents, prevent finalization, or trigger unhandled promise rejections.
-- **Concurrency & Delivery Guarantees:**
-  - Each finalized incident triggers at most one upload attempt.
-  - Multiple incidents can upload concurrently.
-  - `stop()` does not wait for pending network uploads.
-  - There is currently no delivery guarantee (persistent retry queue, offline backoff, etc.); if transport fails, the incident remains saved in local IndexedDB and can be accessed or resent by the application.
-
----
-
-## Release and trace correlation
-
-Backtrack artifacts (`formatVersion: 2`) provide an observability `context` to correlate client-side replays with backend traces, application releases, and environments.
-
-### Static Context
-
-Configure static metadata when initializing Backtrack:
-
-```typescript
-const recorder = new Backtrack({
-  context: {
-    release: 'checkout-web@2.14.0',
-    environment: 'production',
-    traceId: '4bf92f3577b34da6a3ce929d0e0e4736',
-    spanId: '00f067aa0ba902b7'
-  }
-});
-```
-
-### Dynamic Context (`getContext`)
-
-When trace IDs or active environments change dynamically during user navigation (e.g. from OpenTelemetry, Datadog, Sentry, or custom APM SDKs), use `getContext` to evaluate the latest context at incident export time:
-
-```typescript
-const recorder = new Backtrack({
-  context: {
-    release: 'checkout-web@2.14.0',
-    environment: 'production'
-  },
-  getContext: async () => {
-    const activeSpan = tracer.getActiveSpan();
-    const spanContext = activeSpan?.spanContext();
-
-    return {
-      release: 'checkout-web@2.14.0',
-      environment: 'production',
-      traceId: spanContext?.traceId,
-      spanId: spanContext?.spanId
-    };
-  }
-});
-```
-
-### Correlation Semantics
-
-- **Precedence:** `getContext() > context (static) > environment metadata`.
-- **Trace correlation scope:** Backtrack **only correlates** external trace and span identifiers supplied by your application. It does **not** generate backend traces, start trace spans, or perform distributed instrumentation on its own.
-- **Normalization:** `traceId` (32 hex characters) and `spanId` (16 hex characters) are validated and normalized to lowercase. A `spanId` cannot be supplied without an accompanying `traceId`.
-- **Fault Resilience:** If `getContext()` throws an error or rejects, incident export continues safely using available static context without failing the export or losing incident data.
-
----
-
-## Inspecting Incidents (Viewer)
-
-Backtrack includes an offline visualizer with video replay, console logs, network inspection, and breadcrumbs.
-
-### Launch the Viewer CLI
-Run the embedded CLI to launch the local visualizer:
-
-```bash
-npx backtrack
-```
-
-This starts a local server at `http://localhost:5173/` and opens your default browser. Drag and drop any exported incident `.json` file to replay it!
-
----
-
-## API Reference
-
-### `Backtrack`
-
-| Method | Return Type | Description |
-| --- | --- | --- |
-| `start()` | `Promise<void>` | Initializes storage and begins recording. |
-| `stop()` | `Promise<void>` | Stops recording, flushes pending batches to storage, and detaches listeners. |
-| `capture(reason?, windowSeconds?)` | `Promise<string>` | Manually captures and finalizes an incident. Returns incident ID. |
-| `captureException(error, context?)` | `Promise<string \| undefined> \| void` | Records a caught exception and triggers an incident. |
-| `listIncidents()` | `Promise<IncidentSummary[]>` | Lists all stored incidents. |
-| `getArtifact(incidentId)` | `Promise<FlightRecorderArtifact>` | Retrieves the full artifact for an incident (v1 or v2). |
-| `exportIncident(incidentId)` | `Promise<FlightRecorderArtifact>` | Exports the artifact and marks it finalized. |
-| `deleteIncident(incidentId)` | `Promise<void>` | Deletes an incident from local storage. |
-| `clear()` | `Promise<void>` | Clears all stored chunks, sessions, and incidents. |
-| `getHealth()` | `RecorderHealth` | Returns current buffer status, storage usage, and state. |
-
----
-
-## License
-
-[Backtrack Free-Use License](LICENSE) — Free for personal and commercial integration. Redistribution, copying, or creating derivative/competing works is strictly prohibited.
+# Backtrack
+
+A flight recorder for your web app. Replay the exact moments before a bug, privately and offline.
+
+[![npm version](https://img.shields.io/npm/v/@backtrack-js/browser.svg)](https://www.npmjs.com/package/@backtrack-js/browser)
+[![license](https://img.shields.io/badge/license-Free_to_Use-blue.svg)](LICENSE)
+
+<!-- TODO: add a GIF or screenshot of the Incident Viewer here (this is the highest-impact change) -->
+<!-- ![Backtrack Incident Viewer](./docs/viewer.gif) -->
+
+Your users hit a bug you can't reproduce. Error trackers tell you what broke, but not what the user did before it did.
+
+Backtrack keeps the last few minutes of DOM changes, clicks, network calls, console logs and errors in a rolling local buffer. When something breaks (or the user asks for help), it freezes that buffer into a replayable incident file. Open it in the built-in viewer and press play.
+
+- **Private by default.** Passwords, card numbers, CPFs and form inputs are masked. Request and response bodies are off unless you turn them on. Nothing leaves the browser unless you export an incident or configure a transport.
+- **Light on the page.** Recording runs into a ring buffer in IndexedDB with automatic retention, so old events are dropped instead of piling up.
+- **Framework-agnostic.** Pure TypeScript core, no React or other framework in your client bundle. ESM and CommonJS builds.
+- **Replay offline.** An interactive viewer with DOM playback, a synchronized timeline, and console and network panels. No account, no server.
+- **Readable production stack traces.** `backtrack symbolize` maps minified frames like `app.min.js:1:48213` back to your original TypeScript, with the surrounding source lines.
+- **Zero-friction local debugging & AI agents.** Automatic dev-server export saves structured Markdown reports (`.backtrack/latest.md`) and full replays straight to your project disk upon error—no manual downloads or copy-pasting required.
+- **Send it where you want.** `transport` and `beforeSend` let you forward incidents to your own backend or observability stack.
+
+---
+
+## Why Backtrack?
+
+| Feature | Error trackers | Hosted session replay | Backtrack |
+| :--- | :---: | :---: | :---: |
+| Shows the error and stack trace | ✅ | ✅ | ✅ |
+| Shows what the user did before it | ⚠️ limited breadcrumbs | ✅ | ✅ |
+| Data stays in the browser by default | ❌ | ❌ | ✅ |
+| Works fully offline | ❌ | ❌ | ✅ |
+| Only records around incidents | n/a | ❌ usually continuous upload | ✅ rolling buffer |
+
+Backtrack doesn't replace your error tracker. It gives you the context your error tracker is missing, and you can correlate the two with `traceId` and `release` (see [Release and trace correlation](#release-and-trace-correlation)).
+
+---
+
+## Installation
+
+```bash
+# npm
+npm install @backtrack-js/browser
+
+# yarn
+yarn add @backtrack-js/browser
+
+# pnpm
+pnpm add @backtrack-js/browser
+```
+
+---
+
+## Quick Start
+
+```typescript
+import { Backtrack } from '@backtrack-js/browser';
+
+const recorder = new Backtrack({
+  bufferMinutes: 5,       // keep the last 5 minutes in the rolling buffer
+  afterErrorSeconds: 15,  // keep recording 15s after an error
+});
+
+await recorder.start();
+
+// Optional: capture manually, e.g. from a "Report a problem" button
+const incidentId = await recorder.capture('User reported payment bug', 30);
+```
+
+Then inspect it:
+
+```bash
+npx backtrack
+```
+
+Drag an exported incident `.json` into the viewer and hit play.
+
+---
+
+## Readable production stack traces (`backtrack symbolize`)
+
+Production bundles are minified, so a stack frame like `app.3f9a1c.js:1:48213` tells you nothing. `backtrack symbolize` reads your source maps and rewrites the incident's errors with the original file, line, column and the surrounding source code.
+
+```bash
+npx backtrack symbolize <incident> --sourcemaps <directory> [options]
+```
+
+| Argument / option | Description |
+| :--- | :--- |
+| `<incident>` | Path to an exported incident: `.json`, `.ffr.json`, `.gz` or `.ffr.json.gz`. Gzip is detected automatically. |
+| `--sourcemaps <directory>` | Directory containing your `.js.map`, `.mjs.map` and `.cjs.map` files. Searched recursively (e.g. `./dist`, `./build`). |
+| `--output <file>` | Custom output path. Defaults to `<name>.symbolicated.ffr.json` next to the original. The output can never overwrite the input file. |
+| `--release <id>` | Build or release identifier. Validates against the incident's recorded release (if present), warning on mismatch. |
+| `--context-lines <number>` | Lines of original source shown before and after the failing line. Range 0–10, default 3. |
+| `-h, --help` | Show help. |
+
+### Example
+
+```bash
+npx backtrack symbolize ./incidents/checkout-bug.ffr.json --sourcemaps ./dist --context-lines 5
+```
+
+```text
+[Backtrack] Symbolication concluída.
+
+Incidente: inc_1727500000_3f2a
+Erros encontrados: 1
+Frames da exceção resolvidos: 4
+Frames da exceção não resolvidos: 0
+Frames React resolvidos: 2
+Frames React não resolvidos: 0
+Saída: /projects/app/incidents/checkout-bug.symbolicated.ffr.json
+```
+
+If some frames have no matching source map, the command reports a partial symbolication with warnings instead of failing.
+
+Open the `.symbolicated.ffr.json` file in the viewer (`npx backtrack`) and the error tab shows the resolved stack trace, with the failing line highlighted:
+
+```text
+applyCoupon  src/cart/coupon.ts:42:18
+
+40 function applyCoupon(cart, coupon) {
+41   // coupon discount might be missing from API
+42   const off = coupon.discount.percent;   <-- highlighted
+43   return cart.total * (1 - off / 100);
+44 }
+```
+
+### What it does (and doesn't do)
+
+- **Validates safely:** Reads the incident (up to 50 MB, gzip supported) and validates its schema with a strict validator. The original file is never modified.
+- **Multi-browser stack parsing:** Supports V8 (Chrome/Edge), Firefox, and Safari stack formats, stripping URL hashes/query strings and skipping native frames (`[native code]`).
+- **Resolves both exception location and React tree:** Simboliza tanto o ponto onde a exceção foi lançada (`resolvedStack`) quanto a árvore de componentes React (`resolvedComponentStack`), mantendo-os estritamente separados.
+- **Sourcemap validation:** Checks the sourcemap `file` attribute against the minified bundle to prevent cross-bundle misattribution.
+- **Extracts source context:** Extracts the original code from `sourcesContent`, so your source maps must include it.
+- **Doesn't leak local paths:** File paths are normalized (e.g. `C:\Users\alice\...` or `/home/bob/...` become paths starting at `src/`).
+- **Atomic write:** Writes the result atomically (to a `.tmp` file, then renames) and stores it in `resolvedStack` and `resolvedComponentStack`.
+
+### Limitations & Caveats
+
+- **Frames without line/column:** Stack frames missing line or column numbers cannot be mapped to source locations.
+- **Matching sourcemap release:** Source maps must correspond to the exact production build that generated the incident. Use `--release <id>` to ensure compatibility.
+- **Privacy notice:** O artefato poderá incluir replay visual, URLs, logs, respostas de rede, anotações e trechos do código-fonte incorporados durante a symbolication.
+
+---
+
+## Privacy & Data Masking
+
+Backtrack is designed with strict security defaults:
+
+- **Inputs & Forms:** All `<input>`, `<textarea>`, and `<select>` values are masked by default (`maskAllInputs: true`).
+- **Network Headers:** Authorization, Cookies, API keys, and Bearer tokens are automatically redacted.
+- **Sensitive Selectors:** Use standard selectors or CSS classes to protect proprietary or personal data:
+
+```typescript
+const recorder = new Backtrack({
+  privacy: {
+    maskAllInputs: true,
+    blockMedia: true,
+    blockSelector: '.backtrack-block, [data-private]',      // Completely hides elements in replay
+    maskTextSelector: '.backtrack-mask, .customer-pII',     // Scrambles text content
+    sanitizeUrl: (url) => {
+      // Remove sensitive query parameters
+      url.searchParams.delete('token');
+      return url.toString();
+    }
+  }
+});
+```
+
+---
+
+## Network & Payload Capture
+
+Network requests and responses can be configured using `network` options:
+
+```typescript
+const recorder = new Backtrack({
+  network: {
+    capturePayloads: false, // Bodies are disabled by default for privacy
+    maxPayloadSize: 64 * 1024
+  }
+});
+```
+
+- **Bodies are not captured by default (`capturePayloads: false`):** Request and response bodies are disabled by default to prevent unintentional data leakage. HTTP method, URL, status, timing, and sanitized headers continue to be captured.
+- **Enabling bodies increases the risk of PII:** Enabling `capturePayloads: true` should be done mindfully according to your compliance and privacy requirements.
+- **Sanitization remains active:** Even when payload capture is explicitly enabled, Backtrack continues to sanitize and redact known sensitive keys (passwords, tokens, credentials, etc.) and patterns (Bearer tokens, emails, CPFs, cards).
+- **`maxPayloadSize` is a limit per payload, not per incident:** It bounds each individual request or response body (default is `64 * 1024` bytes). Payloads exceeding this limit are truncated safely with a truncation marker.
+
+---
+
+## Capturing Incidents
+
+### Automatic Triggers
+Backtrack automatically triggers and freezes an incident when:
+1. An unhandled window exception occurs (`window.onerror`).
+2. An unhandled promise rejection occurs (`unhandledrejection`).
+3. An HTTP request returns a matching error status (`captureHttpStatus`).
+
+### Manual Capture
+You can trigger incident recording manually anywhere in your code (e.g. from an error boundary or user feedback modal):
+
+```typescript
+// Capture the last 60 seconds of context
+const incidentId = await recorder.capture('Checkout error', 60);
+
+// Export the complete incident artifact as a JSON object
+const artifact = await recorder.exportIncident(incidentId);
+
+// Download or send artifact to your support/logging service
+const jsonBlob = new Blob([JSON.stringify(artifact, null, 2)], { type: 'application/json' });
+```
+
+### Exception Capture
+
+#### React Error Boundary
+Em Error Boundaries (ex: `componentDidCatch` ou `react-error-boundary`), forneça `source: 'react'` e a árvore de componentes `componentStack`:
+
+```typescript
+// React Error Boundary (captura renderização/lifecycle com árvore de componentes)
+componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
+  recorder.captureException(error, {
+    source: 'react',
+    componentStack: errorInfo.componentStack
+  });
+}
+```
+
+#### Captura manual (try / catch)
+Para exceções capturadas imperativamente em handlers de eventos, chamadas assíncronas ou blocos `try/catch`, use `source: 'manual'`:
+
+```typescript
+// Captura imperativa sem árvore de componentes React
+try {
+  processCheckout();
+} catch (err) {
+  recorder.captureException(err, {
+    source: 'manual'
+  });
+}
+```
+
+> **Atenção:** Use `source: 'react'` apenas quando o erro foi capturado por um Error Boundary com a árvore de renderização. O visualizador e o simbolizador tratam `source: 'react'` e `componentStack` como a árvore de componentes da interface, e a stack JavaScript comum como o local exato do disparo da exceção.
+
+---
+
+## Remote Transport & beforeSend
+
+Backtrack allows applications to automatically dispatch finalized incidents to any remote endpoint or telemetry backend using `transport` and `beforeSend`:
+
+```typescript
+const recorder = new Backtrack({
+  transport: {
+    async send(artifact) {
+      const response = await fetch('/api/backtrack/incidents', {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json'
+        },
+        body: JSON.stringify(artifact)
+      });
+
+      if (!response.ok) {
+        throw new Error(`Upload failed: ${response.status}`);
+      }
+    }
+  },
+
+  beforeSend(artifact) {
+    if (artifact.environment.url.includes('/healthcheck')) {
+      return null;
+    }
+
+    return artifact;
+  }
+});
+```
+
+### Dispatch Flow & Semantics
+
+- **Sent Only When Finalized:** Incidents are dispatched only after they have been completely finalized and safely written to IndexedDB.
+  ```text
+  incident finalized
+          ↓
+    build artifact
+          ↓
+      beforeSend
+          ↓
+  null? cancel upload
+          ↓
+    transport.send
+  ```
+- **Role of `beforeSend`:**
+  - Affects **only** the automated transmission via `transport.send`.
+  - Does **not** mutate the artifact stored in local IndexedDB.
+  - Does **not** affect `getArtifact()` or explicit file downloads via `exportIncident()`.
+  - Returning `null` cancels the upload.
+  - If `beforeSend` throws an error, the upload is aborted cleanly without affecting the application or the recorded incident.
+- **Fault Isolation:** Network or transport errors will never break the host application, reject user captures, delete local incidents, prevent finalization, or trigger unhandled promise rejections.
+- **Concurrency & Delivery Guarantees:**
+  - Each finalized incident triggers at most one upload attempt.
+  - Multiple incidents can upload concurrently.
+  - `stop()` does not wait for pending network uploads.
+  - There is currently no delivery guarantee (persistent retry queue, offline backoff, etc.); if transport fails, the incident remains saved in local IndexedDB and can be accessed or resent by the application.
+
+---
+
+## Automatic Local Incident Export (`@backtrack-js/browser/dev-server`)
+
+During local development, Backtrack can save finalized incidents directly to disk in your project folder (JSON + Markdown report) without requiring manual downloads or clipboard copying.
+
+This is ideal for both human developers and **AI coding assistants** (Cursor, Copilot, Antigravity, Claude Code), enabling instant root-cause diagnosis directly from `.backtrack/latest.md`.
+
+```text
+.backtrack/
+  ├── latest.md             <- Structured markdown report (<= 32 KiB) for quick inspection
+  └── incidents/
+      ├── <id>.json         <- Full replay artifact with DOM, network & timeline
+      └── <id>.md           <- Timestamped markdown report
+```
+
+### 1. Dev Server Setup
+
+The middleware works with any Node-based development server (Vite, Webpack, CRA, Express, Fastify).
+
+#### Vite (`vite.config.ts`)
+```typescript
+import { defineConfig } from 'vite';
+import path from 'path';
+import { createBacktrackMiddleware } from '@backtrack-js/browser/dev-server';
+
+export default defineConfig({
+  plugins: [
+    {
+      name: 'backtrack-dev-server',
+      configureServer(server) {
+        server.middlewares.use(
+          createBacktrackMiddleware({
+            outputDir: path.resolve(__dirname, '.backtrack'),
+          })
+        );
+      },
+    },
+  ],
+});
+```
+
+#### Create React App / Webpack Dev Server (`src/setupProxy.js`)
+```javascript
+const path = require('path');
+const { createBacktrackMiddleware } = require('@backtrack-js/browser/dev-server');
+
+module.exports = function(app) {
+  if (process.env.NODE_ENV === 'development') {
+    app.use(
+      createBacktrackMiddleware({
+        outputDir: path.resolve(__dirname, '../.backtrack'),
+        allowedOrigins: ['http://localhost:3000', 'http://127.0.0.1:3000'],
+      })
+    );
+  }
+};
+```
+
+#### Express / Custom Node Dev Server
+```javascript
+const path = require('path');
+const { createBacktrackMiddleware } = require('@backtrack-js/browser/dev-server');
+
+app.use(
+  createBacktrackMiddleware({
+    outputDir: path.resolve(__dirname, '.backtrack'),
+    maxIncidents: 20, // keeps disk clean automatically
+  })
+);
+```
+
+### 2. Client Setup
+
+In your client application initialization, configure `transport` to POST to `/__backtrack/incident`:
+
+```typescript
+import { Backtrack } from '@backtrack-js/browser';
+
+const isDev = process.env.NODE_ENV === 'development';
+
+const recorder = await Backtrack.init({
+  ignoredUrls: ['/__backtrack/incident'],
+  transport: isDev
+    ? {
+        async send(artifact) {
+          await fetch('/__backtrack/incident', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(artifact),
+          });
+        },
+      }
+    : undefined,
+});
+```
+
+### Middleware Options
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `outputDir` / `directory` | `string` | *(required)* | Absolute path to the directory where incidents are stored. |
+| `allowedOrigins` | `string[]` | local origins | Allowed request origins. Defaults to loopback (`localhost`, `127.0.0.1`, `::1`). |
+| `maxBodyBytes` | `number` | `52428800` (50 MiB) | Maximum allowed JSON request body size. Aborts stream early if exceeded. |
+| `maxIncidents` | `number` | `20` | Maximum number of managed incidents retained on disk. |
+| `maxStorageBytes` | `number` | `209715200` (200 MiB) | Aggregate disk space limit for managed incidents. Oldest files are pruned first. |
+
+> **Security & Best Practices:**
+> - Add `.backtrack/` to your `.gitignore`.
+> - Never enable the local dev-server middleware in staging or production.
+> - The middleware validates requests against local peer sockets and host headers to prevent external access. Writes are atomic via `.tmp` files.
+
+## Release and trace correlation
+
+Backtrack artifacts (`formatVersion: 2`) provide an observability `context` to correlate client-side replays with backend traces, application releases, and environments.
+
+### Static Context
+
+Configure static metadata when initializing Backtrack:
+
+```typescript
+const recorder = new Backtrack({
+  context: {
+    release: 'checkout-web@2.14.0',
+    environment: 'production',
+    traceId: '4bf92f3577b34da6a3ce929d0e0e4736',
+    spanId: '00f067aa0ba902b7'
+  }
+});
+```
+
+### Dynamic Context (`getContext`)
+
+When trace IDs or active environments change dynamically during user navigation (e.g. from OpenTelemetry, Datadog, Sentry, or custom APM SDKs), use `getContext` to evaluate the latest context at incident export time:
+
+```typescript
+const recorder = new Backtrack({
+  context: {
+    release: 'checkout-web@2.14.0',
+    environment: 'production'
+  },
+  getContext: async () => {
+    const activeSpan = tracer.getActiveSpan();
+    const spanContext = activeSpan?.spanContext();
+
+    return {
+      release: 'checkout-web@2.14.0',
+      environment: 'production',
+      traceId: spanContext?.traceId,
+      spanId: spanContext?.spanId
+    };
+  }
+});
+```
+
+### Correlation Semantics
+
+- **Precedence:** `getContext() > context (static) > environment metadata`.
+- **Trace correlation scope:** Backtrack **only correlates** external trace and span identifiers supplied by your application. It does **not** generate backend traces, start trace spans, or perform distributed instrumentation on its own.
+- **Normalization:** `traceId` (32 hex characters) and `spanId` (16 hex characters) are validated and normalized to lowercase. A `spanId` cannot be supplied without an accompanying `traceId`.
+- **Fault Resilience:** If `getContext()` throws an error or rejects, incident export continues safely using available static context without failing the export or losing incident data.
+
+---
+
+## Inspecting Incidents (Viewer)
+
+Backtrack includes an offline visualizer with video replay, console logs, network inspection, and breadcrumbs.
+
+### Launch the Viewer CLI
+Run the embedded CLI to launch the local visualizer:
+
+```bash
+npx backtrack
+```
+
+This starts a local server at `http://localhost:5173/` and opens your default browser. Drag and drop any exported incident `.json` file to replay it!
+
+---
+
+## API Reference
+
+### `Backtrack`
+
+| Method | Return Type | Description |
+| --- | --- | --- |
+| `start()` | `Promise<void>` | Initializes storage and begins recording. |
+| `stop()` | `Promise<void>` | Stops recording, flushes pending batches to storage, and detaches listeners. |
+| `capture(reason?, windowSeconds?)` | `Promise<string>` | Manually captures and finalizes an incident. Returns incident ID. |
+| `captureException(error, context?)` | `Promise<string \| undefined> \| void` | Records a caught exception and triggers an incident. |
+| `listIncidents()` | `Promise<IncidentSummary[]>` | Lists all stored incidents. |
+| `getArtifact(incidentId)` | `Promise<FlightRecorderArtifact>` | Retrieves the full artifact for an incident (v1 or v2). |
+| `exportIncident(incidentId)` | `Promise<FlightRecorderArtifact>` | Exports the artifact and marks it finalized. |
+| `deleteIncident(incidentId)` | `Promise<void>` | Deletes an incident from local storage. |
+| `clear()` | `Promise<void>` | Clears all stored chunks, sessions, and incidents. |
+| `getHealth()` | `RecorderHealth` | Returns current buffer status, storage usage, and state. |
+
+---
+
+## License
+
+[Backtrack Free-Use License](LICENSE) — Free for personal and commercial integration. Redistribution, copying, or creating derivative/competing works is strictly prohibited.