browser

package
v0.0.0-...-8acab51 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 26, 2026 License: MIT Imports: 43 Imported by: 0

Documentation

Overview

Package browser provides browser automation capabilities using Rod. This module is designed to be compatible with clawdbot's browser tool interface.

Index

Constants

View Source 
const (
	// SitePresetBrowserCommon expands a browser-heavy site bundle covering the
	// common community, blog, video, travel, review, and shopping targets users
	// frequently ask Blue to handle.
	SitePresetBrowserCommon = "browser_common"
	// SitePresetRelayFocused keeps only the highest-value sites for relay:
	// login-heavy, anti-bot-prone, or strongly session-dependent destinations.
	SitePresetRelayFocused = "relay_focused"
)
View Source 
const (
	// DefaultRelayHost is the default loopback host for Blue's local browser relay.
	DefaultRelayHost = "127.0.0.1"
	// DefaultRelayPort is the default loopback port for Blue's local browser relay.
	DefaultRelayPort = 18792
)
View Source 
const (
	// RelayAuthHeader authenticates Blue's loopback relay HTTP and WebSocket requests.
	RelayAuthHeader = "X-Blue-Relay-Token"
)

Variables

View Source 
var (
	// ErrLightpandaUnsupportedCapability reports that the requested operation
	// exceeds Lightpanda v1's read-only capability boundary.
	ErrLightpandaUnsupportedCapability = errors.New("unsupported_capability")
	// ErrLightpandaDOMUnstable reports that the fetched DOM is not stable enough
	// to trust for structured read-only extraction.
	ErrLightpandaDOMUnstable = errors.New("dom_unstable")
	// ErrLightpandaEmptyTree reports that no meaningful DOM tree could be built.
	ErrLightpandaEmptyTree = errors.New("empty_tree")
	// ErrLightpandaNavigationBlocked reports that the target page could not be
	// fetched in read-only mode.
	ErrLightpandaNavigationBlocked = errors.New("navigation_blocked")
	// ErrLightpandaJSRequired reports that the target page appears to require a
	// JS-capable browser before content becomes readable.
	ErrLightpandaJSRequired = errors.New("js_required")
)
View Source 
var (
	// ErrBrowserNotAvailable is returned when no browser instance is available.
	ErrBrowserNotAvailable = errors.New("browser not available")
	// ErrBrowserNotRunning is returned when the browser is not running.
	ErrBrowserNotRunning = errors.New("browser not running")
	// ErrPageNotFound is returned when a page is not found.
	ErrPageNotFound = errors.New("page not found")
	// ErrTabNotFound is returned when a tab is not found.
	ErrTabNotFound = errors.New("tab not found")
	// ErrTimeout is returned when an operation times out.
	ErrTimeout = errors.New("operation timed out")
	// ErrURLNotAllowed is returned when a URL is not in the allowlist.
	ErrURLNotAllowed = errors.New("URL not allowed")
	// ErrURLBlocked is returned when a URL is in the blocklist.
	ErrURLBlocked = errors.New("URL blocked")
	// ErrResourceLimitExceeded is returned when resource limits are exceeded.
	ErrResourceLimitExceeded = errors.New("resource limit exceeded")
	// ErrInvalidSelector is returned when a CSS selector is invalid.
	ErrInvalidSelector = errors.New("invalid selector")
	// ErrElementNotFound is returned when an element is not found.
	ErrElementNotFound = errors.New("element not found")
	// ErrInvalidAction is returned when an action is invalid.
	ErrInvalidAction = errors.New("invalid action")
)
View Source 
var (
	// ErrEvaluateDisabled is returned when JavaScript evaluation is disabled.
	ErrEvaluateDisabled = errors.New("JavaScript evaluation is disabled by configuration (browser.evaluate_enabled=false)")
)

Functions

func EnsureRelayExtensionDir 

func EnsureRelayExtensionDir(root string) (string, error)

EnsureRelayExtensionDir materializes Blue's unpacked browser relay extension files.

func ExpandRelayPreferredSitePresets 

func ExpandRelayPreferredSitePresets(presets []string) []string

ExpandRelayPreferredSitePresets resolves built-in relay site preset names into host/origin match patterns.

func ExpandTrustedSitePresets 

func ExpandTrustedSitePresets(presets []string) []string

ExpandTrustedSitePresets resolves built-in trusted site preset names into exact origins.

func GetTimeout 

func GetTimeout(requested int, config *Config) time.Duration

GetTimeout returns the timeout duration, applying defaults and limits.

func MatchSitePattern 

func MatchSitePattern(rawURL, pattern string) bool

