cdp-toolkit 3.3.0 → 3.5.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/dist/index.js CHANGED
@@ -322,6 +322,9 @@ function leaseTtlMs() {
322
322
  function markLongLivedProcess(value = true) {
323
323
  longLived = value;
324
324
  }
325
+ function isLongLivedProcess() {
326
+ return longLived;
327
+ }
325
328
  function requireLease() {
326
329
  if (!longLived)
327
330
  return false;
@@ -686,7 +689,7 @@ async function originIndex(backend, liveIds) {
686
689
  return index;
687
690
  }
688
691
  async function newTrackedPage(driver, backend, opts = {}) {
689
- const page = await driver.newPage(opts.url);
692
+ const page = await driver.newPage(opts.url, { focus: opts.focus === true });
690
693
  await recordOrigin(backend, page.id, { label: opts.label });
691
694
  return page;
692
695
  }
@@ -1000,6 +1003,165 @@ var init_session = __esm(() => {
1000
1003
  init_endpoint();
1001
1004
  });
1002
1005
 
1006
+ // src/cdp/hiddenTabs.ts
1007
+ function hiddenTabsRequested() {
1008
+ return TRUTHY.has((process.env.CDP_HIDDEN_TABS ?? "").trim().toLowerCase());
1009
+ }
1010
+ function hiddenTabsMax() {
1011
+ const raw = Number(process.env.CDP_HIDDEN_TABS_MAX);
1012
+ return Number.isFinite(raw) && raw >= 1 ? Math.floor(raw) : DEFAULT_HIDDEN_TABS_MAX;
1013
+ }
1014
+
1015
+ class HiddenTabOwner {
1016
+ deps;
1017
+ conn;
1018
+ connecting;
1019
+ tabs = new Map;
1020
+ reserved = 0;
1021
+ constructor(deps) {
1022
+ this.deps = deps;
1023
+ }
1024
+ sweep() {
1025
+ if (this.conn && !this.conn.isOpen) {
1026
+ this.conn = undefined;
1027
+ this.tabs.clear();
1028
+ }
1029
+ }
1030
+ has(id) {
1031
+ this.sweep();
1032
+ return this.tabs.has(id);
1033
+ }
1034
+ ids() {
1035
+ this.sweep();
1036
+ return [...this.tabs.keys()];
1037
+ }
1038
+ async owner() {
1039
+ this.sweep();
1040
+ if (this.conn)
1041
+ return this.conn;
1042
+ if (!this.connecting) {
1043
+ this.connecting = (async () => {
1044
+ const conn = await this.deps.connect();
1045
+ conn.on("Target.targetDestroyed", (params) => {
1046
+ const id = params.targetId;
1047
+ if (typeof id === "string")
1048
+ this.tabs.delete(id);
1049
+ });
1050
+ this.conn = conn;
1051
+ return conn;
1052
+ })().finally(() => {
1053
+ this.connecting = undefined;
1054
+ });
1055
+ }
1056
+ return this.connecting;
1057
+ }
1058
+ async create(url) {
1059
+ this.sweep();
1060
+ const max = (this.deps.max ?? hiddenTabsMax)();
1061
+ if (this.tabs.size + this.reserved >= max)
1062
+ throw new HiddenTabCapError(max, [...this.tabs.keys()]);
1063
+ this.reserved++;
1064
+ try {
1065
+ const conn = await this.owner();
1066
+ const id = await this.deps.createSettled(conn, url, { hidden: true });
1067
+ try {
1068
+ const { sessionId } = await conn.send("Target.attachToTarget", { targetId: id, flatten: true }, { timeoutMs: OWNER_COMMAND_TIMEOUT_MS });
1069
+ const dpr = await conn.send("Runtime.evaluate", { expression: "devicePixelRatio", returnByValue: true }, { sessionId, timeoutMs: OWNER_COMMAND_TIMEOUT_MS }).then((r) => r.result?.value).catch(() => {
1070
+ return;
1071
+ });
1072
+ await conn.send("Emulation.setDeviceMetricsOverride", {
1073
+ width: HIDDEN_TAB_VIEWPORT.width,
1074
+ height: HIDDEN_TAB_VIEWPORT.height,
1075
+ deviceScaleFactor: typeof dpr === "number" && Number.isFinite(dpr) && dpr > 0 ? dpr : FALLBACK_DEVICE_SCALE_FACTOR,
1076
+ mobile: false
1077
+ }, { sessionId, timeoutMs: OWNER_COMMAND_TIMEOUT_MS });
1078
+ this.tabs.set(id, sessionId);
1079
+ return id;
1080
+ } catch (e) {
1081
+ await conn.send("Target.closeTarget", { targetId: id }, { timeoutMs: OWNER_COMMAND_TIMEOUT_MS }).catch(() => {
1082
+ return;
1083
+ });
1084
+ throw e;
1085
+ }
1086
+ } finally {
1087
+ this.reserved--;
1088
+ }
1089
+ }
1090
+ async close(id) {
1091
+ this.sweep();
1092
+ const conn = this.conn;
1093
+ const held = this.tabs.delete(id);
1094
+ if (!conn || !held)
1095
+ return { success: false };
1096
+ const res = await conn.send("Target.closeTarget", { targetId: id }, { timeoutMs: OWNER_COMMAND_TIMEOUT_MS });
1097
+ return { success: res.success ?? true };
1098
+ }
1099
+ async dispose() {
1100
+ const conn = this.conn;
1101
+ const ids = [...this.tabs.keys()];
1102
+ this.tabs.clear();
1103
+ this.conn = undefined;
1104
+ if (!conn)
1105
+ return;
1106
+ if (conn.isOpen) {
1107
+ await Promise.all(ids.map((targetId) => conn.send("Target.closeTarget", { targetId }, { timeoutMs: OWNER_COMMAND_TIMEOUT_MS }).catch(() => {
1108
+ return;
1109
+ })));
1110
+ }
1111
+ conn.close();
1112
+ }
1113
+ }
1114
+ function hiddenTabOwner(base, deps) {
1115
+ let owner = owners.get(base);
1116
+ if (!owner) {
1117
+ owner = new HiddenTabOwner(deps());
1118
+ owners.set(base, owner);
1119
+ }
1120
+ return owner;
1121
+ }
1122
+ function existingHiddenTabOwner(base) {
1123
+ return owners.get(base);
1124
+ }
1125
+ function markHiddenTargets(base, targets) {
1126
+ const owner = owners.get(base);
1127
+ if (!owner)
1128
+ return targets;
1129
+ const hidden = new Set(owner.ids());
1130
+ if (hidden.size === 0)
1131
+ return targets;
1132
+ const visible = [];
1133
+ const marked = [];
1134
+ for (const t of targets) {
1135
+ if (hidden.has(t.id))
1136
+ marked.push({ ...t, type: "page", hidden: true });
1137
+ else
1138
+ visible.push(t);
1139
+ }
1140
+ return marked.length ? [...visible, ...marked] : targets;
1141
+ }
1142
+ async function disposeHiddenTabs() {
1143
+ const all = [...owners.values()];
1144
+ owners.clear();
1145
+ await Promise.all(all.map((o) => o.dispose()));
1146
+ }
1147
+ var DEFAULT_HIDDEN_TABS_MAX = 20, HIDDEN_TAB_VIEWPORT, FALLBACK_DEVICE_SCALE_FACTOR = 2, OWNER_COMMAND_TIMEOUT_MS = 5000, TRUTHY, HiddenTabCapError, owners;
1148
+ var init_hiddenTabs = __esm(() => {
1149
+ HIDDEN_TAB_VIEWPORT = { width: 1280, height: 800 };
1150
+ TRUTHY = new Set(["1", "true", "yes", "on"]);
1151
+ HiddenTabCapError = class HiddenTabCapError extends Error {
1152
+ max;
1153
+ openIds;
1154
+ code = "page-error";
1155
+ constructor(max, openIds) {
1156
+ super(`hidden-tab cap reached: ${openIds.length} hidden tabs are open (CDP_HIDDEN_TABS_MAX=${max}). ` + `Close one with close_page (open hidden tabs, oldest first: ${openIds.join(", ")}), ` + `or pass focus:true to open a visible tab instead.`);
1157
+ this.max = max;
1158
+ this.openIds = openIds;
1159
+ this.name = "HiddenTabCapError";
1160
+ }
1161
+ };
1162
+ owners = new Map;
1163
+ });
1164
+
1003
1165
  // src/client.ts
1004
1166
  class CdpConnection {
1005
1167
  wsUrl;
@@ -1118,6 +1280,9 @@ class CdpConnection {
1118
1280
  });
1119
1281
  });
