Module surface 

Shell-surface component — resolution of an OS shell surface (menu bar, Dock/taskbar/panel, tray status items, desktop, flyouts) as a targeting root.

This is a COMPONENT, not a tool: it knows how to turn a SurfaceKind into a ShellSurface handle (whose locator / as_element slot into the exact same selector flow apps use) and how to enforce the name | pid | surface targeting exclusivity, and nothing else. The observation tools (computer_snapshot, computer_screenshot) and the semantic pipeline (computer_act) compose it; a future tool that needs shell targeting can reuse it without carrying any of them along.

Enumeration is read-only by xa11y’s contract: listing a surface never opens, closes, focuses or presses anything.

Functions

resolve

Resolve a surface kind against the global singleton provider — the production path (same singleton every other tool reaches apps through).

resolve_with

Resolve a surface kind against an EXPLICIT provider — the seam the mock-provider tests use (they supply the mock instead of the live desktop session).

surface_label

Wire-facing label of a surface kind (matches the snake_case serde renaming), for error and output messages.

validate_act

Targeting check for computer_act (name/pid/surface on a semantic step).

validate_screenshot

Targeting check for computer_screenshot (app/pid/surface).

validate_snapshot

Targeting check for computer_snapshot (name/pid/surface).