@reticlehq/server 2.7.0 → 2.9.0

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` is the Reticle bridge, MCP server and CLI in one Node package. It hosts the WebSocket your app dials into, exposes the MCP tools your agent calls, and ships the `reticle` binary. **You do not add it to your project**: your agent runs it with `npx @reticlehq/server mcp`.
+
+**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>

package/docs/packages/tauri.mdx

@@ -0,0 +1,63 @@
+---
+title: 'reticle-tauri'
+description: The Rust crate that gives a Tauri app Reticle screenshots and headless mode.
+icon: rust
+---
+
+`reticle-tauri` is a Rust crate on crates.io, not an npm package. You need it only if your Tauri app should answer `reticle_screenshot`, or run headless in CI. Everything else about a Tauri app, including IPC observation, works without it.
+
+It is versioned **independently** of the ten npm packages. **MIT licensed, unlike the Apache 2.0 npm packages. Edition 2021.**
+
+## Why it exists, and why it is small
+
+Tauri IPC observation needs nothing on the Rust side. An `invoke('load_todos')` already reaches Reticle as `ipc://load_todos` through the SDK in the webview. You only need this crate for two things: screenshots, and headless mode.
+
+<Warning>
+  Do not expect this to match the npm version. Doing so would imply a release cadence the crate does
+  not have, and it would make every npm release a crates.io release for no reason.
+</Warning>
+
+## Install
+
+```toml
+[dependencies]
+reticle-tauri = "0.1"
+```
+
+Its own dependencies are `tauri = "2"` plus the per-platform capture backends: `objc2` and friends on macOS, `webview2-com` and `windows` on Windows, `webkit2gtk` and `cairo-rs` on Linux and the BSDs.
+
+## Wiring
+
+```rust
+tauri::Builder::default()
+    .invoke_handler(tauri::generate_handler![reticle_tauri::reticle_capture])
+    .on_page_load(reticle_tauri::on_page_load)
+```
+
+Nothing is needed on the JavaScript side. Tauri has no preload stage, so the SDK reaches `reticle_capture` through Tauri's own internals.
+
+## The public API
+
+| Item | Signature |
+| --- | --- |
+| `reticle_capture` | `#[tauri::command] pub async fn reticle_capture(window: tauri::WebviewWindow, full_page: Option<bool>) -> Result<String, String>` |
+| `on_page_load` | `pub fn on_page_load<R: Runtime>(webview: &Webview<R>, payload: &tauri::webview::PageLoadPayload<'_>)` |
+| `FULL_PAGE_UNSUPPORTED` | `pub const FULL_PAGE_UNSUPPORTED: &str = "full-page-unsupported"` |
+
+There are no public traits and no macros.
+
+### `reticle_capture`
+
+Runs on a blocking thread, writes a PNG into a per-process `0700` directory under the OS temp dir as `reticle-capture-<nanos>.png`, and returns the **path**, not the bytes. Full-page capture is supported on Linux only; elsewhere it returns `FULL_PAGE_UNSUPPORTED`, which is pinned to core's `VisualReason` value so the refusal is the same string everywhere.
+
+### `on_page_load`
+
+Hides the window on `PageLoadEvent::Finished` when the environment variable `RETICLE_HEADLESS=1` is set. That ordering matters: the window exists and renders, then it is hidden, so the capture path still works.
+
+## The silent failure to know about
+
+A Tauri app with the default CSP runs perfectly and never connects to Reticle, with nothing said anywhere. [`reticle doctor`](/cli/doctor) diagnoses this explicitly on a desktop project, because it is invisible otherwise.
+
+<Card title="Desktop setup in full" icon="display" href="/desktop">
+  The CSP entry, the headless flag, and how capture differs from a browser screenshot.
+</Card>

package/docs/packages/test.mdx

