dsh-builtin-browser 0.1.10 → 0.1.11

package/README.en.md

@@ -120,9 +120,15 @@ The browser's **visible view**, the **browser column layout**, and the **column-
 ## Known limitations
 
 - Screenshots are PNG-only (CDP JPEG hangs on Electron 43); JPEG awaits a non-CDP conversion path.
+- Self-hosted captures prefer Electron's native `capturePage` (CDP `captureScreenshot` can hang with multiple views in the window); the target tab is raised before capturing.
+- **Electron >= 40 is recommended**: 33.x has a compositor defect that intermittently breaks capture ("display surface not available"). The plugin automatically picks the newest Electron in the environment (peer dependency > `ELECTRON_PATH` > newest among anchors/pnpm store).
 - `fullPage` capture is flaky under software compositing on some hosts.
-- Session lifecycle is plugin-level (one session shared by the model), not per-agent yet.
+- Sessions are isolated per task (each DSH session gets its own browser session with own tabs/history; concurrent tasks never interfere; calls within one task reuse the same session). Logins (cookies) are shared and can be exported/restored with `browser_auth`.
+- CAPTCHA cannot be solved automatically: snapshots flag detected challenges (`browser_challenge` checks explicitly); ask the human to complete it in the shared window instead of retrying.
 - Private mode (`privateMode`) is not implemented: it needs Electron session partitioning, which is host-layer territory; this plugin does not promise it.
+- `browser_download` fetches in the page context (keeps logins) and is subject to same-origin/CORS constraints; single files are capped at 256 MB.
+- The `browser_auth` cookie round-trip does not preserve `hostOnly`/`sameSite` (host-only cookies come back as domain cookies); it is available on the self-hosted browser only.
+- After a self-hosted child crash the browser host restarts automatically, but sessions opened before the crash are gone — call `browser_reset_session` to rebuild.
 - This plugin contains no browser-column UI — that is host-shell territory; do not treat "browser column" as a plugin feature.
 
 ## License

package/README.md

@@ -127,10 +127,15 @@ provider 按构造与 Electron 解耦:它通过 `ElectronBrowserViewHost` 接缝
 ## 已知限制
 
 - 截图仅 PNG(CDP JPEG 在 Electron 43 上挂起);JPEG 等待非 CDP 转换路径。
+- 自托管截图优先走 Electron 原生 `capturePage`(CDP `captureScreenshot` 在多视图下会挂起);截图前自动把目标标签置顶。
+- **Electron 版本建议 ≥ 40**:33.x 存在合成器缺陷,会间歇性导致截图失败("display surface not available")。插件会**自动选择环境中最新版本的 Electron**(peer 依赖 > `ELECTRON_PATH` > 锚点/pnpm store 中最新版)。
 - 部分主机在软件合成下 `fullPage` 截图不稳定。
 - 会话按任务隔离:每个调用方任务(DSH 会话)拥有独立的浏览器会话(独立标签页与历史),并发任务互不干扰;同一任务的多次调用复用同一会话。登录态(cookie)为共享,可用 `browser_auth` 导出/恢复。
 - 人机验证(CAPTCHA)无法自动解决:快照会标注检测到的挑战(`browser_challenge` 可显式检查),此时应请用户在共享窗口中人工完成,而不是反复重试。
 - 无痕模式(`privateMode`)未实现:它需要 Electron 的 session 分区能力,属于宿主层,本插件不承诺。
+- `browser_download` 在页面上下文内 `fetch`(带登录态),受同源/CORS 约束;单文件上限 256MB。
+- `browser_auth` 的 cookie 往返不保留 `hostOnly`/`sameSite` 字段(host-only cookie 恢复后变成 domain cookie);仅自托管浏览器可用。
+- 自托管浏览器子进程崩溃后会自动重启,但崩溃前已打开的会话视图已失效,调用 `browser_reset_session` 重建即可。
 - 本插件不含浏览器列 UI——那是宿主外壳的配套,别把"浏览器列"当成插件能力。
 
 ## 许可证

package/lib/browser-electron/host-main.js

@@ -16,6 +16,19 @@
 import { app, BrowserWindow, WebContentsView } from 'electron';
 import { createInterface } from 'node:readline';
 import { createConnection } from 'node:net';
+import { join } from 'node:path';
+// Isolate this host's profile from the DSH app's default Electron userData:
+// several Electron instances sharing Roaming\Electron fight over the GPU
+// cache/session locks, which can leave the window without a display surface
+// (capturePage then fails). A dedicated userData also persists cookies across
+// host restarts (on top of browser_auth). Must run before app is ready.
+try {
+    const base = process.env.DSH_HOME ?? app.getPath('appData');
+    app.setPath('userData', join(base, 'dsh-builtin-browser-host'));
+}
+catch (error) {
+    process.stderr.write(`[dsh-browser host] userData setup failed: ${String(error)}\n`);
+}
 /** CDP protocol version attached to every view's debugger. */
 const CDP_VERSION = '1.3';
 /** Download cap: the body is shipped base64 as one JSON line; bound the memory. */
