dsh-builtin-browser 0.1.21 → 0.1.23

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)
@@ -32,19 +33,19 @@ import { dirname, join } from 'node:path';
  * The spawn token the parent sent via stdin (first line). Must be echoed in
  * our hello. Read from stdin so the token never appears in argv (WMI /
  * Process Explorer / /proc/*).
-
+ */
 // 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`)
+    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`);
 }
-
 /**
  * Read the spawn token. The parent sends it two ways and the child prefers
  * the first that yields a value:
@@ -141,7 +142,17 @@ button.tool:hover { background: rgba(255,255,255,.12); }
   <div class="strip" id="strip"></div>
   <div id="err"></div>
 <script>
-const bridge = window.bridge
+// The body runs inside an IIFE on purpose. The preload above exposes
+// window.bridge via contextBridge.exposeInMainWorld(), which installs a
+// NON-CONFIGURABLE global property. A top-level const/let named bridge here
+// would hit HasRestrictedGlobalProperty and throw a SyntaxError at PARSE time
+// — an early error, so the whole script is discarded: nothing gets bound, the
+// address bar and nav buttons go silently dead, and the user sees no error.
+// Function scope sidesteps that check (the tb name below stops the collision
+// from returning by habit) and keeps these bindings off the page global.
+// Keep this block free of backticks — it lives inside a TS template literal.
+(() => {
+const tb = window.bridge
 const addr = document.getElementById('addr')
 const strip = document.getElementById('strip')
 const errBox = document.getElementById('err')
@@ -152,7 +163,7 @@ function showErr(text) {
   clearTimeout(showErrT)
   showErrT = setTimeout(() => errBox.classList.remove('show'), 5000)
 }
-function post(action, payload) { bridge.post(action, payload || {}) }
+function post(action, payload) { tb.post(action, payload || {}) }
 document.getElementById('back').onclick = () => post('back')
 document.getElementById('fwd').onclick = () => post('forward')
 document.getElementById('reload').onclick = () => post('reload')
@@ -167,7 +178,7 @@ addr.addEventListener('keydown', e => {
     if (v !== '') { post('navigate', { url: v }); addr.blur() }
   }
 })
-bridge.onTabs(payload => {
+tb.onTabs(payload => {
   const tabs = (payload && payload.tabs) || []
   strip.textContent = ''
   for (const t of tabs) {
@@ -189,7 +200,8 @@ bridge.onTabs(payload => {
   const act = tabs.find(t => t.active)
   if (act && document.activeElement !== addr) addr.value = act.url || ''
 })
-bridge.onError(text => showErr(text))
+tb.onError(text => showErr(text))
+})()
 </script>
 </body>
 </html>
@@ -206,6 +218,49 @@ function ensureToolbarFiles() {
     writeFileSync(join(TOOLBAR_DIR, 'preload.js'), TOOLBAR_PRELOAD);
     writeFileSync(join(TOOLBAR_DIR, 'toolbar.html'), TOOLBAR_HTML);
 }
+/**
+ * Bound an await with a timeout. Used so a wedged renderer surfaces as an
+ * explicit error instead of a command that never settles.
+ */
+function withTimeout(promise, ms, label) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new Error(`${label} timed out after ${ms}ms`));
+        }, ms);
+        promise.then((value) => { clearTimeout(timer); resolve(value); }, (error) => { clearTimeout(timer); reject(error); });
+    });
+}
+/**
+ * CDP commands are bounded here as well as in the parent: a view whose
+ * renderer stopped responding must produce a clear error, not a hang that
+ * 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
+ * settle. That is what made a host restart unrecoverable: the provider
+ * rebuilds the session with a fresh blank view whose very first action is a
+ * location.href read, which hung until the tool timeout.
+ *
+ * Loading about:blank spawns the renderer, so the view answers the moment it
+ * exists; a real navigation replaces it right after. Bounded + best-effort —
+ * the caller still gets its reply if this fails.
+ */
+const RENDERER_PRIME_TIMEOUT_MS = 3000;
+async function primeRenderer(view) {
+    try {
+        await withTimeout(view.webContents.loadURL('about:blank'), RENDERER_PRIME_TIMEOUT_MS, 'renderer prime');
+    }
+    catch { /* best effort: the first real navigation creates the renderer */ }
+}
 /** Reply to the parent over the RPC socket. */
 function reply(id, payload) {
     if (rpcSocket === undefined) {
@@ -434,7 +489,19 @@ function showViewInWindow(win, viewId, label) {
     const entry = win.views.get(viewId);
     if (entry === undefined)
         return;
-    if (win.visibleViewId !== viewId) {
+    // A navigation replaced this view's renderer, and the new one has no
+    // display surface yet. Chromium drops CDP synthesized input (Input.*) for a
+    // view without a surface, which silently swallowed the FIRST click/keystroke
+    // after every navigation — and because the view was already the visible one,
+    // the dance below used to be skipped entirely. Force it once.
+    const mustRepresent = entry.needsRepresent;
+    if (mustRepresent) {
+        try {
+            entry.webContentsView.setVisible(false);
+        }
+        catch { /* destroyed */ }
+    }
+    if (win.visibleViewId !== viewId || mustRepresent) {
         // Hide every other view in THIS window, then show and RAISE the target
         // (topmost child wins). When the target is already visible, skip the
         // remove/re-add dance — doing it on every operation flickered.
@@ -453,6 +520,7 @@ function showViewInWindow(win, viewId, label) {
         }
         catch { /* window closing */ }
         win.visibleViewId = viewId;
+        entry.needsRepresent = false;
         syncToolbar(win);
     }
     // Always refresh the title: it reflects the CURRENT page of the visible
@@ -551,11 +619,19 @@ async function handle(op, msg) {
                 // New views start hidden: only the shown one may be visible.
                 view.setVisible(false);
                 win.window.contentView.addChildView(view);
-                win.views.set(viewId, { webContentsView: view });
+                win.views.set(viewId, { webContentsView: view, needsRepresent: false });
                 // Keep the window title and the toolbar tab strip live as the page
                 // changes (navigations, title updates).
                 view.webContents.on('page-title-updated', () => { updateWindowTitle(win, viewId, undefined); syncToolbar(win); });
-                view.webContents.on('did-navigate', () => { updateWindowTitle(win, viewId, undefined); syncToolbar(win); });
+                view.webContents.on('did-navigate', () => {
+                    // The renderer process was just replaced: mark the view so the next
+                    // show forces a fresh display surface (see showViewInWindow).
+                    const current = win.views.get(viewId);
+                    if (current !== undefined)
+                        current.needsRepresent = true;
+                    updateWindowTitle(win, viewId, undefined);
+                    syncToolbar(win);
+                });
                 view.webContents.on('did-navigate-in-page', () => syncToolbar(win));
                 wireFocusRouting(win, view, viewId);
                 const first = win.views.size === 1;
@@ -567,6 +643,10 @@ async function handle(op, msg) {
                 if (first)
                     updateWindowTitle(win, viewId, undefined);
                 syncToolbar(win);
+                // Prime the renderer BEFORE replying: the parent's next command
+                // (a location.href read) would otherwise hang on a view that has no
+                // renderer yet — the root of "host restarted and never recovers".
+                await primeRenderer(view);
                 reply(msg.id, { ok: true });
                 return;
             }
@@ -649,10 +729,33 @@ async function handle(op, msg) {
                 const method = msg.method;
                 if (typeof method !== 'string')
                     throw new Error('command missing method');
-                const result = await entry.webContentsView.webContents.debugger.sendCommand(method, msg.params ?? {});
+                const result = await withTimeout(entry.webContentsView.webContents.debugger.sendCommand(method, msg.params ?? {}), COMMAND_TIMEOUT_MS, `CDP ${method}`);
                 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)
@@ -925,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
@@ -965,6 +1097,13 @@ void app.whenReady().then(() => {
         }
     }
     const rl = createInterface({ input: socket });
+    // Handle messages STRICTLY in order. Ops depend on each other completing:
+    // a `command` for a view must not overtake the `createView` that makes it,
+    // and the parent's present-barrier (`showView` then `ping`) is only
+    // meaningful if the child cannot answer the ping mid-show. The previous
+    // fire-and-forget loop let all of them race, which is how a fresh tab's
+    // first click could be dispatched before its view was ever on screen.
+    let queue = Promise.resolve();
     rl.on('line', line => {
         const text = line.trim();
         if (text === '')
@@ -978,7 +1117,10 @@ void app.whenReady().then(() => {
         }
         if (typeof msg.id !== 'number' || typeof msg.op !== 'string')
             return;
-        void handle(msg.op, msg).catch(() => { });
+        // Bind the narrowed op now: the check above does not survive into the
+        // deferred callback (msg is a mutable binding).
+        const op = msg.op;
+        queue = queue.then(() => handle(op, msg)).catch(() => { });
     });
     socket.on('error', error => {
         process.stderr.write(`[dsh-browser host] socket error: ${String(error)}\n`);

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

@@ -37,6 +37,20 @@ export interface ElectronBrowserViewHost {
      * tell which task's page is currently visible.
      */
     showView?(handle: ElectronViewHandle, label?: string): void;
+    /**
+     * Optional: (re)present a view and WAIT until the host confirms it. Chromium
+     * silently drops CDP-synthesized input (`Input.*`) for a view that has no
+     * display surface, which made clicks/typing report success while the page
+     * received nothing (and made the first input after a navigation vanish,
+     * because the replaced renderer has no surface yet). Unlike
+     * {@link showView}, this round-trips an RPC barrier that is ordered AFTER
+     * the show on the same socket, so its reply means the view is on screen.
+     * Rejects when the view cannot be presented; a host without this method is
+     * assumed to present every view (headless/probe hosts).
+     * @param handle - the handle to present.
+     * @param label - human-readable session/task label, as in {@link showView}.
+     */
+    presentView?(handle: ElectronViewHandle, label?: string): Promise<void>;
     /**
      * Optional cheap usability probe (no network): whether the host can back
      * views at all right now. The self-hosted host checks for a usable Electron
@@ -112,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 {
@@ -137,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 {
@@ -226,6 +248,55 @@ export declare class ElectronBrowserProvider implements BrowserProvider {
     navigate(session: BrowserSessionId, request: {
         readonly url: string;
     }, signal?: AbortSignal): Promise<void>;
+    /**
+     * A per-document stamp: `performance.timeOrigin` is unique per document load,
+     * so it tells a same-URL reload and an A→B→A redirect apart from the document
+     * that was current before the navigation. Empty string when unreadable.
+     */
+    private documentStamp;
+    /**
+     * One cheap in-page reading of the document's identity and parse state.
+     *
+     * Returns null when the page did NOT answer (mid-commit, execution context
+     * destroyed) — the caller keeps waiting. A page that answered with an
+     * unexpected shape (an override or a non-conforming host; the production
+     * expression always yields a string) is reported as `unknown` rather than as
+     * "no answer": blocking the navigation for the whole budget on a page that
+     * demonstrably responded has no upside.
+     */
+    private documentProbe;
+    /**
+     * Page.navigate resolves at navigation COMMIT, not at load: the new document
+     * is already current (so location.href and document.title are the new page's)
+     * while its DOM is still being parsed. browser_open snapshots immediately
+     * after navigating, which is why it could report the right title with zero
+     * interactive elements — and why a separate browser_snapshot right after
+     * always found them.
+     *
+     * Wait — bounded, best-effort — for the new document to settle: readyState
+     * must reach interactive/complete AND the document identity must have
+     * changed. A page that never settles must not fail a navigation that already
+     * succeeded, so a timeout here is swallowed.
+     */
+    private settleDocument;
+    /**
+     * Make sure the active tab's view can actually receive synthesized input.
+     * Chromium drops `Input.*` events for a view with no display surface, so this
+     * runs before click/type/key and fails loudly (BROWSER_VIEW_NOT_PRESENTED)
+     * 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>;
     /**
@@ -290,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;
     /**
@@ -320,13 +393,29 @@ export declare class ElectronBrowserProvider implements BrowserProvider {
      */
     scrape(session: BrowserSessionId, request: BrowserScrapeRequest, signal?: AbortSignal): Promise<BrowserScrapeResult>;
     /**
-     * Download a URL to a local file, keeping the session's cookies/login.
-     * Requires the self-hosted host (which implements view-level download); the
-     * desktop shell's embedded views delegate downloads to the real browser UI.
-     * Admission: only HTTP(S) targets (the in-page fetch cannot meaningfully
-     * fetch anything else), and the save path must be absolute — confined to
-     * `downloadDir` when one is configured, so a prompt-injected agent cannot
-     * write arbitrary machine paths.
+     * Admit a caller-supplied save path for a file the browser writes to disk.
+     * ONE gate for both `browser_download` and `browser_screenshot`: the path
+     * must be absolute, must resolve inside `downloadDir`, and must not already
+     * exist. Without it a prompt-injected agent could write — or silently
+     * replace — any file the DSH process can reach, which also escapes the file
+     * sandbox every other tool in the set runs under.
+     * @param savePath - the caller's target path.
+     * @param kind - the operation, used in the error code and message.
+     * @returns the resolved absolute target path.
+     * @throws BrowserError when the path is relative, outside the directory, or occupied.
+     */
+    private admitSavePath;
+    /**
+     * Download an HTTP(S) URL with the session's cookies to a local file.
+     * Admission is the shared {@link admitSavePath} gate; only the self-hosted
+     * host implements it (the desktop shell's embedded views delegate downloads
+     * to the real browser UI). Both admitted paths and screenshots are confined
+     * to `downloadDir`, so a prompt-injected agent cannot write arbitrary
+     * machine paths.
+     * @param session - the session whose cookies are used.
+     * @param request - the URL plus the absolute target path.
+     * @param signal - optional cancellation.
+     * @returns the path the file was written to.
      */
     download(session: BrowserSessionId, request: {
         readonly url: string;
@@ -346,7 +435,13 @@ export declare class ElectronBrowserProvider implements BrowserProvider {
         readonly dataUrl: string;
         readonly path?: string;
     }>;
-    /** Build the data URL and optionally write the image to disk. */
+    /**
+     * Build the data URL and optionally write the image to disk. The caller's
+     * path goes through the SAME {@link admitSavePath} gate as a download — it
+     * must be absolute, resolve inside `downloadDir`, and not be an existing
+     * file — so a screenshot cannot be used to write to, or silently replace,
+     * files anywhere the DSH process happens to have permission (issue #13).
+     */
     private saveScreenshot;
     /** Append one operation to the session's history. */
     private record;