headfox-js 0.1.1

package/dist/mappings/warnings.config.d.ts

@@ -0,0 +1,16 @@
+declare const _default: {
+    navigator: string;
+    locale: string;
+    geolocation: string;
+    "header-ua": string;
+    viewport: string;
+    custom_fingerprint: string;
+    proxy_without_geoip: string;
+    ff_version: string;
+    no_region: string;
+    block_webgl: string;
+    block_images: string;
+    custom_fonts_only: string;
+    disable_coop: string;
+};
+export default _default;

package/dist/mappings/warnings.config.js

@@ -0,0 +1,27 @@
+export default {
+    navigator: "Manually setting navigator properties is not recommended." +
+        " Device information is automatically generated within Headfox" +
+        " based on the provided `os`.",
+    locale: "Use the `locale` parameter in Headfox instead of setting the config manually.",
+    geolocation: "Please use the `geoip` parameter in Headfox instead of setting your geolocation manually." +
+        " This can lead to detection if your target geolocation does not match your IP." +
+        " Pass `geoip=True` or a target IP (ex: geoip='123.45.67.89') to let Headfox populate this data for you.",
+    "header-ua": "Do not set the header.User-Agent manually. Headfox will generate a User-Agent for you.",
+    viewport: "Manually setting screen & window properties is not recommended." +
+        " Screen dimensions are randomly generated within Headfox" +
+        " based on the provided screen constraints.",
+    custom_fingerprint: "Passing your own fingerprint is not recommended." +
+        " BrowserForge fingerprints are automatically generated within Headfox" +
+        " based on the provided `os` and `screen` constraints.",
+    proxy_without_geoip: "When using a proxy, it is heavily recommended that you pass `geoip=True`.",
+    ff_version: "Spoofing the Firefox version will likely lead to detection." +
+        " If rotating the Firefox version is absolutely necessary, it would be more advisable to" +
+        " rotate between older versions of Headfox instead.",
+    no_region: "Because you did not pass in a locale region, Headfox will generate one for you." +
+        " This can cause suspicion if your IP does not match your locale region.",
+    block_webgl: "Disabling WebGL is not recommended. Many WAFs will check if WebGL is enabled.",
+    block_images: "Blocking image requests has been reported to cause detection issues on major WAFs.",
+    custom_fonts_only: "Disabling OS-specific fonts while spoofing your OS will make your browser fingerprint inconsistent." +
+        " WAFs can detect this mismatch between your claimed OS and available system fonts.",
+    disable_coop: "Disabling Cross-Origin-Opener-Policy (COOP) handling can potentially be detected by sophisticated WAFs.",
+};

package/dist/pkgman.d.ts

@@ -0,0 +1,67 @@
+import type { PathLike } from "node:fs";
+import type { Writable } from "node:stream";
+export declare const OS_NAME: "mac" | "win" | "lin";
+export declare const INSTALL_DIR: string;
+export declare const LOCAL_DATA: PathLike;
+export declare const OS_ARCH_MATRIX: {
+    [key: string]: string[];
+};
+declare class Version {
+    release: string;
+    version?: string;
+    sorted_rel: number[];
+    constructor(release: string, version?: string);
+    private buildSortedRel;
+    get fullString(): string;
+    equals(other: Version): boolean;
+    lessThan(other: Version): boolean;
+    isSupported(): boolean;
+    static fromPath(filePath?: PathLike): Version;
+    static isSupportedPath(path: PathLike): boolean;
+    static buildMinMax(): [Version, Version];
+}
+export declare class GitHubDownloader {
+    githubRepo: string;
+    apiUrl: string;
+    constructor(githubRepo: string);
+    checkAsset(asset: any): any;
+    missingAssetError(): void;
+    getAsset({ retries }?: {
+        retries: number;
+    }): Promise<any>;
+}
+export declare class HeadfoxFetcher extends GitHubDownloader {
+    arch: string;
+    _version_obj?: Version;
+    pattern: RegExp;
+    _url?: string;
+    constructor();
+    init(): Promise<void>;
+    checkAsset(asset: any): [Version, string] | null;
+    missingAssetError(): void;
+    static getPlatformArch(): string;
+    fetchLatest(): Promise<void>;
+    static downloadFile(url: string): Promise<Buffer>;
+    extractZip(zipFile: string | Buffer): Promise<void>;
+    static cleanup(): boolean;
+    setVersion(): void;
+    install(): Promise<void>;
+    get url(): string;
+    get version(): string;
+    get release(): string;
+    get verstr(): string;
+}
+export declare function installedVerStr(): string;
+export declare function isBrowserInstalled(): boolean;
+export declare function ensureBrowserInstalled(): Promise<string>;
+export declare function getInstalledBrowserDir(): string;
+export declare function headfoxPath(downloadIfMissing?: boolean): string;
+export declare const camoufoxPath: typeof headfoxPath;
+export declare const CamoufoxFetcher: typeof HeadfoxFetcher;
+export declare function getPath(file: string): string;
+export declare function launchPath(): string;
+export declare function webdl(url: string, desc?: string, bar?: boolean, buffer?: Writable | null, { retries }?: {
+    retries: number;
+}): Promise<Buffer>;
+export declare function unzip(zipFile: Buffer, extractPath: string, desc?: string, bar?: boolean): Promise<void>;
+export {};

