cdp-toolkit 3.1.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.
@@ -1,20 +1,23 @@
1
1
  /**
2
2
  * The complete Firefox tool registry: the 23 tools shared with Chrome (src/shared-tools.ts), the
3
3
  * 7 Firefox-only console/network/mock tools (src/bidi-tools.ts), the 3 lease tools
4
- * (src/leases-tools.ts), and extract_page (src/tools/extract.ts), which is backend-neutral by
5
- * construction (its page work runs entirely through Driver.evaluate). This is what src/neutral.ts
6
- * used to be; it now composes four files instead of reimplementing everything in one.
4
+ * (src/leases-tools.ts), the 2 browser-scoped tools wait_for_download / grant_permissions
5
+ * (src/bidi-browser-tools.ts, Firefox 160+), and extract_page (src/tools/extract.ts), which is
6
+ * backend-neutral by construction (its page work runs entirely through Driver.evaluate). This is
7
+ * what src/neutral.ts used to be; it now composes five files instead of reimplementing everything in one.
7
8
  */
8
9
  import type { BrowserDriver } from "./driver.ts";
9
10
  import type { ToolName } from "./index.ts";
10
11
  import { SHARED_TOOLS } from "./shared-tools.ts";
11
12
  import { BIDI_ONLY_TOOLS } from "./bidi-tools.ts";
12
13
  import { LEASE_TOOLS } from "./leases-tools.ts";
14
+ import { BIDI_BROWSER_TOOLS } from "./bidi-browser-tools.ts";
13
15
  import { extractPage } from "./tools/extract.ts";
14
16
 
15
17
  export const FIREFOX_TOOLS: Partial<Record<ToolName, (driver: BrowserDriver, args: never) => Promise<unknown>>> = {
16
18
  ...SHARED_TOOLS,
17
19
  ...BIDI_ONLY_TOOLS,
18
20
  ...LEASE_TOOLS,
21
+ ...BIDI_BROWSER_TOOLS,
19
22
  extract_page: extractPage,
20
23
  };
package/src/manifest.ts CHANGED
@@ -622,7 +622,7 @@ export const MANIFEST: ToolSpec[] = [
622
622
  },
