feat(tui): animate spinner — wave verb, 3 dots, ↑/↓ token counters

Make the chat-spinner line come alive during model activity:

  ▛  Elucidating ●○○  ↑ 1.2k ↓ 0.3k  (1.4s)  (Press ESC to stop)

- braille_spinner.go: add SetWave(true) so the verb label is colored
  per character from hawkRandomPalette, with the color phase shifted
  by Tick() so the bright peak sweeps across the word. In wave mode
  three trailing dots (○/●) ride after the verb; one is highlighted
  in hawk orange and cycles 0→1→2 each tick, like a typing indicator.
- chat_model.go: add per-turn turnInputTokens/turnOutputTokens fields
  and a usageUpdateMsg{usage *engine.StreamUsage} message.
- chat.go: forward 'usage' stream events to the TUI (was a no-op for
  stream-json print mode only) and reset the per-turn counters each
  time the spinner starts (Enter pressed, queued message, slash loop).
- chat_view.go: append a renderTokenCounters(input, output) segment
  to the spinner line. Uses ↑ (soft blue) for input and ↓ (soft
  amber) for output, formatted via formatModelTableContext. Hidden
  until the first usage event lands so it doesn't pop in empty.
- braille_spinner_test.go: TestHawkRandomSolidLabel now opts out
  of wave mode; new TestHawkWaveLabel_MultipleColorsPerChar and
  TestHawkWaveAnimatedDots_PresentInFrame lock the new behavior in.

Author: Patel230

cmd/braille_spinner.go

@@ -3,6 +3,7 @@ package cmd
 import (
 	"fmt"
 	"math/rand"
+	"strings"
 	"sync"
 	"time"
 )
@@ -97,6 +98,8 @@ type BrailleSpinner struct {
 	text       string
 	glyphColor [3]int
 	labelColor [3]int
+	wave       bool // when true, label is colored as a moving wave
+	dots       int  // 0..2 — position of the highlighted dot in the trailing animation
 	running    bool
 	stopCh     chan struct{}
 }
@@ -138,21 +141,82 @@ func (s *BrailleSpinner) SetLabel(text string) {
 	}
 }
 
+// SetWave enables or disables color-wave animation on the label. When on,
+// each character in the label is colored from a rotating slice of the
+// hawk palette, producing a visible wave that moves with each tick.
+func (s *BrailleSpinner) SetWave(on bool) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.wave = on
+}
+
 func (s *BrailleSpinner) renderGlyphLocked(glyph string) string {
 	if s.style == SpinnerHawk {
 		return colorHawkRGB(s.glyphColor, glyph)
 	}
 	return colorSpinnerGlyph(glyph)
 }
 
