@reticlehq/browser 2.3.0 → 2.4.0

package/dist/commands/commands.js

@@ -3,6 +3,7 @@ import { buildSnapshot } from '../dom/snapshot.js';
 import { matchQuery, runQuery } from '../dom/query.js';
 import { executeAction, executeSequence, dispatchWebMcp, } from '../actions/actions.js';
 import { describe } from '../dom/a11y.js';
+import { sourceFor, formatSource } from '../dom/source.js';
 import { themeReport } from '../dom/theme.js';
 import { refs } from '../dom/refs.js';
 import { isButton, isInput } from '../dom/realm.js';
@@ -74,8 +75,15 @@ function inspect(ref) {
             visibility: cs.visibility,
         }
         : null;
+    // `describe()` carries the CHEAP source (the nearest babel-stamped ancestor), because it runs per
+    // element on paths that describe hundreds at once. inspect is a single-element path, so it takes
+    // the adapter's answer first — the component that actually RENDERED this element, not the nearest
+    // stamped host. `act` already did this; inspect did not, so the two tools disagreed about the same
+    // ref and inspect — the tool you reach for to ask where something lives — was the one saying null.
+    const source = formatSource(sourceFor(el, component?.source));
     return {
         ...describe(el),
+        ...(source !== undefined ? { source } : {}),
         tag: el.tagName.toLowerCase(),
         href: el.getAttribute('href') ?? undefined,
         formAction: isButton(el) || isInput(el) ? (el.form?.getAttribute('action') ?? undefined) : undefined,
@@ -132,6 +140,10 @@ function readState(ref, store, path, depth) {
             // what keeps "the list is short" distinguishable from "I shortened the list".
             ...(projected.truncation === undefined ? {} : { truncation: projected.truncation }),
             ...('availableKeys' in selection ? { availableKeys: selection.availableKeys } : {}),
+            // How many keys there REALLY were, when the near-miss list is a sample. Without it, 50 names
+            // and no marker reads as "the key you asked for does not exist" — the strongest negative
+            // signal there is, and a false one when the key is simply number 51.
+            ...('totalKeys' in selection ? { totalKeys: selection.totalKeys } : {}),
             storeNames: names,
         };
     }

package/dist/connect-options.d.ts

@@ -0,0 +1,97 @@
+import type { RedactionConfig } from '@reticlehq/core';
+/**
+ * What `reticle.connect()` accepts.
+ *
+ * Split out of reticle.ts when that file crossed the 600-line cap — the same move `session-info.ts`
+ * made for the server's Session. A pure description of the SDK's public entry contract has no reason
+ * to live inside the class that happens to consume it, and separating them keeps the surface every
+ * integrating app actually reads reviewable on its own.
+ */
+export interface ReticleConnectOptions {
+    /** WS endpoint of the local bridge. Defaults to ws://localhost:<port><path>. */
+    url?: string;
+    /** Human-friendly session label so the agent can target the right tab. */
+    session?: string;
+    /**
+     * Stable project identity, normally stamped by the build plugin (e.g. "acme-web-9f3c1d"). Lets the
+     * agent scope to the right app even when its dev server boots on an unexpected port. Optional.
+     */
+    projectId?: string;
+    /** Browser/bridge pairing token. Required when either endpoint is non-localhost. */
+    token?: string;
+    /** Explicitly allow Reticle on a non-localhost page or bridge. Requires token. */
+    allowNonLocalhost?: boolean;
+    /**
+     * Escape hatch for the production backstop. Reticle is dev-only and refuses to connect when the
+     * build reports NODE_ENV=production (an SSR healthcheck or a prod bundle opened locally would
+     * otherwise activate). The real fix is to gate the import behind `import.meta.env.DEV` so it's
+     * tree-shaken out; this flag only exists for the rare intentional prod diagnostic.
+     */
+    allowInProduction?: boolean;
+    /** Show a small in-page status chip (connection + event count). */
+    overlay?: boolean;
+    /**
+     * Capture request/response bodies on net.request events (dev-only; text-like content only,
+     * sensitive keys redacted, per-body capped). Off by default — bodies cost tokens and can carry PII.
+     */
+    captureNetworkBodies?: boolean;
+    /**
+     * The project root, so source paths report repo-relative instead of absolute.
+     *
+     * React's `_debugSource.fileName` is absolute; the babel stamp is repo-relative. Build plugins that
+     * can `define` a global set it themselves; frameworks that cannot (Next passes it through env,
+     * Astro through its own config) hand it here instead. Taking it as a connect OPTION is what keeps
+     * the generated app-side code plain JavaScript — the previous shape made the caller assign a global,
+     * and the TypeScript cast that needed shipped into a `.jsx` file and broke the build.
+     */
+    root?: string;
+    /** Presenter mode: glow border, animated cursor, click/hover effects, narration HUD. */
+    present?: boolean;
+    /** Per-action pacing (ms) in presenter mode so a human can follow. Default 450. */
+    pace?: number;
+    /** Min ms each narration line stays visible before the next replaces it (presenter). Default 3000. */
+    narrationDwellMs?: number;
+    /**
+     * Border behavior in presenter mode: 'session' (default) persists the border for the whole
+     * session; 'busy' restores the fade-after-idle behavior.
+     */
+    border?: 'session' | 'busy';
+    /** Max accumulated activity-log rows before the oldest are pruned (presenter). Default 50. */
+    logMax?: number;
+    /**
+     * Mount the floating human-recorder toolbar (Record/Stop/Annotate).
+     * Default off — purely additive, dev-only.
+     */
+    recorder?: boolean;
+    /**
+     * Mount the "Flag a bug" annotator: the human clicks an element that looks wrong, types what's
+     * wrong, and Reticle emits a HUMAN_MARK the agent drains via reticle_review. Defaults to ON with the
+     * presenter (it's the human's side of the look→act→assert loop); pass `annotate: false` to suppress.
+     */
+    annotate?: boolean;
+    /** Live-control: overridable ended-border fade delay (native timer). Default 4000. */
+    endedFadeMs?: number;
+    /** Session auto-end after this much agent idle (presenter). Default 5min; agent-tunable via reticle_session. */
+    idleEndMs?: number;
+    /**
+     * Extend the redaction rules with your app's own vocabulary.
+     *
+     * ```ts
+     * reticle.connect({
+     *   redact: {
+     *     keys: ['deviceSecretRef', /^partner[-_]?code$/i],  // also redact these
+     *     allow: ['designToken'],                            // stop redacting this false positive
+     *   },
+     * });
+     * ```
+     *
+     * Additive only — there is no way to replace the built-in rule, because a config that could would
+     * eventually ship an app that leaks. `keys` strings match a key name exactly (case-insensitively);
+     * a RegExp is tested against it. `allow` exempts a key from the DEFAULT rule and loses to `keys`.
+     *
+     * Literal `keys` strings also cross the bridge, so the daemon redacts them on the driven path,
+     * where request bodies are captured raw from the network stack and never pass through this SDK.
+     * RegExp entries and `allow` do NOT cross — see docs/usage.md ("Extending the redaction rules") for why, and what that means.
+     */
+    redact?: RedactionConfig;
+}

