dsh-builtin-browser 0.3.1 → 0.4.0

package/lib/browser-electron/missing-system-browser.js

@@ -0,0 +1,89 @@
+/**
+ * How each product is named in the message, and what to install.
+ *
+ * Only chrome and edge can appear: the constructor's type excludes `bundled` and `auto`,
+ * and `BrowserChannel` has no `brave`. A brave entry here would be unreachable code.
+ */
+const PRODUCT = {
+    chrome: {
+        label: 'Google Chrome',
+        install: 'install Google Chrome',
+        variable: 'DSH_BROWSER_CHROME_PATH',
+    },
+    edge: {
+        label: 'Microsoft Edge',
+        install: 'install Microsoft Edge',
+        variable: 'DSH_BROWSER_EDGE_PATH',
+    },
+};
+/** How the setting is named to the user. */
+const SETTING_LABEL = {
+    chrome: '本机 Chrome / installed Chrome',
+    edge: '本机 Edge / installed Edge',
+    auto: '自动 / automatic',
+    bundled: '内置 / bundled',
+};
+/**
+ * A carrier that cannot carry anything: every command explains the real problem.
+ *
+ * The message is written to be acted on, not just read: it says which browser was
+ * requested, where the plugin looked, and the three concrete ways to resolve it.
+ */
+export class MissingSystemBrowserHost {
+    kind;
+    searched;
+    /**
+     * @param kind - the browser the user asked for.
+     * @param searched - the names and locations that were checked, for the report.
+     */
+    constructor(kind, searched) {
+        this.kind = kind;
+        this.searched = searched;
+    }
+    /** @returns always true: see the module comment — reporting false would hide this. */
+    available() {
+        return true;
+    }
+    /**
+     * The message every command fails with.
+     * @returns a multi-line explanation with the fixes.
+     */
+    explain() {
+        const product = PRODUCT[this.kind] ?? { label: this.kind, install: `install ${this.kind}`, variable: 'DSH_BROWSER_<KIND>_PATH' };
+        const searched = this.searched.length > 0 ? this.searched.join(', ') : 'PATH and the usual install locations';
+        return [
+            `dsh-builtin-browser: the browser you selected is not installed — no ${product.label} was found.`,
+            ``,
+            `  Setting:  browser carrier = "${SETTING_LABEL[this.kind] ?? this.kind}"`,
+            `  Looked for: ${searched}`,
+            ``,
+            `Nothing else is wrong: the plugin falls back to its own bundled browser only when the`,
+            `setting is "bundled" or "automatic". Because this one names a browser explicitly, it`,
+            `reports the missing browser instead of silently using a different one.`,
+            ``,
+            `To fix it, any ONE of these is enough:`,
+            `  1. ${product.install}, then restart DSH;`,
+            `  2. point ${product.variable} at its executable;`,
+            `  3. set the browser carrier back to "内置 / bundled" (or "自动 / automatic" to let it`,
+            `     fall back on its own next time).`,
+        ].join('\n');
+    }
+    /**
+     * Create a handle whose every command fails with the explanation.
+     * @returns a handle that never reaches a page.
+     */
+    createView() {
+        const message = this.explain();
+        return {
+            id: `missing-${this.kind}`,
+            sendCommand: async () => { throw new Error(message); },
+        };
+    }
+    /**
+     * Accept a handle for destruction. Nothing was created, so nothing is released.
+     * @param handle - the handle returned by {@link createView}.
+     */
+    destroyView(handle) {
+        void handle;
+    }
+}

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

