dsh-builtin-browser 0.4.6 → 0.4.7

package/lib/browser-electron/entry.js

@@ -81,9 +81,10 @@ export function apply(ctx, config) {
     // a sessionId). One conversation per process, so the list holds this one.
     const sessionId = readSessionId(ctx);
     // One settings document per plugin instance: the settings panel writes it, the
-    // provider reads it live, and both ends agree on the same file.
-    const settings = new SettingsStore();
-    installSettingsRoute(ctx, settings);
+    // provider reads it live, and both ends agree on the same file. The logger is passed so a
+    // discarded value (a mistyped channel, most of all) is reported instead of being silently
+    // replaced by the default — "my setting did nothing" and "I misspelled it" must not look alike.
+    const settings = new SettingsStore(undefined, message => ctx.logger?.warn?.(message));
     const providerConfig = {
         httpOnly: config.httpOnly,
         downloadDir: config.downloadDir,
@@ -96,6 +97,15 @@ export function apply(ctx, config) {
     if (config.viewHost !== undefined) {
         const external = ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(config.viewHost, providerConfig));
         ctx.effect(() => () => { external(); });
+        // The composition supplied the carrier, so `browser.channel` is not ours to honour on this
+        // surface. Saying so is the difference between a setting that cannot apply and a setting that
+        // appears not to have worked — the second is what sends people looking for a bug elsewhere.
+        const asked = settings.get().browser.channel;
+        if (asked !== 'sidebar' && asked !== 'bundled') {
+            ctx.logger?.warn?.(`dsh-builtin-browser: browser.channel is "${asked}", but this surface's carrier was `
+                + 'supplied by its composition (the desktop shell), which outranks the setting. Set it to '
+                + '"sidebar" to record the intent, or run on a surface that picks its own carrier.');
+        }
         return;
     }
     // Otherwise start self-hosted — a working browser from the first call, on every
@@ -106,26 +116,69 @@ export function apply(ctx, config) {
     const selfHosted = new RemoteElectronViewHost(defaultHostMainPath());
     let unregister = ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(selfHosted, providerConfig));
     let upgraded = false;
+    /** The carrier an `adopt` installed, so a later choice can release it. */
+    let adoptedCarrier;
     ctx.effect(() => () => {
         unregister();
         selfHosted.dispose();
     });
+    /**
+     * Put the self-hosted browser back after an adopted carrier reports that it is gone.
+     *
+     * This is the half the startup retries never covered: a bridge that was alive at apply time and
+     * exited later left every subsequent call dialling a port nobody owns, because the swap happened
+     * once and only in one direction. Reaching here means the shell is gone, so the choice made at
+     * startup is no longer a choice — the alternative to falling back is a browser surface that does
+     * nothing until DSH is restarted.
+     * @param adopted - the carrier that reported the loss, disposed once its replacement is in place.
+     */
+    const restoreSelfHosted = (adopted) => {
+        try {
+            const restored = new RemoteElectronViewHost(defaultHostMainPath());
+            unregister();
+            unregister = ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(restored, providerConfig));
+            ctx.logger?.warn?.('dsh-builtin-browser: the desktop shell backed the sidebar browser and has exited, so the '
+                + 'browser this plugin hosts itself takes over. Pages from the sidebar are gone with it; '
+                + 'open the page again.');
+        }
+        catch (error) {
+            // Nothing better is available: the adopted carrier is gone and a provider that throws is
+            // worse than one that explains.
+            ctx.logger?.warn?.(`dsh-builtin-browser: could not fall back to the self-hosted browser: ${String(error)}`);
+        }
+        finally {
+            adopted.dispose?.();
+        }
+    };
     /**
      * Swap the provider to another carrier, releasing the previous one.
      * @param host - the carrier to adopt.
      * @param note - a one-line description for the log.
      */
     const adopt = (host, note) => {
-        if (upgraded) {
-            host.dispose?.();
-            return;
-        }
+        // This guard used to make the FIRST choice final, disposing anything that arrived later. That
+        // is right against two carriers racing in, and exactly wrong for a user changing the setting:
+        // `chooseCarrier` runs again on purpose, and a refusal here is indistinguishable from the
+        // write having done nothing. The previous carrier is now released by the replacement instead.
         upgraded = true;
         try {
             unregister();
             unregister = ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(host, providerConfig));
             selfHosted.dispose();
             ctx.logger?.info?.(`dsh-builtin-browser: ${note}`);
+            // A borrowed carrier can lose the process behind it, and this is the only notification that
+            // will ever arrive. Registering AFTER the swap succeeded means a listener can never fire
+            // against a provider that was never installed.
+            host.onLost?.(() => { restoreSelfHosted(host); });
+            const previous = adoptedCarrier;
+            adoptedCarrier = host;
+            // Released AFTER the replacement is installed, so the surface is never without a provider.
+            if (previous !== undefined && previous !== host) {
+                try {
+                    previous.dispose?.();
+                }
+                catch { /* the replacement is already serving */ }
+            }
         }
         catch (error) {
             // Never leave the surface without a provider. The half-built host is disposed FIRST: an
@@ -153,103 +206,119 @@ export function apply(ctx, config) {
             }
         }
     };
