def app() -> App:
    """Get the active GUI application instance.

    Returns the singleton App instance for the current process, creating and
    initializing it if necessary. The GUI backend is determined automatically
    using `determine_app()`.

    This function should be used whenever you need to interact with the GUI
    application, such as running the event loop, showing windows, or scheduling
    thread-safe operations.

    Returns
    -------
    App
        The active App instance wrapping the GUI backend.

    Examples
    --------
    Get the app and run the event loop:

    >>> app().run()

    See Also
    --------
    determine_app : Function that selects which GUI backend to use
    GuiFrontend : Enumeration of available backends
    App : Base class defining the application interface
    """
    global _APP
    if _APP is not None:
        return _APP

    # ensure the app is created for explicitly requested frontends
    _APP = _load_app(*GUI_PROVIDERS[determine_app()])
    _APP.create_app()
    return _APP

def determine_app() -> GuiFrontend:
    """Determine which GUI backend to use for the application.

    This function selects the appropriate GUI framework backend through a
    three-tier strategy:

    1. **Explicit request**: If the SCENEX_APP_BACKEND environment variable
       is set, that backend is used (e.g., "qt", "wx", "jupyter").
    2. **Running application**: If a GUI application is already running in the
       process (detected via framework imports), that backend is used.
    3. **Available backend**: Try importing each backend in a predefined order until one
       succeeds.

    Returns
    -------
    GuiFrontend
        The determined GUI backend to use.

    Raises
    ------
    ValueError
        If the SCENEX_APP_BACKEND environment variable is set to an invalid
        value.
    RuntimeError
        If no GUI backend can be found or loaded.

    Examples
    --------
    Let the function auto-detect the backend:

    >>> backend = determine_app()

    Force a specific backend via environment variable:

    >>> import os
    >>> os.environ["SCENEX_APP_BACKEND"] = "qt"  # doctest: +SKIP
    >>> backend = determine_app()  # Will use Qt

    See Also
    --------
    app : Get the active App instance using the determined backend
    GuiFrontend : Enumeration of available backends
    """
    running = list(_running_apps())

    # Try 1: Load a frontend explicitly requested by the user
    requested = os.getenv(GUI_ENV_VAR, "").lower()
    valid = {x.value for x in GuiFrontend}
    if requested:
        if requested not in valid:
            raise ValueError(
                f"Invalid GUI frontend: {requested!r}. Valid options: {valid}"
            )
        return GuiFrontend(requested)

    # Try 2: Utilize an existing, running app
    for key in GUI_PROVIDERS.keys():
        if key in running:
            return key

    # Try 3: Load an existing app
    errors: list[tuple[str, BaseException]] = []
    for key, provider in GUI_PROVIDERS.items():
        try:
            _load_app(*provider)
            return key
        except Exception as e:
            errors.append((key, e))

    raise RuntimeError(  # pragma: no cover
        f"Could not find an appropriate GUI frontend: {valid!r}. Tried:\n\n"
        + "\n".join(f"- {key}: {err}" for key, err in errors)
    )

def ensure_main_thread(func: Callable[P, T]) -> Callable[P, Future[T]]:
    """Decorator that ensures a function is called in the main GUI thread.

    This decorator wraps a function so that when called, it is automatically
    scheduled to run on the main GUI thread rather than the caller's thread.
    This is essential for GUI operations that must occur on the main thread.

    Parameters
    ----------
    func : Callable[P, T]
        The function to wrap. Can have any signature.

    Returns
    -------
    Callable[P, Future[T]]
        A wrapped version of func that returns a Future instead of the direct
        result. The Future will contain the function's return value once the
        call completes on the main thread.

    Examples
    --------
    Ensure a GUI operation runs on the main thread:

    >>> @ensure_main_thread
    ... def update_widget(value: int) -> None:
    ...     # Update some GUI widget with the given value
    ...     pass
    >>> future = update_widget(42)  # Returns immediately with Future
    >>> result = future.result()  # Block until completion if needed

    See Also
    --------
    App.call_in_main_thread : Underlying method for thread-safe calls
    """

    @wraps(func)
    def _wrapper(*args: P.args, **kwargs: P.kwargs) -> Future[T]:
        return app().call_in_main_thread(func, *args, **kwargs)

    return _wrapper