engine

package
v0.5.0 Latest Latest
Warning

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

Go to latest
Published: Apr 20, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var ErrStaleRef = errors.New("stale ref: snapshot is missing or no longer matches the page")

ErrStaleRef indicates that a ref no longer maps to a live element.

Functions

func ApplyColorScheme added in v0.4.0

func ApplyColorScheme(page *rod.Page, scheme string) error

ApplyColorScheme emulates prefers-color-scheme. Accepts "dark", "light", "no-preference" (case-insensitive).

func ApplyDevice added in v0.4.0

func ApplyDevice(page *rod.Page, d Device) error

ApplyDevice applies viewport metrics, UA, and touch emulation from a preset.

func ApplyStealth

func ApplyStealth(page *rod.Page) error

ApplyStealth applies anti-detection patches to a page via CDP. Targets DataDome, Akamai, and similar bot-detection systems.

func ApplyTimezone added in v0.4.0

func ApplyTimezone(page *rod.Page, tz string) error

ApplyTimezone overrides the JavaScript Date/Intl timezone.

func ApplyUserAgent added in v0.4.0

func ApplyUserAgent(page *rod.Page, ua string) error

ApplyUserAgent overrides navigator.userAgent and the HTTP User-Agent header.

func ClickRef

func ClickRef(page *rod.Page, ref string, snapshot *PageSnapshot) error

ClickRef clicks the element at the given ref.

func CloseTab

func CloseTab(browser *rod.Browser, index int) (proto.TargetTargetID, error)

CloseTab closes the tab at the given index.

func CountSelector added in v0.4.0

func CountSelector(page *rod.Page, selector string) int

CountSelector returns the number of elements matching selector. Errors are swallowed and reported as 0 so the polling caller can distinguish "not-yet-rendered" from "match count below threshold".

func DetectAgent added in v0.2.0

func DetectAgent() bool

DetectAgent reports whether the current process runs inside an LLM agent. Detection order:

  1. GHOSTCHROME_PROFILE=agent|human (explicit override).
  2. GHOSTCHROME_AGENT=1|true (explicit opt-in).
  3. Known agent environment variables set by Claude Code, Cursor, Aider, Devin, Gemini CLI, and similar tools.

func DismissCookieBanner

func DismissCookieBanner(page *rod.Page) bool

DismissCookieBanner attempts to find and click a cookie accept button. Returns true if a banner was found and dismissed.

func EvalJS

func EvalJS(page *rod.Page, expr string, elementRef string, snapshot *PageSnapshot) (string, error)

EvalJS evaluates JavaScript on the page or in an element context. If elementRef is non-empty, the JS runs with `this` bound to that element.

func FormatCollect added in v0.2.0

func FormatCollect(r *CollectResult) string

FormatCollect renders a compact text table from collected items.

func FormatDiff added in v0.2.0

func FormatDiff(d SnapshotDiff) string

FormatDiff renders a SnapshotDiff as compact text.

func FormatErrors

func FormatErrors(errors []ErrorEntry) string

FormatErrors formats errors as compact text lines.

func FormatMultiCollect added in v0.2.0

func FormatMultiCollect(r *MultiCollectResult) string

FormatMultiCollect renders a compact text report for multi-URL results.

func FormatPreview

func FormatPreview(r *PreviewResult) string

FormatPreview renders a compact text report (human profile).

func FormatPreviewProfile added in v0.2.0

func FormatPreviewProfile(r *PreviewResult, p RenderProfile) string

FormatPreviewProfile renders the preview using the given profile. In agent mode, empty sections and zero-stat headers are dropped, failed requests are grouped by status code and the DOM dump uses one-letter role tags.

func FormatText

func FormatText(result *ExtractionResult) string

FormatText renders the extraction result as compact text (human profile).

func FormatTextProfile added in v0.2.0

func FormatTextProfile(result *ExtractionResult, p RenderProfile) string

FormatTextProfile renders the extraction result using the given profile. The agent profile uses one-letter role tags, truncates long labels and shortens hrefs (see TruncateURL).

func HasSelector added in v0.4.0

func HasSelector(page *rod.Page, selector string) bool

HasSelector reports whether at least one element matches selector. It is a non-throwing alternative to page.Element used by polling loops.

