webhands 0.2.0 → 0.4.0

package/src/errors.ts

@@ -2,11 +2,15 @@ import {
 	isControllerError,
 	MissingBrowserBinaryError,
 	MissingStealthDependencyError,
+	InvalidProxyError,
 	MissingProfileError,
 	AttachNotChromiumError,
 	AttachNoContextError,
 	NoLiveServerError,
 	SessionAlreadyActiveError,
+	CrossOriginFrameError,
+	ScreenshotPathError,
+	StaleRefError,
 	type ControllerError,
 	type ControllerErrorCode,
 } from '@webhands/core';
@@ -52,6 +56,10 @@ export function fixCommandFor(error: ControllerError, binary: string): string {
 			// is absent. Name the package from the typed error so the install command
 			// is ready to run; we never silently fall back to vanilla Playwright.
 			return `pnpm add ${(error as MissingStealthDependencyError).dependency}`;
+		case 'invalid-proxy':
+			// The --proxy value could not be parsed into a SOCKS proxy. Show the
+			// expected URL shape; socks5h tunnels DNS too (no leak).
+			return `${binary} serve --proxy socks5h://host:1080 (or socks5://user:pass@host:1080)`;
 		case 'missing-profile':
 			// A profile is created by the headed `setup-profile` flow (the ONE place
 			// a profile dir is created — see core's MissingProfileError). Name the
@@ -73,6 +81,25 @@ export function fixCommandFor(error: ControllerError, binary: string): string {
 			// A session is already live; v1 holds exactly one. The fix is to tear it
 			// down before starting another.
 			return `${binary} stop`;
+		case 'cross-origin-frame':
+			// `eval --frame` reaches the top document and SAME-ORIGIN child frames
+			// only (page-world JS cannot cross a security boundary). There is no
+			// flag that makes a cross-origin frame reachable here; the fix is to
+			// target a same-origin frame, or omit --frame for the top document. (The
+			// cross-origin reach is the separate Tier-4 surface.)
+			return `${binary} eval '<expression>' (drop --frame for the top document, or pass a SAME-ORIGIN frame selector)`;
+		case 'screenshot-path-outside-managed-dir':
+			// A --out override escaped the managed screenshots dir. webhands writes
+			// only WITHIN that dir; the fix is to drop --out (let webhands mint a
+			// path) or pass one under the managed dir.
+			return `${binary} screenshot (drop --out to let webhands mint a path under ${(error as ScreenshotPathError).managedDir}, or pass an --out inside it)`;
+		case 'stale-ref':
+			// A durable `query` ref went stale (resolve-to-zero) or ambiguous
+			// (resolve-to-many) before the action ran: the page changed between the
+			// query and the act. There is no flag that revives a stale handle; the
+			// fix is to re-run `query --with-refs` against the fresh DOM and act on
+			// the NEW ref (the agent's natural read-then-act loop).
+			return `${binary} query '<locator>' --with-refs (re-read the page to get a fresh ref, then click/type --by-ref with it)`;
 		default: {
 			// Exhaustiveness guard: a new ControllerErrorCode must add a fix command
 			// here rather than silently fall through to a generic message.
@@ -112,10 +139,14 @@ export function mapControllerError(
 export {
 	MissingBrowserBinaryError,
 	MissingStealthDependencyError,
+	InvalidProxyError,
 	MissingProfileError,
 	AttachNotChromiumError,
 	AttachNoContextError,
 	NoLiveServerError,
 	SessionAlreadyActiveError,
+	CrossOriginFrameError,
+	ScreenshotPathError,
+	StaleRefError,
 };
 export type {ControllerError, ControllerErrorCode};