browser

package
v0.3.2 Latest Latest
Warning

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

 Go to latest Published: Apr 6, 2026 License: MIT Imports: 32 Imported by: 0

Documentation

Overview

Package browser defines the persistent browser session metadata model used by the planned `tap browser ...` workflow.

Phase 1 establishes the durable state contract before the runtime is added:

  • A session is one persistent browser instance, either local or remote.
  • A tab is a named tracked browser target within a session.
  • Stored metadata is the source of truth for names and selection defaults.
  • Each command must reconcile metadata against live targets before acting.
  • Untracked live browser tabs are ignored by default.
  • Missing tracked targets become stale until they are recreated or removed.

The package also defines the initial local-vs-remote capability matrix used by CLI help text and README documentation:

  • Local sessions own their browser process and profile directory.
  • Remote sessions bind metadata to an explicit CDP WebSocket endpoint.
  • Remote session creation validates the endpoint up front.
  • Remote session close removes tap metadata only and never kills the remote browser process.

Package browser manages alternative browser backends for CDP-based automation.

Index

Constants

View Source 
const (
	// StateVersion is the current on-disk schema version for browser metadata.
	StateVersion = 1

	// DefaultSessionName is the session used when --session is omitted.
	DefaultSessionName = "default"

	// EnvStateRoot overrides the default durable state directory.
	EnvStateRoot = "TAP_BROWSER_STATE_DIR"
)
View Source 
const TargetTypePage = "page"

Variables

View Source 
var (
	ErrSessionNotFound   = errors.New("browser session not found")
	ErrNoTabs            = errors.New("no tracked tabs found")
	ErrAmbiguousTab      = errors.New("browser tab selection is ambiguous")
	ErrTabNotFound       = errors.New("browser tab not found")
	ErrClosedTabSelected = errors.New("browser tab is closed")
	ErrStaleTabSelected  = errors.New("browser tab is stale")
)

Functions

func BackTarget added in v0.3.0 

func BackTarget(ctx context.Context, debugURL string, targetID string) error

BackTarget navigates the tab backwards in history.

func CapabilitiesForMode added in v0.1.7 

func CapabilitiesForMode(mode Mode) map[Operation]Capability

CapabilitiesForMode returns the documented capability contract for the given mode.

func CheckProcess added in v0.1.7 

func CheckProcess(record *ProcessRecord) error

CheckProcess verifies that the process described by record is alive and its debug endpoint is reachable.

func CheckProcessContext added in v0.1.7 

func CheckProcessContext(ctx context.Context, record *ProcessRecord) error

CheckProcessContext is like CheckProcess but accepts a context for cancellation.

func ClearCookiesTarget added in v0.3.0 

func ClearCookiesTarget(ctx context.Context, debugURL string, targetID string) error

ClearCookiesTarget deletes all cookies for the current page.

func ClearIntercept added in v0.2.0 

func ClearIntercept(ctx context.Context, debugURL string, targetID string) error

ClearIntercept disables the Fetch domain on a target.

func ClickTarget added in v0.3.0 

func ClickTarget(ctx context.Context, debugURL string, targetID string, sel string) error

ClickTarget dispatches a real mouse click on the first element matching sel. chromedp.Click sends the full mouseMoved → mousePressed → mouseReleased sequence.

func CloseTarget added in v0.1.7 

func CloseTarget(ctx context.Context, debugURL string, targetID string) error

CloseTarget closes the browser tab identified by targetID.

func CreateTarget added in v0.1.7 

func CreateTarget(ctx context.Context, debugURL string, url string) (string, error)

CreateTarget creates a new browser tab navigated to url and returns its target ID.

func DefaultStateRoot added in v0.1.7 

func DefaultStateRoot() (string, error)

DefaultStateRoot returns the durable directory used for browser metadata. Uses $XDG_CACHE_HOME/tap/browser, falling back to ~/.cache/tap/browser.

func DialogTarget added in v0.3.0 

func DialogTarget(ctx context.Context, debugURL string, targetID string, accept bool, promptText string) error

DialogTarget accepts or dismisses a pending JavaScript dialog (alert/confirm/prompt). For prompt dialogs, promptText is entered before accepting.

