@agentrhq/webcmd 0.3.0 → 0.3.2

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

@@ -243,7 +243,7 @@ describe('BasePage native input routing', () => {
             .mockResolvedValueOnce({ root: { nodeId: 1 } })
             .mockResolvedValueOnce({ nodeId: 9 })
             .mockResolvedValueOnce({});
-        page.results = [resolveOk, { x: 50, y: 100, w: 200, h: 32, visible: true }];
+        page.results = [resolveOk, { x: 50, y: 100, w: 200, h: 32, visible: true, hit: 'target' }];
         page.withArgsResults = [{ ok: true, multiple: false, accept: 'application/pdf' }, undefined];
         await page.click('#save');
         expect(page.cdp).toHaveBeenCalledWith('DOM.scrollIntoViewIfNeeded', { nodeId: 9 });
@@ -253,14 +253,38 @@ describe('BasePage native input routing', () => {
     it('clicks via CDP Input.dispatchMouseEvent when rect is visible', async () => {
         const page = new ActionPage();
         page.nativeClick = vi.fn().mockResolvedValue(undefined);
-        page.results = [resolveOk, { x: 50, y: 100, w: 200, h: 32, visible: true }];
-        await page.click('#category');
+        page.results = [resolveOk, { x: 50, y: 100, w: 200, h: 32, visible: true, hit: 'target', retargeted: false }];
+        await expect(page.click('#category')).resolves.toEqual({
+            matches_n: 1,
+            match_level: 'exact',
+            click_method: 'cdp',
+            hit: 'target',
+            retargeted: false,
+        });
         expect(page.nativeClick).toHaveBeenCalledWith(50, 100);
         expect(page.nativeClick).toHaveBeenCalledTimes(1);
         expect(page.scripts).toHaveLength(2);
         expect(page.scripts[1]).toContain('getBoundingClientRect');
         expect(page.scripts.join('\n')).not.toContain('el.click()');
     });
+    it('falls back to direct JS click when an unrelated overlay covers the target', async () => {
+        const page = new ActionPage();
+        page.nativeClick = vi.fn().mockResolvedValue(undefined);
+        page.results = [
+            resolveOk,
+            { x: 50, y: 100, w: 200, h: 32, visible: true, hit: 'other', retargeted: false },
+            { status: 'clicked', x: 50, y: 100 },
+        ];
+        await expect(page.click('#covered')).resolves.toEqual({
+            matches_n: 1,
+            match_level: 'exact',
+            click_method: 'js',
+            hit: 'other',
+            retargeted: false,
+        });
+        expect(page.nativeClick).not.toHaveBeenCalled();
+        expect(page.scripts.at(-1)).toContain('el.click()');
+    });
     it('clicks AX snapshot refs through backend node coordinates without DOM resolver', async () => {
         const page = new ActionPage();
         page.nativeClick = vi.fn().mockResolvedValue(undefined);
@@ -284,7 +308,7 @@ describe('BasePage native input routing', () => {
             return {};
         });
         await expect(page.snapshot({ source: 'ax' })).resolves.toContain('[1]button "Submit"');
-        await expect(page.click('1')).resolves.toEqual({ matches_n: 1, match_level: 'exact' });
+        await expect(page.click('1')).resolves.toEqual({ matches_n: 1, match_level: 'exact', click_method: 'ax' });
         expect(page.cdp).toHaveBeenNthCalledWith(1, 'Accessibility.enable', {});
         expect(page.cdp).toHaveBeenNthCalledWith(2, 'Accessibility.getFullAXTree', {});
         expect(page.cdp).toHaveBeenCalledWith('Accessibility.getFullAXTree', {});
@@ -343,7 +367,7 @@ describe('BasePage native input routing', () => {
         expect(snapshot).toContain('[2]button "Frame Save"');
         expect(snapshot).toContain('frame "https://other.example/embed":');
         expect(snapshot).toContain('[3]button "Cross Save"');
-        await expect(page.click('2')).resolves.toEqual({ matches_n: 1, match_level: 'exact' });
+        await expect(page.click('2')).resolves.toEqual({ matches_n: 1, match_level: 'exact', click_method: 'ax' });
         expect(page.cdp).toHaveBeenCalledWith('Accessibility.getFullAXTree', { frameId: 'same-frame' });
         expect(page.cdp).toHaveBeenCalledWith('Accessibility.enable', { frameId: 'cross-frame', sessionId: 'target', targetUrl: 'https://other.example/embed' });
         expect(page.cdp).toHaveBeenCalledWith('Accessibility.getFullAXTree', { frameId: 'cross-frame', sessionId: 'target', targetUrl: 'https://other.example/embed' });
@@ -380,7 +404,7 @@ describe('BasePage native input routing', () => {
         });
         const snapshot = await page.snapshot({ source: 'ax' });
         expect(snapshot).toContain('[1]button "Cross Save"');
-        await expect(page.click('1')).resolves.toEqual({ matches_n: 1, match_level: 'exact' });
+        await expect(page.click('1')).resolves.toEqual({ matches_n: 1, match_level: 'exact', click_method: 'ax' });
         expect(page.cdp).toHaveBeenCalledWith('Accessibility.enable', { frameId: 'cross-frame', sessionId: 'target', targetUrl: 'https://other.example/embed' });
         expect(page.cdp).toHaveBeenCalledWith('Accessibility.getFullAXTree', { frameId: 'cross-frame', sessionId: 'target', targetUrl: 'https://other.example/embed' });
         expect(page.cdp).toHaveBeenCalledWith('DOM.getBoxModel', { backendNodeId: 99, frameId: 'cross-frame', sessionId: 'target', targetUrl: 'https://other.example/embed' });
@@ -420,7 +444,7 @@ describe('BasePage native input routing', () => {
             return {};
         });
         await page.snapshot({ source: 'ax' });
-        await expect(page.click('1')).resolves.toEqual({ matches_n: 1, match_level: 'reidentified' });
+        await expect(page.click('1')).resolves.toEqual({ matches_n: 1, match_level: 'reidentified', click_method: 'ax' });
         expect(page.cdp).toHaveBeenCalledWith('Accessibility.enable', { frameId: 'cross-frame', sessionId: 'target', targetUrl: 'https://other.example/embed' });
         expect(page.cdp).toHaveBeenCalledWith('Accessibility.getFullAXTree', { frameId: 'cross-frame', sessionId: 'target', targetUrl: 'https://other.example/embed' });
         expect(page.cdp).toHaveBeenCalledWith('DOM.getBoxModel', { backendNodeId: 99, frameId: 'cross-frame', sessionId: 'target', targetUrl: 'https://other.example/embed' });
@@ -465,7 +489,7 @@ describe('BasePage native input routing', () => {
             return {};
         });
         await page.snapshot({ source: 'ax' });
-        await expect(page.click('2')).resolves.toEqual({ matches_n: 1, match_level: 'reidentified' });
+        await expect(page.click('2')).resolves.toEqual({ matches_n: 1, match_level: 'reidentified', click_method: 'ax' });
         expect(page.cdp).toHaveBeenCalledWith('Accessibility.enable', {});
         expect(page.cdp).toHaveBeenCalledWith('Accessibility.getFullAXTree', { frameId: 'same-frame' });
         expect(page.cdp).toHaveBeenCalledWith('DOM.getBoxModel', { backendNodeId: 20 });
@@ -494,7 +518,7 @@ describe('BasePage native input routing', () => {
             return {};
         });
         await page.snapshot({ source: 'ax' });
-        await expect(page.click('1')).resolves.toEqual({ matches_n: 1, match_level: 'reidentified' });
+        await expect(page.click('1')).resolves.toEqual({ matches_n: 1, match_level: 'reidentified', click_method: 'ax' });
         expect(page.cdp).toHaveBeenCalledWith('DOM.getBoxModel', { backendNodeId: 10 });
         expect(page.cdp).toHaveBeenCalledWith('DOM.getBoxModel', { backendNodeId: 42 });
         expect(page.nativeClick).toHaveBeenCalledWith(120, 210);
@@ -525,7 +549,7 @@ describe('BasePage native input routing', () => {
         for (let i = 0; i < 10; i++) {
             staleBackendIds.add(currentBackendId);
             currentBackendId += 1;
-            await expect(page.click('1')).resolves.toEqual({ matches_n: 1, match_level: 'reidentified' });
+            await expect(page.click('1')).resolves.toEqual({ matches_n: 1, match_level: 'reidentified', click_method: 'ax' });
         }
         expect(page.nativeClick).toHaveBeenCalledTimes(10);
     });
@@ -562,7 +586,7 @@ describe('BasePage native input routing', () => {
         page.nativeClick = nativeClick;
         page.results = [
             resolveOk,
-            { x: 10, y: 20, w: 100, h: 30, visible: true },
+            { x: 10, y: 20, w: 100, h: 30, visible: true, hit: 'target' },
             { status: 'js_failed', x: 10, y: 20, error: 'click intercepted' },
         ];
         await page.click('#flaky');
@@ -624,7 +648,7 @@ describe('BasePage native input routing', () => {
             resolveOk,
             { ok: true, checked: false, disabled: false, kind: 'checkbox' },
             resolveOk,
-            { x: 20, y: 30, w: 40, h: 20, visible: true },
+            { x: 20, y: 30, w: 40, h: 20, visible: true, hit: 'target' },
             { ok: true, checked: true, disabled: false, kind: 'checkbox' },
         ];
         await expect(page.setChecked('#agree', true)).resolves.toEqual({
@@ -801,3 +825,12 @@ describe('BasePage.evaluateWithArgs scoping', () => {
     `, { value: 20 })).resolves.toBe(42);
     });
 });
+describe('BasePage.sleep', () => {
+    it('is a pure client-side sleep that never evaluates page script', async () => {
+        const page = new ActionPage();
+        const evaluateSpy = vi.spyOn(page, 'evaluate');
+        await page.sleep(0);
+        expect(evaluateSpy).not.toHaveBeenCalled();
+        expect(page.scripts).toHaveLength(0);
+    });
+});

package/dist/src/browser/command-catalog.d.ts

@@ -0,0 +1,6 @@
+import type { HostedArgumentContract, HostedBrowserCommandContract } from '../hosted/contract.js';
+/** Exact local Commander flags for every catalogued browser option. */
+export declare function browserOptionFlags(option: HostedArgumentContract): string;
+/** Shared Commander value parser for browser options with structural coercion. */
+export declare function browserOptionValueParser(commandPath: string, optionName: string): ((value: string) => unknown) | undefined;
+export declare const browserCommandCatalog: readonly HostedBrowserCommandContract[];

package/dist/src/browser/command-catalog.js

@@ -0,0 +1,259 @@
+import { InvalidArgumentError } from 'commander';
+function argument(name, type, description, positional, metadata = {}) {
+    return {
+        name,
+        type,
+        description,
+        positional,
+        required: metadata.required === true,
+        variadic: metadata.variadic === true,
+        ...(metadata.default !== undefined ? { default: metadata.default } : {}),
+        ...(metadata.choices?.length ? { choices: [...metadata.choices] } : {}),
+    };
+}
+function positional(name, description = '', metadata = {}) {
+    return argument(name, 'string', description, true, metadata);
+}
+function option(name, description, metadata = {}) {
+    return argument(name, 'string', description, false, metadata);
+}
+function flag(name, description, defaultValue) {
+    return argument(name, 'boolean', description, false, {
+        ...(defaultValue !== undefined ? { default: defaultValue } : {}),
+    });
+}
+const BROWSER_OPTION_VALUE_NAMES = {
+    amount: 'pixels',
+    as: 'format',
+    childrenMax: 'n',
+    chunkSize: 'chars',
+    css: 'selector',
+    depth: 'n',
+    detail: 'key',
+    filter: 'fields',
+    frame: 'index',
+    fromLabel: 'text',
+    fromName: 'text',
+    fromNth: 'n',
+    fromRole: 'role',
+    fromTestid: 'id',
+    fromText: 'text',
+    height: 'n',
+    index: 'n',
+    label: 'text',
+    level: 'level',
+    limit: 'n',
+    max: 'n',
+    maxBody: 'chars',
+    name: 'text',
+    nth: 'n',
+    page: 'id',
+    role: 'role',
+    seedArgs: 'value',
+    selector: 'css',
+    since: 'duration',
+    source: 'source',
+    start: 'char',
+    tab: 'targetId',
+    testid: 'id',
+    text: 'text',
+    textMax: 'n',
+    timeout: 'ms',
+    toLabel: 'text',
+    toName: 'text',
+    toNth: 'n',
+    toRole: 'role',
+    toTestid: 'id',
+    toText: 'text',
+    trace: 'mode',
+    ttl: 'ms',
+    until: 'duration',
+    width: 'n',
+};
+/** Exact local Commander flags for every catalogued browser option. */
+export function browserOptionFlags(option) {
+    const longName = option.name.replace(/[A-Z]/g, character => `-${character.toLowerCase()}`);
+    if (option.type === 'boolean')
+        return option.name === 'fixture' ? '--no-fixture' : `--${longName}`;
+    const valueName = BROWSER_OPTION_VALUE_NAMES[option.name];
+    if (!valueName)
+        throw new Error(`Browser option --${longName} is missing its Commander value name`);
+    return `--${longName} <${valueName}>`;
+}
+/** Shared Commander value parser for browser options with structural coercion. */
+export function browserOptionValueParser(commandPath, optionName) {
+    if (commandPath !== 'screenshot' || (optionName !== 'width' && optionName !== 'height'))
+        return undefined;
+    return (value) => {
+        if (!/^\d+$/.test(value) || Number.parseInt(value, 10) <= 0) {
+            throw new InvalidArgumentError(`--${optionName} must be a positive integer (got "${value}")`);
+        }
+        return Number.parseInt(value, 10);
+    };
+}
+function command(commandPath, description, action, positionals = [], options = [], sessionPolicy = 'require-existing') {
+    return {
+        command: commandPath,
+        aliases: [],
+        description,
+        positionals,
+        options,
+        sessionPolicy,
+        ...(action !== undefined ? { action } : {}),
+    };
+}
+const TAB_TARGET_HELP = 'Target tab/page identity returned by "browser open", "browser tab new", or "browser tab list"';
+const TARGET_HELP = 'Numeric ref (from browser state / find), CSS selector, or omit when using --role/--name/etc.';
+const WRITE_NTH_HELP = 'When <target> is a multi-match CSS selector, pick the nth match (0-based)';
+const READ_NTH_HELP = 'Pick the nth match (0-based) when <target> is a multi-match CSS selector';
+const tabOption = option('tab', TAB_TARGET_HELP);
+const semanticLocatorOptions = [
+    option('role', 'Semantic role (button, link, textbox, option, etc.)'),
+    option('name', 'Accessible name contains text (aria-label, label, title, placeholder, or visible text)'),
+    option('label', 'Associated label contains text'),
+    option('text', 'Visible text contains text'),
+    option('testid', 'data-testid / data-test / test-id contains id'),
+];
+const semanticWriteOptions = [
+    ...semanticLocatorOptions,
+    option('nth', WRITE_NTH_HELP),
+    tabOption,
+];
+const semanticReadOptions = [
+    ...semanticLocatorOptions,
+    option('nth', READ_NTH_HELP),
+    tabOption,
+];
+export const browserCommandCatalog = [
+    command('analyze', 'Classify site: anti-bot vendor, real-data API candidates, pattern (A/B/C/D), nearest adapter, next step', 'analyze', [positional('url', '', { required: true })], [tabOption], 'create-or-reuse'),
+    command('back', 'Go back in browser history', 'back', [], [tabOption]),
+    command('bind', 'Bind an existing Cloak runtime tab to the browser session named by <session>', undefined, [], [
+        option('page', 'Cloak tab page id from `webcmd browser <session> tab list`'),
+        option('index', 'Cloak tab index from `webcmd browser <session> tab list`'),
+    ], 'local-only'),
+    command('check', 'Ensure a checkbox/radio/aria-checked control is checked — JSON envelope {checked, changed, target, matches_n}', 'check', [positional('target', TARGET_HELP)], semanticWriteOptions),
+    command('click', 'Click element — JSON envelope {clicked, target, matches_n}', 'click', [positional('target', TARGET_HELP)], semanticWriteOptions),
+    command('close', 'Release the current browser session tab lease', 'close-window', [], [], 'close-existing'),
+    command('console', 'Read recent browser console messages', 'console', [], [
+        tabOption,
+        option('level', 'Console level: all, error, warning, log, info, debug', { default: 'all' }),
+        option('since', 'Only include messages from the last duration (for example: 30s, 2m)'),
+        option('until', 'Only include messages older than the duration from now'),
+        flag('follow', 'Continuously print new console messages as JSON lines', false),
+    ]),
+    command('dblclick', 'Double-click element — JSON envelope {dblclicked, target, matches_n}', 'dblclick', [positional('target', TARGET_HELP)], semanticWriteOptions),
+    command('dialog/accept', 'Accept the currently open JavaScript dialog', 'dialog-accept', [], [option('text', 'Prompt text to submit for prompt() dialogs'), tabOption]),
+    command('dialog/dismiss', 'Dismiss the currently open JavaScript dialog', 'dialog-dismiss', [], [tabOption]),
+    command('drag', 'Drag one element to another — JSON envelope {dragged, source, target, source_matches_n, target_matches_n}', 'drag', [
+        positional('source', 'Numeric ref/CSS selector to drag from, or omit with --from-role/--from-name/etc.'),
+        positional('target', 'Numeric ref/CSS selector to drop onto, or omit with --to-role/--to-name/etc.'),
+    ], [
+        option('fromRole', 'from semantic role'),
+        option('fromName', 'from accessible name contains text'),
+        option('fromLabel', 'from associated label contains text'),
+        option('fromText', 'from visible text contains text'),
+        option('fromTestid', 'from data-testid / data-test / test-id contains id'),
+        option('toRole', 'to semantic role'),
+        option('toName', 'to accessible name contains text'),
+        option('toLabel', 'to associated label contains text'),
+        option('toText', 'to visible text contains text'),
+        option('toTestid', 'to data-testid / data-test / test-id contains id'),
+        option('fromNth', 'When <source> is a multi-match CSS selector, pick the nth match (0-based)'),
+        option('toNth', 'When <target> is a multi-match CSS selector, pick the nth match (0-based)'),
+        tabOption,
+    ]),
+    command('eval', 'Execute JS in page context, return result', 'exec', [positional('js', 'JavaScript code', { required: true })], [option('frame', 'Cross-origin iframe index from "browser frames"'), tabOption]),
+    command('extract', 'Extract page content as markdown, paragraph-aware chunks for long pages', 'extract', [], [
+        option('selector', 'CSS selector scope; defaults to <main>/<article>/<body>'),
+        option('chunkSize', 'Target chunk size in chars', { default: '20000' }),
+        option('start', 'Start offset (use next_start_char from a previous extract)', { default: '0' }),
+        tabOption,
+    ]),
+    command('fill', 'Set input/textarea/contenteditable text exactly and verify the value — JSON envelope {filled, verified, text, actual}', 'fill', [
+        positional('targetOrText', 'Numeric ref/CSS target, or text when using --role/--name/etc.'),
+        positional('text', 'Text to set exactly'),
+    ], semanticWriteOptions),
+    command('find', 'Find DOM elements by CSS or semantic locator — returns JSON {matches_n, entries[]}', 'find', [], [
+        ...semanticLocatorOptions,
+        option('css', 'CSS selector (required)'),
+        option('limit', 'Max entries returned', { default: '50' }),
+        option('textMax', 'Max chars of trimmed text per entry', { default: '120' }),
+        tabOption,
+    ]),
+    command('focus', 'Focus an element — JSON envelope {focused, target, matches_n}', 'focus', [positional('target', TARGET_HELP)], semanticWriteOptions),
+    command('frames', 'List cross-origin iframe targets in snapshot order', 'frames', [], [tabOption]),
+    command('get/attributes', 'Element attributes — JSON envelope {value, matches_n}', 'get-attributes', [positional('target', TARGET_HELP)], semanticReadOptions),
+    command('get/html', 'Page HTML (or scoped); use --as json for a {tag, attrs, text, children} tree', 'get-html', [], [
+        option('selector', 'CSS selector scope (first match)'),
+        option('as', 'Output format: "html" (default) or "json" for structured tree', { default: 'html' }),
+        option('max', 'Max characters of raw HTML to return (0 = unlimited)', { default: '0' }),
+        option('depth', '(--as json) Max tree depth below root (0 = root only, 0 disables = unlimited via empty)', { default: '' }),
+        option('childrenMax', '(--as json) Max element children kept per node (empty = unlimited)', { default: '' }),
+        option('textMax', '(--as json) Max chars of direct text kept per node (empty = unlimited)', { default: '' }),
+        tabOption,
+    ]),
+    command('get/text', 'Element text content — JSON envelope {value, matches_n}', 'get-text', [positional('target', TARGET_HELP)], semanticReadOptions),
+    command('get/title', 'Page title', 'get-title', [], [tabOption]),
+    command('get/url', 'Current page URL', 'get-url', [], [tabOption]),
+    command('get/value', 'Input/textarea value — JSON envelope {value, matches_n}', 'get-value', [positional('target', TARGET_HELP)], semanticReadOptions),
+    command('hover', 'Move the mouse over an element — JSON envelope {hovered, target, matches_n}', 'hover', [positional('target', TARGET_HELP)], semanticWriteOptions),
+    command('init', 'Generate adapter scaffold in ~/.webcmd/clis/', 'init', [positional('name', 'Adapter name in site/command format (e.g. hn/top)', { required: true })]),
+    command('keys', 'Press keyboard key', 'press-key', [positional('key', 'Key to press (Enter, Escape, Tab, Control+a)', { required: true })], [tabOption]),
+    command('network', 'Capture network requests as shape previews; retrieve full bodies by key', 'network', [], [
+        tabOption,
+        option('detail', 'Emit full body for the entry with this key'),
+        flag('all', 'Include static resources (js/css/images/telemetry)'),
+        flag('raw', 'Emit full bodies for every entry (skip shape preview)'),
+        option('filter', 'Comma-separated field names; keep only entries whose body shape has ALL names as path segments'),
+        option('since', 'Only include entries from the last duration (for example: 30s, 2m)'),
+        option('until', 'Only include entries older than the duration from now'),
+        flag('follow', 'Continuously print new matching entries as JSON lines', false),
+        flag('failed', 'Only include failed HTTP requests (status 0 or >= 400)', false),
+        option('maxBody', 'With --detail: cap the emitted body at N chars (0 = unlimited, default)', { default: '0' }),
+        option('ttl', 'Cache TTL in ms for --detail lookups', { default: '86400000' }),
+    ]),
+    command('open', 'Open URL in the browser session', 'navigate', [positional('url', '', { required: true })], [tabOption], 'create-or-reuse'),
+    command('screenshot', 'Take screenshot', 'screenshot', [positional('path', 'Save to file (base64 if omitted)')], [
+        tabOption,
+        flag('fullPage', 'Capture the full scrollable page, not just the viewport', false),
+        flag('annotate', 'Overlay visible browser state ref labels on the screenshot', false),
+        option('width', 'Override viewport width in CSS pixels for this screenshot only'),
+        option('height', 'Override viewport height in CSS pixels for this screenshot only (ignored with --full-page)'),
+    ]),
+    command('scroll', 'Scroll page', 'scroll', [positional('direction', 'up or down', { required: true })], [option('amount', 'Pixels to scroll', { default: '500' }), tabOption]),
+    command('select', 'Select dropdown option — JSON envelope {selected, target, matches_n}', 'select', [
+        positional('targetOrOption', 'Numeric ref/CSS target, or option text when using --role/--name/etc.'),
+        positional('option', 'Option text (or value) to select'),
+    ], semanticWriteOptions),
+    command('state', 'Page state: URL, title, interactive elements with [N] indices', 'snapshot', [], [
+        option('source', 'Snapshot backend: dom (default) or ax prototype', { default: 'dom' }),
+        flag('compareSources', 'Print DOM vs AX snapshot metrics for observation promotion decisions', false),
+        tabOption,
+    ]),
+    command('tab/close', 'Close a tab by target ID', 'tabs', [positional('targetId', TAB_TARGET_HELP)], [tabOption]),
+    command('tab/list', 'List tabs in the browser session with target IDs', 'tabs'),
+    command('tab/new', 'Create a new tab and print its target ID', 'tabs', [positional('url', 'Optional URL to open in the new tab')]),
+    command('tab/select', 'Select a tab by target ID and make it the default browser tab', 'tabs', [positional('targetId', TAB_TARGET_HELP)], [tabOption]),
+    command('type', 'Click element, then type text — JSON envelope {typed, text, target, matches_n, autocomplete}', 'type', [
+        positional('targetOrText', 'Numeric ref/CSS target, or text when using --role/--name/etc.'),
+        positional('text', 'Text to type'),
+    ], semanticWriteOptions),
+    command('unbind', 'Compatibility command; release the Cloak browser session named by <session>', 'close-window', [], [], 'close-existing'),
+    command('uncheck', 'Ensure a checkbox/aria-checked control is unchecked — JSON envelope {checked, changed, target, matches_n}', 'uncheck', [positional('target', TARGET_HELP)], semanticWriteOptions),
+    command('upload', 'Attach local files to a file input — JSON envelope {uploaded, files, file_names, target, matches_n}', 'set-file-input', [
+        positional('targetOrFile', 'Numeric ref/CSS target, or first file when using --role/--name/etc.'),
+        positional('files', 'Local file path(s) to attach', { variadic: true }),
+    ], semanticWriteOptions),
+    command('verify', 'Execute an adapter and validate output; uses fixture at ~/.webcmd/sites/<site>/verify/<cmd>.json when present', 'verify', [positional('name', 'Adapter name in site/command format (e.g. hn/top)', { required: true })], [
+        flag('writeFixture', 'Write a starter fixture to ~/.webcmd/sites/<site>/verify/<command>.json if none exists'),
+        flag('updateFixture', 'Overwrite an existing fixture with one derived from current output'),
+        flag('fixture', 'Ignore any fixture file for this run (no value-level validation)'),
+        flag('strictMemory', 'Fail (not just warn) when ~/.webcmd/sites/<site>/endpoints.json or notes.md is missing'),
+        option('seedArgs', 'Seed args when no fixture exists; use JSON array/object for multiple args or flags'),
+        option('trace', 'Trace capture for the adapter subprocess: off, on, retain-on-failure', { default: 'off' }),
+    ]),
+    command('wait', '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)', 'wait', [
+        positional('type', 'selector, text, time, xhr, or download', { required: true }),
+        positional('value', 'CSS selector, text string, seconds, XHR URL regex, or download filename/URL pattern'),
+    ], [tabOption, option('timeout', 'Timeout in milliseconds', { default: '10000' })]),
+];

package/dist/src/browser/command-catalog.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/browser/command-catalog.test.js

@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'vitest';
+import { createProgram } from '../cli.js';
+import { commanderNamespaceHelpData } from '../help.js';
+import { buildHostedContract, } from '../hosted/contract.js';
+import { browserCommandCatalog, browserOptionFlags } from './command-catalog.js';
+function browserCommand() {
+    const browser = createProgram('', '').commands.find(command => command.name() === 'browser');
+    if (!browser)
+        throw new Error('Local browser command is not registered');
+    return browser;
+}
+function localBrowserCommands() {
+    const help = commanderNamespaceHelpData(browserCommand());
+    return help.commands;
+}
+function normalizeArgument(argument, positional) {
+    return {
+        name: argument.name,
+        type: positional || argument.takes_value ? 'string' : 'boolean',
+        description: argument.help ?? '',
+        positional,
+        required: positional && argument.required === true,
+        variadic: argument.variadic === true,
+        ...(argument.default !== undefined ? { default: argument.default } : {}),
+        ...(argument.choices?.length ? { choices: [...argument.choices] } : {}),
+    };
+}
+function normalizeLocalCommand(command) {
+    return {
+        command: command.name.replaceAll(' ', '/'),
+        aliases: [...(command.aliases ?? [])],
+        description: command.description,
+        positionals: command.positionals.map(argument => normalizeArgument(argument, true)),
+        options: command.command_options.map(argument => normalizeArgument(argument, false)),
+    };
+}
+describe('browserCommandCatalog', () => {
+    it('catalogues the exact local Commander browser leaf set and metadata', () => {
+        const local = localBrowserCommands().map(normalizeLocalCommand);
+        const catalogPaths = new Set(browserCommandCatalog.map(command => command.command));
+        const localPaths = new Set(local.map(command => command.command));
+        expect({
+            uncatalogued: [...localPaths].filter(command => !catalogPaths.has(command)).sort(),
+            stale: [...catalogPaths].filter(command => !localPaths.has(command)).sort(),
+        }).toEqual({ uncatalogued: [], stale: [] });
+        expect(browserCommandCatalog.map(({ sessionPolicy: _sessionPolicy, action: _action, ...command }) => command))
+            .toEqual(local);
+    });
+    it('preserves the exact local Commander flag grammar for every browser option', () => {
+        const local = new Map(localBrowserCommands().map(command => [
+            command.name.replaceAll(' ', '/'),
+            command.command_options.map(option => option.flags),
+        ]));
+        expect(Object.fromEntries(browserCommandCatalog.map(command => [
+            command.command,
+            command.options.map(browserOptionFlags),
+        ]))).toEqual(Object.fromEntries(local));
+    });
+    it('marks bind as the only local-only command and gives every hosted command an action', () => {
+        expect(browserCommandCatalog.filter(command => command.sessionPolicy === 'local-only').map(command => command.command))
+            .toEqual(['bind']);
+        expect(browserCommandCatalog.find(command => command.command === 'bind')).not.toHaveProperty('action');
+        expect(browserCommandCatalog.filter(command => command.command !== 'bind').every(command => command.action))
+            .toBe(true);
+    });
+    it('classifies lifecycle commands from their actual local behavior', () => {
+        const policies = Object.fromEntries(browserCommandCatalog.map(command => [command.command, command.sessionPolicy]));
+        expect(policies.open).toBe('create-or-reuse');
+        expect(policies.close).toBe('close-existing');
+        expect(policies.unbind).toBe('close-existing');
+        expect(policies.state).toBe('require-existing');
+    });
+    it('is the production browser surface emitted by buildHostedContract', () => {
+        const contract = buildHostedContract([], [], '1.0.0');
+        expect(contract.browserCommands).toEqual(browserCommandCatalog);
+        expect(contract.browserCommands.filter(command => !command.action).map(command => command.command))
+            .toEqual(['bind']);
+    });
+});

package/dist/src/browser/runtime/local-cloak/darwin-background-launch.d.ts

@@ -0,0 +1,17 @@
+import { buildLaunchOptions, humanizeBrowser } from 'cloakbrowser';
+import type { LaunchPersistentContextOptions } from 'cloakbrowser';
+import type { Browser, BrowserContext } from 'playwright-core';
+type Dependencies = {
+    buildLaunchOptions: typeof buildLaunchOptions;
+    humanizeBrowser: typeof humanizeBrowser;
+    openApplication: (appPath: string, args: string[]) => Promise<void>;
+    activateApplication: (appPath: string) => Promise<void>;
+    readPort: (portFile: string) => Promise<number>;
+    connectOverCDP: (endpoint: string) => Promise<Browser>;
+    terminateProfile: (userDataDir: string) => Promise<void>;
+    removePortFile: (portFile: string) => Promise<void>;
+};
+export declare function waitForDevToolsPort(portFile: string, timeoutMs?: number): Promise<number>;
+export declare function activateDarwinBackgroundContext(context: BrowserContext): Promise<void>;
+export declare function launchDarwinBackgroundPersistentContext(options: LaunchPersistentContextOptions, deps?: Dependencies): Promise<BrowserContext>;
+export {};

package/dist/src/browser/runtime/local-cloak/darwin-background-launch.js

@@ -0,0 +1,106 @@
+import { execFile } from 'node:child_process';
+import { readFile, rm } from 'node:fs/promises';
+import { posix as path } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { promisify } from 'node:util';
+import { buildLaunchOptions, humanizeBrowser } from 'cloakbrowser';
+import { chromium } from 'playwright-core';
+const execFileAsync = promisify(execFile);
+async function openApplication(appPath, args) {
+    await execFileAsync('/usr/bin/open', ['-g', '-n', appPath, '--args', ...args]);
+}
+export async function waitForDevToolsPort(portFile, timeoutMs = 10_000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            const port = Number.parseInt((await readFile(portFile, 'utf8')).split('\n')[0], 10);
+            if (Number.isInteger(port) && port > 0)
+                return port;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        await delay(50);
+    }
+    throw new Error('Timed out waiting for background Chromium CDP endpoint');
+}
+async function terminateProfile(userDataDir) {
+    const { stdout } = await execFileAsync('/bin/ps', ['-axo', 'pid=,command=']);
+    const needle = `--user-data-dir=${userDataDir}`;
+    for (const line of stdout.split('\n')) {
+        if (!line.includes(needle))
+            continue;
+        const pid = Number.parseInt(line.trim().split(/\s+/, 1)[0], 10);
+        if (Number.isInteger(pid) && pid !== process.pid)
+            process.kill(pid, 'SIGTERM');
+    }
+}
+const defaultDependencies = {
+    buildLaunchOptions,
+    humanizeBrowser,
+    openApplication,
+    activateApplication: async (appPath) => {
+        await execFileAsync('/usr/bin/open', [appPath]);
+    },
+    readPort: waitForDevToolsPort,
+    connectOverCDP: endpoint => chromium.connectOverCDP(endpoint),
+    terminateProfile,
+    removePortFile: portFile => rm(portFile, { force: true }),
+};
+const contextActivators = new WeakMap();
+export async function activateDarwinBackgroundContext(context) {
+    await contextActivators.get(context)?.();
+}
+function appPathFor(executablePath) {
+    const marker = `${path.sep}Contents${path.sep}MacOS${path.sep}`;
+    const index = executablePath.lastIndexOf(marker);
+    if (index < 0)
+        throw new Error(`Cloak Chromium executable is not inside a macOS app bundle: ${executablePath}`);
+    return executablePath.slice(0, index);
+}
+export async function launchDarwinBackgroundPersistentContext(options, deps = defaultDependencies) {
+    const portFile = path.join(options.userDataDir, 'DevToolsActivePort');
+    await deps.removePortFile(portFile);
+    const launchOptions = await deps.buildLaunchOptions(options);
+    if (!launchOptions.executablePath)
+        throw new Error('Cloak Chromium executable path is missing');
+    const appPath = appPathFor(launchOptions.executablePath);
+    let browser;
+    let launched = false;
+    try {
+        await deps.openApplication(appPath, [
+            ...(launchOptions.args ?? []),
+            '--password-store=basic',
+            '--use-mock-keychain',
+            `--user-data-dir=${options.userDataDir}`,
+            '--remote-debugging-address=127.0.0.1',
+            '--remote-debugging-port=0',
+            'about:blank',
+        ]);
+        launched = true;
+        const port = await deps.readPort(portFile);
+        browser = await deps.connectOverCDP(`http://127.0.0.1:${port}`);
+        await deps.humanizeBrowser(browser, options);
+        const context = browser.contexts()[0];
+        if (!context)
+            throw new Error('Background Chromium did not expose a persistent context');
+        contextActivators.set(context, () => deps.activateApplication(appPath));
+        context.close = async () => {
+            try {
+                await browser.close();
+            }
+            finally {
+                contextActivators.delete(context);
+                await deps.terminateProfile(options.userDataDir);
+            }
+        };
+        return context;
+    }
+    catch (error) {
+        await browser?.close().catch(() => { });
+        if (launched)
+            await deps.terminateProfile(options.userDataDir).catch(() => { });
+        throw error;
+    }
+}

package/dist/src/browser/runtime/local-cloak/darwin-background-launch.test.d.ts

@@ -0,0 +1 @@
+export {};