623
623
  {
624
624
  "name": "dispatch_mouse",
625
- "description": "Dispatch one raw mouse event at viewport coordinates; Chrome-only.",
625
+ "description": "Dispatch one raw mouse event at viewport coordinates; Firefox needs 160 or newer.",
626
626
  "inputSchema": {
627
627
  "type": "object",
628
628
  "properties": {
@@ -779,7 +779,7 @@ export const MANIFEST: ToolSpec[] = [
779
779
  },
780
780
  {
781
781
  "name": "grant_permissions",
782
- "description": "Grant or reset browser permissions; permissions are origin-scoped and Chrome-only.",
782
+ "description": "Grant or reset browser permissions; permissions are origin-scoped (Chrome, Firefox 160+).",
783
783
  "inputSchema": {
784
784
  "type": "object",
785
785
  "properties": {
package/src/policy.ts CHANGED
@@ -95,8 +95,8 @@ export const MUTATING_TOOLS: ReadonlySet<string> = new Set([
95
95
  "dispatch_mouse",
96
96
  "focus_emulation", // Emulation.setFocusEmulationEnabled
97
97
  "click_focus_gated",
98
- "wait_for_download", // borderline: Browser.setDownloadBehavior changes browser state
99
- "grant_permissions", // Browser.grantPermissions
98
+ "wait_for_download", // borderline: Browser.setDownloadBehavior / BiDi browser.setDownloadBehavior changes browser state
99
+ "grant_permissions", // Browser.grantPermissions / BiDi permissions.setPermission
100
100
  // leases: claim installs an activity beacon in the page and writes a lease; release can close a tab
101
101
  "claim_page",
102
102
  "release_page",
@@ -50,6 +50,7 @@ import { newTrackedPage, originIndex, resolveLiveLabel, type PageOrigin } from "
50
50
  import { isWorkerSelector, WORKER_SELECTOR_PAGE_ONLY_MESSAGE, WORKER_SELECTOR_UNSUPPORTED_MESSAGE } from "./workers.ts";
51
51
  import { FRAME_SELECTOR_PAGE_ONLY_MESSAGE, FRAME_SELECTOR_UNSUPPORTED_MESSAGE, isFrameSelector } from "./frames.ts";
52
52
  import { reapAllowed, reapStaleAgentTabs, type ReapedTab } from "./reap.ts";
53
+ import { ACCNAME_HELPERS_SOURCE, MAX_NAME_LENGTH } from "./bidi/snapshot.ts";
53
54
  import { allEndpoints, currentEndpoint, isDefaultEndpoint, withEndpointScope } from "./endpoints.ts";
54
55
 
55
56
  const ARTIFACT_DIR = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
@@ -908,13 +909,66 @@ export async function takeSnapshot(
908
909
 
909
910
  /* ------------------------------ interaction (8) ------------------------------ */
910
911
 
912
+ /**
913
+ * In-page source that names the element `this` is, as a snapshot-style `role "name"` string
914
+ * (`button "Save"`, `textbox "Email"`). It reuses the snapshot walker's role/accname heuristics;
915
+ * an element with no role falls back to its tag, and one with no accessible name falls back to
916
+ * its own text, so a click on a bare `<div>` still says what it hit. Exported for the tests.
917
+ */
918
+ export function describeElementSource(): string {
919
+ return `function() {
920
+ var MAX_NAME_LENGTH = ${MAX_NAME_LENGTH};
921
+ ${ACCNAME_HELPERS_SOURCE}
922
+ var el = this;
923
+ if (!el || el.nodeType !== 1) return null;
924
+ var role = implicitRole(el);
925
+ var name = accessibleName(el, !!CONTENT_NAMED_ROLES[role]);
926
+ if (!name) name = truncate(el.innerText || el.textContent || "");
927
+ return (role || el.tagName.toLowerCase()) + (name ? " " + JSON.stringify(name) : "");
928
+ }`;
929
+ }
930
+
931
+ /** How long describing may delay the action it precedes before it is given up on. */
932
+ const DESCRIBE_TIMEOUT_MS = 2_000;
933
+
934
+ /**
935
+ * Best-effort `role "name"` for the element an action is about to touch, read BEFORE the action
936
+ * (a click can navigate or unmount its node; fill should report the label, not the new value).
937
+ * Never throws and never blocks past DESCRIBE_TIMEOUT_MS: a stale or unresolvable locator is left
938
+ * for the action itself to fail on with its usual error, and the result just omits `element`.
939
+ */
940
+ export async function describeElement(page: PageDriver, loc: ElementLocator): Promise<string | undefined> {
941
+ let timer: ReturnType<typeof setTimeout> | undefined;
942
+ try {
943
+ const timeout = new Promise<undefined>((r) => { timer = setTimeout(() => r(undefined), DESCRIBE_TIMEOUT_MS); });
944
+ const desc = await Promise.race([page.callOnElement(loc, describeElementSource()), timeout]);
945
+ return typeof desc === "string" && desc.length > 0 ? desc : undefined;
946
+ } catch {
947
+ return undefined;
948
+ } finally {
949
+ clearTimeout(timer);
950
+ }
951
+ }
952
+
953
+ /** A drag destination that names an element, as opposed to a viewport point or an offset. */
954
+ function isElementLocator(d: DragDestination): d is ElementLocator {
955
+ return !("x" in d) && !("dx" in d);
956
+ }
957
+
958
+ /** `{ element }` when there is a description, `{}` otherwise, for spreading into a result. */
959
+ function elementField(element: string | undefined): { element?: string } {
960
+ return element === undefined ? {} : { element };
961
+ }
962
+
911
963
  export async function click(
912
964
  driver: BrowserDriver,
913
965
  args: { target?: TargetSelector; uid?: DriverUid; selector?: string; button?: "left" | "right" | "middle"; clickCount?: number; modifiers?: string[] },
914
- ): Promise<{ clicked: true; x: number; y: number }> {
966
+ ): Promise<{ clicked: true; element?: string; x: number; y: number }> {
967
+ const loc = locatorOf(args);
915
968
  return withPage(driver, args.target, async (page) => {
916
- const { x, y } = await page.click(locatorOf(args), { button: args.button ?? "left", clickCount: args.clickCount ?? 1, modifiers: args.modifiers });
917
- return { clicked: true, x, y };
969
+ const element = await describeElement(page, loc);
970
+ const { x, y } = await page.click(loc, { button: args.button ?? "left", clickCount: args.clickCount ?? 1, modifiers: args.modifiers });
971
+ return { clicked: true, ...elementField(element), x, y };
918
972
  });
919
973
  }
920
974
 
@@ -959,10 +1013,12 @@ export async function scroll(
959
1013
  });
960
1014
  }
961
1015
 
962
- export async function hover(driver: BrowserDriver, args: { target?: TargetSelector; uid?: DriverUid; selector?: string }): Promise<{ hovered: true; x: number; y: number }> {
1016
+ export async function hover(driver: BrowserDriver, args: { target?: TargetSelector; uid?: DriverUid; selector?: string }): Promise<{ hovered: true; element?: string; x: number; y: number }> {
1017
+ const loc = locatorOf(args);
963
1018
  return withPage(driver, args.target, async (page) => {
964
- const { x, y } = await page.hover(locatorOf(args));
965
- return { hovered: true, x, y };
1019
+ const element = await describeElement(page, loc);
1020
+ const { x, y } = await page.hover(loc);
1021
+ return { hovered: true, ...elementField(element), x, y };
966
1022
  });
967
1023
  }
968
1024
 
@@ -1057,47 +1113,60 @@ export async function drag(
1057
1113
  mode?: "mouse" | "html5";
1058
1114
  steps?: number;
1059
1115
  },
1060
- ): Promise<{ dragged: true; mode: "mouse" | "html5"; steps: number; from: { x: number; y: number }; to: { x: number; y: number } }> {
1116
+ ): Promise<{ dragged: true; element?: string; target_element?: string; mode: "mouse" | "html5"; steps: number; from: { x: number; y: number }; to: { x: number; y: number } }> {
1061
1117
  if (!args.from) throw new SharedToolError("drag requires { from }");
1062
1118
  const destination = resolveDragDestination(args);
1063
1119
  const steps = resolveDragSteps(args.steps);
1064
1120
  // Capability check BEFORE withPage: an unsupported mode must not claim a lease or open a socket.
1065
1121
  const mode = resolveDragMode(args.mode, driver.capabilities);
1066
1122
  return withPage(driver, args.target, async (page) => {
1067
- const { from, to } = await page.drag(locatorOf(args.from), destination, { mode, steps });
1068
- return { dragged: true, mode, steps, from, to };
1123
+ const fromLoc = locatorOf(args.from);
1124
+ const element = await describeElement(page, fromLoc);
1125
+ const targetElement = isElementLocator(destination) ? await describeElement(page, destination) : undefined;
1126
+ const { from, to } = await page.drag(fromLoc, destination, { mode, steps });
1127
+ return {
1128
+ dragged: true, ...elementField(element), ...(targetElement === undefined ? {} : { target_element: targetElement }),
1129
+ mode, steps, from, to,
1130
+ };
1069
1131
  });
1070
1132
  }
1071
1133
 
1072
- export async function fill(driver: BrowserDriver, args: { target?: TargetSelector; uid?: DriverUid; selector?: string; value: string }): Promise<{ filled: true; value: string }> {
1134
+ export async function fill(driver: BrowserDriver, args: { target?: TargetSelector; uid?: DriverUid; selector?: string; value: string }): Promise<{ filled: true; element?: string; value: string }> {
1073
1135
  if (typeof args.value !== "string") throw new SharedToolError("fill requires a string { value }");
1136
+ const loc = locatorOf(args);
1074
1137
  return withPage(driver, args.target, async (page) => {
1075
- await page.setValue(locatorOf(args), args.value);
1076
- return { filled: true, value: args.value };
1138
+ const element = await describeElement(page, loc);
1139
+ await page.setValue(loc, args.value);
1140
+ return { filled: true, ...elementField(element), value: args.value };
1077
1141
  });
1078
1142
  }
1079
1143
 
1080
1144
  export async function fillForm(
1081
1145
  driver: BrowserDriver,
1082
1146
  args: { target?: TargetSelector; fields: Array<{ uid?: DriverUid; selector?: string; value: string }> },
1083
- ): Promise<{ filled: number; fields: number }> {
1147
+ ): Promise<{ filled: number; fields: number; elements: Array<string | null> }> {
1084
1148
  if (!Array.isArray(args.fields) || args.fields.length === 0) throw new SharedToolError("fill_form requires a non-empty { fields } array");
1085
1149
  return withPage(driver, args.target, async (page) => {
1086
1150
  let filled = 0;
1151
+ const elements: Array<string | null> = [];
1087
1152
  for (const f of args.fields) {
1088
1153
  if (typeof f.value !== "string") throw new SharedToolError("each fill_form field requires a string value");
1089
- await page.setValue(locatorOf(f), f.value);
1154
+ const loc = locatorOf(f);
1155
+ elements.push((await describeElement(page, loc)) ?? null);
1156
+ await page.setValue(loc, f.value);
1090
1157
  filled++;
1091
1158
  }
1092
- return { filled, fields: args.fields.length };
1159
+ return { filled, fields: args.fields.length, elements };
1093
1160
  });
1094
1161
  }
1095
1162
 
1096
- export async function typeText(driver: BrowserDriver, args: { target?: TargetSelector; uid?: DriverUid; selector?: string; text: string }): Promise<{ typed: true; text: string }> {
1163
+ export async function typeText(driver: BrowserDriver, args: { target?: TargetSelector; uid?: DriverUid; selector?: string; text: string }): Promise<{ typed: true; element?: string; text: string }> {
1097
1164
  if (typeof args.text !== "string") throw new SharedToolError("type_text requires a string { text }");
1165
+ const loc = locatorOf(args);
1098
1166
  return withPage(driver, args.target, async (page) => {
1099
- await page.typeText(locatorOf(args), args.text);
1100
- return { typed: true, text: args.text };
1167
+ const element = await describeElement(page, loc);
1168
+ await page.typeText(loc, args.text);
1169
+ return { typed: true, ...elementField(element), text: args.text };
1101
1170
  });
1102
1171
  }
1103
1172
 
@@ -1110,14 +1179,16 @@ export async function pressKey(driver: BrowserDriver, args: { target?: TargetSel
1110
1179
  });
1111
1180
  }
1112
1181
 
1113
- export async function uploadFile(driver: BrowserDriver, args: { target?: TargetSelector; uid?: DriverUid; selector?: string; files: string | string[] }): Promise<{ uploaded: string[] }> {
1182
+ export async function uploadFile(driver: BrowserDriver, args: { target?: TargetSelector; uid?: DriverUid; selector?: string; files: string | string[] }): Promise<{ uploaded: string[]; element?: string }> {
1114
1183
  const files = Array.isArray(args.files) ? args.files : [args.files];
1115
1184
  if (!files.length || files.some((f) => typeof f !== "string" || !f.length)) {
1116
1185
  throw new SharedToolError("upload_file requires { files } as a non-empty path or array of paths");
1117
1186
  }
1118
1187
  return withPage(driver, args.target, async (page) => {
1119
- await page.setFiles(locatorOf(args), files);
1120
- return { uploaded: files };
1188
+ const loc = locatorOf(args);
1189
+ const element = await describeElement(page, loc);
1190
+ await page.setFiles(loc, files);
1191
+ return { uploaded: files, ...elementField(element) };
1121
1192
  });
1122
1193
  }
1123
1194
 
@@ -1136,8 +1207,9 @@ const MAX_SCREENSHOT_SCALE = 8;
1136
1207
  /**
1137
1208
  * take_screenshot's `scale`, plus the second backend gate in this file (resolveDragMode is the
1138
1209
  * first, and this follows its shape exactly). scale needs Capability "screenshot.scale", which
1139
- * only the Chrome driver declares: Page.captureScreenshot takes a per-call clip.scale, while
1140
- * 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
1141
1213
  * this is a PARAM-level gap, not a whole-tool one — take_screenshot stays in tools/list on Firefox
1142
1214
  * because every other argument works there, and asking for a scale on Firefox is a clear
1143
1215
  * validation error, never a silent 1x capture that would return an image the caller never asked
@@ -1150,7 +1222,7 @@ export function resolveScreenshotScale(scale: number | undefined, capabilities:
1150
1222
  }
1151
1223
  if (scale !== 1 && !capabilities.has("screenshot.scale")) {
1152
1224
  throw new SharedToolError(
1153
- "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). " +
1154
1226
  `Call emulate with deviceScaleFactor:${scale} first and capture at scale 1, or use --browser chrome for a per-capture scale.`,
1155
1227
  );
1156
1228
  }
package/src/toolDocs.ts CHANGED
@@ -118,7 +118,7 @@ export const TOOL_DOCS: Record<string, ToolDoc> = {
118
118
  }
119
119
  },
120
120
  "click": {
121
- "description": "Click an element via a synthetic mouse press/release at its scrolled-into-view center. Give exactly one of uid or selector. modifiers (Alt/Control/Meta/Shift) throws on the Firefox backend — use --browser chrome for a modifier-click. clickCount:3 triple-clicks (selects a line/paragraph in most editors).",
121
+ "description": "Click an element via a synthetic mouse press/release at its scrolled-into-view center. Give exactly one of uid or selector. modifiers (Alt/Control/Meta/Shift) throws on the Firefox backend — use --browser chrome for a modifier-click. clickCount:3 triple-clicks (selects a line/paragraph in most editors). Returns {clicked,element,x,y}; element names what was hit, snapshot-style (button \"Save\"), read before the click and omitted if it cannot be read.",
122
122
  "params": {
123
123
  "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.",
124
124
  "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.",
@@ -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.",
@@ -216,7 +216,7 @@ export const TOOL_DOCS: Record<string, ToolDoc> = {
216
216
  }
217
217
  },
218
218
  "fill": {
219
- "description": "Fills an element by focusing it, clearing existing content, then inserting value via Input.insertText (atomic paste-like commit, not per-character keystrokes — won't fire per-keypress handlers). Give exactly one of uid or selector.",
219
+ "description": "Fills an element by focusing it, clearing existing content, then inserting value via Input.insertText (atomic paste-like commit, not per-character keystrokes — won't fire per-keypress handlers). Give exactly one of uid or selector. Returns {filled,element,value}; element names the field (textbox \"Email\").",
220
220
  "params": {
221
221
  "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.",
222
222
  "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.",
@@ -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
  * ---------------------------------------------------------
@@ -15,7 +15,7 @@
15
15
  * `CdpError` carrying the exception/description text.
16
16
  */
17
17
  import { CdpError, withPage } from "../client.ts";
18
- import type { CdpConnection } from "../client.ts";
18
+ import type { PageConnection } from "../client.ts";
19
19
  import type { TargetSelector } from "../types.ts";
20
20
 
21
21
  /** A CDP RemoteObject as returned by Runtime.evaluate / Runtime.callFunctionOn. */
@@ -78,7 +78,7 @@ function unwrap(obj: RemoteObject): unknown {
78
78
  return obj.description ?? null;
79
79
  }
80
80
 
81
- async function evaluateExpression(conn: CdpConnection, expression: string, awaitPromise: boolean): Promise<unknown> {
81
+ async function evaluateExpression(conn: PageConnection, expression: string, awaitPromise: boolean): Promise<unknown> {
82
82
  const res = await conn.send<EvalResponse>("Runtime.evaluate", {
83
83
  expression,
84
84
  returnByValue: true,
@@ -94,7 +94,7 @@ async function evaluateExpression(conn: CdpConnection, expression: string, await
94
94
  }
95
95
 
96
96
  async function evaluateFunction(
97
- conn: CdpConnection,
97
+ conn: PageConnection,
98
98
  expression: string,
99
99
  awaitPromise: boolean,
100
100
  args: unknown[],
@@ -12,7 +12,7 @@
12
12
  * on a fixed interval until the text appears or the timeout elapses.
13
13
  */
14
14
  import { CdpError, withPage } from "../client.ts";
15
- import type { CdpConnection } from "../client.ts";
15
+ import type { PageConnection } from "../client.ts";
16
16
  import type { Target, TargetSelector } from "../types.ts";
17
17
 
18
18
  export interface NavigatePageArgs {
@@ -65,7 +65,7 @@ export async function navigatePage(args: NavigatePageArgs): Promise<NavigatePage
65
65
 
66
66
  return withPage(
67
67
  args.target,
68
- async (conn: CdpConnection): Promise<NavigatePageResult> => {
68
+ async (conn: PageConnection): Promise<NavigatePageResult> => {
69
69
  await conn.send("Page.enable");
70
70
 
71
71
  // Subscribe to the load milestone BEFORE acting so a fast page that loads
@@ -156,7 +156,7 @@ export async function waitForText(args: WaitForArgs): Promise<WaitForResult> {
156
156
 
157
157
  return withPage(
158
158
  args.target,
159
- async (conn: CdpConnection, _target: Target): Promise<WaitForResult> => {
159
+ async (conn: PageConnection, _target: Target): Promise<WaitForResult> => {
160
160
  await conn.send("Runtime.enable");
161
161
  const expr = `(() => { const b = document.body; return !!b && typeof b.innerText === 'string' && b.innerText.includes(${JSON.stringify(args.text)}); })()`;
162
162
 
@@ -11,7 +11,7 @@
11
11
  * CDP connection per target; integration-tested in test/mock-smoke.ts.
12
12
  */
13
13
  import { CdpError, openPage, resolveTarget } from "../client.ts";
14
- import type { CdpConnection } from "../client.ts";
14
+ import type { PageConnection } from "../client.ts";
15
15
  import type { Target, TargetSelector } from "../types.ts";
16
16
 
17
17
  /* ============================================================================
@@ -143,7 +143,7 @@ interface MockRule {
143
143
  }
144
144
 
145
145
  interface MockSession {
146
- conn: CdpConnection;
146
+ conn: PageConnection;
147
147
  target: Target;
148
148
  rules: MockRule[];
149
149
  intercepted: Array<{ url: string; method: string; action: MockAction }>;
@@ -35,7 +35,7 @@
35
35
  * path and the recommended entry point.
36
36
  */
37
37
  import type { Target, TargetSelector } from "../types.ts";
38
- import type { CdpConnection } from "../client.ts";
38
+ import type { PageConnection } from "../client.ts";
39
39
  import { CdpError, openPage } from "../client.ts";
40
40
  import { mkdir, readFile, writeFile, stat, unlink } from "node:fs/promises";
41
41
  import { join } from "node:path";
@@ -75,7 +75,7 @@ interface TraceEvent {
75
75
 
76
76
  /** A traced-page registry entry held in-process between start and stop. */
77
77
  interface LiveTrace {
78
- conn: CdpConnection;
78
+ conn: PageConnection;
79
79
  target: Target;
80
80
  events: TraceEvent[];
81
81
  startedAt: number;
@@ -108,7 +108,7 @@ function stateFilePath(): string {
108
108
  }
109
109
 
110
110
  /** Subscribe to Tracing.dataCollected and buffer every event into `sink`. */
111
- function bufferTraceData(conn: CdpConnection, sink: TraceEvent[]): () => void {
111
+ function bufferTraceData(conn: PageConnection, sink: TraceEvent[]): () => void {
112
112
  return conn.on("Tracing.dataCollected", (params: Record<string, unknown>) => {
113
113
  const value = (params as { value?: TraceEvent[] }).value;
114
114
  if (Array.isArray(value)) sink.push(...value);
@@ -116,7 +116,7 @@ function bufferTraceData(conn: CdpConnection, sink: TraceEvent[]): () => void {
116
116
  }
117
117
 
118
118
  /** Begin a trace on an already-open page connection. */
119
- async function beginTrace(conn: CdpConnection, categories: string[]): Promise<void> {
119
+ async function beginTrace(conn: PageConnection, categories: string[]): Promise<void> {
120
120
  await conn.send("Tracing.start", {
121
121
  traceConfig: { includedCategories: categories },
122
122
  transferMode: "ReportEvents",
@@ -127,7 +127,7 @@ async function beginTrace(conn: CdpConnection, categories: string[]): Promise<vo
127
127
  * End a trace, drain all buffered Tracing.dataCollected, and resolve once
128
128
  * Tracing.tracingComplete fires (or the timeout elapses). Returns the events.
129
129
  */
130
- async function endTrace(conn: CdpConnection, sink: TraceEvent[], timeoutMs = 30_000): Promise<TraceEvent[]> {
130
+ async function endTrace(conn: PageConnection, sink: TraceEvent[], timeoutMs = 30_000): Promise<TraceEvent[]> {
131
131
  const complete = conn.waitFor("Tracing.tracingComplete", undefined, timeoutMs);
132
132
  await conn.send("Tracing.end");
133
133
  await complete;
@@ -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
  * ----------------------------------------------------------
@@ -66,7 +66,7 @@
66
66
  */
67
67
  import { mkdir, appendFile, writeFile, copyFile } from "node:fs/promises";
68
68
  import { CdpError, listTargets, openPage, resolveTarget } from "../client.ts";
69
- import type { CdpConnection } from "../client.ts";
69
+ import type { PageConnection } from "../client.ts";
70
70
  import { resolveWorkerSelector } from "../cdp/workers.ts";
71
71
  import type { Target, TargetSelector } from "../types.ts";
72
72
  import {
@@ -189,7 +189,7 @@ export interface RecorderHandle {
189
189
  /** The resolved target this recorder is attached to. */
190
190
  target: Target;
191
191
  /** The live connection (exposed so a one-shot caller can drive Page.reload on it). */
192
- conn: CdpConnection;
192
+ conn: PageConnection;
193
193
  /** Count of buffer-write failures observed (0 on a healthy capture). */
194
194
  droppedWrites(): number;
195
195
  }
@@ -286,7 +286,7 @@ export interface CaptureWindow {
286
286
  /** The unique per-capture buffer file (read this for isolated results). */
287
287
  file: string;
288
288
  /** Live connection (open until stop), for Network.getResponseBody etc. */
289
- conn: CdpConnection;
289
+ conn: PageConnection;
290
290
  /** Resolved target identity. */
291
291
  resolved: { id: string; url: string; title: string };
292
292
  /** How the window was driven: "reload" for a page, "listen" for a worker. */