@alfe.ai/browser 0.2.0 → 0.3.0

package/dist/index.js

@@ -1,5 +1,134 @@
-import { RemoteFrameType, TurnController, decodeJson, encodeFrame, encodeJsonFrame, encodeScreencastFrame } from "@alfe.ai/remote";
+import { RemoteFrameType, TurnController, decodeKeyInputPayload, decodeMouseInputPayload, decodeResizePayload, decodeScreencastAckPayload, decodeWheelInputPayload, encodeFrame, encodeJsonFrame, encodeScreencastFrame } from "@alfe.ai/remote";
 import puppeteer, { TargetType } from "puppeteer-core";
+//#region src/boundary.ts
+const MAX_VIEWPORT_WIDTH = 4096;
+const MAX_VIEWPORT_HEIGHT = 4096;
+const MAX_SELECTOR_CHARS = 4096;
+const MAX_EXPRESSION_CHARS = 128 * 1024;
+const MAX_NAVIGATION_URL_CHARS = 8192;
+const MAX_WAIT_MS = 12e4;
+const MAX_RESULT_BYTES = 1024 * 1024;
+const MAX_RESULT_DEPTH = 10;
+const MAX_RESULT_NODES = 2e4;
+const MAX_RESULT_ARRAY_ITEMS = 1e4;
+const MAX_RESULT_STRING_CHARS = 25e4;
+const UNSAFE_KEYS = new Set([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
+const FORBIDDEN_CHROME_ARG_PREFIXES = [
+	"--allow-file-access-from-files",
+	"--disable-web-security",
+	"--host-resolver-rules",
+	"--load-extension",
+	"--remote-debugging-address",
+	"--remote-debugging-pipe",
+	"--remote-debugging-port",
+	"--user-data-dir"
+];
+function normalizeViewport(width, height, dpr) {
+	if (!Number.isInteger(width) || width < 1 || width > 4096) throw new Error(`viewport width must be an integer from 1 to ${String(MAX_VIEWPORT_WIDTH)}`);
+	if (!Number.isInteger(height) || height < 1 || height > 4096) throw new Error(`viewport height must be an integer from 1 to ${String(MAX_VIEWPORT_HEIGHT)}`);
+	if (!Number.isFinite(dpr) || dpr < .1 || dpr > 4) throw new Error(`viewport dpr must be from 0.1 to ${String(4)}`);
+	if (width * height * dpr * dpr > 33554432) throw new Error("viewport exceeds the device-pixel budget");
+	return {
+		width,
+		height,
+		dpr
+	};
+}
+function validateIdleShutdownMs(value) {
+	if (!Number.isInteger(value) || value < 1e3 || value > 1440 * 60 * 1e3) throw new Error("idle shutdown must be an integer from 1000 to 86400000ms");
+	return value;
+}
+function validateChromeArgs(values) {
+	if (values.length > 64) throw new Error("too many extra Chrome arguments");
+	return values.map((value) => {
+		const arg = validateString("Chrome argument", value, 4096);
+		const key = arg.split("=", 1)[0]?.toLowerCase() ?? "";
+		if (FORBIDDEN_CHROME_ARG_PREFIXES.includes(key)) throw new Error(`Chrome argument ${key} is owned by the browser runtime`);
+		return arg;
+	});
+}
+function validateNavigationUrl(value) {
+	const raw = validateString("navigation URL", value, MAX_NAVIGATION_URL_CHARS);
+	let parsed;
+	try {
+		parsed = new URL(raw);
+	} catch {
+		throw new Error("navigation URL must be an absolute HTTP(S) URL");
+	}
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:" || parsed.username !== "" || parsed.password !== "") throw new Error("navigation URL must be an absolute HTTP(S) URL without credentials");
+	return parsed.href;
+}
+function validateSelector(value) {
+	return validateString("selector", value, MAX_SELECTOR_CHARS);
+}
+function validateTypeText(value) {
+	if (value.length > 32768) throw new Error("type text exceeds the character limit");
+	return value;
+}
+function validateExpression(value) {
+	return validateString("expression", value, MAX_EXPRESSION_CHARS);
+}
+function validateWaitOptions(opts) {
+	if ([
+		opts.selector !== void 0,
+		opts.ms !== void 0,
+		opts.urlPattern !== void 0
+	].filter(Boolean).length !== 1) throw new Error("waitFor requires exactly one selector, ms, or urlPattern");
+	if (opts.selector !== void 0) return { selector: validateSelector(opts.selector) };
+	if (opts.urlPattern !== void 0) return { urlPattern: validateString("URL pattern", opts.urlPattern, MAX_NAVIGATION_URL_CHARS) };
+	if (!Number.isInteger(opts.ms) || (opts.ms ?? 0) < 0 || (opts.ms ?? 0) > 12e4) throw new Error(`wait duration must be an integer from 0 to ${String(MAX_WAIT_MS)}ms`);
+	return { ms: opts.ms };
+}
+function assertBoundedAutomationResult(value) {
+	cloneJson(value, 0, { nodes: 0 });
+	let encoded;
+	try {
+		encoded = JSON.stringify(value);
+	} catch {
+		throw new Error("browser evaluation result must be JSON serializable");
+	}
+	if (Buffer.byteLength(encoded, "utf8") > MAX_RESULT_BYTES) throw new Error("browser evaluation result exceeds the byte limit");
+	return value;
+}
+function validateString(label, value, maxChars) {
+	if (value.length < 1 || value.length > maxChars || containsControlCharacter(value)) throw new Error(`${label} must contain 1 to ${String(maxChars)} non-control characters`);
+	return value;
+}
+function cloneJson(value, depth, state) {
+	state.nodes += 1;
+	if (state.nodes > MAX_RESULT_NODES) throw new Error("browser evaluation result contains too many values");
+	if (depth > MAX_RESULT_DEPTH) throw new Error("browser evaluation result exceeds the depth limit");
+	if (value === null || typeof value === "boolean") return value;
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) throw new Error("browser evaluation result contains a non-finite number");
+		return value;
+	}
+	if (typeof value === "string") {
+		if (value.length > MAX_RESULT_STRING_CHARS) throw new Error("browser evaluation result contains an oversized string");
+		return value;
+	}
+	if (Array.isArray(value)) {
+		if (value.length > MAX_RESULT_ARRAY_ITEMS) throw new Error("browser evaluation result contains an oversized array");
+		return value.map((entry) => cloneJson(entry, depth + 1, state));
+	}
+	if (typeof value !== "object") throw new Error("browser evaluation result contains a non-JSON value");
+	for (const [key, nested] of Object.entries(value)) {
+		if (UNSAFE_KEYS.has(key) || key.length < 1 || key.length > 256) throw new Error("browser evaluation result contains an unsafe property name");
+		cloneJson(nested, depth + 1, state);
+	}
+	return value;
+}
+function containsControlCharacter(value) {
+	return Array.from(value).some((character) => {
+		const codePoint = character.codePointAt(0) ?? 0;
+		return codePoint < 32 || codePoint === 127;
+	});
+}
+//#endregion
 //#region src/browser-session.ts
 /**
 * BrowserSession — owns the single headless Chrome instance the agent
@@ -29,50 +158,79 @@ var BrowserSession = class {
 	launching = null;
 	holds = 0;
 	idleTimer = null;
+	generation = 0;
+	preparedPages = /* @__PURE__ */ new WeakSet();
+	activePageListeners = /* @__PURE__ */ new Set();
 	log;
 	idleMs;
 	constructor(options) {
 		this.options = options;
 		this.log = options.logger ?? noopLogger$2;
-		this.idleMs = options.idleShutdownMs ?? DEFAULT_IDLE_MS;
+		this.idleMs = validateIdleShutdownMs(options.idleShutdownMs ?? DEFAULT_IDLE_MS);
 	}
 	/** Launch Chrome if not already running (idempotent, concurrent-safe). */
 	async ensureLaunched() {
 		if (this.browser) return;
 		if (this.launching) return this.launching;
-		this.launching = this.doLaunch().finally(() => {
-			this.launching = null;
+		const generation = ++this.generation;
+		const launching = this.doLaunch(generation).finally(() => {
+			if (this.launching === launching) this.launching = null;
 		});
-		return this.launching;
+		this.launching = launching;
+		return launching;
 	}
-	async doLaunch() {
+	async doLaunch(generation) {
 		const args = [
 			"--disable-blink-features=AutomationControlled",
 			...this.options.noSandbox ? ["--no-sandbox", "--disable-setuid-sandbox"] : [],
-			...this.options.extraArgs ?? []
+			...validateChromeArgs(this.options.extraArgs ?? [])
 		];
 		this.log.info(`Launching Chrome (${this.options.executablePath})`);
-		this.browser = await puppeteer.launch({
+		const browser = await puppeteer.launch({
 			executablePath: this.options.executablePath,
 			headless: this.options.headless ?? true,
 			userDataDir: this.options.userDataDir,
 			args
 		});
-		this.activePage = (await this.browser.pages())[0] ?? await this.browser.newPage();
-		this.browser.on("targetcreated", (target) => {
-			if (target.type() !== TargetType.PAGE) return;
-			target.page().then((page) => {
-				if (!page) return;
-				if (this.adoptIfNavigable(page)) return;
-				page.on("framenavigated", (frame) => {
-					if (frame === page.mainFrame()) this.adoptIfNavigable(page);
+		try {
+			if (!this.isLaunchCurrent(generation, browser)) throw new Error("Browser launch superseded");
+			browser.on("disconnected", () => {
+				if (this.browser !== browser) return;
+				this.generation += 1;
+				this.browser = null;
+				this.activePage = null;
+			});
+			const pages = await browser.pages();
+			const initialPage = pages[0] ?? await browser.newPage();
+			await Promise.all(pages.map((page) => this.preparePage(page)));
+			await this.preparePage(initialPage);
+			if (!this.isLaunchCurrent(generation, browser)) throw new Error("Browser launch superseded");
+			this.browser = browser;
+			this.setActivePage(initialPage);
+			browser.on("targetcreated", (target) => {
+				if (this.browser !== browser || target.type() !== TargetType.PAGE) return;
+				target.page().then(async (page) => {
+					if (!page || this.browser !== browser) return;
+					await this.preparePage(page);
+					if (this.adoptIfNavigable(page)) return;
+					page.on("framenavigated", (frame) => {
+						if (this.browser === browser && frame === page.mainFrame()) this.adoptIfNavigable(page);
+					});
+				}).catch(() => {});
+			});
+			browser.on("targetdestroyed", (target) => {
+				const closedPage = this.activePage;
+				if (this.browser !== browser || !closedPage || target.type() !== TargetType.PAGE) return;
+				target.page().then(async (page) => {
+					if (page === closedPage && this.browser === browser && this.activePage === closedPage) await this.restoreAfterClose(browser, closedPage, target.opener());
+				}).catch(() => {
+					this.log.warn("Could not restore the browser page after a popup closed");
 				});
-			}).catch(() => {});
-		});
-		this.browser.on("disconnected", () => {
-			this.browser = null;
-			this.activePage = null;
-		});
+			});
+		} catch (error) {
+			await browser.close().catch(() => void 0);
+			throw error;
+		}
 	}
 	/**
 	* Adopt `page` as the streamed active page iff it has a real navigable
@@ -82,18 +240,98 @@ var BrowserSession = class {
 	adoptIfNavigable(page) {
 		if (page.isClosed() || !isNavigablePageUrl(page.url())) return false;
 		if (this.activePage === page) return true;
-		this.activePage = page;
+		this.setActivePage(page);
 		this.log.debug("Active page switched to new target");
 		return true;
 	}
+	/** A login popup can close while the agent is parked for human control.
+	* Recover here, without waiting for another automation call to discover
+	* that the active page is closed, and rebind the viewer to its opener. */
+	async restoreAfterClose(browser, closedPage, openerTarget) {
+		let opener = await openerTarget?.page();
+		while (this.browser === browser && this.activePage === closedPage) {
+			const pages = await browser.pages();
+			if (this.browser !== browser || this.activePage !== closedPage) return;
+			const page = opener && !opener.isClosed() ? opener : pages.find((candidate) => !candidate.isClosed() && isNavigablePageUrl(candidate.url())) ?? pages.find((candidate) => !candidate.isClosed()) ?? await browser.newPage();
+			opener = null;
+			try {
+				await this.preparePage(page);
+			} catch (error) {
+				if (page.isClosed()) continue;
+				throw error;
+			}
+			if (page.isClosed()) continue;
+			if (this.browser === browser && this.activePage === closedPage) this.setActivePage(page);
+			return;
+		}
+	}
 	/** The current active page, launching Chrome first if needed. */
 	async getActivePage() {
 		await this.ensureLaunched();
 		if (!this.activePage || this.activePage.isClosed()) {
 			if (!this.browser) throw new Error("Browser not available");
-			this.activePage = (await this.browser.pages()).find((p) => !p.isClosed()) ?? await this.browser.newPage();
+			const page = (await this.browser.pages()).find((candidate) => !candidate.isClosed()) ?? await this.browser.newPage();
+			await this.preparePage(page);
+			this.setActivePage(page);
+		}
+		const activePage = this.activePage;
+		if (activePage === null) throw new Error("Browser page not available");
+		return activePage;
+	}
+	onActivePageChange(listener) {
+		this.activePageListeners.add(listener);
+		return () => {
+			this.activePageListeners.delete(listener);
+		};
+	}
+	/** Internal to the serialized automation turn. The caller holds Chrome until
+	* the adapter has disconnected its client/awaited its child process exit. */
+	async withCdpTarget(operation, signal) {
+		signal.throwIfAborted();
+		const page = await this.getActivePage();
+		const browser = this.browser;
+		const generation = this.generation;
+		if (!browser) throw new Error("Browser is unavailable");
+		const disconnected = new AbortController();
+		const abort = () => {
+			disconnected.abort(/* @__PURE__ */ new Error("Browser operation interrupted"));
+		};
+		const operationSignal = AbortSignal.any([signal, disconnected.signal]);
+		const assertCurrent = () => {
+			operationSignal.throwIfAborted();
+			if (this.browser !== browser || this.generation !== generation || !browser.connected || page.isClosed()) throw new Error("Browser operation interrupted");
+		};
+		browser.on("disconnected", abort);
+		page.on("close", abort);
+		try {
+			assertCurrent();
+			const cdp = await page.createCDPSession();
+			let targetId;
+			try {
+				const { targetInfo } = await cdp.send("Target.getTargetInfo");
+				targetId = targetInfo.targetId;
+			} finally {
+				await cdp.detach().catch(() => void 0);
+			}
+			assertCurrent();
+			const browserWSEndpoint = browser.wsEndpoint();
+			const endpoint = new URL(browserWSEndpoint);
+			if (endpoint.protocol !== "ws:" || ![
+				"127.0.0.1",
+				"[::1]",
+				"localhost"
+			].includes(endpoint.hostname) || endpoint.username !== "" || endpoint.password !== "" || !endpoint.pathname.startsWith("/devtools/browser/")) throw new Error("Browser local attachment is unavailable");
+			const result = await operation({
+				browserWSEndpoint,
+				targetId,
+				signal: operationSignal
+			});
+			assertCurrent();
+			return result;
+		} finally {
+			browser.off("disconnected", abort);
+			page.off("close", abort);
 		}
-		return this.activePage;
 	}
 	/** Prevent idle shutdown while a viewer or op is active. */
 	addHold() {
@@ -128,6 +366,8 @@ var BrowserSession = class {
 	}
 	async shutdown() {
 		this.clearIdleTimer();
+		this.generation += 1;
+		this.launching = null;
 		const browser = this.browser;
 		this.browser = null;
 		this.activePage = null;
@@ -135,6 +375,40 @@ var BrowserSession = class {
 			await browser.close();
 		} catch {}
 	}
+	setActivePage(page) {
+		if (this.activePage === page) return;
+		this.activePage = page;
+		for (const listener of this.activePageListeners) try {
+			Promise.resolve(listener(page)).catch((error) => {
+				this.log.warn(`Active-page listener failed: ${error instanceof Error ? error.message : String(error)}`);
+			});
+		} catch (error) {
+			this.log.warn(`Active-page listener failed: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	async preparePage(page) {
+		if (this.preparedPages.has(page)) return;
+		this.preparedPages.add(page);
+		const policy = this.options.isNavigationAllowed;
+		if (policy === void 0) return;
+		try {
+			await page.setRequestInterception(true);
+			page.on("request", (request) => {
+				if (request.isInterceptResolutionHandled()) return;
+				let allowed = false;
+				try {
+					allowed = policy(request.url());
+				} catch {}
+				(allowed ? request.continue() : request.abort("blockedbyclient")).catch(() => void 0);
+			});
+		} catch (error) {
+			this.preparedPages.delete(page);
+			throw error;
+		}
+	}
+	isLaunchCurrent(generation, browser) {
+		return generation === this.generation && browser.connected;
+	}
 };
 //#endregion
 //#region src/screencast-pump.ts
@@ -149,6 +423,12 @@ var ScreencastPump = class {
 	running = false;
 	frameSeq = 0;
 	outstanding = null;
+	generation = 0;
+	viewport = {
+		width: 1280,
+		height: 720,
+		dpr: 1
+	};
 	log;
 	quality;
 	ackTimeoutMs;
@@ -157,6 +437,8 @@ var ScreencastPump = class {
 		this.log = options.logger ?? noopLogger$1;
 		this.quality = options.quality ?? 70;
 		this.ackTimeoutMs = options.ackTimeoutMs ?? 2e3;
+		if (!Number.isInteger(this.quality) || this.quality < 1 || this.quality > 100) throw new Error("Screencast quality must be an integer from 1 to 100");
+		if (!Number.isInteger(this.ackTimeoutMs) || this.ackTimeoutMs < 100 || this.ackTimeoutMs > 3e4) throw new Error("Screencast ack timeout must be an integer from 100 to 30000ms");
 	}
 	get isRunning() {
 		return this.running;
@@ -164,33 +446,60 @@ var ScreencastPump = class {
 	/** Start (or restart) the screencast on the given page. */
 	async start(page, viewport) {
 		await this.stop();
+		const generation = ++this.generation;
+		this.viewport = normalizeViewport(viewport.width, viewport.height, viewport.dpr);
 		const cdp = await page.createCDPSession();
+		if (generation !== this.generation) {
+			await cdp.detach().catch(() => void 0);
+			return;
+		}
 		this.cdp = cdp;
-		await cdp.send("Emulation.setDeviceMetricsOverride", {
-			width: viewport.width,
-			height: viewport.height,
-			deviceScaleFactor: viewport.dpr,
-			mobile: false
-		});
-		cdp.on("Page.screencastFrame", (event) => {
-			this.onCdpFrame(event.data, event.sessionId, event.metadata);
-		});
-		await cdp.send("Page.startScreencast", {
-			format: "jpeg",
-			quality: this.quality,
-			maxWidth: Math.round(viewport.width * viewport.dpr),
-			maxHeight: Math.round(viewport.height * viewport.dpr),
-			everyNthFrame: 1
-		});
-		this.running = true;
-		this.log.debug("Screencast started");
+		try {
+			await cdp.send("Emulation.setDeviceMetricsOverride", {
+				width: this.viewport.width,
+				height: this.viewport.height,
+				deviceScaleFactor: this.viewport.dpr,
+				mobile: false
+			});
+			if (generation !== this.generation || this.cdp !== cdp) return;
+			cdp.on("Page.screencastFrame", (event) => {
+				if (generation !== this.generation || this.cdp !== cdp) return;
+				this.onCdpFrame(cdp, generation, event.data, event.sessionId, event.metadata);
+			});
+			await cdp.send("Page.startScreencast", {
+				format: "jpeg",
+				quality: this.quality,
+				maxWidth: Math.round(this.viewport.width * this.viewport.dpr),
+				maxHeight: Math.round(this.viewport.height * this.viewport.dpr),
+				everyNthFrame: 1
+			});
+			if (generation !== this.generation || this.cdp !== cdp) return;
+			this.running = true;
+			this.log.debug("Screencast started");
+		} catch (error) {
+			if (this.cdp === cdp) this.cdp = null;
+			await cdp.detach().catch(() => void 0);
+			throw error;
+		}
 	}
-	onCdpFrame(dataBase64, cdpSessionId, metadata) {
+	onCdpFrame(cdp, generation, dataBase64, cdpSessionId, metadata) {
 		if (this.outstanding) this.ackCdp(this.outstanding);
-		const frameSeq = ++this.frameSeq;
+		if (dataBase64.length > Math.ceil(9437184 * 4 / 3) + 4) {
+			cdp.send("Page.screencastFrameAck", { sessionId: cdpSessionId }).catch(() => void 0);
+			this.log.warn("Dropped oversized browser screencast frame");
+			return;
+		}
+		const jpeg = Buffer.from(dataBase64, "base64");
+		if (jpeg.length < 3 || jpeg.length > 9437184 || jpeg[0] !== 255 || jpeg[1] !== 216 || jpeg[2] !== 255) {
+			cdp.send("Page.screencastFrameAck", { sessionId: cdpSessionId }).catch(() => void 0);
+			this.log.warn("Dropped invalid browser screencast frame");
+			return;
+		}
+		this.frameSeq = this.frameSeq >= 4294967295 ? 1 : this.frameSeq + 1;
+		const frameSeq = this.frameSeq;
 		const meta = {
-			deviceWidth: metadata.deviceWidth ?? 0,
-			deviceHeight: metadata.deviceHeight ?? 0,
+			deviceWidth: metadata.deviceWidth ?? this.viewport.width * this.viewport.dpr,
+			deviceHeight: metadata.deviceHeight ?? this.viewport.height * this.viewport.dpr,
 			frameSeq,
 			offsetTop: metadata.offsetTop,
 			pageScaleFactor: metadata.pageScaleFactor,
@@ -202,11 +511,19 @@ var ScreencastPump = class {
 		}, this.ackTimeoutMs);
 		timer.unref();
 		this.outstanding = {
+			cdp,
+			generation,
 			cdpSessionId,
 			frameSeq,
 			timer
 		};
-		this.options.onFrame(Buffer.from(dataBase64, "base64"), meta);
+		try {
+			this.options.onFrame(jpeg, meta);
+		} catch (error) {
+			this.log.warn(`Screencast consumer failed: ${error instanceof Error ? error.message : String(error)}`);
+			const outstanding = this.outstanding;
+			if (outstanding.frameSeq === frameSeq) this.ackCdp(outstanding);
+		}
 	}
 	/** Viewer acked frame `frameSeq` — release Chrome to send the next frame. */
 	ackFromViewer(frameSeq) {
@@ -215,9 +532,10 @@ var ScreencastPump = class {
 	ackCdp(outstanding) {
 		clearTimeout(outstanding.timer);
 		this.outstanding = null;
-		if (this.cdp && this.running) this.cdp.send("Page.screencastFrameAck", { sessionId: outstanding.cdpSessionId }).catch(() => {});
+		if (this.cdp === outstanding.cdp && this.running && this.generation === outstanding.generation) outstanding.cdp.send("Page.screencastFrameAck", { sessionId: outstanding.cdpSessionId }).catch(() => {});
 	}
 	async stop() {
+		this.generation += 1;
 		this.running = false;
 		if (this.outstanding) {
 			clearTimeout(this.outstanding.timer);
@@ -242,17 +560,64 @@ const MOUSE_TYPE = {
 	mousepressed: "mousePressed",
 	mousereleased: "mouseReleased"
 };
+const VIRTUAL_KEYS = {
+	Backspace: 8,
+	Tab: 9,
+	Enter: 13,
+	NumpadEnter: 13,
+	Shift: 16,
+	Control: 17,
+	Alt: 18,
+	Pause: 19,
+	CapsLock: 20,
+	Escape: 27,
+	Space: 32,
+	" ": 32,
+	PageUp: 33,
+	PageDown: 34,
+	End: 35,
+	Home: 36,
+	ArrowLeft: 37,
+	ArrowUp: 38,
+	ArrowRight: 39,
+	ArrowDown: 40,
+	Insert: 45,
+	Delete: 46,
+	Meta: 91
+};
+function virtualKeyCode(input) {
+	const named = VIRTUAL_KEYS[input.key ?? ""] ?? VIRTUAL_KEYS[input.code ?? ""];
+	if (typeof named === "number") return named;
+	const letter = /^Key([A-Z])$/.exec(input.code ?? "");
+	if (letter) return letter[1].charCodeAt(0);
+	const digit = /^Digit([0-9])$/.exec(input.code ?? "");
+	if (digit) return digit[1].charCodeAt(0);
+	const key = input.key ?? "";
+	if (/^[A-Za-z0-9]$/.test(key)) return key.toUpperCase().charCodeAt(0);
+	const functionKey = /^F([1-9]|1[0-9]|2[0-4])$/.exec(input.key ?? "");
+	if (functionKey) return 111 + Number(functionKey[1]);
+}
 var InputInjector = class {
 	cdp = null;
 	viewport;
+	generation = 0;
 	constructor(viewport) {
-		this.viewport = viewport;
+		this.viewport = normalizeViewport(viewport.width, viewport.height, viewport.dpr);
 	}
 	async attach(page) {
-		await this.detach();
-		this.cdp = await page.createCDPSession();
+		const generation = ++this.generation;
+		const old = this.cdp;
+		this.cdp = null;
+		if (old) await old.detach().catch(() => void 0);
+		const cdp = await page.createCDPSession();
+		if (generation !== this.generation) {
+			await cdp.detach().catch(() => void 0);
+			return;
+		}
+		this.cdp = cdp;
 	}
 	async detach() {
+		this.generation += 1;
 		const cdp = this.cdp;
 		this.cdp = null;
 		if (cdp) try {
@@ -260,12 +625,12 @@ var InputInjector = class {
 		} catch {}
 	}
 	updateViewport(viewport) {
-		this.viewport = viewport;
+		this.viewport = normalizeViewport(viewport.width, viewport.height, viewport.dpr);
 	}
 	toCssPx(nx, ny) {
 		return {
-			x: Math.round(clamp01(nx) * this.viewport.width),
-			y: Math.round(clamp01(ny) * this.viewport.height)
+			x: Math.round(clamp01(nx) * Math.max(0, this.viewport.width - 1)),
+			y: Math.round(clamp01(ny) * Math.max(0, this.viewport.height - 1))
 		};
 	}
 	mouse(p) {
@@ -296,19 +661,18 @@ var InputInjector = class {
 	key(p) {
 		if (!this.cdp) return;
 		if (p.type === "char") {
-			this.cdp.send("Input.dispatchKeyEvent", {
-				type: "char",
-				text: p.text ?? "",
-				modifiers: p.modifiers ?? 0
-			}).catch(() => {});
+			this.cdp.send("Input.insertText", { text: p.text ?? "" }).catch(() => {});
 			return;
 		}
+		const modifiers = p.modifiers ?? 0;
+		const text = p.type === "keydown" && !(modifiers & 7) ? p.text ?? (p.key === "Enter" ? "\r" : void 0) : void 0;
 		this.cdp.send("Input.dispatchKeyEvent", {
-			type: p.type === "keydown" ? "keyDown" : "keyUp",
+			type: p.type === "keyup" ? "keyUp" : text ? "keyDown" : "rawKeyDown",
 			key: p.key,
 			code: p.code,
-			text: p.type === "keydown" ? p.text : void 0,
-			modifiers: p.modifiers ?? 0
+			text,
+			windowsVirtualKeyCode: virtualKeyCode(p),
+			modifiers
 		}).catch(() => {});
 	}
 };
@@ -318,64 +682,129 @@ function clamp01(n) {
 }
 //#endregion
 //#region src/automation.ts
+const OPERATION_TIMEOUT_MS = 3e4;
 var BrowserAutomation = class {
+	operationTail = Promise.resolve();
+	stopping = new AbortController();
 	constructor(session, turn, isNavigationAllowed) {
 		this.session = session;
 		this.turn = turn;
 		this.isNavigationAllowed = isNavigationAllowed;
 	}
 	async navigate(url) {
-		await this.turn.acquireAgent();
-		if (!this.isNavigationAllowed(url)) throw new Error(`Navigation to ${url} blocked by SSRF policy`);
-		const page = await this.session.getActivePage();
-		await page.goto(url, { waitUntil: "domcontentloaded" });
-		return {
-			url: page.url(),
-			title: await page.title()
-		};
+		return this.run(async () => {
+			const target = validateNavigationUrl(url);
+			let allowed = false;
+			try {
+				allowed = this.isNavigationAllowed(target);
+			} catch {}
+			if (!allowed) throw new Error("Navigation blocked by browser policy");
+			const page = await this.session.getActivePage();
+			await page.goto(target, {
+				waitUntil: "domcontentloaded",
+				timeout: OPERATION_TIMEOUT_MS
+			});
+			return {
+				url: page.url(),
+				title: await page.title()
+			};
+		});
 	}
 	async click(selector) {
-		await this.turn.acquireAgent();
-		await (await this.session.getActivePage()).click(selector);
+		await this.run(async () => {
+			await (await this.session.getActivePage()).click(validateSelector(selector));
+		});
 	}
 	async type(selector, text) {
-		await this.turn.acquireAgent();
-		await (await this.session.getActivePage()).type(selector, text);
+		await this.run(async () => {
+			await (await this.session.getActivePage()).type(validateSelector(selector), validateTypeText(text));
+		});
 	}
 	async waitFor(opts) {
-		await this.turn.acquireAgent();
-		const page = await this.session.getActivePage();
-		if (opts.selector) await page.waitForSelector(opts.selector);
-		else if (opts.urlPattern) {
-			const pattern = opts.urlPattern;
-			await page.waitForFunction((p) => window.location.href.includes(p), {}, pattern);
-		} else if (typeof opts.ms === "number") await new Promise((resolve) => setTimeout(resolve, opts.ms));
+		await this.run(async () => {
+			const normalized = validateWaitOptions(opts);
+			const page = await this.session.getActivePage();
+			if (normalized.selector !== void 0) await page.waitForSelector(normalized.selector, { timeout: OPERATION_TIMEOUT_MS });
+			else if (normalized.urlPattern !== void 0) await page.waitForFunction((pattern) => window.location.href.includes(pattern), { timeout: OPERATION_TIMEOUT_MS }, normalized.urlPattern);
+			else await new Promise((resolve) => {
+				setTimeout(resolve, normalized.ms ?? 0).unref();
+			});
+		});
 	}
 	/** One-shot JPEG screenshot (base64) for the agent's own reasoning — distinct
 	* from the continuous screencast stream to viewers. */
 	async screenshot() {
-		await this.turn.acquireAgent();
-		return (await this.session.getActivePage()).screenshot({
-			type: "jpeg",
-			quality: 70,
-			encoding: "base64"
+		return this.run(async () => {
+			const image = await (await this.session.getActivePage()).screenshot({
+				type: "jpeg",
+				quality: 70,
+				encoding: "base64"
+			});
+			if (image.length > 14680064) throw new Error("Browser screenshot exceeds the byte limit");
+			return image;
 		});
 	}
 	/** Evaluate an expression in the page context via CDP (no eval on our side). */
 	async evaluate(expression) {
-		await this.turn.acquireAgent();
-		const cdp = await (await this.session.getActivePage()).createCDPSession();
-		try {
-			return (await cdp.send("Runtime.evaluate", {
-				expression,
-				returnByValue: true,
-				awaitPromise: true
-			})).result.value;
-		} finally {
+		return this.run(async () => {
+			const cdp = await (await this.session.getActivePage()).createCDPSession();
 			try {
-				await cdp.detach();
-			} catch {}
-		}
+				const res = await cdp.send("Runtime.evaluate", {
+					expression: validateExpression(expression),
+					returnByValue: true,
+					awaitPromise: true,
+					timeout: OPERATION_TIMEOUT_MS,
+					disableBreaks: true
+				});
+				if (res.exceptionDetails !== void 0) throw new Error("Browser evaluation failed");
+				return assertBoundedAutomationResult(res.result.value ?? null);
+			} finally {
+				try {
+					await cdp.detach();
+				} catch {}
+			}
+		});
+	}
+	/** Wait until all agent operations that were already queued have settled. */
+	async waitUntilIdle() {
+		await this.operationTail;
+	}
+	/** Trusted local adapters share the built-in automation queue and exact page.
+	* The callback must disconnect/await children in finally, including on abort.
+	* Do not invoke another automation operation or handoff from the callback. */
+	withCdpOperation(operation, options = {}) {
+		return this.run((signal) => this.session.withCdpTarget(operation, signal), options);
+	}
+	/** Insert the claim at a precise queue position; later automation parks. */
+	async yieldToHuman(grant) {
+		await this.run(() => {
+			grant();
+			return Promise.resolve();
+		});
+	}
+	/** Abort first, then await callback cleanup before the owner closes Chrome. */
+	async shutdown() {
+		this.stopping.abort(/* @__PURE__ */ new Error("Browser automation stopped"));
+		this.turn.releaseHuman();
+		await this.operationTail;
+	}
+	run(operation, options = {}) {
+		const signal = options.signal ? AbortSignal.any([this.stopping.signal, options.signal]) : this.stopping.signal;
+		const result = this.operationTail.catch(() => void 0).then(async () => {
+			signal.throwIfAborted();
+			this.session.addHold();
+			try {
+				await this.turn.acquireAgent(signal);
+				signal.throwIfAborted();
+				const result = await operation(signal);
+				signal.throwIfAborted();
+				return result;
+			} finally {
+				this.session.removeHold();
+			}
+		});
+		this.operationTail = result.then(() => void 0, () => void 0);
+		return result;
 	}
 };
 //#endregion
@@ -410,12 +839,29 @@ var BrowserSurface = class {
 		dpr: 1
 	};
 	handoff = null;
+	controllerSessionId = null;
+	pendingControllerSessionId = null;
+	claimGeneration = 0;
+	streamGeneration = 0;
+	streamQueue = Promise.resolve();
+	closed = false;
+	removePageListener;
 	log;
 	constructor(options, sendFrame) {
-		this.options = options;
 		this.sendFrame = sendFrame;
 		this.log = options.logger ?? noopLogger;
-		this.session = new BrowserSession(options);
+		const navigationPolicy = options.isNavigationAllowed ?? ((url) => {
+			try {
+				validateNavigationUrl(url);
+				return true;
+			} catch {
+				return false;
+			}
+		});
+		this.session = new BrowserSession({
+			...options,
+			isNavigationAllowed: navigationPolicy
+		});
 		this.turn = new TurnController({ onOwnerChange: () => {
 			this.broadcastState();
 		} });
@@ -426,56 +872,93 @@ var BrowserSurface = class {
 			logger: this.log
 		});
 		this.injector = new InputInjector(this.viewport);
-		this.automation = new BrowserAutomation(this.session, this.turn, options.isNavigationAllowed ?? (() => true));
+		this.automation = new BrowserAutomation(this.session, this.turn, navigationPolicy);
+		this.removePageListener = this.session.onActivePageChange(async () => {
+			if (this.viewers.size > 0) {
+				await this.restartStreaming();
+				this.broadcastState();
+			}
+		});
 	}
 	async openSession(sessionId, open) {
+		if (this.closed) throw new Error("Browser surface is shut down");
+		if (this.viewers.has(sessionId)) {
+			this.sendState(sessionId);
+			return;
+		}
+		const firstViewer = this.viewers.size === 0;
 		this.viewers.add(sessionId);
 		this.session.addHold();
-		if (open.width && open.height) this.viewport = {
-			width: open.width,
-			height: open.height,
-			dpr: open.dpr ?? 1
-		};
-		await this.ensureStreaming();
-		this.sendState(sessionId);
+		try {
+			if (open.width !== void 0 && open.height !== void 0) this.viewport = normalizeViewport(open.width, open.height, open.dpr ?? 1);
+			if (firstViewer) await this.restartStreaming();
+			this.sendState(sessionId);
+		} catch (error) {
+			this.viewers.delete(sessionId);
+			this.session.removeHold();
+			if (this.viewers.size === 0) {
+				this.streamGeneration += 1;
+				this.enqueueStreamCleanup();
+			}
+			throw error;
+		}
 	}
 	handleFrame(frame) {
+		if (this.closed || !this.viewers.has(frame.sessionId)) return;
 		switch (frame.type) {
 			case RemoteFrameType.SCREENCAST_ACK: {
-				const ack = decodeJson(frame.payload);
+				const ack = decodeScreencastAckPayload(frame.payload);
 				if (ack) this.pump.ackFromViewer(ack.frameSeq);
 				this.session.touch();
 				break;
 			}
 			case RemoteFrameType.RESIZE: {
-				const r = decodeJson(frame.payload);
-				if (r) this.applyResize(r.width, r.height, r.dpr ?? 1);
+				const resize = decodeResizePayload(frame.payload);
+				if (resize && frame.sessionId === this.controllerSessionId) this.applyResize(resize.width, resize.height, resize.dpr ?? 1);
 				break;
 			}
 			case RemoteFrameType.INPUT_MOUSE:
-				if (this.turn.humanInControl) {
-					const p = decodeJson(frame.payload);
-					if (p) this.injector.mouse(p);
+				if (frame.sessionId === this.controllerSessionId && this.turn.humanInControl) {
+					const input = decodeMouseInputPayload(frame.payload);
+					if (input) this.injector.mouse(input);
 				}
 				break;
 			case RemoteFrameType.INPUT_WHEEL:
-				if (this.turn.humanInControl) {
-					const p = decodeJson(frame.payload);
-					if (p) this.injector.wheel(p);
+				if (frame.sessionId === this.controllerSessionId && this.turn.humanInControl) {
+					const input = decodeWheelInputPayload(frame.payload);
+					if (input) this.injector.wheel(input);
 				}
 				break;
 			case RemoteFrameType.INPUT_KEY:
-				if (this.turn.humanInControl) {
-					const p = decodeJson(frame.payload);
-					if (p) this.injector.key(p);
+				if (frame.sessionId === this.controllerSessionId && this.turn.humanInControl) {
+					const input = decodeKeyInputPayload(frame.payload);
+					if (input) this.injector.key(input);
 				}
 				break;
-			case RemoteFrameType.TAKEOVER_REQUEST:
-				if (this.turn.grantHuman()) this.broadcast(RemoteFrameType.TAKEOVER_GRANTED);
-				else this.sendFrame(encodeFrame(RemoteFrameType.TAKEOVER_DENIED, frame.sessionId));
+			case RemoteFrameType.TAKEOVER_REQUEST: {
+				if (this.controllerSessionId !== null || this.pendingControllerSessionId !== null) {
+					this.sendFrameSafe(encodeFrame(RemoteFrameType.TAKEOVER_DENIED, frame.sessionId));
+					break;
+				}
+				this.pendingControllerSessionId = frame.sessionId;
+				const claimGeneration = ++this.claimGeneration;
+				this.automation.yieldToHuman(() => {
+					if (this.claimGeneration !== claimGeneration || this.pendingControllerSessionId !== frame.sessionId || !this.viewers.has(frame.sessionId) || this.closed) return;
+					this.pendingControllerSessionId = null;
+					if (this.turn.grantHuman()) {
+						this.controllerSessionId = frame.sessionId;
+						this.broadcast(RemoteFrameType.TAKEOVER_GRANTED);
+					} else this.sendFrameSafe(encodeFrame(RemoteFrameType.TAKEOVER_DENIED, frame.sessionId));
+				}).catch((error) => {
+					if (this.claimGeneration !== claimGeneration || this.pendingControllerSessionId !== frame.sessionId) return;
+					this.pendingControllerSessionId = null;
+					this.log.warn(`Could not grant browser control: ${error instanceof Error ? error.message : String(error)}`);
+					this.sendFrameSafe(encodeFrame(RemoteFrameType.TAKEOVER_DENIED, frame.sessionId));
+				});
 				break;
+			}
 			case RemoteFrameType.RELEASE_CONTROL:
-				this.releaseToAgent();
+				if (frame.sessionId === this.controllerSessionId) this.releaseToAgent();
 				break;
 			default: break;
 		}
@@ -483,9 +966,14 @@ var BrowserSurface = class {
 	closeSession(sessionId) {
 		if (!this.viewers.delete(sessionId)) return;
 		this.session.removeHold();
+		if (this.pendingControllerSessionId === sessionId) {
+			this.pendingControllerSessionId = null;
+			this.claimGeneration += 1;
+		}
+		if (this.controllerSessionId === sessionId) this.releaseToAgent();
 		if (this.viewers.size === 0) {
-			this.pump.stop();
-			if (this.turn.humanInControl) this.releaseToAgent();
+			this.streamGeneration += 1;
+			this.enqueueStreamCleanup();
 		}
 	}
 	/**
@@ -503,17 +991,28 @@ var BrowserSurface = class {
 	* under the user (mislabeled 409 on the real claim; agent only resuming when
 	* the tab closed).
 	*/
-	async requestHandoff(timeoutMs) {
+	async requestHandoff(timeoutMs, signal) {
+		if (!Number.isInteger(timeoutMs) || timeoutMs < 1e3 || timeoutMs > 1800 * 1e3) throw new Error("Browser handoff timeout must be an integer from 1000 to 1800000ms");
+		if (this.closed) throw new Error("Browser surface is shut down");
+		signal?.throwIfAborted();
 		if (this.handoff) this.releaseToAgent();
-		return new Promise((resolve) => {
+		return new Promise((resolve, reject) => {
+			const settle = (result) => {
+				signal?.removeEventListener("abort", onAbort);
+				resolve(result);
+			};
 			const timer = setTimeout(() => {
+				if (this.handoff !== waiter) return;
 				this.handoff = null;
+				this.pendingControllerSessionId = null;
+				this.claimGeneration += 1;
 				if (this.turn.humanInControl) {
 					this.turn.releaseHuman();
+					this.controllerSessionId = null;
 					this.broadcast(RemoteFrameType.CONTROL_REVOKED);
 				}
 				this.currentPageInfo().then(({ url, title }) => {
-					resolve({
+					settle({
 						released: false,
 						timedOut: true,
 						url,
@@ -522,10 +1021,27 @@ var BrowserSurface = class {
 				});
 			}, timeoutMs);
 			timer.unref();
-			this.handoff = {
-				resolve,
+			const waiter = {
+				resolve: settle,
 				timer
 			};
+			const onAbort = () => {
+				if (this.handoff !== waiter) return;
+				this.handoff = null;
+				clearTimeout(timer);
+				signal?.removeEventListener("abort", onAbort);
+				this.pendingControllerSessionId = null;
+				this.claimGeneration += 1;
+				if (this.turn.humanInControl) {
+					this.turn.releaseHuman();
+					this.controllerSessionId = null;
+					this.broadcast(RemoteFrameType.CONTROL_REVOKED);
+				}
+				reject(/* @__PURE__ */ new Error("Browser handoff cancelled"));
+			};
+			this.handoff = waiter;
+			signal?.addEventListener("abort", onAbort, { once: true });
+			if (signal?.aborted) onAbort();
 		});
 	}
 	/**
@@ -541,11 +1057,33 @@ var BrowserSurface = class {
 		this.session.removeHold();
 	}
 	async shutdown() {
-		await this.pump.stop();
-		await this.injector.detach();
+		if (this.closed) return;
+		this.closed = true;
+		this.removePageListener();
+		this.streamGeneration += 1;
+		this.pendingControllerSessionId = null;
+		this.claimGeneration += 1;
+		this.controllerSessionId = null;
+		const waiter = this.handoff;
+		this.handoff = null;
+		if (waiter) {
+			clearTimeout(waiter.timer);
+			waiter.resolve({
+				released: false,
+				timedOut: true,
+				url: "",
+				title: ""
+			});
+		}
+		this.turn.releaseHuman();
+		await this.automation.shutdown();
+		await this.enqueueStreamCleanup();
 		await this.session.shutdown();
 	}
 	releaseToAgent() {
+		this.pendingControllerSessionId = null;
+		this.claimGeneration += 1;
+		this.controllerSessionId = null;
 		this.turn.releaseHuman();
 		const waiter = this.handoff;
 		this.handoff = null;
@@ -561,51 +1099,82 @@ var BrowserSurface = class {
 			});
 		}
 	}
-	async ensureStreaming() {
-		if (this.pump.isRunning || this.viewers.size === 0) return;
-		const page = await this.session.getActivePage();
-		await this.injector.attach(page);
-		this.injector.updateViewport(this.viewport);
-		await this.pump.start(page, this.viewport);
+	restartStreaming() {
+		const generation = ++this.streamGeneration;
+		const run = this.streamQueue.catch(() => void 0).then(async () => {
+			if (!this.shouldStream(generation)) return;
+			try {
+				const page = await this.session.getActivePage();
+				if (!this.shouldStream(generation)) return;
+				await this.injector.attach(page);
+				this.injector.updateViewport(this.viewport);
+				await this.pump.start(page, this.viewport);
+				if (!this.shouldStream(generation)) {
+					await this.pump.stop();
+					await this.injector.detach();
+				}
+			} catch (error) {
+				await this.pump.stop();
+				await this.injector.detach();
+				throw error;
+			}
+		});
+		this.streamQueue = run.catch((error) => {
+			this.log.warn(`Browser streaming failed: ${error instanceof Error ? error.message : String(error)}`);
+		});
+		return run;
+	}
+	enqueueStreamCleanup() {
+		const cleanup = this.streamQueue.catch(() => void 0).then(async () => {
+			await this.pump.stop();
+			await this.injector.detach();
+		});
+		this.streamQueue = cleanup.catch(() => void 0);
+		return cleanup;
+	}
+	shouldStream(generation) {
+		return !this.closed && this.viewers.size > 0 && generation === this.streamGeneration;
 	}
 	async applyResize(width, height, dpr) {
-		this.viewport = {
-			width,
-			height,
-			dpr
-		};
+		this.viewport = normalizeViewport(width, height, dpr);
 		this.injector.updateViewport(this.viewport);
-		if (this.pump.isRunning) {
-			const page = await this.session.getActivePage();
-			await this.pump.start(page, this.viewport);
-		}
+		if (this.viewers.size > 0) await this.restartStreaming();
 	}
 	broadcastFrame(jpeg, meta) {
-		for (const sessionId of this.viewers) this.sendFrame(encodeScreencastFrame(sessionId, meta, jpeg));
+		for (const sessionId of this.viewers) try {
+			this.sendFrameSafe(encodeScreencastFrame(sessionId, meta, jpeg));
+		} catch (error) {
+			this.log.warn(`Browser frame encoding failed: ${error instanceof Error ? error.message : String(error)}`);
+		}
 	}
 	broadcast(type) {
-		for (const sessionId of this.viewers) this.sendFrame(encodeFrame(type, sessionId));
+		for (const sessionId of this.viewers) this.sendFrameSafe(encodeFrame(type, sessionId));
 	}
 	broadcastState() {
 		for (const sessionId of this.viewers) this.sendState(sessionId);
 	}
 	sendState(sessionId) {
 		this.currentPageInfo().then(({ url, title }) => {
+			if (!this.viewers.has(sessionId) || this.closed) return;
 			const state = {
 				surface: "browser",
 				url,
 				title,
 				controller: this.turn.currentOwner
 			};
-			this.sendFrame(encodeJsonFrame(RemoteFrameType.SESSION_STATE, sessionId, state));
+			try {
+				this.sendFrameSafe(encodeJsonFrame(RemoteFrameType.SESSION_STATE, sessionId, state));
+			} catch (error) {
+				this.log.warn(`Browser state encoding failed: ${error instanceof Error ? error.message : String(error)}`);
+			}
 		});
 	}
 	async currentPageInfo() {
 		try {
 			const page = await this.session.getActivePage();
 			return {
-				url: page.url(),
-				title: await page.title()
+				url: page.url().slice(0, 8192),
+				title: (await page.title()).slice(0, 4096)
 			};
 		} catch {
 			return {
@@ -614,6 +1183,13 @@ var BrowserSurface = class {
 			};
 		}
 	}
+	sendFrameSafe(frame) {
+		try {
+			this.sendFrame(frame);
+		} catch (error) {
+			this.log.warn(`Browser frame send failed: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
 };
 //#endregion
 export { BrowserAutomation, BrowserSession, BrowserSurface };