@generativereality/browser-automation 0.4.15 → 0.4.17

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.15",
4
+ "version": "0.4.17",
5
5
  "author": {
6
6
  "name": "generativereality"
7
7
  },
package/README.md CHANGED
@@ -186,6 +186,7 @@ same one-action-per-snapshot rule as Playwright refs.
186
186
  `doctor` prints it too, and warns if another user holds it.
187
187
  - `BROWSER_AUTOMATION_CDP` — full CDP host, overriding the port entirely.
188
188
  - `BROWSER_AUTOMATION_PROFILE` — Chrome profile dir for `launch`. Default `~/.browser-automation/chrome-profile`; a profile still at the old location inside Chrome's own folder is moved there on launch (`browser-automation profile --migrate` to do it by hand).
189
+ - `BAC_SHOW_TAB=1` — `--show` on every `goto`/`new`: select the tab in its window when the automation Chrome is already in front (never raises Chrome over another app). macOS and Windows.
189
190
  - `BAC_SESSION` — default session name for page commands.
190
191
 
191
192
  ## License
package/dist/index.js CHANGED
@@ -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.15";
12
+ var version = "0.4.17";
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,
@@ -918,6 +918,10 @@ function chromeProcesses() {
918
918
  renderers
919
919
  };
920
920
  }