func EnableNetworkLog added in v0.2.0 

func EnableNetworkLog(ctx context.Context, debugURL string, targetID string, filter NetworkFilter) (<-chan NetworkEntry, func(), error)

EnableNetworkLog enables the Network domain on a target and streams completed request/response entries to the returned channel. The channel is buffered (256 entries); if the buffer fills, new entries are dropped.

Call the returned cancel func to stop capturing and close the channel. The caller should drain the channel or call cancel to avoid goroutine leaks.

func EvalTarget added in v0.1.7 

func EvalTarget(ctx context.Context, debugURL string, targetID string, js string) (any, error)

EvalTarget evaluates JavaScript in the context of an existing browser tab and returns the result.

func FillTarget added in v0.1.7 

func FillTarget(ctx context.Context, debugURL string, targetID string, fields []FillField, submitSelector string) error

FillTarget fills form fields in a browser tab using React-compatible value setting.

func ForwardTarget added in v0.3.0 

func ForwardTarget(ctx context.Context, debugURL string, targetID string) error

ForwardTarget navigates the tab forwards in history.

func GetHTMLTarget added in v0.3.0 

func GetHTMLTarget(ctx context.Context, debugURL string, targetID string, sel string) (string, string, error)

GetHTMLTarget returns the outerHTML of the element matching sel, or the full page HTML if sel is empty.

func GetResponseBody added in v0.2.0 

func GetResponseBody(ctx context.Context, debugURL string, targetID string, requestID string) ([]byte, error)

GetResponseBody fetches the response body for a completed request by its ID.

func HoverTarget added in v0.3.0 

func HoverTarget(ctx context.Context, debugURL string, targetID string, sel string) error

HoverTarget moves the mouse to the center of the element matching sel, dispatching mouseMoved events that trigger CSS :hover states and mouseenter listeners.

func KeypressTarget added in v0.3.0 

func KeypressTarget(ctx context.Context, debugURL string, targetID string, keys string) error

KeypressTarget sends key events to the page (not a specific element). The keys string uses chromedp/kb constants: "\r" for Enter, "\t" for Tab, "\u001b" for Escape, etc. Regular characters are sent as-is.

func KillProcess added in v0.1.7 

func KillProcess(record *ProcessRecord) error

KillProcess terminates the Chrome process described by record. It sends a graceful shutdown signal first and falls back to forceful termination after a grace period. 

func NavigateTarget(ctx context.Context, debugURL string, targetID string, url string) error

NavigateTarget navigates an existing browser tab to url and waits for the body to be ready.

func PDFTarget added in v0.3.0 

func PDFTarget(ctx context.Context, debugURL string, targetID string, landscape bool, printBackground bool, scale float64) ([]byte, error)

PDFTarget saves the current page as PDF and returns the bytes.

func ReloadTarget added in v0.3.0 

func ReloadTarget(ctx context.Context, debugURL string, targetID string) error

ReloadTarget reloads the current page in the tab.

func ScreenshotTarget added in v0.1.7 

func ScreenshotTarget(ctx context.Context, debugURL string, targetID string) ([]byte, error)

ScreenshotTarget captures a full-page screenshot of an existing browser tab and returns the PNG bytes.

func ScrollTarget added in v0.3.0 

func ScrollTarget(ctx context.Context, debugURL string, targetID string, sel string, x, y float64) error

ScrollTarget scrolls the element matching sel into view. If sel is empty, scrolls to the given x,y pixel coordinates.

func SelectTarget added in v0.3.0 

func SelectTarget(ctx context.Context, debugURL string, targetID string, sel string, value string) error

SelectTarget selects an option in a <select> element by value, dispatching focus, input, and change events.

func SetCookieTarget added in v0.3.0 

func SetCookieTarget(ctx context.Context, debugURL string, targetID string, name, value, domain, path string) error

SetCookieTarget sets a cookie on the page.

func SetInterceptRules added in v0.2.0 

func SetInterceptRules(ctx context.Context, debugURL string, targetID string, rules []InterceptRule) (func(), error)