MatchSitePattern matches either an exact origin pattern (scheme://host[:port]) or a host pattern such as "zhihu.com", which also matches subdomains.

func MatchSitePatternList 

func MatchSitePatternList(rawURL string, patterns []string) bool

MatchSitePatternList reports whether the raw URL matches any configured host/origin pattern.

func ProbeCDPURL 

func ProbeCDPURL(ctx context.Context, raw string) error

ProbeCDPURL verifies that a CDP endpoint can be resolved into a usable websocket URL.

Types

type AccessibilityTreeResponse 

type AccessibilityTreeResponse struct {
	// Tree is the DSL representation of the accessibility tree.
	// Format: @ref [role] "name" properties
	// The @ref can be used in Act() to target elements.
	Tree string `json:"tree"`
	// URL is the page URL.
	URL string `json:"url"`
	// Title is the page title.
	Title string `json:"title"`
	// TargetID is the tab ID.
	TargetID string `json:"target_id"`
	// RefMap maps @ref numbers to backend DOM node IDs for action targeting.
	RefMap map[int]int `json:"ref_map,omitempty"`
}

AccessibilityTreeResponse represents the accessibility tree of a page.

type ActRequest 

type ActRequest struct {
	// Kind is the action type: click, type, select, scroll, hover, drag, press, fill, close, wait.
	Kind string `json:"kind" validate:"required"`
	// Ref is the element reference from snapshot.
	Ref string `json:"ref,omitempty"`
	// Selector is a CSS selector (alternative to ref).
	Selector string `json:"selector,omitempty"`
	// TargetID is the optional tab ID.
	TargetID string `json:"target_id,omitempty"`
	// Value is the value for type/select actions.
	Value string `json:"value,omitempty"`
	// Files are local file paths used by upload actions.
	Files []string `json:"files,omitempty"`
	// Text is the text to type.
	Text string `json:"text,omitempty"`
	// Key is the key to press.
	Key string `json:"key,omitempty"`
	// X is the X coordinate for scroll/click.
	X int `json:"x,omitempty"`
	// Y is the Y coordinate for scroll/click.
	Y int `json:"y,omitempty"`
	// Double indicates a double-click.
	Double bool `json:"double,omitempty"`
	// Submit submits the form after typing.
	Submit bool `json:"submit,omitempty"`
	// Options are select options.
	Options []string `json:"options,omitempty"`
	// ToRef is the target ref for drag actions.
	ToRef string `json:"to_ref,omitempty"`
	// Duration is the wait duration in milliseconds.
	Duration int `json:"duration,omitempty"`
	// Timeout is the action timeout in milliseconds.
	Timeout int `json:"timeout,omitempty"`
}

ActRequest represents an action request.

type ActResponse 

type ActResponse struct {
	// Success indicates if the action succeeded.
	Success bool `json:"success"`
	// Message is an optional message.
	Message string `json:"message,omitempty"`
	// Data contains any data returned by the action.
	Data interface{} `json:"data,omitempty"`
}

ActResponse represents the result of an action.

type ActionType 

type ActionType string

ActionType represents the type of automation action. 

const (
	// ActionClick clicks an element.
	ActionClick ActionType = "click"
	// ActionTypeText types text into an element.
	ActionTypeText ActionType = "type"
	// ActionSelect selects an option from a dropdown.
	ActionSelect ActionType = "select"
	// ActionWait waits for a specified time.
	ActionWait ActionType = "wait"
	// ActionWaitFor waits for an element to appear.
	ActionWaitFor ActionType = "wait_for"
	// ActionScroll scrolls the page or element.
	ActionScroll ActionType = "scroll"
	// ActionScreenshot takes a screenshot.
	ActionScreenshot ActionType = "screenshot"
	// ActionNavigate navigates to a URL.
	ActionNavigate ActionType = "navigate"
	// ActionEval evaluates JavaScript.
	ActionEval ActionType = "eval"
	// ActionHover hovers over an element.
	ActionHover ActionType = "hover"
	// ActionDrag drags from one element to another.
	ActionDrag ActionType = "drag"
	// ActionPress presses a key.
	ActionPress ActionType = "press"
	// ActionFill fills form fields.
	ActionFill ActionType = "fill"
	// ActionUpload uploads one or more local files to a file input.
	ActionUpload ActionType = "upload"
)

type AutomateRequest 

type AutomateRequest struct {
	// URL is the starting URL.
	URL string `json:"url" validate:"required,url"`
	// Steps is the list of automation steps.
	Steps []AutomationStep `json:"steps" validate:"required,min=1"`
	// Timeout is the maximum time for the entire task (milliseconds).
	Timeout int `json:"timeout,omitempty"`
}

AutomateRequest represents a request to run an automation task.

type AutomateResponse 

type AutomateResponse struct {
	// Success indicates if all steps completed successfully.
	Success bool `json:"success"`
	// StepsCompleted is the number of steps completed.
	StepsCompleted int `json:"steps_completed"`
	// Results contains results from each step.
	Results []StepResult `json:"results"`
	// FinalURL is the URL after all steps.
	FinalURL string `json:"final_url"`
	// FinalTitle is the page title after all steps.
	FinalTitle string `json:"final_title"`
}

AutomateResponse represents the result of an automation task.

type AutomationStep 

type AutomationStep struct {
	// Action is the action type.
	Action ActionType `json:"action" validate:"required"`
	// Selector is the CSS selector for the target element.
	Selector string `json:"selector,omitempty"`
	// Value is the value for input actions.
	Value string `json:"value,omitempty"`
	// WaitFor is the time to wait after this step (milliseconds).
	WaitFor int `json:"wait_for,omitempty"`
	// Optional marks this step as optional (won't fail if element not found).
	Optional bool `json:"optional,omitempty"`
}

AutomationStep represents a single automation step.

type BrowserOverviewTaskProvider 

type BrowserOverviewTaskProvider interface {
	List(ctx context.Context, query BrowserOverviewTaskQuery) ([]map[string]any, error)
}

type BrowserOverviewTaskQuery 

type BrowserOverviewTaskQuery struct {
	UserID         string
	ConversationID string
	Scope          string
	Limit          int
}

type BrowserSecurityConfig 

type BrowserSecurityConfig struct {
	AllowedDomains []string `json:"allowed_domains"`
	BlockedDomains []string `json:"blocked_domains"`
}

BrowserSecurityConfig represents the browser security configuration.

type BrowserStrategy 

type BrowserStrategy string

BrowserStrategy selects how Blue routes browser work. 

const (
	// BrowserStrategySingle keeps Blue on a single browser runtime.
	BrowserStrategySingle BrowserStrategy = "single"
	// BrowserStrategyHybridCapability routes by capability between engines.
	BrowserStrategyHybridCapability BrowserStrategy = "hybrid_capability"
)

type CapabilityRouterConfig 

type CapabilityRouterConfig struct {
	EscalateOnFailure *bool `json:"escalate_on_failure" yaml:"escalate_on_failure"`
}

CapabilityRouterConfig configures hybrid browser escalation behavior.

type ChromiumConfig 

type ChromiumConfig struct {
	PreferLocalChrome *bool `json:"prefer_local_chrome" yaml:"prefer_local_chrome"`
}

ChromiumConfig configures Chromium-specific routing preferences.

type Config 

type Config struct {
	// Strategy selects the runtime routing strategy.
	Strategy BrowserStrategy `json:"strategy" yaml:"strategy"`
	// Driver selects how Blue connects to the browser.
	// Supported values: "managed" (default), "relay", "cdp".
	Driver string `json:"driver" yaml:"driver"`
	// RelayEnabled starts Blue's built-in loopback relay server and lets Blue attach
	// to tabs from the companion Chrome extension.
	RelayEnabled bool `json:"relay_enabled" yaml:"relay_enabled"`
	// RelayHost is the loopback host for Blue's built-in relay server.
	RelayHost string `json:"relay_host" yaml:"relay_host"`
	// RelayPort is the loopback port for Blue's built-in relay server.
	RelayPort int `json:"relay_port" yaml:"relay_port"`
	// RelayToken authenticates CDP and extension clients against Blue's relay server.
	RelayToken string `json:"relay_token" yaml:"relay_token"`
	// PoolSize is the maximum number of browser instances.
	PoolSize int `json:"pool_size" yaml:"pool_size"`
	// Headless controls whether browsers run without a visible window.
	Headless bool `json:"headless" yaml:"headless"`
	// DefaultTimeout is the default timeout in milliseconds.
	DefaultTimeout int `json:"default_timeout" yaml:"default_timeout"`
	// MaxTimeout is the maximum allowed timeout in milliseconds.
	MaxTimeout int `json:"max_timeout" yaml:"max_timeout"`
	// DefaultViewportWidth is the default viewport width.
	DefaultViewportWidth int `json:"default_viewport_width" yaml:"default_viewport_width"`
	// DefaultViewportHeight is the default viewport height.
	DefaultViewportHeight int `json:"default_viewport_height" yaml:"default_viewport_height"`
	// AllowedDomains is a list of allowed domains (empty allows all).
	AllowedDomains []string `json:"allowed_domains" yaml:"allowed_domains"`
	// BlockedDomains is a list of blocked domains.
	BlockedDomains []string `json:"blocked_domains" yaml:"blocked_domains"`
	// UserAgent is the custom user agent string.
	UserAgent string `json:"user_agent" yaml:"user_agent"`
	// ProxyURL is the proxy server URL.
	ProxyURL string `json:"proxy_url" yaml:"proxy_url"`
	// BrowserPath is the path to the browser executable.
	BrowserPath string `json:"browser_path" yaml:"browser_path"`
	// CDPURL attaches Blue to an existing browser or relay via Chrome DevTools Protocol.
	// Examples:
	//   http://127.0.0.1:18792?token=...
	//   ws://127.0.0.1:9222/devtools/browser/<id>
	CDPURL string `json:"cdp_url" yaml:"cdp_url"`
	// TrustedSites seeds browser checkpoint auto-approval with exact origins or hosts.
	TrustedSites []string `json:"trusted_sites" yaml:"trusted_sites"`
	// TrustedSitePresets expands built-in trusted-site origin bundles.
	// Supported presets: "browser_common", "relay_focused".
	TrustedSitePresets []string `json:"trusted_site_presets" yaml:"trusted_site_presets"`
	// RelayPreferredSites lists hosts/origins that should prefer relay/local Chrome.
	RelayPreferredSites []string `json:"relay_preferred_sites" yaml:"relay_preferred_sites"`
	// RelayPreferredSitePresets expands built-in relay site bundles.
	// Supported presets: "browser_common", "relay_focused".
	RelayPreferredSitePresets []string `json:"relay_preferred_site_presets" yaml:"relay_preferred_site_presets"`
	// RelayPreferredFallbackDriver controls which driver Blue should retry with when
	// a relay-preferred site cannot be served by relay/local Chrome.
	// Supported values: "managed", "relay", "" (defaults to managed).
	RelayPreferredFallbackDriver string `json:"relay_preferred_fallback_driver" yaml:"relay_preferred_fallback_driver"`
	// EvaluateEnabled controls whether JavaScript evaluation is allowed.
	// When false, act:evaluate and wait --fn are disabled to prevent
	// prompt injection attacks from executing arbitrary JavaScript.
	// Default: true
	EvaluateEnabled *bool `json:"evaluate_enabled" yaml:"evaluate_enabled"`
	// NetworkObserveEnabled controls whether Blue records lightweight browser
	// network telemetry for retrieval fallback and adapter synthesis.
	NetworkObserveEnabled bool `json:"network_observe_enabled" yaml:"network_observe_enabled"`
	// SessionScreenshotRetention controls how long monitor frame history is kept
	// in memory. It is derived from companion session retention at runtime.
	SessionScreenshotRetention time.Duration `json:"-" yaml:"-"`
	// Lightpanda configures the lightweight read-only browser runtime.
	Lightpanda LightpandaConfig `json:"lightpanda" yaml:"lightpanda"`
	// Chromium configures Chromium routing preferences.
	Chromium ChromiumConfig `json:"chromium" yaml:"chromium"`
	// CapabilityRouter configures hybrid escalation behavior.
	CapabilityRouter CapabilityRouterConfig `json:"capability_router" yaml:"capability_router"`
}

Config contains browser service configuration.

func DefaultConfig 

func DefaultConfig() *Config

DefaultConfig returns the default configuration.

func (*Config) CapabilityEscalateOnFailure 

func (c *Config) CapabilityEscalateOnFailure() bool

CapabilityEscalateOnFailure reports whether Lightpanda failures should be upgraded to Chromium once during new-session routing.

func (*Config) Clone 

func (c *Config) Clone() *Config

Clone returns a deep copy of the browser configuration.

func (*Config) CloneForDriver 

func (c *Config) CloneForDriver(driver string) *Config

CloneForDriver returns a deep copy of the config forced to the requested driver.

func (*Config) EffectiveCDPURL 

func (c *Config) EffectiveCDPURL() string

EffectiveCDPURL returns the external or built-in relay CDP endpoint Blue should use.

func (*Config) EffectivePoolSize 

func (c *Config) EffectivePoolSize() int

EffectivePoolSize returns the runtime pool size after driver-specific normalization.

func (*Config) ExpandedRelayPreferredSites 

func (c *Config) ExpandedRelayPreferredSites() []string

ExpandedRelayPreferredSites returns the merged explicit relay-preferred site patterns and preset host bundles.

func (*Config) ExpandedTrustedSites 

func (c *Config) ExpandedTrustedSites() []string

ExpandedTrustedSites returns the merged explicit trusted sites and preset origins.

func (*Config) IsEvaluateEnabled 

func (c *Config) IsEvaluateEnabled() bool

IsEvaluateEnabled returns whether JavaScript evaluation is enabled.

func (*Config) LightpandaAutoDownload 

func (c *Config) LightpandaAutoDownload() bool

LightpandaAutoDownload reports whether Blue should warm or download the upstream Lightpanda binary automatically in the background when enabled.

func (*Config) LightpandaDownloadTimeout 

func (c *Config) LightpandaDownloadTimeout() time.Duration

LightpandaDownloadTimeout returns the bounded timeout used for background Lightpanda binary warmup/download.

func (*Config) PreferLocalChrome 

func (c *Config) PreferLocalChrome() bool

PreferLocalChrome reports whether Chromium routes should try relay/local Chrome first.

func (*Config) RelayBaseURL 

func (c *Config) RelayBaseURL() string

RelayBaseURL returns the built-in relay HTTP base URL.

func (*Config) RelayCDPURL 

func (c *Config) RelayCDPURL() string

RelayCDPURL returns the built-in relay HTTP endpoint Blue can resolve into a WS URL.

func (*Config) RelayHostOrDefault 

func (c *Config) RelayHostOrDefault() string

RelayHostOrDefault returns the configured relay host or the loopback default.

func (*Config) RelayPortOrDefault 

func (c *Config) RelayPortOrDefault() int

RelayPortOrDefault returns the configured relay port or the default port.

func (*Config) RelayPreferredFallback 

func (c *Config) RelayPreferredFallback() string

RelayPreferredFallback resolves the configured fallback driver for relay-preferred sites.

func (*Config) ResolvedDriver 

func (c *Config) ResolvedDriver() string

ResolvedDriver returns the normalized browser driver name.

func (*Config) ResolvedStrategy 

func (c *Config) ResolvedStrategy() BrowserStrategy

ResolvedStrategy returns the normalized browser routing strategy.

func (*Config) UsesRelayDriver 

func (c *Config) UsesRelayDriver() bool

UsesRelayDriver reports whether Blue should attach to an external CDP/relay endpoint.

type ConsoleMessage 

type ConsoleMessage struct {
	// Level is the log level.
	Level string `json:"level"`
	// Text is the message text.
	Text string `json:"text"`
	// Timestamp is when the message was logged.
	Timestamp time.Time `json:"timestamp"`
	// URL is the source URL.
	URL string `json:"url,omitempty"`
	// Line is the source line number.
	Line int `json:"line,omitempty"`
}

ConsoleMessage represents a single console message.

type ConsoleRequest 

type ConsoleRequest struct {
	// TargetID is the optional tab ID.
	TargetID string `json:"target_id,omitempty"`
	// Level filters by log level: "log", "info", "warn", "error".
	Level string `json:"level,omitempty"`
	// Clear clears the console after returning messages.
	Clear bool `json:"clear,omitempty"`
}

ConsoleRequest represents a request for console messages.

type ConsoleResponse 

type ConsoleResponse struct {
	// Messages is the list of console messages.
	Messages []ConsoleMessage `json:"messages"`
}

ConsoleResponse represents console messages. 

type Cookie struct {
	// Name is the cookie name.
	Name string `json:"name"`
	// Value is the cookie value.
	Value string `json:"value"`
	// Domain is the cookie domain.
	Domain string `json:"domain"`
	// Path is the cookie path.
	Path string `json:"path,omitempty"`
	// Expires is the expiration time.
	Expires *time.Time `json:"expires,omitempty"`
	// HTTPOnly marks the cookie as HTTP only.
	HTTPOnly bool `json:"http_only,omitempty"`
	// Secure marks the cookie as secure.
	Secure bool `json:"secure,omitempty"`
	// SameSite is the SameSite attribute.
	SameSite string `json:"same_site,omitempty"`
}

Cookie represents a browser cookie.

type Geolocation 

type Geolocation struct {
	// Latitude is the latitude.
	Latitude float64 `json:"latitude"`
	// Longitude is the longitude.
	Longitude float64 `json:"longitude"`
	// Accuracy is the accuracy in meters.
	Accuracy float64 `json:"accuracy,omitempty"`
}

Geolocation represents a geolocation override.

type Handler 

type Handler struct {
	// contains filtered or unexported fields
}

Handler handles browser automation HTTP requests.

func NewHandler 

func NewHandler(service Service) *Handler

NewHandler creates a new browser handler.

func NewLazyHandler 

func NewLazyHandler(factory func() Service) *Handler

NewLazyHandler creates a browser handler whose service is initialized on demand.

func (*Handler) Act 

func (h *Handler) Act(c echo.Context) error

Act performs an action on the page.

func (*Handler) AddAllowedDomain 

func (h *Handler) AddAllowedDomain(c echo.Context) error

AddAllowedDomain adds a domain to the allowed list.

func (*Handler) AddBlockedDomain 

func (h *Handler) AddBlockedDomain(c echo.Context) error

AddBlockedDomain adds a domain to the blocked list.

func (*Handler) Automate 

func (h *Handler) Automate(c echo.Context) error

Automate runs an automation task.

func (*Handler) CloseSession 

func (h *Handler) CloseSession(c echo.Context) error

CloseSession closes a browser session.

func (*Handler) CloseTab 

func (h *Handler) CloseTab(c echo.Context) error

CloseTab closes a tab.

func (*Handler) Console 

func (h *Handler) Console(c echo.Context) error

Console returns console messages.

func (*Handler) CreateSession 

func (h *Handler) CreateSession(c echo.Context) error

CreateSession creates a new browser session.

func (*Handler) ExecuteRecipe 

func (h *Handler) ExecuteRecipe(c echo.Context) error

ExecuteRecipe runs a browser recipe.

func (*Handler) FocusTab 

func (h *Handler) FocusTab(c echo.Context) error

FocusTab focuses a tab.

func (*Handler) GetSecurityConfig 

func (h *Handler) GetSecurityConfig(c echo.Context) error

GetSecurityConfig returns the configured browser security settings.

func (*Handler) GetService 

func (h *Handler) GetService() Service

GetService returns the current service, creating it if needed.

func (*Handler) ListRecipes 

func (h *Handler) ListRecipes(c echo.Context) error

ListRecipes returns all available recipes.

func (*Handler) Navigate 

func (h *Handler) Navigate(c echo.Context) error

Navigate navigates to a URL.

func (*Handler) OpenTab 

func (h *Handler) OpenTab(c echo.Context) error

OpenTab opens a new tab.

func (*Handler) Overview 

func (h *Handler) Overview(c echo.Context) error

Overview returns the Browser Monitor overview payload in one request.

func (*Handler) PDF 

func (h *Handler) PDF(c echo.Context) error

PDF generates a PDF.

func (*Handler) PeekService 

func (h *Handler) PeekService() Service

PeekService returns the current browser service without creating it.

func (*Handler) RegisterRoutes 

func (h *Handler) RegisterRoutes(g *echo.Group)

RegisterRoutes registers the browser routes.

func (*Handler) RelayInfo 

func (h *Handler) RelayInfo(c echo.Context) error

RelayInfo returns built-in browser relay runtime details.

func (*Handler) RemoveAllowedDomain 

func (h *Handler) RemoveAllowedDomain(c echo.Context) error

RemoveAllowedDomain removes a domain from the allowed list.

func (*Handler) RemoveBlockedDomain 

func (h *Handler) RemoveBlockedDomain(c echo.Context) error

RemoveBlockedDomain removes a domain from the blocked list.

func (*Handler) Scrape 

func (h *Handler) Scrape(c echo.Context) error

Scrape extracts data from a page.

func (*Handler) Screenshot 

func (h *Handler) Screenshot(c echo.Context) error

Screenshot captures a screenshot.

func (*Handler) SessionExecute 

func (h *Handler) SessionExecute(c echo.Context) error

SessionExecute executes a step in a session.

func (*Handler) SessionMonitor 

func (h *Handler) SessionMonitor(c echo.Context) error

SessionMonitor returns the unified text/image monitor payload for a session.

func (*Handler) SessionNavigate 

func (h *Handler) SessionNavigate(c echo.Context) error

func (*Handler) SessionScreenshot 

func (h *Handler) SessionScreenshot(c echo.Context) error

func (*Handler) SetIdleReclaim 

func (h *Handler) SetIdleReclaim(idleAfter time.Duration)

SetIdleReclaim configures idle reclaim for lazily created browser services.

func (*Handler) SetRelayInfoProvider 

func (h *Handler) SetRelayInfoProvider(provider func() RelayInfo)

SetRelayInfoProvider configures how relay runtime info is exposed over HTTP.

func (*Handler) SetSessionRouteProvider 

func (h *Handler) SetSessionRouteProvider(provider SessionRouteProvider)

SetSessionRouteProvider configures a multi-engine session provider for session and monitor HTTP routes.

func (*Handler) SetTaskProjectionService 

func (h *Handler) SetTaskProjectionService(provider BrowserOverviewTaskProvider)

SetTaskProjectionService configures the task provider used by the browser overview route.

func (*Handler) Snapshot 

func (h *Handler) Snapshot(c echo.Context) error

Snapshot returns a page snapshot.

func (*Handler) Start 

func (h *Handler) Start(c echo.Context) error

Start starts the browser.

func (*Handler) Status 

func (h *Handler) Status(c echo.Context) error

Status returns the browser status.

func (*Handler) Stop 

func (h *Handler) Stop(c echo.Context) error

Stop stops the browser.

func (*Handler) Tabs 

func (h *Handler) Tabs(c echo.Context) error

Tabs returns all open tabs.

func (*Handler) TestURL 

func (h *Handler) TestURL(c echo.Context) error

TestURL tests whether a URL is allowed by the configured browser security rules.

func (*Handler) UpdateSecurityConfig 

func (h *Handler) UpdateSecurityConfig(c echo.Context) error

UpdateSecurityConfig updates the configured browser security settings.

type InteractiveElementsResponse 

type InteractiveElementsResponse struct {
	Tree     string         `json:"tree"`
	URL      string         `json:"url"`
	Title    string         `json:"title"`
	TargetID string         `json:"target_id"`
	RefMap   map[int]string `json:"ref_map,omitempty"`
	Count    int            `json:"count"`
}

InteractiveElementsResponse represents the interactive elements extracted via JS. Lighter than the full accessibility tree — only returns actionable elements.

type LightpandaBinaryManager 

type LightpandaBinaryManager struct {
	// contains filtered or unexported fields
}

LightpandaBinaryManager resolves or downloads the Lightpanda binary.

func NewLightpandaBinaryManager 

func NewLightpandaBinaryManager(config *Config) *LightpandaBinaryManager

NewLightpandaBinaryManager creates a new Lightpanda binary manager.

func (*LightpandaBinaryManager) Ensure 

func (m *LightpandaBinaryManager) Ensure(ctx context.Context) (string, error)

Ensure returns a usable Lightpanda binary path, downloading and extracting a cached binary when no explicit binary_path is configured.

func (*LightpandaBinaryManager) ReadyPath 

func (m *LightpandaBinaryManager) ReadyPath() (string, bool, error)

ReadyPath returns a usable Lightpanda binary path when one is already present locally, without attempting any network downloads.

type LightpandaBinaryRuntime 

type LightpandaBinaryRuntime struct {
	// contains filtered or unexported fields
}

LightpandaBinaryRuntime manages a local upstream Lightpanda process and the relay-mode Rod service Blue uses to attach to it.

func NewLightpandaBinaryRuntime 

func NewLightpandaBinaryRuntime(config *Config) *LightpandaBinaryRuntime

NewLightpandaBinaryRuntime creates a new runtime manager for the upstream Lightpanda binary.

func (*LightpandaBinaryRuntime) PeekService 

func (r *LightpandaBinaryRuntime) PeekService() *RodService

PeekService returns the current runtime service without creating or starting a new Lightpanda process.

func (*LightpandaBinaryRuntime) Start 

func (r *LightpandaBinaryRuntime) Start(ctx context.Context) (*RodService, error)

Start returns a relay-mode Rod service bound to a live upstream Lightpanda process. The returned service is not started until callers invoke svc.Start.

func (*LightpandaBinaryRuntime) Stop 

func (r *LightpandaBinaryRuntime) Stop(ctx context.Context) error

Stop stops the current runtime and clears the cached service.

type LightpandaConfig 

type LightpandaConfig struct {
	Enabled         bool          `json:"enabled" yaml:"enabled"`
	BinaryPath      string        `json:"binary_path" yaml:"binary_path"`
	AutoDownload    *bool         `json:"auto_download,omitempty" yaml:"auto_download,omitempty"`
	DownloadTimeout time.Duration `json:"download_timeout,omitempty" yaml:"download_timeout,omitempty"`
	Args            []string      `json:"args" yaml:"args"`
}

LightpandaConfig configures the read-only Lightpanda runtime.

type LightpandaReadDocument 

type LightpandaReadDocument struct {
	URL               string `json:"url,omitempty"`
	Title             string `json:"title,omitempty"`
	Content           string `json:"content,omitempty"`
	Summary           string `json:"summary,omitempty"`
	TreePreview       string `json:"tree_preview,omitempty"`
	AccessibilityTree string `json:"accessibility_tree,omitempty"`
	InteractiveTree   string `json:"interactive_tree,omitempty"`
	InteractiveCount  int    `json:"interactive_count,omitempty"`
}

LightpandaReadDocument is the structured read result emitted by Blue's Lightpanda shim for fetch/read-layer use cases.

type LightpandaService 

type LightpandaService struct {
	// contains filtered or unexported fields
}

LightpandaService provides Blue's read-layer Lightpanda shim session model.

func NewLightpandaService 

func NewLightpandaService(config *Config) *LightpandaService

NewLightpandaService creates a Lightpanda read-layer session service.

func (*LightpandaService) AccessibilityTree 

func (s *LightpandaService) AccessibilityTree(ctx context.Context, targetID string, _ int) (*AccessibilityTreeResponse, error)

AccessibilityTree returns the current Lightpanda tree for a session.

func (*LightpandaService) BinaryAvailable 

func (s *LightpandaService) BinaryAvailable() bool

BinaryAvailable reports whether a usable upstream Lightpanda binary already exists locally without triggering a download attempt.

func (*LightpandaService) CaptureMonitor 

func (s *LightpandaService) CaptureMonitor(targetID string) (*SessionMonitorResponse, error)

CaptureMonitor returns the text-based monitor payload for a Lightpanda session.

func (*LightpandaService) CaptureScreenshot 

func (s *LightpandaService) CaptureScreenshot(targetID string) (*SessionScreenshotResponse, error)

CaptureScreenshot returns the compatibility payload for the legacy screenshot endpoint. Lightpanda does not provide image frames in v1.

func (*LightpandaService) CloseTab 

func (s *LightpandaService) CloseTab(_ context.Context, targetID string) error

CloseTab closes a Lightpanda session.

func (*LightpandaService) CountInteractiveElements 

func (s *LightpandaService) CountInteractiveElements(ctx context.Context, targetID string) (int, error)

CountInteractiveElements returns the cached interactive element count for a session.

func (*LightpandaService) EnsureBinary 

func (s *LightpandaService) EnsureBinary(ctx context.Context) (string, error)

EnsureBinary resolves or downloads the configured upstream Lightpanda binary.

func (*LightpandaService) HasSession 

func (s *LightpandaService) HasSession(targetID string) bool

HasSession reports whether targetID belongs to a Lightpanda session.

func (*LightpandaService) InteractiveElements 

func (s *LightpandaService) InteractiveElements(ctx context.Context, targetID string) (*InteractiveElementsResponse, error)

InteractiveElements returns the current interactive element list for a session.

func (*LightpandaService) ListSessionInfos 

func (s *LightpandaService) ListSessionInfos() []SessionInfo

ListSessionInfos returns all Lightpanda session summaries.

func (*LightpandaService) Navigate 

func (s *LightpandaService) Navigate(ctx context.Context, req *NavigateRequest) (*NavigateResponse, error)

Navigate fetches a page in read-only mode and stores/update a Lightpanda session.

func (*LightpandaService) ReadDocument 

func (s *LightpandaService) ReadDocument(ctx context.Context, rawURL string, timeoutMS int) (*LightpandaReadDocument, error)

ReadDocument fetches a page through the Lightpanda shim without persisting a browser session. This is used by fetch/read-layer routing.

func (*LightpandaService) ReadDocumentWithProfile 

func (s *LightpandaService) ReadDocumentWithProfile(ctx context.Context, rawURL string, timeoutMS int, profile *Profile) (*LightpandaReadDocument, error)

ReadDocumentWithProfile fetches a page through the Lightpanda shim while applying cookie/header/user-agent state exported from another runtime.

func (*LightpandaService) SessionInfo 

func (s *LightpandaService) SessionInfo(targetID string) (*SessionInfo, error)

SessionInfo returns a single Lightpanda session summary.

func (*LightpandaService) Start 

func (s *LightpandaService) Start(ctx context.Context) error

Start starts the Lightpanda service. The shim runtime is HTTP/DOM based, so startup is intentionally lightweight.

func (*LightpandaService) Tabs 

func (s *LightpandaService) Tabs(context.Context) ([]*Tab, error)

Tabs returns all active Lightpanda sessions as browser tabs.

func (*LightpandaService) WarmBinary 

func (s *LightpandaService) WarmBinary(ctx context.Context) (string, error)

WarmBinary resolves an already-ready Lightpanda binary path or performs a bounded background-friendly download attempt when auto-download is enabled. It never blocks the read-layer shim startup path directly; callers should invoke it from their own goroutine if they want non-blocking warmup. 

type NavigateRequest struct {
	// URL is the URL to navigate to.
	URL string `json:"url" validate:"required,url"`
	// TargetID is the optional tab ID to navigate in.
	TargetID string `json:"target_id,omitempty"`
	// WaitUntil specifies when navigation is considered complete.
	// Options: "load", "domcontentloaded", "networkidle"
	WaitUntil string `json:"wait_until,omitempty"`
	// Timeout is the navigation timeout in milliseconds.
	Timeout int `json:"timeout,omitempty"`
}

NavigateRequest represents a navigation request. 

type NavigateResponse struct {
	// URL is the final URL after navigation.
	URL string `json:"url"`
	// Title is the page title.
	Title string `json:"title"`
	// TargetID is the tab ID.
	TargetID string `json:"target_id"`
}

NavigateResponse represents the result of navigation.

type ObservedNetworkEvent 

type ObservedNetworkEvent struct {
	Method       string            `json:"method,omitempty"`
	URL          string            `json:"url,omitempty"`
	Status       int               `json:"status,omitempty"`
	ContentType  string            `json:"content_type,omitempty"`
	ResourceType string            `json:"resource_type,omitempty"`
	Initiator    string            `json:"initiator,omitempty"`
	DurationMS   int64             `json:"duration_ms,omitempty"`
	Headers      map[string]string `json:"headers,omitempty"`
	BodySample   string            `json:"body_sample,omitempty"`
}

ObservedNetworkEvent is a lightweight network capture entry from a tab.

type ObservedNetworkResult 

type ObservedNetworkResult struct {
	TargetID string                 `json:"target_id,omitempty"`
	Events   []ObservedNetworkEvent `json:"events,omitempty"`
}

ObservedNetworkResult returns recent browser network activity for a target tab.

type PDFFormat 

type PDFFormat string

PDFFormat represents the paper format for PDF generation. 

const (
	// PDFFormatA4 is A4 paper size.
	PDFFormatA4 PDFFormat = "A4"
	// PDFFormatLetter is Letter paper size.
	PDFFormatLetter PDFFormat = "Letter"
	// PDFFormatLegal is Legal paper size.
	PDFFormatLegal PDFFormat = "Legal"
)

type PDFRequest 

type PDFRequest struct {
	// URL is the page URL to convert.
	URL string `json:"url" validate:"required,url"`
	// Format is the paper format.
	Format PDFFormat `json:"format,omitempty"`
	// Landscape sets landscape orientation if true.
	Landscape bool `json:"landscape,omitempty"`
	// PrintBackground includes background graphics if true.
	PrintBackground bool `json:"print_background,omitempty"`
	// Scale is the scale factor (0.1-2.0).
	Scale float64 `json:"scale,omitempty"`
	// MarginTop is the top margin in inches.
	MarginTop float64 `json:"margin_top,omitempty"`
	// MarginBottom is the bottom margin in inches.
	MarginBottom float64 `json:"margin_bottom,omitempty"`
	// MarginLeft is the left margin in inches.
	MarginLeft float64 `json:"margin_left,omitempty"`
	// MarginRight is the right margin in inches.
	MarginRight float64 `json:"margin_right,omitempty"`
	// WaitFor is the time to wait after page load (milliseconds).
	WaitFor int `json:"wait_for,omitempty"`
	// Timeout is the maximum time to wait (milliseconds).
	Timeout int `json:"timeout,omitempty"`
}

PDFRequest represents a request to generate a PDF.

type PDFResponse 

type PDFResponse struct {
	// Data is the base64-encoded PDF data.
	Data string `json:"data"`
	// URL is the source URL.
	URL string `json:"url"`
	// Title is the page title.
	Title string `json:"title"`
	// PageCount is the number of pages.
	PageCount int `json:"page_count"`
}

PDFResponse represents the result of PDF generation.

type PageInfo 

type PageInfo struct {
	URL   string
	Title string
}

PageInfo contains basic page information.

type Pool 

type Pool struct {
	// contains filtered or unexported fields
}

Pool manages a pool of browser instances.

func NewPool 

func NewPool(config *Config) (*Pool, error)

NewPool creates a new browser pool.

func (*Pool) Acquire 

func (p *Pool) Acquire(ctx context.Context) (*rod.Browser, error)

Acquire gets a browser instance from the pool.

func (*Pool) Close 

func (p *Pool) Close() error

Close shuts down the browser pool.

func (*Pool) NewPage 

func (p *Pool) NewPage(ctx context.Context) (*rod.Page, *rod.Browser, error)

NewPage creates a new page in a browser instance. If the acquired browser is dead (Chrome crashed), it replaces the instance and retries once.

func (*Pool) Release 

func (p *Pool) Release(browser *rod.Browser)

Release returns a browser instance to the pool.

func (*Pool) ReleasePage 

func (p *Pool) ReleasePage(page *rod.Page, browser *rod.Browser)

ReleasePage closes a page and releases the browser back to the pool.

func (*Pool) Start 

func (p *Pool) Start(ctx context.Context) error

Start initializes the browser pool.

func (*Pool) Status 

func (p *Pool) Status() *StatusResponse

Status returns the pool status.

type Profile 

type Profile struct {
	// ID is the unique profile identifier.
	ID string `json:"id"`
	// Name is the display name.
	Name string `json:"name"`
	// Description is an optional description.
	Description string `json:"description,omitempty"`
	// UserAgent is the custom user agent string.
	UserAgent string `json:"user_agent,omitempty"`
	// Viewport is the default viewport size.
	Viewport *Viewport `json:"viewport,omitempty"`
	// Proxy is the proxy configuration.
	Proxy *ProxyConfig `json:"proxy,omitempty"`
	// Cookies are pre-set cookies.
	Cookies []Cookie `json:"cookies,omitempty"`
	// Headers are custom HTTP headers.
	Headers map[string]string `json:"headers,omitempty"`
	// LocalStorage is pre-set local storage data.
	LocalStorage map[string]map[string]string `json:"local_storage,omitempty"`
	// SessionStorage is pre-set session storage data.
	SessionStorage map[string]map[string]string `json:"session_storage,omitempty"`
	// Geolocation is the geolocation override.
	Geolocation *Geolocation `json:"geolocation,omitempty"`
	// Timezone is the timezone override.
	Timezone string `json:"timezone,omitempty"`
	// Locale is the locale override.
	Locale string `json:"locale,omitempty"`
	// ColorScheme is the preferred color scheme (light/dark).
	ColorScheme string `json:"color_scheme,omitempty"`
	// ReducedMotion enables reduced motion preference.
	ReducedMotion bool `json:"reduced_motion,omitempty"`
	// Permissions are granted permissions.
	Permissions []string `json:"permissions,omitempty"`
	// BlockedURLs are URLs to block.
	BlockedURLs []string `json:"blocked_urls,omitempty"`
	// CreatedAt is when the profile was created.
	CreatedAt time.Time `json:"created_at"`
	// UpdatedAt is when the profile was last updated.
	UpdatedAt time.Time `json:"updated_at"`
	// IsDefault indicates if this is the default profile.
	IsDefault bool `json:"is_default,omitempty"`
}

Profile represents a browser profile configuration.

type ProfileManager 

type ProfileManager struct {
	// contains filtered or unexported fields
}

ProfileManager manages browser profiles.

func NewProfileManager 

func NewProfileManager(profileDir string) (*ProfileManager, error)

NewProfileManager creates a new profile manager.

func (*ProfileManager) CloneProfile 

func (pm *ProfileManager) CloneProfile(ctx context.Context, sourceID, newID, newName string) (*Profile, error)

CloneProfile creates a copy of an existing profile.

func (*ProfileManager) CreateDefaultProfile 

func (pm *ProfileManager) CreateDefaultProfile(ctx context.Context) (*Profile, error)

CreateDefaultProfile creates a default profile if none exists.

func (*ProfileManager) CreateProfile 

func (pm *ProfileManager) CreateProfile(ctx context.Context, profile *Profile) (*Profile, error)

CreateProfile creates a new profile.

func (*ProfileManager) DeleteProfile 

func (pm *ProfileManager) DeleteProfile(ctx context.Context, profileID string) error

DeleteProfile deletes a profile.

func (*ProfileManager) ExportProfile 

func (pm *ProfileManager) ExportProfile(profileID string) ([]byte, error)

ExportProfile exports a profile to JSON.

func (*ProfileManager) GetDefaultProfile 

func (pm *ProfileManager) GetDefaultProfile() *Profile

GetDefaultProfile returns the default profile.

func (*ProfileManager) GetProfile 

func (pm *ProfileManager) GetProfile(profileID string) (*Profile, error)

GetProfile returns a profile by ID.

func (*ProfileManager) GetProfileDataDir 

func (pm *ProfileManager) GetProfileDataDir(profileID string) string

GetProfileDataDir returns the data directory for a profile.

func (*ProfileManager) ImportProfile 

func (pm *ProfileManager) ImportProfile(ctx context.Context, data []byte) (*Profile, error)

ImportProfile imports a profile from JSON.

func (*ProfileManager) ListProfiles 

func (pm *ProfileManager) ListProfiles() []*Profile

ListProfiles returns all profiles.

func (*ProfileManager) SetDefaultProfile 

func (pm *ProfileManager) SetDefaultProfile(ctx context.Context, profileID string) error

SetDefaultProfile sets a profile as the default.

func (*ProfileManager) UpdateProfile 

func (pm *ProfileManager) UpdateProfile(ctx context.Context, profile *Profile) (*Profile, error)

UpdateProfile updates an existing profile.

type ProxyConfig 

type ProxyConfig struct {
	// Server is the proxy server URL.
	Server string `json:"server"`
	// Username is the proxy username.
	Username string `json:"username,omitempty"`
	// Password is the proxy password.
	Password string `json:"password,omitempty"`
	// Bypass is a list of hosts to bypass the proxy.
	Bypass []string `json:"bypass,omitempty"`
}

ProxyConfig represents proxy configuration.

type Recipe 

type Recipe interface {
	// Name returns the recipe identifier (e.g. "search", "fill_form").
	Name() string
	// Description returns a human-readable description.
	Description() string
	// Validate checks that params are valid before execution.
	Validate(params map[string]string) error
	// Execute runs the recipe and returns structured results.
	Execute(ctx context.Context, svc *RodService, params map[string]string) (*RecipeResult, error)
	// KeepTab returns true if the tab should stay open after execution.
	KeepTab() bool
}

Recipe defines a reusable browser automation template. Recipes encapsulate multi-step browser operations (search, form fill, etc.) into a single call, eliminating the need for LLM to orchestrate each step.

type RecipeInfo 

type RecipeInfo struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	KeepTab     bool   `json:"keep_tab"`
}

