@generativereality/browser-automation 0.5.0 → 0.5.1

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.5.0",
4
+ "version": "0.5.1",
5
5
  "author": {
6
6
  "name": "generativereality"
7
7
  },
package/dist/index.js CHANGED
@@ -9,7 +9,7 @@ import { execFileSync, spawn, 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.5.0";
12
+ var version = "0.5.1";
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,
@@ -345,8 +345,7 @@ async function withPage(targetId, fn) {
345
345
  * CDP `Input.*` events (and the user-activation they grant) are dropped by the
346
346
  * renderer when the tab's `visibilityState` is `hidden` — which it is whenever
347
347
  * the automation Chrome window isn't the frontmost OS window (the normal case:
348
- * the user is in their terminal). `Page.bringToFront` alone does NOT fix this;
349
- * the tab still reports `hidden`. `Emulation.setFocusEmulationEnabled` forces
348
+ * the user is in their terminal). `Emulation.setFocusEmulationEnabled` forces
350
349
  * the renderer to treat itself as focused+visible regardless of the real window
351
350
  * state (this is how Playwright drives backgrounded/headless pages), and
352
351
  * `Page.setWebLifecycleState: active` un-throttles a frozen tab. Together they
@@ -354,9 +353,20 @@ async function withPage(targetId, fn) {
354
353
  * drag actually lands and grants user activation — which activation-gated flows
355
354
  * (e.g. drop-zone uploaders that only start work inside a user gesture) require.
356
355
  *
357
- * All three are best-effort: older Chrome builds may not expose every command. */
356
+ * Both are best-effort: older Chrome builds may not expose every command.
357
+ *
358
+ * ⛔ **No `Page.bringToFront` here, and do not add it back.** It used to be the
359
+ * first call, and it makes this tab the SELECTED tab of its Chrome window: the
360
+ * tab the person had showing goes `hidden`, and the next time they bring Chrome
361
+ * forward and type, the keys land in the automated tab. That happened for real
362
+ * (issue #28, 2026-10-14): an agent's quiet `focus` left its Outlook calendar
363
+ * selected, and the person's typing created events named "A", "d", "w", "a",
364
+ * "cti" in their real calendar. It bought nothing: measured the same day on
365
+ * Chrome 155 / macOS 27, a background tab with ONLY the two commands below
366
+ * reports `visible` + `hasFocus()`, takes a CDP mouse click as
367
+ * `isTrusted: true` and a CDP key, and the person's tab stays the visible one
368
+ * throughout and after the probe tab is closed. */
358
369
  async function forceForeground(s) {
359
- await s.send("Page.bringToFront").catch(() => {});
360
370
  await s.send("Emulation.setFocusEmulationEnabled", { enabled: true }).catch(() => {});
361
371
  await s.send("Page.setWebLifecycleState", { state: "active" }).catch(() => {});
362
372
  }
@@ -1701,7 +1711,7 @@ const clickCommand = define({
1701
1711
  },
1702
1712
  trusted: {
1703
1713
  type: "boolean",
1704
- description: "Dispatch a real, genuinely-trusted CDP mouse click (Input.dispatchMouseEvent) at the element instead of the default JS-dispatched el.click(). Brings the tab to front and WAITS for it to be focused+visible (CDP input no-ops on a backgrounded tab), then waits for the element to be actionable (stable position + unoccluded hit-test) before pressing — mirroring Playwright. Use for widgets that demand isTrusted events AND animate in: artdeco dropdown menu items (LinkedIn More→Connect), Radix dropdown/popover triggers, cmdk comboboxes — which a default click, or an immediate trusted click on stale coordinates, only highlights without firing."
1714
+ description: "Dispatch a real, genuinely-trusted CDP mouse click (Input.dispatchMouseEvent) at the element instead of the default JS-dispatched el.click(). Makes the renderer treat the tab as focused+visible and WAITS until it reports so (CDP input no-ops on a backgrounded tab) — without selecting the tab in its window, so the person's own tab keeps their typing, then waits for the element to be actionable (stable position + unoccluded hit-test) before pressing — mirroring Playwright. Use for widgets that demand isTrusted events AND animate in: artdeco dropdown menu items (LinkedIn More→Connect), Radix dropdown/popover triggers, cmdk comboboxes — which a default click, or an immediate trusted click on stale coordinates, only highlights without firing."
1705
1715
  }
1706
1716
  },
1707
1717
  async run(ctx) {
@@ -1929,8 +1939,9 @@ const sleep$2 = (ms) => new Promise((r) => setTimeout(r, ms));
1929
1939
  * # The two ways, and why the quiet one is the default
1930
1940
  *
1931
1941
  * `Emulation.setFocusEmulationEnabled` makes the renderer treat itself as
1932
- * focused and visible whatever the real window is doing — no window moves, and
1933
- * the operator's frontmost app is undisturbed. That is what this does by
1942
+ * focused and visible whatever the real window is doing — no window moves, the
1943
+ * operator's frontmost app is undisturbed, and the tab their window SHOWS stays
1944
+ * the one it showed (it did not until issue #28: see forceForeground). That is what this does by
1934
1945
  * default, and it is how Playwright drives backgrounded pages.
1935
1946
  *
1936
1947
  * `--raise` additionally calls `Target.activateTarget`, which genuinely brings
@@ -1941,14 +1952,14 @@ const sleep$2 = (ms) => new Promise((r) => setTimeout(r, ms));
1941
1952
  *
1942
1953
  * # It reports the outcome, not the acceptance
1943
1954
  *
1944
- * All three CDP commands are best-effort — an older Chrome may not expose one —
1955
+ * Both CDP commands are best-effort — an older Chrome may not expose one —
1945
1956
  * so "sent" says nothing. This reads `document.hasFocus()` and
1946
1957
  * `visibilityState` back afterwards and prints what it actually achieved,
1947
1958
  * naming what it could not confirm rather than printing a tick over it.
1948
1959
  */
1949
1960
  const focusCommand = define({
1950
1961
  name: "focus",
1951
- 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.",
1962
+ 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, the operator keeps their frontmost app, and their window keeps showing its own tab. Add --raise to genuinely bring the tab to the front, which DOES take the screen.",
1952
1963
  args: {
1953
1964
  ...targetArgs,
1954
1965
  raise: {
@@ -2381,7 +2392,7 @@ function guessMime(p) {
2381
2392
  }
2382
2393
  const dropCommand = define({
2383
2394
  name: "drop",
2384
- description: "Drop local file(s) onto a drop-zone element by ref — for uploaders wired to drag-and-drop (a `drop` listener reading `e.dataTransfer.files`) rather than an <input type=file>. Default fires a genuinely-trusted CDP drag sequence (Input.dispatchDragEvent) carrying the real files from disk: brings the tab to front, waits for it to be focused+visible, waits for the target to be actionable (stable + unoccluded), then dragEnter→dragOver→drop — mirroring `click --trusted`. Use --js for a synthetic (isTrusted=false) DataTransfer drop that does NOT steal focus, for zones that accept synthetic events. For a static <input type=file> use `setfiles`; for a button that opens a file chooser use `upload`.",
2395
+ description: "Drop local file(s) onto a drop-zone element by ref — for uploaders wired to drag-and-drop (a `drop` listener reading `e.dataTransfer.files`) rather than an <input type=file>. Default fires a genuinely-trusted CDP drag sequence (Input.dispatchDragEvent) carrying the real files from disk: makes the renderer treat the tab as focused+visible (without selecting it in its window), waits for that, waits for the target to be actionable (stable + unoccluded), then dragEnter→dragOver→drop — mirroring `click --trusted`. Use --js for a synthetic (isTrusted=false) DataTransfer drop that does NOT steal focus, for zones that accept synthetic events. For a static <input type=file> use `setfiles`; for a button that opens a file chooser use `upload`.",
2385
2396
  args: {
2386
2397
  ...targetArgs,
2387
2398
  on: {
@@ -2394,7 +2405,7 @@ const dropCommand = define({
2394
2405
  },
2395
2406
  js: {
2396
2407
  type: "boolean",
2397
- description: "Dispatch a synthetic (isTrusted=false) DataTransfer drop instead of the trusted CDP path. Does not bring the tab to front (no focus steal). Injects each file's bytes into the page to build the File objects. Use for drop zones that accept synthetic events; falls short on zones that gate on isTrusted."
2408
+ description: "Dispatch a synthetic (isTrusted=false) DataTransfer drop instead of the trusted CDP path. Needs no focus emulation. Injects each file's bytes into the page to build the File objects. Use for drop zones that accept synthetic events; falls short on zones that gate on isTrusted."
2398
2409
  }
2399
2410
  },
2400
2411
  async run(ctx) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@generativereality/browser-automation",
3
- "version": "0.5.0",
3
+ "version": "0.5.1",
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": {
@@ -13,7 +13,11 @@ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
13
13
  # finish` points it at the released tag, so what ships is what was tagged —
14
14
  # while still running THIS copy of the script (an old tag's copy lacks fixes).
15
15
  REPO_ROOT="${BA_PLUGIN_SOURCE:-$(dirname "$SCRIPT_DIR")}"
16
- PLUGINS_DIR="${BA_PLUGINS_DIR:-$(dirname "$SCRIPT_DIR")/../plugins}" # override for tests
16
+ # Beside the MAIN checkout, not beside this script: a release run from a linked
17
+ # worktree (scratch dirs, .claude/worktrees/…) has no ../plugins next to it —
18
+ # 0.5.0's finish died there. --git-common-dir is the main checkout's .git.
19
+ MAIN_CHECKOUT="$(dirname "$(git -C "$SCRIPT_DIR" rev-parse --path-format=absolute --git-common-dir)")"
20
+ PLUGINS_DIR="${BA_PLUGINS_DIR:-$MAIN_CHECKOUT/../plugins}" # override for tests
17
21
  CHECK_ONLY=false
18
22
  [ "${1:-}" = "--check" ] && CHECK_ONLY=true
19
23
 
@@ -40,12 +40,23 @@ file under `~/.browser-automation/sessions/`.
40
40
  background, and nothing fronts a tab as a side effect of ordinary driving:
41
41
  `goto`, `read`, `snapshot`, `fill`, `eval`, `screenshot` all leave your
42
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.
43
+ `focus`, `click --trusted` and `drop` make the RENDERER believe the tab is
44
+ focused and visible (focus emulation; CDP input grants no user activation to
45
+ a renderer that considers itself hidden) — **no window moves, and the tab the
46
+ person's window shows stays the one it showed**. `focus --raise` calls
47
+ `Target.activateTarget` and **genuinely takes the operator's screen**; it is
48
+ the only one that does. Reach for plain `focus` unless a person needs to see
49
+ the tab.
50
+ - ⛔ **Selecting a tab moves where the person's typing goes.** Whatever tab a
51
+ Chrome window shows is where their keystrokes land the next time they bring
52
+ Chrome forward. Before CLI 0.5.1 a plain `focus` (and `click --trusted`,
53
+ `drop`) also selected the session's tab in its window; an agent's quiet
54
+ `focus` left an Outlook calendar selected, and the person's typing created
55
+ events named "A", "d", "w", "a", "cti" in their real calendar (issue #28,
56
+ 2026-10-14). So: `--show` and `focus --raise` are the only commands that
57
+ select a tab on purpose — use them when a person is meant to look, and on an
58
+ older CLI avoid `focus` on a tab where stray keys do damage (calendars, chat,
59
+ editors).
49
60
  - **Show the work: `--show` / `BAC_SHOW_TAB=1`.** A person watching the Chrome
50
61
  window sees whichever tab is SELECTED, and the tabs you work in are background
51
62
  tabs — so by default they watch one stale page while titles change elsewhere
@@ -216,9 +227,9 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
216
227
  those refs for one action → re-snapshot. "ref not found" means re-snapshot.
217
228
  - **`isTrusted` / synthetic events.** Clicks and fills are JS-dispatched by
218
229
  default, so widgets that demand trusted events ignore them. **For clicks, pass
219
- `--trusted`** — it dispatches a real CDP `Input.dispatchMouseEvent`, brings the
220
- tab to front, waits for it to be focused+visible (CDP input no-ops on a
221
- backgrounded tab) and waits for the element to be actionable (stable position +
230
+ `--trusted`** — it dispatches a real CDP `Input.dispatchMouseEvent`, makes the
231
+ renderer treat the tab as focused+visible (CDP input no-ops on a backgrounded
232
+ tab; the person's window keeps showing its own tab) and waits for the element to be actionable (stable position +
222
233
  unoccluded hit-test) before pressing. For fills, pass `--native` to drive
223
234
  character insertion through CDP `Input.insertText`, which fires real
224
235
  `beforeinput`/`input` events.
@@ -260,8 +271,8 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
260
271
  underlying export URL/endpoint and use `--url`, or the site's API.
261
272
  - **File upload — three paths:** `setfiles [ref] [path…]` for a static `<input type=file>`;
262
273
  `upload --click [ref] [path…]` for a button that opens a native file chooser; `drop [ref]
263
- [path…]` for a drag-and-drop zone with no file input (`--js` for a synthetic drop that does
264
- not front the tab). ⛔ **Upload once, verify by `snapshot`/`screenshot`, and don't blindly
274
+ [path…]` for a drag-and-drop zone with no file input (`--js` for a synthetic drop that needs
275
+ no focus emulation). ⛔ **Upload once, verify by `snapshot`/`screenshot`, and don't blindly
265
276
  retry** — each successful run adds another attachment, and apps reset `files` to 0 after
266
277
  consuming it. How each path works and when to pick it:
267
278
  [`references/input-and-forms.md`](references/input-and-forms.md).
@@ -118,11 +118,12 @@ under Gotchas; this is the detail and the worked cases behind them.
118
118
  all — a `drop` listener reading `e.dataTransfer.files` (vocalremover-style audio
119
119
  tools, many image/video drop zones). Neither `setfiles` nor `upload` applies;
120
120
  use `drop <ref> <path…>`. By default it fires a genuinely-**trusted** CDP drag
121
- (`Input.dispatchDragEvent`) carrying the real files from disk: it force-fronts
122
- the tab (bringToFront + focus emulation + active lifecycle — so the tab reports
123
- focused+visible even when the Chrome window isn't the frontmost OS window),
121
+ (`Input.dispatchDragEvent`) carrying the real files from disk: it forces the
122
+ tab foreground for the renderer (focus emulation + active lifecycle — so the
123
+ tab reports focused+visible even when the Chrome window isn't the frontmost OS
124
+ window, without selecting it in that window; see issue #28),
124
125
  waits for the zone to be actionable, then dragEnter→dragOver→drop. The
125
- force-front matters: drop-zone uploaders commonly do their work only inside a
126
+ forced foreground matters: drop-zone uploaders commonly do their work only inside a
126
127
  **user activation**, and CDP input grants no activation on a tab the renderer
127
128
  considers `hidden` — which it is whenever the window is occluded (the usual
128
129
  case while you work in the terminal). vocalremover.org is the canonical example: