chrome-cdp-manager 1.2.1 → 1.2.3

package/package.json

@@ -1,12 +1,19 @@
 {
   "name": "chrome-cdp-manager",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "Set up and drive a Chrome DevTools Protocol (CDP) instance on macOS or Windows through a dedicated launcher (consistent Dock/taskbar icon). Works with any Chromium-based browser — Chrome, Edge, Brave, Chromium, Vivaldi, Opera, Arc.",
   "type": "module",
   "main": "./src/index.js",
+  "types": "./types/index.d.ts",
   "exports": {
-    ".": "./src/index.js",
-    "./playwright": "./src/playwright.js",
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./playwright": {
+      "types": "./types/playwright.d.ts",
+      "default": "./src/playwright.js"
+    },
     "./package.json": "./package.json"
   },
   "bin": {
@@ -16,6 +23,7 @@
   "files": [
     "bin",
     "src",
+    "types",
     "README.md",
     "LICENSE"
   ],
@@ -28,8 +36,10 @@
   ],
   "scripts": {
     "start": "node bin/cli.js",
-    "check": "node --check bin/cli.js && for f in src/*.js src/launchers/*.js; do node --check \"$f\" || exit 1; done",
-    "prepublishOnly": "npm run check",
+    "check": "node scripts/check.mjs",
+    "test": "node --test",
+    "build:types": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run check && npm test && npm run build:types",
     "release": "bash scripts/publish.sh"
   },
   "keywords": [
@@ -50,11 +60,14 @@
     "commander": "^12.1.0"
   },
   "peerDependencies": {
-    "playwright": "*"
+    "playwright": ">=1.40.0"
   },
   "peerDependenciesMeta": {
     "playwright": {
       "optional": true
     }
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0"
   }
 }

package/src/cdp.js

@@ -2,19 +2,31 @@
  * Minimal Chrome DevTools Protocol client built on Node's global `fetch` and
  * `WebSocket` (Node >= 22). Avoids a heavyweight Playwright/Puppeteer
  * dependency so `npx` stays fast and browser-download free.
