chrome

type Browser interface {
	List(ctx context.Context) ([]target.Info, error)
	Open(ctx context.Context, url string) (map[string]any, error)
	Navigate(ctx context.Context, targetID, url string) (map[string]any, error)
	// CloseTabs closes tabs by id. It is not Close, which tears down the whole
	// connection.
	CloseTabs(ctx context.Context, targetIDs []string) (map[string]any, error)
	// Activate foregrounds a tab within its window and raises that window, which
	// is the documented remedy for the accessibility-tree throttling that makes
	// --by name/ref/cell stall on a backgrounded tab (`tab_hidden`).
	Activate(ctx context.Context, targetID string) (map[string]any, error)
	// History navigates the tab by delta entries (-1 back, +1 forward). A delta
	// with no entry in that direction is an error, not a silent no-op: a wizard
	// script that quietly failed to go back would act against the wrong page.
	History(ctx context.Context, targetID string, delta int) (map[string]any, error)
	// Reload reloads the tab, optionally bypassing the cache.
	Reload(ctx context.Context, targetID string, hard bool) (map[string]any, error)
	Eval(ctx context.Context, targetID, expr string, opts EvalOpts) (any, error)
	Snapshot(ctx context.Context, targetID string, opts SnapOpts) (any, error)
	// Find ranks the page's accessibility nodes against a plain-language query
	// (RFC-0015) and returns the best matches with refs, states, and centre
	// points. It is a read: it never dispatches input, which is why MCP mode
	// can expose it under --read-only.
	Find(ctx context.Context, targetID, query string, opts FindOpts) (map[string]any, error)
	Key(ctx context.Context, targetID, selector string, keys []KeyStroke, opts KeyOpts) (map[string]any, error)
	// Pointer dispatches every pointer gesture — click included. There is no
	// separate Click: one method means one centre resolution and one place
	// modifiers are applied, which is what lets `click --modifiers cmd`
	// multi-select without a second implementation drifting from the first.
	Pointer(ctx context.Context, targetID, selector string, opts PointerOpts) (map[string]any, error)
	Select(ctx context.Context, targetID, field, option string, opts SelectOpts) (map[string]any, error)
	Grid(ctx context.Context, targetID, selector string, q QueryOpts) (any, error)
	Scroll(ctx context.Context, targetID, selector string, opts ScrollOpts) (map[string]any, error)
	Type(ctx context.Context, targetID, selector, text string, q QueryOpts) (map[string]any, error)
	Fill(ctx context.Context, targetID, selector, value string, q QueryOpts) (map[string]any, error)
	// Upload attaches local files to a file input. The paths must already be
	// absolute, existing, readable files — CDP requires absolute paths, and the
	// CLI validates them before connecting so a bad path never costs a
	// connection. The result reports the files READ BACK from the input.
	Upload(ctx context.Context, targetID, selector string, paths []string, opts UploadOpts) (map[string]any, error)
	HTML(ctx context.Context, targetID, selector string, inner bool, q QueryOpts) (map[string]any, error)
	Text(ctx context.Context, targetID, selector string, opts TextOpts) (map[string]any, error)
	Value(ctx context.Context, targetID, selector string, q QueryOpts) (map[string]any, error)
	Values(ctx context.Context, targetID, selector string, q QueryOpts) (map[string]any, error)
	AttrGet(ctx context.Context, targetID, selector, name string, q QueryOpts) (map[string]any, error)
	AttrList(ctx context.Context, targetID, selector string, q QueryOpts) (map[string]any, error)
	AttrSet(ctx context.Context, targetID, selector, name, value string, q QueryOpts) (map[string]any, error)
	AttrRemove(ctx context.Context, targetID, selector, name string, q QueryOpts) (map[string]any, error)
	SetHeaders(ctx context.Context, targetID string, headers map[string]string) (map[string]any, error)
	EmulateViewport(ctx context.Context, targetID string, width, height int64) (map[string]any, error)
	EmulateGeo(ctx context.Context, targetID string, lat, lon float64) (map[string]any, error)
	EmulateReset(ctx context.Context, targetID string) (map[string]any, error)
	// Window reports or sets the REAL Chrome window's bounds. It is not
	// EmulateViewport: that lies to the page about its size, while this moves
	// the window the user sees — which is what makes a screenshot's pixel
	// coordinates reproducible across runs (RFC-0014).
	Window(ctx context.Context, targetID string, opts WindowOpts) (WindowBounds, error)
	Frames(ctx context.Context, targetID string) (any, error)
	Wait(ctx context.Context, targetID string, cond WaitCond) (map[string]any, error)
	// Screenshot and PDF return the artifact bytes AND the metadata describing
	// them (dimensions, format, mode, resolved clip / page count). The metadata
	// travels with the bytes because only the driver can know it without the CLI
	// decoding the image itself.
	Screenshot(ctx context.Context, targetID string, opts ShotOpts) ([]byte, map[string]any, error)
	PDF(ctx context.Context, targetID string, opts PDFOpts) ([]byte, map[string]any, error)
	// RecordStart begins a screencast recording of a tab (RFC-0011). The frames
	// are retained where the CONNECTION lives — the daemon — because a recording
	// spans many CLI invocations and no per-command process can hold them. That
	// is also what makes a crashed automation's frames survive it (US-7).
	RecordStart(ctx context.Context, targetID string, opts RecordOpts) (map[string]any, error)
	// RecordStop ends the recording and hands back the retained frames plus the
	// accounting an honest export needs (frames, dropped_frames, truncated).
	// Encoding happens in the CLI, via internal/encode, so one capture can be
	// exported in more than one format and annotation stays an export decision.
	RecordStop(ctx context.Context, targetID string) ([]Frame, map[string]any, error)
	// RecordRestore hands a drained recording back, so an export that failed
	// after RecordStop can be retried instead of costing the user the frames.
	//
	// It exists because RecordStop is destructive and encoding is not free of
	// failure modes the CLI cannot rule out in advance (a full disk, an ffmpeg
	// that dies). Everything that CAN be checked first is — the encoder's
	// availability and the output path both are — and this covers the rest. The
	// restored recording is not capturing: it holds the frames for a retry, and
	// `record cancel` discards it like any other.
	RecordRestore(ctx context.Context, targetID string, frames []Frame, meta map[string]any) error
	// RecordStatus reports whether a recording is active and how much it holds.
	RecordStatus(ctx context.Context, targetID string) (map[string]any, error)
	// RecordCancel discards a recording without exporting anything.
	RecordCancel(ctx context.Context, targetID string) (map[string]any, error)
	// Console returns the console messages and uncaught exceptions retained for
	// a tab since the connection attached to it, filtered by opts BEFORE the
	// result is built (see ConsoleOpts in console.go).
	Console(ctx context.Context, targetID string, opts ConsoleOpts) (any, error)
	// ConsoleStream calls emit once per message as it arrives, until ctx ends.
	// It is the one Browser method that is not a single request/response, so
	// the daemon serves it over the streaming RPC path rather than dispatch.
	ConsoleStream(ctx context.Context, targetID string, opts ConsoleOpts, emit func(any) error) error
	// Net returns the HTTP requests retained for a tab since the connection
	// attached to it, filtered by opts BEFORE the result is built (see NetOpts
	// in net.go). Response bodies are fetched here, at read time, only when
	// opts.Body asks for them.
	Net(ctx context.Context, targetID string, opts NetOpts) (any, error)
	// NetStream calls emit once per COMPLETED request as it finishes, until ctx
	// ends. Like ConsoleStream it is served over the daemon's streaming RPC path
	// rather than dispatch.
	NetStream(ctx context.Context, targetID string, opts NetOpts, emit func(any) error) error
	// NetWait blocks until a request matching cond completes, answering from the
	// already-buffered records first so a request that landed between the action
	// and the wait is not missed.
	NetWait(ctx context.Context, targetID string, cond NetCond) (map[string]any, error)
	CookieList(ctx context.Context, targetID string) (any, error)
	CookieSet(ctx context.Context, targetID, name, value, domain, path string) (map[string]any, error)
	CookieDelete(ctx context.Context, targetID, name string) (map[string]any, error)
	CookieClear(ctx context.Context, targetID string) (map[string]any, error)
	Raw(ctx context.Context, targetID, method string, params json.RawMessage) (any, error)
	Close() error
}

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