1120
1282
  }
1283
+ get isOpen() {
1284
+ return !this.closed && this.ws !== undefined;
1285
+ }
1121
1286
  close() {
1122
1287
  this.closed = true;
1123
1288
  this.rejectAll(new CdpError("closed by caller"));
@@ -1146,11 +1311,11 @@ async function getTargetsOverBrowserWs() {
1146
1311
  async function listTargets() {
1147
1312
  const base = currentEndpoint().base;
1148
1313
  if (knownTransports.get(base) === "browser-ws")
1149
- return getTargetsOverBrowserWs();
1314
+ return markHiddenTargets(base, await getTargetsOverBrowserWs());
1150
1315
  try {
1151
1316
  const listing = await httpJson("/json/list");
1152
1317
  knownTransports.set(base, "http");
1153
- return listing;
1318
+ return markHiddenTargets(base, listing);
1154
1319
  } catch (httpError) {
1155
1320
  const detected = await detectEndpoint().catch(() => {
1156
1321
  return;
@@ -1161,7 +1326,7 @@ async function listTargets() {
1161
1326
  throw httpError;
1162
1327
  });
1163
1328
  knownTransports.set(base, "browser-ws");
1164
- return targets;
1329
+ return markHiddenTargets(base, targets);
1165
1330
  }
1166
1331
  }
1167
1332
  async function browserWsUrl() {
@@ -1274,6 +1439,7 @@ var init_client = __esm(() => {
1274
1439
  init_frames();
1275
1440
  init_endpoint();
1276
1441
  init_session();
1442
+ init_hiddenTabs();
1277
1443
  init_session();
1278
1444
  BASE = (() => {
1279
1445
  try {
@@ -1296,6 +1462,53 @@ var init_client = __esm(() => {
1296
1462
  knownTransports = new Map;
1297
1463
  });
1298
1464
 
1465
+ // src/frontApp.ts
1466
+ import { execFile } from "node:child_process";
1467
+ function run(cmd, args) {
1468
+ return new Promise((resolve) => {
1469
+ execFile(cmd, args, { timeout: 2000 }, (err, stdout) => resolve(err ? "" : String(stdout)));
1470
+ });
1471
+ }
1472
+ function restoreFrontAppEnabled(platform = process.platform) {
1473
+ return platform === "darwin" && (process.env.CDP_RESTORE_FRONT_APP ?? "").trim() !== "0";
1474
+ }
1475
+ async function keepFrontApp(fn, opts = {}) {
1476
+ const enabled = opts.enabled ?? restoreFrontAppEnabled();
1477
+ if (!enabled)
1478
+ return fn();
1479
+ const ops = opts.ops ?? macFrontAppOps;
1480
+ const before = await ops.front().catch(() => null);
1481
+ const result = await fn();
1482
+ if (before === null)
1483
+ return result;
1484
+ const fix = async () => {
1485
+ const now = await ops.front().catch(() => null);
1486
+ if (now !== null && now !== before)
1487
+ await ops.setFront(before).catch(() => {
1488
+ return;
1489
+ });
1490
+ };
1491
+ await fix();
1492
+ await new Promise((r) => setTimeout(r, opts.recheckMs ?? 250));
1493
+ await fix();
1494
+ return result;
1495
+ }
1496
+ var macFrontAppOps;
1497
+ var init_frontApp = __esm(() => {
1498
+ macFrontAppOps = {
1499
+ async front() {
1500
+ const asn = (await run("lsappinfo", ["front"])).trim();
1501
+ if (!asn)
1502
+ return null;
1503
+ const m = /"?pid"?\s*=\s*(\d+)/.exec(await run("lsappinfo", ["info", "-only", "pid", asn]));
1504
+ return m ? Number(m[1]) : null;
1505
+ },
1506
+ async setFront(pid) {
1507
+ await run("osascript", ["-e", `tell application "System Events" to set frontmost of (first process whose unix id is ${pid}) to true`]);
1508
+ }
1509
+ };
1510
+ });
1511
+
1299
1512
  // src/activity.ts
1300
1513
  function dispatchKey(backend, targetId) {
1301
1514
  return `${backend}:${targetId}`;
@@ -2000,7 +2213,9 @@ function implicitRole(el) {
2000
2213
  // src/cdp/driver.ts
2001
2214
  init_client();
2002
2215
  init_session();
2216
+ init_frontApp();
2003
2217
  init_leases();
2218
+ init_hiddenTabs();
2004
2219
  init_endpoints();
2005
2220
  init_activity();
2006
2221
 
@@ -2177,6 +2392,47 @@ async function centerOf(conn, objectId) {
2177
2392
  throw driverError("page-error", "element has zero size / is not visible; cannot compute a click point");
2178
2393
  return result.value;
2179
2394
  }
2395
+ var SNAPSHOT_TEXT_FN = "function(){var e=this;e.__cdpSawInput=false;var f=function(){e.__cdpSawInput=true;};" + "e.addEventListener('beforeinput',f,{capture:true,once:true});e.addEventListener('input',f,{capture:true,once:true});" + "return e.isContentEditable?e.textContent:('value' in e?String(e.value):null);}";
2396
+ var LANDED_TEXT_FN = "function(before){var e=this;var now=function(){return e.isContentEditable?e.textContent:('value' in e?String(e.value):null);};" + "var hit=function(){return e.__cdpSawInput===true||now()!==before;};" + "if(hit())return true;return new Promise(function(r){setTimeout(function(){r(hit());},50);});}";
2397
+ var FALLBACK_TEXT_FN = "function(t){var e=this;if(e.disabled||e.readOnly)return 'skipped';var ce=e.isContentEditable===true;" + "var ta=e instanceof HTMLTextAreaElement;var inp=e instanceof HTMLInputElement&&!/^(checkbox|radio|file|button|submit|reset|image|hidden|range|color)$/i.test(e.type);" + "if(!ce&&!ta&&!inp)return 'skipped';e.focus();" + "if(ce){var r=document.createRange();r.selectNodeContents(e);r.collapse(false);var s=window.getSelection();s.removeAllRanges();s.addRange(r);}" + "else{try{var n=e.value.length;e.setSelectionRange(n,n);}catch(x){}}" + "var read=function(){return ce?e.textContent:e.value;};var before=read();" + "if(document.execCommand('insertText',false,t)&&read()!==before){e.dispatchEvent(new Event('change',{bubbles:true}));return 'execCommand';}" + "if(ce)return 'failed';var proto=ta?HTMLTextAreaElement.prototype:HTMLInputElement.prototype;" + "Object.getOwnPropertyDescriptor(proto,'value').set.call(e,before+t);" + "e.dispatchEvent(new InputEvent('input',{bubbles:true,inputType:'insertText',data:t}));" + "e.dispatchEvent(new Event('change',{bubbles:true}));return 'setter';}";
2398
+ async function insertTextVerified(conn, objectId, text, sendInput) {
2399
+ const call = async (fn, args = [], awaitPromise = false) => {
2400
+ const { result, exceptionDetails } = await conn.send("Runtime.callFunctionOn", {
2401
+ objectId,
2402
+ functionDeclaration: fn,
2403
+ arguments: args.map((value) => ({ value })),
2404
+ returnByValue: true,
2405
+ awaitPromise
2406
+ });
2407
+ if (exceptionDetails)
2408
+ throw driverError("page-error", `text input check failed: ${exceptionDetails.text ?? "error"}`);
2409
+ return result?.value;
2410
+ };
2411
+ const before = await call(SNAPSHOT_TEXT_FN);
2412
+ await sendInput("Input.insertText", { text });
2413
+ if (await call(LANDED_TEXT_FN, [before], true) === true)
2414
+ return "trusted";
2415
+ const via = await call(FALLBACK_TEXT_FN, [text]);
2416
+ if (via === "execCommand" || via === "setter" || via === "skipped")
2417
+ return via;
2418
+ throw driverError("page-error", "text did not land: trusted Input.insertText was not delivered (a background tab gets no trusted keyboard input) and document.execCommand('insertText') changed nothing on this element");
2419
+ }
2420
+ var ARM_KEY_WITNESS = "(function(){window.__cdpKeySeen=false;window.addEventListener('keydown',function(){window.__cdpKeySeen=true;},{capture:true,once:true});return true;})()";
2421
+ var READ_KEY_WITNESS = "(function(){if(window.__cdpKeySeen===true)return true;return new Promise(function(r){setTimeout(function(){r(window.__cdpKeySeen===true);},50);});})()";
2422
+ async function pressKeyObserved(conn, dispatch) {
2423
+ const eval_ = (expression, awaitPromise = false) => conn.send("Runtime.evaluate", { expression, returnByValue: true, awaitPromise }).then((r) => r.result?.value, () => {
2424
+ return;
2425
+ });
2426
+ const armed = await eval_(ARM_KEY_WITNESS) === true;
2427
+ await dispatch();
2428
+ if (!armed)
2429
+ return;
2430
+ const seen = await eval_(READ_KEY_WITNESS, true);
2431
+ if (seen === false)
2432
+ return { delivered: false };
2433
+ if (seen === true)
2434
+ return { delivered: true };
2435
+ }
2180
2436
  async function focusElement(conn, objectId) {
2181
2437
  await conn.send("Runtime.callFunctionOn", { objectId, functionDeclaration: "function(){this.focus&&this.focus();}", returnByValue: true });
2182
2438
  }
@@ -2191,10 +2447,12 @@ async function awaitScrollSettle(conn) {
2191
2447
  }
2192
2448
  async function setValueOnObject(conn, objectId, value, sendInput) {
2193
2449
  await focusElement(conn, objectId);
2194
- const fn = "function(){if('value'in this){this.value='';this.dispatchEvent(new Event('input',{bubbles:true}));}else if(this.isContentEditable){this.textContent='';}}";
2195
- await conn.send("Runtime.callFunctionOn", { objectId, functionDeclaration: fn, returnByValue: true });
2196
- if (value.length)
2197
- await sendInput("Input.insertText", { text: value });
2450
+ const fn = "function(){if(this.disabled||this.readOnly)return this.disabled?'disabled':'readonly';if('value'in this){this.value='';this.dispatchEvent(new Event('input',{bubbles:true}));}else if(this.isContentEditable){this.textContent='';}return 'ok';}";
2451
+ const { result } = await conn.send("Runtime.callFunctionOn", { objectId, functionDeclaration: fn, returnByValue: true });
2452
+ if (result?.value === "disabled" || result?.value === "readonly") {
2453
+ throw driverError("page-error", `cannot fill a ${result.value} field: it was left unchanged`);
2454
+ }
2455
+ return value.length ? insertTextVerified(conn, objectId, value, sendInput) : "trusted";
2198
2456
  }
2199
2457
  var NAMED_KEYS = {
2200
2458
  enter: { key: "Enter", code: "Enter", keyCode: 13, text: "\r" },
@@ -2742,13 +3000,12 @@ class CdpPageDriver {
2742
3000
  }
2743
3001
  async setValue(loc, value) {
2744
3002
  const { objectId } = await resolveElementLocator(this.conn, loc);
2745
- await setValueOnObject(this.conn, objectId, value, (method, params) => this.dispatchInput(method, params));
3003
+ return setValueOnObject(this.conn, objectId, value, (method, params) => this.dispatchInput(method, params));
2746
3004
  }
2747
3005
  async typeText(loc, text) {
2748
3006
  const { objectId } = await resolveElementLocator(this.conn, loc);
2749
3007
  await focusElement(this.conn, objectId);
2750
- if (text.length)
2751
- await this.dispatchInput("Input.insertText", { text });
3008
+ return text.length ? insertTextVerified(this.conn, objectId, text, (method, params) => this.dispatchInput(method, params)) : "trusted";
2752
3009
  }
2753
3010
  async pressKey(press) {
2754
3011
  const spec = resolveKey(press.key);
@@ -2763,8 +3020,10 @@ class CdpPageDriver {
2763
3020
  const down = { type: "keyDown", key: spec.key, code: spec.code, windowsVirtualKeyCode: spec.keyCode, nativeVirtualKeyCode: spec.keyCode, modifiers: modBits };
2764
3021
  if (spec.text && !suppressText)
2765
3022
  down.text = spec.text;
2766
- await this.dispatchInput("Input.dispatchKeyEvent", down);
2767
- await this.dispatchInput("Input.dispatchKeyEvent", { type: "keyUp", key: spec.key, code: spec.code, windowsVirtualKeyCode: spec.keyCode, nativeVirtualKeyCode: spec.keyCode, modifiers: modBits });
3023
+ return pressKeyObserved(this.conn, async () => {
3024
+ await this.dispatchInput("Input.dispatchKeyEvent", down);
3025
+ await this.dispatchInput("Input.dispatchKeyEvent", { type: "keyUp", key: spec.key, code: spec.code, windowsVirtualKeyCode: spec.keyCode, nativeVirtualKeyCode: spec.keyCode, modifiers: modBits });
3026
+ });
2768
3027
  }
2769
3028
  async setFiles(loc, files) {
2770
3029
  const { objectId } = await resolveElementLocator(this.conn, loc);
@@ -3141,7 +3400,7 @@ function noSuchTarget(e) {
3141
3400
  throw driverError("no-such-target", e instanceof CdpError ? e.message : String(e));
3142
3401
  }
3143
3402
  var NEW_TARGET_SETTLE_MS = 2000;
3144
- async function createSettledTarget(conn, url, settleMs = NEW_TARGET_SETTLE_MS) {
3403
+ async function createSettledTarget(conn, url, settleMs = NEW_TARGET_SETTLE_MS, opts = {}) {
3145
3404
  const changed = new Set;
3146
3405
  let id = "";
3147
3406
  let wake;
@@ -3157,7 +3416,10 @@ async function createSettledTarget(conn, url, settleMs = NEW_TARGET_SETTLE_MS) {
3157
3416
  await conn.send("Target.setDiscoverTargets", { discover: true }).catch(() => {
3158
3417
  return;
3159
3418
  });
3160
- const { targetId } = await conn.send("Target.createTarget", { url });
3419
+ const hidden = opts.hidden === true;
3420
+ const params = hidden ? { url, background: true, hidden: true } : { url, background: opts.focus !== true };
3421
+ const create = () => conn.send("Target.createTarget", params);
3422
+ const { targetId } = opts.focus === true || hidden ? await create() : await keepFrontApp(create);
3161
3423
  if (!targetId)
3162
3424
  throw driverError("page-error", "Target.createTarget returned no targetId");
3163
3425
  id = targetId;
@@ -3175,6 +3437,19 @@ async function createSettledTarget(conn, url, settleMs = NEW_TARGET_SETTLE_MS) {
3175
3437
  off();
3176
3438
  }
3177
3439
  }
3440
+ function hiddenTabsEnabled() {
3441
+ return hiddenTabsRequested() && isLongLivedProcess();
3442
+ }
3443
+ function currentHiddenOwner() {
3444
+ return hiddenTabOwner(currentEndpoint().base, () => ({
3445
+ connect: () => openBrowser(),
3446
+ createSettled: (conn, url, opts) => createSettledTarget(conn, url, NEW_TARGET_SETTLE_MS, opts)
3447
+ }));
3448
+ }
3449
+ function hiddenOwnerOf(id) {
3450
+ const owner = existingHiddenTabOwner(currentEndpoint().base);
3451
+ return owner?.has(id) ? owner : undefined;
3452
+ }
3178
3453
 
3179
3454
  class CdpBrowserDriver {
3180
3455
  scheme = "cdp";
@@ -3185,17 +3460,28 @@ class CdpBrowserDriver {
3185
3460
  async listPages(opts) {
3186
3461
  const targets = await listTargets();
3187
3462
  const filtered = opts?.all ? targets : targets.filter((t) => t.type === "page");
3188
- return filtered.map((t) => ({ id: t.id, url: t.url, title: t.title, type: t.type }));
3463
+ return filtered.map((t) => ({ id: t.id, url: t.url, title: t.title, type: t.type, ...t.hidden ? { hidden: true } : {} }));
3189
3464
  }
3190
- async newPage(url) {
3465
+ async newPage(url, opts) {
3466
+ if (opts?.focus !== true && hiddenTabsEnabled()) {
3467
+ const id = await currentHiddenOwner().create(url ?? "about:blank");
3468
+ return { id, url: url ?? "about:blank", title: "", hidden: true };
3469
+ }
3191
3470
  return withBrowserConn(async (conn) => {
3192
- const targetId = await createSettledTarget(conn, url ?? "about:blank");
3471
+ const targetId = await createSettledTarget(conn, url ?? "about:blank", NEW_TARGET_SETTLE_MS, { focus: opts?.focus === true });
3193
3472
  return { id: targetId, url: url ?? "about:blank", title: "" };
3194
3473
  });
3195
3474
  }
3196
3475
  async closePage(id) {
3476
+ const owner = hiddenOwnerOf(id);
3477
+ if (owner) {
3478
+ const res = await owner.close(id);
3479
+ if (res.success)
3480
+ beaconSessions.drop(beaconKey(id));
3481
+ return res;
3482
+ }
3197
3483
  return withBrowserConn(async (conn) => {
3198
- const res = await conn.send("Target.closeTarget", { targetId: id });
3484
+ const res = await keepFrontApp(() => conn.send("Target.closeTarget", { targetId: id }));
3199
3485
  if (res.success !== false)
3200
3486
  beaconSessions.drop(beaconKey(id));
3201
3487
  return { success: res.success ?? true };
@@ -3203,6 +3489,16 @@ class CdpBrowserDriver {
3203
3489
  }
3204
3490
  async activatePage(id) {
3205
3491
  const target = await resolveTarget(id).catch(noSuchTarget);
3492
+ const owner = hiddenOwnerOf(target.id);
3493
+ if (owner) {
3494
+ const url = target.url || "about:blank";
3495
+ const newId = await withBrowserConn((conn) => createSettledTarget(conn, url, NEW_TARGET_SETTLE_MS, { focus: true }));
3496
+ await owner.close(target.id).catch(() => {
3497
+ return;
3498
+ });
3499
+ beaconSessions.drop(beaconKey(target.id));
3500
+ return { id: newId, url, title: target.title, revealedFrom: target.id };
3501
+ }
3206
3502
  await withBrowserConn((conn) => conn.send("Target.activateTarget", { targetId: target.id }));
3207
3503
  return { id: target.id, url: target.url, title: target.title };
3208
3504
  }
@@ -3276,6 +3572,7 @@ class CdpBrowserDriver {
3276
3572
  }
3277
3573
  async dispose() {
3278
3574
  beaconSessions.clear();
3575
+ await disposeHiddenTabs();
3279
3576
  }
3280
3577
  }
3281
3578
  function createCdpDriver() {
@@ -3865,7 +4162,6 @@ init_workers();
3865
4162
  init_frames();
3866
4163
  init_endpoints();
3867
4164
  var ARTIFACT_DIR = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
3868
- var STATE_DIR = process.env.CDP_STATE_DIR ?? "/tmp/cdp-toolkit";
3869
4165
 
3870
4166
  class SharedToolError extends Error {
3871
4167
  }
@@ -4024,17 +4320,18 @@ async function listPagesOne(driver, args = {}) {
4024
4320
  }
4025
4321
  async function newPage(driver, args = {}) {
4026
4322
  const label = typeof args.label === "string" && args.label.length ? args.label : defaultLabel();
4027
- const p = await newTrackedPage(driver, backendOf(driver), { url: args.url, label });
4323
+ const p = await newTrackedPage(driver, backendOf(driver), { url: args.url, label, focus: args.focus === true });
4324
+ const hidden = p.hidden === true ? { hidden: true } : {};
4028
4325
  const explicit = args.claim === true;
4029
4326
  if (!explicit && !requireLease())
4030
- return { targetId: p.id, url: p.url };
4327
+ return { targetId: p.id, url: p.url, ...hidden };
4031
4328
  const { record, token } = await claimLease(backendOf(driver), p.id, {
4032
4329
  label,
4033
4330
  ttlMs: typeof args.ttlMs === "number" && args.ttlMs > 0 ? args.ttlMs : leaseTtlMs(),
4034
4331
  auto: !explicit
4035
4332
  });
4036
4333
  await installBeacon(driver, p.id);
4037
- return { targetId: p.id, url: p.url, lease: token, label: record.label, expiresAt: record.lastUsedAt + record.ttlMs };
4334
+ return { targetId: p.id, url: p.url, ...hidden, lease: token, label: record.label, expiresAt: record.lastUsedAt + record.ttlMs };
4038
4335
  }
4039
4336
  async function closePage(driver, args) {
4040
4337
  if (args.target === undefined || args.target === "")
@@ -4047,16 +4344,41 @@ async function closePage(driver, args) {
4047
4344
  return { closed: p.id, success: true, ...released.released ? { leaseReleased: true } : {} };
4048
4345
  }
4049
4346
  async function writeSelectedFile(id) {
4050
- await mkdir5(STATE_DIR, { recursive: true });
4051
- await writeFile4(join5(STATE_DIR, "selected"), id, "utf8");
4347
+ const stateDir = process.env.CDP_STATE_DIR ?? "/tmp/cdp-toolkit";
4348
+ await mkdir5(stateDir, { recursive: true });
4349
+ await writeFile4(join5(stateDir, "selected"), id, "utf8");
4052
4350
  }
4053
4351
  async function selectPage(driver, args) {
4054
4352
  if (args.target === undefined || args.target === "")
4055
4353
  throw new SharedToolError("select_page requires an explicit target");
4056
4354
  const p = await resolvePage(driver, args.target);
4057
- const activated = await driver.activatePage(p.id);
4058
- await writeSelectedFile(activated.id);
4059
- return { selected: activated.id };
4355
+ if (args.focus !== true) {
4356
+ await writeSelectedFile(p.id);
4357
+ return { selected: p.id, focused: false };
4358
+ }
4359
+ const shown = await driver.activatePage(p.id);
4360
+ if (shown.revealedFrom === undefined || shown.id === p.id) {
4361
+ await writeSelectedFile(shown.id);
4362
+ return { selected: shown.id, focused: true };
4363
+ }
4364
+ const moved = await moveRevealedTab(backendOf(driver), shown.revealedFrom, shown.id);
4365
+ await writeSelectedFile(shown.id);
4366
+ return { selected: shown.id, focused: true, revealedFrom: shown.revealedFrom, ...moved.lease ? { lease: moved.lease } : {} };
4367
+ }
4368
+ async function moveRevealedTab(backend, fromId, toId) {
4369
+ const origin = await readOrigin(backend, fromId).catch(() => {
4370
+ return;
4371
+ });
4372
+ if (origin)
4373
+ await recordOrigin(backend, toId, { label: origin.label, now: origin.createdAt });
4374
+ const lease = await readLease(backend, fromId).catch(() => {
4375
+ return;
4376
+ });
4377
+ if (!lease)
4378
+ return {};
4379
+ await releaseLeaseFor(backend, fromId);
4380
+ const { token } = await claimLease(backend, toId, { label: lease.label, ttlMs: lease.ttlMs, auto: lease.auto === true });
4381
+ return { lease: token };
4060
4382
  }
4061
4383
  function toLegacyWaitedFor(w) {
4062
4384
  if (w === "committed")
@@ -4415,14 +4737,17 @@ async function drag(driver, args) {
4415
4737
  };
4416
4738
  });
4417
4739
  }
4740
+ function inputPathField(path) {
4741
+ return path && path !== "trusted" ? { inputPath: path } : {};
4742
+ }
4418
4743
  async function fill(driver, args) {
4419
4744
  if (typeof args.value !== "string")
4420
4745
  throw new SharedToolError("fill requires a string { value }");
4421
4746
  const loc = locatorOf(args);
4422
4747
  return withPage2(driver, args.target, async (page) => {
4423
4748
  const element = await describeElement(page, loc);
4424
- await page.setValue(loc, args.value);
4425
- return { filled: true, ...elementField(element), value: args.value };
4749
+ const path = await page.setValue(loc, args.value);
4750
+ return { filled: true, ...elementField(element), value: args.value, ...inputPathField(path) };
4426
4751
  });
4427
4752
  }
4428
4753
  async function fillForm(driver, args) {
@@ -4431,15 +4756,16 @@ async function fillForm(driver, args) {
4431
4756
  return withPage2(driver, args.target, async (page) => {
4432
4757
  let filled = 0;
4433
4758
  const elements = [];
4759
+ const paths = [];
4434
4760
  for (const f of args.fields) {
4435
4761
  if (typeof f.value !== "string")
4436
4762
  throw new SharedToolError("each fill_form field requires a string value");
4437
4763
  const loc = locatorOf(f);
4438
4764
  elements.push(await describeElement(page, loc) ?? null);
4439
- await page.setValue(loc, f.value);
4765
+ paths.push(await page.setValue(loc, f.value) || "trusted");
4440
4766
  filled++;
4441
4767
  }
4442
- return { filled, fields: args.fields.length, elements };
4768
+ return { filled, fields: args.fields.length, elements, ...paths.some((p) => p !== "trusted") ? { inputPaths: paths } : {} };
4443
4769
  });
4444
4770
  }
4445
4771
  async function typeText(driver, args) {
@@ -4448,8 +4774,8 @@ async function typeText(driver, args) {
4448
4774
  const loc = locatorOf(args);
4449
4775
  return withPage2(driver, args.target, async (page) => {
4450
4776
  const element = await describeElement(page, loc);
4451
- await page.typeText(loc, args.text);
4452
- return { typed: true, ...elementField(element), text: args.text };
4777
+ const path = await page.typeText(loc, args.text);
4778
+ return { typed: true, ...elementField(element), text: args.text, ...inputPathField(path) };
4453
4779
  });
4454
4780
  }
4455
4781
  async function pressKey(driver, args) {
@@ -4457,7 +4783,15 @@ async function pressKey(driver, args) {
4457
4783
  throw new SharedToolError("press_key requires a non-empty { key }");
4458
4784
  const modifiers = args.modifiers ?? [];
4459
4785
  return withPage2(driver, args.target, async (page) => {
4460
- await page.pressKey({ key: args.key, modifiers });
4786
+ const res = await page.pressKey({ key: args.key, modifiers });
4787
+ if (res && res.delivered === false) {
4788
+ return {
4789
+ pressed: args.key,
4790
+ modifiers,
4791
+ delivered: false,
4792
+ note: "the page saw no keydown: a background tab gets no trusted keyboard input. A click on the tab's page (click tool) usually gives it focus so keys land; or open the tab with new_page focus:true. A key handled inside a cross-origin iframe also reads as not delivered."
4793
+ };
4794
+ }
4461
4795
  return { pressed: args.key, modifiers };
4462
4796
  });
4463
4797
  }
@@ -4710,6 +5044,7 @@ async function claimPage(driver, args = {}) {
4710
5044
  let targetId;
4711
5045
  let url;
4712
5046
  let opened;
5047
+ let hidden = false;
4713
5048
  if (hasTarget) {
4714
5049
  const hit = await pickPage(driver, pages, args.target).catch((err) => {
4715
5050
  throw new LeaseToolError(`claim_page: no open tab matches target '${args.target}' (${err.message}). No tab was opened: claim_page never creates one when 'target' is given.`);
@@ -4725,10 +5060,11 @@ async function claimPage(driver, args = {}) {
4725
5060
  url = existing.url;
4726
5061
  opened = false;
4727
5062
  } else {
4728
- const page = await newTrackedPage(driver, backend, { url: args.url, label });
5063
+ const page = await newTrackedPage(driver, backend, { url: args.url, label, focus: args.focus === true });
4729
5064
  targetId = page.id;
4730
5065
  url = page.url;
4731
5066
  opened = true;
5067
+ hidden = page.hidden === true;
4732
5068
  }
4733
5069
  const humanMs = opened ? null : await readHumanActiveMs(driver, backend, targetId);
4734
5070
  const liveIds = [...pages.map((p) => p.id), targetId];
@@ -4747,6 +5083,7 @@ async function claimPage(driver, args = {}) {
4747
5083
  ttlMs: record.ttlMs,
4748
5084
  expiresAt: record.lastUsedAt + record.ttlMs,
4749
5085
  opened,
5086
+ ...hidden ? { hidden: true } : {},
4750
5087
  ...beaconSupported(driver) ? { humanActiveMs: humanMs } : {},
4751
5088
  ...contention !== undefined ? { contention } : {}
4752
5089
  };
@@ -5225,7 +5562,7 @@ init_client();
5225
5562
  import { mkdir as mkdir7, readFile as readFile7, writeFile as writeFile6, stat, unlink as unlink4 } from "node:fs/promises";
5226
5563
  import { join as join6 } from "node:path";
5227
5564
  var ARTIFACT_DIR2 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
5228
- var STATE_DIR2 = process.env.CDP_STATE_DIR ?? "/tmp/cdp-toolkit";
5565
+ var STATE_DIR = process.env.CDP_STATE_DIR ?? "/tmp/cdp-toolkit";
5229
5566
  var DEFAULT_CATEGORIES = [
5230
5567
  "devtools.timeline",
5231
5568
  "blink.user_timing",
@@ -5241,7 +5578,7 @@ function shortId(id) {
5241
5578
  return id.slice(0, 8);
5242
5579
  }
5243
5580
  function stateFilePath() {
5244
- return join6(STATE_DIR2, "trace-state.json");
5581
+ return join6(STATE_DIR, "trace-state.json");
5245
5582
  }
5246
5583
  function bufferTraceData(conn, sink) {
5247
5584
  return conn.on("Tracing.dataCollected", (params) => {
@@ -5286,7 +5623,7 @@ async function performanceStartTrace(args = {}) {
5286
5623
  throw err;
5287
5624
  }
5288
5625
  liveTraces.set(target.id, { conn, target, events, startedAt: Date.now() });
5289
- await mkdir7(STATE_DIR2, { recursive: true });
5626
+ await mkdir7(STATE_DIR, { recursive: true });
5290
5627
  const state = {
5291
5628
  targetId: target.id,
5292
5629
  url: target.url,
@@ -5615,7 +5952,7 @@ function buildFfmpegArgs(manifestPath, outPath, choice) {
5615
5952
  outPath
5616
5953
  ];
5617
5954
  }
5618
- function run(bin, args) {
5955
+ function run2(bin, args) {
5619
5956
  return new Promise((resolve, reject) => {
5620
5957
  const child = spawn(bin, args, { stdio: ["ignore", "pipe", "pipe"] });
5621
5958
  let stdout = "";
@@ -5637,7 +5974,7 @@ async function probeEncoder() {
5637
5974
  encoderProbe = (async () => {
5638
5975
  let res;
5639
5976
  try {
5640
- res = await run(FFMPEG_BIN, ["-hide_banner", "-encoders"]);
5977
+ res = await run2(FFMPEG_BIN, ["-hide_banner", "-encoders"]);
5641
5978
  } catch (err) {
5642
5979
  throw new CdpError(`${FFMPEG_MISSING} (${err.message})`);
5643
5980
  }
@@ -5646,7 +5983,7 @@ async function probeEncoder() {
5646
5983
  const choice = selectEncoder(`${res.stdout}
5647
5984
  ${res.stderr}`);
5648
5985
  const output = async (args) => {
5649
- const r = await run(FFMPEG_BIN, args).catch(() => {
5986
+ const r = await run2(FFMPEG_BIN, args).catch(() => {
5650
5987
  return;
5651
5988
  });
5652
5989
  return r && r.code === 0 ? `${r.stdout}
@@ -5819,7 +6156,7 @@ async function stopScreenRecording(args = {}) {
5819
6156
  const { width, height } = evenDimensions(ledger[0].width, ledger[0].height);
5820
6157
  let res;
5821
6158
  try {
5822
- res = await run(FFMPEG_BIN, buildFfmpegArgs(manifestPath, outPath, rec.encoder));
6159
+ res = await run2(FFMPEG_BIN, buildFfmpegArgs(manifestPath, outPath, rec.encoder));
5823
6160
  } catch (err) {
5824
6161
  throw new CdpError(`${FFMPEG_MISSING} Spooled frames kept at ${rec.spoolDir}. (${err.message})`);
5825
6162
  }