browser-use-typescript/browser-use-typescript/README.md

A TypeScript-based browser automation framework

# browser-use-typescript

A TypeScript port of the browser-use library, providing a powerful and flexible framework for browser automation using Large Language Models (LLMs).

## Features

- **LLM-Powered Automation**: Leverage the power of Large Language Models for intelligent browser automation
- **Type Safety**: Full TypeScript support with comprehensive type definitions
- **Async/Await Support**: Built with modern JavaScript practices for better control flow
- **DOM Manipulation**: Advanced DOM traversal and manipulation capabilities
- **Performance Metrics**: Built-in performance tracking and optimization
- **Error Handling**: Robust error handling and recovery mechanisms
- **Modular Design**: Clean architecture for easy extension and customization

## Installation

```bash
npm install browser-use-typescript
```

## Quick Start

```typescript
import { Agent } from 'browser-use-typescript';

async function example() {
    const agent = new Agent();
    await agent.init();
    
    // Navigate to a page
    await agent.navigate('https://example.com');
    
    // Perform actions
    await agent.act('Click the login button');
    
    // Extract information
    const data = await agent.extract('Get the main heading text');
    
    console.log(data);
}
```

## Key Components

### Agent
The main interface for browser automation. Handles high-level operations and coordinates between different components.

### Browser Context
Manages browser state and provides low-level browser operations. Uses an async initialization pattern for better performance:
- Async initialization in constructor
- Promise-based state management
- Initialization state verification
- Safe method execution with state checks

### DOM Service
Handles DOM manipulation and traversal with efficient caching mechanisms:
- Element location caching
- Computed style caching
- Efficient DOM tree traversal
- Smart element selection strategies

### Controller Context
Manages the execution flow and coordinates between the agent and browser components:
- Action registry management
- State synchronization
- Error handling and recovery
- Event management

## Advanced Usage

### Custom Actions
```typescript
import { Agent, ActionConfig } from 'browser-use-typescript';

const agent = new Agent();
await agent.init();

const customAction: ActionConfig = {
    name: 'customClick',
    description: 'Custom click action with verification',
    handler: async (target) => {
        await agent.act(`Click ${target}`);
        await agent.verify('Element was clicked');
    }
};

agent.registerAction(customAction);
```

### Performance Optimization
The library includes built-in performance optimization features:
- DOM tree caching for faster element lookup
- Computed style caching to reduce browser reflows
- Efficient DOM traversal algorithms
- Smart element selection based on context

## API Documentation

### Agent Class
- `init()`: Initialize the agent and browser context
- `act(instruction: string)`: Perform an action based on natural language instruction
- `extract(query: string)`: Extract information from the page
- `navigate(url: string)`: Navigate to a URL
- `verify(condition: string)`: Verify a condition on the page

### Browser Context
- `initialize()`: Set up browser environment
- `getPage()`: Get current page instance
- `executeScript()`: Execute JavaScript in page context
- `_ensure_initialized()`: Internal method to verify initialization

### DOM Service
- `findElement()`: Find elements using various strategies
- `getAttribute()`: Get element attributes
- `modifyElement()`: Modify element properties
- `buildDomTreeOverlay()`: Create DOM tree visualization

## Contributing

Contributions are welcome! Please read our contributing guidelines for details on our code of conduct and the process for submitting pull requests.

## License

MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

This project is a TypeScript port of the original browser-use project, enhanced with:
- Complete type safety
- Modern JavaScript features
- Improved error handling
- Better performance optimization
- Comprehensive documentation

## Support

- Documentation (Coming Soon)
- [Issue Tracker](https://github.com/yourusername/browser-use-typescript/issues)
- [Discussions](https://github.com/yourusername/browser-use-typescript/discussions)

## Version History

Current Version: 1.0.10
- Added comprehensive TypeScript support
- Implemented async initialization pattern
- Enhanced DOM manipulation capabilities
- Improved performance with caching mechanisms
- Added type definitions for all components