type ConnectError struct {
	Code    string
	Message string
}

type ConsoleOpts struct {
	Grep   string        // keep only messages whose text matches this regex
	Levels []string      // keep only these levels (empty = all)
	Limit  int           // most recent N matches (0 = all)
	Since  time.Duration // only messages newer than this
	Clear  bool          // drop the buffer after reading
}

type EvalOpts struct {
	Await bool
}

type FindOpts struct {
	Role     string  // hard-filter matches to one ARIA role
	Limit    int     // maximum matches returned (default DefaultFindLimit)
	Region   string  // scope to the subtree of a container whose name contains this
	All      bool    // include ignored/hidden nodes (excluded by default)
	Dedupe   bool    // collapse identical role+name matches (keep first)
	MinScore float64 // drop matches scoring below this (0..1)
}

type Frame struct {
	Data   []byte    `json:"data"`
	TS     time.Time `json:"ts"`
	Width  int       `json:"width"`  // image pixels
	Height int       `json:"height"` // image pixels

	// CSSWidth/CSSHeight are what the frame covers in PAGE pixels. They are the
	// mapping a mark's coordinates need when the capture was scaled down, and
	// come from the screencast frame's own metadata rather than from the
	// requested scale — the two differ whenever the device scale factor is not 1.
	CSSWidth  float64 `json:"css_width,omitempty"`
	CSSHeight float64 `json:"css_height,omitempty"`

	// Marks are the actions that landed while this frame was on screen.
	Marks []FrameMark `json:"marks,omitempty"`
}

