@reticlehq/server 3.8.1 → 3.8.2

package/dist/portal/input/drive-error.d.ts

@@ -0,0 +1,6 @@
+import type { DriveErrorCode } from '@reticlehq/core';
+/** Structured, code-tagged failure so callers branch on cause, not message text. */
+export declare class DriveError extends Error {
+    readonly code: DriveErrorCode;
+    constructor(code: DriveErrorCode, message: string);
+}

package/dist/portal/input/drive-error.js

@@ -0,0 +1,9 @@
+/** Structured, code-tagged failure so callers branch on cause, not message text. */
+export class DriveError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'DriveError';
+    }
+}

package/dist/portal/input/real-input-press.d.ts

@@ -0,0 +1,34 @@
+import type { Page } from 'playwright';
+import { InputModeReason } from '@reticlehq/core';
+import type { RealInputArgs } from './real-input.js';
+type SleepFn = (ms: number) => Promise<void>;
+/**
+ * Drive a `press` with a real keyboard — coordinate-free; the key goes to whatever holds focus.
+ * Key and modifiers come from the same core helpers the synthetic dispatcher uses, so the two paths
+ * cannot read the same args differently.
+ *
+ * A `holdMs` splits the chord into down / wait / up, the same shape the page uses for a held key.
+ * `keyboard.press` would send it instantly instead, reporting a hold-to-confirm that never held.
+ * The one thing this cannot reproduce is the auto-repeat a held key emits: the driver sends a single
+ * keydown, where the in-page path sends the repeats a browser would. Named rather than papered over
+ * — an app that counts repeats needs the synthetic path, and a caller that sees a held key do
+ * nothing now has a reason to try it.
+ */
+export declare function pressViaKeyboard(page: Page, args: RealInputArgs, sleep: SleepFn, now: () => number): Promise<number>;
+/**
+ * The `press`es this module will NOT drive: a chord that only the in-page dispatcher can express.
+ *
+ * `args.keys` asks for several keys held down TOGETHER, pressed in order and released in reverse.
+ * That is not a `page.keyboard.press` chord — a non-modifier key cannot appear before the last `+`
+ * — and a real keyboard cannot aim a key at a named element. `args.code` is the third: the driver
+ * presses by KEY name and offers no way to send a physical `code` that disagrees with it, so
+ * `{ text: 'z', code: 'KeyY' }` would strike a different key than the one asked for. All three are
+ * routed to the synthetic path by the caller, which reports the reason rather than pretending a
+ * different gesture happened.
+ *
+ * Ordered by how specifically the caller asked: `keys` then `code` name the KEY, `ref` names only
+ * the target. Two can apply at once, and the earlier one is the more unusual request — the reason
+ * should name that, not the generic "you passed a ref".
+ */
+export declare function unspellablePressReason(ref: string, args: Record<string, unknown>): InputModeReason | undefined;
+export {};

package/dist/portal/input/real-input-press.js

@@ -0,0 +1,150 @@
+import { clampHoldMs, DriveErrorCode, explicitCodeFromArgs, InputModeReason, pressKeyFromArgs, pressKeysFromArgs, pressModifiersFromArgs, } from '@reticlehq/core';
+import { DriveError } from './drive-error.js';
+/**
+ * Drive a `press` with a real keyboard — coordinate-free; the key goes to whatever holds focus.
+ * Key and modifiers come from the same core helpers the synthetic dispatcher uses, so the two paths
+ * cannot read the same args differently.
+ *
+ * A `holdMs` splits the chord into down / wait / up, the same shape the page uses for a held key.
+ * `keyboard.press` would send it instantly instead, reporting a hold-to-confirm that never held.
+ * The one thing this cannot reproduce is the auto-repeat a held key emits: the driver sends a single
+ * keydown, where the in-page path sends the repeats a browser would. Named rather than papered over
+ * — an app that counts repeats needs the synthetic path, and a caller that sees a held key do
+ * nothing now has a reason to try it.
+ */
+export async function pressViaKeyboard(page, args, sleep, now) {
+    const key = pressKeyFromArgs(args);
+    const modifiers = pressModifiersFromArgs(args);
+    const chord = 0 < modifiers.length ? `${modifiers.join('+')}+${key}` : key;
+    const holdMs = clampHoldMs(args.holdMs);
+    if (0 === holdMs) {
+        // `press` DOES take a chord string ("Control+k"), so the tap path needs no splitting.
+        await page.keyboard.press(chord);
+        return 0;
+    }
+    /*
+     * `down`/`up` take ONE key each, unlike `press`: `down('Control+k')` throws
+     * `Unknown key: "Control+k"` — measured on a real Chromium, not assumed. The chord string the
+     * tap path uses therefore cannot express a hold, so the chord is split here: modifiers down in
+     * chord order, the key last, and released in reverse (key first, modifiers reversed), which is
+     * what a hand does and what an app's keyup bookkeeping expects.
+     *
+     * Without the split a held shortcut threw before a single key moved, the caller fell back to
+     * the synthetic path, and a real hold was impossible for any press with modifiers — the exact
+     * gesture `holdMs` exists for.
+     *
+     * ## Why every key that went down is tracked, and every exit path cleans up
+     *
+     * The down calls are the ones that MOVE the keyboard, and they can fail partway: `Control` goes
+     * down, the key after it rejects, and the driver's copy of `Control` is still held. That path
+     * used to fall straight to the caller's synthetic replay — which presses the same chord again on
+     * a keyboard that is already holding a modifier. Tracking what actually went down is what makes
+     * the cleanup below able to release the right keys, and only those: releasing a key that never
+     * went down is its own lie, and it would turn a clean failure into an unnecessary refusal.
+     */
+    const pressed = [];
+    const pressDown = async (k) => {
+        await page.keyboard.down(k);
+        pressed.push(k);
+    };
+    try {
+        for (const modifier of modifiers) {
+            await pressDown(modifier);
+        }
+        await pressDown(key);
+    }
+    catch (error) {
+        // The chord is PARTIALLY down. Release what is held before reporting the failure; if that
+        // cannot be proved, `releaseKeys` throws RELEASE_FAILED and the caller refuses the replay —
+        // the same rule as a failed release on the ordinary path, for the same reason. Only when the
+        // cleanup DOES succeed is the original error safe to hand back.
+        await releaseKeys(page, pressed);
+        throw error;
+    }
+    const startedAt = now();
+    try {
+        await sleep(holdMs);
+    }
+    catch (error) {
+        // The wait failed, and the caller is about to run the synthetic path — which presses this SAME
+        // key a second time. If the driver's copy stays down, a held modifier then colours every later
+        // action for the rest of the run. Best-effort on purpose: whatever went wrong with the wait is
+        // the error worth reporting. A cleanup that cannot be proved is the exception — that one is a
+        // stuck key, and it must reach the caller as a refusal rather than be swallowed.
+        try {
+            await releaseKeys(page, pressed);
+        }
+        catch {
+            throw new DriveError(DriveErrorCode.RELEASE_FAILED, 'the wait failed and the keys it pressed could not be released, so they may still be held');
+        }
+        throw error;
+    }
+    // NOT best-effort: on the ordinary path a failed release is a real failure the caller must hear
+    // about, and swallowing it would report a press whose key is still down.
+    await releaseKeys(page, pressed);
+    return now() - startedAt;
+}
+/**
+ * Release the given keys, in reverse press order, and report a failure as one that leaves the
+ * keyboard UNKNOWN rather than as an ordinary provider error.
+ *
+ * Every release is attempted even after one fails: a stuck `Control` is worse than a stuck letter,
+ * so a failure on one key must not skip the rest. The first failure is what is thrown, since it is
+ * the one that happened first, and it is wrapped in `DriveError` so the caller can tell "this
+ * gesture failed" from "this gesture may have left a key down" — the difference between a safe
+ * synthetic replay and an unsafe one.
+ */
+async function releaseKeys(page, pressed) {
+    let failure;
+    for (const k of [...pressed].reverse()) {
+        try {
+            await page.keyboard.up(k);
+        }
+        catch (error) {
+            failure ??= error;
+        }
+    }
+    if (failure !== undefined) {
+        throw new DriveError(DriveErrorCode.RELEASE_FAILED, `the key was pressed but could not be released, so it may still be held: ${describeFailure(failure)}`);
+    }
+}
+/**
+ * A thrown value as a line a reader can act on.
+ *
+ * Not `String(error)`: a non-Error thrown value (a rejected plain object, an SDK that throws a
+ * record) stringifies to `[object Object]`, which names nothing and hides the one fact the message
+ * exists to carry. Anything that is neither an Error nor a string says so rather than pretending.
+ */
+function describeFailure(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return 'string' === typeof error ? error : 'an unknown error';
+}
+/**
+ * The `press`es this module will NOT drive: a chord that only the in-page dispatcher can express.
+ *
+ * `args.keys` asks for several keys held down TOGETHER, pressed in order and released in reverse.
+ * That is not a `page.keyboard.press` chord — a non-modifier key cannot appear before the last `+`
+ * — and a real keyboard cannot aim a key at a named element. `args.code` is the third: the driver
+ * presses by KEY name and offers no way to send a physical `code` that disagrees with it, so
+ * `{ text: 'z', code: 'KeyY' }` would strike a different key than the one asked for. All three are
+ * routed to the synthetic path by the caller, which reports the reason rather than pretending a
+ * different gesture happened.
+ *
+ * Ordered by how specifically the caller asked: `keys` then `code` name the KEY, `ref` names only
+ * the target. Two can apply at once, and the earlier one is the more unusual request — the reason
+ * should name that, not the generic "you passed a ref".
+ */
+export function unspellablePressReason(ref, args) {
+    if (0 < pressKeysFromArgs(args).length) {
+        return InputModeReason.SYNTHETIC_MULTI_KEY_PRESS_PREFERRED;
+    }
+    if (explicitCodeFromArgs(args) !== undefined) {
+        return InputModeReason.SYNTHETIC_KEY_CODE_PRESS_PREFERRED;
+    }
+    if (0 < ref.length) {
+        return InputModeReason.SYNTHETIC_ELEMENT_PRESS_PREFERRED;
+    }
+    return undefined;
+}

