Pup - the AI's own browser

@@ -57,6 +57,49 @@ const BRIDGE_VERSION = (() => { try { return fs.readFileSync(path.join(__dirname const SHOTS_DIR = path.join(__dirname, 'screenshots'); fs.mkdirSync(SHOTS_DIR, { recursive: true }); +// v1.8.21: shadow-DOM-piercing + nested-scroll helpers, installed into every page's+// window so browser_eval can use them ($deep / $$deep / deepText) AND so browser_scroll+// / browser_screenshot_element resolve elements + the ACTUAL scroll container the same+// way. Idempotent (guarded by __pupDeepInstalled). Injected via evaluateOnNewDocument+// (persists across navigations) AND ensured on-demand before each verb (covers the+// already-loaded document).+const PUP_DEEP_HELPERS = `(function(){+  if (window.__pupDeepInstalled) return; window.__pupDeepInstalled = true;+  // querySelectorAll piercing OPEN shadow roots+  window.$$deep = function(sel, root){ root = root||document; var out=[];+    var walk=function(n){ var f; try{f=n.querySelectorAll(sel);}catch(e){f=[];}+      for(var i=0;i<f.length;i++)out.push(f[i]);+      var a=n.querySelectorAll('*'); for(var j=0;j<a.length;j++){ if(a[j].shadowRoot) walk(a[j].shadowRoot); } };+    walk(root); return out; };+  window.$deep = function(sel, root){ var a=window.$$deep(sel,root); return a[0]||null; };+  // first VISIBLE element whose own text contains txt (case-insensitive), piercing shadow+  window.deepText = function(txt, root){ root=root||document; txt=(txt||'').toLowerCase(); var best=null;+    var walk=function(n){ var a=n.querySelectorAll('*'); for(var i=0;i<a.length;i++){ var el=a[i], own='';+      for(var k=0;k<el.childNodes.length;k++){ if(el.childNodes[k].nodeType===3) own+=el.childNodes[k].textContent; }+      if(own.toLowerCase().indexOf(txt)!==-1){ var r=el.getBoundingClientRect(); if(r.width>0&&r.height>0){ best=el; return true; } }+      if(el.shadowRoot&&walk(el.shadowRoot)) return true; } return false; };+    walk(root); return best; };+  // nearest scrollable ancestor of el (crosses shadow boundaries via host)+  window.__pupScrollableAncestor = function(el){ var n=el;+    while(n && n!==document.documentElement){ try{ var s=getComputedStyle(n), oy=s.overflowY;+      if((oy==='auto'||oy==='scroll'||oy==='overlay') && n.scrollHeight>n.clientHeight+1) return n; }catch(e){}+      n = n.parentElement || (n.getRootNode&&n.getRootNode().host) || null; }+    return document.scrollingElement||document.documentElement; };+  // the page's MAIN scroller: the document if it scrolls, else the biggest scrollable container+  window.__pupMainScroller = function(){ var doc=document.scrollingElement||document.documentElement;+    if(doc.scrollHeight>doc.clientHeight+1) return doc;+    var best=doc, area=0, all=window.$$deep('*');+    for(var i=0;i<all.length;i++){ var el=all[i]; try{ var s=getComputedStyle(el);+      if((s.overflowY==='auto'||s.overflowY==='scroll'||s.overflowY==='overlay') && el.scrollHeight>el.clientHeight+1){+        var a=(el.scrollHeight-el.clientHeight)*el.clientWidth; if(a>area){ area=a; best=el; } } }catch(e){} }+    return best; };+  window.__pupDesc = function(el){ if(!el) return null;+    var id=el.id?('#'+el.id):''; var cn=(el.className&&el.className.toString)?el.className.toString().trim():'';+    var cls=cn?('.'+cn.split(/\\s+/).slice(0,2).join('.')):''; return (el.tagName||'').toLowerCase()+id+cls; };+})();`;++async function ensureDeepHelpers(page) { try { await page.evaluate(PUP_DEEP_HELPERS); } catch (e) {} }+ // Persistent Chrome profiles — each session gets its own userDataDir // so IndexedDB, cookies, localStorage survive across restarts const PROFILES_DIR = path.join(__dirname, 'profiles');@@ -187,6 +230,9 @@ function attachTab(session, sessionId, page, { makeActive = true, opener = 'user       if (!observe()) document.addEventListener('DOMContentLoaded', () => { observe(); ensure(); });     }, sessionId).catch(() => {});   } catch (e) {}+  // v1.8.21: install the shadow-DOM + scroll helpers on every document so browser_eval+  // can use $deep / $$deep / deepText without hand-rolling a shadow-root walk.+  try { page.evaluateOnNewDocument(PUP_DEEP_HELPERS).catch(() => {}); } catch (e) {}   // Tag console logs with tabId so the caller can tell which tab emitted them   page.on('console', msg => {     try {@@ -2590,7 +2636,10 @@ const server = http.createServer(async (req, res) => {             V('browser_click', 'Click an element (by selector or coords).', { sessionId: 'required str', selector: 'optional str', x: 'optional int', y: 'optional int' }, 20, { sessionId: 'work', selector: 'button#go' }),             V('browser_type', 'Type text into the focused/selected field.', { sessionId: 'required str', text: 'required str', selector: 'optional str' }, 20, { sessionId: 'work', text: 'hello' }),             V('browser_press_key', 'Press a key / chord (e.g. Enter, Ctrl+A).', { sessionId: 'required str', key: 'required str' }, 15, { sessionId: 'work', key: 'Enter' }),-            V('browser_screenshot', 'Screenshot the page (PNG; fullPage optional).', { sessionId: 'required str', fullPage: 'optional bool' }, 30, { sessionId: 'work' }),+            V('browser_screenshot', 'Screenshot the page (PNG; fullPage optional). NOTE: fullPage only covers DOCUMENT-level scroll — on SPAs that scroll inside a nested container it returns just the viewport + a nestedScroll hint; use browser_screenshot_element or browser_scroll for those.', { sessionId: 'required str', fullPage: 'optional bool' }, 30, { sessionId: 'work' }),+            V('browser_screenshot_element', 'Screenshot ONE element, resolved by CSS selector OR visible text (pierces shadow DOM), scrolled into view first. The clean way to grab a single card/widget on a component-heavy page. Returns base64 + filePath like browser_screenshot.', { sessionId: 'required str', selector: 'CSS selector (or use text)', text: 'visible text to match (or use selector)', padding: 'optional int px around the element', deep: 'optional bool — pierce shadow DOM (default true)' }, 30, { sessionId: 'work', text: 'Download for your machine' }),+            V('browser_scroll', 'Scroll the ACTUAL scrolling element (nearest ancestor whose scrollHeight>clientHeight, NOT just window — window.scrollTo no-ops on nested-scroll SPAs). Scroll by delta {dy,dx} OR to an element {toSelector|toText} (pierces shadow DOM). Returns {scrollElement, scrollTop, scrollHeight, clientHeight} so you can confirm it landed.', { sessionId: 'required str', dy: 'optional int px (down+/up-)', dx: 'optional int px', toSelector: 'optional CSS selector to scroll to', toText: 'optional visible text to scroll to', block: 'optional start|center|end (for scroll-to; default center)', behavior: 'optional auto|smooth' }, 30, { sessionId: 'work', toText: 'Download' }),+            V('browser_set_viewport', 'Set the page viewport (CDP device-metrics) deterministically, independent of the OS window size — fixes a too-small innerWidth so fullPage/element shots render at a known width. width+height required.', { sessionId: 'required str', width: 'required int px', height: 'required int px', deviceScaleFactor: 'optional number (default 1)' }, 15, { sessionId: 'work', width: 1280, height: 900 }),             V('browser_evaluate', 'Evaluate JS in the page; returns the result.', { sessionId: 'required str', expression: 'required str' }, 30, { sessionId: 'work', expression: 'document.title' }),             V('browser_fetch_url', 'Fetch a URL\'s content via the browser (cookies/session intact).', { sessionId: 'required str', url: 'required str' }, 45, { sessionId: 'work', url: 'https://api.example.com' }),             V('browser_input_dispatch', 'Low-level input (mouse/keyboard) at coords — beats some overlays.', { sessionId: 'required str', type: 'required str', x: 'optional int', y: 'optional int' }, 20, { sessionId: 'work', type: 'mousePressed', x: 100, y: 200 }),@@ -2738,7 +2787,14 @@ const server = http.createServer(async (req, res) => {           const w = Number(args.width), h = Number(args.height), wx = Number(args.x), wy = Number(args.y);           const sized = Number.isFinite(w) && Number.isFinite(h);           const foreground = !!(args.foreground || args.raise || args.show);-          if (sized) { try { await setSessionWindowBounds(session, { x: wx, y: wy, width: w, height: h }); } catch (e) {} }+          if (sized) {+            try { await setSessionWindowBounds(session, { x: wx, y: wy, width: w, height: h }); } catch (e) {}+            // v1.8.21: ALSO pin the page VIEWPORT (CDP device-metrics) to width×height.+            // The OS-window bounds alone don't guarantee a matching inner viewport (DPI /+            // window-state quirks left it at ~170px on some laptops); page.setViewport makes+            // innerWidth/innerHeight deterministic, which is what fullPage/element shots need.+            try { await session.page.setViewport({ width: Math.round(w), height: Math.round(h), deviceScaleFactor: Number(args.deviceScaleFactor) || 1 }); } catch (e) {}+          }           if (!foreground) { try { osSendWindowToBack(args.profile); } catch (e) {} }           // Verbose browser report: which browser we actually drove, what else is available.           const brep = browserPickReport();@@ -3098,6 +3154,23 @@ const server = http.createServer(async (req, res) => {             tab.page.screenshot({ type: 'png', fullPage }),             20_000, 'page.screenshot'           );+          // v1.8.21: fullPage only covers DOCUMENT-level scroll. On SPAs that scroll inside+          // a nested container (the document itself doesn't grow), fullPage silently returns+          // just the visible viewport. Detect that and hand the caller the right tool.+          let nestedScrollHint = null;+          if (fullPage) {+            try {+              await ensureDeepHelpers(tab.page);+              const ns = await tab.page.evaluate(() => {+                const doc = document.scrollingElement || document.documentElement;+                const docScrolls = doc.scrollHeight > doc.clientHeight + 1;+                const main = window.__pupMainScroller();+                const nested = !docScrolls && main !== doc && main.scrollHeight > main.clientHeight + 1;+                return { docScrolls, nested, scroller: window.__pupDesc(main), scrollHeight: main.scrollHeight, clientHeight: main.clientHeight };+              });+              if (ns.nested) nestedScrollHint = `fullPage captured only the viewport: this page scrolls inside a NESTED container (${ns.scroller}, ${ns.scrollHeight}px of content vs ${ns.clientHeight}px visible), not the document — fullPage can't stitch that. To capture the whole thing, either browser_scroll {dy:...} through it and stitch, or (for one region) browser_screenshot_element {selector|text}. To capture a specific card, browser_screenshot_element is the one-shot fix.`;+            } catch (e) {}+          }            // Downscale to keep the image under Claude's Read limit when sharp is           // available; otherwise serve at capture size (sharp is optional — see the@@ -3123,11 +3196,122 @@ const server = http.createServer(async (req, res) => {             origHeight: shot.origHeight,             resized: shot.resized,             ...(shot.sharpUsed ? {} : { sharpUnavailable: true, _hint: 'Screenshot served at CAPTURE size — the sharp resize library is not installed on this box, so the image was NOT downscaled and may exceed Claude\'s ~2000px Read limit. If a Read fails on size, capture a smaller viewport, or (rare) this box\'s native-dep install failed — see browser_readiness.' }),+            ...(nestedScrollHint ? { nestedScroll: true, _hint: nestedScrollHint } : {}),             sessionId: resolvedId,             tabId,           }) });           return;         }+        case 'browser_set_viewport': {+          // v1.8.21: set the page viewport (CDP device-metrics) deterministically —+          // independent of the OS window size. Fixes "innerWidth came up ~170px" and lets a+          // fullPage/element shot render at a known width. width+height required.+          let session, resolvedId;+          try { ({ session, resolvedId } = await recoverOrRelaunchSession(args)); }+          catch (e) { sendSessionResolveError(res, e); return; }+          let tab, tabId;+          try { ({ tab, tabId } = resolveTabOrError(session, resolvedId, args)); }+          catch (e) { sendTabResolveError(res, e); return; }+          const vw = Number(args.width), vh = Number(args.height);+          if (!Number.isFinite(vw) || !Number.isFinite(vh)) {+            sendJSON(res, { success: false, error: 'browser_set_viewport requires numeric width + height.', _hint: 'e.g. browser_set_viewport {"sessionId":"...","width":1280,"height":900}. Optional deviceScaleFactor (default 1).' });+            return;+          }+          const dsf = Number(args.deviceScaleFactor) || 1;+          try {+            await tab.page.setViewport({ width: Math.round(vw), height: Math.round(vh), deviceScaleFactor: dsf });+            const dims = await tab.page.evaluate(() => ({ innerWidth: window.innerWidth, innerHeight: window.innerHeight, devicePixelRatio: window.devicePixelRatio }));+            sendJSON(res, { success: true, output: JSON.stringify({ ok: true, sessionId: resolvedId, tabId, applied: { width: Math.round(vw), height: Math.round(vh), deviceScaleFactor: dsf }, ...dims, _hint: `Viewport set to ${Math.round(vw)}×${Math.round(vh)} (innerWidth now ${dims.innerWidth}). Now browser_screenshot / browser_screenshot_element render at this size.` }) });+          } catch (e) { sendJSON(res, { success: false, error: `setViewport failed: ${e.message}` }); }+          return;+        }+        case 'browser_scroll': {+          // v1.8.21: first-class scroll. Resolves the ACTUAL scrolling element (nearest+          // ancestor whose scrollHeight>clientHeight, NOT just window — window.scrollTo+          // no-ops on nested-scroll SPAs). Supports scroll-by-delta {dy,dx} AND scroll-to+          // {toSelector|toText, deep} piercing shadow roots; returns the scroller's metrics+          // so the caller can confirm it landed.+          let session, resolvedId;+          try { ({ session, resolvedId } = await recoverOrRelaunchSession(args)); }+          catch (e) { sendSessionResolveError(res, e); return; }+          let tab, tabId;+          try { ({ tab, tabId } = resolveTabOrError(session, resolvedId, args)); }+          catch (e) { sendTabResolveError(res, e); return; }+          await ensureDeepHelpers(tab.page);+          try {+            const r = await tab.page.evaluate((o) => {+              let target = null;+              if (o.toSelector) target = window.$deep(o.toSelector);+              else if (o.toText) target = window.deepText(o.toText);+              let scroller;+              if (o.toSelector || o.toText) {+                if (!target) return { found: false };+                scroller = window.__pupScrollableAncestor(target);+                target.scrollIntoView({ block: o.block || 'center', inline: 'nearest', behavior: o.behavior || 'auto' });+              } else {+                scroller = window.__pupMainScroller();+                scroller.scrollBy({ top: o.dy || 0, left: o.dx || 0, behavior: o.behavior || 'auto' });+              }+              return { found: true, scrollElement: window.__pupDesc(scroller), scrollTop: Math.round(scroller.scrollTop), scrollLeft: Math.round(scroller.scrollLeft), scrollHeight: scroller.scrollHeight, clientHeight: scroller.clientHeight, atBottom: scroller.scrollTop + scroller.clientHeight >= scroller.scrollHeight - 2 };+            }, { dy: Number(args.dy) || 0, dx: Number(args.dx) || 0, toSelector: args.toSelector || null, toText: args.toText || null, block: args.block || null, behavior: args.behavior || 'auto' });+            if (!r.found) {+              sendJSON(res, { success: false, errorCode: 'scroll_target_not_found', error: `browser_scroll: could not resolve ${args.toSelector ? 'selector "'+args.toSelector+'"' : 'text "'+args.toText+'"'} (searched, piercing shadow roots).`, sessionId: resolvedId, tabId });+              return;+            }+            sendJSON(res, { success: true, output: JSON.stringify({ ok: true, sessionId: resolvedId, tabId, ...r, _hint: `Scrolled ${args.toSelector||args.toText ? 'to the target' : 'by delta'} inside ${r.scrollElement} — scrollTop ${r.scrollTop}/${r.scrollHeight - r.clientHeight}${r.atBottom ? ' (at bottom)' : ''}. Screenshot to confirm, or browser_screenshot_element to grab just a card.` }) });+          } catch (e) { sendJSON(res, { success: false, error: `browser_scroll failed: ${e.message}` }); }+          return;+        }+        case 'browser_screenshot_element': {+          // v1.8.21: screenshot ONE element, resolved by CSS selector OR visible text+          // (piercing shadow DOM), scrolled into view first. The clean fix for "capture+          // just this card" on component-heavy pages. Returns the same shape as+          // browser_screenshot (base64 + filePath, downscaled for Read).+          let session, resolvedId;+          try { ({ session, resolvedId } = await recoverOrRelaunchSession(args)); }+          catch (e) { sendSessionResolveError(res, e); return; }+          let tab, tabId;+          try { ({ tab, tabId } = resolveTabOrError(session, resolvedId, args)); }+          catch (e) { sendTabResolveError(res, e); return; }+          if (!args.selector && !args.text) {+            sendJSON(res, { success: false, error: 'browser_screenshot_element requires a selector OR text.', _hint: 'e.g. {"selector":".download-card"} or {"text":"Download for your machine"}. Pierces shadow DOM by default.' });+            return;+          }+          await ensureDeepHelpers(tab.page);+          let handle;+          try {+            handle = await tab.page.evaluateHandle((sel, txt) => (sel ? window.$deep(sel) : window.deepText(txt)), args.selector || null, args.text || null);+            const el = handle.asElement();+            if (!el) {+              try { await handle.dispose(); } catch {}+              sendJSON(res, { success: false, errorCode: 'element_not_found', error: `browser_screenshot_element: no element matched ${args.selector ? 'selector "'+args.selector+'"' : 'text "'+args.text+'"'} (searched, piercing shadow roots).`, sessionId: resolvedId, tabId });+              return;+            }+            await el.evaluate((e) => e.scrollIntoView({ block: 'center', inline: 'center' }));+            await new Promise(r => setTimeout(r, 150)); // let layout settle after scroll+            const pad = Number(args.padding) || 0;+            let rawBuf;+            if (pad > 0) {+              const box = await el.boundingBox();+              if (!box) throw new Error('element has no rendered box (hidden/zero-size)');+              const clip = { x: Math.max(0, box.x - pad), y: Math.max(0, box.y - pad), width: box.width + 2 * pad, height: box.height + 2 * pad };+              rawBuf = await withTimeout(tab.page.screenshot({ type: 'png', clip }), 20_000, 'element.screenshot(clip)');+            } else {+              rawBuf = await withTimeout(el.screenshot({ type: 'png' }), 20_000, 'element.screenshot');+            }+            try { await handle.dispose(); } catch {}+            const shot = await processScreenshot(rawBuf, MAX_SCREENSHOT_DIM);+            const ts = Date.now();+            const filePath = path.join(SHOTS_DIR, `pup-el-${ts}.png`);+            fs.writeFileSync(filePath, shot.buf);+            session.latestShot = filePath;+            sendJSON(res, { success: true, output: JSON.stringify({ ok: true, sessionId: resolvedId, tabId, matchedBy: args.selector ? 'selector' : 'text', sizeKB: Math.round(shot.buf.length / 1024), filePath, base64: shot.buf.toString('base64'), width: shot.width, height: shot.height, origWidth: shot.origWidth, origHeight: shot.origHeight, resized: shot.resized, _hint: 'Captured just that element (scrolled into view first). Read the filePath to see it.' }) });+          } catch (e) {+            try { if (handle) await handle.dispose(); } catch {}+            sendJSON(res, { success: false, error: `browser_screenshot_element failed: ${e.message}` });+          }+          return;+        }         case 'browser_screenshot_full_res': {           // v1.8.40+: full-resolution variant for the rare "save to disk for           // external use" case (export to wiki, hand to a designer, etc.).@@ -3191,6 +3375,9 @@ const server = http.createServer(async (req, res) => {           let tab, tabId;           try { ({ tab, tabId } = resolveTabOrError(session, resolvedId, args)); }           catch (e) { sendTabResolveError(res, e); return; }+          // v1.8.21: ensure the shadow-DOM helpers are present so an expr can use+          // $deep(sel) / $$deep(sel) / deepText(txt) without hand-rolling a shadow walk.+          await ensureDeepHelpers(tab.page);           let result;           try {             result = await withTimeout(