@jackwener/opencli 1.7.14 → 1.7.16

package/dist/src/cli.test.js

@@ -337,6 +337,236 @@ describe('createProgram root help descriptions', () => {
                 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).toEqual(expect.arrayContaining([
+                expect.objectContaining({
+                    name: 'workspace',
+                    flags: '--workspace <name>',
+                    takes_value: 'required',
+                }),
+                expect.objectContaining({
+                    name: 'window',
+                    flags: '--window <mode>',
+                    takes_value: 'required',
+                }),
+                expect.objectContaining({
+                    name: 'keepTab',
+                    flags: '--keep-tab <bool>',
+                    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', 'window', 'keepTab']);
+            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', 'window', 'keepTab']);
+            expect(data.global_options.map((option) => option.name)).toContain('profile');
+        }
+        finally {
+            process.argv = argv;
+        }
+    });
+    it('renders daemon namespace structured help with leaves and global options', () => {
+        const argv = process.argv;
+        try {
+            const program = createProgram('', '');
+            const daemon = program.commands.find(cmd => cmd.name() === 'daemon');
+            expect(daemon).toBeTruthy();
+            process.argv = ['node', 'opencli', 'daemon', '--help', '-f', 'yaml'];
+            const data = yaml.load(daemon.helpInformation());
+            expect(data).toMatchObject({
+                namespace: 'daemon',
+                command: 'opencli daemon',
+                usage: 'opencli daemon <command> [args] [options]',
+                description: 'Manage the opencli daemon',
+                command_count: 3,
+                namespace_options: [],
+                structured_help: { usage: 'opencli daemon --help -f yaml' },
+            });
+            expect(data.commands.map((cmd) => cmd.name)).toEqual(['restart', 'status', 'stop']);
+            expect(data.global_options.map((option) => option.name)).toEqual(expect.arrayContaining(['version', 'profile']));
+        }
+        finally {
+            process.argv = argv;
+        }
+    });
+    it('renders plugin namespace structured help with positional + option leaves', () => {
+        const argv = process.argv;
+        try {
+            const program = createProgram('', '');
+            const plugin = program.commands.find(cmd => cmd.name() === 'plugin');
+            expect(plugin).toBeTruthy();
+            process.argv = ['node', 'opencli', 'plugin', '--help', '-f', 'yaml'];
+            const data = yaml.load(plugin.helpInformation());
+            expect(data).toMatchObject({
+                namespace: 'plugin',
+                command: 'opencli plugin',
+                description: 'Manage opencli plugins',
+                namespace_options: [],
+            });
+            expect(data.commands.map((cmd) => cmd.name)).toEqual(['create', 'install', 'list', 'uninstall', 'update']);
+            const update = data.commands.find((cmd) => cmd.name === 'update');
+            expect(update).toMatchObject({
+                usage: 'opencli plugin update [name] [options]',
+                positionals: [{ name: 'name' }],
+            });
+            expect(update.command_options.map((option) => option.name)).toEqual(['all']);
+        }
+        finally {
+            process.argv = argv;
+        }
+    });
+    it('renders adapter namespace structured help preserving original description after applyRootSubcommandSummaries', () => {
+        const argv = process.argv;
+        try {
+            const program = createProgram('', '');
+            const adapter = program.commands.find(cmd => cmd.name() === 'adapter');
+            expect(adapter).toBeTruthy();
+            process.argv = ['node', 'opencli', 'adapter', '--help', '-f', 'yaml'];
+            const data = yaml.load(adapter.helpInformation());
+            // applyRootSubcommandSummaries() rewrites .description() to a child-name listing;
+            // structured help must surface the original product description via the snapshot.
+            expect(data.description).toBe('Manage CLI adapters');
+            expect(data.commands.map((cmd) => cmd.name)).toEqual(['eject', 'reset', 'status']);
+            const reset = data.commands.find((cmd) => cmd.name === 'reset');
+            expect(reset).toMatchObject({
+                usage: 'opencli adapter reset [site] [options]',
+                positionals: [{ name: 'site' }],
+            });
+            expect(reset.command_options.map((option) => option.name)).toEqual(['all']);
+        }
+        finally {
+            process.argv = argv;
+        }
+    });
+    it('renders profile namespace structured help including required positionals', () => {
+        const argv = process.argv;
+        try {
+            const program = createProgram('', '');
+            const profile = program.commands.find(cmd => cmd.name() === 'profile');
+            expect(profile).toBeTruthy();
+            process.argv = ['node', 'opencli', 'profile', '--help', '-f', 'yaml'];
+            const data = yaml.load(profile.helpInformation());
+            expect(data).toMatchObject({
+                namespace: 'profile',
+                description: 'Manage Browser Bridge Chrome profiles',
+                command_count: 3,
+            });
+            expect(data.commands.map((cmd) => cmd.name)).toEqual(['list', 'rename', 'use']);
+            const rename = data.commands.find((cmd) => cmd.name === 'rename');
+            expect(rename).toMatchObject({
+                usage: 'opencli profile rename <contextId> <alias> [options]',
+                positionals: [
+                    { name: 'contextId', required: true },
+                    { name: 'alias', required: true },
+                ],
+            });
+        }
+        finally {
+            process.argv = argv;
+        }
+    });
 });
 describe('resolveBrowserVerifyInvocation', () => {
     it('prefers the built entry declared in package metadata', () => {
@@ -607,6 +837,8 @@ describe('browser tab targeting commands', () => {
         stderrSpy.mockClear();
         mockBrowserConnect.mockClear();
         mockBrowserClose.mockReset().mockResolvedValue(undefined);
+        delete process.env.OPENCLI_WINDOW;
+        delete process.env.OPENCLI_KEEP_TAB;
         mockBindTab.mockReset().mockResolvedValue({
             workspace: 'bound:default',
             page: 'tab-2',
@@ -636,7 +868,17 @@ 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([]),
+            closeWindow: vi.fn().mockResolvedValue(undefined),
+            waitForDownload: vi.fn().mockResolvedValue({
+                downloaded: true,
+                filename: '/tmp/receipt.pdf',
+                url: 'https://app.example/receipt.pdf',
+                state: 'complete',
+                elapsedMs: 10,
+            }),
         };
     });
     function lastJsonLog() {
@@ -672,8 +914,90 @@ describe('browser tab targeting commands', () => {
     it('runs browser commands against an explicit bound workspace', async () => {
         const program = createProgram('', '');
         await program.parseAsync(['node', 'opencli', 'browser', '--workspace', 'bound:default', 'state']);
-        expect(mockBrowserConnect).toHaveBeenCalledWith({ timeout: 30, workspace: 'bound:default' });
+        expect(mockBrowserConnect).toHaveBeenCalledWith({ timeout: 30, workspace: 'bound:default', windowMode: 'foreground' });
+        expect(browserState.page?.snapshot).toHaveBeenCalled();
+    });
+    it('passes browser --window through Commander options without relying on env pre-processing', async () => {
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', '--window', 'background', 'state']);
+        expect(mockBrowserConnect).toHaveBeenCalledWith({ timeout: 30, workspace: 'browser:default', windowMode: 'background' });
+        expect(browserState.page?.snapshot).toHaveBeenCalled();
+    });
+    it('releases non-bound browser tab leases when --keep-tab=false', async () => {
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', '--keep-tab', 'false', 'state']);
         expect(browserState.page?.snapshot).toHaveBeenCalled();
+        expect(browserState.page?.closeWindow).toHaveBeenCalled();
+    });
+    it('does not auto-release explicit bound workspaces when --keep-tab=false', async () => {
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', '--workspace', 'bound:default', '--keep-tab', 'false', 'state']);
+        expect(browserState.page?.snapshot).toHaveBeenCalled();
+        expect(browserState.page?.closeWindow).not.toHaveBeenCalled();
+        expect(stderrSpy.mock.calls.flat().join('')).toContain('--window/--keep-tab ignored for bound:* workspaces');
+    });
+    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 = {
@@ -1036,6 +1360,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(() => { });
@@ -1687,6 +2060,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('', '');
@@ -1742,6 +2134,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' });
@@ -1797,6 +2223,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,
@@ -1817,6 +2265,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('', '');
@@ -1863,6 +2468,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' });
@@ -1996,6 +2711,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,