chrome-cdp-manager 1.1.0 → 1.2.1

package/README.md

@@ -73,6 +73,41 @@ chrome-cdp stop
 | `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                                                   |

package/package.json

@@ -1,8 +1,14 @@
 {
   "name": "chrome-cdp-manager",
-  "version": "1.1.0",
+  "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"
@@ -42,5 +48,13 @@
   "license": "MIT",
   "dependencies": {
     "commander": "^12.1.0"
+  },
+  "peerDependencies": {
+    "playwright": "*"
+  },
+  "peerDependenciesMeta": {
+    "playwright": {
+      "optional": true
+    }
   }
 }

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/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 });
+}