AutomationBase and UIA facades

@handle_csharp_exceptions
def compare(self, element1: Any, element2: Any) -> bool:
    """Return whether two elements refer to the same underlying UI element."""
    return self.raw_automation.Compare(
        self._to_cs_automation_element(element1),
        self._to_cs_automation_element(element2),
    )

@handle_csharp_exceptions
def dispose(self) -> None:
    """Release automation resources (matches C# Dispose)."""
    self.raw_automation.Dispose()

@handle_csharp_exceptions
def focused_element(self) -> Optional[AutomationElement]:
    """Return the currently focused element, or None when the provider has no focus."""
    from flaui.core.automation_elements import AutomationElement as PyAutomationElement

    raw = self.raw_automation.FocusedElement()
    if raw is None:
        return None
    return PyAutomationElement(raw_element=raw)

@handle_csharp_exceptions
def from_handle(self, hwnd: int) -> AutomationElement:
    """Return the element for a window handle (HWND)."""
    from System import IntPtr  # pyright: ignore
    from flaui.core.automation_elements import AutomationElement as PyAutomationElement

    return PyAutomationElement(raw_element=self.raw_automation.FromHandle(IntPtr(hwnd)))

@handle_csharp_exceptions
def from_point(self, point: Point) -> AutomationElement:
    """Return the element at the given screen point."""
    from flaui.core.automation_elements import AutomationElement as PyAutomationElement

    return PyAutomationElement(raw_element=self.raw_automation.FromPoint(point.raw_value))

@handle_csharp_exceptions
def get_desktop(self) -> AutomationElement:
    """Return the desktop (root) element as a Python AutomationElement."""
    from flaui.core.automation_elements import AutomationElement as PyAutomationElement

    return PyAutomationElement(raw_element=self.raw_automation.GetDesktop())

@handle_csharp_exceptions
def register_focus_changed_event(self, action: Any) -> Any:
    """Register a focus-changed handler.

    :param action: Callback ``(element) -> None`` invoked when focus changes.
    :return: An :class:`~flaui.core.event_handlers.EventRegistration` handle that keeps the
        callback alive and can unregister it.
    """
    from flaui.core.automation_elements import AutomationElement as PyAutomationElement
    from flaui.core.event_handlers import EventRegistration, make_focus_changed_delegate, safe_invoke

    def _handler(sender: Any) -> None:
        """Bridge the C# callback to the Python action."""
        safe_invoke(action, PyAutomationElement(raw_element=sender))

    handler = self.raw_automation.RegisterFocusChangedEvent(make_focus_changed_delegate(_handler))
    return EventRegistration(
        cs_handler=handler,
        callback=_handler,
        unregister=lambda h: self.raw_automation.UnregisterFocusChangedEvent(h),
    )

@handle_csharp_exceptions
def unregister_all_events(self) -> None:
    """Remove all registered UI Automation event handlers."""
    self.raw_automation.UnregisterAllEvents()

@handle_csharp_exceptions
def unregister_focus_changed_event(self, event_handler: Any) -> None:
    """Unregister a focus-changed handler returned by :meth:`register_focus_changed_event`.

    :param event_handler: The :class:`~flaui.core.event_handlers.EventRegistration` returned by
        :meth:`register_focus_changed_event`, or a raw C# handler.
    """
    from flaui.core.event_handlers import EventRegistration

    if isinstance(event_handler, EventRegistration):
        event_handler.unregister()
    else:
        self.raw_automation.UnregisterFocusChangedEvent(event_handler)

@field_validator("raw_automation")
@classmethod
def validate_raw_automation(cls, v: Any, info: ValidationInfo) -> Any:
    """Reject a missing C# automation reference."""
    if v is None:
        raise ValueError("raw_automation must not be None")
    return v