SetInterceptRules enables Fetch domain interception with the given rules. It replaces any previously set rules. The returned cancel func stops the interception goroutine and disables the Fetch domain.

Pass nil/empty rules to effectively disable interception (or use ClearIntercept).

func TypeTarget added in v0.3.0 

func TypeTarget(ctx context.Context, debugURL string, targetID string, sel string, text string) error

TypeTarget sends individual key events to the element matching sel. Unlike FillTarget which sets .value directly, this dispatches keyDown/keyUp per character — behaving like a real user typing.

func ValidateInterceptRules added in v0.2.0 

func ValidateInterceptRules(rules []InterceptRule) error

ValidateInterceptRules checks that rules are well-formed.

func ValidateSessionName added in v0.1.7 

func ValidateSessionName(name string) error

ValidateSessionName checks the user-facing session naming rules.

func ValidateTabName added in v0.1.7 

func ValidateTabName(name string) error

ValidateTabName checks the user-facing tab naming rules.

func WaitForTarget added in v0.3.0 

func WaitForTarget(ctx context.Context, debugURL string, targetID string, sel string, timeout time.Duration) error

WaitForTarget waits until the element matching sel is visible in the tab. The caller controls the deadline via ctx.

Types

type Capability added in v0.1.7 

type Capability struct {
	Supported bool   `json:"supported"`
	Notes     string `json:"notes,omitempty"`
}

Capability describes whether an operation is supported for a session mode.

type ChromeInfo added in v0.3.2 

type ChromeInfo struct {
	Path    string
	Version string
}

ChromeInfo holds information about an installed Chrome browser.

func DetectChrome added in v0.3.2 

func DetectChrome() *ChromeInfo

DetectChrome finds a Chrome/Chromium installation and returns its path and version. It reuses the same discovery logic as the browser launcher (findChrome). Returns nil if no Chrome is found.

type CookieEntry added in v0.3.0 

type CookieEntry struct {
	Name     string  `json:"name"`
	Value    string  `json:"value"`
	Domain   string  `json:"domain"`
	Path     string  `json:"path"`
	Expires  float64 `json:"expires"`
	HTTPOnly bool    `json:"httpOnly"`
	Secure   bool    `json:"secure"`
	Session  bool    `json:"session"`
	SameSite string  `json:"sameSite,omitempty"`
}

CookieEntry represents a browser cookie for JSON output.

func GetCookiesTarget added in v0.3.0 

func GetCookiesTarget(ctx context.Context, debugURL string, targetID string) ([]CookieEntry, error)

GetCookiesTarget returns all cookies for the current page.

type FillField added in v0.1.7 

type FillField struct {
	Selector string
	Value    string
}

FillField pairs a CSS selector with the value to fill.

type FormField added in v0.1.7 

type FormField struct {
	Selector    string `json:"selector"`
	Tag         string `json:"tag"`
	Type        string `json:"type,omitempty"`
	Name        string `json:"name,omitempty"`
	ID          string `json:"id,omitempty"`
	Placeholder string `json:"placeholder,omitempty"`
	Value       string `json:"value,omitempty"`
	Label       string `json:"label,omitempty"`
	Required    bool   `json:"required,omitempty"`
	Disabled    bool   `json:"disabled,omitempty"`
	Role        string `json:"role,omitempty"`
}

FormField describes a fillable form element on the page.

func FormsTarget added in v0.1.7 

func FormsTarget(ctx context.Context, debugURL string, targetID string) ([]FormField, error)

FormsTarget discovers fillable form elements in a browser tab.

type InterceptRule added in v0.2.0 

type InterceptRule struct {
	Filter      NetworkFilter     `json:"filter"`
	Block       bool              `json:"block,omitempty"`
	AddHeaders  map[string]string `json:"addHeaders,omitempty"`
	MockStatus  int               `json:"mockStatus,omitempty"`
	MockBody    string            `json:"mockBody,omitempty"`
	MockHeaders map[string]string `json:"mockHeaders,omitempty"`
}

InterceptRule defines how to modify or block requests matching a filter. Block and MockBody are mutually exclusive.

type Lightpanda 

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

Lightpanda manages the Lightpanda browser process.

func NewLightpanda 