type FrameMark struct {
	X       float64   `json:"x"`
	Y       float64   `json:"y"`
	Command string    `json:"command,omitempty"`
	TS      time.Time `json:"ts"`
}

type JSError struct {
	Message string
	Stack   string
}

type KeyOpts struct {
	Repeat int           // press the sequence this many times (1..100)
	Delay  time.Duration // pause between repeats, for apps that debounce
	Query  QueryOpts
}

type KeyStroke struct {
	Key       string // DOM KeyboardEvent.key ("Escape", "a", "ArrowDown")
	Code      string // DOM KeyboardEvent.code ("Escape", "KeyA", "ArrowDown")
	KeyCode   int64  // windowsVirtualKeyCode
	Text      string // the text a printable key inserts ("" for non-printable)
	Modifiers int64  // CDP modifier bitmask (alt 1, ctrl 2, meta 4, shift 8)
}

type NetCond struct {
	URL     string
	Methods []string
	Status  string
	Types   []string
	Failed  bool

	Headers  bool
	Body     bool
	NoRedact bool
}

type NetOpts struct {
	URL     string        // substring match; a "re:" prefix switches to regex
	Methods []string      // keep only these HTTP methods (empty = all)
	Status  string        // --status spec: 200 | 2xx | >=400 | !2xx (empty = all)
	Types   []string      // keep only these resource types (empty = all)
	Failed  bool          // keep only non-2xx or network-level failures
	Limit   int           // most recent N matches (0 = all)
	Since   time.Duration // only requests newer than this
	Clear   bool          // drop the buffer after reading

	// Rendering. Headers and bodies are ABSENT from the envelope unless asked
	// for; NoRedact turns off the credential redaction that is otherwise always
	// applied to headers and URLs.
	Headers  bool
	Body     bool
	NoRedact bool
}

type NetStatusMatcher func(status int64, hasStatus bool) bool

type Options struct {
	PortFile   string // override DevToolsActivePort location (else OS candidates)
	ProfileDir string // managed-launch profile dir (else CHROME_CDP_PROFILE / default)
	Port       int    // explicit debug port to attach to / launch with (0 = auto)
	NoLaunch   bool   // don't fall back to launching a managed Chrome
	Headless   bool   // headless for the managed-launch fallback (tests use this)

	// ConsentTimeout bounds the wait for Chrome's "Allow remote debugging?"
	// dialog (config key consent_timeout). It applies ONLY to an open port
	// whose upgrade is hanging; a refused endpoint still fails in
	// milliseconds. See browser.AwaitUpgrade.
	//
	// It arrives already normalised: config resolution is the one boundary
	// where flag, env and file meet, and ClampConsentTimeout runs there.
	ConsentTimeout time.Duration
	// ConsentPendingAfter is how much silence from an OPEN port counts as
	// "Chrome is asking the user", i.e. when OnConsentPending fires. Zero means
	// DefaultConsentPendingAfter, which is what production always uses.
	//
	// It is a field rather than a package var because a test needs to shrink
	// it, and the tests that need it most are in another package: the daemon's
	// had to sit a 3s consent budget and a 3s poll around a 2s threshold it
	// could not reach, measuring 3.05s against a marker at ~2.0s. A 1.5x margin
	// on a timing this repo has already been bitten by four times on macOS is
	// not a margin. Options already carries ConsentTimeout and
	// OnConsentPending; this belongs with them.
	ConsentPendingAfter time.Duration
	// OnConsentPending fires once, as soon as the upgrade is classified as
	// pending — i.e. while the dialog is still on screen, not after the wait.
	// The daemon uses it to tell the CLI what it is waiting for.
	OnConsentPending func()

	// Event-capture bounds (config keys console_buffer / console_max_entry).
	// Zero means the built-in default; see configureCapture.
	ConsoleBuffer   int // retained console messages per target
	ConsoleMaxEntry int // per-message text cap, in bytes

	// Network-capture bounds (config keys net_buffer / net_max_body). Separate
	// from the console's because a correlated request record is much larger than
	// a console line. Zero means the built-in default.
	NetBuffer  int // retained network records per target
	NetMaxBody int // per-body cap, in bytes

	// Recording bounds (config keys record_buffer / record_max_bytes). A frame
	// is orders of magnitude larger than either of the above, so it gets its own
	// ring size AND a byte ceiling — a frame count alone does not bound memory
	// when the viewport can be 4K. Zero means the built-in default.
	RecordBuffer   int // retained frames per target
	RecordMaxBytes int // retained frame bytes per target
}

