@generativereality/browser-automation 0.4.13 → 0.4.15

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.
@@ -79,12 +79,40 @@ or a non-zero exit and the full renderer-wedge diagnosis. That matters because a
79
79
  held port, a `/json/version` that answers and a `list` full of targets are all
80
80
  properties of the browser **process**, and the way a long-lived Chrome dies is
81
81
  that it keeps all three while losing the ability to give any new tab a
82
- **renderer** (see Gotchas). Older CLIs printed `nothing to do.` in exactly that
82
+ **renderer** (see Gotchas, and [`references/renderer-health.md`](references/renderer-health.md)). Older CLIs printed `nothing to do.` in exactly that
83
83
  state — **if your `launch` ends without a `Renderer capacity:` line, you are on
84
84
  one of those; run `doctor`, which is the same probe.** Override the profile path
85
85
  with `BROWSER_AUTOMATION_PROFILE=...` and the CDP host with
86
86
  `BROWSER_AUTOMATION_CDP=http://localhost:PORT` if needed.
87
87
 
88
+ **The profile lives in `~/.browser-automation/chrome-profile`** (`browser-automation
89
+ profile` prints it). Older CLIs kept it inside Chrome's own folder,
90
+ `~/Library/Application Support/Google/Chrome/browser-automation`, and `launch` moves
91
+ it out the first time it can — logins included; the move is a single rename and
92
+ Chrome's cookie key lives in the Keychain, not in the path. To move it on demand:
93
+
94
+ ```bash
95
+ browser-automation profile --migrate # refuses, changing nothing, if a Chrome has it open
96
+ browser-automation launch --restart # quits Chrome first, then moves it and relaunches
97
+ ```
98
+
99
+ **Why it moved: macOS decides access to Chrome's folder per HOST app.** A session
100
+ started from a terminal that was once allowed reaches it; one started by an app
101
+ that was not — Clerk.AI, denied in 2026-08 and silently refused ever since — gets
102
+ `EPERM`, and Chrome dies with
103
+
104
+ ```
105
+ Failed to create …/browser-automation/SingletonLock: Operation not permitted (1)
106
+ Failed to create a ProcessSingleton for your profile directory. … Aborting now
107
+ ```
108
+
109
+ **That is not a stale lock**, and there is no lock file to delete. It is also why
110
+ the same command works from your terminal and fails from an app. ⛔ **Do not work
111
+ around it with a scratch `--user-data-dir` or `BROWSER_AUTOMATION_PROFILE` pointed
112
+ at an empty folder**: Chrome starts, and the person is signed out of every site in
113
+ the real profile. Run `browser-automation profile --migrate` once from a terminal
114
+ that can reach the old folder; every host reaches the new one.
115
+
88
116
  ## Commands
89
117
 
