@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.
@@ -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.1",
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, not cross-origin iframes
117
- (each is its own CDP target).
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.1";
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
- /** Resolve to an EXISTING live tab. Never creates. For read/snapshot/click/fill/close. */
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 r = await evaluate(await resolveExistingTargetId(targetOpts(ctx.values)), clickExpr(ref));
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: { json: {
1006
- type: "boolean",
1007
- description: "Output raw JSON"
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.1",
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": {