@generativereality/browser-automation 0.4.3 → 0.4.5

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.3",
4
+ "version": "0.4.5",
5
5
  "author": {
6
6
  "name": "generativereality"
7
7
  },
package/README.md CHANGED
@@ -104,6 +104,8 @@ 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) |
107
109
  | `network (-s\|-m\|-t) [--reload\|--click\|--nav] [--filter --headers --body]` | Capture network requests (find the API, headers, response bodies) |
108
110
  | `screenshot (-s\|-m\|-t) [--full] [-o path]` | Save a PNG screenshot (viewport or full page) |
109
111
  | `close (-s\|-m\|-t) [--tab]` | Forget the session (tab stays open); `--tab` also closes the browser tab |
@@ -125,6 +127,18 @@ same one-action-per-snapshot rule as Playwright refs.
125
127
  - `read`/`snapshot` see the page + same-origin frames. A **cross-origin iframe**
126
128
  is its own CDP target — reach it with `-F <substr>` (or `-t <iframeTargetId>`
127
129
  from `list --frames`); every page command then runs inside that frame.
130
+ - **File upload** has two entry points (Playwright's two paths). For a static
131
+ `<input type=file>` you can snapshot, use `setfiles <ref> <path…>`. For a custom
132
+ "attach" button that opens a native file chooser — and reads a *transient* input
133
+ that only exists during the chooser (App Store Connect's "Attach File", many
134
+ React dropzones) — use `upload --click <ref> <path…>`: it intercepts the chooser
135
+ and sets files on whatever input Chrome opens. Setting the static input via JS
136
+ won't work there; the button uses its own throwaway input. `upload` judges
137
+ success by the `change` event (reports "delivered"), since apps reset the input
138
+ to 0 after consuming the file — so `files=0` afterward is normal. **Verify by
139
+ re-snapshot/screenshot and don't blindly retry:** the file may stage as a row in
140
+ an attachment *list* (not a single chip), and each successful run adds another
141
+ attachment, so retrying can silently create duplicates.
128
142
  - `launch` resolves Chrome on macOS/Linux; elsewhere start Chrome manually with
129
143
  `--remote-debugging-port=9223 --user-data-dir="<profile>"`.
130
144
 
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 { dirname, 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.3";
10
+ var version = "0.4.5";
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
@@ -468,10 +468,24 @@ const SNAPSHOT_EXPR = WALK + `(() => {
468
468
  const disabled=(el.disabled===true)||truthy(el.getAttribute&&el.getAttribute('aria-disabled'));
469
469
  return [checked?'checked':'',disabled?'disabled':''].filter(Boolean).join(' ');
470
470
  };
471
- 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=[];
472
481
  __baEachEl((el)=>{
473
- if(out.length>=200) return;
474
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){
475
489
  const ref='e'+(i++);
476
490
  el.setAttribute('data-ba-ref',ref);
477
491
  const tag=el.tagName.toLowerCase();
@@ -479,8 +493,21 @@ const SNAPSHOT_EXPR = WALK + `(() => {
479
493
  const type=el.getAttribute('type')||'';
480
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);
481
495
  out.push({ref,role,tag,type,name,state:stateOf(el)});
482
- });
483
- 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};
484
511
  })()`;
485
512
  function clickExpr(ref) {
486
513
  const r = JSON.stringify(ref);
@@ -575,6 +602,14 @@ function readValueAndTrackerExpr(ref) {
575
602
  return {value,trackerValue,hasReactFiber};
576
603
  })()`;
577
604
  }
605
+ /** Return the live element for a ref as an OBJECT (evaluate with
606
+ * returnByValue:false) so the caller gets a Runtime RemoteObject `objectId`,
607
+ * which `DOM.setFileInputFiles` accepts directly. Resolves through shadow DOM
608
+ * and same-origin iframes like every other ref op. Yields `null` (subtype
609
+ * 'null', no objectId) when the ref is stale. */
610
+ function findRefExpr(ref) {
611
+ return WALK + `(() => __baFind(${JSON.stringify(ref)}))()`;
612
+ }
578
613
  function readExpr(selector) {
579
614
  return WALK + `(() => { const r=${selector ? `__baQuery(${JSON.stringify(selector)})` : `document.body`}; return r ? __baText(r) : ${selector ? `'(no element matches ' + ${JSON.stringify(selector)} + ')'` : `''`}; })()`;
580
615
  }
