@orkestrel/browser 0.0.22 → 0.0.24

package/dist/src/core/index.d.cts

@@ -107,7 +107,7 @@ export declare const BROWSER_FRAME_WORLD_NAME = "__orkestrelBrowserFrame";
  */
 export declare const BROWSER_HAR_CREATOR: Readonly<{
     name: "@orkestrel/browser";
-    version: "0.0.22";
+    version: "0.0.24";
 }>;
 
 /** Names accessibility roles that receive actionable outline references. */
@@ -159,7 +159,7 @@ export declare const BROWSER_JOURNEY_STEP_KEYS: readonly string[];
 
 /**
  * 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`.
  */
 export declare const BROWSER_JOURNEY_TOOL_NAMES: readonly BrowserToolName[];
 
@@ -786,6 +786,8 @@ export declare interface BrowserContextInterface {
  * - `emulation` — emulation overrides inherited by every page of the context
  */
 export declare interface BrowserContextOptions {
+    /** Names each element reference the context's pages issue. Default: a counter the context owns. */
+    readonly reference?: BrowserReferenceFunction;
     readonly on?: EmitterHooks<BrowserContextEventMap>;
     readonly error?: EmitterErrorHandler;
     readonly proxy?: BrowserProxy;
@@ -1799,7 +1801,7 @@ export declare type BrowserJourneyEditRequest = BrowserJourneyEdit | {
  *
  * @remarks
  * - `store` — keeps the journeys the tools record, list, edit, and replay
- * - `runs` — keeps each replay's run; omitting it writes no run
+ * - `runs` — keeps each replay's run and saves standalone images when it provides `snapshot`
  * - `limit` — positive integer listing cap in characters; Default: the owner's `limit`, including direct construction
  * - `readonly` — if `true`, refuses `record`, `save`, `edit`, and `forget` before any store access, and
  *   `replay` still writes runs; if `false` or omitted, every tool runs
@@ -1928,13 +1930,13 @@ export declare interface BrowserJourneyTarget {
 }
 
 /**
- * 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.
@@ -1950,7 +1952,7 @@ export declare interface BrowserJourneyTarget {
  * 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
@@ -1970,7 +1972,7 @@ export declare class BrowserJourneyToolset implements BrowserJourneyToolsetInter
 }
 
 /**
- * Registers the six journey tools over a toolset and owns the recording and the active replay.
+ * Registers the journey tools over a toolset and owns the recording and the active replay.
  *
  * @remarks
  * - `recording` — the name of the journey being recorded, or `undefined` when none is
@@ -1979,7 +1981,7 @@ export declare class BrowserJourneyToolset implements BrowserJourneyToolsetInter
 export declare interface BrowserJourneyToolsetInterface {
     readonly recording: string | undefined;
     readonly replaying: string | undefined;
-    /** Aborts the active replay and removes the six journey tools from the manager. */
+    /** Aborts the active replay and removes the journey tools from the manager. */
     destroy(): Promise<void>;
 }
 
@@ -3481,6 +3483,14 @@ export declare interface BrowserRunStep {
 
 /** Keeps runs by the journey name and run id the run carries. */
 export declare interface BrowserRunStoreInterface {
+    /**
+     * Saves a standalone PNG under the runs root without replacing an existing file.
+     * @param bytes - PNG bytes to persist
+     * @param options - Cancellation options
+     * @returns Absolute path of the saved image
+     * @remarks Stores without standalone file storage omit this capability.
+     */
+    snapshot?(bytes: Uint8Array, options?: BrowserStoreOptions): Promise<string>;
     /** Mints a run id for the journey and creates its run directory exclusively. */
     open(name: string, options?: BrowserStoreOptions): Promise<BrowserRunSlot>;
     /** Returns the run stored under the journey name and id, or `undefined` when none is stored. */
@@ -3965,9 +3975,9 @@ export declare interface BrowserRunStoreInterface {
     /**
      * Names a tool the browser toolset reserves: the generic tools, the staged `dialog`, the
      * opt-in `tabs` and `switch`, and the journey tools `record`, `save`, `journeys`, `edit`,
-     * `replay`, and `forget`, which a toolset constructed with `journeys` reserves.
+     * `replay`, `forget`, and `capture`, which a toolset constructed with `journeys` reserves.
      */
-    export declare type BrowserToolName = 'look' | 'read' | 'plain' | 'click' | 'type' | 'press' | 'navigate' | 'wait' | 'dialog' | 'tabs' | 'switch' | 'record' | 'save' | 'journeys' | 'edit' | 'replay' | 'forget';
+    export declare type BrowserToolName = 'look' | 'read' | 'plain' | 'click' | 'type' | 'press' | 'navigate' | 'wait' | 'dialog' | 'tabs' | 'switch' | 'record' | 'save' | 'journeys' | 'edit' | 'replay' | 'forget' | 'capture';
 
     /** Identifies a removed WebMCP tool by document and name. */
     export declare interface BrowserToolRemoval {

package/dist/src/core/index.d.ts

@@ -107,7 +107,7 @@ export declare const BROWSER_FRAME_WORLD_NAME = "__orkestrelBrowserFrame";
  */
 export declare const BROWSER_HAR_CREATOR: Readonly<{
     name: "@orkestrel/browser";
-    version: "0.0.22";
+    version: "0.0.24";
 }>;
 
 /** Names accessibility roles that receive actionable outline references. */
@@ -159,7 +159,7 @@ export declare const BROWSER_JOURNEY_STEP_KEYS: readonly string[];
 
 /**
  * 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`.
  */
 export declare const BROWSER_JOURNEY_TOOL_NAMES: readonly BrowserToolName[];
 
@@ -786,6 +786,8 @@ export declare interface BrowserContextInterface {
  * - `emulation` — emulation overrides inherited by every page of the context
  */
 export declare interface BrowserContextOptions {
+    /** Names each element reference the context's pages issue. Default: a counter the context owns. */
+    readonly reference?: BrowserReferenceFunction;
     readonly on?: EmitterHooks<BrowserContextEventMap>;
     readonly error?: EmitterErrorHandler;
     readonly proxy?: BrowserProxy;
@@ -1799,7 +1801,7 @@ export declare type BrowserJourneyEditRequest = BrowserJourneyEdit | {
  *
  * @remarks
  * - `store` — keeps the journeys the tools record, list, edit, and replay
- * - `runs` — keeps each replay's run; omitting it writes no run
+ * - `runs` — keeps each replay's run and saves standalone images when it provides `snapshot`
  * - `limit` — positive integer listing cap in characters; Default: the owner's `limit`, including direct construction
  * - `readonly` — if `true`, refuses `record`, `save`, `edit`, and `forget` before any store access, and
  *   `replay` still writes runs; if `false` or omitted, every tool runs
@@ -1928,13 +1930,13 @@ export declare interface BrowserJourneyTarget {
 }
 
 /**
- * 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.
@@ -1950,7 +1952,7 @@ export declare interface BrowserJourneyTarget {
  * 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
@@ -1970,7 +1972,7 @@ export declare class BrowserJourneyToolset implements BrowserJourneyToolsetInter
 }
 
 /**
- * Registers the six journey tools over a toolset and owns the recording and the active replay.
+ * Registers the journey tools over a toolset and owns the recording and the active replay.
  *
  * @remarks
  * - `recording` — the name of the journey being recorded, or `undefined` when none is
@@ -1979,7 +1981,7 @@ export declare class BrowserJourneyToolset implements BrowserJourneyToolsetInter
 export declare interface BrowserJourneyToolsetInterface {
     readonly recording: string | undefined;
     readonly replaying: string | undefined;
-    /** Aborts the active replay and removes the six journey tools from the manager. */
+    /** Aborts the active replay and removes the journey tools from the manager. */
     destroy(): Promise<void>;
 }
 
@@ -3481,6 +3483,14 @@ export declare interface BrowserRunStep {
 
 /** Keeps runs by the journey name and run id the run carries. */
 export declare interface BrowserRunStoreInterface {
+    /**
+     * Saves a standalone PNG under the runs root without replacing an existing file.
+     * @param bytes - PNG bytes to persist
+     * @param options - Cancellation options
+     * @returns Absolute path of the saved image
+     * @remarks Stores without standalone file storage omit this capability.
+     */
+    snapshot?(bytes: Uint8Array, options?: BrowserStoreOptions): Promise<string>;
     /** Mints a run id for the journey and creates its run directory exclusively. */
     open(name: string, options?: BrowserStoreOptions): Promise<BrowserRunSlot>;
     /** Returns the run stored under the journey name and id, or `undefined` when none is stored. */
@@ -3965,9 +3975,9 @@ export declare interface BrowserRunStoreInterface {
     /**
      * Names a tool the browser toolset reserves: the generic tools, the staged `dialog`, the
      * opt-in `tabs` and `switch`, and the journey tools `record`, `save`, `journeys`, `edit`,
-     * `replay`, and `forget`, which a toolset constructed with `journeys` reserves.
+     * `replay`, `forget`, and `capture`, which a toolset constructed with `journeys` reserves.
      */
-    export declare type BrowserToolName = 'look' | 'read' | 'plain' | 'click' | 'type' | 'press' | 'navigate' | 'wait' | 'dialog' | 'tabs' | 'switch' | 'record' | 'save' | 'journeys' | 'edit' | 'replay' | 'forget';
+    export declare type BrowserToolName = 'look' | 'read' | 'plain' | 'click' | 'type' | 'press' | 'navigate' | 'wait' | 'dialog' | 'tabs' | 'switch' | 'record' | 'save' | 'journeys' | 'edit' | 'replay' | 'forget' | 'capture';
 
     /** Identifies a removed WebMCP tool by document and name. */
     export declare interface BrowserToolRemoval {

package/dist/src/core/index.js

@@ -162,7 +162,7 @@ var BROWSER_MOUSE_BUTTON_MASKS = Object.freeze({
 */
 var BROWSER_HAR_CREATOR = Object.freeze({
 	name: "@orkestrel/browser",
-	version: "0.0.22"
+	version: "0.0.24"
 });
 /** Names the attribute that tags temporary screenshot styles and masks. */
 var BROWSER_SCREENSHOT_ATTRIBUTE = "data-orkestrel-screenshot";
@@ -741,7 +741,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({
@@ -817,6 +817,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.",
@@ -885,7 +897,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",
@@ -893,7 +905,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]);
@@ -6450,9 +6463,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) {
@@ -6481,7 +6496,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 = (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);
@@ -6513,11 +6528,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;
@@ -6528,6 +6552,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 (!isRecord(hit) || !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) {
@@ -11183,6 +11211,7 @@ var BrowserContext = class {
 	#viewport;
 	#writer;
 	#downloads;
+	#allocator;
 	#emitter;
 	#cookies;
 	#permissions;
@@ -11202,6 +11231,7 @@ var BrowserContext = class {
 		this.#viewport = viewport;
 		this.#writer = writer;
 		this.#downloads = downloads;
+		this.#allocator = options?.reference;
 		this.#emitter = new Emitter({
 			...options?.on !== void 0 ? { on: options.on } : {},
 			...options?.error !== void 0 ? { error: options.error } : {}
@@ -11338,7 +11368,7 @@ var BrowserContext = class {
 			sessionId = await this.#openSession(targetId);
 			await this.#enableSession(sessionId);
 			const frameId = await this.#mainFrame(sessionId);
-			page = new BrowserPage(this.#client, targetId, sessionId, this.#writer, url, frameId, this.#id, void 0, options, this.#nextReference.bind(this), ready);
+			page = new BrowserPage(this.#client, targetId, sessionId, this.#writer, url, frameId, this.#id, void 0, options, this.#allocator ?? this.#nextReference.bind(this), ready);
 			this.#observe(page);
 			await this.#configurePage(page);
 			await this.#emulation.attach(page);
@@ -11357,7 +11387,7 @@ var BrowserContext = class {
 			sessionId = await this.#openSession(targetId);
 			await this.#enableSession(sessionId);
 			const frameId = await this.#mainFrame(sessionId);
-			page = new BrowserPage(this.#client, targetId, sessionId, this.#writer, url, frameId, this.#id, void 0, void 0, this.#nextReference.bind(this), ready);
+			page = new BrowserPage(this.#client, targetId, sessionId, this.#writer, url, frameId, this.#id, void 0, void 0, this.#allocator ?? this.#nextReference.bind(this), ready);
 			this.#observe(page);
 			await this.#configurePage(page);
 			await this.#emulation.attach(page);
@@ -12275,13 +12305,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.
@@ -12297,7 +12327,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
@@ -12338,7 +12368,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);
 	}
@@ -12365,6 +12396,22 @@ var BrowserJourneyToolset = class {
 		signal.throwIfAborted();
 		return handler(args, signal);
 	}
+	async #capture(args, signal) {
+		const full = args["full"];
+		if (!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();