Lightweight browser automation for Starpod via Chrome DevTools Protocol.

This crate provides [BrowserSession], a high-level async interface for controlling a CDP-speaking browser (Lightpanda or headless Chromium). It uses direct CDP over WebSocket and handles process lifecycle, connection management, and common browser operations.

Architecture

┌────────────────────┐     CDP/WebSocket     ┌──────────────────────┐
│  BrowserSession    │ ◄──────────────────── │  lightpanda serve    │
│  (async-tungstenite)│                       │  (auto-spawned)      │
└────────────────────┘                       └──────────────────────┘

Usage modes

• Auto-spawn (recommended): [BrowserSession::launch()] finds a free port, spawns lightpanda serve, waits for CDP readiness, and connects. The process is killed on close() or [Drop].

• External: [BrowserSession::connect()] attaches to a pre-existing CDP endpoint (e.g. headless Chromium started by the user or systemd).

Requirements

For auto-spawn mode, lightpanda is automatically downloaded and installed to ~/.local/bin/ if not already on PATH. No manual setup is needed.

Example

# async fn example() -> starpod_browser::Result<()> {
use starpod_browser::BrowserSession;

// Auto-spawn Lightpanda and navigate
let session = BrowserSession::launch().await?;
let title = session.navigate("https://example.com").await?;
println!("Page title: {title}");

// Extract page text
let text = session.extract(None).await?;
println!("Page text: {text}");

// Clean up
session.close().await?;
# Ok(())
# }