//! # Error Module
//!
//! Defines `WsgError`, the application-level error type for all WGPU operations in Context and Renderer methods.
//! Every variant maps a specific failure mode to a user-friendly message via `thiserror`. Errors propagate up through
//! Context's GPU initialization/rendering flow back to the orchestrator (main.rs), which handles them by skipping frames,
//! reconfiguring surfaces, or crashing gracefully.
//!
//! ## Interaction with Other Modules
//! - **context** uses WsgError as return types for `new()`, `configure()`, and `begin_frame()`.
//! - **renderer** does not use errors directly (render panics on invalid state rather than returning Result).

use thiserror::Error;

/// Application-level errors for the WSG library.
/// Every variant maps a specific failure mode during GPU initialization or rendering
/// to a user-friendly message via `thiserror`.
#[derive(Error, Debug)]
pub enum WsgError {
    /// The windowing system (winit) failed to create the surface — e.g. no display available.
    /// Caller: `Context::new()` after `Instance::create_surface()`.
    #[error("Window system error (winit)")]
    WindowSystem,

    /// No compatible graphics adapter was found for the given surface.
    /// This can happen if no Vulkan/Metal/DX12 backend is installed or if the integrated GPU
    /// is not exposed to the process.
    /// Caller: `Context::new()` after `Instance::request_adapter()`.
    #[error("No graphics adapter found")]
    NoAdapter,

    /// The requested device could not be obtained from the adapter — typically a driver bug
    /// or insufficient capabilities.
    /// Caller: `Context::new()` after `Adapter::request_device()`.
    #[error("Failed to create WGPU device")]
    DeviceCreation,

    /// A shader module failed to compile or link. The inner string holds the compiler output.
    /// Caller: renderer code that creates shaders via `Device::create_shader_module()`.
    #[error("Shader compilation or creation error: {0}")]
    ShaderError(String),

    /// An internal WGPU error propagated from a device request failure.
    /// Automatically converted via `thiserror`'s `#[from]` from `wgpu::RequestDeviceError`.
    /// Caller: `Context::new()` — maps the wgpu error into this variant automatically.
    #[error("Internal WGPU error: {0}")]
    InternalWgpu(#[from] wgpu::RequestDeviceError),

    /// The OS-level surface could not be created for the given window.
    /// Common causes: unsupported display server, window closed before surface creation,
    /// or platform-specific limitation.
    /// Caller: `Context::new()` after `Instance::create_surface()`.
    #[error("Failed to create rendering surface")]
    SurfaceCreation(wgpu::CreateSurfaceError),

    /// The surface is incompatible — no SRGB texture format and alpha mode are available on the device.
    /// Caller: `Context::configure()` when selecting a render format/alpha mode from surface capabilities.
    #[error("No compatible render format or alpha mode found for the surface")]
    SurfaceIncompatible,

    /// A timeout was encountered while acquiring a surface texture. Skip this frame and retry. Caller: `Context::begin_frame()`.
    #[error("Frame acquisition timed out")]
    FrameTimeout,

    /// The window is occluded (minimized or behind another window). Skip until visible. Caller: `Context::begin_frame()`.
    #[error("Window is occluded")]
    Occluded,

    /// The underlying surface changed — call configure() before retrying. Caller: `Context::begin_frame()` on surface mismatch.
    #[error("Surface configuration outdated; reconfigure required")]
    Outdated,

    /// The surface has been lost and needs to be recreated. Caller: `Context::begin_frame()` on surface loss.
    #[error("Surface lost")]
    Lost,

    /// A validation error inside get_current_texture() was raised. Caller: `Context::begin_frame()`.
    #[error("Validation error during frame acquisition")]
    Validation,

    /// Successfully acquired the surface texture but it no longer matches the surface properties.
    /// Reconfigure recommended for optimal performance. Caller: `Context::begin_frame()` on suboptimal acquire.
    #[error("Acquired suboptimal surface texture; reconfigure recommended")]
    SuboptimalTexture,
}