@generativereality/browser-automation 0.4.4 → 0.4.6

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.4",
4
+ "version": "0.4.6",
5
5
  "author": {
6
6
  "name": "generativereality"
7
7
  },
package/README.md CHANGED
@@ -104,6 +104,9 @@ browser-automation bind -s bank -m nordnet # …or adopt it into a session
104
104
  | `read (-s\|-m\|-t) [selector]` | Print page text (or a CSS selector's text) |
105
105
  | `eval (-s\|-m\|-t) <js>` | Evaluate a JS expression in the tab (escape hatch) |
106
106
  | `download (-s\|-m\|-t) (--click <ref>\|--url <href>)` | Capture a file/CSV download, wait for completion, print the path |
107
+ | `setfiles (-s\|-m\|-t) <ref> <path…>` | Set files on a known `<input type=file>` by ref (fires input/change) |
108
+ | `upload (-s\|-m\|-t) --click <ref> <path…>` | Upload via a button that opens a file chooser (transient/custom inputs) |
109
+ | `drop (-s\|-m\|-t) [--js] <ref> <path…>` | Drop file(s) onto a drag-and-drop zone by ref (trusted CDP drag by default; `--js` for a synthetic drop) |
107
110
  | `network (-s\|-m\|-t) [--reload\|--click\|--nav] [--filter --headers --body]` | Capture network requests (find the API, headers, response bodies) |
108
111
  | `screenshot (-s\|-m\|-t) [--full] [-o path]` | Save a PNG screenshot (viewport or full page) |
109
112
  | `close (-s\|-m\|-t) [--tab]` | Forget the session (tab stays open); `--tab` also closes the browser tab |
@@ -125,6 +128,35 @@ same one-action-per-snapshot rule as Playwright refs.
125
128
  - `read`/`snapshot` see the page + same-origin frames. A **cross-origin iframe**
126
129
  is its own CDP target — reach it with `-F <substr>` (or `-t <iframeTargetId>`
127
130
  from `list --frames`); every page command then runs inside that frame.
131
+ - **File upload** has two entry points (Playwright's two paths). For a static
132
+ `<input type=file>` you can snapshot, use `setfiles <ref> <path…>`. For a custom
133
+ "attach" button that opens a native file chooser — and reads a *transient* input
134
+ that only exists during the chooser (App Store Connect's "Attach File", many
135
+ React dropzones) — use `upload --click <ref> <path…>`: it intercepts the chooser
136
+ and sets files on whatever input Chrome opens. Setting the static input via JS
137
+ won't work there; the button uses its own throwaway input. `upload` judges
138
+ success by the `change` event (reports "delivered"), since apps reset the input
139
+ to 0 after consuming the file — so `files=0` afterward is normal. **Verify by
140
+ re-snapshot/screenshot and don't blindly retry:** the file may stage as a row in
141
+ an attachment *list* (not a single chip), and each successful run adds another
142
+ attachment, so retrying can silently create duplicates.
143
+ - **Drag-and-drop upload** is a third path, for zones with no `<input type=file>`
144
+ at all — a `drop` listener reading `e.dataTransfer.files` (vocalremover-style
145
+ audio tools, many image/video drop zones). `drop <ref> <path…>` fires a
146
+ genuinely-**trusted** CDP drag (`Input.dispatchDragEvent`) carrying the real
147
+ files from disk: it force-fronts the tab (bringToFront + focus emulation +
148
+ active lifecycle, so the renderer reports focused+visible even when the Chrome
149
+ window is occluded), waits for the zone to be actionable, then
150
+ dragEnter→dragOver→drop — same discipline as `click --trusted`. The force-front
151
+ matters because drop-zone uploaders often act only inside a **user activation**,
152
+ which CDP input can't grant on a tab the renderer considers `hidden`
153
+ (vocalremover.org is the canonical case). `--js` instead dispatches a synthetic
154
+ (isTrusted=false) `DataTransfer` drop without force-fronting/stealing focus, for
155
+ zones that accept synthetic events. The `<ref>` is any snapshot element over the
156
+ drop region — the drop bubbles to the zone/document handler, so a heading or
157
+ button inside the zone works even when the zone div itself isn't
158
+ snapshot-interactive. After dropping, confirm with `read`/`screenshot` and pull
159
+ the result (often a `download --url` endpoint).
128
160
  - `launch` resolves Chrome on macOS/Linux; elsewhere start Chrome manually with
129
161
  `--remote-debugging-port=9223 --user-data-dir="<profile>"`.
130
162
 
package/dist/index.js CHANGED
@@ -2,12 +2,12 @@
2
2
  import { cli, define } from "gunshi";
3
3
  import { consola } from "consola";
4
4
  import { homedir } from "node:os";
5
- import { dirname, join } from "node:path";
5
+ import { basename, dirname, extname, join, resolve } from "node:path";
6
6
  import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
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.4";
10
+ var version = "0.4.6";
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
@@ -150,6 +150,27 @@ async function withPage(targetId, fn) {
150
150
  s.close();
151
151
  }
152
152
  }
153
+ /** Make a page target behave as the foreground tab for trusted CDP input,
154
+ * WITHOUT stealing OS focus from the user's other apps.
155
+ *
156
+ * CDP `Input.*` events (and the user-activation they grant) are dropped by the
157
+ * renderer when the tab's `visibilityState` is `hidden` — which it is whenever
158
+ * the automation Chrome window isn't the frontmost OS window (the normal case:
159
+ * the user is in their terminal). `Page.bringToFront` alone does NOT fix this;
160
+ * the tab still reports `hidden`. `Emulation.setFocusEmulationEnabled` forces
161
+ * the renderer to treat itself as focused+visible regardless of the real window
162
+ * state (this is how Playwright drives backgrounded/headless pages), and
163
+ * `Page.setWebLifecycleState: active` un-throttles a frozen tab. Together they
164
+ * flip `document.hasFocus()`+`visibilityState:visible` on, so a trusted click /
165
+ * drag actually lands and grants user activation — which activation-gated flows
166
+ * (e.g. drop-zone uploaders that only start work inside a user gesture) require.
167
+ *
168
+ * All three are best-effort: older Chrome builds may not expose every command. */
169
+ async function forceForeground(s) {
170
+ await s.send("Page.bringToFront").catch(() => {});
171
+ await s.send("Emulation.setFocusEmulationEnabled", { enabled: true }).catch(() => {});
172
+ await s.send("Page.setWebLifecycleState", { state: "active" }).catch(() => {});
173
+ }
153
174
  /** Run `fn` against the browser-level endpoint (Target.* commands), then close. */
154
175
  async function withBrowser(fn) {
155
176
  const s = await connect(await browserWsUrl());
@@ -579,7 +600,19 @@ function focusAndSelectExpr(ref) {
579
600
  if(!el)return {err:'ref not found: '+${r}+' (re-run snapshot)'};
580
601
  el.scrollIntoView({block:'center',inline:'center'});
581
602
  el.focus();
582
- try{ if(typeof el.select==='function') el.select(); }catch(e){}
603
+ // Select-all in JS so the subsequent Input.insertText REPLACES the field
604
+ // rather than appending. Doing this here (not via a synthetic Cmd+A key
605
+ // chord) keeps the trusted-fill path from ever dispatching a Meta-modified
606
+ // key event — an unhandled one of those leaks to the macOS main menu and
607
+ // pops system UI (e.g. "About This Mac"). Inputs/textareas: .select();
608
+ // contenteditable: the Selection API.
609
+ try{
610
+ if(typeof el.select==='function') el.select();
611
+ else if(el.isContentEditable){
612
+ const range=document.createRange();range.selectNodeContents(el);
613
+ const sel=window.getSelection();sel.removeAllRanges();sel.addRange(range);
614
+ }
615
+ }catch(e){}
583
616
  return {ok:true,tag:el.tagName.toLowerCase(),len:el.value!==undefined?String(el.value).length:0};
584
617
  })()`;
585
618
  }
@@ -602,6 +635,44 @@ function readValueAndTrackerExpr(ref) {
602
635
  return {value,trackerValue,hasReactFiber};
603
636
  })()`;
604
637
  }
