@webhands/core 0.4.0 → 0.6.0

package/src/session-rpc.ts

@@ -1,7 +1,18 @@
 import {
 	locator,
+	validateSnapshotOptions,
+	type ActionOptions,
 	type Cookie,
+	type EvalOptions,
+	type MouseInput,
+	type QueryOptions,
+	type QueryRow,
+	type Screenshot,
+	type ScreenshotOptions,
+	type ScrollTarget,
+	type SelectChoice,
 	type Snapshot,
+	type SnapshotOptions,
 	type WaitCondition,
 } from './seam.js';
 import type {WebHandsPage} from './seam.js';
@@ -64,12 +75,78 @@ export type SessionRpcRequest =
 export type SessionRpcBuiltInRequest =
 	| {readonly verb: 'navigate'; readonly url: string}
 	| {readonly verb: 'snapshot'; readonly full?: boolean}
-	| {readonly verb: 'click'; readonly locator: string}
-	| {readonly verb: 'type'; readonly locator: string; readonly text: string}
-	| {readonly verb: 'eval'; readonly expression: string}
+	| {
+			readonly verb: 'click';
+			readonly locator: string;
+			/**
+			 * Optional {@link ActionOptions}: `{byRef: true}` marks `locator` as a
+			 * durable `query` `ref` so the server resolves it with the loud-stale
+			 * EXACTLY-ONE contract ({@link StaleRefError}). Omitted == plain locator
+			 * click (additive, R1).
+			 */
+			readonly options?: ActionOptions;
+	  }
+	| {
+			readonly verb: 'type';
+			readonly locator: string;
+			readonly text: string;
+			/** Optional {@link ActionOptions} (`{byRef}`); see the `click` request. */
+			readonly options?: ActionOptions;
+	  }
+	| {
+			readonly verb: 'eval';
+			readonly expression: string;
+			/**
+			 * Optional SAME-ORIGIN child-frame selector to evaluate in (Tier-3 frame
+			 * scope). A plain string on the wire; the server passes it as the seam
+			 * {@link EvalOptions.frame}. Omitted == top-document `eval`.
+			 */
+			readonly frame?: string;
+	  }
 	| {readonly verb: 'wait'; readonly condition: WaitCondition}
 	| {readonly verb: 'cookies'}
