cdp-toolkit 3.4.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;
@@ -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 {
@@ -2049,6 +2215,7 @@ init_client();
2049
2215
  init_session();
2050
2216
  init_frontApp();
2051
2217
  init_leases();
2218
+ init_hiddenTabs();
2052
2219
  init_endpoints();
2053
2220
  init_activity();
2054
2221
 
@@ -3249,8 +3416,10 @@ async function createSettledTarget(conn, url, settleMs = NEW_TARGET_SETTLE_MS, o
3249
3416
  await conn.send("Target.setDiscoverTargets", { discover: true }).catch(() => {
3250
3417
  return;
3251
3418
  });
3252
- const create = () => conn.send("Target.createTarget", { url, background: opts.focus !== true });
3253
- const { targetId } = opts.focus === true ? await create() : await keepFrontApp(create);
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);
3254
3423
  if (!targetId)
3255
3424
  throw driverError("page-error", "Target.createTarget returned no targetId");
3256
3425
  id = targetId;
@@ -3268,6 +3437,19 @@ async function createSettledTarget(conn, url, settleMs = NEW_TARGET_SETTLE_MS, o
3268
3437
  off();
3269
3438
  }
3270
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
+ }
3271
3453
 
3272
3454
  class CdpBrowserDriver {
3273
3455
  scheme = "cdp";
@@ -3278,15 +3460,26 @@ class CdpBrowserDriver {
3278
3460
  async listPages(opts) {
3279
3461
  const targets = await listTargets();
3280
3462
  const filtered = opts?.all ? targets : targets.filter((t) => t.type === "page");
3281
- 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 } : {} }));
3282
3464
  }
3283
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
+ }
3284
3470
  return withBrowserConn(async (conn) => {
3285
3471
  const targetId = await createSettledTarget(conn, url ?? "about:blank", NEW_TARGET_SETTLE_MS, { focus: opts?.focus === true });
3286
3472
  return { id: targetId, url: url ?? "about:blank", title: "" };
3287
3473
  });
3288
3474
  }
3289
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
+ }
3290
3483
  return withBrowserConn(async (conn) => {
3291
3484
  const res = await keepFrontApp(() => conn.send("Target.closeTarget", { targetId: id }));
3292
3485
  if (res.success !== false)
@@ -3296,6 +3489,16 @@ class CdpBrowserDriver {
3296
3489
  }
3297
3490
  async activatePage(id) {
3298
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
+ }
3299
3502
  await withBrowserConn((conn) => conn.send("Target.activateTarget", { targetId: target.id }));
3300
3503
  return { id: target.id, url: target.url, title: target.title };
3301
3504
  }
@@ -3369,6 +3572,7 @@ class CdpBrowserDriver {
3369
3572
  }
3370
3573
  async dispose() {
3371
3574
  beaconSessions.clear();
3575
+ await disposeHiddenTabs();
3372
3576
  }
3373
3577
  }
3374
3578
  function createCdpDriver() {
@@ -4117,16 +4321,17 @@ async function listPagesOne(driver, args = {}) {
4117
4321
  async function newPage(driver, args = {}) {
4118
4322
  const label = typeof args.label === "string" && args.label.length ? args.label : defaultLabel();
4119
4323
  const p = await newTrackedPage(driver, backendOf(driver), { url: args.url, label, focus: args.focus === true });
4324
+ const hidden = p.hidden === true ? { hidden: true } : {};
4120
4325
  const explicit = args.claim === true;
4121
4326
  if (!explicit && !requireLease())
4122
- return { targetId: p.id, url: p.url };
4327
+ return { targetId: p.id, url: p.url, ...hidden };
4123
4328
  const { record, token } = await claimLease(backendOf(driver), p.id, {
4124
4329
  label,
4125
4330
  ttlMs: typeof args.ttlMs === "number" && args.ttlMs > 0 ? args.ttlMs : leaseTtlMs(),
4126
4331
  auto: !explicit
4127
4332
  });
4128
4333
  await installBeacon(driver, p.id);
4129
- 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 };
4130
4335
  }
4131
4336
  async function closePage(driver, args) {
4132
4337
  if (args.target === undefined || args.target === "")
@@ -4147,9 +4352,33 @@ async function selectPage(driver, args) {
4147
4352
  if (args.target === undefined || args.target === "")
4148
4353
  throw new SharedToolError("select_page requires an explicit target");
4149
4354
  const p = await resolvePage(driver, args.target);
4150
- const id = args.focus === true ? (await driver.activatePage(p.id)).id : p.id;
4151
- await writeSelectedFile(id);
4152
- return { selected: id, focused: args.focus === true };
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 };
4153
4382
  }
4154
4383
  function toLegacyWaitedFor(w) {
4155
4384
  if (w === "committed")
@@ -4815,6 +5044,7 @@ async function claimPage(driver, args = {}) {
4815
5044
  let targetId;
4816
5045
  let url;
4817
5046
  let opened;
5047
+ let hidden = false;
4818
5048
  if (hasTarget) {
4819
5049
  const hit = await pickPage(driver, pages, args.target).catch((err) => {
4820
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.`);
@@ -4834,6 +5064,7 @@ async function claimPage(driver, args = {}) {
4834
5064
  targetId = page.id;
4835
5065
  url = page.url;
4836
5066
  opened = true;
5067
+ hidden = page.hidden === true;
4837
5068
  }
4838
5069
  const humanMs = opened ? null : await readHumanActiveMs(driver, backend, targetId);
4839
5070
  const liveIds = [...pages.map((p) => p.id), targetId];
@@ -4852,6 +5083,7 @@ async function claimPage(driver, args = {}) {
4852
5083
  ttlMs: record.ttlMs,
4853
5084
  expiresAt: record.lastUsedAt + record.ttlMs,
4854
5085
  opened,
5086
+ ...hidden ? { hidden: true } : {},
4855
5087
  ...beaconSupported(driver) ? { humanActiveMs: humanMs } : {},
4856
5088
  ...contention !== undefined ? { contention } : {}
4857
5089
  };