@generativereality/browser-automation 0.6.0 → 0.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@generativereality/browser-automation",
3
- "version": "0.6.0",
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.",
3
+ "version": "0.7.1",
4
+ "description": "Let many Claude Code sessions use your own signed-in Chrome at once, each in its own tab, without stealing your screen. Daemonless CLI over per-target CDP: persistent profile and extensions, no MCP server, nothing long-lived to crash.",
5
5
  "type": "module",
6
6
  "bin": {
7
7
  "browser-automation": "dist/index.js"
@@ -28,7 +28,11 @@
28
28
  "cdp",
29
29
  "chrome-devtools-protocol",
30
30
  "playwright-alternative",
31
- "ai-agents"
31
+ "ai-agents",
32
+ "chrome",
33
+ "claude-code-plugin",
34
+ "parallel-agents",
35
+ "cli"
32
36
  ],
33
37
  "author": "motin",
34
38
  "license": "MIT",
@@ -0,0 +1,40 @@
1
+ # Testing the pipe broker on the Windows 11 ARM64 guest
2
+
3
+ What validated 0.7.0 on Windows (2026-10-27, Chrome 156, Node 22): the user's own Chrome
4
+ and a login context each on a randomly named pipe, no Chrome TCP listener, `launch`
5
+ refusing a Chrome still on the old port and `launch --restart` switching it over, and
6
+ the named pipe's ACL. The guest is the qemu VM in `~/VMs/win11` on mbp21; booting it,
7
+ console login and the shared-VM rules (snapshot before, revert after) are in the
8
+ `windows-dev` skill and in cctabs' `scripts/windows-guest/README.md`.
9
+
10
+ ## ⛔ Do not point USERPROFILE at a test folder
11
+
12
+ With `USERPROFILE` changed, Chrome cannot find its app-data folder, takes the
13
+ `--user-data-dir` for its DEFAULT profile, and refuses DevTools on it ("DevTools remote
14
+ debugging requires a non-default data directory") — on the pipe AND on a port. `launch`
15
+ then times out, and a port Chrome never listens, so it cannot be quit cleanly. That cost
16
+ one full run. Isolate with `BROWSER_AUTOMATION_HOME` and `BROWSER_AUTOMATION_PROFILE`
17
+ instead (contexts still land in the real `~\.browser-automation\contexts`, which the
18
+ snapshot revert removes). `rawpipe.mjs` is the minimal check: real USERPROFILE answers,
19
+ an overridden one does not.
20
+
21
+ ## Run
22
+
23
+ 1. Stage the branch build on the Mac (no plain `npm pack`: `prepack` builds, which is fine
24
+ here, but the tarball's version is whatever package.json says):
25
+
26
+ ```sh
27
+ W=<scratch>; npm run build && npm pack --ignore-scripts --pack-destination $W/stage
28
+ (cd $W/stage && echo '{"private":true}' > package.json && npm i --omit=dev --ignore-scripts ./generativereality-browser-automation-*.tgz)
29
+ tar czf $W/ba-stage.tgz -C $W/stage node_modules package.json
30
+ ```
31
+ 2. Copy `ba-stage.tgz` and these scripts to `C:\Users\dev\ba-test\`, unpack into `stage\`.
32
+ The guest's SSH shell is **PowerShell 5.1: no `&&`**, use `;`.
33
+ 3. A console session must be logged in (`query user` shows `console … Active`): Chrome is
34
+ started in the desktop session by `run-in-session.ps1` (a one-off scheduled task).
35
+ 4. `powershell -ExecutionPolicy Bypass -File run-in-session.ps1`, then wait for `DONE` in
36
+ `result.log`.
37
+ 5. `cleanup.ps1` stops every process whose command line mentions `ba-test` and nothing else.
38
+
39
+ `Get-Acl` cannot read a named pipe's ACL (error 87); `test.ps1` reads it off a
40
+ `NamedPipeClientStream` connection instead.
@@ -0,0 +1,5 @@
1
+ # Stop only what the ba-test run started: processes whose command line mentions ba-test.
2
+ $mine = Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -and $_.CommandLine -match 'ba-test' -and $_.ProcessId -ne $PID -and $_.CommandLine -notmatch 'cleanup\.ps1' }
3
+ foreach ($p in $mine) { "stop $($p.ProcessId) $($p.Name)"; Stop-Process -Id $p.ProcessId -Force -ErrorAction SilentlyContinue }
4
+ Start-Sleep 2
5
+ "left: " + @(Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -match 'ba-test' -and $_.CommandLine -notmatch 'cleanup\.ps1' }).Count
@@ -0,0 +1,16 @@
1
+ // Minimal: does Chrome on Windows answer on --remote-debugging-pipe (fds 3/4)?
2
+ // node rawpipe.mjs <dir-for-a-temp-profile>. Run it once as is, and once with USERPROFILE
3
+ // pointed elsewhere to see Chrome refuse DevTools (see README).
4
+ import { spawn } from 'node:child_process'
5
+ import { mkdtempSync } from 'node:fs'
6
+ import { join } from 'node:path'
7
+ import { tmpdir } from 'node:os'
8
+ const chrome = process.env.LOCALAPPDATA + '\\Google\\Chrome\\Application\\chrome.exe'
9
+ const dir = mkdtempSync(join(process.argv[2] || tmpdir(), 'rawpipe-'))
10
+ const c = spawn(chrome, ['--remote-debugging-pipe', `--user-data-dir=${dir}`, '--headless=new', '--no-first-run', 'about:blank'], { stdio: ['ignore', 'pipe', 'pipe', 'pipe', 'pipe'] })
11
+ let err = ''
12
+ c.stderr.on('data', (d) => { err += d })
13
+ c.stdout.on('data', () => {})
14
+ c.stdio[4].on('data', (d) => { console.log('REPLY', String(d).replace(/\0/g, '').slice(0, 160)); c.kill(); process.exit(0) })
15
+ setTimeout(() => c.stdio[3].write(JSON.stringify({ id: 1, method: 'Browser.getVersion' }) + '\0'), 3000)
16
+ setTimeout(() => { console.log('NO REPLY in 15s; stderr:', err.split('\n').slice(0, 5).join(' | ')); c.kill(); process.exit(1) }, 15000)
@@ -0,0 +1,8 @@
1
+ # Run test.ps1 in the logged-in desktop session (a GUI started over SSH is invisible).
2
+ $ProgressPreference = 'SilentlyContinue'
3
+ $name = 'ba-pipe-test'
4
+ $a = New-ScheduledTaskAction -Execute 'powershell.exe' -Argument '-NoProfile -ExecutionPolicy Bypass -WindowStyle Hidden -File C:\Users\dev\ba-test\test.ps1'
5
+ $p = New-ScheduledTaskPrincipal -UserId 'dev' -LogonType Interactive
6
+ Register-ScheduledTask -TaskName $name -Action $a -Principal $p -Force | Out-Null
7
+ try { Start-ScheduledTask -TaskName $name } finally { Start-Sleep 2; Unregister-ScheduledTask -TaskName $name -Confirm:$false }
8
+ 'started'
@@ -0,0 +1,59 @@
1
+ # browser-automation pipe broker on Windows, run in the desktop session (scheduled task).
2
+ # The user's own Chrome lives under C:\Users\dev\ba-test (BROWSER_AUTOMATION_HOME, _PROFILE,
3
+ # a port of its own). USERPROFILE stays real: pointed elsewhere, Chrome refuses DevTools.
4
+ $ErrorActionPreference = 'Continue'
5
+ $T = 'C:\Users\dev\ba-test'
6
+ $log = "$T\result.log"
7
+ $env:BROWSER_AUTOMATION_HOME = "$T\home\.browser-automation"; $env:BROWSER_AUTOMATION_PROFILE = "$T\profile"
8
+ $env:BROWSER_AUTOMATION_PORT = '40123'; $env:NO_UPDATE_NOTIFIER = '1'; $env:NO_COLOR = '1'
9
+ Remove-Item Env:BROWSER_AUTOMATION_CDP -ErrorAction SilentlyContinue
10
+ Remove-Item Env:BAC_CONTEXT -ErrorAction SilentlyContinue
11
+ New-Item -ItemType Directory -Force "$T\home" | Out-Null
12
+ $node = 'C:\Users\dev\node\node.exe'
13
+ $ba = "$T\stage\node_modules\@generativereality\browser-automation\dist\index.js"
14
+ function BA { param([Parameter(ValueFromRemainingArguments = $true)]$a) "`n>>> ba $($a -join ' ')"; & $node $ba @a 2>&1 | ForEach-Object { "$_" }; "<<< exit $LASTEXITCODE" }
15
+ function ChromeListens {
16
+ $ids = @((Get-Process chrome -ErrorAction SilentlyContinue).Id)
17
+ $l = Get-NetTCPConnection -State Listen -ErrorAction SilentlyContinue | Where-Object { $ids -contains $_.OwningProcess }
18
+ "chrome processes: $($ids.Count); chrome TCP listeners: [" + (($l | ForEach-Object { "$($_.LocalAddress):$($_.LocalPort)" }) -join ', ') + "]"
19
+ }
20
+ function PipeAcl($stateFile) {
21
+ $s = (Get-Content $stateFile | ConvertFrom-Json).socket; "pipe: $s"
22
+ try {
23
+ $c = New-Object System.IO.Pipes.NamedPipeClientStream('.', $s.Substring('\\.\pipe\'.Length), [System.IO.Pipes.PipeDirection]::InOut)
24
+ $c.Connect(3000)
25
+ $c.GetAccessControl().Access | ForEach-Object { " $($_.IdentityReference) $($_.AccessControlType) $($_.PipeAccessRights)" }
26
+ $c.Dispose()
27
+ } catch { " acl: $_" }
28
+ }
29
+ & {
30
+ "=== 1. an old Chrome on the port, same profile"
31
+ $chrome = "$env:LOCALAPPDATA\Google\Chrome\Application\chrome.exe"
32
+ New-Item -ItemType Directory -Force "$T\profile" | Out-Null
33
+ Start-Process $chrome -ArgumentList "--remote-debugging-port=40123", "--user-data-dir=$T\profile", "--no-first-run", "--no-default-browser-check", "about:blank" | Out-Null
34
+ Start-Sleep 8
35
+ ChromeListens
36
+ BA launch
37
+ BA launch --restart
38
+ ChromeListens
39
+ "=== 2. own Chrome on the pipe"
40
+ Get-Content "$T\home\.browser-automation\broker.json"
41
+ BA launch --status
42
+ BA new -s t1 "data:text/html,<h1>pipe-ok</h1>"
43
+ BA eval -s t1 "document.querySelector('h1').textContent"
44
+ BA doctor
45
+ "=== 3. a login context"
46
+ BA new -s c1 --context bapipe "data:text/html,<h1>context-ok</h1>"
47
+ BA eval -s c1 "document.querySelector('h1').textContent"
48
+ Get-Content "C:\Users\dev\.browser-automation\contexts\bapipe\broker.json"
49
+ BA context
50
+ ChromeListens
51
+ "=== 4. pipe ACLs"
52
+ PipeAcl "$T\home\.browser-automation\broker.json"
53
+ PipeAcl "C:\Users\dev\.browser-automation\contexts\bapipe\broker.json"
54
+ "=== 5. stop the context"
55
+ BA context stop bapipe
56
+ Start-Sleep 6
57
+ BA context
58
+ "DONE"
59
+ } *>> $log
@@ -14,14 +14,19 @@ file under `~/.browser-automation/sessions/`.
14
14
 
15
15
  ## The model — read this first
16
16
 
17
- - **One shared headed Chrome per USER** on a uid-derived
18
- `--remote-debugging-port` (`9223` for the first account on the machine) with a
19
- persistent profile (`browser-automation`). Cookies, logins, and **browser
20
- extensions (password managers, etc.) all persist** across runs and across
21
- Claude Code restarts. The user can watch and complete interactive auth in the
22
- same window.
23
- - **Per-target CDP, not whole-browser.** The CLI talks to a single tab's
24
- `webSocketDebuggerUrl`. It never does Playwright-style "connect to the whole
17
+ - **One shared headed Chrome per USER** with a persistent profile. Cookies,
18
+ logins, and **browser extensions (password managers, etc.) all persist** across
19
+ runs and across Claude Code restarts. The user can watch and complete
20
+ interactive auth in the same window.
21
+ - **No debugging port.** Chrome runs with `--remote-debugging-pipe`, held by a
22
+ small broker that `launch` starts, and the CLI reaches it through
23
+ `~/.browser-automation/cdp.sock` (macOS, Linux) or a randomly named pipe
24
+ (Windows) — only this OS user can open either. A debugging port has no
25
+ authentication, so with one open any program on the computer could drive the
26
+ signed-in browser. Login contexts get a broker each. Only `BROWSER_AUTOMATION_CDP` means a port.
27
+ - **Per-target CDP, not whole-browser.** Each command opens its own connection
28
+ bound to a single tab (over the socket, a CDP session the broker attaches for
29
+ that command and detaches after it). It never does Playwright-style "connect to the whole
25
30
  browser and enumerate every target" — so a stuck iframe/worker or a pile of
26
31
  open tabs can never wedge it (the failure that made `playwright-cli` time out).
27
32
  - **Address any tab on demand.** Every page command picks its tab three ways
@@ -84,11 +89,10 @@ file under `~/.browser-automation/sessions/`.
84
89
  attribute. Because each invocation is a fresh process, **re-snapshot after any
85
90
  action that changes the DOM** — refs from an old snapshot go stale, exactly
86
91
  like Playwright refs.
87
- - **Clicks/fills are JS-dispatched** (`element.click()`, native value setter +
88
- `input`/`change` events). This works on background tabs, which native CDP
89
- mouse events do not reliably reach in headed Chrome. Trade-off: dispatched
90
- events are not `isTrusted`, so a few hard anti-bot / payment flows may reject
91
- them (see Gotchas).
92
+ - **Clicks/fills are JS-dispatched** (a real click's pointer + mouse events, then
93
+ `element.click()`; native value setter + `input`/`change`). This works on
94
+ background tabs without taking focus, and drives Radix / headless-UI controls.
95
+ Trade-off: not `isTrusted`, so a few anti-bot / payment flows reject them (see Gotchas).
92
96
 
93
97
  ## Setup (per machine)
94
98
 
@@ -113,8 +117,15 @@ that it keeps all three while losing the ability to give any new tab a
113
117
  **renderer** (see Gotchas, and [`references/renderer-health.md`](references/renderer-health.md)). Older CLIs printed `nothing to do.` in exactly that
114
118
  state — **if your `launch` ends without a `Renderer capacity:` line, you are on
115
119
  one of those; run `doctor`, which is the same probe.** Override the profile path
116
- with `BROWSER_AUTOMATION_PROFILE=...` and the CDP host with
117
- `BROWSER_AUTOMATION_CDP=http://localhost:PORT` if needed.
120
+ with `BROWSER_AUTOMATION_PROFILE=...`. `BROWSER_AUTOMATION_CDP=http://localhost:PORT`
121
+ drives a browser somebody else started on a port instead — which exposes it to
122
+ everything on the computer, so only for a browser that holds no logins.
123
+
124
+ **Moving off the port.** If this user's browser from an older CLI is still on the
125
+ port, `launch` stops and says so: `browser-automation launch --restart` quits it
126
+ (closing its tabs; logins are kept, and the profile moves out of Chrome's folder
127
+ as below) and starts it on the pipe. A browser on the port with a *different*
128
+ profile is left alone and only named.
118
129
 
119
130
  **The profile lives in `~/.browser-automation/chrome-profile`** (`browser-automation
120
131
  profile` prints it). Older CLIs kept it inside Chrome's own folder,
@@ -163,6 +174,7 @@ Page commands take a tab selector — `-s <session>` (default `$BAC_SESSION`, el
163
174
  | Adopt an open tab into a session | `browser-automation bind -s bank -m nordnet` |
164
175
  | List interactive elements (refs) | `browser-automation snapshot -m op.fi` |
165
176
  | Click by ref | `browser-automation click -m op.fi e7` |
177
+ | Press a key on a ref (listbox, menu, cmdk list) | `browser-automation key -s app e7 Enter` |
166
178
  | Type into a field by ref | `browser-automation fill -s work e3 "value" [--submit]` |
167
179
  | Read page text (or a selector) | `browser-automation read -m op.fi ['.balance']` |
168
180
  | Evaluate JS in the tab (escape hatch) | `browser-automation eval -m op.fi 'document.title'` |
@@ -217,36 +229,56 @@ browser-automation read -s cf # later runs: already authenticate
217
229
 
218
230
  There's no `state-save`/`state-load` to manage — the profile *is* the auth store.
219
231
 
220
- ### A second account next to the first — `--context <name>`
232
+ ### A second account, or a project of its own — `--context <name>`
221
233
 
222
234
  The profile holds ONE login per site. For a second account beside it (two
223
- Cloudflare dashboards, a client's Google account next to the user's), open the
224
- session in a named **login context**: a separate Chrome with its own profile,
225
- port and window, started on demand. The user's own Chrome is not touched.
235
+ Cloudflare dashboards), or to keep a whole project's logins apart from the
236
+ user's (a client's Google Workspace, AWS), open the session in a named **login
237
+ context**: a separate Chrome with its own profile, pipe and window, started on
238
+ demand. The user's own Chrome is not touched.
226
239
 
227
240
  ```bash
228
241
  browser-automation new -s cf2 --context cloudflare-2 https://dash.cloudflare.com
229
- # FIRST time only: in the new window (a copy of the automation profile), the user
230
- # signs out of the first account and signs in to the other one
242
+ # FIRST time only: the user signs in to the account in the new (coloured) window
231
243
  browser-automation read -s cf2 # follows the session's context — no flag
232
244
  ```
233
245
 
246
+ - **A project uses one context for all its sessions: set `BAC_CONTEXT`** in the
247
+ env of the project's Claude settings — e.g. `"env": {"BAC_CONTEXT": "gapminder"}`
248
+ in `.claude/settings.json`, or in a separate account's `$CLAUDE_CONFIG_DIR/settings.json`.
249
+ Then every NEW session, `-m`/`-t`, `list` and `doctor` use that Chrome with no
250
+ flag, and nothing of the project lands in the user's main profile. ⛔ If a
251
+ project should be separate and `BAC_CONTEXT` is not set, ask before working in
252
+ the main profile — a logout or sign-in there is the user's real account.
253
+
234
254
  - **A session remembers its context**: later commands on `-s cf2` go to that
235
255
  Chrome without `--context`. A session can't change context; use another `-s`.
236
256
  - **It is a real profile** (`~/.browser-automation/contexts/<name>/chrome-profile`):
237
257
  logins and extensions persist across restarts, like the main profile.
238
- - **It starts as a copy of the automation profile** (caches left out, ~0.9 GB,
239
- a few seconds): the same extensions work at once — a password manager, for
240
- passkeys — and it is signed in to the same accounts. So in the new window,
241
- **sign out of the account this context is NOT for** (e.g. the first Cloudflare
242
- account), then sign in to the other. `--empty-profile` (only when the context
243
- is first made) starts it with nothing instead. The user's ordinary Chrome
244
- profile is never copied.
258
+ - **How a new context starts** — chosen once, when it is first made:
259
+
260
+ | | extensions (password manager…) | site logins, cookies | Chrome's own Google sign-in |
261
+ |---|---|---|---|
262
+ | default | ✅ copied, still signed in | ❌ none | ❌ signed out |
263
+ | `--full-copy` | ✅ | ✅ every one, personal too | ✅ — may become the DEFAULT Google account |
264
+ | `--empty-profile` | ❌ | ❌ | ❌ |
265
+
266
+ The source is the AUTOMATION profile, never the user's ordinary Chrome. With
267
+ `--full-copy`, Google pages pick the copied personal account and `?authuser=`
268
+ does not move them: open
269
+ `https://accounts.google.com/AccountChooser?Email=<work address>&continue=<url>`.
270
+ - **Each context's window has its own colour**, and its profile is named after
271
+ it, so the user can tell the Chromes apart (`context` names the colours).
272
+ Contexts made before 0.6.1 get theirs at their next start.
245
273
  - **Starting it takes the screen once** — a cold Chrome launch comes to the
246
- front (issue #25). `goto`/`new` start it when it isn't running; `context stop
247
- <name>` quits it; `context forget <name> [--delete-profile]` removes it.
274
+ front (issue #25), and keys the user is typing can land in it. `goto`/`new`
275
+ start it when it isn't running; `context stop <name>` quits it; `context
276
+ forget <name> [--delete-profile]` removes it.
277
+ - **`context` lists every Chrome** — the user's own and each context's — with
278
+ port, pid, colour and sessions. `list` says which Chrome its tabs are in.
248
279
  - `-m`/`-t`, `list`, `doctor`, `launch` act on the user's Chrome unless given
249
- `--context <name>` (or `BAC_CONTEXT`).
280
+ `--context <name>` (or `BAC_CONTEXT`). A session always stays in the Chrome
281
+ it was opened in; only an explicit `--context` that disagrees is refused.
250
282
  - ⛔ **Not a second Chrome profile in the main Chrome, not an incognito-style
251
283
  CDP context.** A second profile becomes Chrome's default while its window is
252
284
  open — every other session's new tab opens in it, logged out. A CDP
@@ -264,23 +296,27 @@ browser-automation read -s cf2 # follows the session's context
264
296
  - **Refs go stale after any DOM change**, not just navigation. Snapshot → use
265
297
  those refs for one action → re-snapshot. "ref not found" means re-snapshot.
266
298
  - **`isTrusted` / synthetic events.** Clicks and fills are JS-dispatched by
267
- default, so widgets that demand trusted events ignore them. **For clicks, pass
268
- `--trusted`** — it dispatches a real CDP `Input.dispatchMouseEvent`, makes the
299
+ default and need no focus. **Radix and headless-UI triggers, menu items and popovers
300
+ work with a plain `click`** (a Radix Select option is picked by keyboard; the CLI prints
301
+ `(keyboard)`); for keyboard-driven lists use `key [ref] Enter` / `ArrowDown` / `Escape`.
302
+ Only widgets that check `isTrusted` ignore this. **For those clicks, pass `--trusted`** — it dispatches a real CDP `Input.dispatchMouseEvent`, makes the
269
303
  renderer treat the tab as focused+visible (CDP input no-ops on a backgrounded
270
304
  tab; the person's window keeps showing its own tab) and waits for the element to be actionable (stable position +
271
305
  unoccluded hit-test) before pressing. For fills, pass `--native` to drive
272
306
  character insertion through CDP `Input.insertText`, which fires real
273
307
  `beforeinput`/`input` events.
274
- **Reach for `--trusted` the moment a click "succeeds" but nothing happens** —
275
- the CLI prints `✔ clicked e7` on a dispatched event regardless of whether the
276
- widget reacted, so a silent no-op is the signature, not an error. Canonical
277
- cases: LinkedIn artdeco dropdown items, Radix dropdowns/popovers, cmdk
278
- comboboxes, and **framework-state form widgets whose inputs are `readonly` with
308
+ `--trusted` brings the tab's renderer to the foreground, so use it only when
309
+ the default click "succeeds" but nothing happens. The CLI prints `✔ clicked e7`
310
+ on a dispatched event regardless of whether the widget reacted, so a silent
311
+ no-op is the signature, not an error. Canonical cases: LinkedIn artdeco dropdown
312
+ items, and **framework-state form widgets whose inputs are `readonly` with
279
313
  no `name`** (Viking Line's booking selectors — the visible fields are display
280
314
  shells; the real state lives in the framework, so `fill` and DOM value-setting
281
315
  do nothing at all).
282
- - **There is NO way to send real keystrokes, and `fill --native` is not one** — it never fires
283
- `keydown`, so a combobox that filters on keystrokes stays empty. ⛔ **Do not hand-roll a
316
+ - **There is NO way to send real (trusted) keystrokes.** `key` dispatches an untrusted
317
+ `keydown`/`keyup`, enough for listboxes, menus and cmdk lists, but it types nothing into a
318
+ text field. `fill --native` never fires `keydown`, so a combobox that filters on keystrokes
319
+ stays empty. ⛔ **Do not hand-roll a
284
320
  raw-CDP trusted click** — `--trusted` already waits for actionability; check
285
321
  `browser-automation click --help` before building anything. A form can also swallow a
286
322
  dispatched click and fall through to a native POST (a raw `{"message":"Not Found"}` page,
@@ -364,7 +400,7 @@ browser-automation read -s cf2 # follows the session's context
364
400
  on the tab first, and capture the **viewport**, not `--full` (with
365
401
  `captureBeyondViewport` they composite at their pre-capture width, narrow and
366
402
  clipped). A blank region on a page with no cross-origin iframes is a real finding.
367
- - **Controls that ignore `click`** (Radix menus, `click` vs `--trusted`), hidden
403
+ - **Controls that ignore `click`** (`click` vs `--trusted`), hidden
368
404
  dialogs, stalled infinite scroll, React composers and GitHub image attachments:
369
405
  **[`references/page-recipes.md`](references/page-recipes.md)**.
370
406
  - **This needs the operator's machine, awake.** The shared headed Chrome and its
@@ -449,8 +485,8 @@ code lives, how to validate with `node dist/index.js`, and the PR steps:
449
485
  - **The Chrome on the port is on a profile you did not expect** → someone worked
450
486
  around a launch failure by hand (`BROWSER_AUTOMATION_PROFILE`, a typed
451
487
  `--user-data-dir`), and that instance has few or no logins. Read the live
452
- browser's profile before trusting a drive:
453
- `ps -p $(lsof -ti:9223) -o command= | tr ' ' '\n' | grep user-data-dir`. The
488
+ browser's profile before trusting a drive: the `profile` field of
489
+ `~/.browser-automation/broker.json` (a context's is in `contexts/<name>/`). The
454
490
  shared profile is `~/.browser-automation/chrome-profile`. ⚠️ Do not just kill it;
455
491
  it may be the operator's live browser. Ask, then `launch`.
456
492
  - **Chrome was restarted** → nothing to do; the next `goto` recreates the
@@ -10,28 +10,19 @@ clicks and needed `click --trusted`, while a link-styled **Withdraw** anchor was
10
10
  reverse: `Input.dispatchMouseEvent` at its centre silently did nothing, and `el.click()`
11
11
  opened the confirm dialog every time. Try both before concluding a control is broken.
12
12
 
13
- ## Radix menus open on `pointerdown`
14
-
15
- A Radix `DropdownMenu` or a row "⋯" trigger will not open from `click`, nor from a bare
16
- `element.click()`. Radix listens on `pointerdown`, so you get a snapshot with no
17
- `[role=menuitem]` in it. Send pointer events **plus** a real click, and return the items
18
- in the same call so you see at once whether it opened:
19
-
20
- ```bash
21
- browser-automation eval -s app '(() => {
22
- const b = [...document.querySelectorAll("button")].find(x => /Open menu/.test(x.getAttribute("aria-label") || x.textContent));
23
- const o = { bubbles: true, cancelable: true, pointerId: 1, isPrimary: true, button: 0 };
24
- b.dispatchEvent(new PointerEvent("pointerdown", o));
25
- b.dispatchEvent(new PointerEvent("pointerup", o));
26
- b.click();
27
- return [...document.querySelectorAll("[role=menuitem]")].map(x => x.textContent.trim()).join(" | ");
28
- })()'
29
- ```
30
-
31
- ⚠️ **Do not fire `click` and then this sequence.** Two activations toggle the menu open
32
- and shut again, which looks identical to it never opening. Once it is open, the menu
33
- items and dialog buttons take an ordinary `click [ref]` after a re-snapshot; only the
34
- trigger needs pointer events.
13
+ ## Radix menus open on `pointerdown`: a plain `click` handles it
14
+
15
+ A Radix `DropdownMenu` trigger, a row "⋯" trigger or a Select trigger acts on
16
+ `pointerdown`, not on `click`. The default `click` sends `pointerdown` and the rest of a
17
+ real click's events before `click`, so it opens them without taking focus, and the items
18
+ take a plain `click` after a re-snapshot. A Radix Select option is picked by keyboard
19
+ (focus + Enter), because Select ignores a `pointerup` that comes right after the
20
+ `pointerdown` that opened it; `click` does this by itself and prints `(keyboard)`.
21
+
22
+ Older CLIs sent only `element.click()`, so the trigger stayed shut and the snapshot had no
23
+ `[role=menuitem]` in it. ⚠️ With those, never send `click` and then a hand-rolled pointer
24
+ sequence: two activations toggle the menu open and shut again, which looks identical to
25
+ it never opening.
35
26
 
36
27
  ## Dialogs: filter by visibility, not by role
37
28
 
@@ -21,16 +21,17 @@ With **zero open tabs**, `list` prints the full saved-session list — every row
21
21
  describes a saved session whose tab is gone, not the browser's health. The tell is the
22
22
  `# open tabs (0)` line at the **end** of the output, easy to miss under a long listing.
23
23
 
24
- ⭐ **Ask the CDP endpoint instead.** It answers in one call and names the browser:
24
+ ⭐ **Ask `launch --status` instead.** It answers in one call (exit 0 = up):
25
25
 
26
26
  ```powershell
27
- Invoke-RestMethod -Uri "http://127.0.0.1:9223/json/version" -TimeoutSec 5 # Browser : Chrome/…
27
+ & "$env:APPDATA\npm\browser-automation.cmd" launch --status # Chrome is up on the pipe (\\.\pipe\browser-automation-…)
28
28
  ```
29
29
 
30
- A stale session list plus a live `/json/version` means **open a tab**
31
- (`new -s [name] [url]`), not relaunch the browser. It also tells you *which* browser is
32
- on the port: a Chrome started by hand, or an Edge standing in for Chrome, answers the same
33
- way.
30
+ A stale session list plus a browser that is up means **open a tab**
31
+ (`new -s [name] [url]`), not relaunch the browser. Since 0.7.0 Chrome on Windows
32
+ listens on no port: `http://127.0.0.1:9223/json/version` answering means a Chrome
33
+ from before the move, which anything on the computer can drive —
34
+ `launch --restart` switches it over.
34
35
 
35
36
  ## `|`, `&` and parentheses break through the `.cmd` shim
36
37