@@ -596,7 +631,9 @@ const snapshotCommand = define({
596
631
  process.stdout.write(JSON.stringify(snap, null, 2) + "\n");
597
632
  return;
598
633
  }
599
- consola.log(`# ${snap.title}\n# ${snap.url}\n# ${snap.count} interactive elements`);
634
+ const overlayNote = snap.overlayCount ? ` (${snap.overlayCount} in an open overlay, listed first)` : "";
635
+ consola.log(`# ${snap.title}\n# ${snap.url}\n# ${snap.count} interactive elements${overlayNote}`);
636
+ if (snap.overlayText) consola.log(`# overlay: ${snap.overlayText}`);
600
637
  for (const el of snap.elements) {
601
638
  const label = el.type ? `${el.role}[${el.type}]` : el.role;
602
639
  const st = el.state ? `[${el.state}] ` : "";
@@ -961,6 +998,238 @@ const downloadCommand = define({
961
998
  }
962
999
  });
963
1000
  //#endregion
1001
+ //#region src/core/upload.ts
1002
+ /** Set files on a known input[type=file] addressed by ref. */
1003
+ async function setFilesByRef(targetId, ref, files) {
1004
+ return withPage(targetId, async (s) => {
1005
+ await s.send("DOM.enable");
1006
+ const ev = await s.send("Runtime.evaluate", {
1007
+ expression: findRefExpr(ref),
1008
+ returnByValue: false
1009
+ });
1010
+ if (ev.exceptionDetails) {
1011
+ const e = ev.exceptionDetails;
1012
+ throw new Error("resolving ref failed: " + (e.exception?.description || e.text || "unknown"));
1013
+ }
1014
+ const objectId = ev.result?.objectId;
1015
+ if (!objectId) throw new Error(`ref not found: ${ref} (re-run \`browser-automation snapshot\`)`);
1016
+ const node = (await s.send("DOM.describeNode", { objectId })).node ?? {};
1017
+ const tag = String(node.nodeName ?? "").toLowerCase();
1018
+ const attrs = node.attributes ?? [];
1019
+ let type = "";
1020
+ for (let i = 0; i < attrs.length; i += 2) if (attrs[i] === "type") type = attrs[i + 1];
1021
+ 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.`);
1022
+ await s.send("DOM.setFileInputFiles", {
1023
+ objectId,
1024
+ files
1025
+ });
1026
+ return {
1027
+ tag,
1028
+ type,
1029
+ files
1030
+ };
1031
+ });
1032
+ }
1033
+ /** Arm file-chooser interception, click the trigger, and set files on whatever
1034
+ * input Chrome opens — handles transient/custom-button uploads. */
1035
+ async function uploadViaChooser(targetId, clickRef, files, timeout = 15e3) {
1036
+ return withPage(targetId, async (s) => {
1037
+ await s.send("Page.enable");
1038
+ await s.send("DOM.enable");
1039
+ await s.send("Page.setInterceptFileChooserDialog", { enabled: true });
1040
+ try {
1041
+ const opened = new Promise((resolve, reject) => {
1042
+ const timer = setTimeout(() => reject(/* @__PURE__ */ new Error(`no file chooser opened within ${timeout}ms after clicking ${clickRef} — is it the right trigger?`)), timeout);
1043
+ s.on("Page.fileChooserOpened", (p) => {
1044
+ clearTimeout(timer);
1045
+ resolve(p.backendNodeId);
1046
+ });
1047
+ });
1048
+ const clickVal = (await s.send("Runtime.evaluate", {
1049
+ expression: clickExpr(clickRef),
1050
+ returnByValue: true,
1051
+ userGesture: true
1052
+ })).result?.value;
1053
+ if (clickVal && clickVal.err) throw new Error(clickVal.err);
1054
+ const backendNodeId = await opened;
1055
+ let connected = true;
1056
+ let reconnected = false;
1057
+ let objectId;
1058
+ try {
1059
+ objectId = (await s.send("DOM.resolveNode", { backendNodeId })).object?.objectId;
1060
+ } catch {}
1061
+ if (objectId) {
1062
+ const pv = (await s.send("Runtime.callFunctionOn", {
1063
+ objectId,
1064
+ returnByValue: true,
1065
+ functionDeclaration: `function(){
1066
+ var el=this;
1067
+ var was=el.isConnected;
1068
+ var reattached=false;
1069
+ if(!el.isConnected){
1070
+ try{ el.style.display='none'; (document.body||document.documentElement).appendChild(el); reattached=true; }catch(e){}
1071
+ }
1072
+ // Record the file count at change-dispatch time — survives the app
1073
+ // resetting el.files to 0 immediately after its handler runs.
1074
+ el.__baDelivered = -1;
1075
+ el.addEventListener('change', function(e){ try{ el.__baDelivered = el.files ? el.files.length : 0; }catch(_){ el.__baDelivered = 0; } }, { once: true });
1076
+ return { connected: was, reconnected: reattached };
1077
+ }`
1078
+ })).result?.value;
1079
+ if (pv) {
1080
+ connected = pv.connected;
1081
+ reconnected = pv.reconnected;
1082
+ }
1083
+ }
1084
+ await s.send("DOM.setFileInputFiles", objectId ? {
1085
+ objectId,
1086
+ files
1087
+ } : {
1088
+ backendNodeId,
1089
+ files
1090
+ });
1091
+ let count = files.length;
1092
+ let delivered = files.length;
1093
+ if (objectId) try {
1094
+ const val = (await s.send("Runtime.callFunctionOn", {
1095
+ objectId,
1096
+ returnByValue: true,
1097
+ functionDeclaration: `function(){
1098
+ var el=this;
1099
+ // If the node was detached, the change from setFileInputFiles couldn't
1100
+ // reach a delegated handler — re-fire bubbling input+change now that
1101
+ // it's on the tree.
1102
+ if(${reconnected ? "true" : "false"}){
1103
+ try{ el.dispatchEvent(new Event('input',{bubbles:true})); }catch(e){}
1104
+ try{ el.dispatchEvent(new Event('change',{bubbles:true})); }catch(e){}
1105
+ }
1106
+ return { count: (el.files?el.files.length:0), delivered: (typeof el.__baDelivered==='number'?el.__baDelivered:-1) };
1107
+ }`
1108
+ })).result?.value;
1109
+ if (val) {
1110
+ count = val.count;
1111
+ delivered = val.delivered >= 0 ? val.delivered : 0;
1112
+ }
1113
+ } catch {}
1114
+ return {
1115
+ backendNodeId,
1116
+ files,
1117
+ count,
1118
+ delivered,
1119
+ connected,
1120
+ reconnected
1121
+ };
1122
+ } finally {
1123
+ try {
1124
+ await s.send("Page.setInterceptFileChooserDialog", { enabled: false });
1125
+ } catch {}
1126
+ }
1127
+ });
1128
+ }
1129
+ //#endregion
1130
+ //#region src/commands/setfiles.ts
1131
+ /** Resolve each path to absolute and verify it's an existing file. */
1132
+ function absFiles$1(paths) {
1133
+ return paths.map((p) => {
1134
+ const abs = resolve(p);
1135
+ if (!existsSync(abs) || !statSync(abs).isFile()) {
1136
+ consola.error(`no such file: ${abs}`);
1137
+ process.exit(1);
1138
+ }
1139
+ return abs;
1140
+ });
1141
+ }
1142
+ const setfilesCommand = define({
1143
+ name: "setfiles",
1144
+ 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.",
1145
+ args: {
1146
+ ...targetArgs,
1147
+ ref: {
1148
+ type: "positional",
1149
+ description: "Ref of the <input type=file> (run snapshot first)"
1150
+ },
1151
+ files: {
1152
+ type: "positional",
1153
+ description: "One or more file paths (absolute, or resolved from cwd)"
1154
+ }
1155
+ },
1156
+ async run(ctx) {
1157
+ const ref = ctx.positionals[1];
1158
+ const paths = ctx.positionals.slice(2);
1159
+ if (!ref || !isValidRef(ref)) {
1160
+ consola.error("A ref like \"e7\" is required (run `browser-automation snapshot` first)");
1161
+ process.exit(1);
1162
+ }
1163
+ if (paths.length === 0) {
1164
+ consola.error("At least one file path is required");
1165
+ process.exit(1);
1166
+ }
1167
+ const files = absFiles$1(paths);
1168
+ const r = await setFilesByRef(await resolveExistingTargetId(targetOpts(ctx.values)), ref, files);
1169
+ consola.success(`set ${r.files.length} file(s) on ${ref} <${r.tag} type=${r.type}>:`);
1170
+ for (const f of r.files) process.stdout.write(f + "\n");
1171
+ }
1172
+ });
1173
+ //#endregion
1174
+ //#region src/commands/upload.ts
1175
+ /** Resolve each path to absolute and verify it's an existing file. */
1176
+ function absFiles(paths) {
1177
+ return paths.map((p) => {
1178
+ const abs = resolve(p);
1179
+ if (!existsSync(abs) || !statSync(abs).isFile()) {
1180
+ consola.error(`no such file: ${abs}`);
1181
+ process.exit(1);
1182
+ }
1183
+ return abs;
1184
+ });
1185
+ }
1186
+ const uploadCommand = define({
1187
+ name: "upload",
1188
+ 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).",
1189
+ args: {
1190
+ ...targetArgs,
1191
+ click: {
1192
+ type: "string",
1193
+ description: "Ref of the trigger (button/link) that opens the file chooser (e.g. e42)"
1194
+ },
1195
+ timeout: {
1196
+ type: "number",
1197
+ description: "Max ms to wait for the chooser to open (default 15000)"
1198
+ },
1199
+ files: {
1200
+ type: "positional",
1201
+ description: "One or more file paths (absolute, or resolved from cwd)"
1202
+ }
1203
+ },
1204
+ async run(ctx) {
1205
+ const click = ctx.values.click;
1206
+ const paths = ctx.positionals.slice(1);
1207
+ if (!click) {
1208
+ consola.error("--click <ref> is required (the button that opens the file chooser)");
1209
+ process.exit(1);
1210
+ }
1211
+ if (!isValidRef(click)) {
1212
+ consola.error("--click expects a ref like e42 (run `browser-automation snapshot` first)");
1213
+ process.exit(1);
1214
+ }
1215
+ if (paths.length === 0) {
1216
+ consola.error("At least one file path is required");
1217
+ process.exit(1);
1218
+ }
1219
+ const files = absFiles(paths);
1220
+ const r = await uploadViaChooser(await resolveExistingTargetId(targetOpts(ctx.values)), click, files, ctx.values.timeout ?? 15e3);
1221
+ if (r.delivered === 0) {
1222
+ 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.`);
1223
+ process.exit(1);
1224
+ }
1225
+ const note = r.reconnected ? " (input was detached — re-attached and re-dispatched input/change so the page's handler fired)" : "";
1226
+ consola.success(`delivered ${r.files.length} file(s) to the page's file handler via chooser (backendNodeId ${r.backendNodeId})${note}:`);
1227
+ for (const f of r.files) process.stdout.write(f + "\n");
1228
+ 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.");
1229
+ else consola.info("Re-snapshot to confirm the attachment chip/preview appeared before submitting — the DOM changed.");
1230
+ }
1231
+ });
1232
+ //#endregion
964
1233
  //#region src/core/network.ts
