@reticlehq/server 2.7.0 → 2.8.0

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 half of Reticle that lives in your app. It installs the observers, builds semantic snapshots, executes actions, and talks to the bridge.
+
+**Version 2.8.0. 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,106 @@
+---
+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 bottom of the 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.
+
+**Version 2.8.0. 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 five 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: 26 `export *` re-exports plus one named export. Grouped by what they are for:
+
+### 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`, `ComponentStateResult`, `InputMode`, `InputModeReason`, `ActionWarning`, `DriveErrorCode`, `TruncationChannel`, `EventAttribution`, `PerfMetric`, `PresenterMode`, `SnapshotMode`, `VisualReason`, `CONSOLE_LEVELS`, `Verified`.
+
+### 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 { DESKTOP_CONTRACT, RETICLE_IPC_GLOBAL } from '@reticlehq/core/desktop-contract';
+```
+
+Five 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` | The `VisualReason` value for a refused full-page capture |
+
+## 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,87 @@
+---
+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 cannot: the IPC boundary, and `capturePage()`.
+
+**Version 2.8.0. 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 returns `null` on an empty image or any error, and it refuses `fullPage: true` explicitly rather than silently returning a viewport shot.
+
+## 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-apps">
+  Electron and Tauri wiring, and what `reticle doctor` checks for each.
+</Card>

package/docs/packages/eslint-plugin.mdx

@@ -0,0 +1,84 @@
+---
+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` 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.
+
+**Version 2.8.0. 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 |
+| `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,91 @@
+---
+title: '@reticlehq/next'
+description: Next.js source mapping for Reticle without giving up SWC, via a dev-only loader.
+icon: n
+---
+
+`@reticlehq/next` gives Next.js users the same `data-reticle-source` stamping the Vite plugin does, without asking them to migrate to Babel.
+
+**Version 2.8.0. 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 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
+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 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
+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>

package/docs/packages/server.mdx