921
+ /** The pid of the browser process serving the port we are driving, if visible. */
922
+ function browserPid() {
923
+ return chromeProcesses().browser;
924
+ }
921
925
  /**
922
926
  * macOS only: is the browser's Mach port rendezvous service still registered?
923
927
  *
@@ -1094,6 +1098,135 @@ async function withRendererDiagnosis(fn) {
1094
1098
  }
1095
1099
  }
1096
1100
  //#endregion
1101
+ //#region src/core/windows-foreground.ts
1102
+ /** The script, with the port substituted. Exported so the test can read it. */
1103
+ function probeScript(port) {
1104
+ return [
1105
+ "$ErrorActionPreference = 'Stop'",
1106
+ "$ProgressPreference = 'SilentlyContinue'",
1107
+ "Add-Type -Namespace BrowserAutomation -Name User32 -MemberDefinition @'",
1108
+ "[DllImport(\"user32.dll\")] public static extern System.IntPtr GetForegroundWindow();",
1109
+ "[DllImport(\"user32.dll\")] public static extern uint GetWindowThreadProcessId(System.IntPtr hWnd, out uint processId);",
1110
+ "'@",
1111
+ "$U = [BrowserAutomation.User32]",
1112
+ "$h = $U::GetForegroundWindow()",
1113
+ "$fg = [uint32]0",
1114
+ "if ($h -ne [IntPtr]::Zero) { [void]$U::GetWindowThreadProcessId($h, [ref]$fg) }",
1115
+ `$re = '--remote-debugging-port=${port}(\\s|"|$)'`,
1116
+ "$sid = [System.Diagnostics.Process]::GetCurrentProcess().SessionId",
1117
+ "$b = Get-CimInstance Win32_Process -Filter \"Name = 'chrome.exe'\" |",
1118
+ " Where-Object { $_.SessionId -eq $sid -and $_.CommandLine -and $_.CommandLine -match $re -and $_.CommandLine -notmatch '--type=' } |",
1119
+ " Select-Object -First 1 -ExpandProperty ProcessId",
1120
+ "Write-Output ('BA-FG ' + $fg + ' ' + [int]$b)"
1121
+ ].join("\n");
1122
+ }
1123
+ /**
1124
+ * Read the answer out of PowerShell's stdout.
1125
+ *
1126
+ * Scans for the line with the expected SHAPE rather than taking the first line:
1127
+ * a PowerShell child process can put other things on its streams (CLIXML
1128
+ * progress records, "Preparing modules for first use"), and keying on line one
1129
+ * is how a parser starts failing the day something precedes the answer.
1130
+ */
1131
+ function parseProbe(stdout) {
1132
+ const m = /^BA-FG (\d+) (\d+)\s*$/m.exec(stdout);
1133
+ return m ? {
1134
+ foreground: Number(m[1]),
1135
+ browser: Number(m[2])
1136
+ } : null;
1137
+ }
1138
+ function windowsForeground(port) {
1139
+ const encoded = Buffer.from(probeScript(port), "utf16le").toString("base64");
1140
+ try {
1141
+ return parseProbe(execFileSync("powershell.exe", [
1142
+ "-NoProfile",
1143
+ "-NonInteractive",
1144
+ "-ExecutionPolicy",
1145
+ "Bypass",
1146
+ "-EncodedCommand",
1147
+ encoded
1148
+ ], {
1149
+ encoding: "utf8",
1150
+ stdio: [
1151
+ "ignore",
1152
+ "pipe",
1153
+ "ignore"
1154
+ ],
1155
+ timeout: 15e3,
1156
+ windowsHide: true
1157
+ }));
1158
+ } catch {
1159
+ return null;
1160
+ }
1161
+ }
1162
+ //#endregion
1163
+ //#region src/core/show.ts
1164
+ /** On for this command: `--show`, or `BAC_SHOW_TAB=1` set once by a skill. */
1165
+ function wantsShow(flag) {
1166
+ return flag === true || /^(1|true|yes|on)$/i.test(process.env.BAC_SHOW_TAB ?? "");
1167
+ }
1168
+ /**
1169
+ * Is the Chrome we drive the frontmost app? `null` when this platform cannot
1170
+ * say — which must not be treated as "yes".
1171
+ *
1172
+ * `lsappinfo`, not AppleScript: it needs no Accessibility or Automation grant,
1173
+ * and a permission dialog mid-command is worse than the problem.
1174
+ */
1175
+ function ourChromeIsFrontmost() {
1176
+ const injected = process.env.BROWSER_AUTOMATION_TEST_FRONTMOST;
1177
+ if (injected) return injected === "chrome";
1178
+ if (process.platform === "win32") {
1179
+ const w = windowsForeground(targetPort());
1180
+ if (!w || !w.foreground || !w.browser) return null;
1181
+ return w.foreground === w.browser;
1182
+ }
1183
+ if (process.platform !== "darwin") return null;
1184
+ try {
1185
+ const asn = execFileSync("lsappinfo", ["front"], {
1186
+ encoding: "utf8",
1187
+ stdio: [
1188
+ "ignore",
1189
+ "pipe",
1190
+ "ignore"
1191
+ ]
1192
+ }).trim();
1193
+ if (!asn) return null;
1194
+ const info = execFileSync("lsappinfo", [
1195
+ "info",
1196
+ "-only",
1197
+ "pid",
1198
+ asn
1199
+ ], {
1200
+ encoding: "utf8",
1201
+ stdio: [
1202
+ "ignore",
1203
+ "pipe",
1204
+ "ignore"
1205
+ ]
1206
+ });
1207
+ const front = Number(/pid\s*=\s*(\d+)/.exec(info)?.[1]);
1208
+ const ours = browserPid();
1209
+ if (!front || !ours) return null;
1210
+ return front === ours;
1211
+ } catch {
1212
+ return null;
1213
+ }
1214
+ }
1215
+ /** Select `targetId` in its window if, and only if, that raises nothing. */
1216
+ async function showTab(targetId) {
1217
+ const front = ourChromeIsFrontmost();
1218
+ if (front === null) return "unsupported";
1219
+ if (!front) return "not-frontmost";
1220
+ await activateTab(targetId);
1221
+ return "shown";
1222
+ }
1223
+ /** One line for the agent when it asked and did not get it — never silent, never loud. */
1224
+ function describeNotShown(outcome) {
1225
+ if (outcome === "not-frontmost") return "Tab not shown: another app (or another Chrome) is in front, and --show never brings this Chrome over it. It selects the tab once the automation Chrome is in front.";
1226
+ if (outcome === "unsupported") return "Tab not shown: cannot tell which app is in front here (supported on macOS and Windows), so --show did nothing rather than risk taking the screen.";
1227
+ return null;
1228
+ }
1229
+ //#endregion
1097
1230
  //#region src/commands/new.ts
