@apifuse/provider-sdk 2.1.0-beta.1 → 2.1.0-beta.10

package/src/runtime/browser.ts

@@ -1,11 +1,16 @@
 import { createRequire } from "node:module";
-import type { LaunchOptions, Page } from "playwright";
+import type { Frame, LaunchOptions, Locator, Page } from "playwright";
 
 import { ProviderError } from "../errors";
 import type {
+	BrowserChallengeRequest,
+	BrowserChallengeResult,
 	BrowserClient as BrowserClientContract,
 	BrowserEngine,
+	BrowserFrame,
+	BrowserLocator,
 	BrowserOptions,
+	BrowserPage,
 } from "../types";
 
 const require = createRequire(import.meta.url);
@@ -13,15 +18,25 @@ const DEFAULT_WAIT_TIMEOUT_MS = 30_000;
 const SELECTOR_POLL_INTERVAL_MS = 100;
 
 type PlaywrightModule = typeof import("playwright");
-type PlaywrightStealthModule = {
-	stealth(page: unknown): Promise<void>;
+type PlaywrightExtraModule = {
+	chromium: PlaywrightModule["chromium"] & { use(plugin: unknown): unknown };
 };
 
+type StealthPluginFactory = (options?: {
+	enabledEvasions?: Set<string>;
+}) => unknown;
+
 type PoolAcquireResponse = {
+	browserContextId?: string;
 	pageId: string;
 	wsEndpoint: string;
 };
 
+type PoolReleaseRequest = {
+	browserContextId?: string;
+	pageId: string;
+};
+
 type JsonRpcId = number;
 
 type JsonRpcError = {
@@ -37,35 +52,37 @@ type JsonRpcMessage = {
 	result?: Record<string, unknown>;
 };
 
-type BrowserPageContract = {
-	close(): Promise<void>;
-	content(): Promise<string>;
-	evaluate<T>(fn: string | (() => T)): Promise<T>;
-	fill?(selector: string, text: string): Promise<void>;
-	goto(url: string): Promise<void>;
-	pageId?: string;
-	screenshot(options?: { fullPage?: boolean }): Promise<Buffer>;
-	click(selector: string): Promise<void>;
-	type(selector: string, text: string): Promise<void>;
-	waitForSelector(
-		selector: string,
-		options?: { timeout?: number },
-	): Promise<void>;
+type CdpFrameTreeNode = {
+	childFrames?: CdpFrameTreeNode[];
+	frame: {
+		id: string;
+		name?: string;
+		parentId?: string;
+		url?: string;
+	};
 };
 
+type BrowserPageContract = BrowserPage;
+
 export type BrowserClientOptions = BrowserOptions & {
+	allowedHosts?: string[];
 	cdpUrl?: string;
 	executablePath?: string;
 	extraArgs?: string[];
 };
 
-type SupportedBrowserClient = BrowserClientContract & {
+type SupportedBrowserClient = {
+	readonly engine: BrowserEngine;
 	close(): Promise<void>;
 	newPage(): Promise<BrowserPageContract>;
+	rawPage(): Promise<BrowserPageContract>;
+	withIsolatedContext<T>(
+		handler: (page: BrowserPageContract) => Promise<T>,
+	): Promise<T>;
 };
 
 function getDefaultCdpPoolUrl(env = process.env): string | undefined {
-	return env.CDP_POOL_URL ?? env.APIFUSE_CDP_POOL_URL;
+	return env.APIFUSE__CDP_POOL__URL;
 }
 
 async function importOptionalModule<T extends object>(
@@ -89,11 +106,16 @@ function unwrapModuleDefault<T extends object>(module: T): T {
 }
 
 function isModuleNotFoundError(error: unknown): boolean {
+	if (!(error instanceof Error)) {
+		return false;
+	}
+
+	const code = "code" in error ? error.code : undefined;
 	return (
-		error instanceof Error &&
-		("code" in error
-			? (error as Error & { code?: string }).code === "MODULE_NOT_FOUND"
-			: error.message.includes("Cannot find module"))
+		code === "MODULE_NOT_FOUND" ||
+		code === "ERR_MODULE_NOT_FOUND" ||
+		error.message.includes("Cannot find module") ||
+		error.message.includes("Cannot find package")
 	);
 }
 
@@ -118,9 +140,71 @@ function toLaunchOptions(options: BrowserClientOptions): LaunchOptions {
 	};
 }
 
+class PlaywrightBrowserLocator implements BrowserLocator {
+	constructor(private readonly locator: Locator) {}
+
+	async click(): Promise<void> {
+		await this.locator.click();
+	}
+
+	async fill(text: string): Promise<void> {
+		await this.locator.fill(text);
+	}
+
+	async textContent(): Promise<string | null> {
+		return await this.locator.textContent();
+	}
+
+	async waitFor(options?: { timeout?: number }): Promise<void> {
+		await this.locator.waitFor(options);
+	}
+}
+
+class PlaywrightBrowserFrame implements BrowserFrame {
+	constructor(private readonly frame: Frame) {}
+
+	get id(): string {
+		return this.frame.name() || this.frame.url();
+	}
+
+	get name(): string | undefined {
+		const name = this.frame.name();
+		return name.length > 0 ? name : undefined;
+	}
+
+	get parentId(): string | undefined {
+		const parent = this.frame.parentFrame();
+		return parent ? parent.name() || parent.url() : undefined;
+	}
+
+	async url(): Promise<string> {
+		return this.frame.url();
+	}
+
+	async title(): Promise<string> {
+		return await this.frame.evaluate("document.title");
+	}
+
+	async content(): Promise<string> {
+		return await this.frame.content();
+	}
+
+	async evaluate<T>(fn: string | (() => T)): Promise<T> {
+		if (typeof fn === "string") {
+			return await this.frame.evaluate(fn);
+		}
+
+		return await this.frame.evaluate(fn);
+	}
+
+	locator(selector: string): BrowserLocator {
+		return new PlaywrightBrowserLocator(this.frame.locator(selector));
+	}
+}
+
 async function loadPlaywright(): Promise<PlaywrightModule> {
 	try {
-		require("playwright");
+		await importOptionalModule<PlaywrightModule>("playwright");
 	} catch (error) {
 		if (isModuleNotFoundError(error)) {
 			throw new ProviderError("Playwright is not installed", {
@@ -148,16 +232,31 @@ async function loadPlaywright(): Promise<PlaywrightModule> {
 	}
 }
 
-async function loadPlaywrightStealth(): Promise<PlaywrightStealthModule> {
+const playwrightExtraStealthLaunchers = new WeakSet<object>();
+
+async function loadPlaywrightExtra(): Promise<PlaywrightExtraModule> {
+	try {
+		require("playwright");
+	} catch (error) {
+		if (isModuleNotFoundError(error)) {
+			throw new ProviderError("Playwright is not installed", {
+				cause: error instanceof Error ? error : undefined,
+				fix: "Run: bun add playwright",
+			});
+		}
+
+		throw error;
+	}
+
 	try {
 		return unwrapModuleDefault(
-			await importOptionalModule<PlaywrightStealthModule>("playwright-stealth"),
+			await importOptionalModule<PlaywrightExtraModule>("playwright-extra"),
 		);
 	} catch (error) {
 		if (isModuleNotFoundError(error)) {
-			throw new ProviderError("playwright-stealth is not installed", {
+			throw new ProviderError("playwright-extra is not installed", {
 				cause: error instanceof Error ? error : undefined,
-				fix: "Run: bun add playwright-stealth",
+				fix: "Run: bun add playwright-extra puppeteer-extra-plugin-stealth",
 			});
 		}
 
@@ -165,6 +264,45 @@ async function loadPlaywrightStealth(): Promise<PlaywrightStealthModule> {
 	}
 }
 
+async function loadStealthPluginFactory(): Promise<StealthPluginFactory> {
+	try {
+		return unwrapModuleDefault(
+			await importOptionalModule<StealthPluginFactory>(
+				"puppeteer-extra-plugin-stealth",
+			),
+		);
+	} catch (error) {
+		if (isModuleNotFoundError(error)) {
+			throw new ProviderError(
+				"puppeteer-extra-plugin-stealth is not installed",
+				{
+					cause: error instanceof Error ? error : undefined,
+					fix: "Run: bun add playwright-extra puppeteer-extra-plugin-stealth",
+				},
+			);
+		}
+
+		throw error;
+	}
+}
+
+async function loadChromiumLauncher(
+	options: BrowserClientOptions,
+): Promise<PlaywrightModule["chromium"]> {
+	if (!(options.stealth ?? true)) {
+		return (await loadPlaywright()).chromium;
+	}
+
+	const playwrightExtra = await loadPlaywrightExtra();
+	if (!playwrightExtraStealthLaunchers.has(playwrightExtra.chromium)) {
+		const createStealthPlugin = await loadStealthPluginFactory();
+		playwrightExtra.chromium.use(createStealthPlugin());
+		playwrightExtraStealthLaunchers.add(playwrightExtra.chromium);
+	}
+
+	return playwrightExtra.chromium;
+}
+
 async function loadNodriver(): Promise<void> {
 	try {
 		await importOptionalModule("nodriver");
@@ -196,6 +334,7 @@ async function loadSeleniumBase(): Promise<void> {
 }
 
 class PlaywrightBrowserPage implements BrowserPageContract {
+	readonly id = "main";
 	readonly pageId?: string;
 
 	constructor(private readonly page: Page) {}
@@ -232,6 +371,22 @@ class PlaywrightBrowserPage implements BrowserPageContract {
 		await this.page.fill(selector, text);
 	}
 
+	async frames(): Promise<BrowserFrame[]> {
+		return this.page.frames().map((frame) => new PlaywrightBrowserFrame(frame));
+	}
+
+	locator(selector: string): BrowserLocator {
+		return new PlaywrightBrowserLocator(this.page.locator(selector));
+	}
+
+	async title(): Promise<string> {
+		return await this.page.title();
+	}
+
+	async url(): Promise<string> {
+		return this.page.url();
+	}
+
 	async content(): Promise<string> {
 		return await this.page.content();
 	}
@@ -256,10 +411,8 @@ class PlaywrightBrowserClient implements SupportedBrowserClient {
 			return this.browser;
 		}
 
-		const playwright = await loadPlaywright();
-		this.browser = await playwright.chromium.launch(
-			toLaunchOptions(this.options),
-		);
+		const chromium = await loadChromiumLauncher(this.options);
+		this.browser = await chromium.launch(toLaunchOptions(this.options));
 		return this.browser;
 	}
 
@@ -267,14 +420,35 @@ class PlaywrightBrowserClient implements SupportedBrowserClient {
 		const browser = await this.ensureBrowser();
 		const page = await browser.newPage();
 
-		if (this.options.stealth ?? true) {
-			const { stealth } = await loadPlaywrightStealth();
-			await stealth(page);
-		}
-
 		return new PlaywrightBrowserPage(page);
 	}
 
+	async rawPage(): Promise<BrowserPageContract> {
+		throw new ProviderError("ctx.browser.rawPage() requires a CDP pool", {
+			code: "BROWSER_RUNTIME_UNSUPPORTED",
+			fix: "Set APIFUSE__CDP_POOL__URL and use the SDK CDP pool-backed browser runtime. Local Chromium launch is not allowed for rawPage().",
+		});
+	}
+
+	async withIsolatedContext<T>(
+		handler: (page: BrowserPageContract) => Promise<T>,
+	): Promise<T> {
+		const browser = await this.ensureBrowser();
+		const context = await browser.newContext();
+		const page = await context.newPage();
+		const browserPage = new PlaywrightBrowserPage(page);
+
+		try {
+			return await handler(browserPage);
+		} finally {
+			try {
+				await browserPage.close();
+			} finally {
+				await context.close();
+			}
+		}
+	}
+
 	async close(): Promise<void> {
 		const browser = this.browser;
 		this.browser = null;
@@ -287,8 +461,25 @@ class PlaywrightBrowserClient implements SupportedBrowserClient {
 	}
 }
 
+function normalizeWebSocketEndpoint(endpoint: string): string {
+	const url = new URL(endpoint);
+	if (url.protocol === "http:") {
+		url.protocol = "ws:";
+		return url.toString();
+	}
+	if (url.protocol === "https:") {
+		url.protocol = "wss:";
+		return url.toString();
+	}
+	if (url.protocol === "ws:" || url.protocol === "wss:") {
+		return endpoint;
+	}
+	throw new Error(`Unsupported WebSocket endpoint protocol: ${url.protocol}`);
+}
+
 class JsonRpcWebSocketClient {
 	private nextId = 1;
+	private readonly endpoint: string;
 	private readonly listeners = new Map<
 		string,
 		Set<(params: unknown) => void>
@@ -303,7 +494,9 @@ class JsonRpcWebSocketClient {
 	private socket?: WebSocket;
 	private socketPromise?: Promise<WebSocket>;
 
-	constructor(private readonly endpoint: string) {}
+	constructor(endpoint: string) {
+		this.endpoint = normalizeWebSocketEndpoint(endpoint);
+	}
 
 	on(method: string, listener: (params: unknown) => void): () => void {
 		const listeners = this.listeners.get(method) ?? new Set();
@@ -426,16 +619,233 @@ class JsonRpcWebSocketClient {
 	}
 }
 
+function flattenCdpFrameTree(
+	node: CdpFrameTreeNode | undefined,
+	out: CdpFrameTreeNode["frame"][] = [],
+): CdpFrameTreeNode["frame"][] {
+	if (!node) {
+		return out;
+	}
+
+	out.push(node.frame);
+	for (const child of node.childFrames ?? []) {
+		flattenCdpFrameTree(child, out);
+	}
+
+	return out;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function parsePoolAcquireResponse(value: unknown): PoolAcquireResponse {
+	if (
+		!isRecord(value) ||
+		typeof value.pageId !== "string" ||
+		typeof value.wsEndpoint !== "string"
+	) {
+		throw new ProviderError("CDP Pool returned an invalid acquire response", {
+			code: "BROWSER_RUNTIME_UNSUPPORTED",
+		});
+	}
+
+	if (
+		value.browserContextId !== undefined &&
+		typeof value.browserContextId !== "string"
+	) {
+		throw new ProviderError("CDP Pool returned an invalid acquire response", {
+			code: "BROWSER_RUNTIME_UNSUPPORTED",
+		});
+	}
+
+	return {
+		...(value.browserContextId
+			? { browserContextId: value.browserContextId }
+			: {}),
+		pageId: value.pageId,
+		wsEndpoint: value.wsEndpoint,
+	};
+}
+
+function parseCdpFrameTreeNode(value: unknown): CdpFrameTreeNode | undefined {
+	if (!isRecord(value) || !isRecord(value.frame)) {
+		return undefined;
+	}
+
+	const frameId = value.frame.id;
+	if (typeof frameId !== "string") {
+		return undefined;
+	}
+
+	const childFrames = Array.isArray(value.childFrames)
+		? value.childFrames
+				.map(parseCdpFrameTreeNode)
+				.filter((child): child is CdpFrameTreeNode => child !== undefined)
+		: undefined;
+
+	return {
+		frame: {
+			id: frameId,
+			name: typeof value.frame.name === "string" ? value.frame.name : undefined,
+			parentId:
+				typeof value.frame.parentId === "string"
+					? value.frame.parentId
+					: undefined,
+			url: typeof value.frame.url === "string" ? value.frame.url : undefined,
+		},
+		...(childFrames ? { childFrames } : {}),
+	};
+}
+
+function getCdpExecutionContext(params: unknown): {
+	frameId?: string;
+	id?: number;
+} {
+	if (!isRecord(params) || !isRecord(params.context)) {
+		return {};
+	}
+
+	const contextId = params.context.id;
+	const auxData = params.context.auxData;
+	return {
+		frameId:
+			isRecord(auxData) && typeof auxData.frameId === "string"
+				? auxData.frameId
+				: undefined,
+		id: typeof contextId === "number" ? contextId : undefined,
+	};
+}
+
+class CdpBrowserLocator implements BrowserLocator {
+	constructor(
+		private readonly frame: {
+			evaluate<T>(fn: string | (() => T)): Promise<T>;
+			waitForSelector?(
+				selector: string,
+				options?: { timeout?: number },
+			): Promise<void>;
+		},
+		private readonly selector: string,
+	) {}
+
+	async click(): Promise<void> {
+		await this.waitFor();
+		await this.frame.evaluate(
+			`(() => {
+				const element = document.querySelector(${JSON.stringify(this.selector)});
+				if (!(element instanceof HTMLElement)) {
+					throw new Error(${JSON.stringify(`Selector not found: ${this.selector}`)});
+				}
+				element.click();
+			})()`,
+		);
+	}
+
+	async fill(text: string): Promise<void> {
+		await this.waitFor();
+		await this.frame.evaluate(
+			`(() => {
+				const element = document.querySelector(${JSON.stringify(this.selector)});
+				if (!(element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement)) {
+					throw new Error(${JSON.stringify(`Unsupported input target: ${this.selector}`)});
+				}
+				element.focus();
+				element.value = ${JSON.stringify(text)};
+				element.dispatchEvent(new Event("input", { bubbles: true }));
+				element.dispatchEvent(new Event("change", { bubbles: true }));
+			})()`,
+		);
+	}
+
+	async textContent(): Promise<string | null> {
+		return await this.frame.evaluate<string | null>(
+			`document.querySelector(${JSON.stringify(this.selector)})?.textContent ?? null`,
+		);
+	}
+
+	async waitFor(options?: { timeout?: number }): Promise<void> {
+		if (this.frame.waitForSelector) {
+			await this.frame.waitForSelector(this.selector, options);
+			return;
+		}
+
+		const timeout = options?.timeout ?? DEFAULT_WAIT_TIMEOUT_MS;
+		const deadline = Date.now() + timeout;
+		while (Date.now() < deadline) {
+			const exists = await this.frame.evaluate<boolean>(
+				`Boolean(document.querySelector(${JSON.stringify(this.selector)}))`,
+			);
+			if (exists) {
+				return;
+			}
+			await delay(SELECTOR_POLL_INTERVAL_MS);
+		}
+
+		throw new Error(`Timed out waiting for selector: ${this.selector}`);
+	}
+}
+
+class CdpBrowserFrame implements BrowserFrame {
+	constructor(
+		readonly id: string,
+		private readonly page: CdpPoolBrowserPage,
+		private readonly initialUrl = "",
+		readonly name?: string,
+		readonly parentId?: string,
+	) {}
+
+	async url(): Promise<string> {
+		const evaluatedUrl = await this.evaluate<string | undefined>(
+			"window.location.href",
+		);
+		return evaluatedUrl || this.initialUrl;
+	}
+
+	async title(): Promise<string> {
+		return await this.evaluate<string>("document.title");
+	}
+
+	async content(): Promise<string> {
+		return await this.evaluate<string>("document.documentElement.outerHTML");
+	}
+
+	async evaluate<T>(fn: string | (() => T)): Promise<T> {
+		return await this.page.evaluateInFrame<T>(this.id, fn);
+	}
+
+	locator(selector: string): BrowserLocator {
+		return new CdpBrowserLocator(this, selector);
+	}
+
+	async waitForSelector(
+		selector: string,
+		options?: { timeout?: number },
+	): Promise<void> {
+		await this.page.waitForSelectorInFrame(this.id, selector, options);
+	}
+
+	fallbackUrl(): string {
+		return this.initialUrl;
+	}
+}
+
 class CdpPoolBrowserPage implements BrowserPageContract {
 	private closed = false;
 	private initialized = false;
+	private readonly frameExecutionContexts = new Map<string, number>();
 
 	constructor(
 		readonly pageId: string,
+		private readonly browserContextId: string | undefined,
 		private readonly pageClient: JsonRpcWebSocketClient,
-		private readonly release: (pageId: string) => Promise<void>,
+		private readonly release: (request: PoolReleaseRequest) => Promise<void>,
 	) {}
 
+	get id(): string {
+		return this.pageId;
+	}
+
 	async goto(url: string): Promise<void> {
 		await this.initialize();
 		const startedAt = Date.now();
@@ -457,8 +867,49 @@ class CdpPoolBrowserPage implements BrowserPageContract {
 
 	async evaluate<T>(fn: string | (() => T)): Promise<T> {
 		await this.initialize();
+		return await this.evaluateWithContext<T>(fn);
+	}
+
+	async evaluateInFrame<T>(
+		frameId: string,
+		fn: string | (() => T),
+	): Promise<T> {
+		await this.initialize();
+		const contextId = await this.getFrameExecutionContextId(frameId);
+		return await this.evaluateWithContext<T>(fn, contextId);
+	}
+
+	async waitForSelectorInFrame(
+		frameId: string,
+		selector: string,
+		options?: { timeout?: number },
+	): Promise<void> {
+		const timeout = options?.timeout ?? DEFAULT_WAIT_TIMEOUT_MS;
+		const deadline = Date.now() + timeout;
+
+		while (Date.now() < deadline) {
+			const exists = await this.evaluateInFrame<boolean>(
+				frameId,
+				`Boolean(document.querySelector(${JSON.stringify(selector)}))`,
+			);
+
+			if (exists) {
+				return;
+			}
+
+			await delay(SELECTOR_POLL_INTERVAL_MS);
+		}
+
+		throw new Error(`Timed out waiting for selector: ${selector}`);
+	}
+
+	private async evaluateWithContext<T>(
+		fn: string | (() => T),
+		contextId?: number,
+	): Promise<T> {
 		const result = await this.pageClient.send("Runtime.evaluate", {
 			awaitPromise: true,
+			...(contextId === undefined ? {} : { contextId }),
 			expression: formatExpression(fn),
 			returnByValue: true,
 		});
@@ -539,6 +990,37 @@ class CdpPoolBrowserPage implements BrowserPageContract {
 		);
 	}
 
+	async frames(): Promise<BrowserFrame[]> {
+		await this.initialize();
+		const result = await this.pageClient.send("Page.getFrameTree");
+		const frames = flattenCdpFrameTree(parseCdpFrameTreeNode(result.frameTree));
+		return frames.map(
+			(frame) =>
+				new CdpBrowserFrame(
+					frame.id,
+					this,
+					frame.url ?? "",
+					frame.name,
+					frame.parentId,
+				),
+		);
+	}
+
+	locator(selector: string): BrowserLocator {
+		return new CdpBrowserLocator(this, selector);
+	}
+
+	async title(): Promise<string> {
+		return await this.evaluate<string>("document.title");
+	}
+
+	async url(): Promise<string> {
+		const [mainFrame] = await this.frames();
+		const frameUrl =
+			mainFrame instanceof CdpBrowserFrame ? mainFrame.fallbackUrl() : "";
+		return frameUrl || (await this.evaluate<string>("window.location.href"));
+	}
+
 	async content(): Promise<string> {
 		return await this.evaluate<string>("document.documentElement.outerHTML");
 	}
@@ -562,7 +1044,12 @@ class CdpPoolBrowserPage implements BrowserPageContract {
 		this.closed = true;
 
 		try {
-			await this.release(this.pageId);
+			await this.release({
+				...(this.browserContextId
+					? { browserContextId: this.browserContextId }
+					: {}),
+				pageId: this.pageId,
+			});
 		} finally {
 			await this.pageClient.close();
 		}
@@ -573,11 +1060,39 @@ class CdpPoolBrowserPage implements BrowserPageContract {
 			return;
 		}
 
+		this.pageClient.on("Runtime.executionContextCreated", (params) => {
+			const context = getCdpExecutionContext(params);
+			if (context.frameId && context.id !== undefined) {
+				this.frameExecutionContexts.set(context.frameId, context.id);
+			}
+		});
 		await this.pageClient.send("Page.enable");
 		await this.pageClient.send("Runtime.enable");
 		this.initialized = true;
 	}
 
+	private async getFrameExecutionContextId(frameId: string): Promise<number> {
+		const existing = this.frameExecutionContexts.get(frameId);
+		if (existing !== undefined) {
+			return existing;
+		}
+
+		const result = await this.pageClient.send("Page.createIsolatedWorld", {
+			frameId,
+			grantUniveralAccess: true,
+			worldName: "apifuse-provider-sdk",
+		});
+		const contextId = result.executionContextId;
+		if (typeof contextId !== "number") {
+			throw new Error(
+				`Unable to resolve execution context for frame: ${frameId}`,
+			);
+		}
+
+		this.frameExecutionContexts.set(frameId, contextId);
+		return contextId;
+	}
+
 	private async waitForDocumentReady(
 		deadline: number,
 		isLoadEventSeen: () => boolean,
@@ -598,6 +1113,7 @@ class CdpPoolBrowserPage implements BrowserPageContract {
 }
 
 class CdpPoolBrowserClient implements SupportedBrowserClient {
+	private readonly allowedHosts: string[];
 	private readonly poolClient: JsonRpcWebSocketClient;
 	readonly engine = "playwright-stealth" satisfies BrowserEngine;
 
@@ -608,29 +1124,65 @@ class CdpPoolBrowserClient implements SupportedBrowserClient {
 			});
 		}
 
+		this.allowedHosts = [...new Set(options.allowedHosts ?? [])];
 		this.poolClient = new JsonRpcWebSocketClient(options.cdpUrl);
 	}
 
 	async newPage(): Promise<BrowserPageContract> {
-		const acquireResult = (await this.poolClient.send(
-			"acquire",
-		)) as PoolAcquireResponse;
+		return await this.acquirePage({ isolatedContext: true });
+	}
+
+	private async acquirePage(options?: {
+		isolatedContext?: boolean;
+	}): Promise<BrowserPageContract> {
+		const acquireResult = parsePoolAcquireResponse(
+			await this.poolClient.send("acquire", {
+				...(this.allowedHosts.length > 0
+					? { allowedHosts: this.allowedHosts }
+					: {}),
+				...(options?.isolatedContext
+					? { isolationMode: "browserContext" }
+					: {}),
+			}),
+		);
 		const pageClient = new JsonRpcWebSocketClient(acquireResult.wsEndpoint);
 		const page = new CdpPoolBrowserPage(
 			acquireResult.pageId,
+			acquireResult.browserContextId,
 			pageClient,
-			async (pageId) => {
-				await this.poolClient.send("release", { pageId });
+			async (request) => {
+				await this.poolClient.send("release", request);
 			},
 		);
 
-		await page.evaluate(
-			`window.navigator.webdriver === true ? Object.defineProperty(window.navigator, "webdriver", { configurable: true, get: () => undefined }) : undefined`,
-		);
+		try {
+			await page.evaluate(
+				`window.navigator.webdriver === true ? Object.defineProperty(window.navigator, "webdriver", { configurable: true, get: () => undefined }) : undefined`,
+			);
+		} catch (error) {
+			await page.close().catch(() => undefined);
+			throw error;
+		}
 
 		return page;
 	}
 
+	async rawPage(): Promise<BrowserPageContract> {
+		return await this.newPage();
+	}
+
+	async withIsolatedContext<T>(
+		handler: (page: BrowserPageContract) => Promise<T>,
+	): Promise<T> {
+		const page = await this.acquirePage({ isolatedContext: true });
+
+		try {
+			return await handler(page);
+		} finally {
+			await page.close();
+		}
+	}
+
 	async close(): Promise<void> {
 		await this.poolClient.close();
 	}
@@ -655,6 +1207,14 @@ class UnsupportedBrowserEngineClient implements SupportedBrowserClient {
 		});
 	}
 
+	async rawPage(): Promise<never> {
+		return await this.newPage();
+	}
+
+	async withIsolatedContext<T>(): Promise<T> {
+		return await this.newPage();
+	}
+
 	async close(): Promise<void> {}
 }
 
@@ -680,6 +1240,9 @@ function createSeleniumUCClient(): SupportedBrowserClient {
 
 export class BrowserClient implements BrowserClientContract {
 	private readonly client: SupportedBrowserClient;
+	private readonly cdpUrl?: string;
+	private activePage?: BrowserPageContract;
+	private readonly activePages = new Set<BrowserPageContract>();
 	private readonly _engine: BrowserEngine;
 
 	constructor(options: BrowserClientOptions = {}) {
@@ -689,6 +1252,17 @@ export class BrowserClient implements BrowserClientContract {
 		};
 		const engine = resolvedOptions.engine ?? "playwright-stealth";
 		this._engine = engine;
+		this.cdpUrl = resolvedOptions.cdpUrl;
+
+		if (resolvedOptions.requireCdpPool && !resolvedOptions.cdpUrl) {
+			throw new ProviderError(
+				"Managed CDP Pool is required for browser providers in production",
+				{
+					code: "BROWSER_CDP_POOL_REQUIRED",
+					fix: "Set APIFUSE__CDP_POOL__URL for deployed browser providers. Local standalone development may omit it.",
+				},
+			);
+		}
 
 		switch (engine) {
 			case "nodriver":
@@ -708,15 +1282,152 @@ export class BrowserClient implements BrowserClientContract {
 		return this._engine;
 	}
 
-	async newPage(): Promise<unknown> {
-		return await this.client.newPage();
+	async newPage(): Promise<BrowserPageContract> {
+		const page = await this.client.newPage();
+		return this.activatePage(page);
+	}
+
+	async rawPage(): Promise<BrowserPageContract> {
+		if (!this.cdpUrl) {
+			throw new ProviderError("ctx.browser.rawPage() requires a CDP pool", {
+				code: "BROWSER_RUNTIME_UNSUPPORTED",
+				fix: "Set APIFUSE__CDP_POOL__URL. The SDK escape hatch is CDP pool-backed only and never launches local Chromium.",
+			});
+		}
+
+		const page = await this.client.rawPage();
+		return this.activatePage(page);
+	}
+
+	async withIsolatedContext<T>(
+		handler: (page: BrowserPageContract) => Promise<T>,
+	): Promise<T> {
+		const previousActivePage = this.activePage;
+		let trackedPage: BrowserPageContract | undefined;
+
+		return await this.client.withIsolatedContext(async (page) => {
+			trackedPage = this.activatePage(page);
+			try {
+				return await handler(trackedPage);
+			} finally {
+				this.activePages.delete(trackedPage);
+				if (this.activePage === trackedPage) {
+					this.activePage = previousActivePage;
+				}
+			}
+		});
+	}
+
+	private activatePage(page: BrowserPageContract): BrowserPageContract {
+		let closed = false;
+		const originalClose = page.close.bind(page);
+		const trackedPage = new Proxy(page, {
+			get: (target, property, receiver) => {
+				if (property === "close") {
+					return async () => {
+						if (closed) return;
+						closed = true;
+						try {
+							await originalClose();
+						} finally {
+							this.activePages.delete(trackedPage);
+							if (this.activePage === trackedPage) {
+								this.activePage = undefined;
+							}
+						}
+					};
+				}
+				const value = Reflect.get(target, property, receiver);
+				return typeof value === "function" ? value.bind(target) : value;
+			},
+		});
+		this.activePages.add(trackedPage);
+		this.activePage = trackedPage;
+		return trackedPage;
+	}
+
+	async solveChallenge(
+		request: BrowserChallengeRequest,
+	): Promise<BrowserChallengeResult> {
+		if (request.type !== "recaptcha") {
+			throw new ProviderError(
+				`Unsupported browser challenge: ${request.type}`,
+				{
+					code: "BROWSER_RUNTIME_UNSUPPORTED",
+				},
+			);
+		}
+
+		if (this.activePage) {
+			return await solveRecaptchaChallenge(this.activePage, request);
+		}
+
+		const page = await this.client.newPage();
+		try {
+			return await solveRecaptchaChallenge(page, request);
+		} finally {
+			if (this.activePage === page) {
+				this.activePage = undefined;
+			}
+			await page.close();
+		}
 	}
 
 	async close(): Promise<void> {
-		await this.client.close();
+		const pages = Array.from(this.activePages);
+		this.activePages.clear();
+		this.activePage = undefined;
+		try {
+			await Promise.all(pages.map((page) => page.close()));
+		} finally {
+			await this.client.close();
+		}
 	}
 }
 
+async function solveRecaptchaChallenge(
+	page: BrowserPageContract,
+	request: BrowserChallengeRequest,
+): Promise<BrowserChallengeResult> {
+	const timeout = request.timeout ?? DEFAULT_WAIT_TIMEOUT_MS;
+	const deadline = Date.now() + timeout;
+
+	while (Date.now() < deadline) {
+		const frames = await page.frames();
+		const recaptchaFrame = await findRecaptchaFrame(frames, request.siteKey);
+		if (recaptchaFrame) {
+			await recaptchaFrame.locator("#recaptcha-anchor").click();
+			return {
+				type: "recaptcha",
+				solved: true,
+				frameUrl: await recaptchaFrame.url(),
+			};
+		}
+
+		await delay(SELECTOR_POLL_INTERVAL_MS);
+	}
+
+	throw new Error("Timed out waiting for reCAPTCHA iframe");
+}
+
+async function findRecaptchaFrame(
+	frames: BrowserFrame[],
+	siteKey?: string,
+): Promise<BrowserFrame | undefined> {
+	for (const frame of frames) {
+		const url = await frame.url();
+		const matchesRecaptcha =
+			url.includes("google.com/recaptcha") ||
+			url.includes("recaptcha.net/recaptcha");
+		const matchesSiteKey = !siteKey || url.includes(siteKey);
+		if (matchesRecaptcha && matchesSiteKey) {
+			return frame;
+		}
+	}
+
+	return undefined;
+}
+
 export function createBrowserClient(
 	options: BrowserClientOptions = {},
 ): BrowserClient {