surfsky 0.0.5 → 0.0.8

package/README.md

@@ -99,7 +99,7 @@ Cookies and browser state persist between leases. Handlers are not retried.
 
 - [SDK API reference](https://github.com/surfskyio/surfsky-js/blob/main/docs/api.md)
 - [REST API](https://docs.surfsky.io/api-reference)
-- [Examples](https://github.com/surfskyio/surfsky-js/tree/main/examples): forms, tabs, retries, profiles and CDP connections.
+- [Examples](https://github.com/surfskyio/surfsky-js/tree/main/examples): forms, tabs, retries, profiles, a closed shadow root and CDP connections.
 
 `client.session()` exposes a WebSocket URL for external browser clients.
 See the [Playwright](https://github.com/surfskyio/surfsky-js/blob/main/examples/playwright_connect.ts),

package/dist/index.d.ts

@@ -1266,7 +1266,6 @@ declare class Deadline {
   readonly until: number;
   constructor(timeout: number | null | undefined, message: string);
   error(): BrowserTimeoutError;
-  check(): void;
   race<T>(promise: Promise<T>): Promise<T>;
 }
 declare class CapturedResponse {
@@ -1330,6 +1329,7 @@ declare class Page extends Actions {
   /** @internal */
   _send(method: string, params?: Record<string, unknown>): Promise<any>;
   /** @internal */
+  _change(): Promise<void>;
   _waitReady(): Promise<void>;
   /** @internal */
   _setup(waiting: boolean): Promise<void>;
@@ -1370,6 +1370,12 @@ declare class Page extends Actions {
   fill(selector: string, text: string): Promise<any>;
   getAttribute(selector: string, name: string): Promise<string | null>;
   count(selector: string): Promise<number>;
+  boundingBox(selector: string): Promise<{
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  } | null>;
   selectOption(selector: string, option: string | {
     value?: string;
     label?: string;
@@ -1422,6 +1428,7 @@ declare class Browser extends Page implements AsyncDisposable {
   /** @internal */ _pages: Map<string, Page>;
   /** @internal aborts on close: background sleeps end early */
   _signal: AbortSignal;
+  _changed: PromiseWithResolvers<void>;
   constructor(session: Session, options?: BrowserOptions);
   get internalUuid(): string;
   get cdp(): CDPClient;
@@ -1460,6 +1467,8 @@ declare class Browser extends Page implements AsyncDisposable {
   /** @internal */
   _onAttached(event: Record<string, any>): void;
   /** @internal */
+  _notify(): void;
+  /** @internal */
   _onDetached(event: Record<string, any>): void;
   /** @internal */
   _drop(page: Page): void;
@@ -1622,6 +1631,7 @@ interface RequestOptions {
 interface SessionStartOptions extends SessionOptions {
   /** A saved profile to start; a one-time session when absent. */
   profileUuid?: string;
+  signal?: AbortSignal;
 }
 interface BrowserStartOptions extends SessionStartOptions {
   /** CDP resource types to drop: `["image", "font", "media"]` saves proxy traffic. */
@@ -1668,7 +1678,7 @@ declare class Surfsky implements AsyncDisposable {
   /** An open `BrowserPool`. `close()` stops every browser in it. */
   browsers(options?: PoolOptions): Promise<BrowserPool>;
   /** `browsers()` and `pool.map()` in 1 call. */
-  map<I, R>(handler: PoolHandler<I, R>, items: Iterable<I>, options?: PoolOptions): Promise<PoolOutcome<I, R>[]>;
+  map<I, R>(handler: PoolHandler<I, R>, items: Iterable<I>, options?: PoolOptions & LeaseOptions): Promise<PoolOutcome<I, R>[]>;
   /** Nothing to release with fetch; here for `await using` symmetry. */
   close(): Promise<void>;
   [Symbol.asyncDispose](): Promise<void>;
@@ -1698,6 +1708,9 @@ type PoolOutcome<I, R> = {
   index: number;
   error: unknown;
 };
+interface LeaseOptions {
+  signal?: AbortSignal;
+}
 declare class BrowserPool implements AsyncDisposable {
   #private;
   readonly sessionOptions: SessionOptions;
@@ -1711,9 +1724,9 @@ declare class BrowserPool implements AsyncDisposable {
   close(): Promise<void>;
   [Symbol.asyncDispose](): Promise<void>;
   /** Run `fn` on a live browser, then hand the browser back. Waits while all are busy. */
-  lease<R>(fn: (browser: Browser) => Promise<R>): Promise<R>;
+  lease<R>(fn: (browser: Browser) => Promise<R>, { signal }?: LeaseOptions): Promise<R>;
   /** Run every item through `handler` on a leased browser, `capacity` at a time. */
-  map<I, R>(handler: PoolHandler<I, R>, items: Iterable<I>): Promise<PoolOutcome<I, R>[]>;
+  map<I, R>(handler: PoolHandler<I, R>, items: Iterable<I>, { signal }?: LeaseOptions): Promise<PoolOutcome<I, R>[]>;
 }
 //#endregion
 //#region src/version.d.ts

package/dist/index.js

@@ -860,18 +860,26 @@ const FUNCTION = /^\s*(async\s+)?(function\b|\([^()]*\)\s*=>|[\w$]+\s*=>)/;
 function asXPath(s) {
 	return /^\s*(xpath=|\/\/|\.\.)/.test(s) ? s.trim().replace(/^xpath=/, "") : void 0;
 }
-const SELECT = `(selector, value, label) => {
-  const el = document.querySelector(selector);
-  if (!el) return null;
-  const option = Array.from(el.options).find(
+const SELECT = `function (value, label) {
+  const option = Array.from(this.options).find(
     o => label === null ? o.value === value : o.label === label || o.text === label
   );
   if (!option) return false;
-  el.value = option.value;
-  el.dispatchEvent(new Event("input", {bubbles: true}));
-  el.dispatchEvent(new Event("change", {bubbles: true}));
+  this.value = option.value;
+  this.dispatchEvent(new Event("input", {bubbles: true}));
+  this.dispatchEvent(new Event("change", {bubbles: true}));
   return option.value;
 }`;
+const INNER_TEXT = "function () { return this.innerText }";
+const IS_FOCUSED = "function () { return this.getRootNode().activeElement === this }";
+const MATCHES = "function (s) { return this.nodeType === 1 && (s == null || this.matches(s)) }";
+const WORLD_GONE = ["Cannot find context", "does not belong to the document"];
+const worldIsGone = (err) => err instanceof CDPError && WORLD_GONE.some((text) => err.message.includes(text));
+function remoteResult(result, what) {
+	const details = result.exceptionDetails;
+	if (details) throw new CDPError(`${what} failed: ${(details.exception ?? {}).description ?? details.text}`);
+	return result.result;
+}
 function cookieParam(cookie) {
 	const out = dropNulls(cookie);
 	const expires = out.expirationDate;
@@ -912,9 +920,6 @@ var Deadline = class {
 	error() {
 		return new BrowserTimeoutError(`${this.message} within ${this.timeout}ms`);
 	}
-	check() {
-		if (Date.now() >= this.until) throw this.error();
-	}
 	race(promise) {
 		if (this.timeout === null) return promise;
 		return withTimeout(promise, Math.max(0, this.until - Date.now()), () => this.error());
@@ -1056,17 +1061,22 @@ var Page = class extends Actions {
 		}
 	}
 	/** @internal */
+	_change() {
+		return Promise.race([this._browser._changed.promise, sleep(100)]);
+	}
 	async _waitReady() {
 		await this._ready.wait();
 		if (this._setupError !== void 0) throw this._setupError;
 	}
 	/** @internal */
 	async _setup(waiting) {
+		const patterns = this._browser._fetchPatterns;
 		const commands = [
 			["Page.enable", void 0],
 			["Page.setLifecycleEventsEnabled", { enabled: true }],
-			["Fetch.enable", { patterns: this._browser._fetchPatterns }]
+			["Network.enable", void 0]
 		];
+		if (patterns.length > 0) commands.push(["Fetch.enable", { patterns }]);
 		if (waiting) commands.push(["Runtime.runIfWaitingForDebugger", void 0]);
 		const timeout = this._browser.commandTimeout;
 		let posted = [];
@@ -1103,8 +1113,7 @@ var Page = class extends Actions {
 		const deadline = new Deadline(options.timeout ?? 3e4, `the page did not reach '${state}'`);
 		while (!this._milestones.has(milestone)) {
 			this._requireOpen();
-			deadline.check();
-			await sleep(100);
+			await deadline.race(this._change());
 		}
 	}
 	async goto(url, options = {}) {
@@ -1156,8 +1165,7 @@ var Page = class extends Actions {
 		const deadline = new Deadline(timeout, "history did not move");
 		while (true) {
 			if ((await deadline.race(this.send("Page.getNavigationHistory"))).currentIndex === index) break;
-			deadline.check();
-			await sleep(100);
+			await deadline.race(sleep(100));
 		}
 		return this.url();
 	}
@@ -1167,15 +1175,13 @@ var Page = class extends Actions {
 	/** Record responses whose URL contains a fragment. Call before navigating. */
 	async captureResponses(...fragments) {
 		if (fragments.length === 0) throw new TypeError("captureResponses needs at least one URL fragment");
-		if (this._captures.length === 0) await this.send("Network.enable");
+		this._requireOpen();
 		this._captures.push(...fragments);
 	}
 	async stopCapturing() {
-		if (this._captures.length === 0) return;
 		this._captures = [];
 		this._responses = [];
 		this._inFlight.clear();
-		await this.send("Network.disable");
 	}
 	async waitForResponse(fragment, options = {}) {
 		if (this._captures.length === 0) throw new Error("call captureResponses() before the navigation");
@@ -1184,13 +1190,13 @@ var Page = class extends Actions {
 			const found = this._responses.find((response) => response.url.includes(fragment));
 			if (found !== void 0) return found;
 			this._requireOpen();
-			deadline.check();
-			await sleep(100);
+			await deadline.race(this._change());
 		}
 	}
 	/** @internal */
 	_onResponse(event) {
 		const response = isRecord(event.response) ? event.response : {};
+		if (event.type === "Document" && event.frameId === this._frameId) this._status = typeof response.status === "number" ? response.status : void 0;
 		const url = typeof response.url === "string" ? response.url : "";
 		if (this._captures.some((fragment) => url.includes(fragment))) this._inFlight.set(String(event.requestId), response);
 	}
@@ -1212,6 +1218,7 @@ var Page = class extends Actions {
 			this._browser.logger.debug(`no body for ${String(response.url)}: ${String(err)}`);
 		}
 		into.push(new CapturedResponse(typeof response.url === "string" ? response.url : "", typeof response.status === "number" ? response.status : 0, isRecord(response.headers) ? response.headers : {}, body));
+		this._browser._notify();
 	}
 	localStorage() {
 		return this.#storage(true);
@@ -1279,14 +1286,38 @@ var Page = class extends Actions {
 		try {
 			result = await this.send("Runtime.evaluate", params);
 		} catch (err) {
-			if (!isolated || !(err instanceof CDPError) || !err.message.includes("Cannot find context")) throw err;
+			if (!isolated || !worldIsGone(err)) throw err;
 			this._worldId = void 0;
 			params.contextId = await this.#world();
 			result = await this.send("Runtime.evaluate", params);
 		}
-		const details = result.exceptionDetails;
-		if (details) throw new CDPError(`evaluate failed: ${(details.exception ?? {}).description ?? details.text}`);
-		return result.result;
+		return remoteResult(result, "evaluate");
+	}
+	async #call(nodeId, fn, ...args) {
+		const params = {
+			functionDeclaration: fn,
+			arguments: args.map((value) => ({ value })),
+			returnByValue: true
+		};
+		let result;
+		try {
+			result = await this.#callInWorld(nodeId, params);
+		} catch (err) {
+			if (!worldIsGone(err)) throw err;
+			this._worldId = void 0;
+			result = await this.#callInWorld(nodeId, params);
+		}
+		return remoteResult(result, "call").value;
+	}
+	async #callInWorld(nodeId, params) {
+		const resolved = await this.send("DOM.resolveNode", {
+			nodeId,
+			executionContextId: await this.#world()
+		});
+		return await this.send("Runtime.callFunctionOn", {
+			...params,
+			objectId: resolved.object.objectId
+		});
 	}
 	async #world() {
 		if (this._worldId === void 0) {
@@ -1305,12 +1336,13 @@ var Page = class extends Actions {
 		while (true) {
 			const value = await deadline.race(this.evaluate(expression, rest));
 			if (value) return value;
-			deadline.check();
-			await sleep(100);
+			await deadline.race(sleep(100));
 		}
 	}
-	innerText(selector) {
-		return this.evaluate("s => document.querySelector(s)?.innerText ?? null", { args: [selector] });
+	async innerText(selector) {
+		const nodeId = await this.#nodeId(selector);
+		if (nodeId === void 0) return null;
+		return await this.#call(nodeId, INNER_TEXT);
 	}
 	allInnerTexts(selector) {
 		return this.evaluate("s => Array.from(document.querySelectorAll(s), e => e.innerText)", { args: [selector] });
@@ -1327,7 +1359,8 @@ var Page = class extends Actions {
 		return this.keyboard.type(text);
 	}
 	async #validateFocus(selector) {
-		if (!await this.evaluate("s => document.activeElement === document.querySelector(s)", { args: [selector] })) throw new Error(`'${selector}' did not take focus`);
+		const nodeId = await this.#nodeId(selector);
+		if (nodeId === void 0 || !await this.#call(nodeId, IS_FOCUSED)) throw new Error(`'${selector}' did not take focus`);
 	}
 	async getAttribute(selector, name) {
 		const nodeId = await this.#nodeId(selector);
@@ -1338,22 +1371,38 @@ var Page = class extends Actions {
 	}
 	async count(selector) {
 		const document = await this.send("DOM.getDocument", { depth: 0 });
-		const xpath = asXPath(selector);
-		if (xpath !== void 0) return (await this.#search(xpath)).length;
-		return ((await this.send("DOM.querySelectorAll", {
+		if (asXPath(selector) !== void 0) return (await this.#search(selector)).length;
+		const nodeIds = (await this.send("DOM.querySelectorAll", {
 			nodeId: document.root.nodeId,
 			selector
-		})).nodeIds ?? []).length;
+		})).nodeIds ?? [];
+		if (nodeIds.length > 0) return nodeIds.length;
+		return (await this.#search(selector)).length;
+	}
+	async boundingBox(selector) {
+		const nodeId = await this.#nodeId(selector);
+		if (nodeId === void 0) return null;
+		let box;
+		try {
+			box = await this.send("DOM.getBoxModel", { nodeId });
+		} catch (err) {
+			if (err instanceof CDPError) return null;
+			throw err;
+		}
+		const quad = box.model.content;
+		return {
+			x: quad[0],
+			y: quad[1],
+			width: quad[2] - quad[0],
+			height: quad[5] - quad[1]
+		};
 	}
 	async selectOption(selector, option) {
 		const { value, label } = typeof option === "string" ? { value: option } : option;
 		if (value === void 0 === (label === void 0)) throw new TypeError("selectOption takes either a value or a label");
-		const picked = await this.evaluate(SELECT, { args: [
-			selector,
-			value ?? null,
-			label ?? null
-		] });
-		if (picked === null) throw new Error(`nothing matches '${selector}'`);
+		const nodeId = await this.#nodeId(selector);
+		if (nodeId === void 0) throw new Error(`nothing matches '${selector}'`);
+		const picked = await this.#call(nodeId, SELECT, value ?? null, label ?? null);
 		if (picked === false) throw new Error(`'${selector}' has no option '${label ?? value}'`);
 		return picked;
 	}
@@ -1361,10 +1410,7 @@ var Page = class extends Actions {
 		const visible = options.visible ?? true;
 		const state = visible ? "visible" : "in the document";
 		const deadline = new Deadline(options.timeout ?? 3e4, `'${selector}' was not ${state}`);
-		while (!await deadline.race(this.#matches(selector, visible))) {
-			deadline.check();
-			await sleep(100);
-		}
+		while (!await deadline.race(this.#matches(selector, visible))) await deadline.race(sleep(100));
 	}
 	async #matches(selector, visible) {
 		let box;
@@ -1382,22 +1428,34 @@ var Page = class extends Actions {
 	}
 	async #nodeId(selector) {
 		const document = await this.send("DOM.getDocument", { depth: 0 });
-		const xpath = asXPath(selector);
-		if (xpath !== void 0) return (await this.#search(xpath))[0];
-		return (await this.send("DOM.querySelector", {
+		if (asXPath(selector) !== void 0) return (await this.#search(selector))[0];
+		const found = await this.send("DOM.querySelector", {
 			nodeId: document.root.nodeId,
 			selector
-		})).nodeId || void 0;
+		});
+		if (found.nodeId) return found.nodeId;
+		return (await this.#search(selector))[0];
 	}
-	async #search(query) {
-		const { searchId, resultCount = 0 } = await this.send("DOM.performSearch", { query });
+	async #search(selector) {
+		const xpath = asXPath(selector);
+		const { searchId, resultCount = 0 } = await this.send("DOM.performSearch", {
+			query: xpath ?? selector,
+			includeUserAgentShadowDOM: false
+		});
 		try {
 			if (!resultCount) return [];
-			return (await this.send("DOM.getSearchResults", {
+			const nodeIds = (await this.send("DOM.getSearchResults", {
 				searchId,
 				fromIndex: 0,
 				toIndex: resultCount
 			})).nodeIds ?? [];
+			const css = xpath === void 0 ? selector : null;
+			await this.#world();
+			const kept = await Promise.all(nodeIds.map((nodeId) => this.#call(nodeId, MATCHES, css).catch((err) => {
+				if (err instanceof CDPError) return false;
+				throw err;
+			})));
+			return nodeIds.filter((_, i) => kept[i]);
 		} finally {
 			await this.send("DOM.discardSearchResults", { searchId }).catch(() => void 0);
 		}
@@ -1408,8 +1466,7 @@ var Page = class extends Actions {
 		while (true) {
 			const url = await deadline.race(this.url());
 			if (url.includes(fragment)) return url;
-			deadline.check();
-			await sleep(100);
+			await deadline.race(sleep(100));
 		}
 	}
 	/** The first match has a bounding box. */
@@ -1487,6 +1544,7 @@ var Page = class extends Actions {
 			this._loaderId = loaderId;
 			this._milestones = /* @__PURE__ */ new Set([name]);
 		}
+		this._browser._notify();
 		this._waiter?.observe(name, loaderId);
 	}
 	/** @internal */
@@ -1520,12 +1578,7 @@ var Page = class extends Actions {
 			this._browser.logger.warn("Fetch.requestPaused without a requestId");
 			return;
 		}
-		const status = event.responseStatusCode;
-		if (status !== void 0 && status !== null) {
-			if (event.frameId === this._frameId) this._status = status;
-			this._spawn(this._send("Fetch.continueResponse", { requestId }));
-		} else if (event.responseErrorReason) this._spawn(this._send("Fetch.continueRequest", { requestId }));
-		else this._spawn(this._send("Fetch.failRequest", {
+		this._spawn(this._send("Fetch.failRequest", {
 			requestId,
 			errorReason: "BlockedByClient"
 		}));
@@ -1537,11 +1590,6 @@ var Page = class extends Actions {
 };
 //#endregion
 //#region src/browser/browser.ts
-const STATUS_PATTERN = {
-	urlPattern: "*",
-	resourceType: "Document",
-	requestStage: "Response"
-};
 const AUTO_ATTACH = {
 	autoAttach: true,
 	waitForDebuggerOnStart: true,
@@ -1609,6 +1657,7 @@ var Browser = class extends Page {
 	#client;
 	#abort = new AbortController();
 	#pending = /* @__PURE__ */ new Set();
+	_changed = Promise.withResolvers();
 	#closing;
 	#retired = false;
 	#useCount = 0;
@@ -1659,7 +1708,7 @@ var Browser = class extends Page {
 			resourceType: RESOURCE_TYPES[name]
 		}));
 		for (const pattern of this.blockedUrls) patterns.push({ urlPattern: pattern });
-		return [...patterns, STATUS_PATTERN];
+		return patterns;
 	}
 	/** Replace this browser with a fresh one after the lease. */
 	retire() {
@@ -1690,8 +1739,7 @@ var Browser = class extends Page {
 			const last = opened[opened.length - 1];
 			if (last !== void 0) return last;
 			this._requireOpen();
-			deadline.check();
-			await sleep(100);
+			await deadline.race(this._change());
 		}
 	}
 	async connect() {
@@ -1763,8 +1811,7 @@ var Browser = class extends Page {
 		let page = this.#pageFor(targetId);
 		while (page === void 0) {
 			this._requireOpen();
-			deadline.check();
-			await sleep(100);
+			await deadline.race(this._change());
 			page = this.#pageFor(targetId);
 		}
 		await deadline.race(page._waitReady());
@@ -1794,8 +1841,14 @@ var Browser = class extends Page {
 		page._frameId = page._targetId;
 		page._ready = new Flag();
 		this._pages.set(sessionId, page);
+		this._notify();
 		this._spawn(page._setup(waiting));
 	}
+	/** @internal */
+	_notify() {
+		this._changed.resolve();
+		this._changed = Promise.withResolvers();
+	}
 	async #letGo(sessionId, waiting) {
 		const timeout = this.commandTimeout;
 		const detach = async () => {
@@ -1813,6 +1866,7 @@ var Browser = class extends Page {
 	_drop(page) {
 		this._pages.delete(page._sessionId);
 		page._closed = true;
+		this._notify();
 		page._waiter?.fail("page closed");
 		if (page === this) {
 			this.logger.warn(`page target gone for ${this.internalUuid}`);
@@ -1831,6 +1885,7 @@ var Browser = class extends Page {
 			page._closed = true;
 			page._waiter?.fail("CDP connection closed");
 		}
+		this._notify();
 	}
 	/** @internal track a background task; its failure is logged at debug level */
 	_spawn(task) {
@@ -2176,7 +2231,6 @@ var BrowserPool = class {
 	#idle = [];
 	#owned = 0;
 	#planFull = false;
-	#planFullError;
 	#waiters = [];
 	#capacity = 0;
 	#slots;
@@ -2209,7 +2263,6 @@ var BrowserPool = class {
 		this.#capacity = Math.max(1, total);
 		this.#slots = new Semaphore(this.#capacity);
 		this.#planFull = false;
-		this.#planFullError = void 0;
 		this.#owned = 0;
 		return this;
 	}
@@ -2225,14 +2278,17 @@ var BrowserPool = class {
 		return this.close();
 	}
 	/** Run `fn` on a live browser, then hand the browser back. Waits while all are busy. */
-	async lease(fn) {
+	async lease(fn, { signal } = {}) {
+		signal?.throwIfAborted();
 		const slots = this.#requireOpen();
 		await slots.acquire();
 		try {
 			if (this.#slots !== slots) throw new Error("the pool was closed while waiting for a slot");
+			signal?.throwIfAborted();
 			const browser = await this.#acquire();
 			browser._lease();
 			try {
+				signal?.throwIfAborted();
 				return await fn(browser);
 			} finally {
 				await this.#release(browser);
@@ -2263,7 +2319,6 @@ var BrowserPool = class {
 			const idle = this.#idle.pop();
 			if (idle !== void 0) return idle;
 			if (this.#planFull) {
-				if (this.#owned === 0) throw this.#planFullError ?? new RateLimitError("parallel browser limit reached", { statusCode: 429 });
 				await this.#wait();
 				continue;
 			}
@@ -2272,15 +2327,10 @@ var BrowserPool = class {
 			try {
 				browser = await this.#startBrowser();
 			} catch (err) {
-				const full = planIsFull(err);
 				this.#owned -= 1;
-				if (full) {
-					this.#planFull = true;
-					this.#planFullError = err;
-				}
-				const nothingLeft = this.#owned === 0;
+				this.#planFull = planIsFull(err) && this.#owned > 0;
 				this.#notifyAll();
-				if (!full || nothingLeft) throw err;
+				if (!this.#planFull) throw err;
 				this.#client.logger.info("plan is full, waiting for a browser of ours");
 				continue;
 			}
@@ -2304,20 +2354,20 @@ var BrowserPool = class {
 		this.#notifyAll();
 	}
 	/** Run every item through `handler` on a leased browser, `capacity` at a time. */
-	async map(handler, items) {
+	async map(handler, items, { signal } = {}) {
 		const work = items[Symbol.iterator]();
 		const outcomes = [];
 		let index = 0;
 		let stopped = false;
 		const worker = async () => {
-			while (!stopped) {
+			while (!stopped && !signal?.aborted) {
 				const next = work.next();
 				if (next.done) return;
 				const item = next.value;
 				const at = index;
 				index += 1;
 				try {
-					const value = await this.lease((browser) => handler(browser, item));
+					const value = await this.lease((browser) => handler(browser, item), { signal });
 					outcomes.push({
 						ok: true,
 						item,
@@ -2624,7 +2674,7 @@ var Proxies = class {
 };
 //#endregion
 //#region src/version.ts
-const VERSION = "0.0.5";
+const VERSION = "0.0.8";
 //#endregion
 //#region src/client.ts
 function userAgent() {
@@ -2723,13 +2773,18 @@ var Surfsky = class Surfsky {
 	}
 	/** Start a session; `stop()` it (or `await using`) so it does not keep billing. */
 	async session(options = {}) {
-		const { profileUuid, ...rest } = options;
+		const { profileUuid, signal, ...rest } = options;
+		signal?.throwIfAborted();
 		const session = profileUuid === void 0 ? await this.profiles.startOneTime(rest) : await this.profiles.start(profileUuid, rest);
 		let stopping;
 		const stop = () => {
 			stopping ??= stopSession(this, session.internal_uuid);
 			return stopping;
 		};
+		if (signal?.aborted) {
+			await stop();
+			throw signal.reason;
+		}
 		return {
 			...session,
 			stop,
@@ -2738,11 +2793,12 @@ var Surfsky = class Surfsky {
 	}
 	/** Start a session and connect a `Browser` to it. `close()` stops the session. */
 	async browser(options = {}) {
-		const { profileUuid, blockResources, blockUrls, connectTimeout, commandTimeout, createWebSocket, ...sessionOptions } = options;
+		const { profileUuid, signal, blockResources, blockUrls, connectTimeout, commandTimeout, createWebSocket, ...sessionOptions } = options;
 		const blocked = normalizeBlocked(blockResources);
 		const urls = normalizeUrls(blockUrls);
 		const session = await this.session({
 			profileUuid,
+			signal,
 			...sessionOptions
 		});
 		const browser = new Browser(session, {
@@ -2754,7 +2810,19 @@ var Surfsky = class Surfsky {
 			logger: this.logger,
 			onClose: () => session.stop()
 		});
-		await browser.connect();
+		const onAbort = () => void browser.close();
+		signal?.addEventListener("abort", onAbort, { once: true });
+		try {
+			await browser.connect();
+		} catch (err) {
+			throw signal?.aborted ? signal.reason : err;
+		} finally {
+			signal?.removeEventListener("abort", onAbort);
+		}
+		if (signal?.aborted) {
+			await browser.close();
+			throw signal.reason;
+		}
 		return browser;
 	}
 	/** An open `BrowserPool`. `close()` stops every browser in it. */
@@ -2763,9 +2831,10 @@ var Surfsky = class Surfsky {
 	}
 	/** `browsers()` and `pool.map()` in 1 call. */
 	async map(handler, items, options = {}) {
-		const pool = await this.browsers(options);
+		const { signal, ...poolOptions } = options;
+		const pool = await this.browsers(poolOptions);
 		try {
-			return await pool.map(handler, items);
+			return await pool.map(handler, items, { signal });
 		} finally {
 			await pool.close();
 		}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "surfsky",
-  "version": "0.0.5",
+  "version": "0.0.8",
   "description": "TypeScript SDK for the Surfsky antidetect browser cloud.",
   "keywords": [
     "surfsky",