@webhands/core 0.4.0 → 0.6.0

package/src/index.ts

@@ -1,8 +1,22 @@
 export type {
+	ActionOptions,
+	BoundingBox,
 	Cookie,
 	Driver,
+	EvalOptions,
 	LocatorString,
+	MouseAction,
+	MouseButton,
+	MouseInput,
 	OpenTarget,
+	PwExtra,
+	QueryOptions,
+	QueryRow,
+	Screenshot,
+	ScreenshotOptions,
+	ScreenshotScope,
+	ScrollTarget,
+	SelectChoice,
 	WebHandsPage,
 	Session,
 	Snapshot,
@@ -11,7 +25,7 @@ export type {
 	Transport,
 	WaitCondition,
 } from './seam.js';
-export {locator} from './seam.js';
+export {locator, validateSnapshotOptions} from './seam.js';
 
 export {
 	serializeCookies,
@@ -42,6 +56,12 @@ export {
 	type StealthChromiumImporter,
 } from './playwright-launch-transport.js';
 
+export {
+	parseSocksProxy,
+	hostResolverRulesArg,
+	type ParsedSocksProxy,
+} from './socks-proxy.js';
+
 export {PlaywrightAttachTransport} from './playwright-attach-transport.js';
 
 export {
@@ -56,11 +76,15 @@ export {
 	ControllerError,
 	MissingBrowserBinaryError,
 	MissingStealthDependencyError,
+	InvalidProxyError,
 	MissingProfileError,
 	AttachNotChromiumError,
 	AttachNoContextError,
 	NoLiveServerError,
 	SessionAlreadyActiveError,
+	CrossOriginFrameError,
+	ScreenshotPathError,
+	StaleRefError,
 	isControllerError,
 	type ControllerErrorCode,
 } from './errors.js';
@@ -97,9 +121,11 @@ export {
 export {
 	resolveHomeRoot,
 	resolveProfileLocation,
+	resolveScreenshotsDir,
 	CONTROLLER_HOME_ENV,
 	DEFAULT_HOME_DIRNAME,
 	PROFILES_DIRNAME,
+	SCREENSHOTS_DIRNAME,
 	type ProfileLocation,
 	type ProfileLocationOptions,
 } from './profile-location.js';

package/src/playwright-attach-transport.ts

@@ -6,6 +6,10 @@ import {
 } from 'playwright';
 import {AttachNoContextError, AttachNotChromiumError} from './errors.js';
 import {composeWithHands, type Hand, type HandContext} from './hand-host.js';
+import {
+	resolveScreenshotsDir,
+	type ProfileLocationOptions,
+} from './profile-location.js';
 import type {OpenTarget, Session, Transport} from './seam.js';
 
 /**
@@ -33,15 +37,26 @@ import type {OpenTarget, Session, Transport} from './seam.js';
  */
 export class PlaywrightAttachTransport implements Transport {
 	readonly #hands: readonly Hand[];
+	readonly #location: ProfileLocationOptions;
 
 	/**
 	 * @param hands explicitly-loaded third-party hands to compose alongside the
 	 *   built-ins (Phase 2, ADR-0007). These come from {@link loadHands} against
 	 *   the operator's explicit config; the transport does NOT discover them. Omit
 	 *   for the built-ins-only surface.
+	 * @param location overrides for the controller home root, used ONLY to resolve
+	 *   the managed SCREENSHOTS dir (`<homeRoot>/screenshots`) the Tier-4
+	 *   `screenshot` verb mints under — attach reuses the user's own browser, so it
+	 *   owns no profile dir, but the screenshot output location still honours the
+	 *   same `root`/`WEBHANDS_HOME` override so a test can isolate it. Omit in
+	 *   production to use `~/.webhands/screenshots`.
 	 */
-	constructor(hands: readonly Hand[] = []) {
+	constructor(
+		hands: readonly Hand[] = [],
+		location: ProfileLocationOptions = {},
+	) {
 		this.#hands = hands;
+		this.#location = location;
 	}
 
 	async open(target: OpenTarget): Promise<Session> {
@@ -77,7 +92,8 @@ export class PlaywrightAttachTransport implements Transport {
 			// browser exposes a context with no page yet (single active session in
 			// v1, PRD Out of Scope).
 			const pwPage = context.pages()[0] ?? (await context.newPage());
-			return makeAttachedSession(browser, pwPage, this.#hands);
+			const screenshotsDir = resolveScreenshotsDir(this.#location);
+			return makeAttachedSession(browser, pwPage, this.#hands, screenshotsDir);
 		} catch (cause) {
 			// On any open-time refusal, disconnect from the user's browser without
 			// closing it (a CDP connection close detaches; it does not kill the
@@ -107,6 +123,7 @@ function makeAttachedSession(
 	browser: Browser,
 	pwPage: Page,
 	extraHands: readonly Hand[],
+	screenshotsDir: string,
 ): Session {
 	const context: BrowserContext = pwPage.context();
 	let closed = false;
@@ -134,7 +151,12 @@ function makeAttachedSession(
 	// the same shared host the launch transport uses, so the verbs behave
 	// identically across both transports. The live `pwPage`/`context` stay
 	// in-process and never cross the seam (ADR-0003).
-	const handContext: HandContext = {pwPage, context, ensureOpen};
+	const handContext: HandContext = {
+		pwPage,
+		context,
+		ensureOpen,
+		screenshotsDir,
+	};
 	const {page, dispose: disposeHands} = composeWithHands(
 		handContext,
 		extraHands,

package/src/playwright-launch-transport.ts

@@ -8,8 +8,10 @@ import {
 import {composeWithHands, type Hand, type HandContext} from './hand-host.js';
 import {
 	resolveProfileLocation,
+	resolveScreenshotsDir,
 	type ProfileLocationOptions,
 } from './profile-location.js';
+import {hostResolverRulesArg, parseSocksProxy} from './socks-proxy.js';
 import type {OpenTarget, Session, Transport} from './seam.js';
 
 /**
@@ -116,6 +118,29 @@ export interface PlaywrightLaunchTransportOptions {
 	 * Default: none.
 	 */
 	readonly ignoreDefaultArgs?: boolean | readonly string[];
+	/**
+	 * Route ALL browser traffic AND DNS through a single SOCKS proxy, given as a
+	 * SOCKS URL: `socks5h://host:1080` (or `socks5://host:1080`, optionally with a
+	 * `user:pass@` userinfo). When set, the transport forwards the proxy to
+	 * Playwright's `proxy` launch option AND adds Chromium's `--host-resolver-rules`
+	 * catch-all so no DNS query escapes locally (see {@link proxyNoLeak}).
+	 *
+	 * Scheme convention: `socks5h://` means "resolve DNS at the proxy" (no leak),
+	 * `socks5://` means "SOCKS5, local DNS allowed" (Chromium still resolves URL
+	 * hostnames at the proxy, but its DNS prefetcher etc. may issue local DNS). Use
+	 * {@link proxyNoLeak} to override the scheme's implied DNS behaviour. A
+	 * malformed value throws the typed {@link InvalidProxyError} rather than
+	 * launching unproxied. Default: no proxy.
+	 */
+	readonly proxy?: string;
+	/**
+	 * Override whether the {@link proxy} enforces NO local DNS. `true` forces the
+	 * leak-free catch-all even for a plain `socks5://` URL; `false` allows local
+	 * DNS even for a `socks5h://` URL. When omitted, the SCHEME decides
+	 * (`socks5h` => no leak, `socks5`/`socks` => local DNS allowed). Ignored when
+	 * {@link proxy} is unset.
+	 */
+	readonly proxyNoLeak?: boolean;
 	/**
 	 * INTERNAL test seam: override how the stealth chromium is imported. Omit in
 	 * production (defaults to `import('patchright')`). See
@@ -173,6 +198,8 @@ export class PlaywrightLaunchTransport implements Transport {
 	readonly #noViewport: boolean | undefined;
 	readonly #extraLaunchArgs: readonly string[] | undefined;
 	readonly #ignoreDefaultArgs: boolean | readonly string[] | undefined;
+	readonly #proxy: string | undefined;
+	readonly #proxyNoLeak: boolean | undefined;
 	readonly #importStealthChromium: StealthChromiumImporter;
 
 	/**
@@ -202,6 +229,8 @@ export class PlaywrightLaunchTransport implements Transport {
 		this.#noViewport = options.noViewport;
 		this.#extraLaunchArgs = options.extraLaunchArgs;
 		this.#ignoreDefaultArgs = options.ignoreDefaultArgs;
+		this.#proxy = options.proxy;
+		this.#proxyNoLeak = options.proxyNoLeak;
 		this.#importStealthChromium =
 			options.importStealthChromium ?? defaultStealthImporter;
 	}
@@ -266,15 +295,35 @@ export class PlaywrightLaunchTransport implements Transport {
 		} else if (this.#stealth) {
 			launchOptions.ignoreDefaultArgs = ['--enable-automation'];
 		}
+		// Proxy: route ALL traffic + DNS through one SOCKS proxy. We parse the URL
+		// HERE (a malformed value is the typed InvalidProxyError, never a silent
+		// unproxied launch), forward it to Playwright's `proxy` option, and when
+		// no-leak is in effect add Chromium's --host-resolver-rules catch-all so even
+		// the DNS prefetcher cannot leak a raw local DNS query.
+		const hardeningArgs: string[] = [];
+		if (this.#proxy !== undefined && this.#proxy.trim() !== '') {
+			const parsed = parseSocksProxy(this.#proxy, this.#proxyNoLeak);
+			launchOptions.proxy = {
+				server: parsed.server,
+				...(parsed.username !== undefined ? {username: parsed.username} : {}),
+				...(parsed.password !== undefined ? {password: parsed.password} : {}),
+			};
+			if (parsed.noLeak) {
+				hardeningArgs.push(hostResolverRulesArg(parsed.host));
+			}
+		}
 		// Extra launch args (the hardening escape hatch) are appended verbatim. We do
 		// NOT set user-agent/locale/timezone/headers here: a wrong UA is a bigger
 		// tell than none (Patchright warns against overriding them), so those stay
-		// untouched by default.
+		// untouched by default. The proxy's no-leak DNS arg (if any) rides alongside.
 		if (
 			this.#extraLaunchArgs !== undefined &&
 			this.#extraLaunchArgs.length > 0
 		) {
-			launchOptions.args = [...this.#extraLaunchArgs];
+			hardeningArgs.push(...this.#extraLaunchArgs);
+		}
+		if (hardeningArgs.length > 0) {
+			launchOptions.args = hardeningArgs;
 		}
 
 		let context: BrowserContext;
@@ -298,7 +347,11 @@ export class PlaywrightLaunchTransport implements Transport {
 		// the single active page (PRD: single active session in v1). Create one if
 		// the build ever changes that invariant.
 		const pwPage = context.pages()[0] ?? (await context.newPage());
-		return makeSession(context, pwPage, this.#hands);
+		// The managed screenshots dir resolves from the SAME location override as
+		// profiles (`<homeRoot>/screenshots`), so a test's temp `root` isolates
+		// screenshots too and the real `~/.webhands/screenshots` stays untouched.
+		const screenshotsDir = resolveScreenshotsDir(this.#location);
+		return makeSession(context, pwPage, this.#hands, screenshotsDir);
 	}
 
 	/**
@@ -379,6 +432,7 @@ function makeSession(
 	context: BrowserContext,
 	pwPage: Page,
 	extraHands: readonly Hand[],
+	screenshotsDir: string,
 ): Session {
 	let closed = false;
 	const ensureOpen = () => {
@@ -405,7 +459,12 @@ function makeSession(
 	// Build the verb surface from the built-in hands over a live hand-context.
 	// The host keeps the live `pwPage`/`context` in-process (they never cross the
 	// seam, ADR-0003); the hand-context carries live page access only.
-	const handContext: HandContext = {pwPage, context, ensureOpen};
+	const handContext: HandContext = {
+		pwPage,
+		context,
+		ensureOpen,
+		screenshotsDir,
+	};
 	const {page, dispose: disposeHands} = composeWithHands(
 		handContext,
 		extraHands,

package/src/profile-location.ts

@@ -30,6 +30,16 @@ export const CONTROLLER_HOME_ENV = 'WEBHANDS_HOME';
 /** The subdirectory under the home root that holds dedicated profiles. */
 export const PROFILES_DIRNAME = 'profiles';
 
+/**
+ * The subdirectory under the home root where the `screenshot` verb MINTS its
+ * PNG files (the Tier-4 managed screenshots dir, prd
+ * `broaden-agent-verb-surface`, R3). It lives BESIDE `profiles/` under the SAME
+ * overridable home root, so the same `root`/`WEBHANDS_HOME` override that
+ * isolates profiles in a test also isolates screenshots — nothing writes to the
+ * real `~/.webhands/screenshots` unless the home root points there.
+ */
+export const SCREENSHOTS_DIRNAME = 'screenshots';
+
 /** Inputs that influence where a profile resolves (all optional, for tests). */
 export interface ProfileLocationOptions {
 	/**
@@ -90,3 +100,18 @@ export function resolveProfileLocation(
 		profile,
 	};
 }
+
+/**
+ * Resolve the managed SCREENSHOTS directory (`<homeRoot>/screenshots`) the
+ * `screenshot` verb mints PNGs under (prd `broaden-agent-verb-surface`, R3).
+ * Like {@link resolveProfileLocation} it is PURE (creates no directory) and
+ * honours the same `root`/`WEBHANDS_HOME` precedence, so a test that points the
+ * home root at a temp dir isolates screenshots there and the real
+ * `~/.webhands/screenshots` stays untouched. The verb (in the transport) is
+ * responsible for creating the dir lazily on first write.
+ */
+export function resolveScreenshotsDir(
+	options: ProfileLocationOptions = {},
+): string {
+	return join(resolveHomeRoot(options), SCREENSHOTS_DIRNAME);
+}