Skip to content

perf(tui): repaint sidebar only when its rendered content changes - #870

Closed
leonsong09 wants to merge 1 commit into
lsdefine:mainfrom
leonsong09:pr/tui-sidebar-content-refresh
Closed

leonsong09 wants to merge 1 commit into
lsdefine:mainfrom
leonsong09:pr/tui-sidebar-content-refresh

Conversation

@leonsong09

@leonsong09 leonsong09 commented Nov 12, 2026 •

Copy link
Copy Markdown

What

_refresh_sidebar() in frontends/tuiapp_v2.py now repaints only when the sidebar's visible content actually changes, instead of on every call.

A sidebar row is fully determined by (sid, name, status, last user message, last summary). This PR computes a cheap signature of exactly those fields and compares it against the signature of the last painted frame; _paint_sidebar() runs only when it differs.

This is not a bug fix — the sidebar already updates promptly today. It is purely about not doing that work when nothing changed.

Why

_flush_stream_renders() batches streamed output every 50 ms and calls _refresh_sidebar() whenever the batch caused a render — i.e. 20 times per second while a reply streams. Each call:

  1. rebuilds the whole Rich table, and
  2. walks each session's LLM history backwards running a regex to recover the last user question and the last <summary>.

During streaming neither of those can change (history is only appended when a turn completes), so all of it is wasted — and the cost grows with conversation length.

Measured on render_sidebar() alone (4 sessions, ties excluded, best-of-N):

case per call at 20 Hz
last message has <summary> (backward scan hits immediately) 0.12 ms 2.4 ms/s
1500 turns / 3001 messages, no <summary> in history 9.43 ms 188.6 ms/s

The 0.12 ms row is the lucky path — the backward scan finds a summary in the first message it looks at. Once a session has no <summary> anywhere (older histories, sessions written by another client, history whose summaries were trimmed), every repaint rescans the entire history: ~19% of one core, continuously, on the UI thread, while streaming.

render_sidebar() only — Textual's own layout/render cost on top of that is not included.

After the change, the same 20 Hz path costs 0.008 ms per call (4 sessions × 1500 turns, signature only, no table build, no regex) — 0.16 ms/s instead of 188.6 ms/s, ~1180× less.

Behaviour

Verified through the real display-queue entry point (_consume_display_queue → _on_stream(done=True)) in a Textual run_test app:

done event → sidebar repaint : < 0.5 ms, exactly 1 paint
status                       : running → idle reflected
streaming, 51 refresh calls  : 0 paints

So: nothing while a reply streams, immediately when the turn ends / a message is added / a status flips.

Compatibility

  • _refresh_sidebar(force: bool = False) — the parameter is optional; all 8 existing call sites are unchanged.
  • No new dependency, no API change, UI output is byte-identical for the same content.
  • _sidebar_last_user / _sidebar_last_summary reuse the previous frame's result when the underlying history object, its length and its last message are unchanged, so even the signature check avoids repeated regex work.

Tests

frontends/tests/test_tuiapp_v2_sidebar_refresh.py (4 tests):

  • unchanged content → repeated _refresh_sidebar() calls produce no repaint
  • Q/S change (history touched) → exactly one repaint, then quiet again
  • status flip → repaint
  • force=True → always repaints

pytest frontends/tests/test_tuiapp_v2_sidebar_refresh.py → 4 passed.

Scope

frontends/tuiapp_v2.py (+68/−1) and one new test file. No other files touched.


Happy to drop this if you'd rather keep the sidebar path as simple as it is — it's a cpu/abstraction tradeoff, not a correctness argument.

`_refresh_sidebar()` is called from `_flush_stream_renders()` on every 50ms
paint batch during a stream, so a busy session rebuilds the session table —
and re-derives each session's Q/S previews by walking and regexing the LLM
history — 20x/s, even though none of it changes while tokens are arriving.

Gate the repaint on a signature of what `render_sidebar()` actually draws
(session id, name, status, Q/S previews):

* streaming: the history is only appended at turn boundaries, so the signature
  is stable and the 20x/s calls collapse into a tuple comparison;
* task completion (running -> idle), a new prompt or a fresh summary flips the
  signature and repaints on that frame — no timer, no polling;
* Q/S derivation is memoised per session on (history identity, length, last
  message) so the preview text is not re-scanned on every call.

`force=True` is kept for callers that know the view must be rebuilt
(switch/rename/rewind/theme).

Measured on a 1500-turn session with no <summary> in history (4 sessions):
9.4ms per repaint before, ~0 after (only the signature compare runs).

Co-Authored-By: GenericAgent <bot@gaagent.ai>
@leonsong09

Copy link
Copy Markdown
Author

superseded by #881 — see #880 / #881.

Folded into #881, unchanged. It is the second commit there (+242/-1 worth of sidebar signature + test).

Closing to keep one open diff per change.

@leonsong09 leonsong09 closed this Nov 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant