chrome-devtools-mcp 1.0.1 → 1.1.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm chrome-devtools-mcp package](https://img.shields.io/npm/v/chrome-devtools-mcp.svg)](https://npmjs.org/package/chrome-devtools-mcp)
 
-Chrome DevTools for agents (`chrome-devtools-mcp`) lets your coding agent (such as Gemini, Claude, Cursor or Copilot)
+Chrome DevTools for agents (`chrome-devtools-mcp`) lets your coding agent (such as Antigravity, Claude, Cursor or Copilot)
 control and inspect a live Chrome browser. It acts as a Model-Context-Protocol
 (MCP) server, giving your AI coding assistant access to the full power of
 Chrome DevTools for reliable automation, in-depth debugging, and performance analysis.
@@ -249,7 +249,7 @@ and the expert guidance it needs to use them effectively.
 
 1.  Open the **Command Palette** (`Cmd+Shift+P` on macOS or `Ctrl+Shift+P` on Windows/Linux).
 2.  Search for and run the **Chat: Install Plugin From Source** command.
-3.  Paste in our repository URL: `https://github.com/ChromeDevTools/chrome-devtools-mcp`
+3.  Paste in our repository name: `ChromeDevTools/chrome-devtools-mcp`.
 
 That's it! Your agent is now supercharged with Chrome DevTools capabilities.
 
@@ -515,11 +515,11 @@ If you run into any issues, checkout our [troubleshooting guide](./docs/troubles
   - [`screencast_start`](docs/tool-reference.md#screencast_start)
   - [`screencast_stop`](docs/tool-reference.md#screencast_stop)
 - **Memory** (5 tools)
-  - [`take_memory_snapshot`](docs/tool-reference.md#take_memory_snapshot)
-  - [`get_memory_snapshot_details`](docs/tool-reference.md#get_memory_snapshot_details)
-  - [`get_node_retainers`](docs/tool-reference.md#get_node_retainers)
-  - [`get_nodes_by_class`](docs/tool-reference.md#get_nodes_by_class)
-  - [`load_memory_snapshot`](docs/tool-reference.md#load_memory_snapshot)
+  - [`take_heapsnapshot`](docs/tool-reference.md#take_heapsnapshot)
+  - [`get_heapsnapshot_class_nodes`](docs/tool-reference.md#get_heapsnapshot_class_nodes)
+  - [`get_heapsnapshot_details`](docs/tool-reference.md#get_heapsnapshot_details)
+  - [`get_heapsnapshot_retainers`](docs/tool-reference.md#get_heapsnapshot_retainers)
+  - [`get_heapsnapshot_summary`](docs/tool-reference.md#get_heapsnapshot_summary)
 - **Extensions** (5 tools)
   - [`install_extension`](docs/tool-reference.md#install_extension)
   - [`list_extensions`](docs/tool-reference.md#list_extensions)

package/build/src/DevtoolsUtils.js

@@ -109,7 +109,7 @@ const DEFAULT_FACTORY = async (page) => {
     targetManager.observeModels(DevTools.NetworkManager.NetworkManager, DISABLE_NETWORK);
     const target = targetManager.createTarget('main', '', 'frame', // eslint-disable-line @typescript-eslint/no-explicit-any
     /* parentTarget */ null, session.id(), undefined, connection);
-    return { target, universe };
+    return { target, universe, session };
 };
 // We don't want to pause any DevTools universe session ever on the MCP side.
 //

package/build/src/HeapSnapshotManager.js

@@ -20,8 +20,8 @@ export class HeapSnapshotManager {
         this.#snapshots.set(absolutePath, {
             snapshot,
             worker,
-            uidToClassKey: new Map(),
-            classKeyToUid: new Map(),
+            idToClassKey: new Map(),
+            classKeyToId: new Map(),
             idGenerator: createIdGenerator(),
         });
         return snapshot;
@@ -31,10 +31,10 @@ export class HeapSnapshotManager {
         const filter = new DevTools.HeapSnapshotModel.HeapSnapshotModel.NodeFilter();
         const aggregates = await snapshot.aggregatesWithFilter(filter);
         for (const key of Object.keys(aggregates)) {
-            const uid = await this.getOrCreateUidForClassKey(filePath, key);
+            const id = await this.getOrCreateIdForClassKey(filePath, key);
             const aggregate = aggregates[key];
             if (aggregate) {
-                aggregate[stableIdSymbol] = uid;
+                aggregate[stableIdSymbol] = id;
             }
         }
         return aggregates;
@@ -47,22 +47,22 @@ export class HeapSnapshotManager {
         const snapshot = await this.getSnapshot(filePath);
         return snapshot.staticData;
     }
-    async getOrCreateUidForClassKey(filePath, classKey) {
+    async getOrCreateIdForClassKey(filePath, classKey) {
         const cached = this.#getCachedSnapshot(filePath);
-        let uid = cached.classKeyToUid.get(classKey);
-        if (!uid) {
-            uid = cached.idGenerator();
-            cached.classKeyToUid.set(classKey, uid);
-            cached.uidToClassKey.set(uid, classKey);
+        let id = cached.classKeyToId.get(classKey);
+        if (!id) {
+            id = cached.idGenerator();
+            cached.classKeyToId.set(classKey, id);
+            cached.idToClassKey.set(id, classKey);
         }
-        return uid;
+        return id;
     }
-    async getNodesByUid(filePath, uid) {
+    async getNodesById(filePath, id) {
         const snapshot = await this.getSnapshot(filePath);
         const filter = new DevTools.HeapSnapshotModel.HeapSnapshotModel.NodeFilter();
-        const className = await this.resolveClassKeyFromUid(filePath, uid);
+        const className = await this.resolveClassKeyFromId(filePath, id);
         if (!className) {
-            throw new Error(`Class with UID ${uid} not found in heap snapshot`);
+            throw new Error(`Class with ID ${id} not found in heap snapshot`);
         }
         const provider = snapshot.createNodesProviderForClass(className, filter);
         return await provider.serializeItemsRange(0, Infinity);
@@ -99,9 +99,9 @@ export class HeapSnapshotManager {
         }
         return cached;
     }
-    async resolveClassKeyFromUid(filePath, uid) {
+    async resolveClassKeyFromId(filePath, id) {
         const cached = this.#getCachedSnapshot(filePath);
-        return cached.uidToClassKey.get(uid);
+        return cached.idToClassKey.get(id);
     }
     async #loadSnapshot(absolutePath) {
         const workerProxy = new DevTools.HeapSnapshotModel.HeapSnapshotProxy.HeapSnapshotWorkerProxy(() => {

package/build/src/McpContext.js

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import fs from 'node:fs/promises';
+import fsPromises from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -14,7 +15,7 @@ import { NetworkCollector, ConsoleCollector, } from './PageCollector.js';
 import { Locator, PredefinedNetworkConditions, } from './third_party/index.js';
 import { listPages } from './tools/pages.js';
 import { CLOSE_PAGE_ERROR } from './tools/ToolDefinition.js';
-import { ensureExtension, getTempFilePath } from './utils/files.js';
+import { ensureExtension, getTempFilePath, resolveCanonicalPath, } from './utils/files.js';
 import { getNetworkMultiplierFromString } from './WaitForHelper.js';
 const DEFAULT_TIMEOUT = 5_000;
 const NAVIGATION_TIMEOUT = 10_000;
@@ -106,7 +107,7 @@ export class McpContext {
     setRoots(roots) {
         this.#roots = roots;
     }
-    validatePath(filePath) {
+    async validatePath(filePath) {
         if (filePath === undefined) {
             return;
         }
@@ -114,15 +115,36 @@ export class McpContext {
         if (roots === undefined) {
             return;
         }
-        const absolutePath = path.resolve(filePath);
+        let canonicalPath;
+        try {
+            canonicalPath = await resolveCanonicalPath(filePath);
+        }
+        catch (err) {
+            const errMsg = err instanceof Error ? err.message : String(err);
+            console.error(`[MCP Context] Error resolving real path for ${filePath}: ${errMsg}`);
+            throw new Error(`Access denied: Cannot resolve base path for ${filePath}.`);
+        }
+        let allowed = false;
         for (const root of roots) {
-            const rootPath = path.resolve(fileURLToPath(root.uri));
-            if (absolutePath === rootPath ||
-                absolutePath.startsWith(rootPath + path.sep)) {
-                return;
+            try {
+                const rootPathUri = root.uri;
+                const rootPath = path.resolve(fileURLToPath(rootPathUri));
+                const canonicalRoot = await fsPromises.realpath(rootPath);
+                if (canonicalPath === canonicalRoot ||
+                    canonicalPath.startsWith(canonicalRoot + path.sep)) {
+                    allowed = true;
+                    break;
+                }
+            }
+            catch (rootErr) {
+                const errMsg = rootErr instanceof Error ? rootErr.message : String(rootErr);
+                console.warn(`[MCP Context] Could not resolve configured root ${root.uri}: ${errMsg}`);
+                // Skip this root if it cannot be resolved.
             }
         }
-        throw new Error(`Access denied: path ${filePath} is not within any of the workspace roots ${JSON.stringify(roots)}.`);
+        if (!allowed) {
+            throw new Error(`Access denied: path ${filePath} (canonical: ${canonicalPath}) is not within any of the configured workspace roots.`);
+        }
     }
     resolveCdpRequestId(page, cdpRequestId) {
         if (!cdpRequestId) {
@@ -213,12 +235,23 @@ export class McpContext {
             await page.emulateNetworkConditions(networkCondition);
             newSettings.networkConditions = options.networkConditions;
         }
+        const secondarySession = this.getDevToolsUniverse(mcpPage)?.session;
         if (!options.cpuThrottlingRate) {
             await page.emulateCPUThrottling(1);
+            if (secondarySession) {
+                await secondarySession.send('Emulation.setCPUThrottlingRate', {
+                    rate: 1,
+                });
+            }
             delete newSettings.cpuThrottlingRate;
         }
         else {
             await page.emulateCPUThrottling(options.cpuThrottlingRate);
+            if (secondarySession) {
+                await secondarySession.send('Emulation.setCPUThrottlingRate', {
+                    rate: options.cpuThrottlingRate,
+                });
+            }
             newSettings.cpuThrottlingRate = options.cpuThrottlingRate;
         }
         if (!options.geolocation) {
@@ -250,7 +283,6 @@ export class McpContext {
             newSettings.colorScheme = options.colorScheme;
         }
         if (!options.viewport) {
-            await page.setViewport(null);
             delete newSettings.viewport;
         }
         else {
@@ -260,14 +292,22 @@ export class McpContext {
                 hasTouch: false,
                 isLandscape: false,
             };
-            const viewport = { ...defaults, ...options.viewport };
-            await page.setViewport(viewport);
-            newSettings.viewport = viewport;
+            newSettings.viewport = { ...defaults, ...options.viewport };
+        }
+        if (options.extraHttpHeaders !== undefined) {
+            await page.setExtraHTTPHeaders(options.extraHttpHeaders);
+            newSettings.extraHttpHeaders = options.extraHttpHeaders;
+            if (Object.keys(options.extraHttpHeaders).length === 0) {
+                delete newSettings.extraHttpHeaders;
+            }
         }
         mcpPage.emulationSettings = Object.keys(newSettings).length
             ? newSettings
             : {};
         this.#updateSelectedPageTimeouts();
+        // This should happen after updating the page timeouts.
+        // Setting the viewport can trigger a reload which we don't want to timeout.
+        await page.setViewport(newSettings.viewport ?? null);
     }
     setIsRunningPerformanceTrace(x) {
         this.#isRunningTrace = x;
@@ -333,9 +373,9 @@ export class McpContext {
         page.pptrPage.setDefaultTimeout(DEFAULT_TIMEOUT * cpuMultiplier);
         // 10sec should be enough for the load event to be emitted during
         // navigations.
-        // Increased in case we throttle the network requests
+        // Increased in case we throttle the network requests or the CPU
         const networkMultiplier = getNetworkMultiplierFromString(page.networkConditions);
-        page.pptrPage.setDefaultNavigationTimeout(NAVIGATION_TIMEOUT * networkMultiplier);
+        page.pptrPage.setDefaultNavigationTimeout(NAVIGATION_TIMEOUT * networkMultiplier * cpuMultiplier);
     }
     // Linear scan over per-page snapshots. The page count is small (typically
     // 2-10) so a reverse index isn't worthwhile given the uid-reuse lifecycle
@@ -499,7 +539,7 @@ export class McpContext {
     }
     async saveTemporaryFile(data, filename) {
         const filepath = await getTempFilePath(filename);
-        this.validatePath(filepath);
+        await this.validatePath(filepath);
         try {
             await fs.writeFile(filepath, data);
         }
@@ -509,7 +549,7 @@ export class McpContext {
         return { filepath };
     }
     async saveFile(data, clientProvidedFilePath, extension) {
-        this.validatePath(clientProvidedFilePath);
+        await this.validatePath(clientProvidedFilePath);
         try {
             const filePath = ensureExtension(path.resolve(clientProvidedFilePath), extension);
             await fs.mkdir(path.dirname(filePath), { recursive: true });
@@ -562,7 +602,6 @@ export class McpContext {
         await this.#networkCollector.init(pages);
     }
     async installExtension(extensionPath) {
-        this.validatePath(extensionPath);
         const id = await this.browser.installExtension(extensionPath);
         return id;
     }
@@ -586,20 +625,16 @@ export class McpContext {
         return pptrExtensions.get(id);
     }
     async getHeapSnapshotAggregates(filePath) {
-        this.validatePath(filePath);
         return await this.#heapSnapshotManager.getAggregates(filePath);
     }
     async getHeapSnapshotStats(filePath) {
-        this.validatePath(filePath);
         return await this.#heapSnapshotManager.getStats(filePath);
     }
     async getHeapSnapshotStaticData(filePath) {
-        this.validatePath(filePath);
         return await this.#heapSnapshotManager.getStaticData(filePath);
     }
-    async getHeapSnapshotNodesByUid(filePath, uid) {
-        this.validatePath(filePath);
-        return await this.#heapSnapshotManager.getNodesByUid(filePath, uid);
+    async getHeapSnapshotNodesById(filePath, id) {
+        return await this.#heapSnapshotManager.getNodesById(filePath, id);
     }
     async getHeapSnapshotRetainers(filePath, nodeId) {
         return await this.#heapSnapshotManager.getRetainers(filePath, nodeId);

package/build/src/McpResponse.js

@@ -505,7 +505,7 @@ export class McpResponse {
         }
         const geolocation = this.#page?.geolocation;
         if (geolocation) {
-            response.push(`Emulating geolocation: latitude=${geolocation.latitude}, longtitude=${geolocation.longitude}`);
+            response.push(`Emulating geolocation: latitude=${geolocation.latitude}, longitude=${geolocation.longitude}`);
             structuredContent.geolocation = geolocation;
         }
         const viewport = this.#page?.viewport;

package/build/src/bin/chrome-devtools-cli-options.js

@@ -136,6 +136,12 @@ export const commands = {
                 description: "Emulate device viewports '<width>x<height>x<devicePixelRatio>[,mobile][,touch][,landscape]'. 'touch' and 'mobile' to emulate mobile devices. 'landscape' to emulate landscape mode.",
                 required: false,
             },
+            extraHttpHeaders: {
+                name: 'extraHttpHeaders',
+                type: 'string',
+                description: 'Extra HTTP headers as a JSON string object, e.g. {"X-Custom": "value", "Authorization": "Bearer token"}. Headers are included into every HTTP request originating from the page and persist across navigations until cleared. Pass an empty string to clear all extra headers.',
+                required: false,
+            },
         },
     },
     evaluate_script: {
@@ -240,8 +246,8 @@ export const commands = {
             },
         },
     },
-    get_memory_snapshot_details: {
-        description: 'Loads a memory heapsnapshot and returns all available information including statistics, static data, and aggregated node information. Supports pagination for aggregates. (requires flag: --experimentalMemory=true)',
+    get_heapsnapshot_class_nodes: {
+        description: 'Loads a memory heapsnapshot and returns instances of a specific class with their IDs. (requires flag: --experimentalMemory=true)',
         category: 'Memory',
         args: {
             filePath: {
@@ -250,45 +256,51 @@ export const commands = {
                 description: 'A path to a .heapsnapshot file to read.',
                 required: true,
             },
+            id: {
+                name: 'id',
+                type: 'number',
+                description: 'The ID for the class, obtained from details.',
+                required: true,
+            },
             pageIdx: {
                 name: 'pageIdx',
                 type: 'number',
-                description: 'The page index for pagination of aggregates.',
+                description: 'The page index for pagination.',
                 required: false,
             },
             pageSize: {
                 name: 'pageSize',
                 type: 'number',
-                description: 'The page size for pagination of aggregates.',
+                description: 'The page size for pagination.',
                 required: false,
             },
         },
     },
-    get_network_request: {
-        description: 'Gets a network request by an optional reqid, if omitted returns the currently selected request in the DevTools Network panel.',
-        category: 'Network',
+    get_heapsnapshot_details: {
+        description: 'Loads a memory heapsnapshot and returns all available information including statistics, static data, and aggregated node information. Supports pagination for aggregates. (requires flag: --experimentalMemory=true)',
+        category: 'Memory',
         args: {
-            reqid: {
-                name: 'reqid',
-                type: 'number',
-                description: 'The reqid of the network request. If omitted returns the currently selected request in the DevTools Network panel.',
-                required: false,
-            },
-            requestFilePath: {
-                name: 'requestFilePath',
+            filePath: {
+                name: 'filePath',
                 type: 'string',
-                description: 'The absolute or relative path to a .network-request file to save the request body to. If omitted, the body is returned inline.',
+                description: 'A path to a .heapsnapshot file to read.',
+                required: true,
+            },
+            pageIdx: {
+                name: 'pageIdx',
+                type: 'number',
+                description: 'The page index for pagination of aggregates.',
                 required: false,
             },
-            responseFilePath: {
-                name: 'responseFilePath',
-                type: 'string',
-                description: 'The absolute or relative path to a .network-response file to save the response body to. If omitted, the body is returned inline.',
+            pageSize: {
+                name: 'pageSize',
+                type: 'number',
+                description: 'The page size for pagination of aggregates.',
                 required: false,
             },
         },
     },
-    get_node_retainers: {
+    get_heapsnapshot_retainers: {
         description: 'Loads a memory heapsnapshot and returns retainers for a specific node ID. (requires flag: --experimentalMemory=true)',
         category: 'Memory',
         args: {
@@ -301,7 +313,7 @@ export const commands = {
             nodeId: {
                 name: 'nodeId',
                 type: 'number',
-                description: 'The stable node ID to get retainers for.',
+                description: 'The node ID to get retainers for.',
                 required: true,
             },
             pageIdx: {
@@ -318,8 +330,8 @@ export const commands = {
             },
         },
     },
-    get_nodes_by_class: {
-        description: 'Loads a memory heapsnapshot and returns instances of a specific class with their stable IDs. (requires flag: --experimentalMemory=true)',
+    get_heapsnapshot_summary: {
+        description: 'Loads a memory heapsnapshot and returns snapshot summary stats. (requires flag: --experimentalMemory=true)',
         category: 'Memory',
         args: {
             filePath: {
@@ -328,22 +340,28 @@ export const commands = {
                 description: 'A path to a .heapsnapshot file to read.',
                 required: true,
             },
-            uid: {
-                name: 'uid',
+        },
+    },
+    get_network_request: {
+        description: 'Gets a network request by an optional reqid, if omitted returns the currently selected request in the DevTools Network panel.',
+        category: 'Network',
+        args: {
+            reqid: {
+                name: 'reqid',
                 type: 'number',
-                description: 'The unique UID for the class, obtained from aggregates listing.',
-                required: true,
+                description: 'The reqid of the network request. If omitted returns the currently selected request in the DevTools Network panel.',
+                required: false,
             },
-            pageIdx: {
-                name: 'pageIdx',
-                type: 'number',
-                description: 'The page index for pagination.',
+            requestFilePath: {
+                name: 'requestFilePath',
+                type: 'string',
+                description: 'The absolute or relative path to a .network-request file to save the request body to. If omitted, the body is returned inline.',
                 required: false,
             },
-            pageSize: {
-                name: 'pageSize',
-                type: 'number',
-                description: 'The page size for pagination.',
+            responseFilePath: {
+                name: 'responseFilePath',
+                type: 'string',
+                description: 'The absolute or relative path to a .network-response file to save the response body to. If omitted, the body is returned inline.',
                 required: false,
             },
         },
@@ -507,18 +525,6 @@ export const commands = {
         category: 'WebMCP',
         args: {},
     },
-    load_memory_snapshot: {
-        description: 'Loads a memory heapsnapshot and returns snapshot summary stats. (requires flag: --experimentalMemory=true)',
-        category: 'Memory',
-        args: {
-            filePath: {
-                name: 'filePath',
-                type: 'string',
-                description: 'A path to a .heapsnapshot file to read.',
-                required: true,
-            },
-        },
-    },
     navigate_page: {
         description: 'Go to a URL, or back, forward, or reload. Use project URL if not specified otherwise.',
         category: 'Navigation automation',
@@ -732,7 +738,7 @@ export const commands = {
             },
         },
     },
-    take_memory_snapshot: {
+    take_heapsnapshot: {
         description: 'Capture a heap snapshot of the currently selected page. Use to analyze the memory distribution of JavaScript objects and debug memory leaks.',
         category: 'Memory',
         args: {

package/build/src/bin/chrome-devtools-mcp-main.js

@@ -5,6 +5,7 @@
  */
 import '../polyfill.js';
 import process from 'node:process';
+import { closeBrowser } from '../browser.js';
 import { createMcpServer, logDisclaimers } from '../index.js';
 import { logger, saveLogsToFile } from '../logger.js';
 import { ClearcutLogger } from '../telemetry/ClearcutLogger.js';
@@ -21,6 +22,43 @@ if (process.env['CHROME_DEVTOOLS_MCP_CRASH_ON_UNCAUGHT'] !== 'true') {
         logger('Unhandled promise rejection', promise, reason);
     });
 }
+// Shutdown on stdin EOF (stdio MCP convention — the client closes the
+// transport to signal exit) and on standard termination signals. Without
+// this, an active Chrome subprocess keeps the Node event loop ref'd after
+// stdin closes and the server hangs until something else kills it.
+let shuttingDown = false;
+async function shutdown(reason) {
+    if (shuttingDown) {
+        return;
+    }
+    shuttingDown = true;
+    logger(`Shutting down (${reason})`);
+    // Backstop in case browser teardown hangs (e.g. unresponsive Chrome,
+    // slow beforeunload handlers, many tabs). Exits 0 because we still
+    // honored the shutdown request; the log line preserves observability.
+    // Unref'd so it doesn't keep the loop alive on the clean path.
+    setTimeout(() => {
+        logger('Shutdown timeout exceeded, forcing exit');
+        process.exit(0);
+    }, 10000).unref();
+    await closeBrowser();
+    process.exit(0);
+}
+process.stdin.on('end', () => {
+    void shutdown('stdin end');
+});
+process.stdin.on('close', () => {
+    void shutdown('stdin close');
+});
+process.on('SIGTERM', () => {
+    void shutdown('SIGTERM');
+});
+process.on('SIGINT', () => {
+    void shutdown('SIGINT');
+});
+process.on('SIGHUP', () => {
+    void shutdown('SIGHUP');
+});
 logger(`Starting Chrome DevTools MCP Server v${VERSION}`);
 const { server } = await createMcpServer(args, {
     logFile,

package/build/src/browser.js

@@ -10,6 +10,7 @@ import path from 'node:path';
 import { logger } from './logger.js';
 import { puppeteer } from './third_party/index.js';
 let browser;
+let browserMode;
 function makeTargetFilter(enableExtensions = false) {
     const ignoredPrefixes = new Set(['chrome://', 'chrome-untrusted://']);
     if (!enableExtensions) {
@@ -95,7 +96,12 @@ export async function ensureBrowserConnected(options) {
     }
     logger('Connecting Puppeteer to ', JSON.stringify(connectOptions));
     try {
-        browser = await puppeteer.connect(connectOptions);
+        // Assign mode before browser so a concurrent closeBrowser() never sees
+        // `browser` set with `browserMode` still undefined (would fall through
+        // to the disconnect() path and orphan a launched Chrome).
+        const connected = await puppeteer.connect(connectOptions);
+        browserMode = 'connected';
+        browser = connected;
     }
     catch (err) {
         throw new Error(`Could not connect to Chrome. ${autoConnect ? `Check if Chrome is running and remote debugging is enabled by going to chrome://inspect/#remote-debugging.` : `Check if Chrome is running.`}`, {
@@ -198,7 +204,35 @@ export async function ensureBrowserLaunched(options) {
     if (browser?.connected) {
         return browser;
     }
-    browser = await launch(options);
+    // Assign mode before browser; see the connect path above for rationale.
+    const launched = await launch(options);
+    browserMode = 'launched';
+    browser = launched;
     return browser;
 }
+/**
+ * Shutdown hook for the active browser. Closes a launched browser (so the
+ * Chrome subprocess is reaped) or disconnects from an attached browser (so
+ * the user's Chrome instance stays alive). No-op if no browser is active or
+ * the connection has already been dropped. Called from the server entrypoint
+ * on stdin EOF / SIGTERM / SIGINT.
+ */
+export async function closeBrowser() {
+    const b = browser;
+    const mode = browserMode;
+    browser = undefined;
+    browserMode = undefined;
+    if (!b || !b.connected) {
+        return;
+    }
+    if (mode === 'launched') {
+        await b.close().catch(err => {
+            logger('Failed to close browser', err);
+        });
+        return;
+    }
+    await b.disconnect().catch(err => {
+        logger('Failed to disconnect from browser', err);
+    });
+}
 //# sourceMappingURL=browser.js.map