chrome-cdp-manager 1.0.0 → 1.2.1

package/README.md

@@ -1,17 +1,24 @@
 # chrome-cdp-manager
 
-Set up and drive a **Chrome DevTools Protocol (CDP)** instance on macOS through a
-dedicated `ChromeCDP.app` bundle, so launches always go through the same app and
-the **Dock icon stays consistent**.
-
-- Builds a real macOS `.app` bundle (`/Applications/ChromeCDP.app`) with a proper
-  `Info.plist` and Chrome's own icon — created automatically on first use.
-- Launches Chrome headed via `open <bundle>` (so LaunchServices attaches the
-  ChromeCDP Dock icon) or headless via `--headless=new`.
+Set up and drive a **Chrome DevTools Protocol (CDP)** instance on **macOS or
+Windows** through a dedicated launcher, so launches always go through the same
+entry point and the **Dock/taskbar icon stays consistent**. Works with any
+**Chromium-based browser** — Chrome, Edge, Brave, Chromium, Vivaldi, Opera, Arc.
+
+- **macOS**: builds a real `.app` bundle (`/Applications/ChromeCDP.app`) with a
+  proper `Info.plist` and the browser's own icon — launched via `open` so
+  LaunchServices attaches a consistent Dock icon.
+- **Windows**: creates a Start Menu `.lnk` shortcut with the CDP flags baked in
+  and a custom icon — headed launches go through the shortcut for a consistent
+  taskbar entry.
 - Connects over CDP with **zero heavy dependencies** — uses Node's built-in
   `fetch` and `WebSocket` (no Playwright/Puppeteer, no browser download).
 
-> Requires macOS on Apple Silicon, Node.js ≥ 22, and Google Chrome installed.
+> Requires Node.js ≥ 22 and a Chromium-based browser installed. On macOS,
+> Apple Silicon (the launcher uses `arch -arm64`).
+>
+> Non-Chromium browsers (Firefox, Safari) are **not** supported — they don't
+> speak the same CDP this tool drives.
 
 ## Usage
 
@@ -27,13 +34,19 @@ npm install -g chrome-cdp-manager
 ```
 
 ```bash
-# Create / repair ChromeCDP.app and save defaults (port 9222, profile ~/.chrome_cdp_profile)
+# Create / repair the launcher and save defaults (port 9222, profile ~/.chrome_cdp_profile)
 chrome-cdp setup
 
-# Launch ChromeCDP (Dock icon = ChromeCDP) and open a page
+# Use a specific browser
+chrome-cdp setup --browser edge
+
+# See which browsers are installed
+chrome-cdp browsers
+
+# Launch ChromeCDP and open a page
 chrome-cdp open https://example.com
 
-# Same, headless (no window/Dock)
+# Same, headless (no window/Dock/taskbar)
 chrome-cdp open https://example.com --headless
 
 # Fetch a page's rendered HTML over CDP (headless by default)
@@ -51,32 +64,71 @@ chrome-cdp stop
 
 ## Commands
 
-| Command            | Description                                                     |
-| ------------------ | --------------------------------------------------------------- |
-| `setup`            | Create or repair `ChromeCDP.app` (icon, `Info.plist`, launcher) |
-| `open [url]`       | Launch via the bundle, optionally open a URL; leaves it running |
-| `html <url>`       | Navigate and print/save the page's serialized HTML              |
-| `status`           | Show bundle presence and CDP connection state                   |
-| `stop`             | Ask the running ChromeCDP instance to quit                      |
+| Command            | Description                                                       |
+| ------------------ | ----------------------------------------------------------------- |
+| `setup`            | Create or repair the launcher (icon + CDP flags)                  |
+| `open [url]`       | Launch via the launcher, optionally open a URL; leaves it running |
+| `html <url>`       | Navigate and print/save the page's serialized HTML                |
+| `status`           | Show launcher presence and CDP connection state                   |
+| `stop`             | Ask the running ChromeCDP instance to quit                        |
+| `browsers`         | List supported browsers and which are installed                   |
+
+## Programmatic API
+
+Beyond the CLI, the package exposes a small ES-module API (Node ≥ 22).
+
+```js
+import { launch, CdpClient } from "chrome-cdp-manager";
+
+// Ensure ChromeCDP is running (launches it if needed) and get its endpoint.
+const { endpoint, config, launched } = await launch({ headless: false });
+
+// Drive it with the built-in zero-dependency raw-CDP client...
+const cdp = await CdpClient.connect(config.cdpPort);
+```
+
+Also exported: `loadConfig`, `getLauncher`, `ensureBrowserRunning`, `probeCdp`,
+`waitForCdp`, `openUrl`, `getPageHtml`, `closeBrowser`.
+
+### Playwright bridge (optional)
+
+If you want Playwright's high-level page API, opt into the separate entry point.
+`playwright` is an **optional peer dependency** — the core stays dependency-free.
+
+```js
+import { connect } from "chrome-cdp-manager/playwright";
+
+await using session = await connect({ headless: false, match: u => u.includes("bing.com") });
+await session.page.goto("https://www.bing.com");
+// `await using` detaches the CDP channel on scope exit; the browser keeps running.
+```
+
+`connect()` resolves config, ensures the launcher + a running browser, connects
+Playwright over CDP, and returns `{ browser, context, page, config }`. In
+zero-install (npx) setups where Playwright can't be resolved automatically,
+inject it: `connect({ chromium })`.
 
 ## Common options
 
-| Option                  | Description                                            |
-| ----------------------- | ------------------------------------------------------ |
-| `--port <port>`         | CDP port (default `9222`)                              |
-| `-p, --profile <dir>`   | Chrome `user-data-dir` (default `~/.chrome_cdp_profile`)|
-| `-c, --chrome <path>`   | Google Chrome executable                               |
-| `--bundle <path>`       | App bundle location (default `/Applications/ChromeCDP.app`) |
-| `-t, --timeout <secs>`  | Startup / load timeout (`open`, `html`)                |
+| Option                  | Description                                                   |
+| ----------------------- | ------------------------------------------------------------- |
+| `--port <port>`         | CDP port (default `9222`)                                     |
+| `-p, --profile <dir>`   | Browser `user-data-dir` (default `~/.chrome_cdp_profile`)     |
+| `-b, --browser <name>`  | Browser: `chrome`, `edge`, `brave`, `chromium`, `vivaldi`, `opera`, `arc` |
+| `--path <path>`         | Explicit browser executable (overrides `--browser`)           |
+| `--target <path>`       | Launcher location (`.app` on macOS, `.lnk` on Windows)        |
+| `-t, --timeout <secs>`  | Startup / load timeout (`open`, `html`)                       |
 
