pawbrowse 0.6.1 → 0.6.3

package/README.md

@@ -19,6 +19,16 @@
 <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-server-blue.svg" alt="MCP"></a>
 </p>
 
+<p align="center">
+  <a href="assets/demo.mp4"><img src="assets/demo.gif" alt="A real Google Flights run at 1× speed: Zürich to London, the cheapest nonstop flight opened in 6.8 seconds, each targeted element highlighted with its ref" width="100%"></a>
+</p>
+
+<p align="center"><sub>
+A real run on live Google Flights at <b>1× speed</b> — every frame is the original screencast, the result is verified from the page itself.
+The plan is scripted, so this is PawBrowse's browser time only; your agent's thinking time comes on top.
+<a href="assets/demo.mp4">MP4</a> · reproduce with <code>node scripts/demo/record.mjs rec && python3 scripts/demo/render.py rec</code>
+</sub></p>
+
 PawBrowse is a **Chrome MV3 extension + a tiny zero-dependency MCP server** that lets your local
 AI coding agent (like **Claude Code**) read and act on your **actual, logged-in browser tabs** —
 your profile, your sessions, your open pages — with **no remote-debug port, no browser relaunch,
@@ -126,30 +136,27 @@ Tips:
 ## Benchmark
 
 <p align="center">
-  <img src="assets/pawbrowse-vs-claude-in-chrome.gif" alt="Real side-by-side recording: PawBrowse vs Claude-in-Chrome on the same task" width="100%">
+  <a href="assets/benchmark.mp4"><img src="assets/benchmark.gif" alt="Side-by-side recording on live Booking.com: the same agent searches a Lisbon hotel through PawBrowse (102.5 s, 8 tool calls) and through Claude in Chrome (112.9 s, 11 tool calls)" width="100%"></a>
 </p>
 
-<p align="center"><em>Real side-by-side screen recording — same task (3 Wikipedia section jumps), same brain (Claude). PawBrowse acts in one call per click and finishes first; Claude-in-Chrome perceives-then-clicks. Measured numbers below.</em></p>
-
-Because PawBrowse keeps **stable element refs** and its `navigate`/`act` already return the fresh
-table, the agent clicks a known target in **one** round trip. Screenshot/accessibility-tree drivers
-do **perceive-then-act** — a read (or screenshot) *then* a click — paying an extra agent round trip
-and a larger payload every action.
-
-Measured task: click 5 different section links on the same Wikipedia page, averaged, same machine,
-same agent (Claude):
+<p align="center"><sub>
+Same task on live Booking.com (Lisbon, Oct 20–22, free cancellation, open the first hotel), same agent (Claude), same real Chrome.
+Each run filmed from its own tab and timed from its first action; played at 8×, clocks in real time. <a href="assets/benchmark.mp4">MP4</a>
+</sub></p>
 
-| | PawBrowse | Claude-in-Chrome |
+| | PawBrowse | Claude in Chrome |
 | --- | --- | --- |
-| Calls per click | **1** (`act` by stable ref) | 2 (`read_page` → click) |
-| Avg wall-clock per click | **~7.6 s** | ~17.0 s |
-| Perception payload | compact, viewport-only | full a11y tree w/ URLs (up to 50 KB) |
-
-> **Honest caveat:** with Claude as the shared brain, absolute wall-clock is dominated by agent
-> latency and is noisy — treat the **~2.2× ratio** as the signal, not the exact seconds. The win is
-> *structural* (fewer round trips + smaller payloads), which also means fewer tokens per step. It's
-> **not** the sub-second speed of a small, dedicated click-picking model — PawBrowse trades that
-> raw speed for a smart, general brain (Claude) with no keys and no per-click cost.
+| Wall-clock (incl. the agent's thinking) | **102.5 s** | 112.9 s |
+| Tool calls | **8** (12 actions) | 11 (19 actions) |
+| Screenshots needed to check state | **0** — every call returns the page's fresh element table | 3 |
+| Surprises handled | sign-in popup reported ("element is disabled") and dismissed; new tab followed automatically | a filter click that silently didn't apply, caught from a screenshot and retried |
+
+> **Honest caveats:** most of the time on both sides is the agent thinking between calls, so the
+> wall-clock gap is modest. The structural signal is **fewer calls and no screenshots** — PawBrowse
+> returns the page's state with every action, so the agent never has to "look again". Run 2 (Claude in
+> Chrome) also started with Booking remembering run 1's destination and dates. One run each; treat it
+> as an illustration, not a statistic. Reproduce: `scripts/demo/peek-record.mjs` films a tab,
+> `scripts/demo/render_compare.py` renders the comparison.
 
 ## How it compares
 

package/extension/background.js

@@ -18,7 +18,8 @@ let ws = null;
 let reconnectTimer = null;
 
 // Per-session state. Each session drives its own tab(s) inside its own tab group.
-const attachedTabs = new Set();           // tabIds we currently hold a debugger on
+const attachedTabs = new Set();
+const peekOnly = new Set();               // tabs attached ONLY for dev frame capture (peek)           // tabIds we currently hold a debugger on
 const sessions = new Map();               // sessionId -> { activeTabId, createdTabs:Set, groupId, num, color }
 const tabOwner = new Map();               // tabId -> sessionId (so sessions don't steal each other's tabs)
 const chains = new Map();
