# `Plushie.Automation.Selector`
[🔗](https://github.com/plushie-ui/plushie-elixir/blob/v0.7.2/lib/plushie/automation/selector.ex#L1)

Selector helpers for automation against a normalized Plushie tree.

This module resolves the selector forms accepted by `Plushie.Automation.Session`
into either tree nodes or renderer interact selectors.

# `encode`

```elixir
@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.

# `find`

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

Finds the first element matching an automation selector.

# `find_all_with_windows`

```elixir
@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.

# `find_node`

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

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

# `find_window_subtree`

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

Finds the window subtree with the given window ID.

# `parse`

```elixir
@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"}}

# `parse_selector`

```elixir
@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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
