🔮 orb-browse

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

🎯 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:

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

TUI Widget Example

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

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:

// 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:

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:

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:

Auto-detects Chrome version - Checks installed Chrome/Chromium version
Downloads matching ChromeDriver - Fetches the correct ChromeDriver for your Chrome version
Caches by version - Keeps multiple ChromeDriver versions for different Chrome installs
Launches headless Chrome - Configures browser with appropriate flags
WebDriver Protocol - Uses W3C WebDriver for reliable control
Screenshot Capture - Renders pages and captures as PNG
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

export ORB_BROWSE_CHROME_PATH=/usr/bin/chromium-browser

ORB_BROWSE_VERBOSE=1 - Enable verbose ChromeDriver logging for debugging
```
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).

🙏 Acknowledgments

Uses fantoccini for WebDriver
Uses ratatui for TUI
Built with tokio async runtime

Made with 🦀 in Rust

orb-browse 0.3.0