webhands 0.3.0 → 0.4.0

package/src/errors.ts

@@ -8,6 +8,9 @@ import {
 	AttachNoContextError,
 	NoLiveServerError,
 	SessionAlreadyActiveError,
+	CrossOriginFrameError,
+	ScreenshotPathError,
+	StaleRefError,
 	type ControllerError,
 	type ControllerErrorCode,
 } from '@webhands/core';
@@ -78,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.
@@ -123,5 +145,8 @@ export {
 	AttachNoContextError,
 	NoLiveServerError,
 	SessionAlreadyActiveError,
+	CrossOriginFrameError,
+	ScreenshotPathError,
+	StaleRefError,
 };
 export type {ControllerError, ControllerErrorCode};