@reticlehq/browser 2.3.0 → 2.5.0

package/dist/actions/actions-dom.js

@@ -17,7 +17,7 @@ export function fireClickSequence(el) {
     const from = doc.activeElement ?? doc.body;
     firePointer(el, 'pointerdown', from);
     el.dispatchEvent(new MouseEvent('mousedown', { bubbles: true, cancelable: true }));
-    if (el.tabIndex >= 0 && typeof el.focus === 'function')
+    if (el.tabIndex >= 0 && 'function' === typeof el.focus)
         el.focus();
     firePointer(el, 'pointerup', from);
     el.dispatchEvent(new MouseEvent('mouseup', { bubbles: true, cancelable: true }));
@@ -31,7 +31,7 @@ function isMeasurable(rect) {
 /** The center of `rect` falls outside the visible viewport. */
 function isOffViewport(el, rect) {
     const win = el.ownerDocument.defaultView;
-    if (win === null)
+    if (null === win)
         return false;
     const cx = rect.left + rect.width / 2;
     const cy = rect.top + rect.height / 2;
@@ -40,7 +40,7 @@ function isOffViewport(el, rect) {
 /** Hit-test the center: occluded iff the top NON-Reticle element is a foreign subtree (not target/ancestor/descendant). */
 function hitTest(el, rect) {
     const top = hitTestOccluder(el, rect);
-    return top === null
+    return null === top
         ? { occluded: false, occludedBy: null }
         : { occluded: true, occludedBy: refs.refFor(top) };
 }
@@ -56,7 +56,7 @@ export function clickGeometry(el) {
     if (!isMeasurable(rect))
         return NO_GEOMETRY;
     let scrolledIntoView = false;
-    if (isOffViewport(el, rect) && typeof el.scrollIntoView === 'function') {
+    if (isOffViewport(el, rect) && 'function' === typeof el.scrollIntoView) {
         el.scrollIntoView({ block: 'center', inline: 'center' });
         scrolledIntoView = true;
         rect = el.getBoundingClientRect();
@@ -64,7 +64,7 @@ export function clickGeometry(el) {
     return { ...hitTest(el, rect), scrolledIntoView };
 }
 export function firePointer(el, type, relatedTarget = null) {
-    if (typeof PointerEvent === 'function') {
+    if ('function' === typeof PointerEvent) {
         el.dispatchEvent(new PointerEvent(type, { bubbles: true, cancelable: true, relatedTarget }));
     }
     else {
@@ -73,7 +73,7 @@ export function firePointer(el, type, relatedTarget = null) {
 }
 /** Enter/leave pointer events are non-bubbling per spec; keep them so to avoid double-firing. */
 export function firePointerNonBubbling(el, type, relatedTarget = null) {
-    if (typeof PointerEvent === 'function') {
+    if ('function' === typeof PointerEvent) {
         el.dispatchEvent(new PointerEvent(type, { bubbles: false, cancelable: true, relatedTarget }));
     }
     else {
@@ -87,9 +87,9 @@ function makeDataTransfer(data) {
     // data: { mime, value } or [{ mime, value }, …]
     const entries = Array.isArray(data) ? data : data !== undefined ? [data] : [];
     for (const entry of entries) {
-        if (typeof entry === 'object' && entry !== null) {
+        if ('object' === typeof entry && entry !== null) {
             const e = entry;
-            if (typeof e.mime === 'string' && typeof e.value === 'string')
+            if ('string' === typeof e.mime && 'string' === typeof e.value)
                 dt.setData(e.mime, e.value);
         }
     }
@@ -102,7 +102,7 @@ function makeDataTransfer(data) {
 export async function dragElement(source, target, data) {
     const dest = target ?? source;
     const fire = (el, type) => {
-        if (typeof PointerEvent === 'function' && type.startsWith('pointer')) {
+        if ('function' === typeof PointerEvent && type.startsWith('pointer')) {
             el.dispatchEvent(new PointerEvent(type, { bubbles: true, cancelable: true }));
         }
         else {
@@ -118,7 +118,7 @@ export async function dragElement(source, target, data) {
     fire(dest, 'pointerup');
     fire(dest, 'mouseup');
     let dropPrevented = false;
-    if (typeof DragEvent === 'function') {
+    if ('function' === typeof DragEvent) {
         const dataTransfer = makeDataTransfer(data);
         const init = { bubbles: true, cancelable: true };
         if (dataTransfer !== null)

package/dist/actions/actions.d.ts

@@ -81,7 +81,20 @@ interface SequenceStepResult {
     dispatched: boolean;
     settled: boolean;
     settleReason: SettleReason | null;
+    /**
+     * The SAME anchors a single act reports. Reporting only the testid meant a testid-less app
+     * compiled every sub-step to a volatile ref, so the saved flow carried the degraded sentinel and
+     * every replay drifted.
+     */
     testid?: string;
+    component?: string;
+    role?: string;
+    name?: string;
+    source?: {
+        file: string;
+        line: number;
+        column?: number;
+    };
     /** best-effort caveat for this step (e.g. synthetic hover may not fire enter/leave). */
     warning?: string;
 }

package/dist/actions/actions.js

@@ -1,19 +1,19 @@
 import { ActionType, ActionWarning, DANGEROUS_ACTION_CONFIRM_ARG, ElementState, isDangerousActionText, SettleReason, } from '@reticlehq/core';
-import { refs } from '../dom/refs.js';
+import { echoRef, refs } from '../dom/refs.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 { isForm, isHtmlElement, isInput, isSelect, isTextArea } from '../dom/realm.js';
 import { nativeSetTimeout, settle } from '../timers/native-timers.js';
 function asString(value, fallback = '') {
-    return typeof value === 'string' ? value : fallback;
+    return 'string' === typeof value ? value : fallback;
 }
 function requireElement(ref) {
     const el = refs.resolve(ref);
-    if (el === null)
-        throw new Error(`ref '${ref}' no longer resolves to an element`);
+    if (null === el)
+        throw new Error(`ref '${echoRef(ref)}' no longer resolves to an element`);
     if (!isHtmlElement(el))
-        throw new Error(`ref '${ref}' is not an HTMLElement`);
+        throw new Error(`ref '${echoRef(ref)}' is not an HTMLElement`);
     return el;
 }
 /**
@@ -39,12 +39,20 @@ function anchorOf(el) {
         out.component = component;
     if (info?.source !== undefined)
         out.source = info.source;
+    // Reported INDEPENDENTLY. They used to be all-or-nothing, so an element with a role and no
+    // accessible name — an icon button, a clickable div, a control labelled by an SVG — came back with
+    // no identity at all once identifyComponent (React-specific) also found nothing. Two features read
+    // this and both silently degrade without it: the flow recorder anchors a step by it, and coverage
+    // recognises a control it already drove across a re-render by it.
+    //
+    // A role alone is not a unique anchor, and the flow compiler still requires role AND name before it
+    // will anchor a step that way. But it is real information, and reporting it beats reporting nothing.
     const role = getRole(el);
     const name = getAccessibleName(el);
-    if (role.length > 0 && name.length > 0) {
+    if (role.length > 0)
         out.role = role;
+    if (name.length > 0)
         out.name = name;
-    }
     return out;
 }
 const result = (ref, action, effect, settled, settleReason, anchor, warning) => {
@@ -108,7 +116,7 @@ function assertActionAllowed(el, action, args) {
         action === ActionType.DBLCLICK ||
         action === ActionType.DRAG ||
         action === ActionType.SUBMIT ||
-        (action === ActionType.PRESS && asString(args['key'], 'Enter') === 'Enter');
+        (action === ActionType.PRESS && 'Enter' === asString(args['key'], 'Enter'));
     const dragTarget = action === ActionType.DRAG ? refs.resolve(asString(args['toRef'])) : null;
     const context = isHtmlElement(dragTarget)
         ? `${dangerousActionContext(el)} ${dangerousActionContext(dragTarget)}`
@@ -135,7 +143,7 @@ function valueOf(el) {
 /** Ref of the currently-focused element, treating body/null as "no focus". */
 function activeRef(el) {
     const active = el.ownerDocument.activeElement;
-    if (active === null || active === el.ownerDocument.body)
+    if (null === active || active === el.ownerDocument.body)
         return null;
     return refs.refFor(active);
 }
@@ -165,7 +173,7 @@ async function dispatchFor(el, action, args) {
             firePointer(el, 'pointermove', from);
             const moved = el.dispatchEvent(new MouseEvent('mousemove', { bubbles: true, cancelable: true }));
             // hover-dwell: keep "hovering" for holdMs so timer-gated reveals can mount.
-            const holdMs = typeof args['holdMs'] === 'number' ? args['holdMs'] : 0;
+            const holdMs = 'number' === typeof args['holdMs'] ? args['holdMs'] : 0;
             if (holdMs > 0)
                 await sleep(holdMs);
             return !moved;
@@ -224,13 +232,27 @@ async function dispatchFor(el, action, args) {
             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'];
+                const wanted = args['value'];
+                const options = Array.from(el.options);
+                // REFUSE an option that does not exist, before touching the element.
+                //
+                // This used to assign anyway and report the resulting `valueChanged` delta as proof the
+                // option never took. That only works if nobody is listening. An unmatched value drives
+                // selectedIndex to -1, so `el.value` becomes '' — and we then dispatched `change`. Reported
+                // from a real session: the app read that empty value in its change handler and persisted it,
+                // corrupting a stored language setting. The "detectable no-op" both mutated the app into a
+                // state no user could reach AND did it through the app's own handler.
+                //
+                // Same rule as the readonly/disabled refusal: if a real user could not do it, forcing it is
+                // not a test, it is damage.
+                if (!options.some((option) => option.value === wanted)) {
+                    const available = options.map((option) => `${option.value} (${option.label})`).join(', ');
+                    throw new Error(`no <option> with value '${echoRef(wanted)}' — available: ${0 === options.length ? '(none)' : available}`);
+                }
+                el.value = wanted;
                 el.dispatchEvent(new Event('change', { bubbles: true }));
                 return false; // change is not cancelable.
             }
@@ -245,7 +267,7 @@ async function dispatchFor(el, action, args) {
             throw new Error(`cannot (un)check a <${el.tagName.toLowerCase()}>`);
         case ActionType.SUBMIT: {
             const form = isForm(el) ? el : el.closest('form');
-            if (form === null)
+            if (null === form)
                 throw new Error('no form to submit');
             form.requestSubmit();
             return false; // requestSubmit returns void; the internal submit event is unobservable.
@@ -377,6 +399,14 @@ export async function executeSequence(steps) {
         };
         if (res.testid !== undefined)
             stepBase.testid = res.testid;
+        if (res.component !== undefined)
+            stepBase.component = res.component;
+        if (res.role !== undefined)
+            stepBase.role = res.role;
+        if (res.name !== undefined)
+            stepBase.name = res.name;
+        if (res.source !== undefined)
+            stepBase.source = res.source;
         if (res.warning !== undefined)
             stepBase.warning = res.warning;
         stepResults.push(stepBase);

package/dist/actions/scroll.js

@@ -6,7 +6,7 @@ function nearestScrollable(el) {
     let cur = el;
     while (cur !== null && cur !== document.body) {
         const oy = getComputedStyle(cur).overflowY;
-        if ((oy === 'auto' || oy === 'scroll') && cur.scrollHeight > cur.clientHeight)
+        if (('auto' === oy || 'scroll' === oy) && cur.scrollHeight > cur.clientHeight)
             return cur;
         cur = cur.parentElement;
     }

package/dist/commands/commands.js

@@ -3,8 +3,9 @@ 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 { echoRef, refs } from '../dom/refs.js';
 import { isButton, isInput } from '../dom/realm.js';
 import { hitTestOccluder } from '../dom/occlusion.js';
 import { readStorage } from '../observers/storage.js';
@@ -18,16 +19,16 @@ 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 typeof value === 'string' ? value : undefined;
+    return 'string' === typeof value ? value : undefined;
 }
 function num(value) {
-    return typeof value === 'number' ? value : undefined;
+    return 'number' === typeof value ? value : undefined;
 }
 function record(value) {
-    return typeof value === 'object' && value !== null ? value : {};
+    return 'object' === typeof value && value !== null ? value : {};
 }
 function sourceLocation(value) {
-    if (typeof value !== 'object' || value === null)
+    if (typeof value !== 'object' || null === value)
         return undefined;
     const obj = value;
     if (typeof obj['file'] !== 'string' || typeof obj['line'] !== 'number')
@@ -48,15 +49,20 @@ function queryFromArgs(args) {
         component: str(args['component']),
         scope: str(args['scope']),
         attrs: Array.isArray(args['attrs'])
-            ? args['attrs'].filter((a) => typeof a === 'string')
+            ? args['attrs'].filter((a) => 'string' === typeof a)
             : undefined,
         source: sourceLocation(args['source']),
     };
 }
 function inspect(ref) {
     const el = refs.resolve(ref);
-    if (el === null)
-        return { error: `ref '${ref}' no longer resolves` };
+    // 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(`ref '${echoRef(ref)}' no longer resolves to an element`);
     const rect = el.getBoundingClientRect();
     const component = identifyComponent(el);
     const view = el.ownerDocument.defaultView;
@@ -74,8 +80,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,
@@ -96,7 +109,7 @@ function isOccluded(el, rect) {
 }
 /** Narrowing guard: an adapter returned a ComponentStateResult (has a boolean `ok`). */
 function isComponentStateResult(value) {
-    return (typeof value === 'object' && value !== null && 'ok' in value && typeof value.ok === 'boolean');
+    return ('object' === typeof value && value !== null && 'ok' in value && 'boolean' === typeof value.ok);
 }
 const COMPONENT_UNAVAILABLE = {
     ok: false,
@@ -132,6 +145,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,
         };
     }
@@ -146,7 +163,7 @@ function readState(ref, store, path, depth) {
         result.truncation = truncation;
     if (ref !== undefined && ref.length > 0) {
         const el = refs.resolve(ref);
-        if (el === null) {
+        if (null === el) {
             result.component = COMPONENT_UNAVAILABLE;
         }
         else {
@@ -172,11 +189,11 @@ function listAnimations() {
     return { animations };
 }
 export function resolveNavigationUrl(rawUrl, baseUrl) {
-    if (rawUrl.length === 0 || rawUrl.length > TRANSPORT_LIMITS.MAX_URL_LENGTH)
+    if (0 === rawUrl.length || rawUrl.length > TRANSPORT_LIMITS.MAX_URL_LENGTH)
         return null;
     try {
         const url = new URL(rawUrl, baseUrl);
-        return url.protocol === 'http:' || url.protocol === 'https:' ? url.toString() : null;
+        return 'http:' === url.protocol || 'https:' === url.protocol ? url.toString() : null;
     }
     catch {
         return null;
@@ -191,14 +208,14 @@ export function createCommandRegistry() {
     }));
     reg.set(ReticleCommand.QUERY, (args) => {
         const limit = args['limit'];
-        return runQuery(queryFromArgs(args), typeof limit === 'number' ? limit : undefined);
+        return runQuery(queryFromArgs(args), 'number' === typeof limit ? limit : undefined);
     });
     reg.set(ReticleCommand.MATCH, (args) => matchQuery(ElementQuerySchema.parse(record(args['query'])), str(args['state'])));
     reg.set(ReticleCommand.ACT, (args) => {
         const action = str(args['action']) ?? '';
         if (action === ActionType.WEBMCP) {
             const inner = record(args['args']);
-            return dispatchWebMcp(str(inner['tool']) ?? '', record(inner['params']), inner[DANGEROUS_ACTION_CONFIRM_ARG] === true);
+            return dispatchWebMcp(str(inner['tool']) ?? '', record(inner['params']), true === inner[DANGEROUS_ACTION_CONFIRM_ARG]);
         }
         return executeAction(str(args['ref']) ?? '', action, record(args['args']));
     });
@@ -206,14 +223,14 @@ export function createCommandRegistry() {
     reg.set(ReticleCommand.INSPECT, (args) => inspect(str(args['ref']) ?? ''));
     reg.set(ReticleCommand.ANIMATIONS, () => listAnimations());
     reg.set(ReticleCommand.CLOCK, (args) => {
-        if (args['reset'] === true) {
+        if (true === args['reset']) {
             resetClock();
         }
         else {
-            if (args['freeze'] === true)
+            if (true === args['freeze'])
                 freezeClock();
             const adv = args['advanceMs'];
-            if (typeof adv === 'number')
+            if ('number' === typeof adv)
                 advanceClock(adv);
         }
         return { frozen: isClockFrozen() };
@@ -221,24 +238,24 @@ 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.CAPTURE, (args) => captureDesktopWindow(true === args['fullPage']));
     reg.set(ReticleCommand.SCROLL, (args) => {
         const dy = args['dy'];
         const fraction = args['fraction'];
-        return scrollContainer(str(args['ref']), typeof dy === 'number' ? dy : undefined, typeof fraction === 'number' ? fraction : undefined);
+        return scrollContainer(str(args['ref']), 'number' === typeof dy ? dy : undefined, 'number' === typeof fraction ? fraction : undefined);
     });
     reg.set(ReticleCommand.NAVIGATE, (args) => {
         const rawUrl = str(args['url']);
-        if (rawUrl === undefined || rawUrl.length === 0)
+        if (rawUrl === undefined || 0 === rawUrl.length)
             return { ok: false, reason: 'url required' };
         const url = resolveNavigationUrl(rawUrl, window.location.href);
-        if (url === null)
+        if (null === url)
             return { ok: false, reason: 'only http(s) navigation is allowed' };
         window.location.assign(url);
         return { ok: true, url };
     });
     reg.set(ReticleCommand.REFRESH, (args) => {
-        if (args['hard'] === true) {
+        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()));

package/dist/connect-options.d.ts

@@ -0,0 +1,103 @@
+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;
+    /**
+     * 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 "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.js

@@ -45,15 +45,15 @@ function inputRole(input) {
     const type = input.type.toLowerCase();
     if (INPUT_TEXT_TYPES.has(type))
         return 'textbox';
-    if (type === 'checkbox')
+    if ('checkbox' === type)
         return 'checkbox';
-    if (type === 'radio')
+    if ('radio' === type)
         return 'radio';
-    if (type === 'range')
+    if ('range' === type)
         return 'slider';
-    if (type === 'number')
+    if ('number' === type)
         return 'spinbutton';
-    if (type === 'submit' || type === 'button' || type === 'reset')
+    if ('submit' === type || 'button' === type || 'reset' === type)
         return 'button';
     return 'textbox';
 }
@@ -115,7 +115,7 @@ function collapse(text) {
 }
 function labelledByText(el) {
     const ids = el.getAttribute('aria-labelledby');
-    if (ids === null)
+    if (null === ids)
         return null;
     const parts = [];
     for (const id of ids.split(/\s+/)) {
@@ -144,7 +144,7 @@ function textWithoutHidden(node) {
     if (node.nodeType !== Node.ELEMENT_NODE)
         return '';
     const el = node;
-    if (el.getAttribute('aria-hidden') === 'true')
+    if ('true' === el.getAttribute('aria-hidden'))
         return '';
     let out = '';
     for (const child of el.childNodes)
@@ -191,9 +191,9 @@ export function getAccessibleName(el) {
 }
 function ariaBool(el, attr) {
     const value = el.getAttribute(attr);
-    if (value === null)
+    if (null === value)
         return undefined;
-    return value === 'true';
+    return 'true' === value;
 }
 /**
  * The set of states relevant to assertions. `visible` is an O(depth) forced-style walk; callers that
@@ -203,12 +203,12 @@ export function getStates(el, visible = isVisible(el)) {
     const states = [ElementState.PRESENT];
     states.push(visible ? ElementState.VISIBLE : ElementState.HIDDEN);
     const disabledProp = (isButton(el) || isInput(el) || isSelect(el) || isTextArea(el)) && el.disabled;
-    const disabled = disabledProp || ariaBool(el, 'aria-disabled') === true;
+    const disabled = disabledProp || true === ariaBool(el, 'aria-disabled');
     states.push(disabled ? ElementState.DISABLED : ElementState.ENABLED);
-    const checkedProp = isInput(el) && (el.type === 'checkbox' || el.type === 'radio') && el.checked;
-    if (checkedProp || ariaBool(el, 'aria-checked') === true)
+    const checkedProp = isInput(el) && ('checkbox' === el.type || 'radio' === el.type) && el.checked;
+    if (checkedProp || true === ariaBool(el, 'aria-checked'))
         states.push(ElementState.CHECKED);
-    if (ariaBool(el, 'aria-expanded') === true)
+    if (true === ariaBool(el, 'aria-expanded'))
         states.push(ElementState.EXPANDED);
     if (el.ownerDocument.activeElement === el)
         states.push(ElementState.FOCUSED);
@@ -232,7 +232,7 @@ export function isSensitiveField(el) {
         el.getAttribute('aria-label') ?? '',
     ];
     const sensitiveAutocomplete = /current-password|new-password|cc-number|cc-csc|one-time-code/i.test(autocomplete);
-    return ((isInput(el) && el.type.toLowerCase() === 'password') ||
+    return ((isInput(el) && 'password' === el.type.toLowerCase()) ||
         sensitiveAutocomplete ||
         identifiers.some(isSensitiveKey));
 }
@@ -247,19 +247,19 @@ export function getValue(el) {
 }
 /** Whether the element's OWN box hides it — one forced-style resolution, no ancestor walk. */
 function selfHidden(el) {
-    if (el.getAttribute('aria-hidden') === 'true')
+    if ('true' === el.getAttribute('aria-hidden'))
         return true;
     if (isHtmlElement(el) && el.hidden)
         return true;
     const view = el.ownerDocument.defaultView;
     if (view !== null) {
         const style = view.getComputedStyle(el);
-        if (style.display === 'none' ||
-            style.visibility === 'hidden' ||
-            style.visibility === 'collapse') {
+        if ('none' === style.display ||
+            'hidden' === style.visibility ||
+            'collapse' === style.visibility) {
             return true;
         }
-        if (Number.parseFloat(style.opacity || '1') === 0)
+        if (0 === Number.parseFloat(style.opacity || '1'))
             return true;
     }
     return false;
@@ -282,7 +282,7 @@ export function isVisible(el, memo) {
     // Each cached boolean already folds in that node's own aria-hidden/[hidden]/display/visibility/opacity,
     // so inherited visibility composes by AND up the chain and a sibling short-circuits at the first
     // cached ancestor.
-    const result = !selfHidden(el) && (parent === null || isVisible(parent, memo));
+    const result = !selfHidden(el) && (null === parent || isVisible(parent, memo));
     if (memo !== undefined)
         memo.set(el, result);
     return result;

package/dist/dom/auto-anchor.js

@@ -32,7 +32,7 @@ export const AnchorStrategy = {
     POSITION: 'position',
 };
 function nonEmpty(s) {
-    return typeof s === 'string' && s.length > 0;
+    return 'string' === typeof s && s.length > 0;
 }
 /** Source as a compact `file:line` suffix; basename only to stay terse and path-independent. */
 function sourceTag(source) {