func NewLightpanda(binDir, port string) *Lightpanda

NewLightpanda creates a new Lightpanda manager. binDir is where the binary is stored; if empty, defaults to ~/.cache/tap/lightpanda/. port is the CDP port; if empty, defaults to 9222.

func (*Lightpanda) Cleanup 

func (lp *Lightpanda) Cleanup() error

Cleanup removes the downloaded binary and its metadata.

func (*Lightpanda) EnsureInstalled 

func (lp *Lightpanda) EnsureInstalled(ctx context.Context) error

EnsureInstalled downloads the Lightpanda binary if it doesn't exist or is empty.

func (*Lightpanda) Installed added in v0.3.2 

func (lp *Lightpanda) Installed() bool

Installed reports whether the Lightpanda binary exists and is non-empty.

func (*Lightpanda) ReadMeta added in v0.3.2 

func (lp *Lightpanda) ReadMeta() (*Meta, error)

ReadMeta reads the metadata file for the installed binary. Returns nil if no metadata file exists.

func (*Lightpanda) Running 

func (lp *Lightpanda) Running() bool

Running reports whether the Lightpanda server is currently running.

func (*Lightpanda) Start 

func (lp *Lightpanda) Start(ctx context.Context) error

Start launches the Lightpanda server and waits for it to be ready. It is safe to call multiple times — subsequent calls are no-ops if already running.

func (*Lightpanda) Stop 

func (lp *Lightpanda) Stop()

Stop terminates the Lightpanda process.

func (*Lightpanda) Update added in v0.3.2 

func (lp *Lightpanda) Update(ctx context.Context) error

Update re-downloads the Lightpanda binary regardless of whether it exists.

func (*Lightpanda) WSURL 

func (lp *Lightpanda) WSURL() string

WSURL returns the WebSocket URL for the running Lightpanda instance.

type LocalConfig added in v0.1.7 

type LocalConfig struct {
	ProfileDir string `json:"profile_dir"`
	Headless   bool   `json:"headless"`
}

LocalConfig freezes local launch settings into session metadata.

type Manager added in v0.1.7 

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

Manager coordinates browser session lifecycle, tab management, and browser actions using the metadata store and CDP transport layer.

func NewManager added in v0.1.7 

func NewManager(store *Store) *Manager

NewManager creates a session manager backed by the given store.

func (*Manager) Back added in v0.3.0 

func (m *Manager) Back(ctx context.Context, sessionName string, tabName string) error

Back navigates the tracked tab backwards in history.

func (*Manager) ClearCookies added in v0.3.0 

func (m *Manager) ClearCookies(ctx context.Context, sessionName string, tabName string) error

ClearCookies deletes all cookies for the current page in a tracked tab.

func (*Manager) Click added in v0.3.0 

func (m *Manager) Click(ctx context.Context, sessionName string, tabName string, sel string) error

Click dispatches a real mouse click on the element matching sel in a tracked tab.

func (*Manager) CloseSession added in v0.1.7 

func (m *Manager) CloseSession(ctx context.Context, name string) error

CloseSession terminates a browser session, kills the local process if applicable, and removes all related metadata.

func (*Manager) CloseTab added in v0.1.7 

func (m *Manager) CloseTab(ctx context.Context, sessionName string, tabName string) error

CloseTab closes a browser tab and removes it from session metadata.

func (*Manager) CreateSession added in v0.1.7 

func (m *Manager) CreateSession(ctx context.Context, name string, mode Mode, opts SessionOptions) error

CreateSession launches or connects to a browser and persists session metadata.

func (*Manager) CreateTab added in v0.1.7 

func (m *Manager) CreateTab(ctx context.Context, sessionName string, tabName string, url string) error

CreateTab opens a new browser tab and tracks it in session metadata.

func (*Manager) Dialog added in v0.3.0 

func (m *Manager) Dialog(ctx context.Context, sessionName string, tabName string, accept bool, promptText string) error

Dialog accepts or dismisses a pending JavaScript dialog in a tracked tab.

func (*Manager) Evaluate added in v0.1.7 

func (m *Manager) Evaluate(ctx context.Context, sessionName string, tabName string, js string) (any, error)

