@narumitw/pi-chrome-devtools 0.3.0 → 0.4.1

package/README.md

@@ -15,9 +15,13 @@ This package is inspired by [`chrome-devtools-mcp`](https://github.com/ChromeDev
 - Navigates Chrome to a target URL, creating an inspectable page when none exists.
 - Recovers from stale active page selections by falling back to an available page.
 - Evaluates JavaScript in the selected page.
-- Captures PNG screenshots, including optional full-page screenshots.
+- Captures PNG screenshots, including optional full-page screenshots, and saves them to disk.
 - Renders compact tool results that expand/collapse with Pi's default output toggle (`Ctrl+O`).
-- Uses a local Chrome DevTools Protocol endpoint.
+- Reuses an existing Chrome DevTools Protocol endpoint when one is already available.
+- Lazily auto-launches a Chromium-family browser for missing local endpoints, with Chrome,
+  Chromium, Brave, and Edge fallbacks.
+- Uses a dynamic managed DevTools port by default to avoid port conflicts, while preserving
+  explicit endpoint overrides.
 - Retries briefly while Chrome is starting and reports actionable endpoint errors.
 - Shows statusline activity only while Chrome DevTools tools are running.
 - Provides a `/chrome-devtools` menu with quick-start help and tool controls.
@@ -42,9 +46,37 @@ Try this package locally from the repository root:
 pi -e ./extensions/pi-chrome-devtools
 ```
 
-## 🚀 Start Chrome with CDP enabled
+## 🚀 Browser startup
 
-The extension connects to `127.0.0.1:9222` by default.
+The extension first tries the configured endpoint, defaulting to `127.0.0.1:9222`. If that
+local endpoint is unavailable, it lazily launches an extension-owned Chromium-family browser with
+an isolated temp profile and then retries the CDP request. Existing endpoints are reused and are
+not terminated by the extension.
+
+When `PI_CHROME_DEVTOOLS_PORT` is not set, auto-launch uses Chrome's dynamic DevTools port mode
+(`--remote-debugging-port=0`) and reads `DevToolsActivePort` from the temp profile. This avoids
+forcing every Pi session onto port `9222`. If you set `PI_CHROME_DEVTOOLS_PORT` to a valid port
+(`1`-`65535`), the extension uses that explicit port for both attach and auto-launch. Empty or
+invalid port values are ignored and fall back to the default attach-first behavior.
+
+When `PI_CHROME_DEVTOOLS_BROWSER` is set, that executable is the only auto-launch candidate; a
+missing or unusable forced browser reports an error instead of falling back. Without that override,
+browser discovery checks platform-specific Chrome, Chromium, Brave, and Microsoft Edge candidates.
+Disable auto-launch to keep the older manual flow:
+
+```bash
+PI_CHROME_DEVTOOLS_AUTO_LAUNCH=0 pi -e ./extensions/pi-chrome-devtools
+```
+
+Force a browser executable or endpoint if needed:
+
+```bash
+PI_CHROME_DEVTOOLS_BROWSER=/usr/bin/brave-browser pi -e ./extensions/pi-chrome-devtools
+PI_CHROME_DEVTOOLS_HOST=127.0.0.1 PI_CHROME_DEVTOOLS_PORT=9223 pi -e ./extensions/pi-chrome-devtools
+```
+
+Manual launch still works and is required for remote endpoints, opt-out mode, or unsupported WSL
+browser/profile path setups:
 
 ```bash
 google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/pi-chrome-devtools
@@ -58,11 +90,9 @@ On macOS:
   --user-data-dir=/tmp/pi-chrome-devtools
 ```
 
-Override the endpoint if needed:
-
-```bash
-PI_CHROME_DEVTOOLS_HOST=127.0.0.1 PI_CHROME_DEVTOOLS_PORT=9223 pi -e ./extensions/pi-chrome-devtools
-```
+On session shutdown, the extension terminates only browser processes it started itself and
+best-effort removes their temp profiles. It never closes user-started browsers or remote
+endpoints.
 
 ## 🛠️ Pi tools
 
@@ -70,7 +100,34 @@ PI_CHROME_DEVTOOLS_HOST=127.0.0.1 PI_CHROME_DEVTOOLS_PORT=9223 pi -e ./extension
 - `chrome_devtools_select_page` — select the active page for later tool calls.
 - `chrome_devtools_navigate` — navigate a page to a URL; if no page exists, create one first.
 - `chrome_devtools_evaluate` — evaluate JavaScript in the selected page.
-- `chrome_devtools_screenshot` — capture a PNG screenshot.
+- `chrome_devtools_screenshot` — capture a PNG screenshot and save it as a PNG file.
+
+### Screenshot files
+
+`chrome_devtools_screenshot` always saves the captured PNG to disk. If `savePath` is omitted,
+the extension writes a unique temp file such as:
+
+```text
+/tmp/pi-chrome-devtools-screenshot-<uuid>.png
+```
+
+Pass `savePath` to choose the output path:
+
+```js
+chrome_devtools_screenshot({
+  fullPage: true,
+  savePath: "artifacts/homepage.png",
+});
+```
+
+Relative `savePath` values resolve from Pi's current working directory. A single leading `@`
+is stripped to match Pi file-mention paths. Absolute paths are accepted only when they stay
+inside the current working directory or the OS temp directory. Paths containing `..` segments,
+NUL bytes, symlinked parent directories, directories as targets, final symbolic-link targets, or
+other non-regular file targets are rejected. Existing regular files at the target path are
+replaced. The tool result includes the resolved path, byte count, and an inline image block when
+the active model/provider can consume images. If the model cannot inspect the inline image, ask it
+to read the saved path, for example `read({ path: "artifacts/homepage.png" })`.
 
 ## 💬 Command
 
@@ -94,9 +151,10 @@ Direct subcommands are also available:
 ```
 
 - `help` shows command usage.
-- `quickstart` shows the configured CDP endpoint and launch hint.
-- `status` shows runtime tool state, persisted selection, settings file path, and active
-  non-Chrome tool count.
+- `quickstart` shows the configured CDP endpoint, endpoint source, auto-launch mode, browser
+  candidates, last launch attempt, and launch hints.
+- `status` shows runtime tool state, persisted selection, settings file path, endpoint source,
+  launch mode, last launch attempt, and active non-Chrome tool count.
 - `tools` opens a Plan-mode-style selector for choosing individual `chrome_devtools_*` tools.
 - `toggle` is an alias for `tools`.
 - `enable` enables all `chrome_devtools_*` tools for future turns.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-chrome-devtools",
-	"version": "0.3.0",
+	"version": "0.4.1",
 	"description": "Pi extension that exposes Chrome DevTools Protocol tools.",
 	"type": "module",
 	"license": "MIT",

package/src/chrome-devtools.ts

@@ -1,12 +1,16 @@
-import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { spawn, type ChildProcess } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { access, lstat, mkdir, mkdtemp, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { basename, delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import {
 	defineTool,
 	type AgentToolResult,
 	type ExtensionAPI,
 	type ExtensionCommandContext,
 	type ToolRenderResultOptions,
+	withFileMutationQueue,
 } from "@mariozechner/pi-coding-agent";
 import { Type } from "typebox";
 
@@ -16,6 +20,9 @@ const DEFAULT_TIMEOUT_MS = 10_000;
 const DEFAULT_HTTP_TIMEOUT_MS = 1_000;
 const DEFAULT_ENDPOINT_WAIT_MS = 5_000;
 const DEFAULT_ENDPOINT_RETRY_MS = 250;
+const MANAGED_BROWSER_PROFILE_PREFIX = "pi-chrome-devtools-profile-";
+const DEVTOOLS_ACTIVE_PORT_FILE = "DevToolsActivePort";
+const BROWSER_SHUTDOWN_WAIT_MS = 1_500;
 const STATUS_KEY = "chrome-devtools";
 const SETTINGS_FILE = join(
 	process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent"),
@@ -61,6 +68,7 @@ type CommandAction =
 	| "disable";
 type CommandContext = ExtensionCommandContext;
 type ToolSelectorAction = "enableAll" | "disableAll" | "done";
+type BrowserCandidateSource = "env" | "path" | "wellKnownPath";
 type ToolSelectorRow =
 	| { kind: "tool"; toolName: ChromeDevToolsToolName }
 	| { kind: "action"; action: ToolSelectorAction; label: string };
@@ -90,7 +98,32 @@ interface DevToolsPage {
 interface ChromeDevToolsState {
 	host: string;
 	port: number;
+	configuredPort: number;
+	hostConfigured: boolean;
+	portConfigured: boolean;
+	autoLaunchEnabled: boolean;
+	browserExecutable?: string;
 	activePageId?: string;
+	managedBrowser?: ManagedBrowser;
+	launchPromise?: Promise<void>;
+	lastLaunchAttempt?: BrowserLaunchAttempt;
+	shuttingDown: boolean;
+}
+
+interface ManagedBrowser {
+	process: ChildProcess;
+	userDataDir: string;
+	port?: number;
+	exited: boolean;
+	ready: boolean;
+}
+
+interface BrowserLaunchAttempt {
+	candidateLabels: string[];
+	mode: "dynamic-port" | "explicit-port";
+	selectedCandidate?: string;
+	userDataDir?: string;
+	lastError?: string;
 }
 
 interface ChromeDevToolsSettings {
@@ -114,9 +147,41 @@ interface CdpResponse<T = unknown> {
 	};
 }
 
+interface ResolvedScreenshotPath {
+	path: string;
+	allowedRoots: string[];
+	isDefault: boolean;
+}
+
+interface ScreenshotSaveResult {
+	savedPath: string;
+	bytes: number;
+	isDefaultPath: boolean;
+}
+
+interface BrowserCandidateDefinition {
+	label: string;
+	executable: string;
+	source: BrowserCandidateSource;
+}
+
+interface BrowserCandidate extends BrowserCandidateDefinition {
+	resolvedExecutable: string;
+}
+
+const configuredHost = process.env.PI_CHROME_DEVTOOLS_HOST ?? DEFAULT_HOST;
+const configuredPortOverride = parseConfiguredPort(process.env.PI_CHROME_DEVTOOLS_PORT);
+const configuredPort = configuredPortOverride ?? DEFAULT_PORT;
+
 const state: ChromeDevToolsState = {
-	host: process.env.PI_CHROME_DEVTOOLS_HOST ?? DEFAULT_HOST,
-	port: Number(process.env.PI_CHROME_DEVTOOLS_PORT ?? DEFAULT_PORT),
+	host: configuredHost,
+	port: configuredPort,
+	configuredPort,
+	hostConfigured: process.env.PI_CHROME_DEVTOOLS_HOST !== undefined,
+	portConfigured: configuredPortOverride !== undefined,
+	autoLaunchEnabled: process.env.PI_CHROME_DEVTOOLS_AUTO_LAUNCH !== "0",
+	browserExecutable: process.env.PI_CHROME_DEVTOOLS_BROWSER,
+	shuttingDown: false,
 };
 
 const listPagesTool = defineTool({
@@ -234,13 +299,20 @@ const screenshotTool = defineTool({
 		fullPage: Type.Optional(
 			Type.Boolean({ description: "Capture the full document, not just the viewport." }),
 		),
+		savePath: Type.Optional(
+			Type.String({
+				description:
+					"Screenshot is always saved as a PNG file. Optional output path; omitted defaults to a unique temp file. Relative paths resolve from the current working directory. A single leading @ is stripped to match Pi file-mention paths. Existing regular files are replaced.",
+			}),
+		),
 	}),
 	renderCall: renderToolCall("screenshot"),
 	renderResult: renderScreenshotResult,
-	async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+	async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 		return withStatus(ctx, "🌐 screenshot", async () => {
 			const page = await resolvePage(params.pageId);
 			const result = await withCdp(page, async (client) => {
+				throwIfAborted(signal);
 				await client.send("Page.enable");
 
 				if (!params.fullPage) {
@@ -251,6 +323,7 @@ const screenshotTool = defineTool({
 					contentSize: { x: number; y: number; width: number; height: number };
 				}>("Page.getLayoutMetrics");
 
+				throwIfAborted(signal);
 				return client.send<{ data: string }>("Page.captureScreenshot", {
 					captureBeyondViewport: true,
 					format: "png",
@@ -265,12 +338,21 @@ const screenshotTool = defineTool({
 			});
 
 			state.activePageId = page.id;
+			const savedScreenshot = await saveScreenshot(result.data, params.savePath, ctx.cwd, signal);
 			return {
 				content: [
-					{ type: "text", text: `Captured PNG screenshot from ${page.title || page.url}` },
+					{
+						type: "text",
+						text: formatScreenshotText(page, savedScreenshot),
+					},
 					{ type: "image", data: result.data, mimeType: "image/png" },
 				],
-				details: { page: formatPage(page), bytes: Buffer.byteLength(result.data, "base64") },
+				details: {
+					page: formatPage(page),
+					bytes: savedScreenshot.bytes,
+					savedPath: savedScreenshot.savedPath,
+					isDefaultPath: savedScreenshot.isDefaultPath,
+				},
 			};
 		});
 	},
@@ -292,6 +374,7 @@ export default function chromeDevtools(pi: ExtensionAPI) {
 	});
 
 	pi.on("session_start", async (_event, ctx) => {
+		state.shuttingDown = false;
 		ctx.ui.setStatus(STATUS_KEY, undefined);
 		const settings = await loadSettings();
 		if (settings.kind === "loaded") {
@@ -303,8 +386,9 @@ export default function chromeDevtools(pi: ExtensionAPI) {
 		}
 	});
 
-	pi.on("session_shutdown", (_event, ctx) => {
+	pi.on("session_shutdown", async (_event, ctx) => {
 		ctx.ui.setStatus(STATUS_KEY, undefined);
+		await shutdownManagedBrowser(undefined, { cancelLaunch: true });
 	});
 }
 
@@ -589,13 +673,20 @@ async function buildToolStatusMessage(pi: ExtensionAPI) {
 		`Settings file: ${SETTINGS_FILE}`,
 		`Other active tools preserved: ${summary.activeNonChromeToolCount}`,
 		`Endpoint: ${devToolsEndpoint()}`,
+		`Endpoint source: ${endpointSourceLabel()}`,
+		`Launch mode: ${launchModeLabel()}`,
+		...launchAttemptLines(),
 	].join("\n");
 }
 
 function buildQuickstartMessage() {
 	return [
 		`Chrome DevTools endpoint: ${devToolsEndpoint()}`,
+		`Endpoint source: ${endpointSourceLabel()}`,
+		`Launch mode: ${launchModeLabel()}`,
 		launchHint(),
+		browserCandidateHint(),
+		...launchAttemptLines(),
 		endpointConfigHint(),
 	].join("\n");
 }
@@ -752,11 +843,23 @@ function unique<T>(values: T[]) {
 	return Array.from(new Set(values));
 }
 
+function parseConfiguredPort(value: string | undefined) {
+	if (value === undefined) return undefined;
+	const trimmedValue = value.trim();
+	if (!/^\d+$/.test(trimmedValue)) return undefined;
+
+	const port = Number(trimmedValue);
+	if (!Number.isInteger(port) || port < 1 || port > 65_535) return undefined;
+	return port;
+}
+
 async function listPages(options: { waitMs?: number } = {}) {
+	const waitMs = options.waitMs ?? DEFAULT_ENDPOINT_WAIT_MS;
+	await ensureDevToolsEndpoint(waitMs);
 	return withEndpointRetry(async () => {
 		const pages = await fetchDevToolsJson<DevToolsPage[]>("/json/list");
 		return pages.filter((page) => page.type === "page" && page.webSocketDebuggerUrl);
-	}, options.waitMs ?? DEFAULT_ENDPOINT_WAIT_MS);
+	}, waitMs);
 }
 
 async function getPage(pageId: string) {
@@ -817,10 +920,16 @@ function requirePage(pageId: string, pages: DevToolsPage[]) {
 	);
 }
 
-async function createPage(url: string) {
-	const page = await fetchDevToolsJson<DevToolsPage>(`/json/new?${encodeURIComponent(url)}`, {
-		method: "PUT",
-	});
+async function createPage(url: string, options: { waitMs?: number } = {}) {
+	const waitMs = options.waitMs ?? DEFAULT_ENDPOINT_WAIT_MS;
+	await ensureDevToolsEndpoint(waitMs);
+	const page = await withEndpointRetry(
+		() =>
+			fetchDevToolsJson<DevToolsPage>(`/json/new?${encodeURIComponent(url)}`, {
+				method: "PUT",
+			}),
+		waitMs,
+	);
 	if (page.type !== "page" || !page.webSocketDebuggerUrl) {
 		throw new Error("Chrome DevTools created a target that is not an inspectable page.");
 	}
@@ -828,6 +937,268 @@ async function createPage(url: string) {
 	return page;
 }
 
+async function ensureDevToolsEndpoint(waitMs = DEFAULT_ENDPOINT_WAIT_MS) {
+	if (canAutoLaunchBrowser()) {
+		try {
+			await withEndpointRetry(() => fetchDevToolsJson<unknown>("/json/version"), waitMs);
+			return;
+		} catch (error) {
+			if (shouldAutoLaunchAfterEndpointError(error)) {
+				await ensureManagedBrowserLaunched(waitMs);
+				return;
+			}
+			throw error;
+		}
+	}
+
+	try {
+		await fetchDevToolsJson<unknown>("/json/version");
+	} catch (error) {
+		if (isRetryableEndpointError(error)) return;
+		throw error;
+	}
+}
+
+async function ensureManagedBrowserLaunched(waitMs: number) {
+	if (state.launchPromise) return state.launchPromise;
+	if (state.managedBrowser && !state.managedBrowser.exited && state.managedBrowser.ready) return;
+	if (state.managedBrowser) {
+		await shutdownManagedBrowser(state.managedBrowser, { awaitLaunch: false });
+	}
+	throwIfBrowserLaunchCancelled();
+
+	state.launchPromise = launchManagedBrowser(waitMs).finally(() => {
+		state.launchPromise = undefined;
+	});
+	return state.launchPromise;
+}
+
+async function launchManagedBrowser(waitMs: number) {
+	throwIfBrowserLaunchCancelled();
+	const candidateDefinitions = browserCandidateDefinitions();
+	const candidates = await resolveBrowserCandidates(candidateDefinitions);
+	throwIfBrowserLaunchCancelled();
+	state.lastLaunchAttempt = {
+		candidateLabels: candidateDefinitions.map(formatBrowserCandidateDefinition),
+		mode: state.portConfigured ? "explicit-port" : "dynamic-port",
+	};
+
+	if (candidates.length === 0) {
+		throw new DevToolsEndpointError(noBrowserCandidateMessage(candidateDefinitions));
+	}
+
+	let lastError: unknown;
+	for (const candidate of candidates) {
+		throwIfBrowserLaunchCancelled();
+		try {
+			await launchBrowserCandidate(candidate, waitMs);
+			state.lastLaunchAttempt = {
+				...state.lastLaunchAttempt,
+				selectedCandidate: formatBrowserCandidate(candidate),
+				userDataDir: state.managedBrowser?.userDataDir,
+			};
+			return;
+		} catch (error) {
+			lastError = error;
+			state.lastLaunchAttempt = {
+				...state.lastLaunchAttempt,
+				lastError: formatError(error),
+			};
+		}
+	}
+
+	throw new DevToolsEndpointError(
+		[
+			"Unable to auto-launch a Chromium-family browser for Chrome DevTools.",
+			`Tried: ${candidates.map(formatBrowserCandidate).join(", ")}`,
+			lastError ? `Last error: ${formatError(lastError)}` : undefined,
+			launchHint(),
+			endpointConfigHint(),
+		]
+			.filter(Boolean)
+			.join("\n"),
+	);
+}
+
+async function launchBrowserCandidate(candidate: BrowserCandidate, waitMs: number) {
+	throwIfBrowserLaunchCancelled();
+	const userDataDir = await mkdtemp(join(tmpdir(), MANAGED_BROWSER_PROFILE_PREFIX));
+	let managedBrowser: ManagedBrowser | undefined;
+	try {
+		const portArgument = state.portConfigured ? String(state.port) : "0";
+		const args = [
+			`--remote-debugging-port=${portArgument}`,
+			`--user-data-dir=${userDataDir}`,
+			"--no-first-run",
+			"--no-default-browser-check",
+			"about:blank",
+		];
+		throwIfBrowserLaunchCancelled();
+		const child = spawn(candidate.resolvedExecutable, args, { shell: false, stdio: "ignore" });
+		const launchedBrowser: ManagedBrowser = { process: child, userDataDir, exited: false, ready: false };
+		managedBrowser = launchedBrowser;
+		state.managedBrowser = launchedBrowser;
+
+		child.once("exit", () => {
+			launchedBrowser.exited = true;
+			launchedBrowser.ready = false;
+			if (!state.portConfigured && launchedBrowser.port === state.port) {
+				state.port = state.configuredPort;
+			}
+		});
+
+		await waitForBrowserSpawn(child);
+		if (state.portConfigured) {
+			launchedBrowser.port = state.port;
+		} else {
+			launchedBrowser.port = await readManagedBrowserPort(userDataDir, launchedBrowser, waitMs);
+			state.port = launchedBrowser.port;
+		}
+		await waitForDevToolsEndpoint(waitMs, launchedBrowser);
+		launchedBrowser.ready = true;
+	} catch (error) {
+		if (managedBrowser) await shutdownManagedBrowser(managedBrowser, { awaitLaunch: false });
+		else await rm(userDataDir, { recursive: true, force: true }).catch(() => undefined);
+		throw error;
+	}
+}
+
+function waitForBrowserSpawn(child: ChildProcess) {
+	return new Promise<void>((resolve, reject) => {
+		let settled = false;
+		const settle = (callback: () => void) => {
+			if (settled) return;
+			settled = true;
+			child.off("error", onError);
+			child.off("spawn", onSpawn);
+			callback();
+		};
+		const onError = (error: Error) => settle(() => reject(error));
+		const onSpawn = () => settle(resolve);
+		child.once("error", onError);
+		child.once("spawn", onSpawn);
+	});
+}
+
+async function readManagedBrowserPort(
+	userDataDir: string,
+	managedBrowser: ManagedBrowser,
+	waitMs: number,
+) {
+	const activePortFile = join(userDataDir, DEVTOOLS_ACTIVE_PORT_FILE);
+	const deadline = Date.now() + waitMs;
+	while (true) {
+		throwIfManagedBrowserExited(managedBrowser);
+		const text = await readFile(activePortFile, "utf8").catch((error: unknown) => {
+			if (isNodeError(error) && error.code === "ENOENT") return undefined;
+			throw error;
+		});
+		const portText = text?.split(/\r?\n/, 1)[0]?.trim();
+		const port = Number(portText);
+		if (Number.isInteger(port) && port > 0) return port;
+
+		throwIfBrowserLaunchCancelled();
+		const remainingMs = deadline - Date.now();
+		if (remainingMs <= 0) {
+			throw new DevToolsEndpointError(
+				[
+					"Timed out waiting for auto-launched browser DevToolsActivePort.",
+					`Expected file: ${activePortFile}`,
+					launchHint(),
+				].join("\n"),
+			);
+		}
+		await sleep(Math.min(DEFAULT_ENDPOINT_RETRY_MS, remainingMs));
+	}
+}
+
+async function waitForDevToolsEndpoint(waitMs: number, managedBrowser: ManagedBrowser) {
+	const deadline = Date.now() + waitMs;
+	while (true) {
+		throwIfManagedBrowserExited(managedBrowser);
+		try {
+			await fetchDevToolsJson<unknown>("/json/version");
+			return;
+		} catch (error) {
+			if (!isRetryableEndpointError(error)) throw error;
+		}
+
+		throwIfBrowserLaunchCancelled();
+		const remainingMs = deadline - Date.now();
+		if (remainingMs <= 0) {
+			throw new DevToolsEndpointError(
+				[
+					`Timed out waiting for auto-launched browser at ${devToolsEndpoint()}.`,
+					launchHint(),
+				].join("\n"),
+			);
+		}
+		await sleep(Math.min(DEFAULT_ENDPOINT_RETRY_MS, remainingMs));
+	}
+}
+
+function throwIfManagedBrowserExited(managedBrowser: ManagedBrowser) {
+	if (!managedBrowser.exited) return;
+	throw new DevToolsEndpointError("Auto-launched browser exited before DevTools became available.");
+}
+
+function throwIfBrowserLaunchCancelled() {
+	if (!state.shuttingDown) return;
+	throw new DevToolsEndpointError("Chrome DevTools browser launch cancelled during shutdown.");
+}
+
+async function shutdownManagedBrowser(
+	managedBrowser = state.managedBrowser,
+	options: { awaitLaunch?: boolean; cancelLaunch?: boolean } = {},
+) {
+	if (options.cancelLaunch) state.shuttingDown = true;
+	if (options.awaitLaunch !== false) {
+		await state.launchPromise?.catch(() => undefined);
+		managedBrowser = managedBrowser ?? state.managedBrowser;
+	}
+	if (!managedBrowser) return;
+	if (state.managedBrowser === managedBrowser) state.managedBrowser = undefined;
+
+	if (!managedBrowser.exited) {
+		killManagedBrowserProcess(managedBrowser);
+		await waitForManagedBrowserExit(managedBrowser, BROWSER_SHUTDOWN_WAIT_MS).catch(() => {
+			killManagedBrowserProcess(managedBrowser, "SIGKILL");
+		});
+	}
+	await rm(managedBrowser.userDataDir, { recursive: true, force: true }).catch(() => undefined);
+	if (!state.portConfigured && managedBrowser.port === state.port) state.port = state.configuredPort;
+}
+
+function killManagedBrowserProcess(managedBrowser: ManagedBrowser, signal?: NodeJS.Signals) {
+	try {
+		managedBrowser.process.kill(signal);
+	} catch {
+		// Best-effort shutdown: the browser may have already exited or failed to spawn.
+	}
+}
+
+function waitForManagedBrowserExit(managedBrowser: ManagedBrowser, waitMs: number) {
+	if (managedBrowser.exited) return Promise.resolve();
+	return new Promise<void>((resolve, reject) => {
+		const settle = (callback: () => void) => {
+			clearTimeout(timeout);
+			managedBrowser.process.off("exit", onExitOrClose);
+			managedBrowser.process.off("close", onExitOrClose);
+			callback();
+		};
+		const onExitOrClose = () => {
+			managedBrowser.exited = true;
+			settle(resolve);
+		};
+		const timeout = setTimeout(
+			() => settle(() => reject(new Error("Timed out waiting for browser shutdown."))),
+			waitMs,
+		);
+		managedBrowser.process.once("exit", onExitOrClose);
+		managedBrowser.process.once("close", onExitOrClose);
+	});
+}
+
 async function fetchDevToolsJson<T>(path: string, init?: RequestInit) {
 	const url = `${devToolsEndpoint()}${path}`;
 	let response: Response;
@@ -837,7 +1208,10 @@ async function fetchDevToolsJson<T>(path: string, init?: RequestInit) {
 			signal: AbortSignal.timeout(DEFAULT_HTTP_TIMEOUT_MS),
 		});
 	} catch (error) {
-		throw new DevToolsEndpointError(endpointConnectionErrorMessage(error), { retryable: true });
+		throw new DevToolsEndpointError(endpointConnectionErrorMessage(error), {
+			launchable: true,
+			retryable: true,
+		});
 	}
 
 	if (!response.ok) {
@@ -852,7 +1226,16 @@ async function fetchDevToolsJson<T>(path: string, init?: RequestInit) {
 		);
 	}
 
-	return (await response.json()) as T;
+	try {
+		return (await response.json()) as T;
+	} catch (error) {
+		throw new DevToolsEndpointError(
+			[
+				`Chrome DevTools endpoint ${url} returned invalid JSON: ${formatError(error)}.`,
+				endpointConfigHint(),
+			].join("\n"),
+		);
+	}
 }
 
 async function withEndpointRetry<T>(operation: () => Promise<T>, waitMs: number) {
@@ -875,6 +1258,23 @@ function isRetryableEndpointError(error: unknown) {
 	return error instanceof DevToolsEndpointError && error.retryable;
 }
 
+function isLaunchableEndpointError(error: unknown) {
+	return error instanceof DevToolsEndpointError && error.launchable;
+}
+
+function shouldAutoLaunchAfterEndpointError(error: unknown) {
+	if (!canAutoLaunchBrowser()) return false;
+	if (isLaunchableEndpointError(error)) return true;
+
+	// After the attach-first attempt (including its retry window, when applicable) fails, treat any
+	// DevTools endpoint error on an unpinned port as a conflict we can avoid with a dynamic port.
+	return !state.portConfigured && error instanceof DevToolsEndpointError;
+}
+
+function canAutoLaunchBrowser() {
+	return state.autoLaunchEnabled && isLocalDevToolsHost(state.host);
+}
+
 function endpointConnectionErrorMessage(error: unknown) {
 	const reason = isTimeoutError(error) ? "request timed out" : "connection failed";
 	return [
@@ -889,26 +1289,260 @@ function isTimeoutError(error: unknown) {
 }
 
 function devToolsEndpoint() {
-	return `http://${state.host}:${state.port}`;
+	return `http://${formatHostForUrl(state.host)}:${state.port}`;
+}
+
+function formatHostForUrl(host: string) {
+	if (host.startsWith("[") && host.endsWith("]")) return host;
+	return host.includes(":") ? `[${host}]` : host;
+}
+
+function endpointSourceLabel() {
+	const hostSource = state.hostConfigured ? "PI_CHROME_DEVTOOLS_HOST" : "default host";
+	const portSource = state.portConfigured ? "PI_CHROME_DEVTOOLS_PORT" : "default/dynamic port";
+	return `${hostSource}; ${portSource}`;
+}
+
+function launchModeLabel() {
+	if (!isLocalDevToolsHost(state.host)) return "manual remote endpoint";
+	if (!state.autoLaunchEnabled) return "manual; auto-launch disabled";
+	if (state.managedBrowser && !state.managedBrowser.exited) {
+		return state.portConfigured ? "auto-launched on explicit port" : "auto-launched on dynamic port";
+	}
+	return state.portConfigured ? "attach first; auto-launch explicit port" : "attach first; auto-launch dynamic port";
+}
+
+function launchAttemptLines() {
+	if (!state.lastLaunchAttempt) return [];
+
+	const lines = [`Last launch attempt: ${state.lastLaunchAttempt.mode}`];
+	if (state.lastLaunchAttempt.selectedCandidate) {
+		lines.push(`Launched browser: ${state.lastLaunchAttempt.selectedCandidate}`);
+	} else {
+		lines.push(`Tried browser candidates: ${state.lastLaunchAttempt.candidateLabels.join(", ")}`);
+	}
+	if (state.lastLaunchAttempt.userDataDir) {
+		lines.push(`Managed browser profile: ${state.lastLaunchAttempt.userDataDir}`);
+	}
+	if (state.lastLaunchAttempt.lastError) {
+		lines.push(`Last launch error: ${state.lastLaunchAttempt.lastError}`);
+	}
+	return lines;
 }
 
 function launchHint() {
-	return `Start Chrome with remote debugging enabled: ${chromeLaunchCommand()}`;
+	if (!isLocalDevToolsHost(state.host)) {
+		return `Remote/non-local endpoints are not auto-launched. Start a browser with CDP enabled at ${devToolsEndpoint()}.`;
+	}
+	if (!state.autoLaunchEnabled) {
+		return `Auto-launch is disabled. Start a browser manually: ${chromeLaunchCommand()}`;
+	}
+	const managedMode = state.portConfigured ? `port ${state.port}` : "a dynamic DevTools port";
+	return `If no endpoint is available, Pi will auto-launch a Chromium-family browser with ${managedMode} and an isolated temp profile. Manual command: ${chromeLaunchCommand()}`;
+}
+
+function browserCandidateHint() {
+	return `Browser candidates: ${browserCandidateDefinitions().map((candidate) => candidate.label).join(", ")}`;
 }
 
 function chromeLaunchCommand() {
-	const executable =
-		process.platform === "darwin"
-			? "/Applications/Google\\ Chrome.app/Contents/MacOS/Google\\ Chrome"
-			: process.platform === "win32"
-				? "chrome.exe"
-				: "google-chrome";
-	const dataDir = process.platform === "win32" ? "%TEMP%\\pi-chrome-devtools" : "/tmp/pi-chrome-devtools";
-	return `${executable} --remote-debugging-port=${state.port} --user-data-dir=${dataDir}`;
+	const executable = state.browserExecutable ?? defaultManualBrowserExecutable();
+	const dataDir =
+		process.platform === "win32" ? "%TEMP%\\pi-chrome-devtools" : "/tmp/pi-chrome-devtools";
+	return `${quoteCommandPart(executable)} --remote-debugging-port=${state.port} --user-data-dir=${dataDir}`;
+}
+
+function defaultManualBrowserExecutable() {
+	return process.platform === "darwin"
+		? "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+		: process.platform === "win32"
+			? "chrome.exe"
+			: "google-chrome";
+}
+
+function quoteCommandPart(value: string) {
+	return /\s/.test(value) ? `"${value.replaceAll('"', '\\"')}"` : value;
 }
 
 function endpointConfigHint() {
-	return "Set PI_CHROME_DEVTOOLS_HOST and PI_CHROME_DEVTOOLS_PORT if Chrome uses a different endpoint.";
+	return "Set PI_CHROME_DEVTOOLS_HOST and PI_CHROME_DEVTOOLS_PORT for a manual endpoint, PI_CHROME_DEVTOOLS_BROWSER to choose an executable, or PI_CHROME_DEVTOOLS_AUTO_LAUNCH=0 to disable auto-launch.";
+}
+
+function isLocalDevToolsHost(host: string) {
+	const normalizedHost = host.toLowerCase().replace(/^\[(.*)]$/, "$1");
+	return ["localhost", "127.0.0.1", "::1", "0:0:0:0:0:0:0:1"].includes(normalizedHost);
+}
+
+function browserCandidateDefinitions(): BrowserCandidateDefinition[] {
+	const explicitCandidate = explicitBrowserCandidateDefinition();
+	if (explicitCandidate.length > 0) return explicitCandidate;
+
+	return uniqueBrowserCandidates(platformBrowserCandidateDefinitions());
+}
+
+function explicitBrowserCandidateDefinition(): BrowserCandidateDefinition[] {
+	if (!state.browserExecutable) return [];
+	return [{ label: "PI_CHROME_DEVTOOLS_BROWSER", executable: state.browserExecutable, source: "env" }];
+}
+
+function platformBrowserCandidateDefinitions(): BrowserCandidateDefinition[] {
+	if (process.platform === "darwin") {
+		return [
+			{
+				label: "Google Chrome",
+				executable: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+				source: "wellKnownPath",
+			},
+			{
+				label: "Chromium",
+				executable: "/Applications/Chromium.app/Contents/MacOS/Chromium",
+				source: "wellKnownPath",
+			},
+			{
+				label: "Brave Browser",
+				executable: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
+				source: "wellKnownPath",
+			},
+			{
+				label: "Microsoft Edge",
+				executable: "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+				source: "wellKnownPath",
+			},
+		];
+	}
+
+	if (process.platform === "win32") {
+		return windowsBrowserCandidateDefinitions();
+	}
+
+	return [
+		{ label: "Google Chrome", executable: "google-chrome", source: "path" },
+		{ label: "Google Chrome Stable", executable: "google-chrome-stable", source: "path" },
+		{ label: "Chromium", executable: "chromium", source: "path" },
+		{ label: "Chromium Browser", executable: "chromium-browser", source: "path" },
+		{ label: "Brave Browser", executable: "brave-browser", source: "path" },
+		{ label: "Brave", executable: "brave", source: "path" },
+		{ label: "Microsoft Edge", executable: "microsoft-edge", source: "path" },
+		{ label: "Microsoft Edge Stable", executable: "microsoft-edge-stable", source: "path" },
+	];
+}
+
+function windowsBrowserCandidateDefinitions(): BrowserCandidateDefinition[] {
+	const programFiles = [
+		process.env.PROGRAMFILES,
+		process.env["PROGRAMFILES(X86)"],
+		process.env.LOCALAPPDATA,
+	].filter((value): value is string => typeof value === "string" && value.length > 0);
+	const wellKnownPaths = programFiles.flatMap((root) => [
+		join(root, "Google", "Chrome", "Application", "chrome.exe"),
+		join(root, "Chromium", "Application", "chrome.exe"),
+		join(root, "BraveSoftware", "Brave-Browser", "Application", "brave.exe"),
+		join(root, "Microsoft", "Edge", "Application", "msedge.exe"),
+	]);
+	return [
+		...wellKnownPaths.map((executable) => ({
+			label: browserLabelFromExecutable(executable),
+			executable,
+			source: "wellKnownPath" as const,
+		})),
+		{ label: "Google Chrome", executable: "chrome.exe", source: "path" },
+		{ label: "Chromium", executable: "chromium.exe", source: "path" },
+		{ label: "Brave Browser", executable: "brave.exe", source: "path" },
+		{ label: "Microsoft Edge", executable: "msedge.exe", source: "path" },
+	];
+}
+
+function browserLabelFromExecutable(executable: string) {
+	const normalizedExecutable = normalizePathForComparison(executable);
+	if (normalizedExecutable.includes("brave")) return "Brave Browser";
+	if (normalizedExecutable.includes("edge") || normalizedExecutable.includes("msedge")) {
+		return "Microsoft Edge";
+	}
+	if (normalizedExecutable.includes("chromium")) return "Chromium";
+	return "Google Chrome";
+}
+
+function uniqueBrowserCandidates(candidates: BrowserCandidateDefinition[]) {
+	const seen = new Set<string>();
+	return candidates.filter((candidate) => {
+		const key = normalizePathForComparison(candidate.executable);
+		if (seen.has(key)) return false;
+		seen.add(key);
+		return true;
+	});
+}
+
+async function resolveBrowserCandidates(definitions: BrowserCandidateDefinition[]) {
+	const candidates: BrowserCandidate[] = [];
+	for (const definition of definitions) {
+		const resolvedExecutable = await resolveBrowserExecutable(definition.executable);
+		if (!resolvedExecutable) continue;
+		candidates.push({ ...definition, resolvedExecutable });
+	}
+	return uniqueBrowserCandidatesByResolvedPath(candidates);
+}
+
+function uniqueBrowserCandidatesByResolvedPath(candidates: BrowserCandidate[]) {
+	const seen = new Set<string>();
+	return candidates.filter((candidate) => {
+		const key = normalizePathForComparison(resolve(candidate.resolvedExecutable));
+		if (seen.has(key)) return false;
+		seen.add(key);
+		return true;
+	});
+}
+
+async function resolveBrowserExecutable(executable: string) {
+	if (hasPathSeparator(executable) || isAbsolute(executable)) {
+		const resolvedExecutable = isAbsolute(executable) ? executable : resolve(executable);
+		return (await canAccessExecutable(resolvedExecutable)) ? resolvedExecutable : undefined;
+	}
+
+	for (const directory of executableSearchPath()) {
+		for (const executableName of executableSearchNames(executable)) {
+			const candidate = join(directory, executableName);
+			if (await canAccessExecutable(candidate)) return candidate;
+		}
+	}
+	return undefined;
+}
+
+function hasPathSeparator(path: string) {
+	return path.includes("/") || path.includes("\\");
+}
+
+function executableSearchPath() {
+	return (process.env.PATH ?? "").split(delimiter).filter((part) => part.length > 0);
+}
+
+function executableSearchNames(executable: string) {
+	if (process.platform !== "win32" || /\.[a-z0-9]+$/i.test(executable)) return [executable];
+	return [executable, `${executable}.exe`, `${executable}.cmd`, `${executable}.bat`];
+}
+
+async function canAccessExecutable(path: string) {
+	try {
+		await access(path, process.platform === "win32" ? constants.F_OK : constants.X_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function formatBrowserCandidate(candidate: BrowserCandidate) {
+	return `${candidate.label} (${candidate.resolvedExecutable})`;
+}
+
+function formatBrowserCandidateDefinition(candidate: BrowserCandidateDefinition) {
+	return `${candidate.label} (${candidate.executable})`;
+}
+
+function noBrowserCandidateMessage(candidateDefinitions: BrowserCandidateDefinition[]) {
+	return [
+		"Cannot auto-launch Chrome DevTools because no Chromium-family browser executable was found.",
+		`Tried: ${candidateDefinitions.map(formatBrowserCandidateDefinition).join(", ")}`,
+		endpointConfigHint(),
+	].join("\n");
 }
 
 function formatPageListItem(page: DevToolsPage) {
@@ -921,11 +1555,13 @@ function sleep(ms: number) {
 
 class DevToolsEndpointError extends Error {
 	readonly retryable: boolean;
+	readonly launchable: boolean;
 
-	constructor(message: string, options: { retryable?: boolean } = {}) {
+	constructor(message: string, options: { retryable?: boolean; launchable?: boolean } = {}) {
 		super(message);
 		this.name = "DevToolsEndpointError";
 		this.retryable = options.retryable ?? false;
+		this.launchable = options.launchable ?? false;
 	}
 }
 
@@ -945,6 +1581,233 @@ function textResult(text: string, details: unknown) {
 	};
 }
 
+async function saveScreenshot(
+	base64Png: string,
+	savePath: string | undefined,
+	cwd: string,
+	signal: AbortSignal | undefined,
+): Promise<ScreenshotSaveResult> {
+	const resolvedPath = resolveScreenshotPath(savePath, cwd);
+	const pngBytes = Buffer.from(base64Png, "base64");
+
+	await withFileMutationQueue(resolvedPath.path, async () => {
+		throwIfAborted(signal);
+		await ensureSafeScreenshotParent(resolvedPath);
+		await assertSafeScreenshotTargetPath(resolvedPath);
+		await writeScreenshotFileSafely(resolvedPath, pngBytes, signal);
+	});
+
+	return {
+		savedPath: resolvedPath.path,
+		bytes: pngBytes.byteLength,
+		isDefaultPath: resolvedPath.isDefault,
+	};
+}
+
+function resolveScreenshotPath(savePath: string | undefined, cwd: string): ResolvedScreenshotPath {
+	const cwdRoot = resolve(cwd);
+	const tempRoot = resolve(tmpdir());
+
+	if (savePath === undefined) {
+		return {
+			path: join(tempRoot, `pi-chrome-devtools-screenshot-${randomUUID()}.png`),
+			allowedRoots: [tempRoot],
+			isDefault: true,
+		};
+	}
+
+	const normalizedPath = stripLeadingAtPath(savePath);
+	if (!normalizedPath.trim()) {
+		throw new Error("Screenshot savePath must not be empty.");
+	}
+	if (normalizedPath.includes("\0")) {
+		throw new Error("Screenshot savePath must not contain NUL bytes.");
+	}
+	if (hasParentPathSegment(normalizedPath)) {
+		throw new Error("Screenshot savePath must not contain '..' path segments.");
+	}
+
+	const isAbsolutePath = isAbsolute(normalizedPath);
+	const path = isAbsolutePath ? resolve(normalizedPath) : resolve(cwdRoot, normalizedPath);
+	const allowedRoots = isAbsolutePath ? unique([cwdRoot, tempRoot]) : [cwdRoot];
+	if (!allowedRoots.some((root) => isPathInsideRoot(path, root))) {
+		throw new Error(
+			"Screenshot savePath must be relative to the current working directory, or an absolute path inside the current working directory or OS temp directory.",
+		);
+	}
+
+	return { path, allowedRoots, isDefault: false };
+}
+
+function stripLeadingAtPath(path: string) {
+	return path.startsWith("@") ? path.slice(1) : path;
+}
+
+function hasParentPathSegment(path: string) {
+	return path.split(/[\\/]+/).some((part) => part === "..");
+}
+
+async function ensureSafeScreenshotParent(resolvedPath: ResolvedScreenshotPath) {
+	const parentPath = dirname(resolvedPath.path);
+	const rootPath = selectAllowedRoot(parentPath, resolvedPath.allowedRoots);
+	if (!rootPath) {
+		throw new Error(
+			"Screenshot savePath parent must stay inside the current working directory or OS temp directory.",
+		);
+	}
+
+	const realRootPath = await realpath(rootPath);
+	let currentPath = rootPath;
+	const parentSegments = relative(rootPath, parentPath)
+		.split(/[\\/]+/)
+		.filter((part) => part.length > 0);
+
+	for (const segment of parentSegments) {
+		currentPath = join(currentPath, segment);
+		await ensureSafeDirectorySegment(currentPath, realRootPath);
+	}
+}
+
+function selectAllowedRoot(path: string, roots: readonly string[]) {
+	const matchingRoots = roots.filter((root) => isPathInsideRoot(path, root));
+	matchingRoots.sort(
+		(left, right) =>
+			normalizePathForComparison(resolve(right)).length -
+			normalizePathForComparison(resolve(left)).length,
+	);
+	return matchingRoots[0];
+}
+
+async function ensureSafeDirectorySegment(path: string, realRootPath: string) {
+	const existingDirectory = await lstat(path).catch(async (error: unknown) => {
+		if (!isNodeError(error) || error.code !== "ENOENT") throw error;
+		await mkdir(path).catch((mkdirError: unknown) => {
+			if (!isNodeError(mkdirError) || mkdirError.code !== "EEXIST") throw mkdirError;
+		});
+		return lstat(path);
+	});
+
+	if (existingDirectory.isSymbolicLink()) {
+		throw new Error("Screenshot savePath parent directories must not contain symbolic links.");
+	}
+	if (!existingDirectory.isDirectory()) {
+		throw new Error("Screenshot savePath parent must be a directory.");
+	}
+	await assertPathWithinRealRoot(path, realRootPath);
+}
+
+async function assertSafeScreenshotTargetPath(resolvedPath: ResolvedScreenshotPath) {
+	const existingTarget = await lstat(resolvedPath.path).catch((error: unknown) => {
+		if (isNodeError(error) && error.code === "ENOENT") return undefined;
+		throw error;
+	});
+	if (existingTarget?.isSymbolicLink()) {
+		throw new Error("Screenshot savePath must not point to a symbolic link.");
+	}
+	if (existingTarget?.isDirectory()) {
+		throw new Error("Screenshot savePath must point to a file, not a directory.");
+	}
+	if (existingTarget && !existingTarget.isFile()) {
+		throw new Error("Screenshot savePath may only replace regular files.");
+	}
+
+	const realAllowedRoots = await Promise.all(resolvedPath.allowedRoots.map(realpathOrResolvedPath));
+	const realParent = await realpath(dirname(resolvedPath.path));
+	const realTargetPath = join(realParent, basename(resolvedPath.path));
+	if (!realAllowedRoots.some((root) => isPathInsideRoot(realTargetPath, root))) {
+		throw new Error(
+			"Screenshot savePath resolves outside the current working directory or OS temp directory.",
+		);
+	}
+}
+
+async function assertPathWithinRealRoot(path: string, realRootPath: string) {
+	const realPath = await realpath(path);
+	if (!isPathInsideRoot(realPath, realRootPath)) {
+		throw new Error(
+			"Screenshot savePath parent resolves outside the current working directory or OS temp directory.",
+		);
+	}
+}
+
+async function writeScreenshotFileSafely(
+	resolvedPath: ResolvedScreenshotPath,
+	pngBytes: Buffer,
+	signal: AbortSignal | undefined,
+) {
+	const tempFile = join(
+		dirname(resolvedPath.path),
+		`.${basename(resolvedPath.path)}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`,
+	);
+	try {
+		await writeFile(tempFile, pngBytes, { flag: "wx", signal });
+		throwIfAborted(signal);
+		await replaceScreenshotFile(resolvedPath, tempFile, signal);
+	} catch (error) {
+		await rm(tempFile, { force: true }).catch(() => undefined);
+		throw error;
+	}
+}
+
+async function replaceScreenshotFile(
+	resolvedPath: ResolvedScreenshotPath,
+	tempFile: string,
+	signal: AbortSignal | undefined,
+) {
+	try {
+		await rename(tempFile, resolvedPath.path);
+		return;
+	} catch (error) {
+		if (!shouldRetryRenameAfterRemovingDestination(error)) throw error;
+	}
+
+	// Some Windows filesystems reject renaming over an existing file. Revalidate before
+	// removing the destination so the fallback still refuses directories and symlinks.
+	await assertSafeScreenshotTargetPath(resolvedPath);
+	throwIfAborted(signal);
+	await rm(resolvedPath.path, { force: true });
+	await rename(tempFile, resolvedPath.path);
+}
+
+function shouldRetryRenameAfterRemovingDestination(error: unknown) {
+	return (
+		process.platform === "win32" &&
+		isNodeError(error) &&
+		["EACCES", "EEXIST", "EPERM"].includes(error.code ?? "")
+	);
+}
+
+async function realpathOrResolvedPath(path: string) {
+	return realpath(path).catch(() => resolve(path));
+}
+
+function isPathInsideRoot(path: string, root: string) {
+	const normalizedPath = normalizePathForComparison(resolve(path));
+	const normalizedRoot = normalizePathForComparison(resolve(root));
+	if (normalizedPath === normalizedRoot) return true;
+	const rootWithSeparator = normalizedRoot.endsWith(sep) ? normalizedRoot : `${normalizedRoot}${sep}`;
+	return normalizedPath.startsWith(rootWithSeparator);
+}
+
+function normalizePathForComparison(path: string) {
+	return process.platform === "win32" ? path.toLowerCase() : path;
+}
+
+function throwIfAborted(signal: AbortSignal | undefined) {
+	if (!signal?.aborted) return;
+	throw signal.reason instanceof Error ? signal.reason : new Error("Screenshot capture cancelled.");
+}
+
+function formatScreenshotText(page: DevToolsPage, screenshot: ScreenshotSaveResult) {
+	const pathLabel = screenshot.isDefaultPath ? "Saved to temp file" : "Saved to";
+	return [
+		`Captured PNG screenshot from ${page.title || page.url || page.id}.`,
+		`${pathLabel}: ${screenshot.savedPath}`,
+		`Bytes: ${screenshot.bytes}`,
+		`Use read({ path: ${JSON.stringify(screenshot.savedPath)} }) to inspect the saved screenshot if inline image content is not available.`,
+	].join("\n");
+}
+
 function renderToolCall(action: string) {
 	return () => new PiTextComponent(`Chrome DevTools: ${action}`);
 }
@@ -963,7 +1826,7 @@ function renderScreenshotResult(
 	options: ToolRenderResultOptions,
 	theme: RenderTheme,
 ): RenderComponent {
-	const output = formatCollapsibleOutput(textContent(result), options);
+	const output = formatCollapsibleOutput(screenshotTextContent(result), options);
 	return new PiTextComponent(output.text, theme, output.color);
 }
 
@@ -973,6 +1836,16 @@ function textContent(result: AgentToolResult<unknown>) {
 		.join("\n");
 }
 
+function screenshotTextContent(result: AgentToolResult<unknown>) {
+	const text = textContent(result);
+	if (text.trim()) return text;
+
+	const details = result.details as { savedPath?: unknown; bytes?: unknown } | undefined;
+	if (typeof details?.savedPath !== "string") return text;
+	const bytes = typeof details.bytes === "number" ? ` (${details.bytes} bytes)` : "";
+	return `Saved screenshot to ${details.savedPath}${bytes}`;
+}
+
 function formatCollapsibleOutput(
 	text: string,
 	options: ToolRenderResultOptions,
@@ -984,11 +1857,15 @@ function formatCollapsibleOutput(
 }
 
 class PiTextComponent implements RenderComponent {
-	constructor(
-		private text = "",
-		private readonly theme?: RenderTheme,
-		private readonly color?: string,
-	) {}
+	private text: string;
+	private readonly theme?: RenderTheme;
+	private readonly color?: string;
+
+	constructor(text = "", theme?: RenderTheme, color?: string) {
+		this.text = text;
+		this.theme = theme;
+		this.color = color;
+	}
 
 	setText(text: string) {
 		this.text = text;