Repaint: we already composed the frame - stop having it read back

Every paint handed prompt_toolkit a finished ANSI frame and let it parse
that back into fragments, write all ~1400 cells into a fresh Char grid,
diff the grid, and re-emit ANSI. Measured on the PicoCalc that round trip
is 70-125 ms, and it is paid in full 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 the frame is already rows of text, FastRenderer compares this
frame's rows against the last frame's and rewrites only the ones that
differ. Opt-in for now (MESHTERM_FASTRENDER=1) and deliberately narrow:
a floating dialog or the busy overlay is placed by pt's float containers,
so those paints fall straight through to the stock renderer.

The erase has to lead the row, never follow it. A row that exactly fills
53 columns leaves the cursor in the last column with wrap pending, and an
erase-to-end there clears the character just written - the last cell of
every row went missing until the clear moved in front.

Alongside it, three costs that were pure waste on this platform:

  * The redraw was postponed up to max_render_postpone_time before it
    even started - a flat 3 ms on the Lyra, 10 ms on desktop, on every
    key. That default guards a UI whose own output floods it with
    invalidations; here they are keystrokes and a 2 s tick.
  * The splash rendered its body twice per paint - once to measure the
    box, once to fill it - and ran the corner glow ungated, walking every
    line to hand back the identical list on a console with no truecolor
    to blend. compose_dialog had the same ungated glow.
  * A tile's decoded layers were re-read from the SD card on every frame
    (~96 ms each), so panning one dot re-read every tile that had not
    moved. They are held in RAM now, bounded at a viewport plus its ring.

On the device, driven over the real radio: main menu 115 -> 40 ms,
Contacts 155 -> 73 ms, Dashboard 213 -> 117 ms, leaving a screen
375 -> 103 ms. Console readback confirms the frames are byte-identical.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Jean-Pierre MartineauandClaude Fable 5 committed 2026-08-09 01:29:24 -04:00
1 parent 2d18c45917
commit 57386fe879
5 files changed
+335 -7

No files matched your search

