@orkestrel/browser 0.0.23 → 0.0.24

package/dist/src/server/index.cjs

@@ -237,6 +237,84 @@ var BROWSER_SERVER_OPTIONS = "BROWSER_SERVER_OPTIONS";
 var BROWSER_SERVER_CRASH = "BROWSER_SERVER_CRASH";
 /** Names an interrupted call whose outcome is unknown. */
 var BROWSER_SERVER_UNRESOLVED = "BROWSER_SERVER_UNRESOLVED";
+/** Names the refusal when every browser is admitted to a holder. */
+var BROWSER_SERVER_BUSY = "BROWSER_SERVER_BUSY";
+/** Names the refusal for an unknown or ended holder. */
+var BROWSER_SERVER_HOLDER = "BROWSER_SERVER_HOLDER";
+/** Defines the holder tools independently of the shared browser's vocabulary. */
+var BROWSER_SERVER_COPY = Object.freeze({
+	acquire: Object.freeze({
+		name: "acquire",
+		description: "Acquires an independent browser and returns its holder id and tool catalog. Destroy the holder when its work ends.",
+		parameters: Object.freeze({
+			type: "object",
+			properties: Object.freeze({ purpose: Object.freeze({
+				type: "string",
+				description: "The work this browser will serve."
+			}) }),
+			required: Object.freeze(["purpose"])
+		})
+	}),
+	execute: Object.freeze({
+		name: "execute",
+		description: "Runs a tool on the selected holder, with that tool’s arguments inside arguments. Get its available tools with tools.",
+		parameters: Object.freeze({
+			type: "object",
+			properties: Object.freeze({
+				holder: Object.freeze({
+					type: "string",
+					description: "The holder id returned by acquire."
+				}),
+				name: Object.freeze({
+					type: "string",
+					description: "The tool name from this holder’s catalog."
+				}),
+				arguments: Object.freeze({
+					type: "object",
+					description: "The arguments for the selected tool."
+				})
+			}),
+			required: Object.freeze([
+				"holder",
+				"name",
+				"arguments"
+			])
+		}),
+		annotations: Object.freeze({
+			pure: false,
+			untrusted: true
+		})
+	}),
+	tools: Object.freeze({
+		name: "tools",
+		description: "Lists the selected holder’s tools, including tools supplied by its page.",
+		parameters: Object.freeze({
+			type: "object",
+			properties: Object.freeze({ holder: Object.freeze({
+				type: "string",
+				description: "The holder id returned by acquire."
+			}) }),
+			required: Object.freeze(["holder"])
+		}),
+		annotations: Object.freeze({
+			pure: true,
+			untrusted: true
+		})
+	}),
+	destroy: Object.freeze({
+		name: "destroy",
+		description: "Ends the selected holder and destroys its browser. Calls still running on that holder report an unresolved outcome.",
+		parameters: Object.freeze({
+			type: "object",
+			properties: Object.freeze({ holder: Object.freeze({
+				type: "string",
+				description: "The holder id returned by acquire."
+			}) }),
+			required: Object.freeze(["holder"])
+		}),
+		annotations: Object.freeze({ pure: false })
+	})
+});
 //#endregion
 //#region src/server/errors.ts
 /**
@@ -280,6 +358,25 @@ function isBrowserDestroyedError(value) {
 //#endregion
 //#region src/server/helpers.ts
 /**
+* Parses positive integer viewport dimensions in WIDTHxHEIGHT form.
+* @param value - The viewport environment variable, or undefined when unset
+* @returns The viewport, or undefined when absent or malformed
+* @example
+* parseBrowserViewport('1280x720') // { width: 1280, height: 720 }
+*/
+function parseBrowserViewport(value) {
+	if (value === void 0) return void 0;
+	const match = /^([0-9]+)x([0-9]+)$/u.exec(value);
+	if (match === null || match[0] !== value) return void 0;
+	const width = (0, _orkestrel_contract.parseInteger)(match[1]);
+	const height = (0, _orkestrel_contract.parseInteger)(match[2]);
+	if (width === void 0 || height === void 0 || !Number.isSafeInteger(width) || !Number.isSafeInteger(height) || width <= 0 || height <= 0) return void 0;
+	return {
+		width,
+		height
+	};
+}
+/**
 * Probes whether a process has not been confirmed absent.
 * @param pid - Process identifier to probe with signal zero
 * @returns True if the host has not confirmed absence with ESRCH; false otherwise
@@ -945,7 +1042,7 @@ var FileBrowserWriter = class {
 };
 //#endregion
 //#region package.json
-var version = "0.0.23";
+var version = "0.0.24";
 //#endregion
 //#region src/server/BrowserMCPServer.ts
 /**
@@ -960,8 +1057,11 @@ var version = "0.0.23";
 * absent. After the launch, a tool the toolset's manager adds under another name, such as a page
 * tool it adopts, is mirrored as a dispatcher with that tool's definition, and the mirror is
 * removed when the toolset withdraws the tool, so the server's tool list changes and a subscribed
-* client is notified. Startup warms the pool and leases one validated browser. The legacy
-* handshake and every tool call await that setup; concurrent callers share a replacement lease.
+* client is notified. The server also advertises `acquire`, `execute`, `tools`, and `destroy` with
+* `BROWSER_SERVER_COPY`. Startup warms the pool and leases the shared browser. The legacy
+* handshake and browser calls await that setup. Named holders each own a lease, a pending grant,
+* and loss notices; concurrent calls on a holder share its replacement grant. Ending a holder
+* destroys its token, and admission counts that holder until disposal settles.
 * A launch creates `ROOT/.profiles/PID-UUID/` exclusively, connects a browser that never attaches to an
 * existing endpoint, opens one page in an isolated context, and constructs the page toolset with
 * that context and the file journey and run stores under the root, on a manager the toolset owns.
@@ -971,6 +1071,8 @@ var version = "0.0.23";
 * A disconnect or current-page crash retires its slot. A failed call receives a liveness ping;
 * loss makes its outcome unresolved, while a known success remains successful. Pending losses
 * prefix the next outcome on a successor, or a refusal, and calls are never repeated.
+* Concurrent checks share one ping per slot. Cancelling a call ends only its wait; the ping keeps
+* its deadline and records loss for the next call.
 *
 * `start()` serves stdio and destroys the server at the end of its input, on `SIGINT`, and on
 * `SIGTERM`. `destroy()` stops reading requests and removes every dispatcher, then destroys every
@@ -994,6 +1096,7 @@ var BrowserMCPServer = class {
 	#root;
 	#headless;
 	#executable;
+	#viewport;
 	#readonly;
 	#launcher;
 	#input;
@@ -1002,22 +1105,32 @@ var BrowserMCPServer = class {
 	#abort = new AbortController();
 	#signal;
 	#vocabulary;
-	#added;
-	#removed;
-	#cleared;
+	#mirrored;
 	#pool;
 	#log;
 	#folders = /* @__PURE__ */ new Set();
 	#faults = /* @__PURE__ */ new Set();
 	#losses = /* @__PURE__ */ new WeakMap();
