@reticlehq/server 2.7.0 → 2.9.0

package/docs/packages/babel-plugin.mdx

@@ -0,0 +1,79 @@
+---
+title: '@reticlehq/babel-plugin'
+description: A Babel plugin that stamps data-reticle-source on JSX host elements so Reticle can name the file a node came from.
+icon: file-code
+---
+
+`@reticlehq/babel-plugin` stamps `data-reticle-source="file:line:col"` onto your JSX at build time, in dev only, so Reticle can name the file a DOM node came from. **You probably do not install this one directly**: [`@reticlehq/vite-plugin`](/packages/vite-plugin) and [`@reticlehq/next`](/packages/next) both pull it in. Reach for it only if you drive Babel yourself.
+
+React 19 dropped `_debugSource`, which is what source mapping used to rely on, so without this the tools can tell you the component name but not the file.
+
+**Apache 2.0. CommonJS. No runtime dependencies. Peer dependency: `@babel/core ^7`.**
+
+## What it stamps
+
+```jsx
+// src/components/Login.jsx
+export function Login({ submit }) {
+  return <button onClick={submit}>Sign in</button>;
+}
+```
+
+becomes, in dev only:
+
+```jsx
+export function Login({ submit }) {
+  return (
+    <button onClick={submit} data-reticle-source="src/components/Login.jsx:2:9">
+      Sign in
+    </button>
+  );
+}
+```
+
+The path is relative to `process.cwd()`, with backslashes normalized to forward slashes. A file with no name stamps `unknown`.
+
+## What it skips
+
+- Component tags. Only lowercase host elements are stamped, because a component's own JSX gets stamped where it is defined.
+- Elements that already carry the attribute.
+- Nodes with no location information.
+- Anything whose tag name is not a plain `JSXIdentifier`.
+
+## Do you install it?
+
+Only if you are wiring Babel yourself. [`@reticlehq/vite-plugin`](/packages/vite-plugin) and [`@reticlehq/next`](/packages/next) both pull it in.
+
+```bash
+npm i -D @reticlehq/babel-plugin
+```
+
+## The export
+
+One export, via `export =`. There are no named exports and no `default` interop wrapper, because Babel `require()`s the module and takes the object directly.
+
+```ts
+function reticleSourcePlugin({ types }: { types: typeof BabelTypes }): PluginObj<PluginPass>;
+```
+
+The Babel plugin name is `reticle-source`. Its visitor handles `JSXOpeningElement` only.
+
+**It takes no options.** The plugin reads nothing from `state.opts`.
+
+## Wiring it by hand
+
+```js
+// babel.config.cjs
+module.exports = {
+  plugins: process.env.NODE_ENV === 'development' ? [require('@reticlehq/babel-plugin')] : [],
+};
+```
+
+<Warning>
+  Do not write `require('@reticlehq/babel-plugin').default`. With `export =` there is no `.default`,
+  and an old README example got this wrong.
+</Warning>
+
+## Why an attribute rather than a runtime lookup
+
+The stamp survives minification of everything else, costs nothing at runtime, and is readable from the DOM node itself. That is what lets [`reticle_inspect`](/tools-inspect) answer with a file and a line rather than a component name and a shrug.

package/docs/packages/browser.mdx