type PDFOpts struct {
	Landscape    bool
	PaperWidth   float64 // inches; 0 = Chrome's default (letter)
	PaperHeight  float64 // inches; 0 = Chrome's default (letter)
	MarginTop    float64 // inches
	MarginRight  float64 // inches
	MarginBottom float64 // inches
	MarginLeft   float64 // inches
	Scale        float64 // 0.1–2 (0 means 1)
	Background   bool    // print background graphics
	Pages        string  // page ranges, e.g. "1-3,5" ("" = the whole document)
	Header       string  // HTML template for the print header
	Footer       string  // HTML template for the print footer
}

type Point struct {
	X float64 `json:"x"`
	Y float64 `json:"y"`
}

type PointerAction string

type PointerOpts struct {
	Action    PointerAction
	Modifiers int64 // held during the press (alt 1, ctrl 2, meta 4, shift 8)

	// At bypasses element resolution: the gesture is dispatched at this viewport
	// coordinate. It is how a canvas, a map, or any surface the accessibility
	// tree cannot see gets driven — and how a screenshot-reading agent acts on
	// what it saw. When set, no selector is resolved and no occlusion check
	// runs: the coordinate IS the intent (RFC-0014).
	At *Point

	// Drag targeting: a To selector (resolved with ToQuery), a ToAt coordinate,
	// or a (Dx, Dy) pixel delta from the source. Exactly one is set.
	To      string
	ToQuery QueryOpts
	ToAt    *Point
	Dx, Dy  float64

	// Steps is the number of interpolated move events dispatched between the
	// press and the release. It is not cosmetic: drag implementations require
	// movement to register a drag at all, and a press-then-release at two points
	// is silently a click.
	Steps int
	Hold  time.Duration // pause after press before moving (long-press-to-drag UIs)

	Query QueryOpts
}

type QueryOpts struct {
	By     string // css (default) | id | search | jspath | css-all | name
	Wait   string // visible (default) | ready | enabled
	Pierce bool   // reach into shadow DOM / iframes (via DevTools search)

	// Accessible-name addressing (By == "name"): the selector is the ARIA
	// accessible name; Role optionally constrains the ARIA role, and Nth picks
	// the 1-based match among the visible candidates (0 = first).
	Role string
	Nth  int

	// Match controls how the accessible name is compared (By == "name"):
	// "" / "exact" (default), "contains" (case-insensitive substring), or
	// "regex". Lets a caller click "Review" without knowing its verbose full
	// accessible name.
	Match string

	// InRow scopes an accessible-name match (By == "name") to the table row
	// whose text contains this string — so `click --by name "Delete" --in-row
	// "TEST entry"` hits the Delete button in that row, not the first of many.
	// It resolves via the DOM (not the throttled a11y tree), so it also works on
	// a backgrounded tab. Requires By == "name".
	InRow string

	// OnDialog, set on an action verb (click/type/fill), auto-handles a native
	// JavaScript dialog (alert/confirm/prompt) that opens DURING the action —
	// "accept" or "dismiss" — instead of letting it wedge the CDP connection.
	// The handled dialogs are reported back in the result envelope.
	OnDialog string
}

type RecordOpts struct {
	// FPS is the CAPTURE cadence ceiling, not a fixed interval: a screencast
	// pushes frames only when the page changes, so this throttles a busy page
	// rather than polling a static one.
	FPS float64

	// Scale shrinks the captured frames relative to the viewport. It is applied
	// by Chrome at capture time (maxWidth/maxHeight), so a scaled recording
	// costs less memory in the daemon, not just less disk at export.
	Scale float64

	// Quality is the JPEG quality of each frame, 0-100.
	Quality int

	// MaxFrames is the ring-buffer bound. Eviction is REPORTED (dropped_frames /
	// truncated), never silent.
	MaxFrames int

	// MaxDuration stops the capture — but not the recording — after this long.
	// The frames captured so far stay exportable, with truncated set.
	MaxDuration time.Duration

	// Annotate is the DEFAULT for the export, not a capture-time behaviour.
	// Action marks are recorded either way (they are a few floats each), so one
	// capture can be exported both annotated and clean; `record stop` may
	// override this.
	Annotate bool
}