1098
1231
  const newCommand = define({
1099
1232
  name: "new",
@@ -1108,6 +1241,10 @@ const newCommand = define({
1108
1241
  type: "boolean",
1109
1242
  short: "f",
1110
1243
  description: "Open a new tab even if the session already has one"
1244
+ },
1245
+ show: {
1246
+ type: "boolean",
1247
+ description: "Make this the SELECTED tab in its Chrome window, so someone watching Chrome sees it — only when the automation Chrome is already the frontmost app, so it never brings Chrome over another app. Default on with BAC_SHOW_TAB=1."
1111
1248
  }
1112
1249
  },
1113
1250
  async run(ctx) {
@@ -1131,7 +1268,14 @@ const newCommand = define({
1131
1268
  }
1132
1269
  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.`);
1133
1270
  }
1134
- consola$1.success(`[${name}] opened background tab ${targetId.slice(0, 12)}… → ${url}`);
1271
+ let shown = false;
1272
+ if (wantsShow(ctx.values.show)) {
1273
+ const outcome = await showTab(targetId).catch(() => "unsupported");
1274
+ shown = outcome === "shown";
1275
+ const note = describeNotShown(outcome);
1276
+ if (note) consola$1.info(note);
1277
+ }
1278
+ consola$1.success(`[${name}] opened ${shown ? "and showed" : "background"} tab ${targetId.slice(0, 12)}… → ${url}`);
1135
1279
  }
1136
1280
  });
1137
1281
  //#endregion
@@ -1236,6 +1380,10 @@ const gotoCommand = define({
1236
1380
  url: {
1237
1381
  type: "positional",
1238
1382
  description: "URL to navigate to"
1383
+ },
1384
+ show: {
1385
+ type: "boolean",
1386
+ description: "Make this the SELECTED tab in its Chrome window, so someone watching Chrome sees it — only when the automation Chrome is already the frontmost app, so it never brings Chrome over another app. Default on with BAC_SHOW_TAB=1."
1239
1387
  }
1240
1388
  },
1241
1389
  async run(ctx) {
@@ -1251,6 +1399,10 @@ const gotoCommand = define({
1251
1399
  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.");
1252
1400
  }
1253
1401
  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.");
1402
+ if (wantsShow(ctx.values.show)) {
1403
+ const note = describeNotShown(await showTab(targetId).catch(() => "unsupported"));
1404
+ if (note) consola$1.info(note);
1405
+ }
1254
1406
  if (!opts.match && !opts.target) {
1255
1407
  const name = opts.session || defaultSessionName();
1256
1408
  saveSession({
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@generativereality/browser-automation",
3
- "version": "0.4.15",
3
+ "version": "0.4.17",
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": {
@@ -46,6 +46,26 @@ file under `~/.browser-automation/sessions/`.
46
46
  `focus --raise`, which calls `Target.activateTarget` and **genuinely takes the
47
47
  operator's screen**. `--raise` is the only one that does; reach for plain
48
48
  `focus` unless a person needs to see the tab.
49
+ - **Show the work: `--show` / `BAC_SHOW_TAB=1`.** A person watching the Chrome
50
+ window sees whichever tab is SELECTED, and the tabs you work in are background
51
+ tabs — so by default they watch one stale page while titles change elsewhere
52
+ (filmed: eleven minutes on one tab during a real round). `goto --show` and
53
+ `new --show` make your tab the selected one; `export BAC_SHOW_TAB=1` turns it
54
+ on for every `goto`/`new` in the shell, so a skill sets it once.
55
+ **It only selects when the automation Chrome is already the frontmost app**,
56
+ and otherwise does nothing and says `Tab not shown: another app … is in front`.
57
+ That is the design, not a limitation to work around: on current Chrome every
58
+ way of selecting a tab from outside (`Target.activateTarget`,
59
+ `Page.bringToFront`, `/json/activate`, a foreground `new`, `window.open`)
60
+ also brings Chrome in front of whatever the person is using — measured
61
+ 2026-09-29. When Chrome is already in front nothing gets raised, which is the
62
+ case of someone watching it. The person's everyday Chrome counts as "another
63
+ app": it is checked by process, not by name. ⛔ Do not reach for `focus --raise`
64
+ to "make it show" — that is the screen-taking version; keep it for the moments
65
+ a person must look (a sign-in, a CAPTCHA). **macOS and Windows**; on Linux
66
+ `--show` reports that it cannot tell and does nothing. On Windows each
67
+ `--show` costs about 0.9 s (a PowerShell probe of the foreground window), so
68
+ turn it on where someone may be watching, not by reflex for batch work.
49
69
  - **Self-healing.** If the tab was closed (or Chrome restarted and reissued
50
70
  targetIds), the next `goto` just opens a fresh background tab for that session.
51
71
  - **Refs live in the DOM.** `snapshot` stamps `data-ba-ref="e7"` onto each
@@ -140,6 +160,7 @@ Page commands take a tab selector — `-s <session>` (default `$BAC_SESSION`, el
140
160
  | Inspect network (find the API, headers, bodies) | `browser-automation network -m bank --reload --filter api --headers --body` |
141
161
  | Screenshot a tab | `browser-automation screenshot -m op.fi --full -o shot.png` |
142
162
  | Make a hidden tab render (charts, video, polling) | `browser-automation focus -s work` (add `--raise` to really front it) |
163
+ | Let a person watching Chrome see the tab you work in | `goto --show` / `new --show`, or `export BAC_SHOW_TAB=1` once |
143
164
  | Prune stale session bookmarks + dead tabs | `browser-automation gc --dry` (then without `--dry`) |
144
165
  | Restart Chrome (LAST resort — closes ALL tabs, for EVERY session; only once `doctor` confirms the Mach name is absent) | `browser-automation launch --restart` |
145
166
  | Forget a session (tab stays open) | `browser-automation close -s work` |