feat: add snapped plot hover probe

Keep plot controls stable by moving hover coordinates into a dedicated readout row above the status line.

Snap hover positions to the nearest visible data point and render a subtle vertical guide with highlighted samples in hover-specific cached frames, leaving normal no-hover cache and prefetch behavior untouched.

Author: siriusctrl

CHANGELOG.md

@@ -10,8 +10,9 @@ matching `## [X.Y.Z]` section before the release tag is pushed.
 
 ### Added
 
-- Add read-only plot hover readouts that show the hovered x value and nearest
-  visible point coordinates in the status bar without changing the viewport.
+- Add read-only plot hover readouts that snap to the nearest visible point,
+  show a separate coordinate row above the controls, and draw a subtle vertical
+  hover line with highlighted snapped points.
 
 ## [0.2.2] - 2026-06-18
 

README.md

@@ -49,7 +49,8 @@ Common controls:
 - `0`: fit to terminal
 - arrow keys: pan
 - `m`: toggle metadata or plot summary overlay
-- mouse hover over plots: show the nearest visible point coordinates
+- mouse hover over plots: show a snapped vertical readout and nearest visible
+  point coordinates
 - left mouse drag: pan image inputs
 
 Most users do not need to pass `--protocol`. The default is `auto`:
@@ -236,9 +237,9 @@ Plot data:
   during idle time, and avoids full-screen clears for image protocol frames.
   Background preloads never replace the currently visible frame, so rapid
   zooming and panning keep axis labels and chart body in sync.
-- Plot mouse hover is read-only. Moving the mouse over the chart body updates
-  the status bar with the hover `x` value and nearest visible point coordinates
-  without changing the viewport.
+- Plot mouse hover is read-only. Moving the mouse over the chart body snaps to
+  the nearest visible point, draws a subtle vertical readout line, and shows a
+  separate coordinate row above the controls without changing the viewport.
 - Pixel-protocol plot viewing keeps chart chrome as real terminal text and
   sends only the plot body through the image protocol. This keeps file names,
   legends, axis labels, and controls crisp while reducing image payload size.

docs/architecture.md

@@ -120,9 +120,13 @@ future same-zoom pan frames, then composite those marks over the current
 grid/frame layer so axis labels and grid lines stay correct.
 
 Mouse input in the plot viewer is read-only. Hover events remember the latest
-terminal cell and update only the status chrome with a data-space x value plus
-nearest visible point coordinates; they do not pan, zoom, or invalidate the
-current plot image.
+terminal cell, snap to the nearest visible plot point, and render a separate
+coordinate readout row above the controls. Rasterized plot frames include a
+subtle vertical hover line and highlighted snapped points in the chart body;
+the block fallback receives the same overlay before it is converted to terminal
+text. Hover does not pan or zoom, but it does create a hover-specific plot
+frame so the foreground image can reflect the current readout without
+contaminating the normal no-hover frame cache or prefetch path.
 
 Kitty plot frames use zlib-compressed raw RGBA direct-data payloads so terminal
 updates avoid PNG decode work while still working when the terminal process

src/tui.rs