-	| {readonly verb: 'setCookies'; readonly cookies: readonly Cookie[]};
+	| {readonly verb: 'setCookies'; readonly cookies: readonly Cookie[]}
+	| {
+			readonly verb: 'query';
+			readonly locator: string;
+			readonly options?: QueryOptions;
+	  }
+	| {readonly verb: 'count'; readonly locator: string}
+	| {readonly verb: 'exists'; readonly locator: string}
+	| {readonly verb: 'isVisible'; readonly locator: string}
+	| {
+			readonly verb: 'getAttribute';
+			readonly locator: string;
+			readonly name: string;
+	  }
+	| {
+			readonly verb: 'press';
+			readonly key: string;
+			readonly locator?: string;
+	  }
+	| {readonly verb: 'hover'; readonly locator: string}
+	| {
+			readonly verb: 'select';
+			readonly locator: string;
+			readonly choice: SelectChoice;
+	  }
+	| {readonly verb: 'scroll'; readonly target: ScrollTarget}
+	| {
+			readonly verb: 'drag';
+			readonly source: string;
+			readonly target: string;
+	  }
+	| {readonly verb: 'mouse'; readonly input: MouseInput}
+	| {
+			readonly verb: 'screenshot';
+			/**
+			 * The {@link ScreenshotOptions}, flattened onto the request. `locator`
+			 * (the `element` scope's clip target) is a branded {@link LocatorString}
+			 * that JSON flattens to a plain string; the server re-brands it with
+			 * {@link locator}. No image bytes ever cross — only the path comes back.
+			 */
+			readonly options?: ScreenshotOptions;
+	  };
 
 /**
  * The OPEN escape for a dynamically-loaded third-party hand verb (Phase 2,
@@ -119,15 +196,35 @@ export async function applySessionRpc(
 			await page.navigate(request.url);
 			return undefined;
 		case 'snapshot':
-			return page.snapshot({full: request.full});
+			// Validate on the SERVER side so a malformed request from ANY client
+			// (not just the typed `makeRpcPage`) is rejected faithfully across the
+			// seam, mirroring how a page/eval throw rejects. A raw client could POST
+			// e.g. `{verb: 'snapshot', view: 'full'}`; we rebuild the snapshot
+			// options from the request's non-`verb` keys and reject unknown ones
+			// rather than silently dropping them and returning the wrong view.
+			return page.snapshot(snapshotOptionsFromRequest(request));
 		case 'click':
-			await page.click(locator(request.locator));
+			// Forward the optional ActionOptions only when given, so a plain-locator
+			// click stays `click(target)` (the byRef path is opt-in).
+			await page.click(
+				locator(request.locator),
+				request.options !== undefined ? request.options : undefined,
+			);
 			return undefined;
 		case 'type':
-			await page.type(locator(request.locator), request.text);
+			await page.type(
+				locator(request.locator),
+				request.text,
+				request.options !== undefined ? request.options : undefined,
+			);
 			return undefined;
 		case 'eval':
-			return page.eval(request.expression);
+			// Forward the optional frame selector only when present, so a bare
+			// top-document eval stays `eval(expression)` (no options object).
+			return page.eval(
+				request.expression,
+				request.frame !== undefined ? {frame: request.frame} : undefined,
+			);
 		case 'wait':
 			await page.wait(rebrandWait(request.condition));
 			return undefined;
@@ -136,11 +233,73 @@ export async function applySessionRpc(
 		case 'setCookies':
 			await page.setCookies(request.cookies);
 			return undefined;
+		case 'query':
+			return page.query(locator(request.locator), request.options);
+		case 'count':
+			return page.count(locator(request.locator));
+		case 'exists':
+			return page.exists(locator(request.locator));
+		case 'isVisible':
+			return page.isVisible(locator(request.locator));
+		case 'getAttribute':
+			return page.getAttribute(locator(request.locator), request.name);
+		case 'press':
+			await page.press(
+				request.key,
+				request.locator !== undefined ? locator(request.locator) : undefined,
+			);
+			return undefined;
+		case 'hover':
+			await page.hover(locator(request.locator));
+			return undefined;
+		case 'select':
+			await page.select(locator(request.locator), request.choice);
+			return undefined;
+		case 'scroll':
+			await page.scroll(rebrandScroll(request.target));
+			return undefined;
+		case 'drag':
+			await page.drag(locator(request.source), locator(request.target));
+			return undefined;
+		case 'mouse':
+			await page.mouse(request.input);
+			return undefined;
+		case 'screenshot':
+			// Re-brand the `element`-scope clip locator (plain string over the wire)
+			// before it reaches the page; the rest of the options are plain. Only the
+			// returned {path,width,height} crosses back — never image bytes.
+			return page.screenshot(rebrandScreenshot(request.options));
 		case 'hand':
 			return applyHandVerb(page, request);
 	}
 }
 
+/**
+ * Rebuild and validate the {@link SnapshotOptions} carried by a wire `snapshot`
+ * request. The wire flattens `{full}` onto the request alongside `verb`; a raw
+ * (untyped) client may also send a misspelled key such as `view`. We collect
+ * every non-`verb` key into an options object and run it through the shared
+ * {@link validateSnapshotOptions} so the server rejects an unknown/misshapen
+ * option exactly as the in-process host does. Returns `undefined` when no
+ * options were sent (the bare `snapshot()` case).
+ */
+function snapshotOptionsFromRequest(
+	request: SessionRpcRequest & {readonly verb: 'snapshot'},
+): SnapshotOptions | undefined {
+	const {verb: _verb, ...rest} = request as Record<string, unknown> & {
+		verb: 'snapshot';
+	};
+	// Drop an explicitly-absent `full` (the typed client always sends the key,
+	// even as `undefined`) so a bare `snapshot()` stays `undefined`.
+	if ('full' in rest && rest.full === undefined) {
+		delete rest.full;
+	}
+	if (Object.keys(rest).length === 0) {
+		return undefined;
+	}
+	return validateSnapshotOptions(rest as SnapshotOptions);
+}
+
 /**
  * Invoke a dynamically-loaded hand verb by name against the live composed page.
  *
@@ -191,19 +350,41 @@ export function makeRpcPage(
 			await send({verb: 'navigate', url});
 		},
 		async snapshot(options) {
+			// Fail fast on the client too, so a typed caller's mistake (e.g.
+			// `{view: 'full'}`) is caught before a round-trip. The server
+			// re-validates as the load-bearing check for untyped clients.
+			validateSnapshotOptions(options);
 			return (await send({
 				verb: 'snapshot',
 				full: options?.full,
 			})) as Snapshot;
 		},
-		async click(target) {
-			await send({verb: 'click', locator: target});
+		async click(target, options) {
+			// Carry the optional ActionOptions only when given, so a plain click sends
+			// no `options` key (mirrors `eval`'s optional frame).
+			await send({
+				verb: 'click',
+				locator: target,
+				...(options !== undefined ? {options} : {}),
+			});
 		},
-		async type(target, text) {
-			await send({verb: 'type', locator: target, text});
+		async type(target, text, options) {
+			await send({
+				verb: 'type',
+				locator: target,
+				text,
+				...(options !== undefined ? {options} : {}),
+			});
 		},
-		async eval(expression) {
-			return send({verb: 'eval', expression});
+		async eval(expression, options) {
+			// Carry the optional frame selector only when given, so the focused
+			// top-document form sends no `frame` key (mirrors `press`'s optional
+			// locator).
+			return send({
+				verb: 'eval',
+				expression,
+				...(options?.frame !== undefined ? {frame: options.frame} : {}),
+			});
 		},
 		async wait(condition) {
 			await send({verb: 'wait', condition});
@@ -214,6 +395,59 @@ export function makeRpcPage(
 		async setCookies(cookies) {
 			await send({verb: 'setCookies', cookies});
 		},
+		async query(target, options) {
+			return (await send({
+				verb: 'query',
+				locator: target,
+				options,
+			})) as QueryRow[];
+		},
+		async count(target) {
+			return (await send({verb: 'count', locator: target})) as number;
+		},
+		async exists(target) {
+			return (await send({verb: 'exists', locator: target})) as boolean;
+		},
+		async isVisible(target) {
+			return (await send({verb: 'isVisible', locator: target})) as boolean;
+		},
+		async getAttribute(target, name) {
+			return (await send({
+				verb: 'getAttribute',
+				locator: target,
+				name,
+			})) as string | null;
+		},
+		async press(key, target) {
+			// Forward the optional locator only when given, so the wire request stays
+			// minimal (the focused-element form carries no locator key).
+			await send({
+				verb: 'press',
+				key,
+				...(target !== undefined ? {locator: target} : {}),
+			});
+		},
+		async hover(target) {
+			await send({verb: 'hover', locator: target});
+		},
+		async select(target, choice) {
+			await send({verb: 'select', locator: target, choice});
+		},
+		async scroll(target) {
+			await send({verb: 'scroll', target});
+		},
+		async drag(source, target) {
+			await send({verb: 'drag', source, target});
+		},
+		async mouse(input) {
+			await send({verb: 'mouse', input});
+		},
+		async screenshot(options) {
+			return (await send({
+				verb: 'screenshot',
+				...(options !== undefined ? {options} : {}),
+			})) as Screenshot;
+		},
 	};
 }
 
@@ -251,3 +485,31 @@ function rebrandWait(condition: WaitCondition): WaitCondition {
 	}
 	return condition;
 }
+
+/**
+ * Re-brand a {@link ScrollTarget} that arrived as plain JSON: only the `to` form
+ * carries a branded {@link LocatorString}, flattened to a plain `string` over
+ * the wire, so we re-tag it before it reaches the page (mirrors
+ * {@link rebrandWait}). The `by` form carries only plain numbers.
+ */
+function rebrandScroll(target: ScrollTarget): ScrollTarget {
+	if ('to' in target) {
+		return {to: locator(target.to)};
+	}
+	return target;
+}
+
+/**
+ * Re-brand a {@link ScreenshotOptions} that arrived as plain JSON: only the
+ * `element`-scope `locator` carries a branded {@link LocatorString}, flattened
+ * to a plain `string` over the wire, so we re-tag it before it reaches the page
+ * (mirrors {@link rebrandWait}/{@link rebrandScroll}). `scope`/`out` are plain.
+ */
+function rebrandScreenshot(
+	options?: ScreenshotOptions,
+): ScreenshotOptions | undefined {
+	if (options?.locator === undefined) {
+		return options;
+	}
+	return {...options, locator: locator(options.locator)};
+}

