@orkestrel/browser 0.0.9 → 0.0.11

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

@@ -49,7 +49,7 @@ export declare const BROWSER_FRAME_WORLD_NAME = "__orkestrelBrowserFrame";
 /** Tool identity embedded in HAR 1.2 documents. */
 export declare const BROWSER_HAR_CREATOR: Readonly<{
     name: "@orkestrel/browser";
-    version: "0.0.8";
+    version: "0.0.11";
 }>;
 
 /** CDP Input modifier bit values keyed by canonical key name. */
@@ -739,14 +739,12 @@ export declare class BrowserFrame implements BrowserFrameInterface {
     evaluate(expression: string, timeout?: number): Promise<unknown>;
     handle(expression: string): Promise<BrowserHandleInterface>;
     wait(selector: string, options?: BrowserWaitOptions): Promise<void>;
-    send(method: string, params?: Readonly<Record<string, unknown>>): Promise<unknown>;
+    send(method: string, params?: Readonly<Record<string, unknown>>, timeout?: number): Promise<unknown>;
     subscribe(method: string, handler: CDPHandler): Promise<void>;
     unsubscribe(method: string, handler: CDPHandler): Promise<void>;
     save(path: string, _bytes: Uint8Array): Promise<void>;
-    protected assert(): void;
-    protected request(method: string, params?: Readonly<Record<string, unknown>>, timeout?: number): Promise<unknown>;
-    protected raw(expression: string, timeout?: number): Promise<unknown>;
-    protected update(url: string): void;
+    assert(): void;
+    update(url: string): void;
 }
 
 /**
@@ -781,7 +779,9 @@ export declare interface BrowserFrameInfo {
  * - `select` — choose option(s) in a `<select>` element
  * - `evaluate` — execute a JavaScript expression in the page context
  * - `wait` — wait for an element state
- * - `send` — issue a raw CDP method in the frame's current target session
+ * - `send` — issue a raw CDP method in the frame's current target session, with an optional per-call timeout
+ * - `assert` — throw when the frame can no longer accept protocol work
+ * - `update` — record an externally observed URL as the frame's current URL
  */
 export declare interface BrowserFrameInterface {
     readonly id: string;
@@ -801,10 +801,12 @@ export declare interface BrowserFrameInterface {
     evaluate(expression: string, timeout?: number): Promise<unknown>;
     handle(expression: string): Promise<BrowserHandleInterface>;
     wait(selector: string, options?: BrowserWaitOptions): Promise<void>;
-    send(method: string, params?: Readonly<Record<string, unknown>>): Promise<unknown>;
+    send(method: string, params?: Readonly<Record<string, unknown>>, timeout?: number): Promise<unknown>;
     subscribe(method: string, handler: CDPHandler): Promise<void>;
     unsubscribe(method: string, handler: CDPHandler): Promise<void>;
     save(path: string, bytes: Uint8Array): Promise<void>;
+    assert(): void;
+    update(url: string): void;
 }
 
 /** Function coverage inside one script. */
@@ -1002,7 +1004,7 @@ export declare interface BrowserHARValue {
  * @param headers - Header record
  * @returns Protocol header entries
  */
-export declare function browserHeadersToProtocol(headers: Readonly<Record<string, string>>): readonly Readonly<Record<string, string>>[];
+export declare function browserHeadersToProtocol(headers: Readonly<Record<string, string>>): ReadonlyArray<Readonly<Record<string, string>>>;
 
 /** Normalized CDP keyboard key data. */
 export declare interface BrowserKey {
@@ -1348,7 +1350,7 @@ export declare class BrowserPage extends BrowserFrame implements BrowserPageInte
     codegen(options?: BrowserCodegenOptions): Promise<BrowserCodegenInterface>;
     destroy(): Promise<void>;
     close(): Promise<void>;
-    protected assert(): void;
+    assert(): void;
 }
 
 /** One uncaught page exception. */
@@ -2784,7 +2786,7 @@ export declare function matchesBrowserURL(url: string, pattern: string): boolean
  * @param media - Public media configuration
  * @returns Protocol feature records
  */
-export declare function mediaToFeatures(media: BrowserMedia): readonly Readonly<Record<string, string>>[];
+export declare function mediaToFeatures(media: BrowserMedia): ReadonlyArray<Readonly<Record<string, string>>>;
 
 /**
  * Normalize a raw list of recorded codegen actions.

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

@@ -49,7 +49,7 @@ export declare const BROWSER_FRAME_WORLD_NAME = "__orkestrelBrowserFrame";
 /** Tool identity embedded in HAR 1.2 documents. */
 export declare const BROWSER_HAR_CREATOR: Readonly<{
     name: "@orkestrel/browser";
-    version: "0.0.8";
+    version: "0.0.11";
 }>;
 
 /** CDP Input modifier bit values keyed by canonical key name. */
@@ -739,14 +739,12 @@ export declare class BrowserFrame implements BrowserFrameInterface {
     evaluate(expression: string, timeout?: number): Promise<unknown>;
     handle(expression: string): Promise<BrowserHandleInterface>;
     wait(selector: string, options?: BrowserWaitOptions): Promise<void>;
-    send(method: string, params?: Readonly<Record<string, unknown>>): Promise<unknown>;
+    send(method: string, params?: Readonly<Record<string, unknown>>, timeout?: number): Promise<unknown>;
     subscribe(method: string, handler: CDPHandler): Promise<void>;
     unsubscribe(method: string, handler: CDPHandler): Promise<void>;
     save(path: string, _bytes: Uint8Array): Promise<void>;
-    protected assert(): void;
-    protected request(method: string, params?: Readonly<Record<string, unknown>>, timeout?: number): Promise<unknown>;
-    protected raw(expression: string, timeout?: number): Promise<unknown>;
-    protected update(url: string): void;
+    assert(): void;
+    update(url: string): void;
 }
 
 /**
@@ -781,7 +779,9 @@ export declare interface BrowserFrameInfo {
  * - `select` — choose option(s) in a `<select>` element
  * - `evaluate` — execute a JavaScript expression in the page context
  * - `wait` — wait for an element state
- * - `send` — issue a raw CDP method in the frame's current target session
+ * - `send` — issue a raw CDP method in the frame's current target session, with an optional per-call timeout
+ * - `assert` — throw when the frame can no longer accept protocol work
+ * - `update` — record an externally observed URL as the frame's current URL
  */
 export declare interface BrowserFrameInterface {
     readonly id: string;
@@ -801,10 +801,12 @@ export declare interface BrowserFrameInterface {
     evaluate(expression: string, timeout?: number): Promise<unknown>;
     handle(expression: string): Promise<BrowserHandleInterface>;
     wait(selector: string, options?: BrowserWaitOptions): Promise<void>;
-    send(method: string, params?: Readonly<Record<string, unknown>>): Promise<unknown>;
+    send(method: string, params?: Readonly<Record<string, unknown>>, timeout?: number): Promise<unknown>;
     subscribe(method: string, handler: CDPHandler): Promise<void>;
     unsubscribe(method: string, handler: CDPHandler): Promise<void>;
     save(path: string, bytes: Uint8Array): Promise<void>;
+    assert(): void;
+    update(url: string): void;
 }
 
 /** Function coverage inside one script. */
@@ -1002,7 +1004,7 @@ export declare interface BrowserHARValue {
  * @param headers - Header record
  * @returns Protocol header entries
  */
-export declare function browserHeadersToProtocol(headers: Readonly<Record<string, string>>): readonly Readonly<Record<string, string>>[];
+export declare function browserHeadersToProtocol(headers: Readonly<Record<string, string>>): ReadonlyArray<Readonly<Record<string, string>>>;
 
 /** Normalized CDP keyboard key data. */
 export declare interface BrowserKey {
@@ -1348,7 +1350,7 @@ export declare class BrowserPage extends BrowserFrame implements BrowserPageInte
     codegen(options?: BrowserCodegenOptions): Promise<BrowserCodegenInterface>;
     destroy(): Promise<void>;
     close(): Promise<void>;
-    protected assert(): void;
+    assert(): void;
 }
 
 /** One uncaught page exception. */
@@ -2784,7 +2786,7 @@ export declare function matchesBrowserURL(url: string, pattern: string): boolean
  * @param media - Public media configuration
  * @returns Protocol feature records
  */
-export declare function mediaToFeatures(media: BrowserMedia): readonly Readonly<Record<string, string>>[];
+export declare function mediaToFeatures(media: BrowserMedia): ReadonlyArray<Readonly<Record<string, string>>>;
 
 /**
  * Normalize a raw list of recorded codegen actions.

package/dist/src/core/index.js

@@ -5,7 +5,72 @@ import { createHTML, renderText } from "@orkestrel/html";
 /** Base64 alphabet, index-ordered, used to build {@link BASE64_LOOKUP}. */
 var BASE64_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
 /** Base64 character to 6-bit value lookup table, derived from {@link BASE64_CHARS}. */
-var BASE64_LOOKUP = Object.freeze(Object.fromEntries(BASE64_CHARS.split("").map((char, index) => [char, index])));
+var BASE64_LOOKUP = Object.freeze({
+	A: 0,
+	B: 1,
+	C: 2,
+	D: 3,
+	E: 4,
+	F: 5,
+	G: 6,
+	H: 7,
+	I: 8,
+	J: 9,
+	K: 10,
+	L: 11,
+	M: 12,
+	N: 13,
+	O: 14,
+	P: 15,
+	Q: 16,
+	R: 17,
+	S: 18,
+	T: 19,
+	U: 20,
+	V: 21,
+	W: 22,
+	X: 23,
+	Y: 24,
+	Z: 25,
+	a: 26,
+	b: 27,
+	c: 28,
+	d: 29,
+	e: 30,
+	f: 31,
+	g: 32,
+	h: 33,
+	i: 34,
+	j: 35,
+	k: 36,
+	l: 37,
+	m: 38,
+	n: 39,
+	o: 40,
+	p: 41,
+	q: 42,
+	r: 43,
+	s: 44,
+	t: 45,
+	u: 46,
+	v: 47,
+	w: 48,
+	x: 49,
+	y: 50,
+	z: 51,
+	"0": 52,
+	"1": 53,
+	"2": 54,
+	"3": 55,
+	"4": 56,
+	"5": 57,
+	"6": 58,
+	"7": 59,
+	"8": 60,
+	"9": 61,
+	"+": 62,
+	"/": 63
+});
 /** Default timeout in milliseconds for browser connection, requests, and navigation. */
 var BROWSER_DEFAULT_TIMEOUT_MS = 3e4;
 /**
@@ -75,7 +140,7 @@ var BROWSER_MOUSE_BUTTON_MASKS = Object.freeze({
 /** Tool identity embedded in HAR 1.2 documents. */
 var BROWSER_HAR_CREATOR = Object.freeze({
 	name: "@orkestrel/browser",
-	version: "0.0.8"
+	version: "0.0.11"
 });
 /** Attribute used to tag temporary screenshot styles and masks. */
 var BROWSER_SCREENSHOT_ATTRIBUTE = "data-orkestrel-screenshot";
@@ -4892,9 +4957,9 @@ var BrowserFrame = class {
 		this.assert();
 		await this.#selectors.css(selector).wait(options);
 	}
-	async send(method, params) {
+	async send(method, params, timeout) {
 		this.assert();
-		return await this.#client.send(method, params, await this.#sessionId());
+		return await this.#client.send(method, params, await this.#sessionId(), timeout);
 	}
 	async subscribe(method, handler) {
 		this.assert();
@@ -4909,12 +4974,6 @@ var BrowserFrame = class {
 	assert() {
 		if (!this.#client.connected) throw new BrowserError("Browser frame is disconnected", void 0, { frame: this.#id });
 	}
-	async request(method, params, timeout) {
-		return await this.#client.send(method, params, await this.#sessionId(), timeout);
-	}
-	async raw(expression, timeout) {
-		return await this.#evaluate(expression, timeout);
-	}
 	update(url) {
 		this.#url = url;
 	}
@@ -6133,7 +6192,7 @@ var BrowserPage = class BrowserPage extends BrowserFrame {
 		this.assert();
 		const params = { ...browserScreenshotToParams(options) };
 		if (options?.full === true) {
-			const metrics = await this.request("Page.getLayoutMetrics");
+			const metrics = await this.send("Page.getLayoutMetrics");
 			const size = isRecord(metrics) && isRecord(metrics["cssContentSize"]) ? metrics["cssContentSize"] : isRecord(metrics) && isRecord(metrics["contentSize"]) ? metrics["contentSize"] : void 0;
 			const width = size?.["width"];
 			const height = size?.["height"];
@@ -6151,7 +6210,7 @@ var BrowserPage = class BrowserPage extends BrowserFrame {
 			const ratio = options.scale === "css" ? 1 : await this.evaluate("devicePixelRatio");
 			if (!isFiniteNumber(ratio) || ratio <= 0) throw new BrowserError("Browser screenshot device scale is malformed");
 			if (!isRecord(params["clip"])) {
-				const metrics = await this.request("Page.getLayoutMetrics");
+				const metrics = await this.send("Page.getLayoutMetrics");
 				const viewport = isRecord(metrics) && isRecord(metrics["cssVisualViewport"]) ? metrics["cssVisualViewport"] : void 0;
 				if (viewport === void 0 || !isFiniteNumber(viewport["pageX"]) || !isFiniteNumber(viewport["pageY"]) || !isFiniteNumber(viewport["clientWidth"]) || viewport["clientWidth"] <= 0 || !isFiniteNumber(viewport["clientHeight"]) || viewport["clientHeight"] <= 0) throw new BrowserError("Browser screenshot viewport metrics are malformed");
 				params["clip"] = {
@@ -6173,7 +6232,7 @@ var BrowserPage = class BrowserPage extends BrowserFrame {
 				token = value;
 			}
 			if (options?.transparent === true) {
-				await this.request("Emulation.setDefaultBackgroundColorOverride", { color: {
+				await this.send("Emulation.setDefaultBackgroundColorOverride", { color: {
 					r: 0,
 					g: 0,
 					b: 0,
@@ -6181,7 +6240,7 @@ var BrowserPage = class BrowserPage extends BrowserFrame {
 				} });
 				transparent = true;
 			}
-			const result = await this.request("Page.captureScreenshot", params);
+			const result = await this.send("Page.captureScreenshot", params);
 			if (!isRecord(result) || !isString(result["data"])) throw new BrowserError("Screenshot failed: no data returned");
 			const bytes = decodeBase64(result["data"]);
 			if (options?.path !== void 0) await this.save(options.path, bytes);
@@ -6190,13 +6249,13 @@ var BrowserPage = class BrowserPage extends BrowserFrame {
 				path: options?.path
 			};
 		} finally {
-			if (transparent) await this.request("Emulation.setDefaultBackgroundColorOverride").catch(() => void 0);
+			if (transparent) await this.send("Emulation.setDefaultBackgroundColorOverride").catch(() => void 0);
 			if (token !== void 0) await this.evaluate(compileScreenshotCleanupExpression(token)).catch(() => void 0);
 		}
 	}
 	async pdf(options) {
 		this.assert();
-		const result = await this.request("Page.printToPDF", browserPDFToParams(options));
+		const result = await this.send("Page.printToPDF", browserPDFToParams(options));
 		if (!isRecord(result) || !isString(result["data"])) throw new BrowserError("PDF failed: no data returned");
 		const bytes = decodeBase64(result["data"]);
 		if (options?.path !== void 0) await this.save(options.path, bytes);
@@ -6214,12 +6273,12 @@ var BrowserPage = class BrowserPage extends BrowserFrame {
 	}
 	async frames() {
 		this.assert();
-		return readBrowserFrames(await this.request("Page.getFrameTree")).map((frame) => this.#frame(frame));
+		return readBrowserFrames(await this.send("Page.getFrameTree")).map((frame) => this.#frame(frame));
 	}
 	async snapshot(options) {
 		this.assert();
 		const styles = options?.styles ?? [];
-		return new BrowserSnapshot(decodeBrowserSnapshot(await this.request("DOMSnapshot.captureSnapshot", {
+		return new BrowserSnapshot(decodeBrowserSnapshot(await this.send("DOMSnapshot.captureSnapshot", {
 			computedStyles: [...styles],
 			includePaintOrder: options?.paint ?? false,
 			includeDOMRects: options?.rects ?? false
@@ -6272,7 +6331,7 @@ var BrowserPage = class BrowserPage extends BrowserFrame {
 		wait.catch(() => void 0);
 		let loader;
 		try {
-			const result = await this.request("Page.navigate", { url }, timeout);
+			const result = await this.send("Page.navigate", { url }, timeout);
 			if (isRecord(result) && isString(result["errorText"])) throw new BrowserError(`Navigation failed: ${result["errorText"]}`);
 			if (isRecord(result) && isString(result["loaderId"])) loader = result["loaderId"];
 			await wait;
@@ -6291,7 +6350,7 @@ var BrowserPage = class BrowserPage extends BrowserFrame {
 		const wait = this.#waitForLoadEvent(options?.condition ?? "load", timeout);
 		wait.catch(() => void 0);
 		try {
-			await this.request("Page.reload", void 0, timeout);
+			await this.send("Page.reload", void 0, timeout);
 			await wait;
 		} catch (error) {
 			this.#clearNavigationWatch(watch);
@@ -6316,7 +6375,7 @@ var BrowserPage = class BrowserPage extends BrowserFrame {
 	async #navigateHistory(offset, options) {
 		const timeout = options?.timeout ?? 3e4;
 		validateBrowserTimeout(timeout);
-		const history = await this.request("Page.getNavigationHistory");
+		const history = await this.send("Page.getNavigationHistory");
 		if (!isRecord(history) || !isInteger(history["currentIndex"]) || !isArray(history["entries"])) throw new BrowserError("Navigation history is malformed");
 		const entry = history["entries"][history["currentIndex"] + offset];
 		if (!isRecord(entry) || !isInteger(entry["id"])) return {
@@ -6328,7 +6387,7 @@ var BrowserPage = class BrowserPage extends BrowserFrame {
 		const wait = this.#waitForLoadEvent(options?.condition ?? "load", timeout);
 		wait.catch(() => void 0);
 		try {
-			await this.request("Page.navigateToHistoryEntry", { entryId: entry["id"] }, timeout);
+			await this.send("Page.navigateToHistoryEntry", { entryId: entry["id"] }, timeout);
 			await wait;
 		} catch (error) {
 			this.#clearNavigationWatch(watch);
@@ -6358,7 +6417,7 @@ var BrowserPage = class BrowserPage extends BrowserFrame {
 	}
 	async #completeNavigation(watch, loader) {
 		try {
-			const resolved = requireBrowserString(await this.raw("location.href"), "Navigation URL");
+			const resolved = requireBrowserString(await this.evaluate("location.href"), "Navigation URL");
 			this.update(resolved);
 			return this.#navigationResult(watch, resolved, loader);
 		} catch (error) {
@@ -6492,7 +6551,7 @@ var BrowserPage = class BrowserPage extends BrowserFrame {
 	}
 	async #stopLoading(timeout) {
 		try {
-			await this.request("Page.stopLoading", void 0, timeout);
+			await this.send("Page.stopLoading", void 0, timeout);
 		} catch {}
 	}
 	#handleNavigationResponse(response) {