@@ -160,6 +160,15 @@ export interface ElectronViewHandle {
      * @returns the CDP `result` object.
      */
     sendCommand(method: string, params?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Whether this view's CDP can encode JPEG and honour a quality setting.
+     *
+     * Electron 43's CDP hangs on `Page.captureScreenshot` with `format: 'jpeg'`, so a view
+     * backed by Electron must leave this unset and the provider keeps to PNG. A view backed
+     * by an installed Chrome or Edge is the real browser, where JPEG works, and sets it so
+     * the requested format is not silently downgraded.
+     */
+    readonly supportsCdpJpeg?: boolean;
     /**
      * 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
@@ -236,6 +245,40 @@ export interface CdpEvaluateParams {
 }
 /** CDP method for a full-page screenshot capture. */
 export declare const CDP_PAGE_CAPTURE_SCREENSHOT = "Page.captureScreenshot";
+/**
+ * The document size out of a `Page.getLayoutMetrics` response.
+ *
+ * CDP returns `cssContentSize` (the whole document) and `cssLayoutViewport` (what is
+ * visible); the newer spellings `contentSize` / `layoutViewport` appear on some
+ * versions, so both are accepted. Returns undefined when neither is usable, leaving the
+ * caller to capture unscaled rather than guess.
+ * @param metrics - the raw CDP response.
+ * @returns the document and viewport size in CSS pixels.
+ */
+export declare function layoutSize(metrics: Record<string, unknown>): {
+    width: number;
+    height: number;
+    viewportHeight: number;
+} | undefined;
+/**
+ * Map CDP cookies onto the shape `browser_auth` exports.
+ *
+ * CDP reports a cookie as domain + path rather than a URL, and in seconds rather than
+ * milliseconds, so both are converted. Entries missing a name, value or domain are
+ * dropped rather than exported as broken cookies the caller cannot restore.
+ * @param raw - the `cookies` array from a CDP response, of unknown shape.
+ * @returns the mappable cookies.
+ */
+export declare function toExportedCookies(raw: unknown): ExportedCookie[];
+/**
+ * Map an exported cookie onto the fields `Storage.setCookies` expects.
+ *
+ * An exported cookie may carry only a URL, so the domain and path are recovered from it
+ * when they are absent; without either, CDP cannot place the cookie and it is skipped.
+ * @param cookie - the cookie to convert.
+ * @returns the CDP cookie, or undefined when it lacks a usable domain.
+ */
+export declare function toCdpCookie(cookie: ExportedCookie): Record<string, unknown> | undefined;
 /** Native capture options the self-hosted view handle understands. */
 export interface ScreenshotOptions {
     readonly format?: 'png' | 'jpeg';
@@ -595,7 +638,17 @@ export declare class ElectronBrowserProvider implements BrowserProvider {
      *    diagnostics: it can never be allowed to become the failure.
      */
     private notifyUserActionError;
-    /** Ask the host to show the active tab's view, carrying the session label. */
+    /**
+     * Ask the host to show the active tab's view, carrying the session label.
+     *
+     * The two halves are sequential, not alternatives. `showView` makes the view the
+     * visible one — which is what keeps what the human sees in step with what the agent
+     * drives, and what lets `capturePage` return an image at all (a hidden view captures
+     * empty) — while `collapse` folds the carrier's own chrome away when the user asked
+     * for no auto-expand. Making them exclusive meant that with auto-expand off this
+     * method did nothing at all on carriers without `collapse` (the self-hosted one),
+     * silently desynchronising the two and failing every screenshot.
+     */
     private showActive;
     /** Read the current URL of a view through CDP. */
     private currentUrl;

package/lib/browser-electron/provider.js

@@ -70,6 +70,109 @@ const CHALLENGE_DETECT_EXPRESSION = `(() => {
 export const ELECTRON_BROWSER_PROVIDER_ID = 'electron';
 /** CDP method for a full-page screenshot capture. */
 export const CDP_PAGE_CAPTURE_SCREENSHOT = 'Page.captureScreenshot';
+/**
+ * The document size out of a `Page.getLayoutMetrics` response.
+ *
+ * CDP returns `cssContentSize` (the whole document) and `cssLayoutViewport` (what is
+ * visible); the newer spellings `contentSize` / `layoutViewport` appear on some
+ * versions, so both are accepted. Returns undefined when neither is usable, leaving the
+ * caller to capture unscaled rather than guess.
+ * @param metrics - the raw CDP response.
+ * @returns the document and viewport size in CSS pixels.
+ */
+export function layoutSize(metrics) {
+    const pick = (candidates) => {
+        for (const candidate of candidates) {
+            if (typeof candidate !== 'object' || candidate === null)
+                continue;
+            const box = candidate;
+            if (typeof box.width === 'number' && typeof box.height === 'number' && box.width > 0 && box.height > 0) {
+                return { width: box.width, height: box.height };
+            }
+        }
+        return undefined;
+    };
+    const content = pick([metrics.cssContentSize, metrics.contentSize]);
+    const viewport = pick([metrics.cssLayoutViewport, metrics.layoutViewport]);
+    if (content === undefined)
+        return undefined;
+    return { width: content.width, height: content.height, viewportHeight: viewport?.height ?? content.height };
+}
+/**
+ * Map CDP cookies onto the shape `browser_auth` exports.
+ *
+ * CDP reports a cookie as domain + path rather than a URL, and in seconds rather than
+ * milliseconds, so both are converted. Entries missing a name, value or domain are
+ * dropped rather than exported as broken cookies the caller cannot restore.
+ * @param raw - the `cookies` array from a CDP response, of unknown shape.
+ * @returns the mappable cookies.
+ */
+export function toExportedCookies(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const entry of raw) {
+        if (typeof entry !== 'object' || entry === null)
+            continue;
+        const cookie = entry;
+        // An empty domain is as unusable as a missing one: it cannot form a cookie URL, so
+        // exporting it would hand the caller something that fails to restore.
+        if (typeof cookie.name !== 'string' || cookie.name === '')
+            continue;
+        if (typeof cookie.value !== 'string')
+            continue;
+        if (typeof cookie.domain !== 'string' || cookie.domain === '')
+            continue;
+        const path = typeof cookie.path === 'string' && cookie.path !== '' ? cookie.path : '/';
+        // A leading dot means "this domain and its subdomains"; a cookie URL must not keep it.
+        const host = cookie.domain.replace(/^\./, '');
+        out.push({
+            url: `${cookie.secure === true ? 'https' : 'http'}://${host}${path}`,
+            name: cookie.name,
+            value: cookie.value,
+            domain: cookie.domain,
+            path,
+            ...cookie.secure === true ? { secure: true } : {},
+            ...cookie.httpOnly === true ? { httpOnly: true } : {},
+            ...typeof cookie.expires === 'number' && cookie.expires > 0 ? { expirationDate: cookie.expires } : {},
+        });
+    }
+    return out;
+}
+/**
+ * Map an exported cookie onto the fields `Storage.setCookies` expects.
+ *
+ * An exported cookie may carry only a URL, so the domain and path are recovered from it
+ * when they are absent; without either, CDP cannot place the cookie and it is skipped.
+ * @param cookie - the cookie to convert.
+ * @returns the CDP cookie, or undefined when it lacks a usable domain.
+ */
+export function toCdpCookie(cookie) {
+    let domain = cookie.domain;
+    let path = cookie.path;
+    if (domain === undefined || domain === '') {
+        try {
+            const parsed = new URL(cookie.url);
+            domain = parsed.hostname;
+            if (path === undefined || path === '')
+                path = parsed.pathname === '' ? '/' : parsed.pathname;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (typeof domain !== 'string' || domain === '')
+        return undefined;
+    return {
+        name: cookie.name,
+        value: cookie.value,
+        domain,
+        path: path === undefined || path === '' ? '/' : path,
+        ...cookie.secure === true ? { secure: true } : {},
+        ...cookie.httpOnly === true ? { httpOnly: true } : {},
+        ...typeof cookie.expirationDate === 'number' ? { expires: cookie.expirationDate } : {},
+    };
+}
 /** CDP method for runtime evaluation (the execute path). */
 export const CDP_RUNTIME_EVALUATE = 'Runtime.evaluate';
 /** CDP method for navigation. */
@@ -275,11 +378,11 @@ export class ElectronBrowserProvider {
         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 => stripTabPrefix(tab.id) === wanted);
-            if (index >= 0)
-                return { s: other, index };
-        }
+        // Deliberately NOT searched across other sessions. Accepting a bare uuid and
+        // searching elsewhere are different things: ids are globally unique, so the first is
+        // harmless convenience, but the second lets a stale id close or switch a tab that
+        // belongs to another task — or to the human — while reporting success, which
+        // contradicts the isolation the tools promise.
         const ownIds = s.tabs.map(t => t.id).join(', ') || '(none)';
         throw new BrowserError(`browser: tab "${tabId}" is not open in this session (session tabs: ${ownIds})`, 'BROWSER_TAB_UNKNOWN');
     }
