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

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

  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