Fix _pyrepl rendering bugs and harden refresh pipeline

- Fix cleared_lines using viewport-relative indices instead of absolute
  coordinates in both unix_console and windows_console (crashes in tall
  mode when viewport is scrolled)
- Fix _build_source_lines guard failing for single-line buffers on the
  reuse_full cache path (phantom blank prompt row)
- Add assertion in reuse_full path to catch buffer mutations without
  invalidation
- Extract _compute_lxy() helper to deduplicate cursor position logic
  and replace buf[::-1].index() with str.rindex()
- Give RefreshCache fields proper defaults instead of field(init=False)
- Add assertion and docstring to overlay _compose() method
- Remove dead WrappedRow.line_end_offset field
- Add docstring to RefreshCache.get_cached_location()
- Add explanatory comments for combining-char diff extension and
  build_body_fragments dual-loop optimization
- Use str.replace() instead of list comprehension for \x1a substitution

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: pablogsal

Lib/_pyrepl/content.py

@@ -59,6 +59,7 @@ def build_body_fragments(
     colors: list[ColorSpan] | None,
     start_index: int,
 ) -> tuple[ContentFragment, ...]:
+    # Two separate loops to avoid the THEME() call in the common uncolored path.
     if colors is None:
         return tuple(
             ContentFragment(

Lib/_pyrepl/layout.py

@@ -102,7 +102,6 @@ class WrappedRow:
     suffix: str = ""
     suffix_width: int = 0
     buffer_advance: int = 0
-    line_end_offset: int = 0
 
 
 @dataclass(frozen=True, slots=True)
@@ -132,7 +131,6 @@ def layout_content_lines(
             wrapped_rows.append(
                 WrappedRow(
                     fragments=(leading,),
-                    line_end_offset=offset,
                 )
             )
             layout_rows.append(LayoutRow(0, (), buffer_advance=0))
@@ -152,7 +150,6 @@ def layout_content_lines(
                     fragments=body,
                     layout_widths=body_widths,
                     buffer_advance=len(body) + newline_advance,
-                    line_end_offset=offset,
                 )
             )
             layout_rows.append(
@@ -205,7 +202,6 @@ def layout_content_lines(
                     suffix=suffix,
                     suffix_width=suffix_width,
                     buffer_advance=buffer_advance,
-                    line_end_offset=offset,
                 )
             )
             layout_rows.append(

Lib/_pyrepl/reader.py

@@ -309,10 +309,10 @@ class Reader:
     @dataclass
     class RefreshCache:
         render_lines: list[RenderLine] = field(default_factory=list)
-        layout_rows: list[LayoutRow] = field(init=False)
+        layout_rows: list[LayoutRow] = field(default_factory=list)
         line_end_offsets: list[int] = field(default_factory=list)
-        pos: int = field(init=False)
-        dimensions: Dimensions = field(init=False)
+        pos: int = 0
+        dimensions: Dimensions = (0, 0)
 
         def update_cache(self,
                          reader: Reader,
@@ -338,6 +338,13 @@ def get_cached_location(
             *,
             reuse_full: bool = False,
         ) -> tuple[int, int]:
+            """Return (buffer_offset, num_reusable_lines) for incremental refresh.
+
+            Three paths:
+            - reuse_full (overlay/message-only): reuse all cached lines.
+            - buffer_from_pos=None (full rebuild): rewind to common cursor pos.
+            - explicit buffer_from_pos: reuse lines before that position.
+            """
             if reuse_full:
                 if self.line_end_offsets:
                     last_offset = self.line_end_offsets[-1]
@@ -409,6 +416,9 @@ def calc_screen(self) -> RenderedScreen:
                     self,
                     reuse_full=True,
                 )
+                assert not self.last_refresh_cache.line_end_offsets or (
+                    self.last_refresh_cache.line_end_offsets[-1] >= len(self.buffer)
+                ), "Buffer modified without invalidate_buffer() call"
             else:
                 offset, num_common_lines = self.last_refresh_cache.get_cached_location(
                     self,
@@ -435,14 +445,7 @@ def calc_screen(self) -> RenderedScreen:
         if not source_lines:
             # reuse_full path: _build_source_lines didn't run,
             # so lxy wasn't updated. Derive it from the buffer.
-            buf = self.buffer[:self.pos]
-            lineno = buf.count("\n")
-            if lineno:
-                last_nl = len(buf) - 1 - buf[::-1].index("\n")
-                col = self.pos - last_nl - 1
-            else:
-                col = self.pos
-            self.lxy = col, lineno
+            self.lxy = self._compute_lxy()
         self.last_refresh_cache.update_cache(
             self,
             base_render_lines,
@@ -461,12 +464,22 @@ def _buffer_refresh_from_pos(self) -> int:
             return buffer_from_pos
         return 0
 
+    def _compute_lxy(self) -> CursorXY:
+        """Derive logical cursor (col, lineno) from the buffer and pos."""
+        text = "".join(self.buffer[:self.pos])
+        lineno = text.count("\n")
+        if lineno:
+            col = self.pos - text.rindex("\n") - 1
+        else:
+            col = self.pos
+        return col, lineno
+
     def _build_source_lines(
         self,
         offset: int,
         first_lineno: int,
     ) -> tuple[SourceLine, ...]:
-        if offset == len(self.buffer) and first_lineno > 0:
+        if offset == len(self.buffer) and offset > 0:
             return ()
 
         pos = self.pos - offset

Lib/_pyrepl/render.py

@@ -137,6 +137,11 @@ def from_rendered_text(cls, text: str) -> Self:
 
 @dataclass(frozen=True, slots=True)
 class ScreenOverlay:
+    """An overlay that replaces or inserts lines at a screen position.
+
+    If insert is True, lines are spliced in (shifting content down);
+    if False (default), lines replace existing content at y.
+    """
     y: int
     lines: tuple[RenderLine, ...]
     insert: bool = False
@@ -153,13 +158,18 @@ def __post_init__(self) -> None:
         object.__setattr__(self, "composed_lines", self._compose())
 
     def _compose(self) -> tuple[RenderLine, ...]:
+        """Apply overlays in tuple order; inserts shift subsequent positions."""
         if not self.overlays:
             return self.lines
 
         lines = list(self.lines)
         y_offset = 0
         for overlay in self.overlays:
             adjusted_y = overlay.y + y_offset
+            assert adjusted_y >= 0, (
+                f"Overlay y={overlay.y} with offset={y_offset} is negative; "
+                "overlays must be sorted by ascending y"
+            )
             if overlay.insert:
                 lines[adjusted_y:adjusted_y] = overlay.lines
                 y_offset += len(overlay.lines)
@@ -308,6 +318,8 @@ def diff_render_lines(old: RenderLine, new: RenderLine) -> LineDiff | None:
         old_suffix -= 1
         new_suffix -= 1
 
+    # Extend diff range to include trailing zero-width combining characters,
+    # so we never render a combining char without its base character.
     while old_suffix < len(old.cells) and old.cells[old_suffix].width == 0:
         old_suffix += 1
     while new_suffix < len(new.cells) and new.cells[new_suffix].width == 0:

Lib/_pyrepl/unix_console.py

@@ -346,7 +346,7 @@ def __plan_refresh(
             if update is not None:
                 line_updates.append(update)
 
-        cleared_lines = tuple(range(len(newscr), len(oldscr)))
+        cleared_lines = tuple(range(offset + len(newscr), offset + len(oldscr)))
         console_rendered_screen = RenderedScreen(tuple(next_lines), c_xy)
         trace(
             "unix.refresh plan grow={grow} tall={tall} offset={offset} "

Lib/_pyrepl/windows_console.py

@@ -248,7 +248,7 @@ def __plan_refresh(
             if update is not None:
                 line_updates.append(update)
 
-        cleared_lines = tuple(range(len(newscr), len(oldscr)))
+        cleared_lines = tuple(range(offset + len(newscr), offset + len(oldscr)))
         console_rendered_screen = RenderedScreen(tuple(next_lines), c_xy)
         trace(
             "windows.refresh plan grow={grow} offset={offset} scroll_lines={scroll_lines} "
@@ -446,7 +446,7 @@ def _disable_bracketed_paste(self) -> None:
 
     def __write(self, text: str) -> None:
         if "\x1a" in text:
-            text = ''.join(["^Z" if x == '\x1a' else x for x in text])
+            text = text.replace("\x1a", "^Z")
 
         if self.out is not None:
             self.out.write(text.encode(self.encoding, "replace"))