965
1234
  const INTERESTING = new Set([
966
1235
  "XHR",
@@ -1334,6 +1603,8 @@ const subCommands = new Map([
1334
1603
  ["read", readCommand],
1335
1604
  ["eval", evalCommand],
1336
1605
  ["download", downloadCommand],
1606
+ ["setfiles", setfilesCommand],
1607
+ ["upload", uploadCommand],
1337
1608
  ["network", networkCommand],
1338
1609
  ["screenshot", screenshotCommand],
1339
1610
  ["shot", screenshotCommand],
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@generativereality/browser-automation",
3
- "version": "0.4.3",
3
+ "version": "0.4.5",
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,8 @@ 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` |
86
88
  | Inspect network (find the API, headers, bodies) | `browser-automation network -m bank --reload --filter api --headers --body` |
87
89
  | Screenshot a tab | `browser-automation screenshot -m op.fi --full -o shot.png` |
88
90
  | Forget a session (tab stays open) | `browser-automation close -s work` |
@@ -184,6 +186,27 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
184
186
  whose JS handler builds a client-side **blob** and clicks it via a *nested*
185
187
  synthetic click won't fire (Chrome activation quirk) — for those, grab the
186
188
  underlying export URL/endpoint and use `--url`, or the site's API.
189
+ - **File upload.** Two paths, mirroring Playwright. For a static, snapshot-able
190
+ `<input type=file>`, use `setfiles <ref> <path…>` — it resolves the ref and
191
+ calls `DOM.setFileInputFiles` (a file input's `.files` is read-only to page JS,
192
+ so a value-setter/`eval` can't populate it; CDP can, and fires trusted
193
+ `input`/`change`). For a **custom "attach" button** that opens a native file
194
+ chooser and reads a *transient* `<input type=file>` it creates+clicks on the fly
195
+ (App Store Connect's "Attach File", many React dropzones), `setfiles` on the
196
+ static input is useless — the handler uses its own throwaway input. Use
197
+ `upload --click <ref> <path…>`: it arms `Page.setInterceptFileChooserDialog`,
198
+ clicks the trigger, waits for `Page.fileChooserOpened`, and sets files on the
199
+ `backendNodeId` Chrome reports. Paths are resolved from cwd; pass absolute paths
200
+ to be safe. Multiple paths upload as a multi-file selection.
201
+ **Verify by re-snapshot/screenshot, and DON'T blindly retry.** Apps reset the
202
+ input to 0 right after consuming the file, so `upload` judges success by the
203
+ `change` event (it reports "delivered"), not by residual `input.files` — a
204
+ successful upload legitimately leaves `files=0`. The staged file often shows up
205
+ as a row in an attachment *list* (e.g. ASC's "Message Attachments"), not a single
206
+ chip, so confirm with `snapshot`/`screenshot` rather than assuming. Each
207
+ successful run **adds another attachment** — retrying a "did it work?" upload a
208
+ few times silently produces duplicates (this cost us a dozen copies on a live ASC
209
+ reply). Upload once, verify, and only re-run if verification shows nothing staged.
187
210
  - **Page still loading.** `goto` waits for the load event, but SPAs render after.
188
211
  If a `read`/`snapshot` looks empty, re-run after a moment, or snapshot again
189
212
  once a known element should be present.