-Port, profile, Chrome path and bundle path are baked into the app bundle and
+`-c, --chrome` and `--bundle` remain as aliases for `--path` and `--target`.
+
+Browser, port, profile and launcher path are baked into the launcher and
 persisted (`~/.config/chrome-cdp-manager/config.json`) at `setup` time so every
 command agrees on the same environment. Re-run `setup --force` after changing
 them.
 
-## How the Dock icon stays consistent
+## How the icon stays consistent
 
-The bundle's executable is a small bash launcher:
+**macOS** — the bundle's executable is a small bash launcher:
 
 ```bash
 exec arch -arm64 "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
@@ -85,6 +137,12 @@ exec arch -arm64 "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
   "$@"
 ```
 
-Because headed launches go through `open /Applications/ChromeCDP.app`,
-LaunchServices runs Chrome under the ChromeCDP bundle identity — so you get the
-ChromeCDP Dock icon every time instead of a generic/duplicated Chrome entry.
+Headed launches go through `open /Applications/ChromeCDP.app`, so LaunchServices
+runs the browser under the ChromeCDP bundle identity — a consistent Dock icon
+every time instead of a generic/duplicated entry.
+
+**Windows** — a Start Menu `.lnk` shortcut (`ChromeCDP.lnk`) is created with the
+browser as its target, the CDP flags as its arguments, and the browser's icon.
+Because the dedicated `--user-data-dir` gives the browser its own
+AppUserModelID, the ChromeCDP window gets its own pinnable taskbar entry,
+separate from your everyday browser windows.

package/package.json

@@ -1,8 +1,14 @@
 {
   "name": "chrome-cdp-manager",
-  "version": "1.0.0",
-  "description": "Set up and drive a Chrome DevTools Protocol (CDP) instance on macOS through a dedicated ChromeCDP.app bundle, so the Dock icon stays consistent.",
+  "version": "1.2.1",
+  "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",
+  "exports": {
+    ".": "./src/index.js",
+    "./playwright": "./src/playwright.js",
+    "./package.json": "./package.json"
+  },
   "bin": {
     "chrome-cdp": "bin/cli.js",
     "chrome-cdp-manager": "bin/cli.js"
@@ -17,25 +23,38 @@
     "node": ">=22"
   },
   "os": [
-    "darwin"
+    "darwin",
+    "win32"
   ],
   "scripts": {
     "start": "node bin/cli.js",
-    "check": "node --check bin/cli.js && node --check src/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",
     "release": "bash scripts/publish.sh"
   },
   "keywords": [
     "chrome",
+    "chromium",
+    "edge",
+    "brave",
     "cdp",
     "devtools-protocol",
     "remote-debugging",
     "headless",
     "macos",
+    "windows",
     "automation"
   ],
   "license": "MIT",
   "dependencies": {
     "commander": "^12.1.0"
+  },
+  "peerDependencies": {
+    "playwright": "*"
+  },
+  "peerDependenciesMeta": {
+    "playwright": {
+      "optional": true
+    }
   }
 }

package/src/browser.js

@@ -0,0 +1,50 @@
+import { getLauncher } from "./launcher.js";
+
+/** CDP HTTP endpoint helper. */
+function versionUrl(cdpPort) {
+  return `http://127.0.0.1:${cdpPort}/json/version`;
+}
+
+/** Returns the CDP version payload if the browser is already listening, else null. */
+export async function probeCdp(cdpPort) {
+  try {
+    const res = await fetch(versionUrl(cdpPort), {
+      signal: AbortSignal.timeout(1000),
+    });
+    if (res.ok) return await res.json();
+  } catch {
+    // not up
+  }
+  return null;
+}
+
+/** Poll the CDP endpoint until it responds or the timeout elapses. */
+export async function waitForCdp(cdpPort, timeoutMs = 30_000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const version = await probeCdp(cdpPort);
+    if (version) return version;
+    await delay(250);
+  }
+  throw new Error(
+    `Timed out after ${Math.round(timeoutMs / 1000)}s waiting for browser CDP ` +
+      `at ${versionUrl(cdpPort)}.`,
+  );
+}
+
+/**
+ * Ensure the browser is running and CDP is reachable, launching it if needed.
+ * @returns {Promise<{ launched: boolean, version: object }>}
+ */
+export async function ensureBrowserRunning(config, { headless, timeoutMs } = {}) {
+  const existing = await probeCdp(config.cdpPort);
+  if (existing) return { launched: false, version: existing };
+
+  getLauncher().launch(config, { headless });
+  const version = await waitForCdp(config.cdpPort, timeoutMs);
+  return { launched: true, version };
+}
+
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/browsers.js