func HoverRef

func HoverRef(page *rod.Page, ref string, snapshot *PageSnapshot) error

HoverRef hovers over the element at the given ref.

func LoadFulfillBody added in v0.5.0

func LoadFulfillBody(value string) ([]byte, error)

LoadFulfillBody returns raw bytes from a @path literal or the string otherwise. Useful so CLI flags can take `"@mock.json"` or an inline payload.

func LoadStorageState added in v0.3.0

func LoadStorageState(browser *rod.Browser, page *rod.Page, state *StorageState) error

LoadStorageState restores cookies browser-wide and localStorage per origin. For each origin referenced, the current page is navigated there briefly so the localStorage write lands in the right context.

func NewLauncher added in v0.2.0

func NewLauncher(opts LauncherOpts) *launcher.Launcher

NewLauncher returns a configured launcher with the shared anti-detection flags used by both auto-launch (NewBrowser) and the `serve` command.

func ParseBlockList added in v0.5.0

func ParseBlockList(s string) []string

ParseBlockList splits a comma-separated glob list, trimming spaces and dropping empty entries.

func PressKey

func PressKey(page *rod.Page, key string, ref string, snapshot *PageSnapshot) error

PressKey sends a keyboard key press. If ref is non-empty, focuses the element first.

func ResolveRef

func ResolveRef(page *rod.Page, ref string, snapshot *PageSnapshot) (*rod.Element, error)

ResolveRef finds an element by its ref (@1, @2, etc.) using a persisted snapshot.

func ScrollBy added in v0.4.0

func ScrollBy(page *rod.Page, dy int) (int, error)

ScrollBy scrolls by a relative Y offset. Returns the final scrollY.

func ScrollToRef added in v0.4.0

func ScrollToRef(page *rod.Page, ref string, snapshot *PageSnapshot) error

ScrollToRef scrolls the element at the given ref into view without performing any other interaction.

func ScrollToY added in v0.4.0

func ScrollToY(page *rod.Page, y int, bottomSentinel bool) (int, error)

ScrollToY scrolls the page to an absolute Y pixel position. When bottomSentinel is true, the page is scrolled to document.body.scrollHeight regardless of the y argument — use this for "scroll-to bottom". Returns the final window.scrollY as observed after the scroll.

func SelectOption

func SelectOption(page *rod.Page, ref string, values []string, snapshot *PageSnapshot) error

SelectOption selects option(s) in a <select> element by visible text.

func SetViewport

func SetViewport(page *rod.Page, width, height int) error

SetViewport overrides the page viewport dimensions.

func SwitchTab

func SwitchTab(browser *rod.Browser, index int) (*rod.Page, error)

SwitchTab activates the tab at the given index and returns its page.

func TakeScreenshot

func TakeScreenshot(page *rod.Page, fullPage bool, elementRef string, quality int, snapshot *PageSnapshot) ([]byte, error)

TakeScreenshot captures the page or a specific element. If elementRef is non-empty, captures only that element. If fullPage is true, captures the full scrollable page. quality controls JPEG quality (1-100); PNG is used if quality <= 0.

func TruncateURL added in v0.2.0

func TruncateURL(u string, maxLen int) string

TruncateURL strips common scheme/www prefixes and shortens the URL to maxLen. Used by formatted output from preview and collect.

func TypeRef

func TypeRef(page *rod.Page, ref string, text string, snapshot *PageSnapshot) error

TypeRef types text into the element at the given ref. Uses focus + select all + keyboard typing to work with React/Vue/Angular.

func UploadRef added in v0.3.0

func UploadRef(page *rod.Page, ref string, selector string, files []string, snapshot *PageSnapshot) error

UploadRef sets the files on a file-input element.

The target can be identified either by:

  • ref: a @N reference from the current snapshot (works when the input is a native, visible <input type=file>).
  • selector: a CSS selector (use this when the visible widget is a styled button wrapping a hidden input — common pattern).

Exactly one of ref or selector must be non-empty.

func ValidateExtractLevel added in v0.2.0

func ValidateExtractLevel(level ExtractLevel) error

ValidateExtractLevel ensures the extraction level is supported.

func WaitForBotChallenge added in v0.2.0

func WaitForBotChallenge(page *rod.Page, timeout time.Duration) bool

