fix: apply kitty X=/Y= sub-cell pixel offset to placements (#1646)

* fix: apply kitty X=/Y= sub-cell pixel offset to placements

The kitty graphics protocol lets a placement specify X= and Y= pixel
offsets to "display from a different origin within the cell" (see
"Controlling displayed image layout" in the spec [1]). The wiring for
this was half-finished: KittyPlacement already had cell_x_offset/
cell_y_offset fields and the parser already populated them from X=/Y=,
but nothing connected the two.

Finish the wiring: thread the offset parser -> PlacementRequest ->
KittyPlacement -> render position.

Adds parser tests for the offset and the default.

[1] https://sw.kovidgoyal.net/kitty/graphics-protocol/

* small updates

---------

Co-authored-by: Floens <floens@gmail.com>

Author: raphamorim

frontends/rioterm/src/renderer/mod.rs

@@ -438,8 +438,13 @@ impl Renderer {
                         }
                         overlays.push(rio_backend::sugarloaf::GraphicOverlay {
                             image_id: p.image_id,
-                            x: origin_x + p.dest_col as f32 * cell_width,
-                            y: origin_y + screen_row as f32 * cell_height,
+                            // kitty X=/Y= offset, supports sub-cell positioning
+                            x: origin_x
+                                + p.dest_col as f32 * cell_width
+                                + p.cell_x_offset as f32,
+                            y: origin_y
+                                + screen_row as f32 * cell_height
+                                + p.cell_y_offset as f32,
                             width: p.pixel_width as f32,
                             height: p.pixel_height as f32,
                             z_index: p.z_index,

rio-backend/src/ansi/kitty_graphics_protocol.rs

@@ -111,6 +111,9 @@ pub struct PlacementRequest {
     /// the uppercase `U=1` flag). Currently informational only.
     pub unicode_placeholder: u32,
     pub cursor_movement: u8, // 0 = move cursor to after image (default), 1 = don't move cursor
+    /// kitty `X=`/`Y=` pixel offset, supports sub-cell positioning.
+    pub cell_x_offset: u32,
+    pub cell_y_offset: u32,
 }
 
 #[derive(Debug)]
@@ -631,6 +634,8 @@ pub fn parse(
                     virtual_placement: cmd.virtual_placement,
                     unicode_placeholder: cmd.unicode_placeholder,
                     cursor_movement: cmd.cursor_movement,
+                    cell_x_offset: cmd.cell_x_offset,
+                    cell_y_offset: cmd.cell_y_offset,
                 })
             } else {
                 None
@@ -659,6 +664,8 @@ pub fn parse(
                 virtual_placement: cmd.virtual_placement,
                 unicode_placeholder: cmd.unicode_placeholder,
                 cursor_movement: cmd.cursor_movement,
+                cell_x_offset: cmd.cell_x_offset,
+                cell_y_offset: cmd.cell_y_offset,
             };
             let response = if cmd.implicit_id {
                 None
@@ -1553,6 +1560,33 @@ mod tests {
         assert_eq!(placement.z_index, 2);
     }
 
+    #[test]
+    fn test_parse_placement_subcell_offset() {
+        // `X=`/`Y=` are the sub-cell pixel offset within the placement's
+        // first cell. They must flow through to the PlacementRequest so the
+        // renderer can position the image at pixel (not just cell)
+        // granularity, for smooth sub-cell scrolling.
+        let result = parse_kitty_graphics_protocol("a=p,i=1,X=7,Y=9", "");
+        let placement = result
+            .expect("parse ok")
+            .placement_request
+            .expect("placement");
+        assert_eq!(placement.cell_x_offset, 7);
+        assert_eq!(placement.cell_y_offset, 9);
+    }
+
+    #[test]
+    fn test_parse_placement_subcell_offset_defaults_zero() {
+        // Omitting `X=`/`Y=` leaves the offset at the cell boundary.
+        let result = parse_kitty_graphics_protocol("a=p,i=1", "");
+        let placement = result
+            .expect("parse ok")
+            .placement_request
+            .expect("placement");
+        assert_eq!(placement.cell_x_offset, 0);
+        assert_eq!(placement.cell_y_offset, 0);
+    }
+
     #[test]
     fn test_parse_delete() {
         let result = parse_kitty_graphics_protocol("a=d,d=i,i=1", "");

rio-backend/src/crosswords/mod.rs

@@ -4416,16 +4416,27 @@ impl<U: EventListener> Crosswords<U> {
         // Absolute row = history_size + screen-relative row
         let dest_row = self.history_size() as i64 + cursor_row as i64;
 
-        // Compute cell-based size
+        // kitty spec the `X=`/`Y=` sub-cell offset must be smaller
+        // than the cell size; kitty clamps out-of-range values to the
+        // cell box
+        let cell_x_offset = (placement.cell_x_offset as usize).min(cell_width - 1);
+        let cell_y_offset = (placement.cell_y_offset as usize).min(cell_height - 1);
+
+        // Compute cell-based size.
+        //
+        // the trick is the sub-cell offset shifts the image
+        // within its first cell, so it can spill into one extra
+        // row/column. Include it so cursor movement and row occupation
+        // cover the full image.
         let columns = if placement.columns > 0 {
             placement.columns
         } else {
-            display_w.div_ceil(cell_width) as u32
+            (display_w + cell_x_offset).div_ceil(cell_width) as u32
         };
         let rows = if placement.rows > 0 {
             placement.rows
         } else {
-            display_h.div_ceil(cell_height) as u32
+            (display_h + cell_y_offset).div_ceil(cell_height) as u32
         };
 
         // Create overlay placement.
@@ -4454,8 +4465,8 @@ impl<U: EventListener> Crosswords<U> {
             rows,
             pixel_width: display_w as u32,
             pixel_height: display_h as u32,
-            cell_x_offset: 0,
-            cell_y_offset: 0,
+            cell_x_offset: cell_x_offset as u32,
+            cell_y_offset: cell_y_offset as u32,
             z_index: placement.z_index,
             transmit_time,
         };
@@ -6640,6 +6651,8 @@ mod tests {
             virtual_placement: true,
             unicode_placeholder: 0,
             cursor_movement: 0,
+            cell_x_offset: 0,
+            cell_y_offset: 0,
         };
 
         cw.place_graphic(placement);