dsh-builtin-browser 0.1.22 → 0.1.23

package/README.en.md

@@ -310,8 +310,12 @@ Code layout:
 | 17 | 2026-09-16 | **Screenshot savePath confined + localized download dir** (issue #13): `browser_screenshot` wrote straight to `writeFileSync` — anywhere the process could reach, silently replacing existing files (bypassing the read-only sandbox's write protection) → one shared `admitSavePath` gate for downloads AND screenshots (absolute, inside `downloadDir`, never overwriting an existing file), plus parent-directory creation for screenshots; the default download directory is no longer hardcoded to `~/Downloads` but probed in order: `downloadDir` → `XDG_DOWNLOAD_DIR` → `~/Downloads` / `~/下载` / `~/下載` → fallback (a Chinese desktop needs no configuration) |
 
 | **0.1.22** | 2026-09-16 | **Release**: the macOS binary-probe fix (issues #9 / #14) and rounds 15–17 (issue #11 toolbar SyntaxError / #10 self-hosted trio / #13 screenshot savePath + download dir) ship as **0.1.22** (build clean, **35/35 tests pass**, tag `v0.1.22`) |
+| Round 18 | 2026-09-20 | **Windows on-device trio + probe self-healing + locate verdicts** (measured on a real self-hosted `dsh web` host; defects ①–④ were all the "CDP answered success, the page received nothing" kind): ① Chromium's `CalculateNativeWinOcclusion` marks the plugin window HIDDEN while another window covers it — the page stops producing frames and **every** synthesized mouse/key event is dropped by the renderer (`CanReceiveInput()` false) while CDP replies `{}` → the child appends `disable-features=CalculateNativeWinOcclusion` before `app.whenReady()` (win32 only); ② `click()` had no leading `mouseMoved`, so the first click on a fresh view was routed away and lost → now move→press→release; ③ a fresh view holds no web focus, so the FIRST `browser_key` of a session vanished → new host `focus` op (optional `focus?()` on the view handle), `key()` focuses best-effort before dispatch and waits 80ms only when focus had to move (focus lands asynchronously; a key dispatched in the same turn is still dropped); ④ `available()` cached a FAILED Electron probe for the host's lifetime while provider selection runs once per process, so an Electron that arrived after DSH started was never adopted → successes stay cached, failures re-probe after a cooldown (`DSH_BROWSER_PROBE_RETRY_MS`, default 30s), and `resolveProvider()` now distinguishes "no provider registered" from "registered but reports itself unavailable" with the matching remedy; ⑤ **a failed locate was masked by the outer timeout** — the in-page locate script polls for its whole budget and answers only afterwards, while the outer wait used the SAME budget, so `browser: click timed out after 10000ms` won the race and the in-page verdict never got out; a css/xpath **parse error** also reported as "not found yet", polling a selector that can never become valid. Now a parse error is terminal and names itself (`invalid CSS selector "…" / invalid XPath …`), the outer wait gives the in-page answer 2 s of transport grace, and a miss reports the strategy the provider assumed (`by` defaults to `"by":"css"`) plus the time spent; `scrape`'s item selector fails the same way at once. Same call: before `click timed out after 10000ms`, after `element not found: {"value":"Learn more","by":"css"} (looked for 10000ms)`. 7 new regression tests (**47/47 pass**), 17/17 end-to-end steps against the real host, plus 4/4 locate-verdict steps |
 
-> The npm badge at the top is the authority on the registry's latest version: `0.1.22` is committed and tagged; if the badge still reads `0.1.21`, that version is not published yet.
+| 19 | 2026-10-01 | **DSH 0.2 compatibility**: DSH moved to the 0.2 line (`@deepseek-ai/dsh@0.2.0-rc.2`, with `dsh-llm`/`dsh-tools`/`dsh-system-prompt` following to `0.2.0-rc.2`), while our declaration `>=0.1.1-rc.1 <0.2.0` shut 0.2 out → verified the plugin's (narrow) runtime dependency surface against a **real 0.2.0-rc.2 host** (`cordis` Context/Service, `dsh-tools` defineTool, `dsh-llm` HarnessError, `schemastery`) and found no breaking change: session, navigation, snapshot and the screenshot trio (outside-path refused / legal write / overwrite refused) all pass → peer ranges for the three dsh packages widened to `>=0.1.1-rc.2 <0.3.0`, `dsh.compatibility.dsh` widened to `>=0.1.1-rc.1 <0.3.0`, and `dshReleases` gained `0.2.0-rc.1`/`0.2.0-rc.2` = compatible |
+| **0.1.23** | 2026-10-01 | **Release**: round 18 (PR #15: the Windows synthesized-input trio + Electron probe self-healing + locate verdicts) and round 19 (DSH 0.2 compatibility) ship as **0.1.23** (build clean, **47/47 tests pass**, tag `v0.1.23`) |
+
+> The npm badge at the top is the authority on the registry's latest version: `0.1.23` is committed and tagged; if the badge still reads `0.1.22`, that version is not published yet.
 
 ## Acknowledgements
 

package/README.md

@@ -310,8 +310,12 @@ npm run build
 | 第十七轮 | 2026-09-16 | **截图 savePath 收敛 + 下载目录本地化**(issue #13):`browser_screenshot` 原先直接 `writeFileSync`,可写进程可达的任意路径并**静默覆盖**已有文件(等于绕过只读沙箱的写保护)→ 抽出唯一下载/截图共用准入门 `admitSavePath`(绝对路径 + `downloadDir` 内 + **不覆盖已存在文件**),截图补父目录自动创建;默认下载目录不再写死 `~/Downloads`,按序探测 `downloadDir` → `XDG_DOWNLOAD_DIR` → `~/Downloads`/`~/下载`/`~/下載` → 回退(中文桌面免配置) |
 
 | **0.1.22** | 2026-09-16 | **发布**:macOS 二进制探测修复(issue #9 / #14)与第十五~十七轮(issue #11 工具栏 SyntaxError / #10 自托管三连 / #13 截图 savePath + 下载目录)随 **0.1.22** 收录(构建零错误、**35 项测试全绿**,tag `v0.1.22`) |
+| 第十八轮 | 2026-09-20 | **Windows 真机三连 + 探测自愈 + 定位判词**(真实 `dsh web` 自托管宿主实测,缺陷①~④同为「CDP 报成功、页面没收到」):① Windows 的 `CalculateNativeWinOcclusion` 把被遮挡的插件窗口判定为 HIDDEN → 整站停帧,且每条合成鼠标/键盘事件被渲染端静默丢弃(CanReceiveInput=false)而 CDP 回 `{}` → 子进程 ready 前追加 `disable-features=CalculateNativeWinOcclusion`(仅 win32);② `click()` 缺前置 `mouseMoved`,新视图第一次点击落空 → 改为 move→press→release;③ 新视图从未持有 web focus,`browser_key` 第一次调用无效 → 宿主新增 `focus` op(view handle 可选 `focus?()`),`key()` 派发前 best-effort 聚焦,并在焦点需要移动时等 80ms(焦点落地异步,同轮派发的键仍会被丢);④ `available()` 把**失败**探测按宿主生命周期永久缓存,而 provider 选择每进程一次 → Electron 晚于 DSH 到位就永远接不上 → 成功仍缓存、失败 30s 冷却后重探(`DSH_BROWSER_PROBE_RETRY_MS`),`resolveProvider()` 报错区分「一个都没注册」与「注册了但自报不可用」并附处置;⑤ **定位失败被外层超时掩盖** —— 页内定位脚本会把预算轮询到底才回答,外层却用同一个预算,于是 `browser: click timed out after 10000ms` 抢走了页内早已写好的判词;而 css/xpath **解析失败**(选择器根本不合法)也被写成「还没找到」,对着永远不可能匹配的东西把预算轮完 → 解析失败即刻终止并报 `invalid CSS selector "…" / invalid XPath …`;外层给页内判词 2s 传输余量;未命中判词补上提供方实际采用的策略(`by` 缺省即 `"by":"css"`)与实际耗时;`scrape` 的 item 选择器同样即刻失败(同一个漏写 `by` 的调用:修前 `click timed out after 10000ms`,修后 `element not found: {"value":"Learn more","by":"css"} (looked for 10000ms)`);新增 7 条回归测试(**47/47 全绿**),真实宿主端到端 **17/17** + 定位判词 **4/4** |
 
-> registry 上的最新版本以顶部 npm 徽章为准:本次 `0.1.22` 已入库并打 tag;若徽章仍显示 `0.1.21`,说明该版本尚未 publish。
+| 第十九轮 | 2026-10-01 | **DSH 0.2 兼容性**:DSH 进入 0.2 线(`@deepseek-ai/dsh@0.2.0-rc.2`,peer 包 `dsh-llm`/`dsh-tools`/`dsh-system-prompt` 同步到 `0.2.0-rc.2`),而原声明 `>=0.1.1-rc.1 <0.2.0` 把 0.2 挡在门外 → 在**真实 0.2.0-rc.2 宿主**上实测插件的运行时依赖面(`cordis` 的 Context/Service、`dsh-tools` 的 defineTool、`dsh-llm` 的 HarnessError、`schemastery`),确认无破坏性变更:会话、导航、快照、截图三态(越界拒绝/合法写入/覆盖拒绝)全部通过 → `peerDependencies` 三个 dsh 包范围改为 `>=0.1.1-rc.2 <0.3.0`,`dsh.compatibility.dsh` 放宽为 `>=0.1.1-rc.1 <0.3.0`,`dshReleases` 增加 `0.2.0-rc.1`/`0.2.0-rc.2` = compatible |
+| **0.1.23** | 2026-10-01 | **发布**:第十八轮(PR #15:Windows 合成输入三连 + Electron 探测自愈 + 定位判词)与第十九轮(DSH 0.2 兼容)随 **0.1.23** 发布(构建零错误、**47 项测试全绿**,tag `v0.1.23`) |
+
+> registry 上的最新版本以顶部 npm 徽章为准:本次 `0.1.23` 已入库并打 tag;若徽章仍显示 `0.1.22`,说明该版本尚未 publish。
 
 ## 特别感谢
 

package/lib/browser/runtime.js

@@ -70,7 +70,15 @@ export class BrowserRuntime extends Service {
         const usable = [...providers.values()].filter(provider => provider.available());
         const [single] = usable;
         if (single === undefined) {
-            throw new BrowserError('no usable browser provider is registered', 'BROWSER_PROVIDER_UNAVAILABLE');
+            // Two very different causes used to read identically here — nothing is
+            // registered, or something is registered but cannot run — and only the
+            // second one has a fix the user can apply without reinstalling.
+            const registered = [...providers.values()].map(provider => provider.id);
+            if (registered.length === 0) {
+                throw new BrowserError('no browser provider is registered — install a browser plugin (e.g. dsh-builtin-browser) and enable it in this profile', 'BROWSER_PROVIDER_UNAVAILABLE');
+            }
+            throw new BrowserError(`browser provider(s) ${registered.join(', ')} are registered but report themselves unavailable — `
+                + 'for dsh-builtin-browser this means no spawnable Electron binary was found; run `npx install-electron` in the active profile or set ELECTRON_PATH', 'BROWSER_PROVIDER_UNAVAILABLE');
         }
         if (usable.length > 1) {
             const ids = usable.map(provider => provider.id).join(', ');

package/lib/browser-electron/host-main.d.ts

@@ -13,6 +13,7 @@
  *      { id, op: 'destroyView', viewId } | { id, op: 'showView', viewId } |
  *      { id, op: 'groupView', viewId, windowId, label? } |
  *      { id, op: 'command', viewId, method, params } |
+ *      { id, op: 'focus', viewId } |
  *      { id, op: 'userActionError', windowId, message }
  *   -> { id: 0, op: 'hello', token } (our FIRST message — proves we know the
  *      parent's stdin token; the parent refuses the connection otherwise)

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

@@ -13,6 +13,7 @@
  *      { id, op: 'destroyView', viewId } | { id, op: 'showView', viewId } |
  *      { id, op: 'groupView', viewId, windowId, label? } |
  *      { id, op: 'command', viewId, method, params } |
+ *      { id, op: 'focus', viewId } |
  *      { id, op: 'userActionError', windowId, message }
  *   -> { id: 0, op: 'hello', token } (our FIRST message — proves we know the
  *      parent's stdin token; the parent refuses the connection otherwise)
@@ -235,6 +236,13 @@ function withTimeout(promise, ms, label) {
  * only the tool layer's 10–30s timeout eventually cuts off.
  */
 const COMMAND_TIMEOUT_MS = 20000;
+/**
+ * How long to let a `focus` request land before answering it. Focus moves
+ * asynchronously and a key dispatched in the same turn as the request is still
+ * dropped, so the caller needs this settle — but only on the call where focus
+ * actually had to move.
+ */
+const FOCUS_SETTLE_MS = 80;
 /**
  * A brand-new WebContentsView has no renderer process until something loads,
  * and CDP commands (Runtime.evaluate …) sent to a renderer-less view never
@@ -725,6 +733,29 @@ async function handle(op, msg) {
                 reply(msg.id, { ok: true, result });
                 return;
             }
+            case 'focus': {
+                const viewId = msg.viewId;
+                if (viewId === undefined)
+                    throw new Error('focus missing viewId');
+                const win = windowOfView(viewId);
+                const entry = win?.views.get(viewId);
+                if (win === undefined || entry === undefined)
+                    throw new Error(`focus: unknown view ${viewId}`);
+                // Keys go to the view that holds web focus. A view that was never
+                // clicked holds none, so the FIRST browser_key of a session was dropped
+                // by the renderer while CDP still answered the dispatch with success —
+                // and `document.hasFocus()` inside the page even read true.
+                const contents = entry.webContentsView.webContents;
+                const hadWebFocus = contents.isFocused();
+                contents.focus();
+                // Focus lands asynchronously, and a key dispatched in the same turn as
+                // the request is still dropped, so hold the reply until the renderer can
+                // take input. Only on the call where focus actually had to move.
+                if (!hadWebFocus)
+                    await new Promise(resolve => setTimeout(resolve, FOCUS_SETTLE_MS));
+                reply(msg.id, { ok: true, focused: contents.isFocused() });
+                return;
+            }
             case 'capture': {
                 const viewId = msg.viewId;
                 if (viewId === undefined)
@@ -997,6 +1028,35 @@ async function handle(op, msg) {
         reply(msg.id, { ok: false, err: String(error) });
     }
 }
+/**
+ * Chromium's native-window occlusion tracker (Windows only) asks DWM whether a
+ * window is covered by another window and, when it is, moves the WebContents to
+ * `Visibility::HIDDEN`. That is the wrong model for this host: the shared
+ * browser window normally sits *behind* whatever the human is working in, and
+ * that is exactly the state the agent drives it from. A hidden WebContents
+ * produces no frames at all (`requestAnimationFrame` never fires) and
+ * `RenderWidgetHostImpl::CanReceiveInput()` returns false, so every
+ * `Input.dispatchMouseEvent`/`dispatchKeyEvent` sent over CDP is dropped on the
+ * floor while the CDP call itself still answers `{}` — clicks and keys that
+ * silently do nothing, with no error anywhere. Keep the window's visibility
+ * state application-controlled instead; the parent already shows/raises views
+ * explicitly, and `webContentsView.setVisible()` remains the single source of
+ * truth for whether a view renders.
+ */
+function keepWindowsNonOccluding() {
+    if (process.platform !== 'win32')
+        return;
+    const DISABLED = 'CalculateNativeWinOcclusion';
+    const current = app.commandLine.getSwitchValue('disable-features') ?? '';
+    const features = current
+        .split(',')
+        .map(part => part.trim())
+        .filter(part => part !== '');
+    if (!features.includes(DISABLED))
+        features.push(DISABLED);
+    app.commandLine.appendSwitch('disable-features', features.join(','));
+}
+keepWindowsNonOccluding();
 /**
  * Electron entry: connect back to the parent's RPC server (port from
  * `--rpc-port`) and serve line-delimited JSON-RPC. `ELECTRON_RUN_AS_NODE` is

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

@@ -126,6 +126,12 @@ export interface ElectronViewHandle {
      * @returns the CDP `result` object.
      */
     sendCommand(method: string, params?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Give the backing view web focus so keyboard input reaches its page.
+     * Optional: an adapter that cannot focus a view omits it, and the provider
+     * then behaves exactly as before.
+     */
+    focus?(): Promise<void>;
 }
 /** Provider config: navigation admission defaults and snapshot caps. */
 export interface ElectronBrowserProviderConfig {
@@ -151,14 +157,16 @@ export interface CdpNavigateParams {
     readonly url: string;
 }
 /**
- * CDP method/params for `Input.dispatchMouseEvent` (a click press+release pair).
+ * CDP method/params for `Input.dispatchMouseEvent`: a pointer move, or one half
+ * of a click's press+release pair. `button`/`clickCount` belong to the press and
+ * release halves; a move carries only the position.
  */
 export interface CdpMouseParams {
-    readonly type: 'mousePressed' | 'mouseReleased';
+    readonly type: 'mouseMoved' | 'mousePressed' | 'mouseReleased';
     readonly x: number;
     readonly y: number;
-    readonly button: 'left';
-    readonly clickCount: number;
+    readonly button?: 'left';
+    readonly clickCount?: number;
 }
 /** CDP method/params for `Input.insertText`. */
 export interface CdpInsertTextParams {
@@ -278,6 +286,17 @@ export declare class ElectronBrowserProvider implements BrowserProvider {
      * rather than reporting a success the page never saw.
      */
     private present;
+    /**
+     * Give the view web focus before synthesizing keyboard input.
+     *
+     * A renderer only delivers key events to the view that holds web focus. A
+     * view that was created but never clicked holds none — and `Input` events
+     * injected over CDP do not grant it — so the FIRST `browser_key` of a fresh
+     * session vanished inside the renderer while the command still answered
+     * success. Hosts that cannot focus a view (a test double, a different shell
+     * adapter) simply have no `focus`, and nothing changes for them.
+     */
+    private focusView;
     /** Execute JS in the active tab's page context. */
     execute(session: BrowserSessionId, request: BrowserExecuteRequest, signal?: AbortSignal): Promise<BrowserExecuteResult>;
     /**
@@ -342,6 +361,8 @@ export declare class ElectronBrowserProvider implements BrowserProvider {
      * (polling until it appears or the budget runs out) and then runs `body`
      * with `el` in scope. Shared by the target-based tools: click/type (②),
      * setValue/check/select/clear/getValue (③), and the scrape item wait.
+     * A selector that fails to PARSE is reported immediately instead of being
+     * polled until the budget expires — see the comment in `match`.
      */
     private buildTargetScript;
     /**

package/lib/browser-electron/provider.js

@@ -419,6 +419,27 @@ export class ElectronBrowserProvider {
             throw new BrowserError(`browser: the page view is not presented, so synthesized input would be silently dropped (${String(error)})`, 'BROWSER_VIEW_NOT_PRESENTED', { cause: error });
         }
     }
+    /**
+     * Give the view web focus before synthesizing keyboard input.
+     *
+     * A renderer only delivers key events to the view that holds web focus. A
+     * view that was created but never clicked holds none — and `Input` events
+     * injected over CDP do not grant it — so the FIRST `browser_key` of a fresh
+     * session vanished inside the renderer while the command still answered
+     * success. Hosts that cannot focus a view (a test double, a different shell
+     * adapter) simply have no `focus`, and nothing changes for them.
+     */
+    async focusView(handle) {
+        if (handle.focus === undefined)
+            return;
+        try {
+            await handle.focus();
+        }
+        catch {
+            // Best-effort: a view that refuses focus must not fail the caller's key
+            // press; the dispatch below reports a real channel failure itself.
+        }
+    }
     /** Execute JS in the active tab's page context. */
     async execute(session, request, signal) {
         const s = this.session(session);
@@ -915,24 +936,48 @@ export class ElectronBrowserProvider {
         // Input.* is only delivered to a view with a current display surface; the
         // barrier also re-presents after a navigation replaced the renderer.
         await this.present(s, signal);
-        const press = (type) => handle.sendCommand('Input.dispatchMouseEvent', { type, x, y, button: 'left', clickCount: 1 });
         const timeoutMs = 30_000;
+        const send = (params, label) => withTimeout(handle.sendCommand('Input.dispatchMouseEvent', params), timeoutMs, signal, `browser: click ${label} timed out after ${timeoutMs}ms`);
+        // Chromium routes a synthesized `mousePressed` to the widget's *current*
+        // hover target rather than hit-testing the coordinates, and a real pointer
+        // click is always preceded by movement. A view that has never received a
+        // mouse event has no hover target yet, so the press of the FIRST click on a
+        // fresh tab went nowhere while CDP still answered success; the second click
+        // landed because the first had quietly established the target. Move the
+        // pointer first so a click is self-contained.
         try {
-            await withTimeout(press('mousePressed'), timeoutMs, signal, `browser: click press timed out after ${timeoutMs}ms`);
+            await send({ type: 'mouseMoved', x, y }, 'move');
+        }
+        catch (error) {
+            throw new BrowserError(`browser: click failed: ${String(error)}`, 'BROWSER_CLICK_FAILED', { cause: error });
+        }
+        const release = () => {
+            void handle
+                .sendCommand('Input.dispatchMouseEvent', {
+                type: 'mouseReleased',
+                x,
+                y,
+                button: 'left',
+                clickCount: 1,
+            })
+                .catch(() => { });
+        };
+        try {
+            await send({ type: 'mousePressed', x, y, button: 'left', clickCount: 1 }, 'press');
         }
         catch (error) {
             // The press may still land late; release best-effort so the button is
             // never left in a stuck pressed state.
-            void press('mouseReleased').catch(() => { });
+            release();
             throw new BrowserError(`browser: click failed: ${String(error)}`, 'BROWSER_CLICK_FAILED', { cause: error });
         }
         try {
-            await withTimeout(press('mouseReleased'), timeoutMs, signal, `browser: click release timed out after ${timeoutMs}ms`);
+            await send({ type: 'mouseReleased', x, y, button: 'left', clickCount: 1 }, 'release');
         }
         catch (error) {
             // The press already landed; retry the release so the button is not
             // left pressed before surfacing the failure.
-            void press('mouseReleased').catch(() => { });
+            release();
             throw new BrowserError(`browser: click failed: ${String(error)}`, 'BROWSER_CLICK_FAILED', { cause: error });
         }
         this.record(s, 'click', 'target' in request ? { target: request.target } : { x, y }, true);
@@ -1061,6 +1106,7 @@ export class ElectronBrowserProvider {
         const timeoutMs = 15_000;
         // Input.dispatchKeyEvent is subject to the same display-surface rule.
         await this.present(s, signal);
+        await this.focusView(handle);
         const release = () => handle.sendCommand('Input.dispatchKeyEvent', { type: 'keyUp', ...params });
         try {
             await withTimeout(handle.sendCommand('Input.dispatchKeyEvent', { type: 'keyDown', ...params }), timeoutMs, signal, `browser: key press timed out after ${timeoutMs}ms`);
@@ -1231,10 +1277,16 @@ export class ElectronBrowserProvider {
      * (polling until it appears or the budget runs out) and then runs `body`
      * with `el` in scope. Shared by the target-based tools: click/type (②),
      * setValue/check/select/clear/getValue (③), and the scrape item wait.
+     * A selector that fails to PARSE is reported immediately instead of being
+     * polled until the budget expires — see the comment in `match`.
      */
     buildTargetScript(spec, timeoutMs, body) {
+        // `by` defaults to css in-page; report the strategy that WAS used, or a
+        // miss says only `{"value":"Learn more"}` and the caller cannot tell that a
+        // plain label was queried as a CSS selector.
+        const resolvedSpec = { ...spec, by: spec.by ?? 'css' };
         return `(async () => {
-      const spec = ${JSON.stringify(spec)}
+      const spec = ${JSON.stringify(resolvedSpec)}
       const timeoutMs = ${String(timeoutMs)}
       const sleep = ms => new Promise(r => setTimeout(r, ms))
       const isVisible = el => el instanceof HTMLElement && (el.offsetWidth > 0 || el.offsetHeight > 0 || el.getClientRects().length > 0)
@@ -1246,7 +1298,13 @@ export class ElectronBrowserProvider {
         const index = typeof spec.index === 'number' ? spec.index : 0
         let els = []
         if (by === 'css') {
-          try { els = Array.from(document.querySelectorAll(value)) } catch { return null }
+          // A selector that does not PARSE can never match on a later poll, so
+          // it must not look like a miss: the old "return null" kept the caller
+          // polling until the whole budget was gone, and "element not found
+          // after 10s" reads like a slow page while the real cause is a
+          // malformed selector (a label or plain text passed where one belongs).
+          try { els = Array.from(document.querySelectorAll(value)) }
+          catch (error) { throw new Error('invalid CSS selector ' + JSON.stringify(value) + ' (' + String((error && error.message) || error) + ')') }
         } else if (by === 'xpath') {
           try {
             const snap = document.evaluate(value, document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null)
@@ -1254,7 +1312,7 @@ export class ElectronBrowserProvider {
               const n = snap.snapshotItem(i)
               if (n instanceof Element) els.push(n)
             }
-          } catch { return null }
+          } catch (error) { throw new Error('invalid XPath ' + JSON.stringify(value) + ' (' + String((error && error.message) || error) + ')') }
         } else {
           const all = Array.from(document.querySelectorAll('body *'))
           const exact = all.filter(el => isVisible(el) && ownText(el) === value)
@@ -1268,9 +1326,10 @@ export class ElectronBrowserProvider {
       const deadline = Date.now() + timeoutMs
       let el = null
       for (;;) {
-        el = match()
+        // Only a parse error escapes the poll: see the comment in match() above.
+        try { el = match() } catch (error) { return { ok: false, error: String((error && error.message) || error) } }
         if (el !== null) break
-        if (Date.now() >= deadline) return { ok: false, error: 'element not found: ' + JSON.stringify(spec) }
+        if (Date.now() >= deadline) return { ok: false, error: 'element not found: ' + JSON.stringify(spec) + ' (looked for ' + timeoutMs + 'ms)' }
         await sleep(100)
       }
       ${body}
@@ -1282,7 +1341,12 @@ export class ElectronBrowserProvider {
      * evaluation failure or an in-page `{ ok: false, error }` verdict.
      */
     async runTargetScript(tab, script, timeoutMs, signal, errorCode, errorLabel) {
-        const result = await withTimeout(handleSendEvaluate(tab.handle, script), timeoutMs, signal, `${errorLabel} timed out after ${timeoutMs}ms`, () => terminatePage(tab.handle));
+        // The script polls for its whole `timeoutMs` and only then answers, so an
+        // outer budget of the same size fires at the same instant and wins: the
+        // caller saw `click timed out after 10000ms` while the page had already
+        // decided WHY (selector not found / malformed). Give the answer a chance to
+        // get back before the generic timeout replaces it.
+        const result = await withTimeout(handleSendEvaluate(tab.handle, script), timeoutMs + TARGET_SCRIPT_GRACE_MS, signal, `${errorLabel} timed out after ${timeoutMs}ms`, () => terminatePage(tab.handle));
         if (!result.ok)
             throw new BrowserError(`${errorLabel} failed: ${result.exception}`, errorCode);
         const value = result.value;
@@ -1474,7 +1538,9 @@ export class ElectronBrowserProvider {
       const deadline = Date.now() + timeoutMs
       let items = []
       for (;;) {
-        try { items = Array.from(document.querySelectorAll(itemSel)) } catch (e) { return { ok: false, error: String(e) } }
+        // Immediate, like match() above: an unparseable selector can never match.
+        try { items = Array.from(document.querySelectorAll(itemSel)) }
+        catch (error) { return { ok: false, error: 'invalid CSS selector ' + JSON.stringify(itemSel) + ' (' + String((error && error.message) || error) + ')' } }
         if (items.length > 0) break
         if (Date.now() >= deadline) return { ok: false, error: 'no elements matched: ' + itemSel }
         await sleep(100)
@@ -1913,6 +1979,12 @@ const SETTLE_TIMEOUT_MS = 5_000;
 const SETTLE_GRACE_MS = 150;
 /** Poll interval for the document-settle loop. */
 const SETTLE_POLL_MS = 25;
+/**
+ * Extra time the transport gets over an in-page locate script's own budget: the
+ * script polls for `timeoutMs` and answers only afterwards, so the outer wait
+ * must outlast it or its generic timeout hides the in-page reason.
+ */
+const TARGET_SCRIPT_GRACE_MS = 2_000;
 /** `tab:<uuid>` ↔ `<uuid>`: ids accept either form (see locateTab). */
 function stripTabPrefix(id) {
     return id.startsWith('tab:') ? id.slice(4) : id;

package/lib/browser-electron/remote-host.d.ts

@@ -99,14 +99,20 @@ export declare class RemoteElectronViewHost implements ElectronBrowserViewHost {
     /** Test seam: the executable to spawn instead of the resolved Electron
      *  binary. Absent -> resolveElectronPath() (production behavior). */
     private readonly spawnExecutable?;
+    /** Test seam: the binary probe behind `available()`. Absent ->
+     *  resolveElectronPath(). */
+    private readonly probe;
     private client;
     private server;
     private pendingSocket;
     private readonly views;
     private readyPromise;
     private disposed;
-    /** Cached probe result so `available()` stays cheap after the first call. */
+    /** Last probe result. A success is kept for the host's lifetime; a failure
+     *  is retried after `PROBE_RETRY_MS` (see `available()`). */
     private electronAvailable;
+    /** Earliest time the next probe may run after a negative one. */
+    private nextProbeAt;
     /** Window groups (windowId per view), re-sent on every materialization so
      *  a restarted child still places views in the right windows. */
     private readonly groups;
@@ -115,13 +121,22 @@ export declare class RemoteElectronViewHost implements ElectronBrowserViewHost {
     constructor(hostMainPath: string, 
     /** Test seam: the executable to spawn instead of the resolved Electron
      *  binary. Absent -> resolveElectronPath() (production behavior). */
-    spawnExecutable?: string | undefined);
+    spawnExecutable?: string | undefined, 
+    /** Test seam: the binary probe behind `available()`. Absent ->
+     *  resolveElectronPath(). */
+    probe?: () => void);
     /**
      * Cheap usability probe: can we find an Electron binary to spawn? The scan
-     * is filesystem-only (no network), per the seam's contract, and the result
-     * is cached for the host's lifetime — a missing binary surfaces as
-     * `BROWSER_PROVIDER_UNAVAILABLE` at provider selection instead of a
-     * confusing spawn failure on first use.
+     * is filesystem-only (no network), per the seam's contract, so a missing
+     * binary surfaces as `BROWSER_PROVIDER_UNAVAILABLE` at provider selection
+     * instead of a confusing spawn failure on first use.
+     *
+     * A success is cached for the host's lifetime. A failure is NOT: an install
+     * (`npm i electron`, or the postinstall that fetches the binary) can land
+     * long after DSH started, and provider selection happens once per process —
+     * caching "no" permanently reported "no usable browser provider is
+     * registered" until DSH restarted, with no way back short of that. Retrying
+     * on a cooldown heals it by itself while keeping the scan off the hot path.
      */
     available(): boolean;
     /** Ensure the child is up and ready (lazy on first use; restarts after a crash). */

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

@@ -624,6 +624,10 @@ class RemoteView {
             params: params ?? {},
         });
     }
+    /** Give this view web focus in the child, so keyboard input reaches the page. */
+    focus() {
+        return this.client.call('focus', { viewId: this.id });
+    }
     /** Ask the child to download a URL to a local file (keeps cookies/login). */
     async download(url, savePath) {
         // The child writes the file itself (temp + rename); only a small
@@ -644,6 +648,14 @@ class RemoteView {
         return this.client.call('restoreAuth', { viewId: this.id, cookies }).then(r => r.restored);
     }
 }
+/**
+ * How long a FAILED Electron-binary probe is remembered before the binary
+ * search runs again (`available()`). A success is kept for the host's lifetime.
+ */
+const PROBE_RETRY_MS = (() => {
+    const raw = Number(process.env.DSH_BROWSER_PROBE_RETRY_MS);
+    return Number.isFinite(raw) && raw >= 0 ? raw : 30000;
+})();
 /**
  * Self-hosted view host: spawns the plugin's Electron child on first use and
  * keeps it alive until dispose(). Fallback when no desktop shell provides
@@ -652,14 +664,18 @@ class RemoteView {
 export class RemoteElectronViewHost {
     hostMainPath;
     spawnExecutable;
+    probe;
     client;
     server;
     pendingSocket;
     views = new Map();
     readyPromise;
     disposed = false;
-    /** Cached probe result so `available()` stays cheap after the first call. */
+    /** Last probe result. A success is kept for the host's lifetime; a failure
+     *  is retried after `PROBE_RETRY_MS` (see `available()`). */
     electronAvailable;
+    /** Earliest time the next probe may run after a negative one. */
+    nextProbeAt = 0;
     /** Window groups (windowId per view), re-sent on every materialization so
      *  a restarted child still places views in the right windows. */
     groups = new Map();
@@ -668,30 +684,43 @@ export class RemoteElectronViewHost {
     constructor(hostMainPath, 
     /** Test seam: the executable to spawn instead of the resolved Electron
      *  binary. Absent -> resolveElectronPath() (production behavior). */
-    spawnExecutable) {
+    spawnExecutable, 
+    /** Test seam: the binary probe behind `available()`. Absent ->
+     *  resolveElectronPath(). */
+    probe = resolveElectronPath) {
         this.hostMainPath = hostMainPath;
         this.spawnExecutable = spawnExecutable;
+        this.probe = probe;
     }
     /**
      * Cheap usability probe: can we find an Electron binary to spawn? The scan
-     * is filesystem-only (no network), per the seam's contract, and the result
-     * is cached for the host's lifetime — a missing binary surfaces as
-     * `BROWSER_PROVIDER_UNAVAILABLE` at provider selection instead of a
-     * confusing spawn failure on first use.
+     * is filesystem-only (no network), per the seam's contract, so a missing
+     * binary surfaces as `BROWSER_PROVIDER_UNAVAILABLE` at provider selection
+     * instead of a confusing spawn failure on first use.
+     *
+     * A success is cached for the host's lifetime. A failure is NOT: an install
+     * (`npm i electron`, or the postinstall that fetches the binary) can land
+     * long after DSH started, and provider selection happens once per process —
+     * caching "no" permanently reported "no usable browser provider is
+     * registered" until DSH restarted, with no way back short of that. Retrying
+     * on a cooldown heals it by itself while keeping the scan off the hot path.
      */
     available() {
-        if (this.electronAvailable === undefined) {
-            try {
-                resolveElectronPath();
-                this.electronAvailable = true;
-            }
-            catch (error) {
-                this.electronAvailable = false;
-                // The provider will be reported unavailable, so the detailed
-                // resolution error (install-electron / ELECTRON_PATH guidance) would
-                // otherwise never reach the user — surface it on stderr.
-                process.stderr.write(`[dsh-browser host] electron unavailable: ${error instanceof Error ? error.message : String(error)}\n`);
-            }
+        if (this.electronAvailable === true)
+            return true;
+        if (Date.now() < this.nextProbeAt)
+            return false;
+        this.nextProbeAt = Date.now() + PROBE_RETRY_MS;
+        try {
+            this.probe();
+            this.electronAvailable = true;
+        }
+        catch (error) {
+            this.electronAvailable = false;
+            // The provider will be reported unavailable, so the detailed
+            // resolution error (install-electron / ELECTRON_PATH guidance) would
+            // otherwise never reach the user — surface it on stderr.
+            process.stderr.write(`[dsh-browser host] electron unavailable: ${error instanceof Error ? error.message : String(error)}\n`);
         }
         return this.electronAvailable;
     }
@@ -978,6 +1007,9 @@ class DeferredRemoteView {
     async capture(opts) {
         return this.withRecovery(view => view.capture(opts));
     }
+    async focus() {
+        return this.withRecovery(view => view.focus());
+    }
     async flushAuth() {
         return this.withRecovery(view => view.flushAuth());
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-builtin-browser",
-  "version": "0.1.22",
+  "version": "0.1.23",
   "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",
@@ -65,9 +65,9 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-tools": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-llm": ">=0.1.1-rc.2 <0.3.0",
+    "@deepseek-ai/dsh-tools": ">=0.1.1-rc.2 <0.3.0",
+    "@deepseek-ai/dsh-system-prompt": ">=0.1.1-rc.2 <0.3.0",
     "@deepseek-ai/schemastery": "^3.18.1"
   },
   "devDependencies": {
@@ -79,7 +79,7 @@
       "patch": "./cordis.patch.yml"
     },
     "compatibility": {
-      "dsh": ">=0.1.1-rc.1 <0.2.0",
+      "dsh": ">=0.1.1-rc.1 <0.3.0",
       "profiles": [
         "web",
         "desktop"
@@ -87,7 +87,9 @@
       "dshReleases": {
         "0.1.0-rc.8": "unknown",
         "0.1.1-rc.1": "compatible",
-        "0.1.1-rc.2": "compatible"
+        "0.1.1-rc.2": "compatible",
+        "0.2.0-rc.1": "compatible",
+        "0.2.0-rc.2": "compatible"
       }
     }
   }

package/src/browser/runtime.ts

@@ -177,7 +177,21 @@ export class BrowserRuntime extends Service {
     const usable = [...providers.values()].filter(provider => provider.available())
     const [single] = usable
     if (single === undefined) {
-      throw new BrowserError('no usable browser provider is registered', 'BROWSER_PROVIDER_UNAVAILABLE')
+      // Two very different causes used to read identically here — nothing is
+      // registered, or something is registered but cannot run — and only the
+      // second one has a fix the user can apply without reinstalling.
+      const registered = [...providers.values()].map(provider => provider.id)
+      if (registered.length === 0) {
+        throw new BrowserError(
+          'no browser provider is registered — install a browser plugin (e.g. dsh-builtin-browser) and enable it in this profile',
+          'BROWSER_PROVIDER_UNAVAILABLE',
+        )
+      }
+      throw new BrowserError(
+        `browser provider(s) ${registered.join(', ')} are registered but report themselves unavailable — `
+        + 'for dsh-builtin-browser this means no spawnable Electron binary was found; run `npx install-electron` in the active profile or set ELECTRON_PATH',
+        'BROWSER_PROVIDER_UNAVAILABLE',
+      )
     }
     if (usable.length > 1) {
       const ids = usable.map(provider => provider.id).join(', ')

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

@@ -13,6 +13,7 @@
  *      { id, op: 'destroyView', viewId } | { id, op: 'showView', viewId } |
  *      { id, op: 'groupView', viewId, windowId, label? } |
  *      { id, op: 'command', viewId, method, params } |
+ *      { id, op: 'focus', viewId } |
  *      { id, op: 'userActionError', windowId, message }
  *   -> { id: 0, op: 'hello', token } (our FIRST message — proves we know the
  *      parent's stdin token; the parent refuses the connection otherwise)
@@ -286,6 +287,14 @@ function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise
  */
 const COMMAND_TIMEOUT_MS = 20000
 
+/**
+ * How long to let a `focus` request land before answering it. Focus moves
+ * asynchronously and a key dispatched in the same turn as the request is still
+ * dropped, so the caller needs this settle — but only on the call where focus
+ * actually had to move.
+ */
+const FOCUS_SETTLE_MS = 80
+
 /**
  * A brand-new WebContentsView has no renderer process until something loads,
  * and CDP commands (Runtime.evaluate …) sent to a renderer-less view never
@@ -714,6 +723,26 @@ async function handle(op: string, msg: { id: number; viewId?: string; windowId?:
         reply(msg.id, { ok: true, result })
         return
       }
+      case 'focus': {
+        const viewId = msg.viewId
+        if (viewId === undefined) throw new Error('focus missing viewId')
+        const win = windowOfView(viewId)
+        const entry = win?.views.get(viewId)
+        if (win === undefined || entry === undefined) throw new Error(`focus: unknown view ${viewId}`)
+        // Keys go to the view that holds web focus. A view that was never
+        // clicked holds none, so the FIRST browser_key of a session was dropped
+        // by the renderer while CDP still answered the dispatch with success —
+        // and `document.hasFocus()` inside the page even read true.
+        const contents = entry.webContentsView.webContents
+        const hadWebFocus = contents.isFocused()
+        contents.focus()
+        // Focus lands asynchronously, and a key dispatched in the same turn as
+        // the request is still dropped, so hold the reply until the renderer can
+        // take input. Only on the call where focus actually had to move.
+        if (!hadWebFocus) await new Promise(resolve => setTimeout(resolve, FOCUS_SETTLE_MS))
+        reply(msg.id, { ok: true, focused: contents.isFocused() })
+        return
+      }
       case 'capture': {
         const viewId = msg.viewId
         if (viewId === undefined) throw new Error('capture missing viewId')
@@ -942,6 +971,34 @@ async function handle(op: string, msg: { id: number; viewId?: string; windowId?:
   }
 }
 
+/**
+ * Chromium's native-window occlusion tracker (Windows only) asks DWM whether a
+ * window is covered by another window and, when it is, moves the WebContents to
+ * `Visibility::HIDDEN`. That is the wrong model for this host: the shared
+ * browser window normally sits *behind* whatever the human is working in, and
+ * that is exactly the state the agent drives it from. A hidden WebContents
+ * produces no frames at all (`requestAnimationFrame` never fires) and
+ * `RenderWidgetHostImpl::CanReceiveInput()` returns false, so every
+ * `Input.dispatchMouseEvent`/`dispatchKeyEvent` sent over CDP is dropped on the
+ * floor while the CDP call itself still answers `{}` — clicks and keys that
+ * silently do nothing, with no error anywhere. Keep the window's visibility
+ * state application-controlled instead; the parent already shows/raises views
+ * explicitly, and `webContentsView.setVisible()` remains the single source of
+ * truth for whether a view renders.
+ */
+function keepWindowsNonOccluding(): void {
+  if (process.platform !== 'win32') return
+  const DISABLED = 'CalculateNativeWinOcclusion'
+  const current = app.commandLine.getSwitchValue('disable-features') ?? ''
+  const features = current
+    .split(',')
+    .map(part => part.trim())
+    .filter(part => part !== '')
+  if (!features.includes(DISABLED)) features.push(DISABLED)
+  app.commandLine.appendSwitch('disable-features', features.join(','))
+}
+keepWindowsNonOccluding()
+
 /**
  * Electron entry: connect back to the parent's RPC server (port from
  * `--rpc-port`) and serve line-delimited JSON-RPC. `ELECTRON_RUN_AS_NODE` is

package/src/browser-electron/provider.ts

@@ -207,6 +207,12 @@ export interface ElectronViewHandle {
    * @returns the CDP `result` object.
    */
   sendCommand(method: string, params?: Record<string, unknown>): Promise<Record<string, unknown>>
+  /**
+   * Give the backing view web focus so keyboard input reaches its page.
+   * Optional: an adapter that cannot focus a view omits it, and the provider
+   * then behaves exactly as before.
+   */
+  focus?(): Promise<void>
 }
 
 /** One tab inside a session: its view plus a stable id. */
@@ -254,14 +260,16 @@ export interface CdpNavigateParams {
 }
 
 /**
- * CDP method/params for `Input.dispatchMouseEvent` (a click press+release pair).
+ * CDP method/params for `Input.dispatchMouseEvent`: a pointer move, or one half
+ * of a click's press+release pair. `button`/`clickCount` belong to the press and
+ * release halves; a move carries only the position.
  */
 export interface CdpMouseParams {
-  readonly type: 'mousePressed' | 'mouseReleased'
+  readonly type: 'mouseMoved' | 'mousePressed' | 'mouseReleased'
   readonly x: number
   readonly y: number
-  readonly button: 'left'
-  readonly clickCount: number
+  readonly button?: 'left'
+  readonly clickCount?: number
 }
 
 /** CDP method/params for `Input.insertText`. */
@@ -664,6 +672,26 @@ export class ElectronBrowserProvider implements BrowserProvider {
     }
   }
 
+  /**
+   * Give the view web focus before synthesizing keyboard input.
+   *
+   * A renderer only delivers key events to the view that holds web focus. A
+   * view that was created but never clicked holds none — and `Input` events
+   * injected over CDP do not grant it — so the FIRST `browser_key` of a fresh
+   * session vanished inside the renderer while the command still answered
+   * success. Hosts that cannot focus a view (a test double, a different shell
+   * adapter) simply have no `focus`, and nothing changes for them.
+   */
+  private async focusView(handle: ElectronViewHandle): Promise<void> {
+    if (handle.focus === undefined) return
+    try {
+      await handle.focus()
+    } catch {
+      // Best-effort: a view that refuses focus must not fail the caller's key
+      // press; the dispatch below reports a real channel failure itself.
+    }
+  }
+
   /** Execute JS in the active tab's page context. */
   async execute(session: BrowserSessionId, request: BrowserExecuteRequest, signal?: AbortSignal): Promise<BrowserExecuteResult> {
     const s = this.session(session)
@@ -1196,23 +1224,51 @@ export class ElectronBrowserProvider implements BrowserProvider {
     // Input.* is only delivered to a view with a current display surface; the
     // barrier also re-presents after a navigation replaced the renderer.
     await this.present(s, signal)
-    const press = (type: 'mousePressed' | 'mouseReleased'): Promise<Record<string, unknown>> =>
-      handle.sendCommand('Input.dispatchMouseEvent', { type, x, y, button: 'left', clickCount: 1 } satisfies CdpMouseParams)
     const timeoutMs = 30_000
+    const send = (params: Record<string, unknown>, label: string): Promise<unknown> =>
+      withTimeout(
+        handle.sendCommand('Input.dispatchMouseEvent', params),
+        timeoutMs,
+        signal,
+        `browser: click ${label} timed out after ${timeoutMs}ms`,
+      )
+    // Chromium routes a synthesized `mousePressed` to the widget's *current*
+    // hover target rather than hit-testing the coordinates, and a real pointer
+    // click is always preceded by movement. A view that has never received a
+    // mouse event has no hover target yet, so the press of the FIRST click on a
+    // fresh tab went nowhere while CDP still answered success; the second click
+    // landed because the first had quietly established the target. Move the
+    // pointer first so a click is self-contained.
     try {
-      await withTimeout(press('mousePressed'), timeoutMs, signal, `browser: click press timed out after ${timeoutMs}ms`)
+      await send({ type: 'mouseMoved', x, y } satisfies CdpMouseParams, 'move')
+    } catch (error) {
+      throw new BrowserError(`browser: click failed: ${String(error)}`, 'BROWSER_CLICK_FAILED', { cause: error })
+    }
+    const release = (): void => {
+      void handle
+        .sendCommand('Input.dispatchMouseEvent', {
+          type: 'mouseReleased',
+          x,
+          y,
+          button: 'left',
+          clickCount: 1,
+        } satisfies CdpMouseParams)
+        .catch(() => {})
+    }
+    try {
+      await send({ type: 'mousePressed', x, y, button: 'left', clickCount: 1 }, 'press')
     } catch (error) {
       // The press may still land late; release best-effort so the button is
       // never left in a stuck pressed state.
-      void press('mouseReleased').catch(() => {})
+      release()
       throw new BrowserError(`browser: click failed: ${String(error)}`, 'BROWSER_CLICK_FAILED', { cause: error })
     }
     try {
-      await withTimeout(press('mouseReleased'), timeoutMs, signal, `browser: click release timed out after ${timeoutMs}ms`)
+      await send({ type: 'mouseReleased', x, y, button: 'left', clickCount: 1 }, 'release')
     } catch (error) {
       // The press already landed; retry the release so the button is not
       // left pressed before surfacing the failure.
-      void press('mouseReleased').catch(() => {})
+      release()
       throw new BrowserError(`browser: click failed: ${String(error)}`, 'BROWSER_CLICK_FAILED', { cause: error })
     }
     this.record(s, 'click', 'target' in request ? { target: request.target } : { x, y }, true)
@@ -1375,6 +1431,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
     const timeoutMs = 15_000
     // Input.dispatchKeyEvent is subject to the same display-surface rule.
     await this.present(s, signal)
+    await this.focusView(handle)
     const release = (): Promise<Record<string, unknown>> =>
       handle.sendCommand('Input.dispatchKeyEvent', { type: 'keyUp', ...params })
     try {
@@ -1552,10 +1609,16 @@ export class ElectronBrowserProvider implements BrowserProvider {
    * (polling until it appears or the budget runs out) and then runs `body`
    * with `el` in scope. Shared by the target-based tools: click/type (②),
    * setValue/check/select/clear/getValue (③), and the scrape item wait.
+   * A selector that fails to PARSE is reported immediately instead of being
+   * polled until the budget expires — see the comment in `match`.
    */
   private buildTargetScript(spec: BrowserElementTarget, timeoutMs: number, body: string): string {
+    // `by` defaults to css in-page; report the strategy that WAS used, or a
+    // miss says only `{"value":"Learn more"}` and the caller cannot tell that a
+    // plain label was queried as a CSS selector.
+    const resolvedSpec = { ...spec, by: spec.by ?? 'css' }
     return `(async () => {
-      const spec = ${JSON.stringify(spec)}
+      const spec = ${JSON.stringify(resolvedSpec)}
       const timeoutMs = ${String(timeoutMs)}
       const sleep = ms => new Promise(r => setTimeout(r, ms))
       const isVisible = el => el instanceof HTMLElement && (el.offsetWidth > 0 || el.offsetHeight > 0 || el.getClientRects().length > 0)
@@ -1567,7 +1630,13 @@ export class ElectronBrowserProvider implements BrowserProvider {
         const index = typeof spec.index === 'number' ? spec.index : 0
         let els = []
         if (by === 'css') {
-          try { els = Array.from(document.querySelectorAll(value)) } catch { return null }
+          // A selector that does not PARSE can never match on a later poll, so
+          // it must not look like a miss: the old "return null" kept the caller
+          // polling until the whole budget was gone, and "element not found
+          // after 10s" reads like a slow page while the real cause is a
+          // malformed selector (a label or plain text passed where one belongs).
+          try { els = Array.from(document.querySelectorAll(value)) }
+          catch (error) { throw new Error('invalid CSS selector ' + JSON.stringify(value) + ' (' + String((error && error.message) || error) + ')') }
         } else if (by === 'xpath') {
           try {
             const snap = document.evaluate(value, document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null)
@@ -1575,7 +1644,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
               const n = snap.snapshotItem(i)
               if (n instanceof Element) els.push(n)
             }
-          } catch { return null }
+          } catch (error) { throw new Error('invalid XPath ' + JSON.stringify(value) + ' (' + String((error && error.message) || error) + ')') }
         } else {
           const all = Array.from(document.querySelectorAll('body *'))
           const exact = all.filter(el => isVisible(el) && ownText(el) === value)
@@ -1589,9 +1658,10 @@ export class ElectronBrowserProvider implements BrowserProvider {
       const deadline = Date.now() + timeoutMs
       let el = null
       for (;;) {
-        el = match()
+        // Only a parse error escapes the poll: see the comment in match() above.
+        try { el = match() } catch (error) { return { ok: false, error: String((error && error.message) || error) } }
         if (el !== null) break
-        if (Date.now() >= deadline) return { ok: false, error: 'element not found: ' + JSON.stringify(spec) }
+        if (Date.now() >= deadline) return { ok: false, error: 'element not found: ' + JSON.stringify(spec) + ' (looked for ' + timeoutMs + 'ms)' }
         await sleep(100)
       }
       ${body}
@@ -1611,9 +1681,14 @@ export class ElectronBrowserProvider implements BrowserProvider {
     errorCode: string,
     errorLabel: string,
   ): Promise<Record<string, unknown>> {
+    // The script polls for its whole `timeoutMs` and only then answers, so an
+    // outer budget of the same size fires at the same instant and wins: the
+    // caller saw `click timed out after 10000ms` while the page had already
+    // decided WHY (selector not found / malformed). Give the answer a chance to
+    // get back before the generic timeout replaces it.
     const result = await withTimeout(
       handleSendEvaluate(tab.handle, script),
-      timeoutMs,
+      timeoutMs + TARGET_SCRIPT_GRACE_MS,
       signal,
       `${errorLabel} timed out after ${timeoutMs}ms`,
       () => terminatePage(tab.handle),
@@ -1813,7 +1888,9 @@ export class ElectronBrowserProvider implements BrowserProvider {
       const deadline = Date.now() + timeoutMs
       let items = []
       for (;;) {
-        try { items = Array.from(document.querySelectorAll(itemSel)) } catch (e) { return { ok: false, error: String(e) } }
+        // Immediate, like match() above: an unparseable selector can never match.
+        try { items = Array.from(document.querySelectorAll(itemSel)) }
+        catch (error) { return { ok: false, error: 'invalid CSS selector ' + JSON.stringify(itemSel) + ' (' + String((error && error.message) || error) + ')' } }
         if (items.length > 0) break
         if (Date.now() >= deadline) return { ok: false, error: 'no elements matched: ' + itemSel }
         await sleep(100)
@@ -2295,6 +2372,13 @@ const SETTLE_GRACE_MS = 150
 /** Poll interval for the document-settle loop. */
 const SETTLE_POLL_MS = 25
 
+/**
+ * Extra time the transport gets over an in-page locate script's own budget: the
+ * script polls for `timeoutMs` and answers only afterwards, so the outer wait
+ * must outlast it or its generic timeout hides the in-page reason.
+ */
+const TARGET_SCRIPT_GRACE_MS = 2_000
+
 /** `tab:<uuid>` ↔ `<uuid>`: ids accept either form (see locateTab). */
 function stripTabPrefix(id: string): string {
   return id.startsWith('tab:') ? id.slice(4) : id

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

@@ -657,6 +657,11 @@ class RemoteView implements ElectronViewHandle {
     })
   }
 
+  /** Give this view web focus in the child, so keyboard input reaches the page. */
+  focus(): Promise<void> {
+    return this.client.call<void>('focus', { viewId: this.id })
+  }
+
   /** Ask the child to download a URL to a local file (keeps cookies/login). */
   async download(url: string, savePath: string): Promise<void> {
     // The child writes the file itself (temp + rename); only a small
@@ -681,6 +686,15 @@ class RemoteView implements ElectronViewHandle {
   }
 }
 
+/**
+ * How long a FAILED Electron-binary probe is remembered before the binary
+ * search runs again (`available()`). A success is kept for the host's lifetime.
+ */
+const PROBE_RETRY_MS = (() => {
+  const raw = Number(process.env.DSH_BROWSER_PROBE_RETRY_MS)
+  return Number.isFinite(raw) && raw >= 0 ? raw : 30000
+})()
+
 /**
  * Self-hosted view host: spawns the plugin's Electron child on first use and
  * keeps it alive until dispose(). Fallback when no desktop shell provides
@@ -693,8 +707,11 @@ export class RemoteElectronViewHost implements ElectronBrowserViewHost {
   private readonly views = new Map<string, ElectronViewHandle>()
   private readyPromise: Promise<void> | undefined
   private disposed = false
-  /** Cached probe result so `available()` stays cheap after the first call. */
+  /** Last probe result. A success is kept for the host's lifetime; a failure
+   *  is retried after `PROBE_RETRY_MS` (see `available()`). */
   private electronAvailable: boolean | undefined
+  /** Earliest time the next probe may run after a negative one. */
+  private nextProbeAt = 0
   /** Window groups (windowId per view), re-sent on every materialization so
    *  a restarted child still places views in the right windows. */
   private readonly groups = new Map<string, { windowId: string; label?: string }>()
@@ -706,27 +723,37 @@ export class RemoteElectronViewHost implements ElectronBrowserViewHost {
     /** Test seam: the executable to spawn instead of the resolved Electron
      *  binary. Absent -> resolveElectronPath() (production behavior). */
     private readonly spawnExecutable?: string,
+    /** Test seam: the binary probe behind `available()`. Absent ->
+     *  resolveElectronPath(). */
+    private readonly probe: () => void = resolveElectronPath,
   ) {}
 
   /**
    * Cheap usability probe: can we find an Electron binary to spawn? The scan
-   * is filesystem-only (no network), per the seam's contract, and the result
-   * is cached for the host's lifetime — a missing binary surfaces as
-   * `BROWSER_PROVIDER_UNAVAILABLE` at provider selection instead of a
-   * confusing spawn failure on first use.
+   * is filesystem-only (no network), per the seam's contract, so a missing
+   * binary surfaces as `BROWSER_PROVIDER_UNAVAILABLE` at provider selection
+   * instead of a confusing spawn failure on first use.
+   *
+   * A success is cached for the host's lifetime. A failure is NOT: an install
+   * (`npm i electron`, or the postinstall that fetches the binary) can land
+   * long after DSH started, and provider selection happens once per process —
+   * caching "no" permanently reported "no usable browser provider is
+   * registered" until DSH restarted, with no way back short of that. Retrying
+   * on a cooldown heals it by itself while keeping the scan off the hot path.
    */
   available(): boolean {
-    if (this.electronAvailable === undefined) {
-      try {
-        resolveElectronPath()
-        this.electronAvailable = true
-      } catch (error) {
-        this.electronAvailable = false
-        // The provider will be reported unavailable, so the detailed
-        // resolution error (install-electron / ELECTRON_PATH guidance) would
-        // otherwise never reach the user — surface it on stderr.
-        process.stderr.write(`[dsh-browser host] electron unavailable: ${error instanceof Error ? error.message : String(error)}\n`)
-      }
+    if (this.electronAvailable === true) return true
+    if (Date.now() < this.nextProbeAt) return false
+    this.nextProbeAt = Date.now() + PROBE_RETRY_MS
+    try {
+      this.probe()
+      this.electronAvailable = true
+    } catch (error) {
+      this.electronAvailable = false
+      // The provider will be reported unavailable, so the detailed
+      // resolution error (install-electron / ELECTRON_PATH guidance) would
+      // otherwise never reach the user — surface it on stderr.
+      process.stderr.write(`[dsh-browser host] electron unavailable: ${error instanceof Error ? error.message : String(error)}\n`)
     }
     return this.electronAvailable
   }
@@ -1027,6 +1054,10 @@ class DeferredRemoteView implements ElectronViewHandle {
     return this.withRecovery(view => view.capture(opts))
   }
 
+  async focus(): Promise<void> {
+    return this.withRecovery(view => view.focus())
+  }
+
   async flushAuth(): Promise<ExportedCookie[]> {
     return this.withRecovery(view => view.flushAuth())
   }