webhands 0.2.0 → 0.4.0

package/dist/cli.js

@@ -65,6 +65,12 @@ const stealthOptions = z.object({
         .optional()
         .describe("Drive a browser already installed on the system (e.g. 'chrome', " +
         "'msedge') instead of the bundled Chromium."),
+    proxy: z
+        .string()
+        .optional()
+        .describe('Route ALL traffic and DNS through a SOCKS proxy. Give a SOCKS URL: ' +
+        'socks5h://host:1080 tunnels DNS through the proxy too (no leak), ' +
+        'socks5://host:1080 allows local DNS. A user:pass@ prefix is allowed.'),
     // Modelled as a `viewport` boolean so incur's `--no-<flag>` negation gives the
     // task-mandated `--no-viewport`: passing `--no-viewport` sets `viewport=false`
     // (i.e. noViewport=true). Absent => undefined => core decides the default
@@ -90,6 +96,11 @@ function launchPolicyFrom(options) {
         // `--no-viewport` (viewport=false) => noViewport:true; `--viewport` => false.
         // Only forward when the flag was given.
         ...(options.viewport !== undefined ? { noViewport: !options.viewport } : {}),
+        // Only forward --proxy when given, so the policy object stays minimal (the
+        // `serve` wiring tests assert it by exact shape).
+        ...(options.proxy !== undefined && options.proxy !== ''
+            ? { proxy: options.proxy }
+            : {}),
     };
 }
 /** The structured output schema shared by verbs that act on a page but return no data. */
@@ -122,6 +133,10 @@ function nextAct() {
             command: 'type',
             description: 'Type into an element addressed by a Playwright locator string.',
         },
+        {
+            command: 'query',
+            description: 'Read structured data (attrs/props/visibility) out of matched elements.',
+        },
         {
             command: 'eval',
             description: 'Run JavaScript in the page as an escape hatch.',
@@ -238,6 +253,7 @@ export function createCli(deps = {}) {
             stealth: z.boolean(),
             systemBrowser: z.string().optional(),
             noViewport: z.boolean().optional(),
+            proxy: z.string().optional(),
         }),
         async run(c) {
             try {
@@ -257,6 +273,7 @@ export function createCli(deps = {}) {
                     ...(policy.noViewport !== undefined
                         ? { noViewport: policy.noViewport }
                         : {}),
+                    ...(policy.proxy !== undefined ? { proxy: policy.proxy } : {}),
                 }, {
                     cta: {
                         commands: [
@@ -471,14 +488,22 @@ export function createCli(deps = {}) {
         args: z.object({
             locator: z
                 .string()
-                .describe("A raw Playwright locator expression, e.g. getByRole('button', { name: 'Search' })."),
+                .describe("A raw Playwright locator expression, e.g. getByRole('button', { name: 'Search' }). " +
+                'With --by-ref, a durable `ref` from `query --with-refs` instead.'),
+        }),
+        options: connectionOptions.extend({
+            'by-ref': z
+                .boolean()
+                .default(false)
+                .describe('Treat the argument as a durable `ref` from `query --with-refs`: ' +
+                'resolve it but fail LOUD (stale-ref) if it now matches zero or more ' +
+                'than one element, instead of silently clicking the wrong one.'),
         }),
-        options: connectionOptions,
         output: actionOutput.extend({ verb: z.literal('click') }),
         async run(c) {
             try {
                 return await withSession(provider, targetFrom(c.options), async (s) => {
-                    await s.page.click(locator(c.args.locator));
+                    await s.page.click(locator(c.args.locator), c.options['by-ref'] ? { byRef: true } : undefined);
                     return c.ok({ ok: true, verb: 'click' }, { cta: { commands: [nextSnapshot()] } });
                 });
             }
@@ -492,15 +517,23 @@ export function createCli(deps = {}) {
         args: z.object({
             locator: z
                 .string()
-                .describe('A raw Playwright locator expression for the target input.'),
+                .describe('A raw Playwright locator expression for the target input. ' +
+                'With --by-ref, a durable `ref` from `query --with-refs` instead.'),
             text: z.string().describe('The text to type into the element.'),
         }),
-        options: connectionOptions,
+        options: connectionOptions.extend({
+            'by-ref': z
+                .boolean()
+                .default(false)
+                .describe('Treat the locator argument as a durable `ref` from `query --with-refs`: ' +
+                'resolve it but fail LOUD (stale-ref) if it now matches zero or more ' +
+                'than one element, instead of silently typing into the wrong one.'),
+        }),
         output: actionOutput.extend({ verb: z.literal('type') }),
         async run(c) {
             try {
                 return await withSession(provider, targetFrom(c.options), async (s) => {
-                    await s.page.type(locator(c.args.locator), c.args.text);
+                    await s.page.type(locator(c.args.locator), c.args.text, c.options['by-ref'] ? { byRef: true } : undefined);
                     return c.ok({ ok: true, verb: 'type' }, { cta: { commands: [nextSnapshot()] } });
                 });
             }
@@ -516,7 +549,17 @@ export function createCli(deps = {}) {
                 .string()
                 .describe('A JS expression evaluated in the page context (e.g. document.title).'),
         }),
-        options: connectionOptions,
+        // The ONE `--frame` flag on the surface (R1): `eval` runs page-world JS and
+        // cannot carry a `frameLocator(...)` the way locator-taking verbs do, so it
+        // gets an explicit SAME-ORIGIN frame selector. Omitted == top-document eval.
+        options: connectionOptions.extend({
+            frame: z
+                .string()
+                .optional()
+                .describe('Evaluate inside the named SAME-ORIGIN child frame instead of the top ' +
+                "document: a CSS selector for the iframe element (e.g. '#main-iframe'). " +
+                'A cross-origin frame is unreachable and fails loud.'),
+        }),
         output: z.object({
             ok: z.literal(true),
             verb: z.literal('eval'),
@@ -527,7 +570,9 @@ export function createCli(deps = {}) {
         async run(c) {
             try {
                 return await withSession(provider, targetFrom(c.options), async (s) => {
-                    const result = await s.page.eval(c.args.expression);
+                    const result = await s.page.eval(c.args.expression, c.options.frame !== undefined
+                        ? { frame: c.options.frame }
+                        : undefined);
                     return c.ok({ ok: true, verb: 'eval', result }, { cta: { commands: [nextSnapshot()] } });
                 });
             }
@@ -536,6 +581,482 @@ export function createCli(deps = {}) {
             }
         },
     });
+    // --- Tier-1 read verbs: query + state shorthands (prd broaden-agent-verb-
+    // surface, R2/R5). Each is its own incur command, so one definition yields
+    // both the CLI command and the MCP tool. List flags (--attr/--prop/--pw) are
+    // REPEATABLE, not comma-joined (R5): incur arrays collect each occurrence.
+    // There is NO --frame flag (frame scope rides IN the locator string, R1).
+    cli.command('query', {
+        description: 'Read structured data out of the element(s) a Playwright locator matches: ' +
+            'one row per match carrying exactly the requested DOM attributes (--attr), ' +
+            'live JS properties (--prop), and Playwright extras (--pw visible|bbox).',
+        args: z.object({
+            locator: z
+                .string()
+                .describe('A raw Playwright locator expression addressing the element(s) to read. ' +
+                "Frame scope rides in the string, e.g. frameLocator('#f').locator('#x')."),
+        }),
+        options: connectionOptions.extend({
+            attr: z
+                .array(z.string())
+                .default([])
+                .describe('A DOM ATTRIBUTE to read (getAttribute), e.g. href. Repeatable.'),
+            prop: z
+                .array(z.string())
+                .default([])
+                .describe('A live JS PROPERTY to read (el[name]), e.g. innerText. Repeatable.'),
+            pw: z
+                .array(z.enum(['visible', 'bbox']))
+                .default([])
+                .describe('A Playwright extra to include: visible (actionability-grade) or ' +
+                'bbox (viewport-pixel box). Repeatable.'),
+            limit: z.coerce
+                .number()
+                .optional()
+                .describe('Bound the number of rows returned.'),
+            'with-refs': z
+                .boolean()
+                .default(false)
+                .describe('Also return a durable `ref` per row — a locator handle you feed back ' +
+                'to `click`/`type` --by-ref to act on THAT element even after the ' +
+                'list mutates (fixes the .nth() index-drift footgun). Reuses a ' +
+                'stable unique attribute (id/data-testid/…) when present, mints ' +
+                'a namespaced data-webhands-ref only as a fallback. Off by default: ' +
+                'the default query is a pure read and mutates nothing.'),
+        }),
+        output: z.object({
+            ok: z.literal(true),
+            verb: z.literal('query'),
+            rows: z
+                .array(z.object({
+                attrs: z.record(z.string(), z.string().nullable()).optional(),
+                props: z.record(z.string(), z.unknown()).optional(),
+                pw: z
+                    .object({
+                    visible: z.boolean().optional(),
+                    bbox: z
+                        .object({
+                        x: z.number(),
+                        y: z.number(),
+                        width: z.number(),
+                        height: z.number(),
+                    })
+                        .nullable()
+                        .optional(),
+                })
+                    .optional(),
+                ref: z
+                    .string()
+                    .optional()
+                    .describe('A durable locator handle for this element (only with --with-refs); ' +
+                    'pass it to click/type --by-ref to act on it later.'),
+            }))
+                .describe('One row per matched element, each carrying the asked fields.'),
+        }),
+        async run(c) {
+            try {
+                return await withSession(provider, targetFrom(c.options), async (s) => {
+                    const rows = await s.page.query(locator(c.args.locator), {
+                        attrs: c.options.attr,
+                        props: c.options.prop,
+                        pw: c.options.pw,
+                        ...(c.options.limit !== undefined ? { limit: c.options.limit } : {}),
+                        ...(c.options['with-refs'] ? { refs: true } : {}),
+                    });
+                    return c.ok({ ok: true, verb: 'query', rows }, { cta: { commands: [nextSnapshot()] } });
+                });
+            }
+            catch (cause) {
+                return fail(c, cause, binary);
+            }
+        },
+    });
+    cli.command('count', {
+        description: 'Count how many elements a Playwright locator matches (a match-set size).',
+        args: z.object({
+            locator: z.string().describe('A raw Playwright locator expression.'),
+        }),
+        options: connectionOptions,
+        output: z.object({
+            ok: z.literal(true),
+            verb: z.literal('count'),
+            count: z.number().describe('How many elements matched.'),
+        }),
+        async run(c) {
+            try {
+                return await withSession(provider, targetFrom(c.options), async (s) => {
+                    const count = await s.page.count(locator(c.args.locator));
+                    return c.ok({ ok: true, verb: 'count', count }, { cta: { commands: [nextSnapshot()] } });
+                });
+            }
+            catch (cause) {
+                return fail(c, cause, binary);
+            }
+        },
+    });
+    cli.command('exists', {
+        description: 'Whether a Playwright locator matches at least one element (count > 0).',
+        args: z.object({
+            locator: z.string().describe('A raw Playwright locator expression.'),
+        }),
+        options: connectionOptions,
+        output: z.object({
+            ok: z.literal(true),
+            verb: z.literal('exists'),
+            exists: z.boolean().describe('Whether any element matched.'),
+        }),
+        async run(c) {
+            try {
+                return await withSession(provider, targetFrom(c.options), async (s) => {
+                    const exists = await s.page.exists(locator(c.args.locator));
+                    return c.ok({ ok: true, verb: 'exists', exists }, { cta: { commands: [nextSnapshot()] } });
+                });
+            }
+            catch (cause) {
+                return fail(c, cause, binary);
+            }
+        },
+    });
+    cli.command('is-visible', {
+        description: 'Whether the first match is actionability-grade visible (a present-but-hidden ' +
+            'element reads false).',
+        args: z.object({
+            locator: z.string().describe('A raw Playwright locator expression.'),
+        }),
+        options: connectionOptions,
+        output: z.object({
+            ok: z.literal(true),
+            verb: z.literal('isVisible'),
+            visible: z.boolean().describe("The first match's visibility."),
+        }),
+        async run(c) {
+            try {
+                return await withSession(provider, targetFrom(c.options), async (s) => {
+                    const visible = await s.page.isVisible(locator(c.args.locator));
+                    return c.ok({ ok: true, verb: 'isVisible', visible }, { cta: { commands: [nextSnapshot()] } });
+                });
+            }
+            catch (cause) {
+                return fail(c, cause, binary);
+            }
+        },
+    });
+    cli.command('get-attribute', {
+        description: 'Read a single DOM attribute off the first match (null if absent or no match).',
+        args: z.object({
+            locator: z.string().describe('A raw Playwright locator expression.'),
+        }),
+        options: connectionOptions.extend({
+            name: z
+                .string()
+                .describe('The DOM attribute name to read (e.g. href, data-sitekey).'),
+        }),
+        output: z.object({
+            ok: z.literal(true),
+            verb: z.literal('getAttribute'),
+            name: z.string().describe('The attribute that was read.'),
+            value: z
+                .string()
+                .nullable()
+                .describe('The attribute value, or null if absent / no match.'),
+        }),
+        async run(c) {
+            try {
+                return await withSession(provider, targetFrom(c.options), async (s) => {
+                    const value = await s.page.getAttribute(locator(c.args.locator), c.options.name);
+                    return c.ok({
+                        ok: true,
+                        verb: 'getAttribute',
+                        name: c.options.name,
+                        value,
+                    }, { cta: { commands: [nextSnapshot()] } });
+                });
+            }
+            catch (cause) {
+                return fail(c, cause, binary);
+            }
+        },
+    });
+    // --- Tier-2 rich input verbs: press / hover / select / scroll / drag (prd
+    // broaden-agent-verb-surface, stories 8-12, R5). Each is its own incur
+    // command, so one definition yields both the CLI command and the MCP tool.
+    // Positional-arg + small-flag, mirroring `click` (R5); `select`/`scroll` use
+    // loud "exactly one of" validation, mirroring `wait`. No --frame flag: frame
+    // scope rides IN the locator string (R1).
+    cli.command('press', {
+        description: 'Press a keyboard key or chord (e.g. Enter, ArrowLeft, w, Control+A) at a ' +
+            'locator or, with no locator, the focused element.',
+        args: z.object({
+            key: z
+                .string()
+                .describe('A key or chord in Playwright grammar: a key name (Enter, ArrowLeft, ' +
+                'a) or Modifier+Key (Control+A, Shift+Tab).'),
+        }),
+        options: connectionOptions.extend({
+            locator: z
+                .string()
+                .optional()
+                .describe('A raw Playwright locator expression to press the key at (focuses it ' +
+                'first). Omit to press at the focused element.'),
+        }),
+        output: actionOutput.extend({ verb: z.literal('press') }),
+        async run(c) {
+            try {
+                return await withSession(provider, targetFrom(c.options), async (s) => {
+                    const target = c.options.locator !== undefined && c.options.locator !== ''
+                        ? locator(c.options.locator)
+                        : undefined;
+                    await s.page.press(c.args.key, target);
+                    return c.ok({ ok: true, verb: 'press' }, { cta: { commands: [nextSnapshot()] } });
+                });
+            }
+            catch (cause) {
+                return fail(c, cause, binary);
+            }
+        },
+    });
+    cli.command('hover', {
+        description: 'Hover the pointer over the element a Playwright locator addresses ' +
+            '(reveal hover menus / on-hover controls).',
+        args: z.object({
+            locator: z.string().describe('A raw Playwright locator expression.'),
+        }),
+        options: connectionOptions,
+        output: actionOutput.extend({ verb: z.literal('hover') }),
+        async run(c) {
+            try {
+                return await withSession(provider, targetFrom(c.options), async (s) => {
+                    await s.page.hover(locator(c.args.locator));
+                    return c.ok({ ok: true, verb: 'hover' }, { cta: { commands: [nextSnapshot()] } });
+                });
+            }
+            catch (cause) {
+                return fail(c, cause, binary);
+            }
+        },
+    });
+    cli.command('select', {
+        description: 'Choose an option in the native <select> a Playwright locator addresses, ' +
+            'by --value OR --label (exactly one).',
+        args: z.object({
+            locator: z
+                .string()
+                .describe('A raw Playwright locator expression for the <select>.'),
+        }),
+        options: connectionOptions.extend({
+            value: z
+                .string()
+                .optional()
+                .describe("Match the option's value attribute (value form)."),
+            label: z
+                .string()
+                .optional()
+                .describe("Match the option's visible label text (label form)."),
+        }),
+        output: actionOutput.extend({
+            verb: z.literal('select'),
+            by: z.enum(['value', 'label']),
+        }),
+        async run(c) {
+            const choice = selectChoiceFrom(c.options);
+            if (choice === undefined) {
+                return c.error({
+                    code: 'invalid-select',
+                    message: 'select needs exactly one of --value <v> or --label <l>.',
+                });
+            }
+            try {
+                return await withSession(provider, targetFrom(c.options), async (s) => {
+                    await s.page.select(locator(c.args.locator), choice);
+                    return c.ok({
+                        ok: true,
+                        verb: 'select',
+                        by: 'value' in choice ? 'value' : 'label',
+                    }, { cta: { commands: [nextSnapshot()] } });
+                });
+            }
+            catch (cause) {
+                return fail(c, cause, binary);
+            }
+        },
+    });
+    cli.command('scroll', {
+        description: 'Scroll the page, either --to a Playwright locator (bring it into view) ' +
+            'or --by a dx,dy pixel delta (exactly one).',
+        options: connectionOptions.extend({
+            to: z
+                .string()
+                .optional()
+                .describe('A raw Playwright locator expression to scroll into view (to form).'),
+            by: z
+                .string()
+                .optional()
+                .describe('A dx,dy pixel delta to scroll by, e.g. 0,400 (down) or -100,0 (by form).'),
+        }),
+        output: actionOutput.extend({
+            verb: z.literal('scroll'),
+            form: z.enum(['to', 'by']),
+        }),
+        async run(c) {
+            const target = scrollTargetFrom(c.options);
+            if (target === undefined) {
+                return c.error({
+                    code: 'invalid-scroll',
+                    message: 'scroll needs exactly one of --to <locator> or --by <dx,dy> ' +
+                        '(dx,dy two numbers, e.g. 0,400).',
+                });
+            }
+            try {
+                return await withSession(provider, targetFrom(c.options), async (s) => {
+                    await s.page.scroll(target);
+                    return c.ok({
+                        ok: true,
+                        verb: 'scroll',
+                        form: 'to' in target ? 'to' : 'by',
+                    }, { cta: { commands: [nextSnapshot()] } });
+                });
+            }
+            catch (cause) {
+                return fail(c, cause, binary);
+            }
+        },
+    });
+    cli.command('drag', {
+        description: 'Drag the element a source locator addresses onto the element a target ' +
+            'locator addresses (drag-reorder UIs, drag-slider challenges).',
+        args: z.object({
+            source: z
+                .string()
+                .describe('A raw Playwright locator expression for the drag source.'),
+            target: z
+                .string()
+                .describe('A raw Playwright locator expression for the drop target.'),
+        }),
+        options: connectionOptions,
+        output: actionOutput.extend({ verb: z.literal('drag') }),
+        async run(c) {
+            try {
+                return await withSession(provider, targetFrom(c.options), async (s) => {
+                    await s.page.drag(locator(c.args.source), locator(c.args.target));
+                    return c.ok({ ok: true, verb: 'drag' }, { cta: { commands: [nextSnapshot()] } });
+                });
+            }
+            catch (cause) {
+                return fail(c, cause, binary);
+            }
+        },
+    });
+    // --- Tier-4 coordinate + screenshot verbs: mouse / screenshot (prd
+    // broaden-agent-verb-surface, R3/R5, stories 17-19). Each is its own incur
+    // command, so one definition yields both the CLI command and the MCP tool.
+    // The seam stays string/number-typed (ADR-0003 as amended by the Tier-4 ADR):
+    // `mouse` passes plain numbers + an enum, `screenshot` returns a file PATH
+    // (never image bytes). The MCP `screenshot` result surfaces that path as the
+    // attachment-capable `path` field an agent reads/attaches.
+    cli.command('mouse', {
+        description: 'Coordinate mouse input at VIEWPORT CSS-pixels (Playwright page.mouse, NOT ' +
+            'OS screen coordinates): click / move / down / up at --x,--y. A pixel in a ' +
+            'VIEWPORT screenshot maps directly to these coordinates (the look-then-click ' +
+            'loop); a FULL-PAGE screenshot does NOT.',
+        options: connectionOptions.extend({
+            action: z
+                .enum(['click', 'move', 'down', 'up'])
+                .default('click')
+                .describe('What to do at the coordinate (default: click).'),
+            x: z.coerce.number().describe('Viewport CSS-pixel X (left-relative).'),
+            y: z.coerce.number().describe('Viewport CSS-pixel Y (top-relative).'),
+            button: z
+                .enum(['left', 'right', 'middle'])
+                .default('left')
+                .describe('Which button for click/down/up (default: left).'),
+        }),
+        output: actionOutput.extend({
+            verb: z.literal('mouse'),
+            action: z.enum(['click', 'move', 'down', 'up']),
+            x: z.number(),
+            y: z.number(),
+        }),
+        async run(c) {
+            try {
+                return await withSession(provider, targetFrom(c.options), async (s) => {
+                    const input = {
+                        action: c.options.action,
+                        x: c.options.x,
+                        y: c.options.y,
+                        button: c.options.button,
+                    };
+                    await s.page.mouse(input);
+                    return c.ok({
+                        ok: true,
+                        verb: 'mouse',
+                        action: c.options.action,
+                        x: c.options.x,
+                        y: c.options.y,
+                    }, { cta: { commands: [nextSnapshot()] } });
+                });
+            }
+            catch (cause) {
+                return fail(c, cause, binary);
+            }
+        },
+    });
+    cli.command('screenshot', {
+        description: 'Capture the page to a PNG FILE and return its PATH (never image bytes): ' +
+            '--scope viewport (default, coordinate-matched to mouse) | full (whole page, ' +
+            'NOT coordinate-matched) | element (clipped to --locator, REQUIRED for element). ' +
+            '--out overrides the path (validated to stay under the managed dir).',
+        options: connectionOptions.extend({
+            scope: z
+                .enum(['viewport', 'full', 'element'])
+                .default('viewport')
+                .describe('Region to capture: viewport (default) | full | element (needs --locator).'),
+            locator: z
+                .string()
+                .optional()
+                .describe('A raw Playwright locator expression to clip to (REQUIRED for --scope ' +
+                'element, rejected otherwise). Frame scope rides in the string.'),
+            out: z
+                .string()
+                .optional()
+                .describe('Override the output PNG path (validated to stay under the managed dir).'),
+        }),
+        output: z.object({
+            ok: z.literal(true),
+            verb: z.literal('screenshot'),
+            // `path` is the attachment-capable field (R5): a plain file PATH an agent
+            // reads / attaches; no image bytes ever cross the seam.
+            path: z
+                .string()
+                .describe('The PNG file path (read/attach this; never bytes).'),
+            width: z.number().describe('The PNG pixel width.'),
+            height: z.number().describe('The PNG pixel height.'),
+        }),
+        async run(c) {
+            const options = screenshotOptionsFrom(c.options);
+            if (options === undefined) {
+                return c.error({
+                    code: 'invalid-screenshot',
+                    message: 'screenshot --scope element requires --locator <expr>; --locator is ' +
+                        'only valid with --scope element.',
+                });
+            }
+            try {
+                return await withSession(provider, targetFrom(c.options), async (s) => {
+                    const shot = await s.page.screenshot(options);
+                    return c.ok({
+                        ok: true,
+                        verb: 'screenshot',
+                        path: shot.path,
+                        width: shot.width,
+                        height: shot.height,
+                    }, { cta: { commands: [nextSnapshot()] } });
+                });
+            }
+            catch (cause) {
+                return fail(c, cause, binary);
+            }
+        },
+    });
     cli.command('wait', {
         description: 'Pace actions by waiting for a timeout, a locator to appear, or the next navigation.',
         options: connectionOptions.extend({
@@ -662,8 +1183,11 @@ async function defaultServeSession(target, home, launchPolicy = {}) {
         ...(launchPolicy.noViewport !== undefined
             ? { noViewport: launchPolicy.noViewport }
             : {}),
+        ...(launchPolicy.proxy !== undefined ? { proxy: launchPolicy.proxy } : {}),
     });
-    const attach = new PlaywrightAttachTransport();
+    // attach reuses the user's browser, but the managed screenshots dir still
+    // honours the home-root override so a test isolates screenshot output.
+    const attach = new PlaywrightAttachTransport([], home);
     const transport = {
         open(t) {
             return t.mode === 'attach' ? attach.open(t) : launch.open(t);
@@ -687,6 +1211,80 @@ function waitConditionFrom(options) {
         forms.push({ kind: 'navigation' });
     return forms.length === 1 ? forms[0] : undefined;
 }
+/**
+ * Turn the `select` option forms into the seam's {@link SelectChoice}, or
+ * `undefined` if zero or both of `--value` / `--label` were given (the command
+ * reports that as a clear error). Mirrors `wait`'s loud "exactly one of"
+ * validation (R5): an empty string counts as absent, so `--value ''` is treated
+ * as not given.
+ */
+function selectChoiceFrom(options) {
+    const forms = [];
+    if (options.value !== undefined)
+        forms.push({ value: options.value });
+    if (options.label !== undefined)
+        forms.push({ label: options.label });
+    return forms.length === 1 ? forms[0] : undefined;
+}
+/**
+ * Turn the `scroll` option forms into the seam's {@link ScrollTarget}, or
+ * `undefined` if zero or both of `--to` / `--by` were given OR `--by` is not a
+ * valid `dx,dy` pair (the command reports that as a clear error). Mirrors
+ * `wait`'s loud "exactly one of" validation (R5). `--by` is parsed here (two
+ * comma-separated finite numbers) so a malformed delta fails loud rather than
+ * silently scrolling by `NaN`.
+ */
+function scrollTargetFrom(options) {
+    const forms = [];
+    if (options.to !== undefined && options.to !== '') {
+        forms.push({ to: locator(options.to) });
+    }
+    if (options.by !== undefined && options.by !== '') {
+        const by = parseDelta(options.by);
+        if (by === undefined)
+            return undefined;
+        forms.push({ by });
+    }
+    return forms.length === 1 ? forms[0] : undefined;
+}
+/**
+ * Turn the `screenshot` option flags into the seam's {@link ScreenshotOptions},
+ * or `undefined` when the scope/locator pairing is invalid (the command reports
+ * that as a clear error, mirroring `wait`'s loud validation, R5): `--scope
+ * element` REQUIRES `--locator`, and `--locator` is ONLY valid with `--scope
+ * element`. An empty `--locator`/`--out` string counts as absent. The seam
+ * re-validates as the load-bearing check (an untyped RPC client too), so this is
+ * the friendly fail-fast at the CLI edge.
+ */
+function screenshotOptionsFrom(options) {
+    const hasLocator = options.locator !== undefined && options.locator !== '';
+    if (options.scope === 'element' && !hasLocator)
+        return undefined;
+    if (options.scope !== 'element' && hasLocator)
+        return undefined;
+    return {
+        scope: options.scope,
+        ...(hasLocator ? { locator: locator(options.locator) } : {}),
+        ...(options.out !== undefined && options.out !== ''
+            ? { out: options.out }
+            : {}),
+    };
+}
+/**
+ * Parse a `dx,dy` pixel-delta string into a `{dx, dy}` pair, or `undefined` if
+ * it is not exactly two comma-separated finite numbers. Used by `scroll --by`
+ * so a malformed delta fails loud instead of scrolling by `NaN`.
+ */
+function parseDelta(raw) {
+    const parts = raw.split(',');
+    if (parts.length !== 2)
+        return undefined;
+    const dx = Number(parts[0].trim());
+    const dy = Number(parts[1].trim());
+    if (!Number.isFinite(dx) || !Number.isFinite(dy))
+        return undefined;
+    return { dx, dy };
+}
 /**
  * The shared failure path. Map a typed `core` error to its user-facing message
  * + exact fix command (PRD story 17); fall back to a generic error otherwise.