arn-browser 0.1.30 → 0.1.32

package/src/utility/playwright/pwLaunch.js

@@ -18,7 +18,8 @@ import { FingerprintGenerator } from "fingerprint-generator";
 
 // Internal Utilities
 import { getMultiloginToken } from "../mlx_token.js";
-import { deleteDirectoryWithRetries } from "../deleteDirectory.js";
+import { deleteDirectoryWithRetries } from "./deleteDirectory.js";
+import { findBrowserPath } from "./findBrowserPath.js";
 
 // Human Cursor - for human-like mouse movements
 import { createCursor } from "./human-cursor/index.js";
@@ -78,70 +79,8 @@ function resolveProfilePath(nameOrPath, browserName) {
 	return path.join(PERSISTENT_DIR, folderName);
 }
 
-/**
- * Locates binaries for manual browsers (Brave).
- * Uses ~/.arn-browser/browsers/{browser}/{executable}
- */
-function getBinaryPath(browserName) {
-	const isWindows = process.platform === "win32";
-	const browsersDir = path.join(ARN_BROWSER_DIR, "browsers");
-
-	const binaryMap = {
-		brave: isWindows
-			? path.join(browsersDir, "brave", "brave.exe")
-			: path.join(browsersDir, "brave", "brave"),
-	};
-
-	const binaryPath = binaryMap[browserName];
-	if (!binaryPath) {
-		throw new Error(
-			`░░░░░ [LaunchBrowser] Unknown browser for getBinaryPath: ${browserName}`
-		);
-	}
-
-	if (!fs.existsSync(binaryPath)) {
-		throw new Error(
-			`░░░░░ [LaunchBrowser] ${browserName} binary not found at: ${binaryPath}\n` +
-			`   Run "node bin/cli.js install" to install browsers.`
-		);
-	}
-
-	return binaryPath;
-}
-
-/**
- * Gets the executable path for Playwright-managed browsers (Chromium, Firefox).
- * Uses ~/.arn-browser/browsers/{browser}/{executable}
- */
-function getPlaywrightExePath(browserName) {
-	const isWindows = process.platform === "win32";
-	const browsersDir = path.join(ARN_BROWSER_DIR, "browsers");
-
-	const binaryMap = {
-		chromium: isWindows
-			? path.join(browsersDir, "chromium", "chrome.exe")
-			: path.join(browsersDir, "chromium", "chrome"),
-		firefox: isWindows
-			? path.join(browsersDir, "firefox", "firefox.exe")
-			: path.join(browsersDir, "firefox", "firefox"),
-	};
-
-	const binaryPath = binaryMap[browserName];
-	if (!binaryPath) {
-		throw new Error(
-			`░░░░░ [LaunchBrowser] Unknown browser: ${browserName}`
-		);
-	}
-
-	if (!fs.existsSync(binaryPath)) {
-		throw new Error(
-			`░░░░░ [LaunchBrowser] ${browserName} binary not found at: ${binaryPath}\n` +
-			`   Run "node bin/cli.js install" to install browsers.`
-		);
-	}
-
-	return binaryPath;
-}
+// Browser path resolution now uses OS-installed browsers via findBrowserPath.
+// See src/utility/findBrowserPath.js for detection logic.
 
 const PROFILE_META_FILE = "_profile_meta.json";
 
@@ -385,6 +324,7 @@ export async function pwLaunch({
 					humanize_options: effectiveHumanizeOptions,
 					spoof_fingerprint,
 					cleanupMinutes: effectiveCleanupMinutes,
+					browserType: which_browser, // "chrome" or "chromium"
 				});
 				break;
 			case "firefox":
