// file: crates/engines/engine-v1-platform-api/src/environment.rs
// version: 1

/// Broad physical device class relevant to interaction and score provenance.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum DeviceClass {
    /// Conventional desktop or laptop computer.
    Desktop,
    /// Phone-sized touch device.
    Phone,
    /// Tablet-sized touch device.
    Tablet,
    /// Device class is intentionally unknown or not yet classified.
    Unknown,
}

/// Code execution model used by the game runtime.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum ExecutionModel {
    /// Native machine code for the target platform.
    Native,
    /// WebAssembly execution.
    Wasm,
}

/// Primary control profile relevant to gameplay comparability.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum InputProfile {
    /// Gamepad or equivalent controller is the primary input.
    Gamepad,
    /// Keyboard and mouse are the primary input devices.
    KeyboardMouse,
    /// Multiple materially different input modes are active for the same session.
    Mixed,
    /// Touchscreen or touch gestures are the primary input.
    Touch,
    /// Input profile is intentionally unknown or not yet classified.
    Unknown,
}

/// Broad platform family hosting the game.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum PlatformFamily {
    /// Android application environment.
    Android,
    /// Desktop operating-system environment.
    Desktop,
    /// Browser-oriented Web environment.
    Web,
}

/// Host container in which the game runtime executes.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum RuntimeHost {
    /// Conventional Web browser.
    Browser,
    /// Native process managed directly by the operating system.
    Native,
    /// Tauri desktop WebView host.
    TauriWebView,
}

/// Descriptive provenance attached to one runtime session.
///
/// This structure is intentionally descriptive: it does not decide whether two scores should be
/// compared. Leaderboard policy remains a game/backend responsibility.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct RuntimeProvenance {
    device_class: DeviceClass,
    execution_model: ExecutionModel,
    input_profile: InputProfile,
    platform_family: PlatformFamily,
    runtime_host: RuntimeHost,
}

impl RuntimeProvenance {
    /// Creates an explicit runtime provenance declaration.
    #[must_use]
    pub const fn new(
        device_class: DeviceClass,
        execution_model: ExecutionModel,
        input_profile: InputProfile,
        platform_family: PlatformFamily,
        runtime_host: RuntimeHost,
    ) -> Self {
        return Self { device_class, execution_model, input_profile, platform_family, runtime_host };
    }

    /// Returns the physical device class.
    #[must_use]
    pub const fn device_class(self) -> DeviceClass {
        return self.device_class;
    }

    /// Returns the execution model.
    #[must_use]
    pub const fn execution_model(self) -> ExecutionModel {
        return self.execution_model;
    }

    /// Returns the primary input profile.
    #[must_use]
    pub const fn input_profile(self) -> InputProfile {
        return self.input_profile;
    }

    /// Returns the broad platform family.
    #[must_use]
    pub const fn platform_family(self) -> PlatformFamily {
        return self.platform_family;
    }

    /// Returns the runtime host container.
    #[must_use]
    pub const fn runtime_host(self) -> RuntimeHost {
        return self.runtime_host;
    }
}

#[cfg(test)]
#[path = "../unit_tests/environment.rs"]
mod tests;