Skip to content

perf(tui): stop re-arranging and re-scanning per frame (supersedes #870 #871) - #881

Open
leonsong09 wants to merge 2 commits into
lsdefine:mainfrom
leonsong09:perf/tui-render-umbrella
Open

leonsong09 wants to merge 2 commits into
lsdefine:mainfrom
leonsong09:perf/tui-render-umbrella

Conversation

@leonsong09

Copy link
Copy Markdown

Why one PR

Both changes sit in frontends/tuiapp_v2.py and both are about the same thing: the TUI does work per frame that cannot have changed since the last frame. They touch adjacent code, so reviewing them together is cheaper than reviewing them apart — and they were measured against the same 20 Hz streaming load.

Merged cleanly, no conflicts. pytest frontends/tests/test_tuiapp_v2_sidebar_refresh.py frontends/tests/test_tuiapp_v2_stream_layout.py -q → 5 passed.

1. Streaming repaints without re-arranging the transcript

Symptom. Long sessions: text arrives in lurches during 🤔 思考中, occasionally a 400 ms+ whole-screen reflow.

Measured with py-spy record 12s on a live process — main thread busy 3.46s of 12s (29%), of which 2.41s (70%) was entirely:

_on_timer_update -> _refresh_layout -> reflow -> _arrange_root -> compositor.add_widget...

Not rendering. Re-layout. ~11.6 times/s.

Cause. Static.update() defaults to layout=True (textual 8.2.5), and the stream renderer calls it every 50 ms:

last_widget.update(Text.from_ansi(display, style=C_FG))     # layout=True
self.query_one("#messages", VerticalScroll).refresh()       # dirties it again

So every token batch marks the whole message area layout-dirty, and the next frame arranges everything — cost linear in mounted messages, which is why it degrades with conversation length.

Fix.

  1. _rendered_height() / _update_text(): compute how many lines the new content occupies at the current width and request layout only when the height changes. Appending within a line — the common streaming case — becomes a repaint. Wrapping and new paragraphs still grow the widget, so no line gets clipped.
  2. spinner and turn-end notes go through the same helper (fixed single line, never layouts).
  3. drop the redundant #messages.refresh() — update() already dirties.
  4. batch window 50 ms → STREAM_PAINT_INTERVAL (default 100 ms, GA_TUI_PAINT_MS overrides).

Measured after — headless, real TUI widgets, 30 turns, 20 Hz stream for 2s:

reflows main-thread time
before 37 466 ms
after 3 18 ms

Spinner unit case: 20 → 3. Global update(layout=False) counter: 26 → 0.

2. Sidebar repaints only when its content changes

_flush_stream_renders() calls _refresh_sidebar() on every batch that produced a render — 20 times/s while a reply streams. Each call rebuilds the whole Rich table and walks each session's LLM history backwards running a regex to recover the last user question and the last <summary>.

During streaming neither can change: history is only appended when a turn completes. So all of it is wasted, and the cost grows with conversation length. On render_sidebar() alone (4 sessions, 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

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

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

Tests

  • test_tuiapp_v2_stream_layout.py pins both directions: growth within a line must not request layout; content that grows a new line must grow the widget (height == 9, last line line 08 visible) — guards against clipping.
  • test_tuiapp_v2_sidebar_refresh.py pins that a signature-identical refresh paints zero times, and that each of the five fields, changed alone, triggers exactly one paint.

frontends/tests full run: 273 passed, 3 pre-existing failures (test_data_backup symlink, test_release_qualification missing file) — unrelated, they fail identically after stashing this branch.

Scope

frontends/tuiapp_v2.py +135/-13, two new test files (342 lines). No agent-loop code, so this lands independently of #873/#872/#869/#876/#879/#874.

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