@@ -0,0 +1,111 @@
+---
+title: '@reticlehq/browser'
+description: The Reticle instrumentation SDK that runs inside your page, observing the DOM, network, console, routing and state.
+icon: window
+---
+
+`@reticlehq/browser` is the Reticle SDK that runs inside your page. It installs the observers, builds semantic snapshots, executes actions, and talks to the bridge. Install it directly only if you are **not** on React or want to call `connect()` yourself, because [`@reticlehq/react`](/packages/react) already re-exports all of it.
+
+**Apache 2.0. Depends on `@reticlehq/core` and `@testing-library/dom`.**
+
+## Why it exists
+
+This is what makes Reticle different from a browser-automation tool. Because it runs _inside_ the app rather than driving it from outside, it can see a state mutation and a fired signal, not just a rendered pixel. It never imports a Node API; that boundary is enforced by the dependency graph.
+
+`@testing-library/dom` is why [`reticle_query`](/tools-query) speaks role, label and testid instead of CSS selectors.
+
+## When you need it directly
+
+Install it yourself when you are not on React, or when you want `connect()` under your own control. React users install [`@reticlehq/react`](/packages/react) instead, which re-exports everything here.
+
+```bash
+npm i -D @reticlehq/browser
+```
+
+```ts
+import { reticle } from '@reticlehq/browser';
+if (import.meta.env.DEV) reticle.connect();
+```
+
+## The `reticle` singleton
+
+One instance, memoized on `globalThis` so hot module replacement does not create a second one.
+
+| Method         | Signature                                                |
+| -------------- | -------------------------------------------------------- |
+| `connect`      | `(options?: ReticleConnectOptions) => void`              |
+| `connected`    | `get connected(): boolean`                               |
+| `signal`       | `(name: string, data?: Record<string, unknown>) => void` |
+| `state`        | `(name: string, value: unknown) => void`                 |
+| `renderCommit` | `(commits: number) => void`                              |
+| `describe`     | `(input: CapabilitiesInput) => void`                     |
+| `endSession`   | `() => void`                                             |
+| `disconnect`   | `() => void`                                             |
+
+Everything else on the class is private. `Reticle` itself is exported for typing.
+
+## `ReticleConnectOptions`
+
+Every field is optional.
+
+| Option | Type | What it controls |
+| --- | --- | --- |
+| `url` | `string` | Bridge URL, when you are not on the default port |
+| `session` | `string` | Session id. Defaults to the auto id (`SESSION_AUTO` is re-exported here) |
+| `projectId` | `string` | Project identity stamped on the handshake |
+| `token` | `string` | Pairing token, required for a non-loopback page |
+| `allowNonLocalhost` | `boolean` | Opt in to connecting from a non-localhost origin |
+| `allowInProduction` | `boolean` | Opt in to connecting from a production build. Desktop apps need this |
+| `overlay` | `boolean` | The in-page overlay |
+| `captureNetworkBodies` | `boolean` | Record request and response bodies |
+| `root` | `string` | Repository root, so source paths come back relative |
+| `sdkVersion` | `string` | Reported on the handshake for skew detection |
+| `present` | `boolean` | Presenter mode |
+| `pace` | `number` | Presenter pacing |
+| `narrationDwellMs` | `number` | Presenter narration dwell |
+| `border` | `'session' \| 'busy'` | Which border the overlay draws |
+| `logMax` | `number` | Console buffer cap |
+| `recorder` | `boolean` | Enable flow recording |
+| `annotate` | `boolean` | Enable the human annotation layer |
+| `endedFadeMs` | `number` | Fade after a session ends |
+| `idleEndMs` | `number` | Idle timeout before the session ends itself |
+| `redact` | `RedactionConfig` | Redaction policy, from core |
+
+## Capabilities
+
+Declaring a capability surface is what lets an agent discover what your app can do without guessing.
+
+```ts
+import { registerCapabilities } from '@reticlehq/browser';
+
+registerCapabilities({
+  testids: ['login-submit'],
+  signals: ['auth:granted'],
+  stores: ['session'],
+  flows: [{ name: 'login', steps: ['fill email', 'fill password', 'submit'] }],
+});
+```
+
+Also exported: `getCapabilities()`, `hasCapabilities()`, `setCapabilitiesListener(cb?)`, and the `Capabilities`, `CapabilitiesInput` and `CapabilityFlow` types.
+
+## State adapters
+
+Register a store and its contents become readable through [`reticle_state`](/tools-state).
+
+`registerStore`, `unregisterStore`, `storeNames`, `readStores`, `readStoresWithTruncation`.
+
+Ready-made adapters ship for TanStack Query, Jotai, XState, Valtio, MobX, Recoil, Svelte, Pinia, and a plain push store: `tanstackQueryStore`, `jotaiStore`, `xstateStore`, `valtioStore`, `mobxStore`, `recoilStore`, `svelteStore`, `piniaStore`, `pushStore`.
+
+## Framework adapters
+
+`registerAdapter`, `identifyComponent`, `readComponentState`, `elementHasHoverHandlers`, `adapterNames`, with the `ReticleAdapter`, `ComponentInfo` and `ComponentSource` types. [`@reticlehq/react`](/packages/react) registers the React one.
+
+## Lower-level building blocks
+
+Exported because the server and the test runner use them, and because an integration may need them: `buildSnapshot`, `matchQuery`, `runQuery`, `executeAction`, `executeSequence`, `describe`, `getRole`, `getAccessibleName`, `getStates`, `isVisible`, `refs`, `RefRegistry`, `setIgnoreSelectors`, `Annotator`, `installAnnotator`, `resolveMarkAnchor`, `inspectChart`, `canvasChartData`.
+
+Signal helpers: `createReticleEmitter`, `commitAndSignal`, `registerReticleDomain`.
+
+<Card title="Instrumenting an app properly" icon="plug" href="/instrumentation">
+  Signals, stores, and what makes evidence strong rather than circumstantial.
+</Card>

