@alfe.ai/browser 0.1.0 → 0.2.1

package/dist/index.js

@@ -1,5 +1,134 @@
-import { RemoteFrameType, TurnController, decodeJson, encodeFrame, encodeJsonFrame, encodeScreencastFrame } from "@alfe.ai/remote";
-import puppeteer from "puppeteer-core";
+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
@@ -9,6 +138,14 @@ import puppeteer from "puppeteer-core";
 * new tabs are what gets screencast, not a stale main window.
 */
 const DEFAULT_IDLE_MS = 300 * 1e3;
+/**
+* A page target is worth streaming only once it has a real, navigable http(s)
+* URL. Transient `about:blank` (and `chrome://`, `data:`, blank string) targets
+* are throwaways we must not flip the screencast to.
+*/
+function isNavigablePageUrl(url) {
+	return url.startsWith("http://") || url.startsWith("https://");
+}
 const noopLogger$2 = {
 	info: () => {},
 	warn: () => {},
@@ -21,57 +158,101 @@ 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) => {
-			target.page().then((page) => {
-				if (page) {
-					this.activePage = page;
-					this.log.debug("Active page switched to new target");
-				}
-			}).catch(() => {});
-		});
-		this.browser.on("disconnected", () => {
-			this.browser = null;
-			this.activePage = null;
-		});
+		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(() => {});
+			});
+		} catch (error) {
+			await browser.close().catch(() => void 0);
+			throw error;
+		}
+	}
+	/**
+	* Adopt `page` as the streamed active page iff it has a real navigable
+	* http(s) URL. Returns whether it was adopted. Guards against flipping the
+	* screencast to a transient `about:blank` throwaway target.
+	*/
+	adoptIfNavigable(page) {
+		if (page.isClosed() || !isNavigablePageUrl(page.url())) return false;
+		if (this.activePage === page) return true;
+		this.setActivePage(page);
+		this.log.debug("Active page switched to new target");
+		return true;
 	}
 	/** 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);
 		}
-		return this.activePage;
+		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);
+		};
 	}
 	/** Prevent idle shutdown while a viewer or op is active. */
 	addHold() {
@@ -106,6 +287,8 @@ var BrowserSession = class {
 	}
 	async shutdown() {
 		this.clearIdleTimer();
+		this.generation += 1;
+		this.launching = null;
 		const browser = this.browser;
 		this.browser = null;
 		this.activePage = null;
@@ -113,6 +296,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
@@ -127,6 +344,12 @@ var ScreencastPump = class {
 	running = false;
 	frameSeq = 0;
 	outstanding = null;
+	generation = 0;
+	viewport = {
+		width: 1280,
+		height: 720,
+		dpr: 1
+	};
 	log;
 	quality;
 	ackTimeoutMs;
@@ -135,6 +358,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;
@@ -142,33 +367,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,
@@ -180,11 +432,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) {
@@ -193,9 +453,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);
@@ -223,14 +484,24 @@ const MOUSE_TYPE = {
 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 {
@@ -238,12 +509,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,64 +567,103 @@ function clamp01(n) {
 }
 //#endregion
 //#region src/automation.ts
+const OPERATION_TIMEOUT_MS = 3e4;
 var BrowserAutomation = class {
+	operationTail = Promise.resolve();
 	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;
+	}
+	run(operation) {
+		const result = this.operationTail.catch(() => void 0).then(async () => {
+			await this.turn.acquireAgent();
+			try {
+				return await operation();
+			} finally {
+				this.session.touch();
+			}
+		});
+		this.operationTail = result.then(() => void 0, () => void 0);
+		return result;
 	}
 };
 //#endregion
@@ -388,12 +698,29 @@ var BrowserSurface = class {
 		dpr: 1
 	};
 	handoff = null;
+	controllerSessionId = null;
+	pendingControllerSessionId = null;
+	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();
 		} });
@@ -404,56 +731,87 @@ 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(() => {
+			if (this.viewers.size > 0) this.restartStreaming();
+		});
 	}
 	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));
+				if (this.controllerSessionId !== null || this.pendingControllerSessionId !== null) {
+					this.sendFrameSafe(encodeFrame(RemoteFrameType.TAKEOVER_DENIED, frame.sessionId));
+					break;
+				}
+				this.pendingControllerSessionId = frame.sessionId;
+				this.automation.waitUntilIdle().then(() => {
+					if (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.pendingControllerSessionId === frame.sessionId) 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;
 		}
@@ -461,24 +819,40 @@ var BrowserSurface = class {
 	closeSession(sessionId) {
 		if (!this.viewers.delete(sessionId)) return;
 		this.session.removeHold();
+		if (this.pendingControllerSessionId === sessionId) this.pendingControllerSessionId = null;
+		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();
 		}
 	}
 	/**
-	* Agent tool entry point: hand control to the human and block until they
-	* release it (RELEASE_CONTROL) or `timeoutMs` elapses. Resolves with the
-	* final page URL/title so the agent resumes on the same live page.
+	* Agent tool entry point: PARK the agent and wait for a human to take over
+	* and hand back (RELEASE_CONTROL / viewer teardown after a claim) or for
+	* `timeoutMs` to elapse. Resolves with the final page URL/title so the agent
+	* resumes on the same live page.
+	*
+	* Crucially this does NOT grant the human turn up front. The turn is granted
+	* only when a human ACTUALLY takes control — i.e. when the controlling
+	* (`canControl:true`) viewer sends a `TAKEOVER_REQUEST` frame (see
+	* `handleFrame` → `grantHuman()`). Granting at tool-call time made the session
+	* "human in control" before anyone had claimed, so a read-only viewer's
+	* teardown would fire `releaseToAgent()` and complete the session out from
+	* under the user (mislabeled 409 on the real claim; agent only resuming when
+	* the tab closed).
 	*/
 	async requestHandoff(timeoutMs) {
-		this.turn.grantHuman();
-		this.broadcast(RemoteFrameType.TAKEOVER_GRANTED);
+		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.handoff) this.releaseToAgent();
 		return new Promise((resolve) => {
 			const timer = setTimeout(() => {
 				this.handoff = null;
-				this.turn.releaseHuman();
-				this.broadcast(RemoteFrameType.CONTROL_REVOKED);
+				this.pendingControllerSessionId = null;
+				if (this.turn.humanInControl) {
+					this.turn.releaseHuman();
+					this.controllerSessionId = null;
+					this.broadcast(RemoteFrameType.CONTROL_REVOKED);
+				}
 				this.currentPageInfo().then(({ url, title }) => {
 					resolve({
 						released: false,
@@ -495,12 +869,43 @@ var BrowserSurface = class {
 			};
 		});
 	}
+	/**
+	* Keep the shared Chrome alive across an awaiting-human window. Delegates to
+	* the session's hold counter (which also backs per-viewer holds). Idempotent
+	* and leak-safe when paired with {@link removeHold} in a `finally`.
+	*/
+	addHold() {
+		this.session.addHold();
+	}
+	/** Release a hold taken by {@link addHold}. */
+	removeHold() {
+		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.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.enqueueStreamCleanup();
 		await this.session.shutdown();
 	}
 	releaseToAgent() {
+		this.pendingControllerSessionId = null;
+		this.controllerSessionId = null;
 		this.turn.releaseHuman();
 		const waiter = this.handoff;
 		this.handoff = null;
@@ -516,51 +921,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 {
@@ -569,6 +1005,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 };