core

type Action struct {
	Kind ActionKind
	// Text carries the payload for ActionSetValue/ActionType.
	Text string
	// Amount carries the scroll delta for ActionScroll (positive/negative,
	// backend-defined units).
	Amount int
	// Key carries the key or chord identifier for ActionPress (e.g.
	// "Enter", "Ctrl+A").
	Key string
}

type ActionKind string

type ActionResolver struct {
	Backend       Backend
	Physical      PhysicalInput
	AllowPhysical bool
}

type ActionResult struct {
	// Method is "native" when the backend performed the action directly,
	// or "physical" when a synthetic-input fallback was used.
	Method string
	Action Action
	// Notes records anything worth surfacing to the caller/LLM, e.g. why a
	// fallback was taken.
	Notes []string
}

type AppInfo struct {
	ID      string `json:"id"`
	Name    string `json:"name"`
	PID     int    `json:"pid"`
	Windows int    `json:"windows"`
}

type AttrPredicate struct {
	Attr  string
	Op    string
	Value string
}

type Backend interface {
	// Name returns the backend identifier, e.g. "atspi", "uia", "ax",
	// "cdp", "null".
	Name() string

	// Available reports the Capabilities this backend can offer in the
	// current session. It may perform cheap probing but must not block on
	// user interaction.
	Available(ctx context.Context) (Capabilities, error)

	// Apps lists running applications visible to this backend.
	Apps(ctx context.Context) ([]AppInfo, error)

	// Windows lists the top-level windows of appID, or of all apps when
	// appID is empty.
	Windows(ctx context.Context, appID string) ([]WindowInfo, error)

	// Find resolves a selector within scope, returning at most limit
	// matches (limit <= 0 means "backend default cap"). Implementations
	// should stop traversing as soon as they have enough matches.
	Find(ctx context.Context, scope Scope, sel *Selector, limit int) ([]*Element, error)

	// Children returns the direct children of el.
	Children(ctx context.Context, el *Element) ([]*Element, error)

	// Properties reads a set of extra properties for el. When props is
	// empty, the backend returns whatever extra properties it can cheaply
	// provide.
	Properties(ctx context.Context, el *Element, props []string) (map[string]any, error)

	// Perform executes action against el.
	Perform(ctx context.Context, el *Element, action Action) error

	// Close releases any resources (connections, handles) held by the
	// backend.
	Close() error
}

type BackendFactory func() (Backend, error)

type Bounds struct {
	X int `json:"x"`
	Y int `json:"y"`
	W int `json:"w"`
	H int `json:"h"`
}

type Capabilities struct {
	Screenshot       bool `json:"screenshot"`
	Accessibility    bool `json:"accessibility"`
	UIInspection     bool `json:"uiInspection"`
	Mouse            bool `json:"mouse"`
	Keyboard         bool `json:"keyboard"`
	WindowManagement bool `json:"windowManagement"`
	UIActions        bool `json:"uiActions"`
	Events           bool `json:"events"`
}

type Condition string

type DesktopError struct {
	Code       ErrorCode
	Message    string
	Suggestion string
}

type Element struct {
	ID          ElementRef   `json:"id"`
	Role        Role         `json:"role"`
	Name        string       `json:"name,omitempty"`
	Value       string       `json:"value,omitempty"`
	Description string       `json:"description,omitempty"`
	Bounds      Bounds       `json:"bounds,omitempty"`
	Enabled     bool         `json:"enabled"`
	Visible     bool         `json:"visible"`
	Focused     bool         `json:"focused"`
	ParentID    ElementRef   `json:"parentId,omitempty"`
	ChildIDs    []ElementRef `json:"childIds,omitempty"`
	Actions     []ActionKind `json:"actions,omitempty"`

	// Backend is the name of the backend that produced this element
	// ("atspi", "uia", "ax", "cdp", "null").
	Backend string `json:"backend,omitempty"`
	// AppID identifies the owning application, backend-specific.
	AppID string `json:"appId,omitempty"`
	// WindowID identifies the owning window, backend-specific.
	WindowID string `json:"windowId,omitempty"`

	Native NativeData `json:"native,omitempty"`
}

type ElementRef string

type ErrorCode string

type Locator struct {
	Scope    Scope
	Selector *Selector
}

type NativeData struct {
	// Platform identifies the backend that produced this data, e.g.
	// "atspi", "uia", "ax", "cdp".
	Platform string `json:"platform,omitempty"`
	// Role is the raw, un-normalized platform role (e.g. AT-SPI "push button").
	Role string `json:"role,omitempty"`
	// SubRole is a platform-specific refinement (e.g. macOS AXSubrole).
	SubRole string `json:"subRole,omitempty"`
	// Data carries any additional backend-specific attributes.
	Data map[string]any `json:"data,omitempty"`
}

type NullBackend struct{}

type PhysicalInput interface {
	Click(x, y int) error
	MoveMouse(x, y int) error
	TypeText(s string) error
	PressKey(key string) error
	Scroll(x, y, amount int) error
}

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

type RenderOptions struct {
	// MaxNodes caps how many element lines are emitted; 0 means unbounded.
	MaxNodes int
	// MaxDepth caps how many levels below the root are descended; 0 means
	// unbounded.
	MaxDepth int
	// IncludeBounds appends bounds="x,y,w,h" to each line.
	IncludeBounds bool
	// IncludeInvisible includes elements with Visible == false. When
	// false (the default), invisible subtrees are skipped entirely.
	IncludeInvisible bool
}

type Role string

type Scope struct {
	AppID    string
	WindowID string
	// Root, when set, restricts the search to the subtree rooted at this
	// element instead of the whole app/window.
	Root *Element
	// Depth caps how many levels below Root/window the backend should
	// descend. Zero means "backend default".
	Depth int
}

type Selector struct {
	Steps []SelectorStep
}

type SelectorStep struct {
	// Combinator is the relationship to the previous step: "" for the
	// first step in the chain, CombinatorDescendant or CombinatorChild
	// otherwise.
	Combinator string
	// Role is the raw role token as written in the selector ("" or "*"
	// both mean "any role").
	Role    string
	Attrs   []AttrPredicate
	Pseudos []string
	// Nth is the 1-indexed sibling position filter, or 0 when unset. It
	// requires sibling context that Element alone does not carry, so
	// MatchesElement does not apply it; callers that walk a tree with
	// sibling information are expected to apply it themselves.
	Nth int
}

type Snapshot struct {
	ID        string
	CreatedAt time.Time
	Backend   string
	AppID     string
	WindowID  string
	Root      *Element
	// Elements indexes every element in the snapshot by its bare element
	// id (e.g. "e17", without the "@<snapshotID>:" prefix).
	Elements map[string]*Element
	// Origin is the selector (if any) that produced this snapshot, kept so
	// the snapshot can be re-resolved after it goes stale.
	Origin *Selector
	// NativeHandles lets a backend stash opaque per-element native
	// handles (e.g. a COM pointer or a D-Bus object path) keyed by bare
	// element id, without leaking backend types into core.
	NativeHandles map[string]any
}

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

type WindowInfo struct {
	ID      string `json:"id"`
	AppID   string `json:"appId"`
	Title   string `json:"title"`
	Bounds  Bounds `json:"bounds"`
	Focused bool   `json:"focused"`
}