browser-use 0.0.1 → 0.0.2

package/dist/browser/index.js

@@ -0,0 +1,9 @@
+export * from './profile.js';
+export * from './views.js';
+export * from './utils.js';
+export * from './session.js';
+export * from './extensions.js';
+export * from './dvd-screensaver.js';
+export * from './playwright-manager.js';
+// Re-export the async playwright loader
+export { async_playwright } from './types.js';

package/dist/browser/playwright-manager.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Playwright Global Singleton Manager
+ *
+ * Manages Playwright instances at the event loop level to prevent
+ * duplicate instantiation and ensure proper resource cleanup.
+ *
+ * This is important because:
+ * 1. Playwright instances are heavy and should be reused
+ * 2. Multiple instances can cause port conflicts
+ * 3. Proper cleanup prevents resource leaks
+ */
+/**
+ * Get or create a Playwright instance for the current event loop
+ * Uses singleton pattern to prevent duplicate instances
+ */
+export declare function getPlaywrightInstance(options?: {
+    browserType?: 'chromium' | 'firefox' | 'webkit';
+    forceNew?: boolean;
+}): Promise<any>;
+/**
+ * Release a Playwright instance reference
+ * Decrements reference count and cleans up if no more references
+ */
+export declare function releasePlaywrightInstance(browserType?: 'chromium' | 'firefox' | 'webkit'): Promise<void>;
+/**
+ * Force cleanup of all Playwright instances
+ * Should be called on process exit
+ */
+export declare function cleanupAllPlaywrightInstances(): Promise<void>;
+/**
+ * Register a cleanup handler to be called on shutdown
+ */
+export declare function registerCleanupHandler(handler: () => Promise<void>): void;
+/**
+ * Unregister a cleanup handler
+ */
+export declare function unregisterCleanupHandler(handler: () => Promise<void>): void;
+/**
+ * Get statistics about Playwright instances
+ */
+export declare function getPlaywrightStats(): {
+    totalInstances: number;
+    instances: Array<{
+        key: string;
+        refs: number;
+    }>;
+};

package/dist/browser/playwright-manager.js

