brave-mcp 1.10.1 → 1.12.0

package/README.md

@@ -62,7 +62,7 @@ When the agent connects, Brave asks for permission. Click **Allow**.
 
 Use [Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp) when your target browser is Chrome. Use `brave-mcp` when your target browser is Brave and you want Brave-native discovery, profiles, channels, naming, and privacy defaults without giving up upstream features.
 
-## [Tool reference](./docs/tool-reference.md) | [Changelog](./CHANGELOG.md) | [Contributing](./CONTRIBUTING.md) | [Troubleshooting](./docs/troubleshooting.md) | [Design principles](./docs/design-principles.md)
+## [Tool reference](./docs/tool-reference.md) | [CLI](./docs/cli.md) | [Skills](#skills) | [Changelog](./CHANGELOG.md) | [Contributing](./CONTRIBUTING.md) | [Troubleshooting](./docs/troubleshooting.md) | [Design principles](./docs/design-principles.md)
 
 ## Key features
 
@@ -163,6 +163,70 @@ Brave asks you to allow the connection. After you click **Allow**, your MCP clie
 > [!NOTE]
 > The MCP server connects to Brave only when the MCP client first uses a tool that needs a browser, not when the client starts. Without `--autoConnect`, that is when the server launches its own Brave.
 
+## CLI
+
+The package also includes the `brave-devtools` CLI. Use it to control the browser from your terminal without MCP:
+
+```sh
+npm i brave-mcp@latest -g
+brave-devtools navigate_page 1 --url "https://brave.com"
+brave-devtools take_screenshot 1 --filePath screenshot.png
+brave-devtools stop
+```
+
+See the [CLI guide][cli] for all commands and options.
+
+## Skills
+
+The package includes [skills](./skills) that teach your agent how to use Brave DevTools:
+
+| Skill                                                     | Use it to                                      |
+| --------------------------------------------------------- | ---------------------------------------------- |
+| [`brave-devtools`](./skills/brave-devtools)               | Debug and automate pages with the MCP tools.   |
+| [`brave-devtools-cli`](./skills/brave-devtools-cli)       | Run the CLI and write shell scripts with it.   |
+| [`a11y-debugging`](./skills/a11y-debugging)               | Audit and fix accessibility issues.            |
+| [`cookie-debugging`](./skills/cookie-debugging)           | Debug cookies, sessions, and authentication.   |
+| [`debug-optimize-lcp`](./skills/debug-optimize-lcp)       | Debug and improve Largest Contentful Paint.    |
+| [`memory-leak-debugging`](./skills/memory-leak-debugging) | Find and fix memory leaks.                     |
+| [`troubleshooting`](./skills/troubleshooting)             | Fix connection problems between MCP and Brave. |
+
+### Install skills as a plugin
+
+A plugin installs the MCP server and all skills, including the CLI skill:
+
+- **Claude Code:** Run `/plugin marketplace add triuzzi/brave-devtools-mcp`, then `/plugin install brave-devtools-mcp@brave-devtools-plugins`.
+- **Copilot / VS Code:** Run **Chat: Install Plugin From Source** and enter `triuzzi/brave-devtools-mcp`.
+- **Gemini CLI:** Run `gemini extensions install --auto-update https://github.com/triuzzi/brave-devtools-mcp`.
+
+See the [Client Configurations Guide][client-configurations-guide] for more information.
+
+### Install skills manually
+
+If your agent does not support plugins, copy the skill folders into the skills directory of your agent. The npm package contains the skills:
+
+```sh
+npm i brave-mcp@latest -g
+# Example for Claude Code. Use the skills directory of your agent.
+mkdir -p ~/.claude/skills
+cp -R "$(npm root -g)/brave-mcp/skills/brave-devtools-cli" ~/.claude/skills/
+```
+
+> [!IMPORTANT]
+> The `brave-devtools-cli` skill requires the CLI. Install the package globally before you use the skill.
+
+### Keep skills up to date
+
+Skills describe the tools of a specific version. Update the skills each time you update the MCP server or the CLI. Outdated skills can tell your agent to use tools or parameters that changed.
+
+- **Plugins:** Use the update command of the plugin manager of your agent. The Gemini CLI command above enables automatic updates with `--auto-update`.
+- **Manual installs:** Update the package, then copy the skill folders again:
+
+```sh
+npm i brave-mcp@latest -g
+mkdir -p ~/.claude/skills
+cp -R "$(npm root -g)/brave-mcp/skills/brave-devtools-cli" ~/.claude/skills/
+```
+
 ## Tools
 
 If you run into any issues, checkout our [troubleshooting guide][troubleshooting].
