dsh-builtin-browser 0.3.0 → 0.4.0

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

@@ -38,38 +38,80 @@ 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 child;
-    private readonly client;
-    readonly kind: DetectedBrowser['kind'];
+    private readonly browser;
+    private readonly profileDir;
+    private readonly extraArgs;
     private readonly ephemeralDir?;
     private readonly views;
     private disposed;
     /**
-     * @param child - the launched browser process.
-     * @param client - the CDP connection to it.
-     * @param kind - which product this is (for diagnostics).
-     * @param ephemeralDir - a throwaway profile to remove on release, when the user
-     *   has turned persistence off and no login state should outlive the session.
+     * The browser is started on FIRST USE, never on construction.
+     *
+     * A plugin that launches Chrome the moment its host loads is a plugin that takes
+     * over the machine before anyone asked it to: simply starting DSH would spawn a
+     * browser window. Registration must therefore be inert, and the process is only
+     * spawned when a view is actually needed.
      */
-    private constructor();
+    private client;
+    private child;
+    private starting;
     /**
-     * @param browser - the detected installation to launch.
+     * @param browser - the detected installation to launch on first use.
      * @param profileDir - a plugin-owned directory; the user's own profile is never touched.
      * @param extraArgs - additional Chromium switches.
-     * @param ephemeralDir - a directory to delete when the browser is released, used
-     *   when persistence is switched off so no login state outlives the session.
-     * @returns the host, or undefined when the browser refuses to come up.
+     * @param ephemeralDir - a directory to delete on release, when the user has turned
+     *   persistence off so no login state outlives the session.
+     */
+    constructor(browser: DetectedBrowser, profileDir: string, extraArgs?: readonly string[], ephemeralDir?: string | undefined);
+    /** Which product this host would drive (for diagnostics). */
+    get kind(): DetectedBrowser['kind'];
+    /** Whether the browser has actually been started yet (diagnostics and tests). */
+    get started(): boolean;
+    /**
+     * The CDP client, starting the browser on first use.
+     * @returns the connected client.
+     */
+    private ensureClient;
+    /**
+     * Launch the browser with a private profile and connect over CDP.
+     *
+     * `--remote-debugging-port=0` plus the `DevToolsActivePort` file is the only
+     * reliable way to learn the port: a fixed port collides with whatever else the
+     * machine is running, and parsing stderr is fragile across versions.
+     * @returns the connected client.
+     */
+    private start;
+    /**
+     * Whether this host can back views.
+     *
+     * True while the host is usable — including before the browser has been started,
+     * since the first command is what starts it. Reporting "unavailable" here would
+     * make the plugin fall back for no reason.
      */
-    static launch(browser: DetectedBrowser, profileDir: string, extraArgs?: readonly string[], ephemeralDir?: string): Promise<SystemBrowserViewHost | undefined>;
-    /** Whether this host can back views: the CDP connection is live. */
     available(): boolean;
     createView(): ElectronViewHandle;
     destroyView(handle: ElectronViewHandle): void;
@@ -80,18 +122,29 @@ 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. */
     onUserAction(): void;
     /** The browser reports its own window lifecycle. */
     onViewClosed(): void;
-    /** Close the browser we launched. The user's own windows are a different process. */
+    /**
+     * Close the browser we launched, if we ever launched one.
+     *
+     * The user's own windows belong to a different process and are never touched. A
+     * host whose browser was never started (the common case when nobody used the
+     * browser) simply tears down its bookkeeping.
+     */
     dispose(): void;
     /** The flattened session for a view, creating its page on first use. */
     private ensureSession;

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

