@generativereality/browser-automation 0.4.1 → 0.4.3
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/README.md +12 -2
- package/dist/index.js +158 -11
- package/package.json +1 -1
|
@@ -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.3",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "generativereality"
|
|
7
7
|
},
|
package/README.md
CHANGED
|
@@ -64,6 +64,15 @@ Page commands pick a tab with a selector (precedence `-t` > `-m` > `-s`):
|
|
|
64
64
|
- `-t <targetId>` — an exact tab (from `list`).
|
|
65
65
|
- `-s <name>` — a saved **session** bookmark (default `$BAC_SESSION`, else `default`).
|
|
66
66
|
|
|
67
|
+
A fourth selector, `-F <substr>`, is orthogonal — it descends **into** a tab,
|
|
68
|
+
to a **cross-origin child iframe** (OOPIF) whose URL/title contains the
|
|
69
|
+
substring (e.g. `-F js.stripe.com` to fill Stripe Elements). OOPIFs are
|
|
70
|
+
first-class CDP targets, so every page command (`snapshot`/`click`/`fill`/
|
|
71
|
+
`read`/`eval`) works inside them. Same-origin iframes aren't separate targets —
|
|
72
|
+
they're already reachable from the parent page, no `-F`. Discover frames with
|
|
73
|
+
`list --frames`; an ambiguous `-F` errors (narrow it, use `-t <iframeTargetId>`,
|
|
74
|
+
or `--first`).
|
|
75
|
+
|
|
67
76
|
Sessions are optional bookmarks, not locks — there's no one-session-one-tab rule.
|
|
68
77
|
|
|
69
78
|
```bash
|
|
@@ -113,8 +122,9 @@ same one-action-per-snapshot rule as Playwright refs.
|
|
|
113
122
|
`input`/`change`), which works on background tabs (native CDP mouse events do
|
|
114
123
|
not reliably reach a non-foreground tab in headed Chrome). Synthetic events are
|
|
115
124
|
not `isTrusted`, so a few hard anti-bot/payment flows may reject them.
|
|
116
|
-
- `read`/`snapshot` see the page + same-origin frames
|
|
117
|
-
|
|
125
|
+
- `read`/`snapshot` see the page + same-origin frames. A **cross-origin iframe**
|
|
126
|
+
is its own CDP target — reach it with `-F <substr>` (or `-t <iframeTargetId>`
|
|
127
|
+
from `list --frames`); every page command then runs inside that frame.
|
|
118
128
|
- `launch` resolves Chrome on macOS/Linux; elsewhere start Chrome manually with
|
|
119
129
|
`--remote-debugging-port=9223 --user-data-dir="<profile>"`.
|
|
120
130
|
|
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.3";
|
|
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
|
|
@@ -306,8 +306,23 @@ async function matchOne(match, first) {
|
|
|
306
306
|
if (hits.length > 1 && !first) throw new Error(`"${match}" matches ${hits.length} tabs — narrow it or pass --first:\n` + hits.map((h) => ` ${(h.title ?? "").slice(0, 30)} ${h.url}`).join("\n"));
|
|
307
307
|
return hits[0];
|
|
308
308
|
}
|
|
309
|
-
/**
|
|
309
|
+
/** Match a CROSS-ORIGIN child iframe (OOPIF) by URL/title substring. Out-of-process
|
|
310
|
+
* iframes are first-class CDP targets (type === 'iframe') with their own
|
|
311
|
+
* webSocketDebuggerUrl, so once resolved every page command drives them exactly
|
|
312
|
+
* like a tab. (Same-origin iframes share the parent's target and never appear
|
|
313
|
+
* here — they're already reachable from the parent page.) */
|
|
314
|
+
async function matchIframe(match, first) {
|
|
315
|
+
const frames = (await listTargets()).filter((t) => t.type === "iframe");
|
|
316
|
+
const m = match.toLowerCase();
|
|
317
|
+
const hits = frames.filter((f) => (f.url ?? "").toLowerCase().includes(m) || (f.title ?? "").toLowerCase().includes(m));
|
|
318
|
+
if (hits.length === 0) throw new Error(`no cross-origin iframe matches "${match}" — run \`browser-automation list --frames\` to see them. (Same-origin iframes aren't separate targets; reach them from the parent page without -F.)`);
|
|
319
|
+
if (hits.length > 1 && !first) throw new Error(`-F "${match}" matches ${hits.length} iframes — narrow it, address one exactly with \`-t <iframeTargetId>\` (from \`list --frames\`), or pass --first:\n` + hits.map((h) => ` ${h.id.slice(0, 12)} ${(h.url ?? "").slice(0, 70)}`).join("\n"));
|
|
320
|
+
return hits[0];
|
|
321
|
+
}
|
|
322
|
+
/** Resolve to an EXISTING live tab — or, with `-F`, a cross-origin child iframe
|
|
323
|
+
* of one. Never creates. For read/snapshot/click/fill/eval/close. */
|
|
310
324
|
async function resolveExistingTargetId(opts) {
|
|
325
|
+
if (opts.frame) return (await matchIframe(opts.frame, opts.first)).id;
|
|
311
326
|
if (opts.target) return resolveTargetIdArg(opts.target);
|
|
312
327
|
if (opts.match) return (await matchOne(opts.match, opts.first)).id;
|
|
313
328
|
const name = opts.session || defaultSessionName();
|
|
@@ -345,7 +360,12 @@ const targetArgs = {
|
|
|
345
360
|
},
|
|
346
361
|
first: {
|
|
347
362
|
type: "boolean",
|
|
348
|
-
description: "If --match is ambiguous, use the first match instead of erroring"
|
|
363
|
+
description: "If --match (or --frame) is ambiguous, use the first match instead of erroring"
|
|
364
|
+
},
|
|
365
|
+
frame: {
|
|
366
|
+
type: "string",
|
|
367
|
+
short: "F",
|
|
368
|
+
description: "Descend into a CROSS-ORIGIN child iframe (OOPIF) whose URL or title contains this substring, and run the command against that frame instead of the page (e.g. -F js.stripe.com to fill Stripe Elements). Out-of-process iframes are first-class CDP targets, so snapshot/click/fill/read/eval all work inside them. Same-origin iframes are NOT separate targets — already reachable from the parent page, no -F needed. Discover frames with `list --frames`. An ambiguous substring errors (use a more distinctive substring, an exact `-t <iframeTargetId>`, or --first)."
|
|
349
369
|
}
|
|
350
370
|
};
|
|
351
371
|
function targetOpts(values) {
|
|
@@ -353,7 +373,8 @@ function targetOpts(values) {
|
|
|
353
373
|
session: values.session,
|
|
354
374
|
match: values.match,
|
|
355
375
|
target: values.target,
|
|
356
|
-
first: values.first
|
|
376
|
+
first: values.first,
|
|
377
|
+
frame: values.frame
|
|
357
378
|
};
|
|
358
379
|
}
|
|
359
380
|
//#endregion
|
|
@@ -471,6 +492,25 @@ function clickExpr(ref) {
|
|
|
471
492
|
return {ok:true,tag:el.tagName.toLowerCase()};
|
|
472
493
|
})()`;
|
|
473
494
|
}
|
|
495
|
+
function actionabilityExpr(ref) {
|
|
496
|
+
const r = JSON.stringify(ref);
|
|
497
|
+
return WALK + `(() => {
|
|
498
|
+
const el=__baFind(${r});
|
|
499
|
+
if(!el)return {err:'ref not found: '+${r}+' (re-run snapshot)'};
|
|
500
|
+
el.scrollIntoView({block:'center',inline:'center'});
|
|
501
|
+
const b=el.getBoundingClientRect();
|
|
502
|
+
if(b.width===0&&b.height===0)return {err:'ref '+${r}+' has zero size / not visible'};
|
|
503
|
+
const vw=innerWidth,vh=innerHeight;
|
|
504
|
+
const x=Math.min(Math.max(b.left+b.width/2,1),vw-1);
|
|
505
|
+
const y=Math.min(Math.max(b.top+b.height/2,1),vh-1);
|
|
506
|
+
const root=el.getRootNode();
|
|
507
|
+
let top=(root&&root.elementFromPoint?root:document).elementFromPoint(x,y);
|
|
508
|
+
// descend through any shadow root under the point to find the deepest target
|
|
509
|
+
while(top&&top.shadowRoot){const inner=top.shadowRoot.elementFromPoint(x,y);if(!inner||inner===top)break;top=inner;}
|
|
510
|
+
const hit=!!top&&(top===el||el.contains(top)||(top.contains&&top.contains(el)));
|
|
511
|
+
return {ok:true,tag:el.tagName.toLowerCase(),x,y,hit};
|
|
512
|
+
})()`;
|
|
513
|
+
}
|
|
474
514
|
function fillExpr(ref, value, submit) {
|
|
475
515
|
const r = JSON.stringify(ref);
|
|
476
516
|
const v = JSON.stringify(value);
|
|
@@ -566,6 +606,7 @@ const snapshotCommand = define({
|
|
|
566
606
|
});
|
|
567
607
|
//#endregion
|
|
568
608
|
//#region src/commands/click.ts
|
|
609
|
+
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
|
|
569
610
|
const clickCommand = define({
|
|
570
611
|
name: "click",
|
|
571
612
|
description: "Click an element by ref (from the latest snapshot)",
|
|
@@ -574,6 +615,10 @@ const clickCommand = define({
|
|
|
574
615
|
ref: {
|
|
575
616
|
type: "positional",
|
|
576
617
|
description: "Element ref, e.g. e7"
|
|
618
|
+
},
|
|
619
|
+
trusted: {
|
|
620
|
+
type: "boolean",
|
|
621
|
+
description: "Dispatch a real, genuinely-trusted CDP mouse click (Input.dispatchMouseEvent) at the element instead of the default JS-dispatched el.click(). Brings the tab to front and WAITS for it to be focused+visible (CDP input no-ops on a backgrounded tab), then waits for the element to be actionable (stable position + unoccluded hit-test) before pressing — mirroring Playwright. Use for widgets that demand isTrusted events AND animate in: artdeco dropdown menu items (LinkedIn More→Connect), Radix dropdown/popover triggers, cmdk comboboxes — which a default click, or an immediate trusted click on stale coordinates, only highlights without firing."
|
|
577
622
|
}
|
|
578
623
|
},
|
|
579
624
|
async run(ctx) {
|
|
@@ -582,7 +627,93 @@ const clickCommand = define({
|
|
|
582
627
|
consola.error("A ref like \"e7\" is required (run `browser-automation snapshot` first)");
|
|
583
628
|
process.exit(1);
|
|
584
629
|
}
|
|
585
|
-
const
|
|
630
|
+
const targetId = await resolveExistingTargetId(targetOpts(ctx.values));
|
|
631
|
+
if (ctx.values.trusted ?? false) {
|
|
632
|
+
const trustedTag = await withPage(targetId, async (s) => {
|
|
633
|
+
const evalIn = async (expr) => {
|
|
634
|
+
const res = await s.send("Runtime.evaluate", {
|
|
635
|
+
expression: expr,
|
|
636
|
+
returnByValue: true,
|
|
637
|
+
awaitPromise: true
|
|
638
|
+
});
|
|
639
|
+
if (res.exceptionDetails) {
|
|
640
|
+
const e = res.exceptionDetails;
|
|
641
|
+
throw new Error("page JS exception: " + (e.exception?.description || e.text || "unknown"));
|
|
642
|
+
}
|
|
643
|
+
return res.result?.value;
|
|
644
|
+
};
|
|
645
|
+
await s.send("Page.bringToFront").catch(() => {});
|
|
646
|
+
const focusDeadline = Date.now() + 2e3;
|
|
647
|
+
while (Date.now() < focusDeadline) {
|
|
648
|
+
const f = await evalIn(`({f:document.hasFocus(),v:document.visibilityState})`);
|
|
649
|
+
if (f && f.f && f.v === "visible") break;
|
|
650
|
+
await sleep(50);
|
|
651
|
+
}
|
|
652
|
+
let prev = null;
|
|
653
|
+
let point = null;
|
|
654
|
+
let lastReason = "never became actionable";
|
|
655
|
+
const actDeadline = Date.now() + 5e3;
|
|
656
|
+
while (Date.now() < actDeadline) {
|
|
657
|
+
const a = await evalIn(actionabilityExpr(ref));
|
|
658
|
+
if (a?.err) {
|
|
659
|
+
consola.error(a.err);
|
|
660
|
+
process.exit(1);
|
|
661
|
+
}
|
|
662
|
+
const stable = prev !== null && Math.abs(prev.x - a.x) < .5 && Math.abs(prev.y - a.y) < .5;
|
|
663
|
+
if (a.hit && stable) {
|
|
664
|
+
point = {
|
|
665
|
+
x: a.x,
|
|
666
|
+
y: a.y,
|
|
667
|
+
tag: a.tag
|
|
668
|
+
};
|
|
669
|
+
break;
|
|
670
|
+
}
|
|
671
|
+
lastReason = a.hit ? "position not yet stable (still animating)" : "click-point occluded (hit-test miss)";
|
|
672
|
+
prev = {
|
|
673
|
+
x: a.x,
|
|
674
|
+
y: a.y
|
|
675
|
+
};
|
|
676
|
+
await sleep(60);
|
|
677
|
+
}
|
|
678
|
+
if (!point) {
|
|
679
|
+
consola.error(`<${ref}> not actionable for a trusted click: ${lastReason}`);
|
|
680
|
+
process.exit(1);
|
|
681
|
+
}
|
|
682
|
+
const { x, y } = point;
|
|
683
|
+
await s.send("Input.dispatchMouseEvent", {
|
|
684
|
+
type: "mouseMoved",
|
|
685
|
+
x,
|
|
686
|
+
y,
|
|
687
|
+
button: "none",
|
|
688
|
+
buttons: 0,
|
|
689
|
+
pointerType: "mouse"
|
|
690
|
+
});
|
|
691
|
+
await sleep(20);
|
|
692
|
+
await s.send("Input.dispatchMouseEvent", {
|
|
693
|
+
type: "mousePressed",
|
|
694
|
+
x,
|
|
695
|
+
y,
|
|
696
|
+
button: "left",
|
|
697
|
+
buttons: 1,
|
|
698
|
+
clickCount: 1,
|
|
699
|
+
pointerType: "mouse",
|
|
700
|
+
force: .5
|
|
701
|
+
});
|
|
702
|
+
await s.send("Input.dispatchMouseEvent", {
|
|
703
|
+
type: "mouseReleased",
|
|
704
|
+
x,
|
|
705
|
+
y,
|
|
706
|
+
button: "left",
|
|
707
|
+
buttons: 0,
|
|
708
|
+
clickCount: 1,
|
|
709
|
+
pointerType: "mouse"
|
|
710
|
+
});
|
|
711
|
+
return point.tag;
|
|
712
|
+
});
|
|
713
|
+
consola.success(`clicked ${ref} <${trustedTag}> (trusted)`);
|
|
714
|
+
return;
|
|
715
|
+
}
|
|
716
|
+
const r = await evaluate(targetId, clickExpr(ref));
|
|
586
717
|
if (r.err) {
|
|
587
718
|
consola.error(r.err);
|
|
588
719
|
process.exit(1);
|
|
@@ -1001,18 +1132,26 @@ const screenshotCommand = define({
|
|
|
1001
1132
|
//#region src/commands/list.ts
|
|
1002
1133
|
const listCommand = define({
|
|
1003
1134
|
name: "list",
|
|
1004
|
-
description: "List sessions and every open tab (with targetId + title) so you can pick -m/-t",
|
|
1005
|
-
args: {
|
|
1006
|
-
|
|
1007
|
-
|
|
1008
|
-
|
|
1135
|
+
description: "List sessions and every open tab (with targetId + title) so you can pick -m/-t. Add --frames to also list cross-origin child iframes (OOPIFs) addressable with -F/-t.",
|
|
1136
|
+
args: {
|
|
1137
|
+
json: {
|
|
1138
|
+
type: "boolean",
|
|
1139
|
+
description: "Output raw JSON"
|
|
1140
|
+
},
|
|
1141
|
+
frames: {
|
|
1142
|
+
type: "boolean",
|
|
1143
|
+
description: "Also list cross-origin child iframes (OOPIFs) — their targetIds/URLs let you drive Stripe Elements, embedded SSO widgets, etc. via -F <substr> or -t <id>."
|
|
1144
|
+
}
|
|
1145
|
+
},
|
|
1009
1146
|
async run(ctx) {
|
|
1010
1147
|
const sessions = listSessions();
|
|
1011
1148
|
const targets = await listPageTargets().catch(() => []);
|
|
1149
|
+
const frames = ctx.values.frames ? (await listTargets().catch(() => [])).filter((t) => t.type === "iframe") : [];
|
|
1012
1150
|
if (ctx.values.json) {
|
|
1013
1151
|
process.stdout.write(JSON.stringify({
|
|
1014
1152
|
sessions,
|
|
1015
|
-
targets
|
|
1153
|
+
targets,
|
|
1154
|
+
...ctx.values.frames ? { frames } : {}
|
|
1016
1155
|
}, null, 2) + "\n");
|
|
1017
1156
|
return;
|
|
1018
1157
|
}
|
|
@@ -1028,6 +1167,14 @@ const listCommand = define({
|
|
|
1028
1167
|
const title = (t.title ?? "").replace(/\s+/g, " ").slice(0, 28);
|
|
1029
1168
|
consola.log(` ${t.id.slice(0, 12)} ${owner ? `(${owner.name}) ` : ""}${title.padEnd(28)} ${(t.url ?? "").slice(0, 70)}`);
|
|
1030
1169
|
}
|
|
1170
|
+
if (ctx.values.frames) {
|
|
1171
|
+
consola.log("");
|
|
1172
|
+
consola.log(`# cross-origin iframes (${frames.length}) — address with -F <substr> or -t <id>`);
|
|
1173
|
+
for (const f of frames) {
|
|
1174
|
+
const title = (f.title ?? "").replace(/\s+/g, " ").slice(0, 28);
|
|
1175
|
+
consola.log(` ${f.id.slice(0, 12)} ${title.padEnd(28)} ${(f.url ?? "").slice(0, 70)}`);
|
|
1176
|
+
}
|
|
1177
|
+
}
|
|
1031
1178
|
}
|
|
1032
1179
|
});
|
|
1033
1180
|
//#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.3",
|
|
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": {
|