@generativereality/browser-automation 0.4.11 → 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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@generativereality/browser-automation",
3
- "version": "0.4.11",
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": {
@@ -11,10 +11,19 @@
11
11
  # A browser process can permanently lose the ability to launch renderers (see
12
12
  # src/core/renderer-health.ts for the mechanism). Every existing tab keeps
13
13
  # working, so the browser looks fine, but no new tab or cross-origin
14
- # navigation ever will again. Restarting is the ONLY recovery — and plain
15
- # `launch` cannot do it, because it is idempotent by design and correctly
16
- # reports "already running". Without an explicit flag the only way out was to
17
- # go and kill Chrome by hand, which is how a diagnosis ends up unactionable.
14
+ # navigation ever will again. Restarting is the only recovery FROM THAT ONE
15
+ # CONDITION — and plain `launch` cannot do it, because it is idempotent by
16
+ # design and correctly reports "already running". Without an explicit flag the
17
+ # only way out was to go and kill Chrome by hand, which is how a diagnosis
18
+ # ends up unactionable.
19
+ #
20
+ # It is a flag and not an automatic step because it closes every tab of every
21
+ # session sharing this browser. That condition is confirmed by ONE thing: the
22
+ # Mach bootstrap name being absent from `launchctl print gui/$UID`. A new tab
23
+ # whose renderer is merely slow to answer looks identical and is not it — for
24
+ # three weeks it was reported as it, and restarting for it twice destroyed
25
+ # another session's unrecoverable work. `browser-automation doctor` now prints
26
+ # which of the two it is; nothing here can tell them apart.
18
27
  #
19
28
  # Why this script exists:
20
29
  # The `browser-automation` skill prefers to drive a real, persistent Chrome