WaitForBotChallenge detects bot-challenge pages (DataDome, Cloudflare, etc.) and waits for the challenge JS to resolve and the page to reload. Returns true if a challenge was detected and resolved.

func WaitForPage added in v0.2.0

func WaitForPage(page *rod.Page, waitStrategy string) error

WaitForPage applies a supported page wait strategy.

func WaitForSelector

func WaitForSelector(page *rod.Page, selector string, timeoutSec int) error

WaitForSelector waits for a CSS selector to appear in the DOM.

func WriteHAR added in v0.5.0

func WriteHAR(h *HAR, path string) error

WriteHAR persists the HAR JSON to path (0o600).

Types

type Browser

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

Browser wraps a Rod browser with connect/launch logic.

func NewBrowser

func NewBrowser(connectURL string, headless bool, timeoutSec int) (*Browser, error)

NewBrowser creates a browser instance. If connectURL is set, connects to an existing Chrome via CDP. Otherwise, auto-launches a new Chrome process.

func (*Browser) Close

func (b *Browser) Close()

Close cleans up the browser resources. External Chrome keeps running; the CLI process owns the websocket lifetime.

func (*Browser) Connected

func (b *Browser) Connected() bool

Connected returns true if connected to external Chrome (not launched by us).

func (*Browser) CurrentTargetID added in v0.2.0

func (b *Browser) CurrentTargetID() string

CurrentTargetID returns the persisted current tab target, if any.

func (*Browser) DeleteSnapshot added in v0.2.0

func (b *Browser) DeleteSnapshot(targetID proto.TargetTargetID) error

DeleteSnapshot removes stored ref state for a closed page target.

func (*Browser) Page

func (b *Browser) Page() (*rod.Page, error)

Page returns the active page or creates a new one. When connected to an existing Chrome, it prefers the persisted active tab.

func (*Browser) RodBrowser added in v0.2.0

func (b *Browser) RodBrowser() *rod.Browser

RodBrowser returns the underlying rod.Browser for advanced operations.

func (*Browser) SaveSnapshot added in v0.2.0

func (b *Browser) SaveSnapshot(page *rod.Page, result *ExtractionResult) error

SaveSnapshot persists the latest ref snapshot for the page.

func (*Browser) SetCurrentPage added in v0.2.0

func (b *Browser) SetCurrentPage(page *rod.Page) error

SetCurrentPage marks the provided page as the current tab for the session.

func (*Browser) Snapshot added in v0.2.0

func (b *Browser) Snapshot(page *rod.Page) *PageSnapshot

Snapshot returns the last persisted snapshot for the current page.

type CollectResult added in v0.2.0

type CollectResult struct {
	PageURL   string          `json:"page_url"`
	ItemCount int             `json:"item_count"`
	Items     []CollectedItem `json:"items"`
}

CollectResult holds all collected items from a listing page.

func Collect added in v0.2.0

func Collect(page *rod.Page, limit int) (*CollectResult, error)

Collect auto-detects repeated listing cards on a page and extracts structured data. It finds elements containing price patterns (€, $, £), groups them by common ancestor, and extracts title, price, URL, and metadata from each card.

type CollectedItem added in v0.2.0

type CollectedItem struct {
	Title  string            `json:"title"`
	Price  string            `json:"price,omitempty"`
	URL    string            `json:"url,omitempty"`
	Fields map[string]string `json:"fields,omitempty"`
}

CollectedItem is a single listing item extracted from a page.

type Device added in v0.4.0

type Device struct {
	Name      string
	Width     int
	Height    int
	DPR       float64
	UserAgent string
	Mobile    bool
	Touch     bool
}

Device describes a hardware profile used by the emulate command. Dimensions are CSS pixels; DPR is devicePixelRatio.

func DeviceByName added in v0.4.0

func DeviceByName(name string) (Device, bool)

DeviceByName looks up a Device preset by its canonical name.

func ListDevices added in v0.4.0

func ListDevices() []Device

ListDevices returns a copy of the registered device presets.

type DialogResult added in v0.2.0

type DialogResult struct {
	Handled       bool   `json:"handled"`
	Action        string `json:"action"`
	Type          string `json:"type,omitempty"`
	Message       string `json:"message,omitempty"`
	URL           string `json:"url,omitempty"`
	DefaultPrompt string `json:"default_prompt,omitempty"`
	TimedOut      bool   `json:"timed_out,omitempty"`
}

