@spec encode(
  selector :: parsed_selector() | nil,
  tree :: map() | nil,
  window_id :: String.t() | nil
) :: map()

Encodes an automation selector into the interact selector map expected by the renderer. An optional window_id scopes the selector to a specific window for multi-window apps.

@spec find(map() | nil, Plushie.Automation.Session.selector()) ::
  Plushie.Automation.Element.t() | nil

Finds the first element matching an automation selector.

@spec find_all_with_windows(
  tree :: map() | nil,
  selector :: Plushie.Automation.Session.selector()
) :: [
  {Plushie.Automation.Element.t(), String.t() | nil}
]

Finds all elements matching a selector, returning each with the window ID it belongs to. Used for ambiguity detection in multi-window apps.

@spec find_node(map() | nil, Plushie.Automation.Session.selector()) :: map() | nil

Finds the raw tree node for selectors that resolve directly to a widget.

@spec find_window_subtree(map() | nil, String.t()) :: map() | nil

Finds the window subtree with the given window ID.

@spec parse(Plushie.Automation.Session.selector()) ::
  {String.t() | nil, Plushie.Automation.Session.selector()}

Parses a window-qualified selector string into its components.

Returns {window_id, selector} where window_id is nil when no window qualifier is present.

Examples

iex> parse("main#save")
{"main", "#save"}

iex> parse("main#form/save")
{"main", "#form/save"}

iex> parse("#save")
{nil, "#save"}

iex> parse({:text, "Save"})
{nil, {:text, "Save"}}

@spec parse_selector(String.t()) :: {String.t() | nil, parsed_selector()}

Parse a unified selector string into its typed form.

Supports all selector types in a single string syntax:

• "form/email" or "#form/email" - ID path selector
• "main#form/email" - window-qualified ID selector
• ":focused" - state pseudo-selector
• "main#:focused" - window-qualified state selector
• "[text=Save]" - attribute selector
• "[role=button]" - attribute selector
• "main#[text=Save]" - window-qualified attribute selector

Returns {window_id, resolved_selector} where resolved_selector is one of: "#id" (string), :focused (atom), {:text, "Save"} (tuple), etc. Unknown pseudo-selectors resolve to {:unknown_pseudo, name} so lookup can fail without raising.