@jackwener/opencli 1.7.14 → 1.7.16

package/dist/src/browser/cdp-click-fixture.test.js

@@ -0,0 +1,87 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { JSDOM } from 'jsdom';
+function installDom(html) {
+    const dom = new JSDOM(html, { pretendToBeVisual: true });
+    globalThis.window = dom.window;
+    globalThis.document = dom.window.document;
+    globalThis.Event = dom.window.Event;
+    globalThis.MouseEvent = dom.window.MouseEvent;
+    return dom.window.document;
+}
+function dispatchNativeMouseSequence(target) {
+    for (const type of ['mousemove', 'pointerdown', 'mousedown', 'mouseup', 'pointerup', 'click']) {
+        target.dispatchEvent(new MouseEvent(type, { bubbles: true, cancelable: true, view: window }));
+    }
+}
+describe('CDP-primary click dropdown fixtures', () => {
+    afterEach(() => {
+        Reflect.deleteProperty(globalThis, 'window');
+        Reflect.deleteProperty(globalThis, 'document');
+    });
+    it('captures the Radix/shadcn class of dropdowns that open on pointerdown and select on pointerup', () => {
+        const document = installDom(`
+      <button id="trigger" role="combobox" aria-expanded="false">Category</button>
+      <div id="portal-root"></div>
+      <output id="value"></output>
+    `);
+        const trigger = document.querySelector('#trigger');
+        const portal = document.querySelector('#portal-root');
+        const value = document.querySelector('#value');
+        trigger.addEventListener('pointerdown', () => {
+            trigger.setAttribute('aria-expanded', 'true');
+            portal.innerHTML = `
+        <div role="listbox">
+          <div id="meals" role="option">Meals</div>
+        </div>
+      `;
+            portal.querySelector('#meals').addEventListener('pointerup', () => {
+                value.textContent = 'Meals';
+                trigger.textContent = 'Meals';
+                trigger.setAttribute('aria-expanded', 'false');
+            });
+        });
+        // Baseline: DOM el.click() dispatches click only. This is the old OpenCLI
+        // failure mode: the command reports success but the dropdown never opens.
+        trigger.click();
+        expect(trigger.getAttribute('aria-expanded')).toBe('false');
+        expect(portal.querySelector('[role="option"]')).toBeNull();
+        expect(value.textContent).toBe('');
+        // CDP-style mouse input opens the portal and can commit the option.
+        dispatchNativeMouseSequence(trigger);
+        const option = portal.querySelector('#meals');
+        expect(trigger.getAttribute('aria-expanded')).toBe('true');
+        dispatchNativeMouseSequence(option);
+        expect(value.textContent).toBe('Meals');
+        expect(trigger.textContent).toBe('Meals');
+    });
+    it('captures the MUI autocomplete class that opens on mousedown and commits on mousedown in a popper', () => {
+        const document = installDom(`
+      <label for="category">Category</label>
+      <input id="category" role="combobox" value="" />
+      <div id="mui-popper"></div>
+      <output id="value"></output>
+    `);
+        const input = document.querySelector('#category');
+        const popper = document.querySelector('#mui-popper');
+        const value = document.querySelector('#value');
+        input.addEventListener('mousedown', () => {
+            popper.innerHTML = `
+        <ul role="listbox">
+          <li id="travel" role="option">Travel</li>
+        </ul>
+      `;
+            popper.querySelector('#travel').addEventListener('mousedown', () => {
+                input.value = 'Travel';
+                value.textContent = 'Travel';
+            });
+        });
+        input.click();
+        expect(popper.querySelector('[role="option"]')).toBeNull();
+        expect(input.value).toBe('');
+        dispatchNativeMouseSequence(input);
+        const option = popper.querySelector('#travel');
+        dispatchNativeMouseSequence(option);
+        expect(input.value).toBe('Travel');
+        expect(value.textContent).toBe('Travel');
+    });
+});

package/dist/src/browser/cdp.d.ts

