APPLICATION_README.md

---
title: Chrome Controller Pro
emoji: 🌐
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
license: mit
app_port: 7860
---

# Chrome Controller Pro

A professional-grade Chrome browser controller for Hugging Face Spaces with advanced automation capabilities.

## 🚀 Features

- **Headless Chrome Management**: Start, stop, and monitor Chrome instances
- **Screenshot Capture**: Take high-quality screenshots of web pages
- **URL Navigation**: Navigate to any website with automatic protocol handling
- **JavaScript Execution**: Execute custom JavaScript code in the browser context
- **Process Management**: Robust Chrome process lifecycle management
- **Persistent Profiles**: Chrome user data persistence during session

## 🛠️ Key Improvements Over Previous Version

### Fixed Issues:
1. **Gradio Schema Error**: Resolved `TypeError: argument of type 'bool' is not iterable` by using proper Gradio component initialization
2. **Launch Configuration**: Fixed localhost accessibility issues with proper server configuration
3. **Chrome Stability**: Enhanced Chrome startup reliability with better error handling
4. **Resource Management**: Improved process cleanup and memory management

### New Features:
1. **JavaScript Console**: Execute custom JavaScript code directly in the browser
2. **Tabbed Interface**: Organized functionality into logical tabs
3. **Enhanced Status Monitoring**: Real-time Chrome process status updates
4. **Better Error Handling**: Comprehensive error messages and recovery options
5. **Optimized Performance**: Reduced startup time and improved responsiveness

## 🏗️ Architecture

The application uses a class-based architecture with the `ChromeController` class managing:
- Chrome process lifecycle
- WebDriver connections
- Screenshot capture
- JavaScript execution
- Process monitoring

## 🐳 Docker Configuration

The Dockerfile is optimized for:
- Minimal image size with multi-stage optimization
- Proper Chrome dependencies installation
- Security best practices with non-root user
- Health checks for reliability

## 📋 Usage Instructions

1. **Start Chrome**: Click "🚀 Start Chrome" to launch the browser instance
2. **Navigate**: Enter a URL and click "🧭 Navigate" to visit websites
3. **Screenshot**: Use "📸 Take Screenshot" to capture the current page
4. **Execute JS**: Use the JavaScript tab to run custom code
5. **Monitor**: Check status and manage processes as needed

## 🔧 Technical Details

### Chrome Arguments
Optimized Chrome flags for containerized environments:
- Headless mode with new engine
- Disabled GPU acceleration for CPU environments
- Security sandbox disabled for container compatibility
- Remote debugging enabled on port 9222
- Crash reporting disabled to prevent permission issues

### Dependencies
- `gradio==4.44.0` - Web interface framework
- `selenium==4.25.0` - Browser automation
- `webdriver-manager==4.0.2` - ChromeDriver management
- `psutil==6.0.0` - Process management
- `Pillow==10.4.0` - Image processing

## 🚨 Troubleshooting

### Common Issues:

1. **Chrome won't start**
   - Check the status output for specific error messages
   - Ensure sufficient memory is available
   - Try stopping and restarting Chrome

2. **Screenshots fail**
   - Verify Chrome is running with "📊 Check Status"
   - Ensure the page has finished loading
   - Check if the target URL is accessible

3. **JavaScript execution errors**
   - Verify the JavaScript syntax
   - Ensure Chrome is running and has a page loaded
   - Check browser console for additional error details

### Performance Tips:
- Keep Chrome running between operations for better performance
- Use the status check before taking screenshots
- Clean up processes periodically if running long sessions

## 🔒 Security Notes

- Runs in a sandboxed container environment
- Uses non-root user for enhanced security
- Chrome security features are partially disabled for container compatibility
- No persistent data storage outside the session

## 📝 License

MIT License - Feel free to use and modify as needed.

## 🤝 Contributing

This is an open-source project. Contributions, issues, and feature requests are welcome!

---

*Built with ❤️ for the Hugging Face Spaces community*