DialogResult describes how a JS dialog handler completed.

func HandleNextDialog

func HandleNextDialog(page *rod.Page, accept bool, promptText string, timeout time.Duration) (*DialogResult, error)

HandleNextDialog waits for the next JavaScript dialog and handles it. The timeout is propagated via context so wait() unblocks cleanly on timeout and no goroutine is leaked.

type DiffEntry added in v0.2.0

type DiffEntry struct {
	Before DiffNode `json:"before"`
	After  DiffNode `json:"after"`
}

DiffEntry captures a single ref that changed between snapshots.

type DiffNode added in v0.2.0

type DiffNode struct {
	Ref   string `json:"ref"`
	Role  string `json:"role"`
	Name  string `json:"name,omitempty"`
	Href  string `json:"href,omitempty"`
	Value string `json:"value,omitempty"`
}

DiffNode is the minimal payload we return for added nodes.

type DiffStats added in v0.2.0

type DiffStats struct {
	AddedCount   int `json:"added"`
	RemovedCount int `json:"removed"`
	ChangedCount int `json:"changed"`
	KeptCount    int `json:"kept"`
}

DiffStats summarises a diff for agent consumption.

type ErrorCollector

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

ErrorCollector collects console-side errors from a page via CDP events.

func NewErrorCollector

func NewErrorCollector(page *rod.Page) *ErrorCollector

NewErrorCollector creates a collector and starts listening on the page. It hooks into RuntimeConsoleAPICalled and RuntimeExceptionThrown.

func (*ErrorCollector) Errors

func (c *ErrorCollector) Errors() []ErrorEntry

Errors returns all collected errors (snapshot).

type ErrorEntry

type ErrorEntry struct {
	Type    string `json:"type"`             // "console" or "network"
	Level   string `json:"level"`            // "error", "warning", "4xx", "5xx"
	Message string `json:"message"`          // error message or URL
	Source  string `json:"source"`           // file:line for console, URL for network
	Status  int    `json:"status,omitempty"` // HTTP status for network errors
	Method  string `json:"method,omitempty"` // HTTP method for network
	TimeMs  int64  `json:"time_ms"`          // timestamp relative to collector start
}

ErrorEntry represents a single console or network error.

func CollectErrors added in v0.2.0

func CollectErrors(page *rod.Page, url string, waitStrategy string, afterNavigate func(*rod.Page) error) ([]ErrorEntry, error)

CollectErrors navigates if needed and returns console plus network errors.

type ExtractLevel

type ExtractLevel string

ExtractLevel controls how much of the accessibility tree is returned.

const (
	LevelSkeleton ExtractLevel = "skeleton"
	LevelContent  ExtractLevel = "content"
	LevelFull     ExtractLevel = "full"
)

type ExtractedNode

type ExtractedNode struct {
	Ref           string                 `json:"ref,omitempty"`
	Role          string                 `json:"role"`
	Name          string                 `json:"name,omitempty"`
	Value         string                 `json:"value,omitempty"`
	Level         int                    `json:"level,omitempty"`
	Href          string                 `json:"href,omitempty"`
	Type          string                 `json:"type,omitempty"`
	Checked       *bool                  `json:"checked,omitempty"`
	Disabled      bool                   `json:"disabled,omitempty"`
	BackendNodeID proto.DOMBackendNodeID `json:"-"`
	Children      []ExtractedNode        `json:"children,omitempty"`
}

ExtractedNode represents a filtered accessibility node.

type ExtractionResult

type ExtractionResult struct {
	Nodes []ExtractedNode          `json:"nodes"`
	Refs  map[string]ExtractedNode `json:"refs"`
	Stats ExtractionStats          `json:"stats"`
}

ExtractionResult holds the extraction output.

func Extract

func Extract(page *rod.Page, level ExtractLevel, selector string) (*ExtractionResult, error)

Extract retrieves the accessibility tree from the page and filters it.

type ExtractionStats

type ExtractionStats struct {
	TotalNodes       int `json:"total_nodes"`
	FilteredNodes    int `json:"filtered_nodes"`
	InteractiveCount int `json:"interactive_count"`
}