90
118
  Page commands take a tab selector — `-s <session>` (default `$BAC_SESSION`, else
@@ -94,6 +122,7 @@ Page commands take a tab selector — `-s <session>` (default `$BAC_SESSION`, el
94
122
  |---|---|
95
123
  | Start the Chrome + verify it can make renderers | `browser-automation launch` |
96
124
  | Diagnose setup (incl. renderer capacity) | `browser-automation doctor` |
125
+ | Where the Chrome profile lives / move it out of Chrome's folder | `browser-automation profile` / `profile --migrate` |
97
126
  | List sessions + every open tab (id, title, url) | `browser-automation list` |
98
127
  | Open a background tab | `browser-automation new -s work [url]` |
99
128
  | Navigate (session tab created if needed) | `browser-automation goto -s work https://example.com` |
@@ -180,67 +209,22 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
180
209
  no `name`** (Viking Line's booking selectors — the visible fields are display
181
210
  shells; the real state lives in the framework, so `fill` and DOM value-setting
182
211
  do nothing at all).
183
- **Do NOT hand-roll a raw-CDP trusted click.** Burned 2026-08-22: wrote a
184
- bespoke `Input.dispatchMouseEvent` helper for exactly this, and it clicked
185
- stale coordinates (the panel had animated in) — `--trusted` already solves that
186
- with the actionability wait. Check `browser-automation click --help` before
187
- building anything.
188
- **A form can swallow a dispatched click and submit itself the wrong way.**
189
- npmjs.com's package-settings forms are the case (2026-08-22): a default click
190
- on the submit button did not reach the framework's handler, so the browser fell
191
- through to a plain native POST and the tab was replaced by a raw
192
- `{"message":"Not Found"}` — no error from the CLI, and nothing saved. It looks
193
- like the server rejected your data; it did not. `--trusted` submitted the same
194
- form correctly. On any settings page, verify by reloading and re-reading the
195
- saved state rather than trusting a click that "worked".
196
- - **WebAuthn / security keys need a genuinely focused, visible tab, and you
197
- cannot supply the touch.** `navigator.credentials.get()` refuses outright when
198
- `document.hasFocus()` is false or `visibilityState` is `hidden` — which is the
199
- normal state while you work in the terminal, since `--trusted` only fronts the
200
- tab for the instant of the click. The prompt then never opens and the page just
201
- sits there, so a 2FA step can look like it is waiting for the user when the
202
- browser has already declined to ask. Measured 2026-08-22 on npm's
203
- `Use security key` challenge: the form POST returned **200** and the challenge
204
- was live, but it could only be satisfied once the user brought that Chrome
205
- window to the front themselves. Check with
206
- `eval '({f:document.hasFocus(),v:document.visibilityState})'` before concluding
207
- anything, and hand hardware-2FA steps to the user with the window frontmost.
208
- - **Controlled-form state stickiness.** Form libraries that subscribe to React's
209
- internal value-setter (React Hook Form, Final Form, Formik with a `Controller`,
210
- Blocket/finn.no's `recommerce` editor) sometimes ignore the synthetic `input`
211
- event the default `fill` dispatches: the DOM input shows the new value, but
212
- the form's React state stays on the old one — and the next submit serializes
213
- the *old* value. Two ways out:
214
- 1. **`fill --native --verify <ref> <value>`** — drives character insertion
215
- through CDP `Input.insertText` (trusted events). `--verify` re-reads the
216
- field afterwards and warns if either the DOM value diverged from what you
217
- asked for, or if React's internal `_valueTracker` still holds the old
218
- value (the canonical state-stickiness signature). Use this first; it
219
- solves the vast majority of cases.
220
- 2. **API bypass** — when even `--native` doesn't stick (e.g. the form library
221
- binds to an external state machine that drives its own POST/PUT), grab the
222
- form's underlying endpoint and hit it directly:
223
- ```bash
224
- # Hook fetch and persist a real form-submit's body + headers via localStorage
225
- # (it survives the post-submit navigation, unlike window.* globals):
226
- browser-automation eval -s app "(function(){var f=window.fetch;window.fetch=function(u,o){if(o&&o.method==='PUT'&&u.toString().includes('/api/item/')){localStorage.setItem('__lastPut',o.body||'');localStorage.setItem('__lastHdrs',JSON.stringify(o.headers||{}));}return f.apply(this,arguments);};})()"
227
- # …then click Save once in the form so the hook captures the canonical PUT…
228
- browser-automation eval -s app "({body:localStorage.getItem('__lastPut'),headers:localStorage.getItem('__lastHdrs')})"
229
- # …gives you the endpoint, exact body shape, and custom headers
230
- # (e.g. Blocket uses E-Tag, not the standard If-Match — and the etag lives
231
- # in the JSON body, not the HTTP header).
232
- ```
233
- Then re-fetch the GET endpoint for current data + the current etag, PUT
234
- directly with the modified field(s) and the captured custom header, and
235
- **drive the form's terminal commit step through the UI** — many two-step
236
- editors (`edit → delivery → publish`) only persist `state: "edit"`
237
- server-side until that final Save fires the commit.
238
-
239
- Blocket's recommerce price field is the canonical case: default `fill e43 "500"`
240
- shows 500 in the input but submits 750. Fix: `fill --native --verify e43 "500"`
241
- (or, if --native doesn't stick: direct PUT to
242
- `/recommerce/create/api/item/<id>` with `E-Tag: <body.etag>`, then click
243
- Save on the delivery page to commit).
212
+ - **There is NO way to send real keystrokes, and `fill --native` is not one** — it never fires
213
+ `keydown`, so a combobox that filters on keystrokes stays empty. ⛔ **Do not hand-roll a
214
+ raw-CDP trusted click** — `--trusted` already waits for actionability; check
215
+ `browser-automation click --help` before building anything. A form can also swallow a
216
+ dispatched click and fall through to a native POST (a raw `{"message":"Not Found"}` page,
217
+ nothing saved): use `--trusted`, and on any settings page verify by reloading and re-reading.
218
+ → The raw-CDP `Input.dispatchKeyEvent` recipe and its two traps are in
219
+ [`references/input-and-forms.md`](references/input-and-forms.md).
220
+ - **WebAuthn / security keys need a genuinely focused, visible tab, and you cannot supply the
221
+ touch.** The prompt silently never opens on a backgrounded tab. Check
222
+ `eval '({f:document.hasFocus(),v:document.visibilityState})'` and hand hardware-2FA steps to
223
+ the user with the window frontmost. Detail: [`references/input-and-forms.md`](references/input-and-forms.md).
224
+ - **Controlled-form state stickiness.** The input shows the new value but the submit sends the
225
+ old one (React Hook Form, Formik, Blocket's price field). Use **`fill --native --verify`**
226
+ first; if even that does not stick, bypass to the form's API — the fetch-hook recipe is in
227
+ [`references/input-and-forms.md`](references/input-and-forms.md).
244
228
  - **Cross-origin iframes are separate CDP targets.** `read`/`snapshot` see the
245
229
  page's own document and same-origin frames, not cross-origin iframes (common
246
230
  for SSO bank login widgets and embedded captchas). If the content you need
@@ -253,248 +237,31 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
253
237
  whose JS handler builds a client-side **blob** and clicks it via a *nested*
254
238
  synthetic click won't fire (Chrome activation quirk) — for those, grab the
255
239
  underlying export URL/endpoint and use `--url`, or the site's API.
256
- - **File upload.** Three paths. The first two mirror Playwright. For a static, snapshot-able
257
- `<input type=file>`, use `setfiles <ref> <path…>` — it resolves the ref and
258
- calls `DOM.setFileInputFiles` (a file input's `.files` is read-only to page JS,
259
- so a value-setter/`eval` can't populate it; CDP can, and fires trusted
260
- `input`/`change`). For a **custom "attach" button** that opens a native file
261
- chooser and reads a *transient* `<input type=file>` it creates+clicks on the fly
262
- (App Store Connect's "Attach File", many React dropzones), `setfiles` on the
263
- static input is useless — the handler uses its own throwaway input. Use
264
- `upload --click <ref> <path…>`: it arms `Page.setInterceptFileChooserDialog`,
265
- clicks the trigger, waits for `Page.fileChooserOpened`, and sets files on the
266
- `backendNodeId` Chrome reports. Paths are resolved from cwd; pass absolute paths
267
- to be safe. Multiple paths upload as a multi-file selection.
268
- **Verify by re-snapshot/screenshot, and DON'T blindly retry.** Apps reset the
269
- input to 0 right after consuming the file, so `upload` judges success by the
270
- `change` event (it reports "delivered"), not by residual `input.files` — a
271
- successful upload legitimately leaves `files=0`. The staged file often shows up
272
- as a row in an attachment *list* (e.g. ASC's "Message Attachments"), not a single
273
- chip, so confirm with `snapshot`/`screenshot` rather than assuming. Each
274
- successful run **adds another attachment** — retrying a "did it work?" upload a
275
- few times silently produces duplicates (this cost us a dozen copies on a live ASC
276
- reply). Upload once, verify, and only re-run if verification shows nothing staged.
277
- The **third path is drag-and-drop**, for zones with NO `<input type=file>` at
278
- all — a `drop` listener reading `e.dataTransfer.files` (vocalremover-style audio
279
- tools, many image/video drop zones). Neither `setfiles` nor `upload` applies;
280
- use `drop <ref> <path…>`. By default it fires a genuinely-**trusted** CDP drag
281
- (`Input.dispatchDragEvent`) carrying the real files from disk: it force-fronts
282
- the tab (bringToFront + focus emulation + active lifecycle — so the tab reports
283
- focused+visible even when the Chrome window isn't the frontmost OS window),
284
- waits for the zone to be actionable, then dragEnter→dragOver→drop. The
285
- force-front matters: drop-zone uploaders commonly do their work only inside a
286
- **user activation**, and CDP input grants no activation on a tab the renderer
287
- considers `hidden` — which it is whenever the window is occluded (the usual
288
- case while you work in the terminal). vocalremover.org is the canonical example:
289
- the file reaches its `change`/`drop` handler either way, but it only uploads +
290
- separates once activation is present. `--js` instead dispatches a synthetic
291
- (isTrusted=false) `DataTransfer` drop **without** force-fronting/stealing focus,
292
- for zones that accept synthetic events. The `<ref>` can be any snapshot element
293
- sitting over the drop region (a heading/button inside the zone) — the drop
294
- bubbles to the zone/document handler, so it works even when the drop div itself
295
- isn't snapshot-interactive. After the drop, `read`/`screenshot`/`network` to
296
- confirm processing started, then grab the result (often a download endpoint you
297
- can pull with `download --url`).
240
+ - **File upload — three paths:** `setfiles [ref] [path…]` for a static `<input type=file>`;
241
+ `upload --click [ref] [path…]` for a button that opens a native file chooser; `drop [ref]
242
+ [path…]` for a drag-and-drop zone with no file input (`--js` for a synthetic drop that does
243
+ not front the tab). ⛔ **Upload once, verify by `snapshot`/`screenshot`, and don't blindly
244
+ retry** — each successful run adds another attachment, and apps reset `files` to 0 after
245
+ consuming it. How each path works and when to pick it:
246
+ [`references/input-and-forms.md`](references/input-and-forms.md).
298
247
  - **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
-
334
- - **"The site is blocking us" — when it is really Chrome that cannot make renderers.**
335
- A browser process can permanently lose the ability to launch **renderer processes** while
336
- looking perfectly healthy. Every tab that already exists keeps working, so nothing seems wrong
337
- until you open a tab or navigate somewhere new, and then the errors read as the remote site's
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.
341
-
342
- How it shows up:
343
- - `browser-automation new` + `goto` → `CDP Page.enable timed out after 30000ms`, **even for
344
- `example.com`**.
345
- - **Cross-origin** navigation of an existing, working tab → `navigate failed: net::ERR_ABORTED`.
346
- Site isolation puts a new origin in a new renderer — the exact thing Chrome can no longer do.
347
- - **Same-origin** navigation on that same tab keeps working perfectly (Skyscanner → Skyscanner
348
- with new query params was fine throughout). That asymmetry is what makes it masquerade as
349
- "only site X blocks us": the tab you were already using still behaves.
350
- - A target created at the browser level (`PUT /json/new?<url>`) appears in `/json/list` with the
351
- right URL but an **empty title forever**; every `Runtime.evaluate` against it times out.
352
- `Page.captureScreenshot` returns `Internal error`. The target shell exists; the renderer does not.
353
-
354
- **It gets SLOW before it fails outright — that is the early warning.** Observed 2026-09-07 on a
355
- Chrome that had been up 12 days: every `goto` took ~25–30s, and a batch of three blew a 120s
356
- timeout, hours before anything failed hard. That was misread as "large files, slow browser" and
357
- worked around with longer timeouts for many minutes; the actual fix was one `launch --restart`,
358
- after which the same pages loaded instantly and 14 `file://` tabs opened in two quick batches.
359
- **A `goto` that has quietly become slow is this, not your page.** Raise the timeout at most once,
360
- then run `doctor`.
361
-
362
- **Every cheap signal stays green, so do not take any of them as health.** On that same wedged
363
- browser: `launch` said `Already running on :9223 — nothing to do.`, `curl :9223/json/version`
364
- answered normally, and `list` cheerfully returned 10 targets — while `goto` exited 1 and `eval`
365
- died with `CDP Runtime.evaluate timed out after 30000ms`. Port held, HTTP endpoint answering and
366
- targets listed are all properties of the **browser** process; the thing that is broken is its
367
- ability to start a **renderer**, and only a probe that runs code in one can see it.
368
- **Since fixed:** `launch` now runs that probe itself and exits non-zero with the diagnosis
369
- instead of reporting "nothing to do", so this particular green-across-the-board trap is closed.
370
- It still will not restart for you — that stays something you type, because the tabs are not
371
- only yours. On a CLI old enough to lack it, `doctor` is the same probe; nothing cheaper
372
- substitutes for either.
373
-
374
- **The mechanism** (macOS, from Chrome's own log at `$TMPDIR/chrome-<port>.log` — `launch --restart`
375
- keeps the previous browser's log as `chrome-<port>.log.prev`, which is the one you want after a
376
- restart):
377
- ```
378
- ERROR:base/apple/mach_port_rendezvous_mac.cc:256]
379
- bootstrap_look_up com.google.Chrome.MachPortRendezvousServer.<pid>: (ipc/send) invalid destination port
380
- ERROR:base/memory/shared_memory_switch.cc:261]
381
- No rendezvous client, terminating process (parent died?)
382
- ```
383
- A Chrome child process gets its shared-memory handles by looking up a Mach bootstrap service the
384
- browser registers **once, at startup**, named `com.google.Chrome.MachPortRendezvousServer.<browser-pid>`.
385
- That registration had vanished from the user's launchd namespace — confirmed absent via
386
- `launchctl print gui/$UID | grep MachPortRendezvousServer.<pid>`, while two healthy Chromes on the
387
- same machine were both listed. From then on **every renderer Chrome launches kills itself within
388
- milliseconds**, which is why none ever appears in `ps` and why the browser only reports
389
- `Render process gone.` **What made the name vanish is not established.** Two things
390
- correlated and neither is proven: the binary on disk had moved to 151.0.7922.170 while the live
391
- browser was still running .138, and `GoogleUpdater` was FATAL-ing on its own `bootstrap_check_in`
392
- with error 141. But the first renderer failure (18:53) *preceded* the first updater FATAL (19:42)
393
- by ~50 minutes, so the update churn is at best a fellow symptom of a sick launchd bootstrap
394
- namespace, not the cause. Treat the trigger as unknown; the diagnosis and the recovery do not
395
- depend on it.
396
-
397
- **It is NOT about how many tabs are open.** That was the first theory and it is wrong: a freshly
398
- launched Chrome on the same machine was driven to **421 page targets / 435 live renderer
399
- processes, every one responsive**, and a 256-fd `ulimit` made no difference either (205 renderers,
400
- all fine). The broken browser had 66 tabs. The count was a coincidence — so do not treat a big
401
- tab count as evidence of this, and do not expect closing tabs to fix it.
402
-
403
- **Diagnose it:**
404
- ```bash
405
- browser-automation doctor # measures renderer capacity, not just reachability
406
- ```
407
- `doctor` now creates a throwaway tab, makes its renderer evaluate `1+1`, and closes it — the one
408
- round-trip that separates a wedged browser from a slow network or a hostile site. On failure it
409
- names the root cause (including the missing bootstrap service and the pid) and points at Chrome's
410
- log. On a healthy browser it reports e.g. `✓ Renderer capacity: a new tab got a live renderer in
411
- 73ms`. `goto` and `new` run the same probe automatically **on the error path only**, so a bare
412
- `Page.enable timed out` now arrives with the diagnosis attached instead of sending you to the
413
- site's bot-protection docs.
414
-
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.**
436
-
437
- **Housekeeping is a different problem** — `browser-automation gc` prunes stale session bookmarks
438
- (they are never cleaned up otherwise; this machine had accumulated 234, only 5 of them live) and
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
443
- **not** a fix for the wedge above, and it never closes a working tab unless you pass `--orphans`
444
- — tabs get addressed by `-m` and opened by hand, so "no session claims it" is not evidence that
445
- nobody wants it.
446
-
447
- **The false lead to resist:** a bare `curl` to a suspicious site may genuinely return a bot wall
448
- (vikingline.fi serves an Imperva "Pardon Our Interruption" page, HTTP 200), which feels like
449
- confirmation. It confirms nothing about the browser path — the persistent, cookie-bearing profile
450
- is a completely different client. Check the browser first: if `doctor` says renderer capacity is
451
- fine and a boring cross-origin URL loads, *then* start suspecting the site.
452
-
453
- - **A backgrounded tab may never paint at all — and `read`/`snapshot` will not tell you.** Distinct
454
- from "still loading": `document.readyState` reaches `complete`, but the SPA never renders, so
455
- `read` returns a stale shell (e.g. a bare "Loading") and `snapshot` lists none of the real
456
- controls. The trap is that this looks exactly like *the page does not have that element*, and you
457
- will go hunting for a different selector or conclude the flow changed. Measured 2026-09-02 on
458
- Google's `accounts.google.com/v3/signin/challenge/pwd`: `readyState: "complete"`,
459
- `body.innerText.length: 202` frozen on the previous step's text, and the password field present in
460
- the DOM but `offsetParent === null` for as long as the tab stayed backgrounded.
461
- **Diagnose** before changing your selector:
462
- ```bash
463
- browser-automation eval -s x '({ready:document.readyState,vis:document.visibilityState,len:document.body.innerText.length})'
464
- ```
465
- `visibilityState: "hidden"` with a **stuck `len`** is this, not a selector problem. Note the
466
- stuck `len` is the whole tell: `hidden` on its own is the normal, healthy state of every
467
- backgrounded tab — verified 2026-09-07, a background tab reporting `hidden` returned its real
468
- painted text — so never read `hidden` alone as a diagnosis.
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.)*
483
-
484
- **Do not confuse this with the renderer wedge above.** Both present to an operator as "the page
485
- isn't there, but every tool says fine", and the fixes are opposite — one is a per-tab nudge, the
486
- other closes every tab in the browser. What separates them:
487
-
488
- | | backgrounded tab never paints | Chrome cannot make renderers |
489
- |---|---|---|
490
- | `goto` | succeeds, rc=0 (may be slow) | **rc=1**, or `Page.enable timed out` |
491
- | `eval` | works, returns a result | **`Runtime.evaluate` times out at 30000ms** |
492
- | scope | that one tab | **every** new tab / cross-origin nav |
493
- | `doctor` | `✓ Renderer capacity` | names the wedge + pid |
494
- | fix | `focus` on the tab | `launch --restart` (**ask first**) |
495
-
496
- `eval` is the fast discriminator: if it answers at all, the renderer is alive and you are in the
497
- painting case. If it times out, stop poking the page and run `doctor`.
248
+ ⛔ `launch --restart` closes **every tab of every session** sharing this Chrome (it has
249
+ destroyed other sessions' unrecoverable work). Retry, or drive a tab that already works.
250
+ Restart **only** once `doctor` reports the Mach rendezvous service **absent**, and **ask Fred
251
+ first — never restart unilaterally**.
252
+ - **"The site is blocking us" may really be Chrome unable to make renderers** — `Page.enable
253
+ timed out` even for `example.com`, cross-origin `net::ERR_ABORTED`, a `goto` that quietly
254
+ became slow, while `launch`, `/json/version` and `list` all look healthy. Run `doctor`
255
+ before blaming the site.
256
+ - **A backgrounded tab may never paint, and `read`/`snapshot` will not tell you** — it looks
257
+ like the page lacks the element. Diagnose before changing selectors:
258
+ `eval '({ready:document.readyState,vis:document.visibilityState,len:document.body.innerText.length})'`.
259
+ `hidden` with a stuck `len` ⇒ run `focus` on the tab (`hidden` alone is normal). If `eval`
260
+ itself times out, it is the renderer wedge instead: run `doctor`.
261
+ - → **Read [`references/renderer-health.md`](references/renderer-health.md)** whenever
262
+ `new`/`goto`/`eval` time out or turn slow, a site seems to block you, a page reads as a
263
+ frozen shell, or a restart is on the table. It has the measurements, the two corroborating
264
+ checks, the wedge mechanism, the recovery order, and the never-paints-vs-wedge table.
498
265
  - **Page still loading.** `goto` waits for the load event, but SPAs render after.
499
266
  If a `read`/`snapshot` looks empty, re-run after a moment, or snapshot again
500
267
  once a known element should be present.
@@ -529,37 +296,13 @@ case; drop to raw CDP only for cross-origin-iframe reads or one-off probes.
529
296
 
530
297
  ## Hit a shortcoming or bug? Fix it — it's open source
531
298
 
532
- This CLI is `@generativereality/browser-automation` (repo:
533
- `github.com/generativereality/browser-automation`). When you hit a missing
534
- capability or a bug (a site needs something the CLI can't do yet, an export
535
- won't trigger, a selector strategy fails), **fix it at the source rather than
536
- working around it forever**:
537
-
538
- 1. **Clone** next to your work: `gh repo clone generativereality/browser-automation`
539
- (or `git clone https://github.com/generativereality/browser-automation`).
540
- 2. **Fix** in `src/` — TypeScript. Commands live in `src/commands/<name>.ts`,
541
- the daemonless CDP core in `src/core/` (`cdp.ts` connection/eval/navigate,
542
- `dom.ts` injected snapshot/click/read JS, `download.ts`, `resolve.ts` tab
543
- selection). Add a command by creating `src/commands/x.ts` and registering it
544
- in `src/commands/index.ts`.
545
- 3. **Validate locally** against the running Chrome:
546
- `npm install && npm run typecheck && npm run build`, then run your build as
547
- **`node dist/index.js <cmd>`** from the clone. **Do NOT `npm link`** — it
548
- repoints the machine-global `browser-automation` bin, so a parallel Claude
549
- Code session (or the user's main session) would suddenly be running *your*
550
- work-in-progress clone instead of the installed release. Validate via the
551
- explicit `node dist/index.js` path instead. Reproduce the failure, confirm
552
- the fix, and re-test on a scratch tab you created (read-only-safe; never
553
- disrupt the user's live tabs).
554
- 4. **Propose a PR** for the user to review and contribute upstream — don't
555
- publish yourself (the maintainer cuts releases):
556
- ```bash
557
- git checkout -b fix/<short-desc>
558
- git commit -am "fix: <what and why>"
559
- gh pr create --fill --repo generativereality/browser-automation
560
- ```
561
- Then tell the user the branch/PR link and what it changes, and ask them to
562
- review and merge. After it's released, `npm install -g @generativereality/browser-automation@latest`.
299
+ This CLI is `@generativereality/browser-automation`
300
+ (`github.com/generativereality/browser-automation`). When a site needs something the CLI
301
+ can't do, or it misbehaves, **fix it at the source rather than working around it forever**.
302
+ ⛔ **Never `npm link`** a clone (it hijacks the machine-global bin for every parallel
303
+ session), and never publish yourself — propose a PR for the user. How to clone, where the
304
+ code lives, how to validate with `node dist/index.js`, and the PR steps:
305
+ [`references/contributing.md`](references/contributing.md).
563
306
 
564
307
  ## Troubleshooting
565
308
 
@@ -567,6 +310,26 @@ working around it forever**:
567
310
  If it says the port is held by ANOTHER user, that is not your Chrome and
568
311
  driving it would act in their session — quit Chrome in that account, or set
569
312
  `BROWSER_AUTOMATION_PORT`.
313
+ - **`SingletonLock: Operation not permitted` / "Failed to create a ProcessSingleton"**
314
+ → macOS refused the app this session runs under access to **Chrome's** folder,
315
+ where old CLIs kept the profile (see Setup). Not a stale lock; do not delete
316
+ anything. Upgrade the CLI (`npm install -g @generativereality/browser-automation@latest`)
317
+ and `launch` again: current versions start Chrome through `open(1)`, under
318
+ Chrome's own identity, so it opens its folder whatever app you run under, and
319
+ they move the profile to `~/.browser-automation/` when they can.
320
+
321
+ **What to tell the person — and what NOT to.** ⛔ **Do not ask them to grant
322
+ Full Disk Access** (to the app, to the terminal, to anything). It does work, and
323
+ it hands that app every file on the Mac to fix a problem that needs none of it:
324
+ an agent in Mind My Money said exactly that on 2026-09 — *"let Mind My Money
325
+ reach that folder. Full Disk Access does it, but it also opens far more than
326
+ Chrome"* — when the real fix was a CLI upgrade. Also do not suggest a fresh
327
+ profile or `BROWSER_AUTOMATION_PROFILE` pointed at an empty folder: that signs
328
+ them out of every bank and portal. If `launch` still reports `Profile not moved`
329
+ after upgrading, the browser works anyway (the old folder is still used); the
330
+ one-time move needs a host macOS allows into Chrome's folder, so the ask is small
331
+ and exact: *open Terminal and run `browser-automation profile --migrate`; if macOS
332
+ asks whether Terminal may access data from other apps, allow it.*
570
333
  - **`command not found: browser-automation`** → `npm install -g @generativereality/browser-automation`.
571
334
  - **Chrome was restarted** → nothing to do; the next `goto` recreates the
572
335
  session's tab automatically (sessions self-heal; `list` shows `stale`).
@@ -0,0 +1,36 @@
1
+ # Hit a shortcoming or bug? Fix it — it's open source
2
+
3
+ Reference for the `browser` skill. Read it when the CLI cannot do something a site needs,
4
+ or misbehaves, and you are about to work around it.
5
+
6
+ This CLI is `@generativereality/browser-automation` (repo:
7
+ `github.com/generativereality/browser-automation`). When you hit a missing
8
+ capability or a bug (a site needs something the CLI can't do yet, an export
9
+ won't trigger, a selector strategy fails), **fix it at the source rather than
10
+ working around it forever**:
11
+
12
+ 1. **Clone** next to your work: `gh repo clone generativereality/browser-automation`
13
+ (or `git clone https://github.com/generativereality/browser-automation`).
14
+ 2. **Fix** in `src/` — TypeScript. Commands live in `src/commands/<name>.ts`,
15
+ the daemonless CDP core in `src/core/` (`cdp.ts` connection/eval/navigate,
16
+ `dom.ts` injected snapshot/click/read JS, `download.ts`, `resolve.ts` tab
17
+ selection). Add a command by creating `src/commands/x.ts` and registering it
18
+ in `src/commands/index.ts`.
19
+ 3. **Validate locally** against the running Chrome:
20
+ `npm install && npm run typecheck && npm run build`, then run your build as
21
+ **`node dist/index.js <cmd>`** from the clone. **Do NOT `npm link`** — it
22
+ repoints the machine-global `browser-automation` bin, so a parallel Claude
23
+ Code session (or the user's main session) would suddenly be running *your*
24
+ work-in-progress clone instead of the installed release. Validate via the
25
+ explicit `node dist/index.js` path instead. Reproduce the failure, confirm
26
+ the fix, and re-test on a scratch tab you created (read-only-safe; never
27
+ disrupt the user's live tabs).
28
+ 4. **Propose a PR** for the user to review and contribute upstream — don't
29
+ publish yourself (the maintainer cuts releases):
30
+ ```bash
31
+ git checkout -b fix/<short-desc>
32
+ git commit -am "fix: <what and why>"
33
+ gh pr create --fill --repo generativereality/browser-automation
34
+ ```
35
+ Then tell the user the branch/PR link and what it changes, and ask them to
36
+ review and merge. After it's released, `npm install -g @generativereality/browser-automation@latest`.