feat: display profile avatar image with terminal graphics protocols (#23)

* feat: display profile avatar with terminal image protocols

* docs: add image display documentation to README

Author: unhappychoice

Cargo.lock

@@ -24,3 +24,7 @@ anyhow = "1"
 steamworks = { version = "0.12", features = ["raw-bindings"] }
 libloading = "0.8"
 indicatif = "0.17"
+image = "0.25"
+icy_sixel = "0.5"
+base64 = "0.22.1"
+libc = "0.2.182"

Cargo.toml

@@ -82,9 +82,18 @@ export STEAM_ID="your_steam_id_here"
 # Display your Steam stats
 steamfetch
 
+# Show profile avatar image instead of ASCII logo
+steamfetch --image
+
+# Specify image protocol (auto, kitty, iterm, sixel)
+steamfetch --image --image-protocol sixel
+
 # Demo mode (no API key required)
 steamfetch --demo
 
+# Demo mode with image
+steamfetch --demo --image
+
 # Show config file path
 steamfetch --config-path
 
@@ -110,8 +119,23 @@ steamfetch --help
 - Recently played games (last 2 weeks)
 - Rarest achievement display
 - Beautiful SteamOS ASCII art with gradient colors
+- **Image display**: Show your Steam avatar with `--image` flag
 - Demo mode for testing without API setup
 
+### Image Display
+
+Use `--image` to show your Steam profile avatar instead of the ASCII logo.
+
+Supported protocols:
+- **Sixel** - Windows Terminal, WezTerm, foot, mlterm, xterm
+- **Kitty** - Kitty terminal
+- **iTerm2** - iTerm2
+- **Block characters** - Fallback for unsupported terminals
+
+Protocol is auto-detected by default. Use `--image-protocol` to override.
+
+Images are cached locally at `~/.cache/steamfetch/images/`.
+
 ## How It Works
 
 ### With Steam Client Running

README.md

@@ -1,14 +1,76 @@
 use colored::Colorize;
+use std::io::{self, Write};
 
+use crate::image_display;
 use crate::steam::SteamStats;
+use crate::ImageProtocol;
 
-pub fn render(stats: &SteamStats) {
+const IMAGE_COLS: u32 = 34;
+const IMAGE_ROWS: u32 = 18;
+
+pub struct ImageConfig {
+    pub enabled: bool,
+    pub protocol: ImageProtocol,
+}
+
+pub async fn render(stats: &SteamStats, image_config: &ImageConfig) {
     let info_lines = build_info_lines(stats);
+
+    if image_config.enabled {
+        render_with_image(stats, &info_lines, image_config).await;
+    } else {
+        render_with_ascii(&info_lines);
+    }
+}
+
+async fn render_with_image(stats: &SteamStats, info_lines: &[String], config: &ImageConfig) {
+    let avatar = match &stats.avatar_url {
+        Some(url) => {
+            let cache_key = format!("avatar_{}.png", stats.username);
+            image_display::load_cached_or_download(url, &cache_key).await
+        }
+        None => None,
+    };
+
+    let Some(img) = avatar else {
+        return render_with_ascii(info_lines);
+    };
+
+    println!();
+
+    // Print image and rewind cursor to top-left of image area
+    let image_rows =
+        image_display::print_image_and_rewind(&img, &config.protocol, IMAGE_COLS, IMAGE_ROWS);
+
+    let Some(image_rows) = image_rows else {
+        return render_with_ascii(info_lines);
+    };
+
+    let col_offset = IMAGE_COLS + 3; // image width + gap
+    let mut stdout = io::stdout().lock();
+
+    // Print info lines to the right of the image
+    for (i, line) in info_lines.iter().enumerate() {
+        if i > 0 {
+            writeln!(stdout).unwrap();
+        }
+        image_display::cursor_right(col_offset);
+        write!(stdout, "{}", line).unwrap();
+    }
+
+    // Ensure we end up below the image area
+    let extra = (image_rows as usize).saturating_sub(info_lines.len());
+    for _ in 0..=extra {
+        writeln!(stdout).unwrap();
+    }
+    stdout.flush().unwrap();
+}
+
+fn render_with_ascii(info_lines: &[String]) {
     let logo_lines = build_logo();
 
     println!();
     for (i, logo_line) in logo_lines.iter().enumerate() {
-        // Offset info by 1 line to align vertically
         let info = if i == 0 {
             ""
         } else {