"""Write an already-composed frame straight to the terminal, one changed row at a time. MeshTerm composes every frame itself: :func:`~meshterm.ui.tui.frame.compose_base` returns a finished ANSI string, exactly one line per terminal row, already sliced to the viewport and already folded to the platform's glyph set. prompt_toolkit's own renderer then takes that string and does a full round trip with it — parses the ANSI back into style/text fragments, writes every one of the ~1400 cells into a fresh grid of ``Char`` objects, diffs that grid against the previous frame's grid, and re-emits ANSI for the cells that moved. That round trip is the single largest cost in a keystroke on the PicoCalc, and it is paid in full on *every* paint — a measured 70-125 ms whether the frame changed by one row, by all of them, or not at all (the 2 s header tick recomposes an identical frame and still pays it). Since we already know the frame as rows of text, the same pixels can be reached by comparing this frame's rows against the last frame's rows and rewriting only the ones that differ: ~0.1 ms, and a smaller write besides. The bypass is deliberately narrow. It runs only when the frame is a plain full-screen composition — one base screen, no floating dialog and no busy overlay — because those are laid out by prompt_toolkit's float containers rather than by us, and compositing them here would mean re-implementing that placement. Anything else falls straight through to the stock renderer, which stays the authority: :meth:`FastRenderer.render` is an accelerator for the common case, never a second implementation of the whole layout engine. Two details make the row diff safe rather than merely fast: * **A row is rewritten whole, from column 0.** The terminal's own cursor advance re-lays the line, so a glyph it draws narrower than we measured cannot leave the rest of the row shifted — the same guarantee :meth:`~meshterm.ui.tui.session.TuiSession._emit` relies on, reached here for free rather than by a scrub pass. * **Each row is prefixed with a reset and followed by an erase-to-end-of-line**, so no style leaks in from the row above and a row that got shorter leaves no tail behind. """ from __future__ import annotations import os from typing import Callable, Optional from prompt_toolkit.renderer import Renderer def enabled() -> bool: """Whether the direct row writer is active. On by default — it is 2-3x on every navigation keystroke and its output is verified byte-identical against the stock renderer by reading the console back. Set ``MESHTERM_FASTRENDER=0`` to fall back to prompt_toolkit's renderer, which is the escape hatch if a terminal ever disagrees. """ return os.environ.get("MESHTERM_FASTRENDER", "1") != "0" class FastRenderer(Renderer): """A :class:`~prompt_toolkit.renderer.Renderer` that short-circuits simple frames. Args: frame_source: Returns the composed full-screen frame as one ANSI string (rows joined by newlines), or ``None`` when this paint is not a plain base frame and must go through prompt_toolkit's layout instead. """ def __init__(self, *args, frame_source: Callable[[], Optional[str]], **kwargs) -> None: super().__init__(*args, **kwargs) self._frame_source = frame_source self._prev_rows: Optional[list[str]] = None self._prev_size: Optional[tuple[int, int]] = None #: Paints answered here vs handed to the stock renderer — read by the bench. self.fast_paints = 0 self.slow_paints = 0 def reset(self, _scroll: bool = False, leave_alternate_screen: bool = True) -> None: """Forget the last frame along with prompt_toolkit's own render state.""" self._prev_rows = None super().reset(_scroll=_scroll, leave_alternate_screen=leave_alternate_screen) def erase(self, leave_alternate_screen: bool = True) -> None: """The screen is being cleared out from under us — the next paint must be full.""" self._prev_rows = None super().erase(leave_alternate_screen=leave_alternate_screen) def render(self, app, layout, is_done: bool = False) -> None: # noqa: ANN001 """Paint the frame, taking the row-diff path when this frame is a plain one.""" text = None if is_done else self._frame_source() if text is None: # A dialog, the busy overlay, or the closing paint: prompt_toolkit lays those # out, so it must also own the diff — its grid is the only record of what is # on screen, and it is about to be rebuilt from scratch anyway. self._prev_rows = None self.slow_paints += 1 super().render(app, layout, is_done) return output = self.output pending = False # whether the terminal setup below has queued anything to flush if self.full_screen and not self._in_alternate_screen: self._in_alternate_screen = True output.enter_alternate_screen() pending = True if not self._bracketed_paste_enabled: output.enable_bracketed_paste() self._bracketed_paste_enabled = True pending = True if not self._cursor_key_mode_reset: output.reset_cursor_key_mode() self._cursor_key_mode_reset = True pending = True size = output.get_size() dims = (size.rows, size.columns) rows = text.split("\n")[: size.rows] # A resize invalidates both records of the screen: ours and prompt_toolkit's. full = self._prev_rows is None or self._prev_size != dims if not full and not pending and rows == self._prev_rows: # The app repaints on a timer to keep the header's pulse moving, and most of # those frames come back identical. Writing nothing at all is not merely cheaper # than writing the rows again — it leaves the panel's damage region empty, so # the display never flushes and the SPI bus stays quiet. self._last_size = size self.fast_paints += 1 return if full: self._last_screen = None output.hide_cursor() output.reset_attributes() output.erase_screen() output.cursor_goto(0, 0) write = output.write_raw prev = self._prev_rows last = -2 for i, row in enumerate(rows): if not full and i < len(prev) and prev[i] == row: continue # Stepping down a row with CRLF returns the terminal to a true column 0 # whatever happened on the row above, and costs three bytes less than a # cursor address; only a real jump pays for one. write("\r\n" if i == last + 1 else f"\x1b[{i + 1};1H") # Erase *before* drawing, never after. A row that fills the terminal exactly # leaves the cursor in the last column with wrap pending, and an erase-to-end # there wipes the very character just written (the row's last cell went # missing on the PicoCalc's 53-column console). Clearing first also drops the # tail of a row that got shorter, which is what the erase was for. write("\x1b[0m\x1b[K") write(row) last = i # Park the cursor out of the text. The app hides it, but a terminal that ignores # that should not leave it blinking in the middle of a row. write(f"\x1b[{len(rows)};1H") output.flush() self._prev_rows = rows self._prev_size = dims self._last_size = size # prompt_toolkit's grid no longer describes the screen — if a later paint falls # back to it, it must redraw everything rather than diff against a stale record. self._last_screen = None self.fast_paints += 1