Move displaced output out of the band when a resize shrinks onto it

A terminal that shrinks can leave the command's cursor, and the line it is
writing, on a row the new toolbar band takes. Skipping recovery during a
command kept that cursor where it was, so the band was painted over the
unfinished line and the next write landed inside the toolbar row.

reconfigure() now treats a size change as the transition it is: it resets
to full-screen margins, clears a grown terminal's stale band row, and makes
room for the new band -- indexing at the bottom scrolls the displaced
output up into the usable region and moves the cursor with it, column
intact -- before installing the region. The band is then painted over rows
that hold nothing the command still needs.

The emulated terminal used by these tests gains a shrink that keeps the
cursor's row on screen, as xterm and VTE do; pyte's own clips inside the
scroll margins and drops that row, which is not what a real terminal
shows. The regression test writes past the point the new band will take,
resizes, and checks the line, its cursor column, the toolbar row and the
absence of output in the band.

Validation: 2605 passed, 6 skipped with coverage, twice; the reserved
modules at 100% line coverage; removing the room-making step fails the
new test. Harness acceptance and dynamic gates PASS at 12, 24 and 40 rows,
23/23 observer controls. make check, make test and make docs-test passed.

Author: tleonhardt

CHANGELOG.md

@@ -12,7 +12,9 @@
       wrapping to the old width. A stale toolbar is no longer left behind when the terminal grows.
     - Command output that does not end in a newline (for example a progress line updated with a
       carriage return) is no longer erased by a reserved toolbar's redraw, its shutdown, or a
-      terminal resize. The line in progress is preserved and the next write continues it.
+      terminal resize. The line in progress is preserved and the next write continues it. When
+      shrinking leaves that line in the rows the toolbar takes, the line and its cursor are moved up
+      into the usable region before the toolbar is painted.
     - Reserved rendering is no longer left suppressed, and the main prompt invisible, when a
       terminal that shrank below the two-row minimum during a command grows back afterward.
     - The built-in pager (used by `Cmd.ppaged()`) again displays its content in reserved toolbar

cmd2/terminal_display.py

@@ -465,13 +465,23 @@ def reconfigure(self) -> bool:
             # The guest may have scrolled to the physical bottom, just as the shell
             # that launched us may have done before the initial acquisition.
             self._terminal.make_room_for_region(geometry)
-        elif geometry.physical_rows > previous.physical_rows:
-            # The terminal grew, so the rows the old band occupied are now inside the screen
-            # and still hold its stale text. They never scrolled -- the band sits outside the
-            # scroll region -- so those rows hold nothing but the old toolbar and are safe to
-            # clear before the new region is installed. A terminal that shrank instead pushed
-            # the old band off the bottom, so there is nothing left to clear.
-            self._terminal.erase_rows(previous.usable_rows + 1, previous.physical_rows)
+        elif geometry.physical_size != previous.physical_size:
+            # A resize. The terminal may have reset its margins or kept the old ones; either
+            # way the old region no longer describes the screen, so start from full-screen
+            # margins -- which is also what making room needs, so that an index at the bottom
+            # scrolls the whole screen rather than an obsolete region.
+            self._terminal.release_region()
+            if geometry.physical_rows > previous.physical_rows:
+                # The terminal grew, so the rows the old band occupied are now inside the
+                # screen and still hold its stale text. They never scrolled -- the band sits
+                # outside the scroll region -- so they hold nothing but the old toolbar and
+                # are safe to clear before the new region is installed.
+                self._terminal.erase_rows(previous.usable_rows + 1, previous.physical_rows)
+            # A terminal that shrank may have left the cursor, and the output on its row, in
+            # the rows the new band will take. Making room scrolls that output up into the
+            # usable region and moves the cursor with it, column intact, before the band is
+            # installed over those rows and painted.
+            self._terminal.make_room_for_region(geometry)
         self._terminal.install_region(geometry)
         self._geometry = geometry
         if self._adapter is None:

tests/test_reserved_terminal.py

@@ -34,6 +34,23 @@ def restore_cursor(self) -> None:
         finally:
             self.margins = margins
 