@@ -0,0 +1,119 @@
+---
+title: '@reticlehq/test'
+description: The Reticle spec runner for CI, driving the tools directly with no MCP or stdio in the loop.
+icon: vial
+---
+
+`@reticlehq/test` is Reticle's spec runner for CI. It turns an interactive session into a suite that runs on every pull request, without an agent and without paying model tokens to re-derive the same checks. Install it when you want unattended verification; skip it if you only ever drive Reticle interactively through MCP.
+
+**Licensed under `SEE LICENSE IN LICENSE`. Depends on `@reticlehq/core` and `@reticlehq/server`. Optional peer dependency: `vitest ^3.2.6`.**
+
+```bash
+npm i -D @reticlehq/test
+```
+
+## Why it exists
+
+Driving interactively is reconnaissance. At some point you want the same checks to run unattended. This package invokes the tool layer directly, so a spec is the same evidence an agent would have gathered, minus the model.
+
+## Booting a session
+
+```ts
+import { bootSession, createTestContext, runSpecs, printSummary } from '@reticlehq/test';
+
+const run = await bootSession({ driveUrl: 'http://localhost:5173' });
+const { results, summary } = await runSpecs({
+  invoke: run.invoke,
+  buildContext: (invoke) => createTestContext(invoke),
+  now: () => Date.now(),
+});
+printSummary(summary, results, (line) => process.stdout.write(`${line}\n`));
+await run.close();
+```
+
+### `BootOptions`
+
+| Option        | Type                                  | Default                 |
+| ------------- | ------------------------------------- | ----------------------- |
+| `driveUrl`    | `string`                              | required                |
+| `headless`    | `boolean`                             | `true`                  |
+| `port`        | `number`                              | the default bridge port |
+| `reticleRoot` | `string`                              | `cwd()/.reticle`        |
+| `now`         | `() => number`                        | `Date.now`              |
+| `buildDeps`   | `(server: RunningServer) => ToolDeps` | built in                |
+
+`bootSession` resolves to `BootedRun`: `{ invoke: ToolInvoker; close: () => Promise<void> }`.
+
+## Writing specs
+
+```ts
+import { reticleTest, type TestContext } from '@reticlehq/test';
+
+reticleTest('login grants a session', async (spec) => {
+  const t = spec as TestContext;
+  await t.fill('email', 'user@example.com');
+  await t.fill('password', 'hunter2');
+  await t.actAndWait('login-submit', 'click', { kind: 'signal', name: 'auth:granted' });
+  await t.expectNet('POST', '/api/session', 200);
+  await t.expectNoConsoleErrors();
+});
+```
+
+`reticleTest(name: string, fn: SpecFn): void` registers into a module-level registry. `register`, `getRegistered` and `clearRegistry` are exported for anyone driving it themselves.
+
+<Note>
+  `SpecFn` types its argument as `SpecContext`, which declares only `invoke`. The runner actually
+  hands the spec whatever `buildContext` returned, which is a `TestContext`. In plain JavaScript
+  this is invisible; in TypeScript you get `Property 'fill' does not exist on type 'SpecContext'`
+  unless you narrow it as above.
+</Note>
+
+## The test context
+
+`createTestContext(invoke: ToolInvoker, options?: TestContextOptions): TestContext`, where `TestContextOptions` is `{ sessionId?: string; defaultTimeoutMs?: number }` and the timeout defaults to `DEFAULT_ASSERT_TIMEOUT_MS`.
+
+| Method | Signature |
+| --- | --- |
+| `act` | `(testid: string, action: ActionType, args?: Record<string, unknown>) => Promise<void>` |
+| `fill` | `(testid: string, value: string) => Promise<void>` |
+| `actAndWait` | `(testid: string, action: ActionType, until: Predicate) => Promise<void>` |
+| `expectSignal` | `(name: string, dataMatches?: Record<string, unknown>) => Promise<void>` |
+| `expectNet` | `(method: string, urlContains: string, status?: number) => Promise<void>` |
+| `expectElement` | `(query: ElementQuery, state?: ElementState) => Promise<void>` |
+| `expectText` | `(contains: string) => Promise<void>` |
+| `expectAbsent` | `(query: ElementQuery) => Promise<void>` |
+| `expectNoConsoleErrors` | `() => Promise<void>` |
+| `state` | `(storeOrRef: string) => Promise<unknown>` |
+| `expectInputModeReal` | `() => Promise<void>` |
+| `invoke` | The raw `ToolInvoker` |
+| `clock` | `TestClock` |
+
+## Running and reporting
+
+| Export | Signature |
+| --- | --- |
+| `runOne` | `(spec: ReticleSpec, opts: RunnerOptions) => Promise<SpecResult>` |
+| `runSpecs` | `(opts: RunnerOptions) => Promise<{ results: SpecResult[]; summary: RunSummary }>` |
+| `summarize` | `(results: readonly SpecResult[]) => RunSummary` |
+| `printSummary` | `(summary: RunSummary, results: readonly SpecResult[], print: (line: string) => void) => void`. The sink is injected, never `console` |
+| `toJUnitXml` / `writeJUnit` | JUnit output for CI |
+
+`RunnerOptions` is `{ invoke; buildContext; now; print?; specs? }`. `RunSummary` is `{ total, passed, failed, skipped, ok }`.
+
+## Saved flows as specs
+
+A recorded flow becomes a spec without being rewritten:
+
+`flowToSpec`, `flowsAsSpecs`, `registerFlowSpecs`, with `assertSuccess`, `successToPredicate`, and the `FlowSpec`, `FlowSpecOptions` and `FlowsAsSpecsOptions` types. Malformed flows raise `FlowMalformedError`.
+
+## Errors and control flow
+
+`ReticleSkip` and `isSkip` for skipping, `ReticleAssertionError` with an `AssertionDetail`, `ReticleQueryEmptyError` when a query matched nothing.
+
+Constants: `TestStatus`, `SpecKind`, `SpecOutcome`, `SpecMessage`, `PredicateKind`, `STATUS_GLYPH`, `SUMMARY_FOOTER_PREFIX`, `JUnit`, `DEFAULT_JUNIT_SUITE_NAME`, `SKIP_REASON_REAL_INPUT`, `PROBE_TESTID`, `FLOW_LOAD_ERROR_PREFIX`, `DEFAULT_ASSERT_TIMEOUT_MS`.
+
+Also exported: `resolveTestid`, and the standalone `expectInputModeReal`, `InputModeTracker` and `readInputMode`.
+
+<Card title="Turning a session into a suite" icon="flask" href="/testing">
+  Writing specs that bind to signals rather than DOM structure.
+</Card>

