@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.
@@ -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.12",
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";
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
- async function navigate(targetId, url, { timeout = 3e4 } = {}) {
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
- const loaded = new Promise((resolve) => s.on("Page.loadEventFired", () => resolve()));
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
- await Promise.race([loaded, new Promise((res) => setTimeout(res, timeout))]);
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$1 = (ms) => new Promise((r) => setTimeout(r, ms));
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$1(50);
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$1(60);
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$1(20);
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.12",
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": {
@@ -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 background; the CLI never
40
- calls `Target.activateTarget` / `Page.bringToFront`. Your foreground app and
41
- sibling sessions are left alone.
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:** front the tab. There is no `activate` command — a `click --trusted` on any harmless
462
- element (a wrapper `div` from the snapshot works; avoid submit buttons and links) brings the tab
463
- to front and waits for it to be visible, and the page paints immediately. Same root cause as the
464
- WebAuthn note above, different symptom: that one refuses, this one silently never renders.
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 | `click --trusted` on the tab | `launch --restart` (**ask first**) |
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`.