+26
View File
@@ -43,6 +43,7 @@ import os
import threading
import urllib.error
import urllib.request
from collections import OrderedDict
from pathlib import Path
from typing import Container, NamedTuple, Optional
@@ -70,6 +71,11 @@ _DEFAULT_MAX_DECODED_BYTES = 64 * 1024 * 1024
#: the directory, which is slow on the SD card the PicoCalc runs from.
_PRUNE_AFTER_BYTES = 8 * 1024 * 1024
#: Decoded tiles held in RAM. A viewport spans at most a handful of tiles, so this covers
#: the view plus the ring a pan or a zoom step reaches into, and little more — the PicoCalc
#: has 100 MB of RAM in total and decoded layers are not small.
_MEMO_TILES = 24
_log = logging.getLogger(__name__)
@@ -136,6 +142,12 @@ class BasemapSource:
# than on disk so the claim expires with the process: a blank tile is cheap to
# re-ask about, and a stale one on disk is a permanent hole in the map.
self._blank: set[tuple[int, int, int]] = set()
# Decoded layers kept in RAM, most-recently-used last. The sidecar already spares
# the protobuf decode, but a marshal load off the SD card is still ~96 ms on the
# PicoCalc — and a map paints its whole viewport's worth of tiles on *every*
# frame, so panning one dot re-read every tile that had not moved. Bounded because
# decoded layers are the fattest thing this class holds.
self._memo: "OrderedDict[tuple[int, int, int], list[Layer]]" = OrderedDict()
# -- metadata ---------------------------------------------------------------
@@ -219,8 +231,13 @@ class BasemapSource:
key = (z, x, y)
if key in self._blank:
return None
hot = self._memo.get(key)
if hot is not None:
self._memo.move_to_end(key)
return hot
ready = self._read_decoded(z, x, y)
if ready is not None:
self._remember(key, ready)
return ready
path = self._tile_path(z, x, y)
cached = self._read_cached(path)
@@ -228,6 +245,7 @@ class BasemapSource:
layers = self._decode(cached, key)
if layers is not None:
self._write_decoded(z, x, y, layers)
self._remember(key, layers)
return layers
# Nothing drawable came out: a zero-byte marker from a build that cached
# network failures, or bytes truncated by a link (or a power cut) mid-write.
@@ -243,8 +261,16 @@ class BasemapSource:
return None
self._write_cached(path, raw)
self._write_decoded(z, x, y, layers)
self._remember(key, layers)
return layers
def _remember(self, key: tuple[int, int, int], layers: list[Layer]) -> None:
"""Hold a decoded tile in RAM, evicting the least recently used past the budget."""
self._memo[key] = layers
self._memo.move_to_end(key)
while len(self._memo) > _MEMO_TILES:
self._memo.popitem(last=False)
# -- the decoded sidecar ----------------------------------------------------
def _read_decoded(self, z: int, x: int, y: int) -> Optional[list[Layer]]:
+145
View File
@@ -0,0 +1,145 @@
"""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.
Off by default while it earns its keep on the device; set ``MESHTERM_FASTRENDER=1``
to turn it on, ``=0`` to force the stock renderer.
"""
return os.environ.get("MESHTERM_FASTRENDER", "") == "1"
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
if self.full_screen and not self._in_alternate_screen:
self._in_alternate_screen = True
output.enter_alternate_screen()
if not self._bracketed_paste_enabled:
output.enable_bracketed_paste()
self._bracketed_paste_enabled = True
if not self._cursor_key_mode_reset:
output.reset_cursor_key_mode()
self._cursor_key_mode_reset = 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 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
+19 -5
View File
@@ -368,7 +368,8 @@ def compose_startup(screen: Screen, cols: int, rows: int) -> str:
# Size the box to its widest real row (probe at a generous width, then measure), never
# wider than the terminal and never narrower than the title/hint it must show.
probe = max(10, min(cols - 6, 100))
measured = max((_ansi_width(line) for line in screen.render_body(probe)), default=10)
probe_lines = screen.render_body(probe)
measured = max((_ansi_width(line) for line in probe_lines), default=10)
# Size to the fullest the footer can get, not this frame's — a screen whose hint grows
# as the highlight moves (a select's per-row "Del remove") reports that width here, so
# the box is reserved for it up front and never widens mid-navigation.
@@ -387,7 +388,11 @@ def compose_startup(screen: Screen, cols: int, rows: int) -> str:
footnote_h = 1 if screen.footnote else 0 # the note sits directly under the logo
# Rows left for the box below the fixed banner block: the panel border is 2 rows.
below = rows - top - banner_h - footnote_h - gap
body_lines = screen.render_body(inner_w)
# The probe render is the answer whenever it was already made at the width we settled
# on — the common case, since a body narrower than the probe *is* what set inner_w.
# The splash repaints on every tick while the device list sits there, and rendering
# the same body twice was a measured third of that paint on the PicoCalc.
body_lines = probe_lines if inner_w == probe else screen.render_body(inner_w)
budget = below - 2
vpad = _breathing_room(len(body_lines), budget)
viewport = max(1, min(len(body_lines), budget - 2 * vpad))
@@ -407,8 +412,14 @@ def compose_startup(screen: Screen, cols: int, rows: int) -> str:
padding=(vpad, 1),
width=inner_w + 4,
)
# Glow before centering, while the box still starts at column 0 of its own lines.
panel_lines = _center(apply_corner_glow(render_lines(panel, inner_w + 4)), cols)
# Glow before centering, while the box still starts at column 0 of its own lines. Gated
# on the platform exactly as compose_base gates it: the pass only ever recolours
# truecolor foregrounds, so on the 16-slot console it walked every line of the splash
# to hand back the identical list, on every tick.
panel_lines = render_lines(panel, inner_w + 4)
if get_platform().effects:
panel_lines = apply_corner_glow(panel_lines)
panel_lines = _center(panel_lines, cols)
# A small muted line (e.g. a copyright notice) sits immediately under the logo, its right
# edge hung off the logo's right edge so the two read as one signed block.
@@ -499,7 +510,10 @@ def compose_dialog(screen: Screen, cols: int, rows: int) -> str:
padding=(vpad, 1),
width=max_w,
)
out = "\n".join(apply_corner_glow(render_lines(panel, max_w)))
dialog_lines = render_lines(panel, max_w)
if get_platform().effects:
dialog_lines = apply_corner_glow(dialog_lines)
out = "\n".join(dialog_lines)
_DIALOG_CACHE[key] = out
if len(_DIALOG_CACHE) > _DIALOG_CACHE_MAX:
_DIALOG_CACHE.popitem(last=False)
+36 -2
View File
@@ -31,7 +31,7 @@ from rich.text import Text
from ...platforms import get_platform
from ...services import modifier_watch
from . import fkeys, frame
from . import fastrender, fkeys, frame
from .overlay import BusyOverlay
from .progress import TuiProgress
from .prompt import (
@@ -1129,7 +1129,7 @@ class TuiSession:
),
],
)
return Application(
app = Application(
layout=Layout(root, focused_element=base_window),
key_bindings=self._key_bindings(),
full_screen=True,
@@ -1137,9 +1137,29 @@ class TuiSession:
# Keeps the live monitor counter in the header ticking. Per-platform, so a host
# where an idle repaint is expensive can breathe more slowly between frames.
refresh_interval=get_platform().tick_s,
# Repaint as soon as the loop is free, rather than spinning the event loop for
# up to 10 ms first. prompt_toolkit's default postpone is there to protect a
# UI whose *own* output floods it with invalidations (its motivating case was
# a terminal multiplexer); here an invalidation is a keystroke or the 2 s
# header tick, so the delay buys nothing and was measured as a flat 3 ms on
# the PicoCalc and 10 ms on desktop, paid on every single key.
max_render_postpone_time=None,
input=self._input,
output=self._resolve_output(),
)
if fastrender.enabled():
# Swap in the row-diff renderer for plain full-screen frames. Built with the
# same arguments Application gave the stock one, so everything except the
# paint itself — CPR, alternate screen, mouse, cursor shape — is unchanged.
app.renderer = fastrender.FastRenderer(
app._merged_style,
app.output,
full_screen=True,
mouse_support=False,
cpr_not_supported_callback=app.cpr_not_supported_callback,
frame_source=self._plain_frame,
)
return app
def _resolve_output(self) -> Any:
"""The output the app renders to — optionally widened to reclaim the last column.
@@ -1310,6 +1330,20 @@ class TuiSession:
frame.compose_base(self._header(cols), base, footer, cols, rows, footer_lane=lane)
)
def _plain_frame(self) -> Optional[str]:
"""The composed full-screen frame, when this paint is one the fast path may take.
Answers ``None`` — meaning "let prompt_toolkit lay this one out" — whenever the
frame is more than a single background screen: a floating dialog or the busy
overlay is placed by pt's float containers, not by us (see
:mod:`~meshterm.ui.tui.fastrender`). Composing the base is not wasted in that
case: the float layers draw *over* it, so pt asks for it a moment later and gets
the memoized composition.
"""
if self._has_float() or self._overlay_visible() or not self._stack:
return None
return self._render_base().value
@staticmethod
def _fkey_lane(active: Screen) -> Optional[Callable[[], Text]]:
"""A deferred F-key lane row for ``active``, or ``None`` on a platform without one.
+109
View File
@@ -16,6 +16,8 @@ import subprocess
import sys
from pathlib import Path
from prompt_toolkit.data_structures import Size
from prompt_toolkit.output import DummyOutput
from rich.text import Text
from meshterm.persistence import db
@@ -237,3 +239,110 @@ def test_spinner_interval_reads_the_active_platform() -> None:
assert spinner_interval() == REGULAR.spinner_tick_s
set_platform(PICOCALC)
assert spinner_interval() == PICOCALC.spinner_tick_s
# --- the direct row-diff renderer ---------------------------------------------------
class _CapturingOutput(DummyOutput):
"""A DummyOutput that records what the renderer wrote, at a fixed console size."""
def __init__(self, rows: int = 26, columns: int = 53) -> None:
super().__init__()
self.written: list[str] = []
self._size = Size(rows=rows, columns=columns)
def get_size(self) -> Size:
return self._size
def write_raw(self, data: str) -> None:
self.written.append(data)
def cursor_goto(self, row: int = 0, column: int = 0) -> None:
self.written.append(f"<goto {row},{column}>")
def erase_screen(self) -> None:
self.written.append("<erase-screen>")
@property
def stream(self) -> str:
return "".join(self.written)
def _fast_renderer(frames: list[str]) -> tuple["FastRenderer", _CapturingOutput]:
"""A FastRenderer fed a scripted sequence of composed frames."""
from prompt_toolkit.styles import Style
from meshterm.ui.tui.fastrender import FastRenderer
out = _CapturingOutput()
pending = list(frames)
renderer = FastRenderer(
Style([]), out, full_screen=True, frame_source=lambda: pending.pop(0)
)
return renderer, out
def test_fastrender_is_off_unless_asked_for(monkeypatch) -> None: # noqa: ANN001
"""The bypass is opt-in: an unset environment leaves prompt_toolkit in charge."""
from meshterm.ui.tui import fastrender
monkeypatch.delenv("MESHTERM_FASTRENDER", raising=False)
assert not fastrender.enabled()
monkeypatch.setenv("MESHTERM_FASTRENDER", "1")
assert fastrender.enabled()
def test_fastrender_rewrites_only_the_rows_that_changed() -> None:
"""The whole point: a keystroke that moves one row must not repaint the screen."""
rows_a = [f"row {i:02d}" for i in range(26)]
rows_b = list(rows_a)
rows_b[7] = "row 07 SELECTED"
renderer, out = _fast_renderer(["\n".join(rows_a), "\n".join(rows_b)])
renderer.render(None, None) # first paint: everything
out.written.clear()
renderer.render(None, None) # second: one row moved
stream = out.stream
assert "row 07 SELECTED" in stream
# Every *other* row's text stayed off the wire.
assert "row 06" not in stream
assert "row 08" not in stream
assert "\x1b[8;1H" in stream # addressed row 8 (1-based) directly
def test_fastrender_erases_before_it_draws_so_a_full_row_keeps_its_last_cell() -> None:
"""Erase-to-end *after* a full-width row wipes the character just written.
A row that exactly fills the console leaves the cursor in the last column with wrap
pending; an erase there clears that cell, and the row's final glyph goes missing (it
did, on the PicoCalc's 53 columns). So the erase has to lead, never follow.
"""
full = "x" * 53
renderer, out = _fast_renderer(["\n".join([full] * 26), "\n".join([full] * 26)])
renderer.render(None, None)
stream = out.stream
assert "\x1b[K" in stream
# In every row the clear precedes that row's text, and no clear trails it.
for chunk in stream.split("\x1b[0m")[1:]:
assert chunk.startswith("\x1b[K"), chunk[:40]
assert not chunk.rstrip().endswith("\x1b[K"), chunk[-40:]
def test_fastrender_hands_dialogs_back_to_prompt_toolkit(monkeypatch) -> None: # noqa: ANN001
"""A ``None`` frame means a float is up, which pt lays out — it must own that paint."""
from prompt_toolkit.renderer import Renderer
from prompt_toolkit.styles import Style
from meshterm.ui.tui.fastrender import FastRenderer
calls: list[bool] = []
monkeypatch.setattr(Renderer, "render", lambda *a, **k: calls.append(True))
renderer = FastRenderer(
Style([]), _CapturingOutput(), full_screen=True, frame_source=lambda: None
)
renderer.render(None, None)
assert calls == [True]
assert renderer.slow_paints == 1
assert renderer.fast_paints == 0