# React

The `@domscribe/react` package provides React fiber walking, props/state extraction, and bundler plugins for Vite and Webpack.

## Install

```bash
npm install -D @domscribe/react
```

## Vite Setup

```ts
// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { domscribe } from '@domscribe/react/vite';

export default defineConfig({
  plugins: [react(), domscribe()],
});
```

## Webpack Setup

Webpack requires both a loader (for AST transformation) and a plugin (for relay and overlay coordination):

```js
// webpack.config.js
const { DomscribeWebpackPlugin } = require('@domscribe/react/webpack');

const isDevelopment = process.env.NODE_ENV !== 'production';

module.exports = {
  module: {
    rules: [\
      {\
        test: /\.[jt]sx?$/,
        exclude: /node_modules/,\
        enforce: 'pre',\
        use: [\
          {\
            loader: '@domscribe/transform/webpack-loader',\
            options: { enabled: isDevelopment },\
          },\
        ],\
      },\
    ],
  },
  plugins: [\
    new DomscribeWebpackPlugin({\
      enabled: isDevelopment,\
      overlay: true,\
    }),\
  ],
};
```

## Supported Versions

- **React 18** and **React 19**
- **Vite 5 - 7**
- **Webpack 5**

## Plugin Options

The React plugin extends the base transform options with `runtime` and `capture` namespaces:

```ts
domscribe({
  // Base transform options
  include: /\.(jsx|tsx)$/, 
  exclude: /node_modules/, 
  debug: false, 
  relay: { autoStart: true, port: 0, host: '127.0.0.1' },
  overlay: true,

// React-specific
  runtime: { /* ... */ },
  capture: { /* ... */ },
})
```

### Runtime Options

| Option           | Type                | Default | Description                                                       |
|------------------|---------------------|---------|-------------------------------------------------------------------|
| `phase`         | `1 | 2`            | `1`     | Feature phase gate. Phase 1: props/state. Phase 2: events/perf.  |
| `redactPII`    | `boolean`          | `true`  | Redact sensitive values in captured data.                          |
| `blockSelectors`| `string[]`         | `[]`    | CSS selectors to exclude from capture.                             |

### Capture Options

| Option                  | Type                                       | Default | Description                                                        |
|-------------------------|--------------------------------------------|---------|--------------------------------------------------------------------|
| `strategy`              | `'devtools' | 'fiber' | 'best-effort'`          | `'best-effort'` | Capture strategy (see below).                                      |
| `maxTreeDepth`         | `number`                                   | `50`    | Maximum component tree depth to traverse.                          |
| `includeWrappers`      | `boolean`                                  | `true`  | Include HOC/memo/forwardRef wrapper components.                   |
| `hookNameResolvers`    | `Record<string, Record<number, string>>` | `undefined` | Map component names to hook index to semantic name mappings.      |

## Capture Strategies

The React adapter supports three strategies for accessing component data:

- **`devtools`** \- uses the React DevTools global hook (`window.__REACT_DEVTOOLS_GLOBAL_HOOK__`). Most reliable, but requires React DevTools to be installed.
- **`fiber`** \- accesses the React Fiber tree directly via internal `__reactFiber$` properties on DOM elements. Fast, but relies on React internal APIs.
- **`best-effort`** (default) -- tries multiple strategies in order of reliability and uses whichever succeeds.

## Hook Name Resolvers

By default, React hook state appears as indexed values (hook 0, hook 1, etc.). You can provide semantic names for better readability:

```ts
domscribe({
  capture: {
    hookNameResolvers: {
      Counter: { 0: 'count', 1: 'setCount' },
      TodoList: { 0: 'items', 1: 'filter' },
    },
  },
})
```

## Subpath Exports

- `@domscribe/react/vite` \- Vite plugin with React adapter
- `@domscribe/react/webpack` \- Webpack plugin with React adapter
- `@domscribe/react/auto-init` \- Auto-initialization module