Evaluate runs JavaScript in a tracked tab and returns the result.

func (*Manager) Fill added in v0.1.7 

func (m *Manager) Fill(ctx context.Context, sessionName string, tabName string, fields []FillField, submitSelector string) error

Fill sets values in form fields of a tracked tab.

func (*Manager) Forms added in v0.1.7 

func (m *Manager) Forms(ctx context.Context, sessionName string, tabName string) ([]FormField, error)

Forms discovers fillable form elements in a tracked tab.

func (*Manager) Forward added in v0.3.0 

func (m *Manager) Forward(ctx context.Context, sessionName string, tabName string) error

Forward navigates the tracked tab forwards in history.

func (*Manager) GetCookies added in v0.3.0 

func (m *Manager) GetCookies(ctx context.Context, sessionName string, tabName string) ([]CookieEntry, error)

GetCookies returns all cookies for the current page in a tracked tab.

func (*Manager) GetSession added in v0.1.7 

func (m *Manager) GetSession(_ context.Context, name string) (*SessionRecord, error)

GetSession resolves a session by name (or falls back to the selected/only session).

func (*Manager) Hover added in v0.3.0 

func (m *Manager) Hover(ctx context.Context, sessionName string, tabName string, sel string) error

Hover moves the mouse to the element matching sel in a tracked tab.

func (*Manager) Keypress added in v0.3.0 

func (m *Manager) Keypress(ctx context.Context, sessionName string, tabName string, keys string) error

Keypress sends key events to the page in a tracked tab.

func (*Manager) ListSessions added in v0.1.7 

func (m *Manager) ListSessions(_ context.Context) (*SessionList, error)

ListSessions returns all tracked sessions sorted by name.

func (*Manager) ListTabs added in v0.1.7 

func (m *Manager) ListTabs(_ context.Context, sessionName string) (*TabList, error)

ListTabs returns all tracked tabs for a session sorted by creation time.

func (*Manager) Navigate added in v0.1.7 

func (m *Manager) Navigate(ctx context.Context, sessionName string, tabName string, url string) error

Navigate changes the URL of a tracked tab.

func (*Manager) NetworkClearIntercept added in v0.2.0 

func (m *Manager) NetworkClearIntercept(ctx context.Context, sessionName string, tabName string) error

NetworkClearIntercept removes all Fetch domain interception rules from a tracked tab.

func (*Manager) NetworkGetBody added in v0.2.0 

func (m *Manager) NetworkGetBody(ctx context.Context, sessionName string, tabName string, requestID string) ([]byte, error)

NetworkGetBody fetches the response body for a completed request by its request ID from a tracked tab.

func (*Manager) NetworkIntercept added in v0.2.0 

func (m *Manager) NetworkIntercept(ctx context.Context, sessionName string, tabName string, rules []InterceptRule) error

NetworkIntercept sets Fetch domain interception rules on a tracked tab. Replaces any previously set rules (cancels the old interception goroutine).

func (*Manager) NetworkLog added in v0.2.0 

func (m *Manager) NetworkLog(ctx context.Context, sessionName string, tabName string, filter NetworkFilter) (<-chan NetworkEntry, func(), error)

NetworkLog starts capturing network requests for a tracked tab and streams completed entries to the returned channel. Call cancel to stop capturing.

func (*Manager) NetworkWait added in v0.2.0 

func (m *Manager) NetworkWait(ctx context.Context, sessionName string, tabName string, filter NetworkFilter, includeBody bool) (*NetworkEntry, error)

NetworkWait blocks until a network request matching the filter completes in a tracked tab. If includeBody is true, the response body is fetched before returning. The caller controls the timeout via ctx.

func (*Manager) PDF added in v0.3.0 

func (m *Manager) PDF(ctx context.Context, sessionName string, tabName string, landscape bool, printBackground bool, scale float64) (*PDFResult, error)

PDF saves the current page as PDF from a tracked tab.

func (*Manager) Reconcile added in v0.1.7 

func (m *Manager) Reconcile(ctx context.Context, sessionName string) error

Reconcile refreshes tab liveness by comparing metadata against live CDP targets.

