@bubstack/moe-glass 0.1.0

package/skills/browsing/lib/page-scripts/dom-summary.js

@@ -0,0 +1,31 @@
+// Page-side script: token-efficient page summary used by auto-capture.
+// Loaded as a string at attachCapture setup and embedded in CDP
+// Runtime.evaluate. Tested directly against jsdom in
+// test/lib/page-scripts/dom-summary.test.mjs.
+module.exports = `
+  (() => {
+    const buttons = document.querySelectorAll('button, input[type="button"], input[type="submit"]').length;
+    const inputs = document.querySelectorAll('input:not([type="button"]):not([type="submit"]), textarea, select').length;
+    const links = document.querySelectorAll('a[href]').length;
+
+    const title = document.title.slice(0, 60);
+    const allH1s = Array.from(document.querySelectorAll('h1')).map(h => h.textContent.trim().slice(0, 40)).filter(Boolean);
+    const h1s = allH1s.slice(0, 3);
+    const h1Extra = allH1s.length > 3 ? allH1s.length - 3 : 0;
+
+    const main = document.querySelector('main, [role="main"], .main, #main, .content, #content');
+    const mainTag = main ? main.tagName.toLowerCase() + (main.id ? '#' + main.id : main.className ? '.' + main.className.split(' ')[0] : '') : 'body';
+
+    const forms = document.querySelectorAll('form');
+    const formInfo = forms.length > 0 ? \`\${forms.length} form\${forms.length > 1 ? 's' : ''}\` : '';
+
+    const nav = document.querySelector('nav, [role="navigation"], .nav, #nav') ? 'nav' : '';
+
+    return [
+      \`\${title}\`,
+      \`Interactive: \${buttons} buttons, \${inputs} inputs, \${links} links\`,
+      h1s.length > 0 ? \`Headings: \${h1s.map(h => '"' + h + '"').join(', ')}\${h1Extra > 0 ? ', and ' + h1Extra + ' more' : ''}\` : '',
+      \`Layout: \${nav ? 'nav + ' : ''}\${mainTag}\${formInfo ? ' + ' + formInfo : ''}\`
+    ].filter(Boolean).join('\\n');
+  })()
+`;

package/skills/browsing/lib/page-scripts/markdown.js

@@ -0,0 +1,85 @@
+// Page-side script: walk the DOM and emit token-efficient Markdown.
+// Loaded as a string at attachCapture setup and embedded in CDP
+// Runtime.evaluate. Tested directly against jsdom in
+// test/lib/page-scripts/markdown.test.mjs.
+//
+// Includes images >= 100x100 in a header summary; inlines image references
+// >= 50x50 with size info; skips smaller icons.
+module.exports = `
+  (() => {
+    const results = [];
+
+    const title = document.title;
+    if (title) results.push(\`# \${title}\\n\`);
+
+    const allImages = document.querySelectorAll('img');
+    const significantImages = Array.from(allImages).filter(img => {
+      const rect = img.getBoundingClientRect();
+      return rect.width >= 100 && rect.height >= 100;
+    });
+
+    if (significantImages.length > 0) {
+      results.push(\`\\n**📷 This page contains \${significantImages.length} significant image(s). Check screenshot.png for visual content.**\\n\`);
+    }
+
+    const elements = document.querySelectorAll('h1, h2, h3, h4, h5, h6, p, a, li, pre, code, blockquote, table, img, figure');
+
+    for (const el of elements) {
+      const tag = el.tagName.toLowerCase();
+      const text = el.textContent.trim();
+
+      if (tag === 'img') {
+        const alt = el.alt || '';
+        const src = el.src || '';
+        const rect = el.getBoundingClientRect();
+        if (rect.width >= 50 && rect.height >= 50) {
+          const sizeInfo = \`\${Math.round(rect.width)}x\${Math.round(rect.height)}\`;
+          const description = alt ? \`"\${alt}"\` : '(no alt text)';
+          results.push(\`\\n![Image: \${description} - \${sizeInfo}](\${src})\\n\`);
+        }
+        continue;
+      }
+
+      if (tag === 'figure') {
+        const figcaption = el.querySelector('figcaption');
+        if (figcaption) {
+          results.push(\`\\n*Figure: \${figcaption.textContent.trim()}*\\n\`);
+        }
+        continue;
+      }
+
+      if (!text) continue;
+
+      if (tag.startsWith('h')) {
+        const level = parseInt(tag[1]);
+        results.push(\`\${'#'.repeat(level)} \${text}\\n\`);
+      } else if (tag === 'p') {
+        results.push(\`\${text}\\n\`);
+      } else if (tag === 'a') {
+        const href = el.href;
+        results.push(\`[\${text}](\${href})\`);
+      } else if (tag === 'li') {
+        results.push(\`- \${text}\`);
+      } else if (tag === 'pre' || tag === 'code') {
+        results.push(\`\\\`\\\`\\\`\\n\${text}\\n\\\`\\\`\\\`\\n\`);
+      } else if (tag === 'blockquote') {
+        results.push(\`> \${text}\\n\`);
+      } else if (tag === 'table') {
+        const rows = el.querySelectorAll('tr');
+        if (rows.length > 0) {
+          results.push('\\n| Table Content |\\n|---|');
+          for (let i = 0; i < Math.min(rows.length, 10); i++) {
+            const cells = rows[i].querySelectorAll('td, th');
+            const cellTexts = Array.from(cells).map(cell => cell.textContent.trim()).slice(0, 3);
+            if (cellTexts.length > 0) {
+              results.push(\`| \${cellTexts.join(' | ')} |\`);
+            }
+          }
+          results.push('\\n');
+        }
+      }
+    }
+
+    return results.join('\\n').slice(0, 50000); // Limit size
+  })()
+`;

