@generativereality/browser-automation 0.4.0 → 0.4.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/.claude-plugin/plugin.json +1 -1
- package/dist/index.js +133 -10
- package/package.json +1 -1
- package/skills/browser/SKILL.md +48 -6
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "browser-automation",
|
|
3
3
|
"description": "Daemonless, per-tab-isolated browser automation for Claude Code via the `browser-automation` CLI. Drives one shared headed Chrome (persistent profile + extensions) over per-target CDP — many parallel sessions, no focus stealing, nothing long-lived to crash.",
|
|
4
|
-
"version": "0.4.
|
|
4
|
+
"version": "0.4.1",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "generativereality"
|
|
7
7
|
},
|
package/dist/index.js
CHANGED
|
@@ -7,7 +7,7 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, s
|
|
|
7
7
|
import { spawnSync } from "node:child_process";
|
|
8
8
|
import { fileURLToPath } from "node:url";
|
|
9
9
|
//#region package.json
|
|
10
|
-
var version = "0.4.
|
|
10
|
+
var version = "0.4.1";
|
|
11
11
|
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.";
|
|
12
12
|
//#endregion
|
|
13
13
|
//#region src/core/session.ts
|
|
@@ -427,17 +427,37 @@ function __baText(root){
|
|
|
427
427
|
`;
|
|
428
428
|
const SNAPSHOT_EXPR = WALK + `(() => {
|
|
429
429
|
__baEachEl((el)=>{ if(el.getAttribute && el.getAttribute('data-ba-ref')) el.removeAttribute('data-ba-ref'); });
|
|
430
|
-
const
|
|
430
|
+
const ptr=(el)=>{try{return getComputedStyle(el).cursor==='pointer';}catch(e){return false;}};
|
|
431
|
+
// Interactive = semantic control, OR focusable (tabindex>=0), OR the OUTERMOST
|
|
432
|
+
// element in a cursor:pointer chain (catches React clickable <div>s without
|
|
433
|
+
// dragging in their pointer-inheriting children or huge containers).
|
|
434
|
+
const isInteractive=(el)=>{
|
|
435
|
+
try{ if(el.matches('a,button,input,select,textarea,summary,label,[role=button],[role=link],[role=tab],[role=checkbox],[role=radio],[role=option],[role=menuitem],[role=switch],[onclick],[contenteditable=""],[contenteditable=true]')) return true; }catch(e){}
|
|
436
|
+
const ti=el.getAttribute&&el.getAttribute('tabindex');
|
|
437
|
+
if(ti!=null&&parseInt(ti,10)>=0) return true;
|
|
438
|
+
if(ptr(el)){ const p=el.parentElement; if(!p||!ptr(p)) return true; }
|
|
439
|
+
return false;
|
|
440
|
+
};
|
|
441
|
+
const truthy=(v)=>v==='true';
|
|
442
|
+
const stateOf=(el)=>{
|
|
443
|
+
let checked=(el.tagName==='INPUT')?!!el.checked:false;
|
|
444
|
+
const inp=el.querySelector&&el.querySelector('input[type=checkbox],input[type=radio]');
|
|
445
|
+
if(inp&&inp.checked) checked=true;
|
|
446
|
+
if(truthy(el.getAttribute&&el.getAttribute('aria-checked'))||truthy(el.getAttribute&&el.getAttribute('aria-selected'))||truthy(el.getAttribute&&el.getAttribute('aria-pressed'))) checked=true;
|
|
447
|
+
const disabled=(el.disabled===true)||truthy(el.getAttribute&&el.getAttribute('aria-disabled'));
|
|
448
|
+
return [checked?'checked':'',disabled?'disabled':''].filter(Boolean).join(' ');
|
|
449
|
+
};
|
|
431
450
|
const out=[]; let i=1;
|
|
432
451
|
__baEachEl((el)=>{
|
|
452
|
+
if(out.length>=200) return;
|
|
433
453
|
if(!isInteractive(el)||!__baVisible(el))return;
|
|
434
454
|
const ref='e'+(i++);
|
|
435
455
|
el.setAttribute('data-ba-ref',ref);
|
|
436
456
|
const tag=el.tagName.toLowerCase();
|
|
437
457
|
const role=el.getAttribute('role')||tag;
|
|
438
458
|
const type=el.getAttribute('type')||'';
|
|
439
|
-
let name=(el.getAttribute('aria-label')||el.getAttribute('placeholder')||(el.value||'')||el.innerText||el.getAttribute('title')||el.getAttribute('name')||'').toString().trim().replace(/\\s+/g,' ').slice(0,80);
|
|
440
|
-
out.push({ref,role,tag,type,name});
|
|
459
|
+
let name=(el.getAttribute('aria-label')||el.getAttribute('placeholder')||(el.value||'')||el.innerText||el.textContent||el.getAttribute('title')||el.getAttribute('name')||'').toString().trim().replace(/\\s+/g,' ').slice(0,80);
|
|
460
|
+
out.push({ref,role,tag,type,name,state:stateOf(el)});
|
|
441
461
|
});
|
|
442
462
|
return {url:location.href,title:document.title,count:out.length,elements:out};
|
|
443
463
|
})()`;
|
|
@@ -481,6 +501,40 @@ function fillExpr(ref, value, submit) {
|
|
|
481
501
|
return {ok:true,value:el.value!==undefined?String(el.value).slice(0,80):${v}};
|
|
482
502
|
})()`;
|
|
483
503
|
}
|
|
504
|
+
/** Focus + scroll an element by ref and select-all its existing value. Used by
|
|
505
|
+
* `fill --native`: the actual character insertion is then driven via CDP
|
|
506
|
+
* Input.insertText, which fires trusted events that controlled React forms
|
|
507
|
+
* (RHF, Final Form, Formik Controller) actually subscribe to. */
|
|
508
|
+
function focusAndSelectExpr(ref) {
|
|
509
|
+
const r = JSON.stringify(ref);
|
|
510
|
+
return WALK + `(() => {
|
|
511
|
+
const el=__baFind(${r});
|
|
512
|
+
if(!el)return {err:'ref not found: '+${r}+' (re-run snapshot)'};
|
|
513
|
+
el.scrollIntoView({block:'center',inline:'center'});
|
|
514
|
+
el.focus();
|
|
515
|
+
try{ if(typeof el.select==='function') el.select(); }catch(e){}
|
|
516
|
+
return {ok:true,tag:el.tagName.toLowerCase(),len:el.value!==undefined?String(el.value).length:0};
|
|
517
|
+
})()`;
|
|
518
|
+
}
|
|
519
|
+
/** Re-read an input/textarea/contenteditable's effective value AND, when present,
|
|
520
|
+
* React's internal `_valueTracker.getValue()` — which is what React's onChange
|
|
521
|
+
* fires on. A divergence between the two is the canonical signature of
|
|
522
|
+
* "DOM value set but React form-state stayed stale" (the controlled-form
|
|
523
|
+
* stickiness gotcha — see SKILL.md). Also reports whether a React fiber is
|
|
524
|
+
* attached at all, so callers can tell "controlled component" from "plain DOM". */
|
|
525
|
+
function readValueAndTrackerExpr(ref) {
|
|
526
|
+
const r = JSON.stringify(ref);
|
|
527
|
+
return WALK + `(() => {
|
|
528
|
+
const el=__baFind(${r});
|
|
529
|
+
if(!el)return {err:'ref not found: '+${r}+' (re-run snapshot)'};
|
|
530
|
+
const value=el.value!==undefined?String(el.value):(el.isContentEditable?(el.textContent||''):'');
|
|
531
|
+
let trackerValue=null;
|
|
532
|
+
try{ const t=el._valueTracker; if(t&&typeof t.getValue==='function') trackerValue=String(t.getValue()); }catch(e){}
|
|
533
|
+
let hasReactFiber=false;
|
|
534
|
+
try{ hasReactFiber=Object.keys(el).some(k=>k.startsWith('__reactProps$')||k.startsWith('__reactFiber$')); }catch(e){}
|
|
535
|
+
return {value,trackerValue,hasReactFiber};
|
|
536
|
+
})()`;
|
|
537
|
+
}
|
|
484
538
|
function readExpr(selector) {
|
|
485
539
|
return WALK + `(() => { const r=${selector ? `__baQuery(${JSON.stringify(selector)})` : `document.body`}; return r ? __baText(r) : ${selector ? `'(no element matches ' + ${JSON.stringify(selector)} + ')'` : `''`}; })()`;
|
|
486
540
|
}
|
|
@@ -505,7 +559,8 @@ const snapshotCommand = define({
|
|
|
505
559
|
consola.log(`# ${snap.title}\n# ${snap.url}\n# ${snap.count} interactive elements`);
|
|
506
560
|
for (const el of snap.elements) {
|
|
507
561
|
const label = el.type ? `${el.role}[${el.type}]` : el.role;
|
|
508
|
-
|
|
562
|
+
const st = el.state ? `[${el.state}] ` : "";
|
|
563
|
+
consola.log(`${el.ref.padEnd(5)} ${label.padEnd(18)} ${st}${el.name}`);
|
|
509
564
|
}
|
|
510
565
|
}
|
|
511
566
|
});
|
|
@@ -537,6 +592,7 @@ const clickCommand = define({
|
|
|
537
592
|
});
|
|
538
593
|
//#endregion
|
|
539
594
|
//#region src/commands/fill.ts
|
|
595
|
+
const SELECT_ALL_MOD = process.platform === "darwin" ? 4 : 2;
|
|
540
596
|
const fillCommand = define({
|
|
541
597
|
name: "fill",
|
|
542
598
|
description: "Type a value into an input/textarea/contenteditable by ref",
|
|
@@ -546,6 +602,14 @@ const fillCommand = define({
|
|
|
546
602
|
type: "boolean",
|
|
547
603
|
description: "Submit the form after filling (requestSubmit / Enter)"
|
|
548
604
|
},
|
|
605
|
+
native: {
|
|
606
|
+
type: "boolean",
|
|
607
|
+
description: "Use CDP Input.insertText for trusted keyboard events. Slower than the default JS-dispatched path, but reaches controlled React forms (RHF / Final Form / Formik Controller) that ignore synthetic input events."
|
|
608
|
+
},
|
|
609
|
+
verify: {
|
|
610
|
+
type: "boolean",
|
|
611
|
+
description: "After filling, re-read the field and warn if its DOM value diverges from the value passed, or if React's internal _valueTracker still holds the old value (signals controlled-form state stickiness — the next submit will serialize stale data)."
|
|
612
|
+
},
|
|
549
613
|
ref: {
|
|
550
614
|
type: "positional",
|
|
551
615
|
description: "Element ref, e.g. e3"
|
|
@@ -566,12 +630,71 @@ const fillCommand = define({
|
|
|
566
630
|
consola.error("A value is required");
|
|
567
631
|
process.exit(1);
|
|
568
632
|
}
|
|
569
|
-
const
|
|
570
|
-
|
|
571
|
-
|
|
572
|
-
|
|
633
|
+
const targetId = await resolveExistingTargetId(targetOpts(ctx.values));
|
|
634
|
+
const native = ctx.values.native ?? false;
|
|
635
|
+
const submit = ctx.values.submit ?? false;
|
|
636
|
+
if (native) {
|
|
637
|
+
const focus = await evaluate(targetId, focusAndSelectExpr(ref));
|
|
638
|
+
if (focus.err) {
|
|
639
|
+
consola.error(focus.err);
|
|
640
|
+
process.exit(1);
|
|
641
|
+
}
|
|
642
|
+
await withPage(targetId, async (s) => {
|
|
643
|
+
await s.send("Input.dispatchKeyEvent", {
|
|
644
|
+
type: "rawKeyDown",
|
|
645
|
+
key: "a",
|
|
646
|
+
code: "KeyA",
|
|
647
|
+
windowsVirtualKeyCode: 65,
|
|
648
|
+
nativeVirtualKeyCode: 65,
|
|
649
|
+
modifiers: SELECT_ALL_MOD,
|
|
650
|
+
commands: ["selectAll"]
|
|
651
|
+
});
|
|
652
|
+
await s.send("Input.dispatchKeyEvent", {
|
|
653
|
+
type: "keyUp",
|
|
654
|
+
key: "a",
|
|
655
|
+
code: "KeyA",
|
|
656
|
+
windowsVirtualKeyCode: 65,
|
|
657
|
+
nativeVirtualKeyCode: 65,
|
|
658
|
+
modifiers: SELECT_ALL_MOD
|
|
659
|
+
});
|
|
660
|
+
await s.send("Input.insertText", { text: value });
|
|
661
|
+
if (submit) {
|
|
662
|
+
await s.send("Input.dispatchKeyEvent", {
|
|
663
|
+
type: "rawKeyDown",
|
|
664
|
+
key: "Enter",
|
|
665
|
+
code: "Enter",
|
|
666
|
+
windowsVirtualKeyCode: 13,
|
|
667
|
+
nativeVirtualKeyCode: 13
|
|
668
|
+
});
|
|
669
|
+
await s.send("Input.dispatchKeyEvent", {
|
|
670
|
+
type: "keyUp",
|
|
671
|
+
key: "Enter",
|
|
672
|
+
code: "Enter",
|
|
673
|
+
windowsVirtualKeyCode: 13,
|
|
674
|
+
nativeVirtualKeyCode: 13
|
|
675
|
+
});
|
|
676
|
+
}
|
|
677
|
+
});
|
|
678
|
+
} else {
|
|
679
|
+
const r = await evaluate(targetId, fillExpr(ref, value, submit));
|
|
680
|
+
if (r.err) {
|
|
681
|
+
consola.error(r.err);
|
|
682
|
+
process.exit(1);
|
|
683
|
+
}
|
|
684
|
+
}
|
|
685
|
+
if (ctx.values.verify) {
|
|
686
|
+
const v = await evaluate(targetId, readValueAndTrackerExpr(ref));
|
|
687
|
+
if (v.err) consola.warn(`verify failed to re-read field: ${v.err}`);
|
|
688
|
+
else {
|
|
689
|
+
const domMatches = v.value === value;
|
|
690
|
+
const trackerKnown = v.trackerValue !== null && v.trackerValue !== void 0;
|
|
691
|
+
const trackerMatches = !trackerKnown || v.trackerValue === value;
|
|
692
|
+
if (!domMatches) consola.warn(`verify: DOM value is "${v.value}" but you requested "${value}" — wrong element selected, or the page rewrote it.`);
|
|
693
|
+
else if (!trackerMatches) consola.warn(`verify: DOM shows "${value}" but React's _valueTracker still holds "${v.trackerValue}". The form library will likely submit the stale value. Try --native, or capture the form's PUT endpoint and call it directly (see SKILL.md "Controlled-form state stickiness").`);
|
|
694
|
+
else if (v.hasReactFiber && !trackerKnown && !native) consola.info(`verify: field has a React fiber but no _valueTracker — if the next submit serializes the old value, try --native.`);
|
|
695
|
+
}
|
|
573
696
|
}
|
|
574
|
-
consola.success(`filled ${ref} = "${
|
|
697
|
+
consola.success(`filled ${ref} = "${value}"${native ? " [native]" : ""}${submit ? " + submitted" : ""}`);
|
|
575
698
|
}
|
|
576
699
|
});
|
|
577
700
|
//#endregion
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@generativereality/browser-automation",
|
|
3
|
-
"version": "0.4.
|
|
3
|
+
"version": "0.4.1",
|
|
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": {
|
package/skills/browser/SKILL.md
CHANGED
|
@@ -132,8 +132,46 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
|
|
|
132
132
|
those refs for one action → re-snapshot. "ref not found" means re-snapshot.
|
|
133
133
|
- **`isTrusted` / synthetic events.** Clicks and fills are JS-dispatched, so a
|
|
134
134
|
small number of hard anti-bot or payment widgets that demand trusted events
|
|
135
|
-
may ignore them. For
|
|
136
|
-
|
|
135
|
+
may ignore them. For fills, pass `--native` to drive character insertion
|
|
136
|
+
through CDP `Input.insertText` instead — that fires real (trusted)
|
|
137
|
+
`beforeinput`/`input` events. For clicks, escalate to a foregrounded
|
|
138
|
+
native-input path or have the user do that one step manually.
|
|
139
|
+
- **Controlled-form state stickiness.** Form libraries that subscribe to React's
|
|
140
|
+
internal value-setter (React Hook Form, Final Form, Formik with a `Controller`,
|
|
141
|
+
Blocket/finn.no's `recommerce` editor) sometimes ignore the synthetic `input`
|
|
142
|
+
event the default `fill` dispatches: the DOM input shows the new value, but
|
|
143
|
+
the form's React state stays on the old one — and the next submit serializes
|
|
144
|
+
the *old* value. Two ways out:
|
|
145
|
+
1. **`fill --native --verify <ref> <value>`** — drives character insertion
|
|
146
|
+
through CDP `Input.insertText` (trusted events). `--verify` re-reads the
|
|
147
|
+
field afterwards and warns if either the DOM value diverged from what you
|
|
148
|
+
asked for, or if React's internal `_valueTracker` still holds the old
|
|
149
|
+
value (the canonical state-stickiness signature). Use this first; it
|
|
150
|
+
solves the vast majority of cases.
|
|
151
|
+
2. **API bypass** — when even `--native` doesn't stick (e.g. the form library
|
|
152
|
+
binds to an external state machine that drives its own POST/PUT), grab the
|
|
153
|
+
form's underlying endpoint and hit it directly:
|
|
154
|
+
```bash
|
|
155
|
+
# Hook fetch and persist a real form-submit's body + headers via localStorage
|
|
156
|
+
# (it survives the post-submit navigation, unlike window.* globals):
|
|
157
|
+
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);};})()"
|
|
158
|
+
# …then click Save once in the form so the hook captures the canonical PUT…
|
|
159
|
+
browser-automation eval -s app "({body:localStorage.getItem('__lastPut'),headers:localStorage.getItem('__lastHdrs')})"
|
|
160
|
+
# …gives you the endpoint, exact body shape, and custom headers
|
|
161
|
+
# (e.g. Blocket uses E-Tag, not the standard If-Match — and the etag lives
|
|
162
|
+
# in the JSON body, not the HTTP header).
|
|
163
|
+
```
|
|
164
|
+
Then re-fetch the GET endpoint for current data + the current etag, PUT
|
|
165
|
+
directly with the modified field(s) and the captured custom header, and
|
|
166
|
+
**drive the form's terminal commit step through the UI** — many two-step
|
|
167
|
+
editors (`edit → delivery → publish`) only persist `state: "edit"`
|
|
168
|
+
server-side until that final Save fires the commit.
|
|
169
|
+
|
|
170
|
+
Blocket's recommerce price field is the canonical case: default `fill e43 "500"`
|
|
171
|
+
shows 500 in the input but submits 750. Fix: `fill --native --verify e43 "500"`
|
|
172
|
+
(or, if --native doesn't stick: direct PUT to
|
|
173
|
+
`/recommerce/create/api/item/<id>` with `E-Tag: <body.etag>`, then click
|
|
174
|
+
Save on the delivery page to commit).
|
|
137
175
|
- **Cross-origin iframes are separate CDP targets.** `read`/`snapshot` see the
|
|
138
176
|
page's own document and same-origin frames, not cross-origin iframes (common
|
|
139
177
|
for SSO bank login widgets and embedded captchas). If the content you need
|
|
@@ -194,10 +232,14 @@ working around it forever**:
|
|
|
194
232
|
selection). Add a command by creating `src/commands/x.ts` and registering it
|
|
195
233
|
in `src/commands/index.ts`.
|
|
196
234
|
3. **Validate locally** against the running Chrome:
|
|
197
|
-
`npm install && npm run typecheck && npm run build`, then
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
235
|
+
`npm install && npm run typecheck && npm run build`, then run your build as
|
|
236
|
+
**`node dist/index.js <cmd>`** from the clone. **Do NOT `npm link`** — it
|
|
237
|
+
repoints the machine-global `browser-automation` bin, so a parallel Claude
|
|
238
|
+
Code session (or the user's main session) would suddenly be running *your*
|
|
239
|
+
work-in-progress clone instead of the installed release. Validate via the
|
|
240
|
+
explicit `node dist/index.js` path instead. Reproduce the failure, confirm
|
|
241
|
+
the fix, and re-test on a scratch tab you created (read-only-safe; never
|
|
242
|
+
disrupt the user's live tabs).
|
|
201
243
|
4. **Propose a PR** for the user to review and contribute upstream — don't
|
|
202
244
|
publish yourself (the maintainer cuts releases):
|
|
203
245
|
```bash
|