Use a global animation coordinator for animation ticks

All spinners and general animations animate off the same global tick. Reduces cpu load considerably (> 5x) when multiple spinners are active (e.g. parallel tool calls) etc. since we avoid a barage of ticks propagating through the event loop.

Also keeps animations in sync throughout the app for a more stable appearance

Signed-off-by: Christopher Petito <chrisjpetito@gmail.com>

Author: krissetto

pkg/tui/animation/coordinator.go

@@ -0,0 +1,97 @@
+// Package animation provides centralized animation tick management for the TUI.
+// All animated components (spinners, fades, etc.) share a single tick stream
+// to avoid tick storms and ensure synchronized animations.
+//
+// Thread safety: All exported functions are safe for concurrent use, though the
+// typical usage pattern is single-threaded via Bubble Tea's Update loop.
+package animation
+
+import (
+	"sync"
+	"time"
+
+	tea "charm.land/bubbletea/v2"
+)
+
+// TickMsg is broadcast to all animated components on each animation frame.
+// Components should handle this message to update their animation state.
+type TickMsg struct {
+	Frame int
+}
+
+// Coordinator manages a single tick stream for all animations.
+// It tracks active animations and only generates ticks when at least one is active.
+type Coordinator struct {
+	// mu guards all fields. While Bubble Tea's Update loop is single-threaded,
+	// the mutex protects against accidental misuse from Cmd goroutines and
+	// ensures StartTickIfFirst is atomic (no race between check and register).
+	mu     sync.Mutex
+	frame  int
+	active int32
+}
+
+// globalCoordinator is the singleton coordinator instance.
+var globalCoordinator = &Coordinator{}
+
+// Register increments the active animation count.
+// Call this when an animation starts.
+func Register() {
+	globalCoordinator.mu.Lock()
+	globalCoordinator.active++
+	globalCoordinator.mu.Unlock()
+}
+
+// Unregister decrements the active animation count.
+// Call this when an animation stops.
+func Unregister() {
+	globalCoordinator.mu.Lock()
+	if globalCoordinator.active > 0 {
+		globalCoordinator.active--
+	}
+	globalCoordinator.mu.Unlock()
+}
+
+// HasActive returns true if any animations are currently active.
+func HasActive() bool {
+	globalCoordinator.mu.Lock()
+	active := globalCoordinator.active > 0
+	globalCoordinator.mu.Unlock()
+	return active
+}
+
+// StartTick starts the global animation tick if any animations are active.
+// Call this after processing a TickMsg to continue the tick stream.
+func StartTick() tea.Cmd {
+	globalCoordinator.mu.Lock()
+	defer globalCoordinator.mu.Unlock()
+	if globalCoordinator.active <= 0 {
+		return nil
+	}
+	return globalCoordinator.tickLocked()
+}
+
+// StartTickIfFirst registers an animation and starts the tick if this is the first.
+// This is atomic: no race between checking and registering.
+// Returns the tick command if the tick stream was started, nil otherwise.
+func StartTickIfFirst() tea.Cmd {
+	globalCoordinator.mu.Lock()
+	defer globalCoordinator.mu.Unlock()
+	wasEmpty := globalCoordinator.active == 0
+	globalCoordinator.active++
+	if wasEmpty {
+		return globalCoordinator.tickLocked()
+	}
+	return nil
+}
+
+// tickLocked returns a tick command. Must be called with mu held.
+// 14 FPS - smooth enough for most animations without being too CPU-intensive.
+func (c *Coordinator) tickLocked() tea.Cmd {
+	return tea.Tick(time.Second/14, func(time.Time) tea.Msg {
+		c.mu.Lock()
+		c.frame++
+		frame := c.frame
+		c.mu.Unlock()
+		return TickMsg{Frame: frame}
+	})
+}

pkg/tui/components/message/message.go

@@ -52,7 +52,7 @@ func New(msg, previous *types.Message) *messageModel {
 // Init initializes the message view
 func (mv *messageModel) Init() tea.Cmd {
 	if mv.message.Type == types.MessageTypeSpinner || mv.message.Type == types.MessageTypeLoading {
-		return mv.spinner.Tick()
+		return mv.spinner.Init()
 	}
 	return nil
 }

pkg/tui/components/messages/messages.go

@@ -17,6 +17,7 @@ import (
 	"github.com/docker/cagent/pkg/session"
 	"github.com/docker/cagent/pkg/tools"
 	"github.com/docker/cagent/pkg/tools/builtin"
+	"github.com/docker/cagent/pkg/tui/animation"
 	"github.com/docker/cagent/pkg/tui/components/message"
 	"github.com/docker/cagent/pkg/tui/components/reasoningblock"
 	"github.com/docker/cagent/pkg/tui/components/scrollbar"
@@ -189,6 +190,14 @@ func (m *model) Update(msg tea.Msg) (layout.Model, tea.Cmd) {
 	case reasoningblock.BlockMsg:
 		return m.forwardToReasoningBlock(msg.GetBlockID(), msg)
 
+	case animation.TickMsg:
+		// Invalidate render cache if there's animated content that needs redrawing.
+		// This ensures fades, spinners, etc. actually update visually on each tick.
+		if m.hasAnimatedContent() {
+			m.renderDirty = true
+		}
+		// Fall through to forward tick to all views
+
 	case tea.KeyPressMsg:
 		return m.handleKeyPress(msg)
 	}
@@ -1313,3 +1322,32 @@ func (m *model) handleScrollbarUpdate(msg tea.Msg) (layout.Model, tea.Cmd) {
 	m.scrollOffset = m.scrollbar.GetScrollOffset()
 	return m, cmd
 }
+
+// hasAnimatedContent returns true if the message list contains content that
+// requires tick-driven updates (spinners, fades, etc.). Used to decide whether
+// to invalidate the render cache on animation ticks.
+func (m *model) hasAnimatedContent() bool {
+	for i, msg := range m.messages {
+		switch msg.Type {
+		case types.MessageTypeSpinner, types.MessageTypeLoading:
+			// Spinner/loading messages always need ticks
+			return true
+		case types.MessageTypeToolCall:
+			// Tool calls with pending/running status have spinners
+			if msg.ToolStatus == types.ToolStatusPending ||
+				msg.ToolStatus == types.ToolStatusRunning {
+				return true
+			}
+		case types.MessageTypeAssistantReasoningBlock:
+			// Check if reasoning block needs tick updates
+			if i < len(m.views) {
+				if block, ok := m.views[i].(*reasoningblock.Model); ok {
+					if block.NeedsTick() {
+						return true
+					}
+				}
+			}
+		}
+	}
+	return false
+}