@generativereality/browser-automation 0.4.2 → 0.4.4

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.2",
4
+ "version": "0.4.4",
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.2";
10
+ var version = "0.4.4";
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
@@ -447,10 +468,24 @@ const SNAPSHOT_EXPR = WALK + `(() => {
447
468
  const disabled=(el.disabled===true)||truthy(el.getAttribute&&el.getAttribute('aria-disabled'));
448
469
  return [checked?'checked':'',disabled?'disabled':''].filter(Boolean).join(' ');
449
470
  };
450
- const out=[]; let i=1;
471
+ // Open overlays (menus, dialogs, popovers, listboxes) are almost always WHAT
472
+ // the agent wants to act on next — but they're portal-rendered at the END of
473
+ // the DOM, so on a busy page their items fall past the element cap and vanish
474
+ // from the snapshot (e.g. a dropdown menu's items, a modal's buttons). Collect
475
+ // interactive elements in two buckets and emit OVERLAY ITEMS FIRST and uncapped,
476
+ // so an open menu/dialog is always addressable. Standard ARIA + native popover
477
+ // selectors keep this generic (no app-specific class names).
478
+ const OVERLAY='[role=dialog],[role=menu],[role=listbox],[role=menubar],[aria-modal=true],dialog[open]';
479
+ const inOverlay=(el)=>{ try{ if(el.closest&&el.closest(OVERLAY)) return true; }catch(e){} try{ if(el.matches&&el.matches(':popover-open,'+OVERLAY)) return true; }catch(e){} return false; };
480
+ const overlayEls=[], restEls=[];
451
481
  __baEachEl((el)=>{
452
- if(out.length>=200) return;
453
482
  if(!isInteractive(el)||!__baVisible(el))return;
483
+ (inOverlay(el)?overlayEls:restEls).push(el);
484
+ });
485
+ const CAP=200;
486
+ const chosen=overlayEls.concat(restEls.slice(0,Math.max(0,CAP-overlayEls.length)));
487
+ const out=[]; let i=1;
488
+ for(const el of chosen){
454
489
  const ref='e'+(i++);
455
490
  el.setAttribute('data-ba-ref',ref);
456
491
  const tag=el.tagName.toLowerCase();
@@ -458,8 +493,21 @@ const SNAPSHOT_EXPR = WALK + `(() => {
458
493
  const type=el.getAttribute('type')||'';
459
494
  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
495
  out.push({ref,role,tag,type,name,state:stateOf(el)});
461
- });
462
- return {url:location.href,title:document.title,count:out.length,elements:out};
496
+ }
497
+ // The open overlay's full text — so a caller can read a dialog's prompt
498
+ // (e.g. "send this invitation to <name>", an email-gate warning) WITHOUT a
499
+ // second round-trip. That matters for light-dismiss popovers, which close on
500
+ // the next stray interaction: getting refs + prompt text in one snapshot lets
501
+ // the caller verify and act before the overlay can vanish. Prefer a top-layer
502
+ // popover (always stacked on top); else the last-in-DOM ARIA overlay.
503
+ let overlayText='';
504
+ try{
505
+ const pops=[...document.querySelectorAll('[popover]')].filter(e=>{try{return e.matches(':popover-open')}catch(x){return false}});
506
+ const others=[...document.querySelectorAll(OVERLAY)].filter(e=>__baVisible(e));
507
+ const r=pops.length?pops[pops.length-1]:(others.length?others[others.length-1]:null);
508
+ if(r) overlayText=(r.innerText||'').replace(/\\s+/g,' ').trim().slice(0,600);
509
+ }catch(e){}
510
+ return {url:location.href,title:document.title,count:out.length,overlayCount:overlayEls.length,overlayText,elements:out};
463
511
  })()`;
464
512
  function clickExpr(ref) {
465
513
  const r = JSON.stringify(ref);
@@ -575,7 +623,9 @@ const snapshotCommand = define({
575
623
  process.stdout.write(JSON.stringify(snap, null, 2) + "\n");
576
624
  return;
577
625
  }
578
- consola.log(`# ${snap.title}\n# ${snap.url}\n# ${snap.count} interactive elements`);
626
+ const overlayNote = snap.overlayCount ? ` (${snap.overlayCount} in an open overlay, listed first)` : "";
627
+ consola.log(`# ${snap.title}\n# ${snap.url}\n# ${snap.count} interactive elements${overlayNote}`);
628
+ if (snap.overlayText) consola.log(`# overlay: ${snap.overlayText}`);
579
629
  for (const el of snap.elements) {
580
630
  const label = el.type ? `${el.role}[${el.type}]` : el.role;
581
631
  const st = el.state ? `[${el.state}] ` : "";
@@ -1111,18 +1161,26 @@ const screenshotCommand = define({
1111
1161
  //#region src/commands/list.ts
1112
1162
  const listCommand = define({
1113
1163
  name: "list",
1114
- description: "List sessions and every open tab (with targetId + title) so you can pick -m/-t",
1115
- args: { json: {
1116
- type: "boolean",
1117
- description: "Output raw JSON"
1118
- } },
1164
+ 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.",
1165
+ args: {
1166
+ json: {
1167
+ type: "boolean",
1168
+ description: "Output raw JSON"
1169
+ },
1170
+ frames: {
1171
+ type: "boolean",
1172
+ 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>."
1173
+ }
1174
+ },
1119
1175
  async run(ctx) {
1120
1176
  const sessions = listSessions();
1121
1177
  const targets = await listPageTargets().catch(() => []);
1178
+ const frames = ctx.values.frames ? (await listTargets().catch(() => [])).filter((t) => t.type === "iframe") : [];
1122
1179
  if (ctx.values.json) {
1123
1180
  process.stdout.write(JSON.stringify({
1124
1181
  sessions,
1125
- targets
1182
+ targets,
1183
+ ...ctx.values.frames ? { frames } : {}
1126
1184
  }, null, 2) + "\n");
1127
1185
  return;
1128
1186
  }
@@ -1138,6 +1196,14 @@ const listCommand = define({
1138
1196
  const title = (t.title ?? "").replace(/\s+/g, " ").slice(0, 28);
1139
1197
  consola.log(` ${t.id.slice(0, 12)} ${owner ? `(${owner.name}) ` : ""}${title.padEnd(28)} ${(t.url ?? "").slice(0, 70)}`);
1140
1198
  }
1199
+ if (ctx.values.frames) {
1200
+ consola.log("");
1201
+ consola.log(`# cross-origin iframes (${frames.length}) — address with -F <substr> or -t <id>`);
1202
+ for (const f of frames) {
1203
+ const title = (f.title ?? "").replace(/\s+/g, " ").slice(0, 28);
1204
+ consola.log(` ${f.id.slice(0, 12)} ${title.padEnd(28)} ${(f.url ?? "").slice(0, 70)}`);
1205
+ }
1206
+ }
1141
1207
  }
1142
1208
  });
1143
1209
  //#endregion
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@generativereality/browser-automation",
3
- "version": "0.4.2",
3
+ "version": "0.4.4",
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": {