@jackwener/opencli 1.7.14 → 1.7.15

package/dist/src/cli.js

@@ -18,11 +18,11 @@ import { PKG_VERSION } from './version.js';
 import { printCompletionScript } from './completion.js';
 import { loadExternalClis, executeExternalCli, installExternalCli, registerExternalCli, isBinaryInstalled } from './external.js';
 import { registerAllCommands } from './commanderAdapter.js';
-import { classifyAdapter, formatRootAdapterHelpText, installStructuredHelp, rootHelpData } from './help.js';
+import { classifyAdapter, formatRootAdapterHelpText, installCommanderNamespaceStructuredHelp, installStructuredHelp, rootHelpData } from './help.js';
 import { EXIT_CODES, getErrorMessage, BrowserConnectError } from './errors.js';
 import { TargetError } from './browser/target-errors.js';
 import { resolveTargetJs, getTextResolvedJs, getValueResolvedJs, getAttributesResolvedJs, selectResolvedJs, isAutocompleteResolvedJs } from './browser/target-resolver.js';
-import { buildFindJs, isFindError } from './browser/find.js';
+import { buildFindJs, buildSemanticFindJs, isFindError } from './browser/find.js';
 import { inferShape } from './browser/shape.js';
 import { assignKeys } from './browser/network-key.js';
 import { DEFAULT_TTL_MS, findEntry, loadNetworkCache, saveNetworkCache } from './browser/network-cache.js';
@@ -373,6 +373,41 @@ function getPageScope(page) {
     const contextId = page.contextId;
     return getBrowserScope(getPageWorkspace(page), typeof contextId === 'string' && contextId.trim() ? contextId.trim() : undefined);
 }
