@generativereality/browser-automation 0.4.9 → 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.9",
4
+ "version": "0.4.11",
5
5
  "author": {
6
6
  "name": "generativereality"
7
7
  },
package/README.md CHANGED
@@ -122,6 +122,12 @@ same one-action-per-snapshot rule as Playwright refs.
122
122
 
123
123
  ## Notes & limits
124
124
 
125
+ - **Values are plain POSIX argv.** A positional such as `fill`'s value may contain
126
+ anything — `--force`, a markdown `---` rule, newlines — as long as the shell
127
+ hands it over as one element (quote it). Only an element that *begins* with a
128
+ dash and looks like an option (`--force`, `-5`) is read as one; to pass such a
129
+ value literally, end option parsing with `--`: `fill -t <id> -- e3 "--force"`.
130
+ An unknown option is an error that names the offending element.
125
131
  - Interactions are **JS-dispatched** (`element.click()`, native value setter +
126
132
  `input`/`change`), which works on background tabs (native CDP mouse events do
127
133
  not reliably reach a non-foreground tab in headed Chrome). Synthetic events are
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.9";
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,
@@ -27,8 +27,9 @@ var package_default = {
27
27
  "dev": "bun run ./src/index.ts",
28
28
  "build": "tsdown",
29
29
  "typecheck": "tsc --noEmit",
30
- "check": "npm run typecheck && bash scripts/check-one-port.sh && npm run build",
31
- "release": "bumpp && npm publish",
30
+ "check": "npm run typecheck && bash scripts/check-one-port.sh && npm run build && npm test",
31
+ "test": "node --test \"test/**/*.test.mjs\"",
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",
32
33
  "sync-plugin": "bash scripts/sync-plugin.sh",
33
34
  "prepack": "npm run build"
34
35
  },
@@ -66,6 +67,117 @@ var package_default = {
66
67
  }
67
68
  };
68
69
  //#endregion
70
+ //#region src/core/argv.ts
71
+ var UsageError = class extends Error {
72
+ constructor(message) {
73
+ super(message);
74
+ this.name = "UsageError";
75
+ }
76
+ };
77
+ const COMMON = {
78
+ help: {
79
+ type: "boolean",
80
+ short: "h"
81
+ },
82
+ version: {
83
+ type: "boolean",
84
+ short: "v"
85
+ }
86
+ };
87
+ const PLACEHOLDER_PREFIX = "\0positional:";
88
+ function placeholder(i) {
89
+ return `${PLACEHOLDER_PREFIX}${i}`;
90
+ }
91
+ /** Map gunshi's positionals (which contain placeholders) back to the real values. */
92
+ function restorePositionals(positionals, real) {
93
+ return positionals.map((p) => {
94
+ if (!p.startsWith(PLACEHOLDER_PREFIX)) return p;
95
+ return real[Number(p.slice(12))] ?? p;
96
+ });
97
+ }
98
+ function isOptionShaped(arg) {
99
+ return /^--?[A-Za-z0-9]/.test(arg);
100
+ }
101
+ function separatorHint(sub, positionals, token) {
102
+ return `To pass it as a value, put '--' before the positionals: browser-automation ${sub} [options] -- ${[...positionals, token].map((p) => `'${p}'`).join(" ")}`;
103
+ }
104
+ /**
105
+ * Canonicalise everything after the subcommand.
106
+ *
107
+ * @param sub the subcommand name (argv[0])
108
+ * @param rest argv after the subcommand
109
+ * @param schema the command's declared args (gunshi's `args` table)
110
+ */
111
+ function canonicalize(sub, rest, schema) {
112
+ const specs = {
113
+ ...COMMON,
114
+ ...schema
115
+ };
116
+ const byShort = /* @__PURE__ */ new Map();
117
+ for (const [name, spec] of Object.entries(specs)) if (spec.short) byShort.set(spec.short, name);
118
+ const options = [];
119
+ const positionals = [];
120
+ const unknown = (token) => {
121
+ throw new UsageError(`'${token}' is not an option of '${sub}'. ${separatorHint(sub, positionals, token)}`);
122
+ };
123
+ const takesValue = (name) => specs[name].type !== "boolean";
124
+ let i = 0;
125
+ let terminated = false;
126
+ while (i < rest.length) {
127
+ const arg = rest[i++];
128
+ if (!terminated && arg === "--") {
129
+ terminated = true;
130
+ continue;
131
+ }
132
+ if (terminated || !isOptionShaped(arg)) {
133
+ positionals.push(arg);
134
+ continue;
135
+ }
136
+ if (arg.startsWith("--")) {
137
+ const eq = arg.indexOf("=");
138
+ const name = eq === -1 ? arg.slice(2) : arg.slice(2, eq);
139
+ if (!(name in specs) || specs[name].type === "positional") return unknown(arg);
140
+ if (!takesValue(name)) {
141
+ if (eq !== -1) throw new UsageError(`'--${name}' is a flag and takes no value (got '${arg}')`);
142
+ options.push(`--${name}`);
143
+ continue;
144
+ }
145
+ let value;
146
+ if (eq !== -1) value = arg.slice(eq + 1);
147
+ else if (i < rest.length) value = rest[i++];
148
+ else throw new UsageError(`'${arg}' needs a value`);
149
+ options.push(`--${name}=${value}`);
150
+ continue;
151
+ }
152
+ let j = 1;
153
+ while (j < arg.length) {
154
+ const short = arg[j++];
155
+ const name = byShort.get(short);
156
+ if (!name) return unknown(`-${short}`);
157
+ if (!takesValue(name)) {
158
+ options.push(`--${name}`);
159
+ continue;
160
+ }
161
+ let remainder = arg.slice(j);
162
+ if (remainder.startsWith("=")) remainder = remainder.slice(1);
163
+ let value;
164
+ if (remainder.length > 0) value = remainder;
165
+ else if (i < rest.length) value = rest[i++];
166
+ else throw new UsageError(`'-${short}' needs a value`);
167
+ options.push(`--${name}=${value}`);
168
+ break;
169
+ }
170
+ }
171
+ return {
172
+ argv: [
173
+ sub,
174
+ ...options,
175
+ ...positionals.map((_, k) => placeholder(k))
176
+ ],
177
+ positionals
178
+ };
179
+ }
180
+ //#endregion
69
181
  //#region src/core/session.ts