@@ -0,0 +1,175 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Registry of Chromium-family browsers that speak the DevTools Protocol via the
+ * shared `--remote-debugging-port` flag. Non-Chromium engines (Firefox's
+ * deprecated CDP, Safari's WebKit protocol) are intentionally excluded — they
+ * do not work with the {@link CdpClient} in this package.
+ *
+ * Each entry describes where the browser lives per platform:
+ *   - macOS: the `.app` bundle path + the executable name inside it.
+ *   - Windows: a list of candidate `.exe` paths (env vars like %ProgramFiles%
+ *     are expanded at lookup time); the first that exists wins.
+ */
+const BROWSERS = Object.freeze({
+  chrome: {
+    label: "Google Chrome",
+    darwin: { app: "/Applications/Google Chrome.app", exec: "Google Chrome" },
+    win32: {
+      paths: [
+        "%ProgramFiles%\\Google\\Chrome\\Application\\chrome.exe",
+        "%ProgramFiles(x86)%\\Google\\Chrome\\Application\\chrome.exe",
+        "%LOCALAPPDATA%\\Google\\Chrome\\Application\\chrome.exe",
+      ],
+    },
+  },
+  edge: {
+    label: "Microsoft Edge",
+    darwin: { app: "/Applications/Microsoft Edge.app", exec: "Microsoft Edge" },
+    win32: {
+      paths: [
+        "%ProgramFiles(x86)%\\Microsoft\\Edge\\Application\\msedge.exe",
+        "%ProgramFiles%\\Microsoft\\Edge\\Application\\msedge.exe",
+      ],
+    },
+  },
+  brave: {
+    label: "Brave",
+    darwin: { app: "/Applications/Brave Browser.app", exec: "Brave Browser" },
+    win32: {
+      paths: [
+        "%ProgramFiles%\\BraveSoftware\\Brave-Browser\\Application\\brave.exe",
+        "%ProgramFiles(x86)%\\BraveSoftware\\Brave-Browser\\Application\\brave.exe",
+        "%LOCALAPPDATA%\\BraveSoftware\\Brave-Browser\\Application\\brave.exe",
+      ],
+    },
+  },
+  chromium: {
+    label: "Chromium",
+    darwin: { app: "/Applications/Chromium.app", exec: "Chromium" },
+    win32: {
+      paths: [
+        "%ProgramFiles%\\Chromium\\Application\\chrome.exe",
+        "%LOCALAPPDATA%\\Chromium\\Application\\chrome.exe",
+      ],
+    },
+  },
+  vivaldi: {
+    label: "Vivaldi",
+    darwin: { app: "/Applications/Vivaldi.app", exec: "Vivaldi" },
+    win32: {
+      paths: [
+        "%LOCALAPPDATA%\\Vivaldi\\Application\\vivaldi.exe",
+        "%ProgramFiles%\\Vivaldi\\Application\\vivaldi.exe",
+      ],
+    },
+  },
+  opera: {
+    label: "Opera",
+    darwin: { app: "/Applications/Opera.app", exec: "Opera" },
+    win32: {
+      paths: [
+        "%LOCALAPPDATA%\\Programs\\Opera\\opera.exe",
+        "%ProgramFiles%\\Opera\\opera.exe",
+      ],
+    },
+  },
+  arc: {
+    label: "Arc",
+    darwin: { app: "/Applications/Arc.app", exec: "Arc" },
+    win32: { paths: ["%LOCALAPPDATA%\\Arc\\app\\Arc.exe"] },
+  },
+});
+
+/** The canonical default browser key. */
+export const DEFAULT_BROWSER = "chrome";
+
+/** All known browser keys, in display order. */
+export function browserKeys() {
+  return Object.keys(BROWSERS);
+}
+
+/** Human label for a browser key (falls back to the key itself). */
+export function browserLabel(key) {
+  return BROWSERS[key]?.label ?? key;
+}
+
+/** Expand Windows `%VAR%` placeholders from the environment. */
+function expandWinPath(p) {
+  return p.replace(/%([^%]+)%/g, (_, name) => process.env[name] ?? "");
+}
+
+/**
+ * Pick the icon for a macOS `.app`. Prefers `app.icns` (Chrome's convention),
+ * otherwise the first `.icns` found in `Contents/Resources`.
+ */
+function resolveMacIcon(appPath) {
+  const resources = path.join(appPath, "Contents", "Resources");
+  const preferred = path.join(resources, "app.icns");
+  if (fs.existsSync(preferred)) return preferred;
+  try {
+    const icns = fs.readdirSync(resources).find((f) => f.endsWith(".icns"));
+    if (icns) return path.join(resources, icns);
+  } catch {
+    // Resources dir missing — no icon.
+  }
+  return null;
+}
+
+/**
+ * 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, platform = process.platform) {
+  const def = BROWSERS[key];
+  if (!def) {
+    throw new Error(
+      `Unknown browser "${key}". Known browsers: ${browserKeys().join(", ")}.`,
+    );
+  }
+
+  if (platform === "darwin") {
+    const spec = def.darwin;
+    if (!spec) return notSupported(key, def, platform);
+    const exe = path.join(spec.app, "Contents", "MacOS", spec.exec);
+    const found = fs.existsSync(exe);
+    return {
+      key,
+      label: def.label,
+      path: exe,
+      icon: found ? resolveMacIcon(spec.app) : null,
+      found,
+    };
+  }
+
+  if (platform === "win32") {
+    const spec = def.win32;
+    if (!spec) return notSupported(key, def, platform);
+    const candidates = spec.paths.map(expandWinPath).filter(Boolean);
+    const existing = candidates.find((p) => fs.existsSync(p));
+    return {
+      key,
+      label: def.label,
+      // On Windows the exe carries its own icon, so IconLocation = "<exe>,0".
+      path: existing ?? candidates[0] ?? "",
+      icon: existing ? `${existing},0` : null,
+      found: Boolean(existing),
+    };
+  }
+
+  return notSupported(key, def, platform);
+}
+
+function notSupported(key, def, platform) {
+  return { key, label: def.label, path: "", icon: null, found: false, platform };
+}
+
+/** All browsers detected as installed on the current platform. */
+export function detectInstalled(platform = process.platform) {
+  return browserKeys()
+    .map((key) => resolveBrowser(key, platform))
+    .filter((b) => b.found);
+}

package/src/cli.js

@@ -2,25 +2,30 @@ import { createRequire } from "node:module";
 import { Command } from "commander";
 
 import { DEFAULTS } from "./config.js";
+import { browserKeys, DEFAULT_BROWSER } from "./browsers.js";
 import {
   setupCommand,
   openCommand,
   htmlCommand,
   statusCommand,
   stopCommand,
+  browsersCommand,
 } from "./commands.js";
 
 const require = createRequire(import.meta.url);
 const { version } = require("../package.json");
 
+const TARGET_LABEL = process.platform === "win32" ? "shortcut" : "app bundle";
+
 export async function run(argv) {
   const program = new Command();
 
   program
     .name("chrome-cdp")
     .description(
-      "Set up and drive a Chrome DevTools Protocol instance on macOS through a " +
-        "dedicated ChromeCDP.app bundle (consistent Dock icon).",
+      "Set up and drive a Chrome DevTools Protocol instance on macOS or Windows " +
+        "through a dedicated launcher (consistent Dock/taskbar icon). Works with " +
+        "any Chromium-based browser.",
     )
     .version(version, "-v, --version");
 
@@ -28,22 +33,36 @@ export async function run(argv) {
   const withCommon = (cmd) =>
     cmd
       .option("--port <port>", `CDP port (default: ${DEFAULTS.cdpPort})`)
-      .option("-p, --profile <dir>", "Chrome user-data-dir")
-      .option("-c, --chrome <path>", "Google Chrome executable path")
-      .option("--bundle <path>", `App bundle path (default: ${DEFAULTS.bundlePath})`);
+      .option("-p, --profile <dir>", "Browser user-data-dir")
+      .option(
+        "-b, --browser <name>",
+        `Browser to use: ${browserKeys().join(", ")} (default: ${DEFAULT_BROWSER})`,
+      )
+      .option(
+        "--path <path>",
+        "Explicit browser executable path (overrides --browser)",
+      )
+      // Back-compat alias for --path.
+      .option("-c, --chrome <path>", "Alias for --path")
+      .option(
+        "--target <path>",
+        `Launcher ${TARGET_LABEL} path (default: ${DEFAULTS.launcherPath})`,
+      )
+      // Back-compat alias for --target.
+      .option("--bundle <path>", "Alias for --target");
 
   withCommon(
     program
       .command("setup")
-      .description("Create or repair ChromeCDP.app (icon, Info.plist, launcher)")
-      .option("-f, --force", "Rewrite the bundle even if it already exists"),
+      .description(`Create or repair the ChromeCDP launcher (${TARGET_LABEL})`)
+      .option("-f, --force", "Rewrite the launcher even if it already exists"),
   ).action(setupCommand);
 
   withCommon(
     program
       .command("open")
       .argument("[url]", "URL to open after launch")
-      .description("Launch ChromeCDP via the app bundle and optionally open a URL")
+      .description("Launch ChromeCDP via the launcher and optionally open a URL")
       .option("--headless", "Run headless (no window/Dock)", false)
       .option("-t, --timeout <seconds>", "Startup timeout in seconds", "30"),
   ).action(openCommand);
@@ -67,12 +86,17 @@ export async function run(argv) {
   withCommon(
     program
       .command("status")
-      .description("Show bundle and CDP connection status"),
+      .description("Show launcher and CDP connection status"),
   ).action(statusCommand);
 
   withCommon(
     program.command("stop").description("Quit the running ChromeCDP instance"),
   ).action(stopCommand);
 
+  program
+    .command("browsers")
+    .description("List supported browsers and which are installed")
+    .action(browsersCommand);
+
   await program.parseAsync(argv);
 }

package/src/commands.js

@@ -3,17 +3,53 @@ import path from "node:path";
 
 import { DEFAULTS, loadConfig, saveConfig, CONFIG_FILE } from "./config.js";
 import { assertSupportedPlatform } from "./platform.js";
-import { ensureAppBundle, bundleExists } from "./appBundle.js";
-import { ensureChromeRunning, probeCdp } from "./chrome.js";
+import {
+  resolveBrowser,
+  detectInstalled,
+  browserKeys,
+  browserLabel,
+} from "./browsers.js";
+import { getLauncher } from "./launcher.js";
+import { ensureBrowserRunning, probeCdp } from "./browser.js";
 import { openUrl, getPageHtml, closeBrowser } from "./cdp.js";
 
 /** Merge persisted config with CLI overrides into a fully-resolved config. */
 function resolveConfig(opts = {}) {
   const stored = loadConfig();
   const resolved = { ...stored };
-  if (opts.chrome) resolved.chromePath = opts.chrome;
+
+  const customPath = opts.path || opts.chrome;
+
+  // --browser switches the binary/icon to that browser's per-OS defaults.
+  if (opts.browser) {
+    const key = String(opts.browser).toLowerCase();
+    const r = resolveBrowser(key); // throws on unknown key
+    resolved.browser = key;
+    resolved.browserPath = r.path;
+    resolved.browserIcon = r.icon;
+    if (!r.found && !customPath) {
+      const installed = detectInstalled();
+      const hint = installed.length
+        ? `Installed: ${installed.map((b) => b.key).join(", ")}.`
+        : "No supported browsers detected.";
+      throw new Error(
+        `${browserLabel(key)} not found for --browser ${key}. ${hint}\n` +
+          `Use --path to point at a custom binary.`,
+      );
+    }
+  }
+
+  // An explicit binary path always wins over browser resolution.
+  if (customPath) {
+    const abs = path.resolve(customPath);
+    resolved.browserPath = abs;
+    resolved.browserIcon =
+      process.platform === "win32" ? `${abs},0` : null;
+  }
+
   if (opts.profile) resolved.profileDir = path.resolve(opts.profile);
-  if (opts.bundle) resolved.bundlePath = path.resolve(opts.bundle);
+  const target = opts.target || opts.bundle;
+  if (target) resolved.launcherPath = path.resolve(target);
   if (opts.port !== undefined) resolved.cdpPort = parsePort(opts.port);
   return resolved;
 }
@@ -38,11 +74,15 @@ function normalizeUrl(url) {
   return /^[a-z]+:\/\//i.test(url) ? url : `https://${url}`;
 }
 
-/** Create the bundle on demand (without forcing a rewrite of an existing one). */
-function ensureBundleReady(config) {
-  const { created } = ensureAppBundle(config, { force: false });
+/** Create the launcher on demand (without forcing a rewrite of an existing one). */
+function ensureLauncherReady(config) {
+  const launcher = getLauncher();
+  const { created } = launcher.ensure(config, { force: false });
   if (created) {
-    console.error(`Created ${config.bundlePath} (Dock icon: Chrome).`);
+    console.error(
+      `Created ${launcher.targetLabel.toLowerCase()} ${config.launcherPath} ` +
+        `(${browserLabel(config.browser)}).`,
+    );
   }
 }
 
@@ -50,11 +90,12 @@ function ensureBundleReady(config) {
 export async function setupCommand(opts) {
   assertSupportedPlatform();
   const config = resolveConfig(opts);
-  const { created } = ensureAppBundle(config, { force: true });
+  const launcher = getLauncher();
+  const { created } = launcher.ensure(config, { force: true });
   const file = saveConfig(config);
 
-  console.error(`${created ? "Created" : "Repaired"} ${config.bundlePath}`);
-  console.error(`  Chrome:   ${config.chromePath}`);
+  console.error(`${created ? "Created" : "Repaired"} ${config.launcherPath}`);
+  console.error(`  Browser:  ${browserLabel(config.browser)} (${config.browserPath})`);
   console.error(`  Profile:  ${config.profileDir}`);
   console.error(`  CDP port: ${config.cdpPort}`);
   console.error(`Config saved to ${file}`);
@@ -67,14 +108,9 @@ export async function openCommand(url, opts) {
   const headless = Boolean(opts.headless);
   const timeoutMs = parseTimeoutMs(opts.timeout);
 
-  ensureBundleReady(config);
+  ensureLauncherReady(config);
 
-  const { launched } = await ensureChromeRunning({
-    bundlePath: config.bundlePath,
-    cdpPort: config.cdpPort,
-    headless,
-    timeoutMs,
-  });
+  const { launched } = await ensureBrowserRunning(config, { headless, timeoutMs });
   console.error(
     launched
       ? `Launched ChromeCDP (${headless ? "headless" : "headed"}) on port ${config.cdpPort}.`
@@ -96,13 +132,8 @@ export async function htmlCommand(url, opts) {
   const timeoutMs = parseTimeoutMs(opts.timeout);
   const target = normalizeUrl(url);
 
-  ensureBundleReady(config);
-  await ensureChromeRunning({
-    bundlePath: config.bundlePath,
-    cdpPort: config.cdpPort,
-    headless,
-    timeoutMs,
-  });
+  ensureLauncherReady(config);
+  await ensureBrowserRunning(config, { headless, timeoutMs });
 
   console.error(`Fetching HTML for ${target} ...`);
   const html = await getPageHtml(config.cdpPort, target, {
@@ -123,11 +154,16 @@ export async function htmlCommand(url, opts) {
 export async function statusCommand(opts) {
   assertSupportedPlatform();
   const config = resolveConfig(opts);
-  const exists = bundleExists(config.bundlePath);
+  const launcher = getLauncher();
+  const exists = launcher.exists(config);
   const version = await probeCdp(config.cdpPort);
 
   console.log("ChromeCDP status");
-  console.log(`  Bundle:   ${exists ? "present" : "missing"} (${config.bundlePath})`);
+  console.log(`  Browser:  ${browserLabel(config.browser)} (${config.browserPath})`);
+  console.log(
+    `  ${launcher.targetLabel}: ${exists ? "present" : "missing"} ` +
+      `(${launcher.targetPath(config)})`,
+  );
   console.log(`  Profile:  ${config.profileDir}`);
   console.log(`  CDP port: ${config.cdpPort}`);
   console.log(
@@ -151,4 +187,15 @@ export async function stopCommand(opts) {
   console.error(`Asked ChromeCDP on port ${config.cdpPort} to quit.`);
 }
 
+// MARK: browsers
+export async function browsersCommand() {
+  assertSupportedPlatform();
+  const installed = new Set(detectInstalled().map((b) => b.key));
+  console.log("Supported browsers (--browser <name>):");
+  for (const key of browserKeys()) {
+    const mark = installed.has(key) ? "✓ installed" : "  not found";
+    console.log(`  ${key.padEnd(10)} ${mark}  ${browserLabel(key)}`);
+  }
+}
+
 export { DEFAULTS };

package/src/config.js

@@ -2,24 +2,71 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
+import { DEFAULT_BROWSER, resolveBrowser } from "./browsers.js";
+
 /**
- * Default, canonical values for a ChromeCDP environment.
+ * Canonical values for a ChromeCDP environment. The browser binary/icon and the
+ * launcher target (macOS `.app` bundle or Windows `.lnk`) depend on the OS and
+ * the chosen browser, so they're computed rather than hard-coded.
  *
- * These are baked into the ChromeCDP.app bundle at setup time and persisted to
- * a config file so every subcommand agrees on the same port/profile/binary.
+ * These are baked into the launcher at setup time and persisted to a config
+ * file so every subcommand agrees on the same port/profile/binary.
  */
-export const DEFAULTS = Object.freeze({
-  chromePath: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
-  chromeIcon: "/Applications/Google Chrome.app/Contents/Resources/app.icns",
-  bundlePath: "/Applications/ChromeCDP.app",
-  bundleId: "org.guocity.chrome-cdp",
-  cdpPort: 9222,
-  profileDir: path.join(os.homedir(), ".chrome_cdp_profile"),
-});
+const BUNDLE_ID = "org.guocity.chrome-cdp";
+const CDP_PORT = 9222;
+
+/** Default launcher target path for the platform. */
+function defaultLauncherPath(platform) {
+  if (platform === "win32") {
+    const appData =
+      process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming");
+    return path.join(
+      appData,
+      "Microsoft",
+      "Windows",
+      "Start Menu",
+      "Programs",
+      "ChromeCDP.lnk",
+    );
+  }
+  return "/Applications/ChromeCDP.app";
+}
+
+/** Compute defaults for a given browser/platform (binary, icon, launcher). */
+export function computeDefaults({
+  browser = DEFAULT_BROWSER,
+  platform = process.platform,
+} = {}) {
+  const resolved = resolveBrowser(browser, platform);
+  return {
+    browser,
+    browserPath: resolved.path,
+    browserIcon: resolved.icon,
+    launcherPath: defaultLauncherPath(platform),
+    bundleId: BUNDLE_ID,
+    cdpPort: CDP_PORT,
+    profileDir: path.join(os.homedir(), ".chrome_cdp_profile"),
+  };
+}
+
+/** Defaults for the current platform and default browser (for help text). */
+export const DEFAULTS = Object.freeze(computeDefaults());
 
 const CONFIG_DIR = path.join(os.homedir(), ".config", "chrome-cdp-manager");
 const CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
 
+/** Map legacy (pre-multi-browser) config keys onto the current schema. */
+function migrateLegacy(stored) {
+  const out = { ...stored };
+  if (stored.chromePath && !stored.browserPath) out.browserPath = stored.chromePath;
+  if (stored.chromeIcon && !stored.browserIcon) out.browserIcon = stored.chromeIcon;
+  if (stored.bundlePath && !stored.launcherPath) out.launcherPath = stored.bundlePath;
+  delete out.chromePath;
+  delete out.chromeIcon;
+  delete out.bundlePath;
+  return out;
+}
+
 /** Load persisted config, falling back to {@link DEFAULTS} for missing keys. */
 export function loadConfig() {
   let stored = {};
@@ -28,15 +75,16 @@ export function loadConfig() {
   } catch {
     // No config yet — first run.
   }
-  return { ...DEFAULTS, ...stored };
+  return { ...DEFAULTS, ...migrateLegacy(stored) };
 }
 
-/** Persist the resolved config so other commands stay in sync with the bundle. */
+/** Persist the resolved config so other commands stay in sync with the launcher. */
 export function saveConfig(config) {
   const toStore = {
-    chromePath: config.chromePath,
-    chromeIcon: config.chromeIcon,
-    bundlePath: config.bundlePath,
+    browser: config.browser,
+    browserPath: config.browserPath,
+    browserIcon: config.browserIcon,
+    launcherPath: config.launcherPath,
     bundleId: config.bundleId,
     cdpPort: config.cdpPort,
     profileDir: config.profileDir,

package/src/index.js

@@ -0,0 +1,39 @@
+/**
+ * Public entry point for chrome-cdp-manager.
+ *
+ * Re-exports the stable building blocks and adds {@link launch} — a one-call
+ * helper that resolves config, ensures the launcher exists, and starts the
+ * browser if it isn't already running. Stays dependency-free; the optional
+ * Playwright integration lives in the separate "chrome-cdp-manager/playwright"
+ * entry point so the core keeps its zero-heavy-dependency promise.
+ */
+import { loadConfig } from "./config.js";
+import { getLauncher } from "./launcher.js";
+import { ensureBrowserRunning } from "./browser.js";
+
+export { CdpClient, openUrl, getPageHtml, closeBrowser } from "./cdp.js";
+export { loadConfig, computeDefaults, DEFAULTS } from "./config.js";
+export { getLauncher } from "./launcher.js";
+export { ensureBrowserRunning, probeCdp, waitForCdp } from "./browser.js";
+
+/**
+ * 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 {object}  [opts.config] overrides merged over the persisted config
+ *                  (e.g. `{ cdpPort, profileDir, browserPath }`).
+ * @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 });
+  const { launched, version } = await ensureBrowserRunning(config, { headless, timeoutMs });
+  return {
+    config,
+    endpoint: `http://127.0.0.1:${config.cdpPort}`,
+    launched,
+    version,
+  };
+}

package/src/launcher.js

@@ -0,0 +1,20 @@
+import * as macBundle from "./launchers/macBundle.js";
+import * as winShortcut from "./launchers/winShortcut.js";
+
+/**
+ * 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 = process.platform) {
+  switch (platform) {
+    case "darwin":
+      return macBundle;
+    case "win32":
+      return winShortcut;
+    default:
+      throw new Error(`No launcher available for platform "${platform}".`);
+  }
+}

package/src/{appBundle.js → launchers/macBundle.js}

@@ -1,23 +1,29 @@
 import fs from "node:fs";
 import path from "node:path";
-import { execFileSync } from "node:child_process";
+import { spawn, execFileSync } from "node:child_process";
 
 /**
- * Build the bash launcher that the bundle executes. It bakes in the canonical
- * Chrome path, CDP port and profile, and forwards any extra args (`"$@"`) so
- * callers can append flags such as `--headless=new`.
+ * macOS launcher: a real `.app` bundle whose executable is a small bash
+ * launcher. Headed launches go through `open <bundle>` so LaunchServices
+ * attaches the bundle's Dock icon; headless runs the launcher directly.
  */
-function launcherScript({ chromePath, cdpPort, profileDir }) {
+
+/**
+ * The bash launcher baked into the bundle. It pins the browser path, CDP port
+ * and profile, and forwards extra args (`"$@"`) so callers can add flags such
+ * as `--headless=new`.
+ */
+function launcherScript({ browserPath, cdpPort, profileDir }) {
   return `#!/usr/bin/env bash
 # ChromeCDP launcher — generated by chrome-cdp-manager.
-# Re-run \`npx chrome-cdp-manager setup\` to regenerate this file.
+# Re-run \`chrome-cdp setup\` to regenerate this file.
 set -euo pipefail
 
-CHROME=${shellQuote(chromePath)}
+BROWSER=${shellQuote(browserPath)}
 PORT=${shellQuote(String(cdpPort))}
 PROFILE=${shellQuote(profileDir)}
 
-exec arch -arm64 "$CHROME" \\
+exec arch -arm64 "$BROWSER" \\
   --remote-debugging-port="$PORT" \\
   --user-data-dir="$PROFILE" \\
   "$@"
@@ -60,7 +66,7 @@ function shellQuote(value) {
 }
 
 /** Paths to the files that make up the bundle. */
-export function bundleLayout(bundlePath) {
+function bundleLayout(bundlePath) {
   const contents = path.join(bundlePath, "Contents");
   return {
     contents,
@@ -74,31 +80,37 @@ export function bundleLayout(bundlePath) {
   };
 }
 
+/** Path shown in `status` for the launcher target. */
+export function targetPath(config) {
+  return config.launcherPath;
+}
+
+export const targetLabel = "App bundle";
+
 /** True when the bundle's executable launcher already exists. */
-export function bundleExists(bundlePath) {
-  return fs.existsSync(bundleLayout(bundlePath).executable);
+export function exists(config) {
+  return fs.existsSync(bundleLayout(config.launcherPath).executable);
 }
 
 /**
  * Create or repair the ChromeCDP.app bundle so its Dock icon and launch
  * behaviour are correct and consistent.
- *
- * @returns {{ created: boolean }} whether the bundle existed beforehand.
+ * @returns {{ created: boolean }} whether the bundle was newly created.
  */
-export function ensureAppBundle(config, { force = false } = {}) {
-  const { bundlePath, chromePath, chromeIcon, cdpPort, profileDir, bundleId } =
+export function ensure(config, { force = false } = {}) {
+  const { launcherPath, browserPath, browserIcon, cdpPort, profileDir, bundleId } =
     config;
-  const layout = bundleLayout(bundlePath);
-  const existed = bundleExists(bundlePath);
+  const layout = bundleLayout(launcherPath);
+  const existed = exists(config);
 
   if (existed && !force) {
     return { created: false };
   }
 
-  if (!fs.existsSync(chromePath)) {
+  if (!fs.existsSync(browserPath)) {
     throw new Error(
-      `Google Chrome not found at:\n  ${chromePath}\n` +
-        `Install Chrome or pass --chrome <path>.`,
+      `Browser not found at:\n  ${browserPath}\n` +
+        `Install it, pick another with --browser, or pass --path <path>.`,
     );
   }
 
@@ -108,14 +120,14 @@ export function ensureAppBundle(config, { force = false } = {}) {
 
     fs.writeFileSync(
       layout.executable,
-      launcherScript({ chromePath, cdpPort, profileDir }),
+      launcherScript({ browserPath, cdpPort, profileDir }),
       { mode: 0o755 },
     );
     fs.writeFileSync(layout.plist, infoPlist({ bundleId }));
 
-    // Use Chrome's own icon so the Dock entry is recognisable.
-    if (fs.existsSync(chromeIcon)) {
-      fs.copyFileSync(chromeIcon, layout.icon);
+    // Use the browser's own icon so the Dock entry is recognisable.
+    if (browserIcon && fs.existsSync(browserIcon)) {
+      fs.copyFileSync(browserIcon, layout.icon);
     }
 
     // Remove the legacy classic-Mac "Icon\r" resource-fork file if present;
@@ -130,17 +142,37 @@ export function ensureAppBundle(config, { force = false } = {}) {
   } catch (error) {
     if (error.code === "EACCES" || error.code === "EPERM") {
       throw new Error(
-        `Permission denied writing to ${bundlePath}.\n` +
-          `Try: sudo npx chrome-cdp-manager setup`,
+        `Permission denied writing to ${launcherPath}.\n` +
+          `Try: sudo chrome-cdp setup`,
       );
     }
     throw error;
   }
 
-  refreshLaunchServices(bundlePath);
+  refreshLaunchServices(launcherPath);
   return { created: !existed };
 }
 
+/**
+ * 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, { headless } = {}) {
+  if (headless) {
+    const { executable } = bundleLayout(config.launcherPath);
+    const child = spawn(executable, ["--headless=new"], {
+      detached: true,
+      stdio: "ignore",
+    });
+    child.unref();
+    return;
+  }
+
+  // `open` returns immediately; readiness is awaited via waitForCdp().
+  const child = spawn("open", [config.launcherPath], { stdio: "ignore" });
+  child.unref();
+}
+
 /**
  * Register the bundle with LaunchServices and bump its mtime so Finder/Dock
  * pick up the (possibly new) icon without a logout.

package/src/launchers/winShortcut.js

@@ -0,0 +1,135 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn, execFileSync } from "node:child_process";
+
+/**
+ * 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
+ * Windows uses its icon/identity; headless runs the browser exe directly.
+ *
+ * The shortcut is created with PowerShell's built-in `WScript.Shell` COM object
+ * — no extra npm dependency, no compiled addon.
+ *
+ * Taskbar note: Chromium derives its AppUserModelID (which controls taskbar
+ * grouping and pinning) from `--user-data-dir`, so the dedicated profile this
+ * tool uses already yields a separate, pinnable taskbar entry.
+ */
+
+/** The browser arguments baked into the shortcut. */
+function shortcutArgs({ cdpPort, profileDir }) {
+  return (
+    `--remote-debugging-port=${cdpPort} ` +
+    `--user-data-dir="${profileDir}"`
+  );
+}
+
+/** Quote a value as a PowerShell single-quoted literal. */
+function psLiteral(value) {
+  return `'${String(value).replace(/'/g, "''")}'`;
+}
+
+/** Path shown in `status` for the launcher target. */
+export function targetPath(config) {
+  return config.launcherPath;
+}
+
+export const targetLabel = "Shortcut";
+
+/** True when the shortcut file already exists. */
+export function exists(config) {
+  return fs.existsSync(config.launcherPath);
+}
+
+/**
+ * Create or repair the ChromeCDP shortcut.
+ * @returns {{ created: boolean }} whether the shortcut was newly created.
+ */
+export function ensure(config, { force = false } = {}) {
+  const { launcherPath, browserPath, browserIcon, cdpPort, profileDir } = config;
+  const existed = exists(config);
+
+  if (existed && !force) {
+    return { created: false };
+  }
+
+  if (!fs.existsSync(browserPath)) {
+    throw new Error(
+      `Browser not found at:\n  ${browserPath}\n` +
+        `Install it, pick another with --browser, or pass --path <path>.`,
+    );
+  }
+
+  fs.mkdirSync(path.dirname(launcherPath), { recursive: true });
+
+  // Default the icon to the browser exe itself (it carries its own icon).
+  const iconLocation = browserIcon || `${browserPath},0`;
+  const script = [
+    "$ErrorActionPreference = 'Stop'",
+    "$WshShell = New-Object -ComObject WScript.Shell",
+    `$s = $WshShell.CreateShortcut(${psLiteral(launcherPath)})`,
+    `$s.TargetPath = ${psLiteral(browserPath)}`,
+    `$s.Arguments = ${psLiteral(shortcutArgs({ cdpPort, profileDir }))}`,
+    `$s.IconLocation = ${psLiteral(iconLocation)}`,
+    `$s.WorkingDirectory = ${psLiteral(path.dirname(browserPath))}`,
+    "$s.Description = 'ChromeCDP — CDP-enabled browser (chrome-cdp-manager)'",
+    "$s.Save()",
+  ].join("\n");
+
+  runPowerShell(script, launcherPath);
+  return { created: !existed };
+}
+
+/**
+ * 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, { headless } = {}) {
+  if (headless) {
+    const child = spawn(
+      config.browserPath,
+      [
+        `--remote-debugging-port=${config.cdpPort}`,
+        `--user-data-dir=${config.profileDir}`,
+        "--headless=new",
+      ],
+      { detached: true, stdio: "ignore" },
+    );
+    child.unref();
+    return;
+  }
+
+  // `start "" "<lnk>"` resolves the shortcut so Windows uses its identity/icon.
+  const child = spawn("cmd", ["/c", "start", "", config.launcherPath], {
+    detached: true,
+    stdio: "ignore",
+  });
+  child.unref();
+}
+
+/** Run a PowerShell script via a temp `.ps1` file (avoids -Command quoting). */
+function runPowerShell(script, launcherPath) {
+  const scriptPath = path.join(
+    os.tmpdir(),
+    `chrome-cdp-shortcut-${process.pid}.ps1`,
+  );
+  try {
+    fs.writeFileSync(scriptPath, script);
+    execFileSync(
+      "powershell.exe",
+      ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-File", scriptPath],
+      { stdio: "ignore" },
+    );
+  } catch (error) {
+    throw new Error(
+      `Failed to create the shortcut at ${launcherPath} via PowerShell.\n` +
+        `${error.message}`,
+    );
+  } finally {
+    try {
+      fs.rmSync(scriptPath, { force: true });
+    } catch {
+      // best effort
+    }
+  }
+}

package/src/platform.js

@@ -1,20 +1,23 @@
 import os from "node:os";
 
+const SUPPORTED = new Set(["darwin", "win32"]);
+
 /**
- * This tool builds a macOS `.app` bundle and relies on `arch -arm64` plus the
- * `open` LaunchServices command, so it only runs on Apple Silicon macOS.
+ * 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() {
-  if (process.platform !== "darwin") {
+  if (!SUPPORTED.has(process.platform)) {
     throw new Error(
-      `chrome-cdp-manager only supports macOS (found "${process.platform}").`,
+      `chrome-cdp-manager supports macOS and Windows ` +
+        `(found "${process.platform}").`,
     );
   }
-  if (os.arch() !== "arm64") {
-    // Not fatal — the launcher uses `arch -arm64`, which is a no-op on arm64
-    // and an error on Intel. Warn rather than block in case of Rosetta setups.
+  if (process.platform === "darwin" && os.arch() !== "arm64") {
+    // Not fatal — the macOS launcher uses `arch -arm64`, which is a no-op on
+    // arm64 and an error on Intel. Warn rather than block in case of Rosetta.
     process.emitWarning(
-      `Detected CPU arch "${os.arch()}". The launcher uses \`arch -arm64\`; ` +
+      `Detected CPU arch "${os.arch()}". The macOS launcher uses \`arch -arm64\`; ` +
         `this is intended for Apple Silicon Macs.`,
     );
   }

package/src/playwright.js

@@ -0,0 +1,71 @@
+/**
+ * Optional Playwright bridge for chrome-cdp-manager.
+ *
+ * Loaded only when you opt in via "chrome-cdp-manager/playwright", so the core
+ * package stays free of heavy dependencies. `playwright` is an OPTIONAL peer
+ * dependency: install it yourself, or inject it through the `chromium` option
+ * (handy for zero-install / npx setups where this module can't resolve
+ * Playwright on its own).
+ */
+import { launch } from "./index.js";
+
+/**
+ * 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 {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
+ *          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 });
+
+  const pwChromium = chromium ?? (await importPlaywright()).chromium;
+  const browser = await pwChromium.connectOverCDP(endpoint);
+  const context = browser.contexts()[0] ?? (await browser.newContext());
+  const page =
+    (match && context.pages().find((p) => match(p.url()))) ??
+    context.pages()[0] ??
+    (await context.newPage());
+
+  if (headless) await unmaskHeadlessUserAgent(context, page);
+
+  return {
+    browser,
+    context,
+    page,
+    config,
+    async [Symbol.asyncDispose]() {
+      await browser.close();
+    },
+  };
+}
+
+async function importPlaywright() {
+  try {
+    return await import("playwright");
+  } catch {
+    throw new Error(
+      "Playwright not found. Install it (`npm i playwright`) or pass `{ chromium }` to connect().",
+    );
+  }
+}
+
+/** Drop "HeadlessChrome" from the UA so sites don't treat the session as headless. */
+async function unmaskHeadlessUserAgent(context, page) {
+  const userAgent = await page.evaluate(() => navigator.userAgent).catch(() => "");
+  const clean = userAgent.replace(/HeadlessChrome/g, "Chrome");
+  if (!clean || clean === userAgent) return;
+
+  await context.setExtraHTTPHeaders({ "user-agent": clean });
+  const session = await context.newCDPSession(page);
+  await session.send("Network.setUserAgentOverride", { userAgent: clean });
+}

package/src/chrome.js

@@ -1,74 +0,0 @@
-import { spawn } from "node:child_process";
-import { bundleLayout } from "./appBundle.js";
-
-/** CDP HTTP endpoint helper. */
-function versionUrl(cdpPort) {
-  return `http://127.0.0.1:${cdpPort}/json/version`;
-}
-
-/** Returns the CDP version payload if Chrome is already listening, else null. */
-export async function probeCdp(cdpPort) {
-  try {
-    const res = await fetch(versionUrl(cdpPort), {
-      signal: AbortSignal.timeout(1000),
-    });
-    if (res.ok) return await res.json();
-  } catch {
-    // not up
-  }
-  return null;
-}
-
-/**
- * Launch Chrome through the ChromeCDP.app bundle.
- *
- * Headed mode goes through `open <bundle>` so LaunchServices attaches the
- * ChromeCDP Dock icon. Headless mode runs the bundle's launcher directly
- * (there is no Dock presence to keep consistent) and forwards `--headless=new`.
- */
-export function launchChrome({ bundlePath, headless }) {
-  if (headless) {
-    const { executable } = bundleLayout(bundlePath);
-    const child = spawn(executable, ["--headless=new"], {
-      detached: true,
-      stdio: "ignore",
-    });
-    child.unref();
-    return;
-  }
-
-  // `open` returns immediately; readiness is awaited via waitForCdp().
-  const child = spawn("open", [bundlePath], { stdio: "ignore" });
-  child.unref();
-}
-
-/** Poll the CDP endpoint until it responds or the timeout elapses. */
-export async function waitForCdp(cdpPort, timeoutMs = 30_000) {
-  const deadline = Date.now() + timeoutMs;
-  while (Date.now() < deadline) {
-    const version = await probeCdp(cdpPort);
-    if (version) return version;
-    await delay(250);
-  }
-  throw new Error(
-    `Timed out after ${Math.round(timeoutMs / 1000)}s waiting for Chrome CDP ` +
-      `at ${versionUrl(cdpPort)}.`,
-  );
-}
-
-/**
- * Ensure Chrome is running and CDP is reachable, launching it if needed.
- * @returns {Promise<{ launched: boolean, version: object }>}
- */
-export async function ensureChromeRunning({ bundlePath, cdpPort, headless, timeoutMs }) {
-  const existing = await probeCdp(cdpPort);
-  if (existing) return { launched: false, version: existing };
-
-  launchChrome({ bundlePath, headless });
-  const version = await waitForCdp(cdpPort, timeoutMs);
-  return { launched: true, version };
-}
-
-function delay(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}