@generativereality/browser-automation 0.4.14 → 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.
- package/.claude-plugin/plugin.json +3 -2
- package/LICENSE +21 -0
- package/README.md +9 -4
- package/dist/index.js +2 -2
- package/package.json +2 -2
- package/scripts/release.sh +189 -0
- package/scripts/sync-plugin.sh +37 -5
- package/skills/browser/SKILL.md +48 -356
- package/skills/browser/references/contributing.md +36 -0
- package/skills/browser/references/input-and-forms.md +137 -0
- package/skills/browser/references/renderer-health.md +213 -0
|
@@ -1,9 +1,10 @@
|
|
|
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.
|
|
4
|
+
"version": "0.4.15",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "generativereality"
|
|
7
7
|
},
|
|
8
|
-
"homepage": "https://github.com/generativereality/browser-automation"
|
|
8
|
+
"homepage": "https://github.com/generativereality/browser-automation",
|
|
9
|
+
"license": "MIT"
|
|
9
10
|
}
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 generativereality
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -42,11 +42,16 @@ browser-automation doctor # verify (incl. renderer capacity)
|
|
|
42
42
|
Claude Code skill (so the agent knows how to use it):
|
|
43
43
|
|
|
44
44
|
```bash
|
|
45
|
-
mkdir -p .claude/skills/browser
|
|
46
|
-
|
|
47
|
-
|
|
45
|
+
mkdir -p .claude/skills/browser/references
|
|
46
|
+
base=https://raw.githubusercontent.com/generativereality/browser-automation/master/skills/browser
|
|
47
|
+
for f in SKILL.md references/input-and-forms.md references/renderer-health.md references/contributing.md; do
|
|
48
|
+
curl -fsSL "$base/$f" -o ".claude/skills/browser/$f"
|
|
49
|
+
done
|
|
48
50
|
```
|
|
49
51
|
|
|
52
|
+
The skill is `SKILL.md` plus the `references/` files it points to for the long
|
|
53
|
+
troubleshooting and hard cases; copy all of them.
|
|
54
|
+
|
|
50
55
|
…or install the plugin from the marketplace:
|
|
51
56
|
|
|
52
57
|
```bash
|
|
@@ -185,4 +190,4 @@ same one-action-per-snapshot rule as Playwright refs.
|
|
|
185
190
|
|
|
186
191
|
## License
|
|
187
192
|
|
|
188
|
-
MIT
|
|
193
|
+
MIT — see [`LICENSE`](LICENSE).
|
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.
|
|
12
|
+
var version = "0.4.15";
|
|
13
13
|
var description = "Daemonless, per-tab-isolated browser automation CLI for Claude Code. Drives one shared headed Chrome (persistent profile + extensions) over per-target CDP — many parallel sessions, no focus stealing, nothing long-lived to crash.";
|
|
14
14
|
var package_default = {
|
|
15
15
|
name,
|
|
@@ -29,7 +29,7 @@ var package_default = {
|
|
|
29
29
|
"typecheck": "tsc --noEmit",
|
|
30
30
|
"check": "npm run typecheck && bash scripts/check-one-port.sh && npm run build && npm test",
|
|
31
31
|
"test": "node --test \"test/**/*.test.mjs\"",
|
|
32
|
-
"release": "
|
|
32
|
+
"release": "bash scripts/release.sh",
|
|
33
33
|
"sync-plugin": "bash scripts/sync-plugin.sh",
|
|
34
34
|
"prepack": "npm run build"
|
|
35
35
|
},
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@generativereality/browser-automation",
|
|
3
|
-
"version": "0.4.
|
|
3
|
+
"version": "0.4.15",
|
|
4
4
|
"description": "Daemonless, per-tab-isolated browser automation CLI for Claude Code. Drives one shared headed Chrome (persistent profile + extensions) over per-target CDP — many parallel sessions, no focus stealing, nothing long-lived to crash.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -18,7 +18,7 @@
|
|
|
18
18
|
"typecheck": "tsc --noEmit",
|
|
19
19
|
"check": "npm run typecheck && bash scripts/check-one-port.sh && npm run build && npm test",
|
|
20
20
|
"test": "node --test \"test/**/*.test.mjs\"",
|
|
21
|
-
"release": "
|
|
21
|
+
"release": "bash scripts/release.sh",
|
|
22
22
|
"sync-plugin": "bash scripts/sync-plugin.sh",
|
|
23
23
|
"prepack": "npm run build"
|
|
24
24
|
},
|
|
@@ -0,0 +1,189 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
# Cut a release. Two halves, with the human approval gate between them.
|
|
3
|
+
#
|
|
4
|
+
# scripts/release.sh plan # what would ship since the last tag; changes nothing
|
|
5
|
+
# scripts/release.sh cut <patch|minor|X.Y.Z> [--dry-run]
|
|
6
|
+
# # bump, check, commit onto master, tag, push the tag
|
|
7
|
+
# scripts/release.sh finish # after the run is APPROVED: wait for npm, sync the
|
|
8
|
+
# # plugin, update this machine's install
|
|
9
|
+
#
|
|
10
|
+
# Why a script: every release in September 2026 was improvised from CLAUDE.md
|
|
11
|
+
# prose, and each one hit something the prose did not say — local master
|
|
12
|
+
# checked out in another worktree, a plugin sync rejected because another plugin
|
|
13
|
+
# had synced first, `npm view` reporting the old version for minutes after a
|
|
14
|
+
# successful publish. The steps are mechanical; the JUDGEMENT (which version,
|
|
15
|
+
# whether to approve) is not, so the script does the first and refuses to do
|
|
16
|
+
# the second.
|
|
17
|
+
#
|
|
18
|
+
# It never approves the gated CI run. Approval belongs to the maintainer, and
|
|
19
|
+
# `gh api .../pending_deployments` CAN do it from here — which is exactly why
|
|
20
|
+
# a script must not: see CLAUDE.md, "Releasing".
|
|
21
|
+
set -euo pipefail
|
|
22
|
+
|
|
23
|
+
cd "$(dirname "$0")/.."
|
|
24
|
+
ROOT="$(pwd)"
|
|
25
|
+
# What gets released. Only ever origin/master for real; overridable so a dry run
|
|
26
|
+
# can be tested against a branch that has something unreleased on it.
|
|
27
|
+
BASE="${BA_RELEASE_BASE:-origin/master}"
|
|
28
|
+
REPO=generativereality/browser-automation
|
|
29
|
+
PKG=@generativereality/browser-automation
|
|
30
|
+
|
|
31
|
+
die() { echo "Error: $*" >&2; exit 1; }
|
|
32
|
+
say() { printf '\n== %s\n' "$*"; }
|
|
33
|
+
|
|
34
|
+
last_tag() { git -C "$ROOT" describe --tags --abbrev=0 "$BASE" 2>/dev/null || true; }
|
|
35
|
+
|
|
36
|
+
plan() {
|
|
37
|
+
git fetch -q origin --tags
|
|
38
|
+
local tag; tag="$(last_tag)"
|
|
39
|
+
[ -n "$tag" ] || die "no release tag reachable from origin/master"
|
|
40
|
+
say "Unreleased on $BASE since $tag"
|
|
41
|
+
git log --format=' %h %s' "$tag..$BASE"
|
|
42
|
+
[ -n "$(git log --format=%h "$tag..$BASE")" ] || { echo " (nothing)"; return 0; }
|
|
43
|
+
say "Files touched"
|
|
44
|
+
git diff --stat "$tag..$BASE" | tail -n 25
|
|
45
|
+
say "Decide the version (CLAUDE.md, Versioning policy)"
|
|
46
|
+
cat <<'TXT'
|
|
47
|
+
minor if ANY of these shipped, even inside a "fix":
|
|
48
|
+
- where the CLI keeps or reads user data (profile, sessions, downloads), or a migration of it
|
|
49
|
+
- a changed default, flag meaning, exit code, or output a script might parse
|
|
50
|
+
- anything a user may need to act on after upgrading
|
|
51
|
+
otherwise patch (fixes, and commands that complete the CLI).
|
|
52
|
+
Name it to the maintainer with the reason, and get a yes, before `cut`.
|
|
53
|
+
TXT
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
cut() {
|
|
57
|
+
local want="${1:-}" dry="${2:-}"
|
|
58
|
+
[ -n "$want" ] || die "cut needs patch, minor or X.Y.Z — the version is a decision, not a default"
|
|
59
|
+
git fetch -q origin --tags
|
|
60
|
+
|
|
61
|
+
# Build the release from origin/master exactly, in a throwaway worktree:
|
|
62
|
+
# this checkout is shared with other sessions and local master usually lives
|
|
63
|
+
# in another worktree, so neither "the current branch" nor "master" is safe
|
|
64
|
+
# to assume.
|
|
65
|
+
# Global, not `local`: the EXIT trap runs after this function has returned.
|
|
66
|
+
RELEASE_WT="$(mktemp -d "${TMPDIR:-/tmp}/ba-release.XXXXXX")"
|
|
67
|
+
git worktree add -q --detach "$RELEASE_WT" "$BASE"
|
|
68
|
+
trap 'cd "$ROOT"; git worktree remove --force "$RELEASE_WT" >/dev/null 2>&1 || true' EXIT
|
|
69
|
+
cd "$RELEASE_WT"
|
|
70
|
+
|
|
71
|
+
local cur; cur="$(node -p "require('./package.json').version")"
|
|
72
|
+
local plug; plug="$(node -p "require('./.claude-plugin/plugin.json').version")"
|
|
73
|
+
[ "$cur" = "$plug" ] || die "package.json ($cur) and plugin.json ($plug) disagree on origin/master"
|
|
74
|
+
local next
|
|
75
|
+
case "$want" in
|
|
76
|
+
patch) next="$(node -p "v='$cur'.split('.').map(Number);v[2]++;v.join('.')")" ;;
|
|
77
|
+
minor) next="$(node -p "v='$cur'.split('.').map(Number);v[1]++;v[2]=0;v.join('.')")" ;;
|
|
78
|
+
[0-9]*.[0-9]*.[0-9]*) next="$want" ;;
|
|
79
|
+
*) die "unknown version '$want'" ;;
|
|
80
|
+
esac
|
|
81
|
+
git rev-parse -q --verify "refs/tags/v$next" >/dev/null && die "v$next already exists"
|
|
82
|
+
[ -z "$(git log --format=%h "$(last_tag)..HEAD")" ] && die "nothing unreleased since $(last_tag)"
|
|
83
|
+
|
|
84
|
+
say "Releasing $cur -> $next"
|
|
85
|
+
git log --format=' %h %s' "$(last_tag)..HEAD"
|
|
86
|
+
|
|
87
|
+
node -e "
|
|
88
|
+
const fs=require('fs');
|
|
89
|
+
for (const f of ['package.json','.claude-plugin/plugin.json']) {
|
|
90
|
+
const s=fs.readFileSync(f,'utf8'), t=s.replace(/(\"version\":\s*\")$cur(\")/, '\$1$next\$2');
|
|
91
|
+
if (s===t) { console.error('no version to bump in '+f); process.exit(1) }
|
|
92
|
+
fs.writeFileSync(f,t)
|
|
93
|
+
}"
|
|
94
|
+
npm install --package-lock-only --silent >/dev/null 2>&1 || true
|
|
95
|
+
|
|
96
|
+
say "npm ci + npm run check"
|
|
97
|
+
npm ci --silent >/dev/null
|
|
98
|
+
local log; log="$(mktemp "${TMPDIR:-/tmp}/ba-check.XXXXXX")"
|
|
99
|
+
npm run check >"$log" 2>&1 || {
|
|
100
|
+
tail -n 30 "$log" >&2
|
|
101
|
+
echo "" >&2
|
|
102
|
+
echo "npm run check failed (full log: $log). If it is the renderer-health tests, a busy" >&2
|
|
103
|
+
echo "Chrome on this user's port can fail them locally (CLAUDE.md, Dev gotchas) — compare" >&2
|
|
104
|
+
echo "against master under the same conditions before believing it." >&2
|
|
105
|
+
exit 1
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
git add package.json .claude-plugin/plugin.json package-lock.json
|
|
109
|
+
git commit -q -m "release: v$next"
|
|
110
|
+
git tag -a "v$next" -m "v$next"
|
|
111
|
+
|
|
112
|
+
if [ "$dry" = "--dry-run" ]; then
|
|
113
|
+
# Tags are shared by every worktree of this repo — leave none behind.
|
|
114
|
+
git tag -d "v$next" >/dev/null
|
|
115
|
+
say "Dry run: would push $(git rev-parse --short HEAD) to master and tag v$next. Nothing pushed, no tag kept."
|
|
116
|
+
return 0
|
|
117
|
+
fi
|
|
118
|
+
[ "$BASE" = "origin/master" ] || die "BA_RELEASE_BASE is for --dry-run only"
|
|
119
|
+
# Fast-forward only: if master moved while this ran, stop and re-plan rather
|
|
120
|
+
# than release something nobody looked at.
|
|
121
|
+
git push -q origin "HEAD:refs/heads/master" || die "master moved (push was not a fast-forward). Run plan again."
|
|
122
|
+
git push -q origin "v$next"
|
|
123
|
+
|
|
124
|
+
say "Tag v$next pushed. The release run is now WAITING FOR APPROVAL:"
|
|
125
|
+
sleep 5
|
|
126
|
+
gh run list --repo "$REPO" --workflow release.yml --limit 1 --json url,status --jq '.[0] | " \(.url) (\(.status))"' || true
|
|
127
|
+
cat <<TXT
|
|
128
|
+
|
|
129
|
+
Approving is the maintainer's call. Ask them to approve it there — or approve it
|
|
130
|
+
yourself only if they told you to for THIS release. Then: scripts/release.sh finish
|
|
131
|
+
TXT
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
finish() {
|
|
135
|
+
git fetch -q origin --tags
|
|
136
|
+
local tag; tag="$(last_tag)"; local v="${tag#v}"
|
|
137
|
+
local run; run="$(gh run list --repo "$REPO" --workflow release.yml --branch "$tag" --limit 1 --json databaseId --jq '.[0].databaseId')"
|
|
138
|
+
[ -n "$run" ] || die "no release run for $tag"
|
|
139
|
+
|
|
140
|
+
say "Waiting for the release run of $tag"
|
|
141
|
+
local s
|
|
142
|
+
for _ in $(seq 1 90); do
|
|
143
|
+
s="$(gh run view "$run" --repo "$REPO" --json status,conclusion --jq '.status+" "+.conclusion')"
|
|
144
|
+
case "$s" in
|
|
145
|
+
"completed success") break ;;
|
|
146
|
+
completed*) die "release run $run finished: $s — $(gh run view "$run" --repo "$REPO" --json url --jq .url)" ;;
|
|
147
|
+
waiting*) echo " still waiting for approval…" ;;
|
|
148
|
+
esac
|
|
149
|
+
sleep 10
|
|
150
|
+
done
|
|
151
|
+
[ "$s" = "completed success" ] || die "release run did not finish in 15 minutes"
|
|
152
|
+
|
|
153
|
+
# The registry, not `npm view`: publishing reports success minutes before
|
|
154
|
+
# the version is served (3.5 min for 0.4.13), and `npm view` also caches.
|
|
155
|
+
say "Waiting for $v on the registry"
|
|
156
|
+
local name="${PKG/\//%2F}"
|
|
157
|
+
for _ in $(seq 1 60); do
|
|
158
|
+
[ "$(curl -s -o /dev/null -w '%{http_code}' "https://registry.npmjs.org/$name/$v")" = 200 ] && break
|
|
159
|
+
sleep 10
|
|
160
|
+
done
|
|
161
|
+
[ "$(curl -s -o /dev/null -w '%{http_code}' "https://registry.npmjs.org/$name/$v")" = 200 ] || die "$v not on the registry after 10 minutes"
|
|
162
|
+
echo " $PKG@$v is live"
|
|
163
|
+
|
|
164
|
+
say "Plugin marketplace"
|
|
165
|
+
# Sync from the released tag, not from whatever this checkout has.
|
|
166
|
+
RELEASE_WT="$(mktemp -d "${TMPDIR:-/tmp}/ba-finish.XXXXXX")"
|
|
167
|
+
git worktree add -q --detach "$RELEASE_WT" "$tag"
|
|
168
|
+
trap 'cd "$ROOT"; git worktree remove --force "$RELEASE_WT" >/dev/null 2>&1 || true' EXIT
|
|
169
|
+
# This checkout's script (an old tag's copy lacks its fixes), the tag's files.
|
|
170
|
+
BA_PLUGIN_SOURCE="$RELEASE_WT" bash "$ROOT/scripts/sync-plugin.sh"
|
|
171
|
+
|
|
172
|
+
say "This machine"
|
|
173
|
+
npm install -g "$PKG@$v" >/dev/null 2>&1 && echo " installed $(browser-automation --version)"
|
|
174
|
+
|
|
175
|
+
say "Downstream — not done by this script"
|
|
176
|
+
cat <<TXT
|
|
177
|
+
- rememberthis.ai vendors the skill: python3 scripts/sync-vendored-skills.py --update
|
|
178
|
+
there, re-read its LOCAL block, commit that one file (other sessions work in that
|
|
179
|
+
repo — do not sweep up their changes).
|
|
180
|
+
- Tell the maintainer anything a user must act on (a moved profile, a changed default).
|
|
181
|
+
TXT
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
case "${1:-}" in
|
|
185
|
+
plan) plan ;;
|
|
186
|
+
cut) shift; cut "$@" ;;
|
|
187
|
+
finish) finish ;;
|
|
188
|
+
*) sed -n '2,8p' "$0"; exit 1 ;;
|
|
189
|
+
esac
|
package/scripts/sync-plugin.sh
CHANGED
|
@@ -9,8 +9,11 @@
|
|
|
9
9
|
set -euo pipefail
|
|
10
10
|
|
|
11
11
|
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
|
|
12
|
-
|
|
13
|
-
|
|
12
|
+
# Where the payload is copied FROM. Defaults to this checkout; `release.sh
|
|
13
|
+
# finish` points it at the released tag, so what ships is what was tagged —
|
|
14
|
+
# while still running THIS copy of the script (an old tag's copy lacks fixes).
|
|
15
|
+
REPO_ROOT="${BA_PLUGIN_SOURCE:-$(dirname "$SCRIPT_DIR")}"
|
|
16
|
+
PLUGINS_DIR="${BA_PLUGINS_DIR:-$(dirname "$SCRIPT_DIR")/../plugins}" # override for tests
|
|
14
17
|
CHECK_ONLY=false
|
|
15
18
|
[ "${1:-}" = "--check" ] && CHECK_ONLY=true
|
|
16
19
|
|
|
@@ -27,7 +30,13 @@ PAYLOAD_FILES=(
|
|
|
27
30
|
"skills/browser/SKILL.md"
|
|
28
31
|
".claude-plugin/plugin.json"
|
|
29
32
|
"scripts/launch-chrome.sh"
|
|
33
|
+
"LICENSE"
|
|
30
34
|
)
|
|
35
|
+
# SKILL.md links to these for its long reference material; a payload without
|
|
36
|
+
# them leaves the skill pointing at files that are not there.
|
|
37
|
+
for f in "$REPO_ROOT"/skills/browser/references/*.md; do
|
|
38
|
+
[ -e "$f" ] && PAYLOAD_FILES+=("skills/browser/references/$(basename "$f")")
|
|
39
|
+
done
|
|
31
40
|
|
|
32
41
|
for rel in "${PAYLOAD_FILES[@]}"; do
|
|
33
42
|
if ! diff -q "$REPO_ROOT/$rel" "$PLUGINS_DIR/plugins/browser-automation/$rel" >/dev/null 2>&1; then
|
|
@@ -56,13 +65,36 @@ done
|
|
|
56
65
|
rm -f "$PLUGINS_DIR/plugins/browser-automation/.mcp.json"
|
|
57
66
|
|
|
58
67
|
cd "$PLUGINS_DIR"
|
|
59
|
-
if git diff --quiet; then
|
|
68
|
+
if git diff --quiet -- plugins/browser-automation && [ -z "$(git ls-files --others --exclude-standard -- plugins/browser-automation)" ]; then
|
|
60
69
|
echo "Plugins repo already up to date"
|
|
61
70
|
exit 0
|
|
62
71
|
fi
|
|
63
72
|
|
|
73
|
+
# **Other plugins publish to this repo too.** The 0.4.14 sync was rejected
|
|
74
|
+
# because a cctabs sync had landed on origin/main in between — the marketplace
|
|
75
|
+
# is shared, so "behind origin" is the normal state, not an error. Commit ONLY
|
|
76
|
+
# our directory, then replay it on top of whatever arrived and push; our
|
|
77
|
+
# commit touches nothing outside plugins/browser-automation, so the rebase
|
|
78
|
+
# cannot conflict with another plugin's sync. It can conflict with a sync of
|
|
79
|
+
# THIS plugin from another checkout — then stop rather than guess.
|
|
80
|
+
BRANCH="$(git rev-parse --abbrev-ref HEAD)"
|
|
81
|
+
if [ "$BRANCH" != "main" ]; then
|
|
82
|
+
echo "Error: plugins repo is on '$BRANCH', not main. Not syncing into a branch." >&2
|
|
83
|
+
exit 1
|
|
84
|
+
fi
|
|
85
|
+
VERSION="$(node -p "require('$REPO_ROOT/package.json').version" 2>/dev/null || echo '?')"
|
|
64
86
|
git add plugins/browser-automation
|
|
65
|
-
git commit -m "chore: sync browser-automation plugin"
|
|
66
|
-
|
|
87
|
+
git commit -q -m "chore: sync browser-automation plugin to $VERSION"
|
|
88
|
+
for attempt in 1 2 3; do
|
|
89
|
+
git fetch -q origin main
|
|
90
|
+
if ! git rebase -q origin/main; then
|
|
91
|
+
git rebase --abort
|
|
92
|
+
echo "Error: rebasing the sync onto origin/main conflicted — something else changed" >&2
|
|
93
|
+
echo " plugins/browser-automation. Resolve in $PLUGINS_DIR, then push." >&2
|
|
94
|
+
exit 1
|
|
95
|
+
fi
|
|
96
|
+
git push -q origin main && break
|
|
97
|
+
[ "$attempt" = 3 ] && { echo "Error: push kept being rejected; see $PLUGINS_DIR." >&2; exit 1; }
|
|
98
|
+
done
|
|
67
99
|
|
|
68
100
|
echo "Synced browser-automation to plugins repo"
|
package/skills/browser/SKILL.md
CHANGED
|
@@ -79,7 +79,7 @@ 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
|
|
@@ -209,83 +209,22 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
|
|
|
209
209
|
no `name`** (Viking Line's booking selectors — the visible fields are display
|
|
210
210
|
shells; the real state lives in the framework, so `fill` and DOM value-setting
|
|
211
211
|
do nothing at all).
|
|
212
|
-
- **There is NO way to send real keystrokes, and `fill --native` is not one
|
|
213
|
-
`
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
**Do NOT hand-roll a raw-CDP trusted click.** Burned 2026-08-22: wrote a
|
|
229
|
-
bespoke `Input.dispatchMouseEvent` helper for exactly this, and it clicked
|
|
230
|
-
stale coordinates (the panel had animated in) — `--trusted` already solves that
|
|
231
|
-
with the actionability wait. Check `browser-automation click --help` before
|
|
232
|
-
building anything.
|
|
233
|
-
**A form can swallow a dispatched click and submit itself the wrong way.**
|
|
234
|
-
npmjs.com's package-settings forms are the case (2026-08-22): a default click
|
|
235
|
-
on the submit button did not reach the framework's handler, so the browser fell
|
|
236
|
-
through to a plain native POST and the tab was replaced by a raw
|
|
237
|
-
`{"message":"Not Found"}` — no error from the CLI, and nothing saved. It looks
|
|
238
|
-
like the server rejected your data; it did not. `--trusted` submitted the same
|
|
239
|
-
form correctly. On any settings page, verify by reloading and re-reading the
|
|
240
|
-
saved state rather than trusting a click that "worked".
|
|
241
|
-
- **WebAuthn / security keys need a genuinely focused, visible tab, and you
|
|
242
|
-
cannot supply the touch.** `navigator.credentials.get()` refuses outright when
|
|
243
|
-
`document.hasFocus()` is false or `visibilityState` is `hidden` — which is the
|
|
244
|
-
normal state while you work in the terminal, since `--trusted` only fronts the
|
|
245
|
-
tab for the instant of the click. The prompt then never opens and the page just
|
|
246
|
-
sits there, so a 2FA step can look like it is waiting for the user when the
|
|
247
|
-
browser has already declined to ask. Measured 2026-08-22 on npm's
|
|
248
|
-
`Use security key` challenge: the form POST returned **200** and the challenge
|
|
249
|
-
was live, but it could only be satisfied once the user brought that Chrome
|
|
250
|
-
window to the front themselves. Check with
|
|
251
|
-
`eval '({f:document.hasFocus(),v:document.visibilityState})'` before concluding
|
|
252
|
-
anything, and hand hardware-2FA steps to the user with the window frontmost.
|
|
253
|
-
- **Controlled-form state stickiness.** Form libraries that subscribe to React's
|
|
254
|
-
internal value-setter (React Hook Form, Final Form, Formik with a `Controller`,
|
|
255
|
-
Blocket/finn.no's `recommerce` editor) sometimes ignore the synthetic `input`
|
|
256
|
-
event the default `fill` dispatches: the DOM input shows the new value, but
|
|
257
|
-
the form's React state stays on the old one — and the next submit serializes
|
|
258
|
-
the *old* value. Two ways out:
|
|
259
|
-
1. **`fill --native --verify <ref> <value>`** — drives character insertion
|
|
260
|
-
through CDP `Input.insertText` (trusted events). `--verify` re-reads the
|
|
261
|
-
field afterwards and warns if either the DOM value diverged from what you
|
|
262
|
-
asked for, or if React's internal `_valueTracker` still holds the old
|
|
263
|
-
value (the canonical state-stickiness signature). Use this first; it
|
|
264
|
-
solves the vast majority of cases.
|
|
265
|
-
2. **API bypass** — when even `--native` doesn't stick (e.g. the form library
|
|
266
|
-
binds to an external state machine that drives its own POST/PUT), grab the
|
|
267
|
-
form's underlying endpoint and hit it directly:
|
|
268
|
-
```bash
|
|
269
|
-
# Hook fetch and persist a real form-submit's body + headers via localStorage
|
|
270
|
-
# (it survives the post-submit navigation, unlike window.* globals):
|
|
271
|
-
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);};})()"
|
|
272
|
-
# …then click Save once in the form so the hook captures the canonical PUT…
|
|
273
|
-
browser-automation eval -s app "({body:localStorage.getItem('__lastPut'),headers:localStorage.getItem('__lastHdrs')})"
|
|
274
|
-
# …gives you the endpoint, exact body shape, and custom headers
|
|
275
|
-
# (e.g. Blocket uses E-Tag, not the standard If-Match — and the etag lives
|
|
276
|
-
# in the JSON body, not the HTTP header).
|
|
277
|
-
```
|
|
278
|
-
Then re-fetch the GET endpoint for current data + the current etag, PUT
|
|
279
|
-
directly with the modified field(s) and the captured custom header, and
|
|
280
|
-
**drive the form's terminal commit step through the UI** — many two-step
|
|
281
|
-
editors (`edit → delivery → publish`) only persist `state: "edit"`
|
|
282
|
-
server-side until that final Save fires the commit.
|
|
283
|
-
|
|
284
|
-
Blocket's recommerce price field is the canonical case: default `fill e43 "500"`
|
|
285
|
-
shows 500 in the input but submits 750. Fix: `fill --native --verify e43 "500"`
|
|
286
|
-
(or, if --native doesn't stick: direct PUT to
|
|
287
|
-
`/recommerce/create/api/item/<id>` with `E-Tag: <body.etag>`, then click
|
|
288
|
-
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).
|
|
289
228
|
- **Cross-origin iframes are separate CDP targets.** `read`/`snapshot` see the
|
|
290
229
|
page's own document and same-origin frames, not cross-origin iframes (common
|
|
291
230
|
for SSO bank login widgets and embedded captchas). If the content you need
|
|
@@ -298,254 +237,31 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
|
|
|
298
237
|
whose JS handler builds a client-side **blob** and clicks it via a *nested*
|
|
299
238
|
synthetic click won't fire (Chrome activation quirk) — for those, grab the
|
|
300
239
|
underlying export URL/endpoint and use `--url`, or the site's API.
|
|
301
|
-
- **File upload
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
(
|
|
308
|
-
static input is useless — the handler uses its own throwaway input. Use
|
|
309
|
-
`upload --click <ref> <path…>`: it arms `Page.setInterceptFileChooserDialog`,
|
|
310
|
-
clicks the trigger, waits for `Page.fileChooserOpened`, and sets files on the
|
|
311
|
-
`backendNodeId` Chrome reports. Paths are resolved from cwd; pass absolute paths
|
|
312
|
-
to be safe. Multiple paths upload as a multi-file selection.
|
|
313
|
-
**Verify by re-snapshot/screenshot, and DON'T blindly retry.** Apps reset the
|
|
314
|
-
input to 0 right after consuming the file, so `upload` judges success by the
|
|
315
|
-
`change` event (it reports "delivered"), not by residual `input.files` — a
|
|
316
|
-
successful upload legitimately leaves `files=0`. The staged file often shows up
|
|
317
|
-
as a row in an attachment *list* (e.g. ASC's "Message Attachments"), not a single
|
|
318
|
-
chip, so confirm with `snapshot`/`screenshot` rather than assuming. Each
|
|
319
|
-
successful run **adds another attachment** — retrying a "did it work?" upload a
|
|
320
|
-
few times silently produces duplicates (this cost us a dozen copies on a live ASC
|
|
321
|
-
reply). Upload once, verify, and only re-run if verification shows nothing staged.
|
|
322
|
-
The **third path is drag-and-drop**, for zones with NO `<input type=file>` at
|
|
323
|
-
all — a `drop` listener reading `e.dataTransfer.files` (vocalremover-style audio
|
|
324
|
-
tools, many image/video drop zones). Neither `setfiles` nor `upload` applies;
|
|
325
|
-
use `drop <ref> <path…>`. By default it fires a genuinely-**trusted** CDP drag
|
|
326
|
-
(`Input.dispatchDragEvent`) carrying the real files from disk: it force-fronts
|
|
327
|
-
the tab (bringToFront + focus emulation + active lifecycle — so the tab reports
|
|
328
|
-
focused+visible even when the Chrome window isn't the frontmost OS window),
|
|
329
|
-
waits for the zone to be actionable, then dragEnter→dragOver→drop. The
|
|
330
|
-
force-front matters: drop-zone uploaders commonly do their work only inside a
|
|
331
|
-
**user activation**, and CDP input grants no activation on a tab the renderer
|
|
332
|
-
considers `hidden` — which it is whenever the window is occluded (the usual
|
|
333
|
-
case while you work in the terminal). vocalremover.org is the canonical example:
|
|
334
|
-
the file reaches its `change`/`drop` handler either way, but it only uploads +
|
|
335
|
-
separates once activation is present. `--js` instead dispatches a synthetic
|
|
336
|
-
(isTrusted=false) `DataTransfer` drop **without** force-fronting/stealing focus,
|
|
337
|
-
for zones that accept synthetic events. The `<ref>` can be any snapshot element
|
|
338
|
-
sitting over the drop region (a heading/button inside the zone) — the drop
|
|
339
|
-
bubbles to the zone/document handler, so it works even when the drop div itself
|
|
340
|
-
isn't snapshot-interactive. After the drop, `read`/`screenshot`/`network` to
|
|
341
|
-
confirm processing started, then grab the result (often a download endpoint you
|
|
342
|
-
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).
|
|
343
247
|
- **A NEW tab's renderer can be slow rather than broken — do not restart Chrome for it.**
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
sharing this Chrome. It twice destroyed unrecoverable work belonging to another session —
|
|
362
|
-
a finished AlternativeTo submission with hand edits, and an Azure signup flow mid-form.
|
|
363
|
-
|
|
364
|
-
**Since fixed (v0.4.12+):** `new`/`goto` wait for a late renderer and, if it still has not
|
|
365
|
-
answered, briefly activate the tab to force one and hand the window straight back (you get
|
|
366
|
-
a `WARN` saying so). The probe retries with a doubling budget, and the verdict now names
|
|
367
|
-
the permanent failure **only when its own signature is present**. On an older CLI, the
|
|
368
|
-
cheap move is to retry, or to drive a tab that already works.
|
|
369
|
-
|
|
370
|
-
**Whatever the version: before restarting anything, check the two corroborations.** Both
|
|
371
|
-
were decisive and neither used to be consulted:
|
|
372
|
-
```bash
|
|
373
|
-
launchctl print "gui/$(id -u)" | grep MachPortRendezvousServer.<browser-pid>
|
|
374
|
-
ps -Ao command= | grep -c -- '--type=renderer'
|
|
375
|
-
```
|
|
376
|
-
Mach name **present** + renderers **alive** ⇒ this is slowness, not the wedge. Retry, or use
|
|
377
|
-
a live tab. Mach name **absent** ⇒ it is the wedge, and only then is a restart the answer.
|
|
378
|
-
|
|
379
|
-
- **"The site is blocking us" — when it is really Chrome that cannot make renderers.**
|
|
380
|
-
A browser process can permanently lose the ability to launch **renderer processes** while
|
|
381
|
-
looking perfectly healthy. Every tab that already exists keeps working, so nothing seems wrong
|
|
382
|
-
until you open a tab or navigate somewhere new, and then the errors read as the remote site's
|
|
383
|
-
doing. Diagnosed 2026-08-22; it cost an hour of blaming ferry-operator bot protection.
|
|
384
|
-
⚠️ **This is a real condition and a rare one.** Confirm the Mach name is absent (above)
|
|
385
|
-
before you believe it — a slow background renderer produces every symptom in this list.
|
|
386
|
-
|
|
387
|
-
How it shows up:
|
|
388
|
-
- `browser-automation new` + `goto` → `CDP Page.enable timed out after 30000ms`, **even for
|
|
389
|
-
`example.com`**.
|
|
390
|
-
- **Cross-origin** navigation of an existing, working tab → `navigate failed: net::ERR_ABORTED`.
|
|
391
|
-
Site isolation puts a new origin in a new renderer — the exact thing Chrome can no longer do.
|
|
392
|
-
- **Same-origin** navigation on that same tab keeps working perfectly (Skyscanner → Skyscanner
|
|
393
|
-
with new query params was fine throughout). That asymmetry is what makes it masquerade as
|
|
394
|
-
"only site X blocks us": the tab you were already using still behaves.
|
|
395
|
-
- A target created at the browser level (`PUT /json/new?<url>`) appears in `/json/list` with the
|
|
396
|
-
right URL but an **empty title forever**; every `Runtime.evaluate` against it times out.
|
|
397
|
-
`Page.captureScreenshot` returns `Internal error`. The target shell exists; the renderer does not.
|
|
398
|
-
|
|
399
|
-
**It gets SLOW before it fails outright — that is the early warning.** Observed 2026-09-07 on a
|
|
400
|
-
Chrome that had been up 12 days: every `goto` took ~25–30s, and a batch of three blew a 120s
|
|
401
|
-
timeout, hours before anything failed hard. That was misread as "large files, slow browser" and
|
|
402
|
-
worked around with longer timeouts for many minutes; the actual fix was one `launch --restart`,
|
|
403
|
-
after which the same pages loaded instantly and 14 `file://` tabs opened in two quick batches.
|
|
404
|
-
**A `goto` that has quietly become slow is this, not your page.** Raise the timeout at most once,
|
|
405
|
-
then run `doctor`.
|
|
406
|
-
|
|
407
|
-
**Every cheap signal stays green, so do not take any of them as health.** On that same wedged
|
|
408
|
-
browser: `launch` said `Already running on :9223 — nothing to do.`, `curl :9223/json/version`
|
|
409
|
-
answered normally, and `list` cheerfully returned 10 targets — while `goto` exited 1 and `eval`
|
|
410
|
-
died with `CDP Runtime.evaluate timed out after 30000ms`. Port held, HTTP endpoint answering and
|
|
411
|
-
targets listed are all properties of the **browser** process; the thing that is broken is its
|
|
412
|
-
ability to start a **renderer**, and only a probe that runs code in one can see it.
|
|
413
|
-
**Since fixed:** `launch` now runs that probe itself and exits non-zero with the diagnosis
|
|
414
|
-
instead of reporting "nothing to do", so this particular green-across-the-board trap is closed.
|
|
415
|
-
It still will not restart for you — that stays something you type, because the tabs are not
|
|
416
|
-
only yours. On a CLI old enough to lack it, `doctor` is the same probe; nothing cheaper
|
|
417
|
-
substitutes for either.
|
|
418
|
-
|
|
419
|
-
**The mechanism** (macOS, from Chrome's own log at `$TMPDIR/chrome-<port>.log` — `launch --restart`
|
|
420
|
-
keeps the previous browser's log as `chrome-<port>.log.prev`, which is the one you want after a
|
|
421
|
-
restart):
|
|
422
|
-
```
|
|
423
|
-
ERROR:base/apple/mach_port_rendezvous_mac.cc:256]
|
|
424
|
-
bootstrap_look_up com.google.Chrome.MachPortRendezvousServer.<pid>: (ipc/send) invalid destination port
|
|
425
|
-
ERROR:base/memory/shared_memory_switch.cc:261]
|
|
426
|
-
No rendezvous client, terminating process (parent died?)
|
|
427
|
-
```
|
|
428
|
-
A Chrome child process gets its shared-memory handles by looking up a Mach bootstrap service the
|
|
429
|
-
browser registers **once, at startup**, named `com.google.Chrome.MachPortRendezvousServer.<browser-pid>`.
|
|
430
|
-
That registration had vanished from the user's launchd namespace — confirmed absent via
|
|
431
|
-
`launchctl print gui/$UID | grep MachPortRendezvousServer.<pid>`, while two healthy Chromes on the
|
|
432
|
-
same machine were both listed. From then on **every renderer Chrome launches kills itself within
|
|
433
|
-
milliseconds**, which is why none ever appears in `ps` and why the browser only reports
|
|
434
|
-
`Render process gone.` **What made the name vanish is not established.** Two things
|
|
435
|
-
correlated and neither is proven: the binary on disk had moved to 151.0.7922.170 while the live
|
|
436
|
-
browser was still running .138, and `GoogleUpdater` was FATAL-ing on its own `bootstrap_check_in`
|
|
437
|
-
with error 141. But the first renderer failure (18:53) *preceded* the first updater FATAL (19:42)
|
|
438
|
-
by ~50 minutes, so the update churn is at best a fellow symptom of a sick launchd bootstrap
|
|
439
|
-
namespace, not the cause. Treat the trigger as unknown; the diagnosis and the recovery do not
|
|
440
|
-
depend on it.
|
|
441
|
-
|
|
442
|
-
**It is NOT about how many tabs are open.** That was the first theory and it is wrong: a freshly
|
|
443
|
-
launched Chrome on the same machine was driven to **421 page targets / 435 live renderer
|
|
444
|
-
processes, every one responsive**, and a 256-fd `ulimit` made no difference either (205 renderers,
|
|
445
|
-
all fine). The broken browser had 66 tabs. The count was a coincidence — so do not treat a big
|
|
446
|
-
tab count as evidence of this, and do not expect closing tabs to fix it.
|
|
447
|
-
|
|
448
|
-
**Diagnose it:**
|
|
449
|
-
```bash
|
|
450
|
-
browser-automation doctor # measures renderer capacity, not just reachability
|
|
451
|
-
```
|
|
452
|
-
`doctor` now creates a throwaway tab, makes its renderer evaluate `1+1`, and closes it — the one
|
|
453
|
-
round-trip that separates a wedged browser from a slow network or a hostile site. On failure it
|
|
454
|
-
names the root cause (including the missing bootstrap service and the pid) and points at Chrome's
|
|
455
|
-
log. On a healthy browser it reports e.g. `✓ Renderer capacity: a new tab got a live renderer in
|
|
456
|
-
73ms`. `goto` and `new` run the same probe automatically **on the error path only**, so a bare
|
|
457
|
-
`Page.enable timed out` now arrives with the diagnosis attached instead of sending you to the
|
|
458
|
-
site's bot-protection docs.
|
|
459
|
-
|
|
460
|
-
**Recovery — cheapest first, and a restart only once the Mach name is confirmed absent.**
|
|
461
|
-
|
|
462
|
-
1. **Retry.** A new tab's renderer has been measured taking 12s and more on a loaded
|
|
463
|
-
machine, and late is not broken.
|
|
464
|
-
2. **Drive a tab that already works.** An existing tab navigates same-origin without
|
|
465
|
-
needing a new renderer, so it keeps working throughout even during a genuine wedge:
|
|
466
|
-
```bash
|
|
467
|
-
browser-automation list
|
|
468
|
-
browser-automation eval -t <id> "location.href='<url>'"
|
|
469
|
-
```
|
|
470
|
-
3. **`browser-automation doctor`** — re-measures, prints the two corroborations, and shows
|
|
471
|
-
the recent probe-time distribution from `~/.browser-automation/renderer-probes.jsonl`.
|
|
472
|
-
4. **Only if `doctor` reports the Mach rendezvous service ABSENT**, restart. The bootstrap
|
|
473
|
-
name is registered at startup and never re-registered, so nothing short of a new browser
|
|
474
|
-
process helps; closing tabs does not, and plain `launch` will not either (idempotent by
|
|
475
|
-
design — it sees a live browser and exits happy):
|
|
476
|
-
```bash
|
|
477
|
-
browser-automation launch --restart # quit (CDP, then SIGTERM), wait for the profile, relaunch
|
|
478
|
-
```
|
|
479
|
-
It reports how many tabs it is about to close. `Chrome released its profile but left its
|
|
480
|
-
process running (normal on macOS); ending it.` is the **expected** line, not a fault: on
|
|
481
|
-
macOS 27 / Chrome 153 the browser process never exits on its own after quitting, but it
|
|
482
|
-
does flush and release the profile first, and that release is what the restart waits for.
|
|
483
|
-
(Older CLIs waited only for the port to close and relaunched on top of the still-running
|
|
484
|
-
Chrome — two browsers on one profile. If you see `Chrome did not exit on SIGTERM`, or no
|
|
485
|
-
such line and then odd profile errors, you are on one of those.) **Those tabs belong to every parallel
|
|
486
|
-
Claude Code session sharing this Chrome — ask Fred first, never restart unilaterally.**
|
|
487
|
-
|
|
488
|
-
**Housekeeping is a different problem** — `browser-automation gc` prunes stale session bookmarks
|
|
489
|
-
(they are never cleaned up otherwise; this machine had accumulated 234, only 5 of them live) and
|
|
490
|
-
closes tabs whose renderer does not answer. Use `--dry` first. `list` now counts stale
|
|
491
|
-
bookmarks instead of printing them (`list --all` to see them) — 105 stale lines above a
|
|
492
|
-
24-tab Chrome is how "there are a hundred tabs open" became the leading theory for a
|
|
493
|
-
renderer failure that has nothing to do with tab count. It is genuinely useful, but it is
|
|
494
|
-
**not** a fix for the wedge above, and it never closes a working tab unless you pass `--orphans`
|
|
495
|
-
— tabs get addressed by `-m` and opened by hand, so "no session claims it" is not evidence that
|
|
496
|
-
nobody wants it.
|
|
497
|
-
|
|
498
|
-
**The false lead to resist:** a bare `curl` to a suspicious site may genuinely return a bot wall
|
|
499
|
-
(vikingline.fi serves an Imperva "Pardon Our Interruption" page, HTTP 200), which feels like
|
|
500
|
-
confirmation. It confirms nothing about the browser path — the persistent, cookie-bearing profile
|
|
501
|
-
is a completely different client. Check the browser first: if `doctor` says renderer capacity is
|
|
502
|
-
fine and a boring cross-origin URL loads, *then* start suspecting the site.
|
|
503
|
-
|
|
504
|
-
- **A backgrounded tab may never paint at all — and `read`/`snapshot` will not tell you.** Distinct
|
|
505
|
-
from "still loading": `document.readyState` reaches `complete`, but the SPA never renders, so
|
|
506
|
-
`read` returns a stale shell (e.g. a bare "Loading") and `snapshot` lists none of the real
|
|
507
|
-
controls. The trap is that this looks exactly like *the page does not have that element*, and you
|
|
508
|
-
will go hunting for a different selector or conclude the flow changed. Measured 2026-09-02 on
|
|
509
|
-
Google's `accounts.google.com/v3/signin/challenge/pwd`: `readyState: "complete"`,
|
|
510
|
-
`body.innerText.length: 202` frozen on the previous step's text, and the password field present in
|
|
511
|
-
the DOM but `offsetParent === null` for as long as the tab stayed backgrounded.
|
|
512
|
-
**Diagnose** before changing your selector:
|
|
513
|
-
```bash
|
|
514
|
-
browser-automation eval -s x '({ready:document.readyState,vis:document.visibilityState,len:document.body.innerText.length})'
|
|
515
|
-
```
|
|
516
|
-
`visibilityState: "hidden"` with a **stuck `len`** is this, not a selector problem. Note the
|
|
517
|
-
stuck `len` is the whole tell: `hidden` on its own is the normal, healthy state of every
|
|
518
|
-
backgrounded tab — verified 2026-09-07, a background tab reporting `hidden` returned its real
|
|
519
|
-
painted text — so never read `hidden` alone as a diagnosis.
|
|
520
|
-
**Fix:** make the tab report itself visible.
|
|
521
|
-
```bash
|
|
522
|
-
browser-automation focus -s x # quiet: no window moves, you keep your frontmost app
|
|
523
|
-
```
|
|
524
|
-
`focus` emulates focus + visibility in the renderer, then **reads back what it actually
|
|
525
|
-
achieved** rather than reporting that it sent the command — so a partial result says which half
|
|
526
|
-
is missing instead of printing a tick over it. The page paints immediately. Add `--raise` only
|
|
527
|
-
when a *person* needs to see the tab: that genuinely fronts it and **takes the operator's
|
|
528
|
-
screen**, which is exactly what you normally want to avoid.
|
|
529
|
-
Same root cause as the WebAuthn note above, different symptom: that one refuses, this one
|
|
530
|
-
silently never renders.
|
|
531
|
-
*(Older CLIs had no `focus`; the workaround was a `click --trusted` on a harmless wrapper `div`,
|
|
532
|
-
which fronted the tab as a side effect of needing trusted input. Prefer `focus` — it says what it
|
|
533
|
-
achieved, and it does not click anything.)*
|
|
534
|
-
|
|
535
|
-
**Do not confuse this with the renderer wedge above.** Both present to an operator as "the page
|
|
536
|
-
isn't there, but every tool says fine", and the fixes are opposite — one is a per-tab nudge, the
|
|
537
|
-
other closes every tab in the browser. What separates them:
|
|
538
|
-
|
|
539
|
-
| | backgrounded tab never paints | Chrome cannot make renderers |
|
|
540
|
-
|---|---|---|
|
|
541
|
-
| `goto` | succeeds, rc=0 (may be slow) | **rc=1**, or `Page.enable timed out` |
|
|
542
|
-
| `eval` | works, returns a result | **`Runtime.evaluate` times out at 30000ms** |
|
|
543
|
-
| scope | that one tab | **every** new tab / cross-origin nav |
|
|
544
|
-
| `doctor` | `✓ Renderer capacity` | names the wedge + pid |
|
|
545
|
-
| fix | `focus` on the tab | `launch --restart` (**ask first**) |
|
|
546
|
-
|
|
547
|
-
`eval` is the fast discriminator: if it answers at all, the renderer is alive and you are in the
|
|
548
|
-
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.
|
|
549
265
|
- **Page still loading.** `goto` waits for the load event, but SPAs render after.
|
|
550
266
|
If a `read`/`snapshot` looks empty, re-run after a moment, or snapshot again
|
|
551
267
|
once a known element should be present.
|
|
@@ -580,37 +296,13 @@ case; drop to raw CDP only for cross-origin-iframe reads or one-off probes.
|
|
|
580
296
|
|
|
581
297
|
## Hit a shortcoming or bug? Fix it — it's open source
|
|
582
298
|
|
|
583
|
-
This CLI is `@generativereality/browser-automation`
|
|
584
|
-
`github.com/generativereality/browser-automation`). When
|
|
585
|
-
|
|
586
|
-
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
590
|
-
(or `git clone https://github.com/generativereality/browser-automation`).
|
|
591
|
-
2. **Fix** in `src/` — TypeScript. Commands live in `src/commands/<name>.ts`,
|
|
592
|
-
the daemonless CDP core in `src/core/` (`cdp.ts` connection/eval/navigate,
|
|
593
|
-
`dom.ts` injected snapshot/click/read JS, `download.ts`, `resolve.ts` tab
|
|
594
|
-
selection). Add a command by creating `src/commands/x.ts` and registering it
|
|
595
|
-
in `src/commands/index.ts`.
|
|
596
|
-
3. **Validate locally** against the running Chrome:
|
|
597
|
-
`npm install && npm run typecheck && npm run build`, then run your build as
|
|
598
|
-
**`node dist/index.js <cmd>`** from the clone. **Do NOT `npm link`** — it
|
|
599
|
-
repoints the machine-global `browser-automation` bin, so a parallel Claude
|
|
600
|
-
Code session (or the user's main session) would suddenly be running *your*
|
|
601
|
-
work-in-progress clone instead of the installed release. Validate via the
|
|
602
|
-
explicit `node dist/index.js` path instead. Reproduce the failure, confirm
|
|
603
|
-
the fix, and re-test on a scratch tab you created (read-only-safe; never
|
|
604
|
-
disrupt the user's live tabs).
|
|
605
|
-
4. **Propose a PR** for the user to review and contribute upstream — don't
|
|
606
|
-
publish yourself (the maintainer cuts releases):
|
|
607
|
-
```bash
|
|
608
|
-
git checkout -b fix/<short-desc>
|
|
609
|
-
git commit -am "fix: <what and why>"
|
|
610
|
-
gh pr create --fill --repo generativereality/browser-automation
|
|
611
|
-
```
|
|
612
|
-
Then tell the user the branch/PR link and what it changes, and ask them to
|
|
613
|
-
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).
|
|
614
306
|
|
|
615
307
|
## Troubleshooting
|
|
616
308
|
|
|
@@ -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`.
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
# Input, forms and uploads — the hard cases
|
|
2
|
+
|
|
3
|
+
Reference for the `browser` skill. Read it when a click or fill "succeeds" but nothing
|
|
4
|
+
happens, a combobox needs real keystrokes, a hardware-2FA prompt never appears, a form
|
|
5
|
+
submits a stale value, or you need to upload a file. The short rules are in `SKILL.md`,
|
|
6
|
+
under Gotchas; this is the detail and the worked cases behind them.
|
|
7
|
+
|
|
8
|
+
## Keystrokes, and forms that swallow a dispatched click
|
|
9
|
+
|
|
10
|
+
- **There is NO way to send real keystrokes, and `fill --native` is not one.** `--native` uses CDP
|
|
11
|
+
`Input.insertText`, which fires `beforeinput`/`input` but **never `keydown`**. A combobox that
|
|
12
|
+
filters its list on keystrokes therefore stays empty: the value lands in the DOM and no options
|
|
13
|
+
ever render. npm’s "Select packages and scopes" picker is the canonical case (2026-08-22) — the
|
|
14
|
+
field showed `generativereality` and the list stayed blank through `fill`, `fill --native`, and a
|
|
15
|
+
React native-setter `eval`. There is no `press` or `type` command to escalate to.
|
|
16
|
+
⇒ Drop to raw CDP on the tab’s `webSocketDebuggerUrl` and dispatch `Input.dispatchKeyEvent`
|
|
17
|
+
per character. Two traps, both hit:
|
|
18
|
+
**(1) `keyDown` carrying `text` already inserts the character** — sending a `char` event as well
|
|
19
|
+
types everything twice (`ggeenneerraattiivvee…`), which reads as a flaky page rather than a double
|
|
20
|
+
dispatch. Send `keyDown` + `keyUp` only.
|
|
21
|
+
**(2) Clear with real Backspaces, not select-all+Delete.** A value written by a JS setter is
|
|
22
|
+
invisible to the component’s own state, so the framework keeps the old string and you end up
|
|
23
|
+
appending to it. Backspacing drives the same path a person would.
|
|
24
|
+
Also: the dropdown must actually be **open** first — typing into a collapsed picker’s hidden input
|
|
25
|
+
does nothing, and looks identical to the events not landing.
|
|
26
|
+
**Do NOT hand-roll a raw-CDP trusted click.** Burned 2026-08-22: wrote a
|
|
27
|
+
bespoke `Input.dispatchMouseEvent` helper for exactly this, and it clicked
|
|
28
|
+
stale coordinates (the panel had animated in) — `--trusted` already solves that
|
|
29
|
+
with the actionability wait. Check `browser-automation click --help` before
|
|
30
|
+
building anything.
|
|
31
|
+
**A form can swallow a dispatched click and submit itself the wrong way.**
|
|
32
|
+
npmjs.com's package-settings forms are the case (2026-08-22): a default click
|
|
33
|
+
on the submit button did not reach the framework's handler, so the browser fell
|
|
34
|
+
through to a plain native POST and the tab was replaced by a raw
|
|
35
|
+
`{"message":"Not Found"}` — no error from the CLI, and nothing saved. It looks
|
|
36
|
+
like the server rejected your data; it did not. `--trusted` submitted the same
|
|
37
|
+
form correctly. On any settings page, verify by reloading and re-reading the
|
|
38
|
+
saved state rather than trusting a click that "worked".
|
|
39
|
+
|
|
40
|
+
## WebAuthn / security keys
|
|
41
|
+
|
|
42
|
+
- **WebAuthn / security keys need a genuinely focused, visible tab, and you
|
|
43
|
+
cannot supply the touch.** `navigator.credentials.get()` refuses outright when
|
|
44
|
+
`document.hasFocus()` is false or `visibilityState` is `hidden` — which is the
|
|
45
|
+
normal state while you work in the terminal, since `--trusted` only fronts the
|
|
46
|
+
tab for the instant of the click. The prompt then never opens and the page just
|
|
47
|
+
sits there, so a 2FA step can look like it is waiting for the user when the
|
|
48
|
+
browser has already declined to ask. Measured 2026-08-22 on npm's
|
|
49
|
+
`Use security key` challenge: the form POST returned **200** and the challenge
|
|
50
|
+
was live, but it could only be satisfied once the user brought that Chrome
|
|
51
|
+
window to the front themselves. Check with
|
|
52
|
+
`eval '({f:document.hasFocus(),v:document.visibilityState})'` before concluding
|
|
53
|
+
anything, and hand hardware-2FA steps to the user with the window frontmost.
|
|
54
|
+
|
|
55
|
+
## Controlled-form state stickiness
|
|
56
|
+
|
|
57
|
+
- **Controlled-form state stickiness.** Form libraries that subscribe to React's
|
|
58
|
+
internal value-setter (React Hook Form, Final Form, Formik with a `Controller`,
|
|
59
|
+
Blocket/finn.no's `recommerce` editor) sometimes ignore the synthetic `input`
|
|
60
|
+
event the default `fill` dispatches: the DOM input shows the new value, but
|
|
61
|
+
the form's React state stays on the old one — and the next submit serializes
|
|
62
|
+
the *old* value. Two ways out:
|
|
63
|
+
1. **`fill --native --verify <ref> <value>`** — drives character insertion
|
|
64
|
+
through CDP `Input.insertText` (trusted events). `--verify` re-reads the
|
|
65
|
+
field afterwards and warns if either the DOM value diverged from what you
|
|
66
|
+
asked for, or if React's internal `_valueTracker` still holds the old
|
|
67
|
+
value (the canonical state-stickiness signature). Use this first; it
|
|
68
|
+
solves the vast majority of cases.
|
|
69
|
+
2. **API bypass** — when even `--native` doesn't stick (e.g. the form library
|
|
70
|
+
binds to an external state machine that drives its own POST/PUT), grab the
|
|
71
|
+
form's underlying endpoint and hit it directly:
|
|
72
|
+
```bash
|
|
73
|
+
# Hook fetch and persist a real form-submit's body + headers via localStorage
|
|
74
|
+
# (it survives the post-submit navigation, unlike window.* globals):
|
|
75
|
+
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);};})()"
|
|
76
|
+
# …then click Save once in the form so the hook captures the canonical PUT…
|
|
77
|
+
browser-automation eval -s app "({body:localStorage.getItem('__lastPut'),headers:localStorage.getItem('__lastHdrs')})"
|
|
78
|
+
# …gives you the endpoint, exact body shape, and custom headers
|
|
79
|
+
# (e.g. Blocket uses E-Tag, not the standard If-Match — and the etag lives
|
|
80
|
+
# in the JSON body, not the HTTP header).
|
|
81
|
+
```
|
|
82
|
+
Then re-fetch the GET endpoint for current data + the current etag, PUT
|
|
83
|
+
directly with the modified field(s) and the captured custom header, and
|
|
84
|
+
**drive the form's terminal commit step through the UI** — many two-step
|
|
85
|
+
editors (`edit → delivery → publish`) only persist `state: "edit"`
|
|
86
|
+
server-side until that final Save fires the commit.
|
|
87
|
+
|
|
88
|
+
Blocket's recommerce price field is the canonical case: default `fill e43 "500"`
|
|
89
|
+
shows 500 in the input but submits 750. Fix: `fill --native --verify e43 "500"`
|
|
90
|
+
(or, if --native doesn't stick: direct PUT to
|
|
91
|
+
`/recommerce/create/api/item/<id>` with `E-Tag: <body.etag>`, then click
|
|
92
|
+
Save on the delivery page to commit).
|
|
93
|
+
|
|
94
|
+
## File upload
|
|
95
|
+
|
|
96
|
+
- **File upload.** Three paths. The first two mirror Playwright. For a static, snapshot-able
|
|
97
|
+
`<input type=file>`, use `setfiles <ref> <path…>` — it resolves the ref and
|
|
98
|
+
calls `DOM.setFileInputFiles` (a file input's `.files` is read-only to page JS,
|
|
99
|
+
so a value-setter/`eval` can't populate it; CDP can, and fires trusted
|
|
100
|
+
`input`/`change`). For a **custom "attach" button** that opens a native file
|
|
101
|
+
chooser and reads a *transient* `<input type=file>` it creates+clicks on the fly
|
|
102
|
+
(App Store Connect's "Attach File", many React dropzones), `setfiles` on the
|
|
103
|
+
static input is useless — the handler uses its own throwaway input. Use
|
|
104
|
+
`upload --click <ref> <path…>`: it arms `Page.setInterceptFileChooserDialog`,
|
|
105
|
+
clicks the trigger, waits for `Page.fileChooserOpened`, and sets files on the
|
|
106
|
+
`backendNodeId` Chrome reports. Paths are resolved from cwd; pass absolute paths
|
|
107
|
+
to be safe. Multiple paths upload as a multi-file selection.
|
|
108
|
+
**Verify by re-snapshot/screenshot, and DON'T blindly retry.** Apps reset the
|
|
109
|
+
input to 0 right after consuming the file, so `upload` judges success by the
|
|
110
|
+
`change` event (it reports "delivered"), not by residual `input.files` — a
|
|
111
|
+
successful upload legitimately leaves `files=0`. The staged file often shows up
|
|
112
|
+
as a row in an attachment *list* (e.g. ASC's "Message Attachments"), not a single
|
|
113
|
+
chip, so confirm with `snapshot`/`screenshot` rather than assuming. Each
|
|
114
|
+
successful run **adds another attachment** — retrying a "did it work?" upload a
|
|
115
|
+
few times silently produces duplicates (this cost us a dozen copies on a live ASC
|
|
116
|
+
reply). Upload once, verify, and only re-run if verification shows nothing staged.
|
|
117
|
+
The **third path is drag-and-drop**, for zones with NO `<input type=file>` at
|
|
118
|
+
all — a `drop` listener reading `e.dataTransfer.files` (vocalremover-style audio
|
|
119
|
+
tools, many image/video drop zones). Neither `setfiles` nor `upload` applies;
|
|
120
|
+
use `drop <ref> <path…>`. By default it fires a genuinely-**trusted** CDP drag
|
|
121
|
+
(`Input.dispatchDragEvent`) carrying the real files from disk: it force-fronts
|
|
122
|
+
the tab (bringToFront + focus emulation + active lifecycle — so the tab reports
|
|
123
|
+
focused+visible even when the Chrome window isn't the frontmost OS window),
|
|
124
|
+
waits for the zone to be actionable, then dragEnter→dragOver→drop. The
|
|
125
|
+
force-front matters: drop-zone uploaders commonly do their work only inside a
|
|
126
|
+
**user activation**, and CDP input grants no activation on a tab the renderer
|
|
127
|
+
considers `hidden` — which it is whenever the window is occluded (the usual
|
|
128
|
+
case while you work in the terminal). vocalremover.org is the canonical example:
|
|
129
|
+
the file reaches its `change`/`drop` handler either way, but it only uploads +
|
|
130
|
+
separates once activation is present. `--js` instead dispatches a synthetic
|
|
131
|
+
(isTrusted=false) `DataTransfer` drop **without** force-fronting/stealing focus,
|
|
132
|
+
for zones that accept synthetic events. The `<ref>` can be any snapshot element
|
|
133
|
+
sitting over the drop region (a heading/button inside the zone) — the drop
|
|
134
|
+
bubbles to the zone/document handler, so it works even when the drop div itself
|
|
135
|
+
isn't snapshot-interactive. After the drop, `read`/`screenshot`/`network` to
|
|
136
|
+
confirm processing started, then grab the result (often a download endpoint you
|
|
137
|
+
can pull with `download --url`).
|
|
@@ -0,0 +1,213 @@
|
|
|
1
|
+
# Renderer health — slow tabs, wedged Chrome, tabs that never paint
|
|
2
|
+
|
|
3
|
+
Reference for the `browser` skill. Read it when `new`/`goto` time out or are suddenly slow,
|
|
4
|
+
`eval` times out, a site seems to "block" you, `doctor` reports a renderer problem, a page
|
|
5
|
+
reads as a frozen shell, or before you even consider `launch --restart`. The hard rules are
|
|
6
|
+
in `SKILL.md`, under Gotchas; this is the evidence, the diagnosis and the recovery order.
|
|
7
|
+
|
|
8
|
+
- **A NEW tab's renderer can be slow rather than broken — do not restart Chrome for it.**
|
|
9
|
+
⚠️ **Read this before acting on the wedge diagnosis in the next item.** Measured 2026-09-11 on
|
|
10
|
+
Chrome 152.0.7977.83, time from `Target.createTarget` to the first `Runtime.evaluate`
|
|
11
|
+
returning, 8 trials each:
|
|
12
|
+
|
|
13
|
+
| how the target was created | median | worst |
|
|
14
|
+
|---|---|---|
|
|
15
|
+
| `background: true` (how this tool opens every tab) | 367ms | 12517ms, and >30s once |
|
|
16
|
+
| `background: true` + `Target.activateTarget` | 19ms | 65ms |
|
|
17
|
+
| `background: false` | 18ms | 22ms |
|
|
18
|
+
|
|
19
|
+
The renderer **process exists** in every arm — `ps` gains a `--type=renderer` child either
|
|
20
|
+
way. A background target is simply not given a renderer that answers promptly, and on a
|
|
21
|
+
loaded machine (this one was at load average 38) the tail runs past any budget worth
|
|
22
|
+
waiting. **This is not the wedge**, and a restart does nothing for it.
|
|
23
|
+
|
|
24
|
+
It cost real work to learn: for three weeks `goto` reported this as the permanent,
|
|
25
|
+
restart-only condition below, and `launch --restart` closes every tab of every session
|
|
26
|
+
sharing this Chrome. It twice destroyed unrecoverable work belonging to another session —
|
|
27
|
+
a finished AlternativeTo submission with hand edits, and an Azure signup flow mid-form.
|
|
28
|
+
|
|
29
|
+
**Since fixed (v0.4.12+):** `new`/`goto` wait for a late renderer and, if it still has not
|
|
30
|
+
answered, briefly activate the tab to force one and hand the window straight back (you get
|
|
31
|
+
a `WARN` saying so). The probe retries with a doubling budget, and the verdict now names
|
|
32
|
+
the permanent failure **only when its own signature is present**. On an older CLI, the
|
|
33
|
+
cheap move is to retry, or to drive a tab that already works.
|
|
34
|
+
|
|
35
|
+
**Whatever the version: before restarting anything, check the two corroborations.** Both
|
|
36
|
+
were decisive and neither used to be consulted:
|
|
37
|
+
```bash
|
|
38
|
+
launchctl print "gui/$(id -u)" | grep MachPortRendezvousServer.<browser-pid>
|
|
39
|
+
ps -Ao command= | grep -c -- '--type=renderer'
|
|
40
|
+
```
|
|
41
|
+
Mach name **present** + renderers **alive** ⇒ this is slowness, not the wedge. Retry, or use
|
|
42
|
+
a live tab. Mach name **absent** ⇒ it is the wedge, and only then is a restart the answer.
|
|
43
|
+
|
|
44
|
+
- **"The site is blocking us" — when it is really Chrome that cannot make renderers.**
|
|
45
|
+
A browser process can permanently lose the ability to launch **renderer processes** while
|
|
46
|
+
looking perfectly healthy. Every tab that already exists keeps working, so nothing seems wrong
|
|
47
|
+
until you open a tab or navigate somewhere new, and then the errors read as the remote site's
|
|
48
|
+
doing. Diagnosed 2026-08-22; it cost an hour of blaming ferry-operator bot protection.
|
|
49
|
+
⚠️ **This is a real condition and a rare one.** Confirm the Mach name is absent (above)
|
|
50
|
+
before you believe it — a slow background renderer produces every symptom in this list.
|
|
51
|
+
|
|
52
|
+
How it shows up:
|
|
53
|
+
- `browser-automation new` + `goto` → `CDP Page.enable timed out after 30000ms`, **even for
|
|
54
|
+
`example.com`**.
|
|
55
|
+
- **Cross-origin** navigation of an existing, working tab → `navigate failed: net::ERR_ABORTED`.
|
|
56
|
+
Site isolation puts a new origin in a new renderer — the exact thing Chrome can no longer do.
|
|
57
|
+
- **Same-origin** navigation on that same tab keeps working perfectly (Skyscanner → Skyscanner
|
|
58
|
+
with new query params was fine throughout). That asymmetry is what makes it masquerade as
|
|
59
|
+
"only site X blocks us": the tab you were already using still behaves.
|
|
60
|
+
- A target created at the browser level (`PUT /json/new?<url>`) appears in `/json/list` with the
|
|
61
|
+
right URL but an **empty title forever**; every `Runtime.evaluate` against it times out.
|
|
62
|
+
`Page.captureScreenshot` returns `Internal error`. The target shell exists; the renderer does not.
|
|
63
|
+
|
|
64
|
+
**It gets SLOW before it fails outright — that is the early warning.** Observed 2026-09-07 on a
|
|
65
|
+
Chrome that had been up 12 days: every `goto` took ~25–30s, and a batch of three blew a 120s
|
|
66
|
+
timeout, hours before anything failed hard. That was misread as "large files, slow browser" and
|
|
67
|
+
worked around with longer timeouts for many minutes; the actual fix was one `launch --restart`,
|
|
68
|
+
after which the same pages loaded instantly and 14 `file://` tabs opened in two quick batches.
|
|
69
|
+
**A `goto` that has quietly become slow is this, not your page.** Raise the timeout at most once,
|
|
70
|
+
then run `doctor`.
|
|
71
|
+
|
|
72
|
+
**Every cheap signal stays green, so do not take any of them as health.** On that same wedged
|
|
73
|
+
browser: `launch` said `Already running on :9223 — nothing to do.`, `curl :9223/json/version`
|
|
74
|
+
answered normally, and `list` cheerfully returned 10 targets — while `goto` exited 1 and `eval`
|
|
75
|
+
died with `CDP Runtime.evaluate timed out after 30000ms`. Port held, HTTP endpoint answering and
|
|
76
|
+
targets listed are all properties of the **browser** process; the thing that is broken is its
|
|
77
|
+
ability to start a **renderer**, and only a probe that runs code in one can see it.
|
|
78
|
+
**Since fixed:** `launch` now runs that probe itself and exits non-zero with the diagnosis
|
|
79
|
+
instead of reporting "nothing to do", so this particular green-across-the-board trap is closed.
|
|
80
|
+
It still will not restart for you — that stays something you type, because the tabs are not
|
|
81
|
+
only yours. On a CLI old enough to lack it, `doctor` is the same probe; nothing cheaper
|
|
82
|
+
substitutes for either.
|
|
83
|
+
|
|
84
|
+
**The mechanism** (macOS, from Chrome's own log at `$TMPDIR/chrome-<port>.log` — `launch --restart`
|
|
85
|
+
keeps the previous browser's log as `chrome-<port>.log.prev`, which is the one you want after a
|
|
86
|
+
restart):
|
|
87
|
+
```
|
|
88
|
+
ERROR:base/apple/mach_port_rendezvous_mac.cc:256]
|
|
89
|
+
bootstrap_look_up com.google.Chrome.MachPortRendezvousServer.<pid>: (ipc/send) invalid destination port
|
|
90
|
+
ERROR:base/memory/shared_memory_switch.cc:261]
|
|
91
|
+
No rendezvous client, terminating process (parent died?)
|
|
92
|
+
```
|
|
93
|
+
A Chrome child process gets its shared-memory handles by looking up a Mach bootstrap service the
|
|
94
|
+
browser registers **once, at startup**, named `com.google.Chrome.MachPortRendezvousServer.<browser-pid>`.
|
|
95
|
+
That registration had vanished from the user's launchd namespace — confirmed absent via
|
|
96
|
+
`launchctl print gui/$UID | grep MachPortRendezvousServer.<pid>`, while two healthy Chromes on the
|
|
97
|
+
same machine were both listed. From then on **every renderer Chrome launches kills itself within
|
|
98
|
+
milliseconds**, which is why none ever appears in `ps` and why the browser only reports
|
|
99
|
+
`Render process gone.` **What made the name vanish is not established.** Two things
|
|
100
|
+
correlated and neither is proven: the binary on disk had moved to 151.0.7922.170 while the live
|
|
101
|
+
browser was still running .138, and `GoogleUpdater` was FATAL-ing on its own `bootstrap_check_in`
|
|
102
|
+
with error 141. But the first renderer failure (18:53) *preceded* the first updater FATAL (19:42)
|
|
103
|
+
by ~50 minutes, so the update churn is at best a fellow symptom of a sick launchd bootstrap
|
|
104
|
+
namespace, not the cause. Treat the trigger as unknown; the diagnosis and the recovery do not
|
|
105
|
+
depend on it.
|
|
106
|
+
|
|
107
|
+
**It is NOT about how many tabs are open.** That was the first theory and it is wrong: a freshly
|
|
108
|
+
launched Chrome on the same machine was driven to **421 page targets / 435 live renderer
|
|
109
|
+
processes, every one responsive**, and a 256-fd `ulimit` made no difference either (205 renderers,
|
|
110
|
+
all fine). The broken browser had 66 tabs. The count was a coincidence — so do not treat a big
|
|
111
|
+
tab count as evidence of this, and do not expect closing tabs to fix it.
|
|
112
|
+
|
|
113
|
+
**Diagnose it:**
|
|
114
|
+
```bash
|
|
115
|
+
browser-automation doctor # measures renderer capacity, not just reachability
|
|
116
|
+
```
|
|
117
|
+
`doctor` now creates a throwaway tab, makes its renderer evaluate `1+1`, and closes it — the one
|
|
118
|
+
round-trip that separates a wedged browser from a slow network or a hostile site. On failure it
|
|
119
|
+
names the root cause (including the missing bootstrap service and the pid) and points at Chrome's
|
|
120
|
+
log. On a healthy browser it reports e.g. `✓ Renderer capacity: a new tab got a live renderer in
|
|
121
|
+
73ms`. `goto` and `new` run the same probe automatically **on the error path only**, so a bare
|
|
122
|
+
`Page.enable timed out` now arrives with the diagnosis attached instead of sending you to the
|
|
123
|
+
site's bot-protection docs.
|
|
124
|
+
|
|
125
|
+
**Recovery — cheapest first, and a restart only once the Mach name is confirmed absent.**
|
|
126
|
+
|
|
127
|
+
1. **Retry.** A new tab's renderer has been measured taking 12s and more on a loaded
|
|
128
|
+
machine, and late is not broken.
|
|
129
|
+
2. **Drive a tab that already works.** An existing tab navigates same-origin without
|
|
130
|
+
needing a new renderer, so it keeps working throughout even during a genuine wedge:
|
|
131
|
+
```bash
|
|
132
|
+
browser-automation list
|
|
133
|
+
browser-automation eval -t <id> "location.href='<url>'"
|
|
134
|
+
```
|
|
135
|
+
3. **`browser-automation doctor`** — re-measures, prints the two corroborations, and shows
|
|
136
|
+
the recent probe-time distribution from `~/.browser-automation/renderer-probes.jsonl`.
|
|
137
|
+
4. **Only if `doctor` reports the Mach rendezvous service ABSENT**, restart. The bootstrap
|
|
138
|
+
name is registered at startup and never re-registered, so nothing short of a new browser
|
|
139
|
+
process helps; closing tabs does not, and plain `launch` will not either (idempotent by
|
|
140
|
+
design — it sees a live browser and exits happy):
|
|
141
|
+
```bash
|
|
142
|
+
browser-automation launch --restart # quit (CDP, then SIGTERM), wait for the profile, relaunch
|
|
143
|
+
```
|
|
144
|
+
It reports how many tabs it is about to close. `Chrome released its profile but left its
|
|
145
|
+
process running (normal on macOS); ending it.` is the **expected** line, not a fault: on
|
|
146
|
+
macOS 27 / Chrome 153 the browser process never exits on its own after quitting, but it
|
|
147
|
+
does flush and release the profile first, and that release is what the restart waits for.
|
|
148
|
+
(Older CLIs waited only for the port to close and relaunched on top of the still-running
|
|
149
|
+
Chrome — two browsers on one profile. If you see `Chrome did not exit on SIGTERM`, or no
|
|
150
|
+
such line and then odd profile errors, you are on one of those.) **Those tabs belong to every parallel
|
|
151
|
+
Claude Code session sharing this Chrome — ask Fred first, never restart unilaterally.**
|
|
152
|
+
|
|
153
|
+
**Housekeeping is a different problem** — `browser-automation gc` prunes stale session bookmarks
|
|
154
|
+
(they are never cleaned up otherwise; this machine had accumulated 234, only 5 of them live) and
|
|
155
|
+
closes tabs whose renderer does not answer. Use `--dry` first. `list` now counts stale
|
|
156
|
+
bookmarks instead of printing them (`list --all` to see them) — 105 stale lines above a
|
|
157
|
+
24-tab Chrome is how "there are a hundred tabs open" became the leading theory for a
|
|
158
|
+
renderer failure that has nothing to do with tab count. It is genuinely useful, but it is
|
|
159
|
+
**not** a fix for the wedge above, and it never closes a working tab unless you pass `--orphans`
|
|
160
|
+
— tabs get addressed by `-m` and opened by hand, so "no session claims it" is not evidence that
|
|
161
|
+
nobody wants it.
|
|
162
|
+
|
|
163
|
+
**The false lead to resist:** a bare `curl` to a suspicious site may genuinely return a bot wall
|
|
164
|
+
(vikingline.fi serves an Imperva "Pardon Our Interruption" page, HTTP 200), which feels like
|
|
165
|
+
confirmation. It confirms nothing about the browser path — the persistent, cookie-bearing profile
|
|
166
|
+
is a completely different client. Check the browser first: if `doctor` says renderer capacity is
|
|
167
|
+
fine and a boring cross-origin URL loads, *then* start suspecting the site.
|
|
168
|
+
|
|
169
|
+
- **A backgrounded tab may never paint at all — and `read`/`snapshot` will not tell you.** Distinct
|
|
170
|
+
from "still loading": `document.readyState` reaches `complete`, but the SPA never renders, so
|
|
171
|
+
`read` returns a stale shell (e.g. a bare "Loading") and `snapshot` lists none of the real
|
|
172
|
+
controls. The trap is that this looks exactly like *the page does not have that element*, and you
|
|
173
|
+
will go hunting for a different selector or conclude the flow changed. Measured 2026-09-02 on
|
|
174
|
+
Google's `accounts.google.com/v3/signin/challenge/pwd`: `readyState: "complete"`,
|
|
175
|
+
`body.innerText.length: 202` frozen on the previous step's text, and the password field present in
|
|
176
|
+
the DOM but `offsetParent === null` for as long as the tab stayed backgrounded.
|
|
177
|
+
**Diagnose** before changing your selector:
|
|
178
|
+
```bash
|
|
179
|
+
browser-automation eval -s x '({ready:document.readyState,vis:document.visibilityState,len:document.body.innerText.length})'
|
|
180
|
+
```
|
|
181
|
+
`visibilityState: "hidden"` with a **stuck `len`** is this, not a selector problem. Note the
|
|
182
|
+
stuck `len` is the whole tell: `hidden` on its own is the normal, healthy state of every
|
|
183
|
+
backgrounded tab — verified 2026-09-07, a background tab reporting `hidden` returned its real
|
|
184
|
+
painted text — so never read `hidden` alone as a diagnosis.
|
|
185
|
+
**Fix:** make the tab report itself visible.
|
|
186
|
+
```bash
|
|
187
|
+
browser-automation focus -s x # quiet: no window moves, you keep your frontmost app
|
|
188
|
+
```
|
|
189
|
+
`focus` emulates focus + visibility in the renderer, then **reads back what it actually
|
|
190
|
+
achieved** rather than reporting that it sent the command — so a partial result says which half
|
|
191
|
+
is missing instead of printing a tick over it. The page paints immediately. Add `--raise` only
|
|
192
|
+
when a *person* needs to see the tab: that genuinely fronts it and **takes the operator's
|
|
193
|
+
screen**, which is exactly what you normally want to avoid.
|
|
194
|
+
Same root cause as the WebAuthn note in [`input-and-forms.md`](input-and-forms.md), different symptom: that one refuses, this one
|
|
195
|
+
silently never renders.
|
|
196
|
+
*(Older CLIs had no `focus`; the workaround was a `click --trusted` on a harmless wrapper `div`,
|
|
197
|
+
which fronted the tab as a side effect of needing trusted input. Prefer `focus` — it says what it
|
|
198
|
+
achieved, and it does not click anything.)*
|
|
199
|
+
|
|
200
|
+
**Do not confuse this with the renderer wedge (previous item).** Both present to an operator as "the page
|
|
201
|
+
isn't there, but every tool says fine", and the fixes are opposite — one is a per-tab nudge, the
|
|
202
|
+
other closes every tab in the browser. What separates them:
|
|
203
|
+
|
|
204
|
+
| | backgrounded tab never paints | Chrome cannot make renderers |
|
|
205
|
+
|---|---|---|
|
|
206
|
+
| `goto` | succeeds, rc=0 (may be slow) | **rc=1**, or `Page.enable timed out` |
|
|
207
|
+
| `eval` | works, returns a result | **`Runtime.evaluate` times out at 30000ms** |
|
|
208
|
+
| scope | that one tab | **every** new tab / cross-origin nav |
|
|
209
|
+
| `doctor` | `✓ Renderer capacity` | names the wedge + pid |
|
|
210
|
+
| fix | `focus` on the tab | `launch --restart` (**ask first**) |
|
|
211
|
+
|
|
212
|
+
`eval` is the fast discriminator: if it answers at all, the renderer is alive and you are in the
|
|
213
|
+
painting case. If it times out, stop poking the page and run `doctor`.
|