ExtractionStats provides extraction metrics.

type HAR added in v0.5.0

type HAR struct {
	Log HARLog `json:"log"`
}

HAR follows the HAR 1.2 specification (W3C Web Performance Working Group). It's intentionally minimal: we only populate what NetworkEntry knows about, leaving the optional fields (headers, cookies, content text) empty so parsers treat them as "not captured" rather than "empty".

func BuildHAR added in v0.5.0

func BuildHAR(entries []NetworkEntry, pageURL, pageTitle, creatorVersion string) *HAR

BuildHAR constructs a HAR from the passive NetworkEntry slice collected by requestTracker. pageURL and pageTitle name the top-level page.

type HARContent added in v0.5.0

type HARContent struct {
	Size     int    `json:"size"`
	MimeType string `json:"mimeType"`
}

HARContent carries the payload summary (size, MIME).

type HARCreator added in v0.5.0

type HARCreator struct {
	Name    string `json:"name"`
	Version string `json:"version"`
}

HARCreator identifies the tool that recorded the trace.

type HAREntry added in v0.5.0

type HAREntry struct {
	PageRef         string      `json:"pageref,omitempty"`
	StartedDateTime string      `json:"startedDateTime"`
	Time            int64       `json:"time"`
	Request         HARRequest  `json:"request"`
	Response        HARResponse `json:"response"`
	Cache           struct{}    `json:"cache"`
	Timings         HARTimings  `json:"timings"`
}

HAREntry is one network request + response.

type HARLog added in v0.5.0

type HARLog struct {
	Version string     `json:"version"`
	Creator HARCreator `json:"creator"`
	Pages   []HARPage  `json:"pages"`
	Entries []HAREntry `json:"entries"`
}

HARLog is the top-level container.

type HARPage added in v0.5.0

type HARPage struct {
	StartedDateTime string `json:"startedDateTime"`
	ID              string `json:"id"`
	Title           string `json:"title"`
}

HARPage groups entries by the top-level navigation that produced them.

type HARRequest added in v0.5.0

type HARRequest struct {
	Method      string   `json:"method"`
	URL         string   `json:"url"`
	HTTPVersion string   `json:"httpVersion"`
	Headers     []string `json:"headers"`
	QueryString []string `json:"queryString"`
	HeadersSize int      `json:"headersSize"`
	BodySize    int      `json:"bodySize"`
}

HARRequest describes the outgoing request.

type HARResponse added in v0.5.0

type HARResponse struct {
	Status      int        `json:"status"`
	StatusText  string     `json:"statusText"`
	HTTPVersion string     `json:"httpVersion"`
	Headers     []string   `json:"headers"`
	Cookies     []string   `json:"cookies"`
	Content     HARContent `json:"content"`
	RedirectURL string     `json:"redirectURL"`
	HeadersSize int        `json:"headersSize"`
	BodySize    int        `json:"bodySize"`
}

HARResponse describes the incoming response.

type HARTimings added in v0.5.0

type HARTimings struct {
	Send    int   `json:"send"`
	Wait    int64 `json:"wait"`
	Receive int   `json:"receive"`
}

HARTimings models per-phase durations. We only know the total so we put it on "wait".

type InterceptSession added in v0.5.0

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

InterceptSession owns the router lifetime. Stop() must be called to release resources.

func StartIntercept added in v0.5.0

func StartIntercept(browser *rod.Browser, spec InterceptSpec) (*InterceptSession, error)

StartIntercept enables Fetch interception on the browser and returns an InterceptSession. The caller is responsible for Stop().

func (*InterceptSession) Stats added in v0.5.0

func (s *InterceptSession) Stats() *InterceptStats

Stats returns the live counters.

func (*InterceptSession) Stop added in v0.5.0

func (s *InterceptSession) Stop() error

Stop disables interception and waits for the background goroutine.

type InterceptSpec added in v0.5.0

type InterceptSpec struct {
	// BlockPatterns list glob URL patterns to block with
	// NetworkErrorReasonBlockedByClient.
	BlockPatterns []string

	// FulfillPattern optionally matches requests to be answered with the
	// FulfillBody payload and FulfillStatus response code. Only set one pattern.
	FulfillPattern     string
	FulfillBody        []byte
	FulfillStatus      int
	FulfillContentType string
}