package/dist/pkgman.js

@@ -0,0 +1,421 @@
+import * as fs from "node:fs";
+import { chmod, readdir } from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { setTimeout } from "node:timers/promises";
+import { fileURLToPath } from "node:url";
+import AdmZip from "adm-zip";
+import cliProgress from "cli-progress";
+import prettyBytes from "pretty-bytes";
+import { CONSTRAINTS } from "./__version__.js";
+import { FileNotFoundError, HeadfoxNotInstalled, MissingRelease, UnsupportedArchitecture, UnsupportedOS, UnsupportedVersion, } from "./exceptions.js";
+const ARCH_MAP = {
+    x64: "x86_64",
+    ia32: "i686",
+    arm64: "arm64",
+    arm: "arm64",
+};
+const OS_MAP = {
+    darwin: "mac",
+    linux: "lin",
+    win32: "win",
+};
+if (!(process.platform in OS_MAP)) {
+    throw new UnsupportedOS(`OS ${process.platform} is not supported`);
+}
+export const OS_NAME = OS_MAP[process.platform];
+const RELEASE_REPO = process.env.HEADFOX_JS_RELEASE_REPO ??
+    process.env.CAMOUFOX_JS_RELEASE_REPO ??
+    "CloverLabsAI/camoufox";
+const CACHE_DIR_NAME = process.env.HEADFOX_JS_CACHE_DIR ??
+    process.env.CAMOUFOX_JS_CACHE_DIR ??
+    "headfox";
+const ASSET_PREFIXES = Array.from(new Set((process.env.HEADFOX_JS_ASSET_PREFIXES ??
+    process.env.CAMOUFOX_JS_ASSET_PREFIXES ??
+    "camoufox,headfox")
+    .split(",")
+    .map((value) => value.trim())
+    .filter(Boolean)));
+const APP_BUNDLE_CANDIDATES = ["Headfox.app", "Camoufox.app"];
+const currentDir = import.meta.dirname ?? path.dirname(fileURLToPath(import.meta.url));
+export const INSTALL_DIR = userCacheDir(CACHE_DIR_NAME);
+const formatBytes = (v, _, type) => type === "total" || type === "value" ? prettyBytes(v) : String(v);
+export const LOCAL_DATA = path.join(currentDir, "data-files");
+export const OS_ARCH_MATRIX = {
+    win: ["x86_64", "i686"],
+    mac: ["x86_64", "arm64"],
+    lin: ["x86_64", "arm64", "i686"],
+};
+const LAUNCH_FILE_CANDIDATES = {
+    win: ["headfox.exe", "camoufox.exe"],
+    mac: ["../MacOS/headfox", "../MacOS/camoufox"],
+    lin: ["headfox-bin", "camoufox-bin"],
+};
+function installMissingMessage(product = "Headfox") {
+    return `${product} is not installed at ${INSTALL_DIR}. Please run \`headfox-js fetch\` to install.`;
+}
+function isInstallDirReady() {
+    return fs.existsSync(INSTALL_DIR) && fs.readdirSync(INSTALL_DIR).length > 0;
+}
+async function chmodTree(targetPath, mode) {
+    await chmod(targetPath, mode);
+    const entries = await readdir(targetPath, { withFileTypes: true });
+    for (const entry of entries) {
+        const nextPath = path.join(targetPath, entry.name);
+        if (entry.isDirectory()) {
+            await chmodTree(nextPath, mode);
+            continue;
+        }
+        await chmod(nextPath, mode);
+    }
+}
+function resolveMacAppBundle(installDir) {
+    return (APP_BUNDLE_CANDIDATES.find((candidate) => fs.existsSync(path.join(installDir, candidate))) ?? APP_BUNDLE_CANDIDATES[0]);
+}
+function resolveLaunchBinary(installDir) {
+    const candidates = LAUNCH_FILE_CANDIDATES[OS_NAME].map((launchFile) => {
+        if (OS_NAME === "mac") {
+            return path.resolve(installDir, resolveMacAppBundle(installDir), "Contents", "Resources", launchFile);
+        }
+        return path.join(installDir, launchFile);
+    });
+    return candidates.find((candidate) => fs.existsSync(candidate)) ?? null;
+}
+class Version {
+    release;
+    version;
+    sorted_rel;
+    constructor(release, version) {
+        this.release = release;
+        this.version = version;
+        this.sorted_rel = this.buildSortedRel();
+    }
+    buildSortedRel() {
+        const parts = this.release
+            .split(".")
+            .map((x) => Number.isNaN(Number(x)) ? x.charCodeAt(0) - 1024 : Number(x));
+        while (parts.length < 5) {
+            parts.push(0);
+        }
+        return parts;
+    }
+    get fullString() {
+        return `${this.version}-${this.release}`;
+    }
+    equals(other) {
+        return this.sorted_rel.join(".") === other.sorted_rel.join(".");
+    }
+    lessThan(other) {
+        for (let i = 0; i < this.sorted_rel.length; i++) {
+            if (this.sorted_rel[i] < other.sorted_rel[i])
+                return true;
+            if (this.sorted_rel[i] > other.sorted_rel[i])
+                return false;
+        }
+        return false;
+    }
+    isSupported() {
+        return VERSION_MIN.lessThan(this) && this.lessThan(VERSION_MAX);
+    }
+    static fromPath(filePath = INSTALL_DIR) {
+        const versionPath = path.join(filePath.toString(), "version.json");
+        if (!fs.existsSync(versionPath)) {
+            throw new FileNotFoundError(`Version information not found at ${versionPath}. Please run \`headfox-js fetch\` to install.`);
+        }
+        const versionData = JSON.parse(fs.readFileSync(versionPath, "utf-8"));
+        return new Version(versionData.release, versionData.version);
+    }
+    static isSupportedPath(path) {
+        return Version.fromPath(path).isSupported();
+    }
+    static buildMinMax() {
+        return [
+            new Version(CONSTRAINTS.MIN_VERSION),
+            new Version(CONSTRAINTS.MAX_VERSION),
+        ];
+    }
+}
+const [VERSION_MIN, VERSION_MAX] = Version.buildMinMax();
+export class GitHubDownloader {
+    githubRepo;
+    apiUrl;
+    constructor(githubRepo) {
+        this.githubRepo = githubRepo;
+        this.apiUrl = `https://api.github.com/repos/${githubRepo}/releases`;
+    }
+    checkAsset(asset) {
+        return asset.browser_download_url;
+    }
+    missingAssetError() {
+        throw new MissingRelease(`Could not find a release asset in ${this.githubRepo}.`);
+    }
+    async getAsset({ retries } = { retries: 5 }) {
+        let attempts = 0;
+        let response;
+        while (attempts < retries) {
+            try {
+                response = await fetch(this.apiUrl);
+                if (response.ok)
+                    break;
+            }
+            catch (e) {
+                console.error(e, `retrying (${attempts + 1}/${retries})...`);
+                await setTimeout(5e3);
+            }
+            attempts++;
+        }
+        if (!response || !response.ok) {
+            throw new Error(`Failed to fetch releases from ${this.apiUrl} after ${retries} attempts`);
+        }
+        const releases = await response.json();
+        for (const release of releases) {
+            for (const asset of release.assets) {
+                const data = this.checkAsset(asset);
+                if (data) {
+                    return data;
+                }
+            }
+        }
+        this.missingAssetError();
+    }
+}
+export class HeadfoxFetcher extends GitHubDownloader {
+    arch;
+    _version_obj;
+    pattern;
+    _url;
+    constructor() {
+        super(RELEASE_REPO);
+        this.arch = HeadfoxFetcher.getPlatformArch();
+        this.pattern = new RegExp(`(?:${ASSET_PREFIXES.join("|")})-(.+)-(.+)-${OS_NAME}\\.${this.arch}\\.zip`);
+    }
+    async init() {
+        await this.fetchLatest();
+    }
+    checkAsset(asset) {
+        const match = asset.name.match(this.pattern);
+        if (!match)
+            return null;
+        const version = new Version(match[2], match[1]);
+        if (!version.isSupported())
+            return null;
+        return [version, asset.browser_download_url];
+    }
+    missingAssetError() {
+        throw new MissingRelease(`No matching release found for ${OS_NAME} ${this.arch} in the supported range: (${CONSTRAINTS.asRange()}). Please update the library.`);
+    }
+    static getPlatformArch() {
+        const platArch = os.arch().toLowerCase();
+        if (!(platArch in ARCH_MAP)) {
+            throw new UnsupportedArchitecture(`Architecture ${platArch} is not supported`);
+        }
+        const arch = ARCH_MAP[platArch];
+        if (!OS_ARCH_MATRIX[OS_NAME].includes(arch)) {
+            throw new UnsupportedArchitecture(`Architecture ${arch} is not supported for ${OS_NAME}`);
+        }
+        return arch;
+    }
+    async fetchLatest() {
+        if (this._version_obj)
+            return;
+        const releaseData = await this.getAsset();
+        this._version_obj = releaseData[0];
+        this._url = releaseData[1];
+    }
+    static async downloadFile(url) {
+        const response = await fetch(url);
+        return Buffer.from(await response.arrayBuffer());
+    }
+    async extractZip(zipFile) {
+        const zip = new AdmZip(zipFile);
+        zip.extractAllTo(INSTALL_DIR.toString(), true);
+    }
+    static cleanup() {
+        if (fs.existsSync(INSTALL_DIR)) {
+            fs.rmSync(INSTALL_DIR, { recursive: true });
+            return true;
+        }
+        return false;
+    }
+    setVersion() {
+        fs.writeFileSync(path.join(INSTALL_DIR.toString(), "version.json"), JSON.stringify({ version: this.version, release: this.release }));
+    }
+    async install() {
+        await this.init();
+        HeadfoxFetcher.cleanup();
+        try {
+            fs.mkdirSync(INSTALL_DIR, { recursive: true });
+            const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "headfox-"));
+            const tempFilePath = path.join(tempDir, "headfox.zip");
+            const tempFileStream = fs.createWriteStream(tempFilePath);
+            await webdl(this.url, "Downloading Headfox...", true, tempFileStream);
+            await new Promise((r) => tempFileStream.close(r));
+            await this.extractZip(tempFilePath);
+            this.setVersion();
+            if (OS_NAME !== "win") {
+                await chmodTree(INSTALL_DIR, 0o755);
+            }
+            console.log("Headfox successfully installed.");
+        }
+        catch (e) {
+            console.error(`Error installing Headfox: ${e}`);
+            HeadfoxFetcher.cleanup();
+            throw e;
+        }
+    }
+    get url() {
+        if (!this._url) {
+            throw new Error("Url is not available. Make sure to run fetchLatest first.");
+        }
+        return this._url;
+    }
+    get version() {
+        if (!this._version_obj || !this._version_obj.version) {
+            throw new Error("Version is not available. Make sure to run fetchLatest first.");
+        }
+        return this._version_obj.version;
+    }
+    get release() {
+        if (!this._version_obj) {
+            throw new Error("Release information is not available. Make sure to run the installation first.");
+        }
+        return this._version_obj.release;
+    }
+    get verstr() {
+        if (!this._version_obj) {
+            throw new Error("Version is not available. Make sure to run the installation first.");
+        }
+        return this._version_obj.fullString;
+    }
+}
+function userCacheDir(appName) {
+    if (OS_NAME === "win") {
+        return path.join(os.homedir(), "AppData", "Local", appName, appName, "Cache");
+    }
+    else if (OS_NAME === "mac") {
+        return path.join(os.homedir(), "Library", "Caches", appName);
+    }
+    else {
+        return path.join(os.homedir(), ".cache", appName);
+    }
+}
+export function installedVerStr() {
+    return Version.fromPath(getInstalledBrowserDir()).fullString;
+}
+export function isBrowserInstalled() {
+    if (!isInstallDirReady()) {
+        return false;
+    }
+    try {
+        return Version.isSupportedPath(INSTALL_DIR);
+    }
+    catch {
+        return false;
+    }
+}
+export async function ensureBrowserInstalled() {
+    if (isBrowserInstalled()) {
+        return INSTALL_DIR;
+    }
+    const fetcher = new HeadfoxFetcher();
+    await fetcher.install();
+    return getInstalledBrowserDir();
+}
+export function getInstalledBrowserDir() {
+    if (!isInstallDirReady()) {
+        throw new HeadfoxNotInstalled(installMissingMessage());
+    }
+    if (!Version.isSupportedPath(INSTALL_DIR)) {
+        throw new UnsupportedVersion("The installed Headfox binary is outdated.");
+    }
+    return INSTALL_DIR;
+}
+export function headfoxPath(downloadIfMissing = false) {
+    if (downloadIfMissing) {
+        throw new Error("headfoxPath() no longer performs background installs. Await `ensureBrowserInstalled()` or call `launchOptions()` / `Headfox()` instead.");
+    }
+    return getInstalledBrowserDir();
+}
+export const camoufoxPath = headfoxPath;
+export const CamoufoxFetcher = HeadfoxFetcher;
+export function getPath(file) {
+    const installDir = headfoxPath();
+    if (OS_NAME === "mac") {
+        return path.resolve(installDir, resolveMacAppBundle(installDir), "Contents", "Resources", file);
+    }
+    return path.join(installDir, file);
+}
+export function launchPath() {
+    const installDir = headfoxPath();
+    const executablePath = resolveLaunchBinary(installDir);
+    if (!executablePath) {
+        throw new HeadfoxNotInstalled(installMissingMessage("Headfox"));
+    }
+    return executablePath;
+}
+export async function webdl(url, desc = "", bar = true, buffer = null, { retries } = { retries: 5 }) {
+    let attempts = 0;
+    let response;
+    while (attempts < retries) {
+        try {
+            response = await fetch(url);
+            if (response.ok)
+                break;
+        }
+        catch (e) {
+            console.error(e, `retrying (${attempts + 1}/${retries})...`);
+            await setTimeout(5e3);
+        }
+        attempts++;
+    }
+    if (!response || !response.ok) {
+        throw new Error(`Failed to download from ${url} after ${retries} attempts`);
+    }
+    const totalSize = parseInt(response.headers.get("content-length") || "0", 10);
+    let progressBar = null;
+    if (bar && totalSize > 0) {
+        progressBar = new cliProgress.SingleBar({
+            format: `${desc} [{bar}] {percentage}% | ETA: {eta_formatted} | {value}/{total}`,
+            formatValue: formatBytes,
+            noTTYOutput: true,
+        }, cliProgress.Presets.shades_classic);
+        progressBar.start(totalSize, 0);
+    }
+    const chunks = [];
+    try {
+        if (!response.body) {
+            throw new Error(`Response body was empty while downloading ${desc}`);
+        }
+        for await (const chunk of response.body) {
+            if (buffer) {
+                buffer.write(chunk);
+            }
+            else {
+                chunks.push(chunk);
+            }
+            if (progressBar) {
+                progressBar.increment(chunk.length);
+            }
+        }
+    }
+    finally {
+        progressBar?.stop();
+    }
+    return Buffer.concat(chunks);
+}
+export async function unzip(zipFile, extractPath, desc, bar = true) {
+    const zip = new AdmZip(zipFile);
+    const zipEntries = zip.getEntries();
+    if (bar) {
+        console.log(desc || "Extracting files...");
+    }
+    for (const entry of zipEntries) {
+        if (bar) {
+            console.log(`Extracting ${entry.entryName}`);
+        }
+        zip.extractEntryTo(entry, extractPath, false, true);
+    }
+    if (bar) {
+        console.log("Extraction complete.");
+    }
+}

