@jackwener/opencli 1.7.2 → 1.7.4

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

@@ -18,6 +18,15 @@ export declare abstract class BasePage implements IPage {
         settleMs?: number;
     }): Promise<void>;
     abstract evaluate(js: string): Promise<unknown>;
+    /**
+     * Safely evaluate JS with pre-serialized arguments.
+     * Each key in `args` becomes a `const` declaration with JSON-serialized value,
+     * prepended to the JS code. Prevents injection by design.
+     *
+     * Usage:
+     *   page.evaluateWithArgs(`(async () => { return sym; })()`, { sym: userInput })
+     */
+    evaluateWithArgs(js: string, args: Record<string, unknown>): Promise<unknown>;
     abstract getCookies(opts?: {
         domain?: string;
         url?: string;

package/dist/src/browser/base-page.js

@@ -8,16 +8,43 @@
  * Subclasses implement the transport-specific methods: goto, evaluate,
  * getCookies, screenshot, tabs, etc.
  */
-import { generateSnapshotJs, scrollToRefJs, getFormStateJs } from './dom-snapshot.js';
-import { clickJs, typeTextJs, pressKeyJs, waitForTextJs, waitForCaptureJs, waitForSelectorJs, scrollJs, autoScrollJs, networkRequestsJs, waitForDomStableJs, } from './dom-helpers.js';
+import { generateSnapshotJs, getFormStateJs } from './dom-snapshot.js';
+import { pressKeyJs, waitForTextJs, waitForCaptureJs, waitForSelectorJs, scrollJs, autoScrollJs, networkRequestsJs, waitForDomStableJs, } from './dom-helpers.js';
+import { resolveTargetJs, clickResolvedJs, typeResolvedJs, scrollResolvedJs } from './target-resolver.js';
+import { TargetError } from './target-errors.js';
 import { formatSnapshot } from '../snapshotFormatter.js';
 export class BasePage {
     _lastUrl = null;
     /** Cached previous snapshot hashes for incremental diff marking */
     _prevSnapshotHashes = null;
+    /**
+     * Safely evaluate JS with pre-serialized arguments.
+     * Each key in `args` becomes a `const` declaration with JSON-serialized value,
+     * prepended to the JS code. Prevents injection by design.
+     *
+     * Usage:
+     *   page.evaluateWithArgs(`(async () => { return sym; })()`, { sym: userInput })
+     */
+    async evaluateWithArgs(js, args) {
+        const declarations = Object.entries(args)
+            .map(([key, value]) => {
+            if (!/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key)) {
+                throw new Error(`evaluateWithArgs: invalid key "${key}"`);
+            }
+            return `const ${key} = ${JSON.stringify(value)};`;
+        })
+            .join('\n');
+        return this.evaluate(`${declarations}\n${js}`);
+    }
     // ── Shared DOM helper implementations ──
     async click(ref) {
-        const result = await this.evaluate(clickJs(ref));
+        // Phase 1: Resolve target with fingerprint verification
+        const resolution = await this.evaluate(resolveTargetJs(ref));
+        if (!resolution.ok) {
+            throw new TargetError(resolution);
+        }
+        // Phase 2: Execute click on resolved element
+        const result = await this.evaluate(clickResolvedJs());
         // Backwards compat: old format returned 'clicked' string
         if (typeof result === 'string' || result == null)
             return;
@@ -37,13 +64,25 @@ export class BasePage {
         return false;
     }
     async typeText(ref, text) {
-        await this.evaluate(typeTextJs(ref, text));
+        // Phase 1: Resolve target with fingerprint verification
+        const resolution = await this.evaluate(resolveTargetJs(ref));
+        if (!resolution.ok) {
+            throw new TargetError(resolution);
+        }
+        // Phase 2: Execute type on resolved element
+        await this.evaluate(typeResolvedJs(text));
     }
     async pressKey(key) {
         await this.evaluate(pressKeyJs(key));
     }
     async scrollTo(ref) {
-        return this.evaluate(scrollToRefJs(ref));
+        // Phase 1: Resolve target with fingerprint verification
+        const resolution = await this.evaluate(resolveTargetJs(ref));
+        if (!resolution.ok) {
+            throw new TargetError(resolution);
+        }
+        // Phase 2: Scroll to resolved element
+        return this.evaluate(scrollResolvedJs());
     }
     async getFormState() {
         return (await this.evaluate(getFormStateJs()));

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

@@ -18,6 +18,8 @@ export declare class BrowserBridge implements IBrowserFactory {
     }): Promise<IPage>;
     close(): Promise<void>;
     private _ensureDaemon;
+    /** Poll until daemon is fully stopped (port released). */
+    private _waitForDaemonStop;
     /** Poll getDaemonHealth() until state is 'ready' or deadline is reached. */
     private _pollUntilReady;
 }

package/dist/src/browser/bridge.js

@@ -6,9 +6,10 @@ import { fileURLToPath } from 'node:url';
 import * as path from 'node:path';
 import * as fs from 'node:fs';
 import { Page } from './page.js';
-import { getDaemonHealth } from './daemon-client.js';
+import { getDaemonHealth, requestDaemonShutdown } from './daemon-client.js';
 import { DEFAULT_DAEMON_PORT } from '../constants.js';
 import { BrowserConnectError } from '../errors.js';
+import { PKG_VERSION } from '../version.js';
 const DAEMON_SPAWN_TIMEOUT = 10000; // 10s to wait for daemon + extension
 /**
  * Browser factory: manages daemon lifecycle and provides IPage instances.
@@ -57,18 +58,42 @@ export class BrowserBridge {
         // Fast path: everything ready
         if (health.state === 'ready')
             return;
-        // Daemon running but no extension — wait for extension with progress
+        // Daemon running but no extension
         if (health.state === 'no-extension') {
-            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');
+            // 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 this._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
+            }
+            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))
+                    return;
+                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))
-                return;
-            throw new BrowserConnectError('Browser Bridge extension not connected', 'Install the Browser Bridge:\n' +
-                '  1. Download: https://github.com/jackwener/opencli/releases\n' +
-                '  2. In Chrome or Chromium, open chrome://extensions → Developer Mode → Load unpacked\n' +
-                '  Then run: opencli doctor', 'extension-not-connected');
         }
         // No daemon — spawn one
         const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -94,13 +119,25 @@ export class BrowserBridge {
             return;
         const finalHealth = await getDaemonHealth();
         if (finalHealth.state === 'no-extension') {
-            throw new BrowserConnectError('Browser Bridge extension not connected', 'Install the Browser Bridge:\n' +
+            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. In Chrome or Chromium, open chrome://extensions → Developer Mode → Load unpacked\n' +
-                '  Then run: opencli doctor', 'extension-not-connected');
+                '  2. Open chrome://extensions → Developer Mode → Load unpacked', 'extension-not-connected');
         }
         throw new BrowserConnectError('Failed to start opencli daemon', `Try running manually:\n  node ${daemonPath}\nMake sure port ${DEFAULT_DAEMON_PORT} is available.`, 'daemon-not-running');
     }
+    /** Poll until daemon is fully stopped (port released). */
+    async _waitForDaemonStop(timeoutMs) {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            await new Promise(resolve => setTimeout(resolve, 200));
+            const h = await getDaemonHealth();
+            if (h.state === 'stopped')
+                return true;
+        }
+        return false;
+    }
     /** Poll getDaemonHealth() until state is 'ready' or deadline is reached. */
     async _pollUntilReady(timeoutMs) {
         const deadline = Date.now() + timeoutMs;

package/dist/src/browser/cdp.js

@@ -40,7 +40,11 @@ export class CDPBridge {
         return new Promise((resolve, reject) => {
             const ws = new WebSocket(wsUrl);
             const timeoutMs = (opts?.timeout ?? 10) * 1000;
-            const timeout = setTimeout(() => reject(new Error('CDP connect timeout')), timeoutMs);
+            const timeout = setTimeout(() => {
+                this._ws = null;
+                ws.close();
+                reject(new Error('CDP connect timeout'));
+            }, timeoutMs);
             ws.on('open', async () => {
                 clearTimeout(timeout);
                 this._ws = ws;
@@ -48,7 +52,11 @@ export class CDPBridge {
                     await this.send('Page.enable');
                     await this.send('Page.addScriptToEvaluateOnNewDocument', { source: generateStealthJs() });
                 }
-                catch { }
+                catch (err) {
+                    ws.close();
+                    reject(err instanceof Error ? err : new Error(String(err)));
+                    return;
+                }
                 resolve(new CDPPage(this));
             });
             ws.on('error', (err) => {
@@ -247,6 +255,7 @@ class CDPPage extends BasePage {
             });
             this._networkCapturing = true;
         }
+        return true;
     }
     async readNetworkCapture() {
         // Await all in-flight body fetches so entries have responsePreview populated

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

@@ -47,8 +47,10 @@ export interface DaemonStatus {
     ok: boolean;
     pid: number;
     uptime: number;
+    daemonVersion?: string;
     extensionConnected: boolean;
     extensionVersion?: string;
+    extensionCompatRange?: string;
     pending: number;
     memoryMB: number;
     port: number;

package/dist/src/browser/dom-snapshot.js

@@ -575,6 +575,7 @@ export function generateSnapshotJs(opts = {}) {
   const lines = [];
   const hiddenInteractives = [];
   const currentHashes = [];
+  const refIdentity = {};
   let iframeCount = 0;
 
   function walk(el, depth, parentPropagatingRect) {
@@ -709,11 +710,20 @@ export function generateSnapshotJs(opts = {}) {
     // Scroll marker
     if (isScrollable && !interactive) line += '|scroll|';
 
-    // Interactive index + data-ref
+    // Interactive index + data-ref + fingerprint
     if (interactive) {
       interactiveIndex++;
       if (ANNOTATE_REFS) el.setAttribute('data-opencli-ref', '' + interactiveIndex);
       line += isScrollable ? '|scroll[' + interactiveIndex + ']|' : '[' + interactiveIndex + ']';
+      // Store fingerprint for stale-ref detection
+      refIdentity['' + interactiveIndex] = {
+        tag: tag,
+        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') || '',
+      };
     }
 
     // Tag + attributes
@@ -797,6 +807,8 @@ export function generateSnapshotJs(opts = {}) {
 
   // Store hashes on window for next diff snapshot
   try { window.__opencli_prev_hashes = JSON.stringify(currentHashes); } catch {}
+  // Store ref identity map for stale-ref detection by target resolver
+  try { window.__opencli_ref_identity = refIdentity; } catch {}
 
   return lines.join('\\n');
 })()

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;