RecipeInfo describes a recipe for listing.

type RecipeRegistry 

type RecipeRegistry struct {
	// contains filtered or unexported fields
}

RecipeRegistry holds all registered recipes.

func NewRecipeRegistry 

func NewRecipeRegistry() *RecipeRegistry

NewRecipeRegistry creates a registry with all built-in recipes.

func (*RecipeRegistry) Execute 

func (r *RecipeRegistry) Execute(ctx context.Context, svc *RodService, name string, params map[string]string) (*RecipeResult, error)

Execute runs a recipe by name with the given params.

func (*RecipeRegistry) Get 

func (r *RecipeRegistry) Get(name string) (Recipe, bool)

Get returns a recipe by name.

func (*RecipeRegistry) List 

func (r *RecipeRegistry) List() []RecipeInfo

List returns all registered recipe names and descriptions.

func (*RecipeRegistry) Register 

func (r *RecipeRegistry) Register(recipe Recipe)

Register adds a recipe to the registry.

type RecipeRequest 

type RecipeRequest struct {
	// Recipe is the recipe name (search, fill_form, extract, login).
	Recipe string `json:"recipe" validate:"required"`
	// Params are the recipe-specific parameters.
	Params map[string]string `json:"params" validate:"required"`
}

RecipeRequest represents a request to execute a browser recipe.

