@ricsam/r5d-browser 0.0.50 → 0.0.53

package/dist/cjs/chrome-launcher.cjs

@@ -0,0 +1,680 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var chrome_launcher_exports = {};
+__export(chrome_launcher_exports, {
+  acquireChromeRunLock: () => acquireChromeRunLock,
+  assertChromeProfileAvailable: () => assertChromeProfileAvailable,
+  buildChromeLaunchArgs: () => buildChromeLaunchArgs,
+  defaultChromeLockPath: () => defaultChromeLockPath,
+  defaultChromeProfilePath: () => defaultChromeProfilePath,
+  launchStableChrome: () => launchStableChrome,
+  resolveChromeExecutable: () => resolveChromeExecutable,
+  validateChromeProfilePath: () => validateChromeProfilePath,
+  validateDebuggerWebSocketUrl: () => validateDebuggerWebSocketUrl,
+  validateEndpointOwnership: () => validateEndpointOwnership
+});
+module.exports = __toCommonJS(chrome_launcher_exports);
+var import_node_child_process = require("node:child_process");
+var import_node_fs = __toESM(require("node:fs"), 1);
+var import_node_http = __toESM(require("node:http"), 1);
+var import_node_net = __toESM(require("node:net"), 1);
+var import_node_os = __toESM(require("node:os"), 1);
+var import_node_path = __toESM(require("node:path"), 1);
+var import_promises = require("node:timers/promises");
+var import_playwright_core = require("playwright-core");
+var import_ws = __toESM(require("ws"), 1);
+const DEFAULT_STARTUP_TIMEOUT_MS = 15e3;
+const MAX_LAUNCH_ATTEMPTS = 3;
+const GRACEFUL_CLOSE_TIMEOUT_MS = 5e3;
+const TERMINATE_TIMEOUT_MS = 3e3;
+const CDP_REQUEST_TIMEOUT_MS = 2e3;
+const MAX_DIAGNOSTIC_BYTES = 32 * 1024;
+const SYSTEM_CHROME_PATH = "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome";
+class DebuggerPortCollisionError extends Error {
+}
+class ChromeExitedDuringStartupError extends Error {
+}
+function defaultChromeProfilePath(homeDirectory = import_node_os.default.homedir()) {
+  return import_node_path.default.join(homeDirectory, ".r5d", "browser", "chrome-profile");
+}
+function defaultChromeLockPath(homeDirectory = import_node_os.default.homedir()) {
+  return import_node_path.default.join(homeDirectory, ".r5d", "browser", "run.lock");
+}
+function describeChromeRequirement() {
+  return "Install stable Google Chrome from https://www.google.com/chrome/ or pass --chrome-path (or R5D_BROWSER_CHROME_PATH).";
+}
+function validateExecutable(candidate, source) {
+  const resolved = import_node_path.default.resolve(candidate);
+  try {
+    const stats = import_node_fs.default.statSync(resolved);
+    if (!stats.isFile()) throw new Error("not a regular file");
+    import_node_fs.default.accessSync(resolved, import_node_fs.default.constants.X_OK);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `Google Chrome from ${source} is not an executable regular file: ${resolved} (${detail}). ${describeChromeRequirement()}`
+    );
+  }
+  return resolved;
+}
+function resolveChromeExecutable(options = {}) {
+  const env = options.env ?? process.env;
+  const homeDirectory = options.homeDirectory ?? import_node_os.default.homedir();
+  if (options.chromePath !== void 0) return validateExecutable(options.chromePath, "--chrome-path");
+  if (env.R5D_BROWSER_CHROME_PATH !== void 0) {
+    return validateExecutable(env.R5D_BROWSER_CHROME_PATH, "R5D_BROWSER_CHROME_PATH");
+  }
+  const candidates = [
+    options.systemChromePath ?? SYSTEM_CHROME_PATH,
+    import_node_path.default.join(homeDirectory, "Applications", "Google Chrome.app", "Contents", "MacOS", "Google Chrome")
+  ];
+  for (const candidate of candidates) {
+    try {
+      return validateExecutable(candidate, "the standard installation location");
+    } catch {
+    }
+  }
+  throw new Error(`Stable Google Chrome could not be found. ${describeChromeRequirement()}`);
+}
+function canonicalizePotentialPath(candidate) {
+  const resolved = import_node_path.default.resolve(candidate);
+  let existing = resolved;
+  const missingSegments = [];
+  while (!import_node_fs.default.existsSync(existing)) {
+    const parent = import_node_path.default.dirname(existing);
+    if (parent === existing) return resolved;
+    missingSegments.unshift(import_node_path.default.basename(existing));
+    existing = parent;
+  }
+  try {
+    return import_node_path.default.join(import_node_fs.default.realpathSync.native(existing), ...missingSegments);
+  } catch {
+    return resolved;
+  }
+}
+function validateChromeProfilePath(profilePath, homeDirectory = import_node_os.default.homedir()) {
+  const canonicalProfile = canonicalizePotentialPath(profilePath);
+  const dailyDriverRoot = canonicalizePotentialPath(import_node_path.default.join(homeDirectory, "Library", "Application Support", "Google", "Chrome"));
+  if (canonicalProfile === dailyDriverRoot || canonicalProfile.startsWith(`${dailyDriverRoot}${import_node_path.default.sep}`)) {
+    throw new Error(
+      `Refusing to control Chrome's daily-driver profile at ${import_node_path.default.resolve(profilePath)}. Use the dedicated r5d-browser profile or another separate directory.`
+    );
+  }
+  return canonicalProfile;
+}
+function isProcessAlive(pid) {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+}
+function readLockRecord(lockPath) {
+  const stats = import_node_fs.default.lstatSync(lockPath);
+  if (!stats.isFile() || stats.isSymbolicLink()) throw new Error(`Browser run lock is not a regular file: ${lockPath}`);
+  const raw = import_node_fs.default.readFileSync(lockPath, "utf8");
+  const parsed = JSON.parse(raw);
+  if (!Number.isSafeInteger(parsed.pid) || Number(parsed.pid) <= 0 || typeof parsed.profilePath !== "string" || typeof parsed.token !== "string" || !parsed.token || typeof parsed.createdAt !== "string") {
+    throw new Error(`Browser run lock has invalid contents: ${lockPath}`);
+  }
+  return { raw, record: parsed, stats };
+}
+function acquireChromeRunLock(lockPath, profilePath, ownerPid = process.pid) {
+  const resolvedLockPath = import_node_path.default.resolve(lockPath);
+  import_node_fs.default.mkdirSync(import_node_path.default.dirname(resolvedLockPath), { recursive: true, mode: 448 });
+  for (let attempt = 0; attempt < 10; attempt += 1) {
+    const token = crypto.randomUUID();
+    const record = {
+      pid: ownerPid,
+      profilePath: import_node_path.default.resolve(profilePath),
+      token,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    let descriptor;
+    try {
+      descriptor = import_node_fs.default.openSync(resolvedLockPath, import_node_fs.default.constants.O_CREAT | import_node_fs.default.constants.O_EXCL | import_node_fs.default.constants.O_WRONLY, 384);
+      import_node_fs.default.writeFileSync(descriptor, `${JSON.stringify(record)}
+`, "utf8");
+      import_node_fs.default.fsyncSync(descriptor);
+      import_node_fs.default.closeSync(descriptor);
+      descriptor = void 0;
+      let released = false;
+      return {
+        lockPath: resolvedLockPath,
+        token,
+        release: () => {
+          if (released) return;
+          released = true;
+          try {
+            const current = readLockRecord(resolvedLockPath);
+            if (current.record.token === token) import_node_fs.default.unlinkSync(resolvedLockPath);
+          } catch (error) {
+            if (error.code !== "ENOENT") {
+              process.stderr.write(`[r5d-browser] could not release run lock: ${error instanceof Error ? error.message : String(error)}
+`);
+            }
+          }
+        }
+      };
+    } catch (error) {
+      if (descriptor !== void 0) {
+        try {
+          import_node_fs.default.closeSync(descriptor);
+        } catch {
+        }
+      }
+      const code = error.code;
+      if (code !== "EEXIST") {
+        try {
+          const current = readLockRecord(resolvedLockPath);
+          if (current.record.token === token) import_node_fs.default.unlinkSync(resolvedLockPath);
+        } catch {
+        }
+        throw error;
+      }
+      let existing;
+      try {
+        existing = readLockRecord(resolvedLockPath);
+      } catch (readError) {
+        throw new Error(
+          `Cannot safely inspect the existing browser run lock at ${resolvedLockPath}: ${readError instanceof Error ? readError.message : String(readError)}`
+        );
+      }
+      if (isProcessAlive(existing.record.pid)) {
+        throw new Error(
+          `r5d-browser is already running (PID ${existing.record.pid}, profile ${existing.record.profilePath}). Only one browser may run at a time.`
+        );
+      }
+      try {
+        const currentStats = import_node_fs.default.lstatSync(resolvedLockPath);
+        const currentRaw = import_node_fs.default.readFileSync(resolvedLockPath, "utf8");
+        if (currentStats.dev !== existing.stats.dev || currentStats.ino !== existing.stats.ino || currentRaw !== existing.raw) continue;
+        import_node_fs.default.unlinkSync(resolvedLockPath);
+      } catch (unlinkError) {
+        if (unlinkError.code !== "ENOENT") throw unlinkError;
+      }
+    }
+  }
+  throw new Error(`Could not acquire browser run lock after repeated concurrent changes: ${resolvedLockPath}`);
+}
+function singletonLockOwner(profilePath) {
+  const singletonLockPath = import_node_path.default.join(profilePath, "SingletonLock");
+  let target;
+  try {
+    target = import_node_fs.default.readlinkSync(singletonLockPath);
+  } catch (error) {
+    if (error.code === "ENOENT") return void 0;
+    return { description: singletonLockPath };
+  }
+  const match = /-(\d+)$/.exec(target);
+  const pid = match ? Number(match[1]) : void 0;
+  return { description: target, pid: Number.isSafeInteger(pid) ? pid : void 0 };
+}
+function assertChromeProfileAvailable(profilePath) {
+  const owner = singletonLockOwner(profilePath);
+  if (!owner) return;
+  if (owner.pid !== void 0 && !isProcessAlive(owner.pid)) return;
+  const ownerText = owner.pid === void 0 ? owner.description : `PID ${owner.pid}`;
+  throw new Error(
+    `The dedicated Google Chrome profile is already open (${ownerText}). Quit that Chrome window before starting r5d-browser; it will not attach to or terminate an existing browser.`
+  );
+}
+function buildChromeLaunchArgs(profilePath, debuggingPort) {
+  if (!Number.isInteger(debuggingPort) || debuggingPort < 1 || debuggingPort > 65535) {
+    throw new Error(`Invalid Chrome debugging port: ${debuggingPort}`);
+  }
+  return [
+    `--user-data-dir=${import_node_path.default.resolve(profilePath)}`,
+    "--remote-debugging-address=127.0.0.1",
+    `--remote-debugging-port=${debuggingPort}`,
+    "--no-first-run",
+    "--no-default-browser-check",
+    "--new-window",
+    "about:blank"
+  ];
+}
+function validateDebuggerWebSocketUrl(webSocketDebuggerUrl, debuggingPort) {
+  let parsed;
+  try {
+    parsed = new URL(webSocketDebuggerUrl);
+  } catch {
+    throw new DebuggerPortCollisionError("Chrome returned an invalid DevTools WebSocket URL.");
+  }
+  if (parsed.protocol !== "ws:" || parsed.hostname !== "127.0.0.1" || Number(parsed.port) !== debuggingPort || !/^\/devtools\/browser\/[^/]+$/.test(parsed.pathname) || parsed.username || parsed.password || parsed.search || parsed.hash) {
+    throw new DebuggerPortCollisionError(`Refusing unexpected DevTools WebSocket endpoint: ${webSocketDebuggerUrl}`);
+  }
+  return parsed.toString();
+}
+async function allocateLoopbackPort() {
+  const server = import_node_net.default.createServer();
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen({ host: "127.0.0.1", port: 0, exclusive: true }, () => resolve());
+  });
+  const address = server.address();
+  if (!address || typeof address === "string") {
+    server.close();
+    throw new Error("Could not allocate a loopback debugging port.");
+  }
+  const port = address.port;
+  await new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));
+  return port;
+}
+async function readDebuggerVersion(debuggingPort) {
+  return await new Promise((resolve, reject) => {
+    const request = import_node_http.default.get({ host: "127.0.0.1", port: debuggingPort, path: "/json/version", timeout: 500 }, (response) => {
+      const chunks = [];
+      let length = 0;
+      response.on("data", (chunk) => {
+        length += chunk.byteLength;
+        if (length > 1024 * 1024) {
+          request.destroy(new DebuggerPortCollisionError("DevTools version response exceeded 1 MiB."));
+          return;
+        }
+        chunks.push(chunk);
+      });
+      response.on("end", () => {
+        if (response.statusCode !== 200) {
+          reject(new DebuggerPortCollisionError(`Unexpected response on Chrome debugging port: HTTP ${response.statusCode ?? "unknown"}.`));
+          return;
+        }
+        try {
+          resolve(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+        } catch {
+          reject(new DebuggerPortCollisionError("Unexpected non-JSON response on Chrome debugging port."));
+        }
+      });
+    });
+    request.once("timeout", () => request.destroy());
+    request.once("error", (error) => {
+      if (error.code === "ECONNREFUSED" || error.code === "ECONNRESET" || error.code === "ETIMEDOUT" || error.message === "socket hang up") {
+        resolve(void 0);
+      } else {
+        reject(error);
+      }
+    });
+  });
+}
+async function waitForDebuggerEndpoint(params) {
+  let exitResult;
+  params.exited.then((result) => {
+    exitResult = result;
+  });
+  const deadline = Date.now() + params.startupTimeoutMs;
+  while (Date.now() < deadline) {
+    if (exitResult) {
+      const detail = params.stderr().trim();
+      throw new ChromeExitedDuringStartupError(
+        `Google Chrome exited before its control endpoint became ready (${exitResult.signal ? `signal ${exitResult.signal}` : `code ${exitResult.code ?? "unknown"}`})${detail ? `: ${detail}` : "."}`
+      );
+    }
+    const version = await readDebuggerVersion(params.debuggingPort);
+    if (version) {
+      if (typeof version.webSocketDebuggerUrl !== "string") {
+        throw new DebuggerPortCollisionError("Chrome debugging endpoint did not return a WebSocket URL.");
+      }
+      return {
+        webSocketDebuggerUrl: validateDebuggerWebSocketUrl(version.webSocketDebuggerUrl, params.debuggingPort),
+        version
+      };
+    }
+    await (0, import_promises.setTimeout)(100);
+  }
+  throw new DebuggerPortCollisionError(`Google Chrome control endpoint did not become ready within ${params.startupTimeoutMs} ms.`);
+}
+class RawCdpConnection {
+  constructor(socket) {
+    this.socket = socket;
+    socket.on("message", (data) => {
+      let message;
+      try {
+        message = JSON.parse(data.toString());
+      } catch {
+        return;
+      }
+      if (typeof message.id !== "number") {
+        this.onmessage?.(message);
+        return;
+      }
+      const pending = this.pending.get(message.id);
+      if (!pending) {
+        this.onmessage?.(message);
+        return;
+      }
+      this.pending.delete(message.id);
+      clearTimeout(pending.timer);
+      if (message.error)
+        pending.reject(new Error(typeof message.error.message === "string" ? message.error.message : "CDP request failed."));
+      else pending.resolve(message.result);
+    });
+    const rejectPending = (error) => {
+      for (const pending of this.pending.values()) {
+        clearTimeout(pending.timer);
+        pending.reject(error);
+      }
+      this.pending.clear();
+    };
+    socket.on("error", (error) => rejectPending(error));
+    socket.once("close", (_code, reason) => {
+      rejectPending(new Error("Chrome DevTools connection closed."));
+      this.onclose?.(reason.toString());
+    });
+  }
+  socket;
+  nextId = 1;
+  pending = /* @__PURE__ */ new Map();
+  onmessage;
+  onclose;
+  static async connect(endpoint) {
+    const socket = new import_ws.default(endpoint);
+    socket.on("error", () => void 0);
+    await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        socket.terminate();
+        reject(new Error("Timed out connecting to Chrome DevTools."));
+      }, CDP_REQUEST_TIMEOUT_MS);
+      socket.once("open", () => {
+        clearTimeout(timer);
+        resolve();
+      });
+      socket.once("error", (error) => {
+        clearTimeout(timer);
+        reject(error);
+      });
+    });
+    return new RawCdpConnection(socket);
+  }
+  send(methodOrMessage, params = {}) {
+    if (typeof methodOrMessage !== "string") {
+      this.socket.send(JSON.stringify(methodOrMessage));
+      return;
+    }
+    const method = methodOrMessage;
+    const id = this.nextId++;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`Timed out waiting for ${method}.`));
+      }, CDP_REQUEST_TIMEOUT_MS);
+      this.pending.set(id, { resolve, reject, timer });
+      this.socket.send(JSON.stringify({ id, method, params }), (error) => {
+        if (!error) return;
+        const pending = this.pending.get(id);
+        if (!pending) return;
+        this.pending.delete(id);
+        clearTimeout(pending.timer);
+        pending.reject(error);
+      });
+    });
+  }
+  async sendBrowserClose() {
+    await Promise.race([
+      this.send("Browser.close").then(() => void 0),
+      new Promise((resolve) => this.socket.once("close", () => resolve()))
+    ]);
+  }
+  close() {
+    if (this.socket.readyState !== import_ws.default.CLOSED) this.socket.terminate();
+  }
+}
+function validateEndpointOwnership(params) {
+  const browserProcess = params.processInfo?.find((processInfo) => processInfo.type === "browser");
+  if (!browserProcess || Number(browserProcess.id) !== params.chromePid) {
+    throw new DebuggerPortCollisionError("The DevTools endpoint belongs to a different browser process.");
+  }
+  if (typeof params.product !== "string" || !params.product) throw new Error("Chrome did not report its version.");
+  if (typeof params.commandLine !== "string" || !params.commandLine) {
+    throw new DebuggerPortCollisionError("The DevTools endpoint did not report its browser command line.");
+  }
+  const commandLine = params.commandLine;
+  if (!commandLine.includes(params.chromePath) || params.launchArgs.some((argument) => !commandLine.includes(argument))) {
+    throw new DebuggerPortCollisionError("The DevTools process command line does not match the Chrome process launched by r5d-browser.");
+  }
+  for (const forbidden of ["--enable-automation", "--remote-debugging-pipe", "--remote-debugging-port=0", "AutomationControlled"]) {
+    if (commandLine.includes(forbidden)) throw new Error(`Chrome unexpectedly started with forbidden automation flag ${forbidden}.`);
+  }
+  return params.product;
+}
+async function verifyEndpointOwnership(params) {
+  const cdp = await RawCdpConnection.connect(params.webSocketDebuggerUrl);
+  try {
+    const processResult = await cdp.send("SystemInfo.getProcessInfo");
+    const version = await cdp.send("Browser.getVersion");
+    const systemInfo = await cdp.send("SystemInfo.getInfo");
+    const chromeProduct = validateEndpointOwnership({
+      chromePid: params.chromePid,
+      chromePath: params.chromePath,
+      launchArgs: params.launchArgs,
+      processInfo: processResult.processInfo,
+      product: version.product,
+      commandLine: systemInfo.commandLine
+    });
+    return { chromeProduct, transport: cdp };
+  } catch (error) {
+    cdp.close();
+    throw error;
+  }
+}
+function observeChild(child) {
+  let diagnostics = "";
+  child.stderr?.on("data", (chunk) => {
+    diagnostics += chunk.toString();
+    if (Buffer.byteLength(diagnostics) > MAX_DIAGNOSTIC_BYTES) diagnostics = diagnostics.slice(-MAX_DIAGNOSTIC_BYTES);
+  });
+  const exited = new Promise((resolve) => {
+    let settled = false;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      resolve(result);
+    };
+    child.once("exit", (code, signal) => finish({ code, signal }));
+    child.once("error", (error) => {
+      diagnostics += `${diagnostics ? "\n" : ""}${error.message}`;
+      finish({ code: null, signal: null });
+    });
+  });
+  return { exited, stderr: () => diagnostics };
+}
+async function waitForExit(exited, timeoutMs) {
+  let timer;
+  try {
+    return await Promise.race([
+      exited.then(() => true),
+      new Promise((resolve) => {
+        timer = setTimeout(() => resolve(false), timeoutMs);
+      })
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+async function requestOwnedBrowserClose(webSocketDebuggerUrl, chromePid) {
+  const cdp = await RawCdpConnection.connect(webSocketDebuggerUrl);
+  try {
+    const processResult = await cdp.send("SystemInfo.getProcessInfo");
+    const browserProcess = processResult.processInfo?.find((processInfo) => processInfo.type === "browser");
+    if (!browserProcess || Number(browserProcess.id) !== chromePid) return false;
+    await cdp.sendBrowserClose();
+    return true;
+  } finally {
+    cdp.close();
+  }
+}
+async function terminateOwnedProcess(params) {
+  if (params.child.exitCode !== null || params.child.signalCode !== null) return;
+  if (params.browser?.isConnected()) {
+    void params.browser.newBrowserCDPSession().then(async (cdp) => {
+      await cdp.send("Browser.close");
+    }).catch(() => void 0);
+    if (await waitForExit(params.exited, GRACEFUL_CLOSE_TIMEOUT_MS)) return;
+  } else if (params.ownedWebSocketDebuggerUrl) {
+    const closeRequested = await requestOwnedBrowserClose(params.ownedWebSocketDebuggerUrl, params.chromePid).catch(() => false);
+    if (closeRequested && await waitForExit(params.exited, GRACEFUL_CLOSE_TIMEOUT_MS)) return;
+  }
+  if (params.child.exitCode === null && params.child.signalCode === null) params.child.kill("SIGTERM");
+  if (await waitForExit(params.exited, TERMINATE_TIMEOUT_MS)) return;
+  if (params.child.exitCode === null && params.child.signalCode === null) params.child.kill("SIGKILL");
+  await waitForExit(params.exited, TERMINATE_TIMEOUT_MS);
+}
+function occupiedProfileError(profilePath) {
+  const owner = singletonLockOwner(profilePath);
+  if (!owner) return void 0;
+  if (owner.pid !== void 0 && !isProcessAlive(owner.pid)) return void 0;
+  const ownerText = owner.pid === void 0 ? owner.description : `PID ${owner.pid}`;
+  return new Error(
+    `The dedicated Google Chrome profile is already open (${ownerText}). Quit that Chrome window before starting r5d-browser; it will not attach to or terminate an existing browser.`
+  );
+}
+async function launchStableChrome(options) {
+  if (process.platform !== "darwin") throw new Error("r5d-browser currently supports macOS only.");
+  const startupTimeoutMs = options.startupTimeoutMs ?? DEFAULT_STARTUP_TIMEOUT_MS;
+  if (!Number.isFinite(startupTimeoutMs) || startupTimeoutMs <= 0) throw new Error("startupTimeoutMs must be positive.");
+  const chromePath = resolveChromeExecutable({ chromePath: options.chromePath });
+  const profilePath = validateChromeProfilePath(options.profilePath);
+  const playwrightDownloadsPath = import_node_path.default.resolve(options.playwrightDownloadsPath);
+  const lock = acquireChromeRunLock(options.lockPath ?? defaultChromeLockPath(), profilePath);
+  try {
+    import_node_fs.default.mkdirSync(profilePath, { recursive: true, mode: 448 });
+    import_node_fs.default.mkdirSync(playwrightDownloadsPath, { recursive: true, mode: 448 });
+    import_node_fs.default.chmodSync(profilePath, 448);
+    import_node_fs.default.chmodSync(playwrightDownloadsPath, 448);
+    assertChromeProfileAvailable(profilePath);
+    let lastError;
+    for (let attempt = 1; attempt <= MAX_LAUNCH_ATTEMPTS; attempt += 1) {
+      const debuggingPort = await allocateLoopbackPort();
+      const launchArgs = buildChromeLaunchArgs(profilePath, debuggingPort);
+      const child = (0, import_node_child_process.spawn)(chromePath, launchArgs, { stdio: ["ignore", "ignore", "pipe"] });
+      const observed = observeChild(child);
+      const chromePid = child.pid;
+      if (chromePid === void 0) {
+        await observed.exited;
+        throw new Error(`Could not start Google Chrome${observed.stderr().trim() ? `: ${observed.stderr().trim()}` : "."}`);
+      }
+      let ownedWebSocketDebuggerUrl;
+      try {
+        const endpoint = await waitForDebuggerEndpoint({
+          debuggingPort,
+          exited: observed.exited,
+          startupTimeoutMs,
+          stderr: observed.stderr
+        });
+        const ownedEndpoint = await verifyEndpointOwnership({
+          webSocketDebuggerUrl: endpoint.webSocketDebuggerUrl,
+          chromePid,
+          chromePath,
+          launchArgs
+        });
+        ownedWebSocketDebuggerUrl = endpoint.webSocketDebuggerUrl;
+        const browser = await import_playwright_core.chromium.connectOverCDP(ownedEndpoint.transport, {
+          artifactsDir: playwrightDownloadsPath,
+          isLocal: true,
+          noDefaults: false,
+          timeout: startupTimeoutMs
+        });
+        const context = browser.contexts()[0];
+        if (!context) throw new Error("Google Chrome did not expose its default browser context.");
+        const chromeVersion = browser.version();
+        if (!/^\d+(?:\.\d+)+$/.test(chromeVersion)) throw new Error(`Google Chrome reported an invalid version: ${chromeVersion}`);
+        const hadExistingPages = context.pages().length > 0;
+        const verificationPage = await context.newPage();
+        try {
+          await verificationPage.goto("about:blank");
+          if (await verificationPage.evaluate(() => navigator.webdriver) !== false) {
+            throw new Error("Google Chrome unexpectedly exposed navigator.webdriver; refusing an automation-marked session.");
+          }
+        } finally {
+          if (hadExistingPages) await verificationPage.close().catch(() => void 0);
+        }
+        const disconnected = browser.isConnected() ? new Promise((resolve) => browser.once("disconnected", () => resolve())) : Promise.resolve();
+        let closePromise;
+        const close = () => {
+          closePromise ??= (async () => {
+            try {
+              await terminateOwnedProcess({
+                child,
+                exited: observed.exited,
+                chromePid,
+                ownedWebSocketDebuggerUrl,
+                browser
+              });
+              await browser.close().catch(() => void 0);
+            } finally {
+              lock.release();
+            }
+          })();
+          return closePromise;
+        };
+        return {
+          browser,
+          context,
+          chromeVersion,
+          chromePid,
+          debuggingPort,
+          profilePath,
+          exited: observed.exited,
+          disconnected,
+          close
+        };
+      } catch (error) {
+        lastError = error;
+        await terminateOwnedProcess({
+          child,
+          exited: observed.exited,
+          chromePid,
+          ownedWebSocketDebuggerUrl
+        });
+        const occupied = occupiedProfileError(profilePath);
+        if (occupied) throw occupied;
+        if (!(error instanceof DebuggerPortCollisionError)) throw error;
+      }
+    }
+    throw new Error(
+      `Could not launch Google Chrome after ${MAX_LAUNCH_ATTEMPTS} attempts: ${lastError instanceof Error ? lastError.message : String(lastError)}`
+    );
+  } catch (error) {
+    lock.release();
+    throw error;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  acquireChromeRunLock,
+  assertChromeProfileAvailable,
+  buildChromeLaunchArgs,
+  defaultChromeLockPath,
+  defaultChromeProfilePath,
+  launchStableChrome,
+  resolveChromeExecutable,
+  validateChromeProfilePath,
+  validateDebuggerWebSocketUrl,
+  validateEndpointOwnership
+});