func (*Manager) Reload added in v0.3.0 

func (m *Manager) Reload(ctx context.Context, sessionName string, tabName string) error

Reload reloads the current page in a tracked tab.

func (*Manager) ResolveTarget added in v0.3.0 

func (m *Manager) ResolveTarget(ctx context.Context, sessionName string, tabName string) (ResolvedTarget, error)

ResolveTarget resolves a session and tab to their CDP connection details. Exported for commands that need direct CDP access (e.g., text extraction).

func (*Manager) Screenshot added in v0.1.7 

func (m *Manager) Screenshot(ctx context.Context, sessionName string, tabName string) (*ScreenshotResult, error)

Screenshot captures a full-page PNG of a tracked tab.

func (*Manager) Scroll added in v0.3.0 

func (m *Manager) Scroll(ctx context.Context, sessionName string, tabName string, sel string, x, y float64) error

Scroll scrolls to the element matching sel, or to absolute x,y if sel is empty.

func (*Manager) Select added in v0.3.0 

func (m *Manager) Select(ctx context.Context, sessionName string, tabName string, sel string, value string) error

Select selects an option by value in a <select> element in a tracked tab.

func (*Manager) SelectTab added in v0.1.7 

func (m *Manager) SelectTab(ctx context.Context, sessionName string, tabName string) error

SelectTab persists the default tab used when --tab is omitted.

func (*Manager) SetCookie added in v0.3.0 

func (m *Manager) SetCookie(ctx context.Context, sessionName string, tabName string, name, value, domain, path string) error

SetCookie sets a cookie in a tracked tab.

func (*Manager) Type added in v0.3.0 

func (m *Manager) Type(ctx context.Context, sessionName string, tabName string, sel string, text string) error

Type sends individual key events to the element matching sel in a tracked tab.

func (*Manager) WaitFor added in v0.3.0 

func (m *Manager) WaitFor(ctx context.Context, sessionName string, tabName string, sel string, timeout time.Duration) error

WaitFor waits until the element matching sel is visible in a tracked tab.

type Meta added in v0.3.2 

type Meta struct {
	DownloadedAt time.Time `json:"downloaded_at"`
	URL          string    `json:"url"`
}

Meta holds metadata about the installed Lightpanda binary.

type Mode added in v0.1.7 

type Mode string

Mode identifies how a session connects to Chrome. 

const (
	ModeLocal  Mode = "local"
	ModeRemote Mode = "remote"
)

type NetworkEntry added in v0.2.0 

type NetworkEntry struct {
	RequestID    string            `json:"requestId"`
	URL          string            `json:"url"`
	Method       string            `json:"method"`
	Status       int64             `json:"status"`
	MIMEType     string            `json:"mimeType,omitempty"`
	ResourceType string            `json:"resourceType,omitempty"`
	ReqHeaders   map[string]string `json:"reqHeaders,omitempty"`
	ResHeaders   map[string]string `json:"resHeaders,omitempty"`
	Body         string            `json:"body,omitempty"`
	Error        string            `json:"error,omitempty"`
	Timestamp    time.Time         `json:"timestamp"`
}

NetworkEntry represents a captured network request/response pair.

func WaitForRequest added in v0.2.0 

func WaitForRequest(ctx context.Context, debugURL string, targetID string, filter NetworkFilter, includeBody bool) (*NetworkEntry, error)

WaitForRequest enables the Network domain and blocks until a request matching the filter completes (response received + loading finished/failed). It returns the first matching NetworkEntry. If includeBody is true, the response body is fetched before returning.

The caller controls the timeout via ctx (e.g. context.WithTimeout).

type NetworkFilter added in v0.2.0 

type NetworkFilter struct {
	URLPattern    string   `json:"urlPattern,omitempty"`
	Methods       []string `json:"methods,omitempty"`
	ResourceTypes []string `json:"resourceTypes,omitempty"`
}

NetworkFilter specifies criteria for matching network requests.

type Operation added in v0.1.7 

type Operation string

Operation is a user-facing browser action supported by the session manager. 

