@jackwener/opencli 1.7.3 → 1.7.4

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

@@ -18,6 +18,8 @@ export declare class Page extends BasePage {
     constructor(workspace?: string);
     /** Active page identity (targetId), set after navigate and used in all subsequent commands */
     private _page;
+    private _networkCaptureUnsupported;
+    private _networkCaptureWarned;
     /** Helper: spread workspace into command params */
     private _wsOpt;
     /** Helper: spread workspace + page identity into command params */
@@ -30,6 +32,7 @@ export declare class Page extends BasePage {
     getActivePage(): string | undefined;
     /** @deprecated Use getActivePage() instead */
     getActiveTabId(): number | undefined;
+    private _markUnsupportedNetworkCapture;
     evaluate(js: string): Promise<unknown>;
     getCookies(opts?: {
         domain?: string;
@@ -43,7 +46,7 @@ export declare class Page extends BasePage {
      * Capture a screenshot via CDP Page.captureScreenshot.
      */
     screenshot(options?: ScreenshotOptions): Promise<string>;
-    startNetworkCapture(pattern?: string): Promise<void>;
+    startNetworkCapture(pattern?: string): Promise<boolean>;
     readNetworkCapture(): Promise<unknown[]>;
     /**
      * Set local file paths on a file input element via CDP DOM.setFileInputFiles.

package/dist/src/browser/page.js

@@ -15,6 +15,13 @@ import { generateStealthJs } from './stealth.js';
 import { waitForDomStableJs } from './dom-helpers.js';
 import { BasePage } from './base-page.js';
 import { classifyBrowserError } from './errors.js';
+import { log } from '../logger.js';
+function isUnsupportedNetworkCaptureError(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const normalized = message.toLowerCase();
+    return (normalized.includes('unknown action') && normalized.includes('network-capture'))
+        || (normalized.includes('network capture') && normalized.includes('not supported'));
+}
 /**
  * Page — implements IPage by talking to the daemon via HTTP.
  */
@@ -26,6 +33,8 @@ export class Page extends BasePage {
     }
     /** Active page identity (targetId), set after navigate and used in all subsequent commands */
     _page;
+    _networkCaptureUnsupported = false;
+    _networkCaptureWarned = false;
     /** Helper: spread workspace into command params */
     _wsOpt() {
         return { workspace: this.workspace };
@@ -97,6 +106,14 @@ export class Page extends BasePage {
     getActiveTabId() {
         return undefined;
     }
+    _markUnsupportedNetworkCapture() {
+        this._networkCaptureUnsupported = true;
+        if (this._networkCaptureWarned)
+            return;
+        this._networkCaptureWarned = true;
+        log.warn('Browser Bridge extension does not support network capture; continuing without it. ' +
+            'Explore output may miss API endpoints until you reload or reinstall the extension.');
+    }
     async evaluate(js) {
         const code = wrapForEval(js);
         try {
@@ -125,6 +142,8 @@ export class Page extends BasePage {
         finally {
             this._page = undefined;
             this._lastUrl = null;
+            this._networkCaptureUnsupported = false;
+            this._networkCaptureWarned = false;
         }
     }
     async tabs() {
@@ -152,16 +171,37 @@ export class Page extends BasePage {
         return base64;
     }
     async startNetworkCapture(pattern = '') {
-        await sendCommand('network-capture-start', {
-            pattern,
-            ...this._cmdOpts(),
-        });
+        if (this._networkCaptureUnsupported)
+            return false;
+        try {
+            await sendCommand('network-capture-start', {
+                pattern,
+                ...this._cmdOpts(),
+            });
+            return true;
+        }
+        catch (err) {
+            if (!isUnsupportedNetworkCaptureError(err))
+                throw err;
+            this._markUnsupportedNetworkCapture();
+            return false;
+        }
     }
     async readNetworkCapture() {
-        const result = await sendCommand('network-capture-read', {
-            ...this._cmdOpts(),
-        });
-        return Array.isArray(result) ? result : [];
+        if (this._networkCaptureUnsupported)
+            return [];
+        try {
+            const result = await sendCommand('network-capture-read', {
+                ...this._cmdOpts(),
+            });
+            return Array.isArray(result) ? result : [];
+        }
+        catch (err) {
+            if (!isUnsupportedNetworkCaptureError(err))
+                throw err;
+            this._markUnsupportedNetworkCapture();
+            return [];
+        }
     }
     /**
      * Set local file paths on a file input element via CDP DOM.setFileInputFiles.

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

@@ -1,14 +1,26 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
-const { sendCommandMock } = vi.hoisted(() => ({
+const { sendCommandMock, sendCommandFullMock } = vi.hoisted(() => ({
     sendCommandMock: vi.fn(),
+    sendCommandFullMock: vi.fn(),
+}));
+const { warnMock } = vi.hoisted(() => ({
+    warnMock: vi.fn(),
 }));
 vi.mock('./daemon-client.js', () => ({
     sendCommand: sendCommandMock,
+    sendCommandFull: sendCommandFullMock,
+}));
+vi.mock('../logger.js', () => ({
+    log: {
+        warn: warnMock,
+    },
 }));
 import { Page } from './page.js';
 describe('Page.getCurrentUrl', () => {
     beforeEach(() => {
         sendCommandMock.mockReset();
+        sendCommandFullMock.mockReset();
+        warnMock.mockReset();
     });
     it('reads the real browser URL when no local navigation cache exists', async () => {
         sendCommandMock.mockResolvedValueOnce('https://notebooklm.google.com/notebook/nb-live');
@@ -31,6 +43,8 @@ describe('Page.getCurrentUrl', () => {
 describe('Page.evaluate', () => {
     beforeEach(() => {
         sendCommandMock.mockReset();
+        sendCommandFullMock.mockReset();
+        warnMock.mockReset();
     });
     it('retries once when the inspected target navigated during exec', async () => {
         sendCommandMock
@@ -42,3 +56,49 @@ describe('Page.evaluate', () => {
         expect(sendCommandMock).toHaveBeenCalledTimes(2);
     });
 });
+describe('Page network capture compatibility', () => {
+    beforeEach(() => {
+        sendCommandMock.mockReset();
+        sendCommandFullMock.mockReset();
+        warnMock.mockReset();
+    });
+    it('treats unknown network-capture-start as unsupported and memoizes it', async () => {
+        sendCommandMock.mockRejectedValueOnce(new Error('Unknown action: network-capture-start'));
+        const page = new Page('site:notebooklm');
+        await expect(page.startNetworkCapture()).resolves.toBe(false);
+        await expect(page.startNetworkCapture()).resolves.toBe(false);
+        expect(sendCommandMock).toHaveBeenCalledTimes(1);
+        expect(warnMock).toHaveBeenCalledTimes(1);
+        expect(warnMock).toHaveBeenCalledWith(expect.stringContaining('does not support network capture'));
+        expect(sendCommandMock).toHaveBeenCalledWith('network-capture-start', expect.objectContaining({
+            workspace: 'site:notebooklm',
+        }));
+    });
+    it('returns an empty capture when network-capture-read is unsupported', async () => {
+        sendCommandMock.mockRejectedValueOnce(new Error('Unknown action: network-capture-read'));
+        const page = new Page('site:notebooklm');
+        await expect(page.readNetworkCapture()).resolves.toEqual([]);
+        await expect(page.readNetworkCapture()).resolves.toEqual([]);
+        expect(sendCommandMock).toHaveBeenCalledTimes(1);
+        expect(warnMock).toHaveBeenCalledTimes(1);
+        expect(sendCommandMock).toHaveBeenCalledWith('network-capture-read', expect.objectContaining({
+            workspace: 'site:notebooklm',
+        }));
+    });
+    it('rethrows unrelated network capture failures', async () => {
+        sendCommandMock.mockRejectedValueOnce(new Error('Extension disconnected'));
+        const page = new Page('site:notebooklm');
+        await expect(page.startNetworkCapture()).rejects.toThrow('Extension disconnected');
+        expect(sendCommandMock).toHaveBeenCalledTimes(1);
+        expect(warnMock).not.toHaveBeenCalled();
+    });
+    it('warns only once even if both start and read hit the compatibility fallback', async () => {
+        sendCommandMock
+            .mockRejectedValueOnce(new Error('Unknown action: network-capture-start'))
+            .mockRejectedValueOnce(new Error('Unknown action: network-capture-read'));
+        const page = new Page('site:notebooklm');
+        await expect(page.startNetworkCapture()).resolves.toBe(false);
+        await expect(page.readNetworkCapture()).resolves.toEqual([]);
+        expect(warnMock).toHaveBeenCalledTimes(1);
+    });
+});

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

@@ -0,0 +1,23 @@
+/**
+ * Structured error types for the target resolution system.
+ *
+ * Every browser action (click, type, select, get) that targets a DOM element
+ * goes through the unified resolver. When resolution fails, one of these
+ * structured errors is thrown so that AI agents and adapter authors get
+ * actionable diagnostics instead of a generic "Element not found".
+ */
+export type TargetErrorCode = 'not_found' | 'ambiguous' | 'stale_ref';
+export interface TargetErrorInfo {
+    code: TargetErrorCode;
+    message: string;
+    hint: string;
+    candidates?: string[];
+}
+export declare class TargetError extends Error {
+    readonly code: TargetErrorCode;
+    readonly hint: string;
+    readonly candidates?: string[];
+    constructor(info: TargetErrorInfo);
+    /** Serialize for structured output to AI agents */
+    toJSON(): TargetErrorInfo;
+}

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

@@ -0,0 +1,29 @@
+/**
+ * Structured error types for the target resolution system.
+ *
+ * Every browser action (click, type, select, get) that targets a DOM element
+ * goes through the unified resolver. When resolution fails, one of these
+ * structured errors is thrown so that AI agents and adapter authors get
+ * actionable diagnostics instead of a generic "Element not found".
+ */
+export class TargetError extends Error {
+    code;
+    hint;
+    candidates;
+    constructor(info) {
+        super(info.message);
+        this.name = 'TargetError';
+        this.code = info.code;
+        this.hint = info.hint;
+        this.candidates = info.candidates;
+    }
+    /** Serialize for structured output to AI agents */
+    toJSON() {
+        return {
+            code: this.code,
+            message: this.message,
+            hint: this.hint,
+            ...(this.candidates && { candidates: this.candidates }),
+        };
+    }
+}

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

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

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

@@ -0,0 +1,61 @@
+import { describe, expect, it } from 'vitest';
+import { TargetError } from './target-errors.js';
+describe('TargetError', () => {
+    it('creates not_found error with code and hint', () => {
+        const err = new TargetError({
+            code: 'not_found',
+            message: 'ref=99 not found in DOM',
+            hint: 'Re-run `opencli browser state` to get a fresh snapshot.',
+        });
+        expect(err).toBeInstanceOf(Error);
+        expect(err.name).toBe('TargetError');
+        expect(err.code).toBe('not_found');
+        expect(err.message).toBe('ref=99 not found in DOM');
+        expect(err.hint).toContain('fresh snapshot');
+        expect(err.candidates).toBeUndefined();
+    });
+    it('creates ambiguous error with candidates', () => {
+        const err = new TargetError({
+            code: 'ambiguous',
+            message: 'CSS selector ".btn" matched 3 elements',
+            hint: 'Use a more specific selector.',
+            candidates: ['<button> "Login"', '<button> "Sign Up"', '<button> "Cancel"'],
+        });
+        expect(err.code).toBe('ambiguous');
+        expect(err.candidates).toHaveLength(3);
+        expect(err.candidates[0]).toContain('Login');
+    });
+    it('creates stale_ref error', () => {
+        const err = new TargetError({
+            code: 'stale_ref',
+            message: 'ref=12 was <button>"Login" but now points to <div>"Header"',
+            hint: 'Re-run `opencli browser state` to refresh.',
+        });
+        expect(err.code).toBe('stale_ref');
+        expect(err.message).toContain('was <button>');
+    });
+    it('serializes to JSON for structured output', () => {
+        const err = new TargetError({
+            code: 'ambiguous',
+            message: 'matched 3',
+            hint: 'be specific',
+            candidates: ['a', 'b'],
+        });
+        const json = err.toJSON();
+        expect(json).toEqual({
+            code: 'ambiguous',
+            message: 'matched 3',
+            hint: 'be specific',
+            candidates: ['a', 'b'],
+        });
+    });
+    it('omits candidates from JSON when not present', () => {
+        const err = new TargetError({
+            code: 'not_found',
+            message: 'gone',
+            hint: 'refresh',
+        });
+        const json = err.toJSON();
+        expect(json).not.toHaveProperty('candidates');
+    });
+});

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

@@ -0,0 +1,57 @@
+/**
+ * Unified target resolver for browser actions.
+ *
+ * Replaces the ad-hoc 4-strategy fallback in dom-helpers.ts with a
+ * principled resolution pipeline:
+ *
+ * 1. Input classification: numeric → ref path, CSS-like → CSS path
+ * 2. Ref path: lookup by data-opencli-ref, then verify fingerprint
+ * 3. CSS path: querySelectorAll + uniqueness check
+ * 4. Structured errors: stale_ref / ambiguous / not_found
+ *
+ * All JS is generated as strings for page.evaluate() — runs in the browser.
+ */
+/**
+ * Generate JS that resolves a target to a single DOM element.
+ *
+ * Returns a JS expression that evaluates to:
+ *   { ok: true, el: Element }                      — success (el is assigned to `__resolved`)
+ *   { ok: false, code, message, hint, candidates }  — structured error
+ *
+ * The resolved element is stored in `__resolved` for the caller to use.
+ */
+export declare function resolveTargetJs(ref: string): string;
+/**
+ * Generate JS for click that uses the unified resolver.
+ * Assumes resolveTargetJs has been called and __resolved is set.
+ */
+export declare function clickResolvedJs(): string;
+/**
+ * Generate JS for type that uses the unified resolver.
+ */
+export declare function typeResolvedJs(text: string): string;
+/**
+ * Generate JS for scrollTo that uses the unified resolver.
+ * Assumes resolveTargetJs has been called and __resolved is set.
+ */
+export declare function scrollResolvedJs(): string;
+/**
+ * Generate JS to get text content of resolved element.
+ */
+export declare function getTextResolvedJs(): string;
+/**
+ * Generate JS to get value of resolved input/textarea element.
+ */
+export declare function getValueResolvedJs(): string;
+/**
+ * Generate JS to get all attributes of resolved element.
+ */
+export declare function getAttributesResolvedJs(): string;
+/**
+ * Generate JS to select an option on a resolved <select> element.
+ */
+export declare function selectResolvedJs(option: string): string;
+/**
+ * Generate JS to check if resolved element is an autocomplete/combobox field.
+ */
+export declare function isAutocompleteResolvedJs(): string;

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

@@ -0,0 +1,298 @@
+/**
+ * Unified target resolver for browser actions.
+ *
+ * Replaces the ad-hoc 4-strategy fallback in dom-helpers.ts with a
+ * principled resolution pipeline:
+ *
+ * 1. Input classification: numeric → ref path, CSS-like → CSS path
+ * 2. Ref path: lookup by data-opencli-ref, then verify fingerprint
+ * 3. CSS path: querySelectorAll + uniqueness check
+ * 4. Structured errors: stale_ref / ambiguous / not_found
+ *
+ * All JS is generated as strings for page.evaluate() — runs in the browser.
+ */
+/**
+ * Generate JS that resolves a target to a single DOM element.
+ *
+ * Returns a JS expression that evaluates to:
+ *   { ok: true, el: Element }                      — success (el is assigned to `__resolved`)
+ *   { ok: false, code, message, hint, candidates }  — structured error
+ *
+ * The resolved element is stored in `__resolved` for the caller to use.
+ */
+export function resolveTargetJs(ref) {
+    const safeRef = JSON.stringify(ref);
+    return `
+    (() => {
+      const ref = ${safeRef};
+      const identity = window.__opencli_ref_identity || {};
+
+      // ── Classify input ──
+      const isNumeric = /^\\d+$/.test(ref);
+      const isCssLike = !isNumeric && /^[a-zA-Z#.\\[]/.test(ref);
+
+      if (isNumeric) {
+        // ── Ref path ──
+        let el = document.querySelector('[data-opencli-ref="' + ref + '"]');
+        if (!el) el = document.querySelector('[data-ref="' + ref + '"]');
+
+        if (!el) {
+          return {
+            ok: false,
+            code: 'not_found',
+            message: 'ref=' + ref + ' not found in DOM',
+            hint: 'The element may have been removed. Re-run \`opencli browser state\` to get a fresh snapshot.',
+          };
+        }
+
+        // ── Fingerprint verification (identity vector) ──
+        const fp = identity[ref];
+        if (fp) {
+          const tag = el.tagName.toLowerCase();
+          const text = (el.textContent || '').trim().slice(0, 30);
+          const role = el.getAttribute('role') || '';
+          const ariaLabel = el.getAttribute('aria-label') || '';
+          const id = el.id || '';
+          const testId = el.getAttribute('data-testid') || el.getAttribute('data-test') || '';
+
+          // Hard fail: tag must always match
+          const tagMatch = fp.tag === tag;
+
+          // Soft signals: each non-empty stored field that mismatches counts against
+          var mismatches = 0;
+          var checks = 0;
+          if (fp.id) { checks++; if (fp.id !== id) mismatches++; }
+          if (fp.testId) { checks++; if (fp.testId !== testId) mismatches++; }
+          if (fp.ariaLabel) { checks++; if (fp.ariaLabel !== ariaLabel) mismatches++; }
+          if (fp.role) { checks++; if (fp.role !== role) mismatches++; }
+          if (fp.text) {
+            checks++;
+            // Text: allow prefix match (page text can grow), but empty current text never matches
+            if (!text || (!text.startsWith(fp.text) && !fp.text.startsWith(text))) mismatches++;
+          }
+
+          // Stale if tag changed, or if any uniquely identifying field (id/testId) changed,
+          // or if majority of soft signals mismatch
+          var isStale = !tagMatch;
+          if (!isStale && checks > 0) {
+            // id and testId are strong identifiers — any mismatch on these is decisive
+            if (fp.id && fp.id !== id) isStale = true;
+            else if (fp.testId && fp.testId !== testId) isStale = true;
+            // For remaining signals, stale if more than half mismatch
+            else if (mismatches > checks / 2) isStale = true;
+          }
+
+          if (isStale) {
+            return {
+              ok: false,
+              code: 'stale_ref',
+              message: 'ref=' + ref + ' was <' + fp.tag + '>' + (fp.text ? '"' + fp.text + '"' : '')
+                + ' but now points to <' + tag + '>' + (text ? '"' + text.slice(0, 30) + '"' : ''),
+              hint: 'The page has changed since the last snapshot. Re-run \`opencli browser state\` to refresh.',
+            };
+          }
+        }
+
+        window.__resolved = el;
+        return { ok: true };
+      }
+
+      if (isCssLike) {
+        // ── CSS selector path ──
+        let matches;
+        try {
+          matches = document.querySelectorAll(ref);
+        } catch (e) {
+          return {
+            ok: false,
+            code: 'not_found',
+            message: 'Invalid CSS selector: ' + ref,
+            hint: 'Check the selector syntax. Use ref numbers from snapshot for reliable targeting.',
+          };
+        }
+
+        if (matches.length === 0) {
+          return {
+            ok: false,
+            code: 'not_found',
+            message: 'CSS selector "' + ref + '" matched 0 elements',
+            hint: 'The element may not exist or may be hidden. Re-run \`opencli browser state\` to check.',
+          };
+        }
+
+        if (matches.length > 1) {
+          const candidates = [];
+          const limit = Math.min(matches.length, 5);
+          for (let i = 0; i < limit; i++) {
+            const m = matches[i];
+            const tag = m.tagName.toLowerCase();
+            const text = (m.textContent || '').trim().slice(0, 40);
+            const id = m.id ? '#' + m.id : '';
+            candidates.push('<' + tag + id + '>' + (text ? ' "' + text + '"' : ''));
+          }
+          return {
+            ok: false,
+            code: 'ambiguous',
+            message: 'CSS selector "' + ref + '" matched ' + matches.length + ' elements',
+            hint: 'Use a more specific selector, or use ref numbers from \`opencli browser state\` snapshot.',
+            candidates: candidates,
+          };
+        }
+
+        window.__resolved = matches[0];
+        return { ok: true };
+      }
+
+      // ── Unrecognized input ──
+      return {
+        ok: false,
+        code: 'not_found',
+        message: 'Cannot parse target: ' + ref,
+        hint: 'Use a numeric ref from snapshot (e.g. "12") or a CSS selector (e.g. "#submit").',
+      };
+    })()
+  `;
+}
+/**
+ * Generate JS for click that uses the unified resolver.
+ * Assumes resolveTargetJs has been called and __resolved is set.
+ */
+export function clickResolvedJs() {
+    return `
+    (() => {
+      const el = window.__resolved;
+      if (!el) throw new Error('No resolved element');
+      el.scrollIntoView({ behavior: 'instant', block: 'center' });
+      const rect = el.getBoundingClientRect();
+      const x = Math.round(rect.left + rect.width / 2);
+      const y = Math.round(rect.top + rect.height / 2);
+      try {
+        el.click();
+        return { status: 'clicked', x, y, w: Math.round(rect.width), h: Math.round(rect.height) };
+      } catch (e) {
+        return { status: 'js_failed', x, y, w: Math.round(rect.width), h: Math.round(rect.height), error: e.message };
+      }
+    })()
+  `;
+}
+/**
+ * Generate JS for type that uses the unified resolver.
+ */
+export function typeResolvedJs(text) {
+    const safeText = JSON.stringify(text);
+    return `
+    (() => {
+      const el = window.__resolved;
+      if (!el) throw new Error('No resolved element');
+      el.focus();
+      if (el.isContentEditable) {
+        const sel = window.getSelection();
+        const range = document.createRange();
+        range.selectNodeContents(el);
+        sel.removeAllRanges();
+        sel.addRange(range);
+        document.execCommand('delete', false);
+        document.execCommand('insertText', false, ${safeText});
+        el.dispatchEvent(new Event('input', { bubbles: true }));
+      } else {
+        const proto = el instanceof HTMLTextAreaElement
+          ? HTMLTextAreaElement.prototype
+          : HTMLInputElement.prototype;
+        const nativeSetter = Object.getOwnPropertyDescriptor(proto, 'value')?.set;
+        if (nativeSetter) {
+          nativeSetter.call(el, ${safeText});
+        } else {
+          el.value = ${safeText};
+        }
+        el.dispatchEvent(new Event('input', { bubbles: true }));
+        el.dispatchEvent(new Event('change', { bubbles: true }));
+      }
+      return 'typed';
+    })()
+  `;
+}
+/**
+ * Generate JS for scrollTo that uses the unified resolver.
+ * Assumes resolveTargetJs has been called and __resolved is set.
+ */
+export function scrollResolvedJs() {
+    return `
+    (() => {
+      const el = window.__resolved;
+      if (!el) throw new Error('No resolved element');
+      el.scrollIntoView({ behavior: 'smooth', block: 'center', inline: 'nearest' });
+      return { scrolled: true, tag: el.tagName.toLowerCase(), text: (el.textContent || '').trim().slice(0, 80) };
+    })()
+  `;
+}
+/**
+ * Generate JS to get text content of resolved element.
+ */
+export function getTextResolvedJs() {
+    return `
+    (() => {
+      const el = window.__resolved;
+      if (!el) throw new Error('No resolved element');
+      return el.textContent?.trim() ?? null;
+    })()
+  `;
+}
+/**
+ * Generate JS to get value of resolved input/textarea element.
+ */
+export function getValueResolvedJs() {
+    return `
+    (() => {
+      const el = window.__resolved;
+      if (!el) throw new Error('No resolved element');
+      return el.value ?? null;
+    })()
+  `;
+}
+/**
+ * Generate JS to get all attributes of resolved element.
+ */
+export function getAttributesResolvedJs() {
+    return `
+    (() => {
+      const el = window.__resolved;
+      if (!el) throw new Error('No resolved element');
+      return JSON.stringify(Object.fromEntries([...el.attributes].map(a => [a.name, a.value])));
+    })()
+  `;
+}
+/**
+ * Generate JS to select an option on a resolved <select> element.
+ */
+export function selectResolvedJs(option) {
+    const safeOption = JSON.stringify(option);
+    return `
+    (() => {
+      const el = window.__resolved;
+      if (!el) throw new Error('No resolved element');
+      if (el.tagName !== 'SELECT') return { error: 'Not a <select>' };
+      const match = Array.from(el.options).find(o => o.text.trim() === ${safeOption} || o.value === ${safeOption});
+      if (!match) return { error: 'Option not found', available: Array.from(el.options).map(o => o.text.trim()) };
+      const setter = Object.getOwnPropertyDescriptor(HTMLSelectElement.prototype, 'value')?.set;
+      if (setter) setter.call(el, match.value); else el.value = match.value;
+      el.dispatchEvent(new Event('input', { bubbles: true }));
+      el.dispatchEvent(new Event('change', { bubbles: true }));
+      return { selected: match.text };
+    })()
+  `;
+}
+/**
+ * Generate JS to check if resolved element is an autocomplete/combobox field.
+ */
+export function isAutocompleteResolvedJs() {
+    return `
+    (() => {
+      const el = window.__resolved;
+      if (!el) return false;
+      const role = el.getAttribute('role');
+      const ac = el.getAttribute('aria-autocomplete');
+      const list = el.getAttribute('list');
+      return role === 'combobox' || ac === 'list' || ac === 'both' || !!list;
+    })()
+  `;
+}

package/dist/src/browser/target-resolver.test.d.ts

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