perf(tui): cache renders and calm the streaming refresh loop (#79)

* perf(tui): cache renders and calm the streaming refresh loop

Spinner ticks no longer rebuild the transcript every frame; live step
clocks coalesce at 250ms. Finished steps and finalized message blocks
cache their layout, streaming replies glamour on the 80ms flush, and
cleared-home sessions resume on 1–3.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(tui): invalidate step cache on agent focus and resize live replies

Step block cache now keys on agentSel and clears when tab-cycling chips.
Resize re-glamours open reply segments so mid-stream cards reflow at the
new width instead of keeping stale wrapped markdown.

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: jkyberneees

AGENTS.md

@@ -139,7 +139,11 @@ feat(tui): compact tool steps with Ctrl+E details toggle
   connection per run.
 - Streaming renders are coalesced into one flush per 80ms for
   performance; batching new redraw paths the same way keeps the TUI
-  responsive.
+  responsive. Live reply segments glamour-render on that flush (not only
+  at turn end). The spinner animates the status line only — transcript
+  rebuilds for live step clocks coalesce at 250ms (`tailClockFlushMsg`).
+  Finished message blocks and done tool steps cache their render output;
+  invalidate per message/step on expand, not the whole prefix.
 - The slash-completion popup holds key capture while open; typed keys
   must keep flowing to the input. Route keys through the popup first,
   then fall through to normal input handling.

internal/tui/cache.go

@@ -0,0 +1,83 @@
+package tui
+
+// msgBlockCache holds one finalized transcript message's rendered block.
+// Ref line numbers are relative to the block start (offset at assembly time).
+type msgBlockCache struct {
+	block string
+	refs  []stepRef
+	width int
+	valid bool
+}
+
+func (m *Model) ensureMsgBlocks() {
+	if len(m.msgBlocks) >= len(m.msgs) {
+		return
+	}
+	m.msgBlocks = append(m.msgBlocks, make([]msgBlockCache, len(m.msgs)-len(m.msgBlocks))...)
+}
+
+// invalidateMsgBlock drops one message's cached block (step expand, agent
+// focus, collapse — without rebuilding siblings).
+func (m *Model) invalidateMsgBlock(i int) {
+	if i < 0 || i >= len(m.msgBlocks) {
+		return
+	}
+	m.msgBlocks[i].valid = false
+}
+
+// invalidateAllMsgBlocks drops every cached message block (resize, expand-all,
+// transcript wholesale replace).
+func (m *Model) invalidateAllMsgBlocks() {
+	for i := range m.msgBlocks {
+		m.msgBlocks[i].valid = false
+	}
+	m.convCount = -1
+}
+
+func (m *Model) resetMsgBlocks() {
+	m.msgBlocks = nil
+	m.convCount = -1
+}
+
+// msgBlockAt returns a cached or freshly rendered block for message i and
+// step refs offset to lineOffset in the full transcript.
+func (m *Model) msgBlockAt(i, lineOffset int) (string, []stepRef) {
+	m.ensureMsgBlocks()
+	bc := &m.msgBlocks[i]
+	if !bc.valid || bc.width != m.vp.Width {
+		s, r := m.renderMessage(m.msgs[i], i, 0)
+		bc.block = m.clampLines(s)
+		bc.refs = r
+		bc.width = m.vp.Width
+		bc.valid = true
+	}
+	return bc.block, offsetStepRefs(bc.refs, lineOffset)
+}
+
+func clearStepBlockCache(s *step) {
+	s.blockCache = ""
+	s.blockRefs = nil
+	s.blockWidth = 0
+}
+
+func stepBlockCacheValid(s step, st *step, m *Model, expanded bool) bool {
+	if !s.done || s.blockCache == "" || st == nil {
+		return false
+	}
+	if st.name != s.name || st.done != s.done || st.result != s.result || st.expanded != s.expanded {
+		return false
+	}
+	if st.agentSel != s.agentSel {
+		return false
+	}
+	if s.blockWidth != m.vp.Width {
+		return false
+	}
+	if s.blockExpanded != expanded {
+		return false
+	}
+	if s.blockExpandAll != m.expandAll {
+		return false
+	}
+	return true
+}

internal/tui/cache_test.go

@@ -0,0 +1,96 @@
+package tui
+
+import (
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/BackendStack21/bodek/internal/client"
+	"github.com/charmbracelet/bubbles/spinner"
+)
+
+func TestSpinnerTickDoesNotRebuildPrefixDuringStream(t *testing.T) {
+	m := newTestModel()
+	streamingTurn(m)
+	m.refresh()
+	if m.convCount != 1 {
+		t.Fatalf("precondition convCount=%d, want 1", m.convCount)
+	}
+	prefix := m.convPrefix
+	m.handleEvent(client.Event{Type: "token", Content: "more"})
+	m.Update(spinner.TickMsg{})
+	if m.convPrefix != prefix {
+		t.Error("spinner tick rebuilt the finalized prefix during streaming")
+	}
+}
+
+func TestTailClockRefreshUpdatesLiveStep(t *testing.T) {
+	m := newTestModel()
+	streamingTurn(m)
+	m.handleEvent(client.Event{Type: "tool_call", Name: "read_file", Data: `{"path":"x.go"}`})
+	if i := m.cur(); i >= 0 && len(m.msgs[i].steps) > 0 {
+		m.msgs[i].steps[0].started = time.Now().Add(-500 * time.Millisecond)
+	}
+	m.refresh()
+	before := plain(m.vp.View())
+
+	if i := m.cur(); i >= 0 && len(m.msgs[i].steps) > 0 {
+		m.msgs[i].steps[0].started = time.Now().Add(-1500 * time.Millisecond)
+	}
+	m.tailClockPending = true
+	m.tailClockSeq = 1
+	m.Update(tailClockFlushMsg{seq: 1})
+	after := plain(m.vp.View())
+	if before == after {
+		t.Errorf("tail clock flush should refresh live step duration:\nbefore=%q\nafter=%q", before, after)
+	}
+}
+
+func TestStepBlockCacheReusesFinishedStep(t *testing.T) {
+	m := newTestModel()
+	m.msgs = append(m.msgs, message{role: roleAsst, streaming: false, steps: []step{
+		{name: "shell", arg: "go test ./...", done: true, result: strings.Repeat("line\n", 40)},
+	}})
+	out1, _, _ := m.renderStep(m.msgs[0].steps[0], false, 0, 0, 0)
+	out2, _, _ := m.renderStep(m.msgs[0].steps[0], false, 0, 0, 0)
+	if out1 != out2 {
+		t.Error("finished step should reuse block cache")
+	}
+	if m.msgs[0].steps[0].blockCache == "" {
+		t.Error("renderStep should populate block cache for finished steps")
+	}
+}
+
+func TestHomeResumeKey(t *testing.T) {
+	m := newTestModel()
+	m.homePrompt = "cleared"
+	m.homeSess = []client.Session{{ID: "sess-abc", Task: "fix login", Turns: 2, UpdatedAt: time.Now()}}
+	if cmd := m.handleHomeResumeKey("1"); cmd == nil {
+		t.Fatal("1 should resume the first recent session")
+	}
+	m.msgs = append(m.msgs, message{role: roleUser, content: "busy transcript"})
+	if cmd := m.handleHomeResumeKey("1"); cmd != nil {
+		t.Error("home resume must not fire while transcript has messages")
+	}
+}
+
+func TestMsgBlockPartialInvalidate(t *testing.T) {
+	m := newTestModel()
+	m.msgs = append(m.msgs,
+		message{role: roleUser, content: "q1"},
+		message{role: roleAsst, content: "a1", rendered: m.render("a1"), steps: []step{
+			{name: "read", done: true, result: "ok"},
+		}},
+		message{role: roleUser, content: "q2"},
+		message{role: roleAsst, content: "a2", rendered: m.render("a2")},
+	)
+	m.refresh()
+	block3 := m.msgBlocks[3].block
+	m.toggleStep(1, 0)
+	if len(m.msgBlocks) > 1 && m.msgBlocks[1].valid {
+		t.Error("toggle should invalidate message 1 block")
+	}
+	if len(m.msgBlocks) < 4 || !m.msgBlocks[3].valid || m.msgBlocks[3].block != block3 {
+		t.Error("sibling message block should stay cached")
+	}
+}

internal/tui/chrome.go

@@ -320,14 +320,36 @@ func (m *Model) sessionHome() string {
 		if task == "" {
 			task = "(untitled)"
 		}
-		b.WriteString(th.statsDim.Render(fmt.Sprintf("↩ %s · %d turns · %s",
-			truncate(task, max(w-24, 12)), s.Turns, ago(s.UpdatedAt))) + "\n")
+		b.WriteString(th.statsDim.Render(fmt.Sprintf("%d ↩ %s · %d turns · %s",
+			i+1, truncate(task, max(w-24, 12)), s.Turns, ago(s.UpdatedAt))) + "\n")
 	}
 	b.WriteString("\n")
-	b.WriteString(th.tipKey.Render("type a task") + "  " + th.tipText.Render("⏎ sends · ^K everything · /verbosity dials detail") + "\n")
+	b.WriteString(th.tipKey.Render("type a task") + "  " + th.tipText.Render("1–3 resume · ⏎ sends · ^K everything · /verbosity dials detail") + "\n")
 	return lipgloss.NewStyle().Width(w).PaddingLeft(2).Render(strings.TrimRight(b.String(), "\n"))
 }
 
