cdp-toolkit 3.1.0 → 3.2.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.
- package/CHANGELOG.md +15 -0
- package/README.md +38 -0
- package/dist/bidi/mux-daemon.js +359 -120
- package/dist/cli.js +850 -535
- package/dist/index.js +706 -78
- package/dist/mcp.js +840 -525
- package/package.json +3 -1
- package/src/bidi/snapshot.ts +123 -113
- package/src/cdp/driver.ts +35 -32
- package/src/cdp/endpoint.ts +200 -0
- package/src/cdp/session.ts +246 -0
- package/src/client.ts +118 -10
- package/src/shared-tools.ts +92 -21
- package/src/toolDocs.ts +2 -2
- package/src/tools/evaluate.ts +3 -3
- package/src/tools/navigation.ts +3 -3
- package/src/tools/network_mock.ts +2 -2
- package/src/tools/performance.ts +5 -5
- package/src/tools/recorder.ts +3 -3
- package/src/tools/screencast.ts +46 -6
- package/src/tools/snapshot.ts +2 -2
- package/src/version.ts +1 -1
|
@@ -0,0 +1,246 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A page connection carried by a flat `Target.attachToTarget` session on the
|
|
3
|
+
* browser socket, for the endpoints that serve no per-target socket (see
|
|
4
|
+
* ./endpoint.ts for why those exist).
|
|
5
|
+
*
|
|
6
|
+
* WHAT THIS IS. `SessionConnection` presents the same surface as
|
|
7
|
+
* `CdpConnection` — `send`, `on`, `waitFor`, `close`, with the same
|
|
8
|
+
* per-command timeout — but instead of owning a socket it owns a sessionId and
|
|
9
|
+
* borrows the shared browser socket. Every tool module in the toolkit is typed
|
|
10
|
+
* against that surface, so none of them has to know which one it holds. The
|
|
11
|
+
* one-target-per-call guarantee is unchanged: a call attaches to the ONE
|
|
12
|
+
* target it named and detaches when it is done.
|
|
13
|
+
*
|
|
14
|
+
* WHY FLAT SESSIONS. With `flatten: true` every message for an attached target
|
|
15
|
+
* carries its `sessionId` on the same socket, so routing is a map lookup and
|
|
16
|
+
* two sessions never see each other's events. The nested alternative wraps
|
|
17
|
+
* each message in `Target.receivedMessageFromTarget`, which would mean
|
|
18
|
+
* re-implementing correlation a second time.
|
|
19
|
+
*
|
|
20
|
+
* WHY THE SOCKET IS SHARED AND REFERENCE-COUNTED. Chrome mints a NEW session
|
|
21
|
+
* per attach, and sessions on one socket are independent — measured: attaching
|
|
22
|
+
* twice to one target yields two distinct ids, and detaching one leaves the
|
|
23
|
+
* other working. So concurrent calls can and should share a single browser
|
|
24
|
+
* socket. What they must not do is close it while another call is still using
|
|
25
|
+
* it, hence the refcount: the socket opens on the first borrower and closes
|
|
26
|
+
* after the last one releases.
|
|
27
|
+
*
|
|
28
|
+
* THE WEDGED-TAB PROPERTY IS PRESERVED, and it is the reason the toolkit is
|
|
29
|
+
* worth pointing at a browser with a wedged tab in it. A command to a hung
|
|
30
|
+
* renderer times out in `CdpConnection.send` exactly as before — the timer is
|
|
31
|
+
* per command id, not per socket — and because this transport never attaches
|
|
32
|
+
* to a target it was not asked for, a wedged tab is only ever reached by a
|
|
33
|
+
* call that named it.
|
|
34
|
+
*/
|
|
35
|
+
import { CdpConnection, CdpError, DEFAULT_TIMEOUT_MS } from "../client.ts";
|
|
36
|
+
import { detectEndpoint, forgetEndpoint } from "./endpoint.ts";
|
|
37
|
+
|
|
38
|
+
type EventHandler = (params: Record<string, unknown>, sessionId?: string) => void;
|
|
39
|
+
|
|
40
|
+
/* ----------------------------- shared browser socket ----------------------------- */
|
|
41
|
+
|
|
42
|
+
let shared: { conn: CdpConnection; refs: number; url: string } | undefined;
|
|
43
|
+
let opening: Promise<CdpConnection> | undefined;
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* Borrow the shared browser socket, opening it if nobody holds one.
|
|
47
|
+
*
|
|
48
|
+
* `opening` deduplicates a concurrent first borrow: two calls that arrive
|
|
49
|
+
* together must end up on ONE socket, not race to open two and leak the loser.
|
|
50
|
+
*/
|
|
51
|
+
async function acquireBrowserConn(): Promise<CdpConnection> {
|
|
52
|
+
if (shared) {
|
|
53
|
+
shared.refs++;
|
|
54
|
+
return shared.conn;
|
|
55
|
+
}
|
|
56
|
+
if (!opening) {
|
|
57
|
+
opening = (async () => {
|
|
58
|
+
let { browserWsUrl } = await detectEndpoint();
|
|
59
|
+
let conn: CdpConnection;
|
|
60
|
+
try {
|
|
61
|
+
conn = await new CdpConnection(browserWsUrl).connect();
|
|
62
|
+
} catch (error) {
|
|
63
|
+
// The detection is cached, and a Chrome restart mints a new browser
|
|
64
|
+
// uuid, so a URL that stopped answering may just be stale: forget it and
|
|
65
|
+
// detect once more. Same URL again (CDP_BROWSER_WS, or Chrome really is
|
|
66
|
+
// down) means there is nothing newer to try.
|
|
67
|
+
forgetEndpoint();
|
|
68
|
+
const fresh = (await detectEndpoint().catch(() => undefined))?.browserWsUrl;
|
|
69
|
+
if (!fresh || fresh === browserWsUrl) throw error;
|
|
70
|
+
browserWsUrl = fresh;
|
|
71
|
+
conn = await new CdpConnection(browserWsUrl).connect();
|
|
72
|
+
}
|
|
73
|
+
shared = { conn, refs: 0, url: browserWsUrl };
|
|
74
|
+
return conn;
|
|
75
|
+
})().finally(() => {
|
|
76
|
+
opening = undefined;
|
|
77
|
+
});
|
|
78
|
+
}
|
|
79
|
+
const conn = await opening;
|
|
80
|
+
// `shared` is set by the block above before it resolves; a concurrent
|
|
81
|
+
// release cannot have run in between, because releasing requires a ref and
|
|
82
|
+
// this borrower has not taken one yet.
|
|
83
|
+
shared!.refs++;
|
|
84
|
+
return conn;
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/** Return a borrow. The socket closes when the last holder lets go. */
|
|
88
|
+
function releaseBrowserConn(): void {
|
|
89
|
+
if (!shared) return;
|
|
90
|
+
shared.refs--;
|
|
91
|
+
if (shared.refs <= 0) {
|
|
92
|
+
const { conn } = shared;
|
|
93
|
+
shared = undefined;
|
|
94
|
+
conn.close();
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
/**
|
|
99
|
+
* Run `fn` on the shared browser socket. The browser-domain counterpart of
|
|
100
|
+
* client.ts's `withPage`, and the only way this module opens a socket.
|
|
101
|
+
*/
|
|
102
|
+
export async function withBrowserSocket<T>(fn: (conn: CdpConnection) => Promise<T>): Promise<T> {
|
|
103
|
+
const conn = await acquireBrowserConn();
|
|
104
|
+
try {
|
|
105
|
+
return await fn(conn);
|
|
106
|
+
} finally {
|
|
107
|
+
releaseBrowserConn();
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
/* -------------------------------- page sessions -------------------------------- */
|
|
112
|
+
|
|
113
|
+
/**
|
|
114
|
+
* One attached target, shaped like a `CdpConnection`.
|
|
115
|
+
*
|
|
116
|
+
* Structural, not a subclass: `CdpConnection` owns a socket in its constructor
|
|
117
|
+
* and this owns a sessionId, so there is no state to inherit. Callers hold
|
|
118
|
+
* them through the shared `PageConnection` type below.
|
|
119
|
+
*/
|
|
120
|
+
export class SessionConnection {
|
|
121
|
+
private detached = false;
|
|
122
|
+
private readonly offs: Array<() => void> = [];
|
|
123
|
+
|
|
124
|
+
constructor(
|
|
125
|
+
private readonly browser: CdpConnection,
|
|
126
|
+
readonly sessionId: string,
|
|
127
|
+
private readonly opts: { timeoutMs?: number } = {},
|
|
128
|
+
) {}
|
|
129
|
+
|
|
130
|
+
/** Send over this session. Same timeout semantics as CdpConnection.send. */
|
|
131
|
+
send<T = Record<string, unknown>>(
|
|
132
|
+
method: string,
|
|
133
|
+
params: Record<string, unknown> = {},
|
|
134
|
+
opts: { timeoutMs?: number; sessionId?: string } = {},
|
|
135
|
+
): Promise<T> {
|
|
136
|
+
if (this.detached) return Promise.reject(new CdpError("connection not open"));
|
|
137
|
+
// An explicit sessionId wins, so a caller that attached a NESTED session of
|
|
138
|
+
// its own (cdp/workers.ts does this for ServiceWorker) still addresses it.
|
|
139
|
+
return this.browser.send<T>(method, params, {
|
|
140
|
+
timeoutMs: opts.timeoutMs ?? this.opts.timeoutMs,
|
|
141
|
+
sessionId: opts.sessionId ?? this.sessionId,
|
|
142
|
+
});
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
/**
|
|
146
|
+
* Subscribe, filtered to THIS session.
|
|
147
|
+
*
|
|
148
|
+
* The filter is what makes one socket behave like many: the browser socket
|
|
149
|
+
* carries every attached target's events, and a handler registered here must
|
|
150
|
+
* see only its own. An event with no sessionId is browser-level (a
|
|
151
|
+
* `Target.*` notification) and is delivered too, matching what a per-target
|
|
152
|
+
* socket shows.
|
|
153
|
+
*/
|
|
154
|
+
on(method: string, handler: EventHandler): () => void {
|
|
155
|
+
const off = this.browser.on(method, (params, sessionId) => {
|
|
156
|
+
if (sessionId && sessionId !== this.sessionId) return;
|
|
157
|
+
handler(params, sessionId);
|
|
158
|
+
});
|
|
159
|
+
this.offs.push(off);
|
|
160
|
+
return off;
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
waitFor<P = Record<string, unknown>>(
|
|
164
|
+
method: string,
|
|
165
|
+
predicate?: (params: P) => boolean,
|
|
166
|
+
timeoutMs = this.opts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
|
|
167
|
+
): Promise<P> {
|
|
168
|
+
return new Promise<P>((resolve, reject) => {
|
|
169
|
+
const timer = setTimeout(() => {
|
|
170
|
+
off();
|
|
171
|
+
reject(new CdpError(`waitFor('${method}') timed out after ${timeoutMs}ms`));
|
|
172
|
+
}, timeoutMs);
|
|
173
|
+
const off = this.on(method, (params) => {
|
|
174
|
+
if (!predicate || predicate(params as P)) {
|
|
175
|
+
clearTimeout(timer);
|
|
176
|
+
off();
|
|
177
|
+
resolve(params as P);
|
|
178
|
+
}
|
|
179
|
+
});
|
|
180
|
+
});
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
/**
|
|
184
|
+
* Detach and return the socket borrow.
|
|
185
|
+
*
|
|
186
|
+
* Named `close` because that is the method every tool module already calls in
|
|
187
|
+
* its `finally`. The detach is fire-and-forget: the borrow must be returned
|
|
188
|
+
* even when the target died first, and a failed detach on a target that is
|
|
189
|
+
* already gone is not a caller's problem.
|
|
190
|
+
*/
|
|
191
|
+
close(): void {
|
|
192
|
+
if (this.detached) return;
|
|
193
|
+
this.detached = true;
|
|
194
|
+
for (const off of this.offs) off();
|
|
195
|
+
this.offs.length = 0;
|
|
196
|
+
void this.browser.send("Target.detachFromTarget", { sessionId: this.sessionId }).catch(() => {
|
|
197
|
+
/* target already gone */
|
|
198
|
+
});
|
|
199
|
+
releaseBrowserConn();
|
|
200
|
+
}
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
/**
|
|
204
|
+
* What every tool module actually holds: a `CdpConnection` when the endpoint
|
|
205
|
+
* serves per-target sockets, a `SessionConnection` when it does not.
|
|
206
|
+
*
|
|
207
|
+
* AN INTERFACE, NOT A UNION, on purpose. A union of the two classes would make
|
|
208
|
+
* every tool module narrow before it could send, for a distinction none of them
|
|
209
|
+
* cares about. This is the surface they were already using — four methods —
|
|
210
|
+
* so both implementations satisfy it structurally and `withPage` hands over
|
|
211
|
+
* whichever one the transport produced.
|
|
212
|
+
*/
|
|
213
|
+
export interface PageConnection {
|
|
214
|
+
send<T = Record<string, unknown>>(
|
|
215
|
+
method: string,
|
|
216
|
+
params?: Record<string, unknown>,
|
|
217
|
+
opts?: { timeoutMs?: number; sessionId?: string },
|
|
218
|
+
): Promise<T>;
|
|
219
|
+
on(method: string, handler: EventHandler): () => void;
|
|
220
|
+
waitFor<P = Record<string, unknown>>(
|
|
221
|
+
method: string,
|
|
222
|
+
predicate?: (params: P) => boolean,
|
|
223
|
+
timeoutMs?: number,
|
|
224
|
+
): Promise<P>;
|
|
225
|
+
close(): void;
|
|
226
|
+
}
|
|
227
|
+
|
|
228
|
+
/** Attach to one target and wrap the session. The caller closes it. */
|
|
229
|
+
export async function openSession(
|
|
230
|
+
targetId: string,
|
|
231
|
+
opts: { timeoutMs?: number } = {},
|
|
232
|
+
): Promise<SessionConnection> {
|
|
233
|
+
const browser = await acquireBrowserConn();
|
|
234
|
+
try {
|
|
235
|
+
const { sessionId } = await browser.send<{ sessionId?: string }>(
|
|
236
|
+
"Target.attachToTarget",
|
|
237
|
+
{ targetId, flatten: true },
|
|
238
|
+
{ timeoutMs: opts.timeoutMs },
|
|
239
|
+
);
|
|
240
|
+
if (!sessionId) throw new CdpError(`Target.attachToTarget returned no sessionId for ${targetId}`);
|
|
241
|
+
return new SessionConnection(browser, sessionId, opts);
|
|
242
|
+
} catch (e) {
|
|
243
|
+
releaseBrowserConn();
|
|
244
|
+
throw e;
|
|
245
|
+
}
|
|
246
|
+
}
|
package/src/client.ts
CHANGED
|
@@ -25,6 +25,9 @@ import {
|
|
|
25
25
|
FRAME_EMPTY_NEEDLE_MESSAGE,
|
|
26
26
|
} from "./frames.ts";
|
|
27
27
|
|
|
28
|
+
import { detectEndpoint, resetEndpointCache, type CdpTransport } from "./cdp/endpoint.ts";
|
|
29
|
+
import { openSession, withBrowserSocket, type PageConnection } from "./cdp/session.ts";
|
|
30
|
+
export { SessionConnection, withBrowserSocket, type PageConnection } from "./cdp/session.ts";
|
|
28
31
|
/**
|
|
29
32
|
* Base HTTP origin of the DEFAULT DevTools endpoint, fixed at import (CDP_BASE, else
|
|
30
33
|
* http://127.0.0.1:9222, or the default named by CDP_ENDPOINTS / CDP_ENDPOINTS_FILE).
|
|
@@ -207,6 +210,18 @@ export class CdpConnection {
|
|
|
207
210
|
|
|
208
211
|
/* ----------------------------- endpoint discovery ----------------------------- */
|
|
209
212
|
|
|
213
|
+
/**
|
|
214
|
+
* Which transport each endpoint turned out to serve, learned from its first
|
|
215
|
+
* listing that succeeded, keyed by endpoint base. Absent until then.
|
|
216
|
+
*/
|
|
217
|
+
const knownTransports = new Map<string, CdpTransport>();
|
|
218
|
+
|
|
219
|
+
/** Test seam: forget the learned transport. */
|
|
220
|
+
export function resetTransportCache(): void {
|
|
221
|
+
knownTransports.clear();
|
|
222
|
+
resetEndpointCache();
|
|
223
|
+
}
|
|
224
|
+
|
|
210
225
|
async function httpJson<T>(path: string): Promise<T> {
|
|
211
226
|
// Resolved PER CALL, never cached: the endpoint comes from the dispatch scope, and an
|
|
212
227
|
// endpoint that was down a moment ago is simply tried again.
|
|
@@ -215,15 +230,96 @@ async function httpJson<T>(path: string): Promise<T> {
|
|
|
215
230
|
return (await res.json()) as T;
|
|
216
231
|
}
|
|
217
232
|
|
|
218
|
-
/**
|
|
219
|
-
|
|
220
|
-
|
|
233
|
+
/**
|
|
234
|
+
* `Target.getTargets` reshaped into the `/json/list` record every caller
|
|
235
|
+
* already reads.
|
|
236
|
+
*
|
|
237
|
+
* TWO DIFFERENCES from the HTTP listing, both deliberate:
|
|
238
|
+
*
|
|
239
|
+
* `filter: [{}]` is passed because the DEFAULT filter is not "everything" — it
|
|
240
|
+
* omits types the empty filter includes. Measured on Chrome 153: default
|
|
241
|
+
* returned 4 targets (page, browser_ui), `[{}]` returned 6, and the missing
|
|
242
|
+
* ones were exactly the iframe/worker types that the `frame:` and `worker:`
|
|
243
|
+
* selector arms resolve against. Taking the default would silently delete two
|
|
244
|
+
* documented features.
|
|
245
|
+
*
|
|
246
|
+
* `webSocketDebuggerUrl` is EMPTY, and it has to be: on this transport there is
|
|
247
|
+
* no per-target socket to name, and inventing the `/devtools/page/<id>` URL
|
|
248
|
+
* would hand callers a string that 403s. Nothing reads the field on this path —
|
|
249
|
+
* `openPage` branches on transport before it would — and the emptiness is what
|
|
250
|
+
* makes a caller that ignored the branch fail loudly instead of hanging.
|
|
251
|
+
*/
|
|
252
|
+
async function getTargetsOverBrowserWs(): Promise<Target[]> {
|
|
253
|
+
const { targetInfos } = await withBrowserSocket((conn) =>
|
|
254
|
+
conn.send<{ targetInfos: Array<{ targetId: string; type: string; title: string; url: string; openerId?: string }> }>(
|
|
255
|
+
"Target.getTargets",
|
|
256
|
+
{ filter: [{}] },
|
|
257
|
+
),
|
|
258
|
+
);
|
|
259
|
+
return targetInfos.map((t) => ({
|
|
260
|
+
id: t.targetId,
|
|
261
|
+
type: t.type,
|
|
262
|
+
title: t.title,
|
|
263
|
+
url: t.url,
|
|
264
|
+
webSocketDebuggerUrl: "",
|
|
265
|
+
...(t.openerId ? { parentId: t.openerId } : {}),
|
|
266
|
+
}));
|
|
221
267
|
}
|
|
222
268
|
|
|
223
|
-
/**
|
|
269
|
+
/**
|
|
270
|
+
* All targets: `GET /json/list`, falling back to `Target.getTargets` on the
|
|
271
|
+
* browser socket when this Chrome does not serve it.
|
|
272
|
+
*
|
|
273
|
+
* THE HTTP REQUEST GOES FIRST AND UNCONDITIONALLY, which is the whole
|
|
274
|
+
* no-regression story: against a Chrome that serves `/json/list` this function
|
|
275
|
+
* does exactly what it did before the fallback existed, and the fallback is
|
|
276
|
+
* unreachable. Only a request that failed opens a socket.
|
|
277
|
+
*
|
|
278
|
+
* Once a transport is known it is cached, so the 404 is paid once per process
|
|
279
|
+
* rather than on every listing.
|
|
280
|
+
*/
|
|
281
|
+
export async function listTargets(): Promise<Target[]> {
|
|
282
|
+
const base = currentEndpoint().base;
|
|
283
|
+
if (knownTransports.get(base) === "browser-ws") return getTargetsOverBrowserWs();
|
|
284
|
+
try {
|
|
285
|
+
const listing = await httpJson<Target[]>("/json/list");
|
|
286
|
+
knownTransports.set(base, "http");
|
|
287
|
+
return listing;
|
|
288
|
+
} catch (httpError) {
|
|
289
|
+
// Switch only when detection says this endpoint really serves no `/json`.
|
|
290
|
+
// A Chrome that does serve it can still fail one `/json/list` (restarting,
|
|
291
|
+
// a timeout); its `/json/version` then answers, detection says "http", and
|
|
292
|
+
// pinning browser-ws here would move every later call off the per-target
|
|
293
|
+
// sockets for the rest of the process. Rethrow instead, so the next call
|
|
294
|
+
// tries HTTP again.
|
|
295
|
+
const detected = await detectEndpoint().catch(() => undefined);
|
|
296
|
+
if (detected?.transport !== "browser-ws") throw httpError;
|
|
297
|
+
const targets = await getTargetsOverBrowserWs().catch(() => {
|
|
298
|
+
// The HTTP failure is the one worth reporting: it names the endpoint the
|
|
299
|
+
// user configured, where the fallback's failure only says a profile
|
|
300
|
+
// lookup came up empty.
|
|
301
|
+
throw httpError;
|
|
302
|
+
});
|
|
303
|
+
knownTransports.set(base, "browser-ws");
|
|
304
|
+
return targets;
|
|
305
|
+
}
|
|
306
|
+
}
|
|
307
|
+
|
|
308
|
+
/**
|
|
309
|
+
* Browser-level WebSocket URL, for Target.* / Browser.*.
|
|
310
|
+
*
|
|
311
|
+
* `GET /json/version` first and on every call, as before the browser-ws
|
|
312
|
+
* transport existed: its uuid changes on every Chrome start, so a URL kept
|
|
313
|
+
* across calls goes stale after a restart. Only an endpoint already known to
|
|
314
|
+
* serve no `/json`, or one whose `/json/version` did not answer, goes through
|
|
315
|
+
* detection.
|
|
316
|
+
*/
|
|
224
317
|
export async function browserWsUrl(): Promise<string> {
|
|
225
|
-
|
|
226
|
-
|
|
318
|
+
if (knownTransports.get(currentEndpoint().base) !== "browser-ws") {
|
|
319
|
+
const version = await httpJson<{ webSocketDebuggerUrl: string }>("/json/version").catch(() => undefined);
|
|
320
|
+
if (version?.webSocketDebuggerUrl) return version.webSocketDebuggerUrl;
|
|
321
|
+
}
|
|
322
|
+
return (await detectEndpoint()).browserWsUrl;
|
|
227
323
|
}
|
|
228
324
|
|
|
229
325
|
/** Resolve a TargetSelector to a concrete page target. See types.ts for grammar.
|
|
@@ -333,13 +429,25 @@ export async function openBrowser(opts: { timeoutMs?: number } = {}): Promise<Cd
|
|
|
333
429
|
return new CdpConnection(await browserWsUrl(), opts).connect();
|
|
334
430
|
}
|
|
335
431
|
|
|
336
|
-
/**
|
|
432
|
+
/**
|
|
433
|
+
* Open a connection to a page target. Returns the connection and the target.
|
|
434
|
+
*
|
|
435
|
+
* The one place the two transports diverge for a tool author: a per-target
|
|
436
|
+
* socket where Chrome serves one, an attached session on the shared browser
|
|
437
|
+
* socket where it does not. Both are closed by the caller the same way, and
|
|
438
|
+
* both carry the same per-command timeout, so no tool module branches on this.
|
|
439
|
+
*/
|
|
337
440
|
export async function openPage(
|
|
338
441
|
selector: TargetSelector,
|
|
339
442
|
opts: { timeoutMs?: number; lease?: string } = {},
|
|
340
|
-
): Promise<{ conn:
|
|
443
|
+
): Promise<{ conn: PageConnection; target: Target }> {
|
|
444
|
+
// resolveTarget listed first, so the transport is already known here: an
|
|
445
|
+
// empty webSocketDebuggerUrl is the browser-ws listing's own marker that this
|
|
446
|
+
// target has no socket to dial (see getTargetsOverBrowserWs).
|
|
341
447
|
const target = await resolveTarget(selector, { lease: opts.lease });
|
|
342
|
-
const conn =
|
|
448
|
+
const conn = target.webSocketDebuggerUrl
|
|
449
|
+
? await new CdpConnection(target.webSocketDebuggerUrl, opts).connect()
|
|
450
|
+
: await openSession(target.id, opts);
|
|
343
451
|
return { conn, target };
|
|
344
452
|
}
|
|
345
453
|
|
|
@@ -349,7 +457,7 @@ export async function openPage(
|
|
|
349
457
|
*/
|
|
350
458
|
export async function withPage<T>(
|
|
351
459
|
selector: TargetSelector,
|
|
352
|
-
fn: (conn:
|
|
460
|
+
fn: (conn: PageConnection, target: Target) => Promise<T>,
|
|
353
461
|
opts: { timeoutMs?: number; lease?: string } = {},
|
|
354
462
|
): Promise<T> {
|
|
355
463
|
const { conn, target } = await openPage(selector, opts);
|
package/src/shared-tools.ts
CHANGED
|
@@ -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
|
|
917
|
-
|
|
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
|
|
965
|
-
|
|
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
|
|
1068
|
-
|
|
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
|
|
1076
|
-
|
|
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
|
-
|
|
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
|
|
1100
|
-
|
|
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
|
-
|
|
1120
|
-
|
|
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
|
|
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.",
|
|
@@ -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.",
|
package/src/tools/evaluate.ts
CHANGED
|
@@ -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 {
|
|
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:
|
|
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:
|
|
97
|
+
conn: PageConnection,
|
|
98
98
|
expression: string,
|
|
99
99
|
awaitPromise: boolean,
|
|
100
100
|
args: unknown[],
|