@reticlehq/browser

The Reticle instrumentation SDK that runs inside your page, observing the DOM, network, console, routing and state.

@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 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 instead, which re-exports everything here.

npm i -D @reticlehq/browser

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.

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.

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 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.

Instrumenting an app properly

Signals, stores, and what makes evidence strong rather than circumstantial.