@webhands/core 0.5.0 → 0.6.0

package/dist/test-fixtures/fixture-pages.js.map

@@ -1 +1 @@
-{"version":3,"file":"fixture-pages.js","sourceRoot":"","sources":["../../src/test-fixtures/fixture-pages.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,KAAK,GAAG;;;;;;;;;;;;;CAab,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;CAqBvB,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BlB,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;CAenB,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,IAAI,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BZ,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,OAAO,GAAG;;;;;;;;;;;;;;;;CAgBf,CAAC;AAEF,+EAA+E;AAC/E,MAAM,CAAC,MAAM,aAAa,GAAqC;IAC9D,YAAY,EAAE,KAAK;IACnB,iBAAiB,EAAE,UAAU;IAC7B,cAAc,EAAE,eAAe;IAC/B,kBAAkB,EAAE,WAAW;IAC/B,WAAW,EAAE,IAAI;IACjB,cAAc,EAAE,OAAO;CACvB,CAAC"}
+{"version":3,"file":"fixture-pages.js","sourceRoot":"","sources":["../../src/test-fixtures/fixture-pages.ts"],"names":[],"mappings":"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"}

package/dist/test-fixtures/fixture-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fixture-server.d.ts","sourceRoot":"","sources":["../../src/test-fixtures/fixture-server.ts"],"names":[],"mappings":"AAGA,yEAAyE;AACzE,MAAM,WAAW,aAAa;IAC7B,mDAAmD;IACnD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,4CAA4C;IAC5C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,SAAI,GAAG,OAAO,CAAC,aAAa,CAAC,CAgCzE"}
+{"version":3,"file":"fixture-server.d.ts","sourceRoot":"","sources":["../../src/test-fixtures/fixture-server.ts"],"names":[],"mappings":"AAiBA,yEAAyE;AACzE,MAAM,WAAW,aAAa;IAC7B,mDAAmD;IACnD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,4CAA4C;IAC5C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,SAAI,GAAG,OAAO,CAAC,aAAa,CAAC,CA+CzE"}

package/dist/test-fixtures/fixture-server.js

@@ -1,5 +1,19 @@
 import { createServer } from 'node:http';
 import { FIXTURE_PAGES } from './fixture-pages.js';
+/** Largest artificial response delay a fixture request may ask for (a guard so
+ * a stray `?delayMs=` can never hang the suite). */
+const MAX_DELAY_MS = 5_000;
+/** Parse `?delayMs=N` from a request URL, clamped to `[0, MAX_DELAY_MS]`. */
+function parseDelayMs(reqUrl) {
+    const q = reqUrl.indexOf('?');
+    if (q === -1)
+        return 0;
+    const raw = new URLSearchParams(reqUrl.slice(q + 1)).get('delayMs');
+    const n = raw === null ? 0 : Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n <= 0)
+        return 0;
+    return Math.min(n, MAX_DELAY_MS);
+}
 /**
  * Start a local HTTP server that serves the controlled static fixture pages
  * from {@link FIXTURE_PAGES}. This is the DETERMINISTIC target for later
@@ -12,7 +26,8 @@ import { FIXTURE_PAGES } from './fixture-pages.js';
  */
 export async function startFixtureServer(port = 0) {
     const server = createServer((req, res) => {
-        const rawPath = (req.url ?? '/').split('?')[0];
+        const reqUrl = req.url ?? '/';
+        const rawPath = reqUrl.split('?')[0];
         const key = rawPath === '/' ? 'index.html' : rawPath.replace(/^\/+/, '');
         const body = FIXTURE_PAGES[key];
         if (body === undefined) {
@@ -20,8 +35,23 @@ export async function startFixtureServer(port = 0) {
             res.end('not found');
             return;
         }
-        res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
-        res.end(body);
+        // A `?delayMs=N` query holds the RESPONSE back by N ms before sending the
+        // (otherwise normal) page. This makes a slow NAVIGATION deterministic: a
+        // click that submits to `index.html?delayMs=1500` performs instantly but
+        // the navigation only commits ~1.5s later, the case the `click` verb must
+        // not mistake for a non-actionable element (it auto-waits for navigation
+        // only when not told otherwise). Capped so a bad value cannot hang a test.
+        const delayMs = parseDelayMs(reqUrl);
+        const send = () => {
+            res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+            res.end(body);
+        };
+        if (delayMs > 0) {
+            setTimeout(send, delayMs);
+        }
+        else {
+            send();
+        }
     });
     await new Promise((resolve) => server.listen(port, '127.0.0.1', resolve));
     const address = server.address();

package/dist/test-fixtures/fixture-server.js.map

@@ -1 +1 @@
-{"version":3,"file":"fixture-server.js","sourceRoot":"","sources":["../../src/test-fixtures/fixture-server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,YAAY,EAAc,MAAM,WAAW,CAAC;AACpD,OAAO,EAAC,aAAa,EAAC,MAAM,oBAAoB,CAAC;AAUjD;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,IAAI,GAAG,CAAC;IAChD,MAAM,MAAM,GAAW,YAAY,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;QAChD,MAAM,OAAO,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/C,MAAM,GAAG,GAAG,OAAO,KAAK,GAAG,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACzE,MAAM,IAAI,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;QAChC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACxB,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,EAAC,cAAc,EAAE,2BAA2B,EAAC,CAAC,CAAC;YAClE,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;YACrB,OAAO;QACR,CAAC;QACD,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,EAAC,cAAc,EAAE,0BAA0B,EAAC,CAAC,CAAC;QACjE,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACf,CAAC,CAAC,CAAC;IAEH,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CACnC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,CAAC,CACzC,CAAC;IAEF,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;IACjC,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QACrD,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QACpE,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;IAChE,CAAC;IAED,OAAO;QACN,GAAG,EAAE,oBAAoB,OAAO,CAAC,IAAI,EAAE;QACvC,KAAK;YACJ,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;gBAC5C,MAAM,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;YACxD,CAAC,CAAC,CAAC;QACJ,CAAC;KACD,CAAC;AACH,CAAC"}
+{"version":3,"file":"fixture-server.js","sourceRoot":"","sources":["../../src/test-fixtures/fixture-server.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webhands/core",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Core library for webhands: drives a real, persistent browser via Playwright.",
   "keywords": [
     "browser",

package/src/errors.ts

@@ -24,7 +24,10 @@ export type ControllerErrorCode =
 	| 'attach-not-chromium'
 	| 'attach-no-context'
 	| 'no-live-server'
-	| 'session-already-active';
+	| 'session-already-active'
+	| 'cross-origin-frame'
+	| 'screenshot-path-outside-managed-dir'
+	| 'stale-ref';
 
 /**
  * Base class for every identifiable `core` error. Branch on {@link code}.
@@ -230,6 +233,136 @@ export class SessionAlreadyActiveError extends ControllerError {
 	}
 }
 
+/**
+ * A frame-scoped `eval` (or any same-origin-frame op) addressed a CROSS-ORIGIN
+ * child frame. Page-world JS cannot cross a browser security boundary, so the
+ * frame-scoped `eval` reaches the top document and SAME-ORIGIN descendant frames
+ * ONLY (the idea's honest-scope note); a cross-origin frame is unreachable BY
+ * DESIGN, not a missing feature. We refuse LOUDLY with this typed condition
+ * rather than return a silent empty result, because a silent empty would let an
+ * agent believe its callback fired / its read succeeded when the security
+ * boundary actually blocked it.
+ *
+ * Cross-origin frame reach is the SEPARATE Tier-4 `frameLocator`/coordinate
+ * surface, not this verb; the message points there so the agent is not left
+ * guessing. Mirrors the other typed conditions: the CLI maps {@link code} to a
+ * message, and {@link isControllerError} narrows it across a bundle boundary.
+ */
+export class CrossOriginFrameError extends ControllerError {
+	readonly code = 'cross-origin-frame';
+	/** The frame selector the caller passed (echoed back so it is visible). */
+	readonly frame: string;
+	/** The cross-origin frame's origin, when known (e.g. `https://hcaptcha.com`). */
+	readonly frameOrigin?: string;
+	/** The page's own (main-frame) origin the frame had to match. */
+	readonly pageOrigin?: string;
+
+	constructor(
+		frame: string,
+		details?: {frameOrigin?: string; pageOrigin?: string},
+		message: string = `The frame ${JSON.stringify(frame)} is CROSS-ORIGIN${
+			details?.frameOrigin !== undefined && details?.pageOrigin !== undefined
+				? ` (frame origin ${details.frameOrigin}, page origin ${details.pageOrigin})`
+				: ''
+		} and is unreachable from page-world JS. eval --frame reaches the top document and SAME-ORIGIN child frames only; a cross-origin frame is a browser security boundary. Reach cross-origin frames with the Tier-4 frameLocator/coordinate ops instead.`,
+		options?: {cause?: unknown},
+	) {
+		super(message, options);
+		this.frame = frame;
+		this.frameOrigin = details?.frameOrigin;
+		this.pageOrigin = details?.pageOrigin;
+	}
+}
+
+/**
+ * A `screenshot --out <path>` override pointed OUTSIDE the managed screenshots
+ * dir. webhands MINTS screenshots under one managed directory it owns (under the
+ * controller home root, beside `profiles/`); a caller MAY override the output
+ * path, but only WITHIN that managed dir (prd `broaden-agent-verb-surface`, R3:
+ * "validate it stays under a sane managed dir"). An override that escapes it
+ * (an absolute path elsewhere, or a `..` traversal out) is refused LOUDLY with
+ * this typed condition rather than silently writing a PNG to an arbitrary
+ * filesystem location — the seam returns a path, so an unbounded path would let
+ * the verb clobber any file the process can write.
+ *
+ * Mirrors the other typed conditions: the CLI maps {@link code} to a message,
+ * and {@link isControllerError} narrows it across a bundle boundary.
+ */
+export class ScreenshotPathError extends ControllerError {
+	readonly code = 'screenshot-path-outside-managed-dir';
+	/** The offending caller-supplied `out` path, echoed back so it is visible. */
+	readonly path: string;
+	/** The managed screenshots dir the path had to stay under. */
+	readonly managedDir: string;
+
+	constructor(
+		path: string,
+		managedDir: string,
+		message: string = `The screenshot output path ${JSON.stringify(
+			path,
+		)} is OUTSIDE the managed screenshots dir (${managedDir}). A caller may override --out only within the managed dir; webhands never writes a screenshot to an arbitrary location.`,
+		options?: {cause?: unknown},
+	) {
+		super(message, options);
+		this.path = path;
+		this.managedDir = managedDir;
+	}
+}
+
+/**
+ * A durable `query` `ref` (prd `broaden-agent-verb-surface`, R4; finding
+ * `query-ref-mint-mechanism-attribute-beats-weakmap`) failed to resolve to
+ * EXACTLY ONE element when an action verb (`click`/`type`) tried to act on it.
+ * A `ref` is a SHORT-LIVED handle, not a stable identity: between the `query`
+ * that minted it and the act, the page may have re-rendered (React keyed-list /
+ * Svelte `{#each}` NODE REPLACEMENT), navigated, or cloned a subtree carrying
+ * our minted attribute. Two stale shapes, BOTH this one error, never a silent
+ * wrong-element action:
+ *
+ * - resolve-to-ZERO ({@link matched} `=== 0`) — the element was removed or
+ *   replaced (its minted node is gone, or a reused stable attribute it carried
+ *   no longer exists). The agent must re-`query` against the fresh DOM.
+ * - resolve-to-MANY ({@link matched} `> 1`) — the ref matches more than one
+ *   element (a framework cloned a subtree carrying our minted attribute, or a
+ *   reused attribute turned out non-unique after a mutation). We refuse to
+ *   "pick the first", because that is exactly the silent wrong-element click the
+ *   ref exists to PREVENT.
+ *
+ * This is STRICTLY SAFER than re-addressing by a positional `.nth(i)`, which
+ * SILENTLY clicks whatever now sits at that index. The agent is told "re-query,
+ * the page changed" — its natural loop anyway. Mirrors the other typed
+ * conditions: the CLI maps {@link code} to a message, and
+ * {@link isControllerError} narrows it across a bundle boundary.
+ */
+export class StaleRefError extends ControllerError {
+	readonly code = 'stale-ref';
+	/** The ref locator string that went stale (echoed back so it is visible). */
+	readonly ref: string;
+	/** How many elements the ref resolved to (0 = removed/replaced, >1 = ambiguous). */
+	readonly matched: number;
+	/** Which verb tried to act on the stale ref (e.g. `click`, `type`). */
+	readonly verb: string;
+
+	constructor(
+		ref: string,
+		matched: number,
+		verb: string,
+		message: string = matched === 0
+			? `${verb}: the ref ${JSON.stringify(
+					ref,
+				)} is STALE — it now matches NO element (the page changed: the element was removed, replaced by a re-render, or the page navigated). Re-run query to get a fresh ref.`
+			: `${verb}: the ref ${JSON.stringify(
+					ref,
+				)} is AMBIGUOUS — it now matches ${matched} elements (the page changed: a subtree was cloned, or the attribute is no longer unique). Refusing to act on a guessed element; re-run query to get a fresh ref.`,
+		options?: {cause?: unknown},
+	) {
+		super(message, options);
+		this.ref = ref;
+		this.matched = matched;
+		this.verb = verb;
+	}
+}
+
 /**
  * Narrow an unknown caught value to a {@link ControllerError}. Prefer this over
  * `instanceof` at package boundaries: it checks the {@link ControllerError.isControllerError}