@anvia/browser 1.0.7 → 1.0.10

package/dist/index.js

@@ -1,82 +1,680 @@
-// src/docker-browser.ts
+// src/docker-browser-client.ts
 import { fileURLToPath } from "url";
 
-// src/connection.ts
-import { randomUUID } from "crypto";
-import { chromium } from "playwright-core";
+// src/automation-client.ts
+import { fork } from "child_process";
+
+// src/automation-protocol.ts
+function isAutomationResponse(value) {
+  if (!isRecord(value)) return false;
+  switch (value.kind) {
+    case "event":
+      return value.event === "disconnected";
+    case "cancelled":
+      return isRequestId(value.id);
+    case "response":
+      if (!isRequestId(value.id) || typeof value.ok !== "boolean") return false;
+      return value.ok ? Object.hasOwn(value, "value") : isSerializedError(value.error);
+    default:
+      return false;
+  }
+}
+function isSerializedError(value) {
+  return isRecord(value) && typeof value.name === "string" && typeof value.message === "string" && (value.stack === void 0 || typeof value.stack === "string") && (value.code === void 0 || typeof value.code === "string");
+}
+function isRequestId(value) {
+  return Number.isSafeInteger(value) && value > 0;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 
 // src/errors.ts
+var defaults = {
+  action_timeout: { retryable: true, recovery: "retry" },
+  agent_action_busy: { retryable: true, recovery: "retry" },
+  cancelled: { retryable: true, recovery: "retry" },
+  connection_closed: { retryable: true, recovery: "reconnect" },
+  connection_timeout: { retryable: true, recovery: "reconnect" },
+  human_control_conflict: { retryable: true, recovery: "retry" },
+  human_controlled: { retryable: true, recovery: "retry" },
+  invalid_state: { retryable: false, recovery: "none" },
+  lifecycle_timeout: { retryable: true, recovery: "retry" },
+  navigation_blocked: { retryable: false, recovery: "none" },
+  not_ready: { retryable: true, recovery: "retry" },
+  readiness_timeout: { retryable: true, recovery: "retry" },
+  runtime_destroyed: { retryable: false, recovery: "recreate" },
+  startup_failed: { retryable: true, recovery: "recreate" },
+  tool_failed: { retryable: true, recovery: "retry" },
+  transport_failure: { retryable: true, recovery: "reconnect" }
+};
 var BrowserError = class extends Error {
-  constructor(message, code, options) {
+  constructor(message, code, options = {}) {
     super(message, options);
     this.code = code;
     this.name = "BrowserError";
+    this.retryable = options.retryable ?? defaults[code].retryable;
+    this.recovery = options.recovery ?? defaults[code].recovery;
+    this.capability = options.capability;
+    this.phase = options.phase;
   }
   code;
+  retryable;
+  recovery;
+  capability;
+  phase;
+};
+function cancellationError(reason, phase) {
+  return new BrowserError("Browser operation was cancelled by the caller.", "cancelled", {
+    cause: reason,
+    phase
+  });
+}
+
+// src/automation-client.ts
+var cancellationCleanupTimeoutMs = 5e3;
+var workerTerminationTimeoutMs = 3e3;
+var maxWorkerStderrChars = 32768;
+var AutomationWorkerClient = class _AutomationWorkerClient {
+  child;
+  pending = /* @__PURE__ */ new Map();
+  disconnectedListeners = /* @__PURE__ */ new Set();
+  nextId = 1;
+  isClosed = false;
+  disconnecting = false;
+  termination;
+  workerStderr = "";
+  onStderrData = (chunk) => {
+    this.workerStderr = `${this.workerStderr}${chunk}`.slice(-maxWorkerStderrChars);
+  };
+  onStderrError = () => {
+  };
+  onMessage = (message) => {
+    try {
+      this.handleMessage(message);
+    } catch (error) {
+      this.handleExit(
+        new BrowserError(
+          "Browser automation worker sent an invalid response.",
+          "transport_failure",
+          {
+            cause: error,
+            phase: "automation-worker"
+          }
+        )
+      );
+      void this.terminate().catch(() => void 0);
+    }
+  };
+  onError = (error) => {
+    this.handleExit(error);
+    void this.terminate().catch(() => void 0);
+  };
+  onExit = (code, signal) => {
+    const diagnostics = this.workerStderr.trim();
+    this.handleExit(
+      new Error(
+        `Browser automation worker exited: code=${code ?? "null"} signal=${signal ?? "null"}${diagnostics.length === 0 ? "" : `
+${diagnostics}`}`
+      )
+    );
+  };
+  constructor(factory) {
+    this.child = factory();
+    this.child.stderr?.setEncoding("utf8");
+    this.child.stderr?.on("data", this.onStderrData);
+    this.child.stderr?.on("error", this.onStderrError);
+    this.child.on("message", this.onMessage);
+    this.child.on("error", this.onError);
+    this.child.once("exit", this.onExit);
+  }
+  static async connect(options) {
+    assertPositiveSafeInteger(options.timeoutMs, "timeoutMs");
+    if (options.abortSignal?.aborted) {
+      throw cancellationError(options.abortSignal.reason, "connect");
+    }
+    let client;
+    try {
+      client = new _AutomationWorkerClient(options.workerFactory ?? spawnAutomationWorker);
+    } catch (error) {
+      throw new BrowserError(
+        "Unable to start the browser automation worker.",
+        "transport_failure",
+        {
+          cause: error,
+          phase: "connect",
+          recovery: "reconnect"
+        }
+      );
+    }
+    const timeoutController = new AbortController();
+    const timer = setTimeout(
+      () => timeoutController.abort(
+        new BrowserError(
+          "Browser connection did not initialize before the timeout.",
+          "connection_timeout",
+          { phase: "connect" }
+        )
+      ),
+      options.timeoutMs
+    );
+    timer.unref?.();
+    const abortSignal = options.abortSignal === void 0 ? timeoutController.signal : AbortSignal.any([options.abortSignal, timeoutController.signal]);
+    try {
+      await client.command(
+        {
+          method: "connect",
+          params: { endpointUrl: options.endpointUrl, timeoutMs: options.timeoutMs }
+        },
+        { abortSignal, phase: "connect" }
+      );
+      return client;
+    } catch (error) {
+      await client.terminate();
+      if (options.abortSignal?.aborted) {
+        throw cancellationError(options.abortSignal.reason, "connect");
+      }
+      if (timeoutController.signal.aborted) throw timeoutController.signal.reason;
+      if (error instanceof Error && (error.name === "TimeoutError" || /timeout/i.test(error.message))) {
+        throw new BrowserError(
+          "Browser connection did not initialize before the timeout.",
+          "connection_timeout",
+          { cause: error, phase: "connect" }
+        );
+      }
+      throw new BrowserError("Unable to initialize browser automation.", "transport_failure", {
+        cause: error,
+        phase: "connect"
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  get closed() {
+    return this.isClosed || this.child.exitCode !== null || this.child.signalCode !== null;
+  }
+  command(command, options) {
+    if (this.closed) {
+      return Promise.reject(
+        new BrowserError("Browser automation connection is closed.", "connection_closed", {
+          phase: options.phase
+        })
+      );
+    }
+    if (options.abortSignal?.aborted) {
+      return Promise.reject(this.abortError(options.abortSignal, options.phase));
+    }
+    const id = this.nextId++;
+    return new Promise((resolve, reject) => {
+      const pending = {
+        state: "active",
+        resolve: (value) => resolve(value),
+        reject
+      };
+      if (options.abortSignal !== void 0) {
+        pending.abortSignal = options.abortSignal;
+        pending.abort = () => this.cancelRequest(id, pending, options);
+        options.abortSignal.addEventListener("abort", pending.abort, { once: true });
+      }
+      this.pending.set(id, pending);
+      const request = { kind: "request", id, ...command };
+      try {
+        this.child.send(request, (error) => {
+          if (error == null) return;
+          this.rejectSend(options.phase, error);
+        });
+      } catch (error) {
+        this.rejectSend(options.phase, error);
+      }
+    });
+  }
+  async disconnect(options = {}) {
+    if (this.termination !== void 0) return this.termination;
+    this.disconnecting = true;
+    const timeoutMs = options.timeoutMs ?? 1e4;
+    const timeoutController = new AbortController();
+    const timer = setTimeout(
+      () => timeoutController.abort(
+        new BrowserError("Browser disconnect timed out.", "connection_timeout", {
+          phase: "disconnect"
+        })
+      ),
+      timeoutMs
+    );
+    timer.unref?.();
+    const abortSignal = options.abortSignal === void 0 ? timeoutController.signal : AbortSignal.any([options.abortSignal, timeoutController.signal]);
+    try {
+      if (!this.closed) {
+        await this.command(
+          { method: "disconnect", params: {} },
+          { abortSignal, phase: "disconnect" }
+        );
+      }
+    } catch (error) {
+      if (options.abortSignal?.aborted) {
+        throw cancellationError(options.abortSignal.reason, "disconnect");
+      }
+      if (timeoutController.signal.aborted) throw timeoutController.signal.reason;
+      if (!this.closed) throw error;
+    } finally {
+      clearTimeout(timer);
+      await this.terminate();
+    }
+  }
+  onDisconnected(listener) {
+    if (this.closed) {
+      queueMicrotask(() => {
+        try {
+          listener();
+        } catch {
+        }
+      });
+      return () => void 0;
+    }
+    this.disconnectedListeners.add(listener);
+    return () => this.disconnectedListeners.delete(listener);
+  }
+  async terminate() {
+    if (this.termination !== void 0) return this.termination;
+    this.termination = this.performTerminate();
+    return this.termination;
+  }
+  async performTerminate() {
+    this.isClosed = true;
+    if (this.child.exitCode !== null || this.child.signalCode !== null) return;
+    const exited = new Promise((resolve) => this.child.once("exit", () => resolve()));
+    this.child.kill("SIGTERM");
+    let forceTimer;
+    await Promise.race([
+      exited,
+      new Promise((resolve) => {
+        forceTimer = setTimeout(() => {
+          this.child.kill("SIGKILL");
+          resolve();
+        }, workerTerminationTimeoutMs);
+        forceTimer.unref?.();
+      })
+    ]);
+    if (forceTimer !== void 0) clearTimeout(forceTimer);
+    if (this.child.exitCode === null && this.child.signalCode === null) await exited;
+  }
+  cancelRequest(id, pending, options) {
+    if (pending.state !== "active") return;
+    pending.state = "cancelling";
+    pending.abortError = this.abortError(pending.abortSignal, options.phase);
+    if (options.cancelOperation === true && this.child.connected) {
+      try {
+        this.child.send({ kind: "cancel", id }, (error) => {
+          if (error !== null) void this.terminate().catch(() => void 0);
+        });
+      } catch {
+        void this.terminate().catch(() => void 0);
+        return;
+      }
+      pending.cleanupTimer = setTimeout(() => {
+        void this.terminate().catch(() => void 0);
+      }, cancellationCleanupTimeoutMs);
+      pending.cleanupTimer.unref?.();
+      return;
+    }
+    void this.terminate().catch(() => void 0);
+  }
+  abortError(abortSignal, phase) {
+    return abortSignal.reason instanceof BrowserError ? abortSignal.reason : cancellationError(abortSignal.reason, phase);
+  }
+  handleMessage(message) {
+    if (!isAutomationResponse(message)) {
+      throw new TypeError("Invalid browser automation worker response.");
+    }
+    if (message.kind === "event") {
+      if (!this.disconnecting) {
+        this.handleExit(
+          new BrowserError("Browser disconnected from CDP.", "connection_closed", {
+            phase: "automation-event"
+          })
+        );
+        void this.terminate().catch(() => void 0);
+      }
+      return;
+    }
+    const pending = this.pending.get(message.id);
+    if (pending === void 0) return;
+    if (message.kind === "cancelled") {
+      if (pending.state === "cancelling") {
+        this.settle(message.id, pending, () => pending.reject(pending.abortError));
+      }
+      return;
+    }
+    if (pending.state === "cancelling") return;
+    this.settle(message.id, pending, () => {
+      if (message.ok) pending.resolve(message.value);
+      else pending.reject(deserializeError(message.error));
+    });
+  }
+  handleExit(cause) {
+    if (this.isClosed && this.pending.size === 0) {
+      this.cleanupChildListeners();
+      return;
+    }
+    this.isClosed = true;
+    const error = cause instanceof BrowserError ? cause : new BrowserError("Browser automation worker terminated.", "transport_failure", {
+      cause,
+      phase: "automation-worker"
+    });
+    for (const [id, pending] of this.pending) {
+      this.settle(
+        id,
+        pending,
+        () => pending.reject(pending.state === "cancelling" ? pending.abortError : error)
+      );
+    }
+    const listeners = [...this.disconnectedListeners];
+    this.disconnectedListeners.clear();
+    for (const listener of listeners) {
+      try {
+        listener();
+      } catch {
+      }
+    }
+    this.cleanupChildListeners();
+  }
+  cleanupChildListeners() {
+    this.child.off("message", this.onMessage);
+    this.child.off("exit", this.onExit);
+    this.child.stderr?.off("data", this.onStderrData);
+  }
+  rejectSend(phase, cause) {
+    this.handleExit(
+      new BrowserError("Unable to send browser automation command.", "transport_failure", {
+        cause,
+        phase
+      })
+    );
+    void this.terminate().catch(() => void 0);
+  }
+  settle(id, pending, callback) {
+    if (this.pending.get(id) !== pending) return;
+    this.pending.delete(id);
+    if (pending.cleanupTimer !== void 0) clearTimeout(pending.cleanupTimer);
+    if (pending.abort !== void 0) {
+      pending.abortSignal?.removeEventListener("abort", pending.abort);
+    }
+    callback();
+  }
+};
+function spawnAutomationWorker() {
+  return fork(automationWorkerUrl(), [], {
+    execArgv: [],
+    serialization: "advanced",
+    stdio: ["ignore", "ignore", "pipe", "ipc"]
+  });
+}
+function automationWorkerUrl() {
+  return import.meta.url.endsWith("/src/automation-client.ts") ? new URL("../dist/automation-worker.js", import.meta.url) : new URL("./automation-worker.js", import.meta.url);
+}
+function deserializeError(value) {
+  const error = new Error(value.message);
+  error.name = value.name;
+  if (value.stack !== void 0) error.stack = value.stack;
+  if (value.code !== void 0) Object.assign(error, { code: value.code });
+  return error;
+}
+function assertPositiveSafeInteger(value, name) {
+  if (!Number.isSafeInteger(value) || value <= 0 || value > 2147483647) {
+    throw new RangeError(`${name} must be a positive integer no greater than 2147483647.`);
+  }
+}
+
+// src/scheduler.ts
+var ResourceScheduler = class {
+  resources = /* @__PURE__ */ new Map();
+  readyResources = [];
+  activeTasks = /* @__PURE__ */ new Set();
+  serial;
+  maxConcurrentResources;
+  maxQueuedActions;
+  activeResources = 0;
+  queuedActions = 0;
+  closedError;
+  constructor(options) {
+    this.serial = options.mode === "serial";
+    this.maxConcurrentResources = options.maxConcurrentResources;
+    this.maxQueuedActions = options.maxQueuedActions;
+  }
+  run(resourceKey, abortSignal, operation) {
+    if (this.closedError !== void 0) return Promise.reject(this.closedError);
+    if (abortSignal?.aborted) {
+      return Promise.reject(abortReason(abortSignal, "agent-action-queue"));
+    }
+    if (this.queuedActions >= this.maxQueuedActions) {
+      return Promise.reject(
+        new BrowserError("Browser action queue capacity was reached.", "agent_action_busy", {
+          phase: "agent-action-queue"
+        })
+      );
+    }
+    const key = this.serial ? "browser" : resourceKey;
+    let resource = this.resources.get(key);
+    if (resource === void 0) {
+      resource = { running: false, ready: false, tasks: [] };
+      this.resources.set(key, resource);
+    }
+    return new Promise((resolve, reject) => {
+      const task = {
+        controller: new AbortController(),
+        operation,
+        resolve,
+        reject,
+        ...abortSignal === void 0 ? {} : { abortSignal }
+      };
+      if (abortSignal !== void 0) {
+        task.abort = () => {
+          const current = this.resources.get(key);
+          const index = current?.tasks.indexOf(task) ?? -1;
+          if (index === -1) return;
+          current?.tasks.splice(index, 1);
+          this.queuedActions -= 1;
+          abortSignal.removeEventListener("abort", task.abort);
+          reject(abortReason(abortSignal, "agent-action-queue"));
+          this.deleteIdleResource(key, current);
+        };
+        abortSignal.addEventListener("abort", task.abort, { once: true });
+      }
+      resource.tasks.push(task);
+      this.queuedActions += 1;
+      this.markReady(key, resource);
+      this.pump();
+    });
+  }
+  close(error = new BrowserError("Browser connection is closed.", "connection_closed")) {
+    if (this.closedError !== void 0) return;
+    this.closedError = error;
+    for (const task of this.activeTasks) task.controller.abort(error);
+    for (const [key, resource] of this.resources) {
+      for (const task of resource.tasks.splice(0)) {
+        this.queuedActions -= 1;
+        if (task.abort !== void 0) task.abortSignal?.removeEventListener("abort", task.abort);
+        task.reject(error);
+      }
+      resource.ready = false;
+      if (!resource.running) this.resources.delete(key);
+    }
+    this.readyResources.length = 0;
+  }
+  markReady(key, resource) {
+    if (resource.running || resource.ready || resource.tasks.length === 0) return;
+    resource.ready = true;
+    this.readyResources.push(key);
+  }
+  pump() {
+    while (this.closedError === void 0 && this.activeResources < this.maxConcurrentResources && this.readyResources.length > 0) {
+      const key = this.readyResources.shift();
+      if (key === void 0) return;
+      const resource = this.resources.get(key);
+      if (resource === void 0 || resource.running || resource.tasks.length === 0) continue;
+      resource.ready = false;
+      const task = resource.tasks.shift();
+      if (task === void 0) continue;
+      this.queuedActions -= 1;
+      if (task.abort !== void 0) task.abortSignal?.removeEventListener("abort", task.abort);
+      resource.running = true;
+      this.activeResources += 1;
+      this.activeTasks.add(task);
+      const effectiveSignal = task.abortSignal === void 0 ? task.controller.signal : AbortSignal.any([task.abortSignal, task.controller.signal]);
+      let operation;
+      try {
+        operation = task.operation(effectiveSignal);
+      } catch (error) {
+        operation = Promise.reject(error);
+      }
+      void operation.then(task.resolve, task.reject).finally(() => {
+        this.activeTasks.delete(task);
+        resource.running = false;
+        this.activeResources -= 1;
+        this.markReady(key, resource);
+        this.deleteIdleResource(key, resource);
+        this.pump();
+      });
+    }
+  }
+  deleteIdleResource(key, resource) {
+    if (resource !== void 0 && !resource.running && resource.tasks.length === 0) {
+      this.resources.delete(key);
+    }
+  }
+};
+var AsyncMutex = class {
+  waiters = [];
+  locked = false;
+  closedError;
+  async run(abortSignal, operation) {
+    const release = await this.acquire(abortSignal);
+    try {
+      return await operation();
+    } finally {
+      release();
+    }
+  }
+  close(error = new BrowserError("Browser connection is closed.", "connection_closed")) {
+    if (this.closedError !== void 0) return;
+    this.closedError = error;
+    for (const waiter of this.waiters.splice(0)) {
+      if (waiter.abort !== void 0) {
+        waiter.abortSignal?.removeEventListener("abort", waiter.abort);
+      }
+      waiter.reject(error);
+    }
+  }
+  acquire(abortSignal) {
+    if (this.closedError !== void 0) return Promise.reject(this.closedError);
+    if (abortSignal?.aborted) {
+      return Promise.reject(abortReason(abortSignal, "browser-resource-lock"));
+    }
+    if (!this.locked) {
+      this.locked = true;
+      return Promise.resolve(this.releaseCallback());
+    }
+    return new Promise((resolve, reject) => {
+      const waiter = {
+        resolve,
+        reject,
+        ...abortSignal === void 0 ? {} : { abortSignal }
+      };
+      if (abortSignal !== void 0) {
+        waiter.abort = () => {
+          const index = this.waiters.indexOf(waiter);
+          if (index === -1) return;
+          this.waiters.splice(index, 1);
+          reject(abortReason(abortSignal, "browser-resource-lock"));
+        };
+        abortSignal.addEventListener("abort", waiter.abort, { once: true });
+      }
+      this.waiters.push(waiter);
+    });
+  }
+  releaseCallback() {
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      const waiter = this.waiters.shift();
+      if (waiter === void 0) {
+        this.locked = false;
+        return;
+      }
+      if (waiter.abort !== void 0) {
+        waiter.abortSignal?.removeEventListener("abort", waiter.abort);
+      }
+      waiter.resolve(this.releaseCallback());
+    };
+  }
 };
+function abortReason(abortSignal, phase) {
+  return abortSignal.reason instanceof BrowserError ? abortSignal.reason : cancellationError(abortSignal.reason, phase);
+}
 
 // src/connection.ts
+var defaultConnectionTimeoutMs = 3e4;
+var defaultActionTimeoutMs = 1e4;
+var defaultMaxConcurrentTabs = 8;
+var defaultMaxQueuedActions = 1e3;
+var maxClosedTabTombstones = 1e4;
+var maxTimerMs = 2147483647;
 async function connectPlaywrightBrowser(options) {
+  const timeoutMs = options.timeoutMs ?? defaultConnectionTimeoutMs;
+  assertPositiveSafeInteger2(timeoutMs, "timeoutMs");
   options.abortSignal?.throwIfAborted();
-  const browser = await chromium.connectOverCDP(options.endpointUrl);
-  if (options.abortSignal?.aborted) {
-    await browser.close().catch(() => void 0);
-    options.abortSignal.throwIfAborted();
-  }
-  return new PlaywrightBrowserConnectionImpl(browser, options.control);
+  const backend = await AutomationWorkerClient.connect({
+    endpointUrl: options.endpointUrl,
+    timeoutMs,
+    ...options.abortSignal === void 0 ? {} : { abortSignal: options.abortSignal },
+    ...options.workerFactory === void 0 ? {} : { workerFactory: options.workerFactory }
+  });
+  return new PlaywrightBrowserConnectionImpl({
+    backend,
+    control: options.control,
+    scheduling: options.scheduling,
+    ...options.onClosed === void 0 ? {} : { onClosed: options.onClosed }
+  });
 }
 var PlaywrightBrowserConnectionImpl = class {
-  browser;
+  backend;
   control;
-  tabIds = /* @__PURE__ */ new WeakMap();
-  selected;
-  isClosed = false;
-  actionTail = Promise.resolve();
+  scheduler;
+  compatibilityMutex = new AsyncMutex();
+  contextMutex = new AsyncMutex();
+  closingTabs = /* @__PURE__ */ new Set();
+  closedTabs = /* @__PURE__ */ new Set();
   navigationPolicyKey;
   navigationGuard = Promise.resolve();
-  constructor(browser, control) {
-    this.browser = browser;
-    this.control = control;
-    this.selected = this.pages()[0];
-    this.browser.once("disconnected", () => {
-      this.isClosed = true;
-    });
+  isClosed = false;
+  disconnectCompleted = false;
+  disconnectPromise;
+  removeDisconnectedListener;
+  onClosed;
+  constructor(options) {
+    this.backend = options.backend;
+    this.control = options.control;
+    this.onClosed = options.onClosed;
+    const scheduling = normalizeScheduling(options.scheduling);
+    this.scheduler = new ResourceScheduler(scheduling);
+    this.removeDisconnectedListener = this.backend.onDisconnected(() => this.markClosed());
   }
   get closed() {
-    return this.isClosed || !this.browser.isConnected();
-  }
-  async listTabs() {
-    return this.runAction(void 0, () => this.tabSummaries());
-  }
-  async tabSummaries() {
-    return Object.freeze(
-      await Promise.all(
-        this.pages().map(
-          async (page) => Object.freeze({
-            id: this.idFor(page),
-            title: await page.title(),
-            url: page.url(),
-            selected: page === this.selected
-          })
-        )
+    return this.isClosed || this.backend.closed;
+  }
+  async listTabs(options = {}) {
+    assertOptionsObject(options);
+    return this.runContextAction(
+      options.abortSignal,
+      options.timeoutMs ?? defaultActionTimeoutMs,
+      "list-tabs",
+      (signal) => this.backend.command(
+        { method: "listTabs", params: {} },
+        { abortSignal: signal, cancelOperation: true, phase: "list-tabs" }
       )
     );
   }
-  async runAction(abortSignal, operation) {
-    const previous = this.actionTail;
-    let release;
-    this.actionTail = new Promise((resolve) => {
-      release = resolve;
-    });
-    await previous;
-    try {
-      this.assertOpen();
-      await this.navigationGuard;
-      return await this.control.runAgentAction(() => this.withAbort(abortSignal, operation));
-    } finally {
-      release?.();
-    }
-  }
   setNavigationPolicy(policy) {
     this.assertOpen();
     const key = JSON.stringify(policy);
@@ -87,141 +685,438 @@ var PlaywrightBrowserConnectionImpl = class {
       return;
     }
     this.navigationPolicyKey = key;
-    const routeHandler = (route) => enforceNavigationPolicy(route, policy);
-    this.navigationGuard = Promise.all(
-      this.browser.contexts().map((context) => context.route("**/*", routeHandler))
-    ).then(() => void 0);
+    const installation = this.withActionTimeout(
+      void 0,
+      defaultActionTimeoutMs,
+      "navigation-policy",
+      (signal) => this.scheduler.run(
+        "browser-context",
+        signal,
+        (scheduledSignal) => this.contextMutex.run(
+          scheduledSignal,
+          () => this.control.runAgentAction(async () => {
+            try {
+              await this.backend.command(
+                { method: "setNavigationPolicy", params: { policy } },
+                {
+                  abortSignal: scheduledSignal,
+                  cancelOperation: true,
+                  phase: "navigation-policy"
+                }
+              );
+            } catch (error) {
+              throw normalizeAutomationError(error, "navigation-policy");
+            }
+          })
+        )
+      )
+    );
+    this.navigationGuard = installation.catch(async (error) => {
+      let cleanupError;
+      try {
+        await this.disconnect();
+      } catch (caught) {
+        cleanupError = caught;
+      }
+      throw new BrowserError(
+        "Unable to install the browser navigation policy.",
+        "transport_failure",
+        {
+          cause: combineCleanupError(error, cleanupError),
+          phase: "navigation-policy"
+        }
+      );
+    });
     void this.navigationGuard.catch(() => void 0);
   }
-  selectedPage() {
-    this.assertOpen();
-    if (this.selected !== void 0 && !this.selected.isClosed()) return this.selected;
-    const page = this.pages()[0];
-    if (page === void 0) {
-      throw new BrowserError("Browser has no open tabs.", "invalid_state");
-    }
-    this.selected = page;
-    return page;
-  }
-  async openTab() {
-    const context = this.browser.contexts()[0];
-    if (context === void 0) {
-      throw new BrowserError("Browser has no CDP context.", "invalid_state");
-    }
-    const page = await context.newPage();
-    this.selected = page;
-    this.idFor(page);
-    return page;
-  }
-  selectTab(id) {
-    const page = this.pageFor(id);
-    this.selected = page;
-    return page;
-  }
-  async closeTab(id) {
-    const page = this.pageFor(id);
-    await page.close();
-    if (page === this.selected) this.selected = this.pages()[0];
-  }
-  idFor(page) {
-    const existing = this.tabIds.get(page);
-    if (existing !== void 0) return existing;
-    const id = randomUUID();
-    this.tabIds.set(page, id);
-    return id;
-  }
-  async disconnect() {
-    if (this.isClosed) return;
-    this.isClosed = true;
-    await this.browser.close().catch(() => void 0);
+  async openTab(abortSignal, timeoutMs) {
+    return this.withActionTimeout(
+      abortSignal,
+      timeoutMs,
+      "open-tab",
+      (signal) => this.compatibilityMutex.run(
+        signal,
+        () => this.runContextActionScheduled(
+          signal,
+          "open-tab",
+          (scheduledSignal) => this.backend.command(
+            { method: "openTab", params: {} },
+            { abortSignal: scheduledSignal, cancelOperation: true, phase: "open-tab" }
+          )
+        )
+      )
+    );
+  }
+  async selectTab(tabId, abortSignal, timeoutMs) {
+    this.assertTabUsable(tabId);
+    return this.withActionTimeout(
+      abortSignal,
+      timeoutMs,
+      "select-tab",
+      (signal) => this.compatibilityMutex.run(
+        signal,
+        () => this.runContextActionScheduled(
+          signal,
+          "select-tab",
+          (scheduledSignal) => this.backend.command(
+            { method: "selectTab", params: { tabId } },
+            { abortSignal: scheduledSignal, cancelOperation: true, phase: "select-tab" }
+          )
+        )
+      )
+    );
+  }
+  async closeTab(tabId, abortSignal, timeoutMs) {
+    this.assertTabUsable(tabId);
+    this.closingTabs.add(tabId);
+    let closed = false;
+    try {
+      const result = await this.withActionTimeout(
+        abortSignal,
+        timeoutMs,
+        "close-tab",
+        (signal) => this.scheduler.run(`tab:${tabId}`, signal, (scheduledSignal) => {
+          return this.contextMutex.run(
+            scheduledSignal,
+            () => this.control.runAgentAction(async () => {
+              try {
+                return await this.backend.command(
+                  { method: "closeTab", params: { tabId } },
+                  { abortSignal: scheduledSignal, cancelOperation: true, phase: "close-tab" }
+                );
+              } catch (error) {
+                throw normalizeAutomationError(error, "close-tab");
+              }
+            })
+          );
+        })
+      );
+      closed = true;
+      return result;
+    } finally {
+      this.closingTabs.delete(tabId);
+      if (closed && !this.isClosed) this.rememberClosedTab(tabId);
+    }
+  }
+  async runTabCommand(options) {
+    return this.withActionTimeout(
+      options.abortSignal,
+      options.timeoutMs,
+      options.phase,
+      async (signal) => {
+        if (options.tabId !== void 0) {
+          this.assertTabUsable(options.tabId);
+          return this.runScheduledTabCommand(options.tabId, options, signal);
+        }
+        return this.compatibilityMutex.run(signal, async () => {
+          const tabId = await this.selectedTabId(signal);
+          this.assertTabUsable(tabId);
+          return this.runScheduledTabCommand(tabId, options, signal);
+        });
+      }
+    );
+  }
+  async disconnect(options = {}) {
+    assertOptionsObject(options);
+    if (options.timeoutMs !== void 0) assertPositiveSafeInteger2(options.timeoutMs, "timeoutMs");
+    if (this.disconnectCompleted) return;
+    if (options.abortSignal?.aborted) {
+      throw cancellationError(options.abortSignal.reason, "disconnect");
+    }
+    if (this.disconnectPromise !== void 0) {
+      return waitForSharedDisconnect(this.disconnectPromise, options);
+    }
+    this.markClosed();
+    const promise = this.backend.disconnect(options);
+    this.disconnectPromise = promise;
+    try {
+      await promise;
+      this.disconnectCompleted = true;
+    } finally {
+      if (this.disconnectPromise === promise) this.disconnectPromise = void 0;
+    }
   }
   async [Symbol.asyncDispose]() {
     await this.disconnect();
   }
-  pages() {
-    return this.browser.contexts().flatMap((context) => context.pages());
+  async runScheduledTabCommand(tabId, options, abortSignal) {
+    return this.scheduler.run(
+      `tab:${tabId}`,
+      abortSignal,
+      (scheduledSignal) => this.control.runAgentAction(async () => {
+        await waitForOwnedPromise(this.navigationGuard, scheduledSignal);
+        try {
+          return await this.backend.command(options.command(tabId), {
+            abortSignal: scheduledSignal,
+            cancelOperation: true,
+            phase: options.phase
+          });
+        } catch (error) {
+          throw normalizeAutomationError(error, options.phase);
+        }
+      })
+    );
+  }
+  async selectedTabId(abortSignal) {
+    const tabs = await this.runContextActionScheduled(
+      abortSignal,
+      "selected-tab-lookup",
+      (signal) => this.backend.command(
+        { method: "listTabs", params: {} },
+        { abortSignal: signal, cancelOperation: true, phase: "selected-tab-lookup" }
+      )
+    );
+    const selected = tabs.find((tab) => tab.selected) ?? tabs[0];
+    if (selected === void 0) {
+      throw new BrowserError("Browser has no open tabs.", "invalid_state", {
+        phase: "selected-tab-lookup"
+      });
+    }
+    return selected.id;
+  }
+  runContextAction(abortSignal, timeoutMs, phase, operation) {
+    return this.withActionTimeout(
+      abortSignal,
+      timeoutMs,
+      phase,
+      (signal) => this.runContextActionScheduled(signal, phase, operation)
+    );
+  }
+  runContextActionScheduled(abortSignal, phase, operation) {
+    return this.scheduler.run(
+      "browser-context",
+      abortSignal,
+      (scheduledSignal) => this.contextMutex.run(
+        scheduledSignal,
+        () => this.control.runAgentAction(async () => {
+          this.assertOpen();
+          await waitForOwnedPromise(this.navigationGuard, scheduledSignal);
+          try {
+            return await operation(scheduledSignal);
+          } catch (error) {
+            throw normalizeAutomationError(error, phase);
+          }
+        })
+      )
+    );
+  }
+  async withActionTimeout(abortSignal, timeoutMs, phase, operation) {
+    assertPositiveSafeInteger2(timeoutMs, "timeoutMs");
+    if (abortSignal?.aborted) throw cancellationError(abortSignal.reason, phase);
+    const timeoutController = new AbortController();
+    const timer = setTimeout(
+      () => timeoutController.abort(
+        new BrowserError("Browser action timed out.", "action_timeout", { phase })
+      ),
+      timeoutMs
+    );
+    timer.unref?.();
+    const effectiveSignal = abortSignal === void 0 ? timeoutController.signal : AbortSignal.any([abortSignal, timeoutController.signal]);
+    try {
+      const value = await operation(effectiveSignal);
+      if (abortSignal?.aborted) throw cancellationError(abortSignal.reason, phase);
+      if (timeoutController.signal.aborted) throw timeoutController.signal.reason;
+      return value;
+    } catch (error) {
+      if (abortSignal?.aborted) throw cancellationError(abortSignal.reason, phase);
+      if (timeoutController.signal.aborted) throw timeoutController.signal.reason;
+      throw error;
+    } finally {
+      clearTimeout(timer);
+    }
   }
-  pageFor(id) {
-    const page = this.pages().find((candidate) => this.idFor(candidate) === id);
-    if (page === void 0) {
-      throw new BrowserError(`Browser tab does not exist: ${id}`, "invalid_state");
+  assertTabUsable(tabId) {
+    this.assertOpen();
+    if (this.closingTabs.has(tabId) || this.closedTabs.has(tabId)) {
+      throw new BrowserError(`Browser tab is closing or closed: ${tabId}`, "invalid_state", {
+        phase: "tab-lookup"
+      });
     }
-    return page;
+  }
+  rememberClosedTab(tabId) {
+    this.closedTabs.add(tabId);
+    if (this.closedTabs.size <= maxClosedTabTombstones) return;
+    const oldest = this.closedTabs.values().next().value;
+    if (oldest !== void 0) this.closedTabs.delete(oldest);
   }
   assertOpen() {
-    if (this.closed) throw new BrowserError("Browser connection is closed.", "connection_closed");
+    if (this.closed) {
+      throw new BrowserError("Browser connection is closed.", "connection_closed");
+    }
   }
-  async withAbort(abortSignal, operation) {
-    abortSignal?.throwIfAborted();
-    if (abortSignal === void 0) return operation();
-    return new Promise((resolve, reject) => {
-      let settled = false;
-      const finish = (callback) => {
-        if (settled) return;
-        settled = true;
-        abortSignal.removeEventListener("abort", onAbort);
-        callback();
-      };
-      const onAbort = () => {
-        void this.disconnect().finally(() => finish(() => reject(abortSignal.reason)));
-      };
-      abortSignal.addEventListener("abort", onAbort, { once: true });
-      void operation().then(
-        (value) => finish(() => resolve(value)),
-        (error) => finish(() => reject(error))
-      );
-    });
+  markClosed() {
+    if (this.isClosed) return;
+    this.isClosed = true;
+    const error = new BrowserError("Browser connection is closed.", "connection_closed");
+    this.scheduler.close(error);
+    this.compatibilityMutex.close(error);
+    this.contextMutex.close(error);
+    this.closingTabs.clear();
+    this.closedTabs.clear();
+    this.removeDisconnectedListener?.();
+    this.removeDisconnectedListener = void 0;
+    this.onClosed?.(this);
   }
 };
-async function enforceNavigationPolicy(route, policy) {
-  const request = route.request();
-  const frame = request.frame();
-  if (request.isNavigationRequest() && frame === frame.page().mainFrame() && !isNavigationAllowed(request.url(), policy)) {
-    await route.abort("blockedbyclient");
-    return;
+function normalizeScheduling(value) {
+  if (value === void 0) {
+    return {
+      mode: "serial",
+      maxConcurrentResources: 1,
+      maxQueuedActions: defaultMaxQueuedActions
+    };
   }
-  await route.continue();
-}
-function isNavigationAllowed(value, policy) {
-  let url;
-  try {
-    url = new URL(value);
-  } catch {
-    return false;
+  assertOptionsObject(value);
+  const maxQueuedActions = value.maxQueuedActions ?? defaultMaxQueuedActions;
+  assertPositiveSafeInteger2(maxQueuedActions, "scheduling.maxQueuedActions");
+  if (value.mode === "serial") {
+    return { mode: "serial", maxConcurrentResources: 1, maxQueuedActions };
   }
-  if (url.protocol !== "http:" && url.protocol !== "https:") return false;
-  if (url.username.length > 0 || url.password.length > 0) return false;
-  return policy.mode === "allow-all-http" || policy.origins.includes(url.origin);
+  if (value.mode !== "per-tab") throw new TypeError("Unsupported browser scheduling mode.");
+  const maxConcurrentResources = value.maxConcurrentTabs ?? defaultMaxConcurrentTabs;
+  assertPositiveSafeInteger2(maxConcurrentResources, "scheduling.maxConcurrentTabs");
+  return { mode: "per-tab", maxConcurrentResources, maxQueuedActions };
 }
-function asConnection(connection) {
-  if (!(connection instanceof PlaywrightBrowserConnectionImpl)) {
-    throw new TypeError("connection must be created by DockerBrowser.connect().");
+function normalizeAutomationError(error, phase) {
+  if (error instanceof BrowserError) return error;
+  if (error instanceof Error && /ERR_BLOCKED_BY_CLIENT|blockedbyclient/i.test(error.message)) {
+    return new BrowserError("Browser navigation was rejected by policy.", "navigation_blocked", {
+      cause: error,
+      phase
+    });
+  }
+  if (error instanceof Error && error.name === "TimeoutError") {
+    return new BrowserError("Browser action timed out.", "action_timeout", {
+      cause: error,
+      phase
+    });
+  }
+  if (error instanceof Error && /tab does not exist|has no open tabs|target page.*closed|page has been closed/i.test(
+    error.message
+  )) {
+    return new BrowserError(error.message, "invalid_state", { cause: error, phase });
+  }
+  if (error instanceof Error && /browser.*closed|disconnected|connection.*closed|websocket.*closed/i.test(error.message)) {
+    return new BrowserError("Browser automation connection closed.", "connection_closed", {
+      cause: error,
+      phase
+    });
+  }
+  return new BrowserError("Browser tool operation failed.", "tool_failed", {
+    cause: error,
+    phase
+  });
+}
+function assertPositiveSafeInteger2(value, name) {
+  if (!Number.isSafeInteger(value) || value <= 0 || value > maxTimerMs) {
+    throw new RangeError(`${name} must be a positive integer no greater than ${maxTimerMs}.`);
+  }
+}
+function assertOptionsObject(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new TypeError("options must be an object.");
+  }
+}
+function combineCleanupError(error, cleanupError) {
+  return cleanupError === void 0 ? error : new AggregateError([error, cleanupError], "Browser automation cleanup also failed.");
+}
+async function waitForOwnedPromise(promise, abortSignal) {
+  abortSignal.throwIfAborted();
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = (callback) => {
+      if (settled) return;
+      settled = true;
+      abortSignal.removeEventListener("abort", abort);
+      callback();
+    };
+    const abort = () => finish(() => reject(abortSignal.reason));
+    abortSignal.addEventListener("abort", abort, { once: true });
+    void promise.then(
+      (value) => finish(() => resolve(value)),
+      (error) => finish(() => reject(error))
+    );
+  });
+}
+async function waitForSharedDisconnect(promise, options) {
+  const timeoutMs = options.timeoutMs ?? 1e4;
+  assertPositiveSafeInteger2(timeoutMs, "timeoutMs");
+  if (options.abortSignal?.aborted) {
+    throw cancellationError(options.abortSignal.reason, "disconnect");
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(
+    () => controller.abort(
+      new BrowserError("Browser disconnect timed out.", "connection_timeout", {
+        phase: "disconnect"
+      })
+    ),
+    timeoutMs
+  );
+  timer.unref?.();
+  const signal = options.abortSignal === void 0 ? controller.signal : AbortSignal.any([options.abortSignal, controller.signal]);
+  try {
+    await waitForOwnedPromise(promise, signal);
+  } catch (error) {
+    if (options.abortSignal?.aborted) {
+      throw cancellationError(options.abortSignal.reason, "disconnect");
+    }
+    if (controller.signal.aborted) throw controller.signal.reason;
+    throw error;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function asConnection(connection) {
+  if (!(connection instanceof PlaywrightBrowserConnectionImpl)) {
+    throw new TypeError("connection must be created by DockerBrowser.connect().");
   }
   return connection;
 }
 
 // src/control.ts
-import { randomUUID as randomUUID2 } from "crypto";
+import { randomUUID } from "crypto";
+var defaultAcquireTimeoutMs = 3e4;
+var maxTimerMs2 = 2147483647;
 var BrowserControlState = class {
   activeAgentActions = 0;
   pendingAcquire;
   activeLease;
   humanPending = false;
   destroyed = false;
+  availability = "available";
   snapshot() {
     const lease = this.activeLease;
-    return lease === void 0 ? Object.freeze({ mode: "agent" }) : Object.freeze({
-      mode: "human",
-      ownerId: lease.ownerId,
-      expiresAt: lease.expiresAt
+    const state = lease !== void 0 ? "human" : this.humanPending ? "human-pending" : this.activeAgentActions > 0 ? "agent-active" : "agent";
+    return Object.freeze({
+      mode: lease === void 0 ? "agent" : "human",
+      state,
+      availability: this.availability,
+      activeAgentActions: this.activeAgentActions,
+      humanPending: this.humanPending,
+      ...lease === void 0 ? {} : {
+        ownerId: lease.ownerId,
+        expiresAt: lease.expiresAt
+      }
     });
   }
   async acquireHumanControl(options) {
     validateAcquireOptions(options);
     this.assertActive();
-    options.abortSignal?.throwIfAborted();
-    if (this.activeLease !== void 0 || this.humanPending) {
-      throw new BrowserError("Browser human control is already acquired.", "human_controlled");
+    if (options.abortSignal?.aborted) {
+      throw cancellationError(options.abortSignal.reason, "human-control-acquire");
+    }
+    if (this.activeLease !== void 0) {
+      throw new BrowserError("Browser human control is already acquired.", "human_controlled", {
+        phase: "human-control-acquire"
+      });
+    }
+    if (this.humanPending) {
+      throw new BrowserError(
+        "Browser human control acquisition is already pending.",
+        "human_control_conflict",
+        { phase: "human-control-acquire" }
+      );
     }
     this.humanPending = true;
     try {
@@ -232,16 +1127,30 @@ var BrowserControlState = class {
             pending.abortSignal = options.abortSignal;
             pending.abort = () => {
               if (this.pendingAcquire !== pending) return;
-              this.pendingAcquire = void 0;
-              reject(options.abortSignal?.reason);
+              this.clearPendingAcquire(pending);
+              reject(cancellationError(options.abortSignal?.reason, "human-control-acquire"));
             };
             options.abortSignal.addEventListener("abort", pending.abort, { once: true });
           }
+          pending.timer = setTimeout(() => {
+            if (this.pendingAcquire !== pending) return;
+            this.clearPendingAcquire(pending);
+            reject(
+              new BrowserError(
+                "Timed out waiting to acquire browser human control.",
+                "human_control_conflict",
+                { phase: "human-control-acquire" }
+              )
+            );
+          }, options.timeoutMs ?? defaultAcquireTimeoutMs);
+          pending.timer.unref?.();
           this.pendingAcquire = pending;
         });
       }
       this.assertActive();
-      options.abortSignal?.throwIfAborted();
+      if (options.abortSignal?.aborted) {
+        throw cancellationError(options.abortSignal.reason, "human-control-acquire");
+      }
       const lease = new BrowserHumanControlLeaseImpl({
         owner: this,
         ownerId: options.ownerId,
@@ -252,118 +1161,785 @@ var BrowserControlState = class {
     } finally {
       this.humanPending = false;
     }
-  }
-  async runAgentAction(operation) {
-    this.assertActive();
-    if (this.activeLease !== void 0 || this.humanPending) {
-      throw new BrowserError("Browser is controlled by a human viewer.", "human_controlled");
+  }
+  async runAgentAction(operation) {
+    this.assertActive();
+    if (this.activeLease !== void 0) {
+      throw new BrowserError("Browser is controlled by a human viewer.", "human_controlled", {
+        phase: "agent-action"
+      });
+    }
+    if (this.humanPending) {
+      throw new BrowserError(
+        "Browser human control acquisition is pending.",
+        "human_control_conflict",
+        { phase: "agent-action" }
+      );
+    }
+    this.activeAgentActions += 1;
+    try {
+      return await operation();
+    } finally {
+      this.activeAgentActions -= 1;
+      if (this.activeAgentActions === 0) this.resolvePendingAcquire();
+    }
+  }
+  renewLease(lease, options) {
+    if (this.activeLease !== lease) {
+      throw new BrowserError("Browser human control lease is no longer active.", "invalid_state");
+    }
+    assertPositiveSafeInteger3(options.leaseTimeoutMs, "leaseTimeoutMs");
+    lease.resetExpiration(options.leaseTimeoutMs);
+    return this.snapshot();
+  }
+  releaseLease(lease) {
+    if (this.activeLease !== lease) return;
+    this.activeLease = void 0;
+    lease.markReleased();
+  }
+  destroy() {
+    if (this.destroyed) return;
+    this.destroyed = true;
+    this.activeLease?.release();
+    if (this.pendingAcquire !== void 0) {
+      const pending = this.pendingAcquire;
+      this.pendingAcquire = void 0;
+      this.clearPendingAcquire(pending);
+      pending.reject(new BrowserError("Browser was destroyed.", "runtime_destroyed"));
+    }
+    this.humanPending = false;
+    this.availability = "destroyed";
+  }
+  setAvailability(availability) {
+    if (this.destroyed) return;
+    if (availability === "destroyed") {
+      this.destroy();
+      return;
+    }
+    this.availability = availability;
+    if (availability !== "disconnected") return;
+    this.activeLease?.release();
+    if (this.pendingAcquire !== void 0) {
+      const pending = this.pendingAcquire;
+      this.clearPendingAcquire(pending);
+      pending.reject(
+        new BrowserError("Browser runtime is disconnected.", "connection_closed", {
+          phase: "human-control-acquire"
+        })
+      );
+    }
+    this.humanPending = false;
+  }
+  assertActive() {
+    if (this.destroyed) throw new BrowserError("Browser was destroyed.", "runtime_destroyed");
+    if (this.availability === "disconnected") {
+      throw new BrowserError("Browser runtime is disconnected.", "connection_closed");
+    }
+  }
+  resolvePendingAcquire() {
+    const pending = this.pendingAcquire;
+    if (pending === void 0) return;
+    this.clearPendingAcquire(pending);
+    pending.resolve();
+  }
+  clearPendingAcquire(pending) {
+    if (this.pendingAcquire === pending) this.pendingAcquire = void 0;
+    if (pending.timer !== void 0) clearTimeout(pending.timer);
+    if (pending.abort !== void 0) {
+      pending.abortSignal?.removeEventListener("abort", pending.abort);
+    }
+  }
+};
+var BrowserHumanControlLeaseImpl = class {
+  id = randomUUID();
+  ownerId;
+  owner;
+  expiration = 0;
+  timer;
+  released = false;
+  constructor(options) {
+    this.owner = options.owner;
+    this.ownerId = options.ownerId;
+    this.resetExpiration(options.leaseTimeoutMs);
+  }
+  get expiresAt() {
+    return new Date(this.expiration).toISOString();
+  }
+  renew(options) {
+    if (this.released) {
+      throw new BrowserError("Browser human control lease is no longer active.", "invalid_state");
+    }
+    return this.owner.renewLease(this, options);
+  }
+  release() {
+    this.owner.releaseLease(this);
+  }
+  markReleased() {
+    if (this.released) return;
+    this.released = true;
+    if (this.timer !== void 0) clearTimeout(this.timer);
+    this.timer = void 0;
+  }
+  resetExpiration(leaseTimeoutMs) {
+    if (this.timer !== void 0) clearTimeout(this.timer);
+    this.expiration = Date.now() + leaseTimeoutMs;
+    this.timer = setTimeout(() => this.release(), leaseTimeoutMs);
+    this.timer.unref?.();
+  }
+  async [Symbol.asyncDispose]() {
+    this.release();
+  }
+};
+function validateAcquireOptions(options) {
+  if (!isRecord2(options)) throw new TypeError("options must be an object.");
+  if (typeof options.ownerId !== "string" || options.ownerId.length === 0) {
+    throw new TypeError("ownerId must be a non-empty string.");
+  }
+  assertPositiveSafeInteger3(options.leaseTimeoutMs, "leaseTimeoutMs");
+  if (options.timeoutMs !== void 0) assertPositiveSafeInteger3(options.timeoutMs, "timeoutMs");
+}
+function assertPositiveSafeInteger3(value, name) {
+  if (!Number.isSafeInteger(value) || value <= 0 || value > maxTimerMs2) {
+    throw new RangeError(`${name} must be a positive integer no greater than ${maxTimerMs2}.`);
+  }
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/lifecycle.ts
+var defaultLifecycleTimeoutMs = 12e4;
+var maxTimerMs3 = 2147483647;
+function boundedSignal(options, defaultTimeoutMs, phase) {
+  const timeoutMs = options.timeoutMs ?? defaultTimeoutMs;
+  assertPositiveSafeInteger4(timeoutMs, "timeoutMs");
+  if (options.abortSignal?.aborted) throw cancellationError(options.abortSignal.reason, phase);
+  const controller = new AbortController();
+  const timer = setTimeout(
+    () => controller.abort(
+      new BrowserError(`Browser lifecycle operation timed out: ${phase}.`, "lifecycle_timeout", {
+        phase
+      })
+    ),
+    timeoutMs
+  );
+  timer.unref?.();
+  const signal = options.abortSignal === void 0 ? controller.signal : AbortSignal.any([options.abortSignal, controller.signal]);
+  return {
+    signal,
+    timedOut: () => controller.signal.aborted,
+    throwIfAborted: () => {
+      if (options.abortSignal?.aborted) {
+        throw cancellationError(options.abortSignal.reason, phase);
+      }
+      if (controller.signal.aborted) throw controller.signal.reason;
+    },
+    normalize: (error, message, code) => {
+      if (options.abortSignal?.aborted) {
+        return error instanceof AggregateError ? new BrowserError("Browser operation was cancelled by the caller.", "cancelled", {
+          cause: error,
+          phase
+        }) : cancellationError(options.abortSignal.reason, phase);
+      }
+      if (controller.signal.aborted) {
+        const reason = controller.signal.reason;
+        return error === reason ? reason : new BrowserError(reason.message, "lifecycle_timeout", { cause: error, phase });
+      }
+      if (error instanceof BrowserError) return error;
+      return new BrowserError(message, code, { cause: error, phase });
+    },
+    dispose: () => clearTimeout(timer)
+  };
+}
+function validateLifecycleOptions(options, phase) {
+  if (options.timeoutMs !== void 0) assertPositiveSafeInteger4(options.timeoutMs, "timeoutMs");
+  if (options.abortSignal?.aborted) {
+    throw cancellationError(options.abortSignal.reason, phase);
+  }
+}
+async function waitForSharedLifecycle(promise, options, phase) {
+  const bounded = boundedSignal(options, defaultLifecycleTimeoutMs, phase);
+  try {
+    await waitForPromise(promise, bounded.signal);
+    bounded.throwIfAborted();
+  } catch (error) {
+    throw bounded.normalize(error, `Unable to wait for ${phase}.`, "transport_failure");
+  } finally {
+    bounded.dispose();
+  }
+}
+function assertPositiveSafeInteger4(value, name) {
+  if (!Number.isSafeInteger(value) || value <= 0 || value > maxTimerMs3) {
+    throw new RangeError(`${name} must be a positive integer no greater than ${maxTimerMs3}.`);
+  }
+}
+function assertOptionsObject2(value) {
+  if (!isRecord3(value)) throw new TypeError("options must be an object.");
+}
+function isRecord3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function waitForPromise(promise, abortSignal) {
+  abortSignal.throwIfAborted();
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = (callback) => {
+      if (settled) return;
+      settled = true;
+      abortSignal.removeEventListener("abort", abort);
+      callback();
+    };
+    const abort = () => finish(() => reject(abortSignal.reason));
+    abortSignal.addEventListener("abort", abort, { once: true });
+    void promise.then(
+      (value) => finish(() => resolve(value)),
+      (error) => finish(() => reject(error))
+    );
+  });
+}
+
+// src/readiness.ts
+var cdpPort = 9222;
+var noVncPort = 6080;
+var browserCapabilities = ["runtime", "browser", "automation", "desktop"];
+var automationProbeAttemptTimeoutMs = 5e3;
+async function probeBrowserCapability(options) {
+  const { capability, sandbox, abortSignal, deadline } = options;
+  switch (capability) {
+    case "runtime":
+      if (sandbox.state !== "running") {
+        throw new BrowserError(`Browser is not running: ${sandbox.state}`, "invalid_state");
+      }
+      return;
+    case "browser":
+      await sandbox.runtime.waitForPort({
+        containerPort: cdpPort,
+        timeoutMs: remainingTime(deadline),
+        abortSignal
+      });
+      await assertCdpHttpReady(`${endpointFor(sandbox, cdpPort)}/json/version`, abortSignal);
+      return;
+    case "desktop":
+      await sandbox.runtime.waitForPort({
+        containerPort: noVncPort,
+        timeoutMs: remainingTime(deadline),
+        abortSignal
+      });
+      await assertHttpReady(`${endpointFor(sandbox, noVncPort)}/vnc.html`, abortSignal);
+      return;
+    case "automation":
+      await sandbox.runtime.waitForPort({
+        containerPort: cdpPort,
+        timeoutMs: remainingTime(deadline),
+        abortSignal
+      });
+      await assertCdpHttpReady(`${endpointFor(sandbox, cdpPort)}/json/version`, abortSignal);
+      for (let attempt = 0; ; attempt += 1) {
+        abortSignal.throwIfAborted();
+        try {
+          const connection = await options.connectBrowser({
+            endpointUrl: endpointFor(sandbox, cdpPort),
+            control: options.control,
+            timeoutMs: Math.min(automationProbeAttemptTimeoutMs, remainingTime(deadline)),
+            abortSignal
+          });
+          try {
+            if (connection.closed) {
+              throw new Error("CDP connection closed during initialization.");
+            }
+          } finally {
+            await connection.disconnect({
+              timeoutMs: remainingTime(deadline),
+              abortSignal
+            });
+          }
+          abortSignal.throwIfAborted();
+          return;
+        } catch (error) {
+          if (abortSignal.aborted) throw abortSignal.reason ?? error;
+          await waitForRetry(abortSignal, Math.min(500, 50 * 2 ** Math.min(attempt, 3)));
+        }
+      }
+  }
+}
+function endpointFor(sandbox, containerPort) {
+  const published = publishedPort(sandbox, containerPort);
+  return `http://${hostForUrl(published.host)}:${published.hostPort}`;
+}
+function normalizeReadinessError(error, capability, state) {
+  if (state.callerAborted) {
+    return new BrowserError("Browser readiness was cancelled by the caller.", "cancelled", {
+      cause: error,
+      capability,
+      phase: "readiness"
+    });
+  }
+  if (state.timedOut) {
+    return new BrowserError(
+      `Browser ${capability} capability did not become ready before the timeout.`,
+      "readiness_timeout",
+      { cause: error, capability, phase: "readiness" }
+    );
+  }
+  if (error instanceof BrowserError && (error.code === "connection_closed" || error.code === "runtime_destroyed")) {
+    return error;
+  }
+  return new BrowserError(`Browser ${capability} capability is not ready.`, "not_ready", {
+    cause: error,
+    capability,
+    phase: "readiness"
+  });
+}
+async function assertCdpHttpReady(url, abortSignal) {
+  await assertHttpReady(url, abortSignal, async (response) => {
+    const value = await response.json();
+    if (!isRecord4(value) || typeof value.webSocketDebuggerUrl !== "string" || !value.webSocketDebuggerUrl.startsWith("ws")) {
+      throw new Error("CDP version endpoint did not expose a WebSocket debugger URL.");
+    }
+  });
+}
+async function assertHttpReady(url, abortSignal, verify) {
+  while (true) {
+    abortSignal.throwIfAborted();
+    try {
+      const response = await fetch(url, { signal: abortSignal, redirect: "error" });
+      try {
+        if (response.ok) {
+          await verify?.(response);
+          return;
+        }
+      } finally {
+        await response.body?.cancel().catch(() => void 0);
+      }
+    } catch (error) {
+      if (abortSignal.aborted) throw abortSignal.reason ?? error;
+    }
+    await waitForRetry(abortSignal);
+  }
+}
+async function waitForRetry(abortSignal, delayMs = 50) {
+  await new Promise((resolve, reject) => {
+    const timer = setTimeout(() => finish(), delayMs);
+    timer.unref?.();
+    const abort = () => finish(abortSignal.reason ?? new DOMException("Aborted", "AbortError"));
+    abortSignal.addEventListener("abort", abort, { once: true });
+    function finish(error) {
+      clearTimeout(timer);
+      abortSignal.removeEventListener("abort", abort);
+      if (error === void 0) resolve();
+      else reject(error);
+    }
+  });
+}
+function remainingTime(deadline) {
+  return Math.max(1, deadline - Date.now());
+}
+function publishedPort(sandbox, containerPort) {
+  const port = sandbox.runtime.publishedPorts.find(
+    (candidate) => candidate.containerPort === containerPort && candidate.protocol === "tcp"
+  );
+  if (port === void 0) {
+    throw new BrowserError(`Browser port is not published: ${containerPort}`, "invalid_state");
+  }
+  return port;
+}
+function hostForUrl(host) {
+  return host.includes(":") ? `[${host}]` : host;
+}
+function isRecord4(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/docker-browser.ts
+var defaultConnectTimeoutMs = 3e4;
+var capabilities = browserCapabilities;
+var DockerBrowserHandle = class {
+  id;
+  sandbox;
+  desktop;
+  control = new BrowserControlState();
+  connections = /* @__PURE__ */ new Set();
+  ownedOperations = /* @__PURE__ */ new Set();
+  capabilityStates = new Map(
+    capabilities.map((capability) => [capability, Object.freeze({ capability, state: "unknown" })])
+  );
+  capabilityGenerations = new Map(
+    capabilities.map((capability) => [capability, 0])
+  );
+  handleState = "active";
+  connectionPending = false;
+  stopPromise;
+  destroyPromise;
+  connectBrowser;
+  constructor(sandbox, connectBrowser = connectPlaywrightBrowser) {
+    this.sandbox = sandbox;
+    this.id = sandbox.id;
+    this.connectBrowser = connectBrowser;
+    this.desktop = Object.freeze({
+      protocol: "novnc",
+      containerPort: noVncPort,
+      control: this.control
+    });
+  }
+  get state() {
+    return this.handleState === "active" ? this.sandbox.state : this.handleState;
+  }
+  inspector(options) {
+    return this.sandbox.inspector(options);
+  }
+  readiness() {
+    const terminal = this.handleState === "destroyed" || this.handleState === "destroying" ? "destroyed" : this.handleState === "stopped" || this.handleState === "stopping" ? "stopped" : void 0;
+    const entries = Object.fromEntries(
+      capabilities.map((capability) => {
+        const current = this.capabilityStates.get(capability);
+        return [
+          capability,
+          terminal === void 0 ? current : Object.freeze({ capability, state: terminal })
+        ];
+      })
+    );
+    const values = Object.values(entries);
+    const state = this.handleState === "error" ? "failed" : terminal ?? (values.some((value) => value.state === "checking") ? "checking" : values.every((value) => value.state === "unknown") ? "unknown" : values.every((value) => value.state === "ready") ? "ready" : values.some((value) => value.state === "failed") ? values.some((value) => value.state === "ready") ? "degraded" : "failed" : "partial");
+    return Object.freeze({ state, capabilities: Object.freeze(entries) });
+  }
+  async waitForCapabilities(options) {
+    validateReadinessOptions(options);
+    this.assertRunning();
+    if (options.abortSignal?.aborted) {
+      throw cancellationError(options.abortSignal.reason, "readiness");
+    }
+    const requested = options.capabilities ?? capabilities;
+    const ownedController = new AbortController();
+    const timeoutController = new AbortController();
+    const deadline = Date.now() + options.timeoutMs;
+    const timer = setTimeout(
+      () => timeoutController.abort(
+        new BrowserError("Browser readiness timed out.", "readiness_timeout", {
+          phase: "readiness"
+        })
+      ),
+      options.timeoutMs
+    );
+    timer.unref?.();
+    const signals = [ownedController.signal, timeoutController.signal];
+    if (options.abortSignal !== void 0) signals.push(options.abortSignal);
+    const abortSignal = AbortSignal.any(signals);
+    const previous = new Map(
+      requested.map((capability) => [capability, this.capabilityStates.get(capability)])
+    );
+    const generations = new Map(
+      requested.map((capability) => {
+        const generation = (this.capabilityGenerations.get(capability) ?? 0) + 1;
+        this.capabilityGenerations.set(capability, generation);
+        return [capability, generation];
+      })
+    );
+    for (const capability of requested) this.setCapability(capability, "checking");
+    const promise = Promise.allSettled(
+      requested.map(async (capability) => {
+        try {
+          await probeBrowserCapability({
+            capability,
+            sandbox: this.sandbox,
+            control: this.control,
+            connectBrowser: this.connectBrowser,
+            abortSignal,
+            deadline
+          });
+          abortSignal.throwIfAborted();
+          if (this.capabilityGenerations.get(capability) === generations.get(capability)) {
+            this.setCapability(capability, "ready");
+          }
+        } catch (error) {
+          const normalized = normalizeReadinessError(error, capability, {
+            callerAborted: options.abortSignal?.aborted === true,
+            timedOut: timeoutController.signal.aborted
+          });
+          if (this.capabilityGenerations.get(capability) === generations.get(capability)) {
+            if (options.abortSignal?.aborted) {
+              this.capabilityStates.set(capability, previous.get(capability));
+            } else {
+              this.setCapability(capability, "failed", normalized);
+            }
+          }
+          throw normalized;
+        }
+      })
+    );
+    const owned = { controller: ownedController, promise };
+    this.ownedOperations.add(owned);
+    try {
+      const results = await promise;
+      if (options.abortSignal?.aborted) {
+        throw cancellationError(options.abortSignal.reason, "readiness");
+      }
+      const failures = results.filter(
+        (result) => result.status === "rejected"
+      );
+      this.updateControlAvailability();
+      if (failures.length > 0) throw failures[0].reason;
+      return this.readiness();
+    } finally {
+      clearTimeout(timer);
+      this.ownedOperations.delete(owned);
+    }
+  }
+  async waitUntilReady(options) {
+    await this.waitForCapabilities(options);
+  }
+  async connect(options = {}) {
+    assertOptionsObject2(options);
+    if (options.timeoutMs !== void 0) assertPositiveSafeInteger4(options.timeoutMs, "timeoutMs");
+    this.assertRunning();
+    if (options.abortSignal?.aborted) {
+      throw cancellationError(options.abortSignal.reason, "connect");
+    }
+    if (this.connectionPending || this.connections.size > 0) {
+      throw new BrowserError(
+        "Browser already has an active or pending automation connection.",
+        "agent_action_busy",
+        { phase: "connect" }
+      );
+    }
+    this.connectionPending = true;
+    const controller = new AbortController();
+    const signals = [controller.signal];
+    if (options.abortSignal !== void 0) signals.push(options.abortSignal);
+    const abortSignal = AbortSignal.any(signals);
+    let owned;
+    const promise = (async () => {
+      await Promise.resolve();
+      try {
+        abortSignal.throwIfAborted();
+        const connection = await this.connectBrowser({
+          endpointUrl: endpointFor(this.sandbox, cdpPort),
+          control: this.control,
+          timeoutMs: options.timeoutMs ?? defaultConnectTimeoutMs,
+          abortSignal,
+          scheduling: options.scheduling,
+          onClosed: (closedConnection) => this.connections.delete(closedConnection)
+        });
+        this.connections.add(connection);
+        const disconnectedDuringInitialization = connection.closed;
+        if (disconnectedDuringInitialization || this.handleState !== "active" || this.state !== "running") {
+          this.connections.delete(connection);
+          let cleanupError;
+          try {
+            await connection.disconnect();
+          } catch (caught) {
+            cleanupError = caught;
+          }
+          if (disconnectedDuringInitialization && this.handleState === "active" && this.state === "running") {
+            throw new BrowserError(
+              "Browser disconnected while automation was initializing.",
+              "connection_closed",
+              {
+                ...cleanupError === void 0 ? {} : { cause: cleanupError },
+                phase: "connect"
+              }
+            );
+          }
+          const lifecycleError = this.lifecycleError(
+            "Browser stopped while the connection was initializing."
+          );
+          throw cleanupError === void 0 ? lifecycleError : new BrowserError(lifecycleError.message, lifecycleError.code, {
+            cause: cleanupError,
+            ...lifecycleError.phase === void 0 ? {} : { phase: lifecycleError.phase }
+          });
+        }
+        return connection;
+      } catch (error) {
+        if (options.abortSignal?.aborted) {
+          throw cancellationError(options.abortSignal.reason, "connect");
+        }
+        if (controller.signal.aborted) throw controller.signal.reason;
+        if (error instanceof BrowserError) throw error;
+        throw new BrowserError("Unable to connect to Chromium over CDP.", "transport_failure", {
+          cause: error,
+          phase: "connect"
+        });
+      } finally {
+        this.connectionPending = false;
+        this.ownedOperations.delete(owned);
+      }
+    })();
+    owned = { controller, promise };
+    this.ownedOperations.add(owned);
+    return promise;
+  }
+  async stop(options = {}) {
+    assertOptionsObject2(options);
+    if (this.handleState === "stopped") return;
+    if (this.handleState === "destroyed" || this.handleState === "destroying") {
+      throw new BrowserError("Browser runtime is destroyed.", "runtime_destroyed");
+    }
+    validateLifecycleOptions(options, "stop-browser");
+    if (this.stopPromise !== void 0) {
+      return waitForSharedLifecycle(this.stopPromise, options, "stop-browser");
     }
-    this.activeAgentActions += 1;
+    this.handleState = "stopping";
+    this.control.setAvailability("disconnected");
+    const promise = this.performStop(options);
+    this.stopPromise = promise;
     try {
-      return await operation();
+      await promise;
     } finally {
-      this.activeAgentActions -= 1;
-      if (this.activeAgentActions === 0) this.resolvePendingAcquire();
+      if (this.stopPromise === promise) this.stopPromise = void 0;
     }
   }
-  renewLease(lease, options) {
-    if (this.activeLease !== lease) {
-      throw new BrowserError("Browser human control lease is no longer active.", "invalid_state");
+  async destroy(options = {}) {
+    assertOptionsObject2(options);
+    if (this.handleState === "destroyed") return;
+    validateLifecycleOptions(options, "destroy-browser");
+    if (this.destroyPromise === void 0) {
+      this.handleState = "destroying";
+      this.control.destroy();
+      const activeStop = this.stopPromise;
+      const promise = (async () => {
+        if (activeStop !== void 0) await activeStop.catch(() => void 0);
+        await this.performDestroy();
+      })();
+      this.destroyPromise = promise;
+      void promise.then(
+        () => {
+          if (this.destroyPromise === promise) this.destroyPromise = void 0;
+        },
+        () => {
+          if (this.destroyPromise === promise) this.destroyPromise = void 0;
+        }
+      );
     }
-    assertPositiveSafeInteger(options.leaseTimeoutMs, "leaseTimeoutMs");
-    lease.resetExpiration(options.leaseTimeoutMs);
-    return this.snapshot();
+    return waitForSharedLifecycle(this.destroyPromise, options, "destroy-browser");
   }
-  releaseLease(lease) {
-    if (this.activeLease !== lease) return;
-    this.activeLease = void 0;
-    lease.markReleased();
+  async [Symbol.asyncDispose]() {
+    await this.destroy();
   }
-  destroy() {
-    if (this.destroyed) return;
-    this.destroyed = true;
-    this.activeLease?.release();
-    if (this.pendingAcquire !== void 0) {
-      const pending = this.pendingAcquire;
-      this.pendingAcquire = void 0;
-      if (pending.abort !== void 0) {
-        pending.abortSignal?.removeEventListener("abort", pending.abort);
+  async performStop(options) {
+    const bounded = boundedSignal(options, defaultLifecycleTimeoutMs, "stop-browser");
+    try {
+      await this.abortOwnedOperations(
+        new BrowserError("Browser runtime is stopping.", "connection_closed", {
+          phase: "stop-browser"
+        })
+      );
+      const disconnectFailures = await this.disconnectAll({ abortSignal: bounded.signal });
+      await this.sandbox.stop({ abortSignal: bounded.signal });
+      if (this.handleState === "stopping") this.handleState = "stopped";
+      bounded.throwIfAborted();
+      if (disconnectFailures.length > 0) {
+        throw new BrowserError(
+          "Browser stopped, but one or more automation workers failed to disconnect.",
+          "transport_failure",
+          {
+            cause: new AggregateError(disconnectFailures, "Automation worker cleanup failed."),
+            phase: "stop-browser",
+            recovery: "restart"
+          }
+        );
       }
-      pending.reject(new BrowserError("Browser was destroyed.", "invalid_state"));
+    } catch (error) {
+      if (this.handleState === "stopping") this.handleState = "error";
+      throw bounded.normalize(error, "Unable to stop browser runtime.", "transport_failure");
+    } finally {
+      bounded.dispose();
     }
   }
-  assertActive() {
-    if (this.destroyed) throw new BrowserError("Browser was destroyed.", "invalid_state");
-  }
-  resolvePendingAcquire() {
-    const pending = this.pendingAcquire;
-    if (pending === void 0) return;
-    this.pendingAcquire = void 0;
-    if (pending.abort !== void 0) {
-      pending.abortSignal?.removeEventListener("abort", pending.abort);
+  async performDestroy() {
+    try {
+      await this.abortOwnedOperations(
+        new BrowserError("Browser runtime was destroyed.", "runtime_destroyed", {
+          phase: "destroy-browser"
+        })
+      );
+      const disconnectFailures = await this.disconnectAll({});
+      await this.sandbox.destroy();
+      this.handleState = "destroyed";
+      if (disconnectFailures.length > 0) {
+        throw new BrowserError(
+          "Browser was destroyed, but one or more automation workers failed to disconnect.",
+          "transport_failure",
+          {
+            cause: new AggregateError(disconnectFailures, "Automation worker cleanup failed."),
+            phase: "destroy-browser",
+            retryable: false,
+            recovery: "none"
+          }
+        );
+      }
+    } catch (error) {
+      if (this.handleState !== "destroyed") this.handleState = "error";
+      if (error instanceof BrowserError) throw error;
+      throw new BrowserError("Unable to destroy browser runtime.", "transport_failure", {
+        cause: error,
+        phase: "destroy-browser",
+        recovery: "retry"
+      });
     }
-    pending.resolve();
   }
-};
-var BrowserHumanControlLeaseImpl = class {
-  id = randomUUID2();
-  ownerId;
-  owner;
-  expiration = 0;
-  timer;
-  released = false;
-  constructor(options) {
-    this.owner = options.owner;
-    this.ownerId = options.ownerId;
-    this.resetExpiration(options.leaseTimeoutMs);
-  }
-  get expiresAt() {
-    return new Date(this.expiration).toISOString();
-  }
-  renew(options) {
-    if (this.released) {
-      throw new BrowserError("Browser human control lease is no longer active.", "invalid_state");
+  assertRunning() {
+    if (this.handleState === "destroyed" || this.handleState === "destroying") {
+      throw new BrowserError("Browser runtime is destroyed.", "runtime_destroyed");
+    }
+    if (this.handleState !== "active" || this.state !== "running") {
+      throw new BrowserError(`Browser is not running: ${this.state}`, "invalid_state");
     }
-    return this.owner.renewLease(this, options);
   }
-  release() {
-    this.owner.releaseLease(this);
+  lifecycleError(message) {
+    return this.handleState === "destroying" || this.handleState === "destroyed" ? new BrowserError(message, "runtime_destroyed") : new BrowserError(message, "connection_closed", { phase: "connect" });
   }
-  markReleased() {
-    if (this.released) return;
-    this.released = true;
-    if (this.timer !== void 0) clearTimeout(this.timer);
-    this.timer = void 0;
+  async abortOwnedOperations(error) {
+    const operations = [...this.ownedOperations];
+    for (const operation of operations) operation.controller.abort(error);
+    await Promise.allSettled(operations.map((operation) => operation.promise));
   }
-  resetExpiration(leaseTimeoutMs) {
-    if (this.timer !== void 0) clearTimeout(this.timer);
-    this.expiration = Date.now() + leaseTimeoutMs;
-    this.timer = setTimeout(() => this.release(), leaseTimeoutMs);
-    this.timer.unref?.();
+  async disconnectAll(options) {
+    const connections = [...this.connections];
+    this.connections.clear();
+    const results = await Promise.allSettled(
+      connections.map((connection) => connection.disconnect(options))
+    );
+    return results.filter((result) => result.status === "rejected").map((result) => result.reason);
+  }
+  setCapability(capability, state, error) {
+    this.capabilityStates.set(
+      capability,
+      Object.freeze({
+        capability,
+        state,
+        checkedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        ...error === void 0 ? {} : { error }
+      })
+    );
   }
-  async [Symbol.asyncDispose]() {
-    this.release();
+  updateControlAvailability() {
+    if (this.handleState !== "active" || this.state !== "running") {
+      this.control.setAvailability("disconnected");
+      return;
+    }
+    const failed = capabilities.some(
+      (capability) => this.capabilityStates.get(capability)?.state === "failed"
+    );
+    this.control.setAvailability(failed ? "degraded" : "available");
   }
 };
-function validateAcquireOptions(options) {
-  if (!isRecord(options)) throw new TypeError("options must be an object.");
-  if (typeof options.ownerId !== "string" || options.ownerId.length === 0) {
-    throw new TypeError("ownerId must be a non-empty string.");
-  }
-  assertPositiveSafeInteger(options.leaseTimeoutMs, "leaseTimeoutMs");
-}
-function assertPositiveSafeInteger(value, name) {
-  if (!Number.isSafeInteger(value) || value <= 0) {
-    throw new RangeError(`${name} must be a positive safe integer.`);
+function validateReadinessOptions(options) {
+  assertOptionsObject2(options);
+  assertPositiveSafeInteger4(options.timeoutMs, "timeoutMs");
+  if (options.capabilities === void 0) return;
+  if (!Array.isArray(options.capabilities) || options.capabilities.length === 0) {
+    throw new TypeError("capabilities must be a non-empty array.");
+  }
+  const unique = /* @__PURE__ */ new Set();
+  for (const capability of options.capabilities) {
+    if (!capabilities.includes(capability)) {
+      throw new TypeError(`Unsupported browser capability: ${capability}`);
+    }
+    if (unique.has(capability)) throw new TypeError(`Duplicate browser capability: ${capability}`);
+    unique.add(capability);
   }
 }
-function isRecord(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 
-// src/docker-browser.ts
-var cdpPort = 9222;
-var noVncPort = 6080;
+// src/docker-browser-client.ts
 var browserSchema = "1";
 var defaultSharedMemoryMb = 1024;
 var seccompProfilePath = fileURLToPath(
@@ -373,7 +1949,7 @@ var DockerBrowserClient = class {
   sandboxClient;
   image;
   constructor(options) {
-    if (!isRecord2(options)) throw new TypeError("options must be an object.");
+    if (!isRecord3(options)) throw new TypeError("options must be an object.");
     if (!isSandboxClient(options.sandboxClient)) {
       throw new TypeError("sandboxClient must be a DockerSandboxClient.");
     }
@@ -382,16 +1958,20 @@ var DockerBrowserClient = class {
     this.image = options.image;
   }
   async pullImage(options = {}) {
-    assertOptionsObject(options);
-    let pullOptions = { image: this.image };
-    if (options.abortSignal !== void 0) {
-      pullOptions = { ...pullOptions, abortSignal: options.abortSignal };
+    assertOptionsObject2(options);
+    const bounded = boundedSignal(options, defaultLifecycleTimeoutMs, "pull-image");
+    try {
+      await this.sandboxClient.pullImage({ image: this.image, abortSignal: bounded.signal });
+      bounded.throwIfAborted();
+    } catch (error) {
+      throw bounded.normalize(error, "Unable to pull the browser image.", "startup_failed");
+    } finally {
+      bounded.dispose();
     }
-    await this.sandboxClient.pullImage(pullOptions);
   }
   async createBrowser(options) {
     validateCreateOptions(options);
-    options.abortSignal?.throwIfAborted();
+    const bounded = boundedSignal(options, defaultLifecycleTimeoutMs, "create-browser");
     const resources = {
       ...options.resources,
       sharedMemoryMb: options.resources?.sharedMemoryMb ?? defaultSharedMemoryMb
@@ -402,252 +1982,122 @@ var DockerBrowserClient = class {
       workspace: options.workspace,
       network: { mode: "bridge", ports: [cdpPort, noVncPort] },
       user: "pwuser",
-      labels: {
-        "anvia.browser.schema": browserSchema
-      },
+      labels: { "anvia.browser.schema": browserSchema },
       resources,
       security: {
         noNewPrivileges: true,
         dropCapabilities: ["ALL"],
         addCapabilities: ["SYS_CHROOT"],
         seccompProfile: { type: "path", path: seccompProfilePath }
-      }
+      },
+      abortSignal: bounded.signal
     };
     if (options.id !== void 0) sandboxOptions = { ...sandboxOptions, id: options.id };
     if (options.runtime !== void 0) {
       sandboxOptions = { ...sandboxOptions, runtime: options.runtime };
     }
-    if (options.abortSignal !== void 0) {
-      sandboxOptions = { ...sandboxOptions, abortSignal: options.abortSignal };
-    }
-    const sandbox = await this.sandboxClient.createSandbox(sandboxOptions);
+    let sandbox;
     try {
-      await configureBrowser(sandbox, options);
-      await startBrowserServices(sandbox, options.abortSignal);
+      sandbox = await this.sandboxClient.createSandbox(sandboxOptions);
+      await configureBrowser(sandbox, options, bounded.signal);
+      await startBrowserServices(sandbox, bounded.signal);
+      bounded.throwIfAborted();
       return new DockerBrowserHandle(sandbox);
     } catch (error) {
-      await sandbox.destroy().catch(() => void 0);
-      throw new BrowserError("Unable to configure the browser sandbox.", "startup_failed", {
-        cause: error
-      });
+      let cleanupError;
+      try {
+        await sandbox?.destroy();
+      } catch (caught) {
+        cleanupError = caught;
+      }
+      throw bounded.normalize(
+        combineCleanupError2(error, cleanupError, "Browser sandbox cleanup also failed."),
+        "Unable to configure the browser sandbox.",
+        "startup_failed"
+      );
+    } finally {
+      bounded.dispose();
     }
   }
   async resumeBrowser(options) {
-    assertOptionsObject(options);
+    assertOptionsObject2(options);
     assertNonEmptyString(options.id, "id");
-    options.abortSignal?.throwIfAborted();
-    const sandbox = await this.sandboxClient.resumeSandbox(options);
+    const bounded = boundedSignal(options, defaultLifecycleTimeoutMs, "resume-browser");
+    let sandbox;
     try {
-      await assertBrowserImage(sandbox, options.abortSignal);
-      await startBrowserServices(sandbox, options.abortSignal);
-      return new DockerBrowserHandle(sandbox);
-    } catch (error) {
-      await sandbox.stop().catch(() => void 0);
-      throw new BrowserError("Unable to resume browser services.", "startup_failed", {
-        cause: error
+      sandbox = await this.sandboxClient.resumeSandbox({
+        id: options.id,
+        abortSignal: bounded.signal
       });
-    }
-  }
-};
-var DockerBrowserHandle = class {
-  id;
-  sandbox;
-  desktop;
-  control = new BrowserControlState();
-  connections = /* @__PURE__ */ new Set();
-  constructor(sandbox) {
-    this.sandbox = sandbox;
-    this.id = sandbox.id;
-    this.desktop = Object.freeze({
-      protocol: "novnc",
-      containerPort: noVncPort,
-      control: this.control
-    });
-  }
-  get state() {
-    return this.sandbox.state;
-  }
-  inspector(options) {
-    return this.sandbox.inspector(options);
-  }
-  async waitUntilReady(options) {
-    assertOptionsObject(options);
-    assertPositiveSafeInteger2(options.timeoutMs, "timeoutMs");
-    this.assertRunning();
-    const timeout = AbortSignal.timeout(options.timeoutMs);
-    const abortSignal = options.abortSignal === void 0 ? timeout : AbortSignal.any([options.abortSignal, timeout]);
-    try {
-      await Promise.all([
-        this.sandbox.runtime.waitForPort({
-          containerPort: cdpPort,
-          timeoutMs: options.timeoutMs,
-          abortSignal
-        }),
-        this.sandbox.runtime.waitForPort({
-          containerPort: noVncPort,
-          timeoutMs: options.timeoutMs,
-          abortSignal
-        })
-      ]);
-      await Promise.all([
-        assertHttpReady(`${endpointFor(this.sandbox, cdpPort)}/json/version`, abortSignal),
-        assertHttpReady(`${endpointFor(this.sandbox, noVncPort)}/vnc.html`, abortSignal)
-      ]);
+      await assertBrowserImage(sandbox, bounded.signal);
+      await startBrowserServices(sandbox, bounded.signal);
+      bounded.throwIfAborted();
+      return new DockerBrowserHandle(sandbox);
     } catch (error) {
-      if (options.abortSignal?.aborted) options.abortSignal.throwIfAborted();
-      throw new BrowserError("Browser did not become ready before the timeout.", "not_ready", {
-        cause: error
-      });
-    }
-  }
-  async connect(options = {}) {
-    assertOptionsObject(options);
-    this.assertRunning();
-    try {
-      let connectOptions = {
-        endpointUrl: endpointFor(this.sandbox, cdpPort),
-        control: this.control
-      };
-      if (options.abortSignal !== void 0) {
-        connectOptions = { ...connectOptions, abortSignal: options.abortSignal };
+      let cleanupError;
+      try {
+        await sandbox?.stop();
+      } catch (caught) {
+        cleanupError = caught;
       }
-      const connection = await connectPlaywrightBrowser(connectOptions);
-      this.connections.add(connection);
-      return connection;
-    } catch (error) {
-      if (options.abortSignal?.aborted) options.abortSignal.throwIfAborted();
-      throw new BrowserError("Unable to connect to Chromium over CDP.", "not_ready", {
-        cause: error
-      });
-    }
-  }
-  async stop(options = {}) {
-    assertOptionsObject(options);
-    await this.disconnectAll();
-    await this.sandbox.stop(options);
-  }
-  async destroy() {
-    this.control.destroy();
-    await this.disconnectAll();
-    await this.sandbox.destroy();
-  }
-  async [Symbol.asyncDispose]() {
-    await this.destroy();
-  }
-  assertRunning() {
-    if (this.state !== "running") {
-      throw new BrowserError(`Browser is not running: ${this.state}`, "invalid_state");
-    }
-  }
-  async disconnectAll() {
-    const connections = [...this.connections];
-    this.connections.clear();
-    const results = await Promise.allSettled(
-      connections.map((connection) => connection.disconnect())
-    );
-    const failures = results.filter((result) => result.status === "rejected").map((result) => result.reason);
-    if (failures.length > 0) {
-      throw new AggregateError(failures, "Unable to disconnect browser automation clients.");
+      throw bounded.normalize(
+        combineCleanupError2(error, cleanupError, "Resumed browser cleanup also failed."),
+        "Unable to resume browser services.",
+        "startup_failed"
+      );
+    } finally {
+      bounded.dispose();
     }
   }
 };
-async function configureBrowser(sandbox, options) {
-  let execOptions = {
+async function configureBrowser(sandbox, options, abortSignal) {
+  const result = await sandbox.runtime.exec({
     command: "/usr/local/bin/anvia-browser-configure",
     input: JSON.stringify({
       password: options.desktop.password,
       width: options.desktop.viewport.width,
       height: options.desktop.viewport.height
-    })
-  };
-  if (options.abortSignal !== void 0) {
-    execOptions = { ...execOptions, abortSignal: options.abortSignal };
-  }
-  const result = await sandbox.runtime.exec(execOptions);
+    }),
+    abortSignal
+  });
   if (result.status !== "exited" || result.exitCode !== 0) {
     throw new Error("Browser image rejected its runtime configuration.");
   }
 }
 async function assertBrowserImage(sandbox, abortSignal) {
-  let execOptions = {
-    command: "/usr/local/bin/anvia-browser-version"
-  };
-  if (abortSignal !== void 0) execOptions = { ...execOptions, abortSignal };
-  const result = await sandbox.runtime.exec(execOptions);
+  const result = await sandbox.runtime.exec({
+    command: "/usr/local/bin/anvia-browser-version",
+    abortSignal
+  });
   if (result.status !== "exited" || result.exitCode !== 0 || new TextDecoder("utf-8", { fatal: true }).decode(result.stdout).trim() !== browserSchema) {
     throw new Error("Sandbox does not contain a compatible Anvia browser image.");
   }
 }
 async function startBrowserServices(sandbox, abortSignal) {
-  let startOptions = {
-    command: "/usr/local/bin/anvia-browser-start"
-  };
-  if (abortSignal !== void 0) startOptions = { ...startOptions, abortSignal };
-  await sandbox.runtime.startProcess(startOptions);
-}
-async function assertHttpReady(url, abortSignal) {
-  while (true) {
-    abortSignal.throwIfAborted();
-    try {
-      const response = await fetch(url, { signal: abortSignal, redirect: "error" });
-      if (response.ok) {
-        await response.body?.cancel();
-        return;
-      }
-      await response.body?.cancel();
-    } catch (error) {
-      if (abortSignal.aborted) throw abortSignal.reason ?? error;
-    }
-    await waitForRetry(abortSignal);
-  }
-}
-async function waitForRetry(abortSignal) {
-  await new Promise((resolve, reject) => {
-    const timeout = setTimeout(finish, 50);
-    const abort = () => finish(abortSignal.reason ?? new DOMException("Aborted", "AbortError"));
-    abortSignal.addEventListener("abort", abort, { once: true });
-    function finish(error) {
-      clearTimeout(timeout);
-      abortSignal.removeEventListener("abort", abort);
-      if (error === void 0) resolve();
-      else reject(error);
-    }
+  await sandbox.runtime.startProcess({
+    command: "/usr/local/bin/anvia-browser-start",
+    abortSignal
   });
 }
-function endpointFor(sandbox, containerPort) {
-  const published = publishedPort(sandbox, containerPort);
-  return `http://${hostForUrl(published.host)}:${published.hostPort}`;
-}
-function publishedPort(sandbox, containerPort) {
-  const port = sandbox.runtime.publishedPorts.find(
-    (candidate) => candidate.containerPort === containerPort && candidate.protocol === "tcp"
-  );
-  if (port === void 0) {
-    throw new BrowserError(`Browser port is not published: ${containerPort}`, "invalid_state");
-  }
-  return port;
-}
-function hostForUrl(host) {
-  return host.includes(":") ? `[${host}]` : host;
-}
 function validateCreateOptions(options) {
-  assertOptionsObject(options);
+  assertOptionsObject2(options);
   if (options.id !== void 0) assertNonEmptyString(options.id, "id");
-  if (!isRecord2(options.workspace)) throw new TypeError("workspace must be an object.");
-  if (!isRecord2(options.network) || options.network.mode !== "bridge") {
+  if (!isRecord3(options.workspace)) throw new TypeError("workspace must be an object.");
+  if (!isRecord3(options.network) || options.network.mode !== "bridge") {
     throw new TypeError('network must be { mode: "bridge" }.');
   }
-  if (!isRecord2(options.desktop) || options.desktop.protocol !== "novnc") {
+  if (!isRecord3(options.desktop) || options.desktop.protocol !== "novnc") {
     throw new TypeError('desktop must use protocol: "novnc".');
   }
   if (!/^[\x20-\x7e]{8}$/.test(options.desktop.password)) {
     throw new TypeError("desktop.password must contain exactly 8 printable ASCII characters.");
   }
-  if (!isRecord2(options.desktop.viewport)) {
+  if (!isRecord3(options.desktop.viewport)) {
     throw new TypeError("desktop.viewport must be an object.");
   }
   assertIntegerInRange(options.desktop.viewport.width, "desktop.viewport.width", 640, 3840);
   assertIntegerInRange(options.desktop.viewport.height, "desktop.viewport.height", 480, 2160);
+  if (options.timeoutMs !== void 0) assertPositiveSafeInteger4(options.timeoutMs, "timeoutMs");
   if (options.runtime?.maxProcesses !== void 0 && options.runtime.maxProcesses < 1) {
     throw new RangeError("runtime.maxProcesses must allow the browser service process.");
   }
@@ -657,24 +2107,16 @@ function assertIntegerInRange(value, name, min, max) {
     throw new RangeError(`${name} must be a safe integer between ${min} and ${max}.`);
   }
 }
-function assertPositiveSafeInteger2(value, name) {
-  if (!Number.isSafeInteger(value) || value <= 0) {
-    throw new RangeError(`${name} must be a positive safe integer.`);
-  }
-}
 function assertNonEmptyString(value, name) {
   if (typeof value !== "string" || value.length === 0) {
     throw new TypeError(`${name} must be a non-empty string.`);
   }
 }
-function assertOptionsObject(value) {
-  if (!isRecord2(value)) throw new TypeError("options must be an object.");
-}
 function isSandboxClient(value) {
-  return isRecord2(value) && typeof value.pullImage === "function" && typeof value.createSandbox === "function" && typeof value.resumeSandbox === "function";
+  return isRecord3(value) && typeof value.pullImage === "function" && typeof value.createSandbox === "function" && typeof value.resumeSandbox === "function";
 }
-function isRecord2(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
+function combineCleanupError2(error, cleanupError, message) {
+  return cleanupError === void 0 ? error : new AggregateError([error, cleanupError], message);
 }
 
 // src/tools.ts
@@ -699,15 +2141,18 @@ var targetSchema = z.discriminatedUnion("by", [
 ]);
 var noInput = z.object({});
 var tabInput = z.object({ tabId: z.string().uuid() });
+var explicitTab = { tabId: z.string().uuid().optional() };
 var navigateInput = z.object({
+  ...explicitTab,
   url: z.url(),
   waitUntil: z.enum(["commit", "domcontentloaded", "load", "networkidle"]).optional()
 });
-var clickInput = z.object({ target: targetSchema });
-var typeInput = z.object({ target: targetSchema, text: z.string() });
-var pressKeyInput = z.object({ key: z.string().min(1).max(100) });
-var screenshotInput = z.object({});
-var defaultActionTimeoutMs = 1e4;
+var clickInput = z.object({ ...explicitTab, target: targetSchema });
+var typeInput = z.object({ ...explicitTab, target: targetSchema, text: z.string() });
+var pressKeyInput = z.object({ ...explicitTab, key: z.string().min(1).max(100) });
+var screenshotInput = z.object(explicitTab);
+var snapshotInput = z.object(explicitTab);
+var defaultActionTimeoutMs2 = 1e4;
 var defaultNavigationTimeoutMs = 3e4;
 var defaultSnapshotMaxChars = 5e4;
 var maxTimeoutMs = 3e5;
@@ -718,20 +2163,20 @@ function createBrowserTools(options) {
   const policy = snapshotNavigationPolicy(options.navigation);
   connection.setNavigationPolicy(policy);
   const limits = {
-    actionTimeoutMs: options.limits?.actionTimeoutMs ?? defaultActionTimeoutMs,
+    actionTimeoutMs: options.limits?.actionTimeoutMs ?? defaultActionTimeoutMs2,
     navigationTimeoutMs: options.limits?.navigationTimeoutMs ?? defaultNavigationTimeoutMs,
     snapshotMaxChars: options.limits?.snapshotMaxChars ?? defaultSnapshotMaxChars
   };
   const tools = options.tools.map((name) => {
     switch (name) {
       case "browser_list_tabs":
-        return createListTabsTool(connection);
+        return createListTabsTool(connection, limits.actionTimeoutMs);
       case "browser_open_tab":
-        return createOpenTabTool(connection);
+        return createOpenTabTool(connection, limits.actionTimeoutMs);
       case "browser_select_tab":
-        return createSelectTabTool(connection);
+        return createSelectTabTool(connection, limits.actionTimeoutMs);
       case "browser_close_tab":
-        return createCloseTabTool(connection);
+        return createCloseTabTool(connection, limits.actionTimeoutMs);
       case "browser_navigate":
         return createNavigateTool(connection, policy, limits.navigationTimeoutMs);
       case "browser_snapshot":
@@ -741,185 +2186,174 @@ function createBrowserTools(options) {
       case "browser_type":
         return createTypeTool(connection, limits.actionTimeoutMs);
       case "browser_press_key":
-        return createPressKeyTool(connection);
+        return createPressKeyTool(connection, limits.actionTimeoutMs);
       case "browser_screenshot":
-        return createScreenshotTool(connection);
+        return createScreenshotTool(connection, limits.actionTimeoutMs);
       default:
         return assertNever(name);
     }
   });
   return Object.freeze(tools);
 }
-function createListTabsTool(connection) {
+function createListTabsTool(connection, timeoutMs) {
   return createTool({
     name: "browser_list_tabs",
     description: "List Chromium tabs and identify the tab selected for subsequent browser tools.",
     inputSchema: noInput,
-    execute: async () => ({ tabs: await connection.listTabs() })
+    execute: async (_args, context) => ({
+      tabs: await connection.listTabs({ abortSignal: context.abortSignal, timeoutMs })
+    })
   });
 }
-function createOpenTabTool(connection) {
+function createOpenTabTool(connection, timeoutMs) {
   return createTool({
     name: "browser_open_tab",
     description: "Open and select a new blank Chromium tab.",
     inputSchema: noInput,
-    execute: async (_args, context) => connection.runAction(context.abortSignal, async () => {
-      const page = await connection.openTab();
-      return tabResult(connection, page);
-    })
+    execute: async (_args, context) => connection.openTab(context.abortSignal, timeoutMs)
   });
 }
-function createSelectTabTool(connection) {
+function createSelectTabTool(connection, timeoutMs) {
   return createTool({
     name: "browser_select_tab",
     description: "Select an existing Chromium tab by its browser tab ID.",
     inputSchema: tabInput,
-    execute: async ({ tabId }, context) => connection.runAction(
-      context.abortSignal,
-      async () => tabResult(connection, connection.selectTab(tabId))
-    )
+    execute: async ({ tabId }, context) => connection.selectTab(tabId, context.abortSignal, timeoutMs)
   });
 }
-function createCloseTabTool(connection) {
+function createCloseTabTool(connection, timeoutMs) {
   return createTool({
     name: "browser_close_tab",
     description: "Close an existing Chromium tab by its browser tab ID.",
     inputSchema: tabInput,
-    execute: async ({ tabId }, context) => connection.runAction(context.abortSignal, async () => {
-      await connection.closeTab(tabId);
-      return { closedTabId: tabId, tabs: await connection.tabSummaries() };
-    })
+    execute: async ({ tabId }, context) => connection.closeTab(tabId, context.abortSignal, timeoutMs)
   });
 }
 function createNavigateTool(connection, policy, timeoutMs) {
   return createTool({
     name: "browser_navigate",
-    description: "Navigate the selected Chromium tab to an allowed HTTP or HTTPS URL.",
+    description: "Navigate an explicit tab, or the selected tab in serial compatibility mode, to an allowed HTTP or HTTPS URL.",
     inputSchema: navigateInput,
-    execute: async ({ url, waitUntil }, context) => connection.runAction(context.abortSignal, async () => {
+    execute: async ({ tabId, url, waitUntil }, context) => {
       assertNavigationAllowed(url, policy);
-      const page = connection.selectedPage();
-      await page.goto(url, {
-        timeout: timeoutMs,
-        waitUntil: waitUntil ?? "load"
+      const result = await connection.runTabCommand({
+        tabId,
+        abortSignal: context.abortSignal,
+        timeoutMs,
+        phase: "navigate",
+        command: (targetTabId) => ({
+          method: "navigate",
+          params: {
+            tabId: targetTabId,
+            url,
+            waitUntil: waitUntil ?? "load",
+            timeoutMs
+          }
+        })
       });
-      assertNavigationAllowed(page.url(), policy);
-      return tabResult(connection, page);
-    })
+      assertNavigationAllowed(result.url, policy);
+      return result;
+    }
   });
 }
 function createSnapshotTool(connection, timeoutMs, maxChars) {
   return createTool({
     name: "browser_snapshot",
-    description: "Inspect the selected tab using a bounded ARIA accessibility snapshot.",
-    inputSchema: noInput,
-    execute: async (_args, context) => connection.runAction(context.abortSignal, async () => {
-      const page = connection.selectedPage();
-      const snapshot = await page.locator("body").ariaSnapshot({ timeout: timeoutMs });
-      const truncated = snapshot.length > maxChars;
-      return {
-        ...await tabResult(connection, page),
-        snapshot: truncated ? snapshot.slice(0, maxChars) : snapshot,
-        truncated
-      };
+    description: "Inspect an explicit tab, or the selected tab in serial compatibility mode, using a bounded ARIA accessibility snapshot.",
+    inputSchema: snapshotInput,
+    execute: async ({ tabId }, context) => connection.runTabCommand({
+      tabId,
+      abortSignal: context.abortSignal,
+      timeoutMs,
+      phase: "snapshot",
+      command: (targetTabId) => ({
+        method: "snapshot",
+        params: { tabId: targetTabId, timeoutMs, maxChars }
+      })
     })
   });
 }
 function createClickTool(connection, timeoutMs) {
   return createTool({
     name: "browser_click",
-    description: "Click one strictly matched element in the selected tab.",
+    description: "Click one strictly matched element in an explicit tab or the selected tab.",
     inputSchema: clickInput,
-    execute: async ({ target }, context) => connection.runAction(context.abortSignal, async () => {
-      const page = connection.selectedPage();
-      await locatorFor(page, target).click({ timeout: timeoutMs });
-      return tabResult(connection, page);
+    execute: async ({ tabId, target }, context) => connection.runTabCommand({
+      tabId,
+      abortSignal: context.abortSignal,
+      timeoutMs,
+      phase: "click",
+      command: (targetTabId) => ({
+        method: "click",
+        params: { tabId: targetTabId, target, timeoutMs }
+      })
     })
   });
 }
 function createTypeTool(connection, timeoutMs) {
   return createTool({
     name: "browser_type",
-    description: "Replace the value of one strictly matched editable element.",
+    description: "Replace the value of one strictly matched editable element in an explicit or selected tab.",
     inputSchema: typeInput,
-    execute: async ({ target, text }, context) => connection.runAction(context.abortSignal, async () => {
-      const page = connection.selectedPage();
-      await locatorFor(page, target).fill(text, { timeout: timeoutMs });
-      return tabResult(connection, page);
+    execute: async ({ tabId, target, text }, context) => connection.runTabCommand({
+      tabId,
+      abortSignal: context.abortSignal,
+      timeoutMs,
+      phase: "type",
+      command: (targetTabId) => ({
+        method: "type",
+        params: { tabId: targetTabId, target, text, timeoutMs }
+      })
     })
   });
 }
-function createPressKeyTool(connection) {
+function createPressKeyTool(connection, timeoutMs) {
   return createTool({
     name: "browser_press_key",
-    description: "Press an explicit keyboard key or key combination in the selected tab.",
+    description: "Press an explicit keyboard key or key combination in an explicit or selected tab.",
     inputSchema: pressKeyInput,
-    execute: async ({ key }, context) => connection.runAction(context.abortSignal, async () => {
-      const page = connection.selectedPage();
-      await page.keyboard.press(key);
-      return tabResult(connection, page);
+    execute: async ({ tabId, key }, context) => connection.runTabCommand({
+      tabId,
+      abortSignal: context.abortSignal,
+      timeoutMs,
+      phase: "press-key",
+      command: (targetTabId) => ({
+        method: "pressKey",
+        params: { tabId: targetTabId, key }
+      })
     })
   });
 }
-function createScreenshotTool(connection) {
+function createScreenshotTool(connection, timeoutMs) {
   return createTool({
     name: "browser_screenshot",
-    description: "Capture the visible viewport of the selected Chromium tab as PNG.",
+    description: "Capture the visible viewport of an explicit or selected Chromium tab as PNG.",
     inputSchema: screenshotInput,
-    execute: async (_args, context) => connection.runAction(context.abortSignal, async () => {
-      const page = connection.selectedPage();
-      const png = await page.screenshot({ type: "png", fullPage: false });
-      const metadata = await tabResult(connection, page);
+    execute: async ({ tabId }, context) => {
+      const result = await connection.runTabCommand({
+        tabId,
+        abortSignal: context.abortSignal,
+        timeoutMs,
+        phase: "screenshot",
+        command: (targetTabId) => ({
+          method: "screenshot",
+          params: { tabId: targetTabId, timeoutMs }
+        })
+      });
       return ToolOutput.content([
-        { type: "text", text: JSON.stringify(metadata) },
+        { type: "text", text: JSON.stringify(result.metadata) },
         {
           type: "file",
-          data: { type: "data", data: png.toString("base64") },
+          data: { type: "data", data: result.pngBase64 },
           mediaType: "image/png",
           filename: "browser-screenshot.png"
         }
       ]);
-    })
-  });
-}
-async function tabResult(connection, page) {
-  return {
-    tabId: connection.idFor(page),
-    title: await page.title(),
-    url: page.url()
-  };
-}
-function locatorFor(page, target) {
-  switch (target.by) {
-    case "role": {
-      const options = {};
-      if (target.name !== void 0) options.name = target.name;
-      if (target.exact !== void 0) options.exact = target.exact;
-      return page.getByRole(target.role, options);
-    }
-    case "text": {
-      const options = {};
-      if (target.exact !== void 0) options.exact = target.exact;
-      return page.getByText(target.text, options);
-    }
-    case "label": {
-      const options = {};
-      if (target.exact !== void 0) options.exact = target.exact;
-      return page.getByLabel(target.label, options);
-    }
-    case "placeholder": {
-      const options = {};
-      if (target.exact !== void 0) options.exact = target.exact;
-      return page.getByPlaceholder(target.placeholder, options);
     }
-    case "test-id":
-      return page.getByTestId(target.testId);
-    case "css":
-      return page.locator(target.selector);
-  }
+  });
 }
 function snapshotNavigationPolicy(policy) {
-  if (!isRecord3(policy)) throw new TypeError("navigation must be an object.");
+  if (!isRecord5(policy)) throw new TypeError("navigation must be an object.");
   if (policy.mode === "allow-all-http") return Object.freeze({ mode: "allow-all-http" });
   if (policy.mode !== "origins" || !Array.isArray(policy.origins) || policy.origins.length === 0) {
     throw new TypeError(
@@ -941,11 +2375,11 @@ function normalizeOrigin(value) {
   return url.origin;
 }
 function assertNavigationAllowed(value, policy) {
-  if (!isNavigationAllowed2(value, policy)) {
+  if (!isNavigationAllowed(value, policy)) {
     throw new BrowserError(`Browser navigation is blocked: ${value}`, "navigation_blocked");
   }
 }
-function isNavigationAllowed2(value, policy) {
+function isNavigationAllowed(value, policy) {
   let url;
   try {
     url = parseHttpUrl(value);
@@ -965,7 +2399,7 @@ function parseHttpUrl(value) {
   return url;
 }
 function validateFactoryOptions(options) {
-  if (!isRecord3(options)) throw new TypeError("options must be an object.");
+  if (!isRecord5(options)) throw new TypeError("options must be an object.");
   if (!Array.isArray(options.tools) || options.tools.length === 0) {
     throw new TypeError("tools must be a non-empty array.");
   }
@@ -976,7 +2410,7 @@ function validateFactoryOptions(options) {
     seen.add(name);
   }
   snapshotNavigationPolicy(options.navigation);
-  if (options.limits !== void 0 && !isRecord3(options.limits)) {
+  if (options.limits !== void 0 && !isRecord5(options.limits)) {
     throw new TypeError("limits must be an object.");
   }
   assertOptionalBoundedInteger(options.limits?.actionTimeoutMs, "actionTimeoutMs", 1, maxTimeoutMs);
@@ -1012,7 +2446,7 @@ function isToolName(value) {
     "browser_screenshot"
   ].includes(value);
 }
-function isRecord3(value) {
+function isRecord5(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function assertNever(value) {