70
182
  const DIR = join(homedir(), ".browser-automation", "sessions");
71
183
  function file(name) {
@@ -249,22 +361,32 @@ async function forceForeground(s) {
249
361
  await s.send("Page.setWebLifecycleState", { state: "active" }).catch(() => {});
250
362
  }
251
363
  /** Run `fn` against the browser-level endpoint (Target.* commands), then close. */
252
- async function withBrowser(fn) {
253
- 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 });
254
366
  try {
255
367
  return await fn(s);
256
368
  } finally {
257
369
  s.close();
258
370
  }
259
371
  }
260
- /** Create a new tab in the BACKGROUND (never steals focus) -> returns targetId. */
261
- 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 } = {}) {
262
384
  return withBrowser(async (s) => {
263
385
  return (await s.send("Target.createTarget", {
264
386
  url,
265
387
  background: true
266
- })).targetId;
267
- });
388
+ }, timeout)).targetId;
389
+ }, timeout);
268
390
  }
269
391
  async function closeTab(targetId) {
270
392
  return withBrowser(async (s) => {
@@ -370,7 +492,7 @@ async function probeRenderer({ timeout = 5e3 } = {}) {
370
492
  } catch {}
371
493
  let targetId;
372
494
  try {
373
- targetId = await createTab("about:blank");
495
+ targetId = await createTab("about:blank", { timeout });
374
496
  } catch (e) {
375
497
  return {
376
498
  ok: false,
@@ -504,7 +626,7 @@ function explainRendererFailure(h) {
504
626
  ];
505
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.`);
506
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()}`);
507
- 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.`);
508
630
  return lines.join("\n");
509
631
  }
510
632
  /**
@@ -2017,11 +2139,11 @@ function launchScriptPath() {
2017
2139
  //#region src/commands/launch.ts
2018
2140
  const launchCommand = define({
2019
2141
  name: "launch",
2020
- 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",
2021
2143
  args: {
2022
2144
  status: {
2023
2145
  type: "boolean",
2024
- 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"
2025
2147
  },
2026
2148
  restart: {
2027
2149
  type: "boolean",
@@ -2040,7 +2162,21 @@ const launchCommand = define({
2040
2162
  ...ctx.values.status ? ["--status"] : [],
2041
2163
  ...ctx.values.restart ? ["--restart"] : []
2042
2164
  ]], { stdio: "inherit" });
2043
- 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);
2044
2180
  }
2045
2181
  });
2046
2182
  //#endregion
@@ -2268,13 +2404,38 @@ const subCommands = new Map([
2268
2404
  ["prune", gcCommand],
2269
2405
  ["port", portCommand]
2270
2406
  ]);
2407
+ function withRealPositionals(cmd, real) {
2408
+ return {
2409
+ ...cmd,
2410
+ async run(ctx) {
2411
+ return cmd.run?.({
2412
+ ...ctx,
2413
+ positionals: restorePositionals(ctx.positionals, real)
2414
+ });
2415
+ }
2416
+ };
2417
+ }
2271
2418
  async function run() {
2272
- await cli(process.argv.slice(2), defaultCommand, {
2419
+ let argv = process.argv.slice(2);
2420
+ let commands = subCommands;
2421
+ const sub = argv[0];
2422
+ const command = sub === void 0 ? void 0 : subCommands.get(sub);
2423
+ if (sub !== void 0 && command) {
2424
+ const canonical = canonicalize(sub, argv.slice(1), command.args ?? {});
2425
+ argv = canonical.argv;
2426
+ commands = new Map(subCommands);
2427
+ commands.set(sub, withRealPositionals(command, canonical.positionals));
2428
+ }
2429
+ await cli(argv, defaultCommand, {
2273
2430
  name: "browser-automation",
2274
2431
  version,
2275
2432
  description,
2276
- subCommands,
2277
- renderHeader: null
2433
+ subCommands: commands,
2434
+ renderHeader: null,
2435
+ renderValidationErrors: async (_ctx, error) => {
2436
+ process.exitCode = 1;
2437
+ return error.errors.map((e) => e instanceof Error ? e.message : String(e)).join("\n");
2438
+ }
2278
2439
  });
2279
2440
  }
2280
2441
  //#endregion
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@generativereality/browser-automation",
3
- "version": "0.4.9",
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": {
@@ -16,8 +16,9 @@
16
16
  "dev": "bun run ./src/index.ts",
17
17
  "build": "tsdown",
18
18
  "typecheck": "tsc --noEmit",
19
- "check": "npm run typecheck && bash scripts/check-one-port.sh && npm run build",
20
- "release": "bumpp && npm publish",
19
+ "check": "npm run typecheck && bash scripts/check-one-port.sh && npm run build && npm test",
20
+ "test": "node --test \"test/**/*.test.mjs\"",
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",
21
22
  "sync-plugin": "bash scripts/sync-plugin.sh",
22
23
  "prepack": "npm run build"
23
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]` |
@@ -134,6 +148,12 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
134
148
 
135
149
  ## Gotchas
136
150
 
151
+ - **Values may contain `--` freely.** `fill -s work e3 "see the --native flag"`
152
+ and a whole markdown brief with `---` rules go through as one quoted argv
153
+ element. Only a value that *begins* with a dash and is option-shaped
154
+ (`--force`, `-5`) needs the POSIX separator: `fill -s work -- e3 "--force"`.
155
+ An error naming the element (`'--force' is not an option of 'fill'`)
156
+ means exactly that — add `--`, do not re-quote.
137
157
  - **Refs go stale after any DOM change**, not just navigation. Snapshot → use
138
158
  those refs for one action → re-snapshot. "ref not found" means re-snapshot.
139
159
  - **`isTrusted` / synthetic events.** Clicks and fills are JS-dispatched by
@@ -285,6 +305,26 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
285
305
  right URL but an **empty title forever**; every `Runtime.evaluate` against it times out.
286
306
  `Page.captureScreenshot` returns `Internal error`. The target shell exists; the renderer does not.
287
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
+
288
328
  **The mechanism** (macOS, from Chrome's own log at `$TMPDIR/chrome-<port>.log` — `launch --restart`
289
329
  keeps the previous browser's log as `chrome-<port>.log.prev`, which is the one you want after a
290
330
  restart):
@@ -348,6 +388,41 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
348
388
  is a completely different client. Check the browser first: if `doctor` says renderer capacity is
349
389
  fine and a boring cross-origin URL loads, *then* start suspecting the site.
350
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`.
351
426
  - **Page still loading.** `goto` waits for the load event, but SPAs render after.
352
427
  If a `read`/`snapshot` looks empty, re-run after a moment, or snapshot again
353
428
  once a known element should be present.