package/docs/packages/vite-plugin.mdx

@@ -0,0 +1,94 @@
+---
+title: '@reticlehq/vite-plugin'
+description: One line in vite.config.ts that stamps source locations on your JSX and auto-injects reticle.connect().
+icon: bolt
+---
+
+`@reticlehq/vite-plugin` is one line in `vite.config.ts` that does the two things everyone forgets: injecting `reticle.connect()` and enabling source mapping. Install it if your app builds with Vite. On Next.js use [`@reticlehq/next`](/packages/next) instead; on any other bundler, wire [`@reticlehq/browser`](/packages/browser) by hand.
+
+**Apache 2.0. Depends on `@babel/core`, `@reticlehq/babel-plugin` and `@reticlehq/core`. Optional peer dependency: `vite >= 4`.**
+
+## Install and use
+
+```bash
+npm i -D @reticlehq/vite-plugin @reticlehq/react
+```
+
+```ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { reticle } from '@reticlehq/vite-plugin';
+
+export default defineConfig({
+  plugins: [reticle(), react()],
+});
+```
+
+<Warning>
+  The import specifier is `@reticlehq/vite-plugin` and the export is `reticle`. An old README
+  documented `@reticlehq/core/vite`; that subpath has never existed in core's exports map, and `npx
+  @reticlehq/core init` is not a command either. The binary is `reticle`, from
+  [`@reticlehq/server`](/packages/server).
+</Warning>
+
+## Why it exists
+
+`apply: 'serve'` means it never reaches a production build. That is the guarantee that lets you leave it in the config permanently: there is no way to ship Reticle to your users by forgetting to remove a line.
+
+## What it injects
+
+A virtual module at `/@reticle-connect`, added to the HTML, whose contents are:
+
+```ts
+import { reticle, install } from '@reticlehq/react';
+install();
+reticle.connect({/* resolved args */});
+```
+
+Plus a dynamic import of your dev module if one exists. It looks for `src/reticle-dev.ts`, `.js`, `.tsx` or `.jsx`, in that order, and leaves the file alone if you have one: that file is yours to edit.
+
+## Options
+
+`reticle(options?: ReticleVitePluginOptions): ReticleVitePlugin`. Every option is optional.
+
+| Option | Type | Default |
+| --- | --- | --- |
+| `port` | `number` | Discovered from the daemon registry for this project, falling back to `4400` |
+| `root` | `string` | Vite's `root`, else `process.cwd()` |
+| `sdkVersion` | `string` | Read from the installed `@reticlehq/react` |
+| `session` | `string` | Omitted, so the SDK generates one |
+| `projectId` | `string` | Derived from the package name plus the root path |
+| `token` | `string` | `readPairingToken()`, from `~/.reticle/pairing-token` |
+| `sourceMapping` | `boolean` | `true`. Set `false` to skip the Babel pass |
+| `inject` | `boolean` | `true`. Set `false` to call `connect()` yourself |
+| `desktop` | `boolean` | `false`. When `true` the plugin also applies to `vite build` and passes `allowInProduction: true`, which is what an Electron or Tauri renderer needs |
+| `captureNetworkBodies` | `boolean` | `false`. Also enabled by `VITE_RETICLE_CAPTURE_BODIES=1` |
+| `onWarn` | `(message: string) => void` | `console.warn` |
+
+## Other exports
+
+| Export | Type | What it is |
+| --- | --- | --- |
+| `RETICLE_VITE_PLUGIN_NAME` | `'reticle'` | The plugin name |
+| `RETICLE_TOKEN_GLOBAL` | `'__RETICLE_TOKEN__'` | The global the token is stamped onto |
+| `RETICLE_CONNECT_MODULE` | `'/@reticle-connect'` | The virtual module id |
+| `RENDER_PREHOOK_SOURCE` | `string` | The inline render prehook snippet |
+| `RETICLE_DEV_MODULE_CANDIDATES` | readonly tuple | The four dev-module paths it looks for |
+| `readPairingToken` | `() => string \| undefined` | Read the pairing token from disk |
+| `findDevModule` | `(root: string, exists: (p: string) => boolean) => string \| null` | Locate the dev module |
+| `connectModuleSource` | `(options: ReticleVitePluginOptions, devModule?: string \| null) => string` | Build the injected module source |
+| `cjsDepIncludes` | `(appRoot: string, canResolve?: (dep: string) => boolean) => string[]` | CommonJS deps to add to `optimizeDeps` |
+
+Types: `ReticleVitePluginOptions`, `ReticleVitePlugin`, `ViteDevServerLike`.
+
+## Desktop
+
+```ts
+reticle({ desktop: true });
+```
+
+A packaged Electron or Tauri renderer is a production build loaded from a custom protocol, so the default guards would refuse. This one flag drops `apply: 'serve'` and opts the connect call into production.
+
+<Card title="Desktop wiring in full" icon="display" href="/desktop">
+  Including the Tauri CSP whose failure is completely silent.
+</Card>

package/docs/packages.mdx

@@ -0,0 +1,218 @@
+---
+title: 'Packages: what is in the box'
+sidebarTitle: Packages
+description: Every Reticle package. What it does, why it exists, when you actually need it, and what it depends on.
+icon: cubes
+---
+
+Reticle is eleven packages, and most people install two. This page exists so you can tell which two, and so that the ones you skip stop looking mysterious.
+
+<Note>
+  The ten npm packages ship together at one version: whatever `npm view @reticlehq/core version`
+  says, every other `@reticlehq/*` package says too. The Rust crate `reticle-tauri` is versioned
+  **independently**. That is deliberate, not drift.
+</Note>
+
+## Which ones do I need?
+
+<CardGroup cols={2}>
+  <Card title="A React app on Vite" icon="bolt">
+    `@reticlehq/react` + `@reticlehq/vite-plugin`. That's it, two dev dependencies.
+  </Card>
+  <Card title="A React app on Next.js" icon="n">
+    `@reticlehq/react` + `@reticlehq/next`. Keeps SWC; no Babel migration.
+  </Card>
+  <Card title="Not React, or no bundler plugin" icon="code">
+    `@reticlehq/browser` alone, and call `connect()` yourself.
+  </Card>
+  <Card title="Electron or Tauri" icon="display">
+    The web packages, plus `@reticlehq/electron` or the `reticle-tauri` crate.
+  </Card>
+</CardGroup>
+
+You never install `@reticlehq/server`. Your agent runs it with `npx`.
+
+## The architecture in one rule
+
+The package split is not cosmetic. Each boundary enforces something:
+
+| Package   | Runs in     | Hard rule                                              |
+| --------- | ----------- | ------------------------------------------------------ |
+| `core`    | both        | Depends only on `zod`. Sits at the bottom of the graph |
+| `browser` | the browser | Never imports a Node API                               |
+| `server`  | Node        | Never imports a DOM API                                |
+| `react`   | the browser | Optional. Core must work without it                    |
+
+Those rules are why the browser SDK cannot accidentally pull in a filesystem call, and why the server cannot accidentally depend on `window`. They are enforced by the dependency graph, not by discipline.
+
+---
+
+## @reticlehq/core
+
+**The wire contract.** Every constant and zod schema that crosses a boundary. Browser to bridge, bridge to agent, is defined here.
+
+**Why it exists:** without one shared definition, the browser and the server drift. One renames a field, the other keeps reading the old one, and the failure is silent. A verdict that quietly stops carrying evidence. Core makes that a type error instead.
+
+**Depends on:** `zod`, and nothing else. That is the whole point; it sits at the bottom of the graph so everything can depend on it without cycles.
+
+**Do you install it?** No. It arrives as a dependency of whatever you did install.
+
+<Note>
+  Before 2.0, `@reticlehq/core` was an umbrella package re-exporting everything under subpaths. That
+  was retired: the umbrella meant every consumer pulled the whole world to get one constant.
+</Note>
+
+---
+
+## @reticlehq/browser
+
+**The SDK that lives in your page.** It installs the observers (DOM, network, console, routing, animations), builds semantic snapshots, executes actions, and talks to the bridge.
+
+**Why it exists:** this is the part that 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.
+
+**Depends on:** `@reticlehq/core`, `@testing-library/dom`. The latter is why [`reticle_query`](/tools-query) speaks role, label and testid rather than CSS selectors.
+
+**Install it directly when** you are not on React, or you want `connect()` under your own control:
+
+```ts
+import { reticle } from '@reticlehq/browser';
+if (import.meta.env.DEV) reticle.connect();
+```
+
+---
+
+## @reticlehq/server
+
+**The bridge, the MCP server, and the `reticle` CLI.** Hosts the WebSocket your app dials into and exposes the tools your agent calls.
+
+**Why it exists:** agents speak MCP; browsers speak WebSocket; somebody has to be fluent in both and own the `.reticle/` directory where flows, baselines and runs are stored.
+
+**Depends on:** `@modelcontextprotocol/sdk`, `@reticlehq/core`, `ws`, `zod`.
+
+**Do you install it?** Not into your project. Your agent launches it:
+
+```bash
+npx @reticlehq/server mcp
+```
+
+---
+
+## @reticlehq/react
+
+**The kit most React users install.** It re-exports the browser sensor, so one install gives you `reticle`, `registerCapabilities` and everything else, and it maps a DOM node to its React component and source file through the fiber tree.
+
+**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.
+
+**Depends on:** `@reticlehq/browser`, `@reticlehq/core`. **Peer:** `react`.
+
+```bash
+npm i -D @reticlehq/react
+```
+
+---
+
+## @reticlehq/vite-plugin
+
+**One line in `vite.config.ts`, two jobs.** It stamps source locations onto your JSX and injects `connect()` so you cannot forget to.
+
+**Why it exists:** the two things everyone forgets are wiring the SDK and enabling source mapping. This does both, and `apply: 'serve'` guarantees it never reaches a production build.
+
+**Depends on:** `@babel/core`, `@reticlehq/babel-plugin`, `@reticlehq/core`. **Peer:** `vite`.
+
+```ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { reticle } from '@reticlehq/vite-plugin';
+
+export default defineConfig({ plugins: [reticle(), react()] });
+```
+
+---
+
+## @reticlehq/babel-plugin
+
+**Stamps `data-reticle-source="file:line:col"` onto JSX host elements.**
+
+**Why it exists:** React 19 dropped `_debugSource`, which is what source mapping used to rely on. This plugin puts the information back, at build time, in dev only. Without it, `reticle_inspect` can still tell you the component name but not the file.
+
+**Depends on:** nothing. **Peer:** `@babel/core`.
+
+**Do you install it?** Only directly if you are wiring Babel yourself. The Vite and Next packages both pull it in.
+
+---
+
+## @reticlehq/next
+
+**Next.js source mapping without giving up SWC.**
+
+**Why it exists:** Next users are on SWC, and telling them to switch to Babel for a dev tool would be a rude trade. This adds a dev-only webpack pre-loader that stamps the same attribute, and leaves your build pipeline alone.
+
+**Depends on:** `@babel/core`, `@reticlehq/babel-plugin`. **Peer:** `next`.
+
+```js
+const { withReticle } = require('@reticlehq/next');
+module.exports = withReticle({/* your config */});
+```
+
+<Note>
+  This one 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 moment.
+</Note>
+
+---
+
+## @reticlehq/test
+
+**The spec runner for CI.** `reticleTest` registers declarative specs and runs them against Reticle's tools directly, with no MCP or stdio in the loop.
+
+**Why it exists:** driving interactively is reconnaissance. At some point you want the same checks to run on every pull request without an agent. And without paying model tokens to re-derive them.
+
+**Depends on:** `@reticlehq/core`, `@reticlehq/server`. **Peer:** `vitest`.
+
+<Card title="Turn a session into a suite" icon="vial" href="/testing">
+  Writing specs that bind to signals rather than DOM structure.
+</Card>
+
+---
+
+## @reticlehq/eslint-plugin
+
+**Two rules, the main one being: state changed, so a signal must fire.**
+
+**Why it exists:** signals are the strongest evidence Reticle can use, and they rot the way all 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 makes the signal layer self-enforcing, which is the only way a convention survives contact with a deadline.
+
+**Depends on:** `@typescript-eslint/utils`. **Peer:** `eslint`.
+
+---
+
+## @reticlehq/electron
+
+**Reaches the two places the renderer cannot.**
+
+**Why it exists:** in Electron, the interesting failures often happen across the IPC boundary. The renderer asks the main process for something and the main process quietly fails. The renderer-side SDK cannot see that. This package makes main-process IPC observable and the window screenshottable.
+
+**Depends on:** `@reticlehq/core`. **Peer:** `electron`.
+
+---
+
+## reticle-tauri
+
+**The Rust crate**, on crates.io. Versioned independently of the npm packages.
+
+**Why it exists:** Tauri IPC observation needs nothing on the Rust side; an `invoke('load_todos')` already reaches Reticle as `ipc://load_todos`. You only need this crate for screenshots and headless mode.
+
+```toml
+[dependencies]
+reticle-tauri = "0.1"
+```
+
+<Warning>
+  Do not expect this to match the npm version. Doing so would imply a release cadence the crate does
+  not have, and it would make every npm release a crates.io release for no reason.
+</Warning>
+
+<Card title="Desktop setup in full" icon="display" href="/desktop">
+  Electron and Tauri wiring, including the Tauri CSP whose failure is silent.
+</Card>