@jackwener/opencli 1.7.13 → 1.7.15

package/dist/src/browser/bridge.js

@@ -54,62 +54,64 @@ export class BrowserBridge {
         const effectiveSeconds = (timeoutSeconds && timeoutSeconds > 0) ? timeoutSeconds : Math.ceil(DAEMON_SPAWN_TIMEOUT / 1000);
         const timeoutMs = effectiveSeconds * 1000;
         const health = await getDaemonHealth({ contextId });
+        // Detect stale daemon before any fast path. A stale daemon can still have
+        // the extension connected, so this cannot live only in the no-extension branch.
+        const daemonVersion = health.status?.daemonVersion;
+        const isStale = !!health.status && (!daemonVersion || daemonVersion !== PKG_VERSION);
+        let staleDaemonReplaced = false;
+        if (isStale) {
+            // Stale daemon — restart it so all browser commands run against the
+            // currently installed package code, not the old daemon binary.
+            const reason = daemonVersion
+                ? `v${daemonVersion} ≠ v${PKG_VERSION}`
+                : `pre-version daemon, CLI is v${PKG_VERSION}`;
+            if (process.env.OPENCLI_VERBOSE || process.stderr.isTTY) {
+                process.stderr.write(`⚠️  Stale daemon detected (${reason}). Restarting...\n`);
+            }
+            const shutdownAccepted = await requestDaemonShutdown();
+            const portReleased = shutdownAccepted && await waitForDaemonStop(3000);
+            if (!portReleased) {
+                // Stale daemon replacement failed — don't blindly spawn on an occupied port
+                throw new BrowserConnectError('Stale daemon could not be replaced', `A stale daemon (${reason}) is running but did not shut down.\n` +
+                    '  Run manually: opencli daemon stop && opencli doctor', 'daemon-not-running');
+            }
+            // Port released — fall through to spawn a fresh daemon
+            staleDaemonReplaced = true;
+        }
         // Fast path: everything ready
-        if (health.state === 'ready')
+        if (!staleDaemonReplaced && health.state === 'ready')
             return;
-        if (health.state === 'profile-required') {
+        if (!staleDaemonReplaced && health.state === 'profile-required') {
             throw new BrowserConnectError('Multiple Browser Bridge profiles are connected', 'Select one with --profile <name>, OPENCLI_PROFILE=<name>, or opencli profile use <name>.\n' +
                 'Run opencli profile list to see connected profiles.', 'profile-required');
         }
-        if (health.state === 'profile-disconnected') {
+        if (!staleDaemonReplaced && health.state === 'profile-disconnected') {
             const label = contextId ?? health.status.contextId ?? 'unknown';
             throw new BrowserConnectError(`Browser profile "${label}" is not connected`, 'Open the matching Chrome profile and make sure the OpenCLI extension is enabled, or choose another profile with opencli profile use <name>.', 'profile-disconnected');
         }
         // Daemon running but no extension
-        if (health.state === 'no-extension') {
-            // Detect stale daemon: version mismatch OR missing daemonVersion (pre-version daemon)
-            const daemonVersion = health.status?.daemonVersion;
-            const isStale = !daemonVersion || daemonVersion !== PKG_VERSION;
-            if (isStale) {
-                // Stale daemon — restart it so extension gets a fresh WebSocket endpoint
-                const reason = daemonVersion
-                    ? `v${daemonVersion} ≠ v${PKG_VERSION}`
-                    : `pre-version daemon, CLI is v${PKG_VERSION}`;
-                if (process.env.OPENCLI_VERBOSE || process.stderr.isTTY) {
-                    process.stderr.write(`⚠️  Stale daemon detected (${reason}). Restarting...\n`);
-                }
-                const shutdownAccepted = await requestDaemonShutdown();
-                const portReleased = shutdownAccepted && await waitForDaemonStop(3000);
-                if (!portReleased) {
-                    // Stale daemon replacement failed — don't blindly spawn on an occupied port
-                    throw new BrowserConnectError('Stale daemon could not be replaced', `A stale daemon (${reason}) is running but did not shut down.\n` +
-                        '  Run manually: opencli daemon stop && opencli doctor', 'daemon-not-running');
-                }
-                // Port released — fall through to spawn a fresh daemon
+        if (!staleDaemonReplaced && health.state === 'no-extension') {
+            // Same version — wait for extension to connect
+            if (process.env.OPENCLI_VERBOSE || process.stderr.isTTY) {
+                process.stderr.write('⏳ Waiting for Chrome/Chromium extension to connect...\n');
+                process.stderr.write('   Make sure Chrome or Chromium is open and the OpenCLI extension is enabled.\n');
             }
-            else {
-                // Same version — wait for extension to connect
-                if (process.env.OPENCLI_VERBOSE || process.stderr.isTTY) {
-                    process.stderr.write('⏳ Waiting for Chrome/Chromium extension to connect...\n');
-                    process.stderr.write('   Make sure Chrome or Chromium is open and the OpenCLI extension is enabled.\n');
-                }
-                if (await this._pollUntilReady(timeoutMs, contextId))
-                    return;
-                const finalHealth = await getDaemonHealth({ contextId });
-                if (finalHealth.state === 'profile-required') {
-                    throw new BrowserConnectError('Multiple Browser Bridge profiles are connected', 'Select one with --profile <name>, OPENCLI_PROFILE=<name>, or opencli profile use <name>.\n' +
-                        'Run opencli profile list to see connected profiles.', 'profile-required');
-                }
-                if (finalHealth.state === 'profile-disconnected') {
-                    const label = contextId ?? finalHealth.status.contextId ?? 'unknown';
-                    throw new BrowserConnectError(`Browser profile "${label}" is not connected`, 'Open the matching Chrome profile and make sure the OpenCLI extension is enabled, or choose another profile with opencli profile use <name>.', 'profile-disconnected');
-                }
-                throw new BrowserConnectError('Browser Bridge extension not connected', 'Make sure Chrome/Chromium is open and the extension is enabled.\n' +
-                    'If the extension is installed, try: opencli daemon stop && opencli doctor\n' +
-                    'If not installed:\n' +
-                    '  1. Download: https://github.com/jackwener/opencli/releases\n' +
-                    '  2. Open chrome://extensions → Developer Mode → Load unpacked', 'extension-not-connected');
+            if (await this._pollUntilReady(timeoutMs, contextId))
+                return;
+            const finalHealth = await getDaemonHealth({ contextId });
+            if (finalHealth.state === 'profile-required') {
+                throw new BrowserConnectError('Multiple Browser Bridge profiles are connected', 'Select one with --profile <name>, OPENCLI_PROFILE=<name>, or opencli profile use <name>.\n' +
+                    'Run opencli profile list to see connected profiles.', 'profile-required');
             }
+            if (finalHealth.state === 'profile-disconnected') {
+                const label = contextId ?? finalHealth.status.contextId ?? 'unknown';
+                throw new BrowserConnectError(`Browser profile "${label}" is not connected`, 'Open the matching Chrome profile and make sure the OpenCLI extension is enabled, or choose another profile with opencli profile use <name>.', 'profile-disconnected');
+            }
+            throw new BrowserConnectError('Browser Bridge extension not connected', 'Make sure Chrome/Chromium is open and the extension is enabled.\n' +
+                'If the extension is installed, try: opencli daemon stop && opencli doctor\n' +
+                'If not installed:\n' +
+                '  1. Download: https://github.com/jackwener/opencli/releases\n' +
+                '  2. Open chrome://extensions → Developer Mode → Load unpacked', 'extension-not-connected');
         }
         // No daemon — spawn one
         if (process.env.OPENCLI_VERBOSE || process.stderr.isTTY) {

package/dist/src/browser/cdp-click-fixture.test.d.ts

@@ -0,0 +1 @@
+export {};

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.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,6 +32,8 @@ 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 */

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.
@@ -53,6 +53,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

@@ -246,6 +246,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 +368,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;