+	#pings = /* @__PURE__ */ new WeakMap();
 	#watches = /* @__PURE__ */ new Map();
-	#notice = /* @__PURE__ */ new Set();
+	#shared = {
+		id: "shared",
+		purpose: "Shared browser",
+		abort: this.#abort
+	};
+	#holders = /* @__PURE__ */ new Map([[this.#shared.id, this.#shared]]);
+	#leases = /* @__PURE__ */ new Map();
+	#grants = /* @__PURE__ */ new Map();
+	#notices = /* @__PURE__ */ new Map();
+	#disposals = /* @__PURE__ */ new Map();
+	#drains = /* @__PURE__ */ new Map();
+	#readers = /* @__PURE__ */ new Map();
+	#writers = /* @__PURE__ */ new Set();
+	#size;
 	#reference;
 	#references = 0;
 	#failure;
 	#stranded;
-	#lease;
-	#granting;
 	#starting;
 	#sweeping;
 	#closing;
@@ -1029,6 +1142,7 @@ var BrowserMCPServer = class {
 	constructor(options) {
 		const size = options?.pool?.size ?? 1;
 		if (!(0, _orkestrel_contract.isInteger)(size) || size < 1 || size > 3) throw new _src_core.BrowserError(`pool.size must be an integer from 1 through 3`, BROWSER_SERVER_OPTIONS);
+		this.#size = size;
 		this.#log = options?.log ?? process.stderr;
 		this.#reference = this.#issue.bind(this);
 		this.#pool = (0, _orkestrel_pool.createPool)({
@@ -1043,15 +1157,32 @@ var BrowserMCPServer = class {
 		this.#root = (0, node_path.resolve)(options?.root ?? "tmp/browsers");
 		this.#headless = options?.headless ?? true;
 		this.#executable = options?.executable;
+		this.#viewport = options?.viewport;
 		this.#readonly = options?.readonly ?? false;
 		this.#launcher = options?.launch ?? createBrowser;
 		this.#input = options?.stdio?.input ?? process.stdin;
 		this.#tools = (0, _orkestrel_tool.createToolManager)();
 		const names = [..._src_core.BROWSER_TOOL_NAMES, ..._src_core.BROWSER_JOURNEY_TOOL_NAMES];
-		this.#vocabulary = new Set(names);
+		this.#vocabulary = /* @__PURE__ */ new Set([...names, ...Object.keys(BROWSER_SERVER_COPY)]);
 		for (const name of names) this.#tools.add((0, _orkestrel_tool.createTool)({
 			..._src_core.BROWSER_TOOL_COPY[name],
-			execute: this.#forward.bind(this, name)
+			execute: this.#forward.bind(this, this.#shared, name)
+		}));
+		this.#tools.add((0, _orkestrel_tool.createTool)({
+			...BROWSER_SERVER_COPY.acquire,
+			execute: this.#acquire.bind(this)
+		}));
+		this.#tools.add((0, _orkestrel_tool.createTool)({
+			...BROWSER_SERVER_COPY.execute,
+			execute: this.#dispatch.bind(this)
+		}));
+		this.#tools.add((0, _orkestrel_tool.createTool)({
+			...BROWSER_SERVER_COPY.tools,
+			execute: this.#catalog.bind(this)
+		}));
+		this.#tools.add((0, _orkestrel_tool.createTool)({
+			...BROWSER_SERVER_COPY.destroy,
+			execute: this.#dispose.bind(this)
 		}));
 		const server = (0, _orkestrel_mcp.createMCPServer)({
 			identity: {
@@ -1067,9 +1198,6 @@ var BrowserMCPServer = class {
 			...options?.stdio?.output === void 0 ? {} : { output: options.stdio.output }
 		});
 		this.#signal = this.#end.bind(this);
-		this.#added = this.#mirror.bind(this);
-		this.#removed = this.#withdraw.bind(this);
-		this.#cleared = this.#clear.bind(this);
 	}
 	async start() {
 		if (this.#closing !== void 0) throw this.#ended();
@@ -1090,7 +1218,7 @@ var BrowserMCPServer = class {
 			if (this.#closing !== void 0) return;
 			this.#sweeping = this.#sweep();
 			const warming = this.#pool.start().then(void 0, (error) => error);
-			await this.#grant(this.#abort.signal);
+			await this.#grant(this.#shared, this.#abort.signal);
 			if (this.#closing !== void 0) return;
 			warming.then(this.#exhaust.bind(this));
 		} catch (error) {
@@ -1106,13 +1234,16 @@ var BrowserMCPServer = class {
 		this.#transport.stop();
 		for (const tool of this.#tools.tools()) this.#tools.remove(tool.name);
 		this.#unmirror();
-		this.#lease = void 0;
+		this.#leases.clear();
+		for (const holder of this.#holders.values()) holder.abort.abort();
 		this.#abort.abort();
 		const barrier = this.#pool.destroy().catch((error) => {
 			for (const failure of (0, _orkestrel_pool.isPoolError)(error) ? error.context?.failures ?? [error] : [error]) this.#faults.add(failure);
 		});
 		await this.#starting?.catch(() => void 0);
 		await barrier;
+		await Promise.allSettled(this.#disposals.values());
+		this.#holders.clear();
 		await this.#sweeping;
 		if (this.#stranded !== void 0) this.#faults.add(this.#stranded);
 		for (const folder of this.#folders) {
@@ -1157,22 +1288,141 @@ var BrowserMCPServer = class {
 		process.exitCode = 1;
 		this.#write(`browse: ${describeBrowserServerLoss(BROWSER_SERVER_TEARDOWN, error)}`);
 	}
-	async #forward(name, args, context) {
+	async #acquire(args, context) {
+		context.signal.throwIfAborted();
+		if (this.#closing !== void 0) throw this.#ended();
+		const purpose = args["purpose"];
+		if (!(0, _orkestrel_contract.isString)(purpose) || purpose.trim().length === 0) throw new _src_core.BrowserError("purpose must describe the work", "BROWSER_TOOLSET_ARGUMENT");
+		if (this.#holders.size >= this.#size) throw new _src_core.BrowserError(`${BROWSER_SERVER_BUSY}: ${[...this.#holders.values()].map((holder) => `${holder.id} (${holder.purpose})`).join(", ")}. Call destroy for a holder no longer needed or call the named tools to share the shared browser.`, BROWSER_SERVER_BUSY);
+		const holder = {
+			id: (0, node_crypto.randomUUID)(),
+			purpose,
+			abort: new AbortController()
+		};
+		this.#holders.set(holder.id, holder);
+		const listener = (0, node_events.addAbortListener)(context.signal, () => holder.abort.abort(context.signal.reason));
+		try {
+			const slot = await this.#serve(holder, context.signal);
+			context.signal.throwIfAborted();
+			if (holder.abort.signal.aborted || this.#holders.get(holder.id) !== holder) throw this.#ended();
+			if (this.#leases.get(holder)?.value !== slot) throw this.#unavailable(this.#losses.get(slot)?.cause);
+			const catalog = {
+				holder: holder.id,
+				tools: slot.toolset.tools.definitions()
+			};
+			return JSON.stringify(catalog);
+		} catch (error) {
+			await this.#retire(holder).catch(this.#fault.bind(this));
+			throw error;
+		} finally {
+			listener[Symbol.dispose]();
+		}
+	}
+	#holder(value) {
+		const holder = (0, _orkestrel_contract.isString)(value) ? this.#holders.get(value) : void 0;
+		if (holder === void 0 || holder === this.#shared || holder.abort.signal.aborted) throw new _src_core.BrowserError(`${BROWSER_SERVER_HOLDER}: unknown or ended holder`, BROWSER_SERVER_HOLDER);
+		return holder;
+	}
+	async #dispatch(args, context) {
+		const holder = this.#holder(args["holder"]);
+		const name = args["name"];
+		const parameters = args["arguments"];
+		if (!(0, _orkestrel_contract.isString)(name) || !(0, _orkestrel_contract.isRecord)(parameters)) throw new _src_core.BrowserError("execute requires name and arguments", "BROWSER_TOOLSET_ARGUMENT");
+		return this.#forward(holder, name, parameters, context);
+	}
+	async #catalog(args, context) {
+		const holder = this.#holder(args["holder"]);
+		const signal = AbortSignal.any([context.signal, holder.abort.signal]);
+		try {
+			const slot = await this.#serve(holder, signal);
+			signal.throwIfAborted();
+			if (this.#leases.get(holder)?.value !== slot) throw this.#unavailable(this.#losses.get(slot)?.cause);
+			const catalog = {
+				holder: holder.id,
+				tools: slot.toolset.tools.definitions()
+			};
+			return this.#annotate(holder, JSON.stringify(catalog));
+		} catch (error) {
+			context.signal.throwIfAborted();
+			if (holder.abort.signal.aborted) throw new _src_core.BrowserError(`${BROWSER_SERVER_UNRESOLVED}: the holder ended during the call`, BROWSER_SERVER_UNRESOLVED);
+			if ((0, _src_core.isBrowserError)(error)) throw new _src_core.BrowserError(this.#annotate(holder, `${error.code}: ${error.message}`), error.code);
+			throw error;
+		}
+	}
+	async #dispose(args) {
+		const id = args["holder"];
+		await (((0, _orkestrel_contract.isString)(id) ? this.#disposals.get(id) : void 0) ?? this.#retire(this.#holder(id)));
+		return "Holder destroyed.";
+	}
+	#retire(holder) {
+		const pending = this.#disposals.get(holder.id);
+		if (pending !== void 0) return pending;
+		holder.abort.abort();
+		const token = this.#leases.get(holder);
+		this.#leases.delete(holder);
+		const disposal = Promise.resolve().then(async () => {
+			try {
+				await this.#grants.get(holder)?.catch(() => void 0);
+				await token?.destroy();
+				await Promise.all(this.#drains.get(holder) ?? []);
+			} catch (error) {
+				this.#faults.add(error);
+			} finally {
+				if (this.#holders.get(holder.id) === holder) this.#holders.delete(holder.id);
+				this.#notices.delete(holder);
+				this.#drains.delete(holder);
+			}
+		});
+		this.#disposals.set(holder.id, disposal);
+		return disposal;
+	}
+	async #forward(holder, name, args, context) {
+		context.signal.throwIfAborted();
+		const journey = args["journey"];
+		if (name !== "replay" && name !== "forget" || !(0, _orkestrel_contract.isString)(journey)) return this.#perform(holder, name, args, context);
+		if (this.#writers.has(journey) || name === "forget" && this.#readers.has(journey)) throw new _src_core.BrowserError(`BROWSER_JOURNEY_LOCKED: Journey ${journey} is locked; call ${name} again.`, "BROWSER_JOURNEY_LOCKED", { name: journey });
+		const reader = Symbol(journey);
+		if (name === "forget") this.#writers.add(journey);
+		else {
+			const readers = this.#readers.get(journey) ?? /* @__PURE__ */ new Set();
+			readers.add(reader);
+			this.#readers.set(journey, readers);
+		}
+		try {
+			return await this.#perform(holder, name, args, context);
+		} finally {
+			if (name === "forget") this.#writers.delete(journey);
+			else {
+				const readers = this.#readers.get(journey);
+				readers?.delete(reader);
+				if (readers?.size === 0) this.#readers.delete(journey);
+			}
+		}
+	}
+	async #perform(holder, name, args, context) {
+		const signal = holder === this.#shared ? context.signal : AbortSignal.any([context.signal, holder.abort.signal]);
 		let slot;
 		try {
-			slot = await this.#serve(context.signal);
+			slot = await this.#serve(holder, signal);
 		} catch (error) {
 			context.signal.throwIfAborted();
-			if ((0, _src_core.isBrowserError)(error)) throw new _src_core.BrowserError(this.#annotate(`${error.code}: ${error.message}`), error.code);
+			if (holder !== this.#shared && holder.abort.signal.aborted) throw new _src_core.BrowserError(`${BROWSER_SERVER_UNRESOLVED}: the holder ended during the call`, BROWSER_SERVER_UNRESOLVED);
+			if ((0, _src_core.isBrowserError)(error)) throw new _src_core.BrowserError(this.#annotate(holder, `${error.code}: ${error.message}`), error.code);
 			throw error;
 		}
 		let result;
 		try {
-			result = await slot.toolset.tools.execute({
+			const execution = slot.toolset.tools.execute({
 				id: name,
 				name,
 				arguments: args
-			}, context);
+			}, {
+				...context,
+				signal
+			});
+			const outcome = await (name === "replay" || name === "forget" ? execution : this.#race(execution, signal));
+			if (outcome === void 0) throw this.#ended();
+			result = outcome;
 		} catch (error) {
 			result = {
 				id: name,
@@ -1182,28 +1432,27 @@ var BrowserMCPServer = class {
 			};
 		}
 		context.signal.throwIfAborted();
+		if (holder !== this.#shared && holder.abort.signal.aborted) throw new _src_core.BrowserError(BROWSER_SERVER_UNRESOLVED + ": the holder ended during the call", BROWSER_SERVER_UNRESOLVED);
 		if (!result.success) {
-			if (this.#lease?.value === slot && !context.signal.aborted) try {
-				await slot.browser.ping({ signal: AbortSignal.any([context.signal, this.#abort.signal]) });
-			} catch (error) {
-				if (!context.signal.aborted && !this.#abort.signal.aborted) this.#lose(slot, error);
-			}
+			if (this.#leases.get(holder)?.value === slot && !context.signal.aborted) try {
+				await this.#race(this.#ping(slot), context.signal);
+			} catch {}
 			context.signal.throwIfAborted();
-			if (this.#lease?.value !== slot) {
+			if (this.#leases.get(holder)?.value !== slot) {
 				const loss = this.#losses.get(slot);
-				throw new _src_core.BrowserError(this.#annotate(describeBrowserServerLoss(BROWSER_SERVER_UNRESOLVED, loss?.cause, loss?.url), slot), BROWSER_SERVER_UNRESOLVED);
+				throw new _src_core.BrowserError(this.#annotate(holder, describeBrowserServerLoss(BROWSER_SERVER_UNRESOLVED, loss?.cause, loss?.url), slot), BROWSER_SERVER_UNRESOLVED);
 			}
-			throw new _src_core.BrowserError(this.#annotate(result.error, slot));
+			throw new _src_core.BrowserError(this.#annotate(holder, result.error, slot));
 		}
-		return typeof result.value === "string" ? this.#annotate(result.value, slot) : result.value;
+		return typeof result.value === "string" ? this.#annotate(holder, result.value, slot) : result.value;
 	}
-	#annotate(value, slot) {
+	#annotate(holder, value, slot) {
 		const notes = [];
-		for (const lost of this.#notice) {
+		for (const lost of this.#notices.get(holder) ?? []) {
 			if (lost === slot) continue;
 			const loss = this.#losses.get(lost);
 			notes.push(describeBrowserServerLoss(BROWSER_SERVER_CRASH, loss?.cause, loss?.url));
-			this.#notice.delete(lost);
+			this.#notices.get(holder)?.delete(lost);
 		}
 		return [...notes, value].join("\n");
 	}
@@ -1227,52 +1476,66 @@ var BrowserMCPServer = class {
 			listener[Symbol.dispose]();
 		}
 	}
-	async #grant(signal) {
-		if (this.#lease !== void 0) return this.#lease;
-		this.#granting ??= this.#pool.acquire(this.#abort.signal).then(this.#hold.bind(this), this.#refuse.bind(this));
-		const token = await this.#race(this.#granting, signal);
+	async #grant(holder, signal) {
+		const held = this.#leases.get(holder);
+		if (held !== void 0) return held;
+		let granting = this.#grants.get(holder);
+		if (granting === void 0) {
+			granting = this.#pool.acquire(holder.abort.signal).then(this.#hold.bind(this, holder));
+			this.#grants.set(holder, granting);
+			granting.finally(() => {
+				if (this.#grants.get(holder) === granting) this.#grants.delete(holder);
+			}).catch(() => void 0);
+		}
+		const token = await this.#race(granting, signal);
 		if (token === void 0) throw this.#ended();
 		return token;
 	}
-	#hold(token) {
-		this.#granting = void 0;
-		if (this.#closing !== void 0) throw this.#ended();
+	async #hold(holder, token) {
+		if (this.#closing !== void 0 || this.#holders.get(holder.id) !== holder || holder.abort.signal.aborted) {
+			await token.destroy();
+			throw this.#ended();
+		}
 		if (this.#losses.has(token.value)) {
-			token.destroy().catch(() => void 0);
+			await token.destroy().catch(() => void 0);
 			throw this.#unavailable(this.#losses.get(token.value)?.cause);
 		}
-		this.#lease = token;
-		const tools = token.value.toolset.tools;
-		for (const tool of tools.tools()) this.#mirror(tool);
-		tools.emitter.on("add", this.#added);
-		tools.emitter.on("remove", this.#removed);
-		tools.emitter.on("clear", this.#cleared);
+		this.#leases.set(holder, token);
+		if (holder === this.#shared) {
+			const tools = token.value.toolset.tools;
+			const mirrored = {
+				token,
+				added: this.#mirror.bind(this, token),
+				removed: this.#withdraw.bind(this, token),
+				cleared: this.#clear.bind(this, token)
+			};
+			this.#mirrored = mirrored;
+			for (const tool of tools.tools()) this.#mirror(token, tool);
+			tools.emitter.on("add", mirrored.added);
+			tools.emitter.on("remove", mirrored.removed);
+			tools.emitter.on("clear", mirrored.cleared);
+		}
 		return token;
 	}
-	#refuse(error) {
-		this.#granting = void 0;
-		throw error;
-	}
-	async #serve(signal) {
-		if (this.#closing !== void 0) throw this.#ended();
+	async #serve(holder, signal) {
+		if (this.#closing !== void 0 || holder.abort.signal.aborted) throw this.#ended();
 		await this.#race(this.#starting, signal);
-		if (this.#closing !== void 0) throw this.#ended();
-		const held = this.#lease;
+		if (this.#closing !== void 0 || holder.abort.signal.aborted) throw this.#ended();
+		const held = this.#leases.get(holder);
 		if (held !== void 0) try {
-			await held.value.browser.ping({ signal: AbortSignal.any([signal, this.#abort.signal]) });
-			if (this.#lease === held) return held.value;
-		} catch (error) {
+			await this.#race(this.#ping(held.value), signal);
+			if (this.#leases.get(holder) === held) return held.value;
+		} catch {
 			signal.throwIfAborted();
-			if (this.#abort.signal.aborted) throw this.#ended();
-			this.#lose(held.value, error);
+			if (holder.abort.signal.aborted) throw this.#ended();
 		}
 		try {
-			const token = await this.#grant(signal);
-			if (this.#lease !== token) throw this.#unavailable(this.#losses.get(token.value)?.cause);
+			const token = await this.#grant(holder, signal);
+			if (this.#leases.get(holder) !== token) throw this.#unavailable(this.#losses.get(token.value)?.cause);
 			return token.value;
 		} catch (error) {
 			signal.throwIfAborted();
-			if (this.#abort.signal.aborted || (0, _orkestrel_pool.isPoolError)(error) && error.code === "destroyed") throw this.#ended();
+			if (holder.abort.signal.aborted || (0, _orkestrel_pool.isPoolError)(error) && error.code === "destroyed") throw this.#ended();
 			if ((0, _orkestrel_pool.isPoolError)(error) && (error.code === "create" || error.code === "cleanup")) {
 				this.#exhaust(error);
 				throw this.#unavailable(error.cause ?? this.#failure);
@@ -1280,6 +1543,15 @@ var BrowserMCPServer = class {
 			throw error;
 		}
 	}
+	#ping(slot) {
+		const pending = this.#pings.get(slot);
+		if (pending !== void 0) return pending;
+		const ping = slot.browser.ping({ signal: this.#abort.signal }).catch((error) => {
+			if (!this.#abort.signal.aborted) this.#lose(slot, error);
+		}).finally(() => this.#pings.delete(slot));
+		this.#pings.set(slot, ping);
+		return ping;
+	}
 	async #validate(slot) {
 		try {
 			await slot.browser.ping({ signal: this.#abort.signal });
@@ -1296,12 +1568,19 @@ var BrowserMCPServer = class {
 			url: slot.toolset.view.url
 		});
 		this.#failure = cause;
-		if (this.#lease?.value !== slot) return;
-		const token = this.#lease;
-		this.#unmirror();
-		this.#lease = void 0;
-		this.#notice.add(slot);
-		token.destroy().catch(() => void 0);
+		for (const [holder, token] of this.#leases) {
+			if (token.value !== slot || this.#holders.get(holder.id) !== holder) continue;
+			if (holder === this.#shared) this.#unmirror();
+			this.#leases.delete(holder);
+			const notices = this.#notices.get(holder) ?? /* @__PURE__ */ new Set();
+			notices.add(slot);
+			this.#notices.set(holder, notices);
+			const drain = token.destroy();
+			const drains = this.#drains.get(holder) ?? /* @__PURE__ */ new Set();
+			drains.add(drain);
+			this.#drains.set(holder, drains);
+			drain.finally(() => drains.delete(drain)).catch(() => void 0);
+		}
 	}
 	#watch(slot, signal) {
 		const loss = Promise.withResolvers();
@@ -1374,6 +1653,7 @@ var BrowserMCPServer = class {
 				cdp: { discover: false },
 				signal: this.#abort.signal,
 				...this.#executable === void 0 ? {} : { executable: this.#executable },
+				...this.#viewport === void 0 ? {} : { viewport: this.#viewport },
 				...process.platform === "linux" && process.getuid?.() === 0 ? { args: ["--no-sandbox"] } : {}
 			});
 			await browser.connect();
@@ -1385,7 +1665,11 @@ var BrowserMCPServer = class {
 				}));
 				await (0, node_fs_promises.rename)(`${record}.tmp`, record);
 			}
-			const context = await browser.isolate({ reference: this.#reference });
+			const context = await browser.isolate({
+				reference: this.#reference,
+				downloads: { path: (0, node_path.join)(profile, "downloads") },
+				...this.#viewport === void 0 ? {} : { emulation: { viewport: this.#viewport } }
+			});
 			const page = await context.create();
 			toolset = (0, _src_core.createBrowserToolset)(page, {
 				context,
@@ -1492,29 +1776,31 @@ var BrowserMCPServer = class {
 	#issue() {
 		return `e${++this.#references}`;
 	}
-	#mirror(tool) {
-		if (this.#vocabulary.has(tool.name)) return;
+	#mirror(token, tool) {
+		if (this.#leases.get(this.#shared) !== token || this.#vocabulary.has(tool.name)) return;
 		this.#tools.add((0, _orkestrel_tool.createTool)({
 			...(0, _orkestrel_tool.toolToDefinition)(tool),
-			execute: this.#forward.bind(this, tool.name)
+			execute: this.#forward.bind(this, this.#shared, tool.name)
 		}));
 	}
-	#withdraw(tool) {
-		if (this.#vocabulary.has(tool.name)) return;
-		const current = this.#lease?.value.toolset.tools.tool(tool.name);
+	#withdraw(token, tool) {
+		if (this.#leases.get(this.#shared) !== token || this.#vocabulary.has(tool.name)) return;
+		const current = token.value.toolset.tools.tool(tool.name);
 		if (current === void 0) this.#tools.remove(tool.name);
-		else this.#mirror(current);
+		else this.#mirror(token, current);
 	}
-	#clear(tools) {
-		for (const tool of tools) this.#withdraw(tool);
+	#clear(token, tools) {
+		for (const tool of tools) this.#withdraw(token, tool);
 	}
 	#unmirror() {
-		const mirrored = this.#lease?.value.toolset.tools;
+		const mirrored = this.#mirrored;
 		if (mirrored === void 0) return;
-		for (const tool of mirrored.tools()) if (!this.#vocabulary.has(tool.name)) this.#tools.remove(tool.name);
-		mirrored.emitter.off("add", this.#added);
-		mirrored.emitter.off("remove", this.#removed);
-		mirrored.emitter.off("clear", this.#cleared);
+		this.#mirrored = void 0;
+		const tools = mirrored.token.value.toolset.tools;
+		for (const tool of tools.tools()) if (!this.#vocabulary.has(tool.name)) this.#tools.remove(tool.name);
+		tools.emitter.off("add", mirrored.added);
+		tools.emitter.off("remove", mirrored.removed);
+		tools.emitter.off("clear", mirrored.cleared);
 	}
 	#ended() {
 		return new _src_core.BrowserError("the browser session ended", "BROWSER_TOOLSET_ENDED");
@@ -1952,6 +2238,24 @@ var FileBrowserRunStore = class {
 	constructor(options) {
 		this.#files = new FileBrowserStore(options);
 	}
+	async snapshot(bytes, options) {
+		options?.signal?.throwIfAborted();
+		const owned = new Uint8Array(bytes);
+		const directory = await this.#files.allocate(this.#files.resolvePath(BROWSER_RUN_DIRECTORY), _src_core.generateBrowserRunId, options);
+		const path = this.#files.resolvePath(directory.path, "view.png");
+		try {
+			await this.#files.check(path, options);
+			options?.signal?.throwIfAborted();
+			await (0, node_fs_promises.writeFile)(path, owned, {
+				flag: "wx",
+				signal: options?.signal
+			});
+			return path;
+		} catch (error) {
+			options?.signal?.throwIfAborted();
+			throw this.#files.translateError(path, error);
+		}
+	}
 	async open(name, options) {
 		options?.signal?.throwIfAborted();
 		this.#files.validateName(name);
@@ -3006,8 +3310,11 @@ exports.BROWSER_PROCESS_EXIT_CAUSE = BROWSER_PROCESS_EXIT_CAUSE;
 exports.BROWSER_PROFILE_PREFIX = BROWSER_PROFILE_PREFIX;
 exports.BROWSER_RUN_DIRECTORY = BROWSER_RUN_DIRECTORY;
 exports.BROWSER_RUN_FILE = BROWSER_RUN_FILE;
+exports.BROWSER_SERVER_BUSY = BROWSER_SERVER_BUSY;
+exports.BROWSER_SERVER_COPY = BROWSER_SERVER_COPY;
 exports.BROWSER_SERVER_CRASH = BROWSER_SERVER_CRASH;
 exports.BROWSER_SERVER_EXHAUSTED = BROWSER_SERVER_EXHAUSTED;
+exports.BROWSER_SERVER_HOLDER = BROWSER_SERVER_HOLDER;
 exports.BROWSER_SERVER_LAUNCH = BROWSER_SERVER_LAUNCH;
 exports.BROWSER_SERVER_OPTIONS = BROWSER_SERVER_OPTIONS;
 exports.BROWSER_SERVER_POOL_LIMIT = BROWSER_SERVER_POOL_LIMIT;
@@ -3061,6 +3368,7 @@ exports.normalizeExecutablePath = normalizeExecutablePath;
 exports.parseBrowserEngine = parseBrowserEngine;
 exports.parseBrowserLockEntry = parseBrowserLockEntry;
 exports.parseBrowserProfileRecord = parseBrowserProfileRecord;
+exports.parseBrowserViewport = parseBrowserViewport;
 exports.probePathNames = probePathNames;
 exports.probeProcess = probeProcess;
 exports.readBrowserEndpoint = readBrowserEndpoint;