@alfe.ai/browser 0.2.1 → 0.3.0

package/README.md

@@ -17,5 +17,13 @@ and human-clicked navigation. The package bounds viewports, screencast frames,
 automation input/results, and keeps replacement Chrome/CDP generations from
 mutating current state.
 
+## Browser integration verification
+
+Run `BROWSER_TEST_EXECUTABLE_PATH=/path/to/chrome pnpm test:integration` from
+this package. This dedicated suite launches a real headless Chrome with a fresh
+temporary profile and local HTTP/WebSocket fixtures. It exercises streamed
+JPEGs, human keyboard/mouse input, login popups, hand-back, and cookie persistence
+after browser restart; it never attaches to an existing browser profile.
+
 Part of [Alfe](https://alfe.ai). See the
 [documentation](https://docs.alfe.ai) for platform setup.

package/dist/index.cjs

@@ -242,6 +242,15 @@ var BrowserSession = class {
 					});
 				}).catch(() => {});
 			});
+			browser.on("targetdestroyed", (target) => {
+				const closedPage = this.activePage;
+				if (this.browser !== browser || !closedPage || target.type() !== puppeteer_core.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 (error) {
 			await browser.close().catch(() => void 0);
 			throw error;
@@ -259,6 +268,27 @@ var BrowserSession = class {
 		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();
@@ -278,6 +308,55 @@ var BrowserSession = class {
 			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);
+		}
+	}
 	/** Prevent idle shutdown while a viewer or op is active. */
 	addHold() {
 		this.holds += 1;
@@ -505,6 +584,43 @@ 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;
@@ -569,19 +685,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(() => {});
 	}
 };
@@ -594,6 +709,7 @@ function clamp01(n) {
 const OPERATION_TIMEOUT_MS = 3e4;
 var BrowserAutomation = class {
 	operationTail = Promise.resolve();
+	stopping = new AbortController();
 	constructor(session, turn, isNavigationAllowed) {
 		this.session = session;
 		this.turn = turn;
@@ -677,13 +793,38 @@ var BrowserAutomation = class {
 	async waitUntilIdle() {
 		await this.operationTail;
 	}
-	run(operation) {
+	/** 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 () => {
-			await this.turn.acquireAgent();
+			signal.throwIfAborted();
+			this.session.addHold();
 			try {
-				return await operation();
+				await this.turn.acquireAgent(signal);
+				signal.throwIfAborted();
+				const result = await operation(signal);
+				signal.throwIfAborted();
+				return result;
 			} finally {
-				this.session.touch();
+				this.session.removeHold();
 			}
 		});
 		this.operationTail = result.then(() => void 0, () => void 0);
@@ -724,13 +865,13 @@ var BrowserSurface = class {
 	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;
 		const navigationPolicy = options.isNavigationAllowed ?? ((url) => {
@@ -756,8 +897,11 @@ var BrowserSurface = class {
 		});
 		this.injector = new InputInjector(this.viewport);
 		this.automation = new BrowserAutomation(this.session, this.turn, navigationPolicy);
-		this.removePageListener = this.session.onActivePageChange(() => {
-			if (this.viewers.size > 0) this.restartStreaming();
+		this.removePageListener = this.session.onActivePageChange(async () => {
+			if (this.viewers.size > 0) {
+				await this.restartStreaming();
+				this.broadcastState();
+			}
 		});
 	}
 	async openSession(sessionId, open) {
@@ -815,25 +959,28 @@ var BrowserSurface = class {
 					if (input) this.injector.key(input);
 				}
 				break;
-			case _alfe_ai_remote.RemoteFrameType.TAKEOVER_REQUEST:
+			case _alfe_ai_remote.RemoteFrameType.TAKEOVER_REQUEST: {
 				if (this.controllerSessionId !== null || this.pendingControllerSessionId !== null) {
 					this.sendFrameSafe((0, _alfe_ai_remote.encodeFrame)(_alfe_ai_remote.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;
+				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(_alfe_ai_remote.RemoteFrameType.TAKEOVER_GRANTED);
 					} else this.sendFrameSafe((0, _alfe_ai_remote.encodeFrame)(_alfe_ai_remote.RemoteFrameType.TAKEOVER_DENIED, frame.sessionId));
 				}).catch((error) => {
-					if (this.pendingControllerSessionId === frame.sessionId) this.pendingControllerSessionId = null;
+					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((0, _alfe_ai_remote.encodeFrame)(_alfe_ai_remote.RemoteFrameType.TAKEOVER_DENIED, frame.sessionId));
 				});
 				break;
+			}
 			case _alfe_ai_remote.RemoteFrameType.RELEASE_CONTROL:
 				if (frame.sessionId === this.controllerSessionId) this.releaseToAgent();
 				break;
@@ -843,7 +990,10 @@ var BrowserSurface = class {
 	closeSession(sessionId) {
 		if (!this.viewers.delete(sessionId)) return;
 		this.session.removeHold();
-		if (this.pendingControllerSessionId === sessionId) this.pendingControllerSessionId = null;
+		if (this.pendingControllerSessionId === sessionId) {
+			this.pendingControllerSessionId = null;
+			this.claimGeneration += 1;
+		}
 		if (this.controllerSessionId === sessionId) this.releaseToAgent();
 		if (this.viewers.size === 0) {
 			this.streamGeneration += 1;
@@ -865,20 +1015,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(_alfe_ai_remote.RemoteFrameType.CONTROL_REVOKED);
 				}
 				this.currentPageInfo().then(({ url, title }) => {
-					resolve({
+					settle({
 						released: false,
 						timedOut: true,
 						url,
@@ -887,10 +1045,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(_alfe_ai_remote.RemoteFrameType.CONTROL_REVOKED);
+				}
+				reject(/* @__PURE__ */ new Error("Browser handoff cancelled"));
+			};
+			this.handoff = waiter;
+			signal?.addEventListener("abort", onAbort, { once: true });
+			if (signal?.aborted) onAbort();
 		});
 	}
 	/**
@@ -911,6 +1086,7 @@ var BrowserSurface = class {
 		this.removePageListener();
 		this.streamGeneration += 1;
 		this.pendingControllerSessionId = null;
+		this.claimGeneration += 1;
 		this.controllerSessionId = null;
 		const waiter = this.handoff;
 		this.handoff = null;
@@ -924,11 +1100,13 @@ var BrowserSurface = class {
 			});
 		}
 		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;

package/dist/index.d.cts

@@ -96,9 +96,10 @@ declare class TurnController {
   /**
    * Resolve once the agent is (again) allowed to drive. Resolves immediately if
    * the agent already holds the token; otherwise parks until `releaseHuman()`.
-   * Every automation op awaits this before touching the page.
+   * Every automation op awaits this before touching the page. Cancellation
+   * removes only this waiter and never changes the current human owner.
    */
-  acquireAgent(): Promise<void>;
+  acquireAgent(signal?: AbortSignal): Promise<void>;
   /**
    * Grant control to a human. Succeeds unless a human already holds it (single
    * controller). "Human request always wins over the agent" — the agent parks
@@ -112,6 +113,18 @@ declare class TurnController {
 //#endregion
 //#endregion
 //#region src/types.d.ts
+/** Private local capability for a trusted adapter, never a tool result. */
+interface BrowserOperationContext {
+  /** Loopback Chrome endpoint. Do not log, persist, or expose to a viewer/model. */
+  browserWSEndpoint: string;
+  /** The exact active page's CDP target; never choose the first context/page. */
+  targetId: string;
+  /** On abort, stop and await all external work before returning. */
+  signal: AbortSignal;
+}
+interface BrowserOperationOptions {
+  signal?: AbortSignal;
+}
 interface BrowserSessionOptions {
   /** Path to the Chrome/Chromium binary (from the headless-browser integration). */
   executablePath: string;
@@ -154,9 +167,16 @@ declare class BrowserSession {
    * screencast to a transient `about:blank` throwaway target.
    */
   private adoptIfNavigable;
+  /** 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. */
+  private restoreAfterClose;
   /** The current active page, launching Chrome first if needed. */
   getActivePage(): Promise<Page>;
   onActivePageChange(listener: (page: Page) => void | Promise<void>): () => void;
+  /** Internal to the serialized automation turn. The caller holds Chrome until
+   * the adapter has disconnected its client/awaited its child process exit. */
+  withCdpTarget<T>(operation: (context: BrowserOperationContext) => Promise<T>, signal: AbortSignal): Promise<T>;
   /** Prevent idle shutdown while a viewer or op is active. */
   addHold(): void;
   /** Release a hold; arm idle shutdown when the last one is released. */
@@ -181,6 +201,7 @@ declare class BrowserAutomation {
   private readonly turn;
   private readonly isNavigationAllowed;
   private operationTail;
+  private readonly stopping;
   constructor(session: BrowserSession, turn: TurnController, isNavigationAllowed: (url: string) => boolean);
   navigate(url: string): Promise<NavigateResult>;
   click(selector: string): Promise<void>;
@@ -197,6 +218,14 @@ declare class BrowserAutomation {
   evaluate(expression: string): Promise<unknown>;
   /** Wait until all agent operations that were already queued have settled. */
   waitUntilIdle(): Promise<void>;
+  /** 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<T>(operation: (context: BrowserOperationContext) => Promise<T>, options?: BrowserOperationOptions): Promise<T>;
+  /** Insert the claim at a precise queue position; later automation parks. */
+  yieldToHuman(grant: () => void): Promise<void>;
+  /** Abort first, then await callback cleanup before the owner closes Chrome. */
+  shutdown(): Promise<void>;
   private run;
 }
 //#endregion
@@ -208,7 +237,6 @@ interface HandoffResult {
   title: string;
 }
 declare class BrowserSurface implements SurfaceHandler {
-  private readonly options;
   private readonly sendFrame;
   readonly surface: "browser";
   private readonly session;
@@ -221,6 +249,7 @@ declare class BrowserSurface implements SurfaceHandler {
   private handoff;
   private controllerSessionId;
   private pendingControllerSessionId;
+  private claimGeneration;
   private streamGeneration;
   private streamQueue;
   private closed;
@@ -245,7 +274,7 @@ declare class BrowserSurface implements SurfaceHandler {
    * under the user (mislabeled 409 on the real claim; agent only resuming when
    * the tab closed).
    */
-  requestHandoff(timeoutMs: number): Promise<HandoffResult>;
+  requestHandoff(timeoutMs: number, signal?: AbortSignal): Promise<HandoffResult>;
   /**
    * Keep the shared Chrome alive across an awaiting-human window. Delegates to
    * the session's hold counter (which also backs per-viewer holds). Idempotent
@@ -268,4 +297,4 @@ declare class BrowserSurface implements SurfaceHandler {
   private sendFrameSafe;
 }
 //#endregion
-export { BrowserAutomation, BrowserSession, type BrowserSessionOptions, BrowserSurface, type BrowserSurfaceOptions, type HandoffResult, type Logger, type NavigateResult };
+export { BrowserAutomation, type BrowserOperationContext, type BrowserOperationOptions, BrowserSession, type BrowserSessionOptions, BrowserSurface, type BrowserSurfaceOptions, type HandoffResult, type Logger, type NavigateResult };

package/dist/index.d.ts

@@ -96,9 +96,10 @@ declare class TurnController {
   /**
    * Resolve once the agent is (again) allowed to drive. Resolves immediately if
    * the agent already holds the token; otherwise parks until `releaseHuman()`.
-   * Every automation op awaits this before touching the page.
+   * Every automation op awaits this before touching the page. Cancellation
+   * removes only this waiter and never changes the current human owner.
    */
-  acquireAgent(): Promise<void>;
+  acquireAgent(signal?: AbortSignal): Promise<void>;
   /**
    * Grant control to a human. Succeeds unless a human already holds it (single
    * controller). "Human request always wins over the agent" — the agent parks
@@ -112,6 +113,18 @@ declare class TurnController {
 //#endregion
 //#endregion
 //#region src/types.d.ts
+/** Private local capability for a trusted adapter, never a tool result. */
+interface BrowserOperationContext {
+  /** Loopback Chrome endpoint. Do not log, persist, or expose to a viewer/model. */
+  browserWSEndpoint: string;
+  /** The exact active page's CDP target; never choose the first context/page. */
+  targetId: string;
+  /** On abort, stop and await all external work before returning. */
+  signal: AbortSignal;
+}
+interface BrowserOperationOptions {
+  signal?: AbortSignal;
+}
 interface BrowserSessionOptions {
   /** Path to the Chrome/Chromium binary (from the headless-browser integration). */
   executablePath: string;
@@ -154,9 +167,16 @@ declare class BrowserSession {
    * screencast to a transient `about:blank` throwaway target.
    */
   private adoptIfNavigable;
+  /** 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. */
+  private restoreAfterClose;
   /** The current active page, launching Chrome first if needed. */
   getActivePage(): Promise<Page>;
   onActivePageChange(listener: (page: Page) => void | Promise<void>): () => void;
+  /** Internal to the serialized automation turn. The caller holds Chrome until
+   * the adapter has disconnected its client/awaited its child process exit. */
+  withCdpTarget<T>(operation: (context: BrowserOperationContext) => Promise<T>, signal: AbortSignal): Promise<T>;
   /** Prevent idle shutdown while a viewer or op is active. */
   addHold(): void;
   /** Release a hold; arm idle shutdown when the last one is released. */
@@ -181,6 +201,7 @@ declare class BrowserAutomation {
   private readonly turn;
   private readonly isNavigationAllowed;
   private operationTail;
+  private readonly stopping;
   constructor(session: BrowserSession, turn: TurnController, isNavigationAllowed: (url: string) => boolean);
   navigate(url: string): Promise<NavigateResult>;
   click(selector: string): Promise<void>;
@@ -197,6 +218,14 @@ declare class BrowserAutomation {
   evaluate(expression: string): Promise<unknown>;
   /** Wait until all agent operations that were already queued have settled. */
   waitUntilIdle(): Promise<void>;
+  /** 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<T>(operation: (context: BrowserOperationContext) => Promise<T>, options?: BrowserOperationOptions): Promise<T>;
+  /** Insert the claim at a precise queue position; later automation parks. */
+  yieldToHuman(grant: () => void): Promise<void>;
+  /** Abort first, then await callback cleanup before the owner closes Chrome. */
+  shutdown(): Promise<void>;
   private run;
 }
 //#endregion
@@ -208,7 +237,6 @@ interface HandoffResult {
   title: string;
 }
 declare class BrowserSurface implements SurfaceHandler {
-  private readonly options;
   private readonly sendFrame;
   readonly surface: "browser";
   private readonly session;
@@ -221,6 +249,7 @@ declare class BrowserSurface implements SurfaceHandler {
   private handoff;
   private controllerSessionId;
   private pendingControllerSessionId;
+  private claimGeneration;
   private streamGeneration;
   private streamQueue;
   private closed;
@@ -245,7 +274,7 @@ declare class BrowserSurface implements SurfaceHandler {
    * under the user (mislabeled 409 on the real claim; agent only resuming when
    * the tab closed).
    */
-  requestHandoff(timeoutMs: number): Promise<HandoffResult>;
+  requestHandoff(timeoutMs: number, signal?: AbortSignal): Promise<HandoffResult>;
   /**
    * Keep the shared Chrome alive across an awaiting-human window. Delegates to
    * the session's hold counter (which also backs per-viewer holds). Idempotent
@@ -268,4 +297,4 @@ declare class BrowserSurface implements SurfaceHandler {
   private sendFrameSafe;
 }
 //#endregion
-export { BrowserAutomation, BrowserSession, type BrowserSessionOptions, BrowserSurface, type BrowserSurfaceOptions, type HandoffResult, type Logger, type NavigateResult };
+export { BrowserAutomation, type BrowserOperationContext, type BrowserOperationOptions, BrowserSession, type BrowserSessionOptions, BrowserSurface, type BrowserSurfaceOptions, type HandoffResult, type Logger, type NavigateResult };

package/dist/index.js

@@ -218,6 +218,15 @@ var BrowserSession = class {
 					});
 				}).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 (error) {
 			await browser.close().catch(() => void 0);
 			throw error;
@@ -235,6 +244,27 @@ var BrowserSession = class {
 		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();
@@ -254,6 +284,55 @@ var BrowserSession = class {
 			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);
+		}
+	}
 	/** Prevent idle shutdown while a viewer or op is active. */
 	addHold() {
 		this.holds += 1;
@@ -481,6 +560,43 @@ 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;
@@ -545,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(() => {});
 	}
 };
@@ -570,6 +685,7 @@ function clamp01(n) {
 const OPERATION_TIMEOUT_MS = 3e4;
 var BrowserAutomation = class {
 	operationTail = Promise.resolve();
+	stopping = new AbortController();
 	constructor(session, turn, isNavigationAllowed) {
 		this.session = session;
 		this.turn = turn;
@@ -653,13 +769,38 @@ var BrowserAutomation = class {
 	async waitUntilIdle() {
 		await this.operationTail;
 	}
-	run(operation) {
+	/** 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 () => {
-			await this.turn.acquireAgent();
+			signal.throwIfAborted();
+			this.session.addHold();
 			try {
-				return await operation();
+				await this.turn.acquireAgent(signal);
+				signal.throwIfAborted();
+				const result = await operation(signal);
+				signal.throwIfAborted();
+				return result;
 			} finally {
-				this.session.touch();
+				this.session.removeHold();
 			}
 		});
 		this.operationTail = result.then(() => void 0, () => void 0);
@@ -700,13 +841,13 @@ var BrowserSurface = class {
 	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;
 		const navigationPolicy = options.isNavigationAllowed ?? ((url) => {
@@ -732,8 +873,11 @@ var BrowserSurface = class {
 		});
 		this.injector = new InputInjector(this.viewport);
 		this.automation = new BrowserAutomation(this.session, this.turn, navigationPolicy);
-		this.removePageListener = this.session.onActivePageChange(() => {
-			if (this.viewers.size > 0) this.restartStreaming();
+		this.removePageListener = this.session.onActivePageChange(async () => {
+			if (this.viewers.size > 0) {
+				await this.restartStreaming();
+				this.broadcastState();
+			}
 		});
 	}
 	async openSession(sessionId, open) {
@@ -791,25 +935,28 @@ var BrowserSurface = class {
 					if (input) this.injector.key(input);
 				}
 				break;
-			case RemoteFrameType.TAKEOVER_REQUEST:
+			case RemoteFrameType.TAKEOVER_REQUEST: {
 				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;
+				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.pendingControllerSessionId === frame.sessionId) this.pendingControllerSessionId = null;
+					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:
 				if (frame.sessionId === this.controllerSessionId) this.releaseToAgent();
 				break;
@@ -819,7 +966,10 @@ var BrowserSurface = class {
 	closeSession(sessionId) {
 		if (!this.viewers.delete(sessionId)) return;
 		this.session.removeHold();
-		if (this.pendingControllerSessionId === sessionId) this.pendingControllerSessionId = null;
+		if (this.pendingControllerSessionId === sessionId) {
+			this.pendingControllerSessionId = null;
+			this.claimGeneration += 1;
+		}
 		if (this.controllerSessionId === sessionId) this.releaseToAgent();
 		if (this.viewers.size === 0) {
 			this.streamGeneration += 1;
@@ -841,20 +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,
@@ -863,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();
 		});
 	}
 	/**
@@ -887,6 +1062,7 @@ var BrowserSurface = class {
 		this.removePageListener();
 		this.streamGeneration += 1;
 		this.pendingControllerSessionId = null;
+		this.claimGeneration += 1;
 		this.controllerSessionId = null;
 		const waiter = this.handoff;
 		this.handoff = null;
@@ -900,11 +1076,13 @@ var BrowserSurface = class {
 			});
 		}
 		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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfe.ai/browser",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "CDP-driven browser surface for the Alfe interactive remote-control relay — one shared headless Chrome for agent automation + human co-browse takeover",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,7 +17,7 @@
   ],
   "dependencies": {
     "puppeteer-core": "^24.0.0",
-    "@alfe.ai/remote": "^0.1.1"
+    "@alfe.ai/remote": "^0.2.0"
   },
   "license": "UNLICENSED",
   "homepage": "https://alfe.ai",
@@ -32,6 +32,7 @@
     "build": "tsdown",
     "dev": "tsdown --watch",
     "test": "vitest run --passWithNoTests",
+    "test:integration": "tsc --noEmit -p tsconfig.integration.json && vitest run --config test/vitest.config.ts",
     "typecheck": "tsc --noEmit",
     "lint": "eslint ."
   }