arn-browser 0.0.2 → 0.0.4

package/src/utility/launchBrowser.js

@@ -0,0 +1,868 @@
+/**
+ * @file launchBrowser.js
+ * @description Main entry point for launching various browser engines.
+ * Supports: Chromium, Firefox (Playwright), Brave, Camoufox, and Multilogin.
+ * Handles: Persistent profiles (with prefixes), temp profiles, and tab cleanup.
+ */
+
+import fs from "fs";
+import path from "path";
+import os from "os";
+import crypto from "node:crypto";
+import { chromium, firefox } from "playwright";
+import { setTimeout as sleep } from "timers/promises";
+
+// Fingerprint management
+import { newInjectedContext, FingerprintInjector } from "fingerprint-injector";
+import { FingerprintGenerator } from "fingerprint-generator";
+
+// Internal Utilities
+import { getMultiloginToken } from "./multilogin_token_manager.js";
+import { deleteDirectoryWithRetries } from "./deleteDirectory.js";
+
+// Camoufox Special
+import { launchOptions } from "camoufox-js";
+
+// ==========================================================================
+// 1. CONFIGURATION & CONSTANTS
+// ==========================================================================
+
+const osMap = {
+	win32: "windows",
+	darwin: "macos",
+	linux: "linux",
+};
+const detectedOs = osMap[process.platform] || "windows";
+
+const MULTILOGIN_LAUNCHER_URL = "https://launcher.mlx.yt:45001";
+const MULTILOGIN_FOLDER_ID = "bad9e7e1-cfab-4c8d-bd19-91aa82929711";
+
+const PROJECT_ROOT = process.cwd();
+const BASE_PROFILE_DIR = path.join(PROJECT_ROOT, ".data", "browser_profiles");
+const PERSISTENT_DIR = path.join(BASE_PROFILE_DIR, "persistent");
+const TEMP_DIR = path.join(BASE_PROFILE_DIR, "temp");
+
+if (!fs.existsSync(PERSISTENT_DIR)) fs.mkdirSync(PERSISTENT_DIR, { recursive: true });
+if (!fs.existsSync(TEMP_DIR)) fs.mkdirSync(TEMP_DIR, { recursive: true });
+
+// ==========================================================================
+// 2. HELPER FUNCTIONS
+// ==========================================================================
+
+/**
+ * Resolves the persistent path with a browser-specific prefix.
+ */
+function resolveProfilePath(nameOrPath, browserName) {
+	if (!nameOrPath) return null;
+
+	if (path.isAbsolute(nameOrPath)) return nameOrPath;
+
+	let prefix = browserName.toLowerCase();
+	if (prefix.includes("brave")) prefix = "brave";
+	else if (prefix.includes("chrome") || prefix.includes("chromium")) prefix = "chromium";
+	else if (prefix.includes("firefox")) prefix = "firefox";
+	else if (prefix.includes("camoufox")) prefix = "camoufox";
+
+	const folderName = `${prefix}_${nameOrPath}`;
+	return path.join(PERSISTENT_DIR, folderName);
+}
+
+/**
+ * Locates binaries for manual browsers (Brave).
+ */
+function getBinaryPath(browserName) {
+	const isWindows = process.platform === "win32";
+	const homeDir = os.homedir();
+
+	let binaryPath = "";
+
+	if (browserName === "brave") {
+		if (isWindows) {
+			// Windows: Standard custom install path in Downloads
+			binaryPath = path.join(homeDir, "Downloads", "brave", "brave.exe");
+		} else {
+			// Linux: Primary check in .cache (common for script installs)
+			const cachePath = path.join(homeDir, ".cache", "brave", "brave");
+			const downloadsPath = path.join(homeDir, "Downloads", "brave", "brave");
+
+			if (fs.existsSync(cachePath)) {
+				binaryPath = cachePath;
+			} else if (fs.existsSync(downloadsPath)) {
+				binaryPath = downloadsPath;
+			} else {
+				// Default to cache path for the error message if neither is found
+				binaryPath = cachePath;
+			}
+		}
+	}
+
+	if (!binaryPath || !fs.existsSync(binaryPath)) {
+		throw new Error(
+			`❌ [LaunchBrowser] Binary not found for ${browserName} at: ${binaryPath}\n` +
+				`   Linux checked: ~/.cache/brave/brave AND ~/Downloads/brave/brave`
+		);
+	}
+
+	return binaryPath;
+}
+
+function cleanUpTempProfiles(ageLimitMinutes) {
+	if (!ageLimitMinutes || ageLimitMinutes < 10) return;
+
+	console.log(`🧹 [Cleanup] Checking for temp profiles older than ${ageLimitMinutes} mins...`);
+	const now = Date.now();
+	const limit = ageLimitMinutes * 60 * 1000;
+
+	try {
+		const files = fs.readdirSync(TEMP_DIR);
+		files.forEach((file) => {
+			const curPath = path.join(TEMP_DIR, file);
+			try {
+				const stats = fs.statSync(curPath);
+				if (stats.isDirectory() && now - stats.mtimeMs > limit) {
+					console.log(`   Deleting expired temp profile: ${file}`);
+					deleteDirectoryWithRetries(curPath);
+				}
+			} catch (e) {
+				// Ignore file lock errors
+			}
+		});
+	} catch (err) {
+		console.error("Cleanup Error:", err);
+	}
+}
+
+/**
+ * Helper to generate consistent fingerprint options.
+ */
+function getFingerprintConfig(browserType, maxWidth) {
+	const config = {
+		devices: ["desktop"],
+		operatingSystems: [detectedOs],
+		locales: ["en-US"],
+		browsers: [],
+		screen: {},
+	};
+
+	if (browserType === "chromium") {
+		config.browsers.push({ name: "chrome", minVersion: 140 });
+	} else if (browserType === "firefox") {
+		config.browsers.push({ name: "firefox", minVersion: 140 });
+	} else if (browserType === "brave") {
+		config.browsers.push({ name: "chrome", minVersion: 140 });
+	}
+
+	if (maxWidth) {
+		const widthVal = maxWidth <= 10 ? Math.round(maxWidth * 1920) : maxWidth;
+		config.screen.maxWidth = widthVal;
+	}
+
+	return config;
+}
+
+// ==========================================================================
+// 3. MAIN LAUNCHER ENTRY POINT
+// ==========================================================================
+
+export async function launchBrowser({
+	// Common
+	timezoneId = null,
+	proxy,
+	maxWidth = 1,
+
+	// Path & Storage
+	profile_path = null,
+	custom_profile_path = null, // Backward (Just for throwing error)
+	cleanupMinutes = 0,
+
+	which_browser = "chromium",
+	CapSolver = false,
+
+	// Browser Specific Grouped Options
+	camoufox_options = {}, // { geoip, humanize, ... }
+	multilogin_options = {}, // { profileId, os_type, canvas_noise, ... }
+}) {
+	try {
+		if (custom_profile_path) throw new Error("Please use profile_path");
+
+		// Resolve path using the browser type to ensure prefixes
+		const fullPath = resolveProfilePath(profile_path, which_browser);
+		cleanUpTempProfiles(cleanupMinutes);
+
+		let browserInstance;
+
+		switch (which_browser) {
+			case "chromium":
+			case "chrome":
+				browserInstance = await chromiumLauncher({
+					profilePath: fullPath,
+					proxy,
+					timezoneId,
+					CapSolver,
+					maxWidth,
+				});
+				break;
+			case "firefox":
+				browserInstance = await firefoxLauncher({
+					profilePath: fullPath,
+					proxy,
+					timezoneId,
+					maxWidth,
+				});
+				break;
+			case "brave":
+			case "braveLauncher":
+				browserInstance = await braveLauncher({
+					profilePath: fullPath,
+					proxy,
+					timezoneId,
+					CapSolver,
+					maxWidth,
+				});
+				break;
+			case "camoufox":
+				browserInstance = await camoufoxLauncher({
+					profilePath: fullPath,
+					proxy,
+					timezoneId,
+					maxWidth,
+					camoufox_options,
+				});
+				break;
+			case "multilogin":
+				browserInstance = await multiloginLauncher({
+					proxy,
+					multilogin_options,
+				});
+				break;
+			default:
+				throw new Error(`Unknown browser type: ${which_browser}`);
+		}
+
+		return browserInstance;
+	} catch (error) {
+		console.error("❌ [LaunchBrowser] Critical Error:", error.message || error);
+		return { data: null, error: error, closeBrowser: async () => {} };
+	}
+}
+
+// ==========================================================================
+// 4. ENGINE: CHROMIUM
+// ==========================================================================
+async function chromiumLauncher({ profilePath, proxy, timezoneId, CapSolver, maxWidth }) {
+	const isPersistent = !!profilePath;
+
+	// 1. Determine Path (Temp needs it for fingerprint storage, Persistent needs it for data)
+	const activePath = isPersistent ? profilePath : path.join(TEMP_DIR, crypto.randomUUID());
+	console.log(`🚀 Starting Chromium [${isPersistent ? "Persistent" : "Temp"}]: ${activePath}`);
+
+	// 2. Define Args
+	const args = [
+		"--test-type",
+		// --- Stealth & Anti-Detection ---
+		"--disable-blink-features=AutomationControlled",
+		// "--disable-features=UserAgentClientHint",
+		// --- PREVENT EXTRA TABS ---
+		// "--homepage=about:blank",
+		"--disable-restore-session-state",
+		// --- Error Suppression ---
+		"--disable-session-crashed-bubble",
+		"--hide-crash-restore-bubble",
+		// --- Silence & Networking ---
+		"--disable-background-networking",
+		"--disable-background-timer-throttling",
+		"--disable-breakpad",
+		"--disable-crash-reporter",
+		"--disable-component-update",
+		"--disable-sync",
+		"--no-default-browser-check",
+		"--no-first-run",
+		"--disable-domain-reliability",
+		"--disable-client-side-phishing-detection",
+		// --- UI ---
+		"--disable-infobars",
+	];
+	const ignoreDefaultArgs = ["--enable-automation", "--no-sandbox"];
+
+	if (CapSolver) {
+		const extPath = path.resolve(`./utility/browser-fingerprint/CapSolver`);
+		args.push(`--disable-extensions-except=${extPath}`, `--load-extension=${extPath}`);
+	}
+
+	const proxyObj = formatProxy(proxy);
+	const tz = timezoneId || undefined;
+
+	// ==================================================================
+	// BRANCH A: TEMP PROFILE (launch + newInjectedContext)
+	// ==================================================================
+	if (!isPersistent) {
+		try {
+			const fpConfig = getFingerprintConfig("chromium", maxWidth);
+			const fingerprintData = new FingerprintGenerator().getFingerprint(fpConfig);
+
+			// Launch standard browser (not persistent context)
+			const browser = await chromium.launch({
+				headless: false,
+				proxy: proxyObj,
+				args: args,
+				ignoreDefaultArgs: ignoreDefaultArgs,
+			});
+
+			// Inject the fingerprint
+			const context = await newInjectedContext(browser, {
+				fingerprint: fingerprintData,
+				timezoneId: tz,
+			});
+
+			const page = context.pages()[0] || (await context.newPage());
+
+			// Pass 'activePath' so the temp folder (containing fingerprint.json) gets deleted on close
+			return createBrowserController(browser, context, page, activePath);
+		} catch (err) {
+			console.error("Chromium Temp Launch Error:", err);
+			throw err;
+		}
+	}
+	// ==================================================================
+	// BRANCH B: PERSISTENT PROFILE (launchPersistentContext + Manual Script)
+	// ==================================================================
+	else {
+		try {
+			if (!fs.existsSync(activePath)) fs.mkdirSync(activePath, { recursive: true });
+
+			// Logic: Native Persistent Launch. No fingerprint-injector.
+			const context = await chromium.launchPersistentContext(activePath, {
+				headless: false,
+				proxy: proxyObj,
+				args: args,
+				timezoneId: tz,
+				ignoreDefaultArgs: ignoreDefaultArgs,
+				viewport: null,
+			});
+
+			// Manual Stealth Script
+			await addStealthScript(context);
+
+			const page = context.pages()[0];
+
+			return createBrowserController(context, context, page, null);
+		} catch (err) {
+			console.error("Chromium Persistent Launch Error:", err);
+			throw err;
+		}
+	}
+}
+
+// ==========================================================================
+// 5. ENGINE: FIREFOX
+// ==========================================================================
+async function firefoxLauncher({ profilePath, proxy, timezoneId, maxWidth }) {
+	const isPersistent = !!profilePath;
+
+	// 1. Determine Path
+	const activePath = isPersistent ? profilePath : path.join(TEMP_DIR, crypto.randomUUID());
+	console.log(`🚀 Starting Firefox [${isPersistent ? "Persistent" : "Temp"}]: ${activePath}`);
+
+	const proxyObj = formatProxy(proxy);
+	const tz = timezoneId || undefined;
+
+	// Firefox specific preferences
+	const firefoxUserPrefs = {
+		"dom.webdriver.enabled": false,
+		useAutomationExtension: false,
+		"media.peerconnection.enabled": false,
+	};
+
+	// ==================================================================
+	// BRANCH A: TEMP PROFILE (launch + newInjectedContext)
+	// ==================================================================
+	if (!isPersistent) {
+		try {
+			const fpConfig = getFingerprintConfig("firefox", maxWidth);
+			const fingerprintData = new FingerprintGenerator().getFingerprint(fpConfig);
+
+			const browser = await firefox.launch({
+				headless: false,
+				proxy: proxyObj,
+				ignoreDefaultArgs: ["--enable-automation"],
+				firefoxUserPrefs: firefoxUserPrefs,
+			});
+
+			const context = await newInjectedContext(browser, {
+				fingerprint: fingerprintData,
+				timezoneId: tz,
+			});
+
+			const page = context.pages()[0] || (await context.newPage());
+
+			// Pass 'activePath' to delete temp folder later
+			return createBrowserController(browser, context, page, activePath);
+		} catch (err) {
+			console.error("Firefox Temp Launch Error:", err);
+			throw err;
+		}
+	}
+	// ==================================================================
+	// BRANCH B: PERSISTENT PROFILE (launchPersistentContext + Manual Script)
+	// ==================================================================
+	else {
+		try {
+			if (!fs.existsSync(activePath)) fs.mkdirSync(activePath, { recursive: true });
+
+			const context = await firefox.launchPersistentContext(activePath, {
+				headless: false,
+				proxy: proxyObj,
+				timezoneId: tz,
+				ignoreDefaultArgs: ["--enable-automation"],
+				// firefoxUserPrefs: firefoxUserPrefs,
+				viewport: null,
+			});
+
+			// Manual Stealth Script
+			await addStealthScript(context);
+
+			const page = context.pages()[0];
+
+			return createBrowserController(context, context, page, null);
+		} catch (err) {
+			console.error("Firefox Persistent Launch Error:", err);
+			throw err;
+		}
+	}
+}
+
+// ==========================================================================
+// 6. ENGINE: BRAVE
+// ==========================================================================
+async function braveLauncher({ profilePath, proxy, CapSolver, timezoneId, maxWidth }) {
+	const isPersistent = !!profilePath;
+	const activePath = isPersistent ? profilePath : path.join(TEMP_DIR, crypto.randomUUID());
+
+	console.log(`🚀 Starting Brave: ${activePath}`);
+	fs.mkdirSync(activePath, { recursive: true });
+
+	let fingerprintData;
+	const fingerprintFilePath = path.join(activePath, "fingerprint.json");
+
+	if (fs.existsSync(fingerprintFilePath)) {
+		fingerprintData = JSON.parse(fs.readFileSync(fingerprintFilePath, "utf-8"));
+	} else {
+		const fpConfig = getFingerprintConfig("brave", maxWidth);
+		fingerprintData = new FingerprintGenerator().getFingerprint(fpConfig);
+
+		if (isPersistent) {
+			fs.writeFileSync(fingerprintFilePath, JSON.stringify(fingerprintData, null, 2), "utf-8");
+			console.log("📝 Generated and saved new fingerprint for Brave");
+		}
+	}
+
+	const braveBin = getBinaryPath("brave");
+
+	const args = [
+		"--test-type",
+		// --- Stealth & Anti-Detection ---
+		"--disable-blink-features=AutomationControlled",
+		//"--disable-features=UserAgentClientHint",
+
+		// --- PREVENT EXTRA TABS (New Flags) ---
+		// "--no-startup-window",
+		"--homepage=about:blank",
+		"--disable-restore-session-state", // Prevents restoring old tabs
+
+		// --- Error Suppression ---
+		"--disable-session-crashed-bubble",
+		"--hide-crash-restore-bubble",
+
+		// --- Silence & Networking ---
+		"--disable-background-networking",
+		"--disable-background-timer-throttling",
+		"--disable-breakpad",
+		"--disable-crash-reporter",
+		"--disable-component-update",
+		"--disable-sync",
+		"--no-default-browser-check",
+		"--no-first-run",
+		"--disable-domain-reliability",
+		"--disable-client-side-phishing-detection",
+
+		// --- Brave Specific Silence ---
+		"--disable-features=Translate,BraveRewards,BraveWallet,BraveNews",
+		"--disable-infobars",
+	];
+	const ignoreDefaultArgs = ["--enable-automation", "--no-sandbox"];
+	if (CapSolver) {
+		const extPath = path.resolve(`./utility/browser-fingerprint/CapSolver`);
+		args.push(`--load-extension=${extPath}`);
+	}
+
+	const proxyObj = formatProxy(proxy);
+	const tz = timezoneId || undefined;
+
+	const context = await chromium.launchPersistentContext(activePath, {
+		headless: false,
+		executablePath: braveBin,
+		proxy: proxyObj,
+		timezoneId: tz,
+		ignoreDefaultArgs: ignoreDefaultArgs,
+		args: args,
+		userAgent: fingerprintData.fingerprint.navigator.userAgent,
+		viewport: fingerprintData.fingerprint.screen,
+		locale: fingerprintData.fingerprint.navigator.language,
+	});
+
+	await new FingerprintInjector().attachFingerprintToPlaywright(context, fingerprintData);
+
+	// ======================================================
+	// 🛠️ FIX: Close Extra Tabs (Brave Dashboard / Restore)
+	// ======================================================
+	const pages = context.pages();
+	if (pages.length > 1) {
+		console.log(`🧹 Found ${pages.length} tabs open in Brave. Closing extras...`);
+		// Close all tabs except the last one (which is usually the fresh active one)
+		for (let i = 0; i < pages.length - 1; i++) {
+			await pages[i].close();
+		}
+	}
+	const page = context.pages()[0];
+
+	const dirToDelete = isPersistent ? null : activePath;
+	// Return the remaining open page (context.pages() might change, so we grab index 0 after cleanup)
+	return createBrowserController(context, context, page, dirToDelete);
+}
+
+// ==========================================================================
+// 7. ENGINE: CAMOUFOX
+// ==========================================================================
+async function camoufoxLauncher({ profilePath, proxy, timezoneId, maxWidth, camoufox_options = {} }) {
+	const isPersistent = !!profilePath;
+	const activePath = isPersistent ? profilePath : path.join(TEMP_DIR, crypto.randomUUID());
+
+	console.log(`🚀 Starting camoufoxJs: ${activePath}`);
+	fs.mkdirSync(activePath, { recursive: true });
+
+	const proxyObj = formatProxy(proxy);
+	const tz = timezoneId || undefined;
+
+	// Check if GeoIP is enabled in options (Default to false if undefined)
+	const isGeoIpEnabled = camoufox_options.geoip === true;
+
+	let launchConfig;
+	const fingerprintFilePath = path.join(activePath, "fingerprint.json");
+
+	// 1. Load existing or Generate new config
+	if (fs.existsSync(fingerprintFilePath)) {
+		// Load the previously generated launch options
+		launchConfig = JSON.parse(fs.readFileSync(fingerprintFilePath, "utf-8"));
+
+		// IMPORTANT: For persistent profiles, if we are NOT using GeoIP (static behavior),
+		// we usually want to ensure the proxy for *this* run is applied, as it might have changed.
+		if (!isGeoIpEnabled && proxyObj) {
+			launchConfig.proxy = proxyObj;
+		}
+	} else {
+		function getRandomValidMajorVersion() {
+			// Valid Major Versions (135 - 145)
+			const validMajorVersions = [135, 136, 137, 138, 139, 140, 141, 142, 143, 144, 145];
+			const randomIndex = Math.floor(Math.random() * validMajorVersions.length);
+			return validMajorVersions[randomIndex];
+		}
+		const screenWidth = maxWidth ? (maxWidth <= 10 ? Math.round(maxWidth * 1920) : maxWidth) : 1920;
+
+		// Prepare the base options
+		const optionsGenerator = {
+			ff_version: camoufox_options.ff_version || getRandomValidMajorVersion(),
+			headless: camoufox_options.headless || false,
+			humanize: camoufox_options.humanize ?? true,
+			block_images: camoufox_options.block_images ?? false,
+			block_webrtc: camoufox_options.block_webrtc ?? false,
+			i_know_what_im_doing: true, // Suppress warnings if manual config intentional
+			geoip: isGeoIpEnabled,
+
+			// Apply the strictly validated OS
+			os: camoufox_options.os || detectedOs,
+
+			...camoufox_options, // Spread user overrides
+		};
+
+		if (camoufox_options.screen) {
+			optionsGenerator.screen = camoufox_options.screen;
+		} else {
+			optionsGenerator.screen = {
+				maxWidth: screenWidth,
+			};
+		}
+		// If GeoIP is TRUE, pass proxy inside launchOptions
+		if (isGeoIpEnabled && proxyObj) {
+			optionsGenerator.proxy = proxyObj;
+		}
+
+		// If GeoIP is TRUE, pass proxy inside launchOptions
+		if (isGeoIpEnabled && proxyObj) {
+			optionsGenerator.proxy = proxyObj;
+		}
+
+		// Generate full launch config via camoufox-js
+		launchConfig = await launchOptions(optionsGenerator);
+
+		// Save persistent config
+		if (isPersistent) {
+			fs.writeFileSync(fingerprintFilePath, JSON.stringify(launchConfig, null, 2), "utf-8");
+			console.log("📝 Generated and saved new launch config for Camoufox");
+		}
+	}
+
+	// Post-Generation Adjustments for Playwright Connection
+	if (!isGeoIpEnabled && proxyObj) {
+		launchConfig.proxy = proxyObj;
+	}
+
+	if (!isGeoIpEnabled && tz) {
+		launchConfig.timezoneId = tz;
+	}
+
+	const context = await firefox.launchPersistentContext(activePath, {
+		...launchConfig,
+		// Removed viewport: null, handled by Camoufox args
+	});
+
+	const dirToDelete = isPersistent ? null : activePath;
+	return createBrowserController(context, context, context.pages()[0], dirToDelete);
+}
+
+// ==========================================================================
+// 8. ENGINE: MULTILOGIN
+// ==========================================================================
+async function multiloginLauncher({ proxy, multilogin_options = {} }) {
+	// Destructure defaults from multilogin_options
+	const {
+		profileId = null,
+		os_type = detectedOs,
+		canvas_noise = true,
+		media_masking = true,
+		audio_masking = true,
+		custom_screen = false,
+	} = multilogin_options;
+
+	if (profileId) {
+		return await launchExistingMultiloginProfile(profileId);
+	} else {
+		return await launchQuickMultiloginProfile({
+			os_type,
+			proxy,
+			canvas_noise,
+			media_masking,
+			audio_masking,
+		});
+	}
+}
+
+async function launchExistingMultiloginProfile(profileId) {
+	const startUrl = `${MULTILOGIN_LAUNCHER_URL}/api/v2/profile/f/${MULTILOGIN_FOLDER_ID}/p/${profileId}/start?automation_type=playwright&headless_mode=false`;
+	let browser, context, page;
+
+	try {
+		const token = await getMultiloginToken();
+		let response = await fetch(startUrl, {
+			method: "GET",
+			headers: { Authorization: `Bearer ${token}`, Accept: "application/json", "X-Strict-Mode": "true" },
+		});
+
+		if (response.status === 400) {
+			const errorJson = await response.json().catch(() => null);
+			if (errorJson?.status?.error_code === "PROFILE_ALREADY_RUNNING") {
+				console.log(`⚠️ Profile ${profileId} is running. Restarting...`);
+				await stopMultiloginProfile(profileId);
+				await sleep(5000);
+				response = await fetch(startUrl, {
+					method: "GET",
+					headers: {
+						Authorization: `Bearer ${await getMultiloginToken()}`,
+						Accept: "application/json",
+						"X-Strict-Mode": "true",
+					},
+				});
+			} else {
+				throw new Error(`Multilogin 400 Error: ${JSON.stringify(errorJson)}`);
+			}
+		}
+
+		if (!response.ok) throw new Error(`Failed to start profile: ${await response.text()}`);
+
+		const data = await response.json();
+		const port = data.data.port;
+		console.log(`✅ Multilogin Profile ${profileId} started on port ${port}`);
+
+		browser = await chromium.connectOverCDP(`http://localhost:${port}`);
+		context = browser.contexts()[0];
+		page = context.pages()[0];
+
+		const closeBrowser = async () => {
+			if (browser) await browser.close().catch(() => {});
+			return await stopMultiloginProfile(profileId);
+		};
+
+		return { browser, context, page, isBrowserRunning: () => !!browser, closeBrowser, launchError: null };
+	} catch (error) {
+		console.error("Multilogin Launch Error:", error.message);
+		try {
+			await stopMultiloginProfile(profileId);
+		} catch (e) {}
+		return { data: null, error, closeBrowser: async () => {} };
+	}
+}
+
+async function launchQuickMultiloginProfile({ os_type, proxy, canvas_noise, media_masking, audio_masking }) {
+	const createUrl = `${MULTILOGIN_LAUNCHER_URL}/api/v3/profile/quick`;
+	let browser, context, page, profileId;
+
+	const requestBody = {
+		browser_type: "mimic",
+		os_type,
+		automation: "playwright",
+		is_headless: false,
+		parameters: {
+			flags: {
+				audio_masking: audio_masking ? "mask" : "natural",
+				media_devices_masking: media_masking ? "mask" : "natural",
+				screen_masking: "natural",
+				canvas_noise: canvas_noise ? "mask" : "natural",
+				proxy_masking: proxy ? "custom" : "disabled",
+			},
+		},
+		quickProfilesCount: 1,
+	};
+
+	if (proxy) {
+		const pObj = formatProxy(proxy);
+		if (pObj) {
+			const u = new URL(pObj.server);
+			requestBody.parameters.proxy = {
+				type: "http",
+				host: u.hostname,
+				port: Number(u.port),
+				username: pObj.username || "",
+				password: pObj.password || "",
+			};
+		}
+	}
+
+	try {
+		const token = await getMultiloginToken();
+		const response = await fetch(createUrl, {
+			method: "POST",
+			headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+			body: JSON.stringify(requestBody),
+		});
+
+		if (!response.ok) throw new Error(await response.text());
+		const json = await response.json();
+
+		profileId = json.data.id;
+		const port = json.data.port;
+		console.log(`✅ Quick Profile Created: ${profileId} on port ${port}`);
+
+		browser = await chromium.connectOverCDP(`http://localhost:${port}`);
+		context = browser.contexts()[0];
+		page = context.pages()[0];
+
+		const closeBrowser = async () => {
+			if (browser) await browser.close().catch(() => {});
+			return await stopMultiloginProfile(profileId);
+		};
+
+		return { browser, context, page, isBrowserRunning: () => !!browser, closeBrowser, launchError: null };
+	} catch (error) {
+		console.error("Quick Profile Error:", error);
+		if (profileId) await stopMultiloginProfile(profileId);
+		return { data: null, error, closeBrowser: async () => {} };
+	}
+}
+
+async function stopMultiloginProfile(profileId) {
+	const stopUrl = `${MULTILOGIN_LAUNCHER_URL}/api/v1/profile/stop/p/${profileId}`;
+	try {
+		const token = await getMultiloginToken();
+		const response = await fetch(stopUrl, {
+			method: "GET",
+			headers: { Authorization: `Bearer ${token}`, Accept: "application/json" },
+		});
+
+		if (!response.ok) {
+			const txt = await response.text();
+			if (response.status === 500 && txt.includes("profile already stopped")) {
+				return { error: null };
+			}
+			throw new Error(txt);
+		}
+		console.log(`🛑 Profile ${profileId} stopped.`);
+		return { error: null };
+	} catch (err) {
+		console.error(`Error stopping ${profileId}:`, err);
+		return { error: err };
+	}
+}
+// ==========================================================================
+// 10. SHARED UTILITIES
+// ==========================================================================
+
+async function addStealthScript(context) {
+	await context.addInitScript(() => {
+		// Keep these deletions, they are Playwright-specific bindings
+		delete window.__pwInitScripts;
+		// delete window.playwright;
+		delete window.__playwright__binding__;
+		delete window.__playwright__binding__controller__;
+
+		// Check if navigator.webdriver exists and is true (indicating automation)
+		if (navigator.webdriver) {
+			// console.log("33333333333333333333333 - Automation detected, patching to false");
+
+			// Define a new getter for the property on the prototype
+			// This overrides the native 'true' with 'false'
+			Object.defineProperty(Object.getPrototypeOf(navigator), "webdriver", {
+				get: () => false,
+			});
+		} else {
+			// If it's already false or undefined, we leave it alone to look natural
+			// console.log("Navigator.webdriver is already safe (" + navigator.webdriver + ")");
+		}
+	});
+}
+function formatProxy(proxy) {
+	if (!proxy) return undefined;
+	if (typeof proxy === "string") return { server: proxy };
+
+	const p = { server: `${proxy.type}://${proxy.host}:${proxy.port}` };
+	if (proxy.user) {
+		p.username = proxy.user;
+		p.password = proxy.pass;
+	}
+	return p;
+}
+
+function createBrowserController(browser, context, page, dirToDelete = null) {
+	const closeBrowser = async () => {
+		try {
+			console.log("🔒 Closing browser session...");
+			if (context) await context.close();
+			if (browser && typeof browser.close === "function" && browser !== context) {
+				try {
+					await browser.close();
+				} catch (e) {}
+			}
+			if (dirToDelete) {
+				if (dirToDelete.includes("persistent")) {
+					console.warn(`⚠️  Safety Block: Attempted to delete persistent profile: ${dirToDelete}`);
+				} else {
+					console.log(`🗑️  Deleting temp profile: ${dirToDelete}`);
+					await deleteDirectoryWithRetries(dirToDelete);
+				}
+			}
+			return true;
+		} catch (err) {
+			console.error("Error closing browser:", err);
+			return false;
+		}
+	};
+	return { browser, context, page, isBrowserRunning: () => !!context, closeBrowser, launchError: null };
+}