@generativereality/browser-automation 0.4.10 → 0.4.11

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.10",
4
+ "version": "0.4.11",
5
5
  "author": {
6
6
  "name": "generativereality"
7
7
  },
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.10";
12
+ var version = "0.4.11";
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,
@@ -29,7 +29,7 @@ var package_default = {
29
29
  "typecheck": "tsc --noEmit",
30
30
  "check": "npm run typecheck && bash scripts/check-one-port.sh && npm run build && npm test",
31
31
  "test": "node --test \"test/**/*.test.mjs\"",
32
- "release": "bumpp && npm publish",
32
+ "release": "echo 'Releases publish from CI, not here. Bump package.json + .claude-plugin/plugin.json, commit onto master, then: git tag vX.Y.Z && git push origin vX.Y.Z — then approve the gated job in GitHub Actions. `npm publish` from a laptop 404s (granular token). See .github/workflows/release.yml.' >&2; exit 1",
33
33
  "sync-plugin": "bash scripts/sync-plugin.sh",
34
34
  "prepack": "npm run build"
35
35
  },
@@ -361,22 +361,32 @@ async function forceForeground(s) {
361
361
  await s.send("Page.setWebLifecycleState", { state: "active" }).catch(() => {});
362
362
  }
363
363
  /** Run `fn` against the browser-level endpoint (Target.* commands), then close. */
364
- async function withBrowser(fn) {
365
- const s = await connect(await browserWsUrl());
364
+ async function withBrowser(fn, timeout) {
365
+ const s = await connect(await browserWsUrl(), timeout === void 0 ? void 0 : { timeout });
366
366
  try {
367
367
  return await fn(s);
368
368
  } finally {
369
369
  s.close();
370
370
  }
371
371
  }
372
- /** Create a new tab in the BACKGROUND (never steals focus) -> returns targetId. */
373
- async function createTab(url = "about:blank") {
372
+ /**
373
+ * Create a new tab in the BACKGROUND (never steals focus) -> returns targetId.
374
+ *
375
+ * `timeout` exists for the health probe. On a browser that has lost the ability
376
+ * to make renderers, `Target.createTarget` itself can hang rather than fail, so
377
+ * a caller that means to spend ~100ms deciding whether the browser works would
378
+ * otherwise sit on the default 30s — measured 2026-09-07, when this put a 30s
379
+ * stall in front of every `launch` on a wedged Chrome. Ordinary callers pass
380
+ * nothing and keep the generous default, which is right for them: a real tab
381
+ * opening slowly should still open.
382
+ */
383
+ async function createTab(url = "about:blank", { timeout } = {}) {
374
384
  return withBrowser(async (s) => {
375
385
  return (await s.send("Target.createTarget", {
376
386
  url,
377
387
  background: true
378
- })).targetId;
379
- });
388
+ }, timeout)).targetId;
389
+ }, timeout);
380
390
  }