package/dist/server.d.ts

@@ -0,0 +1,7 @@
+import { type BrowserServer } from "playwright-core";
+import { type LaunchOptions } from "./utils.js";
+export declare function launchHeadfoxServer({ port, ws_path, ...options }: LaunchOptions | {
+    port?: number;
+    ws_path?: string;
+}): Promise<BrowserServer>;
+export declare const launchServer: typeof launchHeadfoxServer;

package/dist/server.js

@@ -0,0 +1,24 @@
+import { firefox } from "playwright-core";
+import { InvalidDebugPort } from "./exceptions.js";
+import { launchOptions } from "./utils.js";
+function assertValidServerOptions(port, wsPath) {
+    if (port !== undefined &&
+        (!Number.isInteger(port) || port < 1 || port > 65535)) {
+        throw new InvalidDebugPort(`Headfox server port must be an integer between 1 and 65535. Received: ${port}`);
+    }
+    if (wsPath && !wsPath.startsWith("/")) {
+        throw new Error(`Headfox server ws_path must start with "/". Received: ${wsPath}`);
+    }
+}
+export async function launchHeadfoxServer({ port, ws_path, ...options }) {
+    // Extract and normalize headless (virtual is treated as true for server mode)
+    const { headless, ...restOptions } = options;
+    const normalizedHeadless = headless === "virtual" ? true : headless;
+    assertValidServerOptions(port, ws_path);
+    return firefox.launchServer({
+        ...(await launchOptions({ ...restOptions, headless: normalizedHeadless })),
+        port,
+        wsPath: ws_path,
+    });
+}
+export const launchServer = launchHeadfoxServer;