package/dist/connect-options.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -8,9 +8,9 @@ export { registerAdapter, identifyComponent, readComponentState, elementHasHover
 export type { ReticleAdapter, ComponentInfo, ComponentSource } from './registry/adapters.js';
 export { registerStore, unregisterStore, storeNames, readStores, readStoresWithTruncation, } from './registry/stores.js';
 export type { StoreGetter, StoreLike, StoreSubscribe } from './registry/stores.js';
-export { tanstackQueryStore, jotaiStore, xstateStore, valtioStore, mobxStore, pushStore, } from './registry/store-adapters.js';
-export type { QuerySnapshot } from './registry/store-adapters.js';
-export { registerCapabilities, getCapabilities, hasCapabilities } from './registry/capabilities.js';
+export { tanstackQueryStore, jotaiStore, xstateStore, valtioStore, mobxStore, recoilStore, svelteStore, piniaStore, pushStore, } from './registry/store-adapters.js';
+export type { QuerySnapshot, RecoilAtomSnapshot } from './registry/store-adapters.js';
+export { registerCapabilities, getCapabilities, hasCapabilities, setCapabilitiesListener, } from './registry/capabilities.js';
 export type { Capabilities, CapabilitiesInput, CapabilityFlow } from './registry/capabilities.js';
 export { createReticleEmitter } from './registry/emitter.js';
 export type { ReticleEmitter, EmitterTarget, CreateReticleEmitterOptions, } from './registry/emitter.js';

package/dist/index.js

@@ -18,9 +18,9 @@ export { registerStore, unregisterStore, storeNames, readStores, readStoresWithT
 // Adapters for state libraries that do not natively expose `{getState, subscribe}`. zustand and Redux
 // need none of these; TanStack Query is the one that matters most, because a stale-cache bug fires no
 // request and renders a plausible value, so the cache is the only witness.
-export { tanstackQueryStore, jotaiStore, xstateStore, valtioStore, mobxStore, pushStore, } from './registry/store-adapters.js';
+export { tanstackQueryStore, jotaiStore, xstateStore, valtioStore, mobxStore, recoilStore, svelteStore, piniaStore, pushStore, } from './registry/store-adapters.js';
 // Capability registry: the app self-describes its testable surface via reticle.describe.
-export { registerCapabilities, getCapabilities, hasCapabilities } from './registry/capabilities.js';
+export { registerCapabilities, getCapabilities, hasCapabilities, setCapabilitiesListener, } from './registry/capabilities.js';
 // SDK helpers: adopt the recommended integration patterns without boilerplate.
 export { createReticleEmitter } from './registry/emitter.js';
 export { commitAndSignal } from './registry/commit-and-signal.js';

package/dist/registry/capabilities.d.ts

@@ -16,6 +16,8 @@ export interface CapabilitiesInput {
     stores?: string[];
     flows?: CapabilityFlow[];
 }
+/** Set by the SDK at connect. Idempotent; the last connect wins. */
+export declare function setCapabilitiesListener(cb: (() => void) | undefined): void;
 /** Called by the host app via reticle.describe. Merges (idempotent), never replaces wholesale. */
 export declare function registerCapabilities(input: CapabilitiesInput): void;
 /** Snapshot copy of the registered capabilities (defensive — never hand out the live arrays). */

package/dist/registry/capabilities.js

@@ -12,6 +12,21 @@ function mergeUnique(into, add) {
         if (!into.includes(v))
             into.push(v);
 }
+/**
+ * Notified whenever capabilities change, so the SDK can re-announce them to the bridge.
+ *
+ * `hasCapabilities` rides in the HELLO, which goes out at connect() — and registering deliberately
+ * happens AFTER connect, because `registerStore` needs a live SDK to subscribe through. Without a
+ * notification, an app that declared its whole testable surface still appeared to the agent as
+ * having none, permanently. The hook lives HERE rather than on `reticle.describe` because the
+ * documented entry point is this bare function; only wiring `describe` would have fixed the path
+ * almost nobody uses.
+ */
+let onChanged;
+/** Set by the SDK at connect. Idempotent; the last connect wins. */
+export function setCapabilitiesListener(cb) {
+    onChanged = cb;
+}
 /** Called by the host app via reticle.describe. Merges (idempotent), never replaces wholesale. */
 export function registerCapabilities(input) {
     mergeUnique(capabilities.testids, input.testids);
@@ -28,6 +43,7 @@ export function registerCapabilities(input) {
             }
         }
     }
+    onChanged?.();
 }
 /** Snapshot copy of the registered capabilities (defensive — never hand out the live arrays). */
 export function getCapabilities() {

package/dist/registry/store-adapters.d.ts

@@ -1,4 +1,4 @@
-import type { StoreLike } from './stores.js';
+import type { StoreLike, StoreSubscribe } from './stores.js';
 /**
  * Adapters that give non-`{getState, subscribe}` state libraries the shape `registerStore` wants.
  *
@@ -119,6 +119,132 @@ export declare function valtioStore<T extends object>(proxy: T, snapshot: (p: T)
  * ```
  */
 export declare function mobxStore<T>(observable: T, toJS: (value: T) => unknown, reaction: (track: () => unknown, effect: () => void) => () => void): StoreLike;
+/** The minimum of a Recoil `Loadable` this adapter touches. */
+interface RecoilLoadableLike {
+    /** 'hasValue' | 'loading' | 'hasError'. Widened to string: it arrives from outside this package. */
+    state: string;
+    /** The value, the pending promise, or the thrown error — which one depends on `state`. */
+    contents: unknown;
+}
+/** The minimum of a Recoil `Snapshot` this adapter touches, generic in the ATOM type. */
+interface RecoilSnapshotLike<A> {
+    getLoadable: (atom: A) => RecoilLoadableLike;
+}
+/** How one Recoil atom is projected: the value never travels without the load state beside it. */
+export interface RecoilAtomSnapshot {
+    status: string;
+    value: unknown;
+    error: string | null;
+}
+/**
+ * Expose a chosen set of Recoil atoms as one Reticle store.
+ *
+ * Three things about Recoil's API shape this adapter is built around, none of them optional:
+ *
+ *  - **The atom map is forced, not an ergonomic choice.** Recoil has no enumerable registry of live
+ *    atoms, so "the whole store" is not a thing that exists. Naming the atoms is the only way to
+ *    snapshot them, and it doubles as a declaration of what matters — the same reason `jotaiStore`
+ *    takes one.
+ *  - **`.state`/`.contents`, never `.getValue()`.** On a pending async selector `getValue()` THROWS
+ *    the pending promise, and on a failed one it throws the error. Either would take down the whole
+ *    state read over one slow atom — so a loading atom reports `status: 'loading'` with a null value
+ *    rather than silently becoming an empty object or an exception.
+ *  - **One subscription, not one per atom.** Recoil exposes no per-atom subscription outside React
+ *    (`jotaiStore` gets `store.sub(atom, …)`; there is no equivalent here). The transaction stream is
+ *    the only public change signal, so the caller passes it in — the same "the library ships free
+ *    functions, so hand them over" shape as `valtioStore` and `mobxStore`.
+ *
+ * Wire it from a bridge component, which is where `useRecoilTransactionObserver_UNSTABLE` lives:
+ *
+ * ```tsx
+ * const latest = useRef(snapshot_UNSTABLE());
+ * const listeners = useRef(new Set<() => void>()).current;
+ * useRecoilTransactionObserver_UNSTABLE(({ snapshot }) => {
+ *   latest.current = snapshot;
+ *   for (const l of listeners) l();
+ * });
+ * registerStore('recoil', recoilStore({ cart: cartAtom }, () => latest.current, (l) => {
+ *   listeners.add(l);
+ *   return () => listeners.delete(l);
+ * }));
+ * ```
+ */
+export declare function recoilStore<A>(atoms: Record<string, A>, snapshot: () => RecoilSnapshotLike<A>, subscribe: StoreSubscribe): StoreLike;
+/**
+ * The minimum of a Svelte store this adapter touches.
+ *
+ * `subscribe` may return either the unsubscribe function or an object carrying one — the store
+ * contract permits both, and an RxJS-shaped source returns the object form.
+ */
+interface SvelteReadable {
+    subscribe: (run: (value: unknown) => void) => (() => void) | {
+        unsubscribe: () => void;
+    };
+}
+/**
+ * Expose a Svelte store as a Reticle store.
+ *
+ * Structurally unlike every other adapter in this file: they all wrap something that can be PULLED
+ * (`getState`, `getSnapshot`, `snapshot(proxy)`, `toJS`). A Svelte store has no pull side at all —
+ * `{ subscribe }` is the entire contract. What makes a pull possible anyway is the part of that
+ * contract which says `subscribe` must call back **immediately and synchronously** with the current
+ * value: subscribe, catch the value, unsubscribe, return it. That is precisely how `svelte/store`'s
+ * own `get()` is implemented, so it is a blessed read rather than a trick.
+ *
+ * Doing it that way is what keeps this adapter free of the `dispose` the obvious implementation
+ * needs. Caching the latest value would mean holding a permanent subscription, which means a
+ * teardown the other five adapters don't have, which means a leak the moment a caller forgets it.
+ * A transient subscription per read owns nothing and leaks nothing.
+ *
+ * ```ts
+ * registerStore('cart', svelteStore(cartStore));
+ * ```
+ */
+export declare function svelteStore(readable: SvelteReadable, warn?: (message: string) => void): StoreLike;
+/**
+ * The minimum of a Pinia store this adapter touches.
+ *
+ * Two things here look over-specified and are not, both found by compiling against the real library
+ * rather than against a fake written to the same belief as the adapter:
+ *
+ *  - **`$state: object`, not `Record<string, unknown>`.** A Pinia store's `$state` is a concrete
+ *    object type with named keys and no index signature, and TypeScript rejects those for a
+ *    `Record<string, unknown>` parameter. `piniaStore(useCartStore())` did not compile — the same
+ *    shape of failure as the Jotai contravariance note above, and equally invisible to a fake.
+ *  - **`flush` as the literal union**, not `string`. The option object is checked contravariantly, so
+ *    a widened `string` here makes the real `$subscribe` unassignable to this shape and the whole
+ *    store stops matching.
+ */
+interface PiniaStoreLike {
+    $state: object;
+    $subscribe: (callback: (mutation: unknown, state: unknown) => void, options?: {
+        detached?: boolean;
+        flush?: 'pre' | 'post' | 'sync';
+    }) => () => void;
+}
+/**
+ * Expose a Pinia store as a Reticle store. `$state` / `$subscribe` are close to `{getState,
+ * subscribe}` but not close enough for `registerStore`'s duck-type, which is the whole reason a Vue
+ * app currently connects and then reports no state at all.
+ *
+ * Both `$subscribe` options are load-bearing:
+ *
+ *  - **`detached`** keeps the subscription alive past the component that happened to register the
+ *    store. Without it Pinia tears the listener down on unmount, so a store registered from inside a
+ *    component goes permanently silent after the first route change — readable, but never again
+ *    emitting a STATE_CHANGE, which reads exactly like an app that stopped changing.
+ *  - **`flush: 'sync'`** puts the notification inside the action's attribution window. The default
+ *    (`'post'`) defers it past the Vue update tick, and a state change that lands after the window
+ *    closed is no longer linked to the click that caused it in the causal summary.
+ *
+ * `$state` carries state, not getters — a Pinia getter is derived, so asserting on the state it
+ * derives from is the stronger assertion anyway.
+ *
+ * ```ts
+ * registerStore('cart', piniaStore(useCartStore()));
+ * ```
+ */
+export declare function piniaStore(store: PiniaStoreLike): StoreLike;
 /**
  * Build a store whose value is PUSHED in rather than pulled — for state that has no object to read.
  *

package/dist/registry/store-adapters.js

@@ -1,3 +1,4 @@
+import { nativeWarn } from '../timers/native-console.js';
 /**
  * Expose a TanStack Query cache as a Reticle store, keyed by query key.
  *
@@ -106,6 +107,183 @@ export function mobxStore(observable, toJS, reaction) {
         subscribe: (listener) => reaction(() => toJS(observable), () => listener()),
     };
 }
+/**
+ * The load states a Recoil `Loadable` reports. Named because the projection below branches on them
+ * and a bare 'hasValue' in three places is exactly the free string the rules forbid.
+ */
+const RecoilLoadState = {
+    HAS_VALUE: 'hasValue',
+    LOADING: 'loading',
+    HAS_ERROR: 'hasError',
+};
+function projectLoadable(loadable) {
+    if (loadable.state === RecoilLoadState.HAS_ERROR) {
+        const contents = loadable.contents;
+        return {
+            status: loadable.state,
+            value: null,
+            error: contents instanceof Error ? contents.message : String(contents),
+        };
+    }
+    // A LOADING loadable's `contents` is the pending promise. Sending it would serialize to `{}` and
+    // read as an empty value — so the value stays null and the status carries the truth.
+    if (loadable.state !== RecoilLoadState.HAS_VALUE) {
+        return { status: loadable.state, value: null, error: null };
+    }
+    return { status: loadable.state, value: loadable.contents, error: null };
+}
+/**
+ * Expose a chosen set of Recoil atoms as one Reticle store.
+ *
+ * Three things about Recoil's API shape this adapter is built around, none of them optional:
+ *
+ *  - **The atom map is forced, not an ergonomic choice.** Recoil has no enumerable registry of live
+ *    atoms, so "the whole store" is not a thing that exists. Naming the atoms is the only way to
+ *    snapshot them, and it doubles as a declaration of what matters — the same reason `jotaiStore`
+ *    takes one.
+ *  - **`.state`/`.contents`, never `.getValue()`.** On a pending async selector `getValue()` THROWS
+ *    the pending promise, and on a failed one it throws the error. Either would take down the whole
+ *    state read over one slow atom — so a loading atom reports `status: 'loading'` with a null value
+ *    rather than silently becoming an empty object or an exception.
+ *  - **One subscription, not one per atom.** Recoil exposes no per-atom subscription outside React
+ *    (`jotaiStore` gets `store.sub(atom, …)`; there is no equivalent here). The transaction stream is
+ *    the only public change signal, so the caller passes it in — the same "the library ships free
+ *    functions, so hand them over" shape as `valtioStore` and `mobxStore`.
+ *
+ * Wire it from a bridge component, which is where `useRecoilTransactionObserver_UNSTABLE` lives:
+ *
+ * ```tsx
+ * const latest = useRef(snapshot_UNSTABLE());
+ * const listeners = useRef(new Set<() => void>()).current;
+ * useRecoilTransactionObserver_UNSTABLE(({ snapshot }) => {
+ *   latest.current = snapshot;
+ *   for (const l of listeners) l();
+ * });
+ * registerStore('recoil', recoilStore({ cart: cartAtom }, () => latest.current, (l) => {
+ *   listeners.add(l);
+ *   return () => listeners.delete(l);
+ * }));
+ * ```
+ */
+export function recoilStore(atoms, snapshot, subscribe) {
+    return {
+        // Resolved per call, not captured once: a Recoil snapshot is IMMUTABLE, so an adapter holding
+        // one would keep answering from the transaction it was built in and never see another write.
+        getState: () => {
+            const current = snapshot();
+            const out = {};
+            for (const [name, atom] of Object.entries(atoms)) {
+                out[name] = projectLoadable(current.getLoadable(atom));
+            }
+            return out;
+        },
+        subscribe,
+    };
+}
+function stopSubscription(handle) {
+    if (typeof handle === 'function') {
+        handle();
+        return;
+    }
+    handle.unsubscribe();
+}
+/**
+ * Expose a Svelte store as a Reticle store.
+ *
+ * Structurally unlike every other adapter in this file: they all wrap something that can be PULLED
+ * (`getState`, `getSnapshot`, `snapshot(proxy)`, `toJS`). A Svelte store has no pull side at all —
+ * `{ subscribe }` is the entire contract. What makes a pull possible anyway is the part of that
+ * contract which says `subscribe` must call back **immediately and synchronously** with the current
+ * value: subscribe, catch the value, unsubscribe, return it. That is precisely how `svelte/store`'s
+ * own `get()` is implemented, so it is a blessed read rather than a trick.
+ *
+ * Doing it that way is what keeps this adapter free of the `dispose` the obvious implementation
+ * needs. Caching the latest value would mean holding a permanent subscription, which means a
+ * teardown the other five adapters don't have, which means a leak the moment a caller forgets it.
+ * A transient subscription per read owns nothing and leaks nothing.
+ *
+ * ```ts
+ * registerStore('cart', svelteStore(cartStore));
+ * ```
+ */
+export function svelteStore(readable, warn = nativeWarn) {
+    let warnedAboutLazyStore = false;
+    return {
+        getState: () => {
+            let value;
+            let called = false;
+            stopSubscription(readable.subscribe((next) => {
+                value = next;
+                called = true;
+            }));
+            // A store that did NOT call back synchronously (an RxJS Observable that is not a
+            // BehaviorSubject, a hand-rolled store that breaks the contract) leaves `value` undefined —
+            // indistinguishable from a store legitimately holding undefined. Reading empty when the answer
+            // is "unknown" is the false green this project exists to prevent, so say it once, out loud.
+            if (!called && !warnedAboutLazyStore) {
+                warnedAboutLazyStore = true;
+                warn('[reticle] a store passed to svelteStore did not call its subscriber synchronously, so ' +
+                    'its current value cannot be read. reticle_state will report undefined for it. Svelte ' +
+                    'stores always call back immediately; an RxJS Observable does not unless it is a ' +
+                    'BehaviorSubject.');
+            }
+            return value;
+        },
+        subscribe: (listener) => {
+            // Swallow whatever arrives DURING the subscribe call. Forwarding it would emit a STATE_CHANGE
+            // at REGISTRATION time for a change that never happened — a diff of nothing that shows up in
+            // causal summaries and that a {kind:'state'} predicate could satisfy without the app doing
+            // anything at all.
+            //
+            // The window is what makes this correct, rather than "swallow the first callback whenever it
+            // arrives". A store that does NOT call back synchronously (an RxJS Observable that is not a
+            // BehaviorSubject — the exact store `getState` warns about) has no registration callback to
+            // drop, so counting callbacks ate its first REAL change: no STATE_CHANGE, and a
+            // {kind:'state'} assertion with nothing to match. A silently missed state change is the false
+            // green this project exists to prevent, so the rule is positional, not ordinal.
+            let inSubscribeCall = true;
+            const handle = readable.subscribe(() => {
+                if (!inSubscribeCall)
+                    listener();
+            });
+            inSubscribeCall = false;
+            return () => stopSubscription(handle);
+        },
+    };
+}
+/** Pinia `$subscribe` options. `sync` and `detached` are library option values, not free strings. */
+const PINIA_SUBSCRIBE_OPTIONS = { detached: true, flush: 'sync' };
+/**
+ * Expose a Pinia store as a Reticle store. `$state` / `$subscribe` are close to `{getState,
+ * subscribe}` but not close enough for `registerStore`'s duck-type, which is the whole reason a Vue
+ * app currently connects and then reports no state at all.
+ *
+ * Both `$subscribe` options are load-bearing:
+ *
+ *  - **`detached`** keeps the subscription alive past the component that happened to register the
+ *    store. Without it Pinia tears the listener down on unmount, so a store registered from inside a
+ *    component goes permanently silent after the first route change — readable, but never again
+ *    emitting a STATE_CHANGE, which reads exactly like an app that stopped changing.
+ *  - **`flush: 'sync'`** puts the notification inside the action's attribution window. The default
+ *    (`'post'`) defers it past the Vue update tick, and a state change that lands after the window
+ *    closed is no longer linked to the click that caused it in the causal summary.
+ *
+ * `$state` carries state, not getters — a Pinia getter is derived, so asserting on the state it
+ * derives from is the stronger assertion anyway.
+ *
+ * ```ts
+ * registerStore('cart', piniaStore(useCartStore()));
+ * ```
+ */
+export function piniaStore(store) {
+    return {
+        // `$state` is a live reactive proxy, so this reads through to the current value rather than
+        // snapshotting at registration. The transport serializer walks it like any object and guards
+        // each key, which is what keeps a throwing reactive trap from costing the whole read.
+        getState: () => store.$state,
+        subscribe: (listener) => store.$subscribe(() => listener(), { ...PINIA_SUBSCRIBE_OPTIONS }),
+    };
+}
 /**
  * Build a store whose value is PUSHED in rather than pulled — for state that has no object to read.
  *

package/dist/reticle.d.ts

@@ -1,62 +1,7 @@
 import { EventType, RETICLE_URL_PARAM, type ReticleEvent } from '@reticlehq/core';
 import { type CapabilitiesInput } from './registry/capabilities.js';
-export interface ReticleConnectOptions {
-    /** WS endpoint of the local bridge. Defaults to ws://localhost:<port><path>. */
-    url?: string;
-    /** Human-friendly session label so the agent can target the right tab. */
-    session?: string;
-    /**
-     * Stable project identity, normally stamped by the build plugin (e.g. "acme-web-9f3c1d"). Lets the
-     * agent scope to the right app even when its dev server boots on an unexpected port. Optional.
-     */
-    projectId?: string;
-    /** Browser/bridge pairing token. Required when either endpoint is non-localhost. */
-    token?: string;
-    /** Explicitly allow Reticle on a non-localhost page or bridge. Requires token. */
-    allowNonLocalhost?: boolean;
-    /**
-     * Escape hatch for the production backstop. Reticle is dev-only and refuses to connect when the
-     * build reports NODE_ENV=production (an SSR healthcheck or a prod bundle opened locally would
-     * otherwise activate). The real fix is to gate the import behind `import.meta.env.DEV` so it's
-     * tree-shaken out; this flag only exists for the rare intentional prod diagnostic.
-     */
-    allowInProduction?: boolean;
-    /** Show a small in-page status chip (connection + event count). */
-    overlay?: boolean;
-    /**
-     * Capture request/response bodies on net.request events (dev-only; text-like content only,
-     * sensitive keys redacted, per-body capped). Off by default — bodies cost tokens and can carry PII.
-     */
-    captureNetworkBodies?: boolean;
-    /** Presenter mode: glow border, animated cursor, click/hover effects, narration HUD. */
-    present?: boolean;
-    /** Per-action pacing (ms) in presenter mode so a human can follow. Default 450. */
-    pace?: number;
-    /** Min ms each narration line stays visible before the next replaces it (presenter). Default 3000. */
-    narrationDwellMs?: number;
-    /**
-     * Border behavior in presenter mode: 'session' (default) persists the border for the whole
-     * session; 'busy' restores the fade-after-idle behavior.
-     */
-    border?: 'session' | 'busy';
-    /** Max accumulated activity-log rows before the oldest are pruned (presenter). Default 50. */
-    logMax?: number;
-    /**
-     * Mount the floating human-recorder toolbar (Record/Stop/Annotate).
-     * Default off — purely additive, dev-only.
-     */
-    recorder?: boolean;
-    /**
-     * Mount the "Flag a bug" annotator: the human clicks an element that looks wrong, types what's
-     * wrong, and Reticle emits a HUMAN_MARK the agent drains via reticle_review. Defaults to ON with the
-     * presenter (it's the human's side of the look→act→assert loop); pass `annotate: false` to suppress.
-     */
-    annotate?: boolean;
-    /** Live-control: overridable ended-border fade delay (native timer). Default 4000. */
-    endedFadeMs?: number;
-    /** Session auto-end after this much agent idle (presenter). Default 5min; agent-tunable via reticle_session. */
-    idleEndMs?: number;
-}
+import type { ReticleConnectOptions } from './connect-options.js';
+export type { ReticleConnectOptions };
 /**
  * Runtime backstop for the dev-only SDK: block connecting when the build reports production, unless
  * explicitly overridden. Pure so it's testable; connect reads NODE_ENV safely (process may be absent

package/dist/reticle.js

@@ -1,8 +1,8 @@
-import { EventType, RETICLE_DEFAULT_PORT, RETICLE_PROTOCOL_VERSION, RETICLE_URL_PARAM, bridgeWsUrl, ReticleCommand, MessageKind, SESSION_AUTO, SessionState, TRANSPORT_LIMITS, isLoopbackHostname, isLocalPage, } from '@reticlehq/core';
+import { EventType, RETICLE_DEFAULT_PORT, RETICLE_PROTOCOL_VERSION, RETICLE_URL_PARAM, bridgeWsUrl, ReticleCommand, MessageKind, SESSION_AUTO, SessionState, TRANSPORT_LIMITS, buildRedactionPolicy, isLoopbackHostname, isLocalPage, setActiveRedactionPolicy, wireRedactionKeys, RETICLE_ROOT_GLOBAL, } from '@reticlehq/core';
 import { createCommandRegistry, RELOAD_CACHE_BUST_PARAM, } from './commands/commands.js';
 import { Transport } from './transport/transport.js';
 import { adapterNames } from './registry/adapters.js';
-import { registerCapabilities, hasCapabilities, } from './registry/capabilities.js';
+import { registerCapabilities, setCapabilitiesListener, hasCapabilities, } from './registry/capabilities.js';
 import { installAllObservers } from './observers/install-all.js';
 import { installOverlay } from './presenter/overlay.js';
 import { Presenter, LOG_KIND, LOG_RESULT, } from './presenter/presenter.js';
@@ -146,6 +146,8 @@ export class Reticle {
     #eventCount = 0;
     #token;
     #projectId;
+    /** App-declared extra redaction keys, announced in hello so the driven path honours them too. */
+    #redactKeys = [];
     /** Act-row log handle for the in-flight act/act_sequence, so its outcome stamps the right row. */
     #actHandle;
     connect(options = {}) {
@@ -172,6 +174,11 @@ export class Reticle {
             globalThis.console.warn(`[Reticle] ${policy.reason ?? 'connection blocked'}`);
             return;
         }
+        // Publish the project root for the adapters' source relativisation. Done HERE, in library code,
+        // so the app-side connect stays plain JavaScript — see ReticleConnectOptions.root.
+        if (options.root !== undefined && options.root.length > 0) {
+            globalThis[RETICLE_ROOT_GLOBAL] = options.root;
+        }
         // A pooled/headless launcher can stamp identity via namespaced URL params; explicit (non-auto)
         // options win, but the `auto` sentinel defers to the URL param so leases correlate.
         const identity = resolveConnectIdentity(options, window.location.search);
@@ -181,6 +188,10 @@ export class Reticle {
         this.#token =
             options.token !== undefined && options.token.length > 0 ? options.token : undefined;
         this.#projectId = identity.projectId;
+        // Install the redaction rule BEFORE anything can emit. Every observer, the serializer and the
+        // snapshot path read it ambiently, so a policy set even one line after installAllObservers would
+        // leave the first events of the session redacted by a different rule than the rest.
+        this.#applyRedaction(options.redact);
         this.#start = performance.now();
         this.#registry = createCommandRegistry();
         this.#transport = new Transport({
@@ -213,6 +224,9 @@ export class Reticle {
                     `or reticle.connect({ url })). Still retrying…`);
             },
         });