@@ -27,6 +27,7 @@ export declare class CDPBridge implements IBrowserFactory {
         cdpEndpoint?: string;
         contextId?: string;
         idleTimeout?: number;
+        windowMode?: 'foreground' | 'background';
     }): Promise<IPage>;
     close(): Promise<void>;
     send(method: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<unknown>;

package/dist/src/browser/cdp.js

@@ -369,6 +369,11 @@ class CDPPage extends BasePage {
         });
     }
     async nativeClick(x, y) {
+        await this.cdp('Input.dispatchMouseEvent', {
+            type: 'mouseMoved',
+            x,
+            y,
+        });
         await this.cdp('Input.dispatchMouseEvent', {
             type: 'mousePressed',
             x,

package/dist/src/browser/cdp.test.js

@@ -69,6 +69,7 @@ describe('CDPBridge cookies', () => {
             ['Input.insertText', { text: 'hello' }],
             ['Input.dispatchKeyEvent', { type: 'keyDown', key: 'a', modifiers: 2 }],
             ['Input.dispatchKeyEvent', { type: 'keyUp', key: 'a', modifiers: 2 }],
+            ['Input.dispatchMouseEvent', { type: 'mouseMoved', x: 10, y: 20 }],
             ['Input.dispatchMouseEvent', { type: 'mousePressed', x: 10, y: 20, button: 'left', clickCount: 1 }],
             ['Input.dispatchMouseEvent', { type: 'mouseReleased', x: 10, y: 20, button: 'left', clickCount: 1 }],
             ['Page.handleJavaScriptDialog', { accept: true, promptText: 'ok' }],

package/dist/src/browser/daemon-client.d.ts

@@ -6,7 +6,7 @@
 import type { BrowserSessionInfo } from '../types.js';
 export interface DaemonCommand {
     id: string;
-    action: 'exec' | 'navigate' | 'tabs' | 'cookies' | 'screenshot' | 'close-window' | 'sessions' | 'set-file-input' | 'insert-text' | 'bind' | 'network-capture-start' | 'network-capture-read' | 'cdp' | 'frames';
+    action: 'exec' | 'navigate' | 'tabs' | 'cookies' | 'screenshot' | 'close-window' | 'sessions' | 'set-file-input' | 'insert-text' | 'bind' | 'network-capture-start' | 'network-capture-read' | 'wait-download' | 'cdp' | 'frames';
     /** Target page identity (targetId). Cross-layer contract with the extension. */
     page?: string;
     code?: string;
@@ -32,10 +32,12 @@ export interface DaemonCommand {
     text?: string;
     /** URL substring filter pattern for network capture */
     pattern?: string;
+    /** Download wait timeout in milliseconds */
+    timeoutMs?: number;
     cdpMethod?: string;
     cdpParams?: Record<string, unknown>;
-    /** When true, the owned automation container is created in the foreground */
-    windowFocused?: boolean;
+    /** Window foreground/background policy for owned Browser Bridge containers. */
+    windowMode?: 'foreground' | 'background';
     /** Custom idle timeout in seconds for this workspace session. Overrides the default. */
     idleTimeout?: number;
     /** Explicitly allow navigation inside a borrowed bound tab. */

package/dist/src/browser/daemon-client.js

@@ -89,10 +89,13 @@ async function sendCommandRaw(action, params) {
     const maxRetries = 4;
     for (let attempt = 1; attempt <= maxRetries; attempt++) {
         const id = generateId();
-        const wf = process.env.OPENCLI_WINDOW_FOCUSED;
-        const windowFocused = (wf === '1' || wf === 'true') ? true : undefined;
+        const rawWindowMode = process.env.OPENCLI_WINDOW;
+        const envWindowMode = rawWindowMode === 'foreground' || rawWindowMode === 'background'
+            ? rawWindowMode
+            : undefined;
         const contextId = params.contextId ?? resolveProfileContextId();
-        const command = { id, action, ...params, ...(contextId && { contextId }), ...(windowFocused && { windowFocused }) };
+        const windowMode = params.windowMode ?? envWindowMode;
+        const command = { id, action, ...params, ...(contextId && { contextId }), ...(windowMode && { windowMode }) };
         try {
             const res = await requestDaemon('/command', {
                 method: 'POST',

package/dist/src/browser/daemon-client.test.js

@@ -144,6 +144,16 @@ describe('daemon-client', () => {
         const body = JSON.parse(String(vi.mocked(fetch).mock.calls[0][1]?.body));
         expect(body.contextId).toBe('work');
     });
+    it('sendCommand uses explicit windowMode before OPENCLI_WINDOW env fallback', async () => {
+        vi.stubEnv('OPENCLI_WINDOW', 'foreground');
+        vi.mocked(fetch).mockResolvedValue({
+            status: 200,
+            json: () => Promise.resolve({ id: 'server', ok: true, data: 'ok' }),
+        });
+        await sendCommand('exec', { code: '1 + 1', windowMode: 'background' });
+        const body = JSON.parse(String(vi.mocked(fetch).mock.calls[0][1]?.body));
+        expect(body.windowMode).toBe('background');
+    });
     it('sendCommand retries with a new id when daemon reports a duplicate pending id', async () => {
         vi.spyOn(Date, 'now').mockReturnValue(1_763_000_000_123);
         const fetchMock = vi.mocked(fetch);

package/dist/src/browser/find.d.ts

@@ -57,7 +57,7 @@ export interface FindResult {
 }
 export interface FindError {
     error: {
-        code: 'invalid_selector' | 'selector_not_found';
+        code: 'invalid_selector' | 'selector_not_found' | 'semantic_not_found';
         message: string;
         hint?: string;
     };
@@ -68,9 +68,17 @@ export interface FindOptions {
     /** Max chars of trimmed text per entry. Default 120. */
     textMax?: number;
 }
+export interface SemanticFindOptions extends FindOptions {
+    role?: string;
+    name?: string;
+    label?: string;
+    text?: string;
+    testid?: string;
+}
 /**
  * Build the browser-side JS that performs the CSS query and emits the
  * FindResult (or FindError) envelope. Evaluated inside `page.evaluate`.
  */
 export declare function buildFindJs(selector: string, opts?: FindOptions): string;
+export declare function buildSemanticFindJs(opts: SemanticFindOptions): string;
 export declare function isFindError(result: unknown): result is FindError;

package/dist/src/browser/find.js

@@ -174,6 +174,225 @@ export function buildFindJs(selector, opts = {}) {
     })()
   `;
 }
+export function buildSemanticFindJs(opts) {
+    const criteria = JSON.stringify({
+        role: opts.role ?? '',
+        name: opts.name ?? '',
+        label: opts.label ?? '',
+        text: opts.text ?? '',
+        testid: opts.testid ?? '',
+    });
+    const limit = opts.limit ?? 50;
+    const textMax = opts.textMax ?? 120;
+    const whitelist = JSON.stringify(FIND_ATTR_WHITELIST);
+    return `
+    (() => {
+      const CRITERIA = ${criteria};
+      const LIMIT = ${limit};
+      const TEXT_MAX = ${textMax};
+      const ATTR_WHITELIST = ${whitelist};
+
+      ${COMPOUND_INFO_JS}
+
+      function normalize(value) {
+        return String(value || '').replace(/\\s+/g, ' ').trim().toLowerCase();
+      }
+
+      function includesNeedle(value, needle) {
+        const n = normalize(needle);
+        if (!n) return true;
+        return normalize(value).includes(n);
+      }
+
+      function nativeRole(el) {
+        const explicit = el.getAttribute('role');
+        if (explicit) return explicit;
+        const tag = el.tagName.toLowerCase();
+        const type = (el.getAttribute('type') || '').toLowerCase();
+        if (tag === 'button') return 'button';
+        if (tag === 'a' && el.getAttribute('href')) return 'link';
+        if (tag === 'textarea') return 'textbox';
+        if (tag === 'select') return 'combobox';
+        if (tag === 'option') return 'option';
+        if (tag === 'input') {
+          if (type === 'button' || type === 'submit' || type === 'reset') return 'button';
+          if (type === 'checkbox') return 'checkbox';
+          if (type === 'radio') return 'radio';
+          if (type === 'range') return 'slider';
+          if (type === 'search') return 'searchbox';
+          return 'textbox';
+        }
+        return '';
+      }
+
+      function labelText(el) {
+        const parts = [];
+        function cssEscape(value) {
+          try {
+            if (window.CSS && typeof window.CSS.escape === 'function') return window.CSS.escape(value);
+          } catch (_) {}
+          return String(value).replace(/["\\\\]/g, '\\\\$&');
+        }
+        if (el.id) {
+          try {
+            const label = document.querySelector('label[for="' + cssEscape(el.id) + '"]');
+            if (label) parts.push(label.textContent || '');
+          } catch (_) {}
+        }
+        const parentLabel = el.closest?.('label');
+        if (parentLabel) parts.push(parentLabel.textContent || '');
+        return parts.join(' ');
+      }
+
+      function byIdText(ids) {
+        if (!ids) return '';
+        const parts = [];
+        for (const id of String(ids).split(/\\s+/)) {
+          if (!id) continue;
+          try {
+            const el = document.getElementById(id);
+            if (el) parts.push(el.textContent || '');
+          } catch (_) {}
+        }
+        return parts.join(' ');
+      }
+
+      function accessibleName(el) {
+        return [
+          el.getAttribute('aria-label') || '',
+          byIdText(el.getAttribute('aria-labelledby')),
+          labelText(el),
+          el.getAttribute('alt') || '',
+          el.getAttribute('title') || '',
+          el.getAttribute('placeholder') || '',
+          el.getAttribute('value') || '',
+          el.textContent || '',
+        ].filter(Boolean).join(' ');
+      }
+
+      function pickAttrs(el) {
+        const out = {};
+        for (const key of ATTR_WHITELIST) {
+          const v = el.getAttribute(key);
+          if (v != null && v !== '') out[key] = v;
+        }
+        return out;
+      }
+
+      function isVisible(el) {
+        const rect = el.getBoundingClientRect();
+        if (rect.width === 0 && rect.height === 0) return false;
+        try {
+          const style = getComputedStyle(el);
+          if (style.display === 'none' || style.visibility === 'hidden') return false;
+          if (parseFloat(style.opacity || '1') === 0) return false;
+        } catch (_) {}
+        return true;
+      }
+
+      function fingerprintOf(el) {
+        return {
+          tag: el.tagName.toLowerCase(),
+          role: el.getAttribute('role') || '',
+          text: (el.textContent || '').trim().slice(0, 30),
+          ariaLabel: el.getAttribute('aria-label') || '',
+          id: el.id || '',
+          testId: el.getAttribute('data-testid') || el.getAttribute('data-test') || '',
+        };
+      }
+
+      function matches(el) {
+        const role = nativeRole(el);
+        const name = accessibleName(el);
+        const label = labelText(el);
+        const text = el.textContent || '';
+        const testid = el.getAttribute('data-testid') || el.getAttribute('data-test') || el.getAttribute('test-id') || '';
+        if (CRITERIA.role && normalize(role) !== normalize(CRITERIA.role)) return false;
+        if (CRITERIA.name && !includesNeedle(name, CRITERIA.name)) return false;
+        if (CRITERIA.label && !includesNeedle(label, CRITERIA.label)) return false;
+        if (CRITERIA.text && !includesNeedle(text, CRITERIA.text)) return false;
+        if (CRITERIA.testid && !includesNeedle(testid, CRITERIA.testid)) return false;
+        return true;
+      }
+
+      const candidates = Array.from(document.querySelectorAll([
+        'a[href]',
+        'button',
+        'input',
+        'textarea',
+        'select',
+        'option',
+        '[role]',
+        '[aria-label]',
+        '[aria-labelledby]',
+        '[data-testid]',
+        '[data-test]',
+        '[test-id]',
+        'label',
+        '[contenteditable="true"]',
+      ].join(',')));
+      const matchesList = candidates.filter(matches);
+
+      if (matchesList.length === 0) {
+        return {
+          error: {
+            code: 'semantic_not_found',
+            message: 'Semantic locator matched 0 elements',
+            hint: 'Try browser state, --source ax, or relax --role/--name/--label/--text/--testid.',
+          },
+        };
+      }
+
+      const identity = (window.__opencli_ref_identity = window.__opencli_ref_identity || {});
+      let maxRef = 0;
+      for (const k in identity) {
+        const n = parseInt(k, 10);
+        if (!isNaN(n) && n > maxRef) maxRef = n;
+      }
+      try {
+        const tagged = document.querySelectorAll('[data-opencli-ref]');
+        for (let t = 0; t < tagged.length; t++) {
+          const v = tagged[t].getAttribute('data-opencli-ref');
+          const n = v != null && /^\\d+$/.test(v) ? parseInt(v, 10) : NaN;
+          if (!isNaN(n) && n > maxRef) maxRef = n;
+        }
+      } catch (_) {}
+
+      const take = Math.min(matchesList.length, LIMIT);
+      const entries = [];
+      for (let i = 0; i < take; i++) {
+        const el = matchesList[i];
+        const refAttr = el.getAttribute('data-opencli-ref');
+        let refNum = refAttr != null && /^\\d+$/.test(refAttr) ? parseInt(refAttr, 10) : null;
+        if (refNum === null) {
+          refNum = ++maxRef;
+          try { el.setAttribute('data-opencli-ref', '' + refNum); } catch (_) {}
+          identity['' + refNum] = fingerprintOf(el);
+        } else if (!identity['' + refNum]) {
+          identity['' + refNum] = fingerprintOf(el);
+        }
+        const text = (el.textContent || '').trim();
+        const entry = {
+          nth: i,
+          ref: refNum,
+          tag: el.tagName.toLowerCase(),
+          role: nativeRole(el),
+          text: text.length > TEXT_MAX ? text.slice(0, TEXT_MAX) : text,
+          attrs: pickAttrs(el),
+          visible: isVisible(el),
+        };
+        const compound = compoundInfoOf(el);
+        if (compound) entry.compound = compound;
+        entries.push(entry);
+      }
+
+      return {
+        matches_n: matchesList.length,
+        entries,
+      };
+    })()
+  `;
+}
 export function isFindError(result) {
     return !!result && typeof result === 'object' && 'error' in result;
 }

package/dist/src/browser/find.test.js

@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest';
-import { buildFindJs, FIND_ATTR_WHITELIST, isFindError } from './find.js';
+import { JSDOM } from 'jsdom';
+import { buildFindJs, buildSemanticFindJs, FIND_ATTR_WHITELIST, isFindError } from './find.js';
 /**
  * These tests validate the shape and options of the generated JS string
  * (no DOM available in the default vitest unit env). Runtime behavior of
@@ -118,3 +119,62 @@ describe('isFindError', () => {
         expect(isFindError('string')).toBe(false);
     });
 });
+describe('buildSemanticFindJs', () => {
+    function runSemanticFind(html, opts) {
+        const dom = new JSDOM(html, { runScripts: 'outside-only' });
+        return {
+            dom,
+            result: dom.window.eval(buildSemanticFindJs(opts)),
+        };
+    }
+    it('produces syntactically valid JS and embeds semantic criteria safely', () => {
+        const js = buildSemanticFindJs({ role: 'button', name: 'Save "now"', testid: 'submit' });
+        expect(() => new Function(`return (${js});`)).not.toThrow();
+        expect(js).toContain(JSON.stringify({
+            role: 'button',
+            name: 'Save "now"',
+            label: '',
+            text: '',
+            testid: 'submit',
+        }));
+    });
+    it('matches native roles, accessible name, labels, text, and test ids', () => {
+        const js = buildSemanticFindJs({ role: 'button', name: 'Save', label: 'Category', text: 'Travel', testid: 'category' });
+        expect(js).toContain('function nativeRole(el)');
+        expect(js).toContain('function accessibleName(el)');
+        expect(js).toContain('function labelText(el)');
+        expect(js).toContain('CRITERIA.role');
+        expect(js).toContain('CRITERIA.name');
+        expect(js).toContain('CRITERIA.label');
+        expect(js).toContain('CRITERIA.text');
+        expect(js).toContain('CRITERIA.testid');
+    });
+    it('allocates refs exactly like CSS find so downstream actions can click them', () => {
+        const js = buildSemanticFindJs({ role: 'button', name: 'Save' });
+        expect(js).toContain("el.setAttribute('data-opencli-ref'");
+        expect(js).toContain('__opencli_ref_identity');
+        expect(js).toContain("identity['' + refNum] = fingerprintOf(el)");
+        expect(js).toContain("document.querySelectorAll('[data-opencli-ref]')");
+    });
+    it('executes semantic role/name/testid matching and allocates a clickable ref', () => {
+        const { dom, result } = runSemanticFind('<button aria-label="Save expense" data-testid="save-button">Ignored copy</button>', { role: 'button', name: 'Save', testid: 'save' });
+        expect(result).toMatchObject({
+            matches_n: 1,
+            entries: [
+                { nth: 0, ref: 1, tag: 'button', role: 'button', attrs: { 'aria-label': 'Save expense', 'data-testid': 'save-button' } },
+            ],
+        });
+        const button = dom.window.document.querySelector('button');
+        expect(button.getAttribute('data-opencli-ref')).toBe('1');
+        expect(dom.window.__opencli_ref_identity['1']).toMatchObject({ tag: 'button', ariaLabel: 'Save expense' });
+    });
+    it('matches associated labels and placeholders for form controls', () => {
+        const { result } = runSemanticFind('<label for="category">Category</label><input id="category" placeholder="Expense category" value="Travel" />', { role: 'textbox', label: 'Category', name: 'Expense category' });
+        expect(result).toMatchObject({
+            matches_n: 1,
+            entries: [
+                { nth: 0, ref: 1, tag: 'input', role: 'textbox' },
+            ],
+        });
+    });
+});

package/dist/src/browser/page.d.ts

@@ -8,7 +8,7 @@
  * by the navigate action and pass it to all subsequent commands. This ensures
  * page-scoped operations target the correct page without guessing.
  */
-import type { BrowserCookie, ScreenshotOptions } from '../types.js';
+import type { BrowserCookie, BrowserDownloadWaitResult, ScreenshotOptions } from '../types.js';
 import { BasePage } from './base-page.js';
 /**
  * Page — implements IPage by talking to the daemon via HTTP.
@@ -16,8 +16,9 @@ import { BasePage } from './base-page.js';
 export declare class Page extends BasePage {
     private readonly workspace;
     readonly contextId?: string | undefined;
+    private readonly windowMode?;
     private readonly _idleTimeout;
-    constructor(workspace?: string, idleTimeout?: number, contextId?: string | undefined);
+    constructor(workspace?: string, idleTimeout?: number, contextId?: string | undefined, windowMode?: "foreground" | "background" | undefined);
     /** Active page identity (targetId), set after navigate and used in all subsequent commands */
     private _page;
     private _networkCaptureUnsupported;
@@ -53,6 +54,7 @@ export declare class Page extends BasePage {
     screenshot(options?: ScreenshotOptions): Promise<string>;
     startNetworkCapture(pattern?: string): Promise<boolean>;
     readNetworkCapture(): Promise<unknown[]>;
+    waitForDownload(pattern?: string, timeoutMs?: number): Promise<BrowserDownloadWaitResult>;
     /**
      * Set local file paths on a file input element via CDP DOM.setFileInputFiles.
      * Chrome reads the files directly from the local filesystem, avoiding the

package/dist/src/browser/page.js

@@ -28,11 +28,13 @@ function isUnsupportedNetworkCaptureError(err) {
 export class Page extends BasePage {
     workspace;
     contextId;
+    windowMode;
     _idleTimeout;
-    constructor(workspace = 'default', idleTimeout, contextId) {
+    constructor(workspace = 'default', idleTimeout, contextId, windowMode) {
         super();
         this.workspace = workspace;
         this.contextId = contextId;
+        this.windowMode = windowMode;
         this._idleTimeout = idleTimeout;
     }
     /** Active page identity (targetId), set after navigate and used in all subsequent commands */
@@ -45,6 +47,7 @@ export class Page extends BasePage {
             workspace: this.workspace,
             ...(this.contextId && { contextId: this.contextId }),
             ...(this._idleTimeout != null && { idleTimeout: this._idleTimeout }),
+            ...(this.windowMode && { windowMode: this.windowMode }),
         };
     }
     /** Helper: spread workspace + page identity into command params */
@@ -54,6 +57,7 @@ export class Page extends BasePage {
             ...(this.contextId && { contextId: this.contextId }),
             ...(this._page !== undefined && { page: this._page }),
             ...(this._idleTimeout != null && { idleTimeout: this._idleTimeout }),
+            ...(this.windowMode && { windowMode: this.windowMode }),
         };
     }
     async goto(url, options) {
@@ -246,6 +250,14 @@ export class Page extends BasePage {
             return [];
         }
     }
+    async waitForDownload(pattern = '', timeoutMs = 30_000) {
+        const result = await sendCommand('wait-download', {
+            pattern,
+            timeoutMs,
+            ...this._cmdOpts(),
+        });
+        return result;
+    }
     /**
      * Set local file paths on a file input element via CDP DOM.setFileInputFiles.
      * Chrome reads the files directly from the local filesystem, avoiding the
@@ -360,6 +372,11 @@ export class Page extends BasePage {
     `);
     }
     async nativeClick(x, y) {
+        await this.cdp('Input.dispatchMouseEvent', {
+            type: 'mouseMoved',
+            x,
+            y,
+        });
         await this.cdp('Input.dispatchMouseEvent', {
             type: 'mousePressed',
             x, y,

package/dist/src/browser/page.test.js

@@ -102,6 +102,34 @@ describe('Page network capture compatibility', () => {
         expect(warnMock).toHaveBeenCalledTimes(1);
     });
 });
+describe('Page download waits', () => {
+    beforeEach(() => {
+        sendCommandMock.mockReset();
+        sendCommandFullMock.mockReset();
+        warnMock.mockReset();
+    });
+    it('sends wait-download through the daemon with workspace and timeout', async () => {
+        sendCommandMock.mockResolvedValueOnce({
+            downloaded: true,
+            filename: '/tmp/receipt.pdf',
+            state: 'complete',
+            elapsedMs: 5,
+        });
+        const page = new Page('site:mercury');
+        const result = await page.waitForDownload('receipt', 1234);
+        expect(result).toEqual({
+            downloaded: true,
+            filename: '/tmp/receipt.pdf',
+            state: 'complete',
+            elapsedMs: 5,
+        });
+        expect(sendCommandMock).toHaveBeenCalledWith('wait-download', expect.objectContaining({
+            workspace: 'site:mercury',
+            pattern: 'receipt',
+            timeoutMs: 1234,
+        }));
+    });
+});
 describe('Page CDP helpers', () => {
     beforeEach(() => {
         sendCommandMock.mockReset();

package/dist/src/browser/target-errors.d.ts

@@ -16,8 +16,10 @@
  *   - selector_ambiguous:     >1 matches for a write op without --nth
  *   - selector_nth_out_of_range: --nth beyond matches_n
  *   - not_editable:           target exists but cannot accept text input
+ *   - not_checkable:          target exists but cannot be checked/unchecked
+ *   - not_file_input:         target exists but is not a usable file input
  */
-export type TargetErrorCode = 'not_found' | 'stale_ref' | 'invalid_selector' | 'selector_not_found' | 'selector_ambiguous' | 'selector_nth_out_of_range' | 'not_editable';
+export type TargetErrorCode = 'not_found' | 'stale_ref' | 'invalid_selector' | 'selector_not_found' | 'selector_ambiguous' | 'selector_nth_out_of_range' | 'not_editable' | 'not_checkable' | 'not_file_input';
 export interface TargetErrorInfo {
     code: TargetErrorCode;
     message: string;

package/dist/src/browser/target-errors.js

@@ -16,6 +16,8 @@
  *   - selector_ambiguous:     >1 matches for a write op without --nth
  *   - selector_nth_out_of_range: --nth beyond matches_n
  *   - not_editable:           target exists but cannot accept text input
+ *   - not_checkable:          target exists but cannot be checked/unchecked
+ *   - not_file_input:         target exists but is not a usable file input
  */
 export class TargetError extends Error {
     code;