638
+ /** Return the live element for a ref as an OBJECT (evaluate with
639
+ * returnByValue:false) so the caller gets a Runtime RemoteObject `objectId`,
640
+ * which `DOM.setFileInputFiles` accepts directly. Resolves through shadow DOM
641
+ * and same-origin iframes like every other ref op. Yields `null` (subtype
642
+ * 'null', no objectId) when the ref is stale. */
643
+ function findRefExpr(ref) {
644
+ return WALK + `(() => __baFind(${JSON.stringify(ref)}))()`;
645
+ }
646
+ /** JS-dispatched drag-and-drop of injected files onto an element by ref. Builds
647
+ * real File objects from base64 bytes, assembles a DataTransfer, and fires the
648
+ * full dragenter→dragover→drop sequence (each carrying dataTransfer.files) so
649
+ * drop-zone handlers that read `e.dataTransfer.files` fire. The events are
650
+ * synthetic (isTrusted=false) — drop zones that gate on isTrusted need the
651
+ * trusted CDP path (`drop` without --js) instead. `files` is [{name,type,b64}]. */
652
+ function dropExpr(ref, files) {
653
+ const r = JSON.stringify(ref);
654
+ return WALK + `(() => {
655
+ const el=__baFind(${r});
656
+ if(!el)return {err:'ref not found: '+${r}+' (re-run snapshot)'};
657
+ el.scrollIntoView({block:'center',inline:'center'});
658
+ const dt=new DataTransfer();
659
+ for(const spec of ${JSON.stringify(files)}){
660
+ const bin=atob(spec.b64); const u8=new Uint8Array(bin.length);
661
+ for(let i=0;i<bin.length;i++) u8[i]=bin.charCodeAt(i);
662
+ dt.items.add(new File([u8],spec.name,{type:spec.type}));
663
+ }
664
+ const b=el.getBoundingClientRect();
665
+ const cx=b.left+b.width/2, cy=b.top+b.height/2;
666
+ const fire=(type)=>{
667
+ const ev=new DragEvent(type,{bubbles:true,cancelable:true,clientX:cx,clientY:cy});
668
+ try{ Object.defineProperty(ev,'dataTransfer',{value:dt}); }catch(e){}
669
+ el.dispatchEvent(ev);
670
+ return ev.defaultPrevented;
671
+ };
672
+ fire('dragenter'); fire('dragover'); fire('drop');
673
+ return {ok:true,tag:el.tagName.toLowerCase(),count:dt.files.length};
674
+ })()`;
675
+ }
605
676
  function readExpr(selector) {
606
677
  return WALK + `(() => { const r=${selector ? `__baQuery(${JSON.stringify(selector)})` : `document.body`}; return r ? __baText(r) : ${selector ? `'(no element matches ' + ${JSON.stringify(selector)} + ')'` : `''`}; })()`;
607
678
  }
