@jackwener/opencli 1.7.3 → 1.7.5

package/dist/src/browser/page.js

@@ -15,26 +15,38 @@ 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.
  */
 export class Page extends BasePage {
     workspace;
-    constructor(workspace = 'default') {
+    _idleTimeout;
+    constructor(workspace = 'default', idleTimeout) {
         super();
         this.workspace = workspace;
+        this._idleTimeout = idleTimeout;
     }
     /** 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 };
+        return { workspace: this.workspace, ...(this._idleTimeout != null && { idleTimeout: this._idleTimeout }) };
     }
     /** Helper: spread workspace + page identity into command params */
     _cmdOpts() {
         return {
             workspace: this.workspace,
             ...(this._page !== undefined && { page: this._page }),
+            ...(this._idleTimeout != null && { idleTimeout: this._idleTimeout }),
         };
     }
     async goto(url, options) {
@@ -93,9 +105,18 @@ export class Page extends BasePage {
     getActivePage() {
         return this._page;
     }
-    /** @deprecated Use getActivePage() instead */
-    getActiveTabId() {
-        return undefined;
+    /** Bind this Page instance to a specific page identity (targetId). */
+    setActivePage(page) {
+        this._page = page;
+        this._lastUrl = null;
+    }
+    _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);
@@ -125,16 +146,47 @@ export class Page extends BasePage {
         finally {
             this._page = undefined;
             this._lastUrl = null;
+            this._networkCaptureUnsupported = false;
+            this._networkCaptureWarned = false;
         }
     }
     async tabs() {
         const result = await sendCommand('tabs', { op: 'list', ...this._wsOpt() });
         return Array.isArray(result) ? result : [];
     }
-    async selectTab(index) {
-        const result = await sendCommandFull('tabs', { op: 'select', index, ...this._wsOpt() });
+    async newTab(url) {
+        const result = await sendCommandFull('tabs', {
+            op: 'new',
+            ...(url !== undefined && { url }),
+            ...this._wsOpt(),
+        });
+        this._lastUrl = null;
+        return result.page;
+    }
+    async closeTab(target) {
+        const params = { op: 'close', ...this._wsOpt() };
+        if (typeof target === 'number')
+            params.index = target;
+        else if (typeof target === 'string')
+            params.page = target;
+        else if (this._page !== undefined)
+            params.page = this._page;
+        const result = await sendCommand('tabs', params);
+        const closedPage = typeof result?.closed === 'string' ? result.closed : undefined;
+        if ((closedPage && closedPage === this._page) || (!closedPage && (target === undefined || target === this._page))) {
+            this._page = undefined;
+            this._lastUrl = null;
+        }
+    }
+    async selectTab(target) {
+        const result = await sendCommandFull('tabs', {
+            op: 'select',
+            ...(typeof target === 'number' ? { index: target } : { page: target }),
+            ...this._wsOpt(),
+        });
         if (result.page)
             this._page = result.page;
+        this._lastUrl = null;
     }
     /**
      * Capture a screenshot via CDP Page.captureScreenshot.
@@ -152,16 +204,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.
@@ -187,6 +260,14 @@ export class Page extends BasePage {
             throw new Error('insertText returned no inserted flag — command may not be supported by the extension');
         }
     }
+    async frames() {
+        const result = await sendCommand('frames', { ...this._cmdOpts() });
+        return Array.isArray(result) ? result : [];
+    }
+    async evaluateInFrame(js, frameIndex) {
+        const code = wrapForEval(js);
+        return sendCommand('exec', { code, frameIndex, ...this._cmdOpts() });
+    }
     async cdp(method, params = {}) {
         return sendCommand('cdp', {
             cdpMethod: method,

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,146 @@ 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);
+    });
+});
+describe('Page active target tracking', () => {
+    beforeEach(() => {
+        sendCommandMock.mockReset();
+        sendCommandFullMock.mockReset();
+        warnMock.mockReset();
+    });
+    it('tracks only one active page identity at a time', async () => {
+        sendCommandFullMock
+            .mockResolvedValueOnce({ data: { url: 'https://first.example' }, page: 'page-1' })
+            .mockResolvedValueOnce({ data: { selected: true }, page: 'page-2' });
+        sendCommandMock.mockResolvedValue('ok');
+        const page = new Page('browser:default');
+        await page.goto('https://first.example', { waitUntil: 'none' });
+        expect(page.getActivePage()).toBe('page-1');
+        await page.selectTab(1);
+        expect(page.getActivePage()).toBe('page-2');
+        await page.evaluate('1 + 1');
+        expect(sendCommandMock).toHaveBeenLastCalledWith('exec', expect.objectContaining({
+            workspace: 'browser:default',
+            page: 'page-2',
+        }));
+    });
+    it('allows the caller to bind a specific active page identity explicitly', async () => {
+        sendCommandMock.mockResolvedValue('bound');
+        const page = new Page('browser:default');
+        page.setActivePage?.('page-explicit');
+        await page.evaluate('1 + 1');
+        expect(sendCommandMock).toHaveBeenCalledWith('exec', expect.objectContaining({
+            workspace: 'browser:default',
+            page: 'page-explicit',
+        }));
+    });
+    it('creates a new tab without changing the current active page binding', async () => {
+        sendCommandFullMock
+            .mockResolvedValueOnce({ data: { url: 'https://first.example' }, page: 'page-1' })
+            .mockResolvedValueOnce({
+            data: { url: 'https://second.example' },
+            page: 'page-2',
+        });
+        sendCommandMock.mockResolvedValue('ok');
+        const page = new Page('browser:default');
+        await page.goto('https://first.example', { waitUntil: 'none' });
+        const created = await page.newTab?.('https://second.example');
+        expect(created).toBe('page-2');
+        expect(page.getActivePage()).toBe('page-1');
+        await page.evaluate('1 + 1');
+        expect(sendCommandMock).toHaveBeenLastCalledWith('exec', expect.objectContaining({
+            workspace: 'browser:default',
+            page: 'page-1',
+        }));
+    });
+    it('allows the caller to adopt a new tab explicitly after creation', async () => {
+        sendCommandFullMock.mockResolvedValueOnce({
+            data: { url: 'https://second.example' },
+            page: 'page-2',
+        });
+        const page = new Page('browser:default');
+        const created = await page.newTab?.('https://second.example');
+        expect(created).toBe('page-2');
+        expect(page.getActivePage()).toBeUndefined();
+        page.setActivePage?.(created);
+        expect(page.getActivePage()).toBe('page-2');
+        expect(sendCommandFullMock).toHaveBeenCalledWith('tabs', expect.objectContaining({
+            op: 'new',
+            url: 'https://second.example',
+            workspace: 'browser:default',
+        }));
+    });
+    it('closes a tab by explicit page identity', async () => {
+        sendCommandMock.mockResolvedValueOnce({ closed: 'page-2' });
+        const page = new Page('browser:default');
+        await page.closeTab?.('page-2');
+        expect(sendCommandMock).toHaveBeenCalledWith('tabs', expect.objectContaining({
+            op: 'close',
+            workspace: 'browser:default',
+            page: 'page-2',
+        }));
+    });
+    it('clears the active page binding when closing the selected tab by numeric index', async () => {
+        sendCommandFullMock.mockResolvedValueOnce({ data: { selected: true }, page: 'page-2' });
+        sendCommandMock
+            .mockResolvedValueOnce({ closed: 'page-2' })
+            .mockResolvedValueOnce('ok');
+        const page = new Page('browser:default');
+        await page.selectTab(1);
+        expect(page.getActivePage()).toBe('page-2');
+        await page.closeTab?.(1);
+        expect(page.getActivePage()).toBeUndefined();
+        await page.evaluate('1 + 1');
+        const evalCall = sendCommandMock.mock.calls.at(-1);
+        expect(evalCall?.[0]).toBe('exec');
+        expect(evalCall?.[1]).toEqual(expect.objectContaining({
+            workspace: 'browser:default',
+        }));
+        expect(evalCall?.[1]).not.toHaveProperty('page');
+    });
+});

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.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;