@backtrack-js/browser 0.4.0 → 0.4.2

package/README.md

@@ -1,291 +1,364 @@
-# Backtrack (@backtrack-js/browser)
-
-[![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-MIT-blue.svg)](LICENSE)
-
-**Backtrack** is a privacy-first, client-side session recorder and time-travel engine for web applications. It captures pre-bug context (DOM mutations, console logs, network requests, navigation, and unhandled errors) in a rolling local ring-buffer, allowing developers to backtrack user sessions and reproduce bugs with exact fidelity.
-
-- 🔒 **Privacy-First:** Strict data masking (passwords, credit cards, inputs, authorization headers). No data leaves the browser unless explicitly exported.
-- ⚡ **Lightweight & Framework-Agnostic:** Pure TypeScript core. Zero framework dependencies (no React required in your client bundle).
-- 🔄 **Rolling Ring Buffer:** Continuously stores the last $N$ minutes of user activity in IndexedDB with automatic retention and storage limits.
-- 🎬 **Full Session Replay:** Powered by [rrweb](https://github.com/rrweb-io/rrweb) with synchronized timeline events.
-- 🛠 **Built-in Incident Viewer:** Includes an interactive web inspector and CLI to replay incidents offline.
-
----
-
-## 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';
-
-// 1. Initialize Backtrack
-const recorder = new Backtrack({
-  bufferMinutes: 5,         // Keep last 5 minutes of activity in rolling buffer
-  afterErrorSeconds: 15,    // Keep recording for 15 seconds after an error occurs
-  maxStorageMb: 50,         // Retention target for rolling buffer (protected incidents are never auto-pruned)
-  captureHttpStatus: [500, 502, 503, 504], // Auto-trigger on server errors
-  network: {
-    capturePayloads: false, // Bodies are disabled by default for privacy
-    maxPayloadSize: 64 * 1024
-  },
-  privacy: {
-    maskAllInputs: true,    // Mask all form inputs by default
-    blockMedia: true        // Replace images/media with placeholders
-  }
-});
-
-// 2. Start recording
-await recorder.start();
-
-// 3. (Optional) Manually trigger an incident on user feedback or caught error
-const incidentId = await recorder.capture('User reported payment bug', 30);
-console.log('Incident captured:', incidentId);
-```
-
----
-
-## 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,
-    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
-  incidente finalizado
-          ↓
-    montar artefato
-          ↓
-      beforeSend
-          ↓
-  null? cancela envio
-          ↓
-    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` (`FlightRecorder`)
-
-| 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
-
-[MIT](LICENSE)
+# 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.