package/docs/packages/core.mdx

@@ -0,0 +1,116 @@
+---
+title: '@reticlehq/core'
+description: 'The shared wire contract for Reticle: constants, zod schemas, and the isomorphic kernel every other package imports.'
+icon: cube
+---
+
+`@reticlehq/core` is the shared wire contract at the bottom of Reticle's dependency graph. Every message that crosses a boundary, browser to bridge, bridge to agent, is defined here as a named constant plus a zod schema. **You almost certainly do not need to install it**: it arrives with whatever Reticle package you did install, and you only reach for it directly if you are building your own integration against the wire format.
+
+**Apache 2.0. Depends on `zod` and nothing else.**
+
+## Why it exists
+
+Without one shared definition the browser and the server drift. One side renames a field, the other keeps reading the old one, and the failure is silent: a verdict that quietly stops carrying its evidence. Core makes that a type error instead.
+
+The single dependency is the point. Everything can depend on core without cycles, and nothing core does can drag a filesystem call into the browser bundle.
+
+## Do you install it?
+
+No. It arrives as a dependency of `@reticlehq/browser`, `@reticlehq/react`, `@reticlehq/server`, `@reticlehq/vite-plugin` or `@reticlehq/electron`. Install it directly only if you are building your own integration against the wire format.
+
+```bash
+npm i @reticlehq/core
+```
+
+## Exports map
+
+| Subpath | What it is |
+| --- | --- |
+| `.` | The ESM barrel. Types at `dist/index.d.ts` |
+| `./desktop-contract` | A CommonJS shim, generated at build, for the strings the desktop adapters share |
+| `./schema/*.json` | Generated JSON Schema for the wire types |
+| `./package.json` | The manifest |
+
+<Warning>
+  There is no `@reticlehq/core/vite` subpath. It was documented in an old README and never existed
+  in the exports map. The Vite plugin is [`@reticlehq/vite-plugin`](/packages/vite-plugin).
+</Warning>
+
+## What the barrel exports
+
+`src/index.ts` is a pure barrel: a stack of `export *` re-exports plus one named export. Grouped by what they are for, and not exhaustive:
+
+### Wire constants
+
+`RETICLE_DEFAULT_PORT` (`4400`), `RETICLE_WS_PATH` (`/reticle`), `MCP_SSE_PATH`, `MCP_MESSAGE_PATH`, `STATUS_PATH`, `RETICLE_PROTOCOL_VERSION` (`1`), `RETICLE_URL_PARAM`, `LOOPBACK_HOST` (`127.0.0.1`), `TRANSPORT_LIMITS`, `REDACTED_VALUE`, `RING_BUFFER_DEFAULTS`, `DEFAULT_ASSERT_TIMEOUT_MS` (`4000`), `VISUAL_PIXEL_THRESHOLD` (`0.1`), `SCROLL_FIND_DEFAULTS`, `CRAWL_DEFAULTS`.
+
+### Environment and directories
+
+`ReticleEnv` names every environment variable Reticle reads: `RETICLE_TOKEN`, `RETICLE_HOST`, `RETICLE_ALLOWED_ORIGINS`, `RETICLE_PORT`, `RETICLE_STATE_DIR`, `RETICLE_CDP_URL`, `RETICLE_MAX_CONTEXTS`, `RETICLE_MAX_MESSAGES_PER_SECOND` and the rest. `ReticleDir` names the paths under `.reticle/`.
+
+### Enum-like frozen objects
+
+`EventType`, `ActionType`, `ElementState`, `QueryBy`, `MessageKind`, `ReticleCommand`, `PhenomenonType`, `SettleReason`, `ComponentStateReason`, `InputMode`, `InputModeReason`, `ActionWarning`, `DriveErrorCode`, `TruncationChannel`, `EventAttribution`, `PerfMetric`, `PresenterMode`, `SnapshotMode`, `VisualReason`, `CONSOLE_LEVELS`, `Verified`.
+
+`ComponentStateResult` is an interface, not one of these: it is a type-only export, so importing it as a value fails with `'ComponentStateResult' only refers to a type, but is being used as a value here`.
+
+### Zod schemas
+
+`ReticleMessageSchema` (a discriminated union on `kind`) and its members `HelloMessageSchema`, `CommandMessageSchema`, `CommandResultSchema`, `EventMessageSchema`, plus `ReticleEventSchema`. Flows are `FlowStepSchema`, `FlowExpectSchema`, `FlowAnchorSchema`, `FlowFileSchema`, `RecordedFlowSchema`. CI runs are `ReticleVerificationRunSchema`, `RunVerdictSchema`, `RunFlowResultSchema`, `RunCheckSchema`, `RunRiskSchema`, `RepairPacketSchema`, `VerificationEvidenceSchema`. Telemetry is `TelemetryEventSchema`, `SessionSummarySchema`, `ProjectProfileSchema`, `FeedbackSchema`, `IdentitySchema`.
+
+### Kernel functions
+
+Pure, isomorphic, and safe on both sides of the wire:
+
+| Function | What it does |
+| --- | --- |
+| `fingerprintOf` / `CONTRACT_FINGERPRINT` | The contract hash the daemon and the SDK compare on handshake |
+| `bridgeWsUrl` | Build the bridge WebSocket URL |
+| `parseEventPayload`, `isHighValueEvent` | Narrow and rank inbound events |
+| `isConsequenceKind`, `isPresenceKind`, `flowExpectHasConsequence`, `flowExpectIsPresenceOnly` | The consequence versus presence distinction the gate's anti-downgrade check runs on |
+| `selectPath`, `capDepth`, `projectComponentState` | Bounded state projection |
+| `isLoopbackHostname`, `isLocalPage`, `isOpaqueOrigin`, `isDangerousActionText` | The security predicates |
+| `defaultIsSensitiveKey`, `buildRedactionPolicy`, `setActiveRedactionPolicy`, `isSensitiveKey`, `scrubKnownSecrets` | Redaction |
+| `toToon`, `resultToToon`, `isToonable` | The compact result encoding |
+| `projectIdFrom`, `slugifyPackageName` | Project identity |
+| `pickDaemonPort`, `daemonRegistryFileName`, `daemonRegistryPort` | Daemon discovery |
+| `isSessionScoped`, `isSessionState` | Session scoping |
+| `buildUpgradeHint`, `isCloudCapability` | Upgrade hints |
+
+## The desktop contract
+
+```ts
+import { RETICLE_IPC_GLOBAL, RETICLE_CAPTURE_CHANNEL } from '@reticlehq/core/desktop-contract';
+```
+
+Six strings shared by the Electron preload and the Tauri crate, in CommonJS because a preload script is required before any ESM transform:
+
+| Constant                        | Value                                                      |
+| ------------------------------- | ---------------------------------------------------------- |
+| `RETICLE_IPC_GLOBAL`            | `__reticleIpc`                                             |
+| `RETICLE_CAPTURE_CHANNEL`       | `__reticle:capture`                                        |
+| `RETICLE_CAPTURE_FILE_PREFIX`   | `reticle-capture-`                                         |
+| `RETICLE_TAURI_CAPTURE_COMMAND` | `reticle_capture`                                          |
+| `RETICLE_FULL_PAGE_UNSUPPORTED` | `full-page-unsupported`, for a refused full-page capture   |
+| `RETICLE_NOT_COMPOSITED`        | `window-not-composited`, for a window that had not painted |
+
+<Warning>
+  The subpath exports those six constants individually and nothing else. The `DESKTOP_CONTRACT`
+  record they are collected into exists on the ESM side only, so importing it here fails with
+  `Module '"@reticlehq/core/desktop-contract"' has no exported member 'DESKTOP_CONTRACT'`. Import
+  `DESKTOP_CONTRACT` from `@reticlehq/core` instead.
+</Warning>
+
+## The JSON schemas
+
+Seven files, generated at build from the zod definitions:
+
+`reticle-message.json`, `reticle-event.json`, `hello-message.json`, `command-message.json`, `command-result.json`, `event-message.json`, `event-type.json`.
+
+```ts
+import schema from '@reticlehq/core/schema/reticle-message.json' with { type: 'json' };
+```
+
+<Card title="How the pieces fit" icon="sitemap" href="/architecture">
+  Where the contract sits between the SDK, the bridge, and the agent.
+</Card>