InterceptSpec configures a request interception router.

type InterceptStats added in v0.5.0

type InterceptStats struct {
	Blocked   int
	Fulfilled int
	Passed    int
	// contains filtered or unexported fields
}

InterceptStats are cumulative counters updated by the router goroutine.

func (*InterceptStats) Snapshot added in v0.5.0

func (s *InterceptStats) Snapshot() (blocked, fulfilled, passed int)

Snapshot returns a concurrent-safe copy of the counters.

type LauncherOpts added in v0.2.0

type LauncherOpts struct {
	Headless   bool
	RemotePort int // 0 = random
}

LauncherOpts configures a stealth-flavored Chrome launcher.

type MultiCollectResult added in v0.2.0

type MultiCollectResult struct {
	TotalItems  int          `json:"total_items"`
	TotalTimeMs int64        `json:"total_time_ms"`
	Sites       []SiteResult `json:"sites"`
}

MultiCollectResult holds results from parallel multi-URL collection.

func MultiCollect added in v0.2.0

func MultiCollect(browser *rod.Browser, urls []string, limit int, stealth bool, maxParallel int) *MultiCollectResult

MultiCollect scrapes multiple URLs in parallel using separate browser tabs. Each URL gets its own tab, navigates, collects, and closes. maxParallel caps the number of concurrent tabs; <= 0 falls back to 5.

type NetworkEntry

type NetworkEntry struct {
	Method   string `json:"method,omitempty"`
	URL      string `json:"url"`
	Status   int    `json:"status"`
	Size     int    `json:"size_bytes"`
	TimeMs   int64  `json:"time_ms"`
	MimeType string `json:"mime_type,omitempty"`
	Error    string `json:"error,omitempty"`
}

NetworkEntry represents a captured network request.

type PageInfo

type PageInfo struct {
	URL    string `json:"url"`
	Title  string `json:"title"`
	Status int    `json:"status"`
	TimeMs int64  `json:"time_ms"`
}

PageInfo holds the result of a navigation.

func Navigate(page *rod.Page, rawURL string, waitStrategy string) (*PageInfo, error)

Navigate goes to the given URL and returns page info.

type PageSnapshot added in v0.2.0

type PageSnapshot struct {
	TargetID string                 `json:"target_id"`
	URL      string                 `json:"url,omitempty"`
	Title    string                 `json:"title,omitempty"`
	Refs     map[string]RefSnapshot `json:"refs,omitempty"`
}

PageSnapshot stores the last known interactive refs for a page target.

func BuildSnapshot added in v0.2.0

func BuildSnapshot(page *rod.Page, result *ExtractionResult) (*PageSnapshot, error)

BuildSnapshot creates an in-memory ref snapshot from an extraction result.

type PreviewResult

type PreviewResult struct {
	PageInfo *PageInfo         `json:"page"`
	Errors   []ErrorEntry      `json:"errors"`
	Network  []NetworkEntry    `json:"network"`
	DOM      *ExtractionResult `json:"dom"`
	Summary  PreviewSummary    `json:"summary"`
}

PreviewResult is the all-in-one dev report for a page.

func Preview

func Preview(page *rod.Page, url string, waitStrategy string, extractLevel ExtractLevel, afterNavigate func(*rod.Page) error, stealth bool) (*PreviewResult, error)

Preview performs a full page analysis: navigate + collect errors + collect network + extract DOM.

type PreviewSummary

type PreviewSummary struct {
	TotalRequests    int `json:"total_requests"`
	FailedRequests   int `json:"failed_requests"`
	ErrorCount       int `json:"error_count"`
	WarningCount     int `json:"warning_count"`
	InteractiveCount int `json:"interactive_count"`
}

PreviewSummary provides quick stats.

type RefSnapshot added in v0.2.0

type RefSnapshot struct {
	BackendNodeID proto.DOMBackendNodeID `json:"backend_node_id"`
	Role          string                 `json:"role,omitempty"`
	Name          string                 `json:"name,omitempty"`
}

RefSnapshot stores a stable backend node mapping for a single ref.

type RenderProfile added in v0.2.0

