Fix native image rendering for Kitty protocol (#181)

- Delete all placements before each redraw so images that scroll out of view are cleared instead of ghosting on screen
- Use source-rect crop params (y/h) instead of scaling when images are partially visible, preventing stretching
- Encode images at full dimensions for caching and crop at display time, fixing inconsistent cache hits at different visible heights
- Skip image emit when visible images match previous frame to prevent flicker during unrelated redraws
- Wrap entire render cycle (clear + draw + image overlay) in synchronized update so the terminal renders atomically
- Suppress terminal responses on graphics commands (q=2)

Author: Dowsley

src/app.rs

@@ -91,11 +91,16 @@ fn show_desktop_notification(sender: &str, body: &str, is_group: bool, group_nam
 }
 
 /// An image visible on screen, for native protocol overlay rendering.
+#[derive(PartialEq, Eq)]
 pub struct VisibleImage {
     pub x: u16,
     pub y: u16,
     pub width: u16,
     pub height: u16,
+    /// Total image height in cells (before viewport clipping).
+    pub full_height: u16,
+    /// Cells cropped from the top when the image is partially scrolled out.
+    pub crop_top: u16,
     pub path: String,
 }
 
@@ -351,10 +356,12 @@ pub struct App {
     pub image_protocol: ImageProtocol,
     /// Images visible on screen for native protocol overlay (cleared each frame)
     pub visible_images: Vec<VisibleImage>,
+    /// Previous frame's visible images, for skipping redundant image redraws
+    pub prev_visible_images: Vec<VisibleImage>,
     /// Experimental: use native terminal image protocols (Kitty/iTerm2) instead of halfblock
     pub native_images: bool,
-    /// Cache of base64-encoded pre-resized PNGs for native protocol (path → base64)
-    pub native_image_cache: HashMap<String, String>,
+    /// Cache of pre-resized PNGs for native protocol (path → (base64, pixel_w, pixel_h))
+    pub native_image_cache: HashMap<String, (String, u32, u32)>,
     /// Previous active conversation ID, for detecting chat switches
     pub prev_active_conversation: Option<String>,
     /// Incognito mode — in-memory DB, no local persistence
@@ -2463,6 +2470,7 @@ impl App {
             link_url_map: HashMap::new(),
             image_protocol: image_render::detect_protocol(),
             visible_images: Vec::new(),
+            prev_visible_images: Vec::new(),
             native_images: false,
             native_image_cache: HashMap::new(),
             prev_active_conversation: None,

src/image_render.rs

@@ -35,9 +35,9 @@ pub fn detect_protocol() -> ImageProtocol {
 
 /// Pre-resize an image and encode as PNG for native terminal protocol rendering.
 ///
-/// Returns the base64-encoded PNG data, sized to look good at the given cell
-/// dimensions. Assumes ~8px per cell width and ~16px per cell height.
-pub fn encode_native_png(path: &Path, cell_width: u32, cell_height: u32) -> Option<String> {
+/// Returns `(base64_data, pixel_width, pixel_height)` sized to look good at the
+/// given cell dimensions. Assumes ~8px per cell width and ~16px per cell height.
+pub fn encode_native_png(path: &Path, cell_width: u32, cell_height: u32) -> Option<(String, u32, u32)> {
     let img = image::open(path).ok()?;
     let (orig_w, orig_h) = img.dimensions();
     if orig_w == 0 || orig_h == 0 {
@@ -65,7 +65,7 @@ pub fn encode_native_png(path: &Path, cell_width: u32, cell_height: u32) -> Opti
         .ok()?;
 
     use base64::Engine;
-    Some(base64::engine::general_purpose::STANDARD.encode(buf.into_inner()))
+    Some((base64::engine::general_purpose::STANDARD.encode(buf.into_inner()), new_w, new_h))
 }
 
 /// Render an image file as halfblock-character lines for display in a terminal.

src/main.rs

@@ -20,7 +20,7 @@ use crossterm::{
     event::{self, EnableBracketedPaste, DisableBracketedPaste, EnableMouseCapture, DisableMouseCapture, Event, KeyEventKind},
     execute, queue,
     style::{Print, ResetColor, SetForegroundColor},
-    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen, BeginSynchronizedUpdate, EndSynchronizedUpdate},
 };
 use ratatui::{
     backend::CrosstermBackend,
@@ -457,25 +457,45 @@ fn emit_native_images(
     app: &mut App,
 ) -> Result<()> {
     let protocol = app.image_protocol;
-    if app.visible_images.is_empty() || protocol == image_render::ImageProtocol::Halfblock {
+    if protocol == image_render::ImageProtocol::Halfblock {
         return Ok(());
     }
+
+    // Skip if visible images haven't changed since last frame
+    if app.visible_images == app.prev_visible_images {
+        return Ok(());
+    }
+
     use std::io::Write;
 
+    // Delete old Kitty placements before rendering new ones,
+    // so images that scroll out of view are properly cleared.
+    if protocol == image_render::ImageProtocol::Kitty {
+        write!(backend, "\x1b_Ga=d,q=2\x1b\\")?;
+    }
+
+    if app.visible_images.is_empty() {
+        app.prev_visible_images.clear();
+        if protocol == image_render::ImageProtocol::Kitty {
+            backend.flush()?;
+        }
+        return Ok(());
+    }
+
     // Take images out to avoid borrow conflict with native_image_cache
     let images = std::mem::take(&mut app.visible_images);
 
     queue!(backend, SavePosition)?;
 
     for img in &images {
-        // Get or compute cached base64 PNG data
-        let b64 = if let Some(cached) = app.native_image_cache.get(&img.path) {
+        // Get or compute cached base64 PNG data (always at full image dimensions)
+        let (b64, _px_w, px_h) = if let Some(cached) = app.native_image_cache.get(&img.path) {
             cached.clone()
         } else {
             let encoded = image_render::encode_native_png(
                 std::path::Path::new(&img.path),
                 img.width as u32,
-                img.height as u32,
+                img.full_height as u32,
             );
             match encoded {
                 Some(data) => {
@@ -492,14 +512,30 @@ fn emit_native_images(
             image_render::ImageProtocol::Kitty => {
                 // f=100 = detect format, a=T = transmit+display
                 // c/r = display size in cells, C=1 = don't move cursor
+                // y/h = source crop in pixels for partially visible images
+                let mut crop_params = String::new();
+                if img.crop_top > 0 || img.height < img.full_height {
+                    let y_px = if img.full_height > 0 {
+                        img.crop_top as u32 * px_h / img.full_height as u32
+                    } else {
+                        0
+                    };
+                    let h_px = if img.full_height > 0 {
+                        (img.height as u32 * px_h / img.full_height as u32).max(1)
+                    } else {
+                        px_h
+                    };
+                    crop_params = format!(",y={y_px},h={h_px}");
+                }
+
                 let chunks: Vec<&[u8]> = b64.as_bytes().chunks(4096).collect();
                 for (i, chunk) in chunks.iter().enumerate() {
                     let m = if i == chunks.len() - 1 { 0 } else { 1 };
                     let chunk_str = std::str::from_utf8(chunk).unwrap_or("");
                     if i == 0 {
                         write!(
                             backend,
-                            "\x1b_Gf=100,a=T,c={},r={},C=1,m={m};{chunk_str}\x1b\\",
+                            "\x1b_Gf=100,a=T,c={},r={},C=1,q=2{crop_params},m={m};{chunk_str}\x1b\\",
                             img.width, img.height
                         )?;
                     } else {
@@ -520,6 +556,8 @@ fn emit_native_images(
 
     queue!(backend, RestorePosition)?;
     backend.flush()?;
+
+    app.prev_visible_images = images;
     Ok(())
 }
 
@@ -796,12 +834,15 @@ async fn run_app(
     loop {
         // Only redraw when state has changed (avoids resetting cursor blink timer every 50ms)
         if needs_redraw {
+            // Wrap entire render (clear + text + image overlay) in synchronized
+            // update so the terminal renders everything atomically.
+            queue!(terminal.backend_mut(), BeginSynchronizedUpdate)?;
+
             // Force full redraw when active conversation changes (clears native image artifacts)
             if app.native_images && app.active_conversation != app.prev_active_conversation {
                 app.prev_active_conversation = app.active_conversation.clone();
                 terminal.clear()?;
             }
-
             terminal.draw(|frame| ui::draw(frame, &mut app))?;
             let has_post_draw = !app.link_regions.is_empty() || app.native_images;
             if has_post_draw && app.mode == InputMode::Insert {
@@ -812,8 +853,9 @@ async fn run_app(
                 emit_native_images(terminal.backend_mut(), &mut app)?;
             }
             if has_post_draw && app.mode == InputMode::Insert {
-                execute!(terminal.backend_mut(), Show)?;
+                queue!(terminal.backend_mut(), Show)?;
             }
+            execute!(terminal.backend_mut(), EndSynchronizedUpdate)?;
             needs_redraw = false;
         }
 
@@ -982,11 +1024,12 @@ async fn run_demo_app(
 
     loop {
         if needs_redraw {
+            queue!(terminal.backend_mut(), BeginSynchronizedUpdate)?;
+
             if app.native_images && app.active_conversation != app.prev_active_conversation {
                 app.prev_active_conversation = app.active_conversation.clone();
                 terminal.clear()?;
             }
-
             terminal.draw(|frame| ui::draw(frame, &mut app))?;
             let has_post_draw = !app.link_regions.is_empty() || app.native_images;
             if has_post_draw && app.mode == InputMode::Insert {
@@ -997,8 +1040,9 @@ async fn run_demo_app(
                 emit_native_images(terminal.backend_mut(), &mut app)?;
             }
             if has_post_draw && app.mode == InputMode::Insert {
-                execute!(terminal.backend_mut(), Show)?;
+                queue!(terminal.backend_mut(), Show)?;
             }
+            execute!(terminal.backend_mut(), EndSynchronizedUpdate)?;
             needs_redraw = false;
         }
 

src/ui.rs

@@ -1183,11 +1183,16 @@ fn draw_messages(frame: &mut Frame, app: &mut App, area: Rect) {
                     0
                 };
 
+                let full_height = (img_end - img_start) as u16;
+                let crop_top = (vis_start as i64 - screen_start) as u16;
+
                 app.visible_images.push(VisibleImage {
                     x: inner.x + 2, // account for 2-char indent
                     y: inner.y + vis_start,
                     width: img_width,
                     height: vis_end - vis_start,
+                    full_height,
+                    crop_top,
                     path: path.clone(),
                 });
             }