package/dist/portal/input/real-input.d.ts

@@ -11,7 +11,8 @@
  */
 import { type ScriptCoverage } from './js-coverage.js';
 import type { Browser, Page } from 'playwright';
-import { ActionType, DriveErrorCode, InputMode, InputModeReason } from '@reticlehq/core';
+import { DriveError } from './drive-error.js';
+import { ActionType, InputMode } from '@reticlehq/core';
 import { type MockRule } from './network-mock.js';
 import { type NetworkDetail } from './network-detail.js';
 /** Viewport CSS-px box as returned by the INSPECT command (getBoundingClientRect). */
@@ -34,6 +35,8 @@ export type RealInputArgs = {
     key?: string;
     /** For press: modifier names (Meta/Control/Shift/Alt; aliases like `cmd` accepted). */
     modifiers?: string[];
+    /** For click: which mouse button to press (left, middle or right). Absent means left. */
+    button?: string;
     /**
      * For press: several keys held down TOGETHER, pressed in order and released in reverse. Read but
      * never forwarded — a chord with a non-modifier key has no `page.keyboard.press` spelling, so the
@@ -152,11 +155,8 @@ export interface OwnedRealInputProvider extends RealInputProvider {
     /** Close the owned browser. Idempotent. */
     dispose(): Promise<void>;
 }