@@ -121,6 +134,94 @@ async function handle(op, msg) {
                 reply(msg.id, { ok: true, result });
                 return;
             }
+            case 'capture': {
+                const viewId = msg.viewId;
+                if (viewId === undefined)
+                    throw new Error('capture missing viewId');
+                const entry = views.get(viewId);
+                if (entry === undefined)
+                    throw new Error(`capture: unknown view ${viewId}`);
+                // Two complementary paths, because each has a failure mode:
+                //  - capturePage: fast and reliable with several WebContentsViews in
+                //    the window, but needs a live display surface (fails when the
+                //    window is minimized/occluded/unpainted).
+                //  - CDP Page.captureScreenshot: works without a display surface, but
+                //    can hang when another hidden WebContentsView exists in the window.
+                // Try capturePage first (show/focus/restore + one retry), then CDP.
+                if (window !== undefined) {
+                    try {
+                        if (!window.isVisible())
+                            window.show();
+                    }
+                    catch { /* closing */ }
+                    try {
+                        window.restore();
+                    }
+                    catch { /* not minimized */ }
+                    window.focus();
+                }
+                let base64 = '';
+                try {
+                    let image;
+                    try {
+                        image = await entry.webContentsView.webContents.capturePage();
+                    }
+                    catch (error) {
+                        process.stderr.write(`[dsh-browser host] capturePage failed: ${String(error)}\n`);
+                        await new Promise(resolve => setTimeout(resolve, 400));
+                        image = await entry.webContentsView.webContents.capturePage();
+                    }
+                    const png = image.toPNG();
+                    if (png.length > 0)
+                        base64 = png.toString('base64');
+                }
+                catch (error) {
+                    const state = window !== undefined
+                        ? JSON.stringify({
+                            win: { visible: window.isVisible(), minimized: window.isMinimized(), focused: window.isFocused() },
+                        })
+                        : 'no-window';
+                    process.stderr.write(`[dsh-browser host] capturePage retry failed: ${String(error)} state=${state}\n`);
+                    base64 = '';
+                }
+                if (base64 === '') {
+                    // CDP fallback. Page.captureScreenshot can hang when OTHER views
+                    // (especially hidden attach-first ones) are in the window, so
+                    // temporarily detach the siblings, capture in single-view state,
+                    // then restore them (target stays on top).
+                    const siblings = [...views.values()].filter(v => v !== entry);
+                    for (const v of siblings) {
+                        try {
+                            window?.contentView.removeChildView(v.webContentsView);
+                        }
+                        catch { /* already gone */ }
+                    }
+                    try {
+                        const shot = await entry.webContentsView.webContents.debugger.sendCommand('Page.captureScreenshot', {});
+                        const data = shot.data;
+                        if (typeof data === 'string' && data.length > 0)
+                            base64 = data;
+                    }
+                    finally {
+                        for (const v of siblings) {
+                            try {
+                                window?.contentView.addChildView(v.webContentsView);
+                            }
+                            catch { /* destroyed */ }
+                        }
+                        try {
+                            window?.contentView.removeChildView(entry.webContentsView);
+                            window?.contentView.addChildView(entry.webContentsView);
+                        }
+                        catch { /* closing */ }
+                    }
+                }
+                if (base64 === '') {
+                    throw new Error('capture produced no image (view not painted)');
+                }
+                reply(msg.id, { ok: true, result: { base64, width: 0, height: 0 } });
+                return;
+            }
             case 'download': {
                 const viewId = msg.viewId;
                 const url = msg.url;

package/lib/browser-electron/provider.d.ts

@@ -183,6 +183,8 @@ export declare class ElectronBrowserProvider implements BrowserProvider {
         readonly dataUrl: string;
         readonly path?: string;
     }>;
+    /** Build the data URL and optionally write the PNG to disk. */
+    private saveScreenshot;
     /** Append one operation to the session's history. */
     private record;
     /** Return the session's chronological operation log (newest last). */

package/lib/browser-electron/provider.js

@@ -569,36 +569,53 @@ export class ElectronBrowserProvider {
     }
     /** Capture the current page, optionally full-page. PNG only (CDP JPEG hangs on Electron 43). */
     async screenshot(session, request, signal) {
-        const { handle } = this.activeTab(this.session(session));
+        const s = this.session(session);
+        const { handle } = this.activeTab(s);
         signal?.throwIfAborted();
+        // Native capturePage path (self-hosted): CDP Page.captureScreenshot can
+        // hang indefinitely on a view once another (hidden) WebContentsView exists
+        // in the window; capturePage is fast for visible views and resolves
+        // immediately (empty) for hidden ones.
+        const capturable = handle;
+        if (request?.fullPage !== true && typeof capturable.capture === 'function') {
+            // Ensure the target view is the visible one before capturing.
+            this.showActive(s);
+            const timeoutMs = 30_000;
+            const shot = await withTimeout(capturable.capture(), timeoutMs, signal, `browser: screenshot timed out after ${timeoutMs}ms`);
+            if (shot.base64 === '') {
+                throw new BrowserError('browser: capture returned an empty image (view not painted); retry shortly', 'BROWSER_SCREENSHOT_FAILED');
+            }
+            return this.saveScreenshot(shot.base64, request?.savePath);
+        }
+        // Fallback: a desktop-shell handle (no capture()) or a full-page capture
+        // uses CDP; full-page needs `captureBeyondViewport` which capturePage lacks.
         const params = {};
         if (request?.fullPage === true) {
             // `captureBeyondViewport` captures the full scrollable content; without
             // a clip this yields the full-page image (CDP default is the viewport).
             params.captureBeyondViewport = true;
         }
-        // Bound the capture: a view that has not painted can wedge
-        // Page.captureScreenshot indefinitely (observed after view re-showing).
         const timeoutMs = 30_000;
         const result = await withTimeout(handle.sendCommand(CDP_PAGE_CAPTURE_SCREENSHOT, params), timeoutMs, signal, `browser: screenshot timed out after ${timeoutMs}ms`);
         const data = result.data;
         if (typeof data !== 'string') {
             throw new BrowserError('browser: screenshot returned no image data', 'BROWSER_SCREENSHOT_FAILED');
         }
-        // Optional disk write so a vision tool (e.g. modlens read_image) can read
-        // the screenshot from a file path. Fire-and-forget: a write failure must
-        // not fail the capture.
-        if (request?.savePath !== undefined) {
+        return this.saveScreenshot(data, request?.savePath);
+    }
+    /** Build the data URL and optionally write the PNG to disk. */
+    saveScreenshot(base64, savePath) {
+        if (savePath !== undefined) {
             try {
-                writeFileSync(request.savePath, Buffer.from(data, 'base64'));
-                return { dataUrl: `data:image/png;base64,${data}`, path: request.savePath };
+                writeFileSync(savePath, Buffer.from(base64, 'base64'));
+                return { dataUrl: `data:image/png;base64,${base64}`, path: savePath };
             }
             catch (error) {
                 // Report the write problem but keep the capture usable.
-                throw new BrowserError(`browser: screenshot save to "${request.savePath}" failed: ${String(error)}`, 'BROWSER_SCREENSHOT_SAVE_FAILED', { cause: error });
+                throw new BrowserError(`browser: screenshot save to "${savePath}" failed: ${String(error)}`, 'BROWSER_SCREENSHOT_SAVE_FAILED', { cause: error });
             }
         }
-        return { dataUrl: `data:image/png;base64,${data}` };
+        return { dataUrl: `data:image/png;base64,${base64}` };
     }
     /** Append one operation to the session's history. */
     record(s, action, params, ok, detail) {

package/lib/browser-electron/remote-host.js

@@ -26,12 +26,13 @@ const READY_TIMEOUT_MS = 20_000;
 /** Safety cap on a single RPC reply line (base64 downloads are the big ones). */
 const MAX_RPC_BUFFER_BYTES = 512 * 1024 * 1024;
 /**
- * Locate the Electron binary, trying, in order:
+ * Locate the Electron binary:
  *   1. require('electron') from this module (optional peer dependency),
- *   2. require.resolve('electron') against DSH install anchors (global dsh
- *      package, npm global root) — desktop-shell environments satisfy this,
- *   3. a pnpm virtual store under common workspace layouts,
- *   4. ELECTRON_PATH (explicit override).
+ *   2. ELECTRON_PATH (explicit override),
+ *   3. every DSH install anchor + pnpm virtual store candidate, choosing the
+ *      NEWEST version found. Older Electron releases (e.g. 33.x) have a
+ *      compositor defect that intermittently breaks page capture, so prefer
+ *      the newest binary available in the environment.
  * @returns the path to the Electron executable.
  */
 function resolveElectronPath() {
@@ -45,8 +46,16 @@ function resolveElectronPath() {
     catch {
         // continue probing
     }
-    // 2. DSH install anchors: the global dsh package and the npm global root
-    // both carry electron junctions under pnpm layouts.
+    // 2. Explicit override (user intent wins).
+    const override = process.env.ELECTRON_PATH;
+    if (typeof override === 'string' && override.length > 0 && existsSync(override))
+        return override;
+    // 3. Collect every candidate (anchors + pnpm stores), then pick the newest.
+    const candidates = [];
+    const add = (version, path) => {
+        if (path !== undefined)
+            candidates.push({ version, path });
+    };
     const anchors = [];
     const globalPrefix = process.env.npm_config_prefix ?? process.env.PREFIX;
     if (globalPrefix !== undefined) {
@@ -60,21 +69,13 @@ function resolveElectronPath() {
         try {
             const resolved = require.resolve('electron', { paths: [anchor] });
             if (typeof resolved === 'string' && resolved.length > 0) {
-                // electron's index.js is not the binary; find the dist executable
-                // next to the package root.
-                const exe = electronExeBeside(resolved);
-                if (exe !== undefined)
-                    return exe;
+                add(versionOf(resolved), electronExeBeside(resolved));
             }
         }
         catch {
             // continue probing
         }
     }
-    // 3. pnpm virtual store, walking up from several candidate roots: this
-    // module (its real path may differ from where the profile resolves it when
-    // installed via a junction/link), the process CWD, and the Node executable
-    // dir (DSH CLI typically runs from the workspace root).
     const roots = new Set([
         fileURLToPath(new URL('.', import.meta.url)),
         process.cwd(),
@@ -85,9 +86,12 @@ function resolveElectronPath() {
         for (let depth = 0; depth < 8; depth++) {
             const store = join(dir, 'node_modules', '.pnpm');
             if (existsSync(store)) {
-                const exe = findElectronExe(store);
-                if (exe !== undefined)
-                    return exe;
+                for (const entry of readdirSync(store)) {
+                    if (!entry.startsWith('electron@'))
+                        continue;
+                    const exe = electronDistExe(join(store, entry, 'node_modules', 'electron'));
+                    add(entry.slice('electron@'.length), exe);
+                }
             }
             const parent = join(dir, '..');
             if (parent === dir)
@@ -95,13 +99,31 @@ function resolveElectronPath() {
             dir = parent;
         }
     }
-    // 4. Explicit override.
-    const override = process.env.ELECTRON_PATH;
-    if (typeof override === 'string' && override.length > 0 && existsSync(override))
-        return override;
+    if (candidates.length > 0) {
+        candidates.sort((a, b) => compareVersions(b.version, a.version));
+        const best = candidates[0];
+        if (best !== undefined)
+            return best.path;
+    }
     throw new Error('dsh-builtin-browser: cannot locate the Electron binary. Install electron in the host profile ' +
         '(e.g. `dsh plugin --profile web add electron`) or set ELECTRON_PATH to the electron executable.');
 }
+/** Extract an electron version like "43.4.0" from a path containing it. */
+function versionOf(path) {
+    const match = /electron@(\d+\.\d+\.\d+)/.exec(path);
+    return match?.[1] ?? '0.0.0';
+}
+/** Compare dotted numeric versions; higher wins. */
+function compareVersions(a, b) {
+    const pa = a.split('.').map(n => Number(n) || 0);
+    const pb = b.split('.').map(n => Number(n) || 0);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+        if (d !== 0)
+            return d;
+    }
+    return 0;
+}
 /** From an electron package entry file, find the dist executable beside it. */
 function electronExeBeside(entry) {
     const candidates = [
@@ -116,6 +138,14 @@ function electronExeBeside(entry) {
     }
     return undefined;
 }
+/** From an electron package root, find its dist executable. */
+function electronDistExe(pkgRoot) {
+    for (const candidate of [join(pkgRoot, 'dist', 'electron.exe'), join(pkgRoot, 'dist', 'electron')]) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return undefined;
+}
 /** dirname without importing node:path's dirname separately. */
 function dirname(p) {
     const i = p.lastIndexOf('/');
@@ -123,23 +153,6 @@ function dirname(p) {
     const k = Math.max(i, j);
     return k < 0 ? p : p.slice(0, k);
 }
-/** Search a pnpm virtual store for an Electron dist binary. */
-function findElectronExe(store) {
-    const entries = existsSync(store) ? readdirSync(store) : [];
-    for (const entry of entries) {
-        if (!entry.startsWith('electron@'))
-            continue;
-        const candidates = [
-            join(store, entry, 'node_modules', 'electron', 'dist', 'electron.exe'),
-            join(store, entry, 'node_modules', 'electron', 'dist', 'electron'),
-        ];
-        for (const candidate of candidates) {
-            if (existsSync(candidate))
-                return candidate;
-        }
-    }
-    return undefined;
-}
 /**
  * Line-delimited JSON-RPC client over a local TCP socket. Electron's main
  * process on Windows does not receive piped stdin, so the parent listens on a
@@ -164,6 +177,7 @@ class ElectronChildClient {
         this.port = port;
         this.onExit = onExit;
         const electron = resolveElectronPath();
+        process.stderr.write(`[dsh-browser host] spawning electron: ${electron}\n`);
         // ELECTRON_RUN_AS_NODE (even an empty string) makes Electron run as plain
         // Node, breaking require('electron'); NODE_OPTIONS can inject flags that
         // break the child. Rebuild the env without either.
@@ -310,6 +324,10 @@ class RemoteView {
         const result = await this.client.call('download', { viewId: this.id, url, savePath });
         writeFileSync(savePath, Buffer.from(result.base64, 'base64'));
     }
+    /** Native capturePage snapshot of the view (PNG base64 + size). */
+    capture() {
+        return this.client.call('capture', { viewId: this.id });
+    }
     /** Export the session's cookies (login state). */
     flushAuth() {
         return this.client.call('flushAuth', { viewId: this.id }).then(r => r.cookies);
@@ -480,6 +498,10 @@ class DeferredRemoteView {
         const view = await this.materializeOnce();
         return view.download(url, savePath);
     }
+    async capture() {
+        const view = await this.materializeOnce();
+        return view.capture();
+    }
     async flushAuth() {
         const view = await this.materializeOnce();
         return view.flushAuth();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-builtin-browser",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "Shared real browser plugin for DeepSeek Harness: install-and-use — a visible native browser the human can take over, driven by the agent over CDP. DOM-level interaction (React/Vue safe), per-task session isolation, cookie persistence (browser_auth), CAPTCHA detection, batch form fill (browser_fill), authenticated download, history/replay, action restriction",
   "type": "module",
   "main": "lib/index.js",

package/src/browser-electron/host-main.ts

@@ -17,6 +17,19 @@
 import { app, BrowserWindow, WebContentsView } from 'electron'
 import { createInterface } from 'node:readline'
 import { createConnection } from 'node:net'
+import { join } from 'node:path'
+
+// Isolate this host's profile from the DSH app's default Electron userData:
+// several Electron instances sharing Roaming\Electron fight over the GPU
+// cache/session locks, which can leave the window without a display surface
+// (capturePage then fails). A dedicated userData also persists cookies across
+// host restarts (on top of browser_auth). Must run before app is ready.
+try {
+  const base = process.env.DSH_HOME ?? app.getPath('appData')
+  app.setPath('userData', join(base, 'dsh-builtin-browser-host'))
+} catch (error) {
+  process.stderr.write(`[dsh-browser host] userData setup failed: ${String(error)}\n`)
+}
 
 /** CDP protocol version attached to every view's debugger. */
 const CDP_VERSION = '1.3'
@@ -120,6 +133,73 @@ async function handle(op: string, msg: { id: number; viewId?: string; method?: s
         reply(msg.id, { ok: true, result })
         return
       }
+      case 'capture': {
+        const viewId = msg.viewId
+        if (viewId === undefined) throw new Error('capture missing viewId')
+        const entry = views.get(viewId)
+        if (entry === undefined) throw new Error(`capture: unknown view ${viewId}`)
+        // Two complementary paths, because each has a failure mode:
+        //  - capturePage: fast and reliable with several WebContentsViews in
+        //    the window, but needs a live display surface (fails when the
+        //    window is minimized/occluded/unpainted).
+        //  - CDP Page.captureScreenshot: works without a display surface, but
+        //    can hang when another hidden WebContentsView exists in the window.
+        // Try capturePage first (show/focus/restore + one retry), then CDP.
+        if (window !== undefined) {
+          try { if (!window.isVisible()) window.show() } catch { /* closing */ }
+          try { window.restore() } catch { /* not minimized */ }
+          window.focus()
+        }
+        let base64 = ''
+        try {
+          let image
+          try {
+            image = await entry.webContentsView.webContents.capturePage()
+          } catch (error) {
+            process.stderr.write(`[dsh-browser host] capturePage failed: ${String(error)}\n`)
+            await new Promise(resolve => setTimeout(resolve, 400))
+            image = await entry.webContentsView.webContents.capturePage()
+          }
+          const png = image.toPNG()
+          if (png.length > 0) base64 = png.toString('base64')
+        } catch (error) {
+          const state = window !== undefined
+            ? JSON.stringify({
+              win: { visible: window.isVisible(), minimized: window.isMinimized(), focused: window.isFocused() },
+            })
+            : 'no-window'
+          process.stderr.write(`[dsh-browser host] capturePage retry failed: ${String(error)} state=${state}\n`)
+          base64 = ''
+        }
+        if (base64 === '') {
+          // CDP fallback. Page.captureScreenshot can hang when OTHER views
+          // (especially hidden attach-first ones) are in the window, so
+          // temporarily detach the siblings, capture in single-view state,
+          // then restore them (target stays on top).
+          const siblings = [...views.values()].filter(v => v !== entry)
+          for (const v of siblings) {
+            try { window?.contentView.removeChildView(v.webContentsView) } catch { /* already gone */ }
+          }
+          try {
+            const shot = await entry.webContentsView.webContents.debugger.sendCommand('Page.captureScreenshot', {})
+            const data = (shot as { data?: unknown }).data
+            if (typeof data === 'string' && data.length > 0) base64 = data
+          } finally {
+            for (const v of siblings) {
+              try { window?.contentView.addChildView(v.webContentsView) } catch { /* destroyed */ }
+            }
+            try {
+              window?.contentView.removeChildView(entry.webContentsView)
+              window?.contentView.addChildView(entry.webContentsView)
+            } catch { /* closing */ }
+          }
+        }
+        if (base64 === '') {
+          throw new Error('capture produced no image (view not painted)')
+        }
+        reply(msg.id, { ok: true, result: { base64, width: 0, height: 0 } })
+        return
+      }
       case 'download': {
         const viewId = msg.viewId
         const url = msg.url

package/src/browser-electron/provider.ts

@@ -743,16 +743,37 @@ export class ElectronBrowserProvider implements BrowserProvider {
     request?: { readonly fullPage?: boolean; readonly savePath?: string },
     signal?: AbortSignal,
   ): Promise<{ readonly dataUrl: string; readonly path?: string }> {
-    const { handle } = this.activeTab(this.session(session))
+    const s = this.session(session)
+    const { handle } = this.activeTab(s)
     signal?.throwIfAborted()
+    // Native capturePage path (self-hosted): CDP Page.captureScreenshot can
+    // hang indefinitely on a view once another (hidden) WebContentsView exists
+    // in the window; capturePage is fast for visible views and resolves
+    // immediately (empty) for hidden ones.
+    const capturable = handle as { capture?(): Promise<{ base64: string; width: number; height: number }> }
+    if (request?.fullPage !== true && typeof capturable.capture === 'function') {
+      // Ensure the target view is the visible one before capturing.
+      this.showActive(s)
+      const timeoutMs = 30_000
+      const shot = await withTimeout(
+        capturable.capture(),
+        timeoutMs,
+        signal,
+        `browser: screenshot timed out after ${timeoutMs}ms`,
+      )
+      if (shot.base64 === '') {
+        throw new BrowserError('browser: capture returned an empty image (view not painted); retry shortly', 'BROWSER_SCREENSHOT_FAILED')
+      }
+      return this.saveScreenshot(shot.base64, request?.savePath)
+    }
+    // Fallback: a desktop-shell handle (no capture()) or a full-page capture
+    // uses CDP; full-page needs `captureBeyondViewport` which capturePage lacks.
     const params: Record<string, unknown> = {}
     if (request?.fullPage === true) {
       // `captureBeyondViewport` captures the full scrollable content; without
       // a clip this yields the full-page image (CDP default is the viewport).
       params.captureBeyondViewport = true
     }
-    // Bound the capture: a view that has not painted can wedge
-    // Page.captureScreenshot indefinitely (observed after view re-showing).
     const timeoutMs = 30_000
     const result = await withTimeout(
       handle.sendCommand(CDP_PAGE_CAPTURE_SCREENSHOT, params),
@@ -764,19 +785,21 @@ export class ElectronBrowserProvider implements BrowserProvider {
     if (typeof data !== 'string') {
       throw new BrowserError('browser: screenshot returned no image data', 'BROWSER_SCREENSHOT_FAILED')
     }
-    // Optional disk write so a vision tool (e.g. modlens read_image) can read
-    // the screenshot from a file path. Fire-and-forget: a write failure must
-    // not fail the capture.
-    if (request?.savePath !== undefined) {
+    return this.saveScreenshot(data, request?.savePath)
+  }
+
+  /** Build the data URL and optionally write the PNG to disk. */
+  private saveScreenshot(base64: string, savePath?: string): { dataUrl: string; path?: string } {
+    if (savePath !== undefined) {
       try {
-        writeFileSync(request.savePath, Buffer.from(data, 'base64'))
-        return { dataUrl: `data:image/png;base64,${data}`, path: request.savePath }
+        writeFileSync(savePath, Buffer.from(base64, 'base64'))
+        return { dataUrl: `data:image/png;base64,${base64}`, path: savePath }
       } catch (error) {
         // Report the write problem but keep the capture usable.
-        throw new BrowserError(`browser: screenshot save to "${request.savePath}" failed: ${String(error)}`, 'BROWSER_SCREENSHOT_SAVE_FAILED', { cause: error })
+        throw new BrowserError(`browser: screenshot save to "${savePath}" failed: ${String(error)}`, 'BROWSER_SCREENSHOT_SAVE_FAILED', { cause: error })
       }
     }
-    return { dataUrl: `data:image/png;base64,${data}` }
+    return { dataUrl: `data:image/png;base64,${base64}` }
   }
 
   /** Append one operation to the session's history. */

package/src/browser-electron/remote-host.ts

@@ -32,12 +32,13 @@ const READY_TIMEOUT_MS = 20_000
 const MAX_RPC_BUFFER_BYTES = 512 * 1024 * 1024
 
 /**
- * Locate the Electron binary, trying, in order:
+ * Locate the Electron binary:
  *   1. require('electron') from this module (optional peer dependency),
- *   2. require.resolve('electron') against DSH install anchors (global dsh
- *      package, npm global root) — desktop-shell environments satisfy this,
- *   3. a pnpm virtual store under common workspace layouts,
- *   4. ELECTRON_PATH (explicit override).
+ *   2. ELECTRON_PATH (explicit override),
+ *   3. every DSH install anchor + pnpm virtual store candidate, choosing the
+ *      NEWEST version found. Older Electron releases (e.g. 33.x) have a
+ *      compositor defect that intermittently breaks page capture, so prefer
+ *      the newest binary available in the environment.
  * @returns the path to the Electron executable.
  */
 function resolveElectronPath(): string {
@@ -49,8 +50,14 @@ function resolveElectronPath(): string {
   } catch {
     // continue probing
   }
-  // 2. DSH install anchors: the global dsh package and the npm global root
-  // both carry electron junctions under pnpm layouts.
+  // 2. Explicit override (user intent wins).
+  const override = process.env.ELECTRON_PATH
+  if (typeof override === 'string' && override.length > 0 && existsSync(override)) return override
+  // 3. Collect every candidate (anchors + pnpm stores), then pick the newest.
+  const candidates: Array<{ version: string; path: string }> = []
+  const add = (version: string, path: string | undefined): void => {
+    if (path !== undefined) candidates.push({ version, path })
+  }
   const anchors: string[] = []
   const globalPrefix = process.env.npm_config_prefix ?? process.env.PREFIX
   if (globalPrefix !== undefined) {
@@ -64,19 +71,12 @@ function resolveElectronPath(): string {
     try {
       const resolved: unknown = require.resolve('electron', { paths: [anchor] })
       if (typeof resolved === 'string' && resolved.length > 0) {
-        // electron's index.js is not the binary; find the dist executable
-        // next to the package root.
-        const exe = electronExeBeside(resolved)
-        if (exe !== undefined) return exe
+        add(versionOf(resolved), electronExeBeside(resolved))
       }
     } catch {
       // continue probing
     }
   }
-  // 3. pnpm virtual store, walking up from several candidate roots: this
-  // module (its real path may differ from where the profile resolves it when
-  // installed via a junction/link), the process CWD, and the Node executable
-  // dir (DSH CLI typically runs from the workspace root).
   const roots = new Set<string>([
     fileURLToPath(new URL('.', import.meta.url)),
     process.cwd(),
@@ -87,23 +87,45 @@ function resolveElectronPath(): string {
     for (let depth = 0; depth < 8; depth++) {
       const store = join(dir, 'node_modules', '.pnpm')
       if (existsSync(store)) {
-        const exe = findElectronExe(store)
-        if (exe !== undefined) return exe
+        for (const entry of readdirSync(store)) {
+          if (!entry.startsWith('electron@')) continue
+          const exe = electronDistExe(join(store, entry, 'node_modules', 'electron'))
+          add(entry.slice('electron@'.length), exe)
+        }
       }
       const parent = join(dir, '..')
       if (parent === dir) break
       dir = parent
     }
   }
-  // 4. Explicit override.
-  const override = process.env.ELECTRON_PATH
-  if (typeof override === 'string' && override.length > 0 && existsSync(override)) return override
+  if (candidates.length > 0) {
+    candidates.sort((a, b) => compareVersions(b.version, a.version))
+    const best = candidates[0]
+    if (best !== undefined) return best.path
+  }
   throw new Error(
     'dsh-builtin-browser: cannot locate the Electron binary. Install electron in the host profile ' +
     '(e.g. `dsh plugin --profile web add electron`) or set ELECTRON_PATH to the electron executable.',
   )
 }
 
+/** Extract an electron version like "43.4.0" from a path containing it. */
+function versionOf(path: string): string {
+  const match = /electron@(\d+\.\d+\.\d+)/.exec(path)
+  return match?.[1] ?? '0.0.0'
+}
+
+/** Compare dotted numeric versions; higher wins. */
+function compareVersions(a: string, b: string): number {
+  const pa = a.split('.').map(n => Number(n) || 0)
+  const pb = b.split('.').map(n => Number(n) || 0)
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0)
+    if (d !== 0) return d
+  }
+  return 0
+}
+
 /** From an electron package entry file, find the dist executable beside it. */
 function electronExeBeside(entry: string): string | undefined {
   const candidates = [
@@ -118,6 +140,14 @@ function electronExeBeside(entry: string): string | undefined {
   return undefined
 }
 
+/** From an electron package root, find its dist executable. */
+function electronDistExe(pkgRoot: string): string | undefined {
+  for (const candidate of [join(pkgRoot, 'dist', 'electron.exe'), join(pkgRoot, 'dist', 'electron')]) {
+    if (existsSync(candidate)) return candidate
+  }
+  return undefined
+}
+
 /** dirname without importing node:path's dirname separately. */
 function dirname(p: string): string {
   const i = p.lastIndexOf('/')
@@ -126,22 +156,6 @@ function dirname(p: string): string {
   return k < 0 ? p : p.slice(0, k)
 }
 
-/** Search a pnpm virtual store for an Electron dist binary. */
-function findElectronExe(store: string): string | undefined {
-  const entries = existsSync(store) ? readdirSync(store) : []
-  for (const entry of entries) {
-    if (!entry.startsWith('electron@')) continue
-    const candidates = [
-      join(store, entry, 'node_modules', 'electron', 'dist', 'electron.exe'),
-      join(store, entry, 'node_modules', 'electron', 'dist', 'electron'),
-    ]
-    for (const candidate of candidates) {
-      if (existsSync(candidate)) return candidate
-    }
-  }
-  return undefined
-}
-
 /** One RPC round-trip with the child. */
 interface Pending {
   resolve(result: unknown): void
@@ -171,6 +185,7 @@ class ElectronChildClient {
     private readonly onExit?: () => void,
   ) {
     const electron = resolveElectronPath()
+    process.stderr.write(`[dsh-browser host] spawning electron: ${electron}\n`)
     // ELECTRON_RUN_AS_NODE (even an empty string) makes Electron run as plain
     // Node, breaking require('electron'); NODE_OPTIONS can inject flags that
     // break the child. Rebuild the env without either.
@@ -308,6 +323,11 @@ class RemoteView implements ElectronViewHandle {
     writeFileSync(savePath, Buffer.from(result.base64, 'base64'))
   }
 
+  /** Native capturePage snapshot of the view (PNG base64 + size). */
+  capture(): Promise<{ base64: string; width: number; height: number }> {
+    return this.client.call<{ base64: string; width: number; height: number }>('capture', { viewId: this.id })
+  }
+
   /** Export the session's cookies (login state). */
   flushAuth(): Promise<ExportedCookie[]> {
     return this.client.call<{ cookies: ExportedCookie[] }>('flushAuth', { viewId: this.id }).then(r => r.cookies)
@@ -483,6 +503,11 @@ class DeferredRemoteView implements ElectronViewHandle {
     return view.download(url, savePath)
   }
 
+  async capture(): Promise<{ base64: string; width: number; height: number }> {
+    const view = await this.materializeOnce()
+    return view.capture()
+  }
+
   async flushAuth(): Promise<ExportedCookie[]> {
     const view = await this.materializeOnce()
     return view.flushAuth()

package/src/types/electron-shim.d.ts

@@ -41,12 +41,17 @@ declare module 'electron' {
       set(details: CookieSetter): Promise<void>
     }
   }
+  export interface NativeImage {
+    toPNG(): Buffer
+    getSize(): { width: number; height: number }
+  }
   export interface WebContents {
     readonly id: number
     readonly debugger: WebContentsDebugger
     readonly session: Session
     close(): void
     downloadURL(url: string): void
+    capturePage(): Promise<NativeImage>
   }
   export interface WebContentsView {
     readonly webContents: WebContents
@@ -62,6 +67,12 @@ declare module 'electron' {
       readonly children: WebContentsView[]
     }
     getContentSize(): [number, number]
+    isVisible(): boolean
+    isMinimized(): boolean
+    isFocused(): boolean
+    show(): void
+    restore(): void
+    focus(): void
     on(event: 'closed', listener: () => void): this
     on(event: 'resize', listener: () => void): this
     off(event: 'closed', listener: () => void): this
@@ -70,6 +81,8 @@ declare module 'electron' {
   export const app: {
     whenReady(): Promise<void>
     exit(code?: number): void
+    getPath(name: string): string
+    setPath(name: string, path: string): void
   }
   export interface BrowserWindowConstructor {
     new(options?: Record<string, unknown>): BrowserWindow