package/skills/browsing/lib/page-scripts/permission-shim.js

@@ -0,0 +1,80 @@
+'use strict';
+
+// Source of the shim that runs in every page at document_start.
+// Exported as a string; `dialogs.attachToConnection` registers it via
+// `Page.addScriptToEvaluateOnNewDocument`.
+
+const SHIM_SOURCE = `
+(() => {
+  const BINDING = '__dialogShim';
+  const pending = new Map();
+  let nextId = 1;
+
+  function ask(name, jsApi) {
+    const id = String(nextId++);
+    return new Promise((resolve) => {
+      pending.set(id, resolve);
+      window[BINDING](JSON.stringify({ type: 'permission-request', id, name, jsApi, origin: location.origin }));
+    });
+  }
+
+  window[BINDING + '_resolve'] = (id, resolution) => {
+    const r = pending.get(id);
+    if (r) { pending.delete(id); r(resolution); }
+  };
+
+  // getUserMedia
+  if (navigator.mediaDevices) {
+    const origGetUM = navigator.mediaDevices.getUserMedia.bind(navigator.mediaDevices);
+    navigator.mediaDevices.getUserMedia = async function(constraints) {
+      const name = constraints && constraints.video ? 'camera' : 'microphone';
+      const decision = await ask(name, 'navigator.mediaDevices.getUserMedia');
+      if (decision === 'grant') return origGetUM(constraints);
+      throw new DOMException('Permission denied', 'NotAllowedError');
+    };
+  }
+
+  // Notification.requestPermission
+  if (typeof Notification !== 'undefined') {
+    const orig = Notification.requestPermission.bind(Notification);
+    Notification.requestPermission = async function(cb) {
+      const decision = await ask('notifications', 'Notification.requestPermission');
+      const result = decision === 'grant' ? 'granted' : 'denied';
+      if (typeof cb === 'function') cb(result);
+      return result;
+    };
+  }
+
+  // Geolocation
+  if (navigator.geolocation) {
+    const origGet = navigator.geolocation.getCurrentPosition.bind(navigator.geolocation);
+    navigator.geolocation.getCurrentPosition = async function(success, error, opts) {
+      const decision = await ask('geolocation', 'navigator.geolocation.getCurrentPosition');
+      if (decision === 'grant') return origGet(success, error, opts);
+      if (error) error(new DOMException('Permission denied', 'NotAllowedError'));
+    };
+  }
+
+  // Clipboard
+  if (navigator.clipboard) {
+    if (navigator.clipboard.readText) {
+      const orig = navigator.clipboard.readText.bind(navigator.clipboard);
+      navigator.clipboard.readText = async function() {
+        const decision = await ask('clipboard-read', 'navigator.clipboard.readText');
+        if (decision === 'grant') return orig();
+        throw new DOMException('Permission denied', 'NotAllowedError');
+      };
+    }
+    if (navigator.clipboard.writeText) {
+      const orig = navigator.clipboard.writeText.bind(navigator.clipboard);
+      navigator.clipboard.writeText = async function(text) {
+        const decision = await ask('clipboard-write', 'navigator.clipboard.writeText');
+        if (decision === 'grant') return orig(text);
+        throw new DOMException('Permission denied', 'NotAllowedError');
+      };
+    }
+  }
+})();
+`;
+
+module.exports = { SHIM_SOURCE };