+ *
+ * Robustness contract:
+ *   - Every {@link CdpClient#send} is bounded by a timeout (and an optional
+ *     AbortSignal), so a missing response can never hang a caller forever.
+ *   - If the socket drops, all in-flight `send`/`waitForEvent` promises reject
+ *     instead of dangling.
+ *   - {@link CdpClient#waitForEvent} supports multiple concurrent waiters for
+ *     the same event.
  */
 export class CdpClient {
   #ws;
   #nextId = 0;
   #pending = new Map();
+  /** @type {Map<string, Set<{resolve, reject, timer}>>} */
   #eventWaiters = new Map();
+  #closed = false;
+  #defaultTimeoutMs;
 
-  constructor(webSocketDebuggerUrl) {
+  constructor(webSocketDebuggerUrl, { timeoutMs = 30_000 } = {}) {
     this.url = webSocketDebuggerUrl;
+    this.#defaultTimeoutMs = timeoutMs;
   }
 
   /** Resolve the browser-level WebSocket endpoint and connect to it. */
-  static async connect(cdpPort) {
+  static async connect(cdpPort, { timeoutMs } = {}) {
     const res = await fetch(`http://127.0.0.1:${cdpPort}/json/version`);
     if (!res.ok) {
       throw new Error(`CDP not reachable on port ${cdpPort} (HTTP ${res.status}).`);
@@ -23,7 +35,7 @@ export class CdpClient {
     if (!webSocketDebuggerUrl) {
       throw new Error("CDP did not advertise a webSocketDebuggerUrl.");
     }
-    const client = new CdpClient(webSocketDebuggerUrl);
+    const client = new CdpClient(webSocketDebuggerUrl, { timeoutMs });
     await client.#open();
     return client;
   }
@@ -38,6 +50,12 @@ export class CdpClient {
         { once: true },
       );
       this.#ws.addEventListener("message", (ev) => this.#onMessage(ev));
+      // A drop after open must fail every in-flight call, not strand it.
+      this.#ws.addEventListener(
+        "close",
+        () => this.#fail(new Error("CDP WebSocket closed.")),
+        { once: true },
+      );
     });
   }
 
@@ -50,7 +68,8 @@ export class CdpClient {
     }
 
     if (data.id !== undefined && this.#pending.has(data.id)) {
-      const { resolve, reject } = this.#pending.get(data.id);
+      const { resolve, reject, timer } = this.#pending.get(data.id);
+      if (timer) clearTimeout(timer);
       this.#pending.delete(data.id);
       if (data.error) reject(new Error(data.error.message));
       else resolve(data.result);
@@ -59,33 +78,134 @@ export class CdpClient {
 
     if (data.method) {
       const key = eventKey(data.method, data.sessionId);
-      const waiter = this.#eventWaiters.get(key);
-      if (waiter) {
+      const waiters = this.#eventWaiters.get(key);
+      if (waiters?.size) {
         this.#eventWaiters.delete(key);
-        waiter(data.params);
+        for (const { resolve, timer } of waiters) {
+          if (timer) clearTimeout(timer);
+          resolve(data.params);
+        }
+      }
+    }
+  }
+
+  /** Reject everything in flight (socket closed / client closed). */
+  #fail(error) {
+    if (this.#closed) return;
+    this.#closed = true;
+    for (const { reject, timer } of this.#pending.values()) {
+      if (timer) clearTimeout(timer);
+      reject(error);
+    }
+    this.#pending.clear();
+    for (const waiters of this.#eventWaiters.values()) {
+      for (const { reject, timer } of waiters) {
+        if (timer) clearTimeout(timer);
+        reject(error);
       }
     }
+    this.#eventWaiters.clear();
   }
 
-  /** Send a CDP command, optionally scoped to an attached session. */
-  send(method, params = {}, sessionId) {
+  /**
+   * Send a CDP command, optionally scoped to an attached session.
+   * @param {string} method
+   * @param {object} [params]
+   * @param {string} [sessionId]
+   * @param {{ timeoutMs?: number, signal?: AbortSignal }} [opts]
+   */
+  send(method, params = {}, sessionId, { timeoutMs = this.#defaultTimeoutMs, signal } = {}) {
+    if (this.#closed) return Promise.reject(new Error("CDP client is closed."));
+    if (this.#ws?.readyState !== WebSocket.OPEN) {
+      return Promise.reject(new Error("CDP WebSocket is not open."));
+    }
+    if (signal?.aborted) return Promise.reject(signal.reason ?? new Error("Aborted."));
+
     const id = ++this.#nextId;
     const message = { id, method, params };
     if (sessionId) message.sessionId = sessionId;
-    this.#ws.send(JSON.stringify(message));
+
     return new Promise((resolve, reject) => {
-      this.#pending.set(id, { resolve, reject });
+      const entry = { resolve, reject, timer: undefined };
+      if (timeoutMs && timeoutMs !== Infinity) {
+        entry.timer = setTimeout(() => {
+          this.#pending.delete(id);
+          reject(new Error(`CDP command "${method}" timed out after ${timeoutMs}ms.`));
+        }, timeoutMs);
+      }
+      if (signal) {
+        signal.addEventListener(
+          "abort",
+          () => {
+            if (entry.timer) clearTimeout(entry.timer);
+            this.#pending.delete(id);
+            reject(signal.reason ?? new Error("Aborted."));
+          },
+          { once: true },
+        );
+      }
+      this.#pending.set(id, entry);
+      try {
+        this.#ws.send(JSON.stringify(message));
+      } catch (err) {
+        if (entry.timer) clearTimeout(entry.timer);
+        this.#pending.delete(id);
+        reject(err);
+      }
     });
   }
 
-  /** Resolve the next time `method` fires (for the given session, if any). */
-  waitForEvent(method, sessionId) {
-    return new Promise((resolve) => {
-      this.#eventWaiters.set(eventKey(method, sessionId), resolve);
+  /**
+   * Resolve the next time `method` fires (for the given session, if any).
+   * Multiple waiters for the same event are all resolved.
+   * @param {string} method
+   * @param {string} [sessionId]
+   * @param {{ timeoutMs?: number, signal?: AbortSignal }} [opts]
+   */
+  waitForEvent(method, sessionId, { timeoutMs, signal } = {}) {
+    const key = eventKey(method, sessionId);
+    return new Promise((resolve, reject) => {
+      const entry = { resolve, reject, timer: undefined };
+      if (timeoutMs && timeoutMs !== Infinity) {
+        entry.timer = setTimeout(() => {
+          this.#removeWaiter(key, entry);
+          reject(new Error(`Timed out after ${timeoutMs}ms waiting for "${method}".`));
+        }, timeoutMs);
+      }
+      if (signal) {
+        if (signal.aborted) {
+          if (entry.timer) clearTimeout(entry.timer);
+          reject(signal.reason ?? new Error("Aborted."));
+          return;
+        }
+        signal.addEventListener(
+          "abort",
+          () => {
+            if (entry.timer) clearTimeout(entry.timer);
+            this.#removeWaiter(key, entry);
+            reject(signal.reason ?? new Error("Aborted."));
+          },
+          { once: true },
+        );
+      }
+      let set = this.#eventWaiters.get(key);
+      if (!set) {
+        set = new Set();
+        this.#eventWaiters.set(key, set);
+      }
+      set.add(entry);
     });
   }
 
+  #removeWaiter(key, entry) {
+    const set = this.#eventWaiters.get(key);
+    if (!set) return;
+    set.delete(entry);
+    if (!set.size) this.#eventWaiters.delete(key);
+  }
+
   close() {
+    this.#fail(new Error("CDP client closed by caller."));
     try {
       this.#ws?.close();
     } catch {
@@ -98,11 +218,31 @@ function eventKey(method, sessionId) {
   return sessionId ? `${sessionId}:${method}` : method;
 }
 
+/**
+ * Strip "HeadlessChrome" from the browser's UA and apply the cleaned value to
+ * the given target so sites (and `navigator.userAgent`) see plain Chrome. A
+ * no-op for headed sessions, where the UA never contains "HeadlessChrome".
+ */
+async function unmaskHeadlessUserAgent(cdp, sessionId) {
+  const { userAgent } = await cdp.send("Browser.getVersion").catch(() => ({}));
+  const clean = userAgent?.replace(/HeadlessChrome/g, "Chrome");
+  if (!clean || clean === userAgent) return;
+  await cdp.send("Network.setUserAgentOverride", { userAgent: clean }, sessionId);
+}
+
 /** Open a URL in a new tab and leave it running. Returns the new targetId. */
 export async function openUrl(cdpPort, url) {
   const cdp = await CdpClient.connect(cdpPort);
   try {
-    const { targetId } = await cdp.send("Target.createTarget", { url });
+    // Open blank, override the UA, then navigate — so the very first request
+    // carries the unmasked (non-headless) User-Agent.
+    const { targetId } = await cdp.send("Target.createTarget", { url: "about:blank" });
+    const { sessionId } = await cdp.send("Target.attachToTarget", {
+      targetId,
+      flatten: true,
+    });
+    await unmaskHeadlessUserAgent(cdp, sessionId);
+    await cdp.send("Page.navigate", { url }, sessionId);
     return targetId;
   } finally {
     cdp.close();
@@ -126,15 +266,12 @@ export async function getPageHtml(cdpPort, url, { close = false, timeoutMs = 30_
     });
 
     await cdp.send("Page.enable", {}, sessionId);
-    const loaded = cdp.waitForEvent("Page.loadEventFired", sessionId);
+    await unmaskHeadlessUserAgent(cdp, sessionId);
+    // Register the waiter (with its own timeout) before navigating so a fast
+    // load can't fire the event before we're listening.
+    const loaded = cdp.waitForEvent("Page.loadEventFired", sessionId, { timeoutMs });
     await cdp.send("Page.navigate", { url }, sessionId);
-
-    await Promise.race([
-      loaded,
-      delay(timeoutMs).then(() => {
-        throw new Error(`Timed out loading ${url} after ${timeoutMs}ms.`);
-      }),
-    ]);
+    await loaded;
 
     const { result } = await cdp.send(
       "Runtime.evaluate",
@@ -162,7 +299,3 @@ export async function closeBrowser(cdpPort) {
     cdp.close();
   }
 }
-
-function delay(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}

package/src/cli.js

@@ -27,7 +27,19 @@ export async function run(argv) {
         "through a dedicated launcher (consistent Dock/taskbar icon). Works with " +
         "any Chromium-based browser.",
     )
-    .version(version, "-v, --version");
+    .version(version, "-v, --version")
+    .addHelpText(
+      "after",
+      `
+Default Headless Behavior:
+  By default, 'html' runs headlessly, and 'open' runs headed.
+  - To run 'html' with a visible window, use the --headed flag:
+      chrome-cdp html <url> --headed
+  - To run 'open' headlessly, use the --headless flag:
+      chrome-cdp open [url] --headless
+
+Run 'chrome-cdp <command> --help' to see all options for a specific command.`,
+    );
 
   // Options shared across commands.
   const withCommon = (cmd) =>
@@ -63,7 +75,7 @@ export async function run(argv) {
       .command("open")
       .argument("[url]", "URL to open after launch")
       .description("Launch ChromeCDP via the launcher and optionally open a URL")
-      .option("--headless", "Run headless (no window/Dock)", false)
+      .option("--headless", "Run headless (no window/Dock) (default: false)")
       .option("-t, --timeout <seconds>", "Startup timeout in seconds", "30"),
   ).action(openCommand);
 
@@ -72,14 +84,14 @@ export async function run(argv) {
       .command("html")
       .argument("<url>", "URL to load")
       .description("Print or save a page's HTML over CDP")
-      .option("--headless", "Run headless (default for html)")
-      .option("--headed", "Force a visible window")
+      .option("--headless", "Run headless (default: true)")
+      .option("--headed", "Force a visible window (default: false)")
       .option("--close", "Close the tab when done", false)
       .option("-o, --output <file>", "Write HTML to a file instead of stdout")
       .option("-t, --timeout <seconds>", "Load timeout in seconds", "30"),
   ).action((url, opts) => {
     // --headed wins over --headless when both are passed.
-    const headless = opts.headed ? false : opts.headless;
+    const headless = opts.headed ? false : (opts.headless === undefined ? true : Boolean(opts.headless));
     return htmlCommand(url, { ...opts, headless });
   });
 

package/src/commands.js

@@ -110,12 +110,15 @@ export async function openCommand(url, opts) {
 
   ensureLauncherReady(config);
 
-  const { launched } = await ensureBrowserRunning(config, { headless, timeoutMs });
-  console.error(
-    launched
-      ? `Launched ChromeCDP (${headless ? "headless" : "headed"}) on port ${config.cdpPort}.`
-      : `ChromeCDP already running on port ${config.cdpPort}.`,
-  );
+  const { launched, version } = await ensureBrowserRunning(config, { headless, timeoutMs });
+  if (launched) {
+    console.error(`Launched ChromeCDP (${headless ? "headless" : "headed"}) on port ${config.cdpPort}.`);
+  } else {
+    const isHeadless =
+      /HeadlessChrome/i.test(version.Browser) ||
+      /HeadlessChrome/i.test(version["User-Agent"] || "");
+    console.error(`ChromeCDP already running on port ${config.cdpPort} (${isHeadless ? "headless" : "headed"}).`);
+  }
 
   if (url) {
     const target = await openUrl(config.cdpPort, normalizeUrl(url));
@@ -133,20 +136,30 @@ export async function htmlCommand(url, opts) {
   const target = normalizeUrl(url);
 
   ensureLauncherReady(config);
-  await ensureBrowserRunning(config, { headless, timeoutMs });
+  const { launched } = await ensureBrowserRunning(config, { headless, timeoutMs });
 
   console.error(`Fetching HTML for ${target} ...`);
-  const html = await getPageHtml(config.cdpPort, target, {
-    close: Boolean(opts.close),
-    timeoutMs,
-  });
-
-  if (opts.output) {
-    const outPath = path.resolve(opts.output);
-    fs.writeFileSync(outPath, html);
-    console.error(`Saved HTML to ${outPath}`);
-  } else {
-    process.stdout.write(html.endsWith("\n") ? html : `${html}\n`);
+  try {
+    const html = await getPageHtml(config.cdpPort, target, {
+      close: !launched || Boolean(opts.close),
+      timeoutMs,
+    });
+
+    if (opts.output) {
+      const outPath = path.resolve(opts.output);
+      fs.writeFileSync(outPath, html);
+      console.error(`Saved HTML to ${outPath}`);
+    } else {
+      process.stdout.write(html.endsWith("\n") ? html : `${html}\n`);
+    }
+  } finally {
+    if (launched && headless) {
+      try {
+        await closeBrowser(config.cdpPort);
+      } catch (err) {
+        // ignore errors during shutdown
+      }
+    }
   }
 }
 
@@ -154,9 +167,15 @@ export async function htmlCommand(url, opts) {
 export async function statusCommand(opts) {
   assertSupportedPlatform();
   const config = resolveConfig(opts);
+  const version = await probeCdp(config.cdpPort);
+
+  if (!version) {
+    console.log(`ChromeCDP is not running on port ${config.cdpPort}.`);
+    return;
+  }
+
   const launcher = getLauncher();
   const exists = launcher.exists(config);
-  const version = await probeCdp(config.cdpPort);
 
   console.log("ChromeCDP status");
   console.log(`  Browser:  ${browserLabel(config.browser)} (${config.browserPath})`);
@@ -166,11 +185,14 @@ export async function statusCommand(opts) {
   );
   console.log(`  Profile:  ${config.profileDir}`);
   console.log(`  CDP port: ${config.cdpPort}`);
-  console.log(
-    version
-      ? `  Running:  yes — ${version.Browser} (${version["Protocol-Version"] ?? "?"})`
-      : "  Running:  no",
-  );
+
+  const isHeadless =
+    /HeadlessChrome/i.test(version.Browser) ||
+    /HeadlessChrome/i.test(version["User-Agent"] || "");
+  const mode = isHeadless ? "headless" : "headed";
+  const runningDetail = `yes — ${version.Browser} (${version["Protocol-Version"] ?? "?"}, ${mode})`;
+
+  console.log(`  Running:  ${runningDetail}`);
   console.log(`  Config:   ${CONFIG_FILE}`);
 }
 

package/src/index.js

@@ -16,19 +16,39 @@ export { loadConfig, computeDefaults, DEFAULTS } from "./config.js";
 export { getLauncher } from "./launcher.js";
 export { ensureBrowserRunning, probeCdp, waitForCdp } from "./browser.js";
 
+// Values the launcher bakes in at creation time; overriding them only takes
+// effect if the launcher is (re)created to match.
+const BAKED_KEYS = ["cdpPort", "profileDir", "browserPath"];
+
 /**
  * Ensure a ChromeCDP instance is running and return its connection details.
  *
  * @param {object}  [opts]
  * @param {boolean} [opts.headless=false]
  * @param {number}  [opts.timeoutMs=30000] startup timeout in milliseconds.
+ * @param {boolean} [opts.force=false] rewrite the launcher even if it exists.
  * @param {object}  [opts.config] overrides merged over the persisted config
- *                  (e.g. `{ cdpPort, profileDir, browserPath }`).
+ *                  (e.g. `{ cdpPort, profileDir, browserPath }`). If these
+ *                  differ from your saved `setup`, the launcher is rewritten so
+ *                  the override actually takes effect (rather than being
+ *                  silently ignored).
  * @returns {Promise<{ config: object, endpoint: string, launched: boolean, version: object }>}
  */
-export async function launch({ headless = false, timeoutMs = 30_000, config: overrides } = {}) {
-  const config = { ...loadConfig(), ...overrides };
-  getLauncher().ensure(config, { force: false });
+export async function launch({ headless = false, timeoutMs = 30_000, force = false, config: overrides } = {}) {
+  const persisted = loadConfig();
+  const config = { ...persisted, ...overrides };
+  const launcher = getLauncher();
+
+  // If a caller overrode a baked value, the existing launcher would still use
+  // the old one — so rewrite it to match instead of producing a port/profile
+  // mismatch that times out at connect time.
+  const diverged =
+    overrides &&
+    launcher.exists(config) &&
+    BAKED_KEYS.some((k) => overrides[k] !== undefined && overrides[k] !== persisted[k]);
+
+  launcher.ensure(config, { force: force || Boolean(diverged) });
+
   const { launched, version } = await ensureBrowserRunning(config, { headless, timeoutMs });
   return {
     config,

package/src/launchers/macBundle.js

@@ -1,7 +1,10 @@
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { spawn, execFileSync } from "node:child_process";
 
+import { getWindowSizeFromProfile } from "../preferences.js";
+
 /**
  * macOS launcher: a real `.app` bundle whose executable is a small bash
  * launcher. Headed launches go through `open <bundle>` so LaunchServices
@@ -14,6 +17,9 @@ import { spawn, execFileSync } from "node:child_process";
  * as `--headless=new`.
  */
 function launcherScript({ browserPath, cdpPort, profileDir }) {
+  // `arch -arm64` is meaningful only on Apple Silicon; on Intel it would error,
+  // so omit it there and exec the browser directly.
+  const archPrefix = os.arch() === "arm64" ? "arch -arm64 " : "";
   return `#!/usr/bin/env bash
 # ChromeCDP launcher — generated by chrome-cdp-manager.
 # Re-run \`chrome-cdp setup\` to regenerate this file.
@@ -23,7 +29,7 @@ BROWSER=${shellQuote(browserPath)}
 PORT=${shellQuote(String(cdpPort))}
 PROFILE=${shellQuote(profileDir)}
 
-exec arch -arm64 "$BROWSER" \\
+exec ${archPrefix}"$BROWSER" \\
   --remote-debugging-port="$PORT" \\
   --user-data-dir="$PROFILE" \\
   "$@"
@@ -160,7 +166,13 @@ export function ensure(config, { force = false } = {}) {
 export function launch(config, { headless } = {}) {
   if (headless) {
     const { executable } = bundleLayout(config.launcherPath);
-    const child = spawn(executable, ["--headless=new"], {
+    const args = ["--headless=new"];
+    const size = getWindowSizeFromProfile(config.profileDir);
+    if (size) {
+      args.push(`--window-size=${size.width},${size.height}`);
+      args.push(`--screen-info={0,0 ${size.width}x${size.height}}`);
+    }
+    const child = spawn(executable, args, {
       detached: true,
       stdio: "ignore",
     });

package/src/launchers/winShortcut.js

@@ -3,6 +3,8 @@ import os from "node:os";
 import path from "node:path";
 import { spawn, execFileSync } from "node:child_process";
 
+import { getWindowSizeFromProfile } from "../preferences.js";
+
 /**
  * Windows launcher: a Start Menu `.lnk` shortcut with a custom icon and the CDP
  * flags baked into its arguments. Headed launches go through the shortcut so
@@ -86,13 +88,19 @@ export function ensure(config, { force = false } = {}) {
  */
 export function launch(config, { headless } = {}) {
   if (headless) {
+    const args = [
+      `--remote-debugging-port=${config.cdpPort}`,
+      `--user-data-dir=${config.profileDir}`,
+      "--headless=new",
+    ];
+    const size = getWindowSizeFromProfile(config.profileDir);
+    if (size) {
+      args.push(`--window-size=${size.width},${size.height}`);
+      args.push(`--screen-info={0,0 ${size.width}x${size.height}}`);
+    }
     const child = spawn(
       config.browserPath,
-      [
-        `--remote-debugging-port=${config.cdpPort}`,
-        `--user-data-dir=${config.profileDir}`,
-        "--headless=new",
-      ],
+      args,
       { detached: true, stdio: "ignore" },
     );
     child.unref();

package/src/playwright.js

@@ -18,15 +18,18 @@ import { launch } from "./index.js";
  *                  falls back to the first tab, then a fresh one.
  * @param {number}  [opts.timeoutMs=30000]
  * @param {object}  [opts.config] config overrides (see {@link launch}).
+ * @param {boolean} [opts.force=false] rewrite the launcher even if it exists.
+ * @param {boolean} [opts.keepOpen=true] on dispose, detach and leave the
+ *                  launcher-managed browser running; set `false` to fully close it.
  * @param {object}  [opts.chromium] a Playwright `chromium` object to use
  *                  instead of `import("playwright")` — for injected/zero-install
  *                  setups.
  * @returns {Promise<{ browser, context, page, config } & AsyncDisposable>}
- *          Dispose (or `await using`) detaches the CDP channel; the
+ *          Dispose (or `await using`) detaches the CDP channel by default; the
  *          launcher-managed browser keeps running.
  */
-export async function connect({ headless = false, match, timeoutMs = 30_000, config: overrides, chromium } = {}) {
-  const { config, endpoint } = await launch({ headless, timeoutMs, config: overrides });
+export async function connect({ headless = false, match, timeoutMs = 30_000, force = false, keepOpen = true, config: overrides, chromium } = {}) {
+  const { config, endpoint } = await launch({ headless, timeoutMs, force, config: overrides });
 
   const pwChromium = chromium ?? (await importPlaywright()).chromium;
   const browser = await pwChromium.connectOverCDP(endpoint);
@@ -44,7 +47,14 @@ export async function connect({ headless = false, match, timeoutMs = 30_000, con
     page,
     config,
     async [Symbol.asyncDispose]() {
-      await browser.close();
+      // Detach (don't kill) by default: this browser is launcher-managed and
+      // may be shared with other sessions. `browser.close()` on a CDP-connected
+      // browser tends to terminate it, so prefer disconnect().
+      if (keepOpen && typeof browser.disconnect === "function") {
+        await browser.disconnect();
+      } else {
+        await browser.close();
+      }
     },
   };
 }

package/src/preferences.js

@@ -0,0 +1,29 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Reads the last closed window dimensions from the Chrome profile Preferences file.
+ * @param {string} profileDir
+ * @returns {{ width: number, height: number, maximized: boolean } | null}
+ */
+export function getWindowSizeFromProfile(profileDir) {
+  try {
+    const preferencesPath = path.join(profileDir, "Default", "Preferences");
+    if (fs.existsSync(preferencesPath)) {
+      const content = fs.readFileSync(preferencesPath, "utf8");
+      const prefs = JSON.parse(content);
+      const placement = prefs?.browser?.window_placement;
+      if (placement) {
+        const { left, top, right, bottom, maximized } = placement;
+        const width = right - left;
+        const height = bottom - top;
+        if (typeof width === "number" && typeof height === "number" && width > 0 && height > 0) {
+          return { width, height, maximized: Boolean(maximized) };
+        }
+      }
+    }
+  } catch {
+    // Ignore and fallback
+  }
+  return null;
+}

package/types/browser.d.ts

@@ -0,0 +1,12 @@
+/** Returns the CDP version payload if the browser is already listening, else null. */
+export function probeCdp(cdpPort: any): Promise<any>;
+/** Poll the CDP endpoint until it responds or the timeout elapses. */
+export function waitForCdp(cdpPort: any, timeoutMs?: number): Promise<any>;
+/**
+ * Ensure the browser is running and CDP is reachable, launching it if needed.
+ * @returns {Promise<{ launched: boolean, version: object }>}
+ */
+export function ensureBrowserRunning(config: any, { headless, timeoutMs }?: {}): Promise<{
+    launched: boolean;
+    version: object;
+}>;

package/types/browsers.d.ts

@@ -0,0 +1,27 @@
+/** All known browser keys, in display order. */
+export function browserKeys(): string[];
+/** Human label for a browser key (falls back to the key itself). */
+export function browserLabel(key: any): any;
+/**
+ * Resolve a browser key to a concrete location on the current platform.
+ * @returns {{ key, label, path, icon: string|null, found: boolean }}
+ *   `found` is whether the executable exists on disk. `path` is the best
+ *   candidate even when not found, so callers can show a helpful message.
+ */
+export function resolveBrowser(key: any, platform?: any): {
+    key: any;
+    label: any;
+    path: any;
+    icon: string | null;
+    found: boolean;
+};
+/** All browsers detected as installed on the current platform. */
+export function detectInstalled(platform?: any): {
+    key: any;
+    label: any;
+    path: any;
+    icon: string | null;
+    found: boolean;
+}[];
+/** The canonical default browser key. */
+export const DEFAULT_BROWSER: "chrome";

package/types/cdp.d.ts

@@ -0,0 +1,59 @@
+/** Open a URL in a new tab and leave it running. Returns the new targetId. */
+export function openUrl(cdpPort: any, url: any): Promise<any>;
+/**
+ * Navigate to a URL and return the page's serialized HTML.
+ * @param {object} opts
+ * @param {boolean} [opts.close] close the tab after capturing.
+ * @param {number} [opts.timeoutMs] navigation timeout.
+ */
+export function getPageHtml(cdpPort: any, url: any, { close, timeoutMs }?: {
+    close?: boolean;
+    timeoutMs?: number;
+}): Promise<any>;
+/** Close the entire browser via CDP (graceful quit). */
+export function closeBrowser(cdpPort: any): Promise<void>;
+/**
+ * Minimal Chrome DevTools Protocol client built on Node's global `fetch` and
+ * `WebSocket` (Node >= 22). Avoids a heavyweight Playwright/Puppeteer
+ * dependency so `npx` stays fast and browser-download free.
+ *
+ * Robustness contract:
+ *   - Every {@link CdpClient#send} is bounded by a timeout (and an optional
+ *     AbortSignal), so a missing response can never hang a caller forever.
+ *   - If the socket drops, all in-flight `send`/`waitForEvent` promises reject
+ *     instead of dangling.
+ *   - {@link CdpClient#waitForEvent} supports multiple concurrent waiters for
+ *     the same event.
+ */
+export class CdpClient {
+    /** Resolve the browser-level WebSocket endpoint and connect to it. */
+    static connect(cdpPort: any, { timeoutMs }?: {}): Promise<CdpClient>;
+    constructor(webSocketDebuggerUrl: any, { timeoutMs }?: {
+        timeoutMs?: number;
+    });
+    url: any;
+    /**
+     * Send a CDP command, optionally scoped to an attached session.
+     * @param {string} method
+     * @param {object} [params]
+     * @param {string} [sessionId]
+     * @param {{ timeoutMs?: number, signal?: AbortSignal }} [opts]
+     */
+    send(method: string, params?: object, sessionId?: string, { timeoutMs, signal }?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<any>;
+    /**
+     * Resolve the next time `method` fires (for the given session, if any).
+     * Multiple waiters for the same event are all resolved.
+     * @param {string} method
+     * @param {string} [sessionId]
+     * @param {{ timeoutMs?: number, signal?: AbortSignal }} [opts]
+     */
+    waitForEvent(method: string, sessionId?: string, { timeoutMs, signal }?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<any>;
+    close(): void;
+    #private;
+}

package/types/cli.d.ts

@@ -0,0 +1 @@
+export function run(argv: any): Promise<void>;

package/types/commands.d.ts

@@ -0,0 +1,8 @@
+export function setupCommand(opts: any): Promise<void>;
+export function openCommand(url: any, opts: any): Promise<void>;
+export function htmlCommand(url: any, opts: any): Promise<void>;
+export function statusCommand(opts: any): Promise<void>;
+export function stopCommand(opts: any): Promise<void>;
+export function browsersCommand(): Promise<void>;
+export { DEFAULTS };
+import { DEFAULTS } from "./config.js";

package/types/config.d.ts

@@ -0,0 +1,28 @@
+/** Compute defaults for a given browser/platform (binary, icon, launcher). */
+export function computeDefaults({ browser, platform, }?: {
+    browser?: string;
+    platform?: any;
+}): {
+    browser: string;
+    browserPath: any;
+    browserIcon: string;
+    launcherPath: any;
+    bundleId: string;
+    cdpPort: number;
+    profileDir: any;
+};
+/** Load persisted config, falling back to {@link DEFAULTS} for missing keys. */
+export function loadConfig(): any;
+/** Persist the resolved config so other commands stay in sync with the launcher. */
+export function saveConfig(config: any): any;
+/** Defaults for the current platform and default browser (for help text). */
+export const DEFAULTS: Readonly<{
+    browser: string;
+    browserPath: any;
+    browserIcon: string;
+    launcherPath: any;
+    bundleId: string;
+    cdpPort: number;
+    profileDir: any;
+}>;
+export const CONFIG_FILE: any;

package/types/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Ensure a ChromeCDP instance is running and return its connection details.
+ *
+ * @param {object}  [opts]
+ * @param {boolean} [opts.headless=false]
+ * @param {number}  [opts.timeoutMs=30000] startup timeout in milliseconds.
+ * @param {boolean} [opts.force=false] rewrite the launcher even if it exists.
+ * @param {object}  [opts.config] overrides merged over the persisted config
+ *                  (e.g. `{ cdpPort, profileDir, browserPath }`). If these
+ *                  differ from your saved `setup`, the launcher is rewritten so
+ *                  the override actually takes effect (rather than being
+ *                  silently ignored).
+ * @returns {Promise<{ config: object, endpoint: string, launched: boolean, version: object }>}
+ */
+export function launch({ headless, timeoutMs, force, config: overrides }?: {
+    headless?: boolean;
+    timeoutMs?: number;
+    force?: boolean;
+    config?: object;
+}): Promise<{
+    config: object;
+    endpoint: string;
+    launched: boolean;
+    version: object;
+}>;
+export { getLauncher } from "./launcher.js";
+export { CdpClient, openUrl, getPageHtml, closeBrowser } from "./cdp.js";
+export { loadConfig, computeDefaults, DEFAULTS } from "./config.js";
+export { ensureBrowserRunning, probeCdp, waitForCdp } from "./browser.js";

package/types/launcher.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Select the platform-specific launcher. Each implementation exposes the same
+ * surface: `ensure`, `exists`, `launch`, `targetPath`, `targetLabel`.
+ *
+ * Adding Linux later means dropping a `linuxDesktop.js` here that builds a
+ * `.desktop` entry — no other module needs to change.
+ */
+export function getLauncher(platform?: any): typeof macBundle | typeof winShortcut;
+import * as macBundle from "./launchers/macBundle.js";
+import * as winShortcut from "./launchers/winShortcut.js";

package/types/launchers/macBundle.d.ts

@@ -0,0 +1,20 @@
+/** Path shown in `status` for the launcher target. */
+export function targetPath(config: any): any;
+/** True when the bundle's executable launcher already exists. */
+export function exists(config: any): any;
+/**
+ * Create or repair the ChromeCDP.app bundle so its Dock icon and launch
+ * behaviour are correct and consistent.
+ * @returns {{ created: boolean }} whether the bundle was newly created.
+ */
+export function ensure(config: any, { force }?: {
+    force?: boolean;
+}): {
+    created: boolean;
+};
+/**
+ * Launch the browser through the bundle. Headed goes via `open <bundle>` so
+ * LaunchServices attaches the Dock icon; headless runs the launcher directly.
+ */
+export function launch(config: any, { headless }?: {}): void;
+export const targetLabel: "App bundle";

package/types/launchers/winShortcut.d.ts

@@ -0,0 +1,19 @@
+/** Path shown in `status` for the launcher target. */
+export function targetPath(config: any): any;
+/** True when the shortcut file already exists. */
+export function exists(config: any): any;
+/**
+ * Create or repair the ChromeCDP shortcut.
+ * @returns {{ created: boolean }} whether the shortcut was newly created.
+ */
+export function ensure(config: any, { force }?: {
+    force?: boolean;
+}): {
+    created: boolean;
+};
+/**
+ * Launch the browser. Headed goes through the shortcut so the taskbar uses its
+ * icon; headless runs the exe directly with the same flags + `--headless=new`.
+ */
+export function launch(config: any, { headless }?: {}): void;
+export const targetLabel: "Shortcut";

package/types/platform.d.ts

@@ -0,0 +1,5 @@
+/**
+ * This tool builds a platform-native launcher (a macOS `.app` bundle or a
+ * Windows `.lnk` shortcut). Only those two platforms are supported today.
+ */
+export function assertSupportedPlatform(): void;

package/types/playwright.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Launch (or attach to) ChromeCDP and return a ready-to-drive Playwright page.
+ *
+ * @param {object} [opts]
+ * @param {boolean} [opts.headless=false]
+ * @param {(url: string) => boolean} [opts.match] pick an existing tab by URL;
+ *                  falls back to the first tab, then a fresh one.
+ * @param {number}  [opts.timeoutMs=30000]
+ * @param {object}  [opts.config] config overrides (see {@link launch}).
+ * @param {boolean} [opts.force=false] rewrite the launcher even if it exists.
+ * @param {boolean} [opts.keepOpen=true] on dispose, detach and leave the
+ *                  launcher-managed browser running; set `false` to fully close it.
+ * @param {object}  [opts.chromium] a Playwright `chromium` object to use
+ *                  instead of `import("playwright")` — for injected/zero-install
+ *                  setups.
+ * @returns {Promise<{ browser, context, page, config } & AsyncDisposable>}
+ *          Dispose (or `await using`) detaches the CDP channel by default; the
+ *          launcher-managed browser keeps running.
+ */
+export function connect({ headless, match, timeoutMs, force, keepOpen, config: overrides, chromium }?: {
+    headless?: boolean;
+    match?: (url: string) => boolean;
+    timeoutMs?: number;
+    config?: object;
+    force?: boolean;
+    keepOpen?: boolean;
+    chromium?: object;
+}): Promise<{
+    browser: any;
+    context: any;
+    page: any;
+    config: any;
+} & AsyncDisposable>;

package/types/preferences.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Reads the last closed window dimensions from the Chrome profile Preferences file.
+ * @param {string} profileDir
+ * @returns {{ width: number, height: number, maximized: boolean } | null}
+ */
+export function getWindowSizeFromProfile(profileDir: string): {
+    width: number;
+    height: number;
+    maximized: boolean;
+} | null;