package/docs/packages/electron.mdx

@@ -0,0 +1,85 @@
+---
+title: '@reticlehq/electron'
+description: The Reticle adapter for Electron, making main-process IPC observable and the window screenshottable.
+icon: display
+---
+
+`@reticlehq/electron` reaches the two places the renderer-side SDK cannot: the IPC boundary, and `capturePage()`. Install it if your app is Electron and you want main-process IPC observable or the window screenshottable. A web app never needs it.
+
+**Apache 2.0. Depends on `@reticlehq/core`. Peer dependency: `electron >= 22`. No build step.**
+
+## Why it exists
+
+In Electron the interesting failures happen across IPC. The renderer asks the main process for something, the main process quietly fails, and the renderer-side SDK sees nothing at all. That reads as "this app makes no backend calls" rather than "you are blind to them".
+
+```bash
+npm i -D @reticlehq/electron
+```
+
+## Exports map
+
+There is no `.` export. Two subpaths only.
+
+| Subpath     | File          | Shape                             |
+| ----------- | ------------- | --------------------------------- |
+| `./preload` | `preload.cjs` | Side effect only. Exports nothing |
+| `./main`    | `main.cjs`    | `{ installReticleCapture }`       |
+
+## The preload
+
+```js
+// preload.js: this line must be FIRST
+require('@reticlehq/electron/preload');
+
+const { contextBridge, ipcRenderer } = require('electron');
+// ... your own bridge setup
+```
+
+<Warning>
+  It must run before `require('electron')` and before any `contextBridge.exposeInMainWorld` call. It
+  patches `ipcRenderer` while those methods are still writable, so ordering is not a style
+  preference.
+</Warning>
+
+It patches three methods, and each IPC call then surfaces to Reticle as a network record on `ipc://<channel>` with `initiator: 'ipc'`:
+
+| Method                 | Recorded as                          |
+| ---------------------- | ------------------------------------ |
+| `ipcRenderer.invoke`   | Two-way, with its outcome            |
+| `ipcRenderer.sendSync` | Two-way, with its outcome            |
+| `ipcRenderer.send`     | One-way, dispatched, with no outcome |
+
+It then exposes `window.__reticleIpc` through the context bridge, with three members used by the SDK rather than by you:
+
+| Member | Signature | Notes |
+| --- | --- | --- |
+| `subscribe` | `(callback) => number` | Returns a token, or `-1` if the argument is not a function |
+| `unsubscribe` | `(token) => void` | Real removal |
+| `capture` | `(fullPage) => Promise<string \| null>` | Resolves to a capture file path, `null` when no main handler is installed, and propagates the explicit full-page refusal |
+
+## The main process
+
+```js
+const { installReticleCapture } = require('@reticlehq/electron/main');
+
+const win = new BrowserWindow({/* ... */});
+installReticleCapture(win);
+```
+
+`installReticleCapture(win): void` is a no-op on `null` or `undefined`, tracks the window until it closes, and registers the capture handler once for the whole app.
+
+The handler calls `webContents.capturePage()`, writes the PNG into a per-process `0700` captures directory as `reticle-capture-<n>.png`, and **returns the file path rather than the bytes**, because the transport has a 64KB cap. It refuses `fullPage: true` explicitly rather than silently returning a viewport shot, and it throws named reasons rather than one blanket silence: `full-page-unsupported` for that refusal, `window-not-composited` when the window had nothing painted yet, `no usable webContents to capture` when the window is gone. The preload re-throws the full-page refusal and turns everything else into `null`.
+
+## Renderer wiring
+
+The renderer still needs the SDK. A packaged app is a production build, so the connect call has to opt in:
+
+```ts
+reticle.connect({ allowInProduction: true });
+```
+
+Or, with the Vite plugin, `reticle({ desktop: true })`.
+
+<Card title="Desktop setup in full" icon="display" href="/desktop">
+  Electron and Tauri wiring, and what `reticle doctor` checks for each.
+</Card>