type RecipeResponse 

type RecipeResponse struct {
	// Success indicates if the recipe completed successfully.
	Success bool `json:"success"`
	// Recipe is the recipe name that was executed.
	Recipe string `json:"recipe"`
	// Data contains the structured result data.
	Data map[string]interface{} `json:"data,omitempty"`
	// TargetID is the tab ID if the recipe kept the tab open.
	TargetID string `json:"target_id,omitempty"`
	// Message is a human-readable summary.
	Message string `json:"message"`
}

RecipeResponse represents the result of a recipe execution.

type RecipeResult 

type RecipeResult struct {
	Success  bool                   `json:"success"`
	Data     map[string]interface{} `json:"data"`
	TargetID string                 `json:"target_id,omitempty"`
	Message  string                 `json:"message"`
}

RecipeResult is the structured output from a recipe execution.

type RelayInfo 

type RelayInfo struct {
	Enabled            bool   `json:"enabled"`
	Host               string `json:"host,omitempty"`
	Port               int    `json:"port,omitempty"`
	BaseURL            string `json:"base_url,omitempty"`
	CDPURL             string `json:"cdp_url,omitempty"`
	Token              string `json:"token,omitempty"`
	AuthHeader         string `json:"auth_header,omitempty"`
	ExtensionDir       string `json:"extension_dir,omitempty"`
	ExtensionConnected bool   `json:"extension_connected"`
}

