@generativereality/browser-automation 0.4.0 → 0.4.2

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.2",
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.2";
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
  })()`;
@@ -451,6 +471,25 @@ function clickExpr(ref) {
451
471
  return {ok:true,tag:el.tagName.toLowerCase()};
452
472
  })()`;
453
473
  }
474
+ function actionabilityExpr(ref) {
475
+ const r = JSON.stringify(ref);
476
+ return WALK + `(() => {
477
+ const el=__baFind(${r});
478
+ if(!el)return {err:'ref not found: '+${r}+' (re-run snapshot)'};
479
+ el.scrollIntoView({block:'center',inline:'center'});
480
+ const b=el.getBoundingClientRect();
481
+ if(b.width===0&&b.height===0)return {err:'ref '+${r}+' has zero size / not visible'};
482
+ const vw=innerWidth,vh=innerHeight;
483
+ const x=Math.min(Math.max(b.left+b.width/2,1),vw-1);
484
+ const y=Math.min(Math.max(b.top+b.height/2,1),vh-1);
485
+ const root=el.getRootNode();
486
+ let top=(root&&root.elementFromPoint?root:document).elementFromPoint(x,y);
487
+ // descend through any shadow root under the point to find the deepest target
488
+ while(top&&top.shadowRoot){const inner=top.shadowRoot.elementFromPoint(x,y);if(!inner||inner===top)break;top=inner;}
489
+ const hit=!!top&&(top===el||el.contains(top)||(top.contains&&top.contains(el)));
490
+ return {ok:true,tag:el.tagName.toLowerCase(),x,y,hit};
491
+ })()`;
492
+ }
454
493
  function fillExpr(ref, value, submit) {
455
494
  const r = JSON.stringify(ref);
456
495
  const v = JSON.stringify(value);
@@ -481,6 +520,40 @@ function fillExpr(ref, value, submit) {
481
520
  return {ok:true,value:el.value!==undefined?String(el.value).slice(0,80):${v}};
482
521
  })()`;
483
522
  }
523
+ /** Focus + scroll an element by ref and select-all its existing value. Used by
524
+ * `fill --native`: the actual character insertion is then driven via CDP
525
+ * Input.insertText, which fires trusted events that controlled React forms
526
+ * (RHF, Final Form, Formik Controller) actually subscribe to. */
527
+ function focusAndSelectExpr(ref) {
528
+ const r = JSON.stringify(ref);
529
+ return WALK + `(() => {
530
+ const el=__baFind(${r});
531
+ if(!el)return {err:'ref not found: '+${r}+' (re-run snapshot)'};
532
+ el.scrollIntoView({block:'center',inline:'center'});
533
+ el.focus();
534
+ try{ if(typeof el.select==='function') el.select(); }catch(e){}
535
+ return {ok:true,tag:el.tagName.toLowerCase(),len:el.value!==undefined?String(el.value).length:0};
536
+ })()`;
537
+ }
538
+ /** Re-read an input/textarea/contenteditable's effective value AND, when present,
539
+ * React's internal `_valueTracker.getValue()` — which is what React's onChange
540
+ * fires on. A divergence between the two is the canonical signature of
541
+ * "DOM value set but React form-state stayed stale" (the controlled-form
542
+ * stickiness gotcha — see SKILL.md). Also reports whether a React fiber is
543
+ * attached at all, so callers can tell "controlled component" from "plain DOM". */
544
+ function readValueAndTrackerExpr(ref) {
545
+ const r = JSON.stringify(ref);
546
+ return WALK + `(() => {
547
+ const el=__baFind(${r});
548
+ if(!el)return {err:'ref not found: '+${r}+' (re-run snapshot)'};
549
+ const value=el.value!==undefined?String(el.value):(el.isContentEditable?(el.textContent||''):'');
550
+ let trackerValue=null;
551
+ try{ const t=el._valueTracker; if(t&&typeof t.getValue==='function') trackerValue=String(t.getValue()); }catch(e){}
552
+ let hasReactFiber=false;
553
+ try{ hasReactFiber=Object.keys(el).some(k=>k.startsWith('__reactProps$')||k.startsWith('__reactFiber$')); }catch(e){}
554
+ return {value,trackerValue,hasReactFiber};
555
+ })()`;
556
+ }
484
557
  function readExpr(selector) {
485
558
  return WALK + `(() => { const r=${selector ? `__baQuery(${JSON.stringify(selector)})` : `document.body`}; return r ? __baText(r) : ${selector ? `'(no element matches ' + ${JSON.stringify(selector)} + ')'` : `''`}; })()`;
486
559
  }
@@ -505,12 +578,14 @@ const snapshotCommand = define({
505
578
  consola.log(`# ${snap.title}\n# ${snap.url}\n# ${snap.count} interactive elements`);
