cdp-toolkit 3.0.1 → 3.0.3

package/CHANGELOG.md

@@ -5,6 +5,24 @@ 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
+
+- CLI: `get_network_request --requestId <id>` failed with "no network request matched" for every Fetch/XHR request. CDP mints those ids as `<pid>.<n>` (e.g. `91775.34`), and the CLI coerced any numeric-looking flag value to a number, so the lookup compared a number against the stored string, and `91775.10` was mangled to `91775.1`. Flag coercion now follows the tool's schema: a key typed as a string keeps its raw text, and every other key is coerced as before. Verified live on headless Chrome 154: all 6 captured requests resolve by `--requestId` from both the source and the built CLI; on 3.0.1 the 5 Fetch requests failed and only the hex-id Document request resolved. MCP callers were not affected, since their arguments arrive already typed. (`src/cli.ts`, `test/cli-coerce.test.ts`)
+
 ## [3.0.1] - 2026-09-29
 
 ### 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:
 
@@ -218,7 +218,7 @@ cdp take_screenshot --target url:example --renderWidth 1920 --renderHeight 1080
 cdp lighthouse_audit --url https://example.com --json '{"categories":["performance"]}'
 ```
 
-**Argument parsing:** the first positional token is the tool name. `--json '<obj>'` merges a JSON object into the args (applied first). `--target <sel>` sets `args.target`. Repeated `--key value` pairs become `args.key`, coerced (`true`/`false` → boolean, numeric strings → number, else string); a bare `--flag` is `true`. Explicit flags override keys from `--json`. Output is `JSON.stringify(result, null, 2)` on stdout (exit 0); on any throw, `{"error":"<message>"}` goes to stderr and the process exits 1.
+**Argument parsing:** the first positional token is the tool name. `--json '<obj>'` merges a JSON object into the args (applied first). `--target <sel>` sets `args.target`. Repeated `--key value` pairs become `args.key`. A key the tool's schema types as a string keeps its raw text (so `--requestId 91775.10` stays `"91775.10"`); any other key is coerced (`true`/`false` → boolean, numeric strings → number, else string). A bare `--flag` is `true`. Explicit flags override keys from `--json`. Output is `JSON.stringify(result, null, 2)` on stdout (exit 0); on any throw, `{"error":"<message>"}` goes to stderr and the process exits 1.
 
 **`--help`/`-h`** are recognized anywhere in argv, ahead of every other flag, and are never treated as a tool argument or a tool name — as of 1.9.3, `<tool> --help` used to run the tool instead. With no tool named, `cdp --help` prints the usage above. With a tool named, `cdp <tool> --help` prints that tool's arguments (name, type, required/optional, description) read from its schema, and exits 0 having made no CDP connection, taken no lease, and written no file.
 

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.
@@ -11370,6 +11409,13 @@ function coerce(raw) {
   }
   return raw;
 }
+function coerceForTool(tool, key, raw) {
+  const spec = tool === undefined ? undefined : MANIFEST.find((t) => t.name === tool);
+  const prop = spec?.inputSchema.properties?.[key];
+  if (prop?.type === "string")
+    return raw;
+  return coerce(raw);
+}
 function parseArgv(argv) {
   const out = { list: false, capabilities: false, help: false, args: {} };
   let jsonObj;
@@ -11407,7 +11453,7 @@ function parseArgv(argv) {
         flagPairs.push(["target", rawValue]);
         continue;
       }
-      flagPairs.push([key, hasValue ? coerce(rawValue) : true]);
+      flagPairs.push([key, hasValue ? rawValue : true]);
       continue;
     }
     if (out.tool === undefined)
@@ -11415,8 +11461,9 @@ function parseArgv(argv) {
   }
   if (jsonObj)
     Object.assign(out.args, jsonObj);
-  for (const [k, v] of flagPairs)
-    out.args[k] = v;
+  for (const [k, v] of flagPairs) {
+    out.args[k] = v === true || k === "target" ? v : coerceForTool(out.tool, k, v);
+  }
   return out;
 }
 function isToolName(name) {
@@ -11559,3 +11606,6 @@ if (isDirectRun()) {
     process.exit(1);
   });
 }
+export {
+  parseArgv
+};

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.1";
+var VERSION = "3.0.3";
 
 // src/mcp.ts
 function isDirectRun() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdp-toolkit",
-  "version": "3.0.1",
+  "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/cli.ts

@@ -9,9 +9,11 @@
  *   - First positional token is the tool name (a key of TOOLS).
  *   - `--json '<obj>'` parses a JSON object and merges it into the args object.
  *   - `--target <sel>` sets `args.target` (a TargetSelector string).
- *   - Any other `--key value` pair becomes `args.key`, with the value coerced:
- *       "true"/"false" -> boolean, a numeric string -> number, else the raw
- *       string. A bare `--flag` with no following value (or followed by another
+ *   - Any other `--key value` pair becomes `args.key`. When the tool's MANIFEST
+ *       inputSchema declares the key `type: "string"`, the raw string is kept
+ *       as-is (so a CDP requestId like "91775.10" is not turned into the number
+ *       91775.1). Otherwise the value is coerced: "true"/"false" -> boolean, a
+ *       numeric string -> number, else the raw string. A bare `--flag` with no following value (or followed by another
  *       --flag) is treated as boolean true.
  *   - Explicit `--key` pairs OVERRIDE keys merged from `--json` (last writer
  *     wins; --json is applied first, then the individual flags).
@@ -108,6 +110,20 @@ function coerce(raw: string): boolean | number | string {
   return raw;
 }
 
+/**
+ * Coerce one `--key value` using the tool's declared schema type. A key the
+ * schema types as "string" keeps its raw text verbatim; coercing it would turn
+ * an id that merely LOOKS numeric ("91775.10", "007") into a number that no
+ * longer matches, or into a different string entirely. Every other key (or a
+ * tool/key the manifest doesn't know) falls back to coerce().
+ */
+function coerceForTool(tool: string | undefined, key: string, raw: string): boolean | number | string {
+  const spec = tool === undefined ? undefined : MANIFEST.find((t) => t.name === tool);
+  const prop = spec?.inputSchema.properties?.[key] as { type?: unknown } | undefined;
+  if (prop?.type === "string") return raw;
+  return coerce(raw);
+}
+
 interface ParsedArgs {
   tool?: string;
   list: boolean;
@@ -117,12 +133,14 @@ interface ParsedArgs {
 }
 
 /** Parse process argv (already sliced to drop the runtime + script, and with --browser already stripped). */
-function parseArgv(argv: string[]): ParsedArgs {
+export function parseArgv(argv: string[]): ParsedArgs {
   const out: ParsedArgs = { list: false, capabilities: false, help: false, args: {} };
   // Collect flag pairs separately so --json can be merged BEFORE individual
   // flags override it, regardless of token order.
   let jsonObj: Record<string, unknown> | undefined;
-  const flagPairs: Array<[string, unknown]> = [];
+  // Raw values are kept until the tool name is known (it may follow the flags),
+  // so coercion can consult that tool's schema.
+  const flagPairs: Array<[string, string | true]> = [];
 
   for (let i = 0; i < argv.length; i++) {
     const token = argv[i]!;
@@ -164,7 +182,7 @@ function parseArgv(argv: string[]): ParsedArgs {
         flagPairs.push(["target", rawValue]);
         continue;
       }
-      flagPairs.push([key, hasValue ? coerce(rawValue) : true]);
+      flagPairs.push([key, hasValue ? rawValue : true]);
       continue;
     }
     // First non-flag positional is the tool name; ignore any extras.
@@ -173,7 +191,9 @@ function parseArgv(argv: string[]): ParsedArgs {
 
   // --json first, then explicit flags win.
   if (jsonObj) Object.assign(out.args, jsonObj);
-  for (const [k, v] of flagPairs) out.args[k] = v;
+  for (const [k, v] of flagPairs) {
+    out.args[k] = v === true || k === "target" ? v : coerceForTool(out.tool, k, v);
+  }
   return out;
 }
 

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.1";
+export const VERSION = "3.0.3";