package/skills/browsing/lib/page-session.js

@@ -0,0 +1,106 @@
+'use strict';
+
+/**
+ * Per-page CDP session over the browser-WS, attached via Target.attachToTarget({flatten:true}).
+ *
+ * Each pageSession wraps:
+ *   - sessionId (from Target.attachToTarget)
+ *   - targetId  (underlying CDP target)
+ *   - a per-session message-id counter (independent of other sessions — collapsing
+ *     id space across sessions would silently misroute responses)
+ *   - pendingRequests + eventListeners (held in the cdp-router)
+ *
+ * pageSession.send is the only way page-action commands reach Chrome via this transport.
+ * There is no fallback. If the browser-WS dies, the call rejects and the caller decides
+ * what to do.
+ */
+
+/**
+ * buildPageSessionFromAttached — constructs a pageSession from an already-attached
+ * sessionId (e.g. from Target.attachedToTarget autoAttach) without making any CDP
+ * calls. The caller is responsible for registering the session with the router
+ * BEFORE calling this function — or passing the sess object from registerSession.
+ *
+ * Both attachPageSession and the auto-attach handler in browser-bridge use this.
+ */
+function buildPageSessionFromAttached({ browser, router, sessionId, targetId }) {
+  const sess = router.registerSession(sessionId);
+  let messageIdCounter = 1;
+  let detached = false;
+  const enabledDomains = new Set();
+
+  async function send(method, params = {}, { timeoutMs = 30000 } = {}) {
+    if (detached) throw new Error(`Page session detached (sessionId=${sessionId})`);
+    const id = messageIdCounter++;
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        sess.pendingRequests.delete(id);
+        reject(new Error(`Page session timeout: ${method}`));
+      }, timeoutMs);
+      sess.pendingRequests.set(id, { resolve, reject, timeout });
+      // browser.send doesn't natively envelope by sessionId, so we use the sendRaw
+      // escape hatch with a pre-built JSON payload. The cdp-router correlates the
+      // response by sessionId.
+      try {
+        browser.sendRaw(JSON.stringify({ id, method, params, sessionId }));
+      } catch (e) {
+        clearTimeout(timeout);
+        sess.pendingRequests.delete(id);
+        reject(e);
+      }
+    });
+  }
+
+  function onEvent(handler) {
+    sess.eventListeners.add(handler);
+    return () => sess.eventListeners.delete(handler);
+  }
+
+  function waitForEvent(method, { timeoutMs = 15000 } = {}) {
+    return new Promise((resolve, reject) => {
+      let unsub = null;
+      const timeout = setTimeout(() => {
+        if (unsub) unsub();
+        reject(new Error(`waitForEvent ${method}: timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+      unsub = onEvent((msg) => {
+        if (msg.method === method) {
+          clearTimeout(timeout);
+          unsub();
+          resolve(msg);
+        }
+      });
+    });
+  }
+
+  /**
+   * Enable a CDP domain idempotently. Multiple callers (navigation auto-capture +
+   * console-logging stream, etc.) can call enableDomain('Runtime') without
+   * coordinating — it's a no-op if already enabled.
+   */
+  async function enableDomain(name) {
+    if (enabledDomains.has(name)) return;
+    await send(`${name}.enable`, {});
+    enabledDomains.add(name);
+  }
+
+  async function detach() {
+    if (detached) return;
+    detached = true;
+    try {
+      await browser.send('Target.detachFromTarget', { sessionId });
+    } catch {
+      // best-effort — Chrome may already have torn down the target
+    }
+    router.unregisterSession(sessionId);
+  }
+
+  return { sessionId, targetId, send, onEvent, waitForEvent, enableDomain, detach };
+}
+
+async function attachPageSession({ browser, router }, targetId) {
+  const { sessionId } = await browser.send('Target.attachToTarget', { targetId, flatten: true });
+  return buildPageSessionFromAttached({ browser, router, sessionId, targetId });
+}
+
+module.exports = { attachPageSession, buildPageSessionFromAttached };

package/skills/browsing/lib/profile-lock.js

@@ -0,0 +1,179 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { getChromeProfileDir } = require('./chrome-launcher-helpers');
+
+/**
+ * Per-profile MCP-instance lock.
+ *
+ * The bridge defaults every MCP server to the `moe-glass` profile,
+ * which means two MCP processes running on the same host silently end up
+ * driving the same Chrome (the second one reconnects to the first's instance
+ * via the meta.json path). Their `activeTab` pointers stomp on each other and
+ * the agents fight over tabs without any error surfacing.
+ *
+ * The fix is to claim a per-process lock file next to the profile dir and,
+ * on conflict with a live holder, auto-pick an unused alternate name
+ * (`moe-glass-2`, `-3`, etc.). The first MCP keeps the simple
+ * default; later MCPs get their own Chrome silently.
+ *
+ * Layout:
+ *   ~/.cache/moe/browser-profiles/<profile>/                 — Chrome user-data-dir
+ *   ~/.cache/moe/browser-profiles/<profile>.meta.json        — port/pid (Chrome process)
+ *   ~/.cache/moe/browser-profiles/<profile>.mcp.lock         — MCP-instance lock
+ *
+ * Semantics:
+ *   - `acquireWithFallback(base)` is the entry point used by chrome-process.js.
+ *     It tries `base`, then `base-2`, `base-3`, ... until it claims one or
+ *     runs out of slots. Returns { profileName, lockPath }.
+ *   - `acquire(profileName)` is a single-profile try-lock. Returns the
+ *     lock path on success, `null` on live-holder conflict, and throws on
+ *     unexpected I/O errors.
+ *   - `release(lockPath)` removes the lock; safe to call unconditionally.
+ *   - A lock whose pid is no longer alive is treated as stale and overwritten
+ *     atomically.
+ *   - File creation uses `wx` flag for atomicity — two MCPs starting at the
+ *     same millisecond can't both win.
+ *
+ * Lock file shape:
+ *   { pid: number, mcpPid: number, startedAt: ISO8601, version: number }
+ *   `version` is the on-disk format; bump if the shape ever changes.
+ */
+
+const LOCK_FORMAT_VERSION = 1;
+const MAX_PROFILE_SLOTS = 100;
+
+function getProfileLockPath(profileName) {
+  // Sibling of the profile dir, mirroring the meta.json placement.
+  // Uses the same directory the launcher already created for the profile.
+  return path.join(path.dirname(getChromeProfileDir(profileName)), `${profileName}.mcp.lock`);
+}
+
+function isPidAlive(pid) {
+  if (!pid || !Number.isFinite(pid)) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    // ESRCH = no such process. EPERM = process exists but we can't signal it
+    // (usually a different user) — still treat as alive so we don't stomp.
+    return e && e.code === 'EPERM';
+  }
+}
+
+function readLockFile(lockPath) {
+  try {
+    const raw = fs.readFileSync(lockPath, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function writeLockFile(lockPath, { atomic = true } = {}) {
+  const payload = {
+    pid: process.pid,
+    mcpPid: process.pid,
+    startedAt: new Date().toISOString(),
+    version: LOCK_FORMAT_VERSION,
+  };
+  fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+  // `wx` opens for write but fails if the file exists — atomic claim.
+  // The non-atomic variant is used only after we've verified the prior
+  // holder is dead and unlinked their lock.
+  const flag = atomic ? 'wx' : 'w';
+  fs.writeFileSync(lockPath, JSON.stringify(payload, null, 2), { flag });
+}
+
+function tryAtomicClaim(lockPath) {
+  try {
+    writeLockFile(lockPath);
+    return true;
+  } catch (e) {
+    if (e && e.code === 'EEXIST') return false;
+    throw e;
+  }
+}
+
+/**
+ * Try to acquire the lock for one specific profile.
+ *
+ * Returns the absolute lock path on success.
+ * Returns `null` if another live MCP already holds it.
+ */
+function acquire(profileName) {
+  const lockPath = getProfileLockPath(profileName);
+
+  // First pass: try atomic create. Wins if no lock exists.
+  if (tryAtomicClaim(lockPath)) return lockPath;
+
+  // Lock file already exists — inspect it.
+  const existing = readLockFile(lockPath);
+  if (existing && isPidAlive(existing.pid)) {
+    return null; // Another MCP is live on this profile.
+  }
+
+  // Stale (dead pid or unreadable). Remove and retake. The unlink → write
+  // pair is not atomic; a parallel acquirer could squeeze in between them.
+  // Re-test atomically after the rewrite to detect that race.
+  try { fs.unlinkSync(lockPath); } catch { /* already gone */ }
+  if (tryAtomicClaim(lockPath)) return lockPath;
+
+  // Someone else took it between our unlink and our claim. Re-inspect.
+  const racer = readLockFile(lockPath);
+  if (racer && isPidAlive(racer.pid)) return null;
+  // Their pid is also dead? Weird. Bail rather than loop forever.
+  return null;
+}
+
+/**
+ * Acquire a lock for `baseProfileName`. If another live MCP holds it,
+ * fall through to `<base>-2`, `<base>-3`, ... up to MAX_PROFILE_SLOTS.
+ *
+ * Returns `{ profileName, lockPath, slot }` on success, where `slot` is 1
+ * for the base name and N for the (N-1)-suffixed alternate.
+ *
+ * Throws if no slot is available — practically only happens if 100 MCPs
+ * are all live on the same host, which means something is wrong.
+ */
+function acquireWithFallback(baseProfileName) {
+  for (let slot = 1; slot <= MAX_PROFILE_SLOTS; slot++) {
+    const candidate = slot === 1 ? baseProfileName : `${baseProfileName}-${slot}`;
+    const lockPath = acquire(candidate);
+    if (lockPath) {
+      return { profileName: candidate, lockPath, slot };
+    }
+  }
+  throw new Error(
+    `Could not acquire a profile lock — ${MAX_PROFILE_SLOTS} live MCP instances ` +
+    `for base '${baseProfileName}'? Use CHROME_WS_PROFILE to set a unique name.`
+  );
+}
+
+function release(lockPath) {
+  if (!lockPath) return;
+  try {
+    // Only remove if it's still ours. Two cases where it isn't:
+    //  1. Some other process unlinked + recreated it (lock file PID differs)
+    //  2. The MCP that holds it has been replaced — same pid would be a coincidence
+    // We compare pid before unlinking to avoid removing a successor's lock.
+    const existing = readLockFile(lockPath);
+    if (existing && existing.pid !== process.pid) return;
+    fs.unlinkSync(lockPath);
+  } catch {
+    // Already gone or unwritable — nothing to do.
+  }
+}
+
+module.exports = {
+  acquire,
+  acquireWithFallback,
+  release,
+  // Exposed for tests:
+  getProfileLockPath,
+  isPidAlive,
+  readLockFile,
+  LOCK_FORMAT_VERSION,
+};

package/skills/browsing/lib/screenshot.js

@@ -0,0 +1,171 @@
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const os = require('os');
+const { getElementSelector } = require('./element-selector');
+const { throwIfExceptionDetails } = require('./cdp-utils');
+
+// Auto-downscale cap so screenshots fit Claude's many-image mode size limit
+// (max 2000px). Headroom of 200px keeps us safely under.
+const MAX_IMAGE_DIMENSION_PX = 1800;
+
+/**
+ * Page / element / full-page screenshots via CDP Page.captureScreenshot,
+ * with auto-downscaling so the resulting PNG fits Claude's many-image mode
+ * size limit (max dimension 2000 — we cap at 1800 for headroom).
+ *
+ * Three clip modes, picked from the args:
+ *   - `fullPage: true` — Page.getLayoutMetrics → captureBeyondViewport
+ *   - `selector` set — element's getBoundingClientRect
+ *   - default — explicit viewport clip from window.innerWidth/Height
+ *
+ * The default-viewport clip is load-bearing on Linux: without it Chrome
+ * uses its internal DPI-scaled dimensions, which produces oversized
+ * screenshots on HiDPI displays (Xft.dpi:144 etc).
+ *
+ * Downscaling is best-effort and platform-specific (sips on macOS,
+ * ImageMagick on Linux, no-op on Windows). Failures are silent — better
+ * to have a big PNG than no PNG.
+ *
+ * Path resolution for user-supplied filenames:
+ *   - Absolute path (starts with `/` or a Windows drive letter) → used as-is.
+ *   - Relative path → resolved against the session directory. If no session
+ *     directory exists yet, `initializeSession()` is called to create one.
+ *   - No filename supplied → auto-generates a timestamped name in session dir.
+ *
+ * `attachScreenshot({ getPageSession, state, initializeSession })` returns
+ * the bound action. `state` and `initializeSession` are optional; when
+ * absent, relative paths are resolved against CWD (legacy behaviour).
+ */
+function attachScreenshot({ getPageSession, state, initializeSession }) {
+  async function downscaleImageIfNeeded(filepath, maxDimension = MAX_IMAGE_DIMENSION_PX) {
+    const platform = os.platform();
+
+    try {
+      let width, height;
+
+      if (platform === 'darwin') {
+        const output = execFileSync('sips', ['-g', 'pixelWidth', '-g', 'pixelHeight', filepath], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+        const widthMatch = output.match(/pixelWidth:\s*(\d+)/);
+        const heightMatch = output.match(/pixelHeight:\s*(\d+)/);
+        width = widthMatch ? parseInt(widthMatch[1]) : 0;
+        height = heightMatch ? parseInt(heightMatch[1]) : 0;
+      } else if (platform === 'linux') {
+        try {
+          const output = execFileSync('identify', ['-format', '%w %h', filepath], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+          [width, height] = output.trim().split(' ').map(Number);
+        } catch {
+          // ImageMagick not available — skip downscaling.
+          return;
+        }
+      } else {
+        // Windows: no shipped downscale path.
+        return;
+      }
+
+      if (width <= maxDimension && height <= maxDimension) {
+        return;
+      }
+
+      if (platform === 'darwin') {
+        execFileSync('sips', ['-Z', String(maxDimension), filepath], { stdio: 'ignore' });
+      } else if (platform === 'linux') {
+        execFileSync('convert', [filepath, '-resize', `${maxDimension}x${maxDimension}>`, filepath], { stdio: 'ignore' });
+      }
+    } catch (_e) {
+      // Better to ship a too-big PNG than none.
+    }
+  }
+
+  /**
+   * Resolve a user-supplied filename to an absolute path.
+   *
+   * - Absolute path → unchanged.
+   * - Relative path → joined with session dir (creating it if necessary).
+   * - Falsy (null / undefined / '') → auto-generated name in session dir.
+   */
+  function resolveScreenshotPath(filename) {
+    if (!filename) {
+      // Auto-generate a timestamped filename in the session dir.
+      const dir = initializeSession ? initializeSession() : (state && state.sessionDir) || process.cwd();
+      return path.join(dir, `screenshot-${Date.now()}.png`);
+    }
+
+    // Absolute: /foo/bar or C:\foo\bar (Windows).
+    if (path.isAbsolute(filename)) {
+      return filename;
+    }
+
+    // Relative: join with session dir.
+    let dir;
+    if (initializeSession) {
+      dir = initializeSession();
+    } else if (state && state.sessionDir) {
+      dir = state.sessionDir;
+    } else {
+      // No session context — fall back to CWD (legacy behaviour).
+      return path.resolve(filename);
+    }
+    return path.join(dir, filename);
+  }
+
+  async function screenshot(tabIndexOrWsUrl, filename, selector = null, fullPage = false) {
+    const resolvedFilename = resolveScreenshotPath(filename);
+    const pageSession = await getPageSession(tabIndexOrWsUrl);
+
+    let clip;
+    if (fullPage) {
+      const metrics = await pageSession.send('Page.getLayoutMetrics');
+      const { width, height } = metrics.contentSize;
+      clip = { x: 0, y: 0, width, height, scale: 1 };
+    } else if (selector) {
+      const js = `
+        (() => {
+          const el = ${getElementSelector(selector)};
+          if (!el) return null;
+          const rect = el.getBoundingClientRect();
+          return {
+            x: rect.left,
+            y: rect.top,
+            width: rect.width,
+            height: rect.height,
+            scale: 1
+          };
+        })()
+      `;
+      const result = await pageSession.send('Runtime.evaluate', {
+        expression: js,
+        returnByValue: true
+      });
+      throwIfExceptionDetails(result);
+      clip = result.result.value;
+    } else {
+      // Explicit viewport clip — required for correct sizing on Linux HiDPI.
+      const vpResult = await pageSession.send('Runtime.evaluate', {
+        expression: '({ width: window.innerWidth, height: window.innerHeight })',
+        returnByValue: true
+      });
+      throwIfExceptionDetails(vpResult);
+      const { width, height } = vpResult.result.value;
+      clip = { x: 0, y: 0, width, height, scale: 1 };
+    }
+
+    const result = await pageSession.send('Page.captureScreenshot', {
+      format: 'png',
+      fromSurface: true,
+      captureBeyondViewport: fullPage,
+      clip
+    });
+
+    const buffer = Buffer.from(result.data, 'base64');
+    fs.writeFileSync(resolvedFilename, buffer);
+
+    await downscaleImageIfNeeded(resolvedFilename, MAX_IMAGE_DIMENSION_PX);
+
+    return resolvedFilename;
+  }
+
+  return { screenshot };
+}
+
+module.exports = { attachScreenshot };