@generativereality/browser-automation 0.4.0 → 0.4.1

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.0",
4
+ "version": "0.4.1",
5
5
  "author": {
6
6
  "name": "generativereality"
7
7
  },
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.0";
10
+ var version = "0.4.1";
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
@@ -427,17 +427,37 @@ function __baText(root){
427
427
  `;
428
428
  const SNAPSHOT_EXPR = WALK + `(() => {
429
429
  __baEachEl((el)=>{ if(el.getAttribute && el.getAttribute('data-ba-ref')) el.removeAttribute('data-ba-ref'); });
430
- const isInteractive=(el)=>{try{return el.matches('a,button,input,select,textarea,summary,[role=button],[role=link],[role=tab],[role=checkbox],[role=radio],[role=menuitem],[role=switch],[onclick],[contenteditable=""],[contenteditable=true]');}catch(e){return false;}};
430
+ const ptr=(el)=>{try{return getComputedStyle(el).cursor==='pointer';}catch(e){return false;}};
431
+ // Interactive = semantic control, OR focusable (tabindex>=0), OR the OUTERMOST
432
+ // element in a cursor:pointer chain (catches React clickable <div>s without
433
+ // dragging in their pointer-inheriting children or huge containers).
434
+ const isInteractive=(el)=>{
435
+ try{ if(el.matches('a,button,input,select,textarea,summary,label,[role=button],[role=link],[role=tab],[role=checkbox],[role=radio],[role=option],[role=menuitem],[role=switch],[onclick],[contenteditable=""],[contenteditable=true]')) return true; }catch(e){}
436
+ const ti=el.getAttribute&&el.getAttribute('tabindex');
437
+ if(ti!=null&&parseInt(ti,10)>=0) return true;
438
+ if(ptr(el)){ const p=el.parentElement; if(!p||!ptr(p)) return true; }
439
+ return false;
440
+ };
441
+ const truthy=(v)=>v==='true';
442
+ const stateOf=(el)=>{
443
+ let checked=(el.tagName==='INPUT')?!!el.checked:false;
444
+ const inp=el.querySelector&&el.querySelector('input[type=checkbox],input[type=radio]');
445
+ if(inp&&inp.checked) checked=true;
446
+ if(truthy(el.getAttribute&&el.getAttribute('aria-checked'))||truthy(el.getAttribute&&el.getAttribute('aria-selected'))||truthy(el.getAttribute&&el.getAttribute('aria-pressed'))) checked=true;
447
+ const disabled=(el.disabled===true)||truthy(el.getAttribute&&el.getAttribute('aria-disabled'));
448
+ return [checked?'checked':'',disabled?'disabled':''].filter(Boolean).join(' ');
449
+ };
431
450
  const out=[]; let i=1;
432
451
  __baEachEl((el)=>{
452
+ if(out.length>=200) return;
433
453
  if(!isInteractive(el)||!__baVisible(el))return;
434
454
  const ref='e'+(i++);
435
455
  el.setAttribute('data-ba-ref',ref);
436
456
  const tag=el.tagName.toLowerCase();
437
457
  const role=el.getAttribute('role')||tag;
438
458
  const type=el.getAttribute('type')||'';
439
- let name=(el.getAttribute('aria-label')||el.getAttribute('placeholder')||(el.value||'')||el.innerText||el.getAttribute('title')||el.getAttribute('name')||'').toString().trim().replace(/\\s+/g,' ').slice(0,80);
440
- out.push({ref,role,tag,type,name});
459
+ 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
+ out.push({ref,role,tag,type,name,state:stateOf(el)});
441
461
  });
442
462
  return {url:location.href,title:document.title,count:out.length,elements:out};
443
463
  })()`;
@@ -481,6 +501,40 @@ function fillExpr(ref, value, submit) {
481
501
  return {ok:true,value:el.value!==undefined?String(el.value).slice(0,80):${v}};
482
502
  })()`;
483
503
  }
