cdp-toolkit 3.0.2 → 3.0.3

package/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to cdp-toolkit are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [3.0.3] - 2026-10-29
+
+### Fixed
+
+- `new_page` (and `claim_page` opening a fresh tab) wedged the tab in Vivaldi: blank content, an empty URL, a renderer that never answered again, and a 15 s `new_page` timeout under `claim:true`, until a person reloaded it. Vivaldi breaks any tab that something attaches to in its first few milliseconds, and the activity beacon attached straight after `Target.createTarget`. `newPage` now waits for the tab's first `Target.targetInfoChanged` (capped at 2 s) before returning. Verified live on Vivaldi 8.2 (Chromium 152) through `new_page {claim:true}`: on 3.0.2 two of two Fidelity tabs hung; with the fix three of three loaded in 230 to 390 ms with the beacon installed. (`src/cdp/driver.ts` `createSettledTarget`, `test/new-page-settle.test.ts`)
+
+### Added
+
+- `vivaldi` is now a supported `cdp install --browser` choice, wired like `arc`: binary detection (`VIVALDI_BIN`, `/Applications/Vivaldi.app/Contents/MacOS/Vivaldi`, `vivaldi` on PATH, `/usr/bin/vivaldi`), the `cdp-vivaldi` alias, the CLI choice list and help text, and the README. Vivaldi is Chromium, so it takes the same launch flags and the server env is the same as chrome and arc. (`src/install/browser.ts`, `src/install/wizard.ts`, `test/install-browser.test.ts`, `test/install-wizard.test.ts`)
+
 ## [3.0.2] - 2026-10-03
 
 ### Fixed

package/README.md