@@ -0,0 +1,98 @@
+---
+title: '@reticlehq/server'
+description: The Reticle bridge, MCP server, and the reticle CLI, all in one Node package.
+icon: server
+---
+
+`@reticlehq/server` hosts the WebSocket your app dials into, exposes the MCP tools your agent calls, and ships the `reticle` binary.
+
+**Version 2.8.0. Licensed under `SEE LICENSE IN LICENSE`, not Apache 2.0 like the rest.** This is the package the enterprise terms apply to.
+
+## Why it exists
+
+Agents speak MCP. Browsers speak WebSocket. Somebody has to be fluent in both, and own the `.reticle/` directory where flows, baselines, capsules and runs are stored. It never imports a DOM API.
+
+## Do you install it?
+
+Not into your project. Your agent launches it:
+
+```bash
+npx @reticlehq/server mcp
+```
+
+The `bin` entry is `reticle`, so `npx @reticlehq/server <command>` works once it is on disk.
+
+## Dependencies
+
+**Runtime:** `@modelcontextprotocol/sdk`, `@reticlehq/core`, `ws`, `zod`.
+
+**Optional:** `playwright`, `pixelmatch`, `pngjs`. Optional on purpose: Reticle observes the browser you already have. You only need Playwright for the paths that launch or diff one, which is `reticle drive`, `reticle verify`, and visual baselines.
+
+## Exports map
+
+| Subpath | What it is                                                                             |
+| ------- | -------------------------------------------------------------------------------------- |
+| `.`     | The programmatic API                                                                   |
+| `./cli` | The CLI entry, which also exports `parseCliArgs`, `CLI_USAGE` and the `CliResult` type |
+
+## Starting a server in process
+
+```ts
+import { start, startDaemon, type StartOptions, type RunningServer } from '@reticlehq/server';
+
+const server: RunningServer = await start({ port: 4400, headless: true });
+await server.close();
+```
+
+`start(options?: StartOptions): Promise<RunningServer>` boots the bridge plus the MCP stdio transport. `startDaemon(options?: StartOptions): Promise<RunningServer>` is what the detached daemon runs.
+
+### `StartOptions`
+
+| Option | Type | Default |
+| --- | --- | --- |
+| `port` | `number` | `RETICLE_PORT`, else `4400` |
+| `host` | `string` | `RETICLE_HOST`, else loopback. A non-loopback host requires a token |
+| `token` | `string` | `RETICLE_TOKEN` |
+| `allowedOrigins` | `string[]` | `RETICLE_ALLOWED_ORIGINS` |
+| `mcp` | `boolean` | `true`. `false` skips the stdio transport |
+| `cdpUrl` | `string` | `RETICLE_CDP_URL`. Attach to a running browser instead of launching one |
+| `driveUrl` | `string` | unset |
+| `headless` | `boolean` | `true` |
+| `realInputFactory` | `(opts) => OwnedRealInputProvider` | built in |
+| `injectConnect` | `InjectConnectOptions` | unset |
+| `storageState` | `string` | unset |
+| `reticleRoot` | `string` | `cwd()/.reticle` |
+| `pairingTokenDir` | `string` | `~/.reticle` |
+| `now` | `() => number` | `Date.now` |
+| `toolProfile` | `string` | `RETICLE_TOOL_PROFILE`, else `full`. `core` serves the lean surface |
+| `httpVerify` | `boolean` | `false` |
+| `httpVerifyPort` | `number` | `RETICLE_VERIFY_DEFAULT_PORT` (`7331`) |
+| `httpVerifyToken` | `string` | `RETICLE_VERIFY_TOKEN` |
+
+### `RunningServer`
+
+`bridge: Bridge`, `close(): Promise<void>`, and the optional `realInput`, `verifyPort`, `isIdle()`, `agentAttached()`, `token`.
+
+## What else the barrel exports
+
+A large surface, because the test runner and the CI paths are built on it. The families:
+
+| Family | Representative exports |
+| --- | --- |
+| Tools | `TOOLS`, `ReticleTool`, `runTool`, `createToolInvoker`, `filterTools`, `resolveToolSurface`, `CORE_TOOL_NAMES`, `SESSION_BOUND_TOOLS`, `SESSION_EXEMPT_TOOLS` |
+| Bridge and sessions | `Bridge`, `Session`, `SessionManager`, `RingBuffer`, `resolveBridgeSecurity`, `buildSessionRecommendation` |
+| Stores on disk | `FlowStore`, `BaselineStore`, `VisualStore`, `RecordingStore`, `RunStore`, `ProjectStore`, `AnnotationStore`, `createNodeFileSystem`, `reticleDirPaths`, `readContract`, `writeContract` |
+| Flow replay | `replayFlow`, `assertSuccess`, `successToPredicate`, `classifyFlowAssertions`, `FlowAssertionGrade`, `nearestTestid` |
+| Runs and CI | `ReticleRunner`, `buildVerificationRun`, `computeVerdict`, `renderRunReport`, `buildRepairPacket`, `classifyChangedFiles`, `buildRisks`, `redactForProfile` |
+| HTTP verify | `handleVerifyRequest`, `createVerifyRequestListener`, `startVerifyServer`, `VERIFY_PATH`, `TOKEN_HEADER`, `tokenOk` |
+| Predicates | `evaluatePredicate`, `waitForPredicate`, `PredicateSchema`, `buildReactionReport` |
+| Browser pool | `BrowserPool`, `playwrightLauncher`, `resolveMaxContexts`, `DEFAULT_LEASE_TTL_MS` |
+| Real input | `CdpRealInputProvider`, `LaunchedRealInputProvider`, `performGesture`, `boxCenter`, `isPointerAction`, `DriveError` |
+| Daemon lifecycle | `writePid`, `readPid`, `removePid`, `isRunning`, `isAlive`, `logPath`, `classifyDaemonLife`, `DAEMON_HEARTBEAT_MS` |
+| Crawl and scroll | `crawl`, `scrollToFind` |
+| Visual | `diffPng` |
+| Domain model | `buildDomainModel` |
+
+<Card title="Every CLI command" icon="terminal" href="/cli">
+  The commands this package installs, one page each.
+</Card>