@@ -172,6 +236,8 @@ See the full [Tool reference][tool-reference] for a complete list of all support
 
 Find the complete list of server parameters (e.g., `--headless`, `--isolated`, `--slim`) and how to configure WebSocket connections in the [Configuration Guide][configuration-guide].
 
+For basic browser tasks only, the `--slim` flag exposes a reduced set of tools. See the [Slim tool reference](./docs/slim-tool-reference.md).
+
 ## Advanced usage
 
 For advanced features such as handling concurrent sessions, persistent user data directories, connecting to a running Brave instance instead of starting a new one, or debugging on Android, see our [Advanced Usage Guide][advanced-usage-guide].
@@ -187,6 +253,8 @@ If you are developing agentic tooling and want to provide an integrated browser
 For a reference implementation, see the [Gemini CLI browser agent documentation](https://geminicli.com/docs/core/subagents/#browser-agent).
 
 [advanced-usage-guide]: ./docs/advanced-usage.md
+[cli]: ./docs/cli.md
+[skills]: #skills
 [client-configurations-guide]: ./docs/client-configurations.md
 [configuration-guide]: ./docs/configuration.md
 [tool-reference]: ./docs/tool-reference.md

package/{build → out/Default/gen}/src/BrowserManager.js

@@ -60,20 +60,28 @@ import { execSync } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { Mutex, puppeteer } from './third_party/index.js';
-import { logger, puppeteerLogger } from './utils/logger.js';
+import { Mutex, puppeteer, } from './third_party/index.js';
+import { logger, puppeteerLogger, redactConnectOptionsForLogging, } from './utils/logger.js';
 import { isAllowedUrl } from './utils/url.js';
+// Node runs a timer whose delay exceeds 2^31-1 ms after 1 ms instead, which
+// would make every CDP call and tool call time out at once.
+const MAXIMUM_TIMER_DELAY_MILLISECONDS = 2_147_483_647;
+export function parseProtocolTimeoutMilliseconds(rawValue) {
+    const timeoutMilliseconds = Number(rawValue ?? '600000');
+    if (!Number.isSafeInteger(timeoutMilliseconds) ||
+        timeoutMilliseconds <= 0 ||
+        timeoutMilliseconds > MAXIMUM_TIMER_DELAY_MILLISECONDS) {
+        throw new Error(`BRAVE_DEVTOOLS_PROTOCOL_TIMEOUT_MS must be a positive integer no greater than ${MAXIMUM_TIMER_DELAY_MILLISECONDS}.`);
+    }
+    return timeoutMilliseconds;
+}
 // Heavy pages (e.g. Studio module dev bundles >100MB) cannot ack
 // `Network.enable` and other auto-attached domain calls within
 // puppeteer's default 180s. Once that fires, the CDP connection is
 // marked dead and every subsequent call throws — only daemon restart
 // recovers. Bumping the ceiling to 10min covers realistic loads;
 // override via env for power users.
-export const PROTOCOL_TIMEOUT_MILLISECONDS = Number(process.env.BRAVE_DEVTOOLS_PROTOCOL_TIMEOUT_MS ?? '600000');
-if (!Number.isSafeInteger(PROTOCOL_TIMEOUT_MILLISECONDS) ||
-    PROTOCOL_TIMEOUT_MILLISECONDS <= 0) {
-    throw new Error('BRAVE_DEVTOOLS_PROTOCOL_TIMEOUT_MS must be a positive integer.');
-}
+export const PROTOCOL_TIMEOUT_MILLISECONDS = parseProtocolTimeoutMilliseconds(process.env.BRAVE_DEVTOOLS_PROTOCOL_TIMEOUT_MS);
 export function resolveBraveExecutablePath(channel = 'release') {
     const environmentPath = process.env['BRAVE_PATH'];
     if (environmentPath) {
@@ -169,11 +177,11 @@ export class BrowserManager {
     #initPromise;
     #mutex = new Mutex();
     #closingCount = 0;
-    #serverArgs;
+    #config;
     #options;
     #browserAttempt = new BrowserAttempt();
-    constructor(serverArgs, options = {}) {
-        this.#serverArgs = serverArgs;
+    constructor(config, options = {}) {
+        this.#config = config;
         this.#options = options;
     }
     static makeTargetFilter(enableExtensions = false) {
@@ -255,7 +263,7 @@ export class BrowserManager {
             // a call silently adopt the freshly-rotated token as its own baseline
             // once the lock frees up, defeating the abandonment check entirely.
             const attempt = this.#browserAttempt;
-            const _guard = __addDisposableResource(env_1, await this.#mutex.acquire(), false);
+            const guard = __addDisposableResource(env_1, await this.#mutex.acquire(), false);
             if (this.#closingCount > 0) {
                 throw new Error('Browser was closed while initializing.');
             }
@@ -300,38 +308,40 @@ export class BrowserManager {
      * McpContext initialization built on it — if ensureBrowser() already
      * resolved and it's that later step hanging (e.g. a dead CDP transport),
      * the token rotation alone does nothing, since #browser is already
-     * cached. Safe to forget unconditionally here: the tool mutex serializes
-     * every call, so there's no concurrent caller to disrupt.
+     * cached. Safe to forget unconditionally here: a tool call that already
+     * received a Browser keeps using it, so forgetting the cached value only
+     * makes the next ensureBrowser() reconnect.
      */
     abandonPendingAttempt() {
         this.#browserAttempt = new BrowserAttempt();
         this.#initPromise = undefined;
-        if (this.#browser) {
-            this.forget(this.#browser);
-        }
+        this.#forgetCurrentBrowser();
     }
     async #initBrowser() {
-        if (this.#serverArgs.browserUrl ||
-            this.#serverArgs.wsEndpoint ||
-            this.#serverArgs.autoConnect) {
+        if (this.#config.resolved.browserUrl ||
+            this.#config.resolved.wsEndpoint ||
+            this.#config.resolved.autoConnect) {
             return await this.#connect();
         }
         return await this.#launch();
     }
     async #launch() {
-        const { channel, headless, isolated = false, categoryExtensions: enableExtensions, viaCli, viewport, acceptInsecureCerts, experimentalDevtools: devtools = false, blockedUrlPattern: blocklist, allowedUrlPattern: allowlist, ignoreDefaultBraveArg, proxyServer, } = this.#serverArgs;
+        const { channel, headless, isolated = false, categoryExtensions: enableExtensions, viaCli, viewport, acceptInsecureCerts, experimentalDevtools: devtools = false, blockedUrlPattern: blocklist, allowedUrlPattern: allowlist, ignoreDefaultBraveArg, proxyServer, } = this.#config.resolved;
         const profileDirName = channel && channel !== 'release'
             ? `brave-profile-${channel}`
             : 'brave-profile';
-        const executablePath = this.#serverArgs.executablePath ?? resolveBraveExecutablePath(channel);
-        let userDataDir = this.#serverArgs.userDataDir;
+        const executablePath = this.#config.resolved.executablePath ??
+            resolveBraveExecutablePath(channel);
+        let userDataDir = this.#config.resolved.userDataDir;
         if (!isolated && !userDataDir) {
             userDataDir = path.join(os.homedir(), '.cache', viaCli ? 'brave-devtools-mcp-cli' : 'brave-devtools-mcp', profileDirName);
             await fs.promises.mkdir(userDataDir, {
                 recursive: true,
             });
         }
-        const args = [...(this.#serverArgs.braveArg ?? [])];
+        const args = [
+            ...(this.#config.resolved.braveArg ?? []),
+        ];
         if (proxyServer) {
             args.push(`--proxy-server=${proxyServer}`);
         }
@@ -364,6 +374,12 @@ export class BrowserManager {
                 blocklist,
                 allowlist,
                 logger: puppeteerLogger,
+                // The entry points own signal handling and call close(), which
+                // closes the browser gracefully. Puppeteer's handlers would SIGKILL
+                // Chrome synchronously on the same signal and win the race.
+                handleSIGINT: false,
+                handleSIGTERM: false,
+                handleSIGHUP: false,
             });
             if (this.#options.logFile) {
                 // FIXME: we are probably subscribing too late to catch startup logs. We
@@ -405,24 +421,31 @@ export class BrowserManager {
         }
     }
     async #connect() {
-        const { browserUrl: browserURL, wsEndpoint, wsHeaders, autoConnect: isAutoConnect, userDataDir, blockedUrlPattern: blocklist, allowedUrlPattern: allowlist, } = this.#serverArgs;
+        const { browserUrl: browserURL, wsEndpoint, wsHeaders, autoConnect: isAutoConnect, userDataDir, blockedUrlPattern: blocklist, allowedUrlPattern: allowlist, categoryExtensions: enableExtensions, } = this.#config.resolved;
         // Important: only pass channel, if autoConnect is true.
-        const channel = isAutoConnect ? this.#serverArgs.channel : undefined;
+        const channel = isAutoConnect ? this.#config.resolved.channel : undefined;
         const connectOptions = {
-            targetFilter: _a.makeTargetFilter(),
+            targetFilter: _a.makeTargetFilter(enableExtensions),
             defaultViewport: null,
             handleDevToolsAsPage: true,
             protocolTimeout: PROTOCOL_TIMEOUT_MILLISECONDS,
             blocklist,
             allowlist,
             logger: puppeteerLogger,
+            // Detects a transport that died without a close frame (e.g. an adb
+            // port-forward torn down mid-call). Puppeteer pings the socket
+            // periodically and terminates it on a missed pong, which rejects the
+            // in-flight CDP calls and fires `disconnected` so #evictIfCurrent()
+            // drops the stale handle. Without this, such a call would hang until
+            // protocolTimeout inside the context queue.
+            wsOptions: {
+                keepAlive: true,
+                headers: wsHeaders,
+            },
         };
         let autoConnect = false;
         if (wsEndpoint) {
             connectOptions.browserWSEndpoint = wsEndpoint;
-            if (wsHeaders) {
-                connectOptions.headers = wsHeaders;
-            }
         }
         else if (browserURL) {
             connectOptions.browserURL = browserURL;
@@ -462,7 +485,7 @@ export class BrowserManager {
         else {
             throw new Error('Either browserURL, wsEndpoint, channel or userDataDir must be provided');
         }
-        logger?.('Connecting Puppeteer to ', JSON.stringify(connectOptions));
+        logger?.('Connecting Puppeteer to ', JSON.stringify(redactConnectOptionsForLogging(connectOptions)));
         try {
             const connected = await puppeteer.connect(connectOptions);
             logger?.('Connected Puppeteer');
@@ -478,32 +501,31 @@ export class BrowserManager {
         }
     }
     /**
-     * Clears the cached browser handle if it still matches `candidate`, so the
-     * next ensureBrowser() call establishes a fresh connection instead of
-     * reusing a handle that looks connected but is actually dead (e.g. its CDP
-     * transport died without ever emitting a `close`/`disconnected` event — as
-     * happens when an adb port-forward is torn down mid-call rather than
-     * closed cleanly).
+     * Drops the cached browser handle so the next ensureBrowser() call
+     * establishes a fresh connection. Only called from abandonPendingAttempt()
+     * when a getContext()-level timeout fires after ensureBrowser() already
+     * resolved, which means the handle looks connected but its CDP
+     * initialization is hanging.
      *
-     * Also actively tears `candidate` down in the background: closes it if it
-     * was launched (so the Brave subprocess doesn't leak), or disconnects if
-     * it was only connected to (so the transport and its listeners don't
-     * leak). This also settles any CDP call still pending against it —
-     * Puppeteer's connection disposal synchronously rejects in-flight
-     * callbacks — instead of leaving a hung call to leak forever.
+     * Also tears the browser down in the background: closes it if it was
+     * launched (so the Brave subprocess doesn't leak), or disconnects if it
+     * was only connected to (so the transport and its listeners don't leak).
+     * Puppeteer's connection disposal rejects any in-flight CDP call, so a hung
+     * call settles instead of leaking forever.
      */
-    forget(candidate) {
-        if (this.#browser !== candidate) {
+    #forgetCurrentBrowser() {
+        const browser = this.#browser;
+        if (!browser) {
             return;
         }
         const mode = this.#browserMode;
         this.#browser = undefined;
         this.#browserMode = undefined;
         if (mode === 'launched') {
-            void this.#closeLaunchedBrowser(candidate);
+            void this.#closeLaunchedBrowser(browser);
         }
         else {
-            void candidate.disconnect().catch(err => {
+            void browser.disconnect().catch(err => {
                 logger?.('Failed to disconnect forgotten browser', err);
             });
         }
@@ -514,9 +536,8 @@ export class BrowserManager {
      * call reconnects proactively rather than only discovering the staleness
      * lazily on the next call's `!this.#browser?.connected` check. No teardown
      * here — the browser is already disconnected/closed, that's why this
-     * fired — so this shares forget()'s identity guard without its cleanup,
-     * making a `disconnected` that fires late on an already-superseded browser
-     * a safe no-op.
+     * fired. The identity guard makes a `disconnected` that fires late on an
+     * already-superseded browser a safe no-op.
      */
     #evictIfCurrent(candidate) {
         if (this.#browser !== candidate) {
@@ -571,7 +592,7 @@ export class BrowserManager {
         try {
             this.#initPromise = undefined;
             this.#closingCount++;
-            const _guard = __addDisposableResource(env_2, await this.#mutex.acquire(), false);
+            const guard = __addDisposableResource(env_2, await this.#mutex.acquire(), false);
             try {
                 await this.#closeBrowser();
             }

package/out/Default/gen/src/LogpointManager.js

@@ -0,0 +1,307 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Script } from 'node:vm';
+import { waitForSourceMaps, } from './devtools/DevtoolsUtils.js';
+import { DevTools } from './third_party/index.js';
+/**
+ * Thrown by {@link LogpointManager.setLogpoints} when some locations could
+ * not be bound. The other logpoints were applied; `logpoints` holds the
+ * resulting state.
+ */
+export class LogpointError extends Error {
+    logpoints;
+    constructor(message, logpoints) {
+        super(message);
+        this.name = 'LogpointError';
+        this.logpoints = logpoints;
+    }
+}
+export const LOGPOINT_FORMAT = '<url>:<lineNumber>[:<columnNumber>] <expression>';
+/**
+ * Parses a logpoint given as `<url>:<lineNumber>[:<columnNumber>] <expression>`.
+ * The url may itself contain colons (for example a port), so the location is
+ * the shortest prefix that ends in one or two numbers followed by whitespace.
+ */
+export function parseLogpoint(text) {
+    const match = /^(\S+?):(\d+)(?::(\d+))?\s+(\S.*)$/s.exec(text.trim());
+    if (!match) {
+        throw new Error(`Invalid logpoint "${text}". Expected the format ${LOGPOINT_FORMAT}, for example "src/app.ts:42 'total', cart.total".`);
+    }
+    const [, url, lineNumber, columnNumber, expression] = match;
+    const logpoint = {
+        url,
+        lineNumber: Number(lineNumber),
+        expression,
+    };
+    if (columnNumber !== undefined) {
+        logpoint.columnNumber = Number(columnNumber);
+    }
+    if (logpoint.lineNumber < 1 || logpoint.columnNumber === 0) {
+        throw new Error(`Invalid logpoint "${text}": line and column numbers are 1-based.`);
+    }
+    return logpoint;
+}
+/**
+ * Checks that the expression parses as `console.log()` arguments. V8 is used
+ * for parsing both here and in the browser, so an expression that is rejected
+ * here would also be rejected as a breakpoint condition. The script is only
+ * compiled, never run.
+ */
+export function validateExpression(expression) {
+    try {
+        new Script(`console.log(${expression})`);
+    }
+    catch (error) {
+        throw new Error(`The logpoint expression \`${expression}\` does not compile: ${error instanceof Error ? error.message : String(error)}. Provide the expression like arguments to console.log(...).`);
+    }
+}
+function toUserCondition(expression) {
+    return expression;
+}
+function isFromSourceMap(uiSourceCode) {
+    return uiSourceCode.contentType().isFromSourceMap();
+}
+function locationKey(url, lineNumber, columnNumber) {
+    return `${url}:${lineNumber}${columnNumber === undefined ? '' : `:${columnNumber}`}`;
+}
+function baseName(url) {
+    return url.slice(url.lastIndexOf('/') + 1).toLowerCase();
+}
+/**
+ * How long to wait for the source maps of the page to load before an original
+ * source URL is reported as unknown. Loads still pending then continue in the
+ * background, so a retry finds the source.
+ */
+const SOURCE_MAP_LOAD_TIMEOUT_MS = 5_000;
+/**
+ * Manages logpoints for a single page on top of the `BreakpointManager` of
+ * the page's DevTools universe.
+ *
+ * A logpoint is a DevTools breakpoint with `isLogpoint` set: its condition
+ * logs the expression and never pauses. The breakpoint manager resolves the
+ * location through source maps, substitutes minified variable names in the
+ * expression and keeps the breakpoint bound across reloads and rebuilt
+ * bundles. This class only maps the tool API (URLs and 1-based positions)
+ * onto workspace source codes.
+ */
+export class LogpointManager {
+    #universe;
+    #target;
+    /**
+     * The breakpoints that are logpoints of this page. The breakpoint manager
+     * keeps one `Breakpoint` per normalized location, so two requested
+     * locations can share one entry.
+     */
+    #records = new Set();
+    constructor(devTools) {
+        this.#universe = devTools.universe;
+        this.#target = devTools.target;
+    }
+    get #debuggerModel() {
+        const model = this.#target.model(DevTools.DebuggerModel);
+        if (!model) {
+            throw new Error('The DevTools debugger model is not available.');
+        }
+        return model;
+    }
+    /**
+     * Makes the given logpoints the complete set of logpoints on the page:
+     * logpoints not in the list are removed, new ones are added and the
+     * expression of an existing logpoint at the same location is replaced.
+     * Expressions and locations are validated before anything is changed.
+     * Throws a {@link LogpointError} when a location has no executable code;
+     * the other logpoints are applied regardless.
+     */
+    async setLogpoints(desired) {
+        for (const options of desired) {
+            validateExpression(options.expression);
+        }
+        const resolved = new Map();
+        for (const options of desired) {
+            const uiSourceCode = await this.#findUISourceCode(options.url);
+            const key = locationKey(uiSourceCode.url(), options.lineNumber, options.columnNumber);
+            // The last entry for a location wins, like setting it twice would.
+            resolved.set(key, { options, uiSourceCode, key });
+        }
+        const kept = new Set();
+        const unbound = [];
+        for (const { options, uiSourceCode, key } of resolved.values()) {
+            const breakpoint = await this.#universe.breakpointManager.setBreakpoint(uiSourceCode, 
+            // The tool API is 1-based like the DevTools UI; the model is 0-based.
+            options.lineNumber - 1, options.columnNumber === undefined
+                ? undefined
+                : options.columnNumber - 1, toUserCondition(options.expression), 
+            /* enabled */ true, 
+            /* isLogpoint */ true, "USER_ACTION" /* DevTools.BreakpointManager.BreakpointOrigin.USER_ACTION */);
+            if (!breakpoint) {
+                unbound.push(key);
+                continue;
+            }
+            // Wait for the breakpoint to be set in the backend so that the result
+            // reports whether the location resolved.
+            await breakpoint.updateBreakpoint();
+            if (!this.#records.has(breakpoint) && !breakpoint.bound()) {
+                await breakpoint.remove(/* keepInStorage */ false);
+                unbound.push(key);
+                continue;
+            }
+            this.#records.add(breakpoint);
+            kept.add(breakpoint);
+        }
+        for (const breakpoint of [...this.#records]) {
+            if (!kept.has(breakpoint)) {
+                this.#records.delete(breakpoint);
+                await breakpoint.remove(/* keepInStorage */ false);
+            }
+        }
+        this.#setLazySourceMapLoading(this.#records.size === 0);
+        const logpoints = this.#currentLogpoints();
+        if (unbound.length) {
+            throw new LogpointError(`No executable code at ${unbound.join(', ')} (for example a comment, type annotation or empty line, or a line not mapped to the generated script). Pick lines containing executable code. The other logpoints were applied.`, logpoints);
+        }
+        return logpoints;
+    }
+    /**
+     * Releases the records. The breakpoints are not removed from the backend:
+     * the universe is being disposed and its session detaches, which removes
+     * them along with the page.
+     */
+    dispose() {
+        this.#records.clear();
+    }
+    #currentLogpoints() {
+        return [...this.#records].map(breakpoint => this.#snapshot(breakpoint));
+    }
+    /**
+     * Reads the current state of a breakpoint, so that the result reflects
+     * the normalized location and the re-binding done by the breakpoint
+     * manager after reloads. The breakpoint manager may have moved a
+     * generated location to its original source, so whether the logpoint is
+     * source-mapped follows from the breakpoint, not from the request.
+     */
+    #snapshot(breakpoint) {
+        const sourceMapped = [...breakpoint.getUiSourceCodes()].some(isFromSourceMap);
+        const modelBreakpoint = breakpoint.modelBreakpoint(this.#debuggerModel);
+        const generatedLocations = [];
+        if (breakpoint.bound()) {
+            for (const position of modelBreakpoint?.currentState ?? []) {
+                generatedLocations.push({
+                    url: position.url,
+                    lineNumber: position.lineNumber + 1,
+                    columnNumber: (position.columnNumber ?? 0) + 1,
+                });
+            }
+        }
+        const columnNumber = breakpoint.columnNumber();
+        return {
+            url: breakpoint.url(),
+            lineNumber: breakpoint.lineNumber() + 1,
+            columnNumber: columnNumber === undefined ? undefined : columnNumber + 1,
+            expression: breakpoint.condition(),
+            sourceMapped,
+            generatedLocations,
+        };
+    }
+    /**
+     * Source maps load lazily by default, so after a reload the original
+     * sources of a rebuilt bundle would not re-appear in the workspace and a
+     * logpoint on an original source file could not be re-bound to the new
+     * generated location. While logpoints exist, source maps are loaded
+     * eagerly instead, like DevTools does with the Sources panel open.
+     */
+    #setLazySourceMapLoading(lazy) {
+        this.#universe.settings
+            .resolve(DevTools.SourceMapManager.lazyLoadingSettingDescriptor)
+            .set(lazy);
+    }
+    /**
+     * Finds the workspace source code for a script or original source URL,
+     * loading source maps if needed. Throws a descriptive error, including
+     * sources with the same file name, when nothing matches.
+     */
+    async #findUISourceCode(url) {
+        // Source maps are loaded lazily in the DevTools universe and original
+        // sources only appear in the workspace once their source map has loaded.
+        let match = this.#matchUISourceCode(url);
+        let timedOut = false;
+        if (match && !isFromSourceMap(match)) {
+            // The script may be a transpiled file served at the URL of its original
+            // source (see #matchUISourceCode); its source map decides.
+            const matchedUrl = match.url();
+            const scripts = this.#debuggerModel
+                .scripts()
+                .filter(script => script.sourceURL === matchedUrl);
+            if (scripts.some(script => script.sourceMapURL)) {
+                const signal = AbortSignal.timeout(SOURCE_MAP_LOAD_TIMEOUT_MS);
+                await waitForSourceMaps(this.#debuggerModel, scripts, signal);
+                match = this.#matchUISourceCode(url);
+                if (signal.aborted && (!match || !isFromSourceMap(match))) {
+                    // Setting the logpoint on the served script would use its line
+                    // numbers instead of those of the original source.
+                    throw new Error(`The source map of ${matchedUrl} was still loading after ${SOURCE_MAP_LOAD_TIMEOUT_MS / 1000} seconds; retry.`);
+                }
+            }
+        }
+        else if (!match) {
+            const signal = AbortSignal.timeout(SOURCE_MAP_LOAD_TIMEOUT_MS);
+            await waitForSourceMaps(this.#debuggerModel, this.#debuggerModel.scripts(), signal);
+            timedOut = signal.aborted;
+            match = this.#matchUISourceCode(url);
+        }
+        if (match) {
+            return match;
+        }
+        const name = baseName(url);
+        const similar = [...this.#pageSourceCodes()]
+            .map(uiSourceCode => uiSourceCode.url())
+            .filter(candidate => baseName(candidate) === name)
+            .slice(0, 5);
+        throw new Error(`No parsed script or original source file matches "${url}". The url must match the URL of a script as served to the browser or an original source file from a source map, exactly or as a path suffix.${timedOut ? ` Some source maps were still loading after ${SOURCE_MAP_LOAD_TIMEOUT_MS / 1000} seconds; retry if the file comes from a source map.` : ''}${similar.length ? ` Sources with the same file name: ${similar.join(', ')}.` : ''}`);
+    }
+    /** The scripts and source-map sources of the page in the workspace. */
+    *#pageSourceCodes() {
+        for (const uiSourceCode of this.#universe.workspace.uiSourceCodes()) {
+            const projectType = uiSourceCode.project().type();
+            // Content scripts of extensions are left out: they are not part of the
+            // page under development and would make path-suffix matches ambiguous.
+            if (projectType === DevTools.Workspace.Workspace.projectTypes.Network) {
+                yield uiSourceCode;
+            }
+        }
+    }
+    /**
+     * Finds the workspace source code for a script or original source URL.
+     * An exact URL match wins; otherwise the URL is matched as a path suffix so
+     * that users can pass "src/app.ts" without knowing the bundler's URL
+     * scheme. An ambiguous suffix match is reported as an error.
+     */
+    #matchUISourceCode(url) {
+        const candidates = new Map();
+        for (const uiSourceCode of this.#pageSourceCodes()) {
+            const candidateUrl = uiSourceCode.url();
+            if (candidateUrl !== url && !candidateUrl.endsWith('/' + url)) {
+                continue;
+            }
+            // Dev servers like Vite serve a transpiled file at the URL of its
+            // original source, with a source map pointing back at that same URL.
+            // The original source then has the line numbers of the file on disk,
+            // so it wins over the script served at the same URL.
+            const existing = candidates.get(candidateUrl);
+            if (!existing || isFromSourceMap(uiSourceCode)) {
+                candidates.set(candidateUrl, uiSourceCode);
+            }
+        }
+        const exact = candidates.get(url);
+        if (exact) {
+            return exact;
+        }
+        if (candidates.size > 1) {
+            throw new Error(`"${url}" matches multiple sources: ${[...candidates.keys()].join(', ')}. Specify a longer path.`);
+        }
+        return candidates.values().next().value ?? null;
+    }
+}
+//# sourceMappingURL=LogpointManager.js.map