506
579
  for (const el of snap.elements) {
507
580
  const label = el.type ? `${el.role}[${el.type}]` : el.role;
508
- consola.log(`${el.ref.padEnd(5)} ${label.padEnd(18)} ${el.name}`);
581
+ const st = el.state ? `[${el.state}] ` : "";
582
+ consola.log(`${el.ref.padEnd(5)} ${label.padEnd(18)} ${st}${el.name}`);
509
583
  }
510
584
  }
511
585
  });
512
586
  //#endregion
513
587
  //#region src/commands/click.ts
588
+ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
514
589
  const clickCommand = define({
515
590
  name: "click",
516
591
  description: "Click an element by ref (from the latest snapshot)",
@@ -519,6 +594,10 @@ const clickCommand = define({
519
594
  ref: {
520
595
  type: "positional",
521
596
  description: "Element ref, e.g. e7"
597
+ },
598
+ trusted: {
599
+ type: "boolean",
600
+ 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."
522
601
  }
523
602
  },
524
603
  async run(ctx) {
@@ -527,7 +606,93 @@ const clickCommand = define({
527
606
  consola.error("A ref like \"e7\" is required (run `browser-automation snapshot` first)");
528
607
  process.exit(1);
529
608
  }
530
- const r = await evaluate(await resolveExistingTargetId(targetOpts(ctx.values)), clickExpr(ref));
609
+ const targetId = await resolveExistingTargetId(targetOpts(ctx.values));
610
+ if (ctx.values.trusted ?? false) {
611
+ const trustedTag = await withPage(targetId, async (s) => {
612
+ const evalIn = async (expr) => {
613
+ const res = await s.send("Runtime.evaluate", {
614
+ expression: expr,
615
+ returnByValue: true,
616
+ awaitPromise: true
617
+ });
618
+ if (res.exceptionDetails) {
619
+ const e = res.exceptionDetails;
620
+ throw new Error("page JS exception: " + (e.exception?.description || e.text || "unknown"));
621
+ }
622
+ return res.result?.value;
623
+ };
624
+ await s.send("Page.bringToFront").catch(() => {});
625
+ const focusDeadline = Date.now() + 2e3;
626
+ while (Date.now() < focusDeadline) {
627
+ const f = await evalIn(`({f:document.hasFocus(),v:document.visibilityState})`);
628
+ if (f && f.f && f.v === "visible") break;
629
+ await sleep(50);
630
+ }
631
+ let prev = null;
632
+ let point = null;
633
+ let lastReason = "never became actionable";
634
+ const actDeadline = Date.now() + 5e3;
635
+ while (Date.now() < actDeadline) {
636
+ const a = await evalIn(actionabilityExpr(ref));
637
+ if (a?.err) {
638
+ consola.error(a.err);
639
+ process.exit(1);
640
+ }
641
+ const stable = prev !== null && Math.abs(prev.x - a.x) < .5 && Math.abs(prev.y - a.y) < .5;
642
+ if (a.hit && stable) {
643
+ point = {
644
+ x: a.x,
645
+ y: a.y,
646
+ tag: a.tag
647
+ };
648
+ break;
649
+ }
650
+ lastReason = a.hit ? "position not yet stable (still animating)" : "click-point occluded (hit-test miss)";
651
+ prev = {
652
+ x: a.x,
653
+ y: a.y
654
+ };
655
+ await sleep(60);
656
+ }
657
+ if (!point) {
658
+ consola.error(`<${ref}> not actionable for a trusted click: ${lastReason}`);
659
+ process.exit(1);
660
+ }
661
+ const { x, y } = point;
662
+ await s.send("Input.dispatchMouseEvent", {
663
+ type: "mouseMoved",
664
+ x,
665
+ y,
666
+ button: "none",
667
+ buttons: 0,
668
+ pointerType: "mouse"
669
+ });
670
+ await sleep(20);
671
+ await s.send("Input.dispatchMouseEvent", {
672
+ type: "mousePressed",
673
+ x,
674
+ y,
675
+ button: "left",
676
+ buttons: 1,
677
+ clickCount: 1,
678
+ pointerType: "mouse",
679
+ force: .5
680
+ });
681
+ await s.send("Input.dispatchMouseEvent", {
682
+ type: "mouseReleased",
683
+ x,
684
+ y,
685
+ button: "left",
686
+ buttons: 0,
687
+ clickCount: 1,
688
+ pointerType: "mouse"
689
+ });
690
+ return point.tag;
691
+ });
692
+ consola.success(`clicked ${ref} <${trustedTag}> (trusted)`);
693
+ return;
694
+ }
695
+ const r = await evaluate(targetId, clickExpr(ref));
531
696
  if (r.err) {
532
697
  consola.error(r.err);
533
698
  process.exit(1);
@@ -537,6 +702,7 @@ const clickCommand = define({
537
702
  });
538
703
  //#endregion
539
704
  //#region src/commands/fill.ts
705
+ const SELECT_ALL_MOD = process.platform === "darwin" ? 4 : 2;
540
706
  const fillCommand = define({
541
707
  name: "fill",
542
708
  description: "Type a value into an input/textarea/contenteditable by ref",
@@ -546,6 +712,14 @@ const fillCommand = define({
546
712
  type: "boolean",
547
713
  description: "Submit the form after filling (requestSubmit / Enter)"
548
714
  },
715
+ native: {
716
+ type: "boolean",
717
+ 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."
718
+ },
719
+ verify: {
720
+ type: "boolean",
721
+ 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)."
722
+ },
549
723
  ref: {
550
724
  type: "positional",
551
725
  description: "Element ref, e.g. e3"
@@ -566,12 +740,71 @@ const fillCommand = define({
566
740
  consola.error("A value is required");
567
741
  process.exit(1);
568
742
  }
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);
743
+ const targetId = await resolveExistingTargetId(targetOpts(ctx.values));
744
+ const native = ctx.values.native ?? false;
745
+ const submit = ctx.values.submit ?? false;
746
+ if (native) {
747
+ const focus = await evaluate(targetId, focusAndSelectExpr(ref));
748
+ if (focus.err) {
749
+ consola.error(focus.err);
750
+ process.exit(1);
751
+ }
752
+ await withPage(targetId, async (s) => {
753
+ await s.send("Input.dispatchKeyEvent", {
754
+ type: "rawKeyDown",
755
+ key: "a",
756
+ code: "KeyA",
757
+ windowsVirtualKeyCode: 65,
758
+ nativeVirtualKeyCode: 65,
759
+ modifiers: SELECT_ALL_MOD,
760
+ commands: ["selectAll"]
761
+ });
762
+ await s.send("Input.dispatchKeyEvent", {
763
+ type: "keyUp",
764
+ key: "a",
765
+ code: "KeyA",
766
+ windowsVirtualKeyCode: 65,
767
+ nativeVirtualKeyCode: 65,
768
+ modifiers: SELECT_ALL_MOD
769
+ });
770
+ await s.send("Input.insertText", { text: value });
771
+ if (submit) {
772
+ await s.send("Input.dispatchKeyEvent", {
773
+ type: "rawKeyDown",
774
+ key: "Enter",
775
+ code: "Enter",
776
+ windowsVirtualKeyCode: 13,
777
+ nativeVirtualKeyCode: 13
778
+ });
779
+ await s.send("Input.dispatchKeyEvent", {
780
+ type: "keyUp",
781
+ key: "Enter",
782
+ code: "Enter",
783
+ windowsVirtualKeyCode: 13,
784
+ nativeVirtualKeyCode: 13
785
+ });
786
+ }
787
+ });
788
+ } else {
789
+ const r = await evaluate(targetId, fillExpr(ref, value, submit));
790
+ if (r.err) {
791
+ consola.error(r.err);
792
+ process.exit(1);
793
+ }
794
+ }
795
+ if (ctx.values.verify) {
796
+ const v = await evaluate(targetId, readValueAndTrackerExpr(ref));
797
+ if (v.err) consola.warn(`verify failed to re-read field: ${v.err}`);
798
+ else {
799
+ const domMatches = v.value === value;
800
+ const trackerKnown = v.trackerValue !== null && v.trackerValue !== void 0;
801
+ const trackerMatches = !trackerKnown || v.trackerValue === value;
802
+ if (!domMatches) consola.warn(`verify: DOM value is "${v.value}" but you requested "${value}" — wrong element selected, or the page rewrote it.`);
803
+ 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").`);
804
+ 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.`);
805
+ }
573
806
  }
574
- consola.success(`filled ${ref} = "${r.value}"${ctx.values.submit ? " + submitted" : ""}`);
807
+ consola.success(`filled ${ref} = "${value}"${native ? " [native]" : ""}${submit ? " + submitted" : ""}`);
575
808
  }
576
809
  });
577
810
  //#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.2",
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