package/dist/sync_api.d.ts

@@ -0,0 +1,10 @@
+import { type Browser, type BrowserContext, type BrowserType } from "playwright-core";
+import { type LaunchOptions } from "./utils.js";
+export declare function Camoufox<UserDataDir extends string | undefined = undefined, ReturnType = UserDataDir extends string ? BrowserContext : Browser>(launch_options?: LaunchOptions & {
+    user_data_dir?: UserDataDir;
+}): Promise<ReturnType>;
+export declare function Headfox<UserDataDir extends string | undefined = undefined, ReturnType = UserDataDir extends string ? BrowserContext : Browser>(launch_options?: LaunchOptions & {
+    user_data_dir?: UserDataDir;
+}): Promise<ReturnType>;
+export declare function NewBrowser<UserDataDir extends string | false = false, ReturnType = UserDataDir extends string ? BrowserContext : Browser>(playwright: BrowserType<Browser>, headless?: boolean | "virtual", fromOptions?: Record<string, any>, userDataDir?: UserDataDir, debug?: boolean, launch_options?: LaunchOptions): Promise<ReturnType>;
+export declare function launchWithHeadfox<UserDataDir extends string | false = false, ReturnType = UserDataDir extends string ? BrowserContext : Browser>(playwright: BrowserType<Browser>, headless?: boolean | "virtual", fromOptions?: Record<string, any>, userDataDir?: UserDataDir, debug?: boolean, launch_options?: LaunchOptions): Promise<ReturnType>;