381
391
  async function closeTab(targetId) {
382
392
  return withBrowser(async (s) => {
@@ -482,7 +492,7 @@ async function probeRenderer({ timeout = 5e3 } = {}) {
482
492
  } catch {}
483
493
  let targetId;
484
494
  try {
485
- targetId = await createTab("about:blank");
495
+ targetId = await createTab("about:blank", { timeout });
486
496
  } catch (e) {
487
497
  return {
488
498
  ok: false,
@@ -616,7 +626,7 @@ function explainRendererFailure(h) {
616
626
  ];
617
627
  if (rendezvous === false) lines.push(` root cause: the browser process (pid ${pid}) has lost its Mach bootstrap`, ` service "com.google.Chrome.MachPortRendezvousServer.${pid}".`, ` Chrome registers that name once, at startup; every child`, ` process looks it up to receive its shared memory. With the`, ` name gone, every renderer Chrome launches immediately exits.`, ` This is permanent for this browser process.`);
618
628
  else if (rendezvous === true) lines.push(` note: the Mach rendezvous service for pid ${pid} IS still registered,`, ` so this is a different renderer failure from the one seen on`, ` 2026-08-22. Chrome's own log will say why:`, ` tail -50 ${chromeLogPath()}`);
619
- lines.push(``, `This is a browser-level failure. It is NOT the site blocking automation, and`, `retrying, changing the URL, or adding a user agent will not help. Two tells:`, `same-origin navigations in tabs that already work keep working (they reuse a`, `renderer that already exists), and cross-origin ones fail with ERR_ABORTED`, `(site isolation needs a new renderer, which is the thing Chrome can't do).`, ``, `Recovery: restart Chrome. Nothing else clears it — closing tabs does not,`, `and plain \`launch\` will not either (it is idempotent and sees a live browser).`, ``, ` browser-automation launch --restart # closes ALL tabs, then relaunches`, ``, `If other sessions are driving this Chrome, agree on the restart first — their`, `open tabs go with it. \`browser-automation list\` shows who holds what.`);
629
+ lines.push(``, `This is a browser-level failure. It is NOT the site blocking automation, and`, `retrying, changing the URL, or adding a user agent will not help. Two tells:`, `same-origin navigations in tabs that already work keep working (they reuse a`, `renderer that already exists), and cross-origin ones fail with ERR_ABORTED`, `(site isolation needs a new renderer, which is the thing Chrome can't do).`, ``, `Recovery: restart Chrome. Nothing else clears it — closing tabs does not,`, `and plain \`launch\` will not either: it now DETECTS this (it runs this same`, `probe and fails), but it will never restart a browser other sessions may be`, `using without being told to. Restarting is always something you type.`, ``, ` browser-automation launch --restart # closes ALL tabs, then relaunches`, ``, `If other sessions are driving this Chrome, agree on the restart first — their`, `open tabs go with it. \`browser-automation list\` shows who holds what.`);
620
630
  return lines.join("\n");
621
631
  }
622
632
  /**
@@ -2129,11 +2139,11 @@ function launchScriptPath() {
2129
2139
  //#region src/commands/launch.ts
2130
2140
  const launchCommand = define({
2131
2141
  name: "launch",
2132
- description: "Start (idempotent) this user's headed Chrome with the persistent profile",
2142
+ description: "Start (idempotent) this user's headed Chrome with the persistent profile, and verify it can still make renderers",
2133
2143
  args: {
2134
2144
  status: {
2135
2145
  type: "boolean",
2136
- description: "Only report whether the CDP browser is up (exit 0/1)"
2146
+ description: "Only report whether the CDP browser is up (exit 0/1) — reachability, not health"
2137
2147
  },
2138
2148
  restart: {
2139
2149
  type: "boolean",
@@ -2152,7 +2162,21 @@ const launchCommand = define({
2152
2162
  ...ctx.values.status ? ["--status"] : [],
2153
2163
  ...ctx.values.restart ? ["--restart"] : []
2154
2164
  ]], { stdio: "inherit" });
2155
- process.exit(r.status ?? 1);
2165
+ if (r.status !== 0 || ctx.values.status) process.exit(r.status ?? 1);
2166
+ const health = await probeRenderer().catch((e) => ({
2167
+ ok: false,
2168
+ ms: 0,
2169
+ pageTargets: 0,
2170
+ reason: String(e?.message ?? e)
2171
+ }));
2172
+ if (health.ok) {
2173
+ consola.success(`Renderer capacity: a new tab got a live renderer in ${health.ms}ms — this Chrome works.`);
2174
+ return;
2175
+ }
2176
+ consola.error("Chrome is up, but it cannot make renderers — this browser is unusable.\n");
2177
+ for (const line of explainRendererFailure(health).split("\n")) consola.log(line);
2178
+ consola.log(`\nChrome's own log: ${chromeLogPath()}`);
2179
+ process.exit(1);
2156
2180
  }
2157
2181
  });
2158
2182
  //#endregion
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@generativereality/browser-automation",
3
- "version": "0.4.10",
3
+ "version": "0.4.11",
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": {
@@ -18,7 +18,7 @@
18
18
  "typecheck": "tsc --noEmit",
19
19
  "check": "npm run typecheck && bash scripts/check-one-port.sh && npm run build && npm test",
20
20
  "test": "node --test \"test/**/*.test.mjs\"",
21
- "release": "bumpp && npm publish",
21
+ "release": "echo 'Releases publish from CI, not here. Bump package.json + .claude-plugin/plugin.json, commit onto master, then: git tag vX.Y.Z && git push origin vX.Y.Z — then approve the gated job in GitHub Actions. `npm publish` from a laptop 404s (granular token). See .github/workflows/release.yml.' >&2; exit 1",
22
22
  "sync-plugin": "bash scripts/sync-plugin.sh",
23
23
  "prepack": "npm run build"
24
24
  },
@@ -133,11 +133,23 @@ if [ "$RESTART" = "1" ] && is_up; then
133
133
  sleep 1
134
134
  fi
135
135
 
136
+ # A held port is the ONLY thing this branch establishes. It is emphatically not
137
+ # a health check: a Chrome that can no longer give a new tab a renderer keeps
138
+ # serving this port, answering /json/version and listing targets, while every
139
+ # goto fails. Only a round-trip through a renderer tells the two apart, and
140
+ # that lives in the CLI (src/core/renderer-health.ts) -- `browser-automation
141
+ # launch` runs it right after this script returns and prints the real verdict.
142
+ #
143
+ # This used to print a standing "use --restart if renderers are broken" hint
144
+ # here. It was correct advice and it did not work: printed on every launch,
145
+ # directly under the words "nothing to do", it read as boilerplate rather than
146
+ # as a diagnosis, and an operator burned many minutes on 25-30s `goto`s in
147
+ # 2026-09 without it registering. Advice that is always on screen carries no
148
+ # information. The verdict now appears only when it is true.
136
149
  if is_up; then
137
- echo "Already running on :${PORT} — nothing to do."
150
+ echo "Already running on :${PORT} — the port is held."
138
151
  echo "Drive it with: browser-automation goto -s <session> <url>"
139
- echo "(To force a fresh browser process — the only fix for a Chrome that can no"
140
- echo " longer launch renderers — use: browser-automation launch --restart)"
152
+ echo "(Port held is not health. Check it works: browser-automation doctor)"
141
153
  exit 0
142
154
  fi
143
155
 
@@ -56,12 +56,26 @@ file under `~/.browser-automation/sessions/`.
56
56
 
57
57
  ```bash
58
58
  npm install -g @generativereality/browser-automation
59
- browser-automation launch # start this user's Chrome (idempotent)
60
- browser-automation doctor # verify Node, Chrome, targets, sessions
59
+ browser-automation launch # start Chrome, and prove it can still make renderers
60
+ browser-automation doctor # verify Node, Chrome, renderer capacity, targets, sessions
61
61
  ```
62
62
 
63
- `launch` is idempotent — safe to call when Chrome is already up. Override the
64
- profile path with `BROWSER_AUTOMATION_PROFILE=...` and the CDP host with
63
+ `launch` is idempotent — safe to call when Chrome is already up. **It also
64
+ verifies the browser works**, which is a different question from whether one is
65
+ running: it ends with either
66
+
67
+ ```
68
+ ✔ Renderer capacity: a new tab got a live renderer in 47ms — this Chrome works.
69
+ ```
70
+
71
+ or a non-zero exit and the full renderer-wedge diagnosis. That matters because a
72
+ held port, a `/json/version` that answers and a `list` full of targets are all
73
+ properties of the browser **process**, and the way a long-lived Chrome dies is
74
+ that it keeps all three while losing the ability to give any new tab a
75
+ **renderer** (see Gotchas). Older CLIs printed `nothing to do.` in exactly that
76
+ state — **if your `launch` ends without a `Renderer capacity:` line, you are on
77
+ one of those; run `doctor`, which is the same probe.** Override the profile path
78
+ with `BROWSER_AUTOMATION_PROFILE=...` and the CDP host with
65
79
  `BROWSER_AUTOMATION_CDP=http://localhost:PORT` if needed.
66
80
 
67
81
  ## Commands
@@ -71,7 +85,7 @@ Page commands take a tab selector — `-s <session>` (default `$BAC_SESSION`, el
71
85
 
72
86
  | Need | Command |
73
87
  |---|---|
74
- | Start/refresh the Chrome | `browser-automation launch` |
88
+ | Start the Chrome + verify it can make renderers | `browser-automation launch` |
75
89
  | Diagnose setup (incl. renderer capacity) | `browser-automation doctor` |
76
90
  | List sessions + every open tab (id, title, url) | `browser-automation list` |
77
91
  | Open a background tab | `browser-automation new -s work [url]` |
@@ -291,6 +305,26 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
291
305
  right URL but an **empty title forever**; every `Runtime.evaluate` against it times out.
292
306
  `Page.captureScreenshot` returns `Internal error`. The target shell exists; the renderer does not.
293
307
 
308
+ **It gets SLOW before it fails outright — that is the early warning.** Observed 2026-09-07 on a
309
+ Chrome that had been up 12 days: every `goto` took ~25–30s, and a batch of three blew a 120s
310
+ timeout, hours before anything failed hard. That was misread as "large files, slow browser" and
311
+ worked around with longer timeouts for many minutes; the actual fix was one `launch --restart`,
312
+ after which the same pages loaded instantly and 14 `file://` tabs opened in two quick batches.
313
+ **A `goto` that has quietly become slow is this, not your page.** Raise the timeout at most once,
314
+ then run `doctor`.
315
+
316
+ **Every cheap signal stays green, so do not take any of them as health.** On that same wedged
317
+ browser: `launch` said `Already running on :9223 — nothing to do.`, `curl :9223/json/version`
318
+ answered normally, and `list` cheerfully returned 10 targets — while `goto` exited 1 and `eval`
319
+ died with `CDP Runtime.evaluate timed out after 30000ms`. Port held, HTTP endpoint answering and
320
+ targets listed are all properties of the **browser** process; the thing that is broken is its
321
+ ability to start a **renderer**, and only a probe that runs code in one can see it.
322
+ **Since fixed:** `launch` now runs that probe itself and exits non-zero with the diagnosis
323
+ instead of reporting "nothing to do", so this particular green-across-the-board trap is closed.
324
+ It still will not restart for you — that stays something you type, because the tabs are not
325
+ only yours. On a CLI old enough to lack it, `doctor` is the same probe; nothing cheaper
326
+ substitutes for either.
327
+
294
328
  **The mechanism** (macOS, from Chrome's own log at `$TMPDIR/chrome-<port>.log` — `launch --restart`
295
329
  keeps the previous browser's log as `chrome-<port>.log.prev`, which is the one you want after a
296
330
  restart):
@@ -354,6 +388,41 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
354
388
  is a completely different client. Check the browser first: if `doctor` says renderer capacity is
355
389
  fine and a boring cross-origin URL loads, *then* start suspecting the site.
356
390
 
391
+ - **A backgrounded tab may never paint at all — and `read`/`snapshot` will not tell you.** Distinct
392
+ from "still loading": `document.readyState` reaches `complete`, but the SPA never renders, so
393
+ `read` returns a stale shell (e.g. a bare "Loading") and `snapshot` lists none of the real
394
+ controls. The trap is that this looks exactly like *the page does not have that element*, and you
395
+ will go hunting for a different selector or conclude the flow changed. Measured 2026-09-02 on
396
+ Google's `accounts.google.com/v3/signin/challenge/pwd`: `readyState: "complete"`,
397
+ `body.innerText.length: 202` frozen on the previous step's text, and the password field present in
398
+ the DOM but `offsetParent === null` for as long as the tab stayed backgrounded.
399
+ **Diagnose** before changing your selector:
400
+ ```bash
401
+ browser-automation eval -s x '({ready:document.readyState,vis:document.visibilityState,len:document.body.innerText.length})'
402
+ ```
403
+ `visibilityState: "hidden"` with a **stuck `len`** is this, not a selector problem. Note the
404
+ stuck `len` is the whole tell: `hidden` on its own is the normal, healthy state of every
405
+ backgrounded tab — verified 2026-09-07, a background tab reporting `hidden` returned its real
406
+ 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.
411
+
412
+ **Do not confuse this with the renderer wedge above.** Both present to an operator as "the page
413
+ isn't there, but every tool says fine", and the fixes are opposite — one is a per-tab nudge, the
414
+ other closes every tab in the browser. What separates them:
415
+
416
+ | | backgrounded tab never paints | Chrome cannot make renderers |
417
+ |---|---|---|
418
+ | `goto` | succeeds, rc=0 (may be slow) | **rc=1**, or `Page.enable timed out` |
419
+ | `eval` | works, returns a result | **`Runtime.evaluate` times out at 30000ms** |
420
+ | scope | that one tab | **every** new tab / cross-origin nav |
421
+ | `doctor` | `✓ Renderer capacity` | names the wedge + pid |
422
+ | fix | `click --trusted` on the tab | `launch --restart` (**ask first**) |
423
+
424
+ `eval` is the fast discriminator: if it answers at all, the renderer is alive and you are in the
425
+ painting case. If it times out, stop poking the page and run `doctor`.
357
426
  - **Page still loading.** `goto` waits for the load event, but SPAs render after.
358
427
  If a `read`/`snapshot` looks empty, re-run after a moment, or snapshot again
359
428
  once a known element should be present.