504
+ /** Focus + scroll an element by ref and select-all its existing value. Used by
505
+ * `fill --native`: the actual character insertion is then driven via CDP
506
+ * Input.insertText, which fires trusted events that controlled React forms
507
+ * (RHF, Final Form, Formik Controller) actually subscribe to. */
508
+ function focusAndSelectExpr(ref) {
509
+ const r = JSON.stringify(ref);
510
+ return WALK + `(() => {
511
+ const el=__baFind(${r});
512
+ if(!el)return {err:'ref not found: '+${r}+' (re-run snapshot)'};
513
+ el.scrollIntoView({block:'center',inline:'center'});
514
+ el.focus();
515
+ try{ if(typeof el.select==='function') el.select(); }catch(e){}
516
+ return {ok:true,tag:el.tagName.toLowerCase(),len:el.value!==undefined?String(el.value).length:0};
517
+ })()`;
518
+ }
519
+ /** Re-read an input/textarea/contenteditable's effective value AND, when present,
520
+ * React's internal `_valueTracker.getValue()` — which is what React's onChange
521
+ * fires on. A divergence between the two is the canonical signature of
522
+ * "DOM value set but React form-state stayed stale" (the controlled-form
523
+ * stickiness gotcha — see SKILL.md). Also reports whether a React fiber is
524
+ * attached at all, so callers can tell "controlled component" from "plain DOM". */
525
+ function readValueAndTrackerExpr(ref) {
526
+ const r = JSON.stringify(ref);
527
+ return WALK + `(() => {
528
+ const el=__baFind(${r});
529
+ if(!el)return {err:'ref not found: '+${r}+' (re-run snapshot)'};
530
+ const value=el.value!==undefined?String(el.value):(el.isContentEditable?(el.textContent||''):'');
531
+ let trackerValue=null;
532
+ try{ const t=el._valueTracker; if(t&&typeof t.getValue==='function') trackerValue=String(t.getValue()); }catch(e){}
533
+ let hasReactFiber=false;
534
+ try{ hasReactFiber=Object.keys(el).some(k=>k.startsWith('__reactProps$')||k.startsWith('__reactFiber$')); }catch(e){}
535
+ return {value,trackerValue,hasReactFiber};
536
+ })()`;
537
+ }
484
538
  function readExpr(selector) {
485
539
  return WALK + `(() => { const r=${selector ? `__baQuery(${JSON.stringify(selector)})` : `document.body`}; return r ? __baText(r) : ${selector ? `'(no element matches ' + ${JSON.stringify(selector)} + ')'` : `''`}; })()`;
486
540
  }
@@ -505,7 +559,8 @@ const snapshotCommand = define({
505
559
  consola.log(`# ${snap.title}\n# ${snap.url}\n# ${snap.count} interactive elements`);
506
560
  for (const el of snap.elements) {
507
561
  const label = el.type ? `${el.role}[${el.type}]` : el.role;
508
- consola.log(`${el.ref.padEnd(5)} ${label.padEnd(18)} ${el.name}`);
562
+ const st = el.state ? `[${el.state}] ` : "";
563
+ consola.log(`${el.ref.padEnd(5)} ${label.padEnd(18)} ${st}${el.name}`);
509
564
  }
510
565
  }
511
566
  });
@@ -537,6 +592,7 @@ const clickCommand = define({
537
592
  });
538
593
  //#endregion
539
594
  //#region src/commands/fill.ts