@@ -30,34 +30,121 @@ import { join } from 'node:path';
 import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 /**
- * Where each Chromium product installs on Windows, plus the registry paths that
- * survive a non-default install location. Only paths that exist are returned, so a
- * caller can tell "not installed" from "installed elsewhere".
+ * Launcher names to look for on PATH, per product and per platform.
+ *
+ * The names genuinely differ: Linux distributions package the launcher under a
+ * versioned name (`microsoft-edge-stable`, `google-chrome-stable`), Windows puts
+ * `chrome.exe` in an Application directory that may or may not be on PATH, and macOS
+ * ships the executable inside the .app bundle. PATH is still consulted first on every
+ * platform — it is what reflects how the user actually installed the browser.
+ */
+const PATH_NAMES = {
+    chrome: {
+        win32: ['chrome'],
+        darwin: ['Google Chrome', 'Chromium'],
+        linux: ['google-chrome-stable', 'google-chrome', 'chromium', 'chromium-browser'],
+    },
+    edge: {
+        win32: ['msedge'],
+        darwin: ['Microsoft Edge'],
+        linux: ['microsoft-edge-stable', 'microsoft-edge', 'microsoft-edge-dev'],
+    },
+    brave: {
+        win32: ['brave'],
+        darwin: ['Brave Browser'],
+        linux: ['brave-browser', 'brave'],
+    },
+};
+/**
+ * Where each product installs when its launcher is not on PATH.
+ *
+ * Windows keeps the executable inside a version-less Application directory; macOS
+ * keeps it inside the .app bundle; Linux distributions that do not use a launcher
+ * put it under /usr/bin or /opt. All are checked, and anything missed can be named
+ * explicitly with DSH_BROWSER_<KIND>_PATH.
  */