-/** Structured, code-tagged failure so callers branch on cause, not message text. */
-export declare class DriveError extends Error {
-    readonly code: DriveErrorCode;
-    constructor(code: DriveErrorCode, message: string);
-}
+export { DriveError };
+export { unspellablePressReason } from './real-input-press.js';
 /** Center of a viewport box in CSS px. Pure — unit-tested directly. */
 export declare function boxCenter(box: ElementBox): {
     cx: number;
@@ -174,22 +174,6 @@ export declare function isPointerAction(action: ActionType): boolean;
 export declare function isRealInputAction(action: ActionType): boolean;
 type SleepFn = (ms: number) => Promise<void>;
 type ConnectFn = (url: string) => Promise<Browser>;
-/**
- * The `press`es this module will NOT drive: a chord that only the in-page dispatcher can express.
- *
- * `args.keys` asks for several keys held down TOGETHER, pressed in order and released in reverse.
- * That is not a `page.keyboard.press` chord — a non-modifier key cannot appear before the last `+`
- * — and a real keyboard cannot aim a key at a named element. `args.code` is the third: the driver
- * presses by KEY name and offers no way to send a physical `code` that disagrees with it, so
- * `{ text: 'z', code: 'KeyY' }` would strike a different key than the one asked for. All three are
- * routed to the synthetic path by the caller, which reports the reason rather than pretending a
- * different gesture happened.
- *
- * Ordered by how specifically the caller asked: `keys` then `code` name the KEY, `ref` names only
- * the target. Two can apply at once, and the earlier one is the more unusual request — the reason
- * should name that, not the generic "you passed a ref".
- */
-export declare function unspellablePressReason(ref: string, args: Record<string, unknown>): InputModeReason | undefined;
 /**
  * Shared gesture executor: drive a native gesture on an already-resolved Page. Used by both the
  * CDP-attached and the launched (drive) providers so the pointer logic lives in one place.
@@ -342,4 +326,3 @@ export declare class LaunchedRealInputProvider implements OwnedRealInputProvider
 export declare function selectPage<T extends {
     url(): string;
 }>(pages: readonly T[], sessionUrl: string): T | undefined;
-export {};

package/dist/portal/input/real-input.js

@@ -10,25 +10,20 @@
  * pay for it; the type-only import is elided by `tsc`, so the build stays green without it.
  */
 import { takeJsCoverage } from './js-coverage.js';
+import { DriveError } from './drive-error.js';
+import { pressViaKeyboard } from './real-input-press.js';
 import { stampedDriveUrl } from './drive-url-stamp.js';
 import { launchChromium } from '../../launch-chromium.js';
 import { chromiumLaunchHint, gotoOptions, SCREENSHOT_DETERMINISM, captureWithChromeHidden, } from '../pool/playwright-launcher.js';
 import { BrowserLaunchKind } from '@reticlehq/core/telemetry';
 import { getSessionMetrics } from '../../telemetry/session-metrics.js';
 import { classifyConnectFailure } from '../../telemetry/connect-failure.js';
-import { ActionType, clampHoldMs, DriveErrorCode, DRIVE_PLAYWRIGHT_MISSING_MSG, explicitCodeFromArgs, InputMode, InputModeReason, pressKeyFromArgs, pressKeysFromArgs, pressModifiersFromArgs, } from '@reticlehq/core';
+import { ActionType, DriveErrorCode, DRIVE_PLAYWRIGHT_MISSING_MSG, ClickButton, clickButtonFromArgs, InputMode, pressModifiersFromArgs, } from '@reticlehq/core';
 import { installNetworkMocks } from './network-mock.js';
 import { attachNetworkDetail } from './network-detail.js';
 import { injectedConnectArgs } from '../pool/zero-install.js';
-/** Structured, code-tagged failure so callers branch on cause, not message text. */
-export class DriveError extends Error {
-    code;
-    constructor(code, message) {
-        super(message);
-        this.code = code;
-        this.name = 'DriveError';
-    }
-}
+export { DriveError };
+export { unspellablePressReason } from './real-input-press.js';
 /** Center of a viewport box in CSS px. Pure — unit-tested directly. */
 export function boxCenter(box) {
     return { cx: box.x + box.width / 2, cy: box.y + box.height / 2 };
@@ -63,149 +58,12 @@ function undriven(action, box) {
 const REAL_INPUT_SETTLE_MS = 16;
 /** Default number of interpolation steps for a native drag. */
 const DEFAULT_DRAG_STEPS = 8;
-/**
- * Drive a `press` with a real keyboard — coordinate-free; the key goes to whatever holds focus.
- * Key and modifiers come from the same core helpers the synthetic dispatcher uses, so the two paths
- * cannot read the same args differently.
- *
- * A `holdMs` splits the chord into down / wait / up, the same shape the page uses for a held key.
- * `keyboard.press` would send it instantly instead, reporting a hold-to-confirm that never held.
- * The one thing this cannot reproduce is the auto-repeat a held key emits: the driver sends a single
- * keydown, where the in-page path sends the repeats a browser would. Named rather than papered over
- * — an app that counts repeats needs the synthetic path, and a caller that sees a held key do
- * nothing now has a reason to try it.
- */
-async function pressViaKeyboard(page, args, sleep, now) {
-    const key = pressKeyFromArgs(args);
-    const modifiers = pressModifiersFromArgs(args);
-    const chord = 0 < modifiers.length ? `${modifiers.join('+')}+${key}` : key;
-    const holdMs = clampHoldMs(args.holdMs);
-    if (0 === holdMs) {
-        // `press` DOES take a chord string ("Control+k"), so the tap path needs no splitting.
-        await page.keyboard.press(chord);
-        return 0;
-    }
-    /*
-     * `down`/`up` take ONE key each, unlike `press`: `down('Control+k')` throws
-     * `Unknown key: "Control+k"` — measured on a real Chromium, not assumed. The chord string the
-     * tap path uses therefore cannot express a hold, so the chord is split here: modifiers down in
-     * chord order, the key last, and released in reverse (key first, modifiers reversed), which is
-     * what a hand does and what an app's keyup bookkeeping expects.
-     *
-     * Without the split a held shortcut threw before a single key moved, the caller fell back to
-     * the synthetic path, and a real hold was impossible for any press with modifiers — the exact
-     * gesture `holdMs` exists for.
-     *
-     * ## Why every key that went down is tracked, and every exit path cleans up
-     *
-     * The down calls are the ones that MOVE the keyboard, and they can fail partway: `Control` goes
-     * down, the key after it rejects, and the driver's copy of `Control` is still held. That path
-     * used to fall straight to the caller's synthetic replay — which presses the same chord again on
-     * a keyboard that is already holding a modifier. Tracking what actually went down is what makes
-     * the cleanup below able to release the right keys, and only those: releasing a key that never
-     * went down is its own lie, and it would turn a clean failure into an unnecessary refusal.
-     */
-    const pressed = [];
-    const pressDown = async (k) => {
-        await page.keyboard.down(k);
-        pressed.push(k);
-    };
-    try {
-        for (const modifier of modifiers)
-            await pressDown(modifier);
-        await pressDown(key);
-    }
-    catch (error) {
-        // The chord is PARTIALLY down. Release what is held before reporting the failure; if that
-        // cannot be proved, `releaseKeys` throws RELEASE_FAILED and the caller refuses the replay —
-        // the same rule as a failed release on the ordinary path, for the same reason. Only when the
-        // cleanup DOES succeed is the original error safe to hand back.
-        await releaseKeys(page, pressed);
-        throw error;
-    }
-    const startedAt = now();
-    try {
-        await sleep(holdMs);
-    }
-    catch (error) {
-        // The wait failed, and the caller is about to run the synthetic path — which presses this SAME
-        // key a second time. If the driver's copy stays down, a held modifier then colours every later
-        // action for the rest of the run. Best-effort on purpose: whatever went wrong with the wait is
-        // the error worth reporting. A cleanup that cannot be proved is the exception — that one is a
-        // stuck key, and it must reach the caller as a refusal rather than be swallowed.
-        try {
-            await releaseKeys(page, pressed);
-        }
-        catch {
-            throw new DriveError(DriveErrorCode.RELEASE_FAILED, 'the wait failed and the keys it pressed could not be released, so they may still be held');
-        }
-        throw error;
-    }
-    // NOT best-effort: on the ordinary path a failed release is a real failure the caller must hear
-    // about, and swallowing it would report a press whose key is still down.
-    await releaseKeys(page, pressed);
-    return now() - startedAt;
-}
-/**
- * Release the given keys, in reverse press order, and report a failure as one that leaves the
- * keyboard UNKNOWN rather than as an ordinary provider error.
- *
- * Every release is attempted even after one fails: a stuck `Control` is worse than a stuck letter,
- * so a failure on one key must not skip the rest. The first failure is what is thrown, since it is
- * the one that happened first, and it is wrapped in `DriveError` so the caller can tell "this
- * gesture failed" from "this gesture may have left a key down" — the difference between a safe
- * synthetic replay and an unsafe one.
- */
-async function releaseKeys(page, pressed) {
-    let failure;
-    for (const k of [...pressed].reverse()) {
-        try {
-            await page.keyboard.up(k);
-        }
-        catch (error) {
-            failure ??= error;
-        }
-    }
-    if (failure !== undefined) {
-        throw new DriveError(DriveErrorCode.RELEASE_FAILED, `the key was pressed but could not be released, so it may still be held: ${describeFailure(failure)}`);
-    }
-}
-/**
- * A thrown value as a line a reader can act on.
- *
- * Not `String(error)`: a non-Error thrown value (a rejected plain object, an SDK that throws a
- * record) stringifies to `[object Object]`, which names nothing and hides the one fact the message
- * exists to carry. Anything that is neither an Error nor a string says so rather than pretending.
- */
-function describeFailure(error) {
-    if (error instanceof Error)
-        return error.message;
-    return 'string' === typeof error ? error : 'an unknown error';
-}
-/**
- * The `press`es this module will NOT drive: a chord that only the in-page dispatcher can express.
- *
- * `args.keys` asks for several keys held down TOGETHER, pressed in order and released in reverse.
- * That is not a `page.keyboard.press` chord — a non-modifier key cannot appear before the last `+`
- * — and a real keyboard cannot aim a key at a named element. `args.code` is the third: the driver
- * presses by KEY name and offers no way to send a physical `code` that disagrees with it, so
- * `{ text: 'z', code: 'KeyY' }` would strike a different key than the one asked for. All three are
- * routed to the synthetic path by the caller, which reports the reason rather than pretending a
- * different gesture happened.
- *
- * Ordered by how specifically the caller asked: `keys` then `code` name the KEY, `ref` names only
- * the target. Two can apply at once, and the earlier one is the more unusual request — the reason
- * should name that, not the generic "you passed a ref".
- */
-export function unspellablePressReason(ref, args) {
-    if (0 < pressKeysFromArgs(args).length) {
-        return InputModeReason.SYNTHETIC_MULTI_KEY_PRESS_PREFERRED;
+/** The mouse options a click needs: the button, only when it is not the default left one. */
+function clickOptionsOf(args) {
+    const button = clickButtonFromArgs({ button: args.button });
+    if (button === ClickButton.RIGHT || button === ClickButton.MIDDLE) {
+        return { button };
     }
-    if (explicitCodeFromArgs(args) !== undefined) {
-        return InputModeReason.SYNTHETIC_KEY_CODE_PRESS_PREFERRED;
-    }
-    if (0 < ref.length)
-        return InputModeReason.SYNTHETIC_ELEMENT_PRESS_PREFERRED;
     return undefined;
 }
 /**
@@ -241,19 +99,32 @@ now = Date.now) {
         await sleep(REAL_INPUT_SETTLE_MS);
         return real(true);
     }
-    if (action === ActionType.CLICK) {
-        await page.mouse.move(cx, cy);
-        await page.mouse.click(cx, cy);
-        return real(true);
-    }
-    if (action === ActionType.DBLCLICK) {
+    if (action === ActionType.CLICK || action === ActionType.DBLCLICK) {
         await page.mouse.move(cx, cy);
-        await page.mouse.dblclick(cx, cy);
+        const options = clickOptionsOf(args);
+        const modifiers = pressModifiersFromArgs(args);
+        for (const modifier of modifiers) {
+            await page.keyboard.down(modifier);
+        }
+        try {
+            if (action === ActionType.CLICK) {
+                await page.mouse.click(cx, cy, options);
+            }
+            else {
+                await page.mouse.dblclick(cx, cy, options);
+            }
+        }
+        finally {
+            for (const modifier of [...modifiers].reverse()) {
+                await page.keyboard.up(modifier);
+            }
+        }
         return real(true);
     }
     if (action === ActionType.DRAG) {
-        if (args.toBox === undefined)
+        if (args.toBox === undefined) {
             return real(false);
+        }
         const dst = boxCenter(args.toBox);
         const steps = args.steps ?? DEFAULT_DRAG_STEPS;
         await page.mouse.move(cx, cy);
@@ -341,8 +212,9 @@ export class CdpRealInputProvider {
     /** Attach the response listener the first time we see a page; a no-op afterwards. */
     #listen(page) {
         const sink = this.#onNetworkDetail;
-        if (sink === undefined || this.#listening.has(page))
+        if (sink === undefined || this.#listening.has(page)) {
             return;
+        }
         this.#listening.add(page);
         attachNetworkDetail(page, sink);
     }
@@ -354,8 +226,9 @@ export class CdpRealInputProvider {
             // Playwright's Browser exposes isConnected(); a test fake may not, so only an EXPLICIT false
             // drops the cache — a fake without the method is assumed live.
             const alive = this.#browser.isConnected?.() ?? true;
-            if (alive)
+            if (alive) {
                 return this.#browser;
+            }
             this.#browser = undefined; // fall through and reconnect
         }
         try {
@@ -369,11 +242,13 @@ export class CdpRealInputProvider {
     }
     async #pageFor(sessionUrl) {
         const browser = await this.#ensureBrowser();
-        if (browser === undefined)
+        if (browser === undefined) {
             return undefined;
+        }
         const page = selectPage(browser.contexts().flatMap((c) => c.pages()), sessionUrl);
-        if (page !== undefined)
+        if (page !== undefined) {
             this.#listen(page);
+        }
         return page;
     }
     async takeCodeCoverage(sessionUrl) {
@@ -390,22 +265,25 @@ export class CdpRealInputProvider {
     }
     async perform(sessionUrl, action, box, args) {
         const page = await this.#pageFor(sessionUrl);
-        if (page === undefined)
+        if (page === undefined) {
             return undriven(action, box);
+        }
         return performGesture(page, action, box, args, this.#sleep, this.#now);
     }
     /** PNG of the correlated page, or undefined if none matches. */
     async screenshot(sessionUrl, opts) {
         const page = await this.#pageFor(sessionUrl);
-        if (page === undefined)
+        if (page === undefined) {
             return undefined;
+        }
         return capturePage(page, opts);
     }
     /** The context's cookies and per-origin storage; undefined when no driven page matches. */
     async storageState(sessionUrl) {
         const page = await this.#pageFor(sessionUrl);
-        if (page === undefined)
+        if (page === undefined) {
             return undefined;
+        }
         return page.context().storageState();
     }
     /**
@@ -416,27 +294,32 @@ export class CdpRealInputProvider {
      */
     async applyStorageState(sessionUrl, state) {
         const page = await this.#pageFor(sessionUrl);
-        if (page === undefined)
+        if (page === undefined) {
             return false;
+        }
         const saved = state;
-        if (saved.cookies !== undefined)
+        if (saved.cookies !== undefined) {
             await page.context().addCookies(saved.cookies);
+        }
         for (const origin of saved.origins ?? []) {
             // Only the document for an origin can write that origin's localStorage, so this is applied in
             // the page rather than through the context. A page sitting on a different origin cannot be
             // given another origin's storage, and silently succeeding there would be the quiet half-restore
             // this whole path exists to avoid.
-            if (!page.url().startsWith(origin.origin))
+            if (!page.url().startsWith(origin.origin)) {
                 continue;
+            }
             await page.evaluate((entries) => {
                 // Reached through `globalThis` rather than `window`: this body is serialised and runs in the
                 // PAGE, but it is typechecked here, and this package never pulls in the DOM lib — a server
                 // that can name `window` is one step from a server that uses it.
                 const store = globalThis.localStorage;
-                if (store === undefined)
+                if (store === undefined) {
                     return;
-                for (const entry of entries)
+                }
+                for (const entry of entries) {
                     store.setItem(entry.name, entry.value);
+                }
             }, origin.localStorage ?? []);
         }
         return true;
@@ -444,16 +327,18 @@ export class CdpRealInputProvider {
     /** Apply network-mock rules to the correlated page; false when no driven page matches. */
     async setMocks(sessionUrl, rules) {
         const page = await this.#pageFor(sessionUrl);
-        if (page === undefined)
+        if (page === undefined) {
             return false;
+        }
         await installNetworkMocks(page, rules);
         return true;
     }
     /** Pin the correlated page's viewport to fixed dimensions; false when no driven page matches. */
     async setViewport(sessionUrl, size) {
         const page = await this.#pageFor(sessionUrl);
-        if (page === undefined)
+        if (page === undefined) {
             return false;
+        }
         await page.setViewportSize({ width: size.width, height: size.height });
         return true;
     }
@@ -461,8 +346,9 @@ export class CdpRealInputProvider {
     async dispose() {
         const browser = this.#browser;
         this.#browser = undefined;
-        if (browser !== undefined)
+        if (browser !== undefined) {
             await browser.close();
+        }
     }
 }
 const INJECT_CONNECT_WAIT_MS = 8_000;
@@ -519,8 +405,9 @@ export class LaunchedRealInputProvider {
         const page = await this.#browser.newPage(this.#storageState !== undefined ? { storageState: this.#storageState } : undefined);
         this.#page = page;
         // Capture CDP-authoritative response detail into the driven session's journal (best-effort).
-        if (this.#onNetworkDetail !== undefined)
+        if (this.#onNetworkDetail !== undefined) {
             attachNetworkDetail(page, this.#onNetworkDetail);
+        }
         try {
             // Same navigation rule as the pool, and for the same measured reason: Playwright's default
             // waits for `load`, which an app with one never-finishing subresource never fires — 30s of
@@ -542,8 +429,9 @@ export class LaunchedRealInputProvider {
      */
     async #tryInjectConnect(page) {
         const opts = this.#injectConnect;
-        if (opts === undefined)
+        if (opts === undefined) {
             return;
+        }
         try {
             await page.waitForFunction('!!globalThis.__reticleInstance', {
                 timeout: INJECT_CONNECT_WAIT_MS,
@@ -567,8 +455,9 @@ export class LaunchedRealInputProvider {
      */
     #livePage() {
         const page = this.#page;
-        if (page === undefined)
+        if (page === undefined) {
             return undefined;
+        }
         if (true === page.isClosed?.()) {
             this.#page = undefined; // never ask a corpse twice
             return undefined;
@@ -577,10 +466,12 @@ export class LaunchedRealInputProvider {
     }
     isAvailableFor(sessionUrl) {
         const page = this.#livePage();
-        if (page === undefined)
+        if (page === undefined) {
             return Promise.resolve(false);
-        if (page.url() === sessionUrl)
+        }
+        if (page.url() === sessionUrl) {
             return Promise.resolve(true);
+        }
         return Promise.resolve(stripVolatile(page.url()) === stripVolatile(sessionUrl));
     }
     /**
@@ -593,8 +484,9 @@ export class LaunchedRealInputProvider {
      */
     async storageState(_sessionUrl) {
         const page = this.#livePage();
-        if (page === undefined)
+        if (page === undefined) {
             return undefined;
+        }
         return page.context().storageState();
     }
     /**
@@ -603,37 +495,44 @@ export class LaunchedRealInputProvider {
      */
     async applyStorageState(_sessionUrl, state) {
         const page = this.#livePage();
-        if (page === undefined)
+        if (page === undefined) {
             return false;
+        }
         const saved = state;
-        if (saved.cookies !== undefined)
+        if (saved.cookies !== undefined) {
             await page.context().addCookies(saved.cookies);
+        }
         for (const origin of saved.origins ?? []) {
             // A page sitting on a different origin cannot be given another origin's storage, and silently
             // succeeding there is the quiet half-restore this whole path exists to avoid.
-            if (!page.url().startsWith(origin.origin))
+            if (!page.url().startsWith(origin.origin)) {
                 continue;
+            }
             await page.evaluate((entries) => {
                 const store = globalThis.localStorage;
-                if (store === undefined)
+                if (store === undefined) {
                     return;
-                for (const entry of entries)
+                }
+                for (const entry of entries) {
                     store.setItem(entry.name, entry.value);
+                }
             }, origin.localStorage ?? []);
         }
         return true;
     }
     perform(_sessionUrl, action, box, args) {
         const page = this.#livePage();
-        if (page === undefined)
+        if (page === undefined) {
             return Promise.resolve(undriven(action, box));
+        }
         return performGesture(page, action, box, args, this.#sleep, this.#now);
     }
     /** PNG of the owned page, or undefined before navigate / after dispose. */
     screenshot(_sessionUrl, opts) {
         const page = this.#livePage();
-        if (page === undefined)
+        if (page === undefined) {
             return Promise.resolve(undefined);
+        }
         return capturePage(page, opts);
     }
     /**
@@ -646,8 +545,9 @@ export class LaunchedRealInputProvider {
      */
     async setViewport(_sessionUrl, size) {
         const page = this.#livePage();
-        if (page === undefined)
+        if (page === undefined) {
             return false;
+        }
         await page.setViewportSize({ width: size.width, height: size.height });
         return true;
     }
@@ -658,8 +558,9 @@ export class LaunchedRealInputProvider {
     /** Apply network-mock rules to the owned page; false before navigate / after dispose. */
     async setMocks(_sessionUrl, rules) {
         const page = this.#livePage();
-        if (page === undefined)
+        if (page === undefined) {
             return false;
+        }
         await installNetworkMocks(page, rules);
         return true;
     }
@@ -668,8 +569,9 @@ export class LaunchedRealInputProvider {
         const browser = this.#browser;
         this.#browser = undefined;
         this.#page = undefined;
-        if (browser !== undefined)
+        if (browser !== undefined) {
             await browser.close();
+        }
     }
 }
 /** Drop hash/query so a page whose URL drifted by fragment still correlates to the session. */
@@ -688,8 +590,9 @@ export class LaunchedRealInputProvider {
  */
 export function selectPage(pages, sessionUrl) {
     const exact = pages.find((p) => p.url() === sessionUrl);
-    if (exact !== undefined)
+    if (exact !== undefined) {
         return exact;
+    }
     const target = stripVolatile(sessionUrl);
     const loose = pages.filter((p) => stripVolatile(p.url()) === target);
     return 1 === loose.length ? loose[0] : undefined;

package/dist/surface/tools/act-tools.js

@@ -123,7 +123,7 @@ export const ACT_TOOLS = [
             args: z
                 .record(z.string(), z.unknown())
                 .optional()
-                .describe('Action-specific arguments: { value } for fill/select, { text } for type/press (the key NAME, e.g. Escape or Tab), { modifiers: ["Meta","Shift"] } for a press shortcut (Meta/Control/Shift/Alt — a Cmd+K), { toRef } for drag (the ref to drop ON — without it the drag lands nowhere), { native: true } to force a trusted native click, { holdMs: N } to keep the pointer or the key DOWN for N ms (hold-to-confirm controls; effect.heldMs reports what was achieved), { confirmDangerous: true } to allow a potentially destructive control — a permission gate, NOT a duration. For press: { keys: ["Control","k"] } holds several keys down TOGETHER (pressed in order, released in reverse) and { code } names the physical key — both stay on the in-page dispatcher, the only path that can express them. For upload: { path } is a path on disk (absolute or relative to the project root; the daemon reads the file and delivers real bytes to the file picker — this is the way to verify document-ingestion flows); or { name, content?, type? } to supply inline bytes directly.'),
+                .describe('Action-specific arguments: { value } for fill/select (select also drives an ARIA combobox: it opens it and clicks the option by its label), { text } for type/press (the key NAME, e.g. Escape or Tab), { modifiers: ["Meta","Shift"] } for a press shortcut (Meta/Control/Shift/Alt — a Cmd+K) or a click/dblclick (Shift+click range select), { button: "right" | "middle" } for a click (right sends contextmenu), { toRef } for drag (the ref to drop ON — without it the drag lands nowhere), { native: true } to force a trusted native click, { holdMs: N } to keep the pointer or the key DOWN for N ms (hold-to-confirm controls; effect.heldMs reports what was achieved), { confirmDangerous: true } to allow a potentially destructive control — a permission gate, NOT a duration. For press: { keys: ["Control","k"] } holds several keys down TOGETHER (pressed in order, released in reverse) and { code } names the physical key — both stay on the in-page dispatcher, the only path that can express them. For upload: { path } is a path on disk (absolute or relative to the project root; the daemon reads the file and delivers real bytes to the file picker — this is the way to verify document-ingestion flows); or { name, content?, type? } to supply inline bytes directly.'),
             refuseWhenThrottled: z
                 .boolean()
                 .optional()
@@ -271,7 +271,7 @@ export const ACT_TOOLS = [
             args: z
                 .record(z.string(), z.unknown())
                 .optional()
-                .describe('Action-specific arguments: { value } for fill/select, { text } for type/press (the key NAME, e.g. Escape or Tab), { modifiers: ["Meta","Shift"] } for a press shortcut (Meta/Control/Shift/Alt), { toRef } for drag (the ref to drop ON — without it the drag lands nowhere), { confirmDangerous: true } for a potentially destructive control. For upload: { path } is a path on disk (absolute or relative to project root; daemon reads real bytes) or { name, content?, type? } for inline bytes.'),
+                .describe('Action-specific arguments: { value } for fill/select (select also drives an ARIA combobox: it opens it and clicks the option by its label), { text } for type/press (the key NAME, e.g. Escape or Tab), { modifiers: ["Meta","Shift"] } for a press shortcut or a click (Meta/Control/Shift/Alt), { button: "right" | "middle" } for a click, { toRef } for drag (the ref to drop ON — without it the drag lands nowhere), { confirmDangerous: true } for a potentially destructive control. For upload: { path } is a path on disk (absolute or relative to project root; daemon reads real bytes) or { name, content?, type? } for inline bytes.'),
             predicate: PredicateSchema.optional().describe('Alias for `until`.'),
             until: PredicateSchema.optional().describe('Predicate to wait for after the action completes (same shape as reticle_assert). OMIT to wait for the page to SETTLE — network + DOM idle — the deterministic default instead of a sleep. To assert a consequence AND settle, allOf them: { kind: "allOf", predicates: [<your predicate>, { kind: "settled" }] }.'),
             timeout_ms: timeoutMsSchema

package/dist/surface/tools/real-input-attempt.js

@@ -19,7 +19,7 @@
  * the base64 4/3 inflation factor applied, so the encoded payload always fits in one WebSocket
  * frame.
  */
-import { ActionType, DriveErrorCode, ElementState, INSPECT_IN_VIEWPORT_FIELD, INSPECT_REVEAL_ARG, InputMode, InputModeReason, ReticleCommand, TRANSPORT_LIMITS, } from '@reticlehq/core';
+import { ActionType, clickInputProblem, DriveErrorCode, ElementState, INSPECT_IN_VIEWPORT_FIELD, INSPECT_REVEAL_ARG, InputMode, InputModeReason, ReticleCommand, TRANSPORT_LIMITS, } from '@reticlehq/core';
 import { boxCenter, DriveError, isRealInputAction, unspellablePressReason, } from '../../portal/input/real-input.js';
 import { assertDragNotDestructive, assertNotDestructive } from './act/act-danger.js';
 import { assertNativeAllowed } from '../../portal/production/production-drive.js';
@@ -101,10 +101,12 @@ const UPLOAD_MAX_BYTES = Math.floor((TRANSPORT_LIMITS.MAX_MESSAGE_BYTES / (4 / 3
  * through unchanged. `home` is injected so unit tests do not depend on the machine's real home.
  */
 function expandUserPath(rawPath, home) {
-    if ('~' === rawPath)
+    if ('~' === rawPath) {
         return home;
-    if (rawPath.startsWith('~/') || rawPath.startsWith('~\\'))
+    }
+    if (rawPath.startsWith('~/') || rawPath.startsWith('~\\')) {
         return join(home, rawPath.slice(2));
+    }
     return rawPath;
 }
 /** True when `real` is inside `root` after both have been realpath'd / resolved. */
@@ -132,15 +134,18 @@ async function readUploadRoots(projectRoot, fs, home) {
     catch {
         return [];
     }
-    if ('object' !== typeof parsed || null === parsed || Array.isArray(parsed))
+    if ('object' !== typeof parsed || null === parsed || Array.isArray(parsed)) {
         return [];
+    }
     const listed = parsed['uploadRoots'];
-    if (!Array.isArray(listed))
+    if (!Array.isArray(listed)) {
         return [];
+    }
     const roots = [];
     for (const entry of listed) {
-        if ('string' !== typeof entry || 0 === entry.trim().length)
+        if ('string' !== typeof entry || 0 === entry.trim().length) {
             continue;
+        }
         roots.push(resolve(expandUserPath(entry.trim(), home)));
     }
     return roots;
@@ -191,11 +196,13 @@ async function resolveUploadPath(rawPath, projectRoot, fs, uploadRoots, home) {
 export async function rewriteUploadArgs(deps, action, innerArgs, 
 /** Injected for tests; production uses the process home directory. */
 home = homedir()) {
-    if (action !== ActionType.UPLOAD)
+    if (action !== ActionType.UPLOAD) {
         return innerArgs;
+    }
     const rawPath = asString(innerArgs['path']);
-    if (rawPath === undefined)
-        return innerArgs; // no path → browser handles as inline upload
+    if (rawPath === undefined) {
+        return innerArgs;
+    } // no path → browser handles as inline upload
     // Project root is one level above .reticle/
     const projectRoot = resolve(join(deps.reticleRoot, '..'));
     const uploadRoots = await readUploadRoots(projectRoot, deps.fs, home);
@@ -236,14 +243,17 @@ function synthetic(reason) {
 function performArgsOf(inner) {
     const performArgs = {};
     const value = asString(inner['value']);
-    if (value !== undefined)
+    if (value !== undefined) {
         performArgs.value = value;
+    }
     const text = asString(inner['text']);
-    if (text !== undefined)
+    if (text !== undefined) {
         performArgs.text = text;
+    }
     const key = asString(inner['key']);
-    if (key !== undefined)
+    if (key !== undefined) {
         performArgs.key = key;
+    }
     const modifiers = inner['modifiers'];
     if (Array.isArray(modifiers)) {
         performArgs.modifiers = modifiers.filter((m) => 'string' === typeof m);
@@ -251,9 +261,14 @@ function performArgsOf(inner) {
     // A held key is the whole point of a hold-to-confirm control, and the synthetic path has honoured
     // `holdMs` all along. Not forwarding it made the real keyboard the WEAKER of the two paths: it
     // drove the key instantly and reported a hold that never held.
+    const button = asString(inner['button']);
+    if (button !== undefined) {
+        performArgs.button = button;
+    }
     const holdMs = asNumber(inner['holdMs']);
-    if (holdMs !== undefined)
+    if (holdMs !== undefined) {
         performArgs.holdMs = holdMs;
+    }
     // `keys` and `code` are read but not forwarded: both are routed away by the caller — a multi-key
     // sequence and an explicit physical code have no driver spelling — so carrying them into the
     // provider would only invite it to guess at a gesture the caller did not ask for.
@@ -285,11 +300,13 @@ const ANCHOR_FIELDS = [
  */
 async function pressOnLease(deps, session, ref, inner) {
     const pool = deps.pool;
-    if (pool === undefined || !pool.hasKeyboard(session.id))
+    if (pool === undefined || !pool.hasKeyboard(session.id)) {
         return undefined;
+    }
     const unspellable = unspellablePressReason('', inner);
-    if (unspellable !== undefined)
+    if (unspellable !== undefined) {
         return synthetic(unspellable);
+    }
     // What the focused element is called, from the focus act's own report, so the saved step can
     // find it again: the real keyboard reports no element of its own.
     let anchor = {};
@@ -307,8 +324,9 @@ async function pressOnLease(deps, session, ref, inner) {
         }
     }
     const performed = await pool.pressLease(session.id, performArgsOf(inner));
-    if (performed?.performed !== true)
+    if (performed?.performed !== true) {
         return undefined;
+    }
     return {
         result: {
             ...anchor,
@@ -382,15 +400,17 @@ async function hoverForReal(deps, session, ref, inner, provider) {
     if (box === undefined) {
         throw new Error(HOVER_NEEDS_POINTER_MSG);
     }
-    if (!inView)
+    if (!inView) {
         throw new Error(HOVER_OFF_VIEWPORT_MSG);
+    }
     if (providerReady && provider !== undefined) {
         try {
             const performed = await provider.perform(session.url, ActionType.HOVER, box, {});
             // Hover always has a resolved box, so there is always a center to report: the provider's own
             // reading, or the box's if it reported none. Both are the same point, not a fabricated one.
-            if (performed.performed)
+            if (performed.performed) {
                 return hoverSucceeded(performed.center ?? boxCenter(box), scrolled);
+            }
         }
         catch {
             // A provider error used to fall back to synthetic dispatch. For hover that is a lie.
@@ -428,8 +448,9 @@ export async function tryRealInput(deps, session, ref, action, args) {
     if (provider === undefined) {
         if (action === ActionType.PRESS) {
             const leased = await pressOnLease(deps, session, ref, inner);
-            if (leased !== undefined)
+            if (leased !== undefined) {
                 return leased;
+            }
         }
         // Silent by default: with no provider EVERY action is synthetic, and a reason on all of them is
         // noise on the most-used tool in the product. But an agent that passed native:true asked a
@@ -441,11 +462,13 @@ export async function tryRealInput(deps, session, ref, action, args) {
     // one was asked for, instead of a different gesture being sent. See `unspellablePressReason`.
     if (action === ActionType.PRESS) {
         const unspellable = unspellablePressReason(ref, inner);
-        if (unspellable !== undefined)
+        if (unspellable !== undefined) {
             return synthetic(unspellable);
+        }
     }
-    if (!isRealInputAction(action))
-        return synthetic(InputModeReason.NOT_POINTER); // fill/type stay synthetic
+    if (!isRealInputAction(action)) {
+        return synthetic(InputModeReason.NOT_POINTER);
+    } // fill/type stay synthetic
     // "Don't click, run the code": a click/dblclick runs the occlusion-honest SYNTHETIC path by default
     // even with a provider configured — no coordinate gesture to be intercepted by the HUD or missed
     // off-screen. Opt into a trusted native click with args.native:true (file pickers, clipboard,
@@ -453,6 +476,13 @@ export async function tryRealInput(deps, session, ref, action, args) {
     if ((action === ActionType.CLICK || action === ActionType.DBLCLICK) && !askedForNative) {
         return synthetic(InputModeReason.SYNTHETIC_CLICK_PREFERRED);
     }
+    // The page refuses the same arguments on the synthetic path. A native click must not drop one.
+    if (action === ActionType.CLICK || action === ActionType.DBLCLICK) {
+        const problem = clickInputProblem(action, inner);
+        if (problem !== undefined) {
+            throw new Error(`cannot ${action}: ${problem}`);
+        }
+    }
     // Under version skew CDP is unusable while DOM tools still work (#688). Surface the skew sentence
     // rather than "page not correlated" / a silent provider-error fallback — those send the agent
     // hunting a dead context that is not dead.
@@ -466,15 +496,17 @@ export async function tryRealInput(deps, session, ref, action, args) {
     if (action !== ActionType.PRESS && session.versionSkew !== undefined) {
         throw new Error(session.versionSkew);
     }
-    if (!(await provider.isAvailableFor(session.url)))
+    if (!(await provider.isAvailableFor(session.url))) {
         return synthetic(InputModeReason.PAGE_NOT_CORRELATED);
+    }
     const performArgs = performArgsOf(inner);
     // A document key has no element of its own: skip INSPECT and the box entirely.
     if (action === ActionType.PRESS) {
         try {
             const performed = await provider.perform(session.url, action, PRESS_HAS_NO_BOX, performArgs);
-            if (!performed.performed)
+            if (!performed.performed) {
                 return synthetic(InputModeReason.PROVIDER_DECLINED);
+            }
             // No `center`: a key addresses focus, not a point. The placeholder's zero happened nowhere.
             //
             // `heldMs` IS forwarded, and it is the whole reason this object is not just the three fields
@@ -521,13 +553,15 @@ export async function tryRealInput(deps, session, ref, action, args) {
     let box = asBox(inspected);
     // A box outside the viewport after the reveal is a gesture that would land on nothing. The
     // synthetic path scrolls and hit-tests on its own, so it is the honest answer.
-    if (box === undefined || !source.inView)
+    if (box === undefined || !source.inView) {
         return synthetic(InputModeReason.ELEMENT_NOT_LOCATABLE);
+    }
     let toBox;
     if (action === ActionType.DRAG) {
         const toRef = asString(inner['toRef']);
-        if (toRef === undefined)
+        if (toRef === undefined) {
             return synthetic(InputModeReason.DRAG_TARGET_UNRESOLVED);
+        }
         const target = await inspectRevealed(deps, session, toRef);
         const targetInspected = target.inspected;
         // A drag is judged on BOTH ends: dropping onto "Trash" is destructive however innocent the
@@ -549,12 +583,14 @@ export async function tryRealInput(deps, session, ref, action, args) {
             }
         }
     }
-    if (toBox !== undefined)
+    if (toBox !== undefined) {
         performArgs.toBox = toBox;
+    }
     try {
         const performed = await provider.perform(session.url, action, box, performArgs);
-        if (!performed.performed)
+        if (!performed.performed) {
             return synthetic(InputModeReason.PROVIDER_DECLINED);
+        }
         return {
             result: {
                 performed: true,
@@ -566,8 +602,9 @@ export async function tryRealInput(deps, session, ref, action, args) {
         };
     }
     catch {
-        if (session.versionSkew !== undefined)
+        if (session.versionSkew !== undefined) {
             throw new Error(session.versionSkew);
+        }
         return {
             result: undefined,
             settled: false,
@@ -585,8 +622,9 @@ export async function tryRealInput(deps, session, ref, action, args) {
  * A Proxy, not a copy: the session keeps private state its own methods read.
  */
 export function withLeaseKeyboard(deps, session) {
-    if (deps.realInput !== undefined || deps.pool?.hasKeyboard(session.id) !== true)
+    if (deps.realInput !== undefined || deps.pool?.hasKeyboard(session.id) !== true) {
         return session;
+    }
     const command = async (name, args = {}, timeoutMs) => {
         if (ReticleCommand.ACT === name && ActionType.PRESS === args['action']) {
             const ref = asString(args['ref']) ?? '';
@@ -600,8 +638,9 @@ export function withLeaseKeyboard(deps, session) {
     };
     return new Proxy(session, {
         get(target, key) {
-            if ('command' === key)
+            if ('command' === key) {
                 return command;
+            }
             const value = Reflect.get(target, key, target);
             return 'function' === typeof value
                 ? value.bind(target)

package/docs/packages/react.mdx

@@ -38,9 +38,21 @@ The bridge refuses a connect without the pairing token, also on localhost. `reti
 
 | Export | Signature | What it does |
 | --- | --- | --- |
-| `install` | `(): void` | Idempotent. Registers the `react` adapter and installs the render meter. Call it once, before `connect()` |
+| `install` | `(options?: InstallOptions): void` | Idempotent. Registers the `react` adapter and installs the render meter. Call it once, before `connect()` |
 
-The [Vite plugin](/packages/vite-plugin) injects `install()` and `reticle.connect()` for you, so a Vite user never writes either line.
+#### `InstallOptions`
+
+| Option | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `discoverStores` | `boolean` | `true` | When `true`, `install` walks the React fiber tree after each of the first ten commits and registers stores it finds in Redux `Provider`, TanStack `QueryClientProvider`, and similar context providers. Set to `false` to skip auto-discovery. Use this when your app has more than one context provider and you want only the stores you name with `registerStore` to appear in `reticle_look`. The render meter still runs. |
+
+```ts
+// Only expose the store you control:
+install({ discoverStores: false });
+registerStore('safe', safeStore);
+```
+
+The [Vite plugin](/packages/vite-plugin) injects `install()` and `reticle.connect()` for you. In Vite, pass `discoverStores: false` to the plugin (`reticle({ discoverStores: false })`) to disable auto-discovery. With manual setup, pass `{ discoverStores: false }` to `install()` before calling `reticle.connect()`.
 
 ### Mapping a node to its component
 

package/docs/packages/vite-plugin.mdx

@@ -67,6 +67,7 @@ Plus a dynamic import of your dev module if one exists. It looks for `src/reticl
 | `present` | `boolean` | `true`. Set `false` to hide Reticle's presenter while keeping the agent connection active |
 | `sourceMapping` | `boolean` | `true`. Set `false` to skip the Babel pass |
 | `inject` | `boolean` | `true`. Set `false` to call `connect()` yourself |
+| `discoverStores` | `boolean` | `true`. Set `false` to disable auto-discovery of context stores in React apps (`install({ discoverStores: false })`) |
 | `desktop` | `boolean` | `false`. When `true` the connect passes `allowInProduction: true`, which an Electron or Tauri renderer needs, and a `vite build` in a non-production mode (`--mode development`) is instrumented too. A production-mode build is stubbed like a web build |
 | `captureNetworkBodies` | `boolean` | `false`. Also enabled by `VITE_RETICLE_CAPTURE_BODIES=1` |
 | `networkBodyMaxChars` | `number` | `8192`, clamped to 256 to 262144. Also `VITE_RETICLE_BODY_MAX_CHARS` |

package/docs/skill.md

@@ -3,7 +3,7 @@ name: reticle-docs
 description: Install, instrument and verify this running web app from the inside (DOM, network, routing, console and framework state) instead of screenshots or guessing. Drives one real flow end to end and returns a verdict with the file:line to fix. Use when the user asks to set up or install Reticle, when a user-facing change needs proving before you call it done, when a test passes but the UI is broken, or when the user types /reticle.
 license: Apache-2.0
 metadata:
-  version: 3.8.1
+  version: 3.8.2
   homepage: https://docs.reticle.sh
   repository: https://github.com/reticlehq/reticle
   internal: true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/server",
-  "version": "3.8.1",
+  "version": "3.8.2",
   "mcpName": "io.github.reticlehq/reticle",
   "description": "Reticle CLI, bridge and MCP server: a coding agent drives your running web app from the inside and gets a verdict with evidence, for change verification, access control, accessibility, performance and SEO checks.",
   "type": "module",
@@ -23,11 +23,11 @@
     "@modelcontextprotocol/sdk": "^1.31.0",
     "ws": "^8.21.3",
     "zod": "^4.6.6",
-    "@reticlehq/engine": "3.8.1",
-    "@reticlehq/core": "3.8.1",
-    "@reticlehq/init": "3.8.1",
-    "open-verification": "1.0.0",
-    "@reticlehq/browser": "3.8.1"
+    "@reticlehq/browser": "3.8.2",
+    "@reticlehq/engine": "3.8.2",
+    "open-verification": "1.1.0",
+    "@reticlehq/core": "3.8.2",
+    "@reticlehq/init": "3.8.2"
   },
   "devDependencies": {
     "@types/pngjs": "^6.0.5",
@@ -64,7 +64,7 @@
     "cli"
   ],
   "reticle": {
-    "changelog": "On Windows, the daemon now keeps running when the agent process that started it ends. A collapsed Next.js \"1 Issue\" badge no longer turns every check into unknown. Reticle moves to zod 4 for a high-severity memory advisory. reticle_lease can omit url and lease the project's own dev server. reticle doctor checks that the daemon answers, and streamed SSE response bodies can be captured. Replay waits for a start page that is still loading, a re-acquired lease moves to the page asked for, and a guarded app driven by fast clicks is no longer accused of applying a stale response. Update the SDK in your app as well as the CLI.",
+    "changelog": "3.8.1 could not record a verdict: every run it built or read failed with an Invalid element at key subject error. 3.8.2 fixes it. Update the CLI and the SDK in your app.",
     "breakingChanges": []
   },
   "publishConfig": {