package/docs/packages/eslint-plugin.mdx

@@ -0,0 +1,86 @@
+---
+title: '@reticlehq/eslint-plugin'
+description: Two lint rules that keep Reticle's signal layer and its comment hygiene self-enforcing.
+icon: shield-check
+---
+
+`@reticlehq/eslint-plugin` is two ESLint rules that keep Reticle's signal layer self-enforcing. It is entirely optional: nothing in Reticle needs it, and you want it only once your app emits signals and you would like the compiler to notice when a new mutation forgets one.
+
+It exists because conventions rot. Someone adds a mutation, forgets the signal, and every verdict for that flow quietly drops a grade. Nothing breaks, the tests still pass, the evidence just gets weaker. A lint rule is the only way a convention survives contact with a deadline.
+
+**Apache 2.0. Depends on `@typescript-eslint/utils`. Peer dependency: `eslint >= 9`.**
+
+```bash
+npm i -D @reticlehq/eslint-plugin
+```
+
+## Exports
+
+| Export                    | What it is                                                         |
+| ------------------------- | ------------------------------------------------------------------ |
+| `default`                 | The plugin object: `{ meta: { name: 'reticle' }, rules, configs }` |
+| `rules`                   | `{ 'require-signal-on-mutation': ..., 'no-internal-tags': ... }`   |
+| `requireSignalOnMutation` | The rule, exported individually                                    |
+| `noInternalTags`          | The rule, exported individually                                    |
+
+## The rules
+
+### `reticle/require-signal-on-mutation`
+
+Warns when a store mutation happens without a mapped Reticle signal.
+
+**Message id:** `mutationWithoutSignal`. **Text:** `store mutation without a mapped Reticle signal`.
+
+**Options** (`options[0]`, no additional properties):
+
+| Option | Type | Default |
+| --- | --- | --- |
+| `mutators` | `string[]` | `[]`. With the default the rule is a no-op, which is deliberate: name your own mutators. Matched by BARE NAME, so `set` also matches `map.set()` and `headers.set()`; prefer an unambiguous name |
+| `signalCallee` | `string \| string[]` | `['reticleSignal', 'signal']` |
+
+```js
+'reticle/require-signal-on-mutation': ['warn', {
+  mutators: ['setState', 'commit', 'dispatch'],
+  signalCallee: ['reticleSignal'],
+}]
+```
+
+The check is scoped per function: a mutation and its signal must live in the same function body.
+
+### `reticle/no-internal-tags`
+
+Errors on internal design-doc reference codes and internal version strings appearing in comments, file names, directory names or test descriptions. **Message id:** `internalTag`, with a `{ tag }` placeholder. No options.
+
+This one is mostly for contributors to Reticle itself, but the `recommended` config turns it on for everyone.
+
+## The recommended config
+
+One config, `recommended`:
+
+```js
+import reticle from '@reticlehq/eslint-plugin';
+
+export default [reticle.configs.recommended];
+```
+
+Which is exactly:
+
+```js
+{
+  plugins: { reticle: plugin },
+  rules: {
+    'reticle/require-signal-on-mutation': 'warn',
+    'reticle/no-internal-tags': 'error',
+  },
+}
+```
+
+<Warning>
+  `recommended` enables **both** rules, and `no-internal-tags` at `error`. An older README
+  documented only the first rule, so the second can arrive as a surprise. Enable the rules
+  individually if you want just the signal check.
+</Warning>
+
+<Card title="Why signals are the strongest evidence" icon="tower-broadcast" href="/instrumentation">
+  What a signal proves that a rendered pixel cannot.
+</Card>