@@ -635,7 +706,7 @@ const snapshotCommand = define({
635
706
  });
636
707
  //#endregion
637
708
  //#region src/commands/click.ts
638
- const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
709
+ const sleep$1 = (ms) => new Promise((r) => setTimeout(r, ms));
639
710
  const clickCommand = define({
640
711
  name: "click",
641
712
  description: "Click an element by ref (from the latest snapshot)",
@@ -671,12 +742,12 @@ const clickCommand = define({
671
742
  }
672
743
  return res.result?.value;
673
744
  };
674
- await s.send("Page.bringToFront").catch(() => {});
745
+ await forceForeground(s);
675
746
  const focusDeadline = Date.now() + 2e3;
676
747
  while (Date.now() < focusDeadline) {
677
748
  const f = await evalIn(`({f:document.hasFocus(),v:document.visibilityState})`);
678
749
  if (f && f.f && f.v === "visible") break;
679
- await sleep(50);
750
+ await sleep$1(50);
680
751
  }
681
752
  let prev = null;
682
753
  let point = null;
@@ -702,7 +773,7 @@ const clickCommand = define({
702
773
  x: a.x,
703
774
  y: a.y
704
775
  };
705
- await sleep(60);
776
+ await sleep$1(60);
706
777
  }
707
778
  if (!point) {
708
779
  consola.error(`<${ref}> not actionable for a trusted click: ${lastReason}`);
@@ -717,7 +788,7 @@ const clickCommand = define({
717
788
  buttons: 0,
718
789
  pointerType: "mouse"
719
790
  });
720
- await sleep(20);
791
+ await sleep$1(20);
721
792
  await s.send("Input.dispatchMouseEvent", {
722
793
  type: "mousePressed",
723
794
  x,
@@ -752,7 +823,6 @@ const clickCommand = define({
752
823
  });
753
824
  //#endregion
754
825
  //#region src/commands/fill.ts
755
- const SELECT_ALL_MOD = process.platform === "darwin" ? 4 : 2;
756
826
  const fillCommand = define({
757
827
  name: "fill",
758
828
  description: "Type a value into an input/textarea/contenteditable by ref",
@@ -800,38 +870,19 @@ const fillCommand = define({
800
870
  process.exit(1);
801
871
  }
802
872
  await withPage(targetId, async (s) => {
803
- await s.send("Input.dispatchKeyEvent", {
804
- type: "rawKeyDown",
805
- key: "a",
806
- code: "KeyA",
807
- windowsVirtualKeyCode: 65,
808
- nativeVirtualKeyCode: 65,
809
- modifiers: SELECT_ALL_MOD,
810
- commands: ["selectAll"]
811
- });
812
- await s.send("Input.dispatchKeyEvent", {
813
- type: "keyUp",
814
- key: "a",
815
- code: "KeyA",
816
- windowsVirtualKeyCode: 65,
817
- nativeVirtualKeyCode: 65,
818
- modifiers: SELECT_ALL_MOD
819
- });
820
873
  await s.send("Input.insertText", { text: value });
821
874
  if (submit) {
822
875
  await s.send("Input.dispatchKeyEvent", {
823
876
  type: "rawKeyDown",
824
877
  key: "Enter",
825
878
  code: "Enter",
826
- windowsVirtualKeyCode: 13,
827
- nativeVirtualKeyCode: 13
879
+ windowsVirtualKeyCode: 13
828
880
  });
829
881
  await s.send("Input.dispatchKeyEvent", {
830
882
  type: "keyUp",
831
883
  key: "Enter",
832
884
  code: "Enter",
833
- windowsVirtualKeyCode: 13,
834
- nativeVirtualKeyCode: 13
885
+ windowsVirtualKeyCode: 13
835
886
  });
836
887
  }
837
888
  });
@@ -990,6 +1041,406 @@ const downloadCommand = define({
990
1041
  }
991
1042
  });
992
1043
  //#endregion
1044
+ //#region src/core/upload.ts
1045
+ /** Set files on a known input[type=file] addressed by ref. */
1046
+ async function setFilesByRef(targetId, ref, files) {
1047
+ return withPage(targetId, async (s) => {
1048
+ await s.send("DOM.enable");
1049
+ const ev = await s.send("Runtime.evaluate", {
1050
+ expression: findRefExpr(ref),
1051
+ returnByValue: false
1052
+ });
1053
+ if (ev.exceptionDetails) {
1054
+ const e = ev.exceptionDetails;
1055
+ throw new Error("resolving ref failed: " + (e.exception?.description || e.text || "unknown"));
1056
+ }
1057
+ const objectId = ev.result?.objectId;
1058
+ if (!objectId) throw new Error(`ref not found: ${ref} (re-run \`browser-automation snapshot\`)`);
1059
+ const node = (await s.send("DOM.describeNode", { objectId })).node ?? {};
1060
+ const tag = String(node.nodeName ?? "").toLowerCase();
1061
+ const attrs = node.attributes ?? [];
1062
+ let type = "";
1063
+ for (let i = 0; i < attrs.length; i += 2) if (attrs[i] === "type") type = attrs[i + 1];
1064
+ if (tag !== "input" || type.toLowerCase() !== "file") throw new Error(`ref ${ref} is <${tag}${type ? ` type=${type}` : ""}>, not <input type=file>. For a custom "attach" button that opens a file chooser, use \`browser-automation upload --click ${ref} …\` instead.`);
1065
+ await s.send("DOM.setFileInputFiles", {
1066
+ objectId,
1067
+ files
1068
+ });
1069
+ return {
1070
+ tag,
1071
+ type,
1072
+ files
1073
+ };
1074
+ });
1075
+ }
1076
+ /** Arm file-chooser interception, click the trigger, and set files on whatever
1077
+ * input Chrome opens — handles transient/custom-button uploads. */
1078
+ async function uploadViaChooser(targetId, clickRef, files, timeout = 15e3) {
1079
+ return withPage(targetId, async (s) => {
1080
+ await s.send("Page.enable");
1081
+ await s.send("DOM.enable");
1082
+ await s.send("Page.setInterceptFileChooserDialog", { enabled: true });
1083
+ try {
1084
+ const opened = new Promise((resolve, reject) => {
1085
+ const timer = setTimeout(() => reject(/* @__PURE__ */ new Error(`no file chooser opened within ${timeout}ms after clicking ${clickRef} — is it the right trigger?`)), timeout);
1086
+ s.on("Page.fileChooserOpened", (p) => {
1087
+ clearTimeout(timer);
1088
+ resolve(p.backendNodeId);
1089
+ });
1090
+ });
1091
+ const clickVal = (await s.send("Runtime.evaluate", {
1092
+ expression: clickExpr(clickRef),
1093
+ returnByValue: true,
1094
+ userGesture: true
1095
+ })).result?.value;
1096
+ if (clickVal && clickVal.err) throw new Error(clickVal.err);
1097
+ const backendNodeId = await opened;
1098
+ let connected = true;
1099
+ let reconnected = false;
1100
+ let objectId;
1101
+ try {
1102
+ objectId = (await s.send("DOM.resolveNode", { backendNodeId })).object?.objectId;
1103
+ } catch {}
1104
+ if (objectId) {
1105
+ const pv = (await s.send("Runtime.callFunctionOn", {
1106
+ objectId,
1107
+ returnByValue: true,
1108
+ functionDeclaration: `function(){
1109
+ var el=this;
1110
+ var was=el.isConnected;
1111
+ var reattached=false;
1112
+ if(!el.isConnected){
1113
+ try{ el.style.display='none'; (document.body||document.documentElement).appendChild(el); reattached=true; }catch(e){}
1114
+ }
1115
+ // Record the file count at change-dispatch time — survives the app
1116
+ // resetting el.files to 0 immediately after its handler runs.
1117
+ el.__baDelivered = -1;
1118
+ el.addEventListener('change', function(e){ try{ el.__baDelivered = el.files ? el.files.length : 0; }catch(_){ el.__baDelivered = 0; } }, { once: true });
1119
+ return { connected: was, reconnected: reattached };
1120
+ }`
1121
+ })).result?.value;
1122
+ if (pv) {
1123
+ connected = pv.connected;
1124
+ reconnected = pv.reconnected;
1125
+ }
1126
+ }
1127
+ await s.send("DOM.setFileInputFiles", objectId ? {
1128
+ objectId,
1129
+ files
1130
+ } : {
1131
+ backendNodeId,
1132
+ files
1133
+ });
1134
+ let count = files.length;
1135
+ let delivered = files.length;
1136
+ if (objectId) try {
1137
+ const val = (await s.send("Runtime.callFunctionOn", {
1138
+ objectId,
1139
+ returnByValue: true,
1140
+ functionDeclaration: `function(){
1141
+ var el=this;
1142
+ // If the node was detached, the change from setFileInputFiles couldn't
1143
+ // reach a delegated handler — re-fire bubbling input+change now that
1144
+ // it's on the tree.
1145
+ if(${reconnected ? "true" : "false"}){
1146
+ try{ el.dispatchEvent(new Event('input',{bubbles:true})); }catch(e){}
1147
+ try{ el.dispatchEvent(new Event('change',{bubbles:true})); }catch(e){}
1148
+ }
1149
+ return { count: (el.files?el.files.length:0), delivered: (typeof el.__baDelivered==='number'?el.__baDelivered:-1) };
1150
+ }`
1151
+ })).result?.value;
1152
+ if (val) {
1153
+ count = val.count;
1154
+ delivered = val.delivered >= 0 ? val.delivered : 0;
1155
+ }
1156
+ } catch {}
1157
+ return {
1158
+ backendNodeId,
1159
+ files,
1160
+ count,
1161
+ delivered,
1162
+ connected,
1163
+ reconnected
1164
+ };
1165
+ } finally {
1166
+ try {
1167
+ await s.send("Page.setInterceptFileChooserDialog", { enabled: false });
1168
+ } catch {}
1169
+ }
1170
+ });
1171
+ }
1172
+ //#endregion
1173
+ //#region src/commands/setfiles.ts
1174
+ /** Resolve each path to absolute and verify it's an existing file. */
1175
+ function absFiles$2(paths) {
1176
+ return paths.map((p) => {
1177
+ const abs = resolve(p);
1178
+ if (!existsSync(abs) || !statSync(abs).isFile()) {
1179
+ consola.error(`no such file: ${abs}`);
1180
+ process.exit(1);
1181
+ }
1182
+ return abs;
1183
+ });
1184
+ }
1185
+ const setfilesCommand = define({
1186
+ name: "setfiles",
1187
+ description: "Set files on a known <input type=file> by ref (fires input/change). For a custom \"attach\" button that opens a file chooser, use `upload` instead.",
1188
+ args: {
1189
+ ...targetArgs,
1190
+ ref: {
1191
+ type: "positional",
1192
+ description: "Ref of the <input type=file> (run snapshot first)"
1193
+ },
1194
+ files: {
1195
+ type: "positional",
1196
+ description: "One or more file paths (absolute, or resolved from cwd)"
1197
+ }
1198
+ },
1199
+ async run(ctx) {
1200
+ const ref = ctx.positionals[1];
1201
+ const paths = ctx.positionals.slice(2);
1202
+ if (!ref || !isValidRef(ref)) {
1203
+ consola.error("A ref like \"e7\" is required (run `browser-automation snapshot` first)");
1204
+ process.exit(1);
1205
+ }
1206
+ if (paths.length === 0) {
1207
+ consola.error("At least one file path is required");
1208
+ process.exit(1);
1209
+ }
1210
+ const files = absFiles$2(paths);
1211
+ const r = await setFilesByRef(await resolveExistingTargetId(targetOpts(ctx.values)), ref, files);
1212
+ consola.success(`set ${r.files.length} file(s) on ${ref} <${r.tag} type=${r.type}>:`);
1213
+ for (const f of r.files) process.stdout.write(f + "\n");
1214
+ }
1215
+ });
1216
+ //#endregion
1217
+ //#region src/commands/upload.ts
1218
+ /** Resolve each path to absolute and verify it's an existing file. */
1219
+ function absFiles$1(paths) {
1220
+ return paths.map((p) => {
1221
+ const abs = resolve(p);
1222
+ if (!existsSync(abs) || !statSync(abs).isFile()) {
1223
+ consola.error(`no such file: ${abs}`);
1224
+ process.exit(1);
1225
+ }
1226
+ return abs;
1227
+ });
1228
+ }
1229
+ const uploadCommand = define({
1230
+ name: "upload",
1231
+ description: "Upload via a button that opens a file chooser: intercept the chooser, click --click <ref>, set files on the input Chrome opens. Handles transient/custom inputs (App Store Connect \"Attach File\", React dropzones).",
1232
+ args: {
1233
+ ...targetArgs,
1234
+ click: {
1235
+ type: "string",
1236
+ description: "Ref of the trigger (button/link) that opens the file chooser (e.g. e42)"
1237
+ },
1238
+ timeout: {
1239
+ type: "number",
1240
+ description: "Max ms to wait for the chooser to open (default 15000)"
1241
+ },
1242
+ files: {
1243
+ type: "positional",
1244
+ description: "One or more file paths (absolute, or resolved from cwd)"
1245
+ }
1246
+ },
1247
+ async run(ctx) {
1248
+ const click = ctx.values.click;
1249
+ const paths = ctx.positionals.slice(1);
1250
+ if (!click) {
1251
+ consola.error("--click <ref> is required (the button that opens the file chooser)");
1252
+ process.exit(1);
1253
+ }
1254
+ if (!isValidRef(click)) {
1255
+ consola.error("--click expects a ref like e42 (run `browser-automation snapshot` first)");
1256
+ process.exit(1);
1257
+ }
1258
+ if (paths.length === 0) {
1259
+ consola.error("At least one file path is required");
1260
+ process.exit(1);
1261
+ }
1262
+ const files = absFiles$1(paths);
1263
+ const r = await uploadViaChooser(await resolveExistingTargetId(targetOpts(ctx.values)), click, files, ctx.values.timeout ?? 15e3);
1264
+ if (r.delivered === 0) {
1265
+ consola.error(`the file chooser opened (backendNodeId ${r.backendNodeId}) but the file never reached the page's change handler — the page likely replaced/destroyed the transient input before it could be set. Re-snapshot and confirm --click points at the real trigger, or try again.`);
1266
+ process.exit(1);
1267
+ }
1268
+ const note = r.reconnected ? " (input was detached — re-attached and re-dispatched input/change so the page's handler fired)" : "";
1269
+ consola.success(`delivered ${r.files.length} file(s) to the page's file handler via chooser (backendNodeId ${r.backendNodeId})${note}:`);
1270
+ for (const f of r.files) process.stdout.write(f + "\n");
1271
+ if (r.count === 0) consola.info("The app consumed the file and reset the input (normal). This confirms delivery, not staging — re-snapshot or screenshot to verify the attachment chip/preview actually appeared before submitting.");
1272
+ else consola.info("Re-snapshot to confirm the attachment chip/preview appeared before submitting — the DOM changed.");
1273
+ }
1274
+ });
1275
+ //#endregion
1276
+ //#region src/commands/drop.ts
1277
+ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
1278
+ /** Resolve each path to absolute and verify it's an existing file. */
1279
+ function absFiles(paths) {
1280
+ return paths.map((p) => {
1281
+ const abs = resolve(p);
1282
+ if (!existsSync(abs) || !statSync(abs).isFile()) {
1283
+ consola.error(`no such file: ${abs}`);
1284
+ process.exit(1);
1285
+ }
1286
+ return abs;
1287
+ });
1288
+ }
1289
+ /** Minimal extension→mime map for the --js path (where the page builds the File
1290
+ * from bytes and needs a type). The trusted CDP path doesn't need this — Chrome
1291
+ * reads the real file off disk and sets the type itself. */
1292
+ function guessMime(p) {
1293
+ return {
1294
+ ".mp3": "audio/mpeg",
1295
+ ".wav": "audio/wav",
1296
+ ".ogg": "audio/ogg",
1297
+ ".flac": "audio/flac",
1298
+ ".m4a": "audio/mp4",
1299
+ ".aac": "audio/aac",
1300
+ ".mp4": "video/mp4",
1301
+ ".mov": "video/quicktime",
1302
+ ".webm": "video/webm",
1303
+ ".png": "image/png",
1304
+ ".jpg": "image/jpeg",
1305
+ ".jpeg": "image/jpeg",
1306
+ ".gif": "image/gif",
1307
+ ".webp": "image/webp",
1308
+ ".svg": "image/svg+xml",
1309
+ ".pdf": "application/pdf",
1310
+ ".zip": "application/zip",
1311
+ ".json": "application/json",
1312
+ ".csv": "text/csv",
1313
+ ".txt": "text/plain"
1314
+ }[extname(p).toLowerCase()] || "application/octet-stream";
1315
+ }
1316
+ const dropCommand = define({
1317
+ name: "drop",
1318
+ description: "Drop local file(s) onto a drop-zone element by ref — for uploaders wired to drag-and-drop (a `drop` listener reading `e.dataTransfer.files`) rather than an <input type=file>. Default fires a genuinely-trusted CDP drag sequence (Input.dispatchDragEvent) carrying the real files from disk: brings the tab to front, waits for it to be focused+visible, waits for the target to be actionable (stable + unoccluded), then dragEnter→dragOver→drop — mirroring `click --trusted`. Use --js for a synthetic (isTrusted=false) DataTransfer drop that does NOT steal focus, for zones that accept synthetic events. For a static <input type=file> use `setfiles`; for a button that opens a file chooser use `upload`.",
1319
+ args: {
1320
+ ...targetArgs,
1321
+ on: {
1322
+ type: "positional",
1323
+ description: "Ref of the drop-zone element (run snapshot first), e.g. e7"
1324
+ },
1325
+ files: {
1326
+ type: "positional",
1327
+ description: "One or more file paths (absolute, or resolved from cwd)"
1328
+ },
1329
+ js: {
1330
+ type: "boolean",
1331
+ description: "Dispatch a synthetic (isTrusted=false) DataTransfer drop instead of the trusted CDP path. Does not bring the tab to front (no focus steal). Injects each file's bytes into the page to build the File objects. Use for drop zones that accept synthetic events; falls short on zones that gate on isTrusted."
1332
+ }
1333
+ },
1334
+ async run(ctx) {
1335
+ const ref = ctx.positionals[1];
1336
+ const paths = ctx.positionals.slice(2);
1337
+ if (!ref || !isValidRef(ref)) {
1338
+ consola.error("A ref like \"e7\" is required (run `browser-automation snapshot` first)");
1339
+ process.exit(1);
1340
+ }
1341
+ if (paths.length === 0) {
1342
+ consola.error("At least one file path is required");
1343
+ process.exit(1);
1344
+ }
1345
+ const files = absFiles(paths);
1346
+ const targetId = await resolveExistingTargetId(targetOpts(ctx.values));
1347
+ if (ctx.values.js ?? false) {
1348
+ const r = await evaluate(targetId, dropExpr(ref, files.map((p) => ({
1349
+ name: basename(p),
1350
+ type: guessMime(p),
1351
+ b64: readFileSync(p).toString("base64")
1352
+ }))));
1353
+ if (r.err) {
1354
+ consola.error(r.err);
1355
+ process.exit(1);
1356
+ }
1357
+ consola.success(`dropped ${r.count} file(s) on ${ref} <${r.tag}> (synthetic — re-snapshot/screenshot to confirm the zone accepted them):`);
1358
+ for (const f of files) process.stdout.write(f + "\n");
1359
+ return;
1360
+ }
1361
+ const tag = await withPage(targetId, async (s) => {
1362
+ const evalIn = async (expr) => {
1363
+ const res = await s.send("Runtime.evaluate", {
1364
+ expression: expr,
1365
+ returnByValue: true,
1366
+ awaitPromise: true
1367
+ });
1368
+ if (res.exceptionDetails) {
1369
+ const e = res.exceptionDetails;
1370
+ throw new Error("page JS exception: " + (e.exception?.description || e.text || "unknown"));
1371
+ }
1372
+ return res.result?.value;
1373
+ };
1374
+ await forceForeground(s);
1375
+ const focusDeadline = Date.now() + 2e3;
1376
+ while (Date.now() < focusDeadline) {
1377
+ const f = await evalIn(`({f:document.hasFocus(),v:document.visibilityState})`);
1378
+ if (f && f.f && f.v === "visible") break;
1379
+ await sleep(50);
1380
+ }
1381
+ let prev = null;
1382
+ let point = null;
1383
+ let lastReason = "never became actionable";
1384
+ const actDeadline = Date.now() + 5e3;
1385
+ while (Date.now() < actDeadline) {
1386
+ const a = await evalIn(actionabilityExpr(ref));
1387
+ if (a?.err) {
1388
+ consola.error(a.err);
1389
+ process.exit(1);
1390
+ }
1391
+ const stable = prev !== null && Math.abs(prev.x - a.x) < .5 && Math.abs(prev.y - a.y) < .5;
1392
+ if (a.hit && stable) {
1393
+ point = {
1394
+ x: a.x,
1395
+ y: a.y,
1396
+ tag: a.tag
1397
+ };
1398
+ break;
1399
+ }
1400
+ lastReason = a.hit ? "position not yet stable (still animating)" : "drop-point occluded (hit-test miss)";
1401
+ prev = {
1402
+ x: a.x,
1403
+ y: a.y
1404
+ };
1405
+ await sleep(60);
1406
+ }
1407
+ if (!point) {
1408
+ consola.error(`<${ref}> not actionable for a drop: ${lastReason}`);
1409
+ process.exit(1);
1410
+ }
1411
+ const { x, y } = point;
1412
+ const data = {
1413
+ items: [],
1414
+ files,
1415
+ dragOperationsMask: 1
1416
+ };
1417
+ await s.send("Input.dispatchDragEvent", {
1418
+ type: "dragEnter",
1419
+ x,
1420
+ y,
1421
+ data
1422
+ });
1423
+ await s.send("Input.dispatchDragEvent", {
1424
+ type: "dragOver",
1425
+ x,
1426
+ y,
1427
+ data
1428
+ });
1429
+ await sleep(20);
1430
+ await s.send("Input.dispatchDragEvent", {
1431
+ type: "drop",
1432
+ x,
1433
+ y,
1434
+ data
1435
+ });
1436
+ return point.tag;
1437
+ });
1438
+ consola.success(`dropped ${files.length} file(s) on ${ref} <${tag}> (trusted):`);
1439
+ for (const f of files) process.stdout.write(f + "\n");
1440
+ consola.info("Re-snapshot or screenshot to confirm the zone accepted the drop — the DOM changed.");
1441
+ }
1442
+ });
1443
+ //#endregion
993
1444
  //#region src/core/network.ts
994
1445
  const INTERESTING = new Set([
995
1446
  "XHR",
@@ -1363,6 +1814,9 @@ const subCommands = new Map([
1363
1814
  ["read", readCommand],
1364
1815
  ["eval", evalCommand],
1365
1816
  ["download", downloadCommand],
1817
+ ["setfiles", setfilesCommand],
1818
+ ["upload", uploadCommand],
1819
+ ["drop", dropCommand],
1366
1820
  ["network", networkCommand],
1367
1821
  ["screenshot", screenshotCommand],
1368
1822
  ["shot", screenshotCommand],
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@generativereality/browser-automation",
3
- "version": "0.4.4",
3
+ "version": "0.4.6",
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": {
@@ -83,6 +83,9 @@ Page commands take a tab selector — `-s <session>` (default `$BAC_SESSION`, el
83
83
  | Read page text (or a selector) | `browser-automation read -m op.fi ['.balance']` |
84
84
  | Evaluate JS in the tab (escape hatch) | `browser-automation eval -m op.fi 'document.title'` |
85
85
  | Download a file / CSV export | `browser-automation download -m bank --click e42` (or `--url <href>`) |
86
+ | Set files on a known `<input type=file>` | `browser-automation setfiles -m app e7 ~/Desktop/clip.mp4` |
87
+ | Upload via a button that opens a file chooser | `browser-automation upload -m app --click e9 ~/Desktop/clip.mp4` |
88
+ | Drop file(s) onto a drag-and-drop zone | `browser-automation drop -m app e7 ~/Desktop/clip.mp4` (add `--js` for a synthetic drop) |
86
89
  | Inspect network (find the API, headers, bodies) | `browser-automation network -m bank --reload --filter api --headers --body` |
87
90
  | Screenshot a tab | `browser-automation screenshot -m op.fi --full -o shot.png` |
88
91
  | Forget a session (tab stays open) | `browser-automation close -s work` |
@@ -184,6 +187,48 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
184
187
  whose JS handler builds a client-side **blob** and clicks it via a *nested*
185
188
  synthetic click won't fire (Chrome activation quirk) — for those, grab the
186
189
  underlying export URL/endpoint and use `--url`, or the site's API.
190
+ - **File upload.** Three paths. The first two mirror Playwright. For a static, snapshot-able
191
+ `<input type=file>`, use `setfiles <ref> <path…>` — it resolves the ref and
192
+ calls `DOM.setFileInputFiles` (a file input's `.files` is read-only to page JS,
193
+ so a value-setter/`eval` can't populate it; CDP can, and fires trusted
194
+ `input`/`change`). For a **custom "attach" button** that opens a native file
195
+ chooser and reads a *transient* `<input type=file>` it creates+clicks on the fly
196
+ (App Store Connect's "Attach File", many React dropzones), `setfiles` on the
197
+ static input is useless — the handler uses its own throwaway input. Use
198
+ `upload --click <ref> <path…>`: it arms `Page.setInterceptFileChooserDialog`,
199
+ clicks the trigger, waits for `Page.fileChooserOpened`, and sets files on the
200
+ `backendNodeId` Chrome reports. Paths are resolved from cwd; pass absolute paths
201
+ to be safe. Multiple paths upload as a multi-file selection.
202
+ **Verify by re-snapshot/screenshot, and DON'T blindly retry.** Apps reset the
203
+ input to 0 right after consuming the file, so `upload` judges success by the
204
+ `change` event (it reports "delivered"), not by residual `input.files` — a
205
+ successful upload legitimately leaves `files=0`. The staged file often shows up
206
+ as a row in an attachment *list* (e.g. ASC's "Message Attachments"), not a single
207
+ chip, so confirm with `snapshot`/`screenshot` rather than assuming. Each
208
+ successful run **adds another attachment** — retrying a "did it work?" upload a
209
+ few times silently produces duplicates (this cost us a dozen copies on a live ASC
210
+ reply). Upload once, verify, and only re-run if verification shows nothing staged.
211
+ The **third path is drag-and-drop**, for zones with NO `<input type=file>` at
212
+ all — a `drop` listener reading `e.dataTransfer.files` (vocalremover-style audio
213
+ tools, many image/video drop zones). Neither `setfiles` nor `upload` applies;
214
+ use `drop <ref> <path…>`. By default it fires a genuinely-**trusted** CDP drag
215
+ (`Input.dispatchDragEvent`) carrying the real files from disk: it force-fronts
216
+ the tab (bringToFront + focus emulation + active lifecycle — so the tab reports
217
+ focused+visible even when the Chrome window isn't the frontmost OS window),
218
+ waits for the zone to be actionable, then dragEnter→dragOver→drop. The
219
+ force-front matters: drop-zone uploaders commonly do their work only inside a
220
+ **user activation**, and CDP input grants no activation on a tab the renderer
221
+ considers `hidden` — which it is whenever the window is occluded (the usual
222
+ case while you work in the terminal). vocalremover.org is the canonical example:
223
+ the file reaches its `change`/`drop` handler either way, but it only uploads +
224
+ separates once activation is present. `--js` instead dispatches a synthetic
225
+ (isTrusted=false) `DataTransfer` drop **without** force-fronting/stealing focus,
226
+ for zones that accept synthetic events. The `<ref>` can be any snapshot element
227
+ sitting over the drop region (a heading/button inside the zone) — the drop
228
+ bubbles to the zone/document handler, so it works even when the drop div itself
229
+ isn't snapshot-interactive. After the drop, `read`/`screenshot`/`network` to
230
+ confirm processing started, then grab the result (often a download endpoint you
231
+ can pull with `download --url`).
187
232
  - **Page still loading.** `goto` waits for the load event, but SPAs render after.
188
233
  If a `read`/`snapshot` looks empty, re-run after a moment, or snapshot again
189
234
  once a known element should be present.