browser-use 0.0.1 → 0.1.0

package/dist/browser/dvd-screensaver.js

@@ -0,0 +1,270 @@
+/**
+ * DVD Screensaver Loading Animation
+ *
+ * Displays a fun DVD logo bouncing animation while waiting for browser operations.
+ * Inspired by the classic DVD screensaver.
+ */
+import { createLogger } from '../logging-config.js';
+const logger = createLogger('browser_use.dvd_screensaver');
+/**
+ * DVD Screensaver Animation Controller
+ */
+export class DVDScreensaver {
+    isRunning = false;
+    intervalId = null;
+    width = 80;
+    height = 20;
+    x = 0;
+    y = 0;
+    dx = 1;
+    dy = 1;
+    logoWidth = 10;
+    logoHeight = 3;
+    colors = [
+        '\x1b[31m',
+        '\x1b[32m',
+        '\x1b[33m',
+        '\x1b[34m',
+        '\x1b[35m',
+        '\x1b[36m',
+    ];
+    currentColorIndex = 0;
+    cornerHits = 0;
+    frameCount = 0;
+    message;
+    constructor(message = 'Loading...') {
+        this.message = message;
+        this.x = Math.floor(Math.random() * (this.width - this.logoWidth));
+        this.y = Math.floor(Math.random() * (this.height - this.logoHeight));
+    }
+    /**
+     * Start the animation
+     */
+    start(fps = 10) {
+        if (this.isRunning) {
+            return;
+        }
+        this.isRunning = true;
+        // Hide cursor
+        process.stderr.write('\x1b[?25l');
+        // Clear screen
+        this.clear();
+        this.intervalId = setInterval(() => {
+            this.update();
+            this.render();
+        }, 1000 / fps);
+    }
+    /**
+     * Stop the animation
+     */
+    stop() {
+        if (!this.isRunning) {
+            return;
+        }
+        this.isRunning = false;
+        if (this.intervalId) {
+            clearInterval(this.intervalId);
+            this.intervalId = null;
+        }
+        // Clear screen one last time
+        this.clear();
+        // Show cursor
+        process.stderr.write('\x1b[?25h');
+        // Log corner hits if any
+        if (this.cornerHits > 0) {
+            logger.debug(`DVD logo hit corner ${this.cornerHits} time(s)! 🎯`);
+        }
+    }
+    /**
+     * Update logo position
+     */
+    update() {
+        this.frameCount++;
+        // Update position
+        this.x += this.dx;
+        this.y += this.dy;
+        let hitCorner = false;
+        // Check horizontal bounds
+        if (this.x <= 0 || this.x >= this.width - this.logoWidth) {
+            this.dx = -this.dx;
+            this.x = Math.max(0, Math.min(this.x, this.width - this.logoWidth));
+            this.changeColor();
+            // Check if hit corner
+            if (this.y <= 0 || this.y >= this.height - this.logoHeight) {
+                hitCorner = true;
+            }
+        }
+        // Check vertical bounds
+        if (this.y <= 0 || this.y >= this.height - this.logoHeight) {
+            this.dy = -this.dy;
+            this.y = Math.max(0, Math.min(this.y, this.height - this.logoHeight));
+            this.changeColor();
+            // Check if hit corner
+            if (this.x <= 0 || this.x >= this.width - this.logoWidth) {
+                hitCorner = true;
+            }
+        }
+        if (hitCorner) {
+            this.cornerHits++;
+        }
+    }
+    /**
+     * Change logo color
+     */
+    changeColor() {
+        this.currentColorIndex = (this.currentColorIndex + 1) % this.colors.length;
+    }
+    /**
+     * Render the current frame
+     */
+    render() {
+        // Move cursor to top-left
+        process.stderr.write('\x1b[H');
+        const color = this.colors[this.currentColorIndex];
+        const reset = '\x1b[0m';
+        // Build frame
+        const frame = [];
+        // Draw border and content
+        for (let row = 0; row < this.height; row++) {
+            let line = '';
+            for (let col = 0; col < this.width; col++) {
+                // Check if this position is part of the logo
+                if (row >= this.y &&
+                    row < this.y + this.logoHeight &&
+                    col >= this.x &&
+                    col < this.x + this.logoWidth) {
+                    // Draw logo
+                    const logoRow = row - this.y;
+                    const logoCol = col - this.x;
+                    line += color + this.getLogoChar(logoRow, logoCol) + reset;
+                }
+                else if (row === 0 ||
+                    row === this.height - 1 ||
+                    col === 0 ||
+                    col === this.width - 1) {
+                    // Draw border
+                    line += '·';
+                }
+                else {
+                    line += ' ';
+                }
+            }
+            frame.push(line);
+        }
+        // Add status message
+        const statusLine = `\n${this.message} (Frame: ${this.frameCount}, Corner hits: ${this.cornerHits})`;
+        // Write frame to stderr
+        process.stderr.write(frame.join('\n') + statusLine);
+    }
+    /**
+     * Get character for logo at specific position
+     */
+    getLogoChar(row, col) {
+        // Simple "DVD" text logo
+        if (row === 1) {
+            const text = '   DVD   ';
+            return col < text.length ? text[col] : ' ';
+        }
+        return '▓';
+    }
+    /**
+     * Clear screen
+     */
+    clear() {
+        process.stderr.write('\x1b[2J\x1b[H');
+    }
+}
+/**
+ * Show DVD screensaver loading animation
+ * Returns a function to stop the animation
+ *
+ * @param message - Message to display
+ * @param fps - Frames per second (default: 10)
+ * @returns Function to stop the animation
+ *
+ * @example
+ * const stopAnimation = showDVDScreensaver('Loading browser...');
+ * await someAsyncOperation();
+ * stopAnimation();
+ */
+export function showDVDScreensaver(message = 'Loading...', fps = 10) {
+    const screensaver = new DVDScreensaver(message);
+    screensaver.start(fps);
+    return () => {
+        screensaver.stop();
+    };
+}
+/**
+ * Run an async operation with DVD screensaver animation
+ *
+ * @param operation - Async operation to run
+ * @param message - Message to display
+ * @returns Result of the operation
+ *
+ * @example
+ * const result = await withDVDScreensaver(
+ *   async () => await longRunningOperation(),
+ *   'Processing...'
+ * );
+ */
+export async function withDVDScreensaver(operation, message = 'Loading...') {
+    const stopAnimation = showDVDScreensaver(message);
+    try {
+        const result = await operation();
+        return result;
+    }
+    finally {
+        stopAnimation();
+    }
+}
+/**
+ * Simple spinner animation (alternative to DVD screensaver)
+ */
+export class SpinnerAnimation {
+    isRunning = false;
+    intervalId = null;
+    frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+    currentFrame = 0;
+    message;
+    constructor(message = 'Loading...') {
+        this.message = message;
+    }
+    start(fps = 10) {
+        if (this.isRunning) {
+            return;
+        }
+        this.isRunning = true;
+        process.stderr.write('\x1b[?25l'); // Hide cursor
+        this.intervalId = setInterval(() => {
+            this.render();
+            this.currentFrame = (this.currentFrame + 1) % this.frames.length;
+        }, 1000 / fps);
+    }
+    stop() {
+        if (!this.isRunning) {
+            return;
+        }
+        this.isRunning = false;
+        if (this.intervalId) {
+            clearInterval(this.intervalId);
+            this.intervalId = null;
+        }
+        // Clear line and show cursor
+        process.stderr.write('\r\x1b[K');
+        process.stderr.write('\x1b[?25h');
+    }
+    render() {
+        const frame = this.frames[this.currentFrame];
+        process.stderr.write(`\r${frame} ${this.message}`);
+    }
+}
+/**
+ * Show simple spinner animation
+ */
+export function showSpinner(message = 'Loading...', fps = 10) {
+    const spinner = new SpinnerAnimation(message);
+    spinner.start(fps);
+    return () => {
+        spinner.stop();
+    };
+}