package/docs/packages/next.mdx

@@ -0,0 +1,89 @@
+---
+title: '@reticlehq/next'
+description: Next.js source mapping for Reticle without giving up SWC, via a dev-only loader.
+icon: n
+---
+
+`@reticlehq/next` gives a Next.js app the same `data-reticle-source` stamping the Vite plugin does, without asking it to migrate off SWC to Babel. Install it if your app is Next.js; on Vite use [`@reticlehq/vite-plugin`](/packages/vite-plugin) instead. Unlike the Vite plugin it does **not** inject `connect()`, so you still call that yourself.
+
+**Apache 2.0. CommonJS, no build step. Depends on `@babel/core` and `@reticlehq/babel-plugin`. Peer dependency: `next >= 13`.**
+
+## Why it exists
+
+Next users are on SWC. Telling them to switch to Babel for a dev tool would be a rude trade, and it would slow down every build they run. This adds a dev-only pre-loader for `.jsx` and `.tsx` and leaves the rest of the pipeline alone.
+
+## Install and use
+
+```bash
+npm i -D @reticlehq/next @reticlehq/react
+```
+
+```js
+// next.config.js
+const { withReticle } = require('@reticlehq/next');
+
+module.exports = withReticle({/* your config */});
+```
+
+<Note>
+  This package is CommonJS on purpose. `next.config.js` is loaded by Node before any ESM transform,
+  so an ESM-only helper would fail at the least helpful possible moment.
+</Note>
+
+## Exports
+
+### `.`
+
+```ts
+function withReticle<T = unknown>(nextConfig?: T): T;
+```
+
+Returns the config unchanged when `NODE_ENV === 'production'`. Otherwise it merges in:
+
+| Addition | What it does |
+| --- | --- |
+| `webpack` | Pushes an `enforce: 'pre'` rule for `/\.(t\|j)sx$/`, excluding `node_modules`, using this package's loader. Your own `webpack` function still runs afterwards |
+| `turbopack` | On Next 15.3 and above only: rules for `*.tsx` and `*.jsx` pointing at `@reticlehq/next/loader` |
+| `env.NEXT_PUBLIC_RETICLE_TOKEN` | The pairing token, when one exists on disk |
+| `env.NEXT_PUBLIC_RETICLE_ROOT` | `process.cwd()`, so source paths come back repository-relative |
+| `env.NEXT_PUBLIC_RETICLE_SDK_VERSION` | The version of the app's installed `@reticlehq/react` |
+
+`readPairingToken()` is also exported at runtime. It is not declared in `index.d.ts`, so TypeScript will not see it.
+
+### `./loader`
+
+```ts
+declare function reticleNextLoader(this: unknown, source: string, inputMap?: unknown): void;
+export = reticleNextLoader;
+```
+
+An async webpack loader. It skips anything that is not `.jsx` or `.tsx`, and anything under `node_modules`. It lazily imports `@reticlehq/babel-plugin` and runs `babel.transformAsync` with `configFile: false`, `babelrc: false`, `retainLines`, and source maps on.
+
+<Note>
+  The loader never fails the build. Any error falls back to the original source, because a dev-only
+  source stamp is not worth breaking someone's `next dev` over.
+</Note>
+
+## What it does not do
+
+It does not inject `connect()`. On Next you call it yourself, once, in a client component:
+
+```tsx
+'use client';
+import { useEffect } from 'react';
+import { reticle, install } from '@reticlehq/react';
+
+export function ReticleDev() {
+  useEffect(() => {
+    if (process.env.NODE_ENV !== 'production') {
+      install();
+      reticle.connect();
+    }
+  }, []);
+  return null;
+}
+```
+
+<Card title="Framework by framework" icon="layer-group" href="/frameworks">
+  What each supported stack needs, and what it gets for free.
+</Card>

package/docs/packages/react.mdx

@@ -0,0 +1,91 @@
+---
+title: '@reticlehq/react'
+description: The React kit for Reticle, mapping a DOM node to its component stack, its hook state, and its source file.
+icon: react
+---
+
+`@reticlehq/react` is the Reticle kit for React apps, and usually the only SDK package a React user needs: it re-exports the whole browser SDK and adds fiber-tree work that maps a DOM node to its component stack, its hook state, and its source file. If your app is React, install this one and not `@reticlehq/browser`.
+
+**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
+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
+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 `install()` and `reticle.connect()` for you, so a Vite user never writes either line.
+
+### 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
+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>