type RenderProfile struct {
	// Agent is true when the output is being consumed by an LLM agent runner
	// (Claude Code, Cursor, Aider, etc.) rather than a human terminal.
	Agent bool

	// Format is "text" or "json".
	Format string

	// MaxLabelLen truncates node names / values to this length in agent mode.
	// 0 means no truncation.
	MaxLabelLen int

	// AbbrevRoles uses 1-2 character role abbreviations (b/a/t/c/s/r/m/x/h).
	AbbrevRoles bool

	// DropEmptyStats omits "[errors] 0 ..." / "[network] ... 0 failed" headers
	// when counts are zero.
	DropEmptyStats bool
}

RenderProfile controls how output is rendered for the calling environment. It is resolved once per CLI invocation (see ResolveProfile) and then threaded into formatters.

func ProfileAgent added in v0.2.0

func ProfileAgent(format string) RenderProfile

ProfileAgent returns the compact agent-optimised profile.

func ProfileHuman added in v0.2.0

func ProfileHuman(format string) RenderProfile

ProfileHuman returns the default human-friendly profile.

func ResolveProfile added in v0.2.0

func ResolveProfile(explicit, format string) RenderProfile

ResolveProfile picks a RenderProfile from an explicit flag ("auto", "human", "agent") with environment-variable fallback for "auto".

type SiteResult added in v0.2.0

type SiteResult struct {
	URL    string          `json:"url"`
	Items  []CollectedItem `json:"items"`
	Count  int             `json:"count"`
	TimeMs int64           `json:"time_ms"`
	Error  string          `json:"error,omitempty"`
}

SiteResult holds the collect result for a single URL in a multi-collect.

type SnapshotDiff added in v0.2.0

type SnapshotDiff struct {
	Unchanged bool                 `json:"unchanged,omitempty"`
	Added     []DiffNode           `json:"added,omitempty"`
	Removed   []string             `json:"removed,omitempty"`
	Changed   map[string]DiffEntry `json:"changed,omitempty"`
	Stats     DiffStats            `json:"stats"`
}

SnapshotDiff reports the changes between two ref maps of a page. All fields are optional in JSON output so an unchanged page serialises to `{"unchanged":true}`.

func DiffRefs added in v0.2.0

func DiffRefs(prev, curr map[string]RefSnapshot) SnapshotDiff

DiffRefs compares two ref maps (typically the persisted PageSnapshot.Refs). Refs are reassigned in document order by the extractor, so a key match indicates the same logical node slot. A role or name change on the same key counts as "changed"; disappearing or new keys count as removed/added.

type StorageCookie added in v0.3.0

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

StorageCookie uses the Playwright-compatible field names (sameSite as string, expires as float64 seconds-since-epoch).

type StorageKeyValue added in v0.3.0

type StorageKeyValue struct {
	Name  string `json:"name"`
	Value string `json:"value"`
}

StorageKeyValue is a single localStorage entry.

type StorageOrigin added in v0.3.0

type StorageOrigin struct {
	Origin       string            `json:"origin"`
	LocalStorage []StorageKeyValue `json:"localStorage"`
}

StorageOrigin groups localStorage entries by origin. sessionStorage is NOT persisted: it's per-tab and generally not replayable.

type StorageState added in v0.3.0

type StorageState struct {
	Cookies []StorageCookie `json:"cookies"`
	Origins []StorageOrigin `json:"origins"`
}

StorageState mirrors the Playwright storageState JSON shape so a state file produced by ghostchrome can be loaded by Playwright (and vice versa, within reasonable limits).

func SaveStorageState added in v0.3.0

func SaveStorageState(browser *rod.Browser, page *rod.Page) (*StorageState, error)

SaveStorageState captures cookies (browser-wide) and localStorage for the origin of the current page. Callers can concatenate multiple SaveStorageState runs if they need multiple origins.

type TabInfo

type TabInfo struct {
	Index    int    `json:"index"`
	URL      string `json:"url"`
	Title    string `json:"title"`
	TargetID string `json:"target_id,omitempty"`
	Active   bool   `json:"active,omitempty"`
}

TabInfo holds metadata about a browser tab.

func ListTabs

func ListTabs(browser *rod.Browser, currentTargetID string) ([]TabInfo, error)

ListTabs returns info for every open tab in the browser.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL