orb-browse 0.3.0

# 🔮 orb-browse

**A TUI browser widget for Rust** - WebDriver automation for terminal applications

[![Crates.io](https://img.shields.io/crates/v/orb-browse.svg)](https://crates.io/crates/orb-browse)
[![Documentation](https://docs.rs/orb-browse/badge.svg)](https://docs.rs/orb-browse)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE-APACHE)

## 🎯 What is this?

**orb-browse** is a reusable browser component for terminal applications. It provides:

- 🎨 **TUI Widget** - Embeddable ratatui widget for terminal apps
- 🌐 **WebDriver Automation** - Full browser control via W3C WebDriver
- 📸 **Screenshot Capture** - Capture web pages as PNG images
- 🚀 **Zero Config** - Auto-detects Chrome version and downloads matching ChromeDriver

Perfect for building terminal-based web browsers, monitoring tools, or integrating web content into TUI applications.

## 🚀 Quick Start

Add to your `Cargo.toml`:

```toml
[dependencies]
orb-browse = "0.2"
tokio = { version = "1", features = ["full"] }
```

### TUI Widget Example

```rust
use orb_browse::{OrbBrowser, widget::{BrowserWidget, BrowserState, BrowserEvent}};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let browser = OrbBrowser::new().await?;
    let mut state = BrowserState::new();

    // Navigate to URL
    state.navigate(&browser, "https://example.com".to_string()).await?;

    // In your ratatui render loop:
    terminal.draw(|f| {
        let widget = BrowserWidget::new(&state)
            .block(Block::default().borders(Borders::ALL));
        f.render_widget(widget, area);
    })?;

    // Handle events
    state.handle_event(&browser, BrowserEvent::Refresh).await?;

    Ok(())
}
```

See `examples/widget.rs` for a complete interactive TUI browser example.

### Automation Example

```rust
use orb_browse::OrbBrowser;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create browser
    let browser = OrbBrowser::new().await?;

    // Navigate and capture
    let screenshot = browser.capture("https://example.com", 1920, 1080).await?;

    // Save screenshot
    std::fs::write("screenshot.png", &screenshot)?;

    // Clean up
    browser.close().await?;

    Ok(())
}
```

That's it! No ChromeDriver installation, no configuration needed.

## 📚 API Documentation

### `OrbBrowser`

The main browser client:

```rust
// Create browser (default 1920x1080)
let browser = OrbBrowser::new().await?;

// Create with custom size
let browser = OrbBrowser::with_size(1280, 720).await?;

// Navigate to URL
browser.goto("https://example.com").await?;

// Capture screenshot
let png_bytes = browser.capture("https://example.com", 1920, 1080).await?;

// Access underlying fantoccini client for advanced control
let client = browser.client();

// Close browser
browser.close().await?;
```

### `BrowserWidget`

Ratatui widget for displaying web content:

```rust
use orb_browse::widget::{BrowserWidget, BrowserState, BrowserEvent};

let mut state = BrowserState::new();
state.navigate(&browser, url).await?;

// Render in your TUI
frame.render_widget(BrowserWidget::new(&state), area);

// Handle events
state.handle_event(&browser, BrowserEvent::ScrollDown).await?;
state.handle_event(&browser, BrowserEvent::Refresh).await?;
```

## ✨ Features

- ✅ **TUI Widget** - Display browser content in ratatui apps
- ✅ **Headless Mode** - Run without visible browser window
- ✅ **Screenshot Capture** - Full-page screenshots as PNG
- ✅ **Auto-Setup** - Detects Chrome version and downloads matching ChromeDriver
- ✅ **Cross-Platform** - Linux, macOS support
- ✅ **Async** - Built on tokio for non-blocking operations

## 🧪 Examples

Run the examples:

```bash
git clone https://github.com/icryo/orb-browse
cd orb-browse

# Simple automation example
cargo run --example simple

# Interactive TUI widget example
cargo run --example widget
```

## 🎯 Use Cases

- **TUI Web Browsers** - Terminal-based browsing like carbonyl
- **Monitoring Tools** - Screenshot monitoring in terminal apps
- **Automation** - Automated web workflows
- **Testing** - Automated browser testing
- **Data Collection** - Gather data from web pages

## 🔧 How It Works

**orb-browse** uses WebDriver protocol to control Chrome/Chromium:

1. **Auto-detects Chrome version** - Checks installed Chrome/Chromium version
2. **Downloads matching ChromeDriver** - Fetches the correct ChromeDriver for your Chrome version
3. **Caches by version** - Keeps multiple ChromeDriver versions for different Chrome installs
4. **Launches headless Chrome** - Configures browser with appropriate flags
5. **WebDriver Protocol** - Uses W3C WebDriver for reliable control
6. **Screenshot Capture** - Renders pages and captures as PNG
7. **TUI Integration** - Provides ratatui widget for terminal display

## ⚠️ Requirements

- **Chrome/Chromium** - Must be installed on system
- **curl and unzip** - For ChromeDriver download
- **Linux/macOS** - Windows support planned

### Environment Variables

- **`ORB_BROWSE_CHROME_PATH`** - Override Chrome binary location
  ```bash
  export ORB_BROWSE_CHROME_PATH=/usr/bin/chromium-browser
  ```

- **`ORB_BROWSE_VERBOSE=1`** - Enable verbose ChromeDriver logging for debugging
  ```bash
  ORB_BROWSE_VERBOSE=1 cargo run
  ```

## 🤝 Contributing

Contributions welcome! Please submit a Pull Request.

## 📄 License

Licensed under the Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE)).

## 🙏 Acknowledgments

- Uses [fantoccini](https://github.com/jonhoo/fantoccini) for WebDriver
- Uses [ratatui](https://github.com/ratatui/ratatui) for TUI
- Built with [tokio](https://tokio.rs) async runtime

---

**Made with 🦀 in Rust**