@webhands/core 0.5.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,
@@ -68,6 +82,9 @@ export {
 	AttachNoContextError,
 	NoLiveServerError,
 	SessionAlreadyActiveError,
+	CrossOriginFrameError,
+	ScreenshotPathError,
+	StaleRefError,
 	isControllerError,
 	type ControllerErrorCode,
 } from './errors.js';
@@ -104,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,6 +8,7 @@ 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';
@@ -346,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);
 	}
 
 	/**
@@ -427,6 +432,7 @@ function makeSession(
 	context: BrowserContext,
 	pwPage: Page,
 	extraHands: readonly Hand[],
+	screenshotsDir: string,
 ): Session {
 	let closed = false;
 	const ensureOpen = () => {
@@ -453,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);
+}