dsh-builtin-browser 0.1.21 → 0.1.22

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
@@ -226,6 +240,44 @@ 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;
     /** Execute JS in the active tab's page context. */
     execute(session: BrowserSessionId, request: BrowserExecuteRequest, signal?: AbortSignal): Promise<BrowserExecuteResult>;
     /**
@@ -320,13 +372,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 +414,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;

package/lib/browser-electron/provider.js

@@ -7,9 +7,9 @@
  * @module dsh-browser/browser-electron
  */
 import { randomUUID } from 'node:crypto';
-import { writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { isAbsolute, join, resolve, sep } from 'node:path';
+import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
 import { BrowserError } from '../browser/types.js';
 /**
  * Page-context human-verification (CAPTCHA / bot-detection) detection. Runs
@@ -95,6 +95,31 @@ const KEY_SPECS = {
 };
 /** Supported key names, exported for the tool's enum and error messages. */
 export const BROWSER_KEY_NAMES = Object.keys(KEY_SPECS);
+/**
+ * Localized names a system Downloads folder may carry, in probe order: the
+ * English default first, then the Chinese spellings — a zh-CN desktop calls
+ * the folder `下载`, a zh-TW one `下載`, and neither is `Downloads`.
+ */
+const DOWNLOAD_DIR_NAMES = ['Downloads', '下载', '下載'];
+/**
+ * Resolve the default download directory when the config names none: an
+ * existing `XDG_DOWNLOAD_DIR` wins (the freedesktop standard, which is what a
+ * localized Linux desktop writes), then the first localized `Downloads` folder
+ * that exists under the home directory, and finally the English name — created
+ * on first use — when none exists yet.
+ * @returns the absolute default download directory.
+ */
+function defaultDownloadDir() {
+    const xdg = process.env.XDG_DOWNLOAD_DIR;
+    if (typeof xdg === 'string' && xdg !== '' && existsSync(xdg))
+        return xdg;
+    for (const name of DOWNLOAD_DIR_NAMES) {
+        const candidate = join(homedir(), name);
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return join(homedir(), DOWNLOAD_DIR_NAMES[0] ?? 'Downloads');
+}
 /**
  * Browser provider over Electron views. Sessions hold an ordered list of
  * tabs; each tab is one view created by the host. The active tab receives
@@ -115,9 +140,12 @@ export class ElectronBrowserProvider {
         this.httpOnly = config.httpOnly ?? true;
         this.snapshotMaxElements = config.snapshotMaxElements ?? 60;
         this.contentMaxChars = config.contentMaxChars ?? 100_000;
-        // Confine downloads to a dedicated directory by default: the OS Downloads
-        // folder is the human-visible, browser-natural place for downloaded files.
-        this.downloadDir = config.downloadDir ?? join(homedir(), 'Downloads');
+        // Confine downloads AND screenshot saves to a dedicated directory by
+        // default: the OS Downloads folder is the human-visible, browser-natural
+        // place for written files, and it is the one directory the DSH file
+        // sandbox does not have to arbitrate. The localized name is probed so a
+        // Chinese desktop (`~/下载`) works without configuring `downloadDir`.
+        this.downloadDir = config.downloadDir ?? defaultDownloadDir();
         // Route toolbar (host UI) actions into the session model: the human and
         // the agent then always drive the same tabs, history, and navigation.
         this.host.onUserAction?.(action => { void this.handleUserAction(action); });
@@ -218,11 +246,16 @@ export class ElectronBrowserProvider {
      */
     locateTab(session, tabId) {
         const s = this.session(session);
-        const own = s.tabs.findIndex(tab => tab.id === tabId);
+        // Accept the bare uuid as well as the "tab:<uuid>" form the tools print:
+        // ids are globally unique, so requiring the printed prefix only produced a
+        // misleading "is not open in this session" error that listed the very tab
+        // the caller had just named.
+        const wanted = stripTabPrefix(tabId);
+        const own = s.tabs.findIndex(tab => stripTabPrefix(tab.id) === wanted);
         if (own >= 0)
             return { s, index: own };
         for (const other of this.sessions.values()) {
-            const index = other.tabs.findIndex(tab => tab.id === tabId);
+            const index = other.tabs.findIndex(tab => stripTabPrefix(tab.id) === wanted);
             if (index >= 0)
                 return { s: other, index };
         }
@@ -263,6 +296,8 @@ export class ElectronBrowserProvider {
             // evaluate paths so a wedged navigation surfaces as an error instead of
             // blocking the tool call forever.
             const timeoutMs = 30_000;
+            // Document identity of the page we are leaving (see settleDocument).
+            const before = await this.documentStamp(handle);
             const result = await withTimeout(handle.sendCommand(CDP_PAGE_NAVIGATE, { url }), timeoutMs, signal, `browser: navigation timed out after ${timeoutMs}ms`, 
             // Best-effort: cancel the in-flight navigation so a wedged load does
             // not leave the debugger queue busy.
@@ -273,7 +308,11 @@ export class ElectronBrowserProvider {
             if (typeof errorText === 'string' && errorText !== '') {
                 throw new BrowserError(`browser: navigation to "${url}" failed: ${errorText}`, 'BROWSER_NAVIGATION_FAILED');
             }
+            // Record as soon as the navigation has committed: history bookkeeping must
+            // not wait on the best-effort settle below (which only delays what the
+            // NEXT observation sees, not whether this action happened).
             this.record(s, 'navigate', { url }, true);
+            await this.settleDocument(handle, before, signal);
             this.showActive(s);
         }
         catch (error) {
@@ -283,6 +322,103 @@ export class ElectronBrowserProvider {
             throw error;
         }
     }
+    /**
+     * 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.
+     */
+    async documentStamp(handle) {
+        const probe = await this.documentProbe(handle);
+        return probe?.stamp ?? '';
+    }
+    /**
+     * 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.
+     */
+    async documentProbe(handle) {
+        try {
+            const result = await withTimeout(handleSendEvaluate(handle, 'String(performance.timeOrigin) + "|" + document.readyState'), 3_000, undefined, 'browser: document probe timed out');
+            if (!result.ok)
+                return null;
+            if (typeof result.value !== 'string')
+                return { stamp: '', readyState: 'unknown' };
+            const [stamp = '', readyState = ''] = result.value.split('|');
+            return { stamp, readyState };
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * 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.
+     */
+    async settleDocument(handle, before, signal) {
+        const started = Date.now();
+        const deadline = started + SETTLE_TIMEOUT_MS;
+        for (;;) {
+            if (signal?.aborted === true)
+                return;
+            // A probe failure is expected while the navigation commits (the context is
+            // being destroyed) — keep polling rather than giving up.
+            const probe = await this.documentProbe(handle);
+            if (probe !== null) {
+                const settled = probe.readyState === 'interactive'
+                    || probe.readyState === 'complete'
+                    || probe.readyState === 'unknown';
+                const isNewDocument = before === '' || probe.stamp === '' || probe.stamp !== before;
+                // The common case: the new document exists and is parsed — return now.
+                if (settled && isNewDocument)
+                    return;
+                // Same document (hash navigation, cancelled/aborted load): there is no
+                // parse to wait for, so do not burn the budget. Outlast the brief
+                // window in which the OUTGOING document may still answer instead.
+                if (settled && Date.now() - started >= SETTLE_GRACE_MS)
+                    return;
+            }
+            if (Date.now() >= deadline)
+                return;
+            await delay(SETTLE_POLL_MS, signal);
+        }
+    }
+    /**
+     * 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.
+     */
+    async present(s, signal) {
+        const { handle } = this.activeTab(s);
+        const present = this.host.presentView?.bind(this.host);
+        if (present === undefined) {
+            this.showActive(s);
+            return;
+        }
+        signal?.throwIfAborted();
+        const timeoutMs = 10_000;
+        try {
+            await withTimeout(present(handle, s.label), timeoutMs, signal, `browser: presenting the page view timed out after ${timeoutMs}ms`);
+            this.showActive(s);
+        }
+        catch (error) {
+            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 });
+        }
+    }
     /** Execute JS in the active tab's page context. */
     async execute(session, request, signal) {
         const s = this.session(session);
@@ -776,6 +912,9 @@ export class ElectronBrowserProvider {
             x = request.x;
             y = request.y;
         }
+        // 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;
         try {
@@ -817,6 +956,9 @@ export class ElectronBrowserProvider {
         }
         const text = 'text' in request ? request.text : '';
         const timeoutMs = 30_000;
+        // Input.insertText goes through the Input domain: same display-surface
+        // requirement as click/key.
+        await this.present(s, signal);
         try {
             await withTimeout(handle.sendCommand('Input.insertText', { text }), timeoutMs, signal, `browser: type timed out after ${timeoutMs}ms`);
         }
@@ -874,8 +1016,12 @@ export class ElectronBrowserProvider {
         const entry = entries[target];
         if (entry?.id === undefined)
             throw new BrowserError('browser: history entry missing id', 'BROWSER_HISTORY_INVALID');
+        // A history step is a navigation too: the classic A→B→A redirect would
+        // otherwise read the outgoing document's identity (see settleDocument).
+        const before = await this.documentStamp(handle);
         await withTimeout(handle.sendCommand('Page.navigateToHistoryEntry', { entryId: entry.id }), timeoutMs, signal, `browser: history navigation timed out after ${timeoutMs}ms`, () => { void handle.sendCommand('Page.stopLoading').catch(() => { }); });
         this.record(s, direction === -1 ? 'back' : 'forward', {}, true);
+        await this.settleDocument(handle, before, signal);
         this.showActive(s);
     }
     /** Go back in the active tab's history. */
@@ -892,10 +1038,14 @@ export class ElectronBrowserProvider {
         const { handle } = this.activeTab(s);
         signal?.throwIfAborted();
         const timeoutMs = 30_000;
+        // Same-URL reload: only the per-load document identity can tell the new
+        // document from the old one, so capture it before reloading.
+        const before = await this.documentStamp(handle);
         await withTimeout(handle.sendCommand('Page.reload', { ignoreCache: false }), timeoutMs, signal, `browser: reload timed out after ${timeoutMs}ms`, 
         // Best-effort: cancel the reload if it wedges the debugger queue.
         () => { void handle.sendCommand('Page.stopLoading').catch(() => { }); });
         this.record(s, 'reload', {}, true);
+        await this.settleDocument(handle, before, signal);
         this.showActive(s);
     }
     /** Press one named key (Enter/Tab/arrows/…) via CDP key events. */
@@ -909,6 +1059,8 @@ export class ElectronBrowserProvider {
         }
         const params = { key: spec.key, code: spec.code, windowsVirtualKeyCode: spec.vk, nativeVirtualKeyCode: spec.vk, ...spec.text !== undefined ? { text: spec.text } : {} };
         const timeoutMs = 15_000;
+        // Input.dispatchKeyEvent is subject to the same display-surface rule.
+        await this.present(s, signal);
         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`);
@@ -1357,13 +1509,53 @@ export class ElectronBrowserProvider {
         return { count: items.length, items };
     }
     /**
-     * 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.
+     */
+    admitSavePath(savePath, kind) {
+        const code = kind === 'download' ? 'BROWSER_DOWNLOAD_BLOCKED' : 'BROWSER_SCREENSHOT_BLOCKED';
+        if (!isAbsolute(savePath)) {
+            throw new BrowserError(`browser: ${kind} savePath must be an absolute path`, code);
+        }
+        const file = resolve(savePath);
+        if (this.downloadDir !== undefined) {
+            const dir = resolve(this.downloadDir);
+            // Case-insensitive comparison: Windows paths are case-insensitive, and
+            // resolve() does not normalize case. Without this, C:\Users\X\Downloads
+            // and c:\users\x\downloads would be treated as different roots.
+            const dirLower = dir.toLowerCase();
+            const fileLower = file.toLowerCase();
+            if (fileLower !== dirLower && !fileLower.startsWith(dirLower + sep.toLowerCase())) {
+                throw new BrowserError(`browser: ${kind} savePath must be inside downloadDir "${dir}"`, code);
+            }
+        }
+        // Never replace an existing file: its previous content is unrecoverable,
+        // and the admitted directory may hold files the human put there. A new
+        // name is one tool call away.
+        if (existsSync(file)) {
+            throw new BrowserError(`browser: refusing to overwrite existing file "${file}" — use another name`, code);
+        }
+        return file;
+    }
+    /**
+     * 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.
      */
     async download(session, request, signal) {
         const s = this.session(session);
@@ -1382,23 +1574,9 @@ export class ElectronBrowserProvider {
         if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
             throw new BrowserError(`browser: refusing download of non-HTTP(S) URL "${request.url}"`, 'BROWSER_DOWNLOAD_BLOCKED');
         }
-        // savePath admission: must be absolute; when downloadDir is configured it
-        // must resolve inside it (no ..-escape).
-        if (!isAbsolute(request.savePath)) {
-            throw new BrowserError('browser: download savePath must be an absolute path', 'BROWSER_DOWNLOAD_BLOCKED');
-        }
-        if (this.downloadDir !== undefined) {
-            const dir = resolve(this.downloadDir);
-            const file = resolve(request.savePath);
-            // Case-insensitive comparison: Windows paths are case-insensitive, and
-            // resolve() does not normalize case. Without this, C:\Users\X\Downloads
-            // and c:\users\x\downloads would be treated as different roots.
-            const dirLower = dir.toLowerCase();
-            const fileLower = file.toLowerCase();
-            if (fileLower !== dirLower && !fileLower.startsWith(dirLower + sep.toLowerCase())) {
-                throw new BrowserError(`browser: download savePath must be inside downloadDir "${dir}"`, 'BROWSER_DOWNLOAD_BLOCKED');
-            }
-        }
+        // savePath admission: the shared gate — absolute, inside `downloadDir`,
+        // and never an existing file. Screenshots use the very same one.
+        const savePath = this.admitSavePath(request.savePath, 'download');
         const downloadable = handle;
         if (typeof downloadable.download !== 'function') {
             throw new BrowserError('browser: download is only available on the self-hosted browser', 'BROWSER_DOWNLOAD_UNSUPPORTED');
@@ -1410,9 +1588,9 @@ export class ElectronBrowserProvider {
         // entry is cleaned up (the promise settles) and the child's eventual
         // reply is harmlessly consumed by the RPC layer.
         const timeoutMs = 60_000;
-        await withTimeout(downloadable.download(request.url, request.savePath), timeoutMs, signal, `browser: download timed out after ${timeoutMs}ms`);
-        this.record(s, 'download', { url: request.url, savePath: request.savePath }, true, { result: request.savePath });
-        return { path: request.savePath };
+        await withTimeout(downloadable.download(request.url, savePath), timeoutMs, signal, `browser: download timed out after ${timeoutMs}ms`);
+        this.record(s, 'download', { url: request.url, savePath }, true, { result: savePath });
+        return { path: savePath };
     }
     /**
      * Export the session's cookies (login state) as serializable objects.
@@ -1487,16 +1665,26 @@ export class ElectronBrowserProvider {
         }
         return this.saveScreenshot(data, request?.savePath, 'image/png');
     }
-    /** 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).
+     */
     saveScreenshot(base64, savePath, mime) {
         if (savePath !== undefined) {
+            // Admission failures propagate unchanged: they describe the caller's
+            // path, not a disk problem.
+            const target = this.admitSavePath(savePath, 'screenshot');
             try {
-                writeFileSync(savePath, Buffer.from(base64, 'base64'));
-                return { dataUrl: `data:${mime};base64,${base64}`, path: savePath };
+                mkdirSync(dirname(target), { recursive: true });
+                writeFileSync(target, Buffer.from(base64, 'base64'));
+                return { dataUrl: `data:${mime};base64,${base64}`, path: target };
             }
             catch (error) {
                 // Report the write problem but keep the capture usable.
-                throw new BrowserError(`browser: screenshot save to "${savePath}" failed: ${String(error)}`, 'BROWSER_SCREENSHOT_SAVE_FAILED', { cause: error });
+                throw new BrowserError(`browser: screenshot save to "${target}" failed: ${String(error)}`, 'BROWSER_SCREENSHOT_SAVE_FAILED', { cause: error });
             }
         }
         return { dataUrl: `data:${mime};base64,${base64}` };
@@ -1712,6 +1900,36 @@ export class ElectronBrowserProvider {
         return result.ok && typeof result.value === 'string' ? result.value : '';
     }
 }
+/**
+ * Hard cap on waiting for a navigation's new document to be parsed. Bounded and
+ * best-effort: a page that never settles must not fail the navigation.
+ */
+const SETTLE_TIMEOUT_MS = 5_000;
+/**
+ * When the document already looks settled but its identity has NOT changed
+ * (same-document navigation, or the outgoing document still answering), wait
+ * only this long before returning — there is no parse in flight to wait for.
+ */
+const SETTLE_GRACE_MS = 150;
+/** Poll interval for the document-settle loop. */
+const SETTLE_POLL_MS = 25;
+/** `tab:<uuid>` ↔ `<uuid>`: ids accept either form (see locateTab). */
+function stripTabPrefix(id) {
+    return id.startsWith('tab:') ? id.slice(4) : id;
+}
+/** Abortable sleep used by the settle loop. */
+function delay(ms, signal) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            if (signal !== undefined)
+                signal.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => { clearTimeout(timer); resolve(); };
+        if (signal !== undefined)
+            signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
 /**
  * Bound a promise so a wedged CDP call surfaces as an error instead of
  * hanging the tool call forever. The caller's signal, when provided, wins

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

@@ -83,6 +83,12 @@ declare function resolveElectronPathImpl(inputs: ElectronPathInputs): string;
  * resources dir at all) likewise cannot run a script argument.
  */
 declare function isBareElectron(exe: string): boolean;
+/** Candidate executable layouts used by the Electron npm package on one platform. */
+declare function electronDistCandidates(pkgRoot: string, platform?: NodeJS.Platform): string[];
+/** From an electron package entry file, find the dist executable beside it. */
+declare function electronExeBeside(entry: string, platform?: NodeJS.Platform): string | undefined;
+/** From an electron package root, find its dist executable. */
+declare function electronDistExe(pkgRoot: string, platform?: NodeJS.Platform): string | undefined;
 /**
  * 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
@@ -126,6 +132,22 @@ export declare class RemoteElectronViewHost implements ElectronBrowserViewHost {
     createView(): ElectronViewHandle;
     private ensureView;
     showView(handle: ElectronViewHandle, label?: string): void;
+    /**
+     * (Re)present a view and WAIT for the child to confirm it, so the provider
+     * can dispatch CDP `Input.*` knowing the view has a display surface.
+     *
+     * Two things this fixes, both silent before:
+     *  - showing a view that does not exist yet is a no-op in the child, so the
+     *    view must be materialized first (a fresh tab's createView races the
+     *    provider's showActive);
+     *  - a view whose renderer was replaced by a navigation is \"already\n   *    visible\" and therefore skipped by the child's flicker-avoidance fast
+     *    path, leaving the new renderer without a surface.
+     *
+     * The barrier ping is meaningful because the child handles messages strictly
+     * in order: its reply is queued behind the showView and so only arrives once
+     * the visibility change has been applied.
+     */
+    presentView(handle: ElectronViewHandle, label?: string): Promise<void>;
     /** Route a view into its session's own window (one window per session). */
     groupView(handle: ElectronViewHandle, windowId: string, label?: string): void;
     /** Register the provider's handler for user-initiated toolbar actions. */
@@ -144,6 +166,9 @@ export declare function defaultHostMainPath(): string;
  * steps; `resolveElectronPath` is the full resolution order.
  */
 export declare const internals: {
+    electronDistCandidates: typeof electronDistCandidates;
+    electronDistExe: typeof electronDistExe;
+    electronExeBeside: typeof electronExeBeside;
     isBareElectron: typeof isBareElectron;
     resolveElectronPath: typeof resolveElectronPath;
     resolveElectronPathImpl: typeof resolveElectronPathImpl;