+// handleHomeResumeKey resumes a recent session from the cleared home card.
+func (m *Model) handleHomeResumeKey(key string) tea.Cmd {
+	if len(m.msgs) > 0 || m.busy || m.panel != panelNone {
+		return nil
+	}
+	var slot int
+	switch key {
+	case "1":
+		slot = 0
+	case "2":
+		slot = 1
+	case "3":
+		slot = 2
+	default:
+		return nil
+	}
+	if slot >= len(m.homeSess) || slot >= 3 {
+		return nil
+	}
+	return m.resumeSession(m.homeSess[slot].ID)
+}
+
 func captureHome(m *Model) {
 	if p := lastUserPrompt(m.msgs); p != "" {
 		m.homePrompt = p

internal/tui/commands_e2e_test.go

@@ -57,7 +57,7 @@ func callCmd(cmd tea.Cmd) tea.Msg {
 
 func timeReArm(msg tea.Msg) bool {
 	switch msg.(type) {
-	case spinner.TickMsg, heartbeatMsg, runsTickMsg, noticeExpireMsg, renderFlushMsg:
+	case spinner.TickMsg, heartbeatMsg, runsTickMsg, noticeExpireMsg, renderFlushMsg, tailClockFlushMsg:
 		return true
 	}
 	return false

internal/tui/events.go

@@ -151,7 +151,8 @@ func (m *Model) handleEvent(ev client.Event) (tea.Model, tea.Cmd) {
 						// unfold it once so the diagnosis is on screen
 						// without a hunt (the user can re-collapse it).
 						steps[j].expanded = true
-						m.convCount = -1
+						clearStepBlockCache(&steps[j])
+						m.invalidateMsgBlock(i)
 					}
 					if steps[j].subagent {
 						steps[j].resultCard = parseAgentResult(ev.Data)
@@ -824,6 +825,7 @@ func markCancel(msg *message) {
 func (m *Model) finalize() {
 	if i := m.cur(); i >= 0 {
 		m.closeTurn(&m.msgs[i])
+		m.invalidateMsgBlock(i)
 	}
 	m.curIdx = -1
 	m.wakeArmed = false // the window closed with the turn

internal/tui/home_dashboard_test.go

@@ -20,7 +20,7 @@ func TestHomeShowsRecentSessions(t *testing.T) {
 		{ID: "s2", Task: "refactor the parser", Turns: 9, UpdatedAt: time.Now().Add(-2 * time.Hour)},
 	}
 	out := plain(m.sessionHome())
-	for _, want := range []string{"fix the login bug", "refactor the parser", "4 turns", "^K"} {
+	for _, want := range []string{"fix the login bug", "refactor the parser", "4 turns", "1 ↩", "1–3 resume"} {
 		if !strings.Contains(out, want) {
 			t.Errorf("session home missing %q:\n%s", want, out)
 		}

internal/tui/input.go

@@ -522,15 +522,20 @@ func (m *Model) dismissChrome() (bool, tea.Cmd) {
 	}
 	if m.expandAll {
 		m.expandAll = false
-		m.convCount = -1
+		m.invalidateAllMsgBlocks()
+		for i := range m.msgs {
+			for j := range m.msgs[i].steps {
+				clearStepBlockCache(&m.msgs[i].steps[j])
+			}
+		}
 		m.refresh()
 		return true, nil
 	}
 	for i := len(m.msgs) - 1; i >= 0; i-- {
 		for j := len(m.msgs[i].items) - 1; j >= 0; j-- {
 			if m.msgs[i].items[j].thinking && m.msgs[i].items[j].open {
 				m.msgs[i].items[j].open = false
-				m.convCount = -1
+				m.invalidateMsgBlock(i)
 				m.refresh()
 				return true, nil
 			}
@@ -539,7 +544,8 @@ func (m *Model) dismissChrome() (bool, tea.Cmd) {
 	for i := len(m.msgs) - 1; i >= 0; i-- {
 		for j := len(m.msgs[i].steps) - 1; j >= 0; j-- {
 			if m.msgs[i].steps[j].clearAgentFocus() {
-				m.convCount = -1
+				clearStepBlockCache(&m.msgs[i].steps[j])
+				m.invalidateMsgBlock(i)
 				m.refresh()
 				return true, nil
 			}
@@ -549,15 +555,16 @@ func (m *Model) dismissChrome() (bool, tea.Cmd) {
 		for j := len(m.msgs[i].steps) - 1; j >= 0; j-- {
 			if m.msgs[i].steps[j].expanded {
 				m.msgs[i].steps[j].expanded = false
-				m.convCount = -1
+				clearStepBlockCache(&m.msgs[i].steps[j])
+				m.invalidateMsgBlock(i)
 				m.refresh()
 				return true, nil
 			}
 		}
 	}
 	if n := len(m.msgs); n > 0 && isEphemeralCard(m.msgs[n-1]) {
 		m.msgs = m.msgs[:n-1]
-		m.convCount = -1
+		m.resetMsgBlocks()
 		m.refresh()
 		return true, nil
 	}