package/dist/sync_api.js

@@ -0,0 +1,35 @@
+import { firefox, } from "playwright-core";
+import { launchOptions, syncAttachVD } from "./utils.js";
+import { VirtualDisplay } from "./virtdisplay.js";
+export async function Camoufox(launch_options = {}) {
+    return Headfox(launch_options);
+}
+export async function Headfox(launch_options = {}) {
+    const { headless, user_data_dir, ...launchOptions } = launch_options;
+    return launchWithHeadfox(firefox, headless, {}, user_data_dir ?? false, false, launchOptions);
+}
+export async function NewBrowser(playwright, headless = false, fromOptions = {}, userDataDir = false, debug = false, launch_options = {}) {
+    return launchWithHeadfox(playwright, headless, fromOptions, userDataDir, debug, launch_options);
+}
+export async function launchWithHeadfox(playwright, headless = false, fromOptions = {}, userDataDir = false, debug = false, launch_options = {}) {
+    let virtualDisplay = null;
+    // Normalize headless to boolean and prepare options for launchOptions function
+    const normalizedHeadless = headless === "virtual" ? false : headless || false;
+    if (headless === "virtual") {
+        virtualDisplay = new VirtualDisplay(debug);
+        launch_options.virtual_display = virtualDisplay.get();
+    }
+    if (!fromOptions || Object.keys(fromOptions).length === 0) {
+        fromOptions = await launchOptions({
+            debug,
+            ...launch_options,
+            headless: normalizedHeadless,
+        });
+    }
+    if (typeof userDataDir === "string") {
+        const context = await playwright.launchPersistentContext(userDataDir, fromOptions);
+        return syncAttachVD(context, virtualDisplay);
+    }
+    const browser = await playwright.launch(fromOptions);
+    return syncAttachVD(browser, virtualDisplay);
+}