package/dist/browser/extensions.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Browser Extension Management
+ * Handles Chrome extension download, installation, and runtime integration.
+ * Supports both Manifest V2 and V3 extensions.
+ */
+export interface BrowserExtensionDescriptor {
+    name: string;
+    webstore_id?: string;
+    id?: string;
+    webstore_url?: string;
+    crx_url?: string;
+    crx_path?: string;
+    unpacked_path?: string;
+    version?: string;
+    manifest?: any;
+    manifest_version?: string;
+    homepage_url?: string;
+    options_url?: string;
+    target?: any;
+    target_ctx?: any;
+    target_type?: string;
+    target_url?: string;
+    read_manifest?: () => any;
+    read_version?: () => string | null;
+    dispatch_eval?: (...args: any[]) => Promise<any>;
+    dispatch_popup?: () => Promise<any>;
+    dispatch_action?: (tab?: any) => Promise<any>;
+    dispatch_message?: (message: any, options?: any) => Promise<any>;
+    dispatch_command?: (command: string, tab?: any) => Promise<any>;
+}
+/**
+ * Generate extension ID from unpacked path
+ * Chrome uses SHA256 hash of the directory path
+ */
+export declare function getExtensionId(unpackedPath: string): string | null;
+/**
+ * Load or install extension
+ */
+export declare function loadOrInstallExtension(ext: BrowserExtensionDescriptor, extensionsDir?: string): Promise<BrowserExtensionDescriptor>;
+/**
+ * Check if a browser target is an extension
+ */
+export declare function isTargetExtension(target: any): Promise<{
+    target_type: string | null;
+    target_ctx: any;
+    target_url: string | null;
+    target_is_bg: boolean;
+    target_is_extension: boolean;
+    extension_id: string | null;
+    manifest_version: string;
+}>;
+/**
+ * Load extension from browser target (runtime connection)
+ */
+export declare function loadExtensionFromTarget(extensions: BrowserExtensionDescriptor[], target: any): Promise<BrowserExtensionDescriptor | null>;
+/**
+ * Load all Chrome extensions from browser targets
+ */
+export declare function getChromeExtensionsFromBrowser(browser: any, extensions: BrowserExtensionDescriptor[]): Promise<BrowserExtensionDescriptor[]>;
+/**
+ * Install extensions from persona configuration
+ */
+export declare function installExtensionsFromConfig(extensionConfigs: BrowserExtensionDescriptor[], extensionsDir: string): Promise<BrowserExtensionDescriptor[]>;

