dsh-builtin-browser 0.1.21 → 0.1.23

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,124 @@ 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 });
+        }
+    }
+    /**
+     * 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);
@@ -776,24 +933,51 @@ export class ElectronBrowserProvider {
             x = request.x;
             y = request.y;
         }
-        const press = (type) => handle.sendCommand('Input.dispatchMouseEvent', { type, x, y, button: 'left', clickCount: 1 });
+        // 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 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);
@@ -817,6 +1001,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 +1061,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 +1083,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 +1104,9 @@ 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);
+        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`);
@@ -1079,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)
@@ -1094,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)
@@ -1102,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)
@@ -1116,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}
@@ -1130,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;
@@ -1322,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)
@@ -1357,13 +1575,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 +1640,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 +1654,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 +1731,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 +1966,42 @@ 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;
+/**
+ * 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;
+}
+/** 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