RelayInfo describes Blue's built-in browser relay runtime.

type RelayServer 

type RelayServer struct {
	// contains filtered or unexported fields
}

RelayServer bridges Chrome extension debugger sessions into a loopback CDP endpoint.

func StartRelayServer 

func StartRelayServer(cfg *Config, extensionDir string) (*RelayServer, error)

StartRelayServer starts Blue's built-in loopback browser relay.

func (*RelayServer) Close 

func (s *RelayServer) Close() error

Close stops the relay server and all active WebSocket bridges.

func (*RelayServer) Info 

func (s *RelayServer) Info() RelayInfo

Info returns the current relay runtime details.

func (*RelayServer) ServeHTTP 

func (s *RelayServer) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP serves the relay's loopback HTTP and WebSocket endpoints.

type ResourceUsage 

type ResourceUsage struct {
	// MemoryMB is the current memory usage in MB.
	MemoryMB int `json:"memory_mb"`
	// CPUPercent is the current CPU usage percentage.
	CPUPercent float64 `json:"cpu_percent"`
	// NetworkBytesSent is the total bytes sent.
	NetworkBytesSent int64 `json:"network_bytes_sent"`
	// NetworkBytesReceived is the total bytes received.
	NetworkBytesReceived int64 `json:"network_bytes_received"`
	// LastUpdated is when the usage was last updated.
	LastUpdated time.Time `json:"last_updated"`
}

ResourceUsage tracks resource consumption.

type RodService 

type RodService struct {
	// contains filtered or unexported fields
}

RodService implements the Service interface using Rod.

func NewService 

func NewService(config *Config) (*RodService, error)