+        // Capabilities registered AFTER connect (which is when they are registered, by design) must
+        // reach the bridge, or an app that declared its whole testable surface reads as having none.
+        setCapabilitiesListener(() => this.#transport?.reannounce());
         const emit = this.#emit;
         this.#teardowns = installAllObservers(emit, {
             captureBodies: options.captureNetworkBodies === true,
@@ -288,7 +302,7 @@ export class Reticle {
     }
     /** Advertise the app's testable surface so the agent learns it without reading source. */
     describe(input) {
-        registerCapabilities(input);
+        registerCapabilities(input); // the registry notifies the transport — see setCapabilitiesListener
     }
     /** Live-control: end the session programmatically from the host app (drives the panel to ended). */
     endSession() {
@@ -340,6 +354,16 @@ export class Reticle {
             /* observation is best-effort; the host app's control flow is not */
         }
     };
+    /**
+     * Resolve the app's redaction config into the ambient policy, and remember the part of it that
+     * travels. A config of `undefined` is not "no policy" — it is the DEFAULT policy, installed
+     * explicitly so a second connect() in the same page (HMR, a re-mount) cannot inherit a rule the
+     * previous one set.
+     */
+    #applyRedaction(config) {
+        setActiveRedactionPolicy(buildRedactionPolicy(config, nativeWarn));
+        this.#redactKeys = wireRedactionKeys(config);
+    }
     #hello() {
         return {
             kind: MessageKind.HELLO,
@@ -351,6 +375,7 @@ export class Reticle {
             adapters: adapterNames(),
             ...(this.#token === undefined ? {} : { token: this.#token }),
             hasCapabilities: hasCapabilities(),
+            ...(this.#redactKeys.length === 0 ? {} : { redactKeys: this.#redactKeys }),
         };
     }
     async #handleCommand(command) {

package/dist/transport/transport.d.ts

@@ -45,6 +45,16 @@ export declare class Transport {
     constructor(deps: TransportDeps);
     connect(): void;
     sendEvent(event: ReticleEvent): void;
+    /**
+     * Re-send the HELLO on a live socket.
+     *
+     * The hello carries `hasCapabilities`, and it goes out at connect() — before the app has had a
+     * chance to call `registerCapabilities`, which by design happens AFTER connect so `registerStore`
+     * has a live SDK to subscribe through. So an app that declared its whole testable surface still
+     * appeared to the agent as having none, and nothing ever corrected it. Cheap and idempotent: the
+     * bridge treats a hello as the session's current identity, not as a new session.
+     */
+    reannounce(): void;
     close(): void;
 }
 export {};

package/dist/transport/transport.js

@@ -243,6 +243,20 @@ export class Transport {
             t: event.t,
         });
     }