@@ -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,8 +110,9 @@ 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
- | Restart Chrome (only fix for the renderer wedge — closes ALL tabs) | `browser-automation launch --restart` |
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` |
109
117
  | Forget **and** close the browser tab | `browser-automation close -s work --tab` |
110
118
 
@@ -287,11 +295,49 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
287
295
  isn't snapshot-interactive. After the drop, `read`/`screenshot`/`network` to
288
296
  confirm processing started, then grab the result (often a download endpoint you
289
297
  can pull with `download --url`).
298
+ - **A NEW tab's renderer can be slow rather than broken — do not restart Chrome for it.**
299
+ ⚠️ **Read this before acting on the wedge diagnosis below.** Measured 2026-09-11 on
300
+ Chrome 152.0.7977.83, time from `Target.createTarget` to the first `Runtime.evaluate`
301
+ returning, 8 trials each:
302
+
303
+ | how the target was created | median | worst |
304
+ |---|---|---|
305
+ | `background: true` (how this tool opens every tab) | 367ms | 12517ms, and >30s once |
306
+ | `background: true` + `Target.activateTarget` | 19ms | 65ms |
307
+ | `background: false` | 18ms | 22ms |
308
+
309
+ The renderer **process exists** in every arm — `ps` gains a `--type=renderer` child either
310
+ way. A background target is simply not given a renderer that answers promptly, and on a
311
+ loaded machine (this one was at load average 38) the tail runs past any budget worth
312
+ waiting. **This is not the wedge**, and a restart does nothing for it.
313
+
314
+ It cost real work to learn: for three weeks `goto` reported this as the permanent,
315
+ restart-only condition below, and `launch --restart` closes every tab of every session
316
+ sharing this Chrome. It twice destroyed unrecoverable work belonging to another session —
317
+ a finished AlternativeTo submission with hand edits, and an Azure signup flow mid-form.
318
+
319
+ **Since fixed (v0.4.12+):** `new`/`goto` wait for a late renderer and, if it still has not
320
+ answered, briefly activate the tab to force one and hand the window straight back (you get
321
+ a `WARN` saying so). The probe retries with a doubling budget, and the verdict now names
322
+ the permanent failure **only when its own signature is present**. On an older CLI, the
323
+ cheap move is to retry, or to drive a tab that already works.
324
+
325
+ **Whatever the version: before restarting anything, check the two corroborations.** Both
326
+ were decisive and neither used to be consulted:
327
+ ```bash
328
+ launchctl print "gui/$(id -u)" | grep MachPortRendezvousServer.<browser-pid>
329
+ ps -Ao command= | grep -c -- '--type=renderer'
330
+ ```
331
+ Mach name **present** + renderers **alive** ⇒ this is slowness, not the wedge. Retry, or use
332
+ a live tab. Mach name **absent** ⇒ it is the wedge, and only then is a restart the answer.
333
+
290
334
  - **"The site is blocking us" — when it is really Chrome that cannot make renderers.**
291
335
  A browser process can permanently lose the ability to launch **renderer processes** while
292
336
  looking perfectly healthy. Every tab that already exists keeps working, so nothing seems wrong
293
337
  until you open a tab or navigate somewhere new, and then the errors read as the remote site's
294
338
  doing. Diagnosed 2026-08-22; it cost an hour of blaming ferry-operator bot protection.
339
+ ⚠️ **This is a real condition and a rare one.** Confirm the Mach name is absent (above)
340
+ before you believe it — a slow background renderer produces every symptom in this list.
295
341
 
296
342
  How it shows up:
297
343
  - `browser-automation new` + `goto` → `CDP Page.enable timed out after 30000ms`, **even for
@@ -366,18 +412,34 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
366
412
  `Page.enable timed out` now arrives with the diagnosis attached instead of sending you to the
367
413
  site's bot-protection docs.
368
414
 
369
- **Recovery — only a Chrome restart clears it.** The bootstrap name is registered at startup and
370
- never re-registered, so nothing short of a new browser process helps. Closing tabs does not, and
371
- plain `launch` will not either (idempotent by design — it sees a live browser and exits happy):
372
- ```bash
373
- browser-automation launch --restart # SIGTERM (profile flushes cleanly), wait, relaunch
374
- ```
375
- It reports how many tabs it is about to close. **Those tabs belong to every parallel Claude Code
376
- session sharing this Chrome — ask Fred first, never restart unilaterally.**
415
+ **Recovery — cheapest first, and a restart only once the Mach name is confirmed absent.**
416
+
417
+ 1. **Retry.** A new tab's renderer has been measured taking 12s and more on a loaded
418
+ machine, and late is not broken.
419
+ 2. **Drive a tab that already works.** An existing tab navigates same-origin without
420
+ needing a new renderer, so it keeps working throughout even during a genuine wedge:
421
+ ```bash
422
+ browser-automation list
423
+ browser-automation eval -t <id> "location.href='<url>'"
424
+ ```
425
+ 3. **`browser-automation doctor`** — re-measures, prints the two corroborations, and shows
426
+ the recent probe-time distribution from `~/.browser-automation/renderer-probes.jsonl`.
427
+ 4. **Only if `doctor` reports the Mach rendezvous service ABSENT**, restart. The bootstrap
428
+ name is registered at startup and never re-registered, so nothing short of a new browser
429
+ process helps; closing tabs does not, and plain `launch` will not either (idempotent by
430
+ design — it sees a live browser and exits happy):
431
+ ```bash
432
+ browser-automation launch --restart # SIGTERM (profile flushes cleanly), wait, relaunch
433
+ ```
434
+ It reports how many tabs it is about to close. **Those tabs belong to every parallel
435
+ Claude Code session sharing this Chrome — ask Fred first, never restart unilaterally.**
377
436
 
378
437
  **Housekeeping is a different problem** — `browser-automation gc` prunes stale session bookmarks
379
438
  (they are never cleaned up otherwise; this machine had accumulated 234, only 5 of them live) and
380
- closes tabs whose renderer does not answer. Use `--dry` first. It is genuinely useful, but it is
439
+ closes tabs whose renderer does not answer. Use `--dry` first. `list` now counts stale
440
+ bookmarks instead of printing them (`list --all` to see them) — 105 stale lines above a
441
+ 24-tab Chrome is how "there are a hundred tabs open" became the leading theory for a
442
+ renderer failure that has nothing to do with tab count. It is genuinely useful, but it is
381
443
  **not** a fix for the wedge above, and it never closes a working tab unless you pass `--orphans`
382
444
  — tabs get addressed by `-m` and opened by hand, so "no session claims it" is not evidence that
383
445
  nobody wants it.
@@ -404,10 +466,20 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
404
466
  stuck `len` is the whole tell: `hidden` on its own is the normal, healthy state of every
405
467
  backgrounded tab — verified 2026-09-07, a background tab reporting `hidden` returned its real
406
468
  painted text — so never read `hidden` alone as a diagnosis.
407
- **Fix:** front the tab. There is no `activate` command — a `click --trusted` on any harmless
408
- element (a wrapper `div` from the snapshot works; avoid submit buttons and links) brings the tab
409
- to front and waits for it to be visible, and the page paints immediately. Same root cause as the
410
- 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.)*
411
483
 
412
484
  **Do not confuse this with the renderer wedge above.** Both present to an operator as "the page
413
485
  isn't there, but every tool says fine", and the fixes are opposite — one is a per-tab nudge, the
@@ -419,7 +491,7 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
419
491
  | `eval` | works, returns a result | **`Runtime.evaluate` times out at 30000ms** |
420
492
  | scope | that one tab | **every** new tab / cross-origin nav |
421
493
  | `doctor` | `✓ Renderer capacity` | names the wedge + pid |
422
- | fix | `click --trusted` on the tab | `launch --restart` (**ask first**) |
494
+ | fix | `focus` on the tab | `launch --restart` (**ask first**) |
423
495
 
424
496
  `eval` is the fast discriminator: if it answers at all, the renderer is alive and you are in the
425
497
  painting case. If it times out, stop poking the page and run `doctor`.