@jackwener/opencli 1.7.13 → 1.7.15

package/dist/src/cli.test.js

@@ -223,6 +223,7 @@ describe('createProgram root help descriptions', () => {
                 strategy: Strategy.PUBLIC,
                 browser: false,
                 args: [{ name: 'limit', type: 'int', default: 20, help: 'Number of videos' }],
+                columns: ['title', 'url'],
             });
             const program = createProgram('', '');
             const site = program.commands.find(cmd => cmd.name() === 'bilibili');
@@ -235,10 +236,13 @@ describe('createProgram root help descriptions', () => {
                     name: 'hot',
                     access: 'read',
                     description: 'Bilibili hot videos',
+                    browser: false,
                     example: 'opencli bilibili hot -f yaml',
-                    args: [{ name: 'limit', type: 'int', default: 20 }],
+                    command_options: [{ name: 'limit', type: 'int', default: 20 }],
+                    columns: ['title', 'url'],
                 },
             ]);
+            expect(data.commands[0]).not.toHaveProperty('args');
         }
         finally {
             process.argv = argv;
@@ -247,6 +251,212 @@ describe('createProgram root help descriptions', () => {
                 registry.set(key, value);
         }
     });
+    it('renders per-site text help without per-command common option noise', () => {
+        const registry = getRegistry();
+        const snapshot = new Map(registry);
+        registry.clear();
+        try {
+            cli({
+                site: 'bilibili',
+                name: 'hot',
+                access: 'read',
+                description: 'Bilibili hot videos',
+                strategy: Strategy.PUBLIC,
+                browser: false,
+                args: [{ name: 'limit', type: 'int', default: 20, help: 'Number of videos' }],
+            });
+            cli({
+                site: 'bilibili',
+                name: 'video',
+                access: 'read',
+                description: 'Read one video',
+                domain: 'www.bilibili.com',
+                strategy: Strategy.PUBLIC,
+                browser: true,
+                args: [{ name: 'bvid', positional: true, required: true, help: 'Video id' }],
+            });
+            const program = createProgram('', '');
+            const site = program.commands.find(cmd => cmd.name() === 'bilibili');
+            expect(site).toBeTruthy();
+            const help = site.helpInformation();
+            expect(help).toContain('hot [options]  [read] Bilibili hot videos');
+            expect(help).toContain('video <bvid>   [read] Read one video');
+            expect(help).toContain('hot [options]');
+            expect(help).not.toContain('video <bvid> [options]');
+            expect(help).not.toContain('\nOptions:');
+            expect(help).toContain('Common options:');
+            expect(help).toContain('-f, --format <fmt>');
+            expect(help).toContain('--trace <mode>');
+            expect(help).toContain('get all command args/options in one structured response');
+        }
+        finally {
+            registry.clear();
+            for (const [key, value] of snapshot)
+                registry.set(key, value);
+        }
+    });
+    it('separates command args from common options in structured help', () => {
+        const registry = getRegistry();
+        const snapshot = new Map(registry);
+        const argv = process.argv;
+        registry.clear();
+        try {
+            cli({
+                site: 'bilibili',
+                name: 'video',
+                access: 'read',
+                description: 'Read one video',
+                strategy: Strategy.PUBLIC,
+                domain: 'www.bilibili.com',
+                browser: true,
+                args: [
+                    { name: 'bvid', positional: true, required: true, help: 'Video id' },
+                    { name: 'with-comments', type: 'boolean', default: false, help: 'Include comments' },
+                ],
+                columns: ['title', 'url'],
+            });
+            const program = createProgram('', '');
+            const site = program.commands.find(cmd => cmd.name() === 'bilibili');
+            const command = site.commands.find(cmd => cmd.name() === 'video');
+            expect(command).toBeTruthy();
+            process.argv = ['node', 'opencli', 'bilibili', 'video', '--help', '-f', 'yaml'];
+            const data = yaml.load(command.helpInformation());
+            expect(data.usage).toBe('opencli bilibili video <bvid> [options]');
+            expect(data.browser).toBe(true);
+            expect(data.domain).toBe('www.bilibili.com');
+            expect(data.positionals).toMatchObject([{ name: 'bvid', positional: true, required: true }]);
+            expect(data.command_options).toMatchObject([{ name: 'with-comments', default: false }]);
+            expect(data.common_options.map((option) => option.name)).toEqual(['format', 'trace', 'verbose', 'help']);
+            expect(data.columns).toEqual(['title', 'url']);
+            expect(data).not.toHaveProperty('args');
+        }
+        finally {
+            process.argv = argv;
+            registry.clear();
+            for (const [key, value] of snapshot)
+                registry.set(key, value);
+        }
+    });
+    it('renders browser namespace structured help from Commander metadata', () => {
+        const argv = process.argv;
+        try {
+            const program = createProgram('', '');
+            const browser = program.commands.find(cmd => cmd.name() === 'browser');
+            expect(browser).toBeTruthy();
+            process.argv = ['node', 'opencli', 'browser', '--help', '-f', 'yaml'];
+            const data = yaml.load(browser.helpInformation());
+            expect(data.namespace).toBe('browser');
+            expect(data.command).toBe('opencli browser');
+            expect(data.description).toBe('Browser control — navigate, click, type, extract, wait (no LLM needed)');
+            expect(data.command_count).toBeGreaterThan(20);
+            expect(data.namespace_options).toMatchObject([
+                {
+                    name: 'workspace',
+                    flags: '--workspace <name>',
+                    takes_value: 'required',
+                },
+            ]);
+            expect(data.global_options).toEqual(expect.arrayContaining([
+                expect.objectContaining({
+                    name: 'version',
+                    flags: '-V, --version',
+                }),
+                expect.objectContaining({
+                    name: 'profile',
+                    flags: '--profile <name>',
+                    takes_value: 'required',
+                }),
+            ]));
+            const click = data.commands.find((cmd) => cmd.name === 'click');
+            expect(click).toMatchObject({
+                command: 'opencli browser click',
+                usage: 'opencli browser click [target] [options]',
+                positionals: [{ name: 'target' }],
+            });
+            expect(click.command_options.map((option) => option.name)).toEqual(['role', 'name', 'label', 'text', 'testid', 'nth', 'tab']);
+            const tabList = data.commands.find((cmd) => cmd.name === 'tab list');
+            expect(tabList).toMatchObject({
+                command: 'opencli browser tab list',
+                usage: 'opencli browser tab list [options]',
+                command_options: [],
+            });
+            const getText = data.commands.find((cmd) => cmd.name === 'get text');
+            expect(getText).toMatchObject({
+                command: 'opencli browser get text',
+                positionals: [{ name: 'target' }],
+            });
+            expect(data.structured_help).toMatchObject({
+                formats: ['yaml', 'json'],
+                usage: 'opencli browser --help -f yaml',
+            });
+        }
+        finally {
+            process.argv = argv;
+        }
+    });
+    it('renders nested browser parent structured help for a subtree', () => {
+        const argv = process.argv;
+        try {
+            const program = createProgram('', '');
+            const browser = program.commands.find(cmd => cmd.name() === 'browser');
+            const tab = browser.commands.find(cmd => cmd.name() === 'tab');
+            expect(tab).toBeTruthy();
+            process.argv = ['node', 'opencli', 'browser', 'tab', '--help', '-f', 'yaml'];
+            const data = yaml.load(tab.helpInformation());
+            expect(data).toMatchObject({
+                namespace: 'browser',
+                group: 'tab',
+                command: 'opencli browser tab',
+                usage: 'opencli browser tab <command> [args] [options]',
+                command_count: 4,
+            });
+            expect(data.commands.map((cmd) => cmd.name)).toEqual([
+                'tab close',
+                'tab list',
+                'tab new',
+                'tab select',
+            ]);
+            expect(data.commands.find((cmd) => cmd.name === 'tab close')).toMatchObject({
+                command: 'opencli browser tab close',
+                usage: 'opencli browser tab close [targetId] [options]',
+                positionals: [{ name: 'targetId', help: 'Target tab/page identity returned by "browser open", "browser tab new", or "browser tab list"' }],
+            });
+            expect(data.namespace_options.map((option) => option.name)).toEqual(['workspace']);
+            expect(data.structured_help).toMatchObject({
+                usage: 'opencli browser tab --help -f yaml',
+            });
+        }
+        finally {
+            process.argv = argv;
+        }
+    });
+    it('renders browser command structured help without needing the full namespace dump', () => {
+        const argv = process.argv;
+        try {
+            const program = createProgram('', '');
+            const browser = program.commands.find(cmd => cmd.name() === 'browser');
+            const click = browser.commands.find(cmd => cmd.name() === 'click');
+            expect(click).toBeTruthy();
+            process.argv = ['node', 'opencli', 'browser', 'click', '--help', '-f', 'yaml'];
+            const data = yaml.load(click.helpInformation());
+            expect(data).toMatchObject({
+                namespace: 'browser',
+                name: 'click',
+                command: 'opencli browser click',
+                usage: 'opencli browser click [target] [options]',
+                positionals: [{ name: 'target' }],
+                structured_help: {
+                    usage: 'opencli browser click --help -f yaml',
+                },
+            });
+            expect(data.command_options.map((option) => option.name)).toEqual(['role', 'name', 'label', 'text', 'testid', 'nth', 'tab']);
+            expect(data.namespace_options.map((option) => option.name)).toEqual(['workspace']);
+            expect(data.global_options.map((option) => option.name)).toContain('profile');
+        }
+        finally {
+            process.argv = argv;
+        }
+    });
 });
 describe('resolveBrowserVerifyInvocation', () => {
     it('prefers the built entry declared in package metadata', () => {
@@ -546,7 +756,16 @@ describe('browser tab targeting commands', () => {
                 { index: 0, frameId: 'frame-1', url: 'https://x.example/embed', name: 'x-embed' },
             ]),
             evaluateInFrame: vi.fn().mockResolvedValue('inside frame'),
+            screenshot: vi.fn().mockResolvedValue('base64-shot'),
+            annotatedScreenshot: vi.fn().mockResolvedValue('annotated-base64-shot'),
             readNetworkCapture: vi.fn().mockResolvedValue([]),
+            waitForDownload: vi.fn().mockResolvedValue({
+                downloaded: true,
+                filename: '/tmp/receipt.pdf',
+                url: 'https://app.example/receipt.pdf',
+                state: 'complete',
+                elapsedMs: 10,
+            }),
         };
     });
     function lastJsonLog() {
@@ -585,6 +804,69 @@ describe('browser tab targeting commands', () => {
         expect(mockBrowserConnect).toHaveBeenCalledWith({ timeout: 30, workspace: 'bound:default' });
         expect(browserState.page?.snapshot).toHaveBeenCalled();
     });
+    it('passes the opt-in AX source to browser state', async () => {
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'state', '--source', 'ax']);
+        expect(browserState.page?.snapshot).toHaveBeenCalledWith({ viewportExpand: 2000, source: 'ax' });
+    });
+    it('prints DOM vs AX snapshot metrics without changing default state output', async () => {
+        browserState.page = {
+            ...browserState.page,
+            snapshot: vi.fn(async (opts) => {
+                if (opts?.source === 'ax') {
+                    return 'source: ax\n---\n[1]button "Save"\nframe "https://app.example/embed":\n  [2]button "Frame Save"\n---\ninteractive: 2';
+                }
+                return 'URL: https://app.example\n[1] button "Save"';
+            }),
+        };
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'state', '--compare-sources']);
+        expect(browserState.page?.snapshot).toHaveBeenCalledWith({ viewportExpand: 2000, source: 'dom' });
+        expect(browserState.page?.snapshot).toHaveBeenCalledWith({ viewportExpand: 2000, source: 'ax' });
+        const out = lastJsonLog();
+        expect(out.url).toBe('https://one.example');
+        expect(out.sources.dom).toMatchObject({ ok: true, refs: 1, frame_sections: 0 });
+        expect(out.sources.ax).toMatchObject({ ok: true, refs: 2, frame_sections: 1, interactive: 2 });
+    });
+    it('keeps compare-sources usable when one observation backend fails', async () => {
+        browserState.page = {
+            ...browserState.page,
+            snapshot: vi.fn(async (opts) => {
+                if (opts?.source === 'ax')
+                    throw new Error('AX unavailable');
+                return '[1] button "Save"';
+            }),
+        };
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'state', '--compare-sources']);
+        const out = lastJsonLog();
+        expect(out.sources.dom).toMatchObject({ ok: true, refs: 1 });
+        expect(out.sources.ax).toMatchObject({
+            ok: false,
+            error: { message: 'AX unavailable' },
+        });
+    });
+    it('rejects unknown browser state sources before touching the page', async () => {
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'state', '--source', 'magic']);
+        expect(browserState.page?.snapshot).not.toHaveBeenCalled();
+        const out = lastJsonLog();
+        expect(out.error.code).toBe('invalid_source');
+        expect(process.exitCode).toBeDefined();
+    });
+    it('captures annotated screenshots through the visual ref overlay path', async () => {
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'screenshot', '--annotate']);
+        expect(browserState.page?.annotatedScreenshot).toHaveBeenCalledWith({
+            fullPage: false,
+            annotate: true,
+            width: undefined,
+            height: undefined,
+            format: 'png',
+        });
+        expect(browserState.page?.screenshot).not.toHaveBeenCalled();
+        expect(consoleLogSpy).toHaveBeenLastCalledWith('annotated-base64-shot');
+    });
     it('blocks history navigation on bound workspaces unless explicitly allowed', async () => {
         browserState.page = {
             ...browserState.page,
@@ -946,6 +1228,55 @@ describe('browser tab targeting commands', () => {
         expect(bufferReads).toBe(2);
         expect(out.matched.url).toBe('https://target.example/api/target');
     });
+    it('browser wait download delegates to the Browser Bridge download observer', async () => {
+        browserState.page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            wait: vi.fn().mockResolvedValue(undefined),
+            waitForDownload: vi.fn().mockResolvedValue({
+                downloaded: true,
+                filename: '/tmp/receipt.pdf',
+                url: 'https://app.example/receipt.pdf',
+                state: 'complete',
+                elapsedMs: 10,
+            }),
+            setActivePage: vi.fn(),
+            getActivePage: vi.fn().mockReturnValue('tab-1'),
+            getCurrentUrl: vi.fn().mockResolvedValue('https://target.example'),
+            tabs: vi.fn().mockResolvedValue([{ index: 0, page: 'tab-1', url: 'https://target.example', title: 'Target', active: true }]),
+        };
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'wait', 'download', 'receipt', '--timeout', '900']);
+        expect(browserState.page?.waitForDownload).toHaveBeenCalledWith('receipt', 900);
+        expect(lastJsonLog()).toEqual({
+            downloaded: true,
+            filename: '/tmp/receipt.pdf',
+            url: 'https://app.example/receipt.pdf',
+            state: 'complete',
+            elapsedMs: 10,
+        });
+    });
+    it('browser wait download reports an error envelope when no matching download completes', async () => {
+        browserState.page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            wait: vi.fn().mockResolvedValue(undefined),
+            waitForDownload: vi.fn().mockResolvedValue({
+                downloaded: false,
+                state: 'interrupted',
+                error: 'No download matched "receipt" within 900ms',
+                elapsedMs: 900,
+            }),
+            setActivePage: vi.fn(),
+            getActivePage: vi.fn().mockReturnValue('tab-1'),
+            getCurrentUrl: vi.fn().mockResolvedValue('https://target.example'),
+            tabs: vi.fn().mockResolvedValue([{ index: 0, page: 'tab-1', url: 'https://target.example', title: 'Target', active: true }]),
+        };
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'wait', 'download', 'receipt', '--timeout', '900']);
+        const out = lastJsonLog();
+        expect(out.error.code).toBe('download_not_seen');
+        expect(out.download.elapsedMs).toBe(900);
+        expect(process.exitCode).toBeDefined();
+    });
 });
 describe('browser network command', () => {
     const consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => { });
@@ -1597,6 +1928,25 @@ describe('browser find command', () => {
         expect(out.entries[1].ref).toBe(17);
         expect(process.exitCode).toBeUndefined();
     });
+    it('finds elements by semantic role/name without requiring CSS', async () => {
+        browserState.page.evaluate.mockResolvedValueOnce({
+            matches_n: 1,
+            entries: [
+                { nth: 0, ref: 9, tag: 'button', role: 'button', text: 'Save', attrs: {}, visible: true },
+            ],
+        });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'find', '--role', 'button', '--name', 'Save']);
+        const js = browserState.page.evaluate.mock.calls[0][0];
+        expect(js).toContain('CRITERIA');
+        expect(js).toContain('function accessibleName');
+        expect(lastJsonLog()).toEqual({
+            matches_n: 1,
+            entries: [
+                { nth: 0, ref: 9, tag: 'button', role: 'button', text: 'Save', attrs: {}, visible: true },
+            ],
+        });
+    });
     it('forwards --limit / --text-max into the generated JS', async () => {
         browserState.page.evaluate.mockResolvedValueOnce({ matches_n: 0, entries: [] });
         const program = createProgram('', '');
@@ -1652,6 +2002,40 @@ describe('browser get text/value/attributes commands', () => {
         await program.parseAsync(['node', 'opencli', 'browser', 'get', 'text', '7']);
         expect(lastJsonLog()).toEqual({ value: 'Hello world', matches_n: 1, match_level: 'exact' });
     });
+    it('resolves a semantic locator to a ref before get text', async () => {
+        const evalMock = browserState.page.evaluate;
+        evalMock.mockResolvedValueOnce({
+            matches_n: 1,
+            entries: [
+                { nth: 0, ref: 12, tag: 'button', role: 'button', text: 'Save', attrs: {}, visible: true },
+            ],
+        });
+        evalMock.mockResolvedValueOnce({ ok: true, matches_n: 1, match_level: 'exact' });
+        evalMock.mockResolvedValueOnce('Save');
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'get', 'text', '--role', 'button', '--name', 'Save']);
+        expect(evalMock.mock.calls[0][0]).toContain('function accessibleName');
+        expect(evalMock.mock.calls[1][0]).toContain('const ref = "12"');
+        expect(lastJsonLog()).toEqual({ value: 'Save', matches_n: 1, match_level: 'exact' });
+    });
+    it('reports total_matches when semantic get reads the first of multiple matches', async () => {
+        const evalMock = browserState.page.evaluate;
+        evalMock.mockResolvedValueOnce({
+            matches_n: 3,
+            entries: [
+                { nth: 0, ref: 12, tag: 'button', role: 'button', text: 'Save', attrs: {}, visible: true },
+                { nth: 1, ref: 13, tag: 'button', role: 'button', text: 'Save draft', attrs: {}, visible: true },
+                { nth: 2, ref: 14, tag: 'button', role: 'button', text: 'Save copy', attrs: {}, visible: true },
+            ],
+        });
+        evalMock.mockResolvedValueOnce({ ok: true, matches_n: 1, match_level: 'exact' });
+        evalMock.mockResolvedValueOnce('Save');
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'get', 'text', '--role', 'button', '--name', 'Save']);
+        expect(evalMock.mock.calls[0][0]).toContain('const LIMIT = 6');
+        expect(evalMock.mock.calls[1][0]).toContain('const ref = "12"');
+        expect(lastJsonLog()).toEqual({ value: 'Save', matches_n: 1, match_level: 'exact', total_matches: 3 });
+    });
     it('reports matches_n on multi-match CSS (read path: first match wins)', async () => {
         const evalMock = browserState.page.evaluate;
         evalMock.mockResolvedValueOnce({ ok: true, matches_n: 3, match_level: 'exact' });
@@ -1707,6 +2091,28 @@ describe('browser click/type commands', () => {
     const { lastJsonLog } = installSelectorFirstTestHarness('click-type', () => ({
         evaluate: vi.fn().mockResolvedValue(false),
         click: vi.fn().mockResolvedValue({ matches_n: 1, match_level: 'exact' }),
+        dblClick: vi.fn().mockResolvedValue({ matches_n: 1, match_level: 'exact' }),
+        hover: vi.fn().mockResolvedValue({ matches_n: 1, match_level: 'exact' }),
+        focus: vi.fn().mockResolvedValue({ focused: true, matches_n: 1, match_level: 'exact' }),
+        setChecked: vi.fn().mockResolvedValue({ checked: true, changed: true, matches_n: 1, match_level: 'exact', kind: 'checkbox' }),
+        uploadFiles: vi.fn().mockResolvedValue({
+            uploaded: true,
+            files: 1,
+            file_names: ['receipt.pdf'],
+            target: '#file',
+            matches_n: 1,
+            match_level: 'exact',
+            multiple: false,
+        }),
+        drag: vi.fn().mockResolvedValue({
+            dragged: true,
+            source: '#card',
+            target: '#lane',
+            source_matches_n: 1,
+            target_matches_n: 1,
+            source_match_level: 'exact',
+            target_match_level: 'exact',
+        }),
         typeText: vi.fn().mockResolvedValue({ matches_n: 1, match_level: 'exact' }),
         fillText: vi.fn().mockResolvedValue({
             filled: true,
@@ -1727,6 +2133,163 @@ describe('browser click/type commands', () => {
         expect(browserState.page.click).toHaveBeenCalledWith('#save', {});
         expect(lastJsonLog()).toEqual({ clicked: true, target: '#save', matches_n: 1, match_level: 'exact' });
     });
+    it('clicks a unique semantic locator without a prior state call', async () => {
+        browserState.page.evaluate.mockResolvedValueOnce({
+            matches_n: 1,
+            entries: [
+                { nth: 0, ref: 23, tag: 'button', role: 'button', text: 'Submit', attrs: {}, visible: true },
+            ],
+        });
+        browserState.page.click.mockResolvedValueOnce({ matches_n: 1, match_level: 'exact' });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'click', '--role', 'button', '--name', 'Submit']);
+        expect(browserState.page.click).toHaveBeenCalledWith('23', {});
+        expect(lastJsonLog()).toEqual({ clicked: true, target: '23', matches_n: 1, match_level: 'exact' });
+    });
+    it('rejects ambiguous semantic locators before write actions', async () => {
+        browserState.page.evaluate.mockResolvedValueOnce({
+            matches_n: 2,
+            entries: [
+                { nth: 0, ref: 1, tag: 'button', role: 'button', text: 'Save', attrs: {}, visible: true },
+                { nth: 1, ref: 2, tag: 'button', role: 'button', text: 'Save draft', attrs: {}, visible: true },
+            ],
+        });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'click', '--role', 'button', '--name', 'Save']);
+        const err = lastJsonLog().error;
+        expect(err.code).toBe('semantic_ambiguous');
+        expect(err.matches_n).toBe(2);
+        expect(browserState.page.click).not.toHaveBeenCalled();
+        expect(process.exitCode).toBeDefined();
+    });
+    it('hover: resolves a semantic locator before moving the mouse', async () => {
+        browserState.page.evaluate.mockResolvedValueOnce({
+            matches_n: 1,
+            entries: [
+                { nth: 0, ref: 31, tag: 'button', role: 'button', text: 'Settings', attrs: {}, visible: true },
+            ],
+        });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'hover', '--role', 'button', '--name', 'Settings']);
+        expect(browserState.page.hover).toHaveBeenCalledWith('31', {});
+        expect(lastJsonLog()).toEqual({ hovered: true, target: '31', matches_n: 1, match_level: 'exact' });
+    });
+    it('check: resolves a semantic locator before setting checked state', async () => {
+        browserState.page.evaluate.mockResolvedValueOnce({
+            matches_n: 1,
+            entries: [
+                { nth: 0, ref: 32, tag: 'input', role: 'checkbox', text: 'Accept', attrs: {}, visible: true },
+            ],
+        });
+        browserState.page.setChecked.mockResolvedValueOnce({ checked: true, changed: false, matches_n: 1, match_level: 'exact', kind: 'checkbox' });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'check', '--role', 'checkbox', '--name', 'Accept']);
+        expect(browserState.page.setChecked).toHaveBeenCalledWith('32', true, {});
+        expect(lastJsonLog()).toEqual({ checked: true, changed: false, target: '32', matches_n: 1, match_level: 'exact', kind: 'checkbox' });
+    });
+    it('upload: treats the first positional as a file when using semantic locator flags', async () => {
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-upload-semantic-'));
+        const file = path.join(dir, 'receipt.pdf');
+        fs.writeFileSync(file, 'pdf');
+        browserState.page.evaluate.mockResolvedValueOnce({
+            matches_n: 1,
+            entries: [
+                { nth: 0, ref: 33, tag: 'input', role: 'button', text: 'Upload receipt', attrs: {}, visible: true },
+            ],
+        });
+        browserState.page.uploadFiles.mockResolvedValueOnce({
+            uploaded: true,
+            files: 1,
+            file_names: ['receipt.pdf'],
+            target: '33',
+            matches_n: 1,
+            match_level: 'exact',
+            multiple: false,
+        });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'upload', '--role', 'button', '--name', 'Upload receipt', file]);
+        expect(browserState.page.uploadFiles).toHaveBeenCalledWith('33', [file], {});
+        expect(lastJsonLog()).toMatchObject({ uploaded: true, target: '33', files: 1 });
+    });
+    it('type: treats the first positional as text when using semantic locator flags', async () => {
+        browserState.page.evaluate
+            .mockResolvedValueOnce({
+            matches_n: 1,
+            entries: [
+                { nth: 0, ref: 34, tag: 'input', role: 'textbox', text: '', attrs: {}, visible: true },
+            ],
+        })
+            .mockResolvedValueOnce(false);
+        browserState.page.click.mockResolvedValueOnce({ matches_n: 1, match_level: 'exact' });
+        browserState.page.typeText.mockResolvedValueOnce({ matches_n: 1, match_level: 'exact' });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'type', '--label', 'Email', 'me@example.com']);
+        expect(browserState.page.click).toHaveBeenCalledWith('34', {});
+        expect(browserState.page.typeText).toHaveBeenCalledWith('34', 'me@example.com', {});
+        expect(lastJsonLog()).toMatchObject({ typed: true, target: '34', text: 'me@example.com' });
+    });
+    it('fill: treats the first positional as text when using semantic locator flags', async () => {
+        browserState.page.evaluate.mockResolvedValueOnce({
+            matches_n: 1,
+            entries: [
+                { nth: 0, ref: 35, tag: 'input', role: 'textbox', text: '', attrs: {}, visible: true },
+            ],
+        });
+        browserState.page.fillText.mockResolvedValueOnce({
+            filled: true,
+            verified: true,
+            expected: 'me@example.com',
+            actual: 'me@example.com',
+            length: 14,
+            matches_n: 1,
+            match_level: 'exact',
+        });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'fill', '--label', 'Email', 'me@example.com']);
+        expect(browserState.page.fillText).toHaveBeenCalledWith('35', 'me@example.com', {});
+        expect(lastJsonLog()).toMatchObject({ filled: true, verified: true, target: '35', text: 'me@example.com' });
+    });
+    it('drag: resolves source and target from prefixed semantic locators', async () => {
+        browserState.page.evaluate
+            .mockResolvedValueOnce({
+            matches_n: 1,
+            entries: [
+                { nth: 0, ref: 40, tag: 'div', role: 'button', text: 'Card A', attrs: {}, visible: true },
+            ],
+        })
+            .mockResolvedValueOnce({
+            matches_n: 1,
+            entries: [
+                { nth: 0, ref: 41, tag: 'div', role: 'region', text: 'Done', attrs: {}, visible: true },
+            ],
+        });
+        browserState.page.drag.mockResolvedValueOnce({
+            dragged: true,
+            source: '40',
+            target: '41',
+            source_matches_n: 1,
+            target_matches_n: 1,
+            source_match_level: 'exact',
+            target_match_level: 'exact',
+        });
+        const program = createProgram('', '');
+        await program.parseAsync([
+            'node',
+            'opencli',
+            'browser',
+            'drag',
+            '--from-role',
+            'button',
+            '--from-name',
+            'Card A',
+            '--to-role',
+            'region',
+            '--to-name',
+            'Done',
+        ]);
+        expect(browserState.page.drag).toHaveBeenCalledWith('40', '41', { from: {}, to: {} });
+        expect(lastJsonLog()).toMatchObject({ dragged: true, source: '40', target: '41' });
+    });
     it('surfaces match_level=stable when resolver falls back to fingerprint match', async () => {
         browserState.page.click.mockResolvedValueOnce({ matches_n: 1, match_level: 'stable' });
         const program = createProgram('', '');
@@ -1773,6 +2336,116 @@ describe('browser click/type commands', () => {
         expect(browserState.page.click).not.toHaveBeenCalled();
         expect(process.exitCode).toBeDefined();
     });
+    it('hover: delegates to page.hover and emits a structured envelope', async () => {
+        browserState.page.hover.mockResolvedValueOnce({ matches_n: 2, match_level: 'exact' });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'hover', '.menu', '--nth', '1']);
+        expect(browserState.page.hover).toHaveBeenCalledWith('.menu', { nth: 1 });
+        expect(lastJsonLog()).toEqual({ hovered: true, target: '.menu', matches_n: 2, match_level: 'exact' });
+    });
+    it('focus: delegates to page.focus and reports whether the element took focus', async () => {
+        browserState.page.focus.mockResolvedValueOnce({ focused: true, matches_n: 1, match_level: 'stable' });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'focus', '7']);
+        expect(browserState.page.focus).toHaveBeenCalledWith('7', {});
+        expect(lastJsonLog()).toEqual({ focused: true, target: '7', matches_n: 1, match_level: 'stable' });
+    });
+    it('dblclick: delegates to page.dblClick and emits a structured envelope', async () => {
+        browserState.page.dblClick.mockResolvedValueOnce({ matches_n: 1, match_level: 'exact' });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'dblclick', '#row']);
+        expect(browserState.page.dblClick).toHaveBeenCalledWith('#row', {});
+        expect(lastJsonLog()).toEqual({ dblclicked: true, target: '#row', matches_n: 1, match_level: 'exact' });
+    });
+    it('check: ensures target is checked through page.setChecked', async () => {
+        browserState.page.setChecked.mockResolvedValueOnce({
+            checked: true,
+            changed: true,
+            matches_n: 2,
+            match_level: 'exact',
+            kind: 'checkbox',
+        });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'check', '.todo', '--nth', '1']);
+        expect(browserState.page.setChecked).toHaveBeenCalledWith('.todo', true, { nth: 1 });
+        expect(lastJsonLog()).toEqual({ checked: true, changed: true, target: '.todo', matches_n: 2, match_level: 'exact', kind: 'checkbox' });
+    });
+    it('uncheck: ensures target is unchecked through page.setChecked', async () => {
+        browserState.page.setChecked.mockResolvedValueOnce({
+            checked: false,
+            changed: false,
+            matches_n: 1,
+            match_level: 'stable',
+            kind: 'checkbox',
+        });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'uncheck', '#subscribe']);
+        expect(browserState.page.setChecked).toHaveBeenCalledWith('#subscribe', false, {});
+        expect(lastJsonLog()).toEqual({ checked: false, changed: false, target: '#subscribe', matches_n: 1, match_level: 'stable', kind: 'checkbox' });
+    });
+    it('upload: validates local files and delegates to page.uploadFiles', async () => {
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-upload-'));
+        const file = path.join(dir, 'receipt.pdf');
+        fs.writeFileSync(file, 'pdf');
+        browserState.page.uploadFiles.mockResolvedValueOnce({
+            uploaded: true,
+            files: 1,
+            file_names: ['receipt.pdf'],
+            target: '#file',
+            matches_n: 1,
+            match_level: 'exact',
+            multiple: false,
+        });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'upload', '#file', file]);
+        expect(browserState.page.uploadFiles).toHaveBeenCalledWith('#file', [file], {});
+        expect(lastJsonLog()).toEqual({
+            uploaded: true,
+            files: 1,
+            file_names: ['receipt.pdf'],
+            target: '#file',
+            matches_n: 1,
+            match_level: 'exact',
+            multiple: false,
+        });
+    });
+    it('upload: rejects missing files before touching the page', async () => {
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'upload', '#file', '/tmp/opencli-missing-file']);
+        expect(lastJsonLog().error.code).toBe('file_not_found');
+        expect(browserState.page.uploadFiles).not.toHaveBeenCalled();
+        expect(process.exitCode).toBeDefined();
+    });
+    it('drag: delegates to page.drag and forwards source/target nth options', async () => {
+        browserState.page.drag.mockResolvedValueOnce({
+            dragged: true,
+            source: '.card',
+            target: '.lane',
+            source_matches_n: 3,
+            target_matches_n: 2,
+            source_match_level: 'exact',
+            target_match_level: 'stable',
+        });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'drag', '.card', '.lane', '--from-nth', '2', '--to-nth', '1']);
+        expect(browserState.page.drag).toHaveBeenCalledWith('.card', '.lane', { from: { nth: 2 }, to: { nth: 1 } });
+        expect(lastJsonLog()).toEqual({
+            dragged: true,
+            source: '.card',
+            target: '.lane',
+            source_matches_n: 3,
+            target_matches_n: 2,
+            source_match_level: 'exact',
+            target_match_level: 'stable',
+        });
+    });
+    it('drag: rejects malformed --from-nth before touching the page', async () => {
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'drag', '.card', '.lane', '--from-nth', 'abc']);
+        expect(lastJsonLog().error.code).toBe('usage_error');
+        expect(browserState.page.drag).not.toHaveBeenCalled();
+        expect(process.exitCode).toBeDefined();
+    });
     it('type: clicks, waits, then typeText — emits {typed, text, target, matches_n, match_level, autocomplete}', async () => {
         browserState.page.click.mockResolvedValueOnce({ matches_n: 1, match_level: 'exact' });
         browserState.page.typeText.mockResolvedValueOnce({ matches_n: 1, match_level: 'exact' });
@@ -1906,6 +2579,21 @@ describe('browser select command', () => {
         expect(err.available).toEqual(['US', 'CA']);
         expect(process.exitCode).toBeDefined();
     });
+    it('select: treats the first positional as option when using semantic locator flags', async () => {
+        const evalMock = browserState.page.evaluate;
+        evalMock
+            .mockResolvedValueOnce({
+            matches_n: 1,
+            entries: [
+                { nth: 0, ref: 36, tag: 'select', role: 'combobox', text: 'Country', attrs: {}, visible: true },
+            ],
+        })
+            .mockResolvedValueOnce({ ok: true, matches_n: 1, match_level: 'exact' })
+            .mockResolvedValueOnce({ selected: 'Uruguay' });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'select', '--label', 'Country', 'Uruguay']);
+        expect(lastJsonLog()).toEqual({ selected: 'Uruguay', target: '36', matches_n: 1, match_level: 'exact' });
+    });
     it('surfaces selector_ambiguous from the resolver before calling selectResolvedJs', async () => {
         browserState.page.evaluate.mockResolvedValueOnce({
             ok: false,