const (
	OperationSessionNew   Operation = "session_new"
	OperationSessionClose Operation = "session_close"
	OperationTabNew       Operation = "tab_new"
	OperationTabClose     Operation = "tab_close"
	OperationNavigate     Operation = "navigate"
	OperationEvaluate     Operation = "evaluate"
	OperationScreenshot   Operation = "screenshot"
)

type PDFResult added in v0.3.0 

type PDFResult struct {
	Data        []byte
	SessionName string
	TabName     string
}

PDFResult holds the PDF data and resolved names.

type ProcessRecord added in v0.1.7 

type ProcessRecord struct {
	PID            int       `json:"pid,omitempty"`
	DebugURL       string    `json:"debug_url,omitempty"`
	OwnershipToken string    `json:"ownership_token,omitempty"`
	StartedAt      time.Time `json:"started_at,omitempty"`
}

ProcessRecord stores the launch markers needed for later ownership checks.

func LaunchBrowser added in v0.1.7 

func LaunchBrowser(ctx context.Context, config LocalConfig) (*ProcessRecord, error)

LaunchBrowser starts a managed Chrome process with remote debugging enabled. The returned ProcessRecord contains the PID, debug WebSocket URL, and an ownership token that later calls can use for verification.

type RemoteConfig added in v0.1.7 

type RemoteConfig struct {
	WSURL string `json:"ws_url"`
}

RemoteConfig freezes the remote reconnect endpoint into session metadata.

type ResolvedTarget added in v0.3.0 

type ResolvedTarget = resolvedTarget

ResolvedTarget holds the result of resolving a session and tab for CDP I/O.

type ScreenshotResult added in v0.1.7 

type ScreenshotResult struct {
	Data        []byte
	SessionName string
	TabName     string
}

ScreenshotResult holds the screenshot data and resolved names.

type SessionList added in v0.1.7 

type SessionList struct {
	Sessions []*SessionRecord
}

SessionList holds the result of listing sessions.

type SessionOptions added in v0.1.7 

type SessionOptions struct {
	// Headless controls whether a local browser launches headlessly.
	Headless bool
	// WSURL is the remote browser WebSocket endpoint (remote mode only).
	WSURL string
}

SessionOptions holds optional settings for session creation.

type SessionRecord added in v0.1.7 

type SessionRecord struct {
	Name             string                   `json:"name"`
	Mode             Mode                     `json:"mode"`
	Local            *LocalConfig             `json:"local,omitempty"`
	Remote           *RemoteConfig            `json:"remote,omitempty"`
	Process          *ProcessRecord           `json:"process,omitempty"`
	SelectedTab      string                   `json:"selected_tab,omitempty"`
	Tabs             map[string]*TabRecord    `json:"tabs,omitempty"`
	Capabilities     map[Operation]Capability `json:"capabilities,omitempty"`
	CreatedAt        time.Time                `json:"created_at"`
	UpdatedAt        time.Time                `json:"updated_at"`
	LastReconciledAt time.Time                `json:"last_reconciled_at,omitempty"`
}

SessionRecord stores one persistent browser session and its tracked tabs.

func NewLocalSession added in v0.1.7 

func NewLocalSession(name string, profileDir string, headless bool, now time.Time) (*SessionRecord, error)

NewLocalSession builds a validated local session record.

func NewRemoteSession added in v0.1.7 

func NewRemoteSession(name string, wsURL string, now time.Time) (*SessionRecord, error)

NewRemoteSession builds a validated remote session record.

func (*SessionRecord) ResolveTab added in v0.1.7 

func (s *SessionRecord) ResolveTab(name string) (*TabRecord, error)

ResolveTab returns an explicit tab, the selected tab, or the only live tracked tab when exactly one live tab exists.

type State added in v0.1.7 

type State struct {
	Version  int                       `json:"version"`
	Sessions map[string]*SessionRecord `json:"sessions"`
}

State is the durable browser session metadata written to disk.

func NewState added in v0.1.7 

func NewState() *State

NewState returns an empty metadata state with initialized maps.

func (*State) CreateSession added in v0.1.7 

func (s *State) CreateSession(session *SessionRecord) error

CreateSession adds a new named session.