-    // A browser the user explicitly asked for outranks every automatic choice: the
-    // whole point of the setting is that they know which browser they want. It is
-    // launched with a plugin-owned profile, so their own windows are untouched.
-    //
-    // Registration is INERT: constructing the host starts nothing. The browser only
-    // launches when a command actually needs a page, so merely running DSH never
-    // spawns a browser window. (An earlier version launched it here, which meant a
-    // browser appeared the moment the plugin loaded — reported and fixed.)
-    const channel = settings.get().browser.channel;
-    // Naming a browser is a decision about which one to use, so it also decides whether the
-    // desktop sidebar may take over. Skipping discovery for an explicit choice is what makes
-    // that choice real — otherwise a user who picked Chrome would silently get the sidebar,
-    // and a user who picked a browser that is not installed would never see the explanation
-    // written for exactly that case, because the sidebar would quietly replace it.
-    const explicitChoice = channel !== 'bundled' && channel !== 'auto' && channel !== 'sidebar';
-    if (channel !== 'bundled' && channel !== 'sidebar') {
-        const detected = detectBrowser(channel);
-        if (detected === undefined) {
-            // `auto` promises to take whatever is available, so falling back is what it
-            // asked for. Naming a browser is a specific request, and quietly satisfying it
-            // with a different one turns the real problem ("no Chrome here") into a
-            // confusing error about Electron later on. Report it instead.
-            if (channel === 'auto') {
-                ctx.logger?.warn?.('dsh-builtin-browser: no installed browser was found; using the bundled browser');
+    /**
+     * Choose and install the carrier that `browser.channel` names RIGHT NOW.
+     *
+     * A function rather than straight-line code because the setting is read live everywhere else:
+     * the settings route writes the file and the provider picks the change up on its next call, so a
+     * channel that could only be honoured at apply time was the one setting whose write silently did
+     * nothing. Re-entrant by design — changing the channel means replacing the carrier, which is
+     * exactly what a second call does.
+     */
+    const chooseCarrier = () => {
+        // A browser the user explicitly asked for outranks every automatic choice: the
+        // whole point of the setting is that they know which browser they want. It is
+        // launched with a plugin-owned profile, so their own windows are untouched.
+        //
+        // Registration is INERT: constructing the host starts nothing. The browser only
+        // launches when a command actually needs a page, so merely running DSH never
+        // spawns a browser window. (An earlier version launched it here, which meant a
+        // browser appeared the moment the plugin loaded — reported and fixed.)
+        const channel = settings.get().browser.channel;
+        // Naming a browser is a decision about which one to use, so it also decides whether the
+        // desktop sidebar may take over. Skipping discovery for an explicit choice is what makes
+        // that choice real — otherwise a user who picked Chrome would silently get the sidebar,
+        // and a user who picked a browser that is not installed would never see the explanation
+        // written for exactly that case, because the sidebar would quietly replace it.
+        const explicitChoice = channel !== 'bundled' && channel !== 'auto' && channel !== 'sidebar';
+        if (channel !== 'bundled' && channel !== 'sidebar') {
+            const detected = detectBrowser(channel);
+            if (detected === undefined) {
+                // `auto` promises to take whatever is available, so falling back is what it
+                // asked for. Naming a browser is a specific request, and quietly satisfying it
+                // with a different one turns the real problem ("no Chrome here") into a
+                // confusing error about Electron later on. Report it instead.
+                if (channel === 'auto') {
+                    ctx.logger?.warn?.('dsh-builtin-browser: no installed browser was found; using the bundled browser');
+                }
+                else {
+                    adopt(new MissingSystemBrowserHost(channel, searchSummary(channel)), `the selected ${channel} is not installed — commands will explain how to fix it`);
+                }
             }
             else {
-                adopt(new MissingSystemBrowserHost(channel, searchSummary(channel)), `the selected ${channel} is not installed — commands will explain how to fix it`);
-            }
-        }
-        else {
-            // Same profile root as settings-store, history-store and desktop-bridge-host: the
-            // `?.dsh` component used to be missing HERE only, so a desktop launched from a
-            // shortcut (no DSH_HOME in the environment) put its browser profile in
-            // `C:\Users\<user>\dsh-builtin-browser-host\` while its settings and history lived in
-            // `~/.dsh/dsh-builtin-browser-host/` — two half-profiles that never met, and a
-            // settings panel whose switches appeared not to apply.
-            const home = process.env.DSH_HOME ?? join(homedir(), '.dsh');
-            // Login state lives in the browser profile, so the cookies setting decides where
-            // that profile goes: a stable directory keeps the user signed in across restarts
-            // (the point of using their own browser), while turning persistence off gets a
-            // throwaway directory that is removed when the browser is released.
-            const persist = settings.get().cookies.persist;
-            const profileRoot = join(home, BROWSER_PROFILE_DIR);
-            adoptLegacyProfileRoot(profileRoot);
-            const profileDir = persist
-                ? join(profileRoot, `${detected.kind}-profile`)
-                : join(profileRoot, ephemeralProfileName(detected.kind, randomUUID()));
-            if (!persist) {
-                // A process killed outright never runs its own cleanup (see ephemeral-profile.ts),
-                // so the sweep happens HERE — at the only moment that can still act on a profile
-                // whose owner is gone — and before this run claims a directory of its own.
-                sweepAbandonedEphemeralProfiles(profileRoot, detected.kind);
-                claimEphemeralProfile(profileDir);
+                // Same profile root as settings-store, history-store and desktop-bridge-host: the
+                // `?.dsh` component used to be missing HERE only, so a desktop launched from a
+                // shortcut (no DSH_HOME in the environment) put its browser profile in
+                // `C:\Users\<user>\dsh-builtin-browser-host\` while its settings and history lived in
+                // `~/.dsh/dsh-builtin-browser-host/` — two half-profiles that never met, and a
+                // settings panel whose switches appeared not to apply.
+                const home = process.env.DSH_HOME ?? join(homedir(), '.dsh');
+                // Login state lives in the browser profile, so the cookies setting decides where
+                // that profile goes: a stable directory keeps the user signed in across restarts
+                // (the point of using their own browser), while turning persistence off gets a
+                // throwaway directory that is removed when the browser is released.
+                const persist = settings.get().cookies.persist;
+                const profileRoot = join(home, BROWSER_PROFILE_DIR);
+                adoptLegacyProfileRoot(profileRoot);
+                const profileDir = persist
+                    ? join(profileRoot, `${detected.kind}-profile`)
+                    : join(profileRoot, ephemeralProfileName(detected.kind, randomUUID()));
+                if (!persist) {
+                    // A process killed outright never runs its own cleanup (see ephemeral-profile.ts),
+                    // so the sweep happens HERE — at the only moment that can still act on a profile
+                    // whose owner is gone — and before this run claims a directory of its own.
+                    sweepAbandonedEphemeralProfiles(profileRoot, detected.kind);
+                    claimEphemeralProfile(profileDir);
+                }
+                adopt(new SystemBrowserViewHost(detected, profileDir, [], persist ? undefined : profileDir), `will drive the installed ${detected.kind} (${detected.path}${persist ? '' : ', ephemeral profile'})`);
             }
-            adopt(new SystemBrowserViewHost(detected, profileDir, [], persist ? undefined : profileDir), `will drive the installed ${detected.kind} (${detected.path}${persist ? '' : ', ephemeral profile'})`);
         }
-    }
-    // An explicit choice was already adopted above; discovering the sidebar here would
-    // replace it, which is exactly what this guard prevents.
-    //
-    // `sidebar` is explicit too, but it names the sidebar, so it is the one explicit choice that
-    // must FALL THROUGH to the discovery below instead of returning here.
-    if (explicitChoice && channel !== 'sidebar')
-        return;
-    // The shell may not be up yet. `dsh web` starts before — or entirely without — the desktop app
-    // that hosts the bridge, and a one-shot discovery meant a bridge that appeared a second later
-    // was never adopted for the rest of the process's life. Retry a handful of times over roughly
-    // half a minute, then stop: this is a convenience, not a promise, and the session the user is
-    // already driving in the self-hosted window is not worth replacing minutes into their work.
-    // `adopt` is itself one-shot (its `upgraded` guard), so the only possible effect of a retry
-    // that lands late is adopting a bridge that showed up just after startup.
-    void (async () => {
-        for (const delay of [0, 2_000, 5_000, 15_000]) {
-            if (delay > 0)
-                await new Promise(resolve => setTimeout(resolve, delay));
-            let sidebar;
-            try {
-                sidebar = await DesktopBridgeViewHost.discover(sessionId);
+        // An explicit choice was already adopted above; discovering the sidebar here would
+        // replace it, which is exactly what this guard prevents.
+        //
+        // `sidebar` is explicit too, but it names the sidebar, so it is the one explicit choice that
+        // must FALL THROUGH to the discovery below instead of returning here.
+        if (explicitChoice && channel !== 'sidebar')
+            return;
+        // The shell may not be up yet. `dsh web` starts before — or entirely without — the desktop app
+        // that hosts the bridge, and a one-shot discovery meant a bridge that appeared a second later
+        // was never adopted for the rest of the process's life. Retry a handful of times over roughly
+        // half a minute, then stop: this is a convenience, not a promise, and the session the user is
+        // already driving in the self-hosted window is not worth replacing minutes into their work.
+        // `adopt` is itself one-shot (its `upgraded` guard), so the only possible effect of a retry
+        // that lands late is adopting a bridge that showed up just after startup.
+        void (async () => {
+            for (const delay of [0, 2_000, 5_000, 15_000]) {
+                if (delay > 0)
+                    await new Promise(resolve => setTimeout(resolve, delay));
+                let sidebar;
+                try {
+                    sidebar = await DesktopBridgeViewHost.discover(sessionId);
+                }
+                catch {
+                    sidebar = undefined; // discovery is documented not to throw; never let it stop the retries
+                }
+                if (sidebar === undefined)
+                    continue;
+                adopt(sidebar, 'driving the desktop sidebar browser');
+                return;
             }
-            catch {
-                sidebar = undefined; // discovery is documented not to throw; never let it stop the retries
+            // The user explicitly asked for the sidebar, so silence would leave them with a setting
+            // that did nothing and no way to tell why. This is reachable on `dsh web`, and on a desktop
+            // whose shell never published a bridge endpoint. An automatic attempt stays quiet (the
+            // self-hosted window is a fine outcome); an explicit request does not.
+            if (channel === 'sidebar') {
+                ctx.logger?.warn?.('dsh-builtin-browser: the sidebar browser was requested but no desktop bridge was found — '
+                    + 'this DSH has no desktop shell, or its bridge never started. Falling back to the bundled '
+                    + 'browser; set browser.channel to another value to silence this.');
             }
-            if (sidebar === undefined)
-                continue;
-            adopt(sidebar, 'driving the desktop sidebar browser');
-            return;
-        }
-        // The user explicitly asked for the sidebar, so silence would leave them with a setting
-        // that did nothing and no way to tell why. This is reachable on `dsh web`, and on a desktop
-        // whose shell never published a bridge endpoint. An automatic attempt stays quiet (the
-        // self-hosted window is a fine outcome); an explicit request does not.
-        if (channel === 'sidebar') {
-            ctx.logger?.warn?.('dsh-builtin-browser: the sidebar browser was requested but no desktop bridge was found — '
-                + 'this DSH has no desktop shell, or its bridge never started. Falling back to the bundled '
-                + 'browser; set browser.channel to another value to silence this.');
-        }
-    })();
+        })();
+    };
+    chooseCarrier();
+    // Wired AFTER the chooser exists, because the handler re-runs it: a settings write that changes
+    // `browser.channel` is a request to switch carriers, and answering `ok` without switching is the
+    // one thing a caller cannot tell apart from a write that worked.
+    installSettingsRoute(ctx, settings, () => { chooseCarrier(); });
 }
 /** Route the settings panel reads and writes. */
 const SETTINGS_ROUTE = '/dsh-builtin-browser/settings';
@@ -303,7 +372,7 @@ export function adoptLegacyProfileRoot(profileRoot, legacyRoot = join(homedir(),
  * @param ctx - the plugin context.
  * @param settings - the settings document to expose.
  */
-function installSettingsRoute(ctx, settings) {
+function installSettingsRoute(ctx, settings, onChannelChange) {
     const inject = ctx.inject;
     if (typeof inject !== 'function')
         return;
@@ -312,7 +381,7 @@ function installSettingsRoute(ctx, settings) {
             host.effect(() => host.webServer.register({
                 kind: 'exact',
                 path: SETTINGS_ROUTE,
-                handler: (request, response) => handleSettingsRequest(request, response, settings),
+                handler: (request, response) => handleSettingsRequest(request, response, settings, onChannelChange),
             }, 'dsh-builtin-browser: settings'));
         });
     }
@@ -326,8 +395,9 @@ function installSettingsRoute(ctx, settings) {
  * @param request - the incoming request.
  * @param response - the response to write.
  * @param settings - the settings document.
+ * @param onChannelChange - re-runs the carrier choice when this write changed `browser.channel`.
  */
-async function handleSettingsRequest(request, response, settings) {
+async function handleSettingsRequest(request, response, settings, onChannelChange) {
     const json = (status, body) => {
         response.writeHead(status, {
             'content-type': 'application/json; charset=utf-8',
@@ -352,7 +422,20 @@ async function handleSettingsRequest(request, response, settings) {
     try {
         const body = await readBody(request);
         const patch = body.trim() === '' ? {} : JSON.parse(body);
-        json(200, { ok: true, settings: settings.update(patch) });
+        const before = settings.get().browser.channel;
+        const updated = settings.update(patch);
+        // A changed `browser.channel` is a request to switch carriers, not just a value to store. The
+        // choice is re-run here so the write takes effect now — and the response says so, because a
+        // caller that cannot tell "applied" from "stored for later" has no way to know what it got,
+        // which is exactly how a write that did nothing read as a success.
+        const channelChanged = updated.browser.channel !== before;
+        if (channelChanged)
+            onChannelChange?.();
+        json(200, {
+            ok: true,
+            settings: updated,
+            ...channelChanged ? { carrierRechosen: true } : {},
+        });
     }
     catch (error) {
         json(400, { ok: false, error: `invalid settings patch: ${String(error)}` });

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

@@ -119,6 +119,17 @@ export interface ElectronBrowserViewHost {
      *   which is only correct from a teardown that is itself global.
      */
     releasePage?(owner?: string): Promise<void>;
+    /**
+     * Report that this carrier can no longer serve anything, so its owner may replace it.
+     *
+     * A carrier that borrows an outside process can lose it: the desktop shell exits, and every call
+     * after that would dial a port nobody owns. Without this signal the swap happens only at
+     * startup, so the choice made then is final for the process's life — which is what a user
+     * experiences as "the browser stopped working until I restart DSH". Optional: a carrier that
+     * owns its own lifetime has nothing to report.
+     * @param listener - called once, when the carrier concludes it is gone.
+     */
+    onLost?(listener: () => void): void;
     /**
      * Fold the carrier's presentation away while keeping the page alive.
      *
@@ -705,6 +716,19 @@ export declare class ElectronBrowserProvider implements BrowserProvider {
     private activeTab;
     /** Append a fresh tab and make it active. */
     private newTab;
+    /**
+     * Swap a wedged view for a fresh blank one, keeping the tab's public id.
+     *
+     * A view whose renderer never commits cannot be read again: every evaluate into it runs out its
+     * whole budget. Replacing it is what turns that from permanent into one bad call — the tab id
+     * callers hold stays valid, and the next `browser_open` with the real URL re-populates it.
+     *
+     * The old view is destroyed AFTER the new one is in place, so a failure here cannot leave the
+     * session holding a handle that is already gone.
+     * @param s - the session owning the tab.
+     * @param tab - the tab to reset.
+     */
+    private replaceTabWithBlank;
     /** Find a session's tab by its backing view id (toolbar actions carry view ids). */
     private tabByViewId;
     /**

package/lib/browser-electron/provider.js

@@ -352,7 +352,7 @@ export class ElectronBrowserProvider {
         // session), carrying the label for the window title. Hosts without
         // groupView keep the shared-window behavior.
         this.host.groupView?.(handle, id, label);
-        this.sessions.set(id, { id, label, tabs: [{ id: `tab:${randomUUID()}`, handle }], activeIndex: 0, history: [], nextSeq: 1 });
+        this.sessions.set(id, { id, label, tabs: [{ id: `tab:${randomUUID()}`, handle, url: '' }], activeIndex: 0, history: [], nextSeq: 1 });
         return Promise.resolve(id);
     }
     /** Open a URL in the active tab (default) or a new tab. */
@@ -371,9 +371,16 @@ export class ElectronBrowserProvider {
             const tab = s.tabs[i];
             if (tab === undefined)
                 continue; // defensive: array can shift under concurrency
+            // A tab we know has never navigated is NOT probed: its view has committed no document, so
+            // the round trip can only answer nothing — and it is the round trip that costs. A tab that
+            // HAS navigated is re-read, because the page may have moved itself since; a read that fails
+            // keeps the last accepted URL rather than reporting the tab as blank.
+            const liveUrl = tab.url === '' ? '' : await this.currentUrl(tab.handle).catch(() => tab.url);
+            if (liveUrl !== '')
+                tab.url = liveUrl;
             result.push({
                 id: tab.id,
-                url: await this.currentUrl(tab.handle).catch(() => ''),
+                url: liveUrl,
                 active: i === s.activeIndex,
             });
         }
@@ -455,7 +462,8 @@ export class ElectronBrowserProvider {
     /** Navigate the active tab's view to a URL, honoring HTTP(S)-only admission. */
     async navigate(session, request, signal) {
         const s = this.session(session);
-        const { handle } = this.activeTab(s);
+        const tab = this.activeTab(s);
+        const { handle } = tab;
         const url = request.url;
         try {
             if (this.httpOnly) {
@@ -496,6 +504,11 @@ export class ElectronBrowserProvider {
             // the visit written to the persistent history for a navigation nobody awaits any more.
             signal?.throwIfAborted();
             this.record(s, 'navigate', { url }, true);
+            // The tab now holds a committed document, which is what the blank short-circuit in
+            // `snapshot`/`a11y` keys on. Recorded here rather than after the settle below: the
+            // navigation HAS committed, and a tab wrongly treated as blank would return empty results
+            // for a page that is really there.
+            tab.url = url;
             await this.settleDocument(handle, before, signal);
             this.recordVisit(s, handle);
             this.showActive(s);
@@ -808,6 +821,11 @@ export class ElectronBrowserProvider {
         const s = this.session(session);
         const tab = this.activeTab(s);
         signal?.throwIfAborted();
+        // A tab that has never navigated is a blank, uncommitted view. The collector cannot answer in
+        // it — there is no document to commit — so the call would sit out its whole budget before
+        // saying anything. Answering the empty page immediately is both faster and more truthful.
+        if (tab.url === '')
+            return { url: '', elements: [], truncated: false };
         const script = `(() => {
       const cap = ${String(this.snapshotMaxElements)}
       const url = location.href
@@ -880,7 +898,22 @@ export class ElectronBrowserProvider {
         // Same hang guard as execute: a renderer that has not committed after
         // navigate would otherwise block snapshot forever.
         const timeoutMs = 30_000;
-        const result = await withTimeout(handleSendEvaluate(tab.handle, script), timeoutMs, signal, `browser: snapshot timed out after ${timeoutMs}ms`, () => terminatePage(tab.handle));
+        let result;
+        try {
+            result = await withTimeout(handleSendEvaluate(tab.handle, script), timeoutMs, signal, `browser: snapshot timed out after ${timeoutMs}ms`, () => terminatePage(tab.handle));
+        }
+        catch (error) {
+            // A timeout leaves the wedged view in the session, so every later read would pay the same
+            // 30 seconds again — and `terminatePage` only interrupts the running script, it does not
+            // make the view readable. Replacing it is what turns a permanent loss into one bad call:
+            // the tab keeps the id the caller holds, and the next browser_open with the real URL
+            // repopulates it.
+            if (error instanceof Error && error.name === 'TimeoutError') {
+                this.replaceTabWithBlank(s, tab);
+                throw new BrowserError('browser: snapshot timed out; the stuck tab was reset to blank. Call browser_open with the real target URL before reading it again.', 'BROWSER_SNAPSHOT_TIMEOUT', { cause: error });
+            }
+            throw error;
+        }
         if (!result.ok)
             throw new BrowserError(`browser: snapshot evaluation failed: ${result.exception}`, 'BROWSER_SNAPSHOT_FAILED');
         const value = result.value;
@@ -898,6 +931,10 @@ export class ElectronBrowserProvider {
         const s = this.session(session);
         const tab = this.activeTab(s);
         signal?.throwIfAborted();
+        // Same short-circuit as `snapshot`: a tab that never navigated has no committed document, so
+        // the tree cannot be read and the call would spend its whole budget discovering that.
+        if (tab.url === '')
+            return { url: '', title: undefined, count: 0, nodes: [], truncated: false };
         const includeHidden = request.includeHidden === true;
         // 150 rather than 500. The cap fills on any real page, and 500 nodes measured 38,953
         // characters — 10k-13k tokens for a single call. A caller that needs more asks for it.
@@ -1059,7 +1096,19 @@ export class ElectronBrowserProvider {
       return { url: location.href, title: document.title || undefined, count: out.length, nodes: out, truncated: out.length >= maxNodes }
     })()`;
         const timeoutMs = 30_000;
-        const result = await withTimeout(handleSendEvaluate(tab.handle, script), timeoutMs, signal, `browser: a11y timed out after ${timeoutMs}ms`, () => terminatePage(tab.handle));
+        let result;
+        try {
+            result = await withTimeout(handleSendEvaluate(tab.handle, script), timeoutMs, signal, `browser: a11y timed out after ${timeoutMs}ms`, () => terminatePage(tab.handle));
+        }
+        catch (error) {
+            // As in `snapshot`: a timeout means the view is wedged, and leaving it in the session would
+            // charge every later read the same 30 seconds. Replaced in place, so the tab id survives.
+            if (error instanceof Error && error.name === 'TimeoutError') {
+                this.replaceTabWithBlank(s, tab);
+                throw new BrowserError('browser: a11y timed out; the stuck tab was reset to blank. Call browser_open with the real target URL before reading it again.', 'BROWSER_A11Y_TIMEOUT', { cause: error });
+            }
+            throw error;
+        }
         if (!result.ok)
             throw new BrowserError(`browser: a11y evaluation failed: ${result.exception}`, 'BROWSER_A11Y_FAILED');
         const value = result.value;
@@ -2579,10 +2628,42 @@ export class ElectronBrowserProvider {
         const handle = this.host.createView(s.label);
         // Same window as the session's other tabs.
         this.host.groupView?.(handle, s.id, s.label);
-        s.tabs.push({ id: `tab:${randomUUID()}`, handle });
+        s.tabs.push({ id: `tab:${randomUUID()}`, handle, url: '' });
         s.activeIndex = s.tabs.length - 1;
         this.showActive(s);
     }
+    /**
+     * Swap a wedged view for a fresh blank one, keeping the tab's public id.
+     *
+     * A view whose renderer never commits cannot be read again: every evaluate into it runs out its
+     * whole budget. Replacing it is what turns that from permanent into one bad call — the tab id
+     * callers hold stays valid, and the next `browser_open` with the real URL re-populates it.
+     *
+     * The old view is destroyed AFTER the new one is in place, so a failure here cannot leave the
+     * session holding a handle that is already gone.
+     * @param s - the session owning the tab.
+     * @param tab - the tab to reset.
+     */
+    replaceTabWithBlank(s, tab) {
+        const index = s.tabs.indexOf(tab);
+        if (index < 0)
+            return;
+        let handle;
+        try {
+            handle = this.host.createView(s.label);
+            this.host.groupView?.(handle, s.id, s.label);
+        }
+        catch {
+            // Creating the replacement failed: leaving the wedged tab in place is worse than nothing
+            // only for the caller, who is about to be told the tab timed out either way.
+            return;
+        }
+        const wedged = tab.handle;
+        s.tabs[index] = { id: tab.id, handle, url: '' };
+        if (index === s.activeIndex)
+            this.showActive(s);
+        this.host.destroyView(wedged);
+    }
     /** Find a session's tab by its backing view id (toolbar actions carry view ids). */
     tabByViewId(s, viewId) {
         return s.tabs.find(tab => tab.handle.id === viewId);

package/lib/browser-electron/settings-store.d.ts

@@ -69,6 +69,13 @@ export declare const DEFAULT_SETTINGS: BrowserSettings;
  * @returns the settings file path.
  */
 export declare function settingsPath(): string;
+/**
+ * The channels a settings document may name.
+ *
+ * Exported so the log line and the error message can quote the same set the parser accepts: a
+ * message that lists a value the code rejects (or omits one it takes) is worse than no message.
+ */
+export declare const BROWSER_CHANNELS: readonly ["chrome", "edge", "auto", "bundled", "sidebar"];
 /**
  * Resolve a raw settings document (already parsed, shape unknown) into the full
  * document, field by field. Unknown keys are dropped: the file is not a place to
@@ -76,7 +83,7 @@ export declare function settingsPath(): string;
  * @param raw - the parsed file contents.
  * @returns the resolved settings.
  */
-export declare function resolveSettings(raw: unknown): BrowserSettings;
+export declare function resolveSettings(raw: unknown, warn?: (message: string) => void): BrowserSettings;
 /**
  * File-backed settings with an in-memory snapshot. Reads re-stat the file so an
  * edit from another process (or the settings panel writing through a second
@@ -85,13 +92,14 @@ export declare function resolveSettings(raw: unknown): BrowserSettings;
  */
 export declare class SettingsStore {
     private readonly file;
+    private readonly log?;
     private cached;
     /** Last observed mtime, used to invalidate the cache on external edits. */
     private cachedMtimeMs;
     /**
      * @param file - settings file path (defaults beside the browser profile).
      */
-    constructor(file?: string);
+    constructor(file?: string, log?: ((message: string) => void) | undefined);
     /** Path this store reads and writes. */
     path(): string;
     /**