@@ -332,6 +435,11 @@ export class ElectronBrowserProvider {
             // 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).
+            // The page has already moved by now, so a caller that aborted must be told that rather
+            // than handed a success: settleDocument returns quietly on abort by design, so without
+            // this the whole path completes exception-free — success reported, success recorded, and
+            // the visit written to the persistent history for a navigation nobody awaits any more.
+            signal?.throwIfAborted();
             this.record(s, 'navigate', { url }, true);
             await this.settleDocument(handle, before, signal);
             this.recordVisit(s, handle);
@@ -460,7 +568,11 @@ export class ElectronBrowserProvider {
         if (handle.focus === undefined)
             return;
         try {
-            await handle.focus();
+            // Bounded, unlike the rest of this call: the child RPC has no timeout of its own,
+            // and this runs before typing, so an unresponsive child would hang browser_key for
+            // good. A timeout is caught below exactly like any other focus failure, so the
+            // best-effort contract is unchanged.
+            await withTimeout(handle.focus(), 5_000, undefined, 'browser: focusing the view timed out');
         }
         catch {
             // Best-effort: a view that refuses focus must not fail the caller's key
@@ -515,6 +627,12 @@ export class ElectronBrowserProvider {
             return { ok: true, value };
         }
         catch (error) {
+            // A caller that aborted is not a failure of the page: report its own reason, or the
+            // cancellation surfaces as "execute failed: AbortError" and — if the caller's reason
+            // happens to be named TimeoutError — as "timed out after 30000ms", quoting a budget
+            // that belongs to the caller rather than to this call.
+            if (signal?.aborted)
+                throw signal.reason;
             if (error instanceof Error && error.name === 'TimeoutError') {
                 throw new BrowserError(`browser: execute timed out after ${request.timeoutMs ?? 30_000}ms`, 'BROWSER_EXECUTE_TIMEOUT', { cause: error });
             }
@@ -585,10 +703,9 @@ export class ElectronBrowserProvider {
                 return { ready: false, reason: misses.join('; ') };
             }
             // Sleep between polls, abortable by the caller.
-            await new Promise((resolve, reject) => {
-                const timer = setTimeout(resolve, 200);
-                signal?.addEventListener('abort', () => { clearTimeout(timer); reject(signal.reason ?? new Error('aborted')); }, { once: true });
-            });
+            // Sleep between polls; delay() removes its abort listener on both paths, which the
+            // hand-rolled version here did not — a 30s wait leaked about 150 of them.
+            await delay(200, signal);
         }
     }
     /** Produce an AI-friendly snapshot of the active tab. */
@@ -1259,7 +1376,31 @@ export class ElectronBrowserProvider {
           continue
         }
         if (els.length === 0) { out.push({ ok: false, error: 'field not found', target: describe(spec) }); continue }
-        const el = els[0]
+        let el = els[0]
+        // The caller may name a kind. Honor it: the branches below read the element's own
+        // tag/type, so without this a selector matching two different controls acted on
+        // whichever came first — usually right, which is what hid the mistake.
+        if (spec.kind) {
+          const matchesKind = (node) => {
+            const nodeTag = node.tagName
+            const nodeType = (node.type || '').toLowerCase()
+            if (spec.kind === 'select') return nodeTag === 'SELECT'
+            if (spec.kind === 'textarea') return nodeTag === 'TEXTAREA'
+            if (spec.kind === 'checkbox' || spec.kind === 'radio') return nodeType === spec.kind
+            return nodeTag === 'INPUT' && nodeType !== 'checkbox' && nodeType !== 'radio' && nodeType !== 'file'
+          }
+          const wanted = els.find(matchesKind)
+          if (wanted === undefined) {
+            out.push({ ok: false, error: 'no "' + spec.kind + '" control matched', target: describe(spec) })
+            continue
+          }
+          els.length = 0
+          els.push(wanted)
+          // el was bound before the filter narrowed els, so the branches below would still
+          // read the first match — the very silent wrong-element behaviour this filter exists
+          // to remove.
+          el = els[0]
+        }
         const tag = el.tagName
         const type = (el.type || '').toLowerCase()
         try {
@@ -1652,7 +1793,7 @@ export class ElectronBrowserProvider {
       }
       return { ok: true, count: out.length, items: out }
     })()`;
-        const result = await withTimeout(handleSendEvaluate(tab.handle, script), timeoutMs, signal, `browser: scrape timed out after ${timeoutMs}ms`, () => terminatePage(tab.handle));
+        const result = await withTimeout(handleSendEvaluate(tab.handle, script), timeoutMs + TARGET_SCRIPT_GRACE_MS, signal, `browser: scrape timed out after ${timeoutMs}ms`, () => terminatePage(tab.handle));
         if (!result.ok)
             throw new BrowserError(`browser: scrape evaluation failed: ${result.exception}`, 'BROWSER_SCRAPE_FAILED');
         const value = result.value;
@@ -1751,28 +1892,54 @@ export class ElectronBrowserProvider {
      * Self-hosted only; the desktop shell's embedded views use the real profile.
      */
     async flushAuth(session) {
+        // The settings panel offers "allow the agent to read cookies / export login state".
+        // Until now nothing read that switch, so turning it off changed nothing at all —
+        // the tool exported every cookie regardless.
+        if (this.settingsSource?.().credentials.allowRead === false) {
+            throw new BrowserError('browser: reading cookies is switched off in settings (Browser → credentials)', 'BROWSER_AUTH_DISABLED');
+        }
         const s = this.session(session);
         const { handle } = this.activeTab(s);
-        const host = handle;
-        if (typeof host.flushAuth !== 'function') {
-            throw new BrowserError('browser: auth export is only available on the self-hosted browser', 'BROWSER_AUTH_UNSUPPORTED');
-        }
         const timeoutMs = 30_000;
-        const cookies = await withTimeout(host.flushAuth(), timeoutMs, undefined, `browser: auth export timed out after ${timeoutMs}ms`);
-        this.record(s, 'flushAuth', {}, true, { result: `${cookies.length} cookies` });
+        // The self-hosted carrier has a native path (the child reads its own session), which
+        // is worth preferring: it reports exactly what the browser persisted.
+        const native = handle;
+        if (typeof native.flushAuth === 'function') {
+            const cookies = await withTimeout(native.flushAuth(), timeoutMs, undefined, `browser: auth export timed out after ${timeoutMs}ms`);
+            this.record(s, 'flushAuth', {}, true, { result: `${cookies.length} cookies` });
+            return cookies;
+        }
+        // Every other carrier drives a real browser over CDP, and cookies are part of CDP —
+        // the sidebar goes through the shell's webContents.debugger, an installed Chrome or
+        // Edge is the browser itself. So this works everywhere rather than only self-hosted.
+        const result = await withTimeout(handle.sendCommand('Storage.getCookies', {}), timeoutMs, undefined, `browser: auth export timed out after ${timeoutMs}ms`);
+        const cookies = toExportedCookies(result.cookies);
+        this.record(s, 'flushAuth', {}, true, { result: `${cookies.length} cookies (CDP)` });
         return cookies;
     }
     /** Import cookies into the session (restore login state). Self-hosted only. */
     async restoreAuth(session, cookies) {
+        // The settings panel offers "allow the agent to read cookies / export login state".
+        // Until now nothing read that switch, so turning it off changed nothing at all —
+        // the tool exported every cookie regardless.
+        if (this.settingsSource?.().credentials.allowRead === false) {
+            throw new BrowserError('browser: reading cookies is switched off in settings (Browser → credentials)', 'BROWSER_AUTH_DISABLED');
+        }
         const s = this.session(session);
         const { handle } = this.activeTab(s);
-        const host = handle;
-        if (typeof host.restoreAuth !== 'function') {
-            throw new BrowserError('browser: auth restore is only available on the self-hosted browser', 'BROWSER_AUTH_UNSUPPORTED');
-        }
         const timeoutMs = 30_000;
-        const restored = await withTimeout(host.restoreAuth(cookies), timeoutMs, undefined, `browser: auth restore timed out after ${timeoutMs}ms`);
-        this.record(s, 'restoreAuth', { count: cookies.length }, true, { result: `${restored} cookies` });
+        const native = handle;
+        if (typeof native.restoreAuth === 'function') {
+            const restored = await withTimeout(native.restoreAuth(cookies), timeoutMs, undefined, `browser: auth restore timed out after ${timeoutMs}ms`);
+            this.record(s, 'restoreAuth', { count: cookies.length }, true, { result: `${restored} cookies` });
+            return restored;
+        }
+        // CDP again, for the same reason as the export: any carrier that drives a real
+        // browser can set cookies on it. Storage.setCookies needs the cookie fields spelled
+        // the CDP way, including the sameSite spelling and seconds rather than milliseconds.
+        const result = await withTimeout(handle.sendCommand('Storage.setCookies', { cookies: cookies.map(toCdpCookie) }), timeoutMs, undefined, `browser: auth restore timed out after ${timeoutMs}ms`);
+        const restored = toExportedCookies(result.cookies).length;
+        this.record(s, 'restoreAuth', { count: cookies.length }, true, { result: `${restored} cookies (CDP)` });
         return restored;
     }
     /** Capture the current page, optionally full-page, PNG or JPEG, scalable. */
@@ -1802,16 +1969,46 @@ export class ElectronBrowserProvider {
             }
             return this.saveScreenshot(shot.base64, request?.savePath, shot.mime ?? 'image/png');
         }
-        // Fallback: a desktop-shell handle (no capture()) or a full-page capture
-        // uses CDP; full-page needs `captureBeyondViewport` which capturePage
-        // lacks. PNG only — the JPEG hang is a CDP-on-Electron-43 defect.
+        // Fallback: a handle without a native capture() (the sidebar, or an installed Chrome
+        // or Edge) uses CDP; full-page needs `captureBeyondViewport`, which capturePage lacks.
+        //
+        // JPEG: Electron 43's CDP hangs on it, which is why the sidebar stays PNG. An
+        // installed Chrome or Edge is the real browser and has no such defect, so it says so
+        // through `supportsCdpJpeg` and gets the format it asked for, and the same for
+        // downscaling, which CDP performs through a full-document clip.
+        const timeoutMs = 30_000;
         const params = {};
         if (request?.fullPage === true) {
             // `captureBeyondViewport` captures the full scrollable content; without
             // a clip this yields the full-page image (CDP default is the viewport).
             params.captureBeyondViewport = true;
         }
-        const timeoutMs = 30_000;
+        const supportsJpeg = handle.supportsCdpJpeg === true;
+        if (format === 'jpeg' && supportsJpeg) {
+            params.format = 'jpeg';
+            // CDP range is 0-100 and defaults to 80 when omitted.
+            if (request?.quality !== undefined)
+                params.quality = request.quality;
+        }
+        // Downscaling on this path: CDP scales through `clip.scale`, and a clip only applies
+        // to the region it names, so it has to cover the whole document. The page's own size
+        // is read first; when that is unavailable the capture proceeds unscaled rather than
+        // failing — an image the caller can shrink itself beats no image at all.
+        if (request?.maxWidth !== undefined || request?.maxHeight !== undefined) {
+            const metrics = await withTimeout(handle.sendCommand('Page.getLayoutMetrics', {}), timeoutMs, signal, `browser: screenshot timed out after ${timeoutMs}ms`);
+            const size = layoutSize(metrics);
+            if (size !== undefined) {
+                const height = request.fullPage === true ? size.height : size.viewportHeight;
+                const byWidth = request.maxWidth !== undefined && size.width > 0 ? request.maxWidth / size.width : 1;
+                const byHeight = request.maxHeight !== undefined && height > 0 ? request.maxHeight / height : 1;
+                const scale = Math.min(1, byWidth, byHeight);
+                if (scale < 1) {
+                    params.clip = { x: 0, y: 0, width: size.width, height, scale };
+                    // The clip defines the captured area; captureBeyondViewport must not also apply.
+                    delete params.captureBeyondViewport;
+                }
+            }
+        }
         const result = await withTimeout(handle.sendCommand(CDP_PAGE_CAPTURE_SCREENSHOT, params), timeoutMs, signal, `browser: screenshot timed out after ${timeoutMs}ms`);
         const data = result.data;
         if (typeof data !== 'string') {
@@ -2151,17 +2348,24 @@ export class ElectronBrowserProvider {
         if (!reported)
             process.stderr.write(`[dsh-browser] user action failed: ${message}\n`);
     }
-    /** Ask the host to show the active tab's view, carrying the session label. */
+    /**
+     * Ask the host to show the active tab's view, carrying the session label.
+     *
+     * The two halves are sequential, not alternatives. `showView` makes the view the
+     * visible one — which is what keeps what the human sees in step with what the agent
+     * drives, and what lets `capturePage` return an image at all (a hidden view captures
+     * empty) — while `collapse` folds the carrier's own chrome away when the user asked
+     * for no auto-expand. Making them exclusive meant that with auto-expand off this
+     * method did nothing at all on carriers without `collapse` (the self-hosted one),
+     * silently desynchronising the two and failing every screenshot.
+     */
     showActive(s) {
-        // §3: whether the agent's page takes over the screen is the user's choice, not
-        // a fixed behaviour. With auto-expand off the page still exists and is still
-        // driven — it is simply folded away, so the agent works without claiming the
-        // sidebar. Carriers that own no presentation (self-hosted) ignore the call.
-        if (this.settingsSource !== undefined && !this.settingsSource().ui.autoExpandOnce) {
-            void this.host.collapse?.().catch(() => undefined);
-            return;
-        }
         this.host.showView?.(this.activeTab(s).handle, s.label);
+        const autoExpand = this.settingsSource === undefined || this.settingsSource().ui.autoExpandOnce;
+        if (autoExpand)
+            return;
+        // Best effort: a carrier that owns no presentation (self-hosted) simply has none.
+        void this.host.collapse?.().catch(() => undefined);
     }
     /** Read the current URL of a view through CDP. */
     async currentUrl(handle) {

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

@@ -868,9 +868,12 @@ export class RemoteElectronViewHost {
     }
     /** The child died: tear down so the next use starts a fresh child. */
     onChildExit() {
-        if (this.disposed)
-            return;
-        process.stderr.write('[dsh-browser host] browser host gone; will restart on next use\n');
+        // A disposed host still has to drop these: returning here left a child that had
+        // already been replaced during a dispose race in no map at all, so nothing would
+        // ever kill it. Only the restart is suppressed, not the cleanup.
+        const wasDisposed = this.disposed;
+        if (!wasDisposed)
+            process.stderr.write('[dsh-browser host] browser host gone; will restart on next use\n');
         this.client = undefined;
         this.server?.close();
         this.server = undefined;

package/lib/browser-electron/settings-store.js

@@ -157,11 +157,17 @@ export class SettingsStore {
             mkdirSync(dirname(this.file), { recursive: true });
             writeFileSync(this.file, `${JSON.stringify(merged, null, 2)}\n`);
         }
-        catch {
-            // Keep the merged value in memory even when the write fails.
+        catch (error) {
+            // Do NOT publish the new value as cached, and do not pretend the file changed: a
+            // reader compares the file's mtime against this stamp, so stamping "now" on a failed
+            // write made the next get() re-read the file and silently revert the user's change.
+            // Clear the cache before failing: the value on disk is still the old one, so leaving
+            // the merged document cached would hand the next reader something that does not exist —
+            // and the stamp would make it look fresh until the mtime comparison rolled it back.
+            this.cached = undefined;
+            this.cachedMtimeMs = -1;
+            throw new Error(`dsh-builtin-browser: settings could not be saved: ${error instanceof Error ? error.message : String(error)}`);
         }
-        this.cached = merged;
-        this.cachedMtimeMs = Date.now();
         return merged;
     }
 }

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

@@ -38,12 +38,28 @@ export interface DetectedBrowser {
  * Find an installed Chromium browser.
  *
  * `auto` prefers Chrome, then Edge, then Brave — the order reflects how likely each
- * is to be the browser a user actually chose rather than one Windows shipped.
+ * is to be the browser a user actually chose rather than one the system shipped.
+ * Each candidate is looked up in three places, most specific first: an explicit
+ * environment override, then PATH, then the platform's conventional install
+ * locations. PATH comes before the fixed paths because it is what actually reflects
+ * how the browser was installed.
  * @param channel - the configured choice; `bundled` never resolves to a system browser.
  * @param env - environment lookup, injected so tests need no real machine.
+ * @param platform - the platform to use conventions for; injected for the same reason.
  * @returns the detected browser, or undefined when the choice is unavailable.
  */
-export declare function detectBrowser(channel: BrowserChannel, env?: NodeJS.ProcessEnv): DetectedBrowser | undefined;
+export declare function detectBrowser(channel: BrowserChannel, env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): DetectedBrowser | undefined;
+/**
+ * Everything that was checked for one product, for reporting a miss.
+ *
+ * Detection returns undefined with no explanation, which left the caller able to say
+ * only "not found". This gives the user the actual list so they can see whether the
+ * plugin looked somewhere their browser is not.
+ * @param kind - the product to describe.
+ * @param platform - the platform whose names and locations apply.
+ * @returns the launcher names (as PATH lookups) and the fixed locations checked.
+ */
+export declare function searchSummary(kind: DetectedBrowser['kind'], platform?: NodeJS.Platform): string[];
 /** A system browser driven over CDP, presented as a browser view host. */
 export declare class SystemBrowserViewHost implements ElectronBrowserViewHost {
     private readonly browser;
@@ -106,11 +122,16 @@ export declare class SystemBrowserViewHost implements ElectronBrowserViewHost {
     /** The browser owns window grouping. */
     groupView(): void;
     /**
-     * Bring the browser's window forward.
+     * Best effort at bringing the browser's window forward.
      *
-     * The browser is a separate application, so there is no view to raise; focusing
-     * the process is the closest honest equivalent, and failing to do so (a minimized
-     * window, a locked session) is never worth an error.
+     * The browser is a separate application, so there is no view to raise. What this can
+     * actually do is ask its process to continue from a stopped state — which is a no-op on
+     * Windows, where `SIGCONT` is not a supported signal and the call throws. It is kept
+     * because it costs nothing and does help on POSIX (a process stopped with SIGSTOP
+     * resumes), but it must not be read as a promise that the window comes to the front;
+     * importantly, it does NOT raise a window that is merely behind another. Raising the
+     * page properly would need `Page.bringToFront` on a specific target session, which is a
+     * view-level concern and not available to the host.
      */
     focus(): Promise<void>;
     /** The browser reports its own window lifecycle. */