type Rect struct {
	X      float64 `json:"x"`
	Y      float64 `json:"y"`
	Width  float64 `json:"width"`
	Height float64 `json:"height"`
}

type ScrollOpts struct {
	Dx    float64
	Dy    float64
	Into  bool
	Wheel bool

	// At anchors a --wheel dispatch at a viewport coordinate instead of an
	// element's centre — for maps and canvases that zoom around the pointer.
	At *Point

	Query QueryOpts
}

type SelectOpts struct {
	// Query addresses the FIELD control (usually By=="name" with a Role like
	// textbox/combobox to disambiguate a same-named column header from the input).
	Query QueryOpts

	// OptionMatch controls how each option segment is compared against rendered
	// option text: "" / "contains" (default — Workday labels are verbose),
	// "exact", or "regex".
	OptionMatch string

	// Filter is optional text typed into the prompt after it opens, to narrow a
	// long option list before the option is clicked.
	Filter string

	// Sep splits Option into cascade levels (default ">"): e.g.
	// "Project Plan Tasks > ShiftLeft: Qwiet" drills the category, then the leaf.
	Sep string
}

type ShotMode string

type ShotOpts struct {
	Selector string // capture this element's box (all QueryOpts flags apply)
	FullPage bool   // capture the whole scrollable page, beyond the fold
	Region   *Rect  // capture an explicit page-coordinate rectangle

	Format  string  // png (default) | jpeg | webp
	Quality int     // 0–100; jpeg/webp only (ignored for png, which the CLI rejects)
	Scale   float64 // output scale factor, 0.1–3 (0 means 1)
	Padding float64 // expand an element clip by this many px, clamped to the page

	Query QueryOpts
}

type SnapOpts struct {
	Role   string // only nodes with this ARIA role
	Grep   string // only nodes whose accessible name matches this regex
	Region string // only nodes within the subtree of a container whose name contains this
	Dedupe bool   // collapse identical role+name (keep first) — for virtualized grids
}

type TextOpts struct {
	Article  bool // extract the main readable content, dropping boilerplate
	Markdown bool // with Article: emit markdown structure instead of plain text
	MinChars int  // with Article: below this many extracted chars, report failure
	Query    QueryOpts
}

type Upgrade struct {
	State browser.WSState
	// contains filtered or unexported fields
}

type UpgradeTimings struct {
	// PendingAfter is how much silence counts as "Chrome is asking the user".
	// Reaching it calls onPending (once) so the caller can say so WHILE it
	// waits, rather than afterwards, which would be a post-mortem.
	PendingAfter time.Duration
	// Total is the whole budget. The same upgrade stays open across it, so an
	// answer that arrives late still lands on a live connection instead of an
	// orphaned one.
	Total time.Duration
}

type UploadOpts struct {
	// Append adds to the files this session already set on the input instead of
	// replacing them. It can only be honoured for files this CLI set itself:
	// setFileInputFiles replaces the FileList wholesale, and the existing
	// entries' PATHS are not readable back from the DOM (File.name is the bare
	// name by design). Appending to an input whose prior contents are unknown is
	// a usage error rather than a guess.
	Append bool

	// Drop delivers the files by synthesized drag-and-drop onto an element
	// instead of setting a file input's FileList — for the growing number of
	// apps whose only upload affordance is a drop zone with no <input
	// type=file> behind it. DropAt does the same at a viewport coordinate.
	//
	// The events are synthesized but the File objects are real: they come from
	// DOM.setFileInputFiles on a temporary hidden input, so a handler reading
	// dataTransfer.files gets genuine file data, not a stub.
	Drop   string
	DropAt *Point

	Query QueryOpts
}

type WaitCond struct {
	URL     string
	Visible string
	Gone    string
	Text    string // until the accessibility tree contains this text (e.g. a "Success" toast)
	Stable  bool   // until the accessibility tree stops changing (the page settled)
	Idle    bool   // until network activity settles (no in-flight requests for a window)
	Query   QueryOpts
}

type WindowBounds struct {
	Left   int64  `json:"left"`
	Top    int64  `json:"top"`
	Width  int64  `json:"width"`
	Height int64  `json:"height"`
	State  string `json:"state"`
}

type WindowOpts struct {
	Width  int64
	Height int64
}