@@ -0,0 +1,146 @@
+/**
+ * Playwright Global Singleton Manager
+ *
+ * Manages Playwright instances at the event loop level to prevent
+ * duplicate instantiation and ensure proper resource cleanup.
+ *
+ * This is important because:
+ * 1. Playwright instances are heavy and should be reused
+ * 2. Multiple instances can cause port conflicts
+ * 3. Proper cleanup prevents resource leaks
+ */
+import { createLogger } from '../logging-config.js';
+const logger = createLogger('browser_use.playwright_manager');
+// Global registry of Playwright instances keyed by event loop/process
+const playwrightInstances = new Map();
+const instanceRefCounts = new Map();
+// Track cleanup handlers
+const cleanupHandlers = new Set();
+/**
+ * Get or create a Playwright instance for the current event loop
+ * Uses singleton pattern to prevent duplicate instances
+ */
+export async function getPlaywrightInstance(options = {}) {
+    const { browserType = 'chromium', forceNew = false } = options;
+    // Use process ID as key for singleton (Node.js is single event loop per process)
+    const instanceKey = `${process.pid}-${browserType}`;
+    // Return existing instance if available and not forcing new
+    if (!forceNew && playwrightInstances.has(instanceKey)) {
+        const instance = playwrightInstances.get(instanceKey);
+        // Increment reference count
+        instanceRefCounts.set(instanceKey, (instanceRefCounts.get(instanceKey) || 0) + 1);
+        logger.debug(`Reusing Playwright ${browserType} instance (refs: ${instanceRefCounts.get(instanceKey)})`);
+        return instance;
+    }
+    // Create new instance
+    logger.info(`Creating new Playwright ${browserType} instance`);
+    try {
+        const playwright = await import('playwright');
+        const instance = playwright[browserType];
+        // Store instance
+        playwrightInstances.set(instanceKey, instance);
+        instanceRefCounts.set(instanceKey, 1);
+        logger.debug(`Playwright ${browserType} instance created successfully`);
+        return instance;
+    }
+    catch (error) {
+        logger.error(`Failed to create Playwright instance: ${error.message}`);
+        throw error;
+    }
+}
+/**
+ * Release a Playwright instance reference
+ * Decrements reference count and cleans up if no more references
+ */
+export async function releasePlaywrightInstance(browserType = 'chromium') {
+    const instanceKey = `${process.pid}-${browserType}`;
+    if (!playwrightInstances.has(instanceKey)) {
+        logger.warning(`Attempted to release non-existent Playwright instance: ${instanceKey}`);
+        return;
+    }
+    // Decrement reference count
+    const currentRefs = instanceRefCounts.get(instanceKey) || 0;
+    const newRefs = Math.max(0, currentRefs - 1);
+    instanceRefCounts.set(instanceKey, newRefs);
+    logger.debug(`Released Playwright ${browserType} instance reference (refs: ${newRefs})`);
+    // If no more references, we could clean up, but Playwright itself doesn't need cleanup
+    // The actual browser instances are cleaned up separately
+    if (newRefs === 0) {
+        logger.debug(`No more references to Playwright ${browserType} instance, keeping for reuse`);
+        // We keep the instance for potential reuse rather than deleting it
+    }
+}
+/**
+ * Force cleanup of all Playwright instances
+ * Should be called on process exit
+ */
+export async function cleanupAllPlaywrightInstances() {
+    logger.info(`Cleaning up ${playwrightInstances.size} Playwright instances`);
+    // Execute all registered cleanup handlers
+    const cleanupPromises = Array.from(cleanupHandlers).map((handler) => handler().catch((error) => {
+        logger.error(`Cleanup handler failed: ${error.message}`);
+    }));
+    await Promise.all(cleanupPromises);
+    // Clear registries
+    playwrightInstances.clear();
+    instanceRefCounts.clear();
+    cleanupHandlers.clear();
+    logger.info('All Playwright instances cleaned up');
+}
+/**
+ * Register a cleanup handler to be called on shutdown
+ */
+export function registerCleanupHandler(handler) {
+    cleanupHandlers.add(handler);
+}
+/**
+ * Unregister a cleanup handler
+ */
+export function unregisterCleanupHandler(handler) {
+    cleanupHandlers.delete(handler);
+}
+/**
+ * Get statistics about Playwright instances
+ */
+export function getPlaywrightStats() {
+    return {
+        totalInstances: playwrightInstances.size,
+        instances: Array.from(playwrightInstances.keys()).map((key) => ({
+            key,
+            refs: instanceRefCounts.get(key) || 0,
+        })),
+    };
+}
+// Setup process exit handlers
+let exitHandlersRegistered = false;
+function registerExitHandlers() {
+    if (exitHandlersRegistered) {
+        return;
+    }
+    exitHandlersRegistered = true;
+    const exitHandler = async (signal) => {
+        logger.debug(`Received ${signal}, cleaning up Playwright instances...`);
+        await cleanupAllPlaywrightInstances();
+        process.exit(0);
+    };
+    // Register handlers for various exit signals
+    process.on('SIGINT', () => exitHandler('SIGINT'));
+    process.on('SIGTERM', () => exitHandler('SIGTERM'));
+    process.on('exit', () => {
+        // Synchronous cleanup on exit
+        logger.debug('Process exiting, Playwright cleanup complete');
+    });
+    // Handle uncaught exceptions
+    process.on('uncaughtException', async (error) => {
+        logger.error(`Uncaught exception: ${error.message}`);
+        await cleanupAllPlaywrightInstances();
+        process.exit(1);
+    });
+    process.on('unhandledRejection', async (reason) => {
+        logger.error(`Unhandled rejection: ${reason}`);
+        await cleanupAllPlaywrightInstances();
+        process.exit(1);
+    });
+}
+// Auto-register exit handlers on module load
+registerExitHandlers();

package/dist/browser/profile.d.ts

