@reticlehq/browser 2.2.1 → 2.4.0

package/dist/actions/actions-dom.d.ts

@@ -26,4 +26,3 @@ export declare function firePointerNonBubbling(el: Element, type: string, relate
  */
 export declare function dragElement(source: HTMLElement, target: HTMLElement | null, data: unknown): Promise<boolean>;
 export {};
-//# sourceMappingURL=actions-dom.d.ts.map

package/dist/actions/actions-dom.js

@@ -133,4 +133,3 @@ export async function dragElement(source, target, data) {
     }
     return dropPrevented;
 }
-//# sourceMappingURL=actions-dom.js.map

package/dist/actions/actions.d.ts

@@ -51,6 +51,9 @@ interface ActionResult {
      * degraded role one — addressing the element across replays with zero hand-added testids.
      */
     component?: string;
+    /** Role + accessible name — the anchor that identifies an INSTANCE, not a JSX site. */
+    role?: string;
+    name?: string;
     source?: {
         file: string;
         line: number;
@@ -89,4 +92,3 @@ export declare function executeSequence(steps: ActionStep[]): Promise<{
     steps: SequenceStepResult[];
 }>;
 export {};
-//# sourceMappingURL=actions.d.ts.map

package/dist/actions/actions.js

@@ -1,26 +1,10 @@
 import { ActionType, ActionWarning, DANGEROUS_ACTION_CONFIRM_ARG, ElementState, isDangerousActionText, SettleReason, } from '@reticlehq/core';
 import { refs } from '../dom/refs.js';
-import { getAccessibleName, isVisible, getStates } from '../dom/a11y.js';
+import { assertEditable, assertNotRichText, setNativeValue } from './value-input.js';
+import { getAccessibleName, getRole, isVisible, getStates } from '../dom/a11y.js';
 import { elementHasHoverHandlers, identifyComponent } from '../registry/adapters.js';
-import { captureValueSetter } from '../patching/capture-method.js';
+import { isForm, isHtmlElement, isInput, isSelect, isTextArea } from '../dom/realm.js';
 import { nativeSetTimeout, settle } from '../timers/native-timers.js';
-/**
- * Set a value on a controlled input the way React expects (native setter + input event).
- * Returns the `input` event's dispatchEvent result (defaultPrevented of the primary event).
- */
-function setNativeValue(el, value) {
-    const proto = el instanceof HTMLTextAreaElement ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype;
-    const setter = captureValueSetter(proto);
-    if (setter !== undefined) {
-        setter.call(el, value);
-    }
-    else {
-        el.value = value;
-    }
-    const notPrevented = el.dispatchEvent(new Event('input', { bubbles: true, cancelable: true }));
-    el.dispatchEvent(new Event('change', { bubbles: true }));
-    return !notPrevented;
-}
 function asString(value, fallback = '') {
     return typeof value === 'string' ? value : fallback;
 }
@@ -28,7 +12,7 @@ function requireElement(ref) {
     const el = refs.resolve(ref);
     if (el === null)
         throw new Error(`ref '${ref}' no longer resolves to an element`);
-    if (!(el instanceof HTMLElement))
+    if (!isHtmlElement(el))
         throw new Error(`ref '${ref}' is not an HTMLElement`);
     return el;
 }
@@ -55,6 +39,12 @@ function anchorOf(el) {
         out.component = component;
     if (info?.source !== undefined)
         out.source = info.source;
+    const role = getRole(el);
+    const name = getAccessibleName(el);
+    if (role.length > 0 && name.length > 0) {
+        out.role = role;
+        out.name = name;
+    }
     return out;
 }
 const result = (ref, action, effect, settled, settleReason, anchor, warning) => {
@@ -77,6 +67,10 @@ const result = (ref, action, effect, settled, settleReason, anchor, warning) =>
         base.component = anchor.component;
     if (anchor.source !== undefined)
         base.source = anchor.source;
+    if (anchor.role !== undefined)
+        base.role = anchor.role;
+    if (anchor.name !== undefined)
+        base.name = anchor.name;
     if (warning !== undefined)
         base.warning = warning;
     return base;
@@ -116,7 +110,7 @@ function assertActionAllowed(el, action, args) {
         action === ActionType.SUBMIT ||
         (action === ActionType.PRESS && asString(args['key'], 'Enter') === 'Enter');
     const dragTarget = action === ActionType.DRAG ? refs.resolve(asString(args['toRef'])) : null;
-    const context = dragTarget instanceof HTMLElement
+    const context = isHtmlElement(dragTarget)
         ? `${dangerousActionContext(el)} ${dangerousActionContext(dragTarget)}`
         : dangerousActionContext(el);
     if (canTrigger &&
@@ -133,9 +127,7 @@ function enabledOf(el) {
 }
 /** Current value for inputs/textareas/selects, else undefined. */
 function valueOf(el) {
-    if (el instanceof HTMLInputElement ||
-        el instanceof HTMLTextAreaElement ||
-        el instanceof HTMLSelectElement) {
+    if (isInput(el) || isTextArea(el) || isSelect(el)) {
         return el.value;
     }
     return undefined;
@@ -190,41 +182,69 @@ async function dispatchFor(el, action, args) {
             el.dispatchEvent(new FocusEvent('focusout', { bubbles: true }));
             return false;
         case ActionType.FILL:
-            if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {
+            if (isInput(el) || isTextArea(el)) {
+                // A MISSING value is a malformed call, not a request to empty the field. `asString` defaults
+                // to '', which made such a fill indistinguishable from `clear`: it wiped what was there,
+                // dispatched a real input event so React committed the empty string to state, and reported
+                // ok:true with nothing flagged. The value is nested (`args:{value}`) at the tool boundary, so
+                // passing it at the top level lands here — measured on bench-app's login form, where
+                // "admin@reticle.dev" was destroyed by a fill that reported success. An explicit '' still
+                // clears, because that is someone asking for it.
+                if (typeof args['value'] !== 'string') {
+                    throw new Error("fill requires a string `value` — pass it nested, as args: { value: '…' }. " +
+                        'To empty a field on purpose use the `clear` action, or fill with an explicit "".');
+                }
+                assertEditable(el, 'fill');
                 el.focus(); // focus first so a later blur commits (onBlur editors)
-                return setNativeValue(el, asString(args['value']));
+                return setNativeValue(el, args['value']);
             }
+            assertNotRichText(el, 'fill');
             throw new Error(`cannot fill a <${el.tagName.toLowerCase()}>`);
         case ActionType.TYPE:
-            if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {
+            if (isInput(el) || isTextArea(el)) {
+                // Same family as the valueless FILL: a missing `text` appended '' and reported ok:true, so an
+                // agent believed it had typed into a field nothing was written to.
+                if (typeof args['text'] !== 'string') {
+                    throw new Error("type requires a string `text` — pass it nested, as args: { text: '…' }.");
+                }
+                assertEditable(el, 'type');
                 el.focus();
-                return setNativeValue(el, el.value + asString(args['text']));
+                return setNativeValue(el, el.value + args['text']);
             }
+            assertNotRichText(el, 'type into');
             throw new Error(`cannot type into a <${el.tagName.toLowerCase()}>`);
         case ActionType.CLEAR:
-            if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {
+            if (isInput(el) || isTextArea(el)) {
                 return setNativeValue(el, '');
             }
             // Consistent with TYPE/SELECT/CHECK: clearing a non-field is not a silent success. Throwing
             // surfaces the mismatch instead of reporting ok:true for an action that did nothing.
             throw new Error(`cannot clear a <${el.tagName.toLowerCase()}>`);
         case ActionType.SELECT:
-            if (el instanceof HTMLSelectElement) {
-                el.value = asString(args['value']);
+            if (isSelect(el)) {
+                // A MISSING value assigned '' to the <select>. No option carries that, so the browser sets
+                // selectedIndex to -1 — deselecting everything — from a call that was simply malformed.
+                // (Selecting a value that no option carries is a different case and is deliberately NOT
+                // refused: `actions.effect.test.ts` pins it as a detectable no-op, where the reported
+                // valueChanged delta is what tells the agent the option never took.)
+                if (typeof args['value'] !== 'string') {
+                    throw new Error("select requires a string `value` — pass it nested, as args: { value: '…' }.");
+                }
+                el.value = args['value'];
                 el.dispatchEvent(new Event('change', { bubbles: true }));
                 return false; // change is not cancelable.
             }
             throw new Error(`cannot select on a <${el.tagName.toLowerCase()}>`);
         case ActionType.CHECK:
         case ActionType.UNCHECK:
-            if (el instanceof HTMLInputElement) {
+            if (isInput(el)) {
                 el.checked = action === ActionType.CHECK;
                 el.dispatchEvent(new Event('change', { bubbles: true }));
                 return false;
             }
             throw new Error(`cannot (un)check a <${el.tagName.toLowerCase()}>`);
         case ActionType.SUBMIT: {
-            const form = el instanceof HTMLFormElement ? el : el.closest('form');
+            const form = isForm(el) ? el : el.closest('form');
             if (form === null)
                 throw new Error('no form to submit');
             form.requestSubmit();
@@ -240,7 +260,7 @@ async function dispatchFor(el, action, args) {
             el.scrollIntoView();
             return false;
         case ActionType.UPLOAD: {
-            if (!(el instanceof HTMLInputElement) || el.type !== 'file') {
+            if (!isInput(el) || el.type !== 'file') {
                 throw new Error('upload target must be a <input type="file">');
             }
             const file = new File([asString(args['content'], 'reticle test file')], asString(args['name'], 'file.txt'), {
@@ -258,7 +278,7 @@ async function dispatchFor(el, action, args) {
             // asString falls back to '' (never undefined), so the old `!== undefined` was always true and
             // handed '' to refs.resolve. A drag with no target ref is a free drag — resolve nothing.
             const resolved = toRef !== '' ? refs.resolve(toRef) : null;
-            return await dragElement(el, resolved instanceof HTMLElement ? resolved : null, args['data']);
+            return await dragElement(el, isHtmlElement(resolved) ? resolved : null, args['data']);
         }
         default:
             throw new Error(`unknown action '${action}'`);
@@ -363,4 +383,3 @@ export async function executeSequence(steps) {
     }
     return { ok: true, count: steps.length, effects, steps: stepResults };
 }
-//# sourceMappingURL=actions.js.map

package/dist/actions/scroll.d.ts

@@ -16,4 +16,3 @@ interface ScrollResult {
  */
 export declare function scrollContainer(ref: string | undefined, dy: number | undefined, fraction?: number): ScrollResult;
 export {};
-//# sourceMappingURL=scroll.d.ts.map

package/dist/actions/scroll.js

@@ -41,4 +41,3 @@ export function scrollContainer(ref, dy, fraction) {
         atEnd: after + target.clientHeight >= target.scrollHeight - 1,
     };
 }
-//# sourceMappingURL=scroll.js.map

package/dist/actions/value-input.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Writing a value into a field, and the two preconditions that make it honest.
+ *
+ * Lifted out of actions.ts when that file hit the 600-line cap. It is a cohesive unit: every export
+ * here exists so that a value write either lands as a real user's edit would, or is refused with a
+ * reason — never forced through while reporting success.
+ */
+/**
+ * Set a value on a controlled input the way React expects (native setter + input event).
+ * Returns the `input` event's dispatchEvent result (defaultPrevented of the primary event).
+ */
+export declare function setNativeValue(el: HTMLInputElement | HTMLTextAreaElement, value: string): boolean;
+/**
+ * Refuse to write to a field a person could not edit.
+ *
+ * `readonly` and `disabled` block USER input, not scripted assignment, so the prototype value setter
+ * writes straight through both. Measured: filling a readonly input reported `ok:true` and
+ * `valueChanged:true` with nothing in the effect block marking it read-only. That leaves the app in a
+ * state no user could reach, and every conclusion drawn from what follows is about software nobody
+ * can operate — the same reason the click path reports `occluded`, and the same choice Playwright
+ * makes when it refuses to fill a non-editable element.
+ */
+/**
+ * A rich-text target is UNSUPPORTED, not a mistake by the caller.
+ *
+ * Every rich-text editor (TipTap, Quill, ProseMirror, Slate, Lexical) is `[contenteditable]`, and
+ * these actions handle only input/textarea. `cannot fill a <div>` reads as "you picked the wrong
+ * element" and sends the reader hunting for a better selector that does not exist. Support is not
+ * faked: assigning textContent would update the DOM while the editor's own model kept the old value,
+ * so the tool would report success for content the app will never submit.
+ */
+export declare function assertNotRichText(el: HTMLElement, action: string): void;
+export declare function assertEditable(el: HTMLInputElement | HTMLTextAreaElement, action: string): void;

package/dist/actions/value-input.js

@@ -0,0 +1,63 @@
+import { captureValueSetter } from '../patching/capture-method.js';
+import { valuePrototypeOf } from '../dom/realm.js';
+/**
+ * Writing a value into a field, and the two preconditions that make it honest.
+ *
+ * Lifted out of actions.ts when that file hit the 600-line cap. It is a cohesive unit: every export
+ * here exists so that a value write either lands as a real user's edit would, or is refused with a
+ * reason — never forced through while reporting success.
+ */
+/**
+ * Set a value on a controlled input the way React expects (native setter + input event).
+ * Returns the `input` event's dispatchEvent result (defaultPrevented of the primary event).
+ */
+export function setNativeValue(el, value) {
+    // Realm-aware: a controlled input inside a same-origin frame has its own prototype.
+    const proto = valuePrototypeOf(el);
+    const setter = proto === undefined ? undefined : captureValueSetter(proto);
+    if (setter !== undefined) {
+        setter.call(el, value);
+    }
+    else {
+        el.value = value;
+    }
+    const notPrevented = el.dispatchEvent(new Event('input', { bubbles: true, cancelable: true }));
+    el.dispatchEvent(new Event('change', { bubbles: true }));
+    return !notPrevented;
+}
+/**
+ * Refuse to write to a field a person could not edit.
+ *
+ * `readonly` and `disabled` block USER input, not scripted assignment, so the prototype value setter
+ * writes straight through both. Measured: filling a readonly input reported `ok:true` and
+ * `valueChanged:true` with nothing in the effect block marking it read-only. That leaves the app in a
+ * state no user could reach, and every conclusion drawn from what follows is about software nobody
+ * can operate — the same reason the click path reports `occluded`, and the same choice Playwright
+ * makes when it refuses to fill a non-editable element.
+ */
+/**
+ * A rich-text target is UNSUPPORTED, not a mistake by the caller.
+ *
+ * Every rich-text editor (TipTap, Quill, ProseMirror, Slate, Lexical) is `[contenteditable]`, and
+ * these actions handle only input/textarea. `cannot fill a <div>` reads as "you picked the wrong
+ * element" and sends the reader hunting for a better selector that does not exist. Support is not
+ * faked: assigning textContent would update the DOM while the editor's own model kept the old value,
+ * so the tool would report success for content the app will never submit.
+ */
+export function assertNotRichText(el, action) {
+    // The ATTRIBUTE, not `isContentEditable`: jsdom does not implement the property, so a test would
+    // pass against a guard that never fires in the environment the unit suite runs in.
+    const flag = el.getAttribute('contenteditable');
+    if (el.isContentEditable || (flag !== null && flag !== 'false')) {
+        throw new Error(`cannot ${action} a contenteditable element — rich-text editors keep their own document model, ` +
+            'so writing to the DOM here would look right and submit the old content. This surface is not supported yet.');
+    }
+}
+export function assertEditable(el, action) {
+    if (el.disabled) {
+        throw new Error(`cannot ${action} a disabled <${el.tagName.toLowerCase()}> — a user could not edit it, so forcing the value would put the app in a state nobody can reach`);
+    }
+    if (el.readOnly) {
+        throw new Error(`cannot ${action} a readonly <${el.tagName.toLowerCase()}> — a user could not edit it, so forcing the value would put the app in a state nobody can reach`);
+    }
+}

package/dist/commands/commands.d.ts

@@ -4,4 +4,3 @@ export declare const RELOAD_CACHE_BUST_PARAM = "_reticle_reload";
 export declare function resolveNavigationUrl(rawUrl: string, baseUrl: string): string | null;
 /** Map browser command names to handlers. Used by the transport on each COMMAND. */
 export declare function createCommandRegistry(): Map<string, CommandHandler>;
-//# sourceMappingURL=commands.d.ts.map

package/dist/commands/commands.js

@@ -3,10 +3,13 @@ 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';
 import { hitTestOccluder } from '../dom/occlusion.js';
 import { readStorage } from '../observers/storage.js';
+import { captureDesktopWindow } from '../dom/desktop-capture.js';
 import { identifyComponent, readComponentState } from '../registry/adapters.js';
 import { readStoresWithTruncation, readStoresRaw, storeNames } from '../registry/stores.js';
 import { sanitizeWithReport } from '../security/serialization.js';
@@ -24,6 +27,14 @@ function num(value) {
 function record(value) {
     return typeof value === 'object' && value !== null ? value : {};
 }
+function sourceLocation(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const obj = value;
+    if (typeof obj['file'] !== 'string' || typeof obj['line'] !== 'number')
+        return undefined;
+    return { file: obj['file'], line: obj['line'], column: num(obj['column']) };
+}
 function queryFromArgs(args) {
     return {
         by: str(args['by']),
@@ -35,10 +46,12 @@ function queryFromArgs(args) {
         placeholder: str(args['placeholder']),
         testid: str(args['testid']),
         alt: str(args['alt']),
+        component: str(args['component']),
         scope: str(args['scope']),
         attrs: Array.isArray(args['attrs'])
             ? args['attrs'].filter((a) => typeof a === 'string')
             : undefined,
+        source: sourceLocation(args['source']),
     };
 }
 function inspect(ref) {
@@ -62,16 +75,19 @@ 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: el instanceof HTMLButtonElement || el instanceof HTMLInputElement
-            ? (el.form?.getAttribute('action') ?? undefined)
-            : undefined,
-        formText: el instanceof HTMLButtonElement || el instanceof HTMLInputElement
-            ? (el.form?.textContent ?? undefined)
-            : undefined,
+        formAction: isButton(el) || isInput(el) ? (el.form?.getAttribute('action') ?? undefined) : undefined,
+        formText: isButton(el) || isInput(el) ? (el.form?.textContent ?? undefined) : undefined,
         box: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
         // True when another element sits over this one's center point — the click would hit the overlay,
         // not this control (a z-index/overlay bug the DOM tree cannot show).
@@ -124,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,
         };
     }
@@ -213,6 +233,7 @@ export function createCommandRegistry() {
     reg.set(ReticleCommand.STATE_READ, (args) => readState(str(args['ref']), str(args['store']), str(args['path']), num(args['depth'])));
     reg.set(ReticleCommand.STORAGE_READ, (args) => readStorage(str(args['area'])));
     reg.set(ReticleCommand.CAPABILITIES, () => getCapabilities());
+    reg.set(ReticleCommand.CAPTURE, (args) => captureDesktopWindow(args['fullPage'] === true));
     reg.set(ReticleCommand.SCROLL, (args) => {
         const dy = args['dy'];
         const fraction = args['fraction'];
@@ -242,4 +263,3 @@ export function createCommandRegistry() {
     });
     return reg;
 }
-//# sourceMappingURL=commands.js.map

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/dom/a11y.d.ts

@@ -1,7 +1,6 @@
 import { ElementState, type ElementDescriptor } from '@reticlehq/core';
 /** Compute the ARIA role (explicit wins, else implicit from the tag). */
 export declare function getRole(el: Element): string;
-/** Accessible name via a practical subset of the accname algorithm. */
 export declare function getAccessibleName(el: Element): string;
 /**
  * The set of states relevant to assertions. `visible` is an O(depth) forced-style walk; callers that
@@ -28,4 +27,3 @@ export declare function isVisible(el: Element, memo?: Map<Element, boolean>): bo
 /** Build the compact descriptor surfaced to the agent. `memo` (optional) shares the per-call
  * visibility cache with the query's state filter so ancestors aren't re-walked per element. */
 export declare function describe(el: Element, memo?: Map<Element, boolean>): ElementDescriptor;
-//# sourceMappingURL=a11y.d.ts.map