@generativereality/browser-automation 0.4.12 → 0.4.13
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/.claude-plugin/plugin.json +1 -1
- package/README.md +1 -0
- package/dist/index.js +223 -115
- package/package.json +1 -1
- package/skills/browser/SKILL.md +26 -8
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "browser-automation",
|
|
3
3
|
"description": "Daemonless, per-tab-isolated browser automation for Claude Code via the `browser-automation` CLI. Drives one shared headed Chrome (persistent profile + extensions) over per-target CDP — many parallel sessions, no focus stealing, nothing long-lived to crash.",
|
|
4
|
-
"version": "0.4.
|
|
4
|
+
"version": "0.4.13",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "generativereality"
|
|
7
7
|
},
|
package/README.md
CHANGED
|
@@ -104,6 +104,7 @@ browser-automation bind -s bank -m nordnet # …or adopt it into a session
|
|
|
104
104
|
| `fill (-s\|-m\|-t) <ref> <value> [--submit]` | Type into a field by ref |
|
|
105
105
|
| `read (-s\|-m\|-t) [selector]` | Print page text (or a CSS selector's text) |
|
|
106
106
|
| `eval (-s\|-m\|-t) <js>` | Evaluate a JS expression in the tab (escape hatch) |
|
|
107
|
+
| `focus (-s\|-m\|-t) [--raise]` | Make the tab report itself focused + visible, for pages that defer work while hidden (rendering, polling, charts, video). Quiet by default — no window moves; `--raise` genuinely brings it to the front and **takes the screen** |
|
|
107
108
|
| `download (-s\|-m\|-t) (--click <ref>\|--url <href>)` | Capture a file/CSV download, wait for completion, print the path |
|
|
108
109
|
| `setfiles (-s\|-m\|-t) <ref> <path…>` | Set files on a known `<input type=file>` by ref (fires input/change) |
|
|
109
110
|
| `upload (-s\|-m\|-t) --click <ref> <path…>` | Upload via a button that opens a file chooser (transient/custom inputs) |
|
package/dist/index.js
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
import updateNotifier from "update-notifier";
|
|
3
3
|
import { cli, define } from "gunshi";
|
|
4
|
-
import { consola } from "consola";
|
|
4
|
+
import consola, { consola as consola$1 } from "consola";
|
|
5
5
|
import { homedir } from "node:os";
|
|
6
6
|
import { basename, dirname, extname, join, resolve } from "node:path";
|
|
7
7
|
import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
|
|
@@ -9,7 +9,7 @@ import { execFileSync, spawnSync } from "node:child_process";
|
|
|
9
9
|
import { fileURLToPath } from "node:url";
|
|
10
10
|
//#region package.json
|
|
11
11
|
var name = "@generativereality/browser-automation";
|
|
12
|
-
var version = "0.4.
|
|
12
|
+
var version = "0.4.13";
|
|
13
13
|
var description = "Daemonless, per-tab-isolated browser automation CLI for Claude Code. Drives one shared headed Chrome (persistent profile + extensions) over per-target CDP — many parallel sessions, no focus stealing, nothing long-lived to crash.";
|
|
14
14
|
var package_default = {
|
|
15
15
|
name,
|
|
@@ -453,13 +453,37 @@ async function captureScreenshot(targetId, { fullPage = false } = {}) {
|
|
|
453
453
|
});
|
|
454
454
|
}
|
|
455
455
|
/** Navigate a page target and wait for load (or timeout). */
|
|
456
|
-
|
|
456
|
+
/**
|
|
457
|
+
* How long to wait for a page's load event before giving up on confirming it.
|
|
458
|
+
*
|
|
459
|
+
* Read from the environment so the suite can exercise the give-up path without
|
|
460
|
+
* spending 30 real seconds on it. Deliberately NOT used by the test that checks
|
|
461
|
+
* a prompt exit: shrinking the timeout there would shrink the leak it exists to
|
|
462
|
+
* catch, and it would pass against the bug.
|
|
463
|
+
*/
|
|
464
|
+
function navTimeout() {
|
|
465
|
+
const v = Number(process.env.BROWSER_AUTOMATION_NAV_TIMEOUT);
|
|
466
|
+
return Number.isFinite(v) && v > 0 ? Math.floor(v) : 3e4;
|
|
467
|
+
}
|
|
468
|
+
async function navigate(targetId, url, { timeout = navTimeout() } = {}) {
|
|
457
469
|
return withPage(targetId, async (s) => {
|
|
458
470
|
await s.send("Page.enable");
|
|
459
|
-
|
|
471
|
+
let seen = false;
|
|
472
|
+
const loaded = new Promise((resolve) => s.on("Page.loadEventFired", () => {
|
|
473
|
+
seen = true;
|
|
474
|
+
resolve();
|
|
475
|
+
}));
|
|
460
476
|
const r = await s.send("Page.navigate", { url });
|
|
461
477
|
if (r.errorText) throw new Error(`navigate failed: ${r.errorText}`);
|
|
462
|
-
|
|
478
|
+
let timer;
|
|
479
|
+
try {
|
|
480
|
+
await Promise.race([loaded, new Promise((res) => {
|
|
481
|
+
timer = setTimeout(res, timeout);
|
|
482
|
+
})]);
|
|
483
|
+
} finally {
|
|
484
|
+
if (timer !== void 0) clearTimeout(timer);
|
|
485
|
+
}
|
|
486
|
+
return { loaded: seen };
|
|
463
487
|
});
|
|
464
488
|
}
|
|
465
489
|
//#endregion
|
|
@@ -1073,7 +1097,7 @@ const newCommand = define({
|
|
|
1073
1097
|
async run(ctx) {
|
|
1074
1098
|
const name = ctx.values.session || defaultSessionName();
|
|
1075
1099
|
const url = ctx.positionals[1] ? normalizeUrl(ctx.positionals[1]) : "about:blank";
|
|
1076
|
-
if (loadSession(name) && !ctx.values.force) consola.warn(`Session "${name}" already maps to a tab. Use --force to open another, or just \`browser-automation goto -s ${name} <url>\`.`);
|
|
1100
|
+
if (loadSession(name) && !ctx.values.force) consola$1.warn(`Session "${name}" already maps to a tab. Use --force to open another, or just \`browser-automation goto -s ${name} <url>\`.`);
|
|
1077
1101
|
const targetId = await withRendererDiagnosis(() => createTab(url));
|
|
1078
1102
|
saveSession({
|
|
1079
1103
|
name,
|
|
@@ -1082,16 +1106,16 @@ const newCommand = define({
|
|
|
1082
1106
|
createdAt: (/* @__PURE__ */ new Date()).toISOString()
|
|
1083
1107
|
});
|
|
1084
1108
|
const r = await ensureRenderer(targetId);
|
|
1085
|
-
if (r.woke) consola.warn(`[${name}] the new tab's renderer did not start on its own, so the tab was activated briefly to force one. The Chrome window was raised and handed straight back.`);
|
|
1109
|
+
if (r.woke) consola$1.warn(`[${name}] the new tab's renderer did not start on its own, so the tab was activated briefly to force one. The Chrome window was raised and handed straight back.`);
|
|
1086
1110
|
if (!r.ok) {
|
|
1087
1111
|
const health = await probeRenderer().catch(() => null);
|
|
1088
1112
|
if (health && !health.ok) {
|
|
1089
|
-
consola.error(`[${name}] tab ${targetId.slice(0, 12)}… was created but has no working renderer.\n\n${explainRendererFailure(health)}`);
|
|
1113
|
+
consola$1.error(`[${name}] tab ${targetId.slice(0, 12)}… was created but has no working renderer.\n\n${explainRendererFailure(health)}`);
|
|
1090
1114
|
process.exit(1);
|
|
1091
1115
|
}
|
|
1092
|
-
consola.warn(`[${name}] tab ${targetId.slice(0, 12)}… did not answer yet (${r.reason ?? r.outcome}). Chrome can still create renderers, so this is likely transient — retry the next command.`);
|
|
1116
|
+
consola$1.warn(`[${name}] tab ${targetId.slice(0, 12)}… did not answer yet (${r.reason ?? r.outcome}). Chrome can still create renderers, so this is likely transient — retry the next command.`);
|
|
1093
1117
|
}
|
|
1094
|
-
consola.success(`[${name}] opened background tab ${targetId.slice(0, 12)}… → ${url}`);
|
|
1118
|
+
consola$1.success(`[${name}] opened background tab ${targetId.slice(0, 12)}… → ${url}`);
|
|
1095
1119
|
}
|
|
1096
1120
|
});
|
|
1097
1121
|
//#endregion
|
|
@@ -1201,16 +1225,16 @@ const gotoCommand = define({
|
|
|
1201
1225
|
async run(ctx) {
|
|
1202
1226
|
const url = ctx.positionals[1];
|
|
1203
1227
|
if (!url) {
|
|
1204
|
-
consola.error("URL is required");
|
|
1228
|
+
consola$1.error("URL is required");
|
|
1205
1229
|
process.exit(1);
|
|
1206
1230
|
}
|
|
1207
1231
|
const target = normalizeUrl(url);
|
|
1208
1232
|
const opts = targetOpts(ctx.values);
|
|
1209
1233
|
const { targetId, created } = await withRendererDiagnosis(() => resolveOrCreateTargetId(opts));
|
|
1210
1234
|
if (created) {
|
|
1211
|
-
if ((await ensureRenderer(targetId)).woke) consola.warn("The new tab's renderer did not start on its own, so the tab was activated briefly to force one. The Chrome window was raised and handed straight back.");
|
|
1235
|
+
if ((await ensureRenderer(targetId)).woke) consola$1.warn("The new tab's renderer did not start on its own, so the tab was activated briefly to force one. The Chrome window was raised and handed straight back.");
|
|
1212
1236
|
}
|
|
1213
|
-
await withRendererDiagnosis(() => navigate(targetId, target));
|
|
1237
|
+
if (!(await withRendererDiagnosis(() => navigate(targetId, target))).loaded) consola$1.warn("No load event arrived, so the page may still be loading. The navigation itself was accepted; this is a statement about what could not be confirmed.");
|
|
1214
1238
|
if (!opts.match && !opts.target) {
|
|
1215
1239
|
const name = opts.session || defaultSessionName();
|
|
1216
1240
|
saveSession({
|
|
@@ -1219,8 +1243,8 @@ const gotoCommand = define({
|
|
|
1219
1243
|
url: target,
|
|
1220
1244
|
createdAt: loadSession(name)?.createdAt ?? (/* @__PURE__ */ new Date()).toISOString()
|
|
1221
1245
|
});
|
|
1222
|
-
consola.success(`[${name}] ${created ? "opened tab + " : ""}navigated → ${target}`);
|
|
1223
|
-
} else consola.success(`[${targetId.slice(0, 12)}…] navigated → ${target}`);
|
|
1246
|
+
consola$1.success(`[${name}] ${created ? "opened tab + " : ""}navigated → ${target}`);
|
|
1247
|
+
} else consola$1.success(`[${targetId.slice(0, 12)}…] navigated → ${target}`);
|
|
1224
1248
|
}
|
|
1225
1249
|
});
|
|
1226
1250
|
//#endregion
|
|
@@ -1486,18 +1510,18 @@ const snapshotCommand = define({
|
|
|
1486
1510
|
return;
|
|
1487
1511
|
}
|
|
1488
1512
|
const overlayNote = snap.overlayCount ? ` (${snap.overlayCount} in an open overlay, listed first)` : "";
|
|
1489
|
-
consola.log(`# ${snap.title}\n# ${snap.url}\n# ${snap.count} interactive elements${overlayNote}`);
|
|
1490
|
-
if (snap.overlayText) consola.log(`# overlay: ${snap.overlayText}`);
|
|
1513
|
+
consola$1.log(`# ${snap.title}\n# ${snap.url}\n# ${snap.count} interactive elements${overlayNote}`);
|
|
1514
|
+
if (snap.overlayText) consola$1.log(`# overlay: ${snap.overlayText}`);
|
|
1491
1515
|
for (const el of snap.elements) {
|
|
1492
1516
|
const label = el.type ? `${el.role}[${el.type}]` : el.role;
|
|
1493
1517
|
const st = el.state ? `[${el.state}] ` : "";
|
|
1494
|
-
consola.log(`${el.ref.padEnd(5)} ${label.padEnd(18)} ${st}${el.name}`);
|
|
1518
|
+
consola$1.log(`${el.ref.padEnd(5)} ${label.padEnd(18)} ${st}${el.name}`);
|
|
1495
1519
|
}
|
|
1496
1520
|
}
|
|
1497
1521
|
});
|
|
1498
1522
|
//#endregion
|
|
1499
1523
|
//#region src/commands/click.ts
|
|
1500
|
-
const sleep$
|
|
1524
|
+
const sleep$2 = (ms) => new Promise((r) => setTimeout(r, ms));
|
|
1501
1525
|
const clickCommand = define({
|
|
1502
1526
|
name: "click",
|
|
1503
1527
|
description: "Click an element by ref (from the latest snapshot)",
|
|
@@ -1515,7 +1539,7 @@ const clickCommand = define({
|
|
|
1515
1539
|
async run(ctx) {
|
|
1516
1540
|
const ref = ctx.positionals[1];
|
|
1517
1541
|
if (!ref || !isValidRef(ref)) {
|
|
1518
|
-
consola.error("A ref like \"e7\" is required (run `browser-automation snapshot` first)");
|
|
1542
|
+
consola$1.error("A ref like \"e7\" is required (run `browser-automation snapshot` first)");
|
|
1519
1543
|
process.exit(1);
|
|
1520
1544
|
}
|
|
1521
1545
|
const targetId = await resolveExistingTargetId(targetOpts(ctx.values));
|
|
@@ -1538,7 +1562,7 @@ const clickCommand = define({
|
|
|
1538
1562
|
while (Date.now() < focusDeadline) {
|
|
1539
1563
|
const f = await evalIn(`({f:document.hasFocus(),v:document.visibilityState})`);
|
|
1540
1564
|
if (f && f.f && f.v === "visible") break;
|
|
1541
|
-
await sleep$
|
|
1565
|
+
await sleep$2(50);
|
|
1542
1566
|
}
|
|
1543
1567
|
let prev = null;
|
|
1544
1568
|
let point = null;
|
|
@@ -1547,7 +1571,7 @@ const clickCommand = define({
|
|
|
1547
1571
|
while (Date.now() < actDeadline) {
|
|
1548
1572
|
const a = await evalIn(actionabilityExpr(ref));
|
|
1549
1573
|
if (a?.err) {
|
|
1550
|
-
consola.error(a.err);
|
|
1574
|
+
consola$1.error(a.err);
|
|
1551
1575
|
process.exit(1);
|
|
1552
1576
|
}
|
|
1553
1577
|
const stable = prev !== null && Math.abs(prev.x - a.x) < .5 && Math.abs(prev.y - a.y) < .5;
|
|
@@ -1564,10 +1588,10 @@ const clickCommand = define({
|
|
|
1564
1588
|
x: a.x,
|
|
1565
1589
|
y: a.y
|
|
1566
1590
|
};
|
|
1567
|
-
await sleep$
|
|
1591
|
+
await sleep$2(60);
|
|
1568
1592
|
}
|
|
1569
1593
|
if (!point) {
|
|
1570
|
-
consola.error(`<${ref}> not actionable for a trusted click: ${lastReason}`);
|
|
1594
|
+
consola$1.error(`<${ref}> not actionable for a trusted click: ${lastReason}`);
|
|
1571
1595
|
process.exit(1);
|
|
1572
1596
|
}
|
|
1573
1597
|
const { x, y } = point;
|
|
@@ -1579,7 +1603,7 @@ const clickCommand = define({
|
|
|
1579
1603
|
buttons: 0,
|
|
1580
1604
|
pointerType: "mouse"
|
|
1581
1605
|
});
|
|
1582
|
-
await sleep$
|
|
1606
|
+
await sleep$2(20);
|
|
1583
1607
|
await s.send("Input.dispatchMouseEvent", {
|
|
1584
1608
|
type: "mousePressed",
|
|
1585
1609
|
x,
|
|
@@ -1601,15 +1625,15 @@ const clickCommand = define({
|
|
|
1601
1625
|
});
|
|
1602
1626
|
return point.tag;
|
|
1603
1627
|
});
|
|
1604
|
-
consola.success(`clicked ${ref} <${trustedTag}> (trusted)`);
|
|
1628
|
+
consola$1.success(`clicked ${ref} <${trustedTag}> (trusted)`);
|
|
1605
1629
|
return;
|
|
1606
1630
|
}
|
|
1607
1631
|
const r = await evaluate(targetId, clickExpr(ref));
|
|
1608
1632
|
if (r.err) {
|
|
1609
|
-
consola.error(r.err);
|
|
1633
|
+
consola$1.error(r.err);
|
|
1610
1634
|
process.exit(1);
|
|
1611
1635
|
}
|
|
1612
|
-
consola.success(`clicked ${ref} <${r.tag}>`);
|
|
1636
|
+
consola$1.success(`clicked ${ref} <${r.tag}>`);
|
|
1613
1637
|
}
|
|
1614
1638
|
});
|
|
1615
1639
|
//#endregion
|
|
@@ -1644,11 +1668,11 @@ const fillCommand = define({
|
|
|
1644
1668
|
const ref = ctx.positionals[1];
|
|
1645
1669
|
const value = ctx.positionals[2];
|
|
1646
1670
|
if (!ref || !isValidRef(ref)) {
|
|
1647
|
-
consola.error("A ref like \"e3\" is required (run `browser-automation snapshot` first)");
|
|
1671
|
+
consola$1.error("A ref like \"e3\" is required (run `browser-automation snapshot` first)");
|
|
1648
1672
|
process.exit(1);
|
|
1649
1673
|
}
|
|
1650
1674
|
if (value === void 0) {
|
|
1651
|
-
consola.error("A value is required");
|
|
1675
|
+
consola$1.error("A value is required");
|
|
1652
1676
|
process.exit(1);
|
|
1653
1677
|
}
|
|
1654
1678
|
const targetId = await resolveExistingTargetId(targetOpts(ctx.values));
|
|
@@ -1657,7 +1681,7 @@ const fillCommand = define({
|
|
|
1657
1681
|
if (native) {
|
|
1658
1682
|
const focus = await evaluate(targetId, focusAndSelectExpr(ref));
|
|
1659
1683
|
if (focus.err) {
|
|
1660
|
-
consola.error(focus.err);
|
|
1684
|
+
consola$1.error(focus.err);
|
|
1661
1685
|
process.exit(1);
|
|
1662
1686
|
}
|
|
1663
1687
|
await withPage(targetId, async (s) => {
|
|
@@ -1680,23 +1704,23 @@ const fillCommand = define({
|
|
|
1680
1704
|
} else {
|
|
1681
1705
|
const r = await evaluate(targetId, fillExpr(ref, value, submit));
|
|
1682
1706
|
if (r.err) {
|
|
1683
|
-
consola.error(r.err);
|
|
1707
|
+
consola$1.error(r.err);
|
|
1684
1708
|
process.exit(1);
|
|
1685
1709
|
}
|
|
1686
1710
|
}
|
|
1687
1711
|
if (ctx.values.verify) {
|
|
1688
1712
|
const v = await evaluate(targetId, readValueAndTrackerExpr(ref));
|
|
1689
|
-
if (v.err) consola.warn(`verify failed to re-read field: ${v.err}`);
|
|
1713
|
+
if (v.err) consola$1.warn(`verify failed to re-read field: ${v.err}`);
|
|
1690
1714
|
else {
|
|
1691
1715
|
const domMatches = v.value === value;
|
|
1692
1716
|
const trackerKnown = v.trackerValue !== null && v.trackerValue !== void 0;
|
|
1693
1717
|
const trackerMatches = !trackerKnown || v.trackerValue === value;
|
|
1694
|
-
if (!domMatches) consola.warn(`verify: DOM value is "${v.value}" but you requested "${value}" — wrong element selected, or the page rewrote it.`);
|
|
1695
|
-
else if (!trackerMatches) consola.warn(`verify: DOM shows "${value}" but React's _valueTracker still holds "${v.trackerValue}". The form library will likely submit the stale value. Try --native, or capture the form's PUT endpoint and call it directly (see SKILL.md "Controlled-form state stickiness").`);
|
|
1696
|
-
else if (v.hasReactFiber && !trackerKnown && !native) consola.info(`verify: field has a React fiber but no _valueTracker — if the next submit serializes the old value, try --native.`);
|
|
1718
|
+
if (!domMatches) consola$1.warn(`verify: DOM value is "${v.value}" but you requested "${value}" — wrong element selected, or the page rewrote it.`);
|
|
1719
|
+
else if (!trackerMatches) consola$1.warn(`verify: DOM shows "${value}" but React's _valueTracker still holds "${v.trackerValue}". The form library will likely submit the stale value. Try --native, or capture the form's PUT endpoint and call it directly (see SKILL.md "Controlled-form state stickiness").`);
|
|
1720
|
+
else if (v.hasReactFiber && !trackerKnown && !native) consola$1.info(`verify: field has a React fiber but no _valueTracker — if the next submit serializes the old value, try --native.`);
|
|
1697
1721
|
}
|
|
1698
1722
|
}
|
|
1699
|
-
consola.success(`filled ${ref} = "${value}"${native ? " [native]" : ""}${submit ? " + submitted" : ""}`);
|
|
1723
|
+
consola$1.success(`filled ${ref} = "${value}"${native ? " [native]" : ""}${submit ? " + submitted" : ""}`);
|
|
1700
1724
|
}
|
|
1701
1725
|
});
|
|
1702
1726
|
//#endregion
|
|
@@ -1712,6 +1736,89 @@ const readCommand = define({
|
|
|
1712
1736
|
}
|
|
1713
1737
|
});
|
|
1714
1738
|
//#endregion
|
|
1739
|
+
//#region src/commands/focus.ts
|
|
1740
|
+
const sleep$1 = (ms) => new Promise((r) => setTimeout(r, ms));
|
|
1741
|
+
/**
|
|
1742
|
+
* Make a tab believe it is the visible one.
|
|
1743
|
+
*
|
|
1744
|
+
* # Why this exists
|
|
1745
|
+
*
|
|
1746
|
+
* A backgrounded tab is not merely unwatched — it reports itself hidden, and
|
|
1747
|
+
* pages act on that. Measured 2026-09-14 on an ordinary tab this CLI had opened:
|
|
1748
|
+
*
|
|
1749
|
+
* {"visibility":"hidden","hasFocus":false,"hidden":true}
|
|
1750
|
+
*
|
|
1751
|
+
* Anything gated on `document.visibilityState` behaves differently there:
|
|
1752
|
+
* deferred rendering, paused polling and animation, charts that never draw,
|
|
1753
|
+
* carousels and videos that never start. `core/renderer-wake.ts` measures the
|
|
1754
|
+
* same deprioritisation one layer down — a background target's renderer answers
|
|
1755
|
+
* in a median 367ms against 19ms once activated, with a tail past 12s.
|
|
1756
|
+
*
|
|
1757
|
+
* Until now nothing exposed this. `click --trusted` and `drop` both force it as
|
|
1758
|
+
* a side effect of needing trusted input to land, so the capability was in the
|
|
1759
|
+
* codebase and reachable only by clicking something.
|
|
1760
|
+
*
|
|
1761
|
+
* # The two ways, and why the quiet one is the default
|
|
1762
|
+
*
|
|
1763
|
+
* `Emulation.setFocusEmulationEnabled` makes the renderer treat itself as
|
|
1764
|
+
* focused and visible whatever the real window is doing — no window moves, and
|
|
1765
|
+
* the operator's frontmost app is undisturbed. That is what this does by
|
|
1766
|
+
* default, and it is how Playwright drives backgrounded pages.
|
|
1767
|
+
*
|
|
1768
|
+
* `--raise` additionally calls `Target.activateTarget`, which genuinely brings
|
|
1769
|
+
* the tab to the front and **takes the operator's screen** — measured in
|
|
1770
|
+
* renderer-wake.ts: every route to a real activation moved the frontmost app
|
|
1771
|
+
* from the terminal to Chrome, and there is no quiet variant. Use it when a
|
|
1772
|
+
* person needs to SEE the tab, not to make a page render.
|
|
1773
|
+
*
|
|
1774
|
+
* # It reports the outcome, not the acceptance
|
|
1775
|
+
*
|
|
1776
|
+
* All three CDP commands are best-effort — an older Chrome may not expose one —
|
|
1777
|
+
* so "sent" says nothing. This reads `document.hasFocus()` and
|
|
1778
|
+
* `visibilityState` back afterwards and prints what it actually achieved,
|
|
1779
|
+
* naming what it could not confirm rather than printing a tick over it.
|
|
1780
|
+
*/
|
|
1781
|
+
const focusCommand = define({
|
|
1782
|
+
name: "focus",
|
|
1783
|
+
description: "Make a tab report itself focused + visible, so pages that defer work while hidden (rendering, polling, charts, video) behave as if watched. Quiet by default — no window moves and the operator keeps their frontmost app. Add --raise to genuinely bring the tab to the front, which DOES take the screen.",
|
|
1784
|
+
args: {
|
|
1785
|
+
...targetArgs,
|
|
1786
|
+
raise: {
|
|
1787
|
+
type: "boolean",
|
|
1788
|
+
short: "r",
|
|
1789
|
+
description: "Also bring the tab to the front for real (Target.activateTarget). This takes the operator's screen — Chrome comes forward over whatever they are using. Only for when a person needs to see the tab."
|
|
1790
|
+
}
|
|
1791
|
+
},
|
|
1792
|
+
async run(ctx) {
|
|
1793
|
+
const raise = ctx.values.raise;
|
|
1794
|
+
const targetId = await resolveExistingTargetId(targetOpts(ctx.values));
|
|
1795
|
+
if (raise) await activateTab(targetId);
|
|
1796
|
+
const state = await withPage(targetId, async (s) => {
|
|
1797
|
+
await forceForeground(s);
|
|
1798
|
+
const deadline = Date.now() + 2e3;
|
|
1799
|
+
let last = {
|
|
1800
|
+
focused: false,
|
|
1801
|
+
visibility: "unknown"
|
|
1802
|
+
};
|
|
1803
|
+
while (Date.now() < deadline) {
|
|
1804
|
+
last = (await s.send("Runtime.evaluate", {
|
|
1805
|
+
expression: "({focused:document.hasFocus(),visibility:document.visibilityState})",
|
|
1806
|
+
returnByValue: true
|
|
1807
|
+
})).result?.value ?? last;
|
|
1808
|
+
if (last.focused && last.visibility === "visible") break;
|
|
1809
|
+
await sleep$1(50);
|
|
1810
|
+
}
|
|
1811
|
+
return last;
|
|
1812
|
+
});
|
|
1813
|
+
const how = raise ? "raised to the front" : "no window focus taken";
|
|
1814
|
+
if (state.focused && state.visibility === "visible") {
|
|
1815
|
+
consola.success(`[${targetId.slice(0, 12)}…] focused + visible (${how})`);
|
|
1816
|
+
return;
|
|
1817
|
+
}
|
|
1818
|
+
consola.warn(`[${targetId.slice(0, 12)}…] hasFocus=${state.focused} visibilityState=${state.visibility} (${how}). The page may still defer work it gates on focus. ` + (raise ? "" : "If the page needs a genuinely front tab, re-run with --raise."));
|
|
1819
|
+
}
|
|
1820
|
+
});
|
|
1821
|
+
//#endregion
|
|
1715
1822
|
//#region src/commands/eval.ts
|
|
1716
1823
|
const evalCommand = define({
|
|
1717
1824
|
name: "eval",
|
|
@@ -1726,7 +1833,7 @@ const evalCommand = define({
|
|
|
1726
1833
|
async run(ctx) {
|
|
1727
1834
|
const expr = ctx.positionals[1];
|
|
1728
1835
|
if (!expr) {
|
|
1729
|
-
consola.error("A JS expression is required");
|
|
1836
|
+
consola$1.error("A JS expression is required");
|
|
1730
1837
|
process.exit(1);
|
|
1731
1838
|
}
|
|
1732
1839
|
const v = await evaluate(await resolveExistingTargetId(targetOpts(ctx.values)), expr);
|
|
@@ -1819,15 +1926,15 @@ const downloadCommand = define({
|
|
|
1819
1926
|
const click = ctx.values.click;
|
|
1820
1927
|
const url = ctx.values.url;
|
|
1821
1928
|
if (!click && !url) {
|
|
1822
|
-
consola.error("Provide --click <ref> or --url <url> to trigger the download");
|
|
1929
|
+
consola$1.error("Provide --click <ref> or --url <url> to trigger the download");
|
|
1823
1930
|
process.exit(1);
|
|
1824
1931
|
}
|
|
1825
1932
|
if (click && !isValidRef(click)) {
|
|
1826
|
-
consola.error(`--click expects a ref like e42 (run snapshot first)`);
|
|
1933
|
+
consola$1.error(`--click expects a ref like e42 (run snapshot first)`);
|
|
1827
1934
|
process.exit(1);
|
|
1828
1935
|
}
|
|
1829
1936
|
const r = await captureDownload(await resolveExistingTargetId(targetOpts(ctx.values)), ctx.values.dir || DEFAULT_DIR$1, click ? clickTriggerExpr(click) : urlTriggerExpr(url), ctx.values.timeout ?? 3e4);
|
|
1830
|
-
consola.success(`Downloaded ${r.filename} (${r.bytes} bytes)`);
|
|
1937
|
+
consola$1.success(`Downloaded ${r.filename} (${r.bytes} bytes)`);
|
|
1831
1938
|
process.stdout.write(r.path + "\n");
|
|
1832
1939
|
}
|
|
1833
1940
|
});
|
|
@@ -1967,7 +2074,7 @@ function absFiles$2(paths) {
|
|
|
1967
2074
|
return paths.map((p) => {
|
|
1968
2075
|
const abs = resolve(p);
|
|
1969
2076
|
if (!existsSync(abs) || !statSync(abs).isFile()) {
|
|
1970
|
-
consola.error(`no such file: ${abs}`);
|
|
2077
|
+
consola$1.error(`no such file: ${abs}`);
|
|
1971
2078
|
process.exit(1);
|
|
1972
2079
|
}
|
|
1973
2080
|
return abs;
|
|
@@ -1991,16 +2098,16 @@ const setfilesCommand = define({
|
|
|
1991
2098
|
const ref = ctx.positionals[1];
|
|
1992
2099
|
const paths = ctx.positionals.slice(2);
|
|
1993
2100
|
if (!ref || !isValidRef(ref)) {
|
|
1994
|
-
consola.error("A ref like \"e7\" is required (run `browser-automation snapshot` first)");
|
|
2101
|
+
consola$1.error("A ref like \"e7\" is required (run `browser-automation snapshot` first)");
|
|
1995
2102
|
process.exit(1);
|
|
1996
2103
|
}
|
|
1997
2104
|
if (paths.length === 0) {
|
|
1998
|
-
consola.error("At least one file path is required");
|
|
2105
|
+
consola$1.error("At least one file path is required");
|
|
1999
2106
|
process.exit(1);
|
|
2000
2107
|
}
|
|
2001
2108
|
const files = absFiles$2(paths);
|
|
2002
2109
|
const r = await setFilesByRef(await resolveExistingTargetId(targetOpts(ctx.values)), ref, files);
|
|
2003
|
-
consola.success(`set ${r.files.length} file(s) on ${ref} <${r.tag} type=${r.type}>:`);
|
|
2110
|
+
consola$1.success(`set ${r.files.length} file(s) on ${ref} <${r.tag} type=${r.type}>:`);
|
|
2004
2111
|
for (const f of r.files) process.stdout.write(f + "\n");
|
|
2005
2112
|
}
|
|
2006
2113
|
});
|
|
@@ -2011,7 +2118,7 @@ function absFiles$1(paths) {
|
|
|
2011
2118
|
return paths.map((p) => {
|
|
2012
2119
|
const abs = resolve(p);
|
|
2013
2120
|
if (!existsSync(abs) || !statSync(abs).isFile()) {
|
|
2014
|
-
consola.error(`no such file: ${abs}`);
|
|
2121
|
+
consola$1.error(`no such file: ${abs}`);
|
|
2015
2122
|
process.exit(1);
|
|
2016
2123
|
}
|
|
2017
2124
|
return abs;
|
|
@@ -2039,28 +2146,28 @@ const uploadCommand = define({
|
|
|
2039
2146
|
const click = ctx.values.click;
|
|
2040
2147
|
const paths = ctx.positionals.slice(1);
|
|
2041
2148
|
if (!click) {
|
|
2042
|
-
consola.error("--click <ref> is required (the button that opens the file chooser)");
|
|
2149
|
+
consola$1.error("--click <ref> is required (the button that opens the file chooser)");
|
|
2043
2150
|
process.exit(1);
|
|
2044
2151
|
}
|
|
2045
2152
|
if (!isValidRef(click)) {
|
|
2046
|
-
consola.error("--click expects a ref like e42 (run `browser-automation snapshot` first)");
|
|
2153
|
+
consola$1.error("--click expects a ref like e42 (run `browser-automation snapshot` first)");
|
|
2047
2154
|
process.exit(1);
|
|
2048
2155
|
}
|
|
2049
2156
|
if (paths.length === 0) {
|
|
2050
|
-
consola.error("At least one file path is required");
|
|
2157
|
+
consola$1.error("At least one file path is required");
|
|
2051
2158
|
process.exit(1);
|
|
2052
2159
|
}
|
|
2053
2160
|
const files = absFiles$1(paths);
|
|
2054
2161
|
const r = await uploadViaChooser(await resolveExistingTargetId(targetOpts(ctx.values)), click, files, ctx.values.timeout ?? 15e3);
|
|
2055
2162
|
if (r.delivered === 0) {
|
|
2056
|
-
consola.error(`the file chooser opened (backendNodeId ${r.backendNodeId}) but the file never reached the page's change handler — the page likely replaced/destroyed the transient input before it could be set. Re-snapshot and confirm --click points at the real trigger, or try again.`);
|
|
2163
|
+
consola$1.error(`the file chooser opened (backendNodeId ${r.backendNodeId}) but the file never reached the page's change handler — the page likely replaced/destroyed the transient input before it could be set. Re-snapshot and confirm --click points at the real trigger, or try again.`);
|
|
2057
2164
|
process.exit(1);
|
|
2058
2165
|
}
|
|
2059
2166
|
const note = r.reconnected ? " (input was detached — re-attached and re-dispatched input/change so the page's handler fired)" : "";
|
|
2060
|
-
consola.success(`delivered ${r.files.length} file(s) to the page's file handler via chooser (backendNodeId ${r.backendNodeId})${note}:`);
|
|
2167
|
+
consola$1.success(`delivered ${r.files.length} file(s) to the page's file handler via chooser (backendNodeId ${r.backendNodeId})${note}:`);
|
|
2061
2168
|
for (const f of r.files) process.stdout.write(f + "\n");
|
|
2062
|
-
if (r.count === 0) consola.info("The app consumed the file and reset the input (normal). This confirms delivery, not staging — re-snapshot or screenshot to verify the attachment chip/preview actually appeared before submitting.");
|
|
2063
|
-
else consola.info("Re-snapshot to confirm the attachment chip/preview appeared before submitting — the DOM changed.");
|
|
2169
|
+
if (r.count === 0) consola$1.info("The app consumed the file and reset the input (normal). This confirms delivery, not staging — re-snapshot or screenshot to verify the attachment chip/preview actually appeared before submitting.");
|
|
2170
|
+
else consola$1.info("Re-snapshot to confirm the attachment chip/preview appeared before submitting — the DOM changed.");
|
|
2064
2171
|
}
|
|
2065
2172
|
});
|
|
2066
2173
|
//#endregion
|
|
@@ -2071,7 +2178,7 @@ function absFiles(paths) {
|
|
|
2071
2178
|
return paths.map((p) => {
|
|
2072
2179
|
const abs = resolve(p);
|
|
2073
2180
|
if (!existsSync(abs) || !statSync(abs).isFile()) {
|
|
2074
|
-
consola.error(`no such file: ${abs}`);
|
|
2181
|
+
consola$1.error(`no such file: ${abs}`);
|
|
2075
2182
|
process.exit(1);
|
|
2076
2183
|
}
|
|
2077
2184
|
return abs;
|
|
@@ -2126,11 +2233,11 @@ const dropCommand = define({
|
|
|
2126
2233
|
const ref = ctx.positionals[1];
|
|
2127
2234
|
const paths = ctx.positionals.slice(2);
|
|
2128
2235
|
if (!ref || !isValidRef(ref)) {
|
|
2129
|
-
consola.error("A ref like \"e7\" is required (run `browser-automation snapshot` first)");
|
|
2236
|
+
consola$1.error("A ref like \"e7\" is required (run `browser-automation snapshot` first)");
|
|
2130
2237
|
process.exit(1);
|
|
2131
2238
|
}
|
|
2132
2239
|
if (paths.length === 0) {
|
|
2133
|
-
consola.error("At least one file path is required");
|
|
2240
|
+
consola$1.error("At least one file path is required");
|
|
2134
2241
|
process.exit(1);
|
|
2135
2242
|
}
|
|
2136
2243
|
const files = absFiles(paths);
|
|
@@ -2142,10 +2249,10 @@ const dropCommand = define({
|
|
|
2142
2249
|
b64: readFileSync(p).toString("base64")
|
|
2143
2250
|
}))));
|
|
2144
2251
|
if (r.err) {
|
|
2145
|
-
consola.error(r.err);
|
|
2252
|
+
consola$1.error(r.err);
|
|
2146
2253
|
process.exit(1);
|
|
2147
2254
|
}
|
|
2148
|
-
consola.success(`dropped ${r.count} file(s) on ${ref} <${r.tag}> (synthetic — re-snapshot/screenshot to confirm the zone accepted them):`);
|
|
2255
|
+
consola$1.success(`dropped ${r.count} file(s) on ${ref} <${r.tag}> (synthetic — re-snapshot/screenshot to confirm the zone accepted them):`);
|
|
2149
2256
|
for (const f of files) process.stdout.write(f + "\n");
|
|
2150
2257
|
return;
|
|
2151
2258
|
}
|
|
@@ -2176,7 +2283,7 @@ const dropCommand = define({
|
|
|
2176
2283
|
while (Date.now() < actDeadline) {
|
|
2177
2284
|
const a = await evalIn(actionabilityExpr(ref));
|
|
2178
2285
|
if (a?.err) {
|
|
2179
|
-
consola.error(a.err);
|
|
2286
|
+
consola$1.error(a.err);
|
|
2180
2287
|
process.exit(1);
|
|
2181
2288
|
}
|
|
2182
2289
|
const stable = prev !== null && Math.abs(prev.x - a.x) < .5 && Math.abs(prev.y - a.y) < .5;
|
|
@@ -2196,7 +2303,7 @@ const dropCommand = define({
|
|
|
2196
2303
|
await sleep(60);
|
|
2197
2304
|
}
|
|
2198
2305
|
if (!point) {
|
|
2199
|
-
consola.error(`<${ref}> not actionable for a drop: ${lastReason}`);
|
|
2306
|
+
consola$1.error(`<${ref}> not actionable for a drop: ${lastReason}`);
|
|
2200
2307
|
process.exit(1);
|
|
2201
2308
|
}
|
|
2202
2309
|
const { x, y } = point;
|
|
@@ -2226,9 +2333,9 @@ const dropCommand = define({
|
|
|
2226
2333
|
});
|
|
2227
2334
|
return point.tag;
|
|
2228
2335
|
});
|
|
2229
|
-
consola.success(`dropped ${files.length} file(s) on ${ref} <${tag}> (trusted):`);
|
|
2336
|
+
consola$1.success(`dropped ${files.length} file(s) on ${ref} <${tag}> (trusted):`);
|
|
2230
2337
|
for (const f of files) process.stdout.write(f + "\n");
|
|
2231
|
-
consola.info("Re-snapshot or screenshot to confirm the zone accepted the drop — the DOM changed.");
|
|
2338
|
+
consola$1.info("Re-snapshot or screenshot to confirm the zone accepted the drop — the DOM changed.");
|
|
2232
2339
|
}
|
|
2233
2340
|
});
|
|
2234
2341
|
//#endregion
|
|
@@ -2341,7 +2448,7 @@ const networkCommand = define({
|
|
|
2341
2448
|
async run(ctx) {
|
|
2342
2449
|
const click = ctx.values.click;
|
|
2343
2450
|
if (click && !isValidRef(click)) {
|
|
2344
|
-
consola.error("--click expects a ref like e42");
|
|
2451
|
+
consola$1.error("--click expects a ref like e42");
|
|
2345
2452
|
process.exit(1);
|
|
2346
2453
|
}
|
|
2347
2454
|
const entries = await captureNetwork(await resolveExistingTargetId(targetOpts(ctx.values)), {
|
|
@@ -2357,14 +2464,14 @@ const networkCommand = define({
|
|
|
2357
2464
|
process.stdout.write(JSON.stringify(entries, null, 2) + "\n");
|
|
2358
2465
|
return;
|
|
2359
2466
|
}
|
|
2360
|
-
consola.log(`# ${entries.length} requests`);
|
|
2467
|
+
consola$1.log(`# ${entries.length} requests`);
|
|
2361
2468
|
for (const e of entries) {
|
|
2362
|
-
consola.log(`${(e.method ?? "").padEnd(5)} ${String(e.status ?? "—").padEnd(4)} ${(e.type ?? "").padEnd(9)} ${e.url.slice(0, 100)}`);
|
|
2469
|
+
consola$1.log(`${(e.method ?? "").padEnd(5)} ${String(e.status ?? "—").padEnd(4)} ${(e.type ?? "").padEnd(9)} ${e.url.slice(0, 100)}`);
|
|
2363
2470
|
if (ctx.values.headers) {
|
|
2364
|
-
if (e.postData) consola.log(` ↑ body: ${e.postData.slice(0, 200)}`);
|
|
2365
|
-
for (const [k, v] of Object.entries(e.requestHeaders ?? {})) if (/^(authorization|cookie|x-|content-type)/i.test(k)) consola.log(` ↑ ${k}: ${String(v).slice(0, 120)}`);
|
|
2471
|
+
if (e.postData) consola$1.log(` ↑ body: ${e.postData.slice(0, 200)}`);
|
|
2472
|
+
for (const [k, v] of Object.entries(e.requestHeaders ?? {})) if (/^(authorization|cookie|x-|content-type)/i.test(k)) consola$1.log(` ↑ ${k}: ${String(v).slice(0, 120)}`);
|
|
2366
2473
|
}
|
|
2367
|
-
if (ctx.values.body && e.body) consola.log(` ↓ ${e.body.replace(/\s+/g, " ").slice(0, 300)}`);
|
|
2474
|
+
if (ctx.values.body && e.body) consola$1.log(` ↓ ${e.body.replace(/\s+/g, " ").slice(0, 300)}`);
|
|
2368
2475
|
}
|
|
2369
2476
|
}
|
|
2370
2477
|
});
|
|
@@ -2395,7 +2502,7 @@ const screenshotCommand = define({
|
|
|
2395
2502
|
out = join(DEFAULT_DIR, `${((await listPageTargets()).find((p) => p.id === targetId)?.title || "page").replace(/[^a-z0-9]+/gi, "-").replace(/^-|-$/g, "").slice(0, 40) || "page"}.png`);
|
|
2396
2503
|
}
|
|
2397
2504
|
writeFileSync(out, png);
|
|
2398
|
-
consola.success(`Saved screenshot (${png.length} bytes)`);
|
|
2505
|
+
consola$1.success(`Saved screenshot (${png.length} bytes)`);
|
|
2399
2506
|
process.stdout.write(out + "\n");
|
|
2400
2507
|
}
|
|
2401
2508
|
});
|
|
@@ -2435,23 +2542,23 @@ const listCommand = define({
|
|
|
2435
2542
|
const stale = sessions.filter((s) => !liveIds.has(s.targetId));
|
|
2436
2543
|
const shown = ctx.values.all ? sessions : live;
|
|
2437
2544
|
if (shown.length) {
|
|
2438
|
-
consola.log(`# sessions (${shown.length}${ctx.values.all ? "" : " live"})`);
|
|
2439
|
-
for (const s of shown) consola.log(` ${s.name.padEnd(16)} [${liveIds.has(s.targetId) ? "live" : "stale"}] ${s.url ?? ""}`);
|
|
2440
|
-
} else if (sessions.length) consola.log(`# sessions (0 live)`);
|
|
2441
|
-
if (stale.length && !ctx.values.all) consola.log(` + ${stale.length} stale bookmark(s) whose tab is gone — \`list --all\` to see them, \`gc --sessions\` to clear them`);
|
|
2442
|
-
if (sessions.length) consola.log("");
|
|
2443
|
-
consola.log(`# open tabs (${targets.length}) — address with -t <id> or -m <substr>`);
|
|
2545
|
+
consola$1.log(`# sessions (${shown.length}${ctx.values.all ? "" : " live"})`);
|
|
2546
|
+
for (const s of shown) consola$1.log(` ${s.name.padEnd(16)} [${liveIds.has(s.targetId) ? "live" : "stale"}] ${s.url ?? ""}`);
|
|
2547
|
+
} else if (sessions.length) consola$1.log(`# sessions (0 live)`);
|
|
2548
|
+
if (stale.length && !ctx.values.all) consola$1.log(` + ${stale.length} stale bookmark(s) whose tab is gone — \`list --all\` to see them, \`gc --sessions\` to clear them`);
|
|
2549
|
+
if (sessions.length) consola$1.log("");
|
|
2550
|
+
consola$1.log(`# open tabs (${targets.length}) — address with -t <id> or -m <substr>`);
|
|
2444
2551
|
for (const t of targets) {
|
|
2445
2552
|
const owner = sessions.find((s) => s.targetId === t.id);
|
|
2446
2553
|
const title = (t.title ?? "").replace(/\s+/g, " ").slice(0, 28);
|
|
2447
|
-
consola.log(` ${t.id.slice(0, 12)} ${owner ? `(${owner.name}) ` : ""}${title.padEnd(28)} ${(t.url ?? "").slice(0, 70)}`);
|
|
2554
|
+
consola$1.log(` ${t.id.slice(0, 12)} ${owner ? `(${owner.name}) ` : ""}${title.padEnd(28)} ${(t.url ?? "").slice(0, 70)}`);
|
|
2448
2555
|
}
|
|
2449
2556
|
if (ctx.values.frames) {
|
|
2450
|
-
consola.log("");
|
|
2451
|
-
consola.log(`# cross-origin iframes (${frames.length}) — address with -F <substr> or -t <id>`);
|
|
2557
|
+
consola$1.log("");
|
|
2558
|
+
consola$1.log(`# cross-origin iframes (${frames.length}) — address with -F <substr> or -t <id>`);
|
|
2452
2559
|
for (const f of frames) {
|
|
2453
2560
|
const title = (f.title ?? "").replace(/\s+/g, " ").slice(0, 28);
|
|
2454
|
-
consola.log(` ${f.id.slice(0, 12)} ${title.padEnd(28)} ${(f.url ?? "").slice(0, 70)}`);
|
|
2561
|
+
consola$1.log(` ${f.id.slice(0, 12)} ${title.padEnd(28)} ${(f.url ?? "").slice(0, 70)}`);
|
|
2455
2562
|
}
|
|
2456
2563
|
}
|
|
2457
2564
|
}
|
|
@@ -2474,12 +2581,12 @@ const closeCommand = define({
|
|
|
2474
2581
|
try {
|
|
2475
2582
|
targetId = await resolveExistingTargetId(opts);
|
|
2476
2583
|
} catch (e) {
|
|
2477
|
-
consola.warn(e instanceof Error ? e.message : String(e));
|
|
2584
|
+
consola$1.warn(e instanceof Error ? e.message : String(e));
|
|
2478
2585
|
return;
|
|
2479
2586
|
}
|
|
2480
2587
|
if (ctx.values.tab) {
|
|
2481
2588
|
const ok = await closeTab(targetId).catch(() => false);
|
|
2482
|
-
consola.log(ok ? `Closed tab ${targetId.slice(0, 12)}….` : `Tab ${targetId.slice(0, 12)}… was already gone.`);
|
|
2589
|
+
consola$1.log(ok ? `Closed tab ${targetId.slice(0, 12)}….` : `Tab ${targetId.slice(0, 12)}… was already gone.`);
|
|
2483
2590
|
}
|
|
2484
2591
|
const forgotten = [];
|
|
2485
2592
|
for (const s of listSessions()) if (s.targetId === targetId) {
|
|
@@ -2493,8 +2600,8 @@ const closeCommand = define({
|
|
|
2493
2600
|
forgotten.push(name);
|
|
2494
2601
|
}
|
|
2495
2602
|
}
|
|
2496
|
-
if (forgotten.length) consola.success(`Forgot session(s): ${forgotten.join(", ")}.`);
|
|
2497
|
-
else if (!ctx.values.tab) consola.info("No session bound to that tab and --tab not given — nothing to do.");
|
|
2603
|
+
if (forgotten.length) consola$1.success(`Forgot session(s): ${forgotten.join(", ")}.`);
|
|
2604
|
+
else if (!ctx.values.tab) consola$1.info("No session bound to that tab and --tab not given — nothing to do.");
|
|
2498
2605
|
}
|
|
2499
2606
|
});
|
|
2500
2607
|
//#endregion
|
|
@@ -2508,7 +2615,7 @@ const bindCommand = define({
|
|
|
2508
2615
|
const match = ctx.values.match;
|
|
2509
2616
|
const target = ctx.values.target;
|
|
2510
2617
|
if (!match && !target) {
|
|
2511
|
-
consola.error("Pick the tab to adopt with -m <url/title substr> or -t <targetId>. See `browser-automation list`.");
|
|
2618
|
+
consola$1.error("Pick the tab to adopt with -m <url/title substr> or -t <targetId>. See `browser-automation list`.");
|
|
2512
2619
|
process.exit(1);
|
|
2513
2620
|
}
|
|
2514
2621
|
let targetId;
|
|
@@ -2527,7 +2634,7 @@ const bindCommand = define({
|
|
|
2527
2634
|
url,
|
|
2528
2635
|
createdAt: (/* @__PURE__ */ new Date()).toISOString()
|
|
2529
2636
|
});
|
|
2530
|
-
consola.success(`Bound session "${name}" → ${url ?? targetId}`);
|
|
2637
|
+
consola$1.success(`Bound session "${name}" → ${url ?? targetId}`);
|
|
2531
2638
|
}
|
|
2532
2639
|
});
|
|
2533
2640
|
//#endregion
|
|
@@ -2556,7 +2663,7 @@ const launchCommand = define({
|
|
|
2556
2663
|
async run(ctx) {
|
|
2557
2664
|
const script = launchScriptPath();
|
|
2558
2665
|
if (!existsSync(script)) {
|
|
2559
|
-
consola.error(`launch-chrome.sh not found at ${script}. Reinstall the package.`);
|
|
2666
|
+
consola$1.error(`launch-chrome.sh not found at ${script}. Reinstall the package.`);
|
|
2560
2667
|
process.exit(1);
|
|
2561
2668
|
}
|
|
2562
2669
|
const r = spawnSync("bash", [script, ...[
|
|
@@ -2577,12 +2684,12 @@ const launchCommand = define({
|
|
|
2577
2684
|
}));
|
|
2578
2685
|
if (health.ok) {
|
|
2579
2686
|
const woke = health.attempts.some((a) => a.woke);
|
|
2580
|
-
consola.success(`Renderer capacity: a new tab got a live renderer in ${health.ms}ms — this Chrome works.` + (woke ? " (It had to be activated to get there — this browser is slow to give background tabs a renderer.)" : ""));
|
|
2687
|
+
consola$1.success(`Renderer capacity: a new tab got a live renderer in ${health.ms}ms — this Chrome works.` + (woke ? " (It had to be activated to get there — this browser is slow to give background tabs a renderer.)" : ""));
|
|
2581
2688
|
return;
|
|
2582
2689
|
}
|
|
2583
|
-
consola.error(health.verdict === "wedged" ? "Chrome is up, but it can never make a renderer again — this browser is unusable.\n" : "Chrome is up, but a new tab did not get a working renderer in time.\n");
|
|
2584
|
-
for (const line of explainRendererFailure(health).split("\n")) consola.log(line);
|
|
2585
|
-
consola.log(`\nChrome's own log: ${chromeLogPath()}`);
|
|
2690
|
+
consola$1.error(health.verdict === "wedged" ? "Chrome is up, but it can never make a renderer again — this browser is unusable.\n" : "Chrome is up, but a new tab did not get a working renderer in time.\n");
|
|
2691
|
+
for (const line of explainRendererFailure(health).split("\n")) consola$1.log(line);
|
|
2692
|
+
consola$1.log(`\nChrome's own log: ${chromeLogPath()}`);
|
|
2586
2693
|
process.exit(1);
|
|
2587
2694
|
}
|
|
2588
2695
|
});
|
|
@@ -2619,12 +2726,12 @@ const doctorCommand = define({
|
|
|
2619
2726
|
description: "Diagnose the setup: Node, this user's Chrome, targets, sessions",
|
|
2620
2727
|
args: {},
|
|
2621
2728
|
async run() {
|
|
2622
|
-
const ok = (m) => consola.log(` ✓ ${m}`);
|
|
2623
|
-
const bad = (m) => consola.log(` ✗ ${m}`);
|
|
2729
|
+
const ok = (m) => consola$1.log(` ✓ ${m}`);
|
|
2730
|
+
const bad = (m) => consola$1.log(` ✗ ${m}`);
|
|
2624
2731
|
if (Number(process.versions.node.split(".")[0]) >= 22) ok(`Node ${process.versions.node} (global WebSocket available)`);
|
|
2625
2732
|
else bad(`Node ${process.versions.node} — need >= 22 for the global WebSocket CDP client`);
|
|
2626
|
-
consola.log(` • CDP host: ${cdpHost()} (port ${cdpPort()} — derived from uid ${process.getuid?.() ?? "?"})`);
|
|
2627
|
-
consola.log(` • Profile: ${PROFILE}`);
|
|
2733
|
+
consola$1.log(` • CDP host: ${cdpHost()} (port ${cdpPort()} — derived from uid ${process.getuid?.() ?? "?"})`);
|
|
2734
|
+
consola$1.log(` • Profile: ${PROFILE}`);
|
|
2628
2735
|
let version;
|
|
2629
2736
|
try {
|
|
2630
2737
|
version = await (await fetch(`${cdpHost()}/json/version`)).json();
|
|
@@ -2643,7 +2750,7 @@ const doctorCommand = define({
|
|
|
2643
2750
|
for (const t of targets) byType[t.type] = (byType[t.type] ?? 0) + 1;
|
|
2644
2751
|
const summary = Object.entries(byType).map(([k, v]) => `${v} ${k}`).join(", ");
|
|
2645
2752
|
ok(`${targets.length} targets (${summary})`);
|
|
2646
|
-
consola.log(` (per-target CDP — target count never wedges this CLI)`);
|
|
2753
|
+
consola$1.log(` (per-target CDP — target count never wedges this CLI)`);
|
|
2647
2754
|
} catch {
|
|
2648
2755
|
bad("Could not enumerate targets");
|
|
2649
2756
|
}
|
|
@@ -2660,23 +2767,23 @@ const doctorCommand = define({
|
|
|
2660
2767
|
const woke = health.attempts.some((a) => a.woke);
|
|
2661
2768
|
ok(`Renderer capacity: a new tab got a live renderer in ${health.ms}ms`);
|
|
2662
2769
|
if (woke) {
|
|
2663
|
-
consola.log(` ⚠ it only answered after being activated — this Chrome is slow to give`);
|
|
2664
|
-
consola.log(` BACKGROUND tabs a renderer (measured: median 367ms, tail past 30s).`);
|
|
2665
|
-
consola.log(` Commands will work; new tabs may briefly raise the Chrome window.`);
|
|
2770
|
+
consola$1.log(` ⚠ it only answered after being activated — this Chrome is slow to give`);
|
|
2771
|
+
consola$1.log(` BACKGROUND tabs a renderer (measured: median 367ms, tail past 30s).`);
|
|
2772
|
+
consola$1.log(` Commands will work; new tabs may briefly raise the Chrome window.`);
|
|
2666
2773
|
}
|
|
2667
2774
|
const ev = gatherEvidence();
|
|
2668
2775
|
if (ev.rendezvous === false) {
|
|
2669
|
-
consola.log(` ⚠ but the Mach rendezvous service for pid ${ev.pid} is NOT registered —`);
|
|
2670
|
-
consola.log(` new renderers are expected to start failing. Restart Chrome soon:`);
|
|
2671
|
-
consola.log(` browser-automation launch --restart`);
|
|
2776
|
+
consola$1.log(` ⚠ but the Mach rendezvous service for pid ${ev.pid} is NOT registered —`);
|
|
2777
|
+
consola$1.log(` new renderers are expected to start failing. Restart Chrome soon:`);
|
|
2778
|
+
consola$1.log(` browser-automation launch --restart`);
|
|
2672
2779
|
}
|
|
2673
2780
|
} else {
|
|
2674
2781
|
bad(`Renderer capacity: FAILED (${health.verdict})`);
|
|
2675
|
-
for (const line of explainRendererFailure(health).split("\n")) consola.log(` ${line}`);
|
|
2676
|
-
consola.log(` Chrome's own log: ${chromeLogPath()}`);
|
|
2782
|
+
for (const line of explainRendererFailure(health).split("\n")) consola$1.log(` ${line}`);
|
|
2783
|
+
consola$1.log(` Chrome's own log: ${chromeLogPath()}`);
|
|
2677
2784
|
}
|
|
2678
2785
|
const stats = recentProbeStats();
|
|
2679
|
-
if (stats) consola.log(` • last ${stats.n} renderer probe(s): ${stats.failures} failed` + (stats.median >= 0 ? `, median ${stats.median}ms, slowest success ${stats.worst}ms` : ""));
|
|
2786
|
+
if (stats) consola$1.log(` • last ${stats.n} renderer probe(s): ${stats.failures} failed` + (stats.median >= 0 ? `, median ${stats.median}ms, slowest success ${stats.worst}ms` : ""));
|
|
2680
2787
|
const sessions = listSessions();
|
|
2681
2788
|
let live = 0;
|
|
2682
2789
|
try {
|
|
@@ -2684,13 +2791,13 @@ const doctorCommand = define({
|
|
|
2684
2791
|
live = sessions.filter((s) => liveIds.has(s.targetId)).length;
|
|
2685
2792
|
} catch {}
|
|
2686
2793
|
const stale = sessions.length - live;
|
|
2687
|
-
consola.log(` • ${sessions.length} known session(s): ${live} live, ${stale} stale`);
|
|
2794
|
+
consola$1.log(` • ${sessions.length} known session(s): ${live} live, ${stale} stale`);
|
|
2688
2795
|
if (sessions.length) {
|
|
2689
2796
|
const names = sessions.map((s) => s.name);
|
|
2690
2797
|
const shown = names.slice(0, 12).join(", ");
|
|
2691
|
-
consola.log(` ${shown}${names.length > 12 ? `, … (+${names.length - 12} more — \`browser-automation list\`)` : ""}`);
|
|
2798
|
+
consola$1.log(` ${shown}${names.length > 12 ? `, … (+${names.length - 12} more — \`browser-automation list\`)` : ""}`);
|
|
2692
2799
|
}
|
|
2693
|
-
if (stale > 20) consola.log(` ${stale} stale bookmarks point at tabs that no longer exist — \`browser-automation gc --dry\` to review.`);
|
|
2800
|
+
if (stale > 20) consola$1.log(` ${stale} stale bookmarks point at tabs that no longer exist — \`browser-automation gc --dry\` to review.`);
|
|
2694
2801
|
}
|
|
2695
2802
|
});
|
|
2696
2803
|
//#endregion
|
|
@@ -2748,10 +2855,10 @@ const gcCommand = define({
|
|
|
2748
2855
|
const stale = sessions.filter((s) => !liveIds.has(s.targetId));
|
|
2749
2856
|
for (const s of stale) {
|
|
2750
2857
|
if (!dry) deleteSession(s.name);
|
|
2751
|
-
consola.log(` session ${act} ${s.name} (tab gone: ${s.targetId.slice(0, 12)}…)`);
|
|
2858
|
+
consola$1.log(` session ${act} ${s.name} (tab gone: ${s.targetId.slice(0, 12)}…)`);
|
|
2752
2859
|
}
|
|
2753
2860
|
if (ctx.values.sessions) {
|
|
2754
|
-
consola.success(`${stale.length} stale session bookmark(s) ${act}. No tabs touched.`);
|
|
2861
|
+
consola$1.success(`${stale.length} stale session bookmark(s) ${act}. No tabs touched.`);
|
|
2755
2862
|
return;
|
|
2756
2863
|
}
|
|
2757
2864
|
const claimed = new Map(sessions.filter((s) => liveIds.has(s.targetId)).map((s) => [s.targetId, s.name]));
|
|
@@ -2763,17 +2870,17 @@ const gcCommand = define({
|
|
|
2763
2870
|
for (const { t, dead: why } of dead) {
|
|
2764
2871
|
const owner = claimed.get(t.id);
|
|
2765
2872
|
if (!dry) await closeTab(t.id).catch(() => {});
|
|
2766
|
-
consola.log(` dead tab ${actTab} ${t.id.slice(0, 12)}… ${owner ? `(${owner}) ` : ""}${(t.url ?? "").slice(0, 60) || "(no url)"} — ${why}`);
|
|
2873
|
+
consola$1.log(` dead tab ${actTab} ${t.id.slice(0, 12)}… ${owner ? `(${owner}) ` : ""}${(t.url ?? "").slice(0, 60) || "(no url)"} — ${why}`);
|
|
2767
2874
|
}
|
|
2768
2875
|
const orphans = probes.filter((p) => !p.dead && !claimed.has(p.t.id));
|
|
2769
2876
|
if (ctx.values.orphans) for (const { t } of orphans) {
|
|
2770
2877
|
if (!dry) await closeTab(t.id).catch(() => {});
|
|
2771
|
-
consola.log(` orphan ${actTab} ${t.id.slice(0, 12)}… ${(t.title ?? "").slice(0, 28).padEnd(28)} ${(t.url ?? "").slice(0, 50)}`);
|
|
2878
|
+
consola$1.log(` orphan ${actTab} ${t.id.slice(0, 12)}… ${(t.title ?? "").slice(0, 28).padEnd(28)} ${(t.url ?? "").slice(0, 50)}`);
|
|
2772
2879
|
}
|
|
2773
|
-
consola.log("");
|
|
2774
|
-
consola.success(`${stale.length} stale bookmark(s) and ${dead.length} dead tab(s) ${dry ? "would be removed" : "removed"}` + (ctx.values.orphans ? `, ${orphans.length} orphan tab(s) ${actTab}` : "") + ".");
|
|
2775
|
-
if (!ctx.values.orphans && orphans.length) consola.log(` ${orphans.length} live tab(s) no session claims were left alone — \`gc --orphans --dry\` to review them.`);
|
|
2776
|
-
if (dead.length && dead.length === pages.length && pages.length > 0) consola.warn("Every open tab was dead. That is the shape of a Chrome that can no longer launch renderers, which closing tabs does not fix — run `browser-automation doctor` for the diagnosis.");
|
|
2880
|
+
consola$1.log("");
|
|
2881
|
+
consola$1.success(`${stale.length} stale bookmark(s) and ${dead.length} dead tab(s) ${dry ? "would be removed" : "removed"}` + (ctx.values.orphans ? `, ${orphans.length} orphan tab(s) ${actTab}` : "") + ".");
|
|
2882
|
+
if (!ctx.values.orphans && orphans.length) consola$1.log(` ${orphans.length} live tab(s) no session claims were left alone — \`gc --orphans --dry\` to review them.`);
|
|
2883
|
+
if (dead.length && dead.length === pages.length && pages.length > 0) consola$1.warn("Every open tab was dead. That is the shape of a Chrome that can no longer launch renderers, which closing tabs does not fix — run `browser-automation doctor` for the diagnosis.");
|
|
2777
2884
|
}
|
|
2778
2885
|
});
|
|
2779
2886
|
//#endregion
|
|
@@ -2804,6 +2911,7 @@ const subCommands = new Map([
|
|
|
2804
2911
|
["click", clickCommand],
|
|
2805
2912
|
["fill", fillCommand],
|
|
2806
2913
|
["read", readCommand],
|
|
2914
|
+
["focus", focusCommand],
|
|
2807
2915
|
["eval", evalCommand],
|
|
2808
2916
|
["download", downloadCommand],
|
|
2809
2917
|
["setfiles", setfilesCommand],
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@generativereality/browser-automation",
|
|
3
|
-
"version": "0.4.
|
|
3
|
+
"version": "0.4.13",
|
|
4
4
|
"description": "Daemonless, per-tab-isolated browser automation CLI for Claude Code. Drives one shared headed Chrome (persistent profile + extensions) over per-target CDP — many parallel sessions, no focus stealing, nothing long-lived to crash.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
package/skills/browser/SKILL.md
CHANGED
|
@@ -36,9 +36,16 @@ file under `~/.browser-automation/sessions/`.
|
|
|
36
36
|
Bind a name to an already-open tab with `bind -s name -m <substr>`. Parallel
|
|
37
37
|
Claude Code sessions stay isolated by *convention* — each drives its own tab
|
|
38
38
|
(its own `-s` name or `-m` match) — but any tab is reachable on demand.
|
|
39
|
-
- **No focus stealing.** New tabs are created in the
|
|
40
|
-
|
|
41
|
-
|
|
39
|
+
- **No focus stealing — unless you ask for it.** New tabs are created in the
|
|
40
|
+
background, and nothing fronts a tab as a side effect of ordinary driving:
|
|
41
|
+
`goto`, `read`, `snapshot`, `fill`, `eval`, `screenshot` all leave your
|
|
42
|
+
frontmost app alone. Three things deliberately do more, and only these:
|
|
43
|
+
`focus` (emulates focus/visibility in the renderer — still **no window
|
|
44
|
+
moves**), `click --trusted` and `drop` (force-front the tab, because CDP input
|
|
45
|
+
grants no user activation to a renderer that considers itself hidden), and
|
|
46
|
+
`focus --raise`, which calls `Target.activateTarget` and **genuinely takes the
|
|
47
|
+
operator's screen**. `--raise` is the only one that does; reach for plain
|
|
48
|
+
`focus` unless a person needs to see the tab.
|
|
42
49
|
- **Self-healing.** If the tab was closed (or Chrome restarted and reissued
|
|
43
50
|
targetIds), the next `goto` just opens a fresh background tab for that session.
|
|
44
51
|
- **Refs live in the DOM.** `snapshot` stamps `data-ba-ref="e7"` onto each
|
|
@@ -103,6 +110,7 @@ Page commands take a tab selector — `-s <session>` (default `$BAC_SESSION`, el
|
|
|
103
110
|
| Drop file(s) onto a drag-and-drop zone | `browser-automation drop -m app e7 ~/Desktop/clip.mp4` (add `--js` for a synthetic drop) |
|
|
104
111
|
| Inspect network (find the API, headers, bodies) | `browser-automation network -m bank --reload --filter api --headers --body` |
|
|
105
112
|
| Screenshot a tab | `browser-automation screenshot -m op.fi --full -o shot.png` |
|
|
113
|
+
| Make a hidden tab render (charts, video, polling) | `browser-automation focus -s work` (add `--raise` to really front it) |
|
|
106
114
|
| Prune stale session bookmarks + dead tabs | `browser-automation gc --dry` (then without `--dry`) |
|
|
107
115
|
| Restart Chrome (LAST resort — closes ALL tabs, for EVERY session; only once `doctor` confirms the Mach name is absent) | `browser-automation launch --restart` |
|
|
108
116
|
| Forget a session (tab stays open) | `browser-automation close -s work` |
|
|
@@ -458,10 +466,20 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
|
|
|
458
466
|
stuck `len` is the whole tell: `hidden` on its own is the normal, healthy state of every
|
|
459
467
|
backgrounded tab — verified 2026-09-07, a background tab reporting `hidden` returned its real
|
|
460
468
|
painted text — so never read `hidden` alone as a diagnosis.
|
|
461
|
-
**Fix:**
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
469
|
+
**Fix:** make the tab report itself visible.
|
|
470
|
+
```bash
|
|
471
|
+
browser-automation focus -s x # quiet: no window moves, you keep your frontmost app
|
|
472
|
+
```
|
|
473
|
+
`focus` emulates focus + visibility in the renderer, then **reads back what it actually
|
|
474
|
+
achieved** rather than reporting that it sent the command — so a partial result says which half
|
|
475
|
+
is missing instead of printing a tick over it. The page paints immediately. Add `--raise` only
|
|
476
|
+
when a *person* needs to see the tab: that genuinely fronts it and **takes the operator's
|
|
477
|
+
screen**, which is exactly what you normally want to avoid.
|
|
478
|
+
Same root cause as the WebAuthn note above, different symptom: that one refuses, this one
|
|
479
|
+
silently never renders.
|
|
480
|
+
*(Older CLIs had no `focus`; the workaround was a `click --trusted` on a harmless wrapper `div`,
|
|
481
|
+
which fronted the tab as a side effect of needing trusted input. Prefer `focus` — it says what it
|
|
482
|
+
achieved, and it does not click anything.)*
|
|
465
483
|
|
|
466
484
|
**Do not confuse this with the renderer wedge above.** Both present to an operator as "the page
|
|
467
485
|
isn't there, but every tool says fine", and the fixes are opposite — one is a per-tab nudge, the
|
|
@@ -473,7 +491,7 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
|
|
|
473
491
|
| `eval` | works, returns a result | **`Runtime.evaluate` times out at 30000ms** |
|
|
474
492
|
| scope | that one tab | **every** new tab / cross-origin nav |
|
|
475
493
|
| `doctor` | `✓ Renderer capacity` | names the wedge + pid |
|
|
476
|
-
| fix | `
|
|
494
|
+
| fix | `focus` on the tab | `launch --restart` (**ask first**) |
|
|
477
495
|
|
|
478
496
|
`eval` is the fast discriminator: if it answers at all, the renderer is alive and you are in the
|
|
479
497
|
painting case. If it times out, stop poking the page and run `doctor`.
|