@@ -108,7 +108,11 @@ impl TerminalSession {
             self.stdout,
             MoveTo(0, 0),
             Clear(ClearType::All),
-            Print(content_to_lines(content, size))
+            Print(content_to_lines(
+                content,
+                size.content_height().max(1),
+                size.width
+            ))
         )
         .context("drawing terminal frame")?;
         if size.height > 0 {
@@ -118,6 +122,45 @@ impl TerminalSession {
         Ok(())
     }
 
+    pub(crate) fn draw_frame_with_readout(
+        &mut self,
+        content: &str,
+        readout: &ChromeLine,
+        status: &str,
+    ) -> Result<()> {
+        let size = self.size()?;
+        let content_rows = size.height.saturating_sub(2).max(1);
+        queue!(
+            self.stdout,
+            MoveTo(0, 0),
+            Clear(ClearType::All),
+            Print(content_to_lines(content, content_rows, size.width))
+        )
+        .context("drawing terminal frame with readout")?;
+        if size.height > 1 {
+            draw_chrome_line(
+                &mut self.stdout,
+                size.height.saturating_sub(2),
+                size.width.max(1),
+                PLOT_CHROME_BG,
+                Color::Rgb {
+                    r: 41,
+                    g: 54,
+                    b: 57,
+                },
+                readout,
+            )
+            .context("drawing terminal frame readout")?;
+        }
+        if size.height > 0 {
+            self.draw_status_line(size, status)?;
+        }
+        self.stdout
+            .flush()
+            .context("flushing terminal frame with readout")?;
+        Ok(())
+    }
+
     pub(crate) fn draw_protocol_frame(&mut self, payload: &str, status: &str) -> Result<()> {
         let size = self.size()?;
         queue!(self.stdout, MoveTo(0, 0), Print(payload)).context("drawing protocol payload")?;
@@ -139,6 +182,7 @@ impl TerminalSession {
         self.draw_plot_dynamic_chrome(size, &frame)?;
         self.draw_plot_axis_labels(&frame)?;
         if size.height > 0 {
+            self.draw_plot_readout_line(size, &frame)?;
             self.draw_plot_status_line(size, &frame.chrome.dynamic_layer.status)?;
         }
         queue!(
@@ -202,6 +246,17 @@ impl TerminalSession {
             .context("painting plot x-axis row")?;
         }
 
+        if frame.chrome.dynamic_layer.readout_row < size.height.saturating_sub(1) {
+            paint_row(
+                &mut self.stdout,
+                0,
+                frame.chrome.dynamic_layer.readout_row,
+                size.width,
+                PLOT_CHROME_BG,
+            )
+            .context("painting plot readout row")?;
+        }
+
         Ok(())
     }
 
@@ -334,6 +389,30 @@ impl TerminalSession {
         Ok(())
     }
 
+    fn draw_plot_readout_line(
+        &mut self,
+        size: TerminalSize,
+        frame: &PlotProtocolFrame<'_>,
+    ) -> Result<()> {
+        if frame.chrome.dynamic_layer.readout_row >= size.height.saturating_sub(1) {
+            return Ok(());
+        }
+        draw_chrome_line(
+            &mut self.stdout,
+            frame.chrome.dynamic_layer.readout_row,
+            size.width.max(1),
+            PLOT_CHROME_BG,
+            Color::Rgb {
+                r: 41,
+                g: 54,
+                b: 57,
+            },
+            &frame.chrome.dynamic_layer.readout,
+        )
+        .context("drawing plot readout line")?;
+        Ok(())
+    }
+
     pub(crate) fn stop(&mut self) -> Result<()> {
         if !self.active {
             return Ok(());
@@ -373,17 +452,17 @@ impl Drop for TerminalSession {
     }
 }
 
-fn content_to_lines(content: &str, size: TerminalSize) -> String {
-    let width = usize::from(size.width.max(1));
-    let content_rows = usize::from(size.content_height().max(1));
+fn content_to_lines(content: &str, content_rows: u16, width: u16) -> String {
+    let width = usize::from(width.max(1));
+    let content_rows = usize::from(content_rows.max(1));
     let mut output = String::new();
     for (row, line) in content.lines().take(content_rows).enumerate() {
         if line.contains('\u{1b}') {
             output.push_str(line);
         } else {
             output.push_str(&trim_to_width(line, width));
         }
-        if row + 1 < content_rows || size.height > 1 {
+        if row + 1 < content_rows {
             output.push_str("\r\n");
         }
     }
@@ -421,13 +500,7 @@ mod tests {
 
     #[test]
     fn frame_content_uses_crlf_for_raw_terminal_mode() {
-        let output = content_to_lines(
-            "alpha\nbeta",
-            TerminalSize {
-                width: 8,
-                height: 3,
-            },
-        );
+        let output = content_to_lines("alpha\nbeta", 2, 8);
 
         assert!(output.contains("alpha   \r\nbeta"));
         assert!(!output.contains("alpha   \nbeta"));

src/tui/plot_frame.rs

@@ -33,6 +33,8 @@ pub(crate) struct DynamicPlotChrome {
     pub(crate) header: ChromeLine,
     pub(crate) y_labels: Vec<PlotAxisLabel>,
     pub(crate) x_labels: Vec<PlotAxisLabel>,
+    pub(crate) readout_row: u16,
+    pub(crate) readout: ChromeLine,
     pub(crate) status: ChromeLine,
 }