@orkestrel/browser 0.0.23 → 0.0.24

package/dist/bin/main.js

@@ -1,16 +1,17 @@
 #!/usr/bin/env node
 import { parseBoolean, parseInteger } from "@orkestrel/contract";
 import { BrowserError, isBrowserError } from "../src/core/index.js";
-import { createBrowserMCPServer } from "../src/server/index.js";
+import { createBrowserMCPServer, parseBrowserViewport } from "../src/server/index.js";
 //#region src/bin/main.ts
 process.stderr.on("error", () => {
 	process.exitCode = 1;
 });
 try {
-	const { BROWSE_ROOT, BROWSE_HEADLESS, BROWSE_EXECUTABLE, BROWSE_READONLY, BROWSE_POOL } = process.env;
+	const { BROWSE_ROOT, BROWSE_HEADLESS, BROWSE_EXECUTABLE, BROWSE_READONLY, BROWSE_POOL, BROWSE_VIEWPORT } = process.env;
 	const headless = parseBoolean(BROWSE_HEADLESS);
 	const readonly = parseBoolean(BROWSE_READONLY);
 	const size = parseInteger(BROWSE_POOL);
+	const viewport = parseBrowserViewport(BROWSE_VIEWPORT);
 	for (const [name, value, parsed] of [[
 		"BROWSE_HEADLESS",
 		BROWSE_HEADLESS,
@@ -27,12 +28,17 @@ try {
 		name: "BROWSE_POOL",
 		value: BROWSE_POOL
 	});
+	if (BROWSE_VIEWPORT !== void 0 && BROWSE_VIEWPORT !== "" && viewport === void 0) throw new BrowserError(`BROWSE_VIEWPORT must be positive integers in WIDTHxHEIGHT form, not ${JSON.stringify(BROWSE_VIEWPORT)}`, "BROWSER_SERVER_ENVIRONMENT", {
+		name: "BROWSE_VIEWPORT",
+		value: BROWSE_VIEWPORT
+	});
 	await createBrowserMCPServer({
 		...BROWSE_ROOT === void 0 || BROWSE_ROOT === "" ? {} : { root: BROWSE_ROOT },
 		...headless === void 0 ? {} : { headless },
 		...BROWSE_EXECUTABLE === void 0 || BROWSE_EXECUTABLE === "" ? {} : { executable: BROWSE_EXECUTABLE },
 		...readonly === void 0 ? {} : { readonly },
-		...size === void 0 ? {} : { pool: { size } }
+		...size === void 0 ? {} : { pool: { size } },
+		...viewport === void 0 ? {} : { viewport }
 	}).start();
 } catch (error) {
 	if (!isBrowserError(error)) throw error;

package/dist/bin/main.js.map

@@ -1 +1 @@
-{"version":3,"file":"main.js","names":[],"sources":["../../src/bin/main.ts"],"sourcesContent":["import { parseBoolean, parseInteger } from '@orkestrel/contract'\nimport { BrowserError, isBrowserError } from '@src/core'\nimport { createBrowserMCPServer } from '@src/server'\n\n// The entry owns stderr; a closed reader must not interrupt the server's teardown barrier.\nprocess.stderr.on('error', () => {\n\tprocess.exitCode = 1\n})\n\ntry {\n\tconst { BROWSE_ROOT, BROWSE_HEADLESS, BROWSE_EXECUTABLE, BROWSE_READONLY, BROWSE_POOL } =\n\t\tprocess.env\n\tconst headless = parseBoolean(BROWSE_HEADLESS)\n\tconst readonly = parseBoolean(BROWSE_READONLY)\n\tconst size = parseInteger(BROWSE_POOL)\n\t// An empty variable counts as unset, as a shell's `NAME=` leaves it.\n\tfor (const [name, value, parsed] of [\n\t\t['BROWSE_HEADLESS', BROWSE_HEADLESS, headless],\n\t\t['BROWSE_READONLY', BROWSE_READONLY, readonly],\n\t] as const) {\n\t\tif (value !== undefined && value !== '' && parsed === undefined) {\n\t\t\tthrow new BrowserError(\n\t\t\t\t`${name} must be true, false, 1, or 0, not ${JSON.stringify(value)}`,\n\t\t\t\t'BROWSER_SERVER_ENVIRONMENT',\n\t\t\t\t{ name, value },\n\t\t\t)\n\t\t}\n\t}\n\tif (BROWSE_POOL !== undefined && BROWSE_POOL !== '' && size === undefined)\n\t\tthrow new BrowserError(\n\t\t\t`BROWSE_POOL must be an integer, not ${JSON.stringify(BROWSE_POOL)}`,\n\t\t\t'BROWSER_SERVER_ENVIRONMENT',\n\t\t\t{ name: 'BROWSE_POOL', value: BROWSE_POOL },\n\t\t)\n\tawait createBrowserMCPServer({\n\t\t...(BROWSE_ROOT === undefined || BROWSE_ROOT === '' ? {} : { root: BROWSE_ROOT }),\n\t\t...(headless === undefined ? {} : { headless }),\n\t\t...(BROWSE_EXECUTABLE === undefined || BROWSE_EXECUTABLE === ''\n\t\t\t? {}\n\t\t\t: { executable: BROWSE_EXECUTABLE }),\n\t\t...(readonly === undefined ? {} : { readonly }),\n\t\t...(size === undefined ? {} : { pool: { size } }),\n\t}).start()\n} catch (error) {\n\tif (!isBrowserError(error)) throw error\n\tconsole.error(`browse: ${error.code}: ${error.message.split(/\\r\\n|\\n/u).join(' ')}`)\n\tprocess.exitCode = 1\n}\n"],"mappings":";;;;;AAKA,QAAQ,OAAO,GAAG,eAAe;CAChC,QAAQ,WAAW;AACpB,CAAC;AAED,IAAI;CACH,MAAM,EAAE,aAAa,iBAAiB,mBAAmB,iBAAiB,gBACzE,QAAQ;CACT,MAAM,WAAW,aAAa,eAAe;CAC7C,MAAM,WAAW,aAAa,eAAe;CAC7C,MAAM,OAAO,aAAa,WAAW;CAErC,KAAK,MAAM,CAAC,MAAM,OAAO,WAAW,CACnC;EAAC;EAAmB;EAAiB;CAAQ,GAC7C;EAAC;EAAmB;EAAiB;CAAQ,CAC9C,GACC,IAAI,UAAU,KAAA,KAAa,UAAU,MAAM,WAAW,KAAA,GACrD,MAAM,IAAI,aACT,GAAG,KAAK,qCAAqC,KAAK,UAAU,KAAK,KACjE,8BACA;EAAE;EAAM;CAAM,CACf;CAGF,IAAI,gBAAgB,KAAA,KAAa,gBAAgB,MAAM,SAAS,KAAA,GAC/D,MAAM,IAAI,aACT,uCAAuC,KAAK,UAAU,WAAW,KACjE,8BACA;EAAE,MAAM;EAAe,OAAO;CAAY,CAC3C;CACD,MAAM,uBAAuB;EAC5B,GAAI,gBAAgB,KAAA,KAAa,gBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,YAAY;EAC/E,GAAI,aAAa,KAAA,IAAY,CAAC,IAAI,EAAE,SAAS;EAC7C,GAAI,sBAAsB,KAAA,KAAa,sBAAsB,KAC1D,CAAC,IACD,EAAE,YAAY,kBAAkB;EACnC,GAAI,aAAa,KAAA,IAAY,CAAC,IAAI,EAAE,SAAS;EAC7C,GAAI,SAAS,KAAA,IAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE;CAChD,CAAC,CAAC,CAAC,MAAM;AACV,SAAS,OAAO;CACf,IAAI,CAAC,eAAe,KAAK,GAAG,MAAM;CAClC,QAAQ,MAAM,WAAW,MAAM,KAAK,IAAI,MAAM,QAAQ,MAAM,UAAU,CAAC,CAAC,KAAK,GAAG,GAAG;CACnF,QAAQ,WAAW;AACpB"}
+{"version":3,"file":"main.js","names":[],"sources":["../../src/bin/main.ts"],"sourcesContent":["import { parseBoolean, parseInteger } from '@orkestrel/contract'\nimport { BrowserError, isBrowserError } from '@src/core'\nimport { createBrowserMCPServer, parseBrowserViewport } from '@src/server'\n\n// The entry owns stderr; a closed reader must not interrupt the server's teardown barrier.\nprocess.stderr.on('error', () => {\n\tprocess.exitCode = 1\n})\n\ntry {\n\tconst {\n\t\tBROWSE_ROOT,\n\t\tBROWSE_HEADLESS,\n\t\tBROWSE_EXECUTABLE,\n\t\tBROWSE_READONLY,\n\t\tBROWSE_POOL,\n\t\tBROWSE_VIEWPORT,\n\t} = process.env\n\tconst headless = parseBoolean(BROWSE_HEADLESS)\n\tconst readonly = parseBoolean(BROWSE_READONLY)\n\tconst size = parseInteger(BROWSE_POOL)\n\tconst viewport = parseBrowserViewport(BROWSE_VIEWPORT)\n\t// An empty variable counts as unset, as a shell's `NAME=` leaves it.\n\tfor (const [name, value, parsed] of [\n\t\t['BROWSE_HEADLESS', BROWSE_HEADLESS, headless],\n\t\t['BROWSE_READONLY', BROWSE_READONLY, readonly],\n\t] as const) {\n\t\tif (value !== undefined && value !== '' && parsed === undefined) {\n\t\t\tthrow new BrowserError(\n\t\t\t\t`${name} must be true, false, 1, or 0, not ${JSON.stringify(value)}`,\n\t\t\t\t'BROWSER_SERVER_ENVIRONMENT',\n\t\t\t\t{ name, value },\n\t\t\t)\n\t\t}\n\t}\n\tif (BROWSE_POOL !== undefined && BROWSE_POOL !== '' && size === undefined)\n\t\tthrow new BrowserError(\n\t\t\t`BROWSE_POOL must be an integer, not ${JSON.stringify(BROWSE_POOL)}`,\n\t\t\t'BROWSER_SERVER_ENVIRONMENT',\n\t\t\t{ name: 'BROWSE_POOL', value: BROWSE_POOL },\n\t\t)\n\tif (BROWSE_VIEWPORT !== undefined && BROWSE_VIEWPORT !== '' && viewport === undefined)\n\t\tthrow new BrowserError(\n\t\t\t`BROWSE_VIEWPORT must be positive integers in WIDTHxHEIGHT form, not ${JSON.stringify(BROWSE_VIEWPORT)}`,\n\t\t\t'BROWSER_SERVER_ENVIRONMENT',\n\t\t\t{ name: 'BROWSE_VIEWPORT', value: BROWSE_VIEWPORT },\n\t\t)\n\tawait createBrowserMCPServer({\n\t\t...(BROWSE_ROOT === undefined || BROWSE_ROOT === '' ? {} : { root: BROWSE_ROOT }),\n\t\t...(headless === undefined ? {} : { headless }),\n\t\t...(BROWSE_EXECUTABLE === undefined || BROWSE_EXECUTABLE === ''\n\t\t\t? {}\n\t\t\t: { executable: BROWSE_EXECUTABLE }),\n\t\t...(readonly === undefined ? {} : { readonly }),\n\t\t...(size === undefined ? {} : { pool: { size } }),\n\t\t...(viewport === undefined ? {} : { viewport }),\n\t}).start()\n} catch (error) {\n\tif (!isBrowserError(error)) throw error\n\tconsole.error(`browse: ${error.code}: ${error.message.split(/\\r\\n|\\n/u).join(' ')}`)\n\tprocess.exitCode = 1\n}\n"],"mappings":";;;;;AAKA,QAAQ,OAAO,GAAG,eAAe;CAChC,QAAQ,WAAW;AACpB,CAAC;AAED,IAAI;CACH,MAAM,EACL,aACA,iBACA,mBACA,iBACA,aACA,oBACG,QAAQ;CACZ,MAAM,WAAW,aAAa,eAAe;CAC7C,MAAM,WAAW,aAAa,eAAe;CAC7C,MAAM,OAAO,aAAa,WAAW;CACrC,MAAM,WAAW,qBAAqB,eAAe;CAErD,KAAK,MAAM,CAAC,MAAM,OAAO,WAAW,CACnC;EAAC;EAAmB;EAAiB;CAAQ,GAC7C;EAAC;EAAmB;EAAiB;CAAQ,CAC9C,GACC,IAAI,UAAU,KAAA,KAAa,UAAU,MAAM,WAAW,KAAA,GACrD,MAAM,IAAI,aACT,GAAG,KAAK,qCAAqC,KAAK,UAAU,KAAK,KACjE,8BACA;EAAE;EAAM;CAAM,CACf;CAGF,IAAI,gBAAgB,KAAA,KAAa,gBAAgB,MAAM,SAAS,KAAA,GAC/D,MAAM,IAAI,aACT,uCAAuC,KAAK,UAAU,WAAW,KACjE,8BACA;EAAE,MAAM;EAAe,OAAO;CAAY,CAC3C;CACD,IAAI,oBAAoB,KAAA,KAAa,oBAAoB,MAAM,aAAa,KAAA,GAC3E,MAAM,IAAI,aACT,uEAAuE,KAAK,UAAU,eAAe,KACrG,8BACA;EAAE,MAAM;EAAmB,OAAO;CAAgB,CACnD;CACD,MAAM,uBAAuB;EAC5B,GAAI,gBAAgB,KAAA,KAAa,gBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,YAAY;EAC/E,GAAI,aAAa,KAAA,IAAY,CAAC,IAAI,EAAE,SAAS;EAC7C,GAAI,sBAAsB,KAAA,KAAa,sBAAsB,KAC1D,CAAC,IACD,EAAE,YAAY,kBAAkB;EACnC,GAAI,aAAa,KAAA,IAAY,CAAC,IAAI,EAAE,SAAS;EAC7C,GAAI,SAAS,KAAA,IAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE;EAC/C,GAAI,aAAa,KAAA,IAAY,CAAC,IAAI,EAAE,SAAS;CAC9C,CAAC,CAAC,CAAC,MAAM;AACV,SAAS,OAAO;CACf,IAAI,CAAC,eAAe,KAAK,GAAG,MAAM;CAClC,QAAQ,MAAM,WAAW,MAAM,KAAK,IAAI,MAAM,QAAQ,MAAM,UAAU,CAAC,CAAC,KAAK,GAAG,GAAG;CACnF,QAAQ,WAAW;AACpB"}

package/dist/src/core/index.cjs

@@ -163,7 +163,7 @@ var BROWSER_MOUSE_BUTTON_MASKS = Object.freeze({
 */
 var BROWSER_HAR_CREATOR = Object.freeze({
 	name: "@orkestrel/browser",
-	version: "0.0.23"
+	version: "0.0.24"
 });
 /** Names the attribute that tags temporary screenshot styles and masks. */
 var BROWSER_SCREENSHOT_ATTRIBUTE = "data-orkestrel-screenshot";
@@ -742,7 +742,7 @@ var BROWSER_TOOL_COPY = Object.freeze({
 					description: "The journey name, such as add-kettle."
 				}),
 				edits: Object.freeze({
-					description: "The changes, as an array or a JSON string of the array, applied in order; one invalid change refuses them all.",
+					description: "The changes, as an array or its JSON string, applied in order; one invalid change refuses them all.",
 					anyOf: Object.freeze([Object.freeze({
 						type: "array",
 						items: Object.freeze({
@@ -818,6 +818,18 @@ var BROWSER_TOOL_COPY = Object.freeze({
 			required: Object.freeze(["journey"])
 		})
 	}),
+	capture: Object.freeze({
+		name: "capture",
+		description: "Saves the current view as a PNG in the runs directory and returns its path.",
+		parameters: Object.freeze({
+			type: "object",
+			properties: Object.freeze({ full: Object.freeze({
+				type: "boolean",
+				description: "True captures the full page; false captures the viewport."
+			}) }),
+			required: Object.freeze(["full"])
+		})
+	}),
 	forget: Object.freeze({
 		name: "forget",
 		description: "Removes a saved journey and all its runs; the name is free to record again.",
@@ -886,7 +898,7 @@ var BROWSER_ACTION_STAGES = Object.freeze([
 var BROWSER_JOURNEY_EMPTY_LISTING = "No journeys are saved; call record to start one.";
 /**
 * Names the journey tools a toolset constructed with `journeys` registers and reserves: `record`,
-* `save`, `journeys`, `edit`, `replay`, and `forget`.
+* `save`, `journeys`, `edit`, `replay`, `forget`, and `capture`.
 */
 var BROWSER_JOURNEY_TOOL_NAMES = Object.freeze([
 	"record",
@@ -894,7 +906,8 @@ var BROWSER_JOURNEY_TOOL_NAMES = Object.freeze([
 	"journeys",
 	"edit",
 	"replay",
-	"forget"
+	"forget",
+	"capture"
 ]);
 /** Names observation and journey tools that cannot become journey steps. */
 var BROWSER_JOURNEY_NON_STEP_TOOLS = Object.freeze([...BROWSER_OBSERVATION_TOOL_NAMES, ...BROWSER_JOURNEY_TOOL_NAMES]);
@@ -6451,9 +6464,11 @@ var BrowserPageElement = class {
 				object: result["object"]["objectId"],
 				context
 			};
-		} catch {
+		} catch (error) {
 			options?.signal?.throwIfAborted();
-			throw new BrowserElementError(this.reference, "GONE");
+			if (isCDPTimeoutError(error) || isCDPConnectionError(error)) throw error;
+			if (isCDPError(error) && /Could not find node|No node with given id|No node found for given backend id/i.test(error.message)) throw new BrowserElementError(this.reference, "GONE");
+			throw error;
 		}
 	}
 	async #call(declaration, options, target) {
@@ -6482,7 +6497,7 @@ var BrowserPageElement = class {
 	}
 	#failure(options, error) {
 		options?.signal?.throwIfAborted();
-		if (isBrowserElementError(error)) throw error;
+		if (isBrowserElementError(error) || isCDPTimeoutError(error) || isCDPConnectionError(error)) throw error;
 		const message = ((0, _orkestrel_contract.isError)(error) ? error.message : String(error)).split("\n", 1)[0] ?? "";
 		const known = BROWSER_ELEMENT_REFUSALS.get(message.replace(/^Error: /, ""));
 		if (known !== void 0) throw new BrowserElementError(this.reference, known.reason, known.detail);
@@ -6514,11 +6529,20 @@ var BrowserPageElement = class {
 			session: this.#input.node.session,
 			...options
 		}).catch(this.#failure.bind(this, options));
-		await this.#call(compileActionabilityFunction({
+		await this.#call(`async function() {
+		await (${compileActionabilityFunction({
 			visible: true,
 			enabled: true,
 			stable: true
-		}), options);
+		})}).call(this)
+		let previous
+		for (;;) {
+			await new Promise((resolve) => requestAnimationFrame(resolve))
+			const current = [window.scrollX, window.scrollY]
+			if (previous && current.every((value, index) => value === previous[index])) return true
+			previous = current
+		}
+	}`, options);
 		const geometry = await this.#geometry(options);
 		const point = geometry.page.center;
 		const local = geometry.local.center;
@@ -6529,6 +6553,10 @@ var BrowserPageElement = class {
 		}, {
 			session: this.#input.node.session,
 			...options
+		}).catch((error) => {
+			options?.signal?.throwIfAborted();
+			if (isCDPError(error) && error.context?.["message"] === "No node found at given location") throw new BrowserElementError(this.reference, "OCCLUDED", "hit-test location held no node");
+			throw error;
 		});
 		if (!(0, _orkestrel_contract.isRecord)(hit) || !(0, _orkestrel_contract.isInteger)(hit["backendNodeId"]) || hit["frameId"] !== void 0 && hit["frameId"] !== this.#input.frame) throw new BrowserElementError(this.reference, "OCCLUDED");
 		if (hit["backendNodeId"] !== this.#input.backend && await this.#call(compileHitFunction(), options, hit["backendNodeId"]) !== true) {
@@ -12278,13 +12306,13 @@ function createMemoryBrowserRunStore() {
 //#endregion
 //#region src/core/BrowserJourneyToolset.ts
 /**
-* Registers the journey tools `record`, `save`, `journeys`, `edit`, `replay`, and `forget` over a toolset
+* Registers the journey tools `record`, `save`, `journeys`, `edit`, `replay`, `forget`, and `capture` over a toolset
 * and owns the recording and the active replay.
 *
 * @remarks
 * The journey toolset composes the toolset's public members: `perform` reads the view a receipt
 * carries through `look`, `hold` and `emitter` drive the recorder and the replay, `view` converts
-* an edit's `ref` to a target, and `tools` receives the six tools at construction, which refuses
+* an edit's `ref` to a target, and `tools` receives the journey tools at construction, which refuses
 * with `BROWSER_TOOLSET_RESERVED` when the manager already holds one of the names. Every refusal
 * is a sentence that names the next call, and a reason inside it is a clause without a directive
 * or a final period.
@@ -12300,7 +12328,7 @@ function createMemoryBrowserRunStore() {
 * by the view after the run.
 *
 * `destroy()` aborts the active replay and waits for it to finish, stops a recording without
-* saving it, and removes the six tools the manager still holds under the instances it added.
+* saving it, and removes the journey tools the manager still holds under the instances it added.
 *
 * @example
 * ```ts
@@ -12341,7 +12369,8 @@ var BrowserJourneyToolset = class {
 			this.#create("journeys", this.#journeys.bind(this)),
 			this.#create("edit", this.#edit.bind(this)),
 			this.#create("replay", this.#replayJourney.bind(this)),
-			this.#create("forget", this.#forget.bind(this))
+			this.#create("forget", this.#forget.bind(this)),
+			this.#create("capture", this.#capture.bind(this))
 		]);
 		toolset.tools.add(this.#tools);
 	}
@@ -12368,6 +12397,22 @@ var BrowserJourneyToolset = class {
 		signal.throwIfAborted();
 		return handler(args, signal);
 	}
+	async #capture(args, signal) {
+		const full = args["full"];
+		if (!(0, _orkestrel_contract.isBoolean)(full)) throw new BrowserError("The full parameter must be true or false.", "BROWSER_TOOLSET_ARGUMENT");
+		this.#idleReplay();
+		const view = this.#toolset.view;
+		if (!view.trusted) throw new BrowserError("This view is untrusted; capture requires a trusted browser view.", "BROWSER_CAPTURE_UNTRUSTED");
+		if (view.screenshot === void 0) throw new BrowserError("This view cannot capture an image.", "BROWSER_CAPTURE_UNAVAILABLE");
+		const runs = this.#runs;
+		if (runs?.snapshot === void 0) throw new BrowserError("Capture requires a runs store with standalone file storage.", "BROWSER_CAPTURE_UNAVAILABLE");
+		const screenshot = await view.screenshot({
+			format: "png",
+			full
+		});
+		signal.throwIfAborted();
+		return runs.snapshot(screenshot.bytes, { signal });
+	}
 	async #record(args, signal) {
 		if (this.#readonly) throw new BrowserError(BROWSER_JOURNEY_READONLY_REFUSAL, "BROWSER_JOURNEY_READONLY");
 		this.#idleReplay();