package/src/socks-proxy.ts

@@ -0,0 +1,127 @@
+import {InvalidProxyError} from './errors.js';
+
+/**
+ * A parsed SOCKS proxy ready to hand to Playwright/Chromium.
+ *
+ * This is the SINGLE place webhands turns a user-facing `--proxy` SOCKS URL into
+ * the concrete launch inputs Chromium needs: the `proxy.server`/credentials
+ * Playwright forwards, plus the extra command-line arg that forces DNS through
+ * the proxy (no DNS leak). Keeping the brittle parsing + Chromium-flag knowledge
+ * in one module mirrors how the launch transport confines its other
+ * Playwright/Chromium details.
+ */
+export interface ParsedSocksProxy {
+	/**
+	 * The Playwright `proxy.server` value, always normalized to `socks5://host:port`.
+	 *
+	 * Chromium's `--proxy-server` understands `socks5://` but NOT the `socks5h://`
+	 * convention, so we normalize the scheme here and carry the "resolve DNS at
+	 * the proxy / block local DNS" intent separately in {@link noLeak} instead of
+	 * in the scheme string.
+	 */
+	readonly server: string;
+	/** Optional proxy username (from a `user:pass@` userinfo component). */
+	readonly username?: string;
+	/** Optional proxy password (from a `user:pass@` userinfo component). */
+	readonly password?: string;
+	/** The proxy host, used to build the DNS catch-all EXCLUDE rule. */
+	readonly host: string;
+	/**
+	 * Whether to enforce NO local DNS (force every hostname to resolve at the
+	 * proxy). When `true`, the transport adds a `--host-resolver-rules` catch-all
+	 * so even Chromium components that bypass `--proxy-server` (DNS prefetcher,
+	 * etc.) cannot leak a raw DNS query (see {@link hostResolverRulesArg}).
+	 */
+	readonly noLeak: boolean;
+}
+
+/**
+ * The SOCKS schemes we accept on a `--proxy` value.
+ *
+ * - `socks5h://` is the widely-used convention meaning "resolve DNS at the
+ *   proxy" (no local DNS, no leak). We map it to {@link ParsedSocksProxy.noLeak}
+ *   `true`.
+ * - `socks5://` means "SOCKS5, local DNS allowed" by the same convention. NOTE:
+ *   Chromium ALREADY resolves URL hostnames at the proxy under `--proxy-server`,
+ *   but other components (the DNS prefetcher) can still issue raw local DNS, so
+ *   plain `socks5://` does NOT by itself guarantee no leak.
+ *
+ * `socks://` is accepted as an alias for `socks5://` (some tools emit it).
+ */
+const SCHEME_NO_LEAK: Readonly<Record<string, boolean>> = {
+	'socks5h:': true,
+	'socks5:': false,
+	'socks:': false,
+};
+
+/**
+ * Parse a user-facing `--proxy` SOCKS URL into a {@link ParsedSocksProxy}.
+ *
+ * Accepts `socks5h://`, `socks5://`, or `socks://` with a host and port and an
+ * optional `user:pass@` userinfo. Anything else (missing host/port, an http(s)
+ * proxy, a bare host with no scheme) is a typed {@link InvalidProxyError} so the
+ * caller refuses LOUDLY rather than launching unproxied.
+ *
+ * `forceNoLeak`, when set, overrides the scheme's implied DNS behaviour: pass
+ * `true` to enforce no local DNS even for a plain `socks5://` URL, or `false` to
+ * allow local DNS even for `socks5h://`. When omitted, the SCHEME decides
+ * (`socks5h` => no-leak, `socks5`/`socks` => local DNS allowed).
+ */
+export function parseSocksProxy(
+	value: string,
+	forceNoLeak?: boolean,
+): ParsedSocksProxy {
+	const trimmed = value.trim();
+	if (trimmed === '') {
+		throw new InvalidProxyError(value);
+	}
+
+	let url: URL;
+	try {
+		url = new URL(trimmed);
+	} catch (cause) {
+		throw new InvalidProxyError(value, undefined, {cause});
+	}
+
+	const schemeNoLeak = SCHEME_NO_LEAK[url.protocol];
+	if (schemeNoLeak === undefined) {
+		// Not a SOCKS scheme (e.g. http://, https://, socks4://, or no scheme).
+		throw new InvalidProxyError(value);
+	}
+	if (url.hostname === '' || url.port === '') {
+		// A host AND an explicit port are both required: Chromium's --proxy-server
+		// needs the port, and we will not guess a default.
+		throw new InvalidProxyError(value);
+	}
+
+	const noLeak = forceNoLeak ?? schemeNoLeak;
+	const server = `socks5://${url.hostname}:${url.port}`;
+
+	const proxy: ParsedSocksProxy = {
+		server,
+		host: url.hostname,
+		noLeak,
+		...(url.username !== ''
+			? {username: decodeURIComponent(url.username)}
+			: {}),
+		...(url.password !== ''
+			? {password: decodeURIComponent(url.password)}
+			: {}),
+	};
+	return proxy;
+}
+
+/**
+ * Build the Chromium `--host-resolver-rules` argument that prevents ANY local
+ * DNS resolution, the catch-all the Chromium SOCKS design doc prescribes for a
+ * leak-free SOCKS proxy.
+ *
+ * `MAP * ~NOTFOUND` maps every hostname to an invalid address so Chromium never
+ * issues a real local DNS query; `EXCLUDE <host>` lets Chromium still resolve
+ * the proxy server's own address (otherwise every request fails with
+ * PROXY_CONNECTION_FAILED). URL loads themselves resolve at the proxy via
+ * `--proxy-server`; this arg closes the side channels (DNS prefetcher, etc.).
+ */
+export function hostResolverRulesArg(host: string): string {
+	return `--host-resolver-rules=MAP * ~NOTFOUND , EXCLUDE ${host}`;
+}