+    /**
+     * Re-send the HELLO on a live socket.
+     *
+     * The hello carries `hasCapabilities`, and it goes out at connect() — before the app has had a
+     * chance to call `registerCapabilities`, which by design happens AFTER connect so `registerStore`
+     * has a live SDK to subscribe through. So an app that declared its whole testable surface still
+     * appeared to the agent as having none, and nothing ever corrected it. Cheap and idempotent: the
+     * bridge treats a hello as the session's current identity, not as a new session.
+     */
+    reannounce() {
+        if (this.#ws === undefined || this.#ws.readyState !== WebSocket.OPEN)
+            return;
+        this.#ws.send(JSON.stringify(this.#deps.hello()));
+    }
     #sendRaw(text, event) {
         if (this.#ws !== undefined && this.#ws.readyState === WebSocket.OPEN) {
             this.#ws.send(text);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/browser",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Reticle browser SDK — installs observers, builds semantic snapshots, executes actions, talks to the bridge.",
   "type": "module",
   "main": "./dist/index.js",
@@ -13,7 +13,7 @@
   },
   "dependencies": {
     "@testing-library/dom": "^10.4.1",
-    "@reticlehq/core": "2.3.0"
+    "@reticlehq/core": "2.4.0"
   },
   "devDependencies": {
     "@tanstack/query-core": "^5.101.4",
@@ -21,7 +21,12 @@
     "jotai": "^2.20.2",
     "jsdom": "^29.1.1",
     "mobx": "^7.0.0",
+    "pinia": "^4.0.2",
+    "react": "^19.2.8",
+    "recoil": "^0.7.7",
+    "svelte": "^5.56.8",
     "valtio": "^2.3.2",
+    "vue": "^3.5.41",
     "xstate": "^5.32.5"
   },
   "license": "Apache-2.0",