NewService creates a new browser service.

func (*RodService) AccessibilityTree 

func (s *RodService) AccessibilityTree(ctx context.Context, targetID string, maxDepth int) (*AccessibilityTreeResponse, error)

AccessibilityTree returns a compact DSL representation of the page's accessibility tree. This is much more token-efficient than raw HTML for LLM consumption. Each interactive element gets an @ref that can be used in Act() to target it.

func (*RodService) Act 

func (s *RodService) Act(ctx context.Context, req *ActRequest) (*ActResponse, error)

Act performs an action on the page.

func (*RodService) ActByInteractiveRef 

func (s *RodService) ActByInteractiveRef(ctx context.Context, targetID string, ref int, refMap map[int]string, action string, value string) (*ActResponse, error)

ActByInteractiveRef performs an action on an element identified by @ref from InteractiveElements.

func (*RodService) ActByRef 

func (s *RodService) ActByRef(ctx context.Context, targetID string, ref int, refMap map[int]int, action string, value string) (*ActResponse, error)

ActByRef performs an action on an element identified by @ref from the accessibility tree DSL. This resolves the ref to a backend DOM node ID and uses CDP to interact with it.

func (*RodService) ApplySessionProfile 

func (s *RodService) ApplySessionProfile(ctx context.Context, targetID string, targetURL string, profile *Profile) error

ApplySessionProfile applies cookies plus best-effort storage state to a Chromium tab.

func (*RodService) Automate 

func (s *RodService) Automate(ctx context.Context, req *AutomateRequest) (*AutomateResponse, error)

Automate runs a multi-step automation task.

func (*RodService) CleanupExpiredMonitorFrames 

func (s *RodService) CleanupExpiredMonitorFrames()

CleanupExpiredMonitorFrames removes expired monitor frame history using the configured retention window.

func (*RodService) Close 

func (s *RodService) Close() error

Close closes the browser service.

func (*RodService) CloseTab 

func (s *RodService) CloseTab(ctx context.Context, targetID string) error

CloseTab closes a tab by target ID.

func (*RodService) Console 

func (s *RodService) Console(ctx context.Context, req *ConsoleRequest) (*ConsoleResponse, error)

Console returns console messages from the page.

func (*RodService) CookieHeader 

func (s *RodService) CookieHeader(ctx context.Context, targetID string, targetURL string) (string, error)

CookieHeader returns cookies applicable to the target URL from the tab's browser context.

func (*RodService) CountInteractiveElements 

func (s *RodService) CountInteractiveElements(ctx context.Context, targetID string) (int, error)

CountInteractiveElements returns the count of interactive elements on the page. This is a lightweight JS call — no DSL building, no ref map.

func (*RodService) ElementExists 

func (s *RodService) ElementExists(ctx context.Context, targetID, selector string) (bool, error)

ElementExists reports whether the given selector matches in the current tab.

func (*RodService) ExecuteRecipe 

func (s *RodService) ExecuteRecipe(ctx context.Context, req *RecipeRequest) (*RecipeResponse, error)

ExecuteRecipe runs a named recipe with the given params.

func (*RodService) ExportSessionProfile 

func (s *RodService) ExportSessionProfile(ctx context.Context, targetID string, targetURL string) (*Profile, error)

ExportSessionProfile exports cookies plus best-effort storage state from a Chromium tab.

func (*RodService) ExtractFirstFromTab 

func (s *RodService) ExtractFirstFromTab(ctx context.Context, targetID, selector, attribute string) (string, error)

ExtractFirstFromTab returns the first matching attribute or text content from the current tab.

func (*RodService) FocusTab 

func (s *RodService) FocusTab(ctx context.Context, targetID string) error

FocusTab focuses a tab by target ID.

func (*RodService) InteractiveElements 

func (s *RodService) InteractiveElements(ctx context.Context, targetID string) (*InteractiveElementsResponse, error)

InteractiveElements extracts only interactive elements from the page using JS. Much lighter than the full accessibility tree — returns a compact DSL with @ref IDs. Each @ref maps to a CSS selector for action targeting.

func (*RodService) Navigate 

func (s *RodService) Navigate(ctx context.Context, req *NavigateRequest) (*NavigateResponse, error)

Navigate navigates to a URL in the current or specified tab.

func (*RodService) ObserveNetwork 

func (s *RodService) ObserveNetwork(ctx context.Context, targetID string, maxEntries int, clear bool) (*ObservedNetworkResult, error)

ObserveNetwork returns recent network activity recorded for a tab.

func (*RodService) OpenTab 

func (s *RodService) OpenTab(ctx context.Context, url string) (*Tab, error)

OpenTab opens a new tab with the given URL.

func (*RodService) PDF 

func (s *RodService) PDF(ctx context.Context, req *PDFRequest) (*PDFResponse, error)

PDF generates a PDF from a page.

func (*RodService) PageDimensions 

func (s *RodService) PageDimensions(ctx context.Context, targetID string) (viewportH, scrollH int, err error)

PageDimensions returns the viewport height and total scroll height of the page.

func (*RodService) PageInfo 

func (s *RodService) PageInfo(ctx context.Context, targetID string) (string, string, error)

PageInfo returns the current URL and title for a tab.

func (*RodService) PageScroll 

func (s *RodService) PageScroll(ctx context.Context, targetID string, x, y int) error

PageScroll performs a relative page scroll using the existing scroll action path so compatibility shims can reuse browser-native scrolling semantics.

func (*RodService) PressKeys 

func (s *RodService) PressKeys(ctx context.Context, targetID string, keys []string, holdMS int) error

func (*RodService) Recipes 

func (s *RodService) Recipes() *RecipeRegistry

Recipes returns the recipe registry.

func (*RodService) Scrape 

func (s *RodService) Scrape(ctx context.Context, req *ScrapeRequest) (*ScrapeResponse, error)

Scrape extracts data from a page.

func (*RodService) Screenshot 

func (s *RodService) Screenshot(ctx context.Context, req *ScreenshotRequest) (*ScreenshotResponse, error)

Screenshot captures a screenshot of a page.

func (*RodService) ScreenshotTab 

func (s *RodService) ScreenshotTab(ctx context.Context, targetID string) (string, error)

ScreenshotTab takes a screenshot of an existing tab by target ID.

func (*RodService) ScreenshotViewport 

func (s *RodService) ScreenshotViewport(ctx context.Context, targetID string) (string, error)

ScreenshotViewport takes a viewport-only screenshot (no full-page scroll capture).

func (*RodService) ScreenshotViewportRaw 

func (s *RodService) ScreenshotViewportRaw(ctx context.Context, targetID string) ([]byte, error)

ScreenshotViewportRaw takes a viewport-only screenshot and returns raw PNG bytes.

func (*RodService) ScrollTo 

func (s *RodService) ScrollTo(ctx context.Context, targetID string, x, y int) error

ScrollTo scrolls the page to the given absolute position.

func (*RodService) SessionScreenshotHistory 

func (s *RodService) SessionScreenshotHistory(targetID string) []SessionScreenshot

SessionScreenshotHistory returns newest-first screenshots captured for a tab.

func (*RodService) SetMonitorActivityListener 

func (s *RodService) SetMonitorActivityListener(listener func(targetID string, observedAt string))

SetMonitorActivityListener sets an optional hook called when a session reports network activity reaching an idle point. This can be used to trigger fast UI refreshes without pushing screenshot binaries over SSE.

func (*RodService) SetMonitorFrameListener 

func (s *RodService) SetMonitorFrameListener(listener func(targetID string, capturedAt string))

SetMonitorFrameListener sets an optional hook called when a new screenshot frame is captured or refreshed for a session. The hook must be fast and non-blocking.

func (*RodService) SetSessionScreenshotRetention 

func (s *RodService) SetSessionScreenshotRetention(retention time.Duration)

SetSessionScreenshotRetention updates the monitor frame retention window and immediately prunes any expired history.

func (*RodService) SetViewport 

func (s *RodService) SetViewport(ctx context.Context, targetID string, width, height int) error

SetViewport changes the viewport size of an existing tab.

func (*RodService) Snapshot 

func (s *RodService) Snapshot(ctx context.Context, req *SnapshotRequest) (*SnapshotResponse, error)

Snapshot returns a structured snapshot of the page.

func (*RodService) Start 

func (s *RodService) Start(ctx context.Context) error

Start starts the browser service.

func (*RodService) Status 

func (s *RodService) Status(ctx context.Context) (*StatusResponse, error)

Status returns the browser status.

func (*RodService) Stop 

func (s *RodService) Stop(ctx context.Context) error

Stop stops the browser service and kills all Chromium processes. The service can be restarted with Start().

func (*RodService) Tabs 

func (s *RodService) Tabs(ctx context.Context) ([]*Tab, error)

Tabs returns all open tabs.

func (*RodService) UsesRelayDriver 

func (s *RodService) UsesRelayDriver() bool

UsesRelayDriver reports whether this service attaches to an external or built-in relay/CDP endpoint.

func (*RodService) WaitNetworkIdle 

func (s *RodService) WaitNetworkIdle(ctx context.Context, targetID string, idleMS int, timeoutMS int) error

WaitNetworkIdle waits until the tab has no pending requests and has been idle for the requested duration.

type Sandbox 

type Sandbox struct {
	// contains filtered or unexported fields
}

Sandbox manages browser isolation and resource limits.

func NewSandbox 

func NewSandbox(config *SandboxConfig) (*Sandbox, error)

NewSandbox creates a new sandbox manager.

func (*Sandbox) CheckResourceLimits 

func (s *Sandbox) CheckResourceLimits(session *SandboxSession) error

CheckResourceLimits checks if resource limits are exceeded.

func (*Sandbox) Close 

func (s *Sandbox) Close() error

Close closes the sandbox and cleans up all sessions.

func (*Sandbox) CreateSession 

func (s *Sandbox) CreateSession(ctx context.Context, sessionID string) (*SandboxSession, error)

CreateSession creates a new isolated browser session.

func (*Sandbox) DestroySession 

func (s *Sandbox) DestroySession(ctx context.Context, sessionID string) error

DestroySession destroys a session and cleans up resources.

func (*Sandbox) GetBrowserArgs 

