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/cli.js CHANGED
@@ -323,6 +323,9 @@ function leaseTtlMs() {
323
323
  function markLongLivedProcess(value = true) {
324
324
  longLived = value;
325
325
  }
326
+ function isLongLivedProcess() {
327
+ return longLived;
328
+ }
326
329
  function requireLease() {
327
330
  if (!longLived)
328
331
  return false;
@@ -687,7 +690,7 @@ async function originIndex(backend, liveIds) {
687
690
  return index;
688
691
  }
689
692
  async function newTrackedPage(driver, backend, opts = {}) {
690
- const page = await driver.newPage(opts.url);
693
+ const page = await driver.newPage(opts.url, { focus: opts.focus === true });
691
694
  await recordOrigin(backend, page.id, { label: opts.label });
692
695
  return page;
693
696
  }
@@ -1001,6 +1004,165 @@ var init_session = __esm(() => {
1001
1004
  init_endpoint();
1002
1005
  });
1003
1006
 
1007
+ // src/cdp/hiddenTabs.ts
1008
+ function hiddenTabsRequested() {
1009
+ return TRUTHY.has((process.env.CDP_HIDDEN_TABS ?? "").trim().toLowerCase());
1010
+ }
1011
+ function hiddenTabsMax() {
1012
+ const raw = Number(process.env.CDP_HIDDEN_TABS_MAX);
1013
+ return Number.isFinite(raw) && raw >= 1 ? Math.floor(raw) : DEFAULT_HIDDEN_TABS_MAX;
1014
+ }
1015
+
1016
+ class HiddenTabOwner {
1017
+ deps;
1018
+ conn;
1019
+ connecting;
1020
+ tabs = new Map;
1021
+ reserved = 0;
1022
+ constructor(deps) {
1023
+ this.deps = deps;
1024
+ }
1025
+ sweep() {
1026
+ if (this.conn && !this.conn.isOpen) {
1027
+ this.conn = undefined;
1028
+ this.tabs.clear();
1029
+ }
1030
+ }
1031
+ has(id) {
1032
+ this.sweep();
1033
+ return this.tabs.has(id);
1034
+ }
1035
+ ids() {
1036
+ this.sweep();
1037
+ return [...this.tabs.keys()];
1038
+ }
1039
+ async owner() {
1040
+ this.sweep();
1041
+ if (this.conn)
1042
+ return this.conn;
1043
+ if (!this.connecting) {
1044
+ this.connecting = (async () => {
1045
+ const conn = await this.deps.connect();
1046
+ conn.on("Target.targetDestroyed", (params) => {
1047
+ const id = params.targetId;
1048
+ if (typeof id === "string")
1049
+ this.tabs.delete(id);
1050
+ });
1051
+ this.conn = conn;
1052
+ return conn;
1053
+ })().finally(() => {
1054
+ this.connecting = undefined;
1055
+ });
1056
+ }
1057
+ return this.connecting;
1058
+ }
1059
+ async create(url) {
1060
+ this.sweep();
1061
+ const max = (this.deps.max ?? hiddenTabsMax)();
1062
+ if (this.tabs.size + this.reserved >= max)
1063
+ throw new HiddenTabCapError(max, [...this.tabs.keys()]);
1064
+ this.reserved++;
1065
+ try {
1066
+ const conn = await this.owner();
1067
+ const id = await this.deps.createSettled(conn, url, { hidden: true });
1068
+ try {
1069
+ const { sessionId } = await conn.send("Target.attachToTarget", { targetId: id, flatten: true }, { timeoutMs: OWNER_COMMAND_TIMEOUT_MS });
1070
+ const dpr = await conn.send("Runtime.evaluate", { expression: "devicePixelRatio", returnByValue: true }, { sessionId, timeoutMs: OWNER_COMMAND_TIMEOUT_MS }).then((r) => r.result?.value).catch(() => {
1071
+ return;
1072
+ });
1073
+ await conn.send("Emulation.setDeviceMetricsOverride", {
1074
+ width: HIDDEN_TAB_VIEWPORT.width,
1075
+ height: HIDDEN_TAB_VIEWPORT.height,
1076
+ deviceScaleFactor: typeof dpr === "number" && Number.isFinite(dpr) && dpr > 0 ? dpr : FALLBACK_DEVICE_SCALE_FACTOR,
1077
+ mobile: false
1078
+ }, { sessionId, timeoutMs: OWNER_COMMAND_TIMEOUT_MS });
1079
+ this.tabs.set(id, sessionId);
1080
+ return id;
1081
+ } catch (e) {
1082
+ await conn.send("Target.closeTarget", { targetId: id }, { timeoutMs: OWNER_COMMAND_TIMEOUT_MS }).catch(() => {
1083
+ return;
1084
+ });
1085
+ throw e;
1086
+ }
1087
+ } finally {
1088
+ this.reserved--;
1089
+ }
1090
+ }
1091
+ async close(id) {
1092
+ this.sweep();
1093
+ const conn = this.conn;
1094
+ const held = this.tabs.delete(id);
1095
+ if (!conn || !held)
1096
+ return { success: false };
1097
+ const res = await conn.send("Target.closeTarget", { targetId: id }, { timeoutMs: OWNER_COMMAND_TIMEOUT_MS });
1098
+ return { success: res.success ?? true };
1099
+ }
1100
+ async dispose() {
1101
+ const conn = this.conn;
1102
+ const ids = [...this.tabs.keys()];
1103
+ this.tabs.clear();
1104
+ this.conn = undefined;
1105
+ if (!conn)
1106
+ return;
1107
+ if (conn.isOpen) {
1108
+ await Promise.all(ids.map((targetId) => conn.send("Target.closeTarget", { targetId }, { timeoutMs: OWNER_COMMAND_TIMEOUT_MS }).catch(() => {
1109
+ return;
1110
+ })));
1111
+ }
1112
+ conn.close();
1113
+ }
1114
+ }
1115
+ function hiddenTabOwner(base, deps) {
1116
+ let owner = owners.get(base);
1117
+ if (!owner) {
1118
+ owner = new HiddenTabOwner(deps());
1119
+ owners.set(base, owner);
1120
+ }
1121
+ return owner;
1122
+ }
1123
+ function existingHiddenTabOwner(base) {
1124
+ return owners.get(base);
1125
+ }
1126
+ function markHiddenTargets(base, targets) {
1127
+ const owner = owners.get(base);
1128
+ if (!owner)
1129
+ return targets;
1130
+ const hidden = new Set(owner.ids());
1131
+ if (hidden.size === 0)
1132
+ return targets;
1133
+ const visible = [];
1134
+ const marked = [];
1135
+ for (const t of targets) {
1136
+ if (hidden.has(t.id))
1137
+ marked.push({ ...t, type: "page", hidden: true });
1138
+ else
1139
+ visible.push(t);
1140
+ }
1141
+ return marked.length ? [...visible, ...marked] : targets;
1142
+ }
1143
+ async function disposeHiddenTabs() {
1144
+ const all = [...owners.values()];
1145
+ owners.clear();
1146
+ await Promise.all(all.map((o) => o.dispose()));
1147
+ }
1148
+ var DEFAULT_HIDDEN_TABS_MAX = 20, HIDDEN_TAB_VIEWPORT, FALLBACK_DEVICE_SCALE_FACTOR = 2, OWNER_COMMAND_TIMEOUT_MS = 5000, TRUTHY, HiddenTabCapError, owners;
1149
+ var init_hiddenTabs = __esm(() => {
1150
+ HIDDEN_TAB_VIEWPORT = { width: 1280, height: 800 };
1151
+ TRUTHY = new Set(["1", "true", "yes", "on"]);
1152
+ HiddenTabCapError = class HiddenTabCapError extends Error {
1153
+ max;
1154
+ openIds;
1155
+ code = "page-error";
1156
+ constructor(max, openIds) {
1157
+ 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.`);
1158
+ this.max = max;
1159
+ this.openIds = openIds;
1160
+ this.name = "HiddenTabCapError";
1161
+ }
1162
+ };
1163
+ owners = new Map;
1164
+ });
1165
+
1004
1166
  // src/client.ts
1005
1167
  class CdpConnection {
1006
1168
  wsUrl;
@@ -1119,6 +1281,9 @@ class CdpConnection {
1119
1281
  });
1120
1282
  });
1121
1283
  }
1284
+ get isOpen() {
1285
+ return !this.closed && this.ws !== undefined;
1286
+ }
1122
1287
  close() {
1123
1288
  this.closed = true;
1124
1289
  this.rejectAll(new CdpError("closed by caller"));
@@ -1147,11 +1312,11 @@ async function getTargetsOverBrowserWs() {
1147
1312
  async function listTargets() {
1148
1313
  const base = currentEndpoint().base;
1149
1314
  if (knownTransports.get(base) === "browser-ws")
1150
- return getTargetsOverBrowserWs();
1315
+ return markHiddenTargets(base, await getTargetsOverBrowserWs());
1151
1316
  try {
1152
1317
  const listing = await httpJson("/json/list");
1153
1318
  knownTransports.set(base, "http");
1154
- return listing;
1319
+ return markHiddenTargets(base, listing);
1155
1320
  } catch (httpError) {
1156
1321
  const detected = await detectEndpoint().catch(() => {
1157
1322
  return;
@@ -1162,7 +1327,7 @@ async function listTargets() {
1162
1327
  throw httpError;
1163
1328
  });
1164
1329
  knownTransports.set(base, "browser-ws");
1165
- return targets;
1330
+ return markHiddenTargets(base, targets);
1166
1331
  }
1167
1332
  }
1168
1333
  async function browserWsUrl() {
@@ -1275,6 +1440,7 @@ var init_client = __esm(() => {
1275
1440
  init_frames();
1276
1441
  init_endpoint();
1277
1442
  init_session();
1443
+ init_hiddenTabs();
1278
1444
  init_session();
1279
1445
  BASE = (() => {
1280
1446
  try {
@@ -1297,6 +1463,53 @@ var init_client = __esm(() => {
1297
1463
  knownTransports = new Map;
1298
1464
  });
1299
1465
 
1466
+ // src/frontApp.ts
1467
+ import { execFile } from "node:child_process";
1468
+ function run(cmd, args) {
1469
+ return new Promise((resolve) => {
1470
+ execFile(cmd, args, { timeout: 2000 }, (err, stdout) => resolve(err ? "" : String(stdout)));
1471
+ });
1472
+ }
1473
+ function restoreFrontAppEnabled(platform = process.platform) {
1474
+ return platform === "darwin" && (process.env.CDP_RESTORE_FRONT_APP ?? "").trim() !== "0";
1475
+ }
1476
+ async function keepFrontApp(fn, opts = {}) {
1477
+ const enabled = opts.enabled ?? restoreFrontAppEnabled();
1478
+ if (!enabled)
1479
+ return fn();
1480
+ const ops = opts.ops ?? macFrontAppOps;
1481
+ const before = await ops.front().catch(() => null);
1482
+ const result = await fn();
1483
+ if (before === null)
1484
+ return result;
1485
+ const fix = async () => {
1486
+ const now = await ops.front().catch(() => null);
1487
+ if (now !== null && now !== before)
1488
+ await ops.setFront(before).catch(() => {
1489
+ return;
1490
+ });
1491
+ };
1492
+ await fix();
1493
+ await new Promise((r) => setTimeout(r, opts.recheckMs ?? 250));
1494
+ await fix();
1495
+ return result;
1496
+ }
1497
+ var macFrontAppOps;
1498
+ var init_frontApp = __esm(() => {
1499
+ macFrontAppOps = {
1500
+ async front() {
1501
+ const asn = (await run("lsappinfo", ["front"])).trim();
1502
+ if (!asn)
1503
+ return null;
1504
+ const m = /"?pid"?\s*=\s*(\d+)/.exec(await run("lsappinfo", ["info", "-only", "pid", asn]));
1505
+ return m ? Number(m[1]) : null;
1506
+ },
1507
+ async setFront(pid) {
1508
+ await run("osascript", ["-e", `tell application "System Events" to set frontmost of (first process whose unix id is ${pid}) to true`]);
1509
+ }
1510
+ };
1511
+ });
1512
+
1300
1513
  // src/activity.ts
1301
1514
  function dispatchKey(backend, targetId) {
1302
1515
  return `${backend}:${targetId}`;
@@ -3506,6 +3719,9 @@ async function pickContext(conn, contexts, selector) {
3506
3719
  return exact;
3507
3720
  throw driverError2("no-such-target", `no context matching '${selector}'`);
3508
3721
  }
3722
+ function bidiCreateTabParams(opts) {
3723
+ return { type: "tab", background: opts?.focus !== true };
3724
+ }
3509
3725
 
3510
3726
  class BidiBrowserDriver {
3511
3727
  endpoint;
@@ -3532,12 +3748,13 @@ class BidiBrowserDriver {
3532
3748
  conn.release();
3533
3749
  }
3534
3750
  }
3535
- async newPage(url) {
3751
+ async newPage(url, opts) {
3536
3752
  const conn = await getConnection(this.endpoint, this.timeoutMs, this.attached);
3537
3753
  try {
3538
- const { context } = await conn.send("browsingContext.create", { type: "tab" }).catch((e) => {
3754
+ const create = () => conn.send("browsingContext.create", bidiCreateTabParams(opts)).catch((e) => {
3539
3755
  throw mapBidiError(e);
3540
3756
  });
3757
+ const { context } = opts?.focus === true ? await create() : await keepFrontApp(create);
3541
3758
  if (url)
3542
3759
  await conn.send("browsingContext.navigate", { context, url, wait: "complete" }).catch((e) => {
3543
3760
  throw mapBidiError(e);
@@ -3550,9 +3767,9 @@ class BidiBrowserDriver {
3550
3767
  async closePage(id) {
3551
3768
  const conn = await getConnection(this.endpoint, this.timeoutMs, this.attached);
3552
3769
  try {
3553
- await conn.send("browsingContext.close", { context: id }).catch((e) => {
3770
+ await keepFrontApp(() => conn.send("browsingContext.close", { context: id }).catch((e) => {
3554
3771
  throw mapBidiError(e);
3555
- });
3772
+ }));
3556
3773
  return { success: true };
3557
3774
  } finally {
3558
3775
  conn.release();
@@ -3736,6 +3953,7 @@ function createFirefoxDriverForEndpoint(wsUrl, opts) {
3736
3953
  }
3737
3954
  var LINE_RE, INTERACTIVE_ROLES3, STAMP_ONE_SOURCE, KEY_VALUES, MODIFIER_VALUES, BUTTON_CODES, RAW_MOUSE_SOURCE_ID = "cdp-raw-mouse", ARM_SCROLL_SETTLE_WATCH_SOURCE, AWAIT_SCROLL_SETTLE_SOURCE = "function(){return window.__cdpScrollSettle;}", BIDI_CAPABILITY_MIN_FIREFOX, POST_HOC_BODY_MAX_BYTES, BIDI_CAPABILITIES, connections, slotHandles, muxes, joined, connecting, sessionEpochs, connEndpoints, disposeHooks, STALE_ID_HINT, sleep3 = (ms) => new Promise((r) => setTimeout(r, ms)), slotLabelOverride, bidiBeaconScripts, BidiPageDriver;
3738
3955
  var init_driver2 = __esm(() => {
3956
+ init_frontApp();
3739
3957
  init_driver();
3740
3958
  init_leases();
3741
3959
  init_origins();
@@ -4077,8 +4295,11 @@ var init_driver2 = __esm(() => {
4077
4295
  await this.callFunctionValue(BidiPageDriver.INSERT_TEXT_SOURCE, [value, false], ref);
4078
4296
  return;
4079
4297
  }
4080
- const clear = "function(){this.focus&&this.focus();if('value' in this){this.value='';this.dispatchEvent(new Event('input',{bubbles:true}));}}";
4081
- await this.callFunctionValue(clear, [], ref);
4298
+ const clear = "function(){if(this.disabled||this.readOnly)return this.disabled?'disabled':'readonly';this.focus&&this.focus();if('value' in this){this.value='';this.dispatchEvent(new Event('input',{bubbles:true}));}return 'ok';}";
4299
+ const state = await this.callFunctionValue(clear, [], ref);
4300
+ if (state === "disabled" || state === "readonly") {
4301
+ throw driverError2("page-error", `cannot fill a ${state} field: it was left unchanged`);
4302
+ }
4082
4303
  await this.sendKeys(value);
4083
4304
  }
4084
4305
  async typeText(loc, text) {
@@ -4473,7 +4694,9 @@ var init_driver2 = __esm(() => {
4473
4694
  // src/cdp/driver.ts
4474
4695
  init_client();
4475
4696
  init_session();
4697
+ init_frontApp();
4476
4698
  init_leases();
4699
+ init_hiddenTabs();
4477
4700
  init_endpoints();
4478
4701
  init_activity();
4479
4702
 
@@ -4650,6 +4873,47 @@ async function centerOf(conn, objectId) {
4650
4873
  throw driverError("page-error", "element has zero size / is not visible; cannot compute a click point");
4651
4874
  return result.value;
4652
4875
  }
4876
+ 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);}";
4877
+ 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);});}";
4878
+ 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';}";
4879
+ async function insertTextVerified(conn, objectId, text, sendInput) {
4880
+ const call = async (fn, args = [], awaitPromise = false) => {
4881
+ const { result, exceptionDetails } = await conn.send("Runtime.callFunctionOn", {
4882
+ objectId,
4883
+ functionDeclaration: fn,
4884
+ arguments: args.map((value) => ({ value })),
4885
+ returnByValue: true,
4886
+ awaitPromise
4887
+ });
4888
+ if (exceptionDetails)
4889
+ throw driverError("page-error", `text input check failed: ${exceptionDetails.text ?? "error"}`);
4890
+ return result?.value;
4891
+ };
4892
+ const before = await call(SNAPSHOT_TEXT_FN);
4893
+ await sendInput("Input.insertText", { text });
4894
+ if (await call(LANDED_TEXT_FN, [before], true) === true)
4895
+ return "trusted";
4896
+ const via = await call(FALLBACK_TEXT_FN, [text]);
4897
+ if (via === "execCommand" || via === "setter" || via === "skipped")
4898
+ return via;
4899
+ 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");
4900
+ }
4901
+ var ARM_KEY_WITNESS = "(function(){window.__cdpKeySeen=false;window.addEventListener('keydown',function(){window.__cdpKeySeen=true;},{capture:true,once:true});return true;})()";
4902
+ var READ_KEY_WITNESS = "(function(){if(window.__cdpKeySeen===true)return true;return new Promise(function(r){setTimeout(function(){r(window.__cdpKeySeen===true);},50);});})()";
4903
+ async function pressKeyObserved(conn, dispatch) {
4904
+ const eval_ = (expression, awaitPromise = false) => conn.send("Runtime.evaluate", { expression, returnByValue: true, awaitPromise }).then((r) => r.result?.value, () => {
4905
+ return;
4906
+ });
4907
+ const armed = await eval_(ARM_KEY_WITNESS) === true;
4908
+ await dispatch();
4909
+ if (!armed)
4910
+ return;
4911
+ const seen = await eval_(READ_KEY_WITNESS, true);
4912
+ if (seen === false)
4913
+ return { delivered: false };
4914
+ if (seen === true)
4915
+ return { delivered: true };
4916
+ }
4653
4917
  async function focusElement(conn, objectId) {
4654
4918
  await conn.send("Runtime.callFunctionOn", { objectId, functionDeclaration: "function(){this.focus&&this.focus();}", returnByValue: true });
4655
4919
  }
@@ -4664,10 +4928,12 @@ async function awaitScrollSettle(conn) {
4664
4928
  }
4665
4929
  async function setValueOnObject(conn, objectId, value, sendInput) {
4666
4930
  await focusElement(conn, objectId);
4667
- const fn = "function(){if('value'in this){this.value='';this.dispatchEvent(new Event('input',{bubbles:true}));}else if(this.isContentEditable){this.textContent='';}}";
4668
- await conn.send("Runtime.callFunctionOn", { objectId, functionDeclaration: fn, returnByValue: true });
4669
- if (value.length)
4670
- await sendInput("Input.insertText", { text: value });
4931
+ 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';}";
4932
+ const { result } = await conn.send("Runtime.callFunctionOn", { objectId, functionDeclaration: fn, returnByValue: true });
4933
+ if (result?.value === "disabled" || result?.value === "readonly") {
4934
+ throw driverError("page-error", `cannot fill a ${result.value} field: it was left unchanged`);
4935
+ }
4936
+ return value.length ? insertTextVerified(conn, objectId, value, sendInput) : "trusted";
4671
4937
  }
4672
4938
  var NAMED_KEYS = {
4673
4939
  enter: { key: "Enter", code: "Enter", keyCode: 13, text: "\r" },
@@ -5215,13 +5481,12 @@ class CdpPageDriver {
5215
5481
  }
5216
5482
  async setValue(loc, value) {
5217
5483
  const { objectId } = await resolveElementLocator(this.conn, loc);
5218
- await setValueOnObject(this.conn, objectId, value, (method, params) => this.dispatchInput(method, params));
5484
+ return setValueOnObject(this.conn, objectId, value, (method, params) => this.dispatchInput(method, params));
5219
5485
  }
5220
5486
  async typeText(loc, text) {
5221
5487
  const { objectId } = await resolveElementLocator(this.conn, loc);
5222
5488
  await focusElement(this.conn, objectId);
5223
- if (text.length)
5224
- await this.dispatchInput("Input.insertText", { text });
5489
+ return text.length ? insertTextVerified(this.conn, objectId, text, (method, params) => this.dispatchInput(method, params)) : "trusted";
5225
5490
  }
5226
5491
  async pressKey(press) {
5227
5492
  const spec = resolveKey(press.key);
@@ -5236,8 +5501,10 @@ class CdpPageDriver {
5236
5501
  const down = { type: "keyDown", key: spec.key, code: spec.code, windowsVirtualKeyCode: spec.keyCode, nativeVirtualKeyCode: spec.keyCode, modifiers: modBits };
5237
5502
  if (spec.text && !suppressText)
5238
5503
  down.text = spec.text;
5239
- await this.dispatchInput("Input.dispatchKeyEvent", down);
5240
- await this.dispatchInput("Input.dispatchKeyEvent", { type: "keyUp", key: spec.key, code: spec.code, windowsVirtualKeyCode: spec.keyCode, nativeVirtualKeyCode: spec.keyCode, modifiers: modBits });
5504
+ return pressKeyObserved(this.conn, async () => {
5505
+ await this.dispatchInput("Input.dispatchKeyEvent", down);
5506
+ await this.dispatchInput("Input.dispatchKeyEvent", { type: "keyUp", key: spec.key, code: spec.code, windowsVirtualKeyCode: spec.keyCode, nativeVirtualKeyCode: spec.keyCode, modifiers: modBits });
5507
+ });
5241
5508
  }
5242
5509
  async setFiles(loc, files) {
5243
5510
  const { objectId } = await resolveElementLocator(this.conn, loc);
@@ -5614,7 +5881,7 @@ function noSuchTarget(e) {
5614
5881
  throw driverError("no-such-target", e instanceof CdpError ? e.message : String(e));
5615
5882
  }
5616
5883
  var NEW_TARGET_SETTLE_MS = 2000;
5617
- async function createSettledTarget(conn, url, settleMs = NEW_TARGET_SETTLE_MS) {
5884
+ async function createSettledTarget(conn, url, settleMs = NEW_TARGET_SETTLE_MS, opts = {}) {
5618
5885
  const changed = new Set;
5619
5886
  let id = "";
5620
5887
  let wake;
@@ -5630,7 +5897,10 @@ async function createSettledTarget(conn, url, settleMs = NEW_TARGET_SETTLE_MS) {
5630
5897
  await conn.send("Target.setDiscoverTargets", { discover: true }).catch(() => {
5631
5898
  return;
5632
5899
  });
5633
- const { targetId } = await conn.send("Target.createTarget", { url });
5900
+ const hidden = opts.hidden === true;
5901
+ const params = hidden ? { url, background: true, hidden: true } : { url, background: opts.focus !== true };
5902
+ const create = () => conn.send("Target.createTarget", params);
5903
+ const { targetId } = opts.focus === true || hidden ? await create() : await keepFrontApp(create);
5634
5904
  if (!targetId)
5635
5905
  throw driverError("page-error", "Target.createTarget returned no targetId");
5636
5906
  id = targetId;
@@ -5648,6 +5918,19 @@ async function createSettledTarget(conn, url, settleMs = NEW_TARGET_SETTLE_MS) {
5648
5918
  off();
5649
5919
  }
5650
5920
  }
5921
+ function hiddenTabsEnabled() {
5922
+ return hiddenTabsRequested() && isLongLivedProcess();
5923
+ }
5924
+ function currentHiddenOwner() {
5925
+ return hiddenTabOwner(currentEndpoint().base, () => ({
5926
+ connect: () => openBrowser(),
5927
+ createSettled: (conn, url, opts) => createSettledTarget(conn, url, NEW_TARGET_SETTLE_MS, opts)
5928
+ }));
5929
+ }
5930
+ function hiddenOwnerOf(id) {
5931
+ const owner = existingHiddenTabOwner(currentEndpoint().base);
5932
+ return owner?.has(id) ? owner : undefined;
5933
+ }
5651
5934
 
5652
5935
  class CdpBrowserDriver {
5653
5936
  scheme = "cdp";
@@ -5658,17 +5941,28 @@ class CdpBrowserDriver {
5658
5941
  async listPages(opts) {
5659
5942
  const targets = await listTargets();
5660
5943
  const filtered = opts?.all ? targets : targets.filter((t) => t.type === "page");
5661
- return filtered.map((t) => ({ id: t.id, url: t.url, title: t.title, type: t.type }));
5944
+ return filtered.map((t) => ({ id: t.id, url: t.url, title: t.title, type: t.type, ...t.hidden ? { hidden: true } : {} }));
5662
5945
  }
5663
- async newPage(url) {
5946
+ async newPage(url, opts) {
5947
+ if (opts?.focus !== true && hiddenTabsEnabled()) {
5948
+ const id = await currentHiddenOwner().create(url ?? "about:blank");
5949
+ return { id, url: url ?? "about:blank", title: "", hidden: true };
5950
+ }
5664
5951
  return withBrowserConn(async (conn) => {
5665
- const targetId = await createSettledTarget(conn, url ?? "about:blank");
5952
+ const targetId = await createSettledTarget(conn, url ?? "about:blank", NEW_TARGET_SETTLE_MS, { focus: opts?.focus === true });
5666
5953
  return { id: targetId, url: url ?? "about:blank", title: "" };
5667
5954
  });
5668
5955
  }
5669
5956
  async closePage(id) {
5957
+ const owner = hiddenOwnerOf(id);
5958
+ if (owner) {
5959
+ const res = await owner.close(id);
5960
+ if (res.success)
5961
+ beaconSessions.drop(beaconKey(id));
5962
+ return res;
5963
+ }
5670
5964
  return withBrowserConn(async (conn) => {
5671
- const res = await conn.send("Target.closeTarget", { targetId: id });
5965
+ const res = await keepFrontApp(() => conn.send("Target.closeTarget", { targetId: id }));
5672
5966
  if (res.success !== false)
5673
5967
  beaconSessions.drop(beaconKey(id));
5674
5968
  return { success: res.success ?? true };
@@ -5676,6 +5970,16 @@ class CdpBrowserDriver {
5676
5970
  }
5677
5971
  async activatePage(id) {
5678
5972
  const target = await resolveTarget(id).catch(noSuchTarget);
5973
+ const owner = hiddenOwnerOf(target.id);
5974
+ if (owner) {
5975
+ const url = target.url || "about:blank";
5976
+ const newId = await withBrowserConn((conn) => createSettledTarget(conn, url, NEW_TARGET_SETTLE_MS, { focus: true }));
5977
+ await owner.close(target.id).catch(() => {
5978
+ return;
5979
+ });
5980
+ beaconSessions.drop(beaconKey(target.id));
5981
+ return { id: newId, url, title: target.title, revealedFrom: target.id };
5982
+ }
5679
5983
  await withBrowserConn((conn) => conn.send("Target.activateTarget", { targetId: target.id }));
5680
5984
  return { id: target.id, url: target.url, title: target.title };
5681
5985
  }
@@ -5749,6 +6053,7 @@ class CdpBrowserDriver {
5749
6053
  }
5750
6054
  async dispose() {
5751
6055
  beaconSessions.clear();
6056
+ await disposeHiddenTabs();
5752
6057
  }
5753
6058
  }
5754
6059
  function createCdpDriver() {
@@ -6338,7 +6643,6 @@ init_workers();
6338
6643
  init_frames();
6339
6644
  init_endpoints();
6340
6645
  var ARTIFACT_DIR = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
6341
- var STATE_DIR = process.env.CDP_STATE_DIR ?? "/tmp/cdp-toolkit";
6342
6646
 
6343
6647
  class SharedToolError extends Error {
6344
6648
  }
@@ -6497,17 +6801,18 @@ async function listPagesOne(driver, args = {}) {
6497
6801
  }
6498
6802
  async function newPage(driver, args = {}) {
6499
6803
  const label = typeof args.label === "string" && args.label.length ? args.label : defaultLabel();
6500
- const p = await newTrackedPage(driver, backendOf(driver), { url: args.url, label });
6804
+ const p = await newTrackedPage(driver, backendOf(driver), { url: args.url, label, focus: args.focus === true });
6805
+ const hidden = p.hidden === true ? { hidden: true } : {};
6501
6806
  const explicit = args.claim === true;
6502
6807
  if (!explicit && !requireLease())
6503
- return { targetId: p.id, url: p.url };
6808
+ return { targetId: p.id, url: p.url, ...hidden };
6504
6809
  const { record, token } = await claimLease(backendOf(driver), p.id, {
6505
6810
  label,
6506
6811
  ttlMs: typeof args.ttlMs === "number" && args.ttlMs > 0 ? args.ttlMs : leaseTtlMs(),
6507
6812
  auto: !explicit
6508
6813
  });
6509
6814
  await installBeacon(driver, p.id);
6510
- return { targetId: p.id, url: p.url, lease: token, label: record.label, expiresAt: record.lastUsedAt + record.ttlMs };
6815
+ return { targetId: p.id, url: p.url, ...hidden, lease: token, label: record.label, expiresAt: record.lastUsedAt + record.ttlMs };
6511
6816
  }
6512
6817
  async function closePage(driver, args) {
6513
6818
  if (args.target === undefined || args.target === "")
@@ -6520,16 +6825,41 @@ async function closePage(driver, args) {
6520
6825
  return { closed: p.id, success: true, ...released.released ? { leaseReleased: true } : {} };
6521
6826
  }
6522
6827
  async function writeSelectedFile(id) {
6523
- await mkdir5(STATE_DIR, { recursive: true });
6524
- await writeFile4(join5(STATE_DIR, "selected"), id, "utf8");
6828
+ const stateDir = process.env.CDP_STATE_DIR ?? "/tmp/cdp-toolkit";
6829
+ await mkdir5(stateDir, { recursive: true });
6830
+ await writeFile4(join5(stateDir, "selected"), id, "utf8");
6525
6831
  }
6526
6832
  async function selectPage(driver, args) {
6527
6833
  if (args.target === undefined || args.target === "")
6528
6834
  throw new SharedToolError("select_page requires an explicit target");
6529
6835
  const p = await resolvePage(driver, args.target);
6530
- const activated = await driver.activatePage(p.id);
6531
- await writeSelectedFile(activated.id);
6532
- return { selected: activated.id };
6836
+ if (args.focus !== true) {
6837
+ await writeSelectedFile(p.id);
6838
+ return { selected: p.id, focused: false };
6839
+ }
6840
+ const shown = await driver.activatePage(p.id);
6841
+ if (shown.revealedFrom === undefined || shown.id === p.id) {
6842
+ await writeSelectedFile(shown.id);
6843
+ return { selected: shown.id, focused: true };
6844
+ }
6845
+ const moved = await moveRevealedTab(backendOf(driver), shown.revealedFrom, shown.id);
6846
+ await writeSelectedFile(shown.id);
6847
+ return { selected: shown.id, focused: true, revealedFrom: shown.revealedFrom, ...moved.lease ? { lease: moved.lease } : {} };
6848
+ }
6849
+ async function moveRevealedTab(backend, fromId, toId) {
6850
+ const origin = await readOrigin(backend, fromId).catch(() => {
6851
+ return;
6852
+ });
6853
+ if (origin)
6854
+ await recordOrigin(backend, toId, { label: origin.label, now: origin.createdAt });
6855
+ const lease = await readLease(backend, fromId).catch(() => {
6856
+ return;
6857
+ });
6858
+ if (!lease)
6859
+ return {};
6860
+ await releaseLeaseFor(backend, fromId);
6861
+ const { token } = await claimLease(backend, toId, { label: lease.label, ttlMs: lease.ttlMs, auto: lease.auto === true });
6862
+ return { lease: token };
6533
6863
  }
6534
6864
  function toLegacyWaitedFor(w) {
6535
6865
  if (w === "committed")
@@ -6888,14 +7218,17 @@ async function drag(driver, args) {
6888
7218
  };
6889
7219
  });
6890
7220
  }
7221
+ function inputPathField(path) {
7222
+ return path && path !== "trusted" ? { inputPath: path } : {};
7223
+ }
6891
7224
  async function fill(driver, args) {
6892
7225
  if (typeof args.value !== "string")
6893
7226
  throw new SharedToolError("fill requires a string { value }");
6894
7227
  const loc = locatorOf(args);
6895
7228
  return withPage2(driver, args.target, async (page) => {
6896
7229
  const element = await describeElement(page, loc);
6897
- await page.setValue(loc, args.value);
6898
- return { filled: true, ...elementField(element), value: args.value };
7230
+ const path = await page.setValue(loc, args.value);
7231
+ return { filled: true, ...elementField(element), value: args.value, ...inputPathField(path) };
6899
7232
  });
6900
7233
  }
6901
7234
  async function fillForm(driver, args) {
@@ -6904,15 +7237,16 @@ async function fillForm(driver, args) {
6904
7237
  return withPage2(driver, args.target, async (page) => {
6905
7238
  let filled = 0;
6906
7239
  const elements = [];
7240
+ const paths = [];
6907
7241
  for (const f of args.fields) {
6908
7242
  if (typeof f.value !== "string")
6909
7243
  throw new SharedToolError("each fill_form field requires a string value");
6910
7244
  const loc = locatorOf(f);
6911
7245
  elements.push(await describeElement(page, loc) ?? null);
6912
- await page.setValue(loc, f.value);
7246
+ paths.push(await page.setValue(loc, f.value) || "trusted");
6913
7247
  filled++;
6914
7248
  }
6915
- return { filled, fields: args.fields.length, elements };
7249
+ return { filled, fields: args.fields.length, elements, ...paths.some((p) => p !== "trusted") ? { inputPaths: paths } : {} };
6916
7250
  });
6917
7251
  }
6918
7252
  async function typeText(driver, args) {
@@ -6921,8 +7255,8 @@ async function typeText(driver, args) {
6921
7255
  const loc = locatorOf(args);
6922
7256
  return withPage2(driver, args.target, async (page) => {
6923
7257
  const element = await describeElement(page, loc);
6924
- await page.typeText(loc, args.text);
6925
- return { typed: true, ...elementField(element), text: args.text };
7258
+ const path = await page.typeText(loc, args.text);
7259
+ return { typed: true, ...elementField(element), text: args.text, ...inputPathField(path) };
6926
7260
  });
6927
7261
  }
6928
7262
  async function pressKey(driver, args) {
@@ -6930,7 +7264,15 @@ async function pressKey(driver, args) {
6930
7264
  throw new SharedToolError("press_key requires a non-empty { key }");
6931
7265
  const modifiers = args.modifiers ?? [];
6932
7266
  return withPage2(driver, args.target, async (page) => {
6933
- await page.pressKey({ key: args.key, modifiers });
7267
+ const res = await page.pressKey({ key: args.key, modifiers });
7268
+ if (res && res.delivered === false) {
7269
+ return {
7270
+ pressed: args.key,
7271
+ modifiers,
7272
+ delivered: false,
7273
+ 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."
7274
+ };
7275
+ }
6934
7276
  return { pressed: args.key, modifiers };
6935
7277
  });
6936
7278
  }
@@ -7183,6 +7525,7 @@ async function claimPage(driver, args = {}) {
7183
7525
  let targetId;
7184
7526
  let url;
7185
7527
  let opened;
7528
+ let hidden = false;
7186
7529
  if (hasTarget) {
7187
7530
  const hit = await pickPage(driver, pages, args.target).catch((err) => {
7188
7531
  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.`);
@@ -7198,10 +7541,11 @@ async function claimPage(driver, args = {}) {
7198
7541
  url = existing.url;
7199
7542
  opened = false;
7200
7543
  } else {
7201
- const page = await newTrackedPage(driver, backend, { url: args.url, label });
7544
+ const page = await newTrackedPage(driver, backend, { url: args.url, label, focus: args.focus === true });
7202
7545
  targetId = page.id;
7203
7546
  url = page.url;
7204
7547
  opened = true;
7548
+ hidden = page.hidden === true;
7205
7549
  }
7206
7550
  const humanMs = opened ? null : await readHumanActiveMs(driver, backend, targetId);
7207
7551
  const liveIds = [...pages.map((p) => p.id), targetId];
@@ -7220,6 +7564,7 @@ async function claimPage(driver, args = {}) {
7220
7564
  ttlMs: record.ttlMs,
7221
7565
  expiresAt: record.lastUsedAt + record.ttlMs,
7222
7566
  opened,
7567
+ ...hidden ? { hidden: true } : {},
7223
7568
  ...beaconSupported(driver) ? { humanActiveMs: humanMs } : {},
7224
7569
  ...contention !== undefined ? { contention } : {}
7225
7570
  };
@@ -7698,7 +8043,7 @@ init_client();
7698
8043
  import { mkdir as mkdir7, readFile as readFile7, writeFile as writeFile6, stat, unlink as unlink4 } from "node:fs/promises";
7699
8044
  import { join as join6 } from "node:path";
7700
8045
  var ARTIFACT_DIR2 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
7701
- var STATE_DIR2 = process.env.CDP_STATE_DIR ?? "/tmp/cdp-toolkit";
8046
+ var STATE_DIR = process.env.CDP_STATE_DIR ?? "/tmp/cdp-toolkit";
7702
8047
  var DEFAULT_CATEGORIES = [
7703
8048
  "devtools.timeline",
7704
8049
  "blink.user_timing",
@@ -7714,7 +8059,7 @@ function shortId(id) {
7714
8059
  return id.slice(0, 8);
7715
8060
  }
7716
8061
  function stateFilePath() {
7717
- return join6(STATE_DIR2, "trace-state.json");
8062
+ return join6(STATE_DIR, "trace-state.json");
7718
8063
  }
7719
8064
  function bufferTraceData(conn, sink) {
7720
8065
  return conn.on("Tracing.dataCollected", (params) => {
@@ -7759,7 +8104,7 @@ async function performanceStartTrace(args = {}) {
7759
8104
  throw err;
7760
8105
  }
7761
8106
  liveTraces.set(target.id, { conn, target, events, startedAt: Date.now() });
7762
- await mkdir7(STATE_DIR2, { recursive: true });
8107
+ await mkdir7(STATE_DIR, { recursive: true });
7763
8108
  const state = {
7764
8109
  targetId: target.id,
7765
8110
  url: target.url,
@@ -8088,7 +8433,7 @@ function buildFfmpegArgs(manifestPath, outPath, choice) {
8088
8433
  outPath
8089
8434
  ];
8090
8435
  }
8091
- function run(bin, args) {
8436
+ function run2(bin, args) {
8092
8437
  return new Promise((resolve, reject) => {
8093
8438
  const child = spawn(bin, args, { stdio: ["ignore", "pipe", "pipe"] });
8094
8439
  let stdout = "";
@@ -8110,7 +8455,7 @@ async function probeEncoder() {
8110
8455
  encoderProbe = (async () => {
8111
8456
  let res;
8112
8457
  try {
8113
- res = await run(FFMPEG_BIN, ["-hide_banner", "-encoders"]);
8458
+ res = await run2(FFMPEG_BIN, ["-hide_banner", "-encoders"]);
8114
8459
  } catch (err) {
8115
8460
  throw new CdpError(`${FFMPEG_MISSING} (${err.message})`);
8116
8461
  }
@@ -8119,7 +8464,7 @@ async function probeEncoder() {
8119
8464
  const choice = selectEncoder(`${res.stdout}
8120
8465
  ${res.stderr}`);
8121
8466
  const output = async (args) => {
8122
- const r = await run(FFMPEG_BIN, args).catch(() => {
8467
+ const r = await run2(FFMPEG_BIN, args).catch(() => {
8123
8468
  return;
8124
8469
  });
8125
8470
  return r && r.code === 0 ? `${r.stdout}
@@ -8292,7 +8637,7 @@ async function stopScreenRecording(args = {}) {
8292
8637
  const { width, height } = evenDimensions(ledger[0].width, ledger[0].height);
8293
8638
  let res;
8294
8639
  try {
8295
- res = await run(FFMPEG_BIN, buildFfmpegArgs(manifestPath, outPath, rec.encoder));
8640
+ res = await run2(FFMPEG_BIN, buildFfmpegArgs(manifestPath, outPath, rec.encoder));
8296
8641
  } catch (err) {
8297
8642
  throw new CdpError(`${FFMPEG_MISSING} Spooled frames kept at ${rec.spoolDir}. (${err.message})`);
8298
8643
  }
@@ -10100,7 +10445,7 @@ var MANIFEST = [
10100
10445
  },
10101
10446
  {
10102
10447
  name: "new_page",
10103
- description: "Open a browser tab, optionally claim it; navigation is not awaited.",
10448
+ description: "Open a browser tab in the background, optionally claim it; navigation is not awaited.",
10104
10449
  inputSchema: {
10105
10450
  type: "object",
10106
10451
  properties: {
@@ -10127,6 +10472,10 @@ var MANIFEST = [
10127
10472
  ttlMs: {
10128
10473
  type: "number",
10129
10474
  description: "Lease TTL in milliseconds."
10475
+ },
10476
+ focus: {
10477
+ type: "boolean",
10478
+ description: "Open in the foreground and take focus; default false (background tab)."
10130
10479
  }
10131
10480
  },
10132
10481
  required: [],
@@ -10156,7 +10505,7 @@ var MANIFEST = [
10156
10505
  },
10157
10506
  {
10158
10507
  name: "select_page",
10159
- description: "Focus a selected page and persist it as active; target must resolve explicitly.",
10508
+ description: "Persist a page as selected; focus:true also raises it. Target must resolve explicitly.",
10160
10509
  inputSchema: {
10161
10510
  type: "object",
10162
10511
  properties: {
@@ -10167,6 +10516,10 @@ var MANIFEST = [
10167
10516
  target: {
10168
10517
  type: "string",
10169
10518
  description: "Page selector (index:/url:/title:/label:/targetId, endpoint:<name>/ prefix, default active); grammar in server instructions."
10519
+ },
10520
+ focus: {
10521
+ type: "boolean",
10522
+ description: "Also raise the tab and take window focus; default false (selection only)."
10170
10523
  }
10171
10524
  },
10172
10525
  required: [
@@ -11758,7 +12111,7 @@ var MANIFEST = [
11758
12111
  },
11759
12112
  {
11760
12113
  name: "claim_page",
11761
- description: "Claim an existing tab or open a fresh one; CLI use is refused.",
12114
+ description: "Claim an existing tab or open a fresh one in the background; CLI use is refused.",
11762
12115
  inputSchema: {
11763
12116
  type: "object",
11764
12117
  properties: {
@@ -11781,6 +12134,10 @@ var MANIFEST = [
11781
12134
  ttlMs: {
11782
12135
  type: "number",
11783
12136
  description: "Lease TTL in milliseconds."
12137
+ },
12138
+ focus: {
12139
+ type: "boolean",
12140
+ description: "Fresh tab only: open it in the foreground; default false (background)."
11784
12141
  }
11785
12142
  },
11786
12143
  required: [],