+// renderWaveLabel colors each character of text with a per-position color
+// drawn from hawkRandomPalette, shifted by the current frame so the
+// bright peak slides across the word.
+func (s *BrailleSpinner) renderWaveLabelLocked(text string) string {
+	if text == "" {
+		return ""
+	}
+	const reset = "\033[0m"
+	var b strings.Builder
+	palette := len(hawkRandomPalette)
+	for i, r := range text {
+		c := hawkRandomPalette[(i*3+s.frame)%palette]
+		fmt.Fprintf(&b, "\033[38;2;%d;%d;%dm%c", c[0], c[1], c[2], r)
+	}
+	b.WriteString(reset)
+	return b.String()
+}
+
+// renderAnimatedDots returns three dots where one is filled and the others
+// are dim, cycling through positions 0..2 with each tick. Used after the
+// verb to show that work is ongoing.
+func (s *BrailleSpinner) renderAnimatedDotsLocked() string {
+	const reset = "\033[0m"
+	dim := "\033[2m"
+	// Bright dot uses hawk orange so it pops against the muted dots.
+	const peakR, peakG, peakB = 255, 94, 14 // matches hawkColor
+	highlightIdx := s.dots % 3
+	var b strings.Builder
+	for i := 0; i < 3; i++ {
+		glyph := "○"
+		if i == highlightIdx {
+			glyph = "●"
+		}
+		if i == highlightIdx {
+			fmt.Fprintf(&b, "\033[38;2;%d;%d;%dm%s", peakR, peakG, peakB, glyph)
+		} else {
+			fmt.Fprintf(&b, "%s%s", dim, glyph)
+		}
+	}
+	b.WriteString(reset)
+	return b.String()
+}
+
 func (s *BrailleSpinner) renderLabelLocked() string {
 	if s.text == "" {
 		return ""
 	}
-	if s.style == SpinnerHawk {
-		return colorHawkRGB(s.labelColor, s.text)
+	var rendered string
+	if s.wave {
+		rendered = s.renderWaveLabelLocked(s.text)
+	} else if s.style == SpinnerHawk {
+		rendered = colorHawkRGB(s.labelColor, s.text)
+	} else {
+		rendered = colorSpinnerGlyph(s.text)
+	}
+	// Trailing animated dots ride with every Hawk spinner in wave mode.
+	if s.wave {
+		rendered += " " + s.renderAnimatedDotsLocked()
 	}
-	return colorSpinnerGlyph(s.text)
+	return rendered
 }
 
 // Frame returns the current rendered frame (spinner + label).
@@ -172,6 +236,7 @@ func (s *BrailleSpinner) Frame() string {
 func (s *BrailleSpinner) Tick() string {
 	s.mu.Lock()
 	s.frame++
+	s.dots = (s.dots + 1) % 3
 	if s.style == SpinnerHawk {
 		s.refreshGlyphColorLocked()
 	}

cmd/braille_spinner_test.go

@@ -122,13 +122,50 @@ func absInt(n int) int {
 
 func TestHawkRandomSolidLabel(t *testing.T) {
 	s := NewBrailleSpinner(SpinnerHawk, "Crafting")
+	// Default mode: solid color label (no wave).
+	s.SetWave(false)
 	f := s.Frame()
-	// entire label should be one color — no reset mid-word for multi-char shimmer
+	// Solid label has at most two reset codes: one for glyph, one for label.
 	if strings.Count(f, "\033[0m") > 2 {
 		t.Errorf("expected solid label color, got mixed resets: %q", f)
 	}
 }
 
+func TestHawkWaveLabel_MultipleColorsPerChar(t *testing.T) {
+	s := NewBrailleSpinner(SpinnerHawk, "Crafting")
+	s.SetWave(true)
+	f := s.Frame()
+	// Wave mode: each character of the verb gets its own foreground color,
+	// so we expect N color codes for the N-char verb plus resets.
+	if strings.Count(f, "\033[38;2;") < len("Crafting") {
+		t.Errorf("expected per-character colors in wave mode, got %q", f)
+	}
+	// Wave frames must change as the spinner ticks (color phase shifts).
+	f0 := f
+	s.Tick()
+	s.Tick()
+	if s.Frame() == f0 {
+		t.Error("expected wave frame to change across ticks")
+	}
+}
+
+func TestHawkWaveAnimatedDots_PresentInFrame(t *testing.T) {
+	s := NewBrailleSpinner(SpinnerHawk, "Crafting")
+	s.SetWave(true)
+	f := s.Frame()
+	// Three dots (○ or ●) ride after the verb in wave mode.
+	dots := strings.Count(f, "○") + strings.Count(f, "●")
+	if dots != 3 {
+		t.Errorf("expected 3 trailing dots in wave mode, got %d in %q", dots, f)
+	}
+	// Tick advances the highlighted dot position.
+	idxBefore := s.dots
+	s.Tick()
+	if s.dots == idxBefore {
+		t.Error("expected dot phase to advance on tick")
+	}
+}
+
 func TestColorHawkRGB(t *testing.T) {
 	got := colorHawkRGB([3]int{255, 94, 14}, "Hi")
 	if strings.Contains(got, "\033[2m") {

cmd/chat.go

@@ -286,6 +286,7 @@ func newChatModel(ref *progRef, systemPrompt string, settings hawkconfig.Setting
 	m.modeManager = shellmode.NewModeManager()
 	m.modeManager.LoadPersistedMode()
 	m.brailleSpinner = NewBrailleSpinner(SpinnerHawk, "")
+	m.brailleSpinner.SetWave(true)
 	m.brailleSpinner.SetLabel(m.spinnerVerb)
 
 	// Initialize BMAD/Aeon features
@@ -852,6 +853,8 @@ func (m chatModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 			m.viewDirty = true
 			m.spinnerVerb = spinnerVerbs[rand.Intn(len(spinnerVerbs))]
 			m.brailleSpinner.SetLabel(m.spinnerVerb)
+			m.turnInputTokens = 0
+			m.turnOutputTokens = 0
 			m.partial.Reset()
 			m.startStream()
 			return m, nil
@@ -978,6 +981,13 @@ func (m chatModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 		m.input.SetValue("")
 		return m, nil
 
+	case usageUpdateMsg:
+		if msg.usage != nil {
+			m.turnInputTokens += msg.usage.PromptTokens
+			m.turnOutputTokens += msg.usage.CompletionTokens
+			m.viewDirty = true
+		}
+
 	case streamDoneMsg:
 		m.flushPartialDirty()
 		if m.partial.Len() > 0 {
@@ -1008,6 +1018,8 @@ func (m chatModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 			m.viewDirty = true
 			m.spinnerVerb = spinnerVerbs[rand.Intn(len(spinnerVerbs))]
 			m.brailleSpinner.SetLabel(m.spinnerVerb)
+			m.turnInputTokens = 0
+			m.turnOutputTokens = 0
 			m.partial.Reset()
 			m.startStream()
 		}
@@ -1202,8 +1214,11 @@ func runChat() error {
 				case "tool_result":
 					p.Send(toolResultMsg{name: ev.ToolName, content: ev.Content})
 				case "usage":
-					// Usage events are only emitted in stream-json print mode
-					// TUI mode ignores them since cost is tracked separately
+					// Forward usage events to TUI so the spinner line can show
+					// running ↑/↓ token counts for the current turn.
+					if ev.Usage != nil {
+						p.Send(usageUpdateMsg{usage: ev.Usage})
+					}
 				case "error":
 					p.Send(streamErrMsg{err: fmt.Errorf("%s", ev.Content)})
 					return

cmd/chat_model.go

@@ -74,6 +74,7 @@ type (
 	streamErrMsg       struct{ err error }
 	blinkTickMsg       struct{}
 	spinnerVerbTickMsg struct{}
+	usageUpdateMsg     struct{ usage *engine.StreamUsage }
 )
 
 type (
@@ -163,7 +164,11 @@ type chatModel struct {
 	configPendingOllamaURL     string
 	pluginRuntime              *plugin.Runtime
 	spinnerVerb                string
-	lastCtrlC                  time.Time
+	// Per-turn token counters shown next to the spinner (↑ input, ↓ output).
+	// Reset each time the user submits a message; updated by usageUpdateMsg.
+	turnInputTokens  int
+	turnOutputTokens int
+	lastCtrlC        time.Time
 	history                    []string
 	historyIdx                 int
 	historyDraft               string // unsent text before navigating history

cmd/chat_view.go

@@ -365,14 +365,16 @@ func (m *chatModel) updateViewportContent() {
 			chatContent.WriteString(hawkC + "⛬ " + rst + renderMarkdown(partial, viewWidth-3))
 			chatContent.WriteString("\n\n")
 		} else {
-			// Hawk QuadBlock spinner: random color glyph + verb label
+			// Hawk QuadBlock spinner: animated glyph + color-waved verb label
+			// + trailing 3-dot typing indicator + live ↑/↓ token counters.
 			spinnerLine := m.brailleSpinner.Frame()
 			if !m.toolStartTime.IsZero() {
 				if elapsed := time.Since(m.toolStartTime); elapsed > 2*time.Second {
 					spinnerLine += fmt.Sprintf(" (%.1fs)", elapsed.Seconds())
 				}
 			}
-			spinnerLine += " " + dimStyle.Render("(Press ESC to stop)")
+			spinnerLine += "  " + renderTokenCounters(m.turnInputTokens, m.turnOutputTokens)
+			spinnerLine += "  " + dimStyle.Render("(Press ESC to stop)")
 			chatContent.WriteString(spinnerLine + "\n\n")
 		}
 	}
@@ -592,3 +594,20 @@ func renderReflectionBox(reflection string, width int) string {
 
 	return border.Render(strings.TrimRight(b.String(), "\n"))
 }
+
+// renderTokenCounters formats the live per-turn token counters that ride
+// next to the spinner. Uses ↑ for input (prompt) and ↓ for output
+// (completion) tokens, formatted via formatModelTableContext (e.g. "1.2k",
+// "262k", "1.5m"). Both halves are muted until at least one event has
+// arrived; on first usage update the input figure lands first.
+func renderTokenCounters(inputTokens, outputTokens int) string {
+	if inputTokens == 0 && outputTokens == 0 {
+		return ""
+	}
+	upStyle := lipgloss.NewStyle().Foreground(lipgloss.Color("#7FB3D5"))   // soft blue
+	downStyle := lipgloss.NewStyle().Foreground(lipgloss.Color("#F5B041")) // soft amber
+	sep := dimStyle.Render(" ")
+	up := upStyle.Render("↑ " + formatModelTableContext(inputTokens))
+	down := downStyle.Render("↓ " + formatModelTableContext(outputTokens))
+	return up + sep + down
+}