+function snapshotMetricText(snapshot) {
+    return typeof snapshot === 'string' ? snapshot : JSON.stringify(snapshot, null, 2);
+}
+function snapshotMetrics(snapshot, elapsedMs) {
+    const text = snapshotMetricText(snapshot);
+    const interactiveMatch = text.match(/^interactive:\s*(\d+)\s*$/m);
+    return {
+        ok: true,
+        chars: text.length,
+        bytes: Buffer.byteLength(text, 'utf8'),
+        lines: text ? text.split(/\r?\n/).length : 0,
+        approx_tokens: Math.ceil(text.length / 4),
+        refs: (text.match(/(^|\n)\s*\[\d+\]/g) ?? []).length,
+        frame_sections: (text.match(/(^|\n)frame /g) ?? []).length,
+        ...(interactiveMatch ? { interactive: Number(interactiveMatch[1]) } : {}),
+        elapsed_ms: elapsedMs,
+    };
+}
+async function snapshotSourceMetrics(page, source) {
+    const started = Date.now();
+    try {
+        const snapshot = await page.snapshot({ viewportExpand: 2000, source });
+        return snapshotMetrics(snapshot, Date.now() - started);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            elapsed_ms: Date.now() - started,
+            error: {
+                ...(err instanceof Error && 'code' in err ? { code: String(err.code) } : {}),
+                message: err instanceof Error ? err.message : String(err),
+            },
+        };
+    }
+}
 function resolveBrowserTabTarget(targetId, opts) {
     if (typeof targetId === 'string' && targetId.trim())
         return targetId.trim();
@@ -549,6 +584,7 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
         .command('browser')
         .option('--workspace <name>', 'Browser workspace to use (default: browser:default; bound tabs use bound:<name>)')
         .description('Browser control — navigate, click, type, extract, wait (no LLM needed)');
+    const originalBrowserDescription = browser.description();
     /**
      * Resolve a `<target>` (numeric ref or CSS selector) via the unified resolver.
      * Returns the CSS match count so callers can propagate `matches_n` into the
@@ -887,9 +923,33 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
         console.log(`Scrolled ${direction}`);
     }));
     // ── Inspect ──
-    addBrowserTabOption(browser.command('state').description('Page state: URL, title, interactive elements with [N] indices'))
-        .action(browserAction(async (page) => {
-        const snapshot = await page.snapshot({ viewportExpand: 2000 });
+    addBrowserTabOption(browser.command('state').description('Page state: URL, title, interactive elements with [N] indices')
+        .option('--source <source>', 'Snapshot backend: dom (default) or ax prototype', 'dom')
+        .option('--compare-sources', 'Print DOM vs AX snapshot metrics for observation promotion decisions', false))
+        .action(browserAction(async (page, opts) => {
+        if (opts.compareSources === true) {
+            const [dom, ax] = await Promise.all([
+                snapshotSourceMetrics(page, 'dom'),
+                snapshotSourceMetrics(page, 'ax'),
+            ]);
+            console.log(JSON.stringify({
+                url: await page.getCurrentUrl?.() ?? '',
+                sources: { dom, ax },
+            }, null, 2));
+            return;
+        }
+        const source = String(opts.source ?? 'dom').toLowerCase();
+        if (source !== 'dom' && source !== 'ax') {
+            console.log(JSON.stringify({
+                error: {
+                    code: 'invalid_source',
+                    message: `--source must be "dom" or "ax", got "${opts.source}"`,
+                },
+            }, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        const snapshot = await page.snapshot({ viewportExpand: 2000, source: source });
         const url = await page.getCurrentUrl?.() ?? '';
         console.log(`URL: ${url}\n`);
         console.log(typeof snapshot === 'string' ? snapshot : JSON.stringify(snapshot, null, 2));
@@ -901,21 +961,26 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
     }));
     addBrowserTabOption(browser.command('screenshot').argument('[path]', 'Save to file (base64 if omitted)'))
         .option('--full-page', 'Capture the full scrollable page, not just the viewport', false)
+        .option('--annotate', 'Overlay visible browser state ref labels on the screenshot', false)
         .option('--width <n>', 'Override viewport width in CSS pixels for this screenshot only', (v) => parseScreenshotDim(v, 'width'))
         .option('--height <n>', 'Override viewport height in CSS pixels for this screenshot only (ignored with --full-page)', (v) => parseScreenshotDim(v, 'height'))
         .description('Take screenshot')
         .action(browserAction(async (page, path, opts) => {
         const shotOpts = {
             fullPage: opts.fullPage === true,
+            annotate: opts.annotate === true,
             width: opts.width,
             height: opts.height,
         };
+        const capture = opts.annotate === true
+            ? (page.annotatedScreenshot ?? page.screenshot).bind(page)
+            : page.screenshot.bind(page);
         if (path) {
-            await page.screenshot({ ...shotOpts, path });
+            await capture({ ...shotOpts, path });
             console.log(`Screenshot saved to: ${path}`);
         }
         else {
-            console.log(await page.screenshot({ ...shotOpts, format: 'png' }));
+            console.log(await capture({ ...shotOpts, format: 'png' }));
         }
     }));
     addBrowserTabOption(browser.command('console'))
@@ -1053,18 +1118,200 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
     // `browser find --css <sel>` lets agents jump straight from a semantic
     // selector to a JSON list of matching elements, without having to parse
     // the free-text state snapshot to recover indices.
-    addBrowserTabOption(browser.command('find')
+    const addSemanticLocatorOptions = (cmd) => cmd
+        .option('--role <role>', 'Semantic role (button, link, textbox, option, etc.)')
+        .option('--name <text>', 'Accessible name contains text (aria-label, label, title, placeholder, or visible text)')
+        .option('--label <text>', 'Associated label contains text')
+        .option('--text <text>', 'Visible text contains text')
+        .option('--testid <id>', 'data-testid / data-test / test-id contains id');
+    const addPrefixedSemanticLocatorOptions = (cmd, prefix) => cmd
+        .option(`--${prefix}-role <role>`, `${prefix} semantic role`)
+        .option(`--${prefix}-name <text>`, `${prefix} accessible name contains text`)
+        .option(`--${prefix}-label <text>`, `${prefix} associated label contains text`)
+        .option(`--${prefix}-text <text>`, `${prefix} visible text contains text`)
+        .option(`--${prefix}-testid <id>`, `${prefix} data-testid / data-test / test-id contains id`);
+    const semanticLocatorFromOptions = (opts) => {
+        const locator = {};
+        for (const key of ['role', 'name', 'label', 'text', 'testid']) {
+            const value = opts[key];
+            if (typeof value === 'string' && value.trim())
+                locator[key] = value.trim();
+        }
+        return Object.keys(locator).length > 0 ? locator : null;
+    };
+    const prefixedSemanticLocatorFromOptions = (opts, prefix) => {
+        const locator = {};
+        const map = {
+            role: `${prefix}Role`,
+            name: `${prefix}Name`,
+            label: `${prefix}Label`,
+            text: `${prefix}Text`,
+            testid: `${prefix}Testid`,
+        };
+        for (const key of ['role', 'name', 'label', 'text', 'testid']) {
+            const value = opts[map[key]];
+            if (typeof value === 'string' && value.trim())
+                locator[key] = value.trim();
+        }
+        return Object.keys(locator).length > 0 ? locator : null;
+    };
+    const semanticTargetFromLocator = async (page, locator, mode) => {
+        const result = await page.evaluate(buildSemanticFindJs({ ...locator, limit: 6 }));
+        if (isFindError(result))
+            return result;
+        if (mode === 'write' && result.matches_n !== 1) {
+            return {
+                error: {
+                    code: 'semantic_ambiguous',
+                    message: `Semantic locator matched ${result.matches_n} elements; write actions require a unique target.`,
+                    hint: 'Add --name/--label/--text/--testid or use browser find with a narrower locator.',
+                    matches_n: result.matches_n,
+                    entries: result.entries,
+                },
+            };
+        }
+        const first = result.entries[0];
+        if (!first) {
+            return {
+                error: {
+                    code: 'semantic_not_found',
+                    message: 'Semantic locator matched 0 elements',
+                    hint: 'Try browser state, --source ax, or relax the semantic locator.',
+                },
+            };
+        }
+        const target = String(first.ref);
+        if (mode === 'read') {
+            return {
+                target,
+                ...(result.matches_n > 1 ? { total_matches: result.matches_n } : {}),
+            };
+        }
+        return target;
+    };
+    const semanticTargetFromOptions = async (page, opts, mode) => {
+        const locator = semanticLocatorFromOptions(opts);
+        if (!locator)
+            return null;
+        return semanticTargetFromLocator(page, locator, mode);
+    };
+    const resolveExplicitOrSemanticTarget = async (page, target, opts, mode) => {
+        const explicit = typeof target === 'string' && target.trim() ? target.trim() : '';
+        const hasSemantic = !!semanticLocatorFromOptions(opts);
+        if (explicit && hasSemantic) {
+            return {
+                error: {
+                    code: 'usage_error',
+                    message: 'Pass either <target> or semantic locator flags, not both.',
+                },
+            };
+        }
+        if (explicit)
+            return explicit;
+        const semantic = await semanticTargetFromOptions(page, opts, mode);
+        if (semantic)
+            return semantic;
+        return {
+            error: {
+                code: 'usage_error',
+                message: 'Missing target. Pass a numeric ref/CSS selector, or semantic flags like --role button --name Submit.',
+            },
+        };
+    };
+    const printTargetResolutionError = (resolved) => {
+        console.log(JSON.stringify(resolved, null, 2));
+        process.exitCode = EXIT_CODES.USAGE_ERROR;
+    };
+    const resolveWriteTargetOrPrint = async (page, target, opts) => {
+        const resolvedTarget = await resolveExplicitOrSemanticTarget(page, target, opts, 'write');
+        if (typeof resolvedTarget === 'string')
+            return resolvedTarget;
+        if ('error' in resolvedTarget)
+            printTargetResolutionError(resolvedTarget);
+        return null;
+    };
+    const resolveWriteTargetAndValueOrPrint = async (page, targetOrValue, value, opts, valueLabel) => {
+        const hasSemantic = !!semanticLocatorFromOptions(opts);
+        if (hasSemantic && value !== undefined) {
+            printTargetResolutionError({
+                error: {
+                    code: 'usage_error',
+                    message: `When using semantic locator flags, pass only <${valueLabel}> as the positional argument.`,
+                },
+            });
+            return null;
+        }
+        const resolvedValue = hasSemantic ? targetOrValue : value;
+        if (resolvedValue === undefined) {
+            printTargetResolutionError({
+                error: {
+                    code: 'usage_error',
+                    message: `Missing ${valueLabel}.`,
+                    hint: hasSemantic
+                        ? `With semantic locator flags, pass the ${valueLabel} as the only positional argument.`
+                        : `Pass both a target and ${valueLabel}.`,
+                },
+            });
+            return null;
+        }
+        const resolvedTarget = await resolveWriteTargetOrPrint(page, hasSemantic ? undefined : targetOrValue, opts);
+        if (!resolvedTarget)
+            return null;
+        return { target: resolvedTarget, value: String(resolvedValue) };
+    };
+    const resolvePrefixedWriteTargetOrPrint = async (page, target, opts, prefix, label) => {
+        const explicit = typeof target === 'string' && target.trim() ? target.trim() : '';
+        const locator = prefixedSemanticLocatorFromOptions(opts, prefix);
+        if (explicit && locator) {
+            printTargetResolutionError({
+                error: {
+                    code: 'usage_error',
+                    message: `Pass either <${label}> or --${prefix}-* semantic locator flags, not both.`,
+                },
+            });
+            return null;
+        }
+        if (explicit)
+            return explicit;
+        if (locator) {
+            const resolved = await semanticTargetFromLocator(page, locator, 'write');
+            if (typeof resolved === 'string')
+                return resolved;
+            if ('error' in resolved)
+                printTargetResolutionError(resolved);
+            return null;
+        }
+        printTargetResolutionError({
+            error: {
+                code: 'usage_error',
+                message: `Missing ${label}. Pass a numeric ref/CSS selector, or --${prefix}-role/--${prefix}-name semantic flags.`,
+            },
+        });
+        return null;
+    };
+    addBrowserTabOption(addSemanticLocatorOptions(browser.command('find'))
         .option('--css <selector>', 'CSS selector (required)')
         .option('--limit <n>', 'Max entries returned', '50')
         .option('--text-max <n>', 'Max chars of trimmed text per entry', '120')
-        .description('Find DOM elements by CSS selector — returns JSON {matches_n, entries[]}'))
+        .description('Find DOM elements by CSS or semantic locator — returns JSON {matches_n, entries[]}'))
         .action(browserAction(async (page, opts) => {
-        if (!opts.css || typeof opts.css !== 'string') {
+        const locator = semanticLocatorFromOptions(opts);
+        if ((!opts.css || typeof opts.css !== 'string') && !locator) {
+            console.log(JSON.stringify({
+                error: {
+                    code: 'usage_error',
+                    message: '--css <selector> or a semantic locator flag is required',
+                    hint: 'Examples: opencli browser find --css ".btn.primary"; opencli browser find --role button --name Save',
+                },
+            }, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        if (opts.css && locator) {
             console.log(JSON.stringify({
                 error: {
                     code: 'usage_error',
-                    message: '--css <selector> is required',
-                    hint: 'Example: opencli browser find --css ".btn.primary"',
+                    message: 'Pass either --css or semantic locator flags, not both.',
                 },
             }, null, 2));
             process.exitCode = EXIT_CODES.USAGE_ERROR;
@@ -1082,10 +1329,16 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
             process.exitCode = EXIT_CODES.USAGE_ERROR;
             return;
         }
-        const result = await page.evaluate(buildFindJs(opts.css, {
-            limit: limit ?? undefined,
-            textMax: textMax ?? undefined,
-        }));
+        const result = await page.evaluate(locator
+            ? buildSemanticFindJs({
+                ...locator,
+                limit: limit ?? undefined,
+                textMax: textMax ?? undefined,
+            })
+            : buildFindJs(opts.css, {
+                limit: limit ?? undefined,
+                textMax: textMax ?? undefined,
+            }));
         if (isFindError(result)) {
             console.log(JSON.stringify(result, null, 2));
             process.exitCode = EXIT_CODES.GENERIC_ERROR;
@@ -1112,13 +1365,21 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
     // or a CSS selector. On multi-match CSS, the first element wins and the real
     // match count is exposed via `matches_n`; `--nth <n>` picks a specific one.
     const runGetCommand = async (page, target, opts, evalJs, field) => {
+        const resolvedTarget = await resolveExplicitOrSemanticTarget(page, target, opts, 'read');
+        if (typeof resolvedTarget !== 'string' && 'error' in resolvedTarget) {
+            console.log(JSON.stringify(resolvedTarget, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        const targetRef = typeof resolvedTarget === 'string' ? resolvedTarget : resolvedTarget.target;
+        const totalMatches = typeof resolvedTarget === 'string' ? undefined : resolvedTarget.total_matches;
         const nth = parseNthFlag(opts.nth);
         if (nth && typeof nth === 'object' && 'error' in nth) {
             console.log(JSON.stringify({ error: { code: 'usage_error', message: nth.error } }, null, 2));
             process.exitCode = EXIT_CODES.USAGE_ERROR;
             return;
         }
-        const { matches_n, match_level } = await resolveRef(page, String(target), {
+        const { matches_n, match_level } = await resolveRef(page, targetRef, {
             firstOnMulti: nth === null,
             ...(typeof nth === 'number' ? { nth } : {}),
         });
@@ -1137,18 +1398,23 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
         else {
             value = raw ?? null;
         }
-        console.log(JSON.stringify({ value, matches_n, match_level }, null, 2));
+        console.log(JSON.stringify({
+            value,
+            matches_n,
+            match_level,
+            ...(totalMatches && totalMatches > 1 ? { total_matches: totalMatches } : {}),
+        }, null, 2));
     };
-    addBrowserTabOption(get.command('text')
-        .argument('<target>', 'Numeric ref (from browser state / find) or CSS selector')
+    addBrowserTabOption(addSemanticLocatorOptions(get.command('text'))
+        .argument('[target]', 'Numeric ref (from browser state / find), CSS selector, or omit when using --role/--name/etc.')
         .option('--nth <n>', 'Pick the nth match (0-based) when <target> is a multi-match CSS selector')
         .description('Element text content — JSON envelope {value, matches_n}'))
-        .action(browserAction(async (page, target, opts) => runGetCommand(page, String(target), opts ?? {}, getTextResolvedJs(), 'text')));
-    addBrowserTabOption(get.command('value')
-        .argument('<target>', 'Numeric ref (from browser state / find) or CSS selector')
+        .action(browserAction(async (page, target, opts) => runGetCommand(page, target, opts ?? {}, getTextResolvedJs(), 'text')));
+    addBrowserTabOption(addSemanticLocatorOptions(get.command('value'))
+        .argument('[target]', 'Numeric ref (from browser state / find), CSS selector, or omit when using --role/--name/etc.')
         .option('--nth <n>', 'Pick the nth match (0-based) when <target> is a multi-match CSS selector')
         .description('Input/textarea value — JSON envelope {value, matches_n}'))
-        .action(browserAction(async (page, target, opts) => runGetCommand(page, String(target), opts ?? {}, getValueResolvedJs(), 'value')));
+        .action(browserAction(async (page, target, opts) => runGetCommand(page, target, opts ?? {}, getValueResolvedJs(), 'value')));
     addBrowserTabOption(get.command('html')
         .option('--selector <css>', 'CSS selector scope (first match)')
         .option('--as <format>', 'Output format: "html" (default) or "json" for structured tree', 'html')
@@ -1263,11 +1529,11 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
         }
         console.log(html);
     }));
-    addBrowserTabOption(get.command('attributes')
-        .argument('<target>', 'Numeric ref (from browser state / find) or CSS selector')
+    addBrowserTabOption(addSemanticLocatorOptions(get.command('attributes'))
+        .argument('[target]', 'Numeric ref (from browser state / find), CSS selector, or omit when using --role/--name/etc.')
         .option('--nth <n>', 'Pick the nth match (0-based) when <target> is a multi-match CSS selector')
         .description('Element attributes — JSON envelope {value, matches_n}'))
-        .action(browserAction(async (page, target, opts) => runGetCommand(page, String(target), opts ?? {}, getAttributesResolvedJs(), 'attributes')));
+        .action(browserAction(async (page, target, opts) => runGetCommand(page, target, opts ?? {}, getAttributesResolvedJs(), 'attributes')));
     // ── Interact ──
     //
     // Write commands (`click/type/select`) share the same `<target>` contract
@@ -1290,26 +1556,73 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
             return { opts: { nth: parsed } };
         return { opts: {} };
     }
-    addBrowserTabOption(browser.command('click')
-        .argument('<target>', 'Numeric ref (from browser state / find) or CSS selector')
+    function resolveUploadFilePaths(rawFiles) {
+        const inputs = Array.isArray(rawFiles) ? rawFiles : [];
+        if (inputs.length === 0) {
+            return {
+                error: {
+                    code: 'usage_error',
+                    message: 'At least one file path is required.',
+                    hint: 'Example: opencli browser upload "input[type=file]" ./receipt.pdf',
+                },
+            };
+        }
+        const files = [];
+        for (const input of inputs) {
+            const raw = String(input);
+            const expanded = raw === '~' || raw.startsWith(`~${path.sep}`)
+                ? path.join(os.homedir(), raw.slice(2))
+                : raw;
+            const resolved = path.resolve(expanded);
+            if (!fs.existsSync(resolved)) {
+                return { error: { code: 'file_not_found', message: `File not found: ${resolved}` } };
+            }
+            const stat = fs.statSync(resolved);
+            if (!stat.isFile()) {
+                return { error: { code: 'not_a_file', message: `Not a regular file: ${resolved}` } };
+            }
+            files.push(resolved);
+        }
+        return { files };
+    }
+    function parseResolveFlag(raw, flag) {
+        const parsed = parseNthFlag(raw);
+        if (parsed && typeof parsed === 'object' && 'error' in parsed) {
+            return { error: parsed.error.replace('--nth', flag) };
+        }
+        if (typeof parsed === 'number')
+            return { opts: { nth: parsed } };
+        return { opts: {} };
+    }
+    addBrowserTabOption(addSemanticLocatorOptions(browser.command('click'))
+        .argument('[target]', 'Numeric ref (from browser state / find), CSS selector, or omit when using --role/--name/etc.')
         .option('--nth <n>', 'When <target> is a multi-match CSS selector, pick the nth match (0-based)')
         .description('Click element — JSON envelope {clicked, target, matches_n}'))
         .action(browserAction(async (page, target, opts) => {
+        const resolvedTarget = await resolveExplicitOrSemanticTarget(page, target, opts ?? {}, 'write');
+        if (typeof resolvedTarget !== 'string') {
+            console.log(JSON.stringify(resolvedTarget, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
         const parsed = nthToResolveOpts(opts?.nth);
         if ('error' in parsed) {
             console.log(JSON.stringify({ error: { code: 'usage_error', message: parsed.error } }, null, 2));
             process.exitCode = EXIT_CODES.USAGE_ERROR;
             return;
         }
-        const { matches_n, match_level } = await page.click(String(target), parsed.opts);
-        console.log(JSON.stringify({ clicked: true, target: String(target), matches_n, match_level }, null, 2));
+        const { matches_n, match_level } = await page.click(resolvedTarget, parsed.opts);
+        console.log(JSON.stringify({ clicked: true, target: resolvedTarget, matches_n, match_level }, null, 2));
     }));
-    addBrowserTabOption(browser.command('type')
-        .argument('<target>', 'Numeric ref (from browser state / find) or CSS selector')
-        .argument('<text>', 'Text to type')
+    addBrowserTabOption(addSemanticLocatorOptions(browser.command('type'))
+        .argument('[targetOrText]', 'Numeric ref/CSS target, or text when using --role/--name/etc.')
+        .argument('[text]', 'Text to type')
         .option('--nth <n>', 'When <target> is a multi-match CSS selector, pick the nth match (0-based)')
         .description('Click element, then type text — JSON envelope {typed, text, target, matches_n, autocomplete}'))
-        .action(browserAction(async (page, target, text, opts) => {
+        .action(browserAction(async (page, targetOrText, text, opts) => {
+        const resolved = await resolveWriteTargetAndValueOrPrint(page, targetOrText, text, opts ?? {}, 'text');
+        if (!resolved)
+            return;
         const parsed = nthToResolveOpts(opts?.nth);
         if ('error' in parsed) {
             console.log(JSON.stringify({ error: { code: 'usage_error', message: parsed.error } }, null, 2));
@@ -1317,42 +1630,199 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
             return;
         }
         // Click first (focuses the field), wait briefly, then type.
-        await page.click(String(target), parsed.opts);
+        await page.click(resolved.target, parsed.opts);
         await page.wait(0.3);
-        const { matches_n, match_level } = await page.typeText(String(target), String(text), parsed.opts);
+        const { matches_n, match_level } = await page.typeText(resolved.target, resolved.value, parsed.opts);
         // __resolved is already set by the resolver call inside page.typeText
         const isAutocomplete = await page.evaluate(isAutocompleteResolvedJs());
         if (isAutocomplete)
             await page.wait(0.4);
         console.log(JSON.stringify({
             typed: true,
-            text: String(text),
-            target: String(target),
+            text: resolved.value,
+            target: resolved.target,
             matches_n,
             match_level,
             autocomplete: !!isAutocomplete,
         }, null, 2));
     }));
-    addBrowserTabOption(browser.command('fill')
-        .argument('<target>', 'Numeric ref (from browser state / find) or CSS selector')
-        .argument('<text>', 'Text to set exactly')
+    addBrowserTabOption(addSemanticLocatorOptions(browser.command('hover'))
+        .argument('[target]', 'Numeric ref (from browser state / find), CSS selector, or omit when using --role/--name/etc.')
+        .option('--nth <n>', 'When <target> is a multi-match CSS selector, pick the nth match (0-based)')
+        .description('Move the mouse over an element — JSON envelope {hovered, target, matches_n}'))
+        .action(browserAction(async (page, target, opts) => {
+        if (typeof page.hover !== 'function')
+            throw new Error('browser hover is not supported by this browser backend');
+        const resolvedTarget = await resolveWriteTargetOrPrint(page, target, opts ?? {});
+        if (!resolvedTarget)
+            return;
+        const parsed = nthToResolveOpts(opts?.nth);
+        if ('error' in parsed) {
+            console.log(JSON.stringify({ error: { code: 'usage_error', message: parsed.error } }, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        const { matches_n, match_level } = await page.hover(resolvedTarget, parsed.opts);
+        console.log(JSON.stringify({ hovered: true, target: resolvedTarget, matches_n, match_level }, null, 2));
+    }));
+    addBrowserTabOption(addSemanticLocatorOptions(browser.command('focus'))
+        .argument('[target]', 'Numeric ref (from browser state / find), CSS selector, or omit when using --role/--name/etc.')
+        .option('--nth <n>', 'When <target> is a multi-match CSS selector, pick the nth match (0-based)')
+        .description('Focus an element — JSON envelope {focused, target, matches_n}'))
+        .action(browserAction(async (page, target, opts) => {
+        if (typeof page.focus !== 'function')
+            throw new Error('browser focus is not supported by this browser backend');
+        const resolvedTarget = await resolveWriteTargetOrPrint(page, target, opts ?? {});
+        if (!resolvedTarget)
+            return;
+        const parsed = nthToResolveOpts(opts?.nth);
+        if ('error' in parsed) {
+            console.log(JSON.stringify({ error: { code: 'usage_error', message: parsed.error } }, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        const { focused, matches_n, match_level } = await page.focus(resolvedTarget, parsed.opts);
+        console.log(JSON.stringify({ focused, target: resolvedTarget, matches_n, match_level }, null, 2));
+    }));
+    addBrowserTabOption(addSemanticLocatorOptions(browser.command('dblclick'))
+        .argument('[target]', 'Numeric ref (from browser state / find), CSS selector, or omit when using --role/--name/etc.')
+        .option('--nth <n>', 'When <target> is a multi-match CSS selector, pick the nth match (0-based)')
+        .description('Double-click element — JSON envelope {dblclicked, target, matches_n}'))
+        .action(browserAction(async (page, target, opts) => {
+        if (typeof page.dblClick !== 'function')
+            throw new Error('browser dblclick is not supported by this browser backend');
+        const resolvedTarget = await resolveWriteTargetOrPrint(page, target, opts ?? {});
+        if (!resolvedTarget)
+            return;
+        const parsed = nthToResolveOpts(opts?.nth);
+        if ('error' in parsed) {
+            console.log(JSON.stringify({ error: { code: 'usage_error', message: parsed.error } }, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        const { matches_n, match_level } = await page.dblClick(resolvedTarget, parsed.opts);
+        console.log(JSON.stringify({ dblclicked: true, target: resolvedTarget, matches_n, match_level }, null, 2));
+    }));
+    const runCheckCommand = async (page, target, opts, checked) => {
+        if (typeof page.setChecked !== 'function')
+            throw new Error(`browser ${checked ? 'check' : 'uncheck'} is not supported by this browser backend`);
+        const resolvedTarget = await resolveWriteTargetOrPrint(page, target, opts);
+        if (!resolvedTarget)
+            return;
+        const parsed = nthToResolveOpts(opts?.nth);
+        if ('error' in parsed) {
+            console.log(JSON.stringify({ error: { code: 'usage_error', message: parsed.error } }, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        const result = await page.setChecked(resolvedTarget, checked, parsed.opts);
+        console.log(JSON.stringify({
+            checked: result.checked,
+            changed: result.changed,
+            target: resolvedTarget,
+            matches_n: result.matches_n,
+            match_level: result.match_level,
+            ...(result.kind ? { kind: result.kind } : {}),
+        }, null, 2));
+    };
+    addBrowserTabOption(addSemanticLocatorOptions(browser.command('check'))
+        .argument('[target]', 'Numeric ref (from browser state / find), CSS selector, or omit when using --role/--name/etc.')
+        .option('--nth <n>', 'When <target> is a multi-match CSS selector, pick the nth match (0-based)')
+        .description('Ensure a checkbox/radio/aria-checked control is checked — JSON envelope {checked, changed, target, matches_n}'))
+        .action(browserAction(async (page, target, opts) => {
+        await runCheckCommand(page, target, opts ?? {}, true);
+    }));
+    addBrowserTabOption(addSemanticLocatorOptions(browser.command('uncheck'))
+        .argument('[target]', 'Numeric ref (from browser state / find), CSS selector, or omit when using --role/--name/etc.')
+        .option('--nth <n>', 'When <target> is a multi-match CSS selector, pick the nth match (0-based)')
+        .description('Ensure a checkbox/aria-checked control is unchecked — JSON envelope {checked, changed, target, matches_n}'))
+        .action(browserAction(async (page, target, opts) => {
+        await runCheckCommand(page, target, opts ?? {}, false);
+    }));
+    addBrowserTabOption(addSemanticLocatorOptions(browser.command('upload'))
+        .argument('[targetOrFile]', 'Numeric ref/CSS target, or first file when using --role/--name/etc.')
+        .argument('[files...]', 'Local file path(s) to attach')
+        .option('--nth <n>', 'When <target> is a multi-match CSS selector, pick the nth match (0-based)')
+        .description('Attach local files to a file input — JSON envelope {uploaded, files, file_names, target, matches_n}'))
+        .action(browserAction(async (page, targetOrFile, files, opts) => {
+        if (typeof page.uploadFiles !== 'function')
+            throw new Error('browser upload is not supported by this browser backend');
+        const hasSemantic = !!semanticLocatorFromOptions(opts ?? {});
+        const target = hasSemantic ? undefined : targetOrFile;
+        const resolvedTarget = await resolveWriteTargetOrPrint(page, target, opts ?? {});
+        if (!resolvedTarget)
+            return;
+        const parsed = nthToResolveOpts(opts?.nth);
+        if ('error' in parsed) {
+            console.log(JSON.stringify({ error: { code: 'usage_error', message: parsed.error } }, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        const rawFiles = hasSemantic
+            ? [targetOrFile, ...(Array.isArray(files) ? files : [])].filter((value) => value !== undefined)
+            : files;
+        const resolvedFiles = resolveUploadFilePaths(rawFiles);
+        if ('error' in resolvedFiles) {
+            console.log(JSON.stringify({ error: resolvedFiles.error }, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        const result = await page.uploadFiles(resolvedTarget, resolvedFiles.files, parsed.opts);
+        console.log(JSON.stringify(result, null, 2));
+    }));
+    addBrowserTabOption(addPrefixedSemanticLocatorOptions(addPrefixedSemanticLocatorOptions(browser.command('drag'), 'from'), 'to')
+        .argument('[source]', 'Numeric ref/CSS selector to drag from, or omit with --from-role/--from-name/etc.')
+        .argument('[target]', 'Numeric ref/CSS selector to drop onto, or omit with --to-role/--to-name/etc.')
+        .option('--from-nth <n>', 'When <source> is a multi-match CSS selector, pick the nth match (0-based)')
+        .option('--to-nth <n>', 'When <target> is a multi-match CSS selector, pick the nth match (0-based)')
+        .description('Drag one element to another — JSON envelope {dragged, source, target, source_matches_n, target_matches_n}'))
+        .action(browserAction(async (page, source, target, opts) => {
+        if (typeof page.drag !== 'function')
+            throw new Error('browser drag is not supported by this browser backend');
+        const resolvedSource = await resolvePrefixedWriteTargetOrPrint(page, source, opts ?? {}, 'from', 'source');
+        if (!resolvedSource)
+            return;
+        const resolvedTarget = await resolvePrefixedWriteTargetOrPrint(page, target, opts ?? {}, 'to', 'target');
+        if (!resolvedTarget)
+            return;
+        const from = parseResolveFlag(opts?.fromNth, '--from-nth');
+        if ('error' in from) {
+            console.log(JSON.stringify({ error: { code: 'usage_error', message: from.error } }, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        const to = parseResolveFlag(opts?.toNth, '--to-nth');
+        if ('error' in to) {
+            console.log(JSON.stringify({ error: { code: 'usage_error', message: to.error } }, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        const result = await page.drag(resolvedSource, resolvedTarget, { from: from.opts, to: to.opts });
+        console.log(JSON.stringify(result, null, 2));
+    }));
+    addBrowserTabOption(addSemanticLocatorOptions(browser.command('fill'))
+        .argument('[targetOrText]', 'Numeric ref/CSS target, or text when using --role/--name/etc.')
+        .argument('[text]', 'Text to set exactly')
         .option('--nth <n>', 'When <target> is a multi-match CSS selector, pick the nth match (0-based)')
         .description('Set input/textarea/contenteditable text exactly and verify the value — JSON envelope {filled, verified, text, actual}'))
-        .action(browserAction(async (page, target, text, opts) => {
+        .action(browserAction(async (page, targetOrText, text, opts) => {
+        const resolved = await resolveWriteTargetAndValueOrPrint(page, targetOrText, text, opts ?? {}, 'text');
+        if (!resolved)
+            return;
         const parsed = nthToResolveOpts(opts?.nth);
         if ('error' in parsed) {
             console.log(JSON.stringify({ error: { code: 'usage_error', message: parsed.error } }, null, 2));
             process.exitCode = EXIT_CODES.USAGE_ERROR;
             return;
         }
-        const result = await page.fillText(String(target), String(text), parsed.opts);
+        const result = await page.fillText(resolved.target, resolved.value, parsed.opts);
         if (!result.verified)
             process.exitCode = EXIT_CODES.GENERIC_ERROR;
         console.log(JSON.stringify({
             filled: result.filled,
             verified: result.verified,
-            target: String(target),
-            text: String(text),
+            target: resolved.target,
+            text: resolved.value,
             actual: result.actual,
             length: result.length,
             matches_n: result.matches_n,
@@ -1360,20 +1830,23 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
             ...(result.mode ? { mode: result.mode } : {}),
         }, null, 2));
     }));
-    addBrowserTabOption(browser.command('select')
-        .argument('<target>', 'Numeric ref (from browser state / find) or CSS selector of a <select> element')
-        .argument('<option>', 'Option text (or value) to select')
+    addBrowserTabOption(addSemanticLocatorOptions(browser.command('select'))
+        .argument('[targetOrOption]', 'Numeric ref/CSS target, or option text when using --role/--name/etc.')
+        .argument('[option]', 'Option text (or value) to select')
         .option('--nth <n>', 'When <target> is a multi-match CSS selector, pick the nth match (0-based)')
         .description('Select dropdown option — JSON envelope {selected, target, matches_n}'))
-        .action(browserAction(async (page, target, option, opts) => {
+        .action(browserAction(async (page, targetOrOption, option, opts) => {
+        const resolved = await resolveWriteTargetAndValueOrPrint(page, targetOrOption, option, opts ?? {}, 'option');
+        if (!resolved)
+            return;
         const parsed = nthToResolveOpts(opts?.nth);
         if ('error' in parsed) {
             console.log(JSON.stringify({ error: { code: 'usage_error', message: parsed.error } }, null, 2));
             process.exitCode = EXIT_CODES.USAGE_ERROR;
             return;
         }
-        const { matches_n, match_level } = await resolveRef(page, String(target), parsed.opts);
-        const result = await page.evaluate(selectResolvedJs(String(option)));
+        const { matches_n, match_level } = await resolveRef(page, resolved.target, parsed.opts);
+        const result = await page.evaluate(selectResolvedJs(resolved.value));
         if (result?.error) {
             // The select-specific "Not a <select>" / "Option not found" errors
             // are domain-level failures — emit a structured envelope so agents
@@ -1390,8 +1863,8 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
             return;
         }
         console.log(JSON.stringify({
-            selected: result?.selected ?? String(option),
-            target: String(target),
+            selected: result?.selected ?? resolved.value,
+            target: resolved.target,
             matches_n,
             match_level,
         }, null, 2));
@@ -1458,10 +1931,10 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
     }));
     // ── Wait commands ──
     addBrowserTabOption(browser.command('wait'))
-        .argument('<type>', 'selector, text, time, or xhr')
-        .argument('[value]', 'CSS selector, text string, seconds, or XHR URL regex')
+        .argument('<type>', 'selector, text, time, xhr, or download')
+        .argument('[value]', 'CSS selector, text string, seconds, XHR URL regex, or download filename/URL pattern')
         .option('--timeout <ms>', 'Timeout in milliseconds', '10000')
-        .description('Wait for selector, text, time, or matching XHR (e.g. wait selector ".loaded", wait text "Success", wait time 3, wait xhr "/api/search")')
+        .description('Wait for selector, text, time, matching XHR, or browser download (e.g. wait selector ".loaded", wait text "Success", wait time 3, wait xhr "/api/search", wait download receipt.pdf)')
         .action(browserAction(async (page, type, value, opts) => {
         const timeout = parseInt(opts.timeout, 10);
         if (type === 'time') {
@@ -1538,8 +2011,36 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
                 matched: { url: matched.url, status: matched.status, contentType: matched.ct },
             }, null, 2));
         }
+        else if (type === 'download') {
+            if (typeof page.waitForDownload !== 'function') {
+                console.log(JSON.stringify({
+                    error: {
+                        code: 'download_wait_unavailable',
+                        message: 'The active browser backend does not support download lifecycle waits.',
+                        hint: 'Use the Browser Bridge extension version 1.0.8 or newer, then retry the command.',
+                    },
+                }, null, 2));
+                process.exitCode = EXIT_CODES.GENERIC_ERROR;
+                return;
+            }
+            const result = await page.waitForDownload(String(value ?? ''), timeout);
+            if (!result.downloaded) {
+                const code = result.state === 'interrupted' && result.id !== undefined ? 'download_failed' : 'download_not_seen';
+                console.log(JSON.stringify({
+                    error: {
+                        code,
+                        message: result.error ?? `No download matched "${value ?? '*'}" within ${timeout}ms`,
+                        hint: 'Check the pattern against the expected filename or URL; use a longer --timeout if the download starts slowly.',
+                    },
+                    download: result,
+                }, null, 2));
+                process.exitCode = EXIT_CODES.GENERIC_ERROR;
+                return;
+            }
+            console.log(JSON.stringify(result, null, 2));
+        }
         else {
-            console.error(`Unknown wait type "${type}". Use: selector, text, time, or xhr`);
+            console.error(`Unknown wait type "${type}". Use: selector, text, time, xhr, or download`);
             process.exitCode = EXIT_CODES.USAGE_ERROR;
         }
     }));
@@ -2605,6 +3106,7 @@ cli({
     }
     const adapterGroups = { external: externalNames, apps, sites };
     const adapterNameSet = new Set([...externalNames, ...siteNames]);
+    installCommanderNamespaceStructuredHelp(browser, { globalCommand: program, description: originalBrowserDescription });
     program.configureHelp({
         visibleCommands: (command) => command.commands.filter(child => command !== program || !adapterNameSet.has(child.name())),
     });