func (*State) DeleteSession added in v0.1.7 

func (s *State) DeleteSession(name string) error

DeleteSession removes a session.

func (*State) DeleteTab added in v0.1.7 

func (s *State) DeleteTab(sessionName string, tabName string) error

DeleteTab removes a tracked tab and advances selection to the next live tab.

func (*State) Normalize added in v0.1.7 

func (s *State) Normalize()

Normalize repairs nil maps and empty versions loaded from disk.

func (*State) ReconcileSession added in v0.1.7 

func (s *State) ReconcileSession(sessionName string, liveTargetIDs []string, now time.Time) error

ReconcileSession updates tab liveness after reloading or reconnecting a browser session.

func (*State) ResolveSession added in v0.1.7 

func (s *State) ResolveSession(name string) (*SessionRecord, error)

ResolveSession returns the session matching name, or the "default" session when name is empty. Callers that need auto-creation of the default session should use Manager.resolveSessionName instead.

func (*State) SelectTab added in v0.1.7 

func (s *State) SelectTab(sessionName string, tabName string) error

SelectTab persists the default live tab used when --tab is omitted.

func (*State) UpsertTab added in v0.1.7 

func (s *State) UpsertTab(sessionName string, tab *TabRecord) error

UpsertTab creates or updates a tracked tab. The first live tab becomes selected.

func (*State) Validate added in v0.1.7 

func (s *State) Validate() error

Validate checks that the in-memory state satisfies the Phase 1 metadata contract.

type Store added in v0.1.7 

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

Store manages durable browser metadata with atomic writes and file locks.

func NewStore added in v0.1.7 

func NewStore(root string) (*Store, error)

NewStore initializes a metadata store rooted at the provided directory.

func (*Store) Load added in v0.1.7 

func (s *Store) Load() (*State, error)

Load reads the current browser metadata state from disk.

func (*Store) Root added in v0.1.7 

func (s *Store) Root() string

Root returns the store's durable state directory.

func (*Store) Save added in v0.1.7 

func (s *Store) Save(state *State) error

Save writes the full metadata state atomically.

func (*Store) Update added in v0.1.7 

func (s *Store) Update(fn func(*State) error) error

Update takes an exclusive store lock, mutates the current state, and saves it.

func (*Store) UpdateSession added in v0.1.7 

func (s *Store) UpdateSession(sessionName string, fn func(*State, *SessionRecord) error) error

UpdateSession combines session-scoped locking with durable store mutation.

func (*Store) WithSessionLock added in v0.1.7 

func (s *Store) WithSessionLock(sessionName string, fn func() error) error

WithSessionLock serializes higher-level runtime work for one session.

type TabList added in v0.1.7 

type TabList struct {
	Tabs        []*TabRecord
	SelectedTab string
}

TabList holds the result of listing tabs including the current selection.

type TabRecord added in v0.1.7 

type TabRecord struct {
	Name       string    `json:"name"`
	TargetID   string    `json:"target_id,omitempty"`
	URL        string    `json:"url,omitempty"`
	Status     TabStatus `json:"status"`
	CreatedAt  time.Time `json:"created_at"`
	UpdatedAt  time.Time `json:"updated_at"`
	LastSeenAt time.Time `json:"last_seen_at,omitempty"`
}

TabRecord stores the durable metadata for a tracked browser target.

func NewTab added in v0.1.7 

func NewTab(name string, targetID string, url string, now time.Time) (*TabRecord, error)

NewTab builds a validated tracked tab record.

type TabStatus added in v0.1.7 

type TabStatus string

TabStatus tracks whether a named tab can be used directly. 

const (
	TabStatusLive   TabStatus = "live"
	TabStatusStale  TabStatus = "stale"
	TabStatusClosed TabStatus = "closed"
)

type TargetInfo added in v0.1.7 

type TargetInfo struct {
	TargetID string
	Title    string
	URL      string
	Type     string
}

TargetInfo holds metadata about a CDP target (browser tab).

func ListTargets added in v0.1.7 

func ListTargets(ctx context.Context, debugURL string) ([]TargetInfo, error)

ListTargets enumerates page targets in a browser reachable at debugURL.

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.