+    def resize(self, lines: int | None = None, columns: int | None = None) -> None:
+        """Shrink by clipping the bottom while the cursor stays on screen.
+
+        pyte clips from the top, inside the scroll margins, which drops the cursor's own
+        line. xterm and VTE keep the cursor's line visible: with the cursor above the new
+        bottom they clip the rows below it, which is the case these tests exercise. The
+        band's old row goes with those rows, as it does on a real terminal.
+        """
+        lines = lines or self.lines
+        if lines < self.lines and self.cursor.y < lines:
+            for y in range(lines, self.lines):
+                self.buffer.pop(y, None)
+            self.lines = lines
+            self.dirty.update(range(lines))
+            self.set_margins()
+        super().resize(lines=lines, columns=columns)
+
 
 class EmulatedTerminal(io.StringIO):
     """Parse output and answer CPR where the cursor actually is when the query arrives."""
@@ -336,6 +353,32 @@ def test_partial_output_survives_a_resize(self, terminal_harness) -> None:
             assert terminal.screen.display[0].startswith("PARTIALEND")
             assert terminal.screen.display[-1].startswith("STATUS")
 
+    def test_partial_output_on_a_row_the_shrunk_band_takes_moves_up_with_its_cursor(self, terminal_harness) -> None:
+        """Shrinking can leave the cursor's row inside the new band. The output there and the
+        cursor move up into the usable region, column intact, before the band is painted."""
+        harness, terminal = terminal_harness
+        with harness.app._reserved_toolbar_context(), harness.app._command_toolbar_context():
+            ui = harness.app._command_toolbar.app
+            harness.app.stdout.write("out\n" * 11 + "PARTIAL")
+            harness.app.stdout.flush()
+            assert (terminal.screen.cursor.x, terminal.screen.cursor.y + 1) == (len("PARTIAL"), 12)
+            resize(harness, terminal, 12, 80)
+            ui.loop.call_soon_threadsafe(ui._on_resize)
+            assert wait_for(lambda: terminal.screen.margins == pyte.screens.Margins(0, 10))
+            assert wait_for(lambda: terminal.screen.display[-1].startswith("STATUS"))
+            # Row 12 is the band now; the line and its cursor were scrolled up to row 11.
+            assert (terminal.screen.cursor.x, terminal.screen.cursor.y + 1) == (len("PARTIAL"), 11)
+            assert terminal.screen.display[10].startswith("PARTIAL")
+            harness.app.stdout.write("END\n")
+            harness.app.stdout.flush()
+            # The newline at the bottom of the usable region scrolls it, so the finished line
+            # sits one row up; it must be complete, and nothing may have landed in the band.
+            usable = terminal.screen.display[:-1]
+            assert any(row.startswith("PARTIALEND") for row in usable)
+            assert terminal.screen.display[-1].startswith("STATUS")
+            assert "END" not in terminal.screen.display[-1]
+            assert sum(row.startswith("STATUS") for row in terminal.screen.display) == 1
+
     def test_partial_output_survives_the_command_display_shutdown(self, terminal_harness) -> None:
         """Leaving the command context stops the empty display, whose shutdown must not erase
         the command output still on the line."""

tests/test_terminal_display.py

@@ -298,9 +298,10 @@ def test_reconfigure_installs_the_region_for_the_new_height(self) -> None:
         screen.rows = 40
         stream.truncate(0), stream.seek(0)
         assert display.reconfigure()
-        # Growing brings the old band's row back inside the screen, so its stale toolbar is
-        # erased before the new region is installed.
-        assert stream.getvalue() == "\x1b7\x1b[24;1H\x1b[2K\x1b8\x1b7\x1b[1;39r\x1b8"
+        # A resize starts from full-screen margins, erases the old band's row -- growing has
+        # brought it back inside the screen with its stale toolbar -- makes room for the new
+        # band, and installs the new region.
+        assert stream.getvalue() == "\x1b7\x1b[r\x1b8\x1b7\x1b[24;1H\x1b[2K\x1b8\x1bD\x1b[1A\x1b7\x1b[1;39r\x1b8"
 
     def test_a_width_change_alone_is_still_a_new_generation(self) -> None:
         """Toolbar height is measured against the width, so a rewrap can change the reservation."""