Module: TUI::Formatting

Included in:
Decorators::BaseDecorator, Screens::Chat
Defined in:
lib/tui/formatting.rb

Overview

Shared formatting helpers for timestamps and token counts. Used by both the Chat screen and client-side decorators to avoid duplicating display logic.

Instance Method Summary collapse

Instance Method Details

#format_ns_timestamp(ns) ⇒ String

Converts nanosecond-precision timestamp to human-readable HH:MM:SS.

Parameters:

  • ns (Integer, nil) —

    nanosecond timestamp

Returns:

  • (String) —

    formatted time, or “–:–:–” when nil



46
47
48
49
50
 
# File 'lib/tui/formatting.rb', line 46

def format_ns_timestamp(ns)
  return "--:--:--" unless ns

  Time.at(ns / 1_000_000_000.0).strftime("%H:%M:%S")
end

#format_token_label(tokens, estimated) ⇒ String

Formats a token count for display, with tilde prefix for estimates.

Parameters:

  • tokens (Integer, nil) —

    token count

  • estimated (Boolean) —

    whether the count is an estimate

Returns:

  • (String) —

    formatted label, e.g. “[42 tok]” or “[~28 tok]”



14
15
16
17
18
19
 
# File 'lib/tui/formatting.rb', line 14

def format_token_label(tokens, estimated)
  return "" unless tokens

  label = estimated ? "~#{tokens}" : tokens.to_s
  "[#{label} tok]"
end

#preserve_indentation(text) ⇒ String

Replaces leading ASCII spaces with non-breaking spaces (u00a0). Ratatui’s Paragraph widget with wrap:true trims regular leading spaces; NBSP preserves visual indentation in wrapped text.

Parameters:

  • text (String) —

    text that may contain leading spaces

Returns:

  • (String) —

    text with leading spaces replaced by NBSP



57
58
59
 
# File 'lib/tui/formatting.rb', line 57

def preserve_indentation(text)
  text.gsub(/^( +)/) { "\u00a0" * _1.length }
end

#token_count_color(tokens) ⇒ String, Integer

Returns a semantic color for token count display. Visually flags expensive messages so runaway tool calls or bloated responses jump out immediately in debug mode.

Thresholds (empirically tuned from real agent sessions):

< 1k  → muted   (routine, ignorable)
< 3k  → text    (normal)
< 10k → warning (notable)
< 20k → 208/orange (expensive)
≥ 20k → error   (alarm — likely runaway)

Parameters:

  • tokens (Integer) —

    token count

Returns:

  • (String, Integer) —

    named color or 256-color index



34
35
36
37
38
39
40
41
 
# File 'lib/tui/formatting.rb', line 34

def token_count_color(tokens)
  return Settings.theme_color_muted if tokens < 1_000
  return Settings.theme_color_text if tokens < 3_000
  return Settings.theme_color_warning if tokens < 10_000
  return Settings.theme_color_expensive if tokens < 20_000

  Settings.theme_color_error
end