@reticlehq/browser 2.13.1 → 2.14.0

package/dist/actions/appeared-text.d.ts

@@ -1,26 +1,6 @@
-/**
- * Gathers the text an action put on the page, from mutation records the observer already receives.
- *
- * `domMutatedWithin` counts records and throws their content away, so a failed login reports
- * `ok / settled / mutated` and reads exactly like a successful one. The message the app rendered
- * was passing through this callback the whole time.
- *
- * Deliberately reports what appeared, never what it means: no error/success classification, no
- * guessing which fragment matters. Truncated, because a route change can add a whole page.
- */
 export declare class AppearedText {
     #private;
     collect(records: readonly MutationRecord[]): void;
-    /**
-     * `{ appeared }` when the APP added text, `{}` otherwise — an absent key means it added none.
-     *
-     * `wrote` is the value the action itself just set, and is excluded: a textarea carries its value
-     * in a child text node, so a controlled one re-rendering after the write mutates characterData
-     * with the caller's own string. Handing that back is noise wearing the name of evidence, and
-     * `valueChanged` already reports that the write landed. Exact-match only, so an app that quotes
-     * your input inside a sentence of its own ("No results for zzz") is still reported — that is
-     * the app talking.
-     */
     effect(wrote?: string): {
         appeared?: string;
     };

package/dist/actions/appeared-text.js

@@ -1,34 +1,11 @@
 import { isIgnored } from '../dom/dom-ignore.js';
-/** Cap on the reported text. Enough for an error message, far short of a re-rendered page. */
 const APPEARED_MAX = 200;
-/** Separator between distinct fragments that appeared in the same window. */
 const JOIN = ' | ';
 const TEXT_NODE = 3;
-/** Any letter, in any script — Latin, Cyrillic, CJK, Arabic. */
 const HAS_LETTER = /\p{L}/u;
-/**
- * A fragment with no letters at all is not the app saying something.
- *
- * The Hostile fixture mutates a counter every 16ms, and clicking a button on that page reported
- * `appeared: "409"` — the ticker, not the action's effect. A count-up animation is exactly what
- * emits a bare number into the settle window, and a bare number carries no message a reader can
- * act on. Deliberately conservative: it drops only fragments with NO letters, so "status 500",
- * "3 items deleted" and "Could not save" all survive. An app whose only feedback is a naked
- * numeral loses it here — the snapshot still shows it, and that is the cheaper mistake.
- */
 function saysSomething(text) {
     return HAS_LETTER.test(text);
 }
-/**
- * Gathers the text an action put on the page, from mutation records the observer already receives.
- *
- * `domMutatedWithin` counts records and throws their content away, so a failed login reports
- * `ok / settled / mutated` and reads exactly like a successful one. The message the app rendered
- * was passing through this callback the whole time.
- *
- * Deliberately reports what appeared, never what it means: no error/success classification, no
- * guessing which fragment matters. Truncated, because a route change can add a whole page.
- */
 export class AppearedText {
     #seen = new Set();
     #length = 0;
@@ -37,7 +14,6 @@ export class AppearedText {
             if (this.#full())
                 return;
             if ('characterData' === record.type) {
-                // The NEW value; oldValue is not requested, so this is what the reader now sees.
                 this.#add(record.target.textContent, record.target.parentElement);
                 continue;
             }
@@ -49,16 +25,6 @@ export class AppearedText {
             }
         }
     }
-    /**
-     * `{ appeared }` when the APP added text, `{}` otherwise — an absent key means it added none.
-     *
-     * `wrote` is the value the action itself just set, and is excluded: a textarea carries its value
-     * in a child text node, so a controlled one re-rendering after the write mutates characterData
-     * with the caller's own string. Handing that back is noise wearing the name of evidence, and
-     * `valueChanged` already reports that the write landed. Exact-match only, so an app that quotes
-     * your input inside a sentence of its own ("No results for zzz") is still reported — that is
-     * the app talking.
-     */
     effect(wrote) {
         const said = [...this.#seen].filter((text) => text !== wrote);
         if (0 === said.length)
@@ -72,8 +38,6 @@ export class AppearedText {
         return this.#length > APPEARED_MAX;
     }
     #add(raw, owner) {
-        // Reticle's own overlay mutates constantly (the "live" panel); reporting it as the app's
-        // response would be worse than reporting nothing.
         if (null !== owner && isIgnored(owner))
             return;
         const text = (raw ?? '').replace(/\s+/g, ' ').trim();

package/dist/actions/danger-context.d.ts

@@ -0,0 +1,3 @@
+export declare function dangerousActionContext(el: HTMLElement): string;
+export declare function submitControlFor(el: HTMLElement): HTMLElement | null;
+export declare function requiresDangerousConfirmation(text: string, role?: string): boolean;

package/dist/actions/danger-context.js

@@ -0,0 +1,39 @@
+import { isDangerousActionText } from '@reticlehq/core';
+import { getAccessibleName } from '../dom/a11y.js';
+const LABEL_VALUED_INPUT_TYPES = new Set([
+    'submit',
+    'button',
+    'reset',
+    'image',
+]);
+function holdsUserText(el) {
+    if (el.isContentEditable)
+        return true;
+    if (el instanceof HTMLTextAreaElement)
+        return true;
+    if (el instanceof HTMLInputElement)
+        return !LABEL_VALUED_INPUT_TYPES.has(el.type.toLowerCase());
+    return false;
+}
+export function dangerousActionContext(el) {
+    const form = el.closest('form');
+    const ownText = holdsUserText(el)
+        ? ['', '']
+        : [el.textContent ?? '', el.getAttribute('value') ?? ''];
+    return [
+        getAccessibleName(el),
+        ...ownText,
+        el.getAttribute('title') ?? '',
+        el.getAttribute('aria-label') ?? '',
+        el.getAttribute('href') ?? '',
+        form?.getAttribute('action') ?? '',
+    ].join(' ');
+}
+const SUBMIT_CONTROL_SELECTOR = 'button[type="submit"], input[type="submit"], button:not([type]):not([type=""])';
+export function submitControlFor(el) {
+    const found = el.closest('form')?.querySelector(SUBMIT_CONTROL_SELECTOR);
+    return found instanceof HTMLElement ? found : null;
+}
+export function requiresDangerousConfirmation(text, role) {
+    return isDangerousActionText(text, role);
+}

package/dist/actions/scroll.d.ts

@@ -1,18 +1,9 @@
-/** Outcome of one container scroll — enough for the server to drive a find loop. */
 interface ScrollResult {
-    /** scrollTop actually moved (false ⇒ already at the end / not scrollable). */
     scrolled: boolean;
     scrollTop: number;
     scrollHeight: number;
     clientHeight: number;
-    /** At (or within 1px of) the bottom — no more rows to reveal by scrolling down. */
     atEnd: boolean;
 }
-/**
- * Scroll the container of `ref` (or the document) down by `dy` (default ~one viewport) so a
- * virtualized list mounts its next window of rows. If `fraction` (0–1) is supplied, jumps
- * directly to that fraction of scrollHeight instead of stepping — enables bisection for large
- * lists where a specific row index is known (targetIndex / totalCount = fraction).
- */
 export declare function scrollContainer(ref: string | undefined, dy: number | undefined, fraction?: number): ScrollResult;
 export {};

package/dist/actions/scroll.js

@@ -1,7 +1,6 @@
 import { refs } from '../dom/refs.js';
 const FALLBACK_STEP_PX = 400;
 const VIEWPORT_FRACTION = 0.8;
-/** The nearest scrollable ancestor of `el` (inclusive), else the document scrolling element. */
 function nearestScrollable(el) {
     let cur = el;
     while (cur !== null && cur !== document.body) {
@@ -12,12 +11,6 @@ function nearestScrollable(el) {
     }
     return document.scrollingElement ?? document.documentElement;
 }
-/**
- * Scroll the container of `ref` (or the document) down by `dy` (default ~one viewport) so a
- * virtualized list mounts its next window of rows. If `fraction` (0–1) is supplied, jumps
- * directly to that fraction of scrollHeight instead of stepping — enables bisection for large
- * lists where a specific row index is known (targetIndex / totalCount = fraction).
- */
 export function scrollContainer(ref, dy, fraction) {
     const base = ref !== undefined ? refs.resolve(ref) : null;
     const target = base instanceof Element

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

@@ -1,9 +1,2 @@
-/** True while a Reticle-dispatched input event is being delivered. */
 export declare function isSyntheticInput(): boolean;
-/**
- * Run `dispatch` marked as Reticle's own.
- *
- * `finally` rather than a trailing decrement: a listener that throws must not leave the flag stuck
- * on, which would silently disable annotation for the rest of the page's life.
- */
 export declare function asSyntheticInput<T>(dispatch: () => T): T;

package/dist/actions/synthetic-input.js

@@ -1,34 +1,7 @@
-/**
- * Is the input event currently being dispatched one that RETICLE made?
- *
- * The annotator listens for clicks in the capture phase and cancels them, because a click in
- * annotate mode is a request to place a mark rather than a request to press a button. That is right
- * for a person and wrong for the agent: `reticle_act` dispatches its clicks into the same document,
- * so with the HUD expanded every agent click was swallowed while the action still reported
- * `dispatched: true`. Measured on this repo's own fixture — the same click that produced
- * `POST /api/login -> 200` with annotate off produced no network at all with it on.
- *
- * `isTrusted` looks like the answer and is not usable: it is false for everything `dispatchEvent`
- * creates, which is also how every test in this package drives the annotator, so gating on it would
- * make annotation untestable and would still not distinguish Reticle's clicks from the page's own
- * synthetic ones.
- *
- * So Reticle marks its own. Dispatch is synchronous, so a plain depth counter held across the call
- * is exact: any listener running inside it — capture phase included — is running because of us.
- * Nested actions are counted rather than flagged, so an inner action finishing does not clear the
- * mark for the outer one still in flight.
- */
 let depth = 0;
-/** True while a Reticle-dispatched input event is being delivered. */
 export function isSyntheticInput() {
     return depth > 0;
 }
-/**
- * Run `dispatch` marked as Reticle's own.
- *
- * `finally` rather than a trailing decrement: a listener that throws must not leave the flag stuck
- * on, which would silently disable annotation for the rest of the page's life.
- */
 export function asSyntheticInput(dispatch) {
     depth += 1;
     try {

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

@@ -1,33 +1,3 @@
-/**
- * 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

@@ -1,18 +1,6 @@
 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) {
@@ -25,28 +13,7 @@ export function setNativeValue(el, value) {
     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, ` +

package/dist/commands/commands.d.ts

@@ -1,6 +1,4 @@
 export type CommandHandler = (args: Record<string, unknown>) => unknown;
-/** Query param appended on a hard reload to bypass the browser cache. */
 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>;

package/dist/commands/commands.js

@@ -17,7 +17,6 @@ import { sanitizeWithReport } from '../security/serialization.js';
 import { getCapabilities } from '../registry/capabilities.js';
 import { freezeClock, advanceClock, resetClock, isClockFrozen } from '../timers/clock.js';
 import { scrollContainer } from '../actions/scroll.js';
-/** Query param appended on a hard reload to bypass the browser cache. */
 export const RELOAD_CACHE_BUST_PARAM = '_reticle_reload';
 function str(value) {
     return 'string' === typeof value ? value : undefined;
@@ -49,10 +48,6 @@ function queryFromArgs(args) {
         alt: str(args['alt']),
         component: str(args['component']),
         scope: str(args['scope']),
-        // The THIRD allowlist a query input has to appear in — tool schema, server forward, and here.
-        // `self` was in the first two and missing from this one, so a live call returned zero matches on
-        // an element that was plainly on the page, with no error to explain it. Same shape as the
-        // `attrs` drop below it.
         self: true === args['self'] ? true : undefined,
         attrs: Array.isArray(args['attrs'])
             ? args['attrs'].filter((a) => 'string' === typeof a)
@@ -62,20 +57,12 @@ function queryFromArgs(args) {
 }
 function inspect(ref) {
     const el = refs.resolve(ref);
-    // THROW, exactly as executeAction does. Returning an error payload made it a SUCCESSFUL command
-    // result, which the server then handed to reticle_inspect's outputSchema (ref/role/name/states/
-    // visible all required) — so the MCP layer answered -32602 Output validation error for the most
-    // ordinary thing that follows a click. The wording matches actions.ts because the server's
-    // recovery table keys off /no longer resolves to an element/ to attach the stale-ref recovery.
     if (null === el)
         throw new Error(editEpoch.staleRefMessage(ref));
     const rect = el.getBoundingClientRect();
     const component = identifyComponent(el);
     const view = el.ownerDocument.defaultView;
     const cs = view !== null ? view.getComputedStyle(el) : null;
-    // Computed style the a11y tree is blind to — `cursor` (does it look interactive?), display/
-    // visibility, and color/opacity — so a UI bug that leaves the element "present but unusable"
-    // (dead cursor, invisible, recolored) is observable in one inspect call.
     const styles = cs !== null
         ? {
             color: cs.color,
@@ -86,16 +73,7 @@ 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));
-    // Say WHY the source is missing rather than omitting the field and leaving the caller to guess.
-    // No stamp anywhere in the document is decisive: the loader is not running, so no element will
-    // have one this session, and the fix is a build-config change rather than anything about this
-    // element. Only computed when `source` is already absent, so the ordinary path pays nothing.
     const sourceUnavailable = source !== undefined
         ? undefined
         : documentHasSourceStamps(el.ownerDocument)
@@ -116,21 +94,16 @@ function inspect(ref) {
         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).
         occluded: isOccluded(el, rect),
         styles,
         scroll,
-        // Theme compliance vs the app's design tokens (off-theme colors a DOM tool can't judge).
         theme: cs !== null ? themeReport(cs) : null,
         component,
     };
 }
-/** Whether a NON-Reticle element covers this one's center point (a transparent overlay / z-index bug). */
 function isOccluded(el, rect) {
     return hitTestOccluder(el, rect) !== null;
 }
-/** Narrowing guard: an adapter returned a ComponentStateResult (has a boolean `ok`). */
 function isComponentStateResult(value) {
     return ('object' === typeof value && value !== null && 'ok' in value && 'boolean' === typeof value.ok);
 }
@@ -138,21 +111,8 @@ const COMPONENT_UNAVAILABLE = {
     ok: false,
     reason: ComponentStateReason.UNAVAILABLE,
 };
-/**
- * Stores are the reliable path. The `ref` component read is bounded: a stale ref, no
- * adapter, or an adapter returning a non-conforming value all collapse to a structured
- * `{ ok: false, reason }` — never a raw (possibly circular) object that could hang serialization.
- *
- * `path`/`depth` are applied HERE, in the page, BEFORE the value crosses the transport — so a scoped
- * read of a huge store (e.g. `deployments.0.status` on a 500-row store) returns only the small
- * sub-tree and is never truncated. (Previously selection ran server-side, AFTER the whole store had
- * already been size-capped in transit, which silently lost any field after a large array.)
- */
 function readState(ref, store, path, depth) {
     const names = storeNames();
-    // Scoped read: walk `path` into the RAW (uncapped) store, then sanitize only the selected sub-tree.
-    // Selecting before the transport cap is what lets a deep/large path (row 250 of a 500-row array)
-    // resolve — capping first would truncate the store before selection ever reached the row.
     if (path !== undefined || depth !== undefined) {
         const rawStores = readStoresRaw(store);
         const base = store !== undefined ? rawStores[store] : { stores: rawStores, storeNames: names };
@@ -164,13 +124,8 @@ function readState(ref, store, path, depth) {
             path,
             found: selection.found,
             value: projected.value,
-            // Even a SCOPED read can hit the caps when the selected sub-tree is itself large; saying so is
-            // 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,
         };
@@ -180,8 +135,6 @@ function readState(ref, store, path, depth) {
         stores,
         storeNames: names,
     };
-    // The whole-store read is where a large store silently became a small one. Present only when a cap
-    // actually fired, so an intact read is unchanged and the field's presence is the warning.
     if (truncation !== undefined)
         result.truncation = truncation;
     if (ref !== undefined && ref.length > 0) {
@@ -196,19 +149,6 @@ function readState(ref, store, path, depth) {
     }
     return result;
 }
-/**
- * Every animation, and WHICH element it drives.
- *
- * Reported from the field: a page with nine concurrent animations returned nine indistinguishable
- * `{playState, currentTime, duration}` rows. `a.effect` was read only for `getTiming()`, never for
- * its `target` — so the tool advertised "targets/timing" and shipped timing alone. A list you cannot
- * index is not a list, and the question this tool exists to answer is "is THAT thing still
- * animating".
- *
- * `describe()` is reused rather than inventing a target shape: it is what `reticle_query` returns,
- * so the descriptor carries a `ref` the agent can pass straight to `reticle_act` — a target you
- * cannot act on would be half an answer.
- */
 function listAnimations() {
     const doc = document;
     if (typeof doc.getAnimations !== 'function')
@@ -216,9 +156,6 @@ function listAnimations() {
     const animations = doc.getAnimations().map((a) => {
         const effect = a.effect;
         const timing = effect?.getTiming();
-        // A KeyframeEffect's target is legitimately nullable, and only KeyframeEffect has one at all.
-        // `null` is reported explicitly: omitting the key would make "this animation has no element"
-        // indistinguishable from the bug above, which is the distinction the fix exists to draw.
         const target = effect?.target ?? null;
         return {
             playState: a.playState,
@@ -240,14 +177,11 @@ export function resolveNavigationUrl(rawUrl, baseUrl) {
         return null;
     }
 }
-/** Map browser command names to handlers. Used by the transport on each COMMAND. */
 export function createCommandRegistry() {
     const reg = new Map();
     reg.set(ReticleCommand.SNAPSHOT, (args) => buildSnapshot({
         scope: str(args['scope']),
         mode: str(args['mode']) ?? SnapshotMode.FULL,
-        // Only the completion re-read sets this: it re-reads a branch the truncated walk stopped
-        // BEFORE emitting, so that branch's own line has to come back with its descendants.
         includeRoot: true === args['includeRoot'],
     }));
     reg.set(ReticleCommand.QUERY, (args) => {
@@ -300,7 +234,6 @@ export function createCommandRegistry() {
     });
     reg.set(ReticleCommand.REFRESH, (args) => {
         if (true === args['hard']) {
-            // Hard reload: navigate to self with a cache-busting param then replace history.
             const url = new URL(window.location.href);
             url.searchParams.set(RELOAD_CACHE_BUST_PARAM, String(Date.now()));
             window.location.replace(url.toString());

package/dist/connect-options.d.ts

@@ -1,120 +1,26 @@
 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 whenever the daemon has one, which is the ordinary case:
-     * it auto-provisions `~/.reticle/pairing-token` on first start and then refuses a hello without it,
-     * including on localhost. Non-localhost additionally needs `allowNonLocalhost`.
-     */
     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;
-    /**
-     * Make Reticle's OWN presenter visible to snapshots and queries. CONTRIBUTORS ONLY.
-     *
-     * The presenter is hidden from every tool by design, for a good reason: an agent that can drive
-     * Reticle's own interface can fabricate its own impact report, and Reticle chrome in a snapshot is
-     * noise in every other app on earth.
-     *
-     * The cost of that rule is that a HUD change is the only kind of change Reticle cannot be used to
-     * check — the panel rendering it is invisible to everything that could look at it. This hatch
-     * exists for exactly that case: the app under test IS Reticle. It reports itself in the app's
-     * capabilities, so a verdict drawn with it open can never be mistaken for an ordinary one.
-     */
+    sourceMapping?: boolean;
+    captureErrorBodies?: boolean;
     exposePresenter?: 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;
-    /**
-     * The SDK's own package version, so a version-skewed pair against the daemon can name itself
-     * rather than surfacing as a bare `-32000`. Build plugins supply it automatically; pass it here
-     * only for a hand-wired connect that has no plugin.
-     */
     sdkVersion?: 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 page annotator: expanding the HUD enters click-to-annotate mode, and Reticle emits
-     * a HUMAN_MARK the agent drains via reticle_review. Defaults to ON with the presenter; 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/dom/a11y.d.ts

@@ -1,38 +1,9 @@
 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;
 export declare function getAccessibleName(el: Element): string;
-/**
- * The set of states relevant to assertions. `visible` is an O(depth) forced-style walk; callers that
- * already computed it (describe) pass it in so it isn't resolved twice per element.
- */
 export declare function getStates(el: Element, visible?: boolean): ElementState[];
-/**
- * True when a form field holds a secret the SDK must never capture verbatim — a password input, a
- * sensitive `autocomplete` (cc-number, one-time-code, …), or a name/id/testid/aria-label that trips
- * `isSensitiveKey`. The single source of truth for both live-snapshot redaction (`getValue`) and the
- * flow recorder's fill-value redaction, so recorded flows never persist typed passwords/OTPs/keys.
- */
 export declare function isSensitiveField(el: Element): boolean;
 export declare function getValue(el: Element): string | undefined;
-/**
- * Whether the element is actually visible (not display:none/hidden/aria-hidden/opacity:0), walking to
- * root. This is an O(depth) forced-style walk PER node; `memo` (optional, scoped to ONE synchronous
- * query pass) caches the full inherited result per element so a broad state-filtered query stops
- * re-resolving getComputedStyle up the same ancestor chain for every sibling. Sound because the DOM is
- * static for the pass's duration — the cache MUST be a per-call Map, never module-level (that would go
- * stale the instant the app mutates, the same trap the shadow-root note in query.ts documents).
- */
-/**
- * True when the element is inside the viewport right now: visible AND its bounding box intersects
- * the window. This is what makes a scroll assertable (#398) — content below the fold of a scrolling
- * container is `visible`/`present` before any scroll, so only a viewport-intersection check can tell
- * "scrolled into view" from "was always in the DOM". Uses getBoundingClientRect (viewport-relative,
- * already accounts for scroll position), not an IntersectionObserver, so it stays synchronous inside
- * the predicate pass.
- */
 export declare function isInViewport(el: Element, memo?: Map<Element, boolean>): boolean;
 export declare function isVisible(el: Element, memo?: Map<Element, boolean>): boolean;
-/** 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;