595
+ const SELECT_ALL_MOD = process.platform === "darwin" ? 4 : 2;
540
596
  const fillCommand = define({
541
597
  name: "fill",
542
598
  description: "Type a value into an input/textarea/contenteditable by ref",
@@ -546,6 +602,14 @@ const fillCommand = define({
546
602
  type: "boolean",
547
603
  description: "Submit the form after filling (requestSubmit / Enter)"
548
604
  },
605
+ native: {
606
+ type: "boolean",
607
+ description: "Use CDP Input.insertText for trusted keyboard events. Slower than the default JS-dispatched path, but reaches controlled React forms (RHF / Final Form / Formik Controller) that ignore synthetic input events."
608
+ },
609
+ verify: {
610
+ type: "boolean",
611
+ description: "After filling, re-read the field and warn if its DOM value diverges from the value passed, or if React's internal _valueTracker still holds the old value (signals controlled-form state stickiness — the next submit will serialize stale data)."
612
+ },
549
613
  ref: {
550
614
  type: "positional",
551
615
  description: "Element ref, e.g. e3"
@@ -566,12 +630,71 @@ const fillCommand = define({
566
630
  consola.error("A value is required");
567
631
  process.exit(1);
568
632
  }
569
- const r = await evaluate(await resolveExistingTargetId(targetOpts(ctx.values)), fillExpr(ref, value, ctx.values.submit ?? false));
570
- if (r.err) {
571
- consola.error(r.err);
572
- process.exit(1);
633
+ const targetId = await resolveExistingTargetId(targetOpts(ctx.values));
634
+ const native = ctx.values.native ?? false;
635
+ const submit = ctx.values.submit ?? false;
636
+ if (native) {
637
+ const focus = await evaluate(targetId, focusAndSelectExpr(ref));
638
+ if (focus.err) {
639
+ consola.error(focus.err);
640
+ process.exit(1);
641
+ }
642
+ await withPage(targetId, async (s) => {
643
+ await s.send("Input.dispatchKeyEvent", {
644
+ type: "rawKeyDown",
645
+ key: "a",
646
+ code: "KeyA",
647
+ windowsVirtualKeyCode: 65,
648
+ nativeVirtualKeyCode: 65,
649
+ modifiers: SELECT_ALL_MOD,
650
+ commands: ["selectAll"]
651
+ });
652
+ await s.send("Input.dispatchKeyEvent", {
653
+ type: "keyUp",
654
+ key: "a",
655
+ code: "KeyA",
656
+ windowsVirtualKeyCode: 65,
657
+ nativeVirtualKeyCode: 65,
658
+ modifiers: SELECT_ALL_MOD
659
+ });
660
+ await s.send("Input.insertText", { text: value });
661
+ if (submit) {
662
+ await s.send("Input.dispatchKeyEvent", {
663
+ type: "rawKeyDown",
664
+ key: "Enter",
665
+ code: "Enter",
666
+ windowsVirtualKeyCode: 13,
667
+ nativeVirtualKeyCode: 13
668
+ });
669
+ await s.send("Input.dispatchKeyEvent", {
670
+ type: "keyUp",
671
+ key: "Enter",
672
+ code: "Enter",
673
+ windowsVirtualKeyCode: 13,
674
+ nativeVirtualKeyCode: 13
675
+ });
676
+ }
677
+ });
678
+ } else {
679
+ const r = await evaluate(targetId, fillExpr(ref, value, submit));
680
+ if (r.err) {
681
+ consola.error(r.err);
682
+ process.exit(1);
683
+ }
684
+ }
685
+ if (ctx.values.verify) {
686
+ const v = await evaluate(targetId, readValueAndTrackerExpr(ref));
687
+ if (v.err) consola.warn(`verify failed to re-read field: ${v.err}`);
688
+ else {
689
+ const domMatches = v.value === value;
690
+ const trackerKnown = v.trackerValue !== null && v.trackerValue !== void 0;
691
+ const trackerMatches = !trackerKnown || v.trackerValue === value;
692
+ if (!domMatches) consola.warn(`verify: DOM value is "${v.value}" but you requested "${value}" — wrong element selected, or the page rewrote it.`);
693
+ else if (!trackerMatches) consola.warn(`verify: DOM shows "${value}" but React's _valueTracker still holds "${v.trackerValue}". The form library will likely submit the stale value. Try --native, or capture the form's PUT endpoint and call it directly (see SKILL.md "Controlled-form state stickiness").`);
694
+ else if (v.hasReactFiber && !trackerKnown && !native) consola.info(`verify: field has a React fiber but no _valueTracker — if the next submit serializes the old value, try --native.`);
695
+ }
573
696
  }
574
- consola.success(`filled ${ref} = "${r.value}"${ctx.values.submit ? " + submitted" : ""}`);
697
+ consola.success(`filled ${ref} = "${value}"${native ? " [native]" : ""}${submit ? " + submitted" : ""}`);
575
698
  }
576
699
  });
577
700
  //#endregion
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@generativereality/browser-automation",
3
- "version": "0.4.0",
3
+ "version": "0.4.1",
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": {
@@ -132,8 +132,46 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
132
132
  those refs for one action → re-snapshot. "ref not found" means re-snapshot.
133
133
  - **`isTrusted` / synthetic events.** Clicks and fills are JS-dispatched, so a
134
134
  small number of hard anti-bot or payment widgets that demand trusted events
135
- may ignore them. For those, escalate to a foregrounded native-input path
136
- (future `--native` flag) or have the user do that one step manually.
135
+ may ignore them. For fills, pass `--native` to drive character insertion
136
+ through CDP `Input.insertText` instead — that fires real (trusted)
137
+ `beforeinput`/`input` events. For clicks, escalate to a foregrounded
138
+ native-input path or have the user do that one step manually.
139
+ - **Controlled-form state stickiness.** Form libraries that subscribe to React's
140
+ internal value-setter (React Hook Form, Final Form, Formik with a `Controller`,
141
+ Blocket/finn.no's `recommerce` editor) sometimes ignore the synthetic `input`
142
+ event the default `fill` dispatches: the DOM input shows the new value, but
143
+ the form's React state stays on the old one — and the next submit serializes
144
+ the *old* value. Two ways out:
145
+ 1. **`fill --native --verify <ref> <value>`** — drives character insertion
146
+ through CDP `Input.insertText` (trusted events). `--verify` re-reads the
147
+ field afterwards and warns if either the DOM value diverged from what you
148
+ asked for, or if React's internal `_valueTracker` still holds the old
149
+ value (the canonical state-stickiness signature). Use this first; it
150
+ solves the vast majority of cases.
151
+ 2. **API bypass** — when even `--native` doesn't stick (e.g. the form library
152
+ binds to an external state machine that drives its own POST/PUT), grab the
153
+ form's underlying endpoint and hit it directly:
154
+ ```bash
155
+ # Hook fetch and persist a real form-submit's body + headers via localStorage
156
+ # (it survives the post-submit navigation, unlike window.* globals):
157
+ browser-automation eval -s app "(function(){var f=window.fetch;window.fetch=function(u,o){if(o&&o.method==='PUT'&&u.toString().includes('/api/item/')){localStorage.setItem('__lastPut',o.body||'');localStorage.setItem('__lastHdrs',JSON.stringify(o.headers||{}));}return f.apply(this,arguments);};})()"
158
+ # …then click Save once in the form so the hook captures the canonical PUT…
159
+ browser-automation eval -s app "({body:localStorage.getItem('__lastPut'),headers:localStorage.getItem('__lastHdrs')})"
160
+ # …gives you the endpoint, exact body shape, and custom headers
161
+ # (e.g. Blocket uses E-Tag, not the standard If-Match — and the etag lives
162
+ # in the JSON body, not the HTTP header).
163
+ ```
164
+ Then re-fetch the GET endpoint for current data + the current etag, PUT
165
+ directly with the modified field(s) and the captured custom header, and
166
+ **drive the form's terminal commit step through the UI** — many two-step
167
+ editors (`edit → delivery → publish`) only persist `state: "edit"`
168
+ server-side until that final Save fires the commit.
169
+
170
+ Blocket's recommerce price field is the canonical case: default `fill e43 "500"`
171
+ shows 500 in the input but submits 750. Fix: `fill --native --verify e43 "500"`
172
+ (or, if --native doesn't stick: direct PUT to
173
+ `/recommerce/create/api/item/<id>` with `E-Tag: <body.etag>`, then click
174
+ Save on the delivery page to commit).
137
175
  - **Cross-origin iframes are separate CDP targets.** `read`/`snapshot` see the
138
176
  page's own document and same-origin frames, not cross-origin iframes (common
139
177
  for SSO bank login widgets and embedded captchas). If the content you need
@@ -194,10 +232,14 @@ working around it forever**:
194
232
  selection). Add a command by creating `src/commands/x.ts` and registering it
195
233
  in `src/commands/index.ts`.
196
234
  3. **Validate locally** against the running Chrome:
197
- `npm install && npm run typecheck && npm run build`, then `npm link` (so the
198
- global `browser-automation` points at your build) — or run `node dist/index.js …`.
199
- Reproduce the failure, confirm the fix, and re-test on a scratch tab you
200
- created (read-only-safe; never disrupt the user's live tabs).
235
+ `npm install && npm run typecheck && npm run build`, then run your build as
236
+ **`node dist/index.js <cmd>`** from the clone. **Do NOT `npm link`** — it
237
+ repoints the machine-global `browser-automation` bin, so a parallel Claude
238
+ Code session (or the user's main session) would suddenly be running *your*
239
+ work-in-progress clone instead of the installed release. Validate via the
240
+ explicit `node dist/index.js` path instead. Reproduce the failure, confirm
241
+ the fix, and re-test on a scratch tab you created (read-only-safe; never
242
+ disrupt the user's live tabs).
201
243
  4. **Propose a PR** for the user to review and contribute upstream — don't
202
244
  publish yourself (the maintainer cuts releases):
203
245
  ```bash