@@ -76,7 +76,7 @@ One honest caveat the benchmark also reports: while a navigation to a dead endpo
 npx -y --package cdp-toolkit cdp install     # or `cdp install` from a clone / after a global install
 ```
 
-It asks for a harness (`claude` | `codex` | `opencode`), a debug port, and a browser (`arc` | `chrome` | `firefox`), then writes an idempotent marker block into your `~/.zshrc`/`~/.bashrc`. The same flags drive it non-interactively: `--harness --browser --port --name --no-alias --yes`. The Firefox alias it writes includes `--marionette` (required for cdp-toolkit's orphaned-session auto-recovery — see [Firefox](#firefox-webdriver-bidi)). It is a CLI subcommand, **not** a 49th tool: `cdp --list` still shows 48.
+It asks for a harness (`claude` | `codex` | `opencode`), a debug port, and a browser (`arc` | `chrome` | `firefox` | `vivaldi`), then writes an idempotent marker block into your `~/.zshrc`/`~/.bashrc`. The same flags drive it non-interactively: `--harness --browser --port --name --no-alias --yes`. The Firefox alias it writes includes `--marionette` (required for cdp-toolkit's orphaned-session auto-recovery — see [Firefox](#firefox-webdriver-bidi)). It is a CLI subcommand, **not** a 49th tool: `cdp --list` still shows 48.
 
 Prefer to wire it by hand? The manual path is three steps:
 

package/dist/cli.js

@@ -4869,6 +4869,41 @@ function noSuchTarget(e) {
     throw e;
   throw driverError("no-such-target", e instanceof CdpError ? e.message : String(e));
 }
+var NEW_TARGET_SETTLE_MS = 2000;
+async function createSettledTarget(conn, url, settleMs = NEW_TARGET_SETTLE_MS) {
+  const changed = new Set;
+  let id = "";
+  let wake;
+  const off = conn.on("Target.targetInfoChanged", (params) => {
+    const t = params.targetInfo?.targetId;
+    if (!t)
+      return;
+    changed.add(t);
+    if (t === id)
+      wake?.();
+  });
+  try {
+    await conn.send("Target.setDiscoverTargets", { discover: true }).catch(() => {
+      return;
+    });
+    const { targetId } = await conn.send("Target.createTarget", { url });
+    if (!targetId)
+      throw driverError("page-error", "Target.createTarget returned no targetId");
+    id = targetId;
+    if (!changed.has(targetId)) {
+      await new Promise((resolve) => {
+        const timer = setTimeout(resolve, settleMs);
+        wake = () => {
+          clearTimeout(timer);
+          resolve();
+        };
+      });
+    }
+    return targetId;
+  } finally {
+    off();
+  }
+}
 
 class CdpBrowserDriver {
   scheme = "cdp";
@@ -4883,9 +4918,7 @@ class CdpBrowserDriver {
   }
   async newPage(url) {
     return withBrowserConn(async (conn) => {
-      const { targetId } = await conn.send("Target.createTarget", { url: url ?? "about:blank" });
-      if (!targetId)
-        throw driverError("page-error", "Target.createTarget returned no targetId");
+      const targetId = await createSettledTarget(conn, url ?? "about:blank");
       return { id: targetId, url: url ?? "about:blank", title: "" };
     });
   }
@@ -10760,6 +10793,12 @@ var CANDIDATE_BUILDERS = {
     "chromium"
   ],
   arc: () => [process.env.ARC_BIN, "/Applications/Arc.app/Contents/MacOS/Arc", "arc"],
+  vivaldi: () => [
+    process.env.VIVALDI_BIN,
+    "/Applications/Vivaldi.app/Contents/MacOS/Vivaldi",
+    "vivaldi",
+    "/usr/bin/vivaldi"
+  ],
   firefox: () => [
     process.env.FIREFOX_BIN,
     "/Applications/Firefox.app/Contents/MacOS/firefox",
@@ -11007,7 +11046,7 @@ function isOnPath(bin) {
 // src/install/wizard.ts
 var DEFAULT_NAME = "cdp-toolkit";
 var HARNESSES = ["claude", "codex", "opencode"];
-var BROWSERS = ["arc", "chrome", "firefox"];
+var BROWSERS = ["arc", "chrome", "firefox", "vivaldi"];
 function defaultPortFor(browser) {
   return browser === "firefox" ? 9223 : 9222;
 }
@@ -11020,10 +11059,10 @@ function parseHarness(v) {
 }
 function parseBrowserChoice(v) {
   if (v === undefined)
-    throw new Error("--browser requires a value: arc, chrome, or firefox");
+    throw new Error("--browser requires a value: arc, chrome, firefox, or vivaldi");
   if (BROWSERS.includes(v))
     return v;
-  throw new Error(`--browser must be one of arc|chrome|firefox (got '${v}')`);
+  throw new Error(`--browser must be one of arc|chrome|firefox|vivaldi (got '${v}')`);
 }
 function parsePort(v) {
   if (v === undefined)
@@ -11104,14 +11143,14 @@ function installHelpText() {
 browser-launch alias (with the remote-debugging port open) to your shell rc.
 
 Usage:
-  cdp install [--harness <claude|codex|opencode>] [--browser <arc|chrome|firefox>]
+  cdp install [--harness <claude|codex|opencode>] [--browser <arc|chrome|firefox|vivaldi>]
               [--port <n>] [--name <server-name>] [--alias-name <name>]
               [--no-alias] [--yes|-y] [--help|-h]
 
 Options:
   --harness <h>     Coding harness to register the MCP server with: claude, codex, opencode.
-  --browser <b>     Browser the alias launches: arc, chrome, firefox.
-  --port <n>        Remote-debugging port (1-65535). Default: 9222 (chrome/arc), 9223 (firefox).
+  --browser <b>     Browser the alias launches: arc, chrome, firefox, vivaldi.
+  --port <n>        Remote-debugging port (1-65535). Default: 9222 (chrome/arc/vivaldi), 9223 (firefox).
   --name <name>     MCP server name to register. Default: ${DEFAULT_NAME}.
   --alias-name <n>  Shell alias name. Default: cdp-<browser> (e.g. cdp-firefox).
   --no-alias        Register the MCP server only; skip writing the shell alias.

package/dist/index.js

@@ -2267,6 +2267,41 @@ function noSuchTarget(e) {
     throw e;
   throw driverError("no-such-target", e instanceof CdpError ? e.message : String(e));
 }
+var NEW_TARGET_SETTLE_MS = 2000;
+async function createSettledTarget(conn, url, settleMs = NEW_TARGET_SETTLE_MS) {
+  const changed = new Set;
+  let id = "";
+  let wake;
+  const off = conn.on("Target.targetInfoChanged", (params) => {
+    const t = params.targetInfo?.targetId;
+    if (!t)
+      return;
+    changed.add(t);
+    if (t === id)
+      wake?.();
+  });
+  try {
+    await conn.send("Target.setDiscoverTargets", { discover: true }).catch(() => {
+      return;
+    });
+    const { targetId } = await conn.send("Target.createTarget", { url });
+    if (!targetId)
+      throw driverError("page-error", "Target.createTarget returned no targetId");
+    id = targetId;
+    if (!changed.has(targetId)) {
+      await new Promise((resolve) => {
+        const timer = setTimeout(resolve, settleMs);
+        wake = () => {
+          clearTimeout(timer);
+          resolve();
+        };
+      });
+    }
+    return targetId;
+  } finally {
+    off();
+  }
+}
 
 class CdpBrowserDriver {
   scheme = "cdp";
@@ -2281,9 +2316,7 @@ class CdpBrowserDriver {
   }
   async newPage(url) {
     return withBrowserConn(async (conn) => {
-      const { targetId } = await conn.send("Target.createTarget", { url: url ?? "about:blank" });
-      if (!targetId)
-        throw driverError("page-error", "Target.createTarget returned no targetId");
+      const targetId = await createSettledTarget(conn, url ?? "about:blank");
       return { id: targetId, url: url ?? "about:blank", title: "" };
     });
   }

package/dist/mcp.js

@@ -4882,6 +4882,41 @@ function noSuchTarget(e) {
     throw e;
   throw driverError("no-such-target", e instanceof CdpError ? e.message : String(e));
 }
+var NEW_TARGET_SETTLE_MS = 2000;
+async function createSettledTarget(conn, url, settleMs = NEW_TARGET_SETTLE_MS) {
+  const changed = new Set;
+  let id = "";
+  let wake;
+  const off = conn.on("Target.targetInfoChanged", (params) => {
+    const t = params.targetInfo?.targetId;
+    if (!t)
+      return;
+    changed.add(t);
+    if (t === id)
+      wake?.();
+  });
+  try {
+    await conn.send("Target.setDiscoverTargets", { discover: true }).catch(() => {
+      return;
+    });
+    const { targetId } = await conn.send("Target.createTarget", { url });
+    if (!targetId)
+      throw driverError("page-error", "Target.createTarget returned no targetId");
+    id = targetId;
+    if (!changed.has(targetId)) {
+      await new Promise((resolve) => {
+        const timer = setTimeout(resolve, settleMs);
+        wake = () => {
+          clearTimeout(timer);
+          resolve();
+        };
+      });
+    }
+    return targetId;
+  } finally {
+    off();
+  }
+}
 
 class CdpBrowserDriver {
   scheme = "cdp";
@@ -4896,9 +4931,7 @@ class CdpBrowserDriver {
   }
   async newPage(url) {
     return withBrowserConn(async (conn) => {
-      const { targetId } = await conn.send("Target.createTarget", { url: url ?? "about:blank" });
-      if (!targetId)
-        throw driverError("page-error", "Target.createTarget returned no targetId");
+      const targetId = await createSettledTarget(conn, url ?? "about:blank");
       return { id: targetId, url: url ?? "about:blank", title: "" };
     });
   }
@@ -11369,7 +11402,7 @@ var TOOL_DOCS = {
 };
 
 // src/version.ts
-var VERSION = "3.0.2";
+var VERSION = "3.0.3";
 
 // src/mcp.ts
 function isDirectRun() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdp-toolkit",
-  "version": "3.0.2",
+  "version": "3.0.3",
   "description": "A lightweight chrome-devtools-mcp alternative: an MCP server + CLI that drives the tabs you name, one target per call over one direct WebSocket, with a bounded timeout on every call, so a stuck page can't wedge your agent or force a /mcp restart. Chrome over CDP and Firefox over WebDriver BiDi, with tools a backend can't run absent from tools/list rather than throwing mid-task. 48 tools (only 5 core tools listed by default, plus search_tools/call_tool to reach the rest) including built-in network mocking, a cookie group, tab leases with human-activity detection, real HTML5 drag-and-drop, raw mouse/scroll dispatch, downloads, permission grants, and tab-to-video screen recording so several agents can drive one browser without stealing each other's tabs or a human's. No Puppeteer, no all-target fan-out.",
   "type": "module",
   "license": "MIT",

package/src/cdp/driver.ts

@@ -1691,6 +1691,56 @@ function noSuchTarget(e: unknown): never {
   if (typeof (e as { code?: unknown } | null | undefined)?.code === "string") throw e;
   throw driverError("no-such-target", e instanceof CdpError ? e.message : String(e));
 }
+/** Upper bound on waiting for a new tab to settle; see createSettledTarget. */
+export const NEW_TARGET_SETTLE_MS = 2000;
+
+/**
+ * Create a tab and return only once the browser has finished adopting it.
+ *
+ * Vivaldi wedges a tab that anything attaches to in the first few milliseconds
+ * after Target.createTarget: the tab keeps an empty URL, its renderer never
+ * answers again (Page.enable, Runtime.evaluate and runIfWaitingForDebugger all
+ * time out), and only a manual reload recovers it. new_page{claim:true} hit this
+ * every time, because the activity beacon attaches straight after creation.
+ * Measured on Vivaldi 8.2 (Chromium 152): an attach at ~0ms wedged 5/5 tabs
+ * (https and about:blank alike, page socket or flattened session alike); an
+ * attach after the tab's first Target.targetInfoChanged loaded 5/5.
+ *
+ * So: discover targets, create, and wait for that first targetInfoChanged for
+ * this id, capped at NEW_TARGET_SETTLE_MS. The listener is registered BEFORE
+ * createTarget because the event can beat the command's response. A browser
+ * that never sends the event costs at most the cap, never a failure.
+ */
+export async function createSettledTarget(
+  conn: Pick<CdpConnection, "send" | "on">,
+  url: string,
+  settleMs = NEW_TARGET_SETTLE_MS,
+): Promise<string> {
+  const changed = new Set<string>();
+  let id = "";
+  let wake: (() => void) | undefined;
+  const off = conn.on("Target.targetInfoChanged", (params) => {
+    const t = (params as { targetInfo?: { targetId?: string } }).targetInfo?.targetId;
+    if (!t) return;
+    changed.add(t);
+    if (t === id) wake?.();
+  });
+  try {
+    await conn.send("Target.setDiscoverTargets", { discover: true }).catch(() => undefined);
+    const { targetId } = await conn.send<{ targetId: string }>("Target.createTarget", { url });
+    if (!targetId) throw driverError("page-error", "Target.createTarget returned no targetId");
+    id = targetId;
+    if (!changed.has(targetId)) {
+      await new Promise<void>((resolve) => {
+        const timer = setTimeout(resolve, settleMs);
+        wake = () => { clearTimeout(timer); resolve(); };
+      });
+    }
+    return targetId;
+  } finally {
+    off();
+  }
+}
 class CdpBrowserDriver implements BrowserDriver {
   readonly scheme = "cdp";
   readonly lifetime: LifetimeModel = "per-call";
@@ -1706,8 +1756,7 @@ class CdpBrowserDriver implements BrowserDriver {
   }
   async newPage(url?: string): Promise<PageInfo> {
     return withBrowserConn(async (conn) => {
-      const { targetId } = await conn.send<{ targetId: string }>("Target.createTarget", { url: url ?? "about:blank" });
-      if (!targetId) throw driverError("page-error", "Target.createTarget returned no targetId");
+      const targetId = await createSettledTarget(conn, url ?? "about:blank");
       return { id: targetId, url: url ?? "about:blank", title: "" };
     });
   }

package/src/install/browser.ts

@@ -10,7 +10,7 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { delimiter, dirname, join } from "node:path";
 
-export type BrowserChoice = "arc" | "chrome" | "firefox";
+export type BrowserChoice = "arc" | "chrome" | "firefox" | "vivaldi";
 
 export interface BrowserInfo {
   choice: BrowserChoice;
@@ -40,7 +40,7 @@ export interface RcAppendResult {
 
 /**
  * Per-choice candidate lists, built fresh on every call so env var overrides (CHROME_BIN /
- * ARC_BIN / FIREFOX_BIN) are read live rather than captured once at module load — important for
+ * ARC_BIN / VIVALDI_BIN / FIREFOX_BIN) are read live rather than captured once at module load — important for
  * tests that set/restore these env vars around a single call.
  *
  * macOS-first, Linux fallback. Order mirrors the spec: env override, then the macOS .app bundle
@@ -56,6 +56,12 @@ const CANDIDATE_BUILDERS: Record<BrowserChoice, () => Array<string | undefined>>
     "chromium",
   ],
   arc: () => [process.env.ARC_BIN, "/Applications/Arc.app/Contents/MacOS/Arc", "arc"],
+  vivaldi: () => [
+    process.env.VIVALDI_BIN,
+    "/Applications/Vivaldi.app/Contents/MacOS/Vivaldi",
+    "vivaldi",
+    "/usr/bin/vivaldi",
+  ],
   firefox: () => [
     process.env.FIREFOX_BIN,
     "/Applications/Firefox.app/Contents/MacOS/firefox",
@@ -113,7 +119,7 @@ export function defaultAliasName(choice: BrowserChoice): string {
 }
 
 /**
- * The launch flags only (no binary). Chrome and Arc are both Chromium-based and Arc accepts
+ * The launch flags only (no binary). Chrome, Arc and Vivaldi are all Chromium-based and accept
  * Chrome's flags, so they share a shape: --remote-debugging-port plus a DEDICATED
  * --user-data-dir. The dedicated profile is required, not cosmetic — Chrome silently ignores
  * --remote-debugging-port when it hands off to an already-running instance on the default

package/src/install/wizard.ts

@@ -63,7 +63,7 @@ export interface InstallerIO {
 
 const DEFAULT_NAME = "cdp-toolkit";
 const HARNESSES: readonly HarnessChoice[] = ["claude", "codex", "opencode"];
-const BROWSERS: readonly BrowserChoice[] = ["arc", "chrome", "firefox"];
+const BROWSERS: readonly BrowserChoice[] = ["arc", "chrome", "firefox", "vivaldi"];
 
 /* --------------------------------- pure: arg parsing --------------------------------- */
 
@@ -79,9 +79,9 @@ function parseHarness(v: string | undefined): HarnessChoice {
 }
 
 function parseBrowserChoice(v: string | undefined): BrowserChoice {
-  if (v === undefined) throw new Error("--browser requires a value: arc, chrome, or firefox");
+  if (v === undefined) throw new Error("--browser requires a value: arc, chrome, firefox, or vivaldi");
   if ((BROWSERS as readonly string[]).includes(v)) return v as BrowserChoice;
-  throw new Error(`--browser must be one of arc|chrome|firefox (got '${v}')`);
+  throw new Error(`--browser must be one of arc|chrome|firefox|vivaldi (got '${v}')`);
 }
 
 function parsePort(v: string | undefined): number {
@@ -165,8 +165,8 @@ export function parseInstallArgs(argv: string[]): InstallArgs {
  * PURE. Build the MCP stdio server config for a given browser + debug port.
  *
  * The server always runs `npx -y cdp-toolkit`. Only the env differs by browser, and even then
- * chrome and arc are IDENTICAL: both are driven over CDP, and the driver just talks CDP to
- * whatever is listening on CDP_BASE — the arc-vs-chrome distinction lives entirely in the shell
+ * chrome, arc and vivaldi are IDENTICAL: both are driven over CDP, and the driver just talks CDP to
+ * whatever is listening on CDP_BASE — the arc-vs-chrome-vs-vivaldi distinction lives entirely in the shell
  * ALIAS (which .app it launches), not in the server env. Firefox is the odd one out: it is driven
  * over WebDriver BiDi, selected by CDP_BROWSER=firefox with the port in CDP_FIREFOX_ENDPOINT.
  */
@@ -185,14 +185,14 @@ export function installHelpText(): string {
 browser-launch alias (with the remote-debugging port open) to your shell rc.
 
 Usage:
-  cdp install [--harness <claude|codex|opencode>] [--browser <arc|chrome|firefox>]
+  cdp install [--harness <claude|codex|opencode>] [--browser <arc|chrome|firefox|vivaldi>]
               [--port <n>] [--name <server-name>] [--alias-name <name>]
               [--no-alias] [--yes|-y] [--help|-h]
 
 Options:
   --harness <h>     Coding harness to register the MCP server with: claude, codex, opencode.
-  --browser <b>     Browser the alias launches: arc, chrome, firefox.
-  --port <n>        Remote-debugging port (1-65535). Default: 9222 (chrome/arc), 9223 (firefox).
+  --browser <b>     Browser the alias launches: arc, chrome, firefox, vivaldi.
+  --port <n>        Remote-debugging port (1-65535). Default: 9222 (chrome/arc/vivaldi), 9223 (firefox).
   --name <name>     MCP server name to register. Default: ${DEFAULT_NAME}.
   --alias-name <n>  Shell alias name. Default: cdp-<browser> (e.g. cdp-firefox).
   --no-alias        Register the MCP server only; skip writing the shell alias.

package/src/version.ts

@@ -6,4 +6,4 @@
  * ready line; keeping it in its own module means a release bump touches one
  * line here plus package.json, not a const buried in the server.
  */
-export const VERSION = "3.0.2";
+export const VERSION = "3.0.3";