@@ -442,7 +382,7 @@ export async function pwLaunch({
 // ==========================================================================
 // 4. ENGINE: CHROMIUM
 // ==========================================================================
-async function chromiumLauncher({ profilePath, proxy, timezoneId, CapSolver, humanize_options, spoof_fingerprint, cleanupMinutes }) {
+async function chromiumLauncher({ profilePath, proxy, timezoneId, CapSolver, humanize_options, spoof_fingerprint, cleanupMinutes, browserType = "chromium" }) {
 	const isPersistent = !!profilePath;
 
 	// 1. Determine Path (Temp needs it for fingerprint storage, Persistent needs it for data)
@@ -504,7 +444,7 @@ async function chromiumLauncher({ profilePath, proxy, timezoneId, CapSolver, hum
 			// Launch standard browser (not persistent context)
 			const browser = await chromium.launch({
 				headless: false,
-				executablePath: getPlaywrightExePath("chromium"),
+				executablePath: findBrowserPath(browserType),
 				proxy: proxyObj,
 				args: args,
 				ignoreDefaultArgs: ignoreDefaultArgs,
@@ -571,7 +511,7 @@ async function chromiumLauncher({ profilePath, proxy, timezoneId, CapSolver, hum
 			// Logic: Native Persistent Launch. No fingerprint-injector.
 			const context = await chromium.launchPersistentContext(activePath, {
 				headless: false,
-				executablePath: getPlaywrightExePath("chromium"),
+				executablePath: findBrowserPath(browserType),
 				proxy: proxyObj,
 				args: args,
 				timezoneId: tz,
@@ -625,7 +565,7 @@ async function firefoxLauncher({ profilePath, proxy, timezoneId, humanize_option
 
 			const browser = await firefox.launch({
 				headless: false,
-				executablePath: getPlaywrightExePath("firefox"),
+				executablePath: findBrowserPath("firefox"),
 				proxy: proxyObj,
 				ignoreDefaultArgs: ["--enable-automation"],
 				firefoxUserPrefs: firefoxUserPrefs,
@@ -667,7 +607,7 @@ async function firefoxLauncher({ profilePath, proxy, timezoneId, humanize_option
 
 			const context = await firefox.launchPersistentContext(activePath, {
 				headless: false,
-				executablePath: getPlaywrightExePath("firefox"),
+				executablePath: findBrowserPath("firefox"),
 				proxy: proxyObj,
 				timezoneId: tz,
 				ignoreDefaultArgs: ["--enable-automation"],
@@ -744,7 +684,7 @@ async function braveLauncher({ profilePath, proxy, CapSolver, timezoneId, humani
 		}
 	}
 
-	const braveBin = getBinaryPath("brave");
+	const braveBin = findBrowserPath("brave");
 
 	// ======================================================
 	// Disable Brave Sidebar via Preferences

package/src/utility/proxy-utility/proxy-chain.js

@@ -208,14 +208,7 @@ export async function startProxyServer({
 		proxy2: createHostMatcher([...PROXY_2_HOSTS, "proxy.multilogin.com", "multilogin.com"]),
 	};
 
-	// 2. Port
-	const selectedPort = await findAvailablePort(50001, 50010);
-	if (!selectedPort) {
-		console.error("░░ Critical Error: No available ports.");
-		return null;
-	}
-
-	// 3. Build URLs
+	// 2. Build URLs
 	const buildURL = (data) => {
 		if (!data) return null; // Returns null if no config
 		const { type = "http", host, port, user, pass } = data;
@@ -230,7 +223,7 @@ export async function startProxyServer({
 		p2: buildURL(PROXY_2_DATA),
 	};
 
-	// 4. Fetch Details (Simplified Logic)
+	// 3. Fetch Details (Simplified Logic)
 	// We pass the URL (or null). The function handles the "Local" logic.
 	const [defaultDetails, p1Details, p2Details] = await Promise.all([
 		fetchProxyDetails(upstreamProxies.default, ip2LocationKey, retryDelayMs),
@@ -243,7 +236,7 @@ export async function startProxyServer({
 	if (upstreamProxies.p1 && !p1Details) { console.warn("░░ Warning: PROXY_1 configured but unreachable."); return null; }
 	if (upstreamProxies.p2 && !p2Details) { console.warn("░░ Warning: PROXY_2 configured but unreachable."); return null; }
 
-	// 5. Stats
+	// 4. Stats
 	const stats = {
 		DEFAULT_PROXY: { request: 0, srcTx: 0, srcRx: 0, trgTx: 0, trgRx: 0 },
 		NO_PROXY: { request: 0, srcTx: 0, srcRx: 0, trgTx: 0, trgRx: 0 },
@@ -261,72 +254,105 @@ export async function startProxyServer({
 	const connectionMap = {}; // Maps connectionId -> { type: "..." }
 	let serverRunning = false;
 
-	// 6. Server
-	const server = new ProxyChain.Server({
-		port: selectedPort,
-		host: "127.0.0.1",
-		verbose: debug,
-		prepareRequestFunction: ({ hostname, connectionId }) => {
-			let proxyType = "DEFAULT_PROXY";
-			let upstreamUrl = upstreamProxies.default;
-			let isCustomResponse = false;
-			let customResponseData = null;
-
-			// Logic to determine Proxy Type
-			if (matchers.noProxy(hostname)) {
-				// A. Direct
-				proxyType = "NO_PROXY";
-				upstreamUrl = null;
-			} else if (matchers.proxy1(hostname) && upstreamProxies.p1) {
-				// C1. Proxy 1
-				proxyType = "PROXY_1";
-				upstreamUrl = upstreamProxies.p1;
-			} else if (matchers.proxy2(hostname) && upstreamProxies.p2) {
-				// C2. Proxy 2
-				proxyType = "PROXY_2";
-				upstreamUrl = upstreamProxies.p2;
-			}
+	// 5. Create server and bind with retry (handles race conditions between concurrent processes)
+	const PORT_RANGE_START = 50001;
+	const PORT_RANGE_END = 50200;
+	const MAX_BIND_RETRIES = 10;
 
-			// B. IP Check Interception (Overrules standard routing for specific domain)
-			if (hostname === "ip.bablosoft.com") {
-				isCustomResponse = true;
-				// Inherit the proxyType determined above to fetch the correct IP details
-				// (e.g. if it matched PROXY_1 matchers, we show PROXY_1 IP)
-				let displayedIP;
-				if (proxyType === "PROXY_1") displayedIP = p1Details?.ip;
-				else if (proxyType === "PROXY_2") displayedIP = p2Details?.ip;
-				else if (proxyType === "NO_PROXY") displayedIP = "127.0.0.1";
-				else displayedIP = defaultDetails?.ip;
-
-				customResponseData = {
-					statusCode: 200,
-					headers: { "Content-Type": "text/plain", Connection: "close" },
-					body: displayedIP || "Unknown IP",
-				};
-			}
+	let selectedPort = null;
+	let server = null;
+
+	for (let attempt = 1; attempt <= MAX_BIND_RETRIES; attempt++) {
+		const candidatePort = await findAvailablePort(PORT_RANGE_START, PORT_RANGE_END);
+		if (!candidatePort) {
+			console.error("░░ Critical Error: No available ports in range " + PORT_RANGE_START + "-" + PORT_RANGE_END);
+			return null;
+		}
 
-			// Record Stats
-			connectionMap[connectionId] = { type: proxyType, hostname: hostname };
-			if (host_stats && hostname) {
-				// Ensure the type exists in map (it should, but safety first)
-				if (!hostStatsMap[proxyType]) hostStatsMap[proxyType] = {};
-				if (!hostStatsMap[proxyType][hostname]) {
-					hostStatsMap[proxyType][hostname] = { req: 0, srcTx: 0, srcRx: 0, trgTx: 0, trgRx: 0 };
+		server = new ProxyChain.Server({
+			port: candidatePort,
+			host: "127.0.0.1",
+			verbose: debug,
+			prepareRequestFunction: ({ hostname, connectionId }) => {
+				let proxyType = "DEFAULT_PROXY";
+				let upstreamUrl = upstreamProxies.default;
+				let isCustomResponse = false;
+				let customResponseData = null;
+
+				// Logic to determine Proxy Type
+				if (matchers.noProxy(hostname)) {
+					// A. Direct
+					proxyType = "NO_PROXY";
+					upstreamUrl = null;
+				} else if (matchers.proxy1(hostname) && upstreamProxies.p1) {
+					// C1. Proxy 1
+					proxyType = "PROXY_1";
+					upstreamUrl = upstreamProxies.p1;
+				} else if (matchers.proxy2(hostname) && upstreamProxies.p2) {
+					// C2. Proxy 2
+					proxyType = "PROXY_2";
+					upstreamUrl = upstreamProxies.p2;
+				}
+
+				// B. IP Check Interception (Overrules standard routing for specific domain)
+				if (hostname === "ip.bablosoft.com") {
+					isCustomResponse = true;
+					let displayedIP;
+					if (proxyType === "PROXY_1") displayedIP = p1Details?.ip;
+					else if (proxyType === "PROXY_2") displayedIP = p2Details?.ip;
+					else if (proxyType === "NO_PROXY") displayedIP = "127.0.0.1";
+					else displayedIP = defaultDetails?.ip;
+
+					customResponseData = {
+						statusCode: 200,
+						headers: { "Content-Type": "text/plain", Connection: "close" },
+						body: displayedIP || "Unknown IP",
+					};
 				}
-				hostStatsMap[proxyType][hostname].req++;
-			}
 
-			// Return Decision
-			if (isCustomResponse) {
-				return { customResponseFunction: () => customResponseData };
+				// Record Stats
+				connectionMap[connectionId] = { type: proxyType, hostname: hostname };
+				if (host_stats && hostname) {
+					if (!hostStatsMap[proxyType]) hostStatsMap[proxyType] = {};
+					if (!hostStatsMap[proxyType][hostname]) {
+						hostStatsMap[proxyType][hostname] = { req: 0, srcTx: 0, srcRx: 0, trgTx: 0, trgRx: 0 };
+					}
+					hostStatsMap[proxyType][hostname].req++;
+				}
+
+				// Return Decision
+				if (isCustomResponse) {
+					return { customResponseFunction: () => customResponseData };
+				}
+
+				return {
+					upstreamProxyUrl: upstreamUrl,
+					requestAuthentication: false,
+				};
+			},
+		});
+
+		try {
+			await server.listen();
+			selectedPort = candidatePort;
+			serverRunning = true;
+			console.log(`░░ Local Proxy Started: http://127.0.0.1:${selectedPort}`);
+			break; // Successfully bound — exit retry loop
+		} catch (err) {
+			if (err.code === "EADDRINUSE" && attempt < MAX_BIND_RETRIES) {
+				console.warn(`░░ Port ${candidatePort} taken (race), retrying... (${attempt}/${MAX_BIND_RETRIES})`);
+				await sleep(50 + Math.random() * 100); // Small random delay to de-sync concurrent processes
+				continue;
 			}
+			console.error("░░ Failed to start proxy server:", err);
+			return null;
+		}
+	}
 
-			return {
-				upstreamProxyUrl: upstreamUrl,
-				requestAuthentication: false, // Auto-handle upstream auth via URL
-			};
-		},
-	});
+	if (!selectedPort || !server) {
+		console.error("░░ Critical Error: Could not bind to any port after " + MAX_BIND_RETRIES + " attempts.");
+		return null;
+	}
 
 	server.on("connectionClosed", ({ connectionId, stats: connStats }) => {
 		const connectionInfo = connectionMap[connectionId];
@@ -355,15 +381,6 @@ export async function startProxyServer({
 		delete connectionMap[connectionId];
 	});
 
-	try {
-		await server.listen();
-		serverRunning = true;
-		console.log(`░░ Local Proxy Started: http://127.0.0.1:${selectedPort}`);
-	} catch (err) {
-		console.error("░░ Failed to start proxy server:", err);
-		return null;
-	}
-
 	const formatBytes = (bytes) => {
 		if (bytes < 1024) return bytes + " B";
 		if (bytes < 1024 * 1024) return (bytes / 1024).toFixed(2) + " KB";

package/src/utility/puppeteer/deleteDirectory.js

@@ -0,0 +1,104 @@
+import fs from "fs";
+import path from "path";
+import { setTimeout as sleep } from "timers/promises";
+
+/**
+ * Deletes a directory with built-in retry logic.
+ * Useful for browser profiles where files might still be locked by the OS process.
+ * * @param {string} targetPath - The absolute path to delete.
+ * @param {number} maxRetries - How many times to retry (default: 5).
+ * @param {number} retryDelayMs - Time to wait between retries (default: 2000ms).
+ */
+export async function deleteDirectoryWithRetries(targetPath, maxRetries = 5, retryDelayMs = 2000) {
+	if (!fs.existsSync(targetPath)) {
+		return true; // Already gone
+	}
+
+	let attempt = 0;
+
+	while (attempt < maxRetries) {
+		try {
+			// Force: true allows deleting files even if read-only
+			// Recursive: true deletes inner folders
+			await fs.promises.rm(targetPath, { recursive: true, force: true });
+
+			// Double check if it's actually gone
+			if (!fs.existsSync(targetPath)) {
+				return true;
+			}
+		} catch (error) {
+			const isLastAttempt = attempt === maxRetries - 1;
+
+			// If it's the last attempt, log error
+			if (isLastAttempt) {
+				console.error(`░░░░░ Failed to delete directory after ${maxRetries} attempts: ${targetPath}`);
+				console.error(`   Error: ${error.message}`);
+				return false;
+			}
+
+			// Log warning and wait
+			console.warn(
+				`░░░░░  Delete failed (Attempt ${attempt + 1}/${maxRetries}). File might be locked. Retrying in ${retryDelayMs / 1000
+				}s...`
+			);
+			await sleep(retryDelayMs);
+		}
+		attempt++;
+	}
+
+	return false;
+}
+
+/**
+ * Deletes specific contents inside a directory but keeps the parent folder.
+ * (Optional utility if you need to clear cache without removing the profile folder itself)
+ */
+export async function deleteAllItemsInDirectory(directoryPath) {
+	try {
+		if (!fs.existsSync(directoryPath)) return;
+
+		const files = await fs.promises.readdir(directoryPath);
+		for (const file of files) {
+			const curPath = path.join(directoryPath, file);
+			await deleteDirectoryWithRetries(curPath);
+		}
+	} catch (error) {
+		console.error(`Error emptying directory ${directoryPath}:`, error);
+	}
+}
+
+/**
+ * Legacy utility: Scan a directory and delete folders older than X minutes.
+ * (Note: launchBrowser.js now has its own internal version of this, but keeping this
+ * here is useful if you want to run cleanup scripts independently).
+ */
+export function deleteOldDirectories({ directoryPath, ageLimitMinutes }) {
+	if (!fs.existsSync(directoryPath)) return;
+
+	const now = Date.now();
+	const limit = ageLimitMinutes * 60 * 1000;
+
+	try {
+		const files = fs.readdirSync(directoryPath);
+
+		files.forEach((file) => {
+			const curPath = path.join(directoryPath, file);
+			try {
+				const stats = fs.statSync(curPath);
+				if (stats.isDirectory()) {
+					const age = now - stats.mtimeMs;
+					if (age > limit) {
+						console.log(`Cleaning up old directory: ${file}`);
+						// We use the sync version of retry logic or just fire-and-forget async here
+						// For simplicity in a sync loop, we often just do a force removal:
+						fs.rmSync(curPath, { recursive: true, force: true });
+					}
+				}
+			} catch (e) {
+				// Ignore access errors on specific files
+			}
+		});
+	} catch (err) {
+		console.error("Error during old directory cleanup:", err);
+	}
+}

package/src/utility/puppeteer/findBrowserPath.js

@@ -0,0 +1,211 @@
+/**
+ * @file findBrowserPath.js
+ * @description Cross-platform utility to find OS-installed browser executables.
+ * Supports: chrome, chromium, firefox, brave
+ * Works on: Linux (x64/arm64), macOS (arm64), Windows (x64)
+ */
+
+import { execSync } from "child_process";
+import fs from "fs";
+import path from "path";
+
+// ==========================================================================
+// KNOWN BINARY PATHS PER PLATFORM
+// ==========================================================================
+
+const BROWSER_PATHS = {
+	chrome: {
+		linux: [
+			"google-chrome-stable",
+			"google-chrome",
+			"/opt/google/chrome/google-chrome",
+			"/usr/bin/google-chrome-stable",
+			"/usr/bin/google-chrome",
+		],
+		darwin: [
+			"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+		],
+		win32: [
+			path.join(process.env.PROGRAMFILES || "C:\\Program Files", "Google", "Chrome", "Application", "chrome.exe"),
+			path.join(process.env["PROGRAMFILES(X86)"] || "C:\\Program Files (x86)", "Google", "Chrome", "Application", "chrome.exe"),
+			path.join(process.env.LOCALAPPDATA || "", "Google", "Chrome", "Application", "chrome.exe"),
+		],
+	},
+	chromium: {
+		linux: [
+			"chromium-browser",
+			"chromium",
+			"/usr/bin/chromium-browser",
+			"/usr/bin/chromium",
+			"/snap/bin/chromium",
+		],
+		darwin: [
+			"/Applications/Chromium.app/Contents/MacOS/Chromium",
+		],
+		win32: [
+			path.join(process.env.PROGRAMFILES || "C:\\Program Files", "Chromium", "Application", "chrome.exe"),
+			path.join(process.env["PROGRAMFILES(X86)"] || "C:\\Program Files (x86)", "Chromium", "Application", "chrome.exe"),
+			path.join(process.env.LOCALAPPDATA || "", "Chromium", "Application", "chrome.exe"),
+		],
+	},
+	firefox: {
+		linux: [
+			"firefox",
+			"/usr/bin/firefox",
+			"/snap/bin/firefox",
+			"/usr/lib/firefox/firefox",
+		],
+		darwin: [
+			"/Applications/Firefox.app/Contents/MacOS/firefox",
+		],
+		win32: [
+			path.join(process.env.PROGRAMFILES || "C:\\Program Files", "Mozilla Firefox", "firefox.exe"),
+			path.join(process.env["PROGRAMFILES(X86)"] || "C:\\Program Files (x86)", "Mozilla Firefox", "firefox.exe"),
+		],
+	},
+	brave: {
+		linux: [
+			"brave-browser",
+			"brave-browser-stable",
+			"/opt/brave.com/brave/brave-browser",
+			"/usr/bin/brave-browser",
+			"/usr/bin/brave-browser-stable",
+			"/snap/bin/brave",
+		],
+		darwin: [
+			"/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
+		],
+		win32: [
+			path.join(process.env.PROGRAMFILES || "C:\\Program Files", "BraveSoftware", "Brave-Browser", "Application", "brave.exe"),
+			path.join(process.env["PROGRAMFILES(X86)"] || "C:\\Program Files (x86)", "BraveSoftware", "Brave-Browser", "Application", "brave.exe"),
+			path.join(process.env.LOCALAPPDATA || "", "BraveSoftware", "Brave-Browser", "Application", "brave.exe"),
+		],
+	},
+};
+
+// Friendly display names for error messages
+const BROWSER_DISPLAY_NAMES = {
+	chrome: "Google Chrome",
+	chromium: "Chromium",
+	firefox: "Mozilla Firefox",
+	brave: "Brave Browser",
+};
+
+// Install hints per platform
+const INSTALL_HINTS = {
+	chrome: {
+		linux: "sudo apt install google-chrome-stable  OR  download from https://www.google.com/chrome/",
+		darwin: "Download from https://www.google.com/chrome/",
+		win32: "Download from https://www.google.com/chrome/",
+	},
+	chromium: {
+		linux: "sudo apt install chromium-browser  OR  sudo snap install chromium",
+		darwin: "brew install --cask chromium  OR  download from https://www.chromium.org/",
+		win32: "Download from https://www.chromium.org/getting-involved/download-chromium/",
+	},
+	firefox: {
+		linux: "sudo apt install firefox  OR  sudo snap install firefox",
+		darwin: "brew install --cask firefox  OR  download from https://www.mozilla.org/firefox/",
+		win32: "Download from https://www.mozilla.org/firefox/",
+	},
+	brave: {
+		linux: "See https://brave.com/linux/  OR  sudo apt install brave-browser",
+		darwin: "brew install --cask brave-browser  OR  download from https://brave.com/",
+		win32: "Download from https://brave.com/",
+	},
+};
+
+// ==========================================================================
+// DETECTION LOGIC
+// ==========================================================================
+
+/**
+ * Try to resolve a command name using `which` (Unix) or `where` (Windows).
+ * Returns the absolute path if found, null otherwise.
+ */
+function resolveFromPath(command) {
+	const isWindows = process.platform === "win32";
+	try {
+		const cmd = isWindows ? `where "${command}"` : `which "${command}"`;
+		const result = execSync(cmd, { stdio: ["pipe", "pipe", "pipe"], encoding: "utf-8" }).trim();
+		// `where` on Windows may return multiple lines — take the first
+		const firstLine = result.split("\n")[0].trim();
+		if (firstLine && fs.existsSync(firstLine)) {
+			return firstLine;
+		}
+	} catch {
+		// Command not found in PATH
+	}
+	return null;
+}
+
+/**
+ * Find the OS-installed executable path for a given browser.
+ *
+ * @param {string} browserName - One of: "chrome", "chromium", "firefox", "brave"
+ * @returns {string} Absolute path to the browser executable
+ * @throws {Error} If the browser is not found on the system
+ */
+export function findBrowserPath(browserName) {
+	const name = browserName.toLowerCase();
+	const candidates = BROWSER_PATHS[name];
+
+	if (!candidates) {
+		throw new Error(
+			`❌ [findBrowserPath] Unknown browser: "${browserName}"\n` +
+			`   Supported: chrome, chromium, firefox, brave`
+		);
+	}
+
+	const platform = process.platform; // 'linux', 'darwin', 'win32'
+	const paths = candidates[platform];
+
+	if (!paths || paths.length === 0) {
+		throw new Error(
+			`❌ [findBrowserPath] ${BROWSER_DISPLAY_NAMES[name]} is not supported on platform: ${platform}`
+		);
+	}
+
+	// Strategy 1: Try PATH lookup first (works for short names like "google-chrome", "firefox")
+	for (const candidate of paths) {
+		// If it's not an absolute path, try resolving from PATH
+		if (!path.isAbsolute(candidate)) {
+			const resolved = resolveFromPath(candidate);
+			if (resolved) return resolved;
+		}
+	}
+
+	// Strategy 2: Check known absolute paths
+	for (const candidate of paths) {
+		if (path.isAbsolute(candidate) && fs.existsSync(candidate)) {
+			return candidate;
+		}
+	}
+
+	// Not found — throw descriptive error
+	const displayName = BROWSER_DISPLAY_NAMES[name];
+	const hint = INSTALL_HINTS[name]?.[platform] || `Install ${displayName} from its official website.`;
+
+	throw new Error(
+		`❌ [findBrowserPath] ${displayName} not found on this system.\n` +
+		`   Platform: ${platform}\n` +
+		`   Searched: ${paths.filter(p => path.isAbsolute(p)).join(", ") || "(PATH lookup only)"}\n\n` +
+		`   To install:\n` +
+		`   ${hint}`
+	);
+}
+
+/**
+ * Check if a browser is available without throwing.
+ *
+ * @param {string} browserName - One of: "chrome", "chromium", "firefox", "brave"
+ * @returns {{ found: boolean, path: string|null, error: string|null }}
+ */
+export function checkBrowserAvailability(browserName) {
+	try {
+		const p = findBrowserPath(browserName);
+		return { found: true, path: p, error: null };
+	} catch (err) {
+		return { found: false, path: null, error: err.message };
+	}
+}