@orkestrel/browser 0.0.1

package/dist/src/core/index.cjs

@@ -0,0 +1,1209 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _orkestrel_contract = require("@orkestrel/contract");
+let _orkestrel_emitter = require("@orkestrel/emitter");
+//#region src/core/constants.ts
+/** 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])));
+/** Default timeout in milliseconds for browser connection, requests, and navigation. */
+var BROWSER_DEFAULT_TIMEOUT_MS = 3e4;
+/**
+* Maximum serialized-character length for an `evaluate()`/`content()` result,
+* enforced IN-PAGE before the result is returned to CDP.
+*
+* @remarks
+* This counts UTF-16 STRING LENGTH (`String#length`), not transport BYTES —
+* the actual CDP frame is UTF-8 encoded (up to 3 bytes/char for common
+* multibyte content) and carries additional JSON/CDP framing overhead on top
+* of the raw content. A `Runtime.evaluate` result above this size, once
+* framed as a CDP JSON response, overflows the native WebSocket inbound frame
+* limit and closes the whole CDP connection — a page-level failure with no
+* clean error. The limit is set well under the observed ~3-4MB transport
+* ceiling (rather than at it) to leave headroom for the length-vs-bytes gap
+* and framing overhead. The cap is enforced by stringifying the candidate
+* result in-page and throwing a recognizable sentinel error (see
+* {@link BROWSER_RESULT_LIMIT_SENTINEL_PREFIX}) before the oversized frame is
+* ever produced, so the caller gets a coded error instead of a dropped
+* connection.
+*/
+var BROWSER_RESULT_LIMIT = 25e5;
+/**
+* Distinctive prefix for the in-page result-limit sentinel error, immediately
+* followed by the serialized length.
+*
+* @remarks
+* Deliberately unlikely to appear in a page's own thrown error text (unlike
+* a plain `BROWSER_RESULT_LIMIT: ` label), so {@link BROWSER_RESULT_LIMIT_PATTERN}
+* can distinguish the guard's own throw from a page error that merely
+* mentions similar text.
+*/
+var BROWSER_RESULT_LIMIT_SENTINEL_PREFIX = "[[ORKESTREL_BROWSER_RESULT_LIMIT]]";
+/**
+* Matches the in-page result-limit sentinel error message, anchored
+* immediately after the `Error: ` (optionally `Uncaught Error: `) prefix that
+* Chromium prepends to a thrown error's description — so the guard's own
+* throw is recognized only at the message START, not wherever the substring
+* happens to occur.
+*/
+var BROWSER_RESULT_LIMIT_PATTERN = new RegExp(`(?:Uncaught )?Error: \\[\\[ORKESTREL_BROWSER_RESULT_LIMIT\\]\\](\\d+)`);
+/** Poll interval in milliseconds while waiting for a selector to appear. */
+var BROWSER_WAIT_POLL_INTERVAL_MS = 100;
+/**
+* Bound (in milliseconds) on the best-effort `Page.stopLoading` call issued
+* after a failed `navigate()`.
+*
+* @remarks
+* A wedged renderer can make the underlying CDP call hang for the full
+* per-call timeout; capping it to a small fixed bound keeps a navigate
+* failure's total latency close to the original timeout instead of doubling
+* it. Best-effort only — never masks the original navigate error.
+*/
+var BROWSER_STOP_LOADING_TIMEOUT_MS = 1e3;
+/** Default viewport width in pixels. */
+var BROWSER_DEFAULT_VIEWPORT_WIDTH = 1280;
+/** Default viewport height in pixels. */
+var BROWSER_DEFAULT_VIEWPORT_HEIGHT = 720;
+/** Name of the CDP runtime binding the codegen recorder script calls into. */
+var BROWSER_CODEGEN_BINDING_NAME = "__orkestrelBrowserCodegen";
+/**
+* In-page recorder script injected via `Page.addScriptToEvaluateOnNewDocument`
+* and `Runtime.evaluate`.
+*
+* @remarks
+* Attaches capturing-phase listeners for `click`, `input` (fill), and
+* `change` (select) on `document`, builds a stable CSS selector for the
+* target element, and forwards each action to the CDP binding
+* ({@link BROWSER_CODEGEN_BINDING_NAME}) as a JSON string payload. Guarded to
+* install exactly once per document (`window[name]` sentinel) so repeated
+* injection on every new document is idempotent.
+*/
+var BROWSER_CODEGEN_SOURCE = `(() => {
+	const bindingName = ${JSON.stringify(BROWSER_CODEGEN_BINDING_NAME)}
+	if (window[bindingName + '__installed']) return
+	window[bindingName + '__installed'] = true
+
+	const selectorFor = (el) => {
+		if (el.id) return '#' + CSS.escape(el.id)
+		const parts = []
+		let node = el
+		while (node && node.nodeType === 1 && parts.length < 8) {
+			let part = node.tagName.toLowerCase()
+			if (node.classList && node.classList.length > 0) {
+				part += '.' + Array.from(node.classList).map((cls) => CSS.escape(cls)).join('.')
+			}
+			const parent = node.parentElement
+			if (parent) {
+				const siblings = Array.from(parent.children).filter((c) => c.tagName === node.tagName)
+				if (siblings.length > 1) {
+					part += ':nth-of-type(' + (siblings.indexOf(node) + 1) + ')'
+				}
+			}
+			parts.unshift(part)
+			node = parent
+		}
+		return parts.join(' > ')
+	}
+
+	const send = (payload) => {
+		if (typeof window[bindingName] === 'function') {
+			window[bindingName](JSON.stringify(payload))
+		}
+	}
+
+	document.addEventListener(
+		'click',
+		(event) => {
+			const target = event.target
+			if (!target || target.nodeType !== 1) return
+			send({ action: 'click', selector: selectorFor(target) })
+		},
+		true,
+	)
+
+	const fillableTypes = new Set([
+		'text',
+		'search',
+		'url',
+		'tel',
+		'email',
+		'password',
+		'number',
+	])
+
+	document.addEventListener(
+		'input',
+		(event) => {
+			const target = event.target
+			if (!target || target.nodeType !== 1) return
+
+			if (target.isContentEditable) {
+				send({ action: 'fill', selector: selectorFor(target), value: target.textContent || '' })
+				return
+			}
+
+			if (typeof target.value !== 'string') return
+			const tag = target.tagName
+			if (tag === 'TEXTAREA') {
+				send({ action: 'fill', selector: selectorFor(target), value: target.value })
+				return
+			}
+			if (tag === 'INPUT' && fillableTypes.has((target.type || 'text').toLowerCase())) {
+				send({ action: 'fill', selector: selectorFor(target), value: target.value })
+			}
+		},
+		true,
+	)
+
+	document.addEventListener(
+		'change',
+		(event) => {
+			const target = event.target
+			if (!target || target.tagName !== 'SELECT') return
+			const values = Array.from(target.selectedOptions || []).map((option) => option.value)
+			send({ action: 'select', selector: selectorFor(target), values })
+		},
+		true,
+	)
+})()`;
+//#endregion
+//#region src/core/errors.ts
+/**
+* Base error for all browser automation operations.
+*
+* @remarks
+* Carries a machine-readable `code` and optional `context` (AGENTS §12) so
+* callers can branch in a `catch` without parsing message strings.
+*/
+var BrowserError = class extends Error {
+	code;
+	context;
+	constructor(message, code = "BROWSER_ERROR", context) {
+		super(message);
+		this.name = "BrowserError";
+		this.code = code;
+		this.context = context;
+	}
+};
+/**
+* A selector-based lookup or wait timed out without the element appearing.
+*/
+var BrowserSelectorError = class extends BrowserError {
+	constructor(message, context) {
+		super(message, "BROWSER_SELECTOR_ERROR", context);
+		this.name = "BrowserSelectorError";
+	}
+};
+/**
+* A CDP request received an error response from the remote endpoint.
+*
+* @remarks
+* Carries the originating `method` plus the CDP error's own `code`,
+* `message`, and `data` (when present) in `context`, so callers can branch
+* on the protocol-level error instead of parsing the message string.
+*/
+var CDPError = class extends BrowserError {
+	constructor(message, context) {
+		super(message, "BROWSER_CDP_ERROR", context);
+		this.name = "CDPError";
+	}
+};
+/**
+* A CDP request could not be sent or completed because the client was not in
+* a connectable state (not connected, closed while connecting, or the
+* connection dropped mid-request).
+*/
+var CDPConnectionError = class extends BrowserError {
+	constructor(message, context) {
+		super(message, "BROWSER_CDP_CONNECTION_ERROR", context);
+		this.name = "CDPConnectionError";
+	}
+};
+/**
+* A pending CDP request was not answered within its timeout window.
+*/
+var CDPTimeoutError = class extends BrowserError {
+	constructor(message, context) {
+		super(message, "BROWSER_CDP_TIMEOUT_ERROR", context);
+		this.name = "CDPTimeoutError";
+	}
+};
+/**
+* An `evaluate()`/`content()` result exceeded {@link BROWSER_RESULT_LIMIT}
+* and was rejected in-page before it could overflow the CDP transport frame.
+*/
+var BrowserResultLimitError = class extends BrowserError {
+	constructor(message, context) {
+		super(message, "BROWSER_RESULT_LIMIT_ERROR", context);
+		this.name = "BrowserResultLimitError";
+	}
+};
+/**
+* Narrow an unknown value to BrowserError.
+*
+* @param value - Value to check
+* @returns True when value is a BrowserError instance
+*/
+function isBrowserError(value) {
+	return value instanceof BrowserError;
+}
+/**
+* Narrow an unknown value to BrowserSelectorError.
+*
+* @param value - Value to check
+* @returns True when value is a BrowserSelectorError instance
+*/
+function isBrowserSelectorError(value) {
+	return value instanceof BrowserSelectorError;
+}
+/**
+* Narrow an unknown value to CDPError.
+*
+* @param value - Value to check
+* @returns True when value is a CDPError instance
+*/
+function isCDPError(value) {
+	return value instanceof CDPError;
+}
+/**
+* Narrow an unknown value to CDPConnectionError.
+*
+* @param value - Value to check
+* @returns True when value is a CDPConnectionError instance
+*/
+function isCDPConnectionError(value) {
+	return value instanceof CDPConnectionError;
+}
+/**
+* Narrow an unknown value to CDPTimeoutError.
+*
+* @param value - Value to check
+* @returns True when value is a CDPTimeoutError instance
+*/
+function isCDPTimeoutError(value) {
+	return value instanceof CDPTimeoutError;
+}
+/**
+* Narrow an unknown value to BrowserResultLimitError.
+*
+* @param value - Value to check
+* @returns True when value is a BrowserResultLimitError instance
+*/
+function isBrowserResultLimitError(value) {
+	return value instanceof BrowserResultLimitError;
+}
+//#endregion
+//#region src/core/helpers.ts
+/**
+* Decode a base64-encoded string into raw bytes.
+*
+* @remarks
+* Pure JS implementation — no `Buffer`, no `atob` (DOM-only) — so it runs
+* identically in Node and browser environments. Whitespace and `=` padding
+* are ignored; invalid characters are skipped.
+*
+* @param text - Base64-encoded input string
+* @returns Decoded bytes
+*
+* @example
+* ```ts
+* decodeBase64('aGVsbG8=') // Uint8Array [104, 101, 108, 108, 111]
+* ```
+*/
+function decodeBase64(text) {
+	const clean = text.replace(/[^A-Za-z0-9+/]/g, "");
+	const bytes = [];
+	let buffer = 0;
+	let bits = 0;
+	for (const char of clean) {
+		const value = BASE64_LOOKUP[char];
+		if (value === void 0) continue;
+		buffer = buffer << 6 | value;
+		bits += 6;
+		if (bits >= 8) {
+			bits -= 8;
+			bytes.push(buffer >> bits & 255);
+		}
+	}
+	return new Uint8Array(bytes);
+}
+/**
+* Wrap a `Runtime.evaluate` expression so the IN-PAGE code stringifies its
+* own result and throws a recognizable error before an oversized result
+* would overflow the CDP transport frame.
+*
+* @remarks
+* A result whose `JSON.stringify` length exceeds `limit` throws
+* `Error('BROWSER_RESULT_LIMIT: <length>')` inside the page instead of being
+* returned — the caller maps that sentinel to a coded
+* {@link BrowserResultLimitError}. A non-serializable result (`undefined`,
+* a function, a symbol) makes `JSON.stringify` return `undefined`, so the
+* length check is skipped and today's undefined-passthrough behavior is
+* unchanged.
+*
+* The expression is placed on its own line inside the wrapper (rather than
+* inline with the guard code) so a trailing `//` line comment in the
+* expression cannot swallow the closing guard syntax that follows it.
+*
+* @param expression - The candidate JavaScript expression to evaluate
+* @param limit - Maximum serialized-character length (see {@link BROWSER_RESULT_LIMIT})
+* @returns The wrapped, guarded expression
+*/
+function guardEvaluateExpression(expression, limit) {
+	return `(() => { const r = (
+${expression}
+); const s = JSON.stringify(r); if (typeof s === 'string' && s.length > ${limit}) throw new Error(${JSON.stringify(BROWSER_RESULT_LIMIT_SENTINEL_PREFIX)} + s.length); return r })()`;
+}
+/**
+* Normalize a raw list of recorded codegen actions.
+*
+* @remarks
+* Collapses consecutive `fill` actions on the same selector into the latest
+* value (a text input fires one `input` event per keystroke) so the
+* compiled script reflects the final typed value rather than every
+* intermediate keystroke.
+*
+* @param actions - Raw recorded actions, in capture order
+* @returns Normalized actions, in the same order
+*/
+function normalizeCodegenActions(actions) {
+	const result = [];
+	for (const action of actions) {
+		const previous = result[result.length - 1];
+		if (previous !== void 0 && previous.action === "fill" && action.action === "fill" && previous.selector === action.selector) {
+			result[result.length - 1] = action;
+			continue;
+		}
+		result.push(action);
+	}
+	return result;
+}
+/**
+* Parse a codegen binding payload into a typed action.
+*
+* @remarks
+* The in-page recorder script calls the CDP binding with a JSON string
+* payload shaped like a {@link BrowserCodegenAction}. Returns `undefined`
+* when the payload is not valid JSON or does not match a known action shape.
+*
+* @param payload - Raw binding call payload (the CDP `payload` param)
+* @returns The parsed action, or `undefined` when the payload is malformed
+*/
+function parseCodegenActionPayload(payload) {
+	if (!(0, _orkestrel_contract.isString)(payload)) return void 0;
+	let parsed;
+	try {
+		parsed = JSON.parse(payload);
+	} catch {
+		return;
+	}
+	if (!(0, _orkestrel_contract.isRecord)(parsed)) return void 0;
+	const action = parsed["action"];
+	const selector = parsed["selector"];
+	if (action === "click" && (0, _orkestrel_contract.isString)(selector)) return {
+		action: "click",
+		selector
+	};
+	if (action === "fill" && (0, _orkestrel_contract.isString)(selector) && (0, _orkestrel_contract.isString)(parsed["value"])) return {
+		action: "fill",
+		selector,
+		value: parsed["value"]
+	};
+	if (action === "select" && (0, _orkestrel_contract.isString)(selector) && Array.isArray(parsed["values"])) {
+		const values = parsed["values"].filter(_orkestrel_contract.isString);
+		if (values.length === parsed["values"].length) return {
+			action: "select",
+			selector,
+			values
+		};
+	}
+}
+/**
+* Derive a `navigate` codegen action from a `Page.frameNavigated` CDP event.
+*
+* @remarks
+* Only the top-level (main) frame's navigation is recorded — a frame
+* carrying a `parentId` is a sub-frame and is ignored.
+*
+* @param params - The CDP `Page.frameNavigated` event params
+* @returns A `navigate` action, or `undefined` when the event is not a
+*   top-level navigation with a resolvable URL
+*/
+function readCodegenNavigateAction(params) {
+	const frame = params["frame"];
+	if (!(0, _orkestrel_contract.isRecord)(frame)) return void 0;
+	if ("parentId" in frame) return void 0;
+	if (!(0, _orkestrel_contract.isString)(frame["url"])) return void 0;
+	return {
+		action: "navigate",
+		url: frame["url"]
+	};
+}
+/**
+* Compile recorded codegen actions into a replayable script.
+*
+* @remarks
+* Emits one statement per action against a `page` object shaped like
+* {@link BrowserPageInterface} (`page.navigate(...)`, `page.click(...)`, …).
+* Both target languages emit an `async function run(page)` body whose
+* statements are `await`-ed; `language` only toggles whether the `page`
+* parameter carries a TypeScript type annotation (default `'javascript'`).
+*
+* @param actions - Normalized actions to compile
+* @param options - Compilation options (target language)
+* @returns The compiled script source
+*/
+function compileCodegenScript(actions, options) {
+	const language = options?.language ?? "javascript";
+	const lines = actions.map((action) => {
+		switch (action.action) {
+			case "navigate": return `await page.navigate(${JSON.stringify(action.url)})`;
+			case "click": return `await page.click(${JSON.stringify(action.selector)})`;
+			case "fill": return `await page.fill(${JSON.stringify(action.selector)}, ${JSON.stringify(action.value)})`;
+			case "select": return `await page.select(${JSON.stringify(action.selector)}, ${JSON.stringify(action.values)})`;
+		}
+	});
+	if (language === "typescript") return [
+		`async function run(page: import('@orkestrel/browser').BrowserPageInterface): Promise<void> {`,
+		...lines.map((line) => `\t${line}`),
+		`}`
+	].join("\n");
+	return [
+		`async function run(page) {`,
+		...lines.map((line) => `\t${line}`),
+		`}`
+	].join("\n");
+}
+//#endregion
+//#region src/core/CDPClient.ts
+/**
+* Lightweight Chrome DevTools Protocol client over a {@link CDPTransportInterface}.
+*
+* @remarks
+* Sends JSON-RPC messages over the injected transport and dispatches
+* responses and events. The transport owns the connection itself
+* (WebSocket, pipe, or any other duplex channel); this class owns only
+* the JSON-RPC framing and id/session correlation.
+*
+* Supports session-scoped event subscriptions: when a sessionId is
+* provided to subscribe/unsubscribe, the handler only fires for CDP
+* events carrying that sessionId. Global subscriptions (no sessionId)
+* continue to see ALL events for backwards compatibility.
+*/
+var CDPClient = class {
+	#transport;
+	#messageId = 0;
+	#pending = /* @__PURE__ */ new Map();
+	#subscriptions = /* @__PURE__ */ new Map();
+	#sessionSubscriptions = /* @__PURE__ */ new Map();
+	#connected = false;
+	#wired = false;
+	#timeout;
+	#connecting;
+	#closeRequested = false;
+	constructor(options) {
+		this.#transport = options.transport;
+		this.#timeout = options.timeout ?? 3e4;
+	}
+	get connected() {
+		return this.#connected;
+	}
+	async connect() {
+		if (this.#connected) return;
+		if (this.#connecting !== void 0) return this.#connecting;
+		this.#closeRequested = false;
+		const attempt = (async () => {
+			if (!this.#wired) {
+				this.#transport.emitter.on("message", (data) => this.#onMessage(data));
+				this.#transport.emitter.on("close", () => this.#onClose());
+				this.#transport.emitter.on("error", (error) => this.#onError(error));
+				this.#wired = true;
+			}
+			await this.#transport.start();
+			if (this.#closeRequested) {
+				this.#closeRequested = false;
+				await this.#transport.close();
+				throw new CDPConnectionError("CDP client was closed while connecting", { method: "connect" });
+			}
+			this.#connected = true;
+		})();
+		this.#connecting = attempt;
+		try {
+			await attempt;
+		} finally {
+			this.#connecting = void 0;
+		}
+	}
+	/**
+	* Close the transport and re-establish a fresh connection.
+	*
+	* @remarks
+	* Client-level subscriptions (`subscribe`/`unsubscribe` registrations)
+	* survive `close()` and remain active after the reconnect — only pending
+	* in-flight requests are rejected. This lets a caller reconnect a dropped
+	* transport without re-registering every handler.
+	*/
+	async reconnect() {
+		await this.close();
+		await this.connect();
+	}
+	async send(method, params, sessionId, timeout) {
+		if (!this.#connected) throw new CDPConnectionError("CDP client is not connected", { method });
+		const id = this.#nextId();
+		const message = {
+			id,
+			method
+		};
+		if (params !== void 0) message["params"] = params;
+		if (sessionId !== void 0) message["sessionId"] = sessionId;
+		const serialized = JSON.stringify(message);
+		const effectiveTimeout = timeout ?? this.#timeout;
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				this.#pending.delete(id);
+				reject(new CDPTimeoutError(`CDP request timed out: ${method}`, {
+					method,
+					timeout: effectiveTimeout
+				}));
+			}, effectiveTimeout);
+			this.#pending.set(id, {
+				method,
+				resolve,
+				reject,
+				timer
+			});
+			this.#transport.send(serialized).catch((thrown) => {
+				this.#pending.delete(id);
+				clearTimeout(timer);
+				reject(thrown);
+			});
+		});
+	}
+	subscribe(method, handler, sessionId) {
+		if (sessionId !== void 0) {
+			let sessionMap = this.#sessionSubscriptions.get(sessionId);
+			if (sessionMap === void 0) {
+				sessionMap = /* @__PURE__ */ new Map();
+				this.#sessionSubscriptions.set(sessionId, sessionMap);
+			}
+			let handlers = sessionMap.get(method);
+			if (handlers === void 0) {
+				handlers = /* @__PURE__ */ new Set();
+				sessionMap.set(method, handlers);
+			}
+			handlers.add(handler);
+		} else {
+			let handlers = this.#subscriptions.get(method);
+			if (handlers === void 0) {
+				handlers = /* @__PURE__ */ new Set();
+				this.#subscriptions.set(method, handlers);
+			}
+			handlers.add(handler);
+		}
+	}
+	unsubscribe(method, handler, sessionId) {
+		if (sessionId !== void 0) {
+			const sessionMap = this.#sessionSubscriptions.get(sessionId);
+			if (sessionMap !== void 0) {
+				const handlers = sessionMap.get(method);
+				if (handlers !== void 0) {
+					handlers.delete(handler);
+					if (handlers.size === 0) sessionMap.delete(method);
+				}
+				if (sessionMap.size === 0) this.#sessionSubscriptions.delete(sessionId);
+			}
+		} else {
+			const handlers = this.#subscriptions.get(method);
+			if (handlers !== void 0) {
+				handlers.delete(handler);
+				if (handlers.size === 0) this.#subscriptions.delete(method);
+			}
+		}
+	}
+	/**
+	* Close the transport and reject all pending requests.
+	*
+	* @remarks
+	* Subscriptions registered via `subscribe()` are client-level
+	* registrations, not connection-level state — they survive `close()`
+	* (and a subsequent `reconnect()`/`connect()`) and keep firing once the
+	* transport is active again. Only pending requests are rejected here.
+	* If `close()` is called while `connect()` is still awaiting
+	* `transport.start()`, the in-flight connect is rejected and the
+	* transport is closed deterministically once `start()` resolves.
+	*/
+	async close() {
+		if (this.#connecting !== void 0) {
+			this.#closeRequested = true;
+			await this.#connecting.catch(() => void 0);
+		}
+		if (!this.#connected) return;
+		this.#connected = false;
+		for (const [id, entry] of this.#pending) {
+			clearTimeout(entry.timer);
+			entry.reject(new CDPConnectionError("CDP connection closed", { method: entry.method }));
+			this.#pending.delete(id);
+		}
+		await this.#transport.close();
+	}
+	#nextId() {
+		this.#messageId += 1;
+		return this.#messageId;
+	}
+	#onClose() {
+		this.#connected = false;
+		for (const [id, entry] of this.#pending) {
+			clearTimeout(entry.timer);
+			entry.reject(new CDPConnectionError("CDP connection closed", { method: entry.method }));
+			this.#pending.delete(id);
+		}
+	}
+	#onError(error) {
+		if (!this.#connected) for (const [id, entry] of this.#pending) {
+			clearTimeout(entry.timer);
+			entry.reject(new CDPConnectionError(`CDP connection failed: ${String(error)}`, {
+				method: entry.method,
+				error
+			}));
+			this.#pending.delete(id);
+		}
+	}
+	#onMessage(data) {
+		let parsed;
+		try {
+			parsed = JSON.parse(data);
+		} catch {
+			return;
+		}
+		if (!(0, _orkestrel_contract.isRecord)(parsed)) return;
+		if (typeof parsed["id"] === "number") {
+			const id = parsed["id"];
+			const entry = this.#pending.get(id);
+			if (entry !== void 0) {
+				this.#pending.delete(id);
+				clearTimeout(entry.timer);
+				const errorValue = parsed["error"];
+				if ((0, _orkestrel_contract.isRecord)(errorValue)) {
+					const message = (0, _orkestrel_contract.isString)(errorValue["message"]) ? errorValue["message"] : "CDP error";
+					const context = { method: entry.method };
+					if ("code" in errorValue) context["code"] = errorValue["code"];
+					context["message"] = message;
+					if ("data" in errorValue) context["data"] = errorValue["data"];
+					entry.reject(new CDPError(message, context));
+				} else entry.resolve("result" in parsed ? parsed["result"] : void 0);
+			}
+			return;
+		}
+		if ((0, _orkestrel_contract.isString)(parsed["method"])) {
+			const method = parsed["method"];
+			const rawParams = parsed["params"];
+			const params = (0, _orkestrel_contract.isRecord)(rawParams) ? rawParams : Object.freeze({});
+			const globalHandlers = this.#subscriptions.get(method);
+			if (globalHandlers !== void 0) for (const handler of [...globalHandlers]) handler(params);
+			const eventSessionId = parsed["sessionId"];
+			if ((0, _orkestrel_contract.isString)(eventSessionId)) {
+				const sessionMap = this.#sessionSubscriptions.get(eventSessionId);
+				if (sessionMap !== void 0) {
+					const sessionHandlers = sessionMap.get(method);
+					if (sessionHandlers !== void 0) for (const handler of [...sessionHandlers]) handler(params);
+				}
+			}
+		}
+	}
+};
+//#endregion
+//#region src/core/BrowserCodegen.ts
+var BrowserCodegen = class {
+	#client;
+	#sessionId;
+	#actions = [];
+	#started = false;
+	#destroyed = false;
+	#emitter;
+	constructor(client, sessionId, options) {
+		this.#client = client;
+		this.#sessionId = sessionId;
+		this.#emitter = new _orkestrel_emitter.Emitter({ on: options?.on });
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get started() {
+		return this.#started;
+	}
+	async start() {
+		if (this.#destroyed) return;
+		if (this.#started) return;
+		this.#started = true;
+		this.#client.subscribe("Runtime.bindingCalled", this.#onBindingCalled, this.#sessionId);
+		this.#client.subscribe("Page.frameNavigated", this.#onFrameNavigated, this.#sessionId);
+		try {
+			await this.#client.send("Runtime.enable", void 0, this.#sessionId);
+			await this.#client.send("Runtime.addBinding", { name: BROWSER_CODEGEN_BINDING_NAME }, this.#sessionId);
+			await this.#client.send("Page.addScriptToEvaluateOnNewDocument", { source: BROWSER_CODEGEN_SOURCE }, this.#sessionId);
+			await this.#client.send("Runtime.evaluate", {
+				expression: BROWSER_CODEGEN_SOURCE,
+				awaitPromise: true
+			}, this.#sessionId);
+		} catch (error) {
+			this.#client.unsubscribe("Runtime.bindingCalled", this.#onBindingCalled, this.#sessionId);
+			this.#client.unsubscribe("Page.frameNavigated", this.#onFrameNavigated, this.#sessionId);
+			this.#started = false;
+			throw error;
+		}
+		this.#emitter.emit("start");
+	}
+	async stop() {
+		if (!this.#started) return this.actions();
+		this.#client.unsubscribe("Runtime.bindingCalled", this.#onBindingCalled, this.#sessionId);
+		this.#client.unsubscribe("Page.frameNavigated", this.#onFrameNavigated, this.#sessionId);
+		this.#started = false;
+		const snapshot = this.actions();
+		this.#emitter.emit("stop", snapshot);
+		return snapshot;
+	}
+	actions() {
+		return normalizeCodegenActions(this.#actions);
+	}
+	script(options) {
+		return compileCodegenScript(this.actions(), options);
+	}
+	clear() {
+		this.#actions = [];
+		this.#emitter.emit("clear");
+	}
+	async destroy() {
+		if (this.#destroyed) return;
+		this.#destroyed = true;
+		try {
+			await this.stop();
+		} catch {}
+		this.#actions = [];
+		this.#emitter.destroy();
+	}
+	#onBindingCalled = (params) => {
+		if (params["name"] !== "__orkestrelBrowserCodegen") return;
+		const action = parseCodegenActionPayload(params["payload"]);
+		if (action === void 0) return;
+		this.#actions.push(action);
+		this.#emitter.emit("action", action);
+	};
+	#onFrameNavigated = (params) => {
+		const action = readCodegenNavigateAction(params);
+		if (action === void 0) return;
+		this.#actions.push(action);
+		this.#emitter.emit("action", action);
+	};
+};
+//#endregion
+//#region src/core/BrowserPage.ts
+var BrowserPage = class {
+	#client;
+	#targetId;
+	#sessionId;
+	#writer;
+	#url = "about:blank";
+	#closed = false;
+	#codegen;
+	#destroyHandler;
+	constructor(client, targetId, sessionId, writer, url) {
+		this.#client = client;
+		this.#targetId = targetId;
+		this.#sessionId = sessionId;
+		this.#writer = writer;
+		if (url !== void 0) this.#url = url;
+		this.#destroyHandler = (params) => {
+			if ((0, _orkestrel_contract.isString)(params["targetId"]) && params["targetId"] === this.#targetId) this.#closed = true;
+		};
+		this.#client.subscribe("Target.targetDestroyed", this.#destroyHandler);
+	}
+	get url() {
+		return this.#url;
+	}
+	get closed() {
+		return this.#closed;
+	}
+	async title() {
+		const result = await this.#evaluate("document.title");
+		return typeof result === "string" ? result : "";
+	}
+	async navigate(url, options) {
+		const timeout = options?.timeout ?? 3e4;
+		const condition = options?.condition ?? "load";
+		const wait = this.#waitForLoadEvent(condition, timeout);
+		const waitOutcome = wait.promise.then(() => ({ ok: true }), (error) => ({
+			ok: false,
+			error
+		}));
+		try {
+			const result = await this.#client.send("Page.navigate", { url }, this.#sessionId, timeout);
+			if ((0, _orkestrel_contract.isRecord)(result) && (0, _orkestrel_contract.isString)(result["errorText"])) throw new BrowserError(`Navigation failed: ${result["errorText"]}`);
+			const outcome = await waitOutcome;
+			if (!outcome.ok) throw outcome.error;
+		} catch (error) {
+			wait.cancel();
+			await this.#stopLoading(Math.min(timeout, BROWSER_STOP_LOADING_TIMEOUT_MS));
+			throw error;
+		}
+		const currentUrl = await this.#evaluate("location.href");
+		this.#url = typeof currentUrl === "string" ? currentUrl : url;
+	}
+	async content() {
+		const [title, html, text, currentUrl] = await Promise.all([
+			this.#evaluate("document.title"),
+			this.#evaluate(guardEvaluateExpression("document.documentElement.outerHTML", BROWSER_RESULT_LIMIT)),
+			this.#evaluate(guardEvaluateExpression("document.body ? document.body.innerText : \"\"", BROWSER_RESULT_LIMIT)),
+			this.#evaluate("location.href")
+		]);
+		if (typeof currentUrl === "string") this.#url = currentUrl;
+		return {
+			url: this.#url,
+			title: typeof title === "string" ? title : "",
+			html: typeof html === "string" ? html : "",
+			text: typeof text === "string" ? text : ""
+		};
+	}
+	async screenshot(options) {
+		const format = options?.type ?? "png";
+		const params = { format };
+		if (options?.quality !== void 0 && format === "jpeg") params["quality"] = options.quality;
+		if (options?.full === true) {
+			const metrics = await this.#client.send("Page.getLayoutMetrics", void 0, this.#sessionId);
+			if ((0, _orkestrel_contract.isRecord)(metrics) && (0, _orkestrel_contract.isRecord)(metrics["contentSize"])) {
+				const contentSize = metrics["contentSize"];
+				const width = typeof contentSize["width"] === "number" ? contentSize["width"] : 0;
+				const height = typeof contentSize["height"] === "number" ? contentSize["height"] : 0;
+				if (width > 0 && height > 0) {
+					params["clip"] = {
+						x: 0,
+						y: 0,
+						width,
+						height,
+						scale: 1
+					};
+					params["captureBeyondViewport"] = true;
+				}
+			}
+		}
+		const result = await this.#client.send("Page.captureScreenshot", params, this.#sessionId);
+		if (!(0, _orkestrel_contract.isRecord)(result) || !(0, _orkestrel_contract.isString)(result["data"])) throw new BrowserError("Screenshot failed: no data returned");
+		const bytes = decodeBase64(result["data"]);
+		if (options?.path !== void 0 && this.#writer !== void 0) await this.#writer.write(options.path, bytes);
+		return {
+			bytes,
+			path: options?.path
+		};
+	}
+	async click(selector, options) {
+		const timeout = options?.timeout ?? 3e4;
+		await this.#waitForSelector(selector, timeout);
+		await this.#evaluate(`(() => { const el = document.querySelector(${JSON.stringify(selector)}); if (el) { el.scrollIntoView({ block: 'center' }); el.click(); } else { throw new Error('Element not found: ' + ${JSON.stringify(selector)}); } })()`);
+	}
+	async fill(selector, value, options) {
+		const timeout = options?.timeout ?? 3e4;
+		await this.#waitForSelector(selector, timeout);
+		await this.#evaluate(`(() => {
+                const el = document.querySelector(${JSON.stringify(selector)});
+                if (!el) throw new Error('Element not found: ' + ${JSON.stringify(selector)});
+                el.focus();
+                if (el.isContentEditable) {
+                    el.textContent = ${JSON.stringify(value)};
+                    el.dispatchEvent(new Event('input', { bubbles: true }));
+                } else {
+                    el.value = ${JSON.stringify(value)};
+                    el.dispatchEvent(new Event('input', { bubbles: true }));
+                    el.dispatchEvent(new Event('change', { bubbles: true }));
+                }
+            })()`);
+	}
+	async select(selector, values, options) {
+		const timeout = options?.timeout ?? 3e4;
+		await this.#waitForSelector(selector, timeout);
+		const valuesJson = JSON.stringify([...values]);
+		await this.#evaluate(`(() => {
+                const el = document.querySelector(${JSON.stringify(selector)});
+                if (!el) throw new Error('Element not found: ' + ${JSON.stringify(selector)});
+                const vals = ${valuesJson};
+                for (const opt of el.options) {
+                    opt.selected = vals.includes(opt.value);
+                }
+                el.dispatchEvent(new Event('change', { bubbles: true }));
+            })()`);
+	}
+	async evaluate(expression) {
+		return this.#evaluate(guardEvaluateExpression(expression, BROWSER_RESULT_LIMIT));
+	}
+	async wait(selector, options) {
+		const timeout = options?.timeout ?? 3e4;
+		await this.#waitForSelector(selector, timeout);
+	}
+	async frame(name) {
+		return (await this.frames()).find((frame) => frame.name === name || frame.url === name);
+	}
+	async frames() {
+		const result = await this.#client.send("Page.getFrameTree", void 0, this.#sessionId);
+		if (!(0, _orkestrel_contract.isRecord)(result) || !(0, _orkestrel_contract.isRecord)(result["frameTree"])) return [];
+		const frames = [];
+		this.#flattenFrameTree(result["frameTree"], frames);
+		return frames;
+	}
+	async codegen(options) {
+		if (this.#codegen !== void 0) return this.#codegen;
+		const codegen = new BrowserCodegen(this.#client, this.#sessionId, options);
+		await codegen.start();
+		this.#codegen = codegen;
+		return codegen;
+	}
+	async close() {
+		if (this.#closed) return;
+		this.#closed = true;
+		if (this.#codegen !== void 0) {
+			try {
+				await this.#codegen.destroy();
+			} catch {}
+			this.#codegen = void 0;
+		}
+		this.#client.unsubscribe("Target.targetDestroyed", this.#destroyHandler);
+		try {
+			await this.#client.send("Target.closeTarget", { targetId: this.#targetId });
+		} catch {}
+	}
+	#flattenFrameTree(node, out) {
+		const frame = node["frame"];
+		if ((0, _orkestrel_contract.isRecord)(frame) && (0, _orkestrel_contract.isString)(frame["id"]) && (0, _orkestrel_contract.isString)(frame["url"])) {
+			const parent = frame["parentId"];
+			const name = frame["name"];
+			out.push({
+				id: frame["id"],
+				...(0, _orkestrel_contract.isString)(parent) ? { parent } : {},
+				...(0, _orkestrel_contract.isString)(name) && name !== "" ? { name } : {},
+				url: frame["url"]
+			});
+		}
+		const children = node["childFrames"];
+		if (Array.isArray(children)) {
+			for (const child of children) if ((0, _orkestrel_contract.isRecord)(child)) this.#flattenFrameTree(child, out);
+		}
+	}
+	async #stopLoading(timeout) {
+		try {
+			await this.#client.send("Page.stopLoading", void 0, this.#sessionId, timeout);
+		} catch {}
+	}
+	async #evaluate(expression) {
+		const result = await this.#client.send("Runtime.evaluate", {
+			expression,
+			returnByValue: true,
+			awaitPromise: true
+		}, this.#sessionId);
+		if (!(0, _orkestrel_contract.isRecord)(result)) return void 0;
+		if ((0, _orkestrel_contract.isRecord)(result["exceptionDetails"])) {
+			const details = result["exceptionDetails"];
+			if ((0, _orkestrel_contract.isRecord)(details["exception"]) && (0, _orkestrel_contract.isString)(details["exception"]["description"])) {
+				const description = details["exception"]["description"];
+				const limitMatch = BROWSER_RESULT_LIMIT_PATTERN.exec(description);
+				if (limitMatch !== null) throw new BrowserResultLimitError("Evaluation result exceeds BROWSER_RESULT_LIMIT", {
+					length: Number(limitMatch[1]),
+					limit: BROWSER_RESULT_LIMIT
+				});
+				throw new BrowserError(description);
+			}
+			throw new BrowserError("JavaScript evaluation failed");
+		}
+		const remoteObject = result["result"];
+		if (!(0, _orkestrel_contract.isRecord)(remoteObject)) return void 0;
+		if ("value" in remoteObject) return remoteObject["value"];
+	}
+	async #waitForSelector(selector, timeout) {
+		const deadline = Date.now() + timeout;
+		const selectorJson = JSON.stringify(selector);
+		while (Date.now() < deadline) {
+			if (await this.#evaluate(`document.querySelector(${selectorJson}) !== null`) === true) return;
+			await new Promise((resolve) => setTimeout(resolve, 100));
+		}
+		throw new BrowserSelectorError(`Timeout waiting for selector: ${selector}`);
+	}
+	#waitForLoadEvent(condition, timeout) {
+		const eventName = condition === "domcontentloaded" ? "Page.domContentEventFired" : "Page.loadEventFired";
+		let settled = false;
+		let timer;
+		let handler;
+		const promise = new Promise((resolve, reject) => {
+			timer = setTimeout(() => {
+				if (settled) return;
+				settled = true;
+				this.#client.unsubscribe(eventName, handler, this.#sessionId);
+				reject(new BrowserError(`Navigation timeout after ${timeout}ms`));
+			}, timeout);
+			handler = () => {
+				if (settled) return;
+				settled = true;
+				clearTimeout(timer);
+				this.#client.unsubscribe(eventName, handler, this.#sessionId);
+				resolve();
+			};
+			this.#client.subscribe(eventName, handler, this.#sessionId);
+		});
+		const cancel = () => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			this.#client.unsubscribe(eventName, handler, this.#sessionId);
+		};
+		return {
+			promise,
+			cancel
+		};
+	}
+};
+//#endregion
+//#region src/core/BrowserContext.ts
+var BrowserContext = class {
+	#client;
+	#id;
+	#viewport;
+	#writer;
+	#pages = /* @__PURE__ */ new Map();
+	constructor(client, id, viewport, writer) {
+		this.#client = client;
+		this.#id = id;
+		this.#viewport = viewport;
+		this.#writer = writer;
+	}
+	get id() {
+		return this.#id;
+	}
+	page(index) {
+		const i = index ?? 0;
+		const values = [...this.#pages.values()];
+		return i >= 0 && i < values.length ? values[i] : void 0;
+	}
+	pages() {
+		return [...this.#pages.values()];
+	}
+	async create(options) {
+		const createParams = { url: "about:blank" };
+		if (this.#id !== void 0) createParams["browserContextId"] = this.#id;
+		const result = await this.#client.send("Target.createTarget", createParams);
+		if (!(0, _orkestrel_contract.isRecord)(result) || !(0, _orkestrel_contract.isString)(result["targetId"])) throw new Error("Failed to create new browser target");
+		const targetId = result["targetId"];
+		const attachResult = await this.#client.send("Target.attachToTarget", {
+			targetId,
+			flatten: true
+		});
+		if (!(0, _orkestrel_contract.isRecord)(attachResult) || !(0, _orkestrel_contract.isString)(attachResult["sessionId"])) throw new Error("Failed to attach to browser target");
+		const sessionId = attachResult["sessionId"];
+		await this.#client.send("Page.enable", void 0, sessionId);
+		await this.#client.send("Runtime.enable", void 0, sessionId);
+		const viewport = options?.viewport ?? this.#viewport;
+		if (viewport !== void 0) await this.#client.send("Emulation.setDeviceMetricsOverride", {
+			width: viewport.width,
+			height: viewport.height,
+			deviceScaleFactor: 1,
+			mobile: false
+		}, sessionId);
+		const page = new BrowserPage(this.#client, targetId, sessionId, this.#writer, options?.url);
+		if (options?.url !== void 0 && options.url !== "about:blank") await page.navigate(options.url, { timeout: options.timeout });
+		this.#pages.set(targetId, page);
+		return page;
+	}
+	async sync(targets) {
+		const pageTargets = targets.filter((t) => t.type === "page");
+		const targetIds = new Set(pageTargets.map((t) => t.id));
+		for (const [id, page] of this.#pages) {
+			if (targetIds.has(id)) continue;
+			try {
+				await page.close();
+			} catch {}
+			this.#pages.delete(id);
+		}
+		for (const target of pageTargets) {
+			if (this.#pages.has(target.id)) continue;
+			try {
+				const attachResult = await this.#client.send("Target.attachToTarget", {
+					targetId: target.id,
+					flatten: true
+				});
+				if (!(0, _orkestrel_contract.isRecord)(attachResult) || !(0, _orkestrel_contract.isString)(attachResult["sessionId"])) continue;
+				const sessionId = attachResult["sessionId"];
+				await this.#client.send("Page.enable", void 0, sessionId);
+				await this.#client.send("Runtime.enable", void 0, sessionId);
+				if (this.#viewport !== void 0) try {
+					await this.#client.send("Emulation.setDeviceMetricsOverride", {
+						width: this.#viewport.width,
+						height: this.#viewport.height,
+						deviceScaleFactor: 1,
+						mobile: false
+					}, sessionId);
+				} catch {}
+				this.#pages.set(target.id, new BrowserPage(this.#client, target.id, sessionId, this.#writer, target.url));
+			} catch {}
+		}
+	}
+	async close() {
+		for (const page of this.#pages.values()) try {
+			await page.close();
+		} catch {}
+		this.#pages.clear();
+		if (this.#id !== void 0) try {
+			await this.#client.send("Target.disposeBrowserContext", { browserContextId: this.#id });
+		} catch {}
+	}
+};
+//#endregion
+//#region src/core/factories.ts
+/**
+* Create a CDP client bound to the given transport.
+*
+* @param options - The transport (and optional timeout) the client uses
+* @returns A {@link CDPClientInterface}
+*
+* @example
+* ```ts
+* import { createCDPClient } from '@src/core'
+*
+* const client = createCDPClient({ transport })
+* await client.connect()
+* ```
+*/
+function createCDPClient(options) {
+	return new CDPClient(options);
+}
+//#endregion
+exports.BASE64_CHARS = BASE64_CHARS;
+exports.BASE64_LOOKUP = BASE64_LOOKUP;
+exports.BROWSER_CODEGEN_BINDING_NAME = BROWSER_CODEGEN_BINDING_NAME;
+exports.BROWSER_CODEGEN_SOURCE = BROWSER_CODEGEN_SOURCE;
+exports.BROWSER_DEFAULT_TIMEOUT_MS = BROWSER_DEFAULT_TIMEOUT_MS;
+exports.BROWSER_DEFAULT_VIEWPORT_HEIGHT = BROWSER_DEFAULT_VIEWPORT_HEIGHT;
+exports.BROWSER_DEFAULT_VIEWPORT_WIDTH = BROWSER_DEFAULT_VIEWPORT_WIDTH;
+exports.BROWSER_RESULT_LIMIT = BROWSER_RESULT_LIMIT;
+exports.BROWSER_RESULT_LIMIT_PATTERN = BROWSER_RESULT_LIMIT_PATTERN;
+exports.BROWSER_RESULT_LIMIT_SENTINEL_PREFIX = BROWSER_RESULT_LIMIT_SENTINEL_PREFIX;
+exports.BROWSER_STOP_LOADING_TIMEOUT_MS = BROWSER_STOP_LOADING_TIMEOUT_MS;
+exports.BROWSER_WAIT_POLL_INTERVAL_MS = BROWSER_WAIT_POLL_INTERVAL_MS;
+exports.BrowserCodegen = BrowserCodegen;
+exports.BrowserContext = BrowserContext;
+exports.BrowserError = BrowserError;
+exports.BrowserPage = BrowserPage;
+exports.BrowserResultLimitError = BrowserResultLimitError;
+exports.BrowserSelectorError = BrowserSelectorError;
+exports.CDPClient = CDPClient;
+exports.CDPConnectionError = CDPConnectionError;
+exports.CDPError = CDPError;
+exports.CDPTimeoutError = CDPTimeoutError;
+exports.compileCodegenScript = compileCodegenScript;
+exports.createCDPClient = createCDPClient;
+exports.decodeBase64 = decodeBase64;
+exports.guardEvaluateExpression = guardEvaluateExpression;
+exports.isBrowserError = isBrowserError;
+exports.isBrowserResultLimitError = isBrowserResultLimitError;
+exports.isBrowserSelectorError = isBrowserSelectorError;
+exports.isCDPConnectionError = isCDPConnectionError;
+exports.isCDPError = isCDPError;
+exports.isCDPTimeoutError = isCDPTimeoutError;
+exports.normalizeCodegenActions = normalizeCodegenActions;
+exports.parseCodegenActionPayload = parseCodegenActionPayload;
+exports.readCodegenNavigateAction = readCodegenNavigateAction;
+
+//# sourceMappingURL=index.cjs.map