@browserbridge/bbx 1.2.0 → 1.3.0

package/README.md

@@ -99,17 +99,18 @@ Managed installs support OpenAI Codex, Claude Code, Cursor, GitHub Copilot, Open
 
 ## Why Browser Bridge
 
-Most adjacent tools optimize for different goals. [Playwright](https://playwright.dev/) and headless automation stacks are excellent for deterministic tests and CI - but they start from a clean browser context by design. [Claude in Chrome](https://support.claude.com/en/articles/12012173-get-started-with-claude-in-chrome) is great for integrated Claude workflows, but is vendor-specific. Generic MCP browser servers offer broad control without the developer-focused depth.
+Most adjacent tools optimize for different goals. [Playwright](https://playwright.dev/) and headless automation stacks are excellent for deterministic tests and CI - but they start from a clean browser context by design. [Claude in Chrome](https://support.claude.com/en/articles/12012173-get-started-with-claude-in-chrome) is great for integrated Claude workflows, and the [Codex extension](https://chromewebstore.google.com/detail/codex/hehggadaopoacecdllhhajmbjkdcmajg) is a great option if you use Codex, but both are vendor-specific. Generic MCP browser servers offer broad control without the developer-focused depth.
 
 Browser Bridge is optimized for the opposite starting point: **inspect the state that already exists** in a real tab - logged-in sessions, feature flags, seeded storage, SPA state - use structured reads to understand it, test a patch in place, then fix the source. It's open-source, agent-agnostic, and scoped to explicit tab sessions rather than ambient browser control.
 
 ## Setup
 
-1. Install [Browser Bridge from the Chrome Web Store](https://chromewebstore.google.com/detail/browser-bridge/jjjkmmcdkpcgamlopogicbnnhdgebhie)
+1. Install [Browser Bridge from the Chrome Web Store](https://chromewebstore.google.com/detail/browser-bridge/jjjkmmcdkpcgamlopogicbnnhdgebhie) in Chrome or another Chromium-based browser
 2. `npm install -g @browserbridge/bbx` - installs the CLI and native host
-3. In the extension side panel, install MCP or CLI (skill) for your agent of choice
-4. Enable Browser Bridge for the Chrome window you want to inspect/control with the AI agent
-5. Ask your agent to use Browser Bridge via MCP (`BB MCP` or `Browser Bridge MCP`), or invoke the `browser-bridge` / `$bbx` skill in CLI mode
+3. Run `bbx install`, or target a specific browser with `bbx install --browser edge`, `bbx install --browser brave`, `bbx install --browser chromium`, or `bbx install --browser arc`
+4. In the extension side panel, install MCP or CLI (skill) for your agent of choice
+5. Enable Browser Bridge for the browser window you want to inspect/control with the AI agent
+6. Ask your agent to use Browser Bridge via MCP (`BB MCP` or `Browser Bridge MCP`), or invoke the `browser-bridge` / `$bbx` skill in CLI mode
 
 ## How it works
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserbridge/bbx",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "private": false,
   "keywords": [
     "agent-tools",

package/packages/agent-client/src/cli.js

@@ -50,8 +50,8 @@ import { getDoctorReport, requestBridge, resolveRef } from './runtime.js';
 import { collectSetupStatus } from './setup-status.js';
 import { annotateBridgeSummary, summarizeBridgeResponse } from './subagent.js';
 
-/** @typedef {import('../../protocol/src/types.js').BridgeMethod} BridgeMethod */
-/** @typedef {{ image: string, rect: Record<string, unknown> }} ScreenshotResult */
+/** @typedef {import('./types.js').BridgeMethod} BridgeMethod */
+/** @typedef {import('./types.js').ScreenshotResult} ScreenshotResult */
 
 const REQUEST_SOURCE = 'cli';
 const TEST_TIMEOUT_ENV = 'BBX_CLIENT_REQUEST_TIMEOUT_MS';
@@ -139,8 +139,8 @@ if (command === 'install-skill') {
       projectPath: isGlobal ? os.homedir() : process.cwd(),
       ...getSetupStatusTestOverrides(),
     });
-    /** @type {import('./install.js').SupportedTarget[]} */
-    const detected = /** @type {import('./install.js').SupportedTarget[]} */ (
+    /** @type {import('./types.js').SupportedTarget[]} */
+    const detected = /** @type {import('./types.js').SupportedTarget[]} */ (
       setupStatus.skillTargets.filter((entry) => entry.detected).map((entry) => entry.key)
     );
     const installedManagedTargets = new Set(
@@ -149,7 +149,7 @@ if (command === 'install-skill') {
         .map((entry) => entry.key)
     );
     const installedManagedTargetList =
-      /** @type {import('./install.js').SupportedTarget[]} */ ([...installedManagedTargets]);
+      /** @type {import('./types.js').SupportedTarget[]} */ ([...installedManagedTargets]);
 
     // Aliases like 'openai' and 'google' map to canonical targets and stay omitted.
     const items = SUPPORTED_TARGETS.map((t) => ({
@@ -167,19 +167,19 @@ if (command === 'install-skill') {
       items
     );
 
-    /** @type {import('./install.js').SupportedTarget[]} */
+    /** @type {import('./types.js').SupportedTarget[]} */
     let targets;
     if (selected === null) {
       // Non-TTY: prefer managed installs, then detected targets (always includes 'agents').
       targets = installedManagedTargets.size > 0 ? installedManagedTargetList : detected;
     } else {
-      targets = /** @type {import('./install.js').SupportedTarget[]} */ (selected);
+      targets = /** @type {import('./types.js').SupportedTarget[]} */ (selected);
     }
 
     const projectPath = isGlobal ? os.homedir() : process.cwd();
     if (selected !== null) {
       const deselectedTargets =
-        /** @type {import('./install.js').SupportedTarget[]} */ (
+        /** @type {import('./types.js').SupportedTarget[]} */ (
           installedManagedTargetList.filter((target) => !targets.includes(target))
         );
       const removableTargets = await findInstalledManagedTargets({
@@ -241,7 +241,7 @@ if (command === 'install-mcp') {
 
   const clientArg = argsLeft[0];
 
-  /** @type {import('./mcp-config.js').McpClientName[]} */
+  /** @type {import('./types.js').McpClientName[]} */
   let clients;
 
   if (!clientArg) {
@@ -252,14 +252,14 @@ if (command === 'install-mcp') {
       projectPath: process.cwd(),
       ...getSetupStatusTestOverrides(),
     });
-    const detected = /** @type {import('./mcp-config.js').McpClientName[]} */ (
+    const detected = /** @type {import('./types.js').McpClientName[]} */ (
       setupStatus.mcpClients.filter((entry) => entry.detected).map((entry) => entry.key)
     );
     const configuredClients = new Set(
       setupStatus.mcpClients.filter((entry) => entry.configured).map((entry) => entry.key)
     );
     const configuredClientList =
-      /** @type {import('./mcp-config.js').McpClientName[]} */ ([...configuredClients]);
+      /** @type {import('./types.js').McpClientName[]} */ ([...configuredClients]);
     const items = MCP_CLIENT_NAMES.map((c) => ({
       value: c,
       label: `${c.padEnd(10)}  ${MCP_CLIENT_LABELS[c]}`,
@@ -284,12 +284,12 @@ if (command === 'install-mcp') {
             ? detected
             : [...MCP_CLIENT_NAMES];
     } else {
-      clients = /** @type {import('./mcp-config.js').McpClientName[]} */ (selected);
+      clients = /** @type {import('./types.js').McpClientName[]} */ (selected);
     }
 
     if (selected !== null) {
       const deselectedClients =
-        /** @type {import('./mcp-config.js').McpClientName[]} */ (
+        /** @type {import('./types.js').McpClientName[]} */ (
           configuredClientList.filter((clientName) => !clients.includes(clientName))
         );
       const removableClients = await findConfiguredMcpClients({
@@ -470,15 +470,20 @@ async function main() {
     }
 
     if (command === 'batch') {
-      await ensureClientConnection();
       const input = rest[0];
       if (!input) {
         throw new Error('Usage: batch \'[{"method":"...","params":{...}}, ...]\'');
       }
-      const calls = JSON.parse(input);
+      let calls;
+      try {
+        calls = JSON.parse(input);
+      } catch {
+        throw new Error('Invalid JSON syntax. Expected a JSON array of bridge calls.');
+      }
       if (!Array.isArray(calls)) {
         throw new Error('Batch input must be a JSON array.');
       }
+      await ensureClientConnection();
       const results = await Promise.all(
         calls.map(async (call) => {
           if (!call || typeof call !== 'object' || typeof call.method !== 'string') {
@@ -847,10 +852,13 @@ async function uninstallBrowserBridge() {
  */
 async function parseCallCommand(args) {
   const parsed = extractTabFlag(args);
-  const [first, second] = parsed.rest;
+  const [first, second, ...extra] = parsed.rest;
   if (!first) {
     throw new Error('Usage: call [--tab <tabId>] <method> [paramsJson]');
   }
+  if (extra.length > 0) {
+    throw new Error('Usage: call [--tab <tabId>] <method> [paramsJson]');
+  }
 
   if (first.includes('.')) {
     const method = /** @type {BridgeMethod} */ (first);

package/packages/agent-client/src/client.js

@@ -17,51 +17,13 @@ import {
 } from '../../native-host/src/config.js';
 import { restartBridgeDaemon } from '../../native-host/src/daemon-process.js';
 
-/** @typedef {import('../../native-host/src/config.js').BridgeTransport} BridgeTransport */
-
-/** @typedef {import('../../protocol/src/types.js').BridgeResponse} BridgeResponse */
-/** @typedef {import('../../protocol/src/types.js').BridgeMeta} BridgeMeta */
-/** @typedef {import('../../protocol/src/types.js').BridgeMethod} BridgeMethod */
-/**
- * @typedef {{
- *   extensionConnected?: boolean,
- *   supported_versions?: string[],
- *   daemon_supported_versions?: string[],
- *   deprecated_since?: string,
- *   migration_hint?: string
- * }} ProtocolHealthResult
- */
-
-/**
- * @typedef {{
- *   type: 'registered',
- *   role: 'agent' | 'extension',
- *   clientId?: string
- * } | {
- *   type: 'agent.response',
- *   response: BridgeResponse
- * }} ClientMessage
- */
-
-/**
- * @typedef {{
- *   resolve: (value: any) => void,
- *   reject: (error: Error) => void,
- *   timeoutId: NodeJS.Timeout
- * }} PendingRequest
- */
-
-/**
- * @typedef {{
- *   transport?: BridgeTransport,
- *   socketPath?: string,
- *   clientId?: string,
- *   defaultTimeoutMs?: number,
- *   autoReconnect?: boolean,
- *   restartDaemonOnVersionMismatch?: boolean,
- *   restartDaemonFn?: typeof restartBridgeDaemon,
- * }} BridgeClientOptions
- */
+/** @typedef {import('./types.js').BridgeMeta} BridgeMeta */
+/** @typedef {import('./types.js').BridgeMethod} BridgeMethod */
+/** @typedef {import('./types.js').BridgeResponse} BridgeResponse */
+/** @typedef {import('./types.js').BridgeClientOptions} BridgeClientOptions */
+/** @typedef {import('./types.js').ClientMessage} ClientMessage */
+/** @typedef {import('./types.js').PendingRequest} PendingRequest */
+/** @typedef {import('./types.js').ProtocolHealthResult} ProtocolHealthResult */
 
 /**
  * @param {string} left

package/packages/agent-client/src/command-registry.js

@@ -3,18 +3,8 @@
 import { BRIDGE_METHOD_REGISTRY, BRIDGE_METHODS } from '../../protocol/src/index.js';
 import { parseCommaList, parseIntArg, parsePropertyAssignments } from './cli-helpers.js';
 
-/** @typedef {import('../../protocol/src/types.js').BridgeMethod} BridgeMethod */
-
-/**
- * @typedef {{
- *   method: BridgeMethod,
- *   resolve?: boolean,
- *   printMethod?: string,
- *   usage: string,
- *   description: string,
- *   build: (r: string[], ref?: string) => Record<string, unknown>
- * }} ShortcutCommand
- */
+/** @typedef {import('./types.js').BridgeMethod} BridgeMethod */
+/** @typedef {import('./types.js').ShortcutCommand} ShortcutCommand */
 
 /**
  * @param {BridgeMethod} method
@@ -247,7 +237,7 @@ export const CLI_HELP_SECTIONS = Object.freeze([
   {
     title: 'Setup',
     lines: [
-      'bbx install [--browser chrome|edge|brave|chromium] [extension-id]  Install native messaging manifest',
+      'bbx install [--browser chrome|edge|brave|chromium|arc] [extension-id]  Install native messaging manifest',
       'bbx uninstall                                                      Remove native host manifests, Browser Bridge runtime files, and managed MCP/skill installs',
       'bbx install [--all] [--browser <name>] [extension-id]              Install native host manifest (--all for all supported browsers)',
       'bbx install-skill [targets|all] [--global] [--project <path>]      Install/update the managed Browser Bridge CLI skill',

package/packages/agent-client/src/detect.js

@@ -4,9 +4,9 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
-/** @typedef {import('./mcp-config.js').McpClientName} McpClientName */
-/** @typedef {import('./install.js').SupportedTarget} SupportedTarget */
-/** @typedef {() => boolean | Promise<boolean>} Detector */
+/** @typedef {import('./types.js').McpClientName} McpClientName */
+/** @typedef {import('./types.js').SupportedTarget} SupportedTarget */
+/** @typedef {import('./types.js').Detector} Detector */
 
 const home = os.homedir();
 const platform = process.platform;

package/packages/agent-client/src/install.js

@@ -41,9 +41,7 @@ const copilotBrowserBridgeNote = [
   '',
 ].join('\n');
 
-/**
- * @typedef {'codex' | 'claude' | 'cursor' | 'copilot' | 'opencode' | 'antigravity' | 'windsurf' | 'agents'} SupportedTarget
- */
+/** @typedef {import('./types.js').SupportedTarget} SupportedTarget */
 
 /** @type {SupportedTarget[]} */
 export const SUPPORTED_TARGETS = [...supportedTargets];
@@ -68,9 +66,7 @@ export function isSupportedTarget(value) {
   return supportedTargets.includes(/** @type {SupportedTarget} */ (value));
 }
 
-/**
- * @typedef {{targets: SupportedTarget[], projectPath: string, global: boolean}} InstallAgentOptions
- */
+/** @typedef {import('./types.js').InstallAgentOptions} InstallAgentOptions */
 
 /**
  * @param {string[]} args
@@ -202,7 +198,7 @@ async function rollbackInstalledSkillDirs(attempted) {
 /**
  * Write MCP config for the given clients.
  *
- * @param {import('./mcp-config.js').McpClientName[]} clients
+ * @param {import('./types.js').McpClientName[]} clients
  * @param {{
  *   global: boolean,
  *   projectPath: string,

package/packages/agent-client/src/mcp-config.js

@@ -5,9 +5,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-/**
- * @typedef {'codex' | 'claude' | 'cursor' | 'copilot' | 'opencode' | 'antigravity' | 'windsurf' | 'agents'} McpClientName
- */
+/** @typedef {import('./types.js').McpClientName} McpClientName */
 
 /** @type {McpClientName[]} */
 export const MCP_CLIENT_NAMES = [

package/packages/agent-client/src/runtime.js

@@ -12,39 +12,14 @@ import { resolveDefaultExtensionId } from '../../native-host/src/install-manifes
 import { methodNeedsTab } from './cli-helpers.js';
 import { BridgeClient } from './client.js';
 
-/** @typedef {import('../../protocol/src/types.js').BridgeMethod} BridgeMethod */
-/** @typedef {import('../../protocol/src/types.js').BridgeMeta} BridgeMeta */
-/** @typedef {import('../../protocol/src/types.js').BridgeRequestSource} BridgeRequestSource */
-/** @typedef {import('../../protocol/src/types.js').BridgeResponse} BridgeResponse */
+/** @typedef {import('./types.js').BridgeMethod} BridgeMethod */
+/** @typedef {import('./types.js').BridgeMeta} BridgeMeta */
+/** @typedef {import('./types.js').BridgeRequestSource} BridgeRequestSource */
+/** @typedef {import('./types.js').BridgeResponse} BridgeResponse */
 /** @typedef {import('../../native-host/src/config.js').SupportedBrowser} SupportedBrowser */
-
-/**
- * @typedef {{
- *   browser: string,
- *   manifestPath: string,
- *   installed: boolean
- * }} BrowserManifestStatus
- */
-
-/**
- * @typedef {{
- *   manifestInstalled: boolean,
- *   manifestPath: string,
- *   allowedOrigins: string[],
- *   defaultExtensionId: string | null,
- *   defaultExtensionIdSource: string,
- *   daemonReachable: boolean,
- *   extensionConnected: boolean,
- *   accessEnabled: boolean,
- *   enabledWindowId: number | null,
- *   routeTabId: number | null,
- *   routeReady: boolean,
- *   routeReason: string,
- *   issues: string[],
- *   nextSteps: string[],
- *   browserManifests: BrowserManifestStatus[]
- * }} DoctorReport
- */
+/** @typedef {import('./types.js').BrowserManifestStatus} BrowserManifestStatus */
+/** @typedef {import('./types.js').DoctorReport} DoctorReport */
+/** @typedef {import('./types.js').DoctorReportOptions} DoctorReportOptions */
 
 /**
  * @param {BridgeClient} client
@@ -178,15 +153,6 @@ export async function checkBrowserManifests() {
   );
 }
 
-/**
- * @typedef {{
- *   loadManifest?: () => Promise<{allowed_origins?: string[]} | null>,
- *   manifestPath?: string,
- *   defaultExtensionIdInfo?: { extensionId: string | null, source: string },
- *   bridgeClientRunner?: <T>(callback: (client: BridgeClient) => Promise<T>) => Promise<T>
- * }} DoctorReportOptions
- */
-
 /**
  * @param {DoctorReportOptions} [options={}]
  * @returns {Promise<DoctorReport>}

package/packages/agent-client/src/setup-status.js

@@ -21,8 +21,8 @@ import {
   SUPPORTED_TARGETS,
 } from './install.js';
 
-/** @typedef {import('./mcp-config.js').McpClientName} McpClientName */
-/** @typedef {import('./install.js').SupportedTarget} SupportedTarget */
+/** @typedef {import('./types.js').McpClientName} McpClientName */
+/** @typedef {import('./types.js').SupportedTarget} SupportedTarget */
 /** @typedef {import('../../protocol/src/types.js').SetupStatus} SetupStatus */
 /** @typedef {import('../../protocol/src/types.js').McpClientStatus} McpClientStatus */
 /** @typedef {import('../../protocol/src/types.js').SkillTargetStatus} SkillTargetStatus */
@@ -52,17 +52,7 @@ const SKILL_TARGET_LABELS = {
   agents: 'Generic agents',
 };
 
-/**
- * @typedef {{
- *   global?: boolean,
- *   cwd?: string,
- *   projectPath?: string,
- *   mcpDetectors?: Record<string, () => boolean | Promise<boolean>>,
- *   skillDetectors?: Record<string, () => boolean | Promise<boolean>>,
- *   access?: (targetPath: string) => Promise<void>,
- *   readFile?: (targetPath: string, encoding: BufferEncoding) => Promise<string>
- * }} SetupStatusOptions
- */
+/** @typedef {import('./types.js').SetupStatusOptions} SetupStatusOptions */
 
 /**
  * Return Browser Bridge MCP and skill installation status for supported clients.

package/packages/agent-client/src/types.ts

@@ -0,0 +1,131 @@
+import type { BridgeTransport } from '../../native-host/src/config.js';
+import type {
+  BridgeMeta,
+  BridgeMethod,
+  BridgeRequestSource,
+  BridgeResponse,
+} from '../../protocol/src/types.js';
+import type { restartBridgeDaemon } from '../../native-host/src/daemon-process.js';
+
+export type { BridgeMeta, BridgeMethod, BridgeRequestSource, BridgeResponse, BridgeTransport };
+
+export type McpClientName =
+  | 'codex'
+  | 'claude'
+  | 'cursor'
+  | 'copilot'
+  | 'opencode'
+  | 'antigravity'
+  | 'windsurf'
+  | 'agents';
+
+export type SupportedTarget = McpClientName;
+
+export type Detector = () => boolean | Promise<boolean>;
+
+export interface InstallAgentOptions {
+  targets: SupportedTarget[];
+  projectPath: string;
+  global: boolean;
+  [key: string]: unknown;
+}
+
+export interface SetupStatusOptions {
+  global?: boolean;
+  cwd?: string;
+  projectPath?: string;
+  mcpDetectors?: Record<string, Detector>;
+  skillDetectors?: Record<string, Detector>;
+  access?: (targetPath: string) => Promise<void>;
+  readFile?: (targetPath: string, encoding: BufferEncoding) => Promise<string>;
+}
+
+export interface ProtocolHealthResult {
+  extensionConnected?: boolean;
+  supported_versions?: string[];
+  daemon_supported_versions?: string[];
+  deprecated_since?: string;
+  migration_hint?: string;
+}
+
+export type ClientMessage =
+  | {
+      type: 'registered';
+      role: 'agent' | 'extension';
+      clientId?: string;
+    }
+  | {
+      type: 'agent.response';
+      response: BridgeResponse;
+    };
+
+export interface PendingRequest {
+  resolve: (value: any) => void;
+  reject: (error: Error) => void;
+  timeoutId: NodeJS.Timeout;
+}
+
+export interface BridgeClientOptions {
+  transport?: BridgeTransport;
+  socketPath?: string;
+  clientId?: string;
+  defaultTimeoutMs?: number;
+  autoReconnect?: boolean;
+  restartDaemonOnVersionMismatch?: boolean;
+  restartDaemonFn?: typeof restartBridgeDaemon;
+}
+
+export interface ShortcutCommand {
+  method: BridgeMethod;
+  resolve?: boolean;
+  printMethod?: string;
+  usage: string;
+  description: string;
+  build: (r: string[], ref?: string) => Record<string, unknown>;
+}
+
+export interface BrowserManifestStatus {
+  browser: string;
+  manifestPath: string;
+  installed: boolean;
+}
+
+export interface DoctorReport {
+  manifestInstalled: boolean;
+  manifestPath: string;
+  allowedOrigins: string[];
+  defaultExtensionId: string | null;
+  defaultExtensionIdSource: string;
+  daemonReachable: boolean;
+  extensionConnected: boolean;
+  accessEnabled: boolean;
+  enabledWindowId: number | null;
+  routeTabId: number | null;
+  routeReady: boolean;
+  routeReason: string;
+  issues: string[];
+  nextSteps: string[];
+  browserManifests: BrowserManifestStatus[];
+}
+
+export interface DoctorReportOptions {
+  loadManifest?: () => Promise<{ allowed_origins?: string[] } | null>;
+  manifestPath?: string;
+  defaultExtensionIdInfo?: { extensionId: string | null; source: string };
+  bridgeClientRunner?: <T>(
+    callback: (client: { request: BridgeClientRequest }) => Promise<T>
+  ) => Promise<T>;
+}
+
+export type BridgeClientRequest = (options: {
+  method: BridgeMethod;
+  tabId?: number | null;
+  params?: Record<string, unknown>;
+  meta?: BridgeMeta;
+  timeoutMs?: number;
+}) => Promise<BridgeResponse>;
+
+export interface ScreenshotResult {
+  image: string;
+  rect: Record<string, unknown>;
+}

package/packages/mcp-server/src/handlers-capture.js

@@ -40,22 +40,34 @@ export const CAPTURE_ACTIONS = {
     params: () => ({}),
   },
   cdp_box_model: {
-    ref: true,
+    ref: false,
     method: 'cdp.get_box_model',
-    params: (_, r) => ({ elementRef: r }),
+    params: (a) => ({ nodeId: a.nodeId }),
   },
   cdp_computed_styles: {
-    ref: true,
+    ref: false,
     method: 'cdp.get_computed_styles_for_node',
-    params: (_, r) => ({ elementRef: r }),
+    params: (a) => ({ nodeId: a.nodeId }),
   },
 };
 
+/** @param {Record<string, unknown>} args */
+function isCdpNodeCapture(args) {
+  return args.action === 'cdp_box_model' || args.action === 'cdp_computed_styles';
+}
+
 /**
- * @param {{ action: string, elementRef?: string, selector?: string, rect?: Record<string, unknown>, tabId?: number, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
+ * @param {{ action: string, elementRef?: string, selector?: string, rect?: Record<string, unknown>, nodeId?: number, tabId?: number, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
  * @returns {Promise<ToolResult>}
  */
 export async function handleCaptureTool(args) {
+  if (
+    isCdpNodeCapture(args) &&
+    (typeof args.nodeId !== 'number' || !Number.isFinite(args.nodeId))
+  ) {
+    return summarizeToolError('nodeId must be a finite number.');
+  }
+
   return dispatchToolAction(CAPTURE_ACTIONS, args, 'capture');
 }
 

package/packages/mcp-server/src/handlers-dom.js

@@ -148,6 +148,7 @@ export const PATCH_ACTIONS = {
       target: { elementRef: r },
       declarations: a.declarations,
       important: a.important,
+      patchId: a.patchId,
       verify: a.verify,
     }),
   },
@@ -160,16 +161,22 @@ export const PATCH_ACTIONS = {
       const opMap = {
         setAttribute: 'set_attribute',
         removeAttribute: 'remove_attribute',
-        addClass: 'toggle_class',
-        removeClass: 'toggle_class',
+        addClass: 'add_class',
+        removeClass: 'remove_class',
         setTextContent: 'set_text',
         setProperty: 'set_attribute',
       };
+      const normalizedOperation = opMap[operation] || operation;
+      const value =
+        normalizedOperation === 'add_class' || normalizedOperation === 'remove_class'
+          ? (a.value ?? a.name)
+          : a.value;
       return {
         target: { elementRef: r },
-        operation: opMap[operation] || operation,
-        value: a.value,
+        operation: normalizedOperation,
+        value,
         name: a.name,
+        patchId: a.patchId,
         verify: a.verify,
       };
     },

package/packages/mcp-server/src/handlers-page.js

@@ -8,7 +8,7 @@ import {
 import {
   annotateBridgeSummary,
   applyLimitBudgetPreset,
-  applyTextBudgetPreset,
+  applyPageTextBudgetPreset,
   bridgeMethodNeedsTab,
   callBridgeTool,
   createToolResult,
@@ -72,7 +72,7 @@ export const PAGE_ACTIONS = {
 export async function handlePageTool(args) {
   let normalizedArgs = args;
   if (args.action === 'text') {
-    normalizedArgs = applyTextBudgetPreset(args);
+    normalizedArgs = applyPageTextBudgetPreset(args);
   } else if (args.action === 'console') {
     normalizedArgs = applyLimitBudgetPreset(args, {
       quick: 10,

package/packages/mcp-server/src/handlers-utils.js

@@ -3,6 +3,7 @@
 import {
   bridgeMethodNeedsTab,
   DEFAULT_MAX_HTML_LENGTH,
+  DEFAULT_PAGE_TEXT_BUDGET,
   estimateJsonPayloadCost,
   getBudgetPreset,
   getErrorRecovery,
@@ -176,6 +177,27 @@ export function applyTextBudgetPreset(args) {
   });
 }
 
+/**
+ * @template {{ budgetPreset?: unknown, textBudget?: unknown }} T
+ * @param {T} args
+ * @returns {T}
+ */
+export function applyPageTextBudgetPreset(args) {
+  const presetName = getBudgetPresetName(args.budgetPreset);
+  if (!presetName) {
+    return args;
+  }
+  const textBudgetByPreset = {
+    quick: 2000,
+    normal: DEFAULT_PAGE_TEXT_BUDGET,
+    deep: DEFAULT_PAGE_TEXT_BUDGET * 2,
+  };
+  return /** @type {T} */ ({
+    ...args,
+    textBudget: args.textBudget ?? textBudgetByPreset[presetName],
+  });
+}
+
 /**
  * @template {{ budgetPreset?: unknown, limit?: unknown }} T
  * @param {T} args