webhands 0.3.0 → 0.4.0

package/src/cli.ts

@@ -12,8 +12,13 @@ import {
 	SessionAlreadyActiveError,
 	startSessionServer,
 	type Cookie,
+	type MouseInput,
 	type OpenTarget,
 	type RunningSessionServer,
+	type ScreenshotOptions,
+	type ScreenshotScope,
+	type ScrollTarget,
+	type SelectChoice,
 	type Session,
 	type SessionServerOptions,
 	type Transport,
@@ -259,6 +264,11 @@ function nextAct() {
 			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.',
@@ -663,15 +673,28 @@ export function createCli(deps: CliDeps = {}) {
 			locator: z
 				.string()
 				.describe(
-					"A raw Playwright locator expression, e.g. getByRole('button', { name: 'Search' }).",
+					"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 as const, verb: 'click' as const},
 						{cta: {commands: [nextSnapshot()]}},
@@ -689,15 +712,31 @@ export function createCli(deps: CliDeps = {}) {
 		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 as const, verb: 'type' as const},
 						{cta: {commands: [nextSnapshot()]}},
@@ -719,7 +758,19 @@ export function createCli(deps: CliDeps = {}) {
 					'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'),
@@ -730,7 +781,12 @@ export function createCli(deps: CliDeps = {}) {
 		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 as const, verb: 'eval' as const, result},
 						{cta: {commands: [nextSnapshot()]}},
@@ -742,6 +798,569 @@ export function createCli(deps: CliDeps = {}) {
 		},
 	});
 
+	// --- 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 as const, verb: 'query' as const, 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 as const, verb: 'count' as const, 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 as const, verb: 'exists' as const, 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 as const, verb: 'isVisible' as const, 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 as const,
+							verb: 'getAttribute' as const,
+							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 as const, verb: 'press' as const},
+						{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 as const, verb: 'hover' as const},
+						{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 as const,
+							verb: 'select' as const,
+							by: 'value' in choice ? ('value' as const) : ('label' as const),
+						},
+						{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 as const,
+							verb: 'scroll' as const,
+							form: 'to' in target ? ('to' as const) : ('by' as const),
+						},
+						{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 as const, verb: 'drag' as const},
+						{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: MouseInput = {
+						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 as const,
+							verb: 'mouse' as const,
+							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 as const,
+							verb: 'screenshot' as const,
+							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.',
@@ -880,7 +1499,9 @@ async function defaultServeSession(
 			: {}),
 		...(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: Transport = {
 		open(t: OpenTarget): Promise<Session> {
 			return t.mode === 'attach' ? attach.open(t) : launch.open(t);
@@ -908,6 +1529,87 @@ function waitConditionFrom(options: {
 	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: {
+	value?: string;
+	label?: string;
+}): SelectChoice | undefined {
+	const forms: SelectChoice[] = [];
+	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: {
+	to?: string;
+	by?: string;
+}): ScrollTarget | undefined {
+	const forms: ScrollTarget[] = [];
+	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: {
+	scope: ScreenshotScope;
+	locator?: string;
+	out?: string;
+}): ScreenshotOptions | undefined {
+	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: string): {dx: number; dy: number} | undefined {
+	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.