package/src/stub-transport.ts

@@ -1,13 +1,23 @@
 import type {
+	ActionOptions,
 	Cookie,
+	EvalOptions,
+	MouseInput,
 	OpenTarget,
 	WebHandsPage,
+	QueryOptions,
+	QueryRow,
+	Screenshot,
+	ScreenshotOptions,
+	ScrollTarget,
+	SelectChoice,
 	Session,
 	Snapshot,
 	SnapshotOptions,
 	Transport,
 	WaitCondition,
 } from './seam.js';
+import {validateSnapshotOptions} from './seam.js';
 
 /**
  * A record of one verb call against the stub, for assertions in seam tests.
@@ -60,6 +70,7 @@ export class StubTransport implements Transport {
 			},
 			async snapshot(options?: SnapshotOptions): Promise<Snapshot> {
 				ensureOpen();
+				validateSnapshotOptions(options);
 				calls.push({verb: 'snapshot', args: [options]});
 				return {
 					url,
@@ -67,17 +78,26 @@ export class StubTransport implements Transport {
 					content: '',
 				};
 			},
-			async click(t): Promise<void> {
+			async click(t, options?: ActionOptions): Promise<void> {
 				ensureOpen();
-				calls.push({verb: 'click', args: [t]});
+				// Record the ActionOptions only when given, so a plain-locator click
+				// stays `[t]` (the existing seam assertions) and a `{byRef}` click
+				// records `[t, {byRef: true}]`.
+				calls.push({
+					verb: 'click',
+					args: options !== undefined ? [t, options] : [t],
+				});
 			},
-			async type(t, text): Promise<void> {
+			async type(t, text, options?: ActionOptions): Promise<void> {
 				ensureOpen();
-				calls.push({verb: 'type', args: [t, text]});
+				calls.push({
+					verb: 'type',
+					args: options !== undefined ? [t, text, options] : [t, text],
+				});
 			},
-			async eval(expression: string): Promise<unknown> {
+			async eval(expression: string, options?: EvalOptions): Promise<unknown> {
 				ensureOpen();
-				calls.push({verb: 'eval', args: [expression]});
+				calls.push({verb: 'eval', args: [expression, options]});
 				return undefined;
 			},
 			async wait(condition: WaitCondition): Promise<void> {
@@ -93,6 +113,63 @@ export class StubTransport implements Transport {
 				ensureOpen();
 				calls.push({verb: 'setCookies', args: [cookies]});
 			},
+			async query(t, options?: QueryOptions): Promise<QueryRow[]> {
+				ensureOpen();
+				calls.push({verb: 'query', args: [t, options]});
+				return [];
+			},
+			async count(t): Promise<number> {
+				ensureOpen();
+				calls.push({verb: 'count', args: [t]});
+				return 0;
+			},
+			async exists(t): Promise<boolean> {
+				ensureOpen();
+				calls.push({verb: 'exists', args: [t]});
+				return false;
+			},
+			async isVisible(t): Promise<boolean> {
+				ensureOpen();
+				calls.push({verb: 'isVisible', args: [t]});
+				return false;
+			},
+			async getAttribute(t, name): Promise<string | null> {
+				ensureOpen();
+				calls.push({verb: 'getAttribute', args: [t, name]});
+				return null;
+			},
+			async press(key: string, t): Promise<void> {
+				ensureOpen();
+				calls.push({verb: 'press', args: [key, t]});
+			},
+			async hover(t): Promise<void> {
+				ensureOpen();
+				calls.push({verb: 'hover', args: [t]});
+			},
+			async select(t, choice: SelectChoice): Promise<void> {
+				ensureOpen();
+				calls.push({verb: 'select', args: [t, choice]});
+			},
+			async scroll(t: ScrollTarget): Promise<void> {
+				ensureOpen();
+				calls.push({verb: 'scroll', args: [t]});
+			},
+			async drag(source, t): Promise<void> {
+				ensureOpen();
+				calls.push({verb: 'drag', args: [source, t]});
+			},
+			async mouse(input: MouseInput): Promise<void> {
+				ensureOpen();
+				calls.push({verb: 'mouse', args: [input]});
+			},
+			async screenshot(options?: ScreenshotOptions): Promise<Screenshot> {
+				ensureOpen();
+				calls.push({verb: 'screenshot', args: [options]});
+				// A deterministic stand-in path/dimensions so a wiring test can assert
+				// the verb round-trip + the attachment-capable `path` field WITHOUT a
+				// real browser (no PNG is written; the stub implements no behaviour).
+				return {path: 'stub://screenshot.png', width: 0, height: 0};
+			},
 		};
 
 		return {