cdp-toolkit 3.2.0 → 3.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1207,8 +1207,9 @@ const MAX_SCREENSHOT_SCALE = 8;
1207
1207
  /**
1208
1208
  * take_screenshot's `scale`, plus the second backend gate in this file (resolveDragMode is the
1209
1209
  * first, and this follows its shape exactly). scale needs Capability "screenshot.scale", which
1210
- * only the Chrome driver declares: Page.captureScreenshot takes a per-call clip.scale, while
1211
- * WebDriver BiDi's browsingContext.captureScreenshot has no scale parameter at all. Per ADR-001
1210
+ * Chrome declares (Page.captureScreenshot takes a per-call clip.scale) and Firefox >= 160 declares
1211
+ * too (a one-capture devicePixelRatio override; captureScreenshot itself has no scale parameter, and
1212
+ * an older Firefox's driver refuses with "unsupported" from requireFirefox). Per ADR-001
1212
1213
  * this is a PARAM-level gap, not a whole-tool one — take_screenshot stays in tools/list on Firefox
1213
1214
  * because every other argument works there, and asking for a scale on Firefox is a clear
1214
1215
  * validation error, never a silent 1x capture that would return an image the caller never asked
@@ -1221,7 +1222,7 @@ export function resolveScreenshotScale(scale: number | undefined, capabilities:
1221
1222
  }
1222
1223
  if (scale !== 1 && !capabilities.has("screenshot.scale")) {
1223
1224
  throw new SharedToolError(
1224
- "take_screenshot: 'scale' is not supported by this backend (WebDriver BiDi's browsingContext.captureScreenshot has no scale parameter). " +
1225
+ "take_screenshot: 'scale' is not supported by this backend (no per-capture scale primitive). " +
1225
1226
  `Call emulate with deviceScaleFactor:${scale} first and capture at scale 1, or use --browser chrome for a per-capture scale.`,
1226
1227
  );
1227
1228
  }
package/src/toolDocs.ts CHANGED
@@ -164,7 +164,7 @@ export const TOOL_DOCS: Record<string, ToolDoc> = {
164
164
  }
165
165
  },
166
166
  "dispatch_mouse": {
167
- "description": "Dispatches one raw mouse event (move/down/up) at absolute viewport coordinates — the toolkit's lowest-level input primitive. Compose move/down/move/up calls yourself for anything click/drag's fixed sequences can't reach: canvas drag-painting, marquee/rubber-band selection, custom hit-testing widgets. Chrome-only: absent from tools/list under the Firefox backend, never present-and-throwing.",
167
+ "description": "Dispatches one raw mouse event (move/down/up) at absolute viewport coordinates — the toolkit's lowest-level input primitive. Compose move/down/move/up calls yourself for anything click/drag's fixed sequences can't reach: canvas drag-painting, marquee/rubber-band selection, custom hit-testing widgets. Works on Chrome and on Firefox 160 or newer (WebDriver BiDi: a press held by 'down' in one call is released by 'up' in a later call); an older Firefox gets an unsupported error naming the version.",
168
168
  "params": {
169
169
  "lease": "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions.",
170
170
  "target": "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', or a 32-hex '<targetId>'. Prefix any of these with 'endpoint:<name>/' for a named CDP endpoint (Chrome only). Grammar: see server instructions.",
@@ -172,7 +172,7 @@ export const TOOL_DOCS: Record<string, ToolDoc> = {
172
172
  "x": "Viewport x-coordinate. Required every call — CDP has no 'current pointer position' to default from.",
173
173
  "y": "Viewport y-coordinate. Required every call.",
174
174
  "button": "Mouse button: 'left' (default), 'right', or 'middle'.",
175
- "clickCount": "Click-run length for a 'down' or 'up' event (2 = second half of a double-click, 3 = triple-click). Ignored for 'move'; defaults to 1.",
175
+ "clickCount": "Click-run length for a 'down' or 'up' event (2 = second half of a double-click, 3 = triple-click). Ignored for 'move'; defaults to 1. Ignored on Firefox (click counts follow native timing).",
176
176
  "modifiers": "Modifier keys held for this one event, e.g. ['Shift']."
177
177
  }
178
178
  },
@@ -197,7 +197,7 @@ export const TOOL_DOCS: Record<string, ToolDoc> = {
197
197
  }
198
198
  },
199
199
  "wait_for_download": {
200
- "description": "Wait for a file download to finish and return it as a real file on disk: {path,suggestedFilename,bytes,url,target}, written under the artifact dir's downloads/. ORDERING RULE, not optional: capture must be ARMED BEFORE the click that starts the download — call wait_for_download{arm:true} first (returns {armed:true,downloadPath,pending}), then click, then call again to collect the file. The download-behavior override is per-connection state Chrome REVERTS the moment the arming client disconnects, and an unarmed headless Chrome denies the download outright, so one triggered before arming is lost. SIDE EFFECT, browser-global: arming redirects EVERY download in this browser (all tabs, all origins) into the toolkit's downloads dir until this server exits — they no longer land in the user's normal Downloads folder. The arm lives on a connection this server holds open (an MCP-server capability): under the one-shot CLI the connection dies with the process and nothing is captured. Chrome-only (capability 'browser.downloads'): absent from tools/list under Firefox.",
200
+ "description": "Wait for a file download to finish and return it as a real file on disk: {path,suggestedFilename,bytes,url,target}, written under the artifact dir's downloads/. ORDERING RULE, not optional: capture must be ARMED BEFORE the click that starts the download — call wait_for_download{arm:true} first (returns {armed:true,downloadPath,pending}), then click, then call again to collect the file. The download-behavior override is per-connection state Chrome REVERTS the moment the arming client disconnects, and an unarmed headless Chrome denies the download outright, so one triggered before arming is lost. SIDE EFFECT, browser-global: arming redirects EVERY download in this browser (all tabs, all origins) into the toolkit's downloads dir until this server exits — they no longer land in the user's normal Downloads folder. The arm lives on a connection this server holds open (an MCP-server capability): under the one-shot CLI the connection dies with the process and nothing is captured. Capability 'browser.downloads': Chrome, and Firefox 160+ (an older Firefox is refused as unsupported). FIREFOX DIFFERS: every call arms, and a collecting call (no arm:true) RESTORES Firefox's normal download behavior when it returns or times out, so arm again before every later download.",
201
201
  "params": {
202
202
  "lease": "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions.",
203
203
  "target": "Names the tab for the lease check and the echoed target — a download is browser-scoped, so this does not pick which download is returned. Grammar: server instructions.",
@@ -206,7 +206,7 @@ export const TOOL_DOCS: Record<string, ToolDoc> = {
206
206
  }
207
207
  },
208
208
  "grant_permissions": {
209
- "description": "Grant browser permissions for an origin up front, so a page asking for geolocation / notifications / clipboard gets an answer instead of a prompt no agent can click. 'permissions' takes CDP PermissionType values ('geolocation','notifications','clipboardReadWrite','camera',...); an unknown name is refused by Chrome, quoting the bad value. Returns {granted,origin,target}, or {reset:true,target} for a reset-only call. Grants are keyed by ORIGIN, not by tab: every tab on that origin is affected, including ones opened later. reset:true clears this server's previous grants first (or instead, when no permissions are given) — CDP's reset is not origin-scoped, so it clears them for every origin at once. The grant lives on a connection this server holds open and Chrome DISCARDS IT when that connection closes: an MCP-server capability, so under the one-shot CLI the grant dies with the process. Chrome-only (capability 'browser.permissions'): absent from tools/list under Firefox, never present-and-throwing.",
209
+ "description": "Grant browser permissions for an origin up front, so a page asking for geolocation / notifications / clipboard gets an answer instead of a prompt no agent can click. 'permissions' takes CDP PermissionType values ('geolocation','notifications','clipboardReadWrite','camera',...); an unknown name is refused by Chrome, quoting the bad value. Returns {granted,origin,target}, or {reset:true,target} for a reset-only call. Grants are keyed by ORIGIN, not by tab: every tab on that origin is affected, including ones opened later. reset:true clears this server's previous grants first (or instead, when no permissions are given) — CDP's reset is not origin-scoped, so it clears them for every origin at once. The grant lives on a connection this server holds open and Chrome DISCARDS IT when that connection closes: an MCP-server capability, so under the one-shot CLI the grant dies with the process. Capability 'browser.permissions': Chrome, and Firefox 160+ (an older Firefox is refused as unsupported). FIREFOX DIFFERS: only geolocation, notifications, audioCapture, videoCapture, durableStorage, midi, midiSysex, wakeLockScreen map to a Firefox permission (any other name, e.g. clipboardReadWrite, is refused as unsupported); Firefox stores grants in the profile, so this server undoes them on reset:true and at shutdown (back to the state the page reported before the grant, or 'prompt' for another origin).",
210
210
  "params": {
211
211
  "lease": "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions.",
212
212
  "target": "Also the origin source when 'origin' is omitted. Grammar: server instructions.",
@@ -270,7 +270,7 @@ export const TOOL_DOCS: Record<string, ToolDoc> = {
270
270
  "format": "Image format, default png. quality applies only to jpeg.",
271
271
  "quality": "JPEG quality 0-100, default 80; ignored for png.",
272
272
  "fullPage": "Capture the full scrollable height (via Page.getLayoutMetrics), not just the viewport.",
273
- "scale": "Output-pixel multiplier for this capture only (0<scale<=8, default 1): output px = ceil(css px x scale x devicePixelRatio); the page is never told anything changed. Chrome only (screenshot.scale) — Firefox BiDi has no scale param, use emulate{deviceScaleFactor} then scale:1. A projection over 16384 device px/side is refused up front, naming the largest scale that fits.",
273
+ "scale": "Output-pixel multiplier for this capture only (0<scale<=8, default 1): output px = ceil(css px x scale x devicePixelRatio); the page is never told anything changed. Needs capability screenshot.scale: Chrome, and Firefox 160 or newer (an older Firefox: emulate{deviceScaleFactor} then scale:1). A projection over 16384 device px/side is refused up front, naming the largest scale that fits.",
274
274
  "renderWidth": "Emulates this viewport width (CSS px, 1-16384) for one capture, then restores it. Required with renderHeight. Unlike scale, this changes what the page believes (media queries re-flow) — e.g. capture a responsive page at 1920x1080 from a differently-sized tab. Restore only works for an override this toolkit itself set; check result.renderRestored (false = still emulated, fix via emulate). Works on both backends (capability screenshot.renderSize).",
275
275
  "renderHeight": "Emulates this viewport height (CSS px, 1-16384) for one capture. Required with renderWidth — a viewport is two numbers. A narrow renderWidth often reflows pages TALLER, which is the usual way a render-size capture trips the 16384px encode limit.",
276
276
  "tile": "Whether to allow vertical-band stitching: omitted=AUTO (band only if a single shot wouldn't fit), false=never band (refuse instead), true=always band (Chrome-only capability). Banded output is PNG-only, can't returnBase64, and only bands on HEIGHT (oversized WIDTH is refused, not split). Bands are a faithful crop, but lazy/virtualized content the real viewport never scrolled to renders blank.",
@@ -1,7 +1,12 @@
1
1
  /**
2
2
  * dispatch-mouse.ts: `dispatch_mouse` over raw CDP, the toolkit's raw mouse-event primitive.
3
3
  *
4
- * WHY THIS IS CHROME-ONLY (capability "input.raw", declared in ../driver.ts /
4
+ * UPDATE: Firefox 160+ now serves dispatch_mouse too (bidi-tools.ts's dispatchMouse over
5
+ * PageDriver.dispatchMouse; same schema and validator from this file). The text below is why THIS
6
+ * module, the Chrome path, stays a raw-CDP tool; its "Chrome-only" and "absent under firefox"
7
+ * statements describe the state before Firefox 160 was measured.
8
+ *
9
+ * WHY THIS IS A STANDALONE CHROME MODULE (capability "input.raw", declared in ../driver.ts /
5
10
  * ../cdp/driver.ts), NOT a PageDriver method
6
11
  * ============================================================================
7
12
  * Every other interaction (click/hover/drag/scroll) is a Driver-neutral, multi-event SEQUENCE:
@@ -2,16 +2,15 @@
2
2
  * downloads.ts: `wait_for_download` — block until a file download finishes, then hand back a real
3
3
  * path on disk with the page's own filename (1.8.0 Track P3).
4
4
  *
5
- * WHY THIS IS CHROME-ONLY (capability "browser.downloads"), NOT a PageDriver method
6
- * ================================================================================
5
+ * WHY THIS IS RAW CDP (capability "browser.downloads"), NOT a PageDriver method
6
+ * ============================================================================
7
7
  * A download is browser-scoped, not page-scoped: Browser.setDownloadBehavior, Browser.downloadWillBegin
8
8
  * and Browser.downloadProgress all live on the CDP browser endpoint, and the download a caller
9
9
  * cares about may be started by a click in one tab and finish while another is focused. There is no
10
10
  * page handle to hang it off, so it stays out of the Driver interface entirely, exactly like
11
- * dispatch-mouse.ts and screencast.ts. WebDriver BiDi has browsingContext.downloadWillBegin and
12
- * downloadEnd events but NO command to redirect a download to a directory of our choosing, so
13
- * Firefox cannot deliver the "here is the file" half of this tool at all: per ADR-001 it is absent
14
- * from tools/list under --browser firefox rather than present and throwing.
11
+ * dispatch-mouse.ts and screencast.ts. This is the CHROME implementation. Firefox 160 added
12
+ * BiDi's browser.setDownloadBehavior, so the Firefox backend has its own implementation in
13
+ * src/bidi-browser-tools.ts, reusing this file's validator, safeFilename and nextFreeName.
15
14
  *
16
15
  * THE ORDERING RULE, and why it is a rule rather than a wart
17
16
  * ---------------------------------------------------------
@@ -3,14 +3,14 @@
3
3
  * that asks for geolocation / notifications / clipboard gets a decision instead of a modal an
4
4
  * agent cannot click (1.8.0 Track P3).
5
5
  *
6
- * WHY THIS IS CHROME-ONLY (capability "browser.permissions"), NOT a PageDriver method
7
- * ==================================================================================
6
+ * WHY THIS IS RAW CDP (capability "browser.permissions"), NOT a PageDriver method
7
+ * ==============================================================================
8
8
  * Browser.grantPermissions and Browser.resetPermissions are browser-endpoint commands keyed by
9
9
  * ORIGIN, not by tab: a grant made "for" one tab applies to every tab on that origin, including
10
10
  * ones opened later. There is no page-scoped concept to put on the Driver interface, so this stays
11
- * a raw-CDP module like dispatch-mouse.ts. WebDriver BiDi's permission handling lives in an
12
- * optional module this driver does not negotiate, so under Firefox the tool is absent from
13
- * tools/list per ADR-001 rather than present and throwing.
11
+ * a raw-CDP module like dispatch-mouse.ts. This is the CHROME implementation; the Firefox 160+ one
12
+ * (BiDi permissions.setPermission, with a Chrome-name -> W3C-descriptor map and its asymmetries
13
+ * documented) is src/bidi-browser-tools.ts, reusing this file's validator and originOf.
14
14
  *
15
15
  * THE STANDING-CONNECTION REQUIREMENT (measured, not assumed)
16
16
  * ----------------------------------------------------------
package/src/version.ts CHANGED
@@ -6,4 +6,4 @@
6
6
  * ready line; keeping it in its own module means a release bump touches one
7
7
  * line here plus package.json, not a const buried in the server.
8
8
  */
9
- export const VERSION = "3.2.0";
9
+ export const VERSION = "3.3.0";