> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reticle.sh/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Reticle is a dev-only, localhost-only verification layer for AI coding agents. It reads program truth (network, state, console, routing, animations, framework state) from inside a running web app and returns a deterministic verdict with evidence. It is not a screenshot tool and not a browser automation library.
> Only `reticle_act_and_wait` and `reticle_assert` produce a verdict. Every other tool moves or reads the app and proves nothing. A drive that ends without one of those two has no result, however many tools it used.
> A verdict of `verified: "unknown"` is not a pass. It means Reticle drove the app and could not tell what happened. Report it as unknown; never weaken a check to make it pass.
> Package names are scoped `@reticlehq/*` and the CLI is `reticle`. Install with `npx reticle init`. The complete tool surface is on the `/usage` page; `/agent-cheatsheet` is the one-screen version.

# @reticlehq/react

> The React kit for Reticle, mapping a DOM node to its component stack, its hook state, and its source file.

`@reticlehq/react` is the package most React users install, and usually the only SDK package they need. It re-exports the whole browser SDK and adds the fiber-tree work on top.

**Version 2.8.0. Apache 2.0. Depends on `@reticlehq/browser` and `@reticlehq/core`. Peer dependency: `react >= 18`.**

## Why it exists

This is the package that turns "the button is broken" into `src/components/Login.tsx:81`. Finding a bug is half the job; Reticle's answer to the other half lives here.

```bash theme={"dark"}
npm i -D @reticlehq/react
```

## It re-exports the browser SDK

`export * from '@reticlehq/browser'` is in the barrel, so one install gives you `reticle`, `registerCapabilities`, every store adapter, and everything else on the [browser page](/packages/browser). You do not add `@reticlehq/browser` separately.

```ts theme={"dark"}
import { reticle, install } from '@reticlehq/react';
install();
reticle.connect();
```

## Exports

### Setup

| Export    | Signature  | What it does                                                                                              |
| --------- | ---------- | --------------------------------------------------------------------------------------------------------- |
| `install` | `(): void` | Idempotent. Registers the `react` adapter and installs the render meter. Call it once, before `connect()` |

The [Vite plugin](/packages/vite-plugin) injects exactly these two lines for you, so a Vite user never writes them.

### Mapping a node to its component

| Export             | Signature                                |
| ------------------ | ---------------------------------------- |
| `identify`         | `(el: Element) => ComponentInfo \| null` |
| `readState`        | `(el: Element) => ComponentStateResult`  |
| `hasHoverHandlers` | `(el: Element) => boolean`               |
| `relativeToRoot`   | `(file: string) => string`               |

`identify` walks the fiber tree to build the component stack and source location. `readState` reads hook state, bounded. `relativeToRoot` turns an absolute source path into a repository-relative one using the root the plugin stamped.

### Render measurement

`installRenderMeter`, `resetRenderMeter`, `getRenderStats`, and the `RenderStats` type. This is what makes a render loop visible as a number rather than a hunch.

### Hydration

`HYDRATION_COMPLETE_SIGNAL`, `createHydrationTracker`, type `HydrationTracker`.

### Error boundaries

`buildErrorBoundaryData`, `reticleOnCaughtError`, type `ErrorBoundaryData`. Wire `reticleOnCaughtError` into React's `onCaughtError` and a boundary that swallows an error stops being invisible.

### Hydration mismatches

`buildHydrationErrorData`, `isHydrationMismatch`, `reticleOnRecoverableError`, type `HydrationErrorData`.

### Commits and CDP

`createCommitAggregator`, type `CommitAggregator`. `readComponentAt`, `buildReaderExpression`, `parseComponentRead`, type `CdpComponentRead`.

## The `./store` subpath

One export, and the only module in the package that imports React:

```ts theme={"dark"}
import { useReticleStore } from '@reticlehq/react/store';

function Cart() {
  const [items, setItems] = useState([]);
  useReticleStore('cart', items); // now readable via reticle_state
}
```

`useReticleStore(name: string, value: unknown): void`.

## Source mapping needs a build step

React 19 dropped `_debugSource`, so `identify` can name the component but not the file unless something stamps the source at build time. That is [`@reticlehq/babel-plugin`](/packages/babel-plugin), pulled in for you by [`@reticlehq/vite-plugin`](/packages/vite-plugin) or [`@reticlehq/next`](/packages/next).

<Card title="Reading component state" icon="layer-group" href="/state-management">
  What `reticle_state` can see, and how to widen it.
</Card>