@@ -0,0 +1,196 @@
+import type { ClientCertificate, Geolocation, HttpCredentials, ProxySettings, ViewportSize, StorageState } from './types.js';
+export declare const CHROME_DEBUG_PORT = 9242;
+export declare const CHROME_DISABLED_COMPONENTS: string[];
+export declare const CHROME_HEADLESS_ARGS: string[];
+export declare const CHROME_DOCKER_ARGS: string[];
+export declare const CHROME_DISABLE_SECURITY_ARGS: string[];
+export declare const CHROME_DETERMINISTIC_RENDERING_ARGS: string[];
+export declare const CHROME_DEFAULT_ARGS: string[];
+export declare const get_display_size: () => ViewportSize | null;
+export declare const get_window_adjustments: () => [number, number];
+export declare enum ColorScheme {
+    LIGHT = "light",
+    DARK = "dark",
+    NO_PREFERENCE = "no-preference",
+    NULL = "null"
+}
+export declare enum Contrast {
+    NO_PREFERENCE = "no-preference",
+    MORE = "more",
+    NULL = "null"
+}
+export declare enum ReducedMotion {
+    REDUCE = "reduce",
+    NO_PREFERENCE = "no-preference",
+    NULL = "null"
+}
+export declare enum ForcedColors {
+    ACTIVE = "active",
+    NONE = "none",
+    NULL = "null"
+}
+export declare enum ServiceWorkers {
+    ALLOW = "allow",
+    BLOCK = "block"
+}
+export declare enum RecordHarContent {
+    OMIT = "omit",
+    EMBED = "embed",
+    ATTACH = "attach"
+}
+export declare enum RecordHarMode {
+    FULL = "full",
+    MINIMAL = "minimal"
+}
+export declare enum BrowserChannel {
+    CHROMIUM = "chromium",
+    CHROME = "chrome",
+    CHROME_BETA = "chrome-beta",
+    CHROME_DEV = "chrome-dev",
+    CHROME_CANARY = "chrome-canary",
+    MSEDGE = "msedge",
+    MSEDGE_BETA = "msedge-beta",
+    MSEDGE_DEV = "msedge-dev",
+    MSEDGE_CANARY = "msedge-canary"
+}
+export declare const BROWSERUSE_DEFAULT_CHANNEL = BrowserChannel.CHROMIUM;
+type Nullable<T> = T | null;
+type WindowRect = {
+    width: number;
+    height: number;
+};
+export interface BrowserContextArgs {
+    accept_downloads: boolean;
+    offline: boolean;
+    strict_selectors: boolean;
+    proxy: Nullable<ProxySettings>;
+    permissions: string[];
+    bypass_csp: boolean;
+    client_certificates: ClientCertificate[];
+    extra_http_headers: Record<string, string>;
+    http_credentials: Nullable<HttpCredentials>;
+    ignore_https_errors: boolean;
+    java_script_enabled: boolean;
+    base_url: Nullable<string>;
+    service_workers: ServiceWorkers;
+    user_agent: Nullable<string>;
+    screen: Nullable<ViewportSize>;
+    viewport: Nullable<ViewportSize>;
+    no_viewport: Nullable<boolean>;
+    device_scale_factor: Nullable<number>;
+    is_mobile: boolean;
+    has_touch: boolean;
+    locale: Nullable<string>;
+    geolocation: Nullable<Geolocation>;
+    timezone_id: Nullable<string>;
+    color_scheme: ColorScheme;
+    contrast: Contrast;
+    reduced_motion: ReducedMotion;
+    forced_colors: ForcedColors;
+    record_har_content: RecordHarContent;
+    record_har_mode: RecordHarMode;
+    record_har_omit_content: boolean;
+    record_har_path: Nullable<string>;
+    record_har_url_filter: Nullable<string | RegExp>;
+    record_video_dir: Nullable<string>;
+    record_video_size: Nullable<ViewportSize>;
+}
+export interface BrowserConnectArgs {
+    headers: Nullable<Record<string, string>>;
+    slow_mo: number;
+    timeout: number;
+}
+export interface BrowserLaunchArgs {
+    env: Nullable<Record<string, string | number | boolean>>;
+    executable_path: Nullable<string>;
+    headless: Nullable<boolean>;
+    args: string[];
+    ignore_default_args: string[] | true;
+    channel: Nullable<BrowserChannel>;
+    chromium_sandbox: boolean;
+    devtools: boolean;
+    slow_mo: number;
+    timeout: number;
+    proxy: Nullable<ProxySettings>;
+    downloads_path: Nullable<string>;
+    traces_dir: Nullable<string>;
+    handle_sighup: boolean;
+    handle_sigint: boolean;
+    handle_sigterm: boolean;
+}
+export type BrowserNewContextArgs = BrowserContextArgs & {
+    storage_state: Nullable<string | StorageState | Record<string, unknown>>;
+};
+export type BrowserLaunchPersistentContextArgs = BrowserContextArgs & BrowserLaunchArgs & {
+    user_data_dir: Nullable<string>;
+};
+export interface BrowserProfileSpecificOptions {
+    id: string;
+    user_data_dir: Nullable<string>;
+    storage_state: Nullable<string | StorageState | Record<string, unknown>>;
+    stealth: boolean;
+    disable_security: boolean;
+    deterministic_rendering: boolean;
+    allowed_domains: Nullable<string[]>;
+    keep_alive: Nullable<boolean>;
+    enable_default_extensions: boolean;
+    window_size: Nullable<ViewportSize>;
+    window_height: Nullable<number>;
+    window_width: Nullable<number>;
+    window_position: Nullable<WindowRect>;
+    default_navigation_timeout: Nullable<number>;
+    default_timeout: Nullable<number>;
+    minimum_wait_page_load_time: number;
+    wait_for_network_idle_page_load_time: number;
+    maximum_wait_page_load_time: number;
+    wait_between_actions: number;
+    include_dynamic_attributes: boolean;
+    highlight_elements: boolean;
+    viewport_expansion: number;
+    profile_directory: string;
+    cookies_file: Nullable<string>;
+}
+export type BrowserProfileOptions = BrowserContextArgs & BrowserLaunchArgs & BrowserConnectArgs & BrowserProfileSpecificOptions;
+export declare class BrowserProfile {
+    private options;
+    constructor(init?: Partial<BrowserProfileOptions>);
+    toString(): string;
+    describe(): string;
+    get config(): BrowserProfileOptions;
+    get allowed_domains(): Nullable<string[]>;
+    get cookies_file(): Nullable<string>;
+    get default_navigation_timeout(): Nullable<number>;
+    get downloads_path(): Nullable<string>;
+    get highlight_elements(): boolean;
+    get keep_alive(): boolean | null;
+    set keep_alive(value: boolean | null);
+    get maximum_wait_page_load_time(): number;
+    get traces_dir(): Nullable<string>;
+    get user_data_dir(): Nullable<string>;
+    get viewport_expansion(): number;
+    get viewport(): Nullable<import("playwright-core").ViewportSize>;
+    get wait_for_network_idle_page_load_time(): number;
+    get window_size(): Nullable<import("playwright-core").ViewportSize>;
+    private applyLegacyWindowSize;
+    private warnStorageStateUserDataDirConflict;
+    private warnUserDataDirNonDefault;
+    private warnDeterministicRenderingWeirdness;
+    private getDefaultArgsList;
+    private getWindowSizeArgs;
+    private getWindowPositionArgs;
+    private getExtensionArgs;
+    private ensureDefaultExtensionsDownloaded;
+    private downloadExtension;
+    private extractExtension;
+    private stripCrxHeader;
+    getArgs(): Promise<string[]>;
+    detect_display_configuration(): Promise<any>;
+    private cloneContextArgs;
+    private cloneLaunchArgs;
+    kwargs_for_new_context(): BrowserNewContextArgs;
+    kwargs_for_connect(): BrowserConnectArgs;
+    kwargs_for_launch(): Promise<BrowserLaunchArgs>;
+    kwargs_for_launch_persistent_context(): Promise<BrowserLaunchPersistentContextArgs>;
+}
+export declare const DEFAULT_BROWSER_PROFILE: BrowserProfile;
+export {};