func (s *Sandbox) GetBrowserArgs(session *SandboxSession) []string

GetBrowserArgs returns browser launch arguments for sandbox mode.

func (*Sandbox) GetSession 

func (s *Sandbox) GetSession(sessionID string) (*SandboxSession, error)

GetSession returns a session by ID.

func (*Sandbox) IsNetworkAllowed 

func (s *Sandbox) IsNetworkAllowed(host string) bool

IsNetworkAllowed checks if a host is allowed under network isolation.

func (*Sandbox) ListSessions 

func (s *Sandbox) ListSessions() []*SandboxSession

ListSessions returns all active sessions.

func (*Sandbox) UpdateResourceUsage 

func (s *Sandbox) UpdateResourceUsage(sessionID string, usage *ResourceUsage) error

UpdateResourceUsage updates the resource usage for a session.

type SandboxConfig 

type SandboxConfig struct {
	// Enabled enables sandbox mode.
	Enabled bool `json:"enabled" yaml:"enabled"`
	// TempDir is the base directory for temporary files.
	TempDir string `json:"temp_dir" yaml:"temp_dir"`
	// MaxMemoryMB is the maximum memory limit in MB (0 = unlimited).
	MaxMemoryMB int `json:"max_memory_mb" yaml:"max_memory_mb"`
	// MaxCPUPercent is the maximum CPU usage percentage (0 = unlimited).
	MaxCPUPercent int `json:"max_cpu_percent" yaml:"max_cpu_percent"`
	// NetworkIsolation enables network isolation.
	NetworkIsolation bool `json:"network_isolation" yaml:"network_isolation"`
	// AllowedHosts is a list of allowed hosts when network isolation is enabled.
	AllowedHosts []string `json:"allowed_hosts" yaml:"allowed_hosts"`
	// DisableGPU disables GPU acceleration.
	DisableGPU bool `json:"disable_gpu" yaml:"disable_gpu"`
	// DisableJavaScript disables JavaScript execution.
	DisableJavaScript bool `json:"disable_javascript" yaml:"disable_javascript"`
	// DisableImages disables image loading.
	DisableImages bool `json:"disable_images" yaml:"disable_images"`
	// DisablePlugins disables browser plugins.
	DisablePlugins bool `json:"disable_plugins" yaml:"disable_plugins"`
	// DisablePopups disables popup windows.
	DisablePopups bool `json:"disable_popups" yaml:"disable_popups"`
	// DisableDownloads disables file downloads.
	DisableDownloads bool `json:"disable_downloads" yaml:"disable_downloads"`
	// CleanupOnExit removes temporary files on exit.
	CleanupOnExit bool `json:"cleanup_on_exit" yaml:"cleanup_on_exit"`
	// SessionTimeout is the maximum session duration.
	SessionTimeout time.Duration `json:"session_timeout" yaml:"session_timeout"`
}

SandboxConfig contains sandbox configuration options.

func DefaultSandboxConfig 

func DefaultSandboxConfig() *SandboxConfig

DefaultSandboxConfig returns the default sandbox configuration.

type SandboxSession 

type SandboxSession struct {
	// ID is the unique session identifier.
	ID string `json:"id"`
	// ProfilePath is the path to the browser profile.
	ProfilePath string `json:"profile_path"`
	// DataDir is the path to the session data directory.
	DataDir string `json:"data_dir"`
	// CreatedAt is when the session was created.
	CreatedAt time.Time `json:"created_at"`
	// ExpiresAt is when the session expires.
	ExpiresAt time.Time `json:"expires_at"`
	// Active indicates if the session is active.
	Active bool `json:"active"`
	// ResourceUsage tracks resource usage.
	ResourceUsage *ResourceUsage `json:"resource_usage"`
}

SandboxSession represents an isolated browser session.

type ScrapeRequest 

type ScrapeRequest struct {
	// URL is the page URL to scrape.
	URL string `json:"url" validate:"required,url"`
	// Selectors is a map of name to CSS selector for data extraction.
	Selectors map[string]SelectorConfig `json:"selectors" validate:"required"`
	// WaitFor is the time to wait after page load (milliseconds).
	WaitFor int `json:"wait_for,omitempty"`
	// WaitForSelector waits for a specific element to appear.
	WaitForSelector *string `json:"wait_for_selector,omitempty"`
	// SkipWaitLoad skips the full page load wait and relies on selector readiness instead.
	SkipWaitLoad bool `json:"skip_wait_load,omitempty"`
	// Timeout is the maximum time to wait (milliseconds).
	Timeout int `json:"timeout,omitempty"`
}

ScrapeRequest represents a request to scrape data from a page.

type ScrapeResponse 

type ScrapeResponse struct {
	// Data is the extracted data.
	Data map[string]interface{} `json:"data"`
	// URL is the scraped URL.
	URL string `json:"url"`
	// Title is the page title.
	Title string `json:"title"`
}

ScrapeResponse represents the result of data scraping.

type ScreenshotFormat 

type ScreenshotFormat string

ScreenshotFormat represents the image format for screenshots. 

const (
	// FormatPNG is PNG format.
	FormatPNG ScreenshotFormat = "png"
	// FormatJPEG is JPEG format.
	FormatJPEG ScreenshotFormat = "jpeg"
	// FormatWebP is WebP format.
	FormatWebP ScreenshotFormat = "webp"
)

type ScreenshotRequest 

type ScreenshotRequest struct {
	// URL is the page URL to capture.
	URL string `json:"url" validate:"required,url"`
	// Selector is an optional CSS selector to capture a specific element.
	Selector *string `json:"selector,omitempty"`
	// Format is the image format (png, jpeg, webp).
	Format ScreenshotFormat `json:"format,omitempty"`
	// Quality is the image quality (1-100, only for jpeg/webp).
	Quality int `json:"quality,omitempty"`
	// FullPage captures the full scrollable page if true.
	FullPage bool `json:"full_page,omitempty"`
	// Width is the viewport width.
	Width int `json:"width,omitempty"`
	// Height is the viewport height.
	Height int `json:"height,omitempty"`
	// WaitFor is the time to wait after page load (milliseconds).
	WaitFor int `json:"wait_for,omitempty"`
	// WaitForSelector waits for a specific element to appear.
	WaitForSelector *string `json:"wait_for_selector,omitempty"`
	// SkipWaitLoad skips the full page load wait and relies on selector readiness instead.
	SkipWaitLoad bool `json:"skip_wait_load,omitempty"`
	// Timeout is the maximum time to wait (milliseconds).
	Timeout int `json:"timeout,omitempty"`
}

ScreenshotRequest represents a request to capture a screenshot.

type ScreenshotResponse 

type ScreenshotResponse struct {
	// Data is the base64-encoded image data.
	Data string `json:"data"`
	// Format is the image format.
	Format ScreenshotFormat `json:"format"`
	// Width is the image width.
	Width int `json:"width"`
	// Height is the image height.
	Height int `json:"height"`
	// URL is the captured URL.
	URL string `json:"url"`
	// Title is the page title.
	Title string `json:"title"`
}

ScreenshotResponse represents the result of a screenshot capture.

type SearchResult 

type SearchResult struct {
	Title   string `json:"title"`
	URL     string `json:"url"`
	Snippet string `json:"snippet"`
}

SearchResult is a single search result entry.

type SecurityChecker 

type SecurityChecker struct {
	// contains filtered or unexported fields
}

SecurityChecker validates URLs against security rules.

func NewSecurityChecker 

func NewSecurityChecker(config *Config) *SecurityChecker

NewSecurityChecker creates a new security checker.

func (*SecurityChecker) CheckEvaluateAllowed 

func (s *SecurityChecker) CheckEvaluateAllowed() error

CheckEvaluateAllowed checks if JavaScript evaluation is allowed. This should be called before executing any JavaScript code via act:evaluate or wait --fn to prevent prompt injection attacks.

func (*SecurityChecker) CheckURL 

func (s *SecurityChecker) CheckURL(rawURL string) error

CheckURL validates a URL against the security rules.

func (*SecurityChecker) NormalizeAndCheckURL 

func (s *SecurityChecker) NormalizeAndCheckURL(rawURL string) (string, error)

NormalizeAndCheckURL validates a URL against security rules and returns a normalized URL string suitable for browser navigation.

func (*SecurityChecker) ValidateScript 

func (s *SecurityChecker) ValidateScript(script string) error

ValidateScript validates JavaScript code for safety. Note: This is a basic check. For production, consider using a proper sandbox. IMPORTANT: Even if this check passes, you should still call CheckEvaluateAllowed() to ensure JavaScript evaluation is enabled in the configuration.

func (*SecurityChecker) ValidateSelector 

func (s *SecurityChecker) ValidateSelector(selector string) error

ValidateSelector validates a CSS selector for safety.

type SelectorConfig 

type SelectorConfig struct {
	// Selector is the CSS selector.
	Selector string `json:"selector" validate:"required"`
	// Attribute is the attribute to extract (empty for text content).
	Attribute string `json:"attribute,omitempty"`
	// Multiple extracts all matching elements if true.
	Multiple bool `json:"multiple,omitempty"`
	// MaxMatches limits how many matching elements are extracted when Multiple is true.
	MaxMatches int `json:"max_matches,omitempty"`
}

SelectorConfig defines how to extract data from an element.

type Service 