@@ -288,7 +289,9 @@ chrome.debugger.onEvent.addListener((source, method, params) => {
   if (method === 'Page.javascriptDialogClosed') { openDialogs.delete(tabId); return; }
   if (method !== 'Page.javascriptDialogOpening') return;
   const pol = acting.get(tabId);
-  const where = source.sessionId ? { tabId, sessionId: source.sessionId } : tabId; // dialogs can come from frames
+  // Dialogs from any frame (incl. out-of-process iframes) are raised on — and answered via — the
+  // root session (Chromium routes them through the main frame's Page domain).
+  const where = tabId;
   if (!pol) { openDialogs.set(tabId, { type: params.type, message: params.message, where }); return; }
   const accept = pol.accept != null ? pol.accept : params.type === 'alert';
   const promptText = pol.text != null ? String(pol.text) : (params.defaultPrompt || '');
@@ -302,7 +305,16 @@ chrome.debugger.onEvent.addListener((source, method, params) => {
 async function whileActing(tabId, fn, policy) {
   const mine = { ...(policy || {}) };
   acting.set(tabId, mine);
-  try { return await fn(); } finally { if (acting.get(tabId) === mine) acting.delete(tabId); }
+  try { return await fn(); } finally {
+    // A dialog that pops up just AFTER the action (a follow-up alert once a confirm is answered) is
+    // still its consequence: keep answering with the default policy for a short while and report it
+    // with the next result, instead of leaving the page frozen for the next call.
+    if (acting.get(tabId) === mine) {
+      const linger = { linger: true };
+      acting.set(tabId, linger);
+      setTimeout(() => { if (acting.get(tabId) === linger) acting.delete(tabId); }, 1500);
+    }
+  }
 }
 
 function takeDialogLog(tabId) {
@@ -322,6 +334,7 @@ function assertNoOpenDialog(tabId) {
 chrome.tabs.onRemoved.addListener((tabId) => {
   attachedTabs.delete(tabId);
   forgetTab(tabId, true);
+  openedBy.delete(tabId);
   const owner = tabOwner.get(tabId);
   tabOwner.delete(tabId);
   if (owner != null) {
@@ -422,7 +435,11 @@ async function endSession(session) {
 const MO_INSTALL = `var M=window.__pawmo; if(!M){ M=window.__pawmo={last:performance.now(),times:[],roots:new WeakSet()};
   M.mo=new MutationObserver(function(){ var t=performance.now(); M.last=t; M.times.push(t); if(M.times.length>64) M.times.shift(); });
   M.watch=function(r){ if(!M.roots.has(r)){ M.roots.add(r); try{ M.mo.observe(r,{subtree:true,childList:true,attributes:true,characterData:true}); }catch(_){} } };
-  M.watch(document); }`;
+  M.watch(document);
+  // A busy main thread (parsing/running JS, rendering) is not "quiet" even when the DOM is still:
+  // SPA routes often mutate nothing for a few hundred ms and then render everything at once.
+  try{ new PerformanceObserver(function(l){ l.getEntries().forEach(function(e){ var end=e.startTime+e.duration; if(end>M.last) M.last=end; }); }).observe({type:'longtask', buffered:false}); }catch(_){}
+  }`;
 const SNAPSHOT = `(function(seed, opts){
   opts=opts||{};
   try{
@@ -472,7 +489,9 @@ const SNAPSHOT = `(function(seed, opts){
     // Visible descendants only: display:none / hidden children (tooltips, menus) must not leak in.
     // A rich-text editor's text is its VALUE, never its name (else typing into it renames it and
     // its ref is refused on the next action).
-    var txt = (tag==='INPUT'||tag==='SELECT'||tag==='TEXTAREA'||e.isContentEditable) ? '' : [].map.call(e.childNodes,function(n){ return n.nodeType===3 ? n.textContent : (n.nodeType===1 && visible(n) ? name(n,seen) : ''); }).join(' ').trim();
+    // A <slot> shows the nodes ASSIGNED to it (a web component's light-DOM label), not its children.
+    var kids = tag==='SLOT' ? ((e.assignedNodes && e.assignedNodes({flatten:true}).length) ? e.assignedNodes({flatten:true}) : e.childNodes) : e.childNodes;
+    var txt = (tag==='INPUT'||tag==='SELECT'||tag==='TEXTAREA'||e.isContentEditable) ? '' : [].map.call(kids,function(n){ return n.nodeType===3 ? n.textContent : (n.nodeType===1 && visible(n) ? name(n,seen) : ''); }).join(' ').trim();
     if(txt) return txt;
     return e.getAttribute('title')||e.getAttribute('placeholder')||e.getAttribute('aria-placeholder')||'';
   }
@@ -506,7 +525,7 @@ const SNAPSHOT = `(function(seed, opts){
   // Semantic controls + custom clickables: any contenteditable, an inline onclick, or a
   // keyboard-focusable [tabindex] (framework buttons — React-Native-Web Pressables, design-system
   // divs — often expose only these). cursor:pointer clickables are added separately in collect().
-  var selector='a[href],button,input,textarea,select,summary,[contenteditable]:not([contenteditable="false"]),[onclick],[tabindex]:not([tabindex="-1"]),[draggable="true"],'+roles.map(function(r){return '[role="'+r+'"]';}).join(',');
+  var selector='a[href],button,input,textarea,select,summary,[contenteditable]:not([contenteditable="false"]),[onclick],[onmousedown],[onmouseup],[onpointerdown],[onpointerup],[ondblclick],[tabindex]:not([tabindex="-1"]),[draggable="true"],'+roles.map(function(r){return '[role="'+r+'"]';}).join(',');
   // Inputs whose value is SET (not typed): typing into these is unreliable, so type() routes them
   // through a value setter. The hint tells the agent the expected format.
   var SETTABLE={date:'YYYY-MM-DD',time:'HH:MM','datetime-local':'YYYY-MM-DDTHH:MM',month:'YYYY-MM',week:'YYYY-Www',color:'#rrggbb',range:''};
@@ -529,13 +548,47 @@ const SNAPSHOT = `(function(seed, opts){
   }
   // Hit-test a frame-local point in the element's own root, descending into nested open shadow
   // roots, so a covered control (overlay, modal backdrop, pointer-events:none) is flagged.
+  // Is f (what is actually under the pointer) just the target's own visible content? Common
+  // pattern (Google results, cards): the accessible element sits UNDER a sibling that renders the
+  // row. Clicking there is what a person does. Not so for an empty overlay, a modal/fixed layer, a
+  // different control, or an ancestor of the target.
+  cache.sameWidget=function(t, f){
+    try{
+      if(!f || f===t || f.contains(t)) return false;
+      var p=t.parentElement, d=0; while(p && d<2 && !p.contains(f)){ p=p.parentElement; d++; }
+      if(!p || !p.contains(f) || p.tagName==='BODY' || p.tagName==='HTML') return false;
+      for(var a=f; a && a!==p; a=a.parentElement){
+        var cs=a.ownerDocument.defaultView.getComputedStyle(a);
+        if(cs.position==='fixed' || cs.position==='sticky') return false;
+        if(a.matches('a[href],button,input,select,textarea,[role=button],[role=link],[role=checkbox],[role=menuitem],[role=option],[role=tab]')) return false;
+      }
+      // A layer that CONTAINS other controls (a promo with its own button) is a different widget.
+      if(f.querySelector('a[href],button,input,select,textarea,[role=button],[role=link],[role=checkbox],[role=menuitem],[role=option],[role=tab]')) return false;
+      return !!((f.innerText||'').trim() || f.querySelector('img,svg') || /^(IMG|SVG)$/i.test(f.tagName));
+    }catch(_){ return false; }
+  };
+  // Where to point at an element: the centre of its box — except for an inline element that WRAPS
+  // (a link across two lines), whose box centre falls between the lines, on the surrounding text.
+  // Then use the centre of its first visible line box.
+  cache.pt=function(el){
+    var r=el.getBoundingClientRect(), rs=el.getClientRects(), v=el.ownerDocument.defaultView;
+    if(rs.length>1){ for(var i=0;i<rs.length;i++){ var q=rs[i]; if(q.width>=2 && q.height>=2 && q.bottom>0 && q.top<v.innerHeight) return {x:q.x+q.width/2, y:q.y+q.height/2, r:r}; } }
+    return {x:r.x+r.width/2, y:r.y+r.height/2, r:r};
+  };
+  // Pointing at a web component's SLOTTED text (its light-DOM label) makes the shadow root's
+  // elementFromPoint answer with the host: that's the control's own content, not a cover.
+  function slotted(t, f){ var rt=t.getRootNode(); return !!(rt && rt.host && f===rt.host && t.querySelector && t.querySelector('slot')); }
+  cache.slotted=slotted;
+  // Does a pointer event landing on f count as hitting t? (t itself or inside it, its label's control,
+  // its slotted content, or its own row content.) Used before AND during the click.
+  cache.accepts=function(t, f){ return !!f && (t===f || (f.nodeType===1 && t.contains(f)) || (t.control && t.control===f) || slotted(t, f) || cache.sameWidget(t, f)); };
   cache.hits=function(t, lx, ly){
     try{
-      if(lx==null){ var hr=t.getBoundingClientRect(); lx=hr.x+hr.width/2; ly=hr.y+hr.height/2; }
+      if(lx==null){ var hp=cache.pt(t); lx=hp.x; ly=hp.y; }
       var root=t.getRootNode(); if(!root.elementFromPoint) root=t.ownerDocument;
       var f=root.elementFromPoint(lx,ly), g=0;
       while(f && sroot(f) && g++<16){ var inner=sroot(f).elementFromPoint(lx,ly); if(!inner||inner===f) break; f=inner; }
-      return !!f && (t===f || t.contains(f) || (t.control && t.control===f));
+      return !!f && (t===f || t.contains(f) || (t.control && t.control===f) || slotted(t, f) || cache.sameWidget(t, f));
     }catch(_){ return true; }
   };
   var hits=cache.hits;
@@ -584,6 +637,8 @@ const SNAPSHOT = `(function(seed, opts){
         // systems) render as role-less <div>s but get cursor:pointer. Include the ROOT of each
         // pointer region (its parent is NOT pointer) so we capture the pressable itself, not its
         // inherited-cursor text children. Bounded scan so huge DOMs stay fast.
+        // <a> without href but with inline JS handlers (onmouseenter/onmousedown/...): JS-driven links.
+        if(!seen.has(n) && n.tagName==='A' && !n.hasAttribute('href')){ for(var ai=0;ai<n.attributes.length;ai++){ if(/^on(mouse|pointer|touch|click|dblclick|key)/.test(n.attributes[ai].name)){ add(n, dx, dy, true); break; } } }
         if(!seen.has(n) && scanned<8000){
           scanned++;
           try{
@@ -614,6 +669,23 @@ const SNAPSHOT = `(function(seed, opts){
     walk(document, 0, 0, 0);
     return out;
   }
+  // Not hittable, but only because a sticky/fixed bar (not a modal) or something OUTSIDE its own
+  // scroll box sits on top of it — e.g. a sidebar list scrolled under the sidebar's filter header.
+  // Acting scrolls it into the open, so it's "scrolled out", not "covered".
+  function reachable(t, lx, ly){
+    try{
+      var root=t.getRootNode(); if(!root.elementFromPoint) root=t.ownerDocument;
+      var f=root.elementFromPoint(lx,ly); if(!f || f.contains(t)) return false;
+      var view=t.ownerDocument.defaultView;
+      for(var a=f; a && a.nodeType===1; a=a.parentElement){
+        if(a.matches('dialog,[role=dialog],[role=alertdialog],[aria-modal=true]')) return false;
+        var cs=view.getComputedStyle(a);
+        if(cs.position==='fixed' || cs.position==='sticky'){ var q=a.getBoundingClientRect(); return q.width*q.height < 0.4*view.innerWidth*view.innerHeight; }
+      }
+      var sc=t.parentElement; while(sc && !(sc.scrollHeight>sc.clientHeight+2 && /(auto|scroll)/.test(view.getComputedStyle(sc).overflowY))) sc=sc.parentElement;
+      return !!sc && sc!==t.ownerDocument.body && sc!==t.ownerDocument.documentElement && !sc.contains(f);
+    }catch(_){ return false; }
+  }
   var scrollerCache=new Map(); // element -> does it clip its overflow? (one style read per ancestor per snapshot)
   function clipper(a, view){ var v=scrollerCache.get(a); if(v===undefined){ var cs=view.getComputedStyle(a); v=!(cs.overflowX==='visible' && cs.overflowY==='visible'); scrollerCache.set(a,v); } return v; }
   function clipped(t){
@@ -643,14 +715,14 @@ const SNAPSHOT = `(function(seed, opts){
       // Only accept it if it has a real label and isn't just a wrapper around an actual control
       // (or a <label> standing in for one), so we don't flood the table with layout containers.
       var ti=e.getAttribute('tabindex');
-      if(clk || e.hasAttribute('onclick') || (ti!==null && ti!=='-1') || e.getAttribute('draggable')==='true'){
+      if(clk || e.hasAttribute('onclick') || e.hasAttribute('onmousedown') || e.hasAttribute('onmouseup') || e.hasAttribute('onpointerdown') || e.hasAttribute('onpointerup') || e.hasAttribute('ondblclick') || (ti!==null && ti!=='-1') || e.getAttribute('draggable')==='true'){
         if(e.tagName==='LABEL' && e.control) continue;
         if(!(name(e)||'').trim() || e.querySelector(selector)) continue;
         rname='button';
       }
     }
     if(!rname) continue;
-    var r=surf.getBoundingClientRect(), lx=r.x+r.width/2, ly=r.y+r.height/2, x=lx+ox, y=ly+oy;
+    var sp=cache.pt(surf), r=sp.r, lx=sp.x, ly=sp.y, x=lx+ox, y=ly+oy;
     if(x<0||x>=VW) continue;
     if(rname==='gridcell' && e.querySelector('button,[role="button"]')) continue;
     var base={node:identity(e), role:rname, label:clean(fieldLabel(e)||hint(e)||rname), x:Math.round(x), y:Math.round(y), w:Math.round(r.width), h:Math.round(r.height)};
@@ -661,6 +733,18 @@ const SNAPSHOT = `(function(seed, opts){
     var asel=e.getAttribute('aria-selected'); if(asel!=null) base.selected=(asel==='true');
     if(e.required || e.getAttribute('aria-required')==='true') base.required=true;
     if(e.getAttribute('draggable')==='true') base.draggable=true;
+    // Site chrome (global header/nav — "Home", language picker, sign-in...) is real and stays
+    // clickable, just demoted to the end of the in-view rows so task content comes first.
+    try{ if(e.closest('nav,[role="navigation"]')) base.chrome=true; }catch(_){}
+    // Repeated links to the exact same destination (a card's photo, title, and "Opens X info"
+    // overlay often all point at the same URL): dedup key, hash dropped, bare "#"/javascript: skipped.
+    if(e.tagName==='A'){
+      // Same-PAGE hash-only hrefs ("#", "#1", "#panel-a") are cheap and collide across totally
+      // unrelated widgets (a sidebar's "#1" and a panel's "#1" resolve to the identical URL) — never
+      // dedup those. Only a link to a genuinely different page/resource is a safe, real duplicate.
+      var hattr=e.getAttribute('href')||'';
+      if(hattr && hattr.charAt(0)!=='#' && !/^javascript:/i.test(hattr)) base._dk=e.href;
+    }
     // Only surface validation errors on fields the user (or agent) has put a value in, or that the
     // page itself flags, so an untouched required form isn't a wall of warnings.
     if(e.getAttribute('aria-invalid')==='true') base.invalid='invalid';
@@ -675,6 +759,8 @@ const SNAPSHOT = `(function(seed, opts){
       base.off=y<0?'up':'down'; base.dist=y<0?-y:y-VH;
     } else if((function(){ var fv=surf.ownerDocument.defaultView; return fv!==window && (lx<0||ly<0||lx>=fv.innerWidth||ly>=fv.innerHeight); })()){
       base.off='scroll'; // scrolled out of its (same-origin) iframe's viewport
+    } else if(!hits(surf, lx, ly) && reachable(surf, lx, ly)){
+      base.off='scroll'; base.dist=1; // hidden under a sticky bar / a panel header: right here, scrolling brings it out
     } else if(!hits(surf, lx, ly)){
       // Not hittable: either scrolled out of an overflow container (reachable — acting scrolls it
       // in) or genuinely covered by an overlay/modal (needs dismissing first).
@@ -709,11 +795,77 @@ const SNAPSHOT = `(function(seed, opts){
   var omitted=Math.max(0, inView.length-250); inView.splice(250);
   // Keep the 25 off-screen controls NEAREST the visible area (not the first 25 in DOM order, which
   // for a scrolled list are the rows furthest behind), then restore page order.
-  var OFFCAP=opts.all?400:25;
+  var OFFCAP=opts.all?400:12; // default trimmed further: the nearest few off-screen rows are rarely the next target
   var offMore=Math.max(0, offView.length-OFFCAP)+farOff;
   if(offView.length>OFFCAP){ offView.forEach(function(a,k){ a.ord=k; }); offView.sort(function(a,b){ return a.dist-b.dist; }); offView.splice(OFFCAP); offView.sort(function(a,b){ return a.ord-b.ord; }); }
+  inView.sort(function(a,b){ return (a.chrome?1:0)-(b.chrome?1:0); }); // stable: keeps relative order within each group
   var actions=inView.concat(offView);
+  // Two rows with the IDENTICAL displayed label where one element contains the other, sitting at
+  // essentially the same spot, are the same control seen twice by our own heuristics — an outer
+  // clickable "cell" (aria-label="Tuesday, October 20, 2026") wrapping the real checkbox/radio/link
+  // with the same name inside it (a calendar day, a selectable list row). A small pixel tolerance
+  // absorbs the cell's own border/padding around an absolutely-positioned inner control. Keep the
+  // one with richer state (checked/selected/expanded) when only one side has it, else the innermost.
+  try{
+    var byLbl={};
+    actions.forEach(function(a){ var k=a.kind+'|'+a.label; (byLbl[k]=byLbl[k]||[]).push(a); });
+    var dropR=new Set();
+    Object.keys(byLbl).forEach(function(key){
+      var grp=byLbl[key]; if(grp.length<2) return;
+      for(var gi=0; gi<grp.length; gi++){
+        for(var gj=0; gj<grp.length; gj++){
+          if(gi===gj) continue;
+          var A=grp[gi], B=grp[gj]; if(dropR.has(A)||dropR.has(B)) continue;
+          var ea=cache.nodes.get(A.node), eb=cache.nodes.get(B.node);
+          if(!ea||!eb||ea===eb) continue;
+          var contains; try{ contains=eb.contains(ea); }catch(_){ contains=false; }
+          if(!contains) continue; // B is an ancestor of A, same label
+          if(Math.abs(A.x-B.x)>8 || Math.abs(A.y-B.y)>8) continue; // not the same visual spot: leave both
+          var richA=A.checked!=null||A.selected!=null||A.expanded!=null;
+          var richB=B.checked!=null||B.selected!=null||B.expanded!=null;
+          if(richB && !richA) dropR.add(A); else dropR.add(B); // prefer the innermost, unless only the ancestor carries state
+        }
+      }
+    });
+    if(dropR.size) actions=actions.filter(function(a){ return !dropR.has(a); });
+  }catch(_){}
+  // Repeated links to the same destination (see _dk above): keep the clearest copy (in view, not
+  // covered, shortest label), drop the rest.
+  try{
+    var byHref={};
+    actions.forEach(function(a){ if(a._dk) (byHref[a._dk]=byHref[a._dk]||[]).push(a); });
+    var dropH=new Set();
+    Object.keys(byHref).forEach(function(href){
+      var grp=byHref[href]; if(grp.length<2) return;
+      // Labels get combined below, so there's no information reason to prefer the shorter one —
+      // prefer the LARGER, more prominent element as the surviving click target's geometry instead
+      // (a tiny trailing ")" fragment next to a wide title link would otherwise become the anchor).
+      var score=function(a){ return (a.off?2:0)+(a.covered?2:0)-Math.min((a.w||0)*(a.h||0),40000)/40000; };
+      // Cluster by PROXIMITY first (a navbar shortcut and a hero CTA can legitimately share a
+      // destination while being two different, intentionally separate controls); only within the
+      // same small visual area is one of them a genuine repeat of the other.
+      var used=new Array(grp.length).fill(false);
+      for(var gi=0; gi<grp.length; gi++){
+        if(used[gi]) continue;
+        var cluster=[grp[gi]]; used[gi]=true;
+        for(var gj=gi+1; gj<grp.length; gj++){
+          if(used[gj]) continue;
+          if(Math.abs(grp[gi].x-grp[gj].x)<=200 && Math.abs(grp[gi].y-grp[gj].y)<=200){ cluster.push(grp[gj]); used[gj]=true; }
+        }
+        if(cluster.length<2) continue;
+        var keep=cluster.reduce(function(b,a){ return score(a)<score(b) ? a : b; });
+        // Different labels on the same destination ("7 hours ago" and "197 comments" both open the
+        // same story) each carry real information — combine them into the surviving row instead of
+        // silently discarding one, so the agent never loses "197 comments" for "7 hours ago".
+        var uniq=[]; cluster.forEach(function(a){ if(uniq.indexOf(a.label)<0) uniq.push(a.label); });
+        if(uniq.length>1) keep.label=clean(uniq.join(' · '),140);
+        cluster.forEach(function(a){ if(a!==keep) dropH.add(a); });
+      }
+    });
+    if(dropH.size) actions=actions.filter(function(a){ return !dropH.has(a); });
+  }catch(_){}
   // The nearest ancestor text that isn't just the label itself: which row/item a control is in.
+  cache.ctxOf=function(el, lab){ return ctxOf(el, lab); };
   function ctxOf(el, lab){
     for(var p=el&&el.parentElement, g=0; p && g<6 && p.tagName!=='BODY'; p=p.parentElement, g++){
       var tx=clean(p.innerText,400); if(!tx || tx===lab) continue;
@@ -1125,49 +1277,81 @@ async function observe(tabId, opts) {
 
 // Re-resolve a ref to its live element, re-check it, and hit-test the center
 // (elementFromPoint containment) so we never click a stale/covered/wrong target.
-async function resolveHit(tabId, ref, opts) {
+async function resolveHit(tabId, ref, opts, _retries) {
+  _retries = _retries || 0;
   const forFill = opts && opts.fill ? 'true' : 'false';
   const noScroll = opts && opts.noScroll ? 'true' : 'false', noHit = opts && opts.noHit ? 'true' : 'false';
+  const TXT = opts && opts.text != null ? JSON.stringify(String(opts.text)) : 'null';
   const R = JSON.stringify(String(ref));
-  return evaluate(tabId, `(function(){
+  const result = await evaluate(tabId, `(function(){
     var c=window.__pawbrowse; if(!c||!c.byId) return {error:'no snapshot yet; observe first'};
     if(c.byId[${R}]==null) return {error:'unknown ref (observe again)'};
     var e=c.get?c.get(${R}):null;
     if(!e||!e.isConnected) return {error:'element no longer on page (observe again)'};
     if(c.guard && c.guards && c.guards[${R}]!=null && c.guard(e)!==c.guards[${R}]) return {error:'element changed since observe (observe again)'};
+    // Same node, same label — but a different ROW? Virtualized lists recycle row elements for other
+    // items: "Delete" may now belong to someone else. The row context it was listed with must hold.
+    var fp=c.fps&&c.fps[${R}]; if(fp && fp.ctx && c.ctxOf && c.ctxOf(e, fp.label)!==fp.ctx) return {error:'the row this control belongs to changed since observe (now in "'+c.ctxOf(e, fp.label)+'"); observe again'};
     if(e.matches(':disabled')||e.closest('[aria-disabled="true"],[inert]')) return {error:'element is disabled'};
     if(${forFill} && (e.readOnly||e.getAttribute('aria-readonly')==='true')) return {error:'field is read-only'};
     if(${forFill} && !('value' in e) && !e.isContentEditable) return {error:'not an editable field (observe again)'};
+    // Typed text that the field would reject (email/number/url/pattern/maxlength) is refused up front:
+    // nothing is typed, instead of a value silently dropped or half-entered.
+    if(${forFill} && ${TXT}!==null && ${TXT}!=='' && e.tagName==='INPUT'){
+      var probe=e.cloneNode(); probe.value=${TXT};
+      if(['email','number','url'].indexOf(e.type)>=0 && (probe.value!==${TXT} || probe.validity.typeMismatch || probe.validity.badInput)) return {error:'"'+${TXT}+'" is not a valid '+e.type+' for this field (nothing typed)'};
+      if(e.hasAttribute('pattern') && probe.validity.patternMismatch) return {error:'the field requires a specific format ('+(e.title||e.getAttribute('pattern'))+'); "'+${TXT}+'" does not match (nothing typed)'};
+    }
     // Value-set inputs (date/time/range/color...) take the setter path, not click+type.
     if(${forFill} && e.tagName==='INPUT' && ['date','time','datetime-local','month','week','color','range'].indexOf(e.type)>=0) return {set:true};
     // Click the control's visible SURFACE: a styled checkbox's <label>, or the element itself.
     var s=c.surface?c.surface(e):e;
     if(!s) return {error:'element not visible'};
-    if(!${noScroll}) s.scrollIntoView({block:'center',inline:'center'});
-    var r=s.getBoundingClientRect(); if(!r.width||!r.height) return {error:'element has no size'};
-    // Frame-local center (in the element's own frame viewport)...
-    var lx=r.x+r.width/2, ly=r.y+r.height/2;
-    // ...plus the offset chain of any ancestor iframes, giving the TOP-LEVEL click point for CDP.
-    var dx=0, dy=0, w=(s.ownerDocument&&s.ownerDocument.defaultView), g=0;
-    while(w && w.frameElement && g++<12){
-      var fe=w.frameElement, fr=fe.getBoundingClientRect(), fcs=fe.ownerDocument.defaultView.getComputedStyle(fe);
-      dx+=fr.left+fe.clientLeft+(parseFloat(fcs.paddingLeft)||0);
-      dy+=fr.top+fe.clientTop+(parseFloat(fcs.paddingTop)||0);
-      w=fe.ownerDocument.defaultView;
-    }
-    var x=Math.round(lx+dx), y=Math.round(ly+dy);
-    if(x<0||y<0||x>=innerWidth||y>=innerHeight) return {error:'element off-screen after scroll'};
     // Hit-test in the surface's OWN root (document / shadow root / iframe doc) with frame-local
-    // coords, descending through nested open shadow roots, so shadow-DOM and iframe elements
-    // aren't falsely reported as covered.
-    if(${noHit}) return {x:x, y:y};
-    var root=s.getRootNode(); if(!root||!root.elementFromPoint) root=s.ownerDocument;
-    var f=root.elementFromPoint(lx,ly), k=0;
+    // coords, descending through nested open/closed shadow roots.
     var sroot=function(n){ return n.shadowRoot || (c.closed && c.closed.get(n)) || null; };
-    while(f && sroot(f) && k++<16){ var inner=sroot(f).elementFromPoint(lx,ly); if(!inner||inner===f) break; f=inner; }
-    if(!f || !(s===f || s.contains(f) || (s.control && s.control===f))) return {error:'element is covered by another element (dismiss the overlay/dialog first)'};
-    return {x:x, y:y};
+    var at=function(){
+      var r=s.getBoundingClientRect(); if(!r.width||!r.height) return {error:'element has no size'};
+      var fw=s.ownerDocument.defaultView;
+      var sp=c.pt?c.pt(s):{x:r.x+r.width/2, y:r.y+r.height/2}, lx=sp.x, ly=sp.y;
+      // ...plus the offset chain of any ancestor iframes, giving the TOP-LEVEL click point for CDP.
+      var dx=0, dy=0, w=fw, g=0;
+      while(w && w.frameElement && g++<12){
+        var fe=w.frameElement, fr=fe.getBoundingClientRect(), fcs=fe.ownerDocument.defaultView.getComputedStyle(fe);
+        dx+=fr.left+fe.clientLeft+(parseFloat(fcs.paddingLeft)||0);
+        dy+=fr.top+fe.clientTop+(parseFloat(fcs.paddingTop)||0);
+        w=fe.ownerDocument.defaultView;
+      }
+      var inView=ly>=0 && lx>=0 && ly<fw.innerHeight && lx<fw.innerWidth && (r.height>fw.innerHeight || (r.top>=0 && r.bottom<=fw.innerHeight));
+      var x=Math.round(lx+dx), y=Math.round(ly+dy);
+      var root=s.getRootNode(); if(!root||!root.elementFromPoint) root=s.ownerDocument;
+      var f=root.elementFromPoint(lx,ly), k=0;
+      while(f && sroot(f) && k++<16){ var inner=sroot(f).elementFromPoint(lx,ly); if(!inner||inner===f) break; f=inner; }
+      var hit=!!f && (s===f || s.contains(f) || (s.control && s.control===f) || (c.slotted && c.slotted(s, f)) || (c.sameWidget && c.sameWidget(s, f)));
+      return {x:x, y:y, inView:inView && x>=0 && y>=0 && x<innerWidth && y<innerHeight, hit:hit};
+    };
+    // Don't move the page when the target is already on screen and hittable: needless scrolling
+    // closes popups/date pickers and jolts the page. Otherwise bring it to the centre and re-check.
+    var p=at(); if(p.error) return p;
+    if(!(p.inView && p.hit) && !${noScroll}){ s.scrollIntoView({block:'center',inline:'center',behavior:'instant'}); p=at(); if(p.error) return p; }
+    if(!p.inView && !${noHit}) return {error:'element off-screen after scroll'};
+    if(${noHit}) return {x:p.x, y:p.y};
+    if(!p.hit) return {error:'element is covered by another element (dismiss the overlay/dialog first)'};
+    return {x:p.x, y:p.y};
   })()`);
+  // A ref the page-side cache no longer recognises (its map was rebuilt, this tab's world was
+  // recreated, or the element is mid-re-render from a JUST-PRIOR action — e.g. switching a
+  // code-language combobox remounts the code block, including its own "Expand code" button, a beat
+  // after the click that triggered it) is not necessarily gone: a fresh scan reruns the SAME
+  // "gone element -> matching new element" rebind snapshot() already does for re-renders. Up to two
+  // free retries with a short growing delay, transparent to the caller — costs nothing on success,
+  // and never hides a real "no longer on page" failure.
+  if(result && result.error === 'unknown ref (observe again)' && _retries < 2){
+    await sleep(_retries === 0 ? 120 : 300);
+    try { await snapshot(tabId, 1); } catch {}
+    return resolveHit(tabId, ref, opts, _retries + 1);
+  }
+  return result;
 }
 
 // Set the value of a date/time/month/week/color/range input the way a user's picker would: via the
@@ -1236,7 +1420,7 @@ async function centerOfText(tabId, text) {
     if(!pool.length) return null;
     pool.sort(function(a,b){return a.area-b.area;});
     var chosen=pool[0].el;
-    chosen.scrollIntoView({block:'center',inline:'center'});
+    chosen.scrollIntoView({block:'center',inline:'center',behavior:'instant'});
     var rr=chosen.getBoundingClientRect();
     var cx=Math.round(rr.left+rr.width/2), cy=Math.round(rr.top+rr.height/2);
     if(cx<0||cy<0||cx>=innerWidth||cy>=innerHeight) return null;
@@ -1247,12 +1431,18 @@ async function centerOfText(tabId, text) {
 
 async function clickAt(tabId, x, y, opts) {
   const button = (opts && opts.button) || 'left', count = Math.max(1, Math.min(3, Number(opts && opts.count) || 1));
-  await sendCdp(tabId, 'Input.dispatchMouseEvent', { type: 'mouseMoved', x, y });
-  // A double/triple click is successive press/release pairs with a rising clickCount.
+  // `buttons` must say which button is held (CDP defaults it to 0; pointer-event widgets ignore a
+  // pointerdown with no button). A double/triple click is press/release pairs with rising clickCount.
+  // Pipelined, like Playwright: move, press and release reach the renderer together. Awaiting each
+  // one leaves a gap in which a mousedown-triggered re-render (a blur committing a date, a ripple)
+  // swaps the element, and Chromium then sends the click to a common ancestor — or nowhere.
+  const held = { left: 1, right: 2, middle: 4 }[button];
+  const sends = [sendCdp(tabId, 'Input.dispatchMouseEvent', { type: 'mouseMoved', x, y })];
   for (let n = 1; n <= count; n++) {
-    await sendCdp(tabId, 'Input.dispatchMouseEvent', { type: 'mousePressed', x, y, button, clickCount: n });
-    await sendCdp(tabId, 'Input.dispatchMouseEvent', { type: 'mouseReleased', x, y, button, clickCount: n });
+    sends.push(sendCdp(tabId, 'Input.dispatchMouseEvent', { type: 'mousePressed', x, y, button, buttons: held, clickCount: n }));
+    sends.push(sendCdp(tabId, 'Input.dispatchMouseEvent', { type: 'mouseReleased', x, y, button, buttons: 0, clickCount: n }));
   }
+  await Promise.all(sends);
 }
 
 /* ------------------------------ Waiting (settle) ---------------------------- *
@@ -1263,10 +1453,11 @@ async function clickAt(tabId, x, y, opts) {
 const watches = new Map(); // tabId -> { mainFrame, inflight: Map(reqId -> startedAt), navStart, navDone }
 function tabWatch(tabId) {
   let w = watches.get(tabId);
-  if (!w) { w = { mainFrame: null, inflight: new Map(), navStart: 0, navDone: 0, committed: true, navReq: null }; watches.set(tabId, w); }
+  if (!w) { w = { mainFrame: null, inflight: new Map(), frameLoads: new Map(), navStart: 0, navDone: 0, committed: true, navReq: null }; watches.set(tabId, w); }
   return w;
 }
-const TRACKED = new Set(['Fetch', 'XHR', 'Document']);
+// Script too: SPA route changes lazy-load code chunks and render only after they run.
+const TRACKED = new Set(['Fetch', 'XHR', 'Document', 'Script']);
 chrome.debugger.onEvent.addListener((source, method, params) => {
   if (source.tabId == null) return;
   const w = watches.get(source.tabId);
@@ -1278,13 +1469,18 @@ chrome.debugger.onEvent.addListener((source, method, params) => {
     if (method === 'Network.loadingFailed' && params.requestId === w.navReq && !w.committed) w.navDone = Date.now(); // blocked/aborted navigation
     return;
   }
+  // Same for frames: an out-of-process iframe starts loading in the parent, stops in its own session.
+  if (method === 'Page.frameStoppedLoading' || method === 'Page.frameDetached') { w.frameLoads.delete(params.frameId); if (source.sessionId) return; }
   if (source.sessionId) return; // everything else: the top-level target only
   const now = Date.now();
   const begin = (loaderId) => { w.navStart = now; w.navDone = 0; w.committed = false; w.navReq = loaderId || null; w.netIdle = 0; };
   switch (method) {
     case 'Network.requestWillBeSent':
       // Documents: only the main frame's (subframe documents finish on other sessions / may never).
-      if (TRACKED.has(params.type) && (params.type !== 'Document' || params.frameId === w.mainFrame)) w.inflight.set(params.requestId, now);
+      if (TRACKED.has(params.type) && (params.type !== 'Document' || params.frameId === w.mainFrame)) {
+        w.inflight.set(params.requestId, now);
+        if (params.type === 'Script') w.lastScript = now; // a code chunk: the page is mid-transition
+      }
       if (params.type === 'Document' && params.frameId === w.mainFrame && params.requestId === params.loaderId && w.navReq !== params.requestId) {
         if (w.navDone >= w.navStart) begin(params.requestId); else w.navReq = params.requestId;
       }
@@ -1306,6 +1502,12 @@ chrome.debugger.onEvent.addListener((source, method, params) => {
       break;
     case 'Page.frameStoppedLoading':
       if (params.frameId === w.mainFrame && w.committed) w.navDone = now;
+      else w.frameLoads.delete(params.frameId);
+      break;
+    case 'Page.frameStartedLoading':
+      // An iframe (menu, widget, embed) that starts loading because of an action: its content is
+      // part of the result, so waits follow it (capped like requests).
+      if (params.frameId !== w.mainFrame) w.frameLoads.set(params.frameId, now);
       break;
     case 'Page.lifecycleEvent':
       // Tied to the NEW document's loader, so the old page's late events can't end a wait.
@@ -1314,7 +1516,11 @@ chrome.debugger.onEvent.addListener((source, method, params) => {
         if (params.name === 'networkAlmostIdle' || params.name === 'networkIdle') w.netIdle = now;
       }
       break;
-    case 'Page.downloadWillBegin': case 'Page.navigatedWithinDocument':
+    case 'Page.navigatedWithinDocument':
+      if (params.frameId === w.mainFrame) w.routeAt = now; // SPA route change (pushState)
+      w.navDone = now;
+      break;
+    case 'Page.downloadWillBegin':
       w.navDone = now;
       break;
   }
@@ -1324,7 +1530,13 @@ chrome.debugger.onEvent.addListener((source, method, params) => {
 const quietExpr = (since) => `(function(){ ${MO_INSTALL}
   var now=performance.now(), s=${Number(since) || 0}-Date.now()+now, b={};
   M.times.forEach(function(t){ if(t<s && t>=s-600) b[Math.floor((s-t)/100)]=1; });
-  return [now-M.last, Object.keys(b).length>=4];
+  // Finite CSS transitions/animations still running (a menu fading in, a panel sliding open):
+  // until they finish, their contents may still be invisible. Infinite ones (spinners) don't count.
+  // Those the ACTION started (startTime after it) are counted separately: they matter even on a page
+  // that animates constantly in the background (a panel's staggered entrance on a carousel page).
+  var anim=0, animNew=0;
+  try{ document.getAnimations().forEach(function(a){ if(a.playState==='running' && a.effect){ var ct=a.effect.getComputedTiming(); if(isFinite(ct.endTime) && ct.endTime<=2000){ anim++; if(a.startTime!=null && a.startTime>=s-30) animNew++; } } }); }catch(_){}
+  return [anim ? 0 : now-M.last, Object.keys(b).length>=4, animNew];
 })()`;
 
 // Network tracking only while an action is being watched (see attach()).
@@ -1392,14 +1604,27 @@ async function settle(tabId, capMs, since, opts) {
       if (!w.inflight.has(id)) { rel.delete(id); windowEnd = Math.max(windowEnd, now + 150); continue; } // finished: allow a follow-up
       if (now - w.inflight.get(id) < 8000) busy = true;
     }
+    for (const [fid, t] of w.frameLoads) {
+      if (now - t > 8000) { w.frameLoads.delete(fid); continue; }
+      if (t >= start - 50 && now - t < 2500) busy = true; // an embed/menu frame; ads shouldn't hold us long
+    }
     if (busy) { idleSince = 0; await sleep(30); continue; }
     if (now < grace) { await sleep(30); continue; } // debounce window: a request may still be coming
     if (!idleSince) idleSince = now;
-    let quiet = 1e9, ambient = false;
-    try { [quiet, ambient] = await evaluate(tabId, quietExpr(start)); } catch { await sleep(30); continue; } // document swapping
+    // A route change or a freshly loaded code chunk means a new view is being built: it often goes
+    // quiet for a beat (JS executing, timers) before rendering, so ask for a longer quiet period.
+    const transition = (w.routeAt || 0) >= start - 50 || (w.lastScript || 0) >= start - 50;
+    const needQuiet = transition ? 250 : 60, quietCap = transition ? 1500 : 600;
+    let quiet = 1e9, ambient = false, animNew = 0;
+    const tq = Date.now();
+    try { [quiet, ambient, animNew] = await evaluate(tabId, quietExpr(start)); } catch { await sleep(30); continue; } // document swapping
+    // If even this tiny probe waited >50ms to run, the page's main thread was busy (JS/render):
+    // not quiet, whatever the observers have reported so far.
+    if (Date.now() - tq > 50) quiet = 0;
     // DOM still changing: wait for 60ms of quiet, capped at 600ms after the network went idle, or
     // 120ms on a page that was already constantly mutating (clocks, tickers, carousels) before us.
-    if (quiet < 60 && now - idleSince < (ambient ? 120 : 600)) { await sleep(Math.max(10, 60 - quiet)); continue; }
+    if (animNew && now - idleSince < 1500) { await sleep(40); continue; } // the action's own animations
+    if (quiet < needQuiet && now - idleSince < (ambient ? 120 : quietCap)) { await sleep(Math.max(10, Math.min(60, needQuiet - quiet))); continue; }
     break;
   }
 }
@@ -1476,6 +1701,27 @@ async function pressKey(tabId, combo) {
   return null;
 }
 
+/* ------------------------- Tabs opened by an action -------------------------- *
+ * target=_blank links and window.open() open a NEW tab: the agent would otherwise keep looking at
+ * the old one and see "page did NOT change". A tab opened by the tab we're acting on is adopted
+ * into the session (and its group) and becomes the one we drive.                                */
+const openedBy = new Map(); // opener tabId -> newest tab it opened during an action
+chrome.tabs.onCreated.addListener((t) => { if (t.openerTabId != null && acting.has(t.openerTabId)) openedBy.set(t.openerTabId, t.id); });
+
+async function followNewTab(session, tabId) {
+  const nt = openedBy.get(tabId);
+  openedBy.delete(tabId);
+  if (nt == null) return null;
+  const s = sessionState(session);
+  s.activeTabId = nt; s.createdTabs.add(nt); tabOwner.set(nt, session); persistState();
+  await ensureGroup(s, nt);
+  // Let it get past about:blank and load, then read it like any navigation.
+  for (let i = 0; i < 50; i++) { try { const t = await chrome.tabs.get(nt); if (t.url && !/^about:blank/.test(t.url) && t.status === 'complete') break; } catch { return null; } await sleep(100); }
+  await attach(nt);
+  await settle(nt, 3000);
+  return nt;
+}
+
 /* ---------------------------------- WebMCP --------------------------------- *
  * Pages that implement WebMCP (navigator.modelContext.registerTool / <form toolname>) describe
  * their own actions with JSON schemas. Calling one is a single deterministic step instead of a
@@ -1536,6 +1782,58 @@ async function invokeTool(tabId, name, input) {
   return `tool ${name}: ${res.status}${res.errorText ? ` (${res.errorText})` : ''}${out ? `\n    output (untrusted page data): ${out.slice(0, 2000).replace(/\n/g, '\n    ')}` : ''}`;
 }
 
+// Wait until the target's box stops moving (an animation, a sliding panel) before clicking it —
+// Playwright's "stable" check. Capped: a forever-spinning element is clicked anyway.
+async function waitStable(target, ref) {
+  const R = JSON.stringify(String(ref));
+  try {
+    await evaluate(target, `new Promise(function(res){
+      var c=window.__pawbrowse, e=c&&c.get&&c.get(${R}), s=e&&(c.surface?c.surface(e):e); if(!s) return res(0);
+      var key=function(){ var r=s.getBoundingClientRect(); return [r.x,r.y,r.width,r.height].map(Math.round).join(','); };
+      // Moving = its box changed, or a finite animation is still running on it or an ancestor (an
+      // orbit/slide can pause at its turning points, which looks "stable" for a frame or two).
+      var animating=function(){ try{ for(var a=s,g=0;a&&g<8;a=a.parentElement,g++){ var an=a.getAnimations?a.getAnimations():[]; for(var i=0;i<an.length;i++){ var ct=an[i].effect&&an[i].effect.getComputedTiming(); if(an[i].playState==='running' && ct && isFinite(ct.endTime)) return true; } } }catch(_){} return false; };
+      // Fast path: nothing animating and the box unchanged over one frame -> go. Once it has been seen
+      // moving, require two quiet frames in a row.
+      // Nothing animating on it or its ancestors: click now (no frame wait). JS-driven motion is
+      // still caught by the click-time hit check.
+      if(!animating()) return res(1);
+      var last=key(), same=0, moved=true, t0=performance.now();
+      (function tick(){ setTimeout(function(){ var k=key(), an=animating(); if(k===last && !an){ if(++same>=(moved?2:1)) return res(1); } else { same=0; last=k; moved=true; } if(performance.now()-t0>6000) return res(0); tick(); }, 16); })();
+    })`);
+  } catch {}
+}
+
+// Click-time hit check (Playwright's hit-target interceptor): the FIRST trusted pointer/mouse event
+// of the click must land on the intended element (or what counts as it). If it would land on
+// something else — an overlay that appeared, a re-render — the whole gesture is stopped before the
+// wrong element sees it, and the op reports what intercepted it.
+async function armClick(target, ref) {
+  const R = JSON.stringify(String(ref));
+  return evaluate(target, `(function(){
+    var c=window.__pawbrowse, e=c&&c.get&&c.get(${R}), s=e&&(c.surface?c.surface(e):e); if(!s||!c.accepts) return false;
+    if(c.__arm) c.__arm.off();
+    var st={ok:null, by:null}, types=['pointerdown','mousedown','pointerup','mouseup','click','auxclick','dblclick','contextmenu'];
+    var hosted=function(f){ for(var r=s.getRootNode(); r && r.host; r=r.host.getRootNode()){ if(r.host===f) return true; } return false; };
+    // The page REPLACED the target during the gesture (re-render on hover/mousedown): the new element
+    // with the same identity (role + label) is the same control to a user.
+    var want=c.guard?c.guard(e):'', replaced=function(f){ if(s.isConnected&&e.isConnected) return false; for(var a=f,g=0;a&&g<6;a=a.parentElement,g++){ if(want && c.guard(a)===want) return true; } return false; };
+    var h=function(ev){
+      if(!ev.isTrusted) return;
+      if(st.ok===null){ var f=(ev.composedPath&&ev.composedPath()[0])||ev.target; if(f && f.nodeType!==1) f=f.parentElement;
+        st.ok = c.accepts(s,f) || hosted(f) || (e!==s && c.accepts(e,f)) || replaced(f);
+        if(!st.ok) st.by = f ? (f.tagName.toLowerCase()+(f.id?'#'+f.id:'')+' "'+String(f.innerText||f.getAttribute('aria-label')||'').trim().replace(/\\s+/g,' ').slice(0,40)+'"') : 'nothing'; }
+      if(st.ok===false){ ev.preventDefault(); ev.stopImmediatePropagation(); }
+    };
+    types.forEach(function(t){ window.addEventListener(t, h, true); });
+    c.__arm={st:st, off:function(){ types.forEach(function(t){ window.removeEventListener(t, h, true); }); c.__arm=null; }};
+    return true;
+  })()`).catch(() => false);
+}
+async function disarmClick(target) {
+  return evaluate(target, `(function(){ var c=window.__pawbrowse, a=c&&c.__arm; if(!a) return null; var st=a.st; a.off(); return st; })()`).catch(() => null);
+}
+
 const dragIntercepts = new Map(); // tabId -> drag data captured by Input.dragIntercepted
 chrome.debugger.onEvent.addListener((source, method, params) => {
   if (method === 'Input.dragIntercepted' && source.tabId != null) dragIntercepts.set(source.tabId, params.data);
@@ -1600,12 +1898,16 @@ async function runOp(tabId, op) {
       return `dialog: ${d.type} "${String(d.message || '').slice(0, 120)}" → ${op.accept ? 'accepted' : 'dismissed'}`;
     }
     case 'click': {
+      await waitStable(T, REF);
       const r = await resolveHit(T, REF);
       if (r.error) return `${op.ref}: ${r.error}`;
       const p = await top(r.x, r.y);
       if (p.covered) return `${op.ref}: element is covered by another element of the page around its frame (dismiss the overlay first)`;
       const button = ['right', 'middle'].includes(op.button) ? op.button : 'left';
+      const armed = await armClick(T, REF);
       await clickAt(tabId, p.x, p.y, { button, count: op.count });
+      const verdict = armed ? await disarmClick(T) : null;
+      if (verdict && verdict.ok === false) return `${op.ref}: click intercepted by ${verdict.by} at the moment of the click — NOT delivered (dismiss what covers it, then retry)`;
       return `${op.count > 1 ? `${op.count}x ` : ''}${button !== 'left' ? `${button}-` : ''}click ${op.ref}`;
     }
     case 'hover': {
@@ -1643,7 +1945,7 @@ async function runOp(tabId, op) {
       return `click_text "${op.text}"`;
     }
     case 'type': {
-      const r = await resolveHit(T, REF, { fill: true });
+      const r = await resolveHit(T, REF, { fill: true, text: op.text ?? '' });
       if (r.error) return `${op.ref}: ${r.error}`;
       if (r.set) {
         const sv = await setValue(T, REF, op.text);
@@ -1697,6 +1999,19 @@ async function runOp(tabId, op) {
       const u = await uploadFiles(T, REF, paths);
       return u.error ? `${op.ref}: ${u.error}` : `upload ${op.ref} (${paths.length} file${paths.length > 1 ? 's' : ''})`;
     }
+    case 'back': case 'forward': {
+      const { currentIndex, entries } = await sendCdp(tabId, 'Page.getNavigationHistory');
+      const to = entries[currentIndex + (op.op === 'back' ? -1 : 1)];
+      if (!to) return `${op.op}: no ${op.op === 'back' ? 'previous' : 'next'} page in this tab's history`;
+      const w = tabWatch(tabId); w.navStart = Date.now(); w.navDone = 0; w.committed = false; w.navReq = null;
+      await sendCdp(tabId, 'Page.navigateToHistoryEntry', { entryId: to.id });
+      return `${op.op} → ${String(to.url).slice(0, 100)}`;
+    }
+    case 'reload': {
+      const w = tabWatch(tabId); w.navStart = Date.now(); w.navDone = 0; w.committed = false; w.navReq = null;
+      await sendCdp(tabId, 'Page.reload', {});
+      return 'reload';
+    }
     case 'click_xy': {
       // Coordinates from the last browser_screenshot image (converted to CSS px).
       const k = shotScale.get(tabId) || 1;
@@ -1857,7 +2172,9 @@ async function handleCommand(cmd, args, token, session) {
       const tabId = await resolveTabId(session, args, 'inspect');
       await attach(tabId);
       assertNoOpenDialog(tabId);
-      return observe(tabId, args);
+      const t = await observe(tabId, args);
+      const dl = takeDialogLog(tabId);
+      return dl ? `${dl}\n${t}` : t;
     }
     case 'read': {
       const tabId = await resolveTabId(session, args, 'inspect');
@@ -1907,6 +2224,11 @@ async function handleCommand(cmd, args, token, session) {
         // the caller think they failed and retry them.
         let table;
         try { table = await observe(tabId); } catch { table = null; }
+        const nt = await followNewTab(session, tabId).catch(() => null);
+        if (nt != null) {
+          const t2 = await observe(nt).catch(() => '(new tab not readable yet: observe next)');
+          return `ran ${ops.length} op(s) [page changed]:\n${logLines.join('\n')}\n${takeDialogLog(tabId)}  → the page opened a NEW TAB (tab ${nt}); now driving it (the previous tab ${tabId} is left open)\n\n${t2}`;
+        }
         const changed = before == null || after == null || before !== after || table == null || seen == null || tableBody(table) !== seen || dialogLog.has(tabId);
         const note = changed ? 'page changed' : 'page did NOT change (if you expected an effect, the action may not have worked — try a different target)';
         if (table == null) {
@@ -1915,6 +2237,25 @@ async function handleCommand(cmd, args, token, session) {
         return `ran ${ops.length} op(s) [${note}]:\n${logLines.join('\n')}\n${takeDialogLog(tabId)}\n${(changed && deltaTable(seenFull, table)) || table}`;
       });
     }
+    case 'peek': {
+      // Dev-only frame capture for recordings: screenshot ANY tab by id without adopting it into a
+      // session, grouping it, or enabling domains on it (so another tool driving that tab — e.g. for
+      // a side-by-side benchmark — is not disturbed). Attaches the debugger only if needed.
+      const tabId = Number(args.tabId);
+      let t; try { t = await chrome.tabs.get(tabId); } catch { throw new Error(`tab ${args.tabId} not found`); }
+      if (restrictedPage(t.url)) throw new Error('that tab is a browser page that cannot be captured');
+      if (!attachedTabs.has(tabId)) {
+        await new Promise((res, rej) => chrome.debugger.attach({ tabId }, '1.3', () => { const e = chrome.runtime.lastError; if (e && !/already attached/i.test(e.message)) rej(new Error(e.message)); else res(); }));
+        peekOnly.add(tabId);
+      }
+      const q = Math.max(20, Math.min(90, Number(args.quality) || 60));
+      const shot = await sendCdp(tabId, 'Page.captureScreenshot', { format: 'jpeg', quality: q });
+      return { data: shot.data, t: Date.now(), url: t.url };
+    }
+    case 'peek_end': {
+      for (const id of [...peekOnly]) { peekOnly.delete(id); if (!attachedTabs.has(id)) await new Promise((r) => chrome.debugger.detach({ tabId: id }, () => { void chrome.runtime.lastError; r(); })); }
+      return { ok: true };
+    }
     case 'screenshot': {
       const tabId = await resolveTabId(session, args, 'inspect');
       await attach(tabId);

package/extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "PawBrowse",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "Let your AI agent (Claude Code) drive your real Chrome. Fast element-table control. Open source, no keys.",
   "minimum_chrome_version": "125",
   "permissions": [

package/mcp/server.mjs

@@ -19,6 +19,7 @@ import path from 'node:path';
 import crypto from 'node:crypto';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
+import fs from 'node:fs';
 
 const posInt = (v, d) => { const n = Number(v); return Number.isFinite(n) && n > 0 ? Math.floor(n) : d; };
 const PORT = posInt(process.env.PAWBROWSE_PORT, 10577);
@@ -32,6 +33,26 @@ function brokerSock(port) {
 const SOCK = brokerSock(PORT);
 const BROKER_PATH = fileURLToPath(new URL('./broker.mjs', import.meta.url));
 // A stable-ish, unique session id per server process (also names this session's tab group).
+// Uploads: only files under these roots (default: the client's working directory, temp, Downloads,
+// Desktop; override with PAWBROWSE_UPLOAD_ROOTS, path-list separated). Hidden files/folders
+// (~/.ssh, .env, .aws …) are refused even inside a root — a page must never be able to talk the
+// agent into uploading secrets.
+const UPLOAD_ROOTS = (process.env.PAWBROWSE_UPLOAD_ROOTS
+  ? process.env.PAWBROWSE_UPLOAD_ROOTS.split(path.delimiter)
+  : [process.cwd(), os.tmpdir(), path.join(os.homedir(), 'Downloads'), path.join(os.homedir(), 'Desktop')])
+  .filter(Boolean).map((r) => { try { return fs.realpathSync(r); } catch { return null; } }).filter(Boolean);
+
+function checkUploadPath(p) {
+  if (typeof p !== 'string' || !p.trim()) throw new Error('upload: empty path');
+  let real;
+  try { real = fs.realpathSync(path.resolve(p)); } catch { throw new Error(`upload: no such file: ${p}`); }
+  if (!fs.statSync(real).isFile()) throw new Error(`upload: not a file: ${p}`);
+  const root = UPLOAD_ROOTS.find((r) => real === r || real.startsWith(r + path.sep));
+  if (!root) throw new Error(`upload: ${p} is outside the allowed folders (${UPLOAD_ROOTS.join(', ')}). Set PAWBROWSE_UPLOAD_ROOTS to allow another folder.`);
+  if (path.relative(root, real).split(path.sep).some((seg) => seg.startsWith('.'))) throw new Error(`upload: refusing hidden file or folder: ${p}`);
+  return real;
+}
+
 const SESSION = process.env.PAWBROWSE_SESSION || `s${process.pid}-${crypto.randomBytes(3).toString('hex')}`;
 
 const log = (...a) => process.stderr.write(`[pawbrowse] ${a.join(' ')}\n`);
@@ -172,7 +193,7 @@ const TOOLS = [
   },
   {
     name: 'browser_act',
-    description: 'Run a list of operations on the target tab in order, then return the fresh element table — or, when the page is the same and mostly unchanged, only its new/changed rows plus the refs that are gone (refs you already hold stay valid; unchanged rows are omitted, and browser_observe returns the full table). The result says whether the page changed — if it did NOT change when you expected an effect, the action likely missed; pick a different target rather than repeating. ops: [{op:"click",ref:"e12"} (add count:2 for double-click, button:"right" for a context menu) | {op:"hover",ref:"e3"} (open hover menus/tooltips) | {op:"drag",ref:"e4",to:"e9"|to_text:"Done column"|dx:120,dy:0} (drag-and-drop, sliders, sortable lists) | {op:"click_text",text:"Built with Claude"} (click the most specific visible element matching text, for custom widgets/menus not in the table) | {op:"type",ref:"e7",text:"..."} | {op:"select",ref:"e8",value:"..."} | {op:"key",key:"Enter"} (any key or chord: "Tab", "Shift+Tab", "Escape", "PageDown", "Mod+a" = Cmd/Ctrl+A, "Control+Enter", a single character) | {op:"upload",ref:"e5",paths:["/abs/file.pdf"]} | {op:"scroll",dy:600} (add ref:"e30" to scroll the box/panel containing that control instead of the page) | {op:"tool",name:"add_to_cart",input:{...}} (call a tool the page itself offers via WebMCP — listed under "page tools" in the table; prefer it over clicking when one fits) | {op:"click_xy",x:340,y:120} (click at a point of the last browser_screenshot image — for canvas apps and things the table lacks) | {op:"wait",ms:500} | {op:"dialog",accept:true,text?:"..."} (answer an alert/confirm/prompt already open)]. JS dialogs raised by an op are answered automatically — alerts accepted, confirm/prompt DISMISSED — and reported; add dialog:"accept" (and dialog_text:"..." for a prompt) to an op to accept instead, only when the user intends it (e.g. a confirmed delete). Tips: a typed search query still needs its matching autocomplete suggestion clicked; set each requested filter explicitly (a matching-looking result alone does not prove a filter was applied); do not re-toggle a checkbox/switch/radio already in the wanted state, and do not re-type into a fill field that already shows the wanted value (the ▸ current value tells you); submit a populated search before opening a result; use wait only when the needed control is absent/disabled or results are still loading — if Submit/Search is ready, click it instead, and a recent wait is not evidence of loading.',
+    description: 'Run a list of operations on the target tab in order, then return the fresh element table — or, when the page is the same and mostly unchanged, only its new/changed rows plus the refs that are gone (refs you already hold stay valid; unchanged rows are omitted, and browser_observe returns the full table). The result says whether the page changed — if it did NOT change when you expected an effect, the action likely missed; pick a different target rather than repeating. ops: [{op:"click",ref:"e12"} (add count:2 for double-click, button:"right" for a context menu) | {op:"hover",ref:"e3"} (open hover menus/tooltips) | {op:"drag",ref:"e4",to:"e9"|to_text:"Done column"|dx:120,dy:0} (drag-and-drop, sliders, sortable lists) | {op:"click_text",text:"Built with Claude"} (click the most specific visible element matching text, for custom widgets/menus not in the table) | {op:"type",ref:"e7",text:"..."} | {op:"select",ref:"e8",value:"..."} | {op:"key",key:"Enter"} (any key or chord: "Tab", "Shift+Tab", "Escape", "PageDown", "Mod+a" = Cmd/Ctrl+A, "Control+Enter", a single character) | {op:"upload",ref:"e5",paths:["/abs/file.pdf"]} (only files under the working directory, temp, Downloads or Desktop unless PAWBROWSE_UPLOAD_ROOTS says otherwise; hidden files are always refused) | {op:"scroll",dy:600} (add ref:"e30" to scroll the box/panel containing that control instead of the page) | {op:"tool",name:"add_to_cart",input:{...}} (call a tool the page itself offers via WebMCP — listed under "page tools" in the table; prefer it over clicking when one fits) | {op:"click_xy",x:340,y:120} (click at a point of the last browser_screenshot image — for canvas apps and things the table lacks) | {op:"back"} | {op:"forward"} | {op:"reload"} | {op:"wait",ms:500} | {op:"dialog",accept:true,text?:"..."} (answer an alert/confirm/prompt already open)]. A link or script that opens a NEW TAB is followed: the result says so and shows the new tab, which becomes the one you drive. Values a field would reject (bad email/number/url, pattern mismatch) are refused before typing. JS dialogs raised by an op are answered automatically — alerts accepted, confirm/prompt DISMISSED — and reported; add dialog:"accept" (and dialog_text:"..." for a prompt) to an op to accept instead, only when the user intends it (e.g. a confirmed delete). Tips: a typed search query still needs its matching autocomplete suggestion clicked; set each requested filter explicitly (a matching-looking result alone does not prove a filter was applied); do not re-toggle a checkbox/switch/radio already in the wanted state, and do not re-type into a fill field that already shows the wanted value (the ▸ current value tells you); submit a populated search before opening a result; use wait only when the needed control is absent/disabled or results are still loading — if Submit/Search is ready, click it instead, and a recent wait is not evidence of loading.',
     inputSchema: { type: 'object', properties: { ops: { type: 'array', items: { type: 'object' } }, tabId: { type: 'number' } }, required: ['ops'] },
     annotations: { title: 'Act on page (click/type/select/scroll)', readOnlyHint: false, destructiveHint: true, openWorldHint: true },
   },
@@ -190,6 +211,16 @@ const TOOLS = [
   },
 ];
 
+// Dev-only tools (recording benchmarks): hidden unless PAWBROWSE_DEV_TOOLS=1.
+if (process.env.PAWBROWSE_DEV_TOOLS === '1') {
+  TOOLS.push({
+    name: 'browser_peek',
+    description: 'DEV: screenshot any tab by id (JPEG base64 + capture time) without adopting or changing it. For recording side-by-side benchmarks.',
+    inputSchema: { type: 'object', properties: { tabId: { type: 'number' }, quality: { type: 'number' }, end: { type: 'boolean' } } },
+    annotations: { title: 'Peek at a tab (dev)', readOnlyHint: true, openWorldHint: true },
+  });
+}
+
 function textResult(obj) {
   const text = typeof obj === 'string' ? obj : JSON.stringify(obj, null, 2);
   return { content: [{ type: 'text', text }] };
@@ -208,8 +239,18 @@ async function callTool(name, args) {
     case 'browser_navigate':return textResult(await callExtension('navigate', args));
     case 'browser_observe': return textResult(await callExtension('observe', args));
     case 'browser_read':    return textResult(await callExtension('read', args));
-    case 'browser_act':     return textResult(await callExtension('act', args));
+    case 'browser_act': {
+      // Enforce the upload policy here: the extension can't see the filesystem, the server can.
+      for (const op of (args && Array.isArray(args.ops) ? args.ops : [])) {
+        if (op && op.op === 'upload') op.paths = [].concat(op.paths ?? op.path ?? []).map(checkUploadPath);
+      }
+      return textResult(await callExtension('act', args));
+    }
     case 'browser_assert':  return textResult(await callExtension('assert', args));
+    case 'browser_peek': {
+      if (process.env.PAWBROWSE_DEV_TOOLS !== '1') throw new Error('unknown tool: browser_peek');
+      return textResult(await callExtension(args.end ? 'peek_end' : 'peek', args));
+    }
     case 'browser_screenshot': {
       const r = await callExtension('screenshot', args);
       return { content: [{ type: 'image', data: r.data, mimeType: r.mimeType }, { type: 'text', text: r.note }] };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pawbrowse",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "Let Claude Code drive your real, logged-in Chrome. A zero-dependency MCP server + a Chrome MV3 extension that uses element-table perception over CDP. The calling agent is the policy: no second model, no API keys, page snapshots never leave for a third party.",
   "type": "module",
   "bin": {
@@ -9,7 +9,7 @@
   "scripts": {
     "start": "node mcp/server.mjs",
     "test": "node --test --test-timeout=15000 --test-force-exit test/*.test.mjs",
-    "test:e2e": "node --test --test-timeout=60000 --test-concurrency=1 test/e2e/*.e2e.mjs"
+    "test:e2e": "node --test --test-timeout=240000 --test-concurrency=1 test/e2e/*.e2e.mjs"
   },
   "repository": {
     "type": "git",