Fix flickering screen for most Terminals (#164)

frame() correctly implements DEC 2026 synchronized output, which allows
for "clear screen" sequences to be used while redrawing the screen
without flicker.

However, two issues prevent it from working.  First, the clear sequence
is *outside of the sync frame*.  Second, when moved within the frame,
the write() method detects ``x1b[2J`` and auto triggers a buffer flush,
bypassing the intended synchronization.

Finally, terminals that do not support DEC 2026 will always flicker with
clear sequence at every frame. But to me, it seems to me that the clear
sequence is not needed during this kind of draw, as each line is written
with explicit cursor positioning, please review!

I suggest also to include HOME to ensure (0,0) position before and after
clear, as some terminals can have indeterminate cursor position.

Author: jquast

pytermgui/ansi_interface.py

@@ -116,7 +116,7 @@ def clear(what: str = "screen") -> None:
     commands = {
         "eos": "\x1b[0J",
         "bos": "\x1b[1J",
-        "screen": "\x1b[2J",
+        "screen": "\x1b[H\x1b[2J",
         "eol": "\x1b[0K",
         "bol": "\x1b[1K",
         "line": "\x1b[2K",

pytermgui/term.py

@@ -358,7 +358,7 @@ def _update_size(self, *_: Any) -> None:
         self._call_listener(self.RESIZE, self.size)
 
         # Wipe the screen in case anything got messed up
-        self.write("\x1b[2J")
+        self.write("\x1b[H\x1b[2J")
 
     @property
     def width(self) -> int:
@@ -454,15 +454,15 @@ def frame(self) -> Generator[StringIO, None, None]:
         buffer = StringIO()
 
         try:
-            with self.no_record():
-                self.write("\x1b[?2026h")
+            # Write directly to stream to avoid write()'s auto-clear behavior
+            self._stream.write("\x1b[?2026h")
             yield buffer
 
         finally:
-            self.write(buffer.getvalue())
-            with self.no_record():
-                self.write("\x1b[?2026l")
-            self.flush()
+            # Write buffer directly to stream - bypasses write()'s \x1b[2J detection
+            self._stream.write(buffer.getvalue())
+            self._stream.write("\x1b[?2026l")
+            self._stream.flush()
 
     @staticmethod
     def isatty() -> bool:
@@ -532,6 +532,7 @@ def _slice(line: str, maximum: int) -> str:
 
             return sliced
 
+        # Truncate pending buffer on clear (may help on Windows)
         if "\x1b[2J" in data:
             self.clear_stream()
 
@@ -565,7 +566,11 @@ def _slice(line: str, maximum: int) -> str:
             self._stream.flush()
 
     def clear_stream(self) -> None:
-        """Clears (truncates) the terminal's stream."""
+        """Clears the terminal screen.
+
+        Attempts to truncate any buffered stream data (may work on Windows),
+        then moves cursor to home position and clears the entire screen.
+        """
 
         try:
             self._stream.truncate(0)
@@ -574,7 +579,7 @@ def clear_stream(self) -> None:
             if error.errno != errno.EINVAL and os.name != "nt":
                 raise
 
-        self._stream.write("\x1b[2J")
+        self._stream.write("\x1b[H\x1b[2J")
 
     def print(
         self,

pytermgui/window_manager/compositor.py

@@ -255,7 +255,6 @@ def draw(self, force: bool = False) -> None:
         if not force and self._previous == lines:
             return
 
-        self.terminal.clear_stream()
         with self.terminal.frame() as frame:
             frame_write = frame.write