type Service interface {
	// Status returns the browser status.
	Status(ctx context.Context) (*StatusResponse, error)
	// Start starts the browser.
	Start(ctx context.Context) error
	// Stop stops the browser.
	Stop(ctx context.Context) error

	// Tab management
	// Tabs returns all open tabs.
	Tabs(ctx context.Context) ([]*Tab, error)
	// OpenTab opens a new tab with the given URL.
	OpenTab(ctx context.Context, url string) (*Tab, error)
	// FocusTab focuses a tab by target ID.
	FocusTab(ctx context.Context, targetID string) error
	// CloseTab closes a tab by target ID.
	CloseTab(ctx context.Context, targetID string) error

	// Navigation
	// Navigate navigates to a URL in the current or specified tab.
	Navigate(ctx context.Context, req *NavigateRequest) (*NavigateResponse, error)

	// Content capture
	// Screenshot captures a screenshot of a page.
	Screenshot(ctx context.Context, req *ScreenshotRequest) (*ScreenshotResponse, error)
	// PDF generates a PDF from a page.
	PDF(ctx context.Context, req *PDFRequest) (*PDFResponse, error)
	// Snapshot returns a structured snapshot of the page (for AI interaction).
	Snapshot(ctx context.Context, req *SnapshotRequest) (*SnapshotResponse, error)

	// Data extraction
	// Scrape extracts data from a page.
	Scrape(ctx context.Context, req *ScrapeRequest) (*ScrapeResponse, error)

	// Actions
	// Act performs an action on the page (click, type, etc.).
	Act(ctx context.Context, req *ActRequest) (*ActResponse, error)
	// Automate runs a multi-step automation task.
	Automate(ctx context.Context, req *AutomateRequest) (*AutomateResponse, error)

	// Console
	// Console returns console messages from the page.
	Console(ctx context.Context, req *ConsoleRequest) (*ConsoleResponse, error)

	// Recipes
	// ExecuteRecipe runs a named recipe with the given params.
	ExecuteRecipe(ctx context.Context, req *RecipeRequest) (*RecipeResponse, error)
	// Recipes returns the recipe registry for listing available recipes.
	Recipes() *RecipeRegistry

	// Close closes the browser service and releases resources.
	Close() error
}

Service defines the browser automation service interface. This interface is designed to be compatible with clawdbot's browser tool.

type SessionEngine 

type SessionEngine string

SessionEngine identifies which browser engine owns a session. 

const (
	// SessionEngineLightpanda is the read-only Lightpanda engine.
	SessionEngineLightpanda SessionEngine = "lightpanda"
	// SessionEngineChromiumManaged is Blue-managed Chromium.
	SessionEngineChromiumManaged SessionEngine = "chromium_managed"
	// SessionEngineChromiumRelay is a relay/local-Chrome Chromium session.
	SessionEngineChromiumRelay SessionEngine = "chromium_relay"
)

type SessionEngineDetail 

type SessionEngineDetail string

SessionEngineDetail identifies the precise runtime behind a compatibility engine bucket. 

const (
	// SessionEngineDetailLightpandaShim is Blue's read-layer Lightpanda shim.
	SessionEngineDetailLightpandaShim SessionEngineDetail = "lightpanda_shim"
	// SessionEngineDetailLightpandaBinary is the upstream Lightpanda binary runtime.
	SessionEngineDetailLightpandaBinary SessionEngineDetail = "lightpanda_binary"
	// SessionEngineDetailChromiumManaged is Blue-managed Chromium.
	SessionEngineDetailChromiumManaged SessionEngineDetail = "chromium_managed"
	// SessionEngineDetailChromiumRelay is relay/local-Chrome Chromium.
	SessionEngineDetailChromiumRelay SessionEngineDetail = "chromium_relay"
)

type SessionImageMonitor 

type SessionImageMonitor struct {
	Screenshot string              `json:"screenshot,omitempty"`
	History    []SessionScreenshot `json:"history,omitempty"`
	UpdatedAt  string              `json:"updated_at,omitempty"`
	Status     string              `json:"status,omitempty"`
}

SessionImageMonitor contains screenshot monitor payload for Chromium sessions.

type SessionInfo 

type SessionInfo struct {
	ID           string              `json:"id"`
	Status       string              `json:"status"`
	CurrentURL   string              `json:"current_url,omitempty"`
	PageTitle    string              `json:"page_title,omitempty"`
	CreatedAt    string              `json:"created_at"`
	LastActivity string              `json:"last_activity"`
	Engine       SessionEngine       `json:"engine"`
	EngineDetail SessionEngineDetail `json:"engine_detail,omitempty"`
	SessionLayer SessionLayer        `json:"session_layer,omitempty"`
	MonitorKind  SessionMonitorKind  `json:"monitor_kind"`
}

SessionInfo is the unified browser session summary returned to clients.

type SessionLayer 

type SessionLayer string

SessionLayer identifies the capability layer that owns a session. 

const (
	// SessionLayerRead is the fetch/read layer.
	SessionLayerRead SessionLayer = "read"
	// SessionLayerBrowserLite is the browser-lite layer.
	SessionLayerBrowserLite SessionLayer = "browser_lite"
	// SessionLayerFullBrowser is the full browser layer.
	SessionLayerFullBrowser SessionLayer = "full_browser"
)

type SessionMonitorKind 

type SessionMonitorKind string

SessionMonitorKind identifies how a session should be monitored. 

const (
	// SessionMonitorKindText represents structured text monitoring.
	SessionMonitorKindText SessionMonitorKind = "text"
	// SessionMonitorKindImage represents screenshot-based monitoring.
	SessionMonitorKindImage SessionMonitorKind = "image"
)

type SessionMonitorResponse 

type SessionMonitorResponse struct {
	Kind  SessionMonitorKind   `json:"kind"`
	Image *SessionImageMonitor `json:"image,omitempty"`
	Text  *SessionTextMonitor  `json:"text,omitempty"`
	Error string               `json:"error,omitempty"`
}

SessionMonitorResponse is the unified monitor API payload.

type SessionRouteProvider 

type SessionRouteProvider interface {
	ListBrowserSessions(ctx context.Context) ([]SessionInfo, error)
	CreateBrowserSession(ctx context.Context) (*SessionInfo, error)
	GetBrowserSession(ctx context.Context, id string) (*SessionInfo, error)
	CloseBrowserSession(ctx context.Context, id string) error
	NavigateBrowserSession(ctx context.Context, id string, url string) (*NavigateResponse, error)
	CaptureBrowserSessionMonitor(ctx context.Context, id string) (*SessionMonitorResponse, error)
	CaptureBrowserSessionScreenshot(ctx context.Context, id string) (*SessionScreenshotResponse, error)
}

SessionRouteProvider allows browser session HTTP routes to be backed by a multi-engine session manager instead of a single browser.Service instance.

type SessionScreenshot 

type SessionScreenshot struct {
	// Data is the base64-encoded PNG payload.
	Data string `json:"data"`
	// URL is the tab URL at capture time.
	URL string `json:"url,omitempty"`
	// Title is the tab title at capture time.
	Title string `json:"title,omitempty"`
	// CapturedAt is the RFC3339 timestamp when the frame was stored.
	CapturedAt string `json:"captured_at"`
	// Scope describes the capture mode (for example viewport or full_page).
	Scope string `json:"scope,omitempty"`
}

SessionScreenshot stores a captured session frame for monitor playback.

type SessionScreenshotResponse 

type SessionScreenshotResponse struct {
	Screenshot string              `json:"screenshot,omitempty"`
	History    []SessionScreenshot `json:"history,omitempty"`
	Error      string              `json:"error,omitempty"`
}

SessionScreenshotResponse is the legacy screenshot compatibility payload.

type SessionTextMonitor 

type SessionTextMonitor struct {
	Title            string `json:"title,omitempty"`
	URL              string `json:"url,omitempty"`
	Summary          string `json:"summary,omitempty"`
	TreePreview      string `json:"tree_preview,omitempty"`
	InteractiveCount int    `json:"interactive_count,omitempty"`
	UpdatedAt        string `json:"updated_at,omitempty"`
	Status           string `json:"status,omitempty"`
}

SessionTextMonitor contains the lightweight text monitor payload.

type SnapshotRequest 

type SnapshotRequest struct {
	// TargetID is the optional tab ID.
	TargetID string `json:"target_id,omitempty"`
	// Format is the snapshot format: "ai" or "aria".
	Format string `json:"format,omitempty"`
	// Selector limits the snapshot to a specific element.
	Selector string `json:"selector,omitempty"`
	// Interactive only includes interactive elements.
	Interactive bool `json:"interactive,omitempty"`
	// Compact uses compact output format.
	Compact bool `json:"compact,omitempty"`
	// MaxChars limits the output character count.
	MaxChars int `json:"max_chars,omitempty"`
	// Depth limits the tree depth.
	Depth int `json:"depth,omitempty"`
}

SnapshotRequest represents a request for a page snapshot.

type SnapshotResponse 

type SnapshotResponse struct {
	// Snapshot is the text representation of the page.
	Snapshot string `json:"snapshot"`
	// Format is the snapshot format used.
	Format string `json:"format"`
	// URL is the page URL.
	URL string `json:"url"`
	// Title is the page title.
	Title string `json:"title"`
	// TargetID is the tab ID.
	TargetID string `json:"target_id"`
	// ElementCount is the number of elements in the snapshot.
	ElementCount int `json:"element_count"`
}

SnapshotResponse represents a page snapshot.

type StatusResponse 

type StatusResponse struct {
	// Running indicates if the browser is running.
	Running bool `json:"running"`
	// Version is the browser version.
	Version string `json:"version,omitempty"`
	// TabCount is the number of open tabs.
	TabCount int `json:"tab_count"`
	// ActiveTabID is the ID of the active tab.
	ActiveTabID string `json:"active_tab_id,omitempty"`
	// Uptime is the browser uptime in seconds.
	Uptime int64 `json:"uptime,omitempty"`
}

StatusResponse represents the browser status.

type StepResult 

type StepResult struct {
	// Step is the step index.
	Step int `json:"step"`
	// Action is the action type.
	Action ActionType `json:"action"`
	// Success indicates if the step succeeded.
	Success bool `json:"success"`
	// Error is the error message if failed.
	Error string `json:"error,omitempty"`
	// Data contains any data returned by the step.
	Data interface{} `json:"data,omitempty"`
	// Duration is the step duration in milliseconds.
	Duration int64 `json:"duration"`
}

StepResult represents the result of a single automation step.

type Tab 

type Tab struct {
	// TargetID is the unique identifier for the tab.
	TargetID string `json:"target_id"`
	// URL is the current URL.
	URL string `json:"url"`
	// Title is the page title.
	Title string `json:"title"`
	// Active indicates if this is the active tab.
	Active bool `json:"active"`
}

Tab represents a browser tab.

type Viewport 

type Viewport struct {
	Width  int
	Height int
}

Viewport represents browser viewport dimensions.

func DefaultViewport 

func DefaultViewport() Viewport

DefaultViewport returns the default viewport.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.