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.
@@ -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
- /** All targets (GET /json/list). */
219
- export function listTargets(): Promise<Target[]> {
220
- return httpJson<Target[]>("/json/list");
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
- /** Browser-level WebSocket URL (GET /json/version), for Target.* / Browser.*. */
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
- const v = await httpJson<{ webSocketDebuggerUrl: string }>("/json/version");
226
- return v.webSocketDebuggerUrl;
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
- /** Open a connection to a page target. Returns the connection and the target. */
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: CdpConnection; target: Target }> {
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 = await new CdpConnection(target.webSocketDebuggerUrl, opts).connect();
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: CdpConnection, target: Target) => Promise<T>,
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);
@@ -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
 
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.",
@@ -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[],