-const WINDOWS_LOCATIONS = {
-    chrome: [
-        String.raw `C:\Program Files\Google\Chrome\Application\chrome.exe`,
-        String.raw `C:\Program Files (x86)\Google\Chrome\Application\chrome.exe`,
-    ],
-    edge: [
-        String.raw `C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe`,
-        String.raw `C:\Program Files\Microsoft\Edge\Application\msedge.exe`,
-    ],
-    brave: [
-        String.raw `C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe`,
-        String.raw `C:\Program Files (x86)\BraveSoftware\Brave-Browser\Application\brave.exe`,
-    ],
+const INSTALL_LOCATIONS = {
+    chrome: {
+        win32: [
+            String.raw `C:\Program Files\Google\Chrome\Application\chrome.exe`,
+            String.raw `C:\Program Files (x86)\Google\Chrome\Application\chrome.exe`,
+        ],
+        darwin: [
+            '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+            '/Applications/Chromium.app/Contents/MacOS/Chromium',
+        ],
+        linux: [
+            '/usr/bin/google-chrome-stable',
+            '/usr/bin/google-chrome',
+            '/usr/bin/chromium',
+            '/opt/google/chrome/chrome',
+            '/snap/bin/chromium',
+        ],
+    },
+    edge: {
+        win32: [
+            String.raw `C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe`,
+            String.raw `C:\Program Files\Microsoft\Edge\Application\msedge.exe`,
+        ],
+        darwin: ['/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge'],
+        linux: [
+            '/usr/bin/microsoft-edge-stable',
+            '/usr/bin/microsoft-edge',
+            '/usr/bin/microsoft-edge-dev',
+        ],
+    },
+    brave: {
+        win32: [
+            String.raw `C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe`,
+            String.raw `C:\Program Files (x86)\BraveSoftware\Brave-Browser\Application\brave.exe`,
+        ],
+        darwin: ['/Applications/Brave Browser.app/Contents/MacOS/Brave Browser'],
+        linux: ['/usr/bin/brave-browser', '/usr/bin/brave', '/snap/bin/brave'],
+    },
 };
+/**
+ * Find an executable by name on PATH.
+ *
+ * PATH is read from the supplied environment rather than the process's own, so the
+ * detection stays testable. On Windows a bare name needs its extension; elsewhere
+ * the launcher is the file itself.
+ * @param names - candidate launcher names, in preference order.
+ * @param env - the environment to read PATH from.
+ * @param platform - the platform whose PATH and extension conventions apply.
+ * @returns the first existing absolute path, or undefined.
+ */
+function findOnPath(names, env, platform) {
+    // Windows spells it Path as often as PATH; the separator differs too.
+    const raw = env.PATH ?? env.Path ?? env.path ?? '';
+    const separator = platform === 'win32' ? ';' : ':';
+    const directories = raw.split(separator).map(entry => entry.trim()).filter(entry => entry !== '');
+    const suffixes = platform === 'win32' ? ['.exe', '.cmd', ''] : [''];
+    for (const name of names) {
+        for (const directory of directories) {
+            for (const suffix of suffixes) {
+                const candidate = join(directory, `${name}${suffix}`);
+                if (existsSync(candidate))
+                    return candidate;
+            }
+        }
+    }
+    return undefined;
+}
 /**
  * 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 function detectBrowser(channel, env = process.env) {
+export function detectBrowser(channel, env = process.env, platform = process.platform) {
     if (channel === 'bundled')
         return undefined;
     const order = channel === 'auto' ? ['chrome', 'edge', 'brave'] : [channel];
@@ -65,16 +152,33 @@ export function detectBrowser(channel, env = process.env) {
         const fromEnv = (kind === 'chrome' ? env.DSH_BROWSER_CHROME_PATH : kind === 'edge' ? env.DSH_BROWSER_EDGE_PATH : undefined);
         if (fromEnv !== undefined && fromEnv !== '' && existsSync(fromEnv))
             return { kind, path: fromEnv };
-        for (const candidate of WINDOWS_LOCATIONS[kind] ?? []) {
+        const onPath = findOnPath(PATH_NAMES[kind]?.[platform] ?? [], env, platform);
+        if (onPath !== undefined)
+            return { kind, path: onPath };
+        for (const candidate of INSTALL_LOCATIONS[kind]?.[platform] ?? []) {
             if (existsSync(candidate))
                 return { kind, path: candidate };
         }
     }
     return 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 function searchSummary(kind, platform = process.platform) {
+    const onPath = (PATH_NAMES[kind]?.[platform] ?? []).map(name => `${name} (on PATH)`);
+    const located = INSTALL_LOCATIONS[kind]?.[platform] ?? [];
+    return [...onPath, ...located];
+}
 /** One CDP connection to a browser-level WebSocket, with flattened sessions. */
 class CdpClient {
-    url;
     nextId = 1;
     pending = new Map();
     ready;
@@ -82,7 +186,6 @@ class CdpClient {
      * @param url - the browser's `webSocketDebuggerUrl`.
      */
     constructor(url) {
-        this.url = url;
         // Node 22 provides WebSocket globally; no dependency is added for this.
         const socket = new WebSocket(url);
         this.socket = socket;
@@ -94,9 +197,30 @@ class CdpClient {
         socket.addEventListener('close', () => this.fail(new Error('dsh-builtin-browser: the browser closed the CDP connection')));
     }
     socket;
-    /** Resolve once the socket is open. */
+    /**
+     * Resolve once the socket is open.
+     *
+     * Bounded on purpose. `ready` settles on the socket's own `open` or `error` events, and
+     * a connection that is dropped by something in between may deliver neither — in which
+     * case an unbounded await here would hang the tool call forever, because the caller's
+     * own deadline is only checked between polls and this await happens inside one of them.
+     * @returns when the handshake completed.
+     */
     async whenReady() {
-        await this.ready;
+        const timeoutMs = 30_000;
+        let timer;
+        try {
+            await Promise.race([
+                this.ready,
+                new Promise((_resolve, reject) => {
+                    timer = setTimeout(() => reject(new Error(`dsh-builtin-browser: the browser did not complete the CDP handshake within ${timeoutMs / 1000}s`)), timeoutMs);
+                }),
+            ]);
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
     }
     /**
      * Send one CDP command, optionally on an attached session.
@@ -155,37 +279,71 @@ class CdpClient {
 }
 /** A system browser driven over CDP, presented as a browser view host. */
 export class SystemBrowserViewHost {
-    child;
-    client;
-    kind;
+    browser;
+    profileDir;
+    extraArgs;
     ephemeralDir;
     views = new Map();
     disposed = false;
     /**
-     * @param child - the launched browser process.
-     * @param client - the CDP connection to it.
-     * @param kind - which product this is (for diagnostics).
-     * @param ephemeralDir - a throwaway profile to remove on release, when the user
-     *   has turned persistence off and no login state should outlive the session.
+     * The browser is started on FIRST USE, never on construction.
+     *
+     * A plugin that launches Chrome the moment its host loads is a plugin that takes
+     * over the machine before anyone asked it to: simply starting DSH would spawn a
+     * browser window. Registration must therefore be inert, and the process is only
+     * spawned when a view is actually needed.
      */
-    constructor(child, client, kind, ephemeralDir) {
-        this.child = child;
-        this.client = client;
-        this.kind = kind;
-        this.ephemeralDir = ephemeralDir;
-    }
+    client;
+    child;
+    starting;
     /**
-     * @param browser - the detected installation to launch.
+     * @param browser - the detected installation to launch on first use.
      * @param profileDir - a plugin-owned directory; the user's own profile is never touched.
      * @param extraArgs - additional Chromium switches.
-     * @param ephemeralDir - a directory to delete when the browser is released, used
-     *   when persistence is switched off so no login state outlives the session.
-     * @returns the host, or undefined when the browser refuses to come up.
+     * @param ephemeralDir - a directory to delete on release, when the user has turned
+     *   persistence off so no login state outlives the session.
+     */
+    constructor(browser, profileDir, extraArgs = [], ephemeralDir) {
+        this.browser = browser;
+        this.profileDir = profileDir;
+        this.extraArgs = extraArgs;
+        this.ephemeralDir = ephemeralDir;
+    }
+    /** Which product this host would drive (for diagnostics). */
+    get kind() {
+        return this.browser.kind;
+    }
+    /** Whether the browser has actually been started yet (diagnostics and tests). */
+    get started() {
+        return this.child !== undefined;
+    }
+    /**
+     * The CDP client, starting the browser on first use.
+     * @returns the connected client.
      */
-    static async launch(browser, profileDir, extraArgs = [], ephemeralDir) {
+    async ensureClient() {
+        // A disposed host must never start a browser: doing so would spawn a process
+        // nobody owns and nobody will kill.
+        if (this.disposed)
+            throw new Error('dsh-builtin-browser: this browser host was released');
+        if (this.client !== undefined)
+            return this.client;
+        // Concurrent first calls share one startup rather than racing two browsers.
+        this.starting ??= this.start().finally(() => { this.starting = undefined; });
+        return await this.starting;
+    }
+    /**
+     * Launch the browser with a private profile and connect over CDP.
+     *
+     * `--remote-debugging-port=0` plus the `DevToolsActivePort` file is the only
+     * reliable way to learn the port: a fixed port collides with whatever else the
+     * machine is running, and parsing stderr is fragile across versions.
+     * @returns the connected client.
+     */
+    async start() {
         const args = [
             '--remote-debugging-port=0',
-            `--user-data-dir=${profileDir}`,
+            `--user-data-dir=${this.profileDir}`,
             // Behave like a fresh, unattended browser: no first-run UI, no default-browser
             // prompt, no restore bubble, and no "Chrome is being controlled" infobar.
             '--no-first-run',
@@ -193,19 +351,59 @@ export class SystemBrowserViewHost {
             '--disable-features=Translate,MediaRouter',
             '--disable-session-crashed-bubble',
             '--hide-crash-restore-bubble',
-            ...extraArgs,
+            ...this.extraArgs,
             'about:blank',
         ];
-        const child = spawn(browser.path, args, { stdio: ['ignore', 'ignore', 'ignore'], windowsHide: false });
-        const portFile = join(profileDir, 'DevToolsActivePort');
+        const child = spawn(this.browser.path, args, { stdio: ['ignore', 'ignore', 'ignore'], windowsHide: false });
+        this.child = child;
+        /**
+         * A launch that fails (ENOENT, no permission, a broken binary) is reported by an
+         * asynchronous 'error' event on the child, NOT by a throw here and NOT by exitCode.
+         * Without this listener Node treats it as unhandled and takes the whole host process
+         * down — one bad browser path would kill DSH, not just fail a tool call.
+         */
+        let launchError;
+        child.on('error', error => { launchError = error; });
+        const portFile = join(this.profileDir, 'DevToolsActivePort');
         const deadline = Date.now() + 30_000;
+        /**
+         * Why the loop stopped, so the failure can say what actually happened. Reporting
+         * every ending as "did not expose CDP within 30s" was wrong three ways: the cause,
+         * the words, and the elapsed time — a browser that cannot be launched says so in
+         * half a second, and the caller then looks for a CDP problem that does not exist.
+         */
+        let stopped = 'timeout';
         for (;;) {
+            // Released while we were starting: stop here rather than keep polling for a
+            // browser that dispose() has already killed, which would leave a connection
+            // to a dead process behind. The child is killed here too — dispose() may have
+            // run before this child was recorded, leaving nobody else to do it.
+            if (this.disposed) {
+                child.kill();
+                if (this.child === child)
+                    this.child = undefined;
+                stopped = 'released';
+                break;
+            }
+            if (launchError !== undefined) {
+                if (this.child === child)
+                    this.child = undefined;
+                stopped = 'launch-failed';
+                break;
+            }
             if (Date.now() > deadline) {
                 child.kill();
-                return undefined;
+                if (this.child === child)
+                    this.child = undefined;
+                stopped = 'timeout';
+                break;
+            }
+            if (child.exitCode !== null) {
+                if (this.child === child)
+                    this.child = undefined;
+                stopped = 'exited';
+                break;
             }
-            if (child.exitCode !== null)
-                return undefined;
             if (existsSync(portFile)) {
                 try {
                     const port = readFileSync(portFile, 'utf8').split('\n')[0]?.trim() ?? '';
@@ -214,7 +412,14 @@ export class SystemBrowserViewHost {
                         if (typeof version.webSocketDebuggerUrl === 'string') {
                             const client = new CdpClient(version.webSocketDebuggerUrl);
                             await client.whenReady();
-                            return new SystemBrowserViewHost(child, client, browser.kind, ephemeralDir);
+                            // Still wanted? A dispose() during the handshake has already killed the
+                            // process, so publishing the client would leave a dangling connection.
+                            if (this.disposed) {
+                                client.close();
+                                break;
+                            }
+                            this.client = client;
+                            return client;
                         }
                     }
                 }
@@ -224,8 +429,28 @@ export class SystemBrowserViewHost {
             }
             await new Promise(resolve => setTimeout(resolve, 250));
         }
+        // Each ending gets its own message. The old single message blamed a CDP timeout for
+        // all of them, which sent the reader looking for a port problem when the browser had
+        // simply failed to launch.
+        const target = `${this.browser.kind} (${this.browser.path})`;
+        if (stopped === 'launch-failed') {
+            throw new Error(`dsh-builtin-browser: could not launch ${target}: ${launchError?.message ?? 'unknown error'}`);
+        }
+        if (stopped === 'exited') {
+            throw new Error(`dsh-builtin-browser: ${target} exited immediately after launch (exit code ${child.exitCode}); check that the path is a runnable browser`);
+        }
+        if (stopped === 'released') {
+            throw new Error(`dsh-builtin-browser: ${target} was released while it was starting`);
+        }
+        throw new Error(`dsh-builtin-browser: ${target} did not expose CDP within 30s`);
     }
-    /** Whether this host can back views: the CDP connection is live. */
+    /**
+     * Whether this host can back views.
+     *
+     * True while the host is usable — including before the browser has been started,
+     * since the first command is what starts it. Reporting "unavailable" here would
+     * make the plugin fall back for no reason.
+     */
     available() {
         return !this.disposed;
     }
@@ -233,9 +458,13 @@ export class SystemBrowserViewHost {
         const viewId = randomUUID();
         return {
             id: viewId,
+            // This is the real browser, not Electron: CDP's JPEG encoder works here, so the
+            // provider may pass format and quality through instead of falling back to PNG.
+            supportsCdpJpeg: true,
             sendCommand: async (method, params) => {
+                const client = await this.ensureClient();
                 const session = this.views.get(viewId) ?? await this.ensureSession(viewId);
-                const result = await this.client.send(method, params, session);
+                const result = await client.send(method, params, session);
                 return (result ?? {});
             },
         };
@@ -249,7 +478,8 @@ export class SystemBrowserViewHost {
         // was attached to, which is why they are tracked separately.
         const targetId = this.sessions.get(session);
         this.sessions.delete(session);
-        if (targetId !== undefined) {
+        // Nothing to close if the browser was never started.
+        if (targetId !== undefined && this.client !== undefined) {
             // Best-effort: a page that is already gone is not an error.
             void this.client.send('Target.closeTarget', { targetId }).catch(() => undefined);
         }
@@ -261,36 +491,47 @@ export class SystemBrowserViewHost {
     /** The browser owns window grouping. */
     groupView() { }
     /**
-     * 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.
      */
     async focus() {
         try {
-            this.child.kill('SIGCONT');
+            this.child?.kill('SIGCONT');
         }
-        catch { /* not supported on Windows; harmless */ }
+        catch { /* Windows has no SIGCONT; nothing to do */ }
     }
     /** The browser reports its own window lifecycle. */
     onUserAction() { }
     /** The browser reports its own window lifecycle. */
     onViewClosed() { }
-    /** Close the browser we launched. The user's own windows are a different process. */
+    /**
+     * Close the browser we launched, if we ever launched one.
+     *
+     * The user's own windows belong to a different process and are never touched. A
+     * host whose browser was never started (the common case when nobody used the
+     * browser) simply tears down its bookkeeping.
+     */
     dispose() {
         if (this.disposed)
             return;
         this.disposed = true;
         this.views.clear();
         this.sessions.clear();
-        this.client.close();
+        this.client?.close();
         try {
-            this.child.kill();
+            this.child?.kill();
         }
         catch { /* already gone */ }
         const ephemeral = this.ephemeralDir;
-        if (ephemeral !== undefined) {
+        if (ephemeral !== undefined && this.child !== undefined) {
             // The browser flushes its profile while shutting down, so deleting later avoids
             // racing it. Leftovers are only a stray temp directory, never a live credential.
             setTimeout(() => { try {
@@ -298,17 +539,25 @@ export class SystemBrowserViewHost {
             }
             catch { /* best effort */ } }, 3_000).unref?.();
         }
+        else if (ephemeral !== undefined) {
+            // Never started, so nothing can be holding it open.
+            try {
+                rmSync(ephemeral, { recursive: true, force: true });
+            }
+            catch { /* best effort */ }
+        }
     }
     /** The flattened session for a view, creating its page on first use. */
     async ensureSession(viewId) {
         const existing = this.views.get(viewId);
         if (existing !== undefined)
             return existing;
-        const created = await this.client.send('Target.createTarget', { url: 'about:blank' });
+        const client = await this.ensureClient();
+        const created = await client.send('Target.createTarget', { url: 'about:blank' });
         const targetId = created?.targetId;
         if (typeof targetId !== 'string')
             throw new Error('dsh-builtin-browser: the browser did not create a page');
-        const attached = await this.client.send('Target.attachToTarget', { targetId, flatten: true });
+        const attached = await client.send('Target.attachToTarget', { targetId, flatten: true });
         const sessionId = attached?.sessionId;
         if (typeof sessionId !== 'string')
             throw new Error('dsh-builtin-browser: the browser did not attach to the new page');