package/dist/browser/extensions.js

@@ -0,0 +1,359 @@
+/**
+ * Browser Extension Management
+ * Handles Chrome extension download, installation, and runtime integration.
+ * Supports both Manifest V2 and V3 extensions.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { pipeline } from 'node:stream/promises';
+import { createWriteStream } from 'node:fs';
+import { Readable } from 'node:stream';
+// @ts-ignore - extract-zip types may not be available
+import extract from 'extract-zip';
+import { createLogger } from '../logging-config.js';
+const logger = createLogger('browser_use.extensions');
+/**
+ * Generate extension ID from unpacked path
+ * Chrome uses SHA256 hash of the directory path
+ */
+export function getExtensionId(unpackedPath) {
+    const manifestPath = path.join(unpackedPath, 'manifest.json');
+    if (!fs.existsSync(manifestPath)) {
+        return null;
+    }
+    // Chrome uses SHA256 hash and converts to letter format
+    const hash = createHash('sha256').update(unpackedPath).digest('hex');
+    const extensionId = hash
+        .slice(0, 32)
+        .split('')
+        .map((char) => String.fromCharCode(parseInt(char, 16) + 'a'.charCodeAt(0)))
+        .join('');
+    return extensionId;
+}
+/**
+ * Download CRX file from Chrome Web Store
+ */
+async function downloadCrx(crxUrl, crxPath) {
+    try {
+        logger.info(`[🛠️] Downloading extension from ${crxUrl}...`);
+        const response = await fetch(crxUrl);
+        if (!response.ok || !response.body) {
+            logger.warning(`[⚠️] Failed to download extension: ${response.statusText}`);
+            return false;
+        }
+        // Ensure directory exists
+        const dir = path.dirname(crxPath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        // Download file
+        const fileStream = createWriteStream(crxPath);
+        await pipeline(Readable.fromWeb(response.body), fileStream);
+        logger.info(`[✅] Downloaded to ${crxPath}`);
+        return true;
+    }
+    catch (error) {
+        logger.error(`[❌] Download failed: ${error.message}`);
+        return false;
+    }
+}
+/**
+ * Extract CRX file to unpacked directory
+ */
+async function unpackCrx(crxPath, unpackedPath) {
+    try {
+        // Ensure unpacked directory exists
+        if (!fs.existsSync(unpackedPath)) {
+            fs.mkdirSync(unpackedPath, { recursive: true });
+        }
+        // Extract zip file (CRX is essentially a ZIP with extra header)
+        await extract(crxPath, { dir: path.resolve(unpackedPath) });
+        // Verify manifest exists
+        const manifestPath = path.join(unpackedPath, 'manifest.json');
+        if (!fs.existsSync(manifestPath)) {
+            logger.error(`[❌] No manifest.json found in ${unpackedPath}`);
+            return false;
+        }
+        logger.info(`[✅] Extracted to ${unpackedPath}`);
+        return true;
+    }
+    catch (error) {
+        logger.error(`[❌] Extraction failed: ${error.message}`);
+        return false;
+    }
+}
+/**
+ * Install extension (download and unpack if needed)
+ */
+async function installExtension(extension) {
+    const manifestPath = path.join(extension.unpacked_path, 'manifest.json');
+    const crxPath = extension.crx_path;
+    // Download CRX if neither manifest nor CRX exists
+    if (!fs.existsSync(manifestPath) && !fs.existsSync(crxPath)) {
+        logger.info(`[🛠️] Downloading missing extension ${extension.name} ${extension.webstore_id} -> ${crxPath}`);
+        const downloaded = await downloadCrx(extension.crx_url, crxPath);
+        if (!downloaded) {
+            return false;
+        }
+    }
+    // Unpack CRX if manifest doesn't exist
+    if (!fs.existsSync(manifestPath)) {
+        const unpacked = await unpackCrx(crxPath, extension.unpacked_path);
+        if (!unpacked) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Load or install extension
+ */
+export async function loadOrInstallExtension(ext, extensionsDir = path.join(process.cwd(), '.browser-use', 'extensions')) {
+    if (!ext.webstore_id && !ext.unpacked_path) {
+        throw new Error('Extension must have either webstore_id or unpacked_path');
+    }
+    // Set statically computable extension metadata
+    ext.webstore_id = ext.webstore_id || ext.id;
+    ext.name = ext.name || ext.webstore_id;
+    ext.webstore_url =
+        ext.webstore_url ||
+            `https://chromewebstore.google.com/detail/${ext.webstore_id}`;
+    ext.crx_url =
+        ext.crx_url ||
+            `https://clients2.google.com/service/update2/crx?response=redirect&prodversion=130.0&acceptformat=crx3&x=id%3D${ext.webstore_id}%26uc`;
+    ext.crx_path =
+        ext.crx_path ||
+            path.join(extensionsDir, `${ext.webstore_id}__${ext.name}.crx`);
+    ext.unpacked_path =
+        ext.unpacked_path ||
+            path.join(extensionsDir, `${ext.webstore_id}__${ext.name}`);
+    const manifestPath = path.join(ext.unpacked_path, 'manifest.json');
+    // Helper functions
+    const readManifest = () => {
+        if (fs.existsSync(manifestPath)) {
+            return JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+        }
+        return null;
+    };
+    const readVersion = () => {
+        const manifest = readManifest();
+        return manifest?.version || null;
+    };
+    ext.read_manifest = readManifest;
+    ext.read_version = readVersion;
+    // Install extension if not already installed
+    if (!readVersion()) {
+        await installExtension(ext);
+    }
+    // Auto-detect ID and version
+    ext.id = getExtensionId(ext.unpacked_path) ?? undefined;
+    ext.version = readVersion() ?? undefined;
+    if (!ext.version) {
+        logger.warning(`[❌] Unable to detect ID and version of installed extension ${ext.unpacked_path}`);
+    }
+    else {
+        logger.info(`[➕] Installed extension ${ext.name} (${ext.version})... ${ext.unpacked_path}`);
+    }
+    return ext;
+}
+/**
+ * Check if a browser target is an extension
+ */
+export async function isTargetExtension(target) {
+    let target_type = null;
+    let target_ctx = null;
+    let target_url = null;
+    try {
+        target_type = await target.type();
+        target_ctx = (await target.worker?.()) || (await target.page?.()) || null;
+        target_url =
+            (await target.url?.()) || (target_ctx ? await target_ctx.url() : null);
+    }
+    catch (error) {
+        if (error.message?.includes('No target with given id found')) {
+            // Target already closed
+            target_type = 'closed';
+            target_ctx = null;
+            target_url = 'about:closed';
+        }
+        else {
+            throw error;
+        }
+    }
+    const target_is_bg = ['service_worker', 'background_page'].includes(target_type || '');
+    const target_is_extension = target_url?.startsWith('chrome-extension://') || false;
+    const extension_id = target_is_extension
+        ? target_url.split('://')[1].split('/')[0]
+        : null;
+    const manifest_version = target_type === 'service_worker' ? '3' : '2';
+    return {
+        target_type,
+        target_ctx,
+        target_url,
+        target_is_bg,
+        target_is_extension,
+        extension_id,
+        manifest_version,
+    };
+}
+/**
+ * Load extension from browser target (runtime connection)
+ */
+export async function loadExtensionFromTarget(extensions, target) {
+    const extensionInfo = await isTargetExtension(target);
+    const { target_is_bg, target_is_extension, target_type, target_ctx, target_url, extension_id, manifest_version, } = extensionInfo;
+    if (!target_is_bg || !extension_id || !target_ctx) {
+        return null;
+    }
+    // Get manifest from extension
+    const manifest = await target_ctx.evaluate('() => chrome.runtime.getManifest()');
+    const name = manifest.name;
+    const version = manifest.version;
+    const homepage_url = manifest.homepage_url;
+    const options_page = manifest.options_page;
+    const options_ui = manifest.options_ui || {};
+    if (!version || !extension_id) {
+        return null;
+    }
+    // Get options URL
+    const options_url = await target_ctx.evaluate('(options_page) => chrome.runtime.getURL(options_page)', options_page || options_ui.page || 'options.html');
+    // Get keyboard commands
+    const commands = await target_ctx.evaluate(`
+		async () => {
+			return await new Promise((resolve) => {
+				if (chrome.commands) {
+					chrome.commands.getAll(resolve);
+				} else {
+					resolve({});
+				}
+			});
+		}
+	`);
+    // Dispatch helpers
+    const dispatch_eval = async (...args) => {
+        return await target_ctx.evaluate(...args);
+    };
+    const dispatch_popup = async () => {
+        return await target_ctx.evaluate("() => chrome.action?.openPopup() || chrome.tabs.create({url: chrome.runtime.getURL('popup.html')})");
+    };
+    let dispatch_action;
+    let dispatch_message;
+    let dispatch_command;
+    if (manifest_version === '3') {
+        // Manifest V3 APIs
+        dispatch_action = async (tab) => {
+            return await target_ctx.evaluate(`
+				async (tab) => {
+					tab = tab || (await new Promise((resolve) =>
+						chrome.tabs.query({currentWindow: true, active: true}, ([tab]) => resolve(tab))
+					));
+					return await chrome.action.onClicked.dispatch(tab);
+				}
+			`, tab);
+        };
+        dispatch_message = async (message, options) => {
+            return await target_ctx.evaluate(`
+				async (extension_id, message, options) => {
+					return await chrome.runtime.sendMessage(extension_id, message, options);
+				}
+			`, extension_id, message, options);
+        };
+        dispatch_command = async (command, tab) => {
+            return await target_ctx.evaluate(`
+				async (command, tab) => {
+					return await chrome.commands.onCommand.dispatch(command, tab);
+				}
+			`, command, tab);
+        };
+    }
+    else {
+        // Manifest V2 APIs
+        dispatch_action = async (tab) => {
+            return await target_ctx.evaluate(`
+				async (tab) => {
+					tab = tab || (await new Promise((resolve) =>
+						chrome.tabs.query({currentWindow: true, active: true}, ([tab]) => resolve(tab))
+					));
+					return await chrome.browserAction.onClicked.dispatch(tab);
+				}
+			`, tab);
+        };
+        dispatch_message = async (message, options) => {
+            return await target_ctx.evaluate(`
+				async (extension_id, message, options) => {
+					return await new Promise((resolve) =>
+						chrome.runtime.sendMessage(extension_id, message, options, resolve)
+					);
+				}
+			`, extension_id, message, options);
+        };
+        dispatch_command = async (command, tab) => {
+            return await target_ctx.evaluate(`
+				async (command, tab) => {
+					return await new Promise((resolve) =>
+						chrome.commands.onCommand.dispatch(command, tab, resolve)
+					);
+				}
+			`, command, tab);
+        };
+    }
+    // Find existing extension or create new one
+    const existing_extension = extensions.find((ext) => ext.id === extension_id) ||
+        {};
+    const new_extension = {
+        ...existing_extension,
+        id: extension_id,
+        name,
+        target,
+        target_ctx,
+        target_type: target_type,
+        target_url: target_url,
+        manifest_version,
+        manifest,
+        version,
+        homepage_url,
+        options_url,
+        dispatch_eval,
+        dispatch_popup,
+        dispatch_action,
+        dispatch_message,
+        dispatch_command,
+    };
+    logger.info(`[➕] Loaded extension ${name.slice(0, 32)} (${version}) ${target_type}... ${target_url}`);
+    // Update existing extension in-place
+    Object.assign(existing_extension, new_extension);
+    return new_extension;
+}
+/**
+ * Load all Chrome extensions from browser targets
+ */
+export async function getChromeExtensionsFromBrowser(browser, extensions) {
+    logger.info(`[⚙️] Loading ${extensions.length} chrome extensions from browser...`);
+    // Find loaded extensions at runtime by checking all browser targets
+    const targets = await browser.targets();
+    for (const target of targets) {
+        await loadExtensionFromTarget(extensions, target);
+    }
+    return extensions;
+}
+/**
+ * Install extensions from persona configuration
+ */
+export async function installExtensionsFromConfig(extensionConfigs, extensionsDir) {
+    logger.info('*************************************************************************');
+    logger.info(`[⚙️] Installing ${extensionConfigs.length} chrome extensions...`);
+    const extensions = [];
+    try {
+        // Install each extension
+        for (const config of extensionConfigs) {
+            const extension = await loadOrInstallExtension(config, extensionsDir);
+            extensions.push(extension);
+        }
+    }
+    catch (error) {
+        logger.error(`[❌] Extension installation failed: ${error.message}`);
+    }
+    logger.info('*************************************************************************');
+    return extensions;
+}

package/dist/browser/index.d.ts

@@ -0,0 +1,10 @@
+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';
+export type { Browser, BrowserConfig, BrowserContext, BrowserContextConfig, } from './context.js';
+export type { Browser as PlaywrightBrowser, BrowserContext as PlaywrightBrowserContext, Page, Locator, FrameLocator, ElementHandle, Playwright, PlaywrightOrPatchright, ClientCertificate, Geolocation, HttpCredentials, ProxySettings, StorageState, ViewportSize, } from './types.js';
+export { async_playwright } from './types.js';