anima-core 1.3.0 → 1.5.0

data/lib/tui/braille_spinner.rb

@@ -23,7 +23,7 @@ module TUI
   #
   # @example Basic usage
   #   spinner = BrailleSpinner.new
-  #   spinner.state = "llm_generating"
+  #   spinner.state = "awaiting"
   #   char = spinner.tick  # => "⠋" (braille pattern)
   class BrailleSpinner
     # Clockwise traversal of the 8 dots in the braille grid.
@@ -73,8 +73,8 @@ module TUI
     # Ticks per frame for each state — controls animation speed.
     # Higher = slower. At ~15fps render loop: 2 = ~7.5fps, 4 = ~3.75fps.
     SPEED = {
-      "llm_generating" => 2,
-      "tool_executing" => 1,
+      "awaiting" => 2,
+      "executing" => 1,
       "interrupting" => 1
     }.freeze
 
@@ -90,8 +90,8 @@ module TUI
     # Updates the session state driving the animation.
     # Resets frame position on state change for a clean transition.
     #
-    # @param new_state [String] one of "idle", "llm_generating",
-    #   "tool_executing", "interrupting"
+    # @param new_state [String] one of "idle", "awaiting",
+    #   "executing", "interrupting"
     def state=(new_state)
       if @state != new_state
         @frame_index = 0
@@ -143,8 +143,8 @@ module TUI
 
     def frames_for_state
       case @state
-      when "llm_generating" then SNAKE_TRAIL_FRAMES
-      when "tool_executing" then TOOL_FRAMES
+      when "awaiting" then SNAKE_TRAIL_FRAMES
+      when "executing" then TOOL_FRAMES
       when "interrupting" then INTERRUPT_FRAMES
       end
     end

data/lib/tui/cable_client.rb

@@ -2,6 +2,7 @@
 
 require "websocket-client-simple"
 require "json"
+require_relative "settings"
 
 module TUI
   # Action Cable WebSocket client for connecting the TUI to the brain server.
@@ -23,14 +24,6 @@ module TUI
   #   messages = client.drain_messages
   #   client.disconnect
   class CableClient
-    DISCONNECT_TIMEOUT = 2 # seconds to wait for WebSocket thread to finish
-    POLL_INTERVAL = 0.1 # seconds between connection status checks
-    CONNECTION_TIMEOUT = 10 # seconds to wait for the connecting state to advance
-    MAX_RECONNECT_ATTEMPTS = 10
-    BACKOFF_BASE = 1.0 # initial backoff delay in seconds
-    BACKOFF_CAP = 30.0 # maximum backoff delay
-    PING_STALE_THRESHOLD = 6.0 # seconds without ping before connection is stale
-
     # Message types queued for the TUI render loop via @message_queue
     MSG_TYPE_CONNECTION = "connection"
 
@@ -180,7 +173,7 @@ module TUI
         @status = :disconnected
       end
       @ws&.close
-      @ws_thread&.join(DISCONNECT_TIMEOUT)
+      @ws_thread&.join(Settings.connection_disconnect_timeout)
     end
 
     private
@@ -260,13 +253,13 @@ module TUI
       loop do
         break if @status == :disconnected
 
-        if @status == :connecting && (Time.now - connection_start) > CONNECTION_TIMEOUT
+        if @status == :connecting && (Time.now - connection_start) > Settings.connection_timeout
           on_disconnected
           break
         end
 
         check_stale_connection
-        sleep POLL_INTERVAL
+        sleep Settings.connection_poll_interval
       end
     end
 
@@ -276,7 +269,7 @@ module TUI
     def check_stale_connection
       stale = @mutex.synchronize do
         next false unless @last_ping_at && @status == :subscribed
-        (Time.now - @last_ping_at) >= PING_STALE_THRESHOLD
+        (Time.now - @last_ping_at) >= Settings.connection_ping_stale_threshold
       end
 
       on_disconnected if stale
@@ -291,12 +284,12 @@ module TUI
         @reconnect_attempt
       end
 
-      if attempt > MAX_RECONNECT_ATTEMPTS
+      if attempt > Settings.connection_max_reconnect_attempts
         @mutex.synchronize { @status = :disconnected }
         @message_queue << {
           "type" => MSG_TYPE_CONNECTION,
           "status" => STATUS_FAILED,
-          "message" => "Reconnection failed after #{MAX_RECONNECT_ATTEMPTS} attempts"
+          "message" => "Reconnection failed after #{Settings.connection_max_reconnect_attempts} attempts"
         }
         return false
       end
@@ -307,7 +300,7 @@ module TUI
         "type" => MSG_TYPE_CONNECTION,
         "status" => STATUS_RECONNECTING,
         "attempt" => attempt,
-        "max_attempts" => MAX_RECONNECT_ATTEMPTS,
+        "max_attempts" => Settings.connection_max_reconnect_attempts,
         "delay" => delay.round(1)
       }
 
@@ -321,7 +314,7 @@ module TUI
     # @param attempt [Integer] current attempt number (1-based)
     # @return [Float] delay in seconds
     def backoff_delay(attempt)
-      max_delay = [BACKOFF_CAP, BACKOFF_BASE * (2**(attempt - 1))].min
+      max_delay = [Settings.connection_backoff_cap, Settings.connection_backoff_base * (2**(attempt - 1))].min
       rand(0.0..max_delay)
     end
 

data/lib/tui/decorators/base_decorator.rb

@@ -19,6 +19,26 @@ module TUI
     # @example Render a tool call
     #   decorator = TUI::Decorators::BaseDecorator.for(data)
     #   lines = decorator.render(tui)
+    # Shared rendering for file-related tool decorators (read, write, edit).
+    # Extracts the file path from input and displays it in the header line,
+    # making the target file immediately visible — like bash shows its command.
+    module FileCallBehavior
+      def render_call(tui)
+        style = tui.style(fg: effective_color)
+        input_lines = data["input"].to_s.split("\n", -1)
+        path_line = input_lines.first.to_s
+
+        header = build_call_header
+        header = "#{header} #{path_line}" unless path_line.empty?
+        lines = [tui.line(spans: [tui.span(content: header, style: style)])]
+
+        input_lines.drop(1).each do |line|
+          lines << tui.line(spans: [tui.span(content: preserve_indentation("  #{line}"), style: style)])
+        end
+        lines
+      end
+    end
+
     class BaseDecorator
       include Formatting
 
@@ -61,11 +81,11 @@ module TUI
       # @param tui [RatatuiRuby] TUI rendering API
       # @return [Array<RatatuiRuby::Widgets::Line>]
       def render_call(tui)
-        style = tui.style(fg: color)
+        style = tui.style(fg: effective_color)
         header = build_call_header
         lines = [tui.line(spans: [tui.span(content: header, style: style)])]
         data["input"].to_s.split("\n", -1).each do |line|
-          lines << tui.line(spans: [tui.span(content: "  #{line}", style: style)])
+          lines << tui.line(spans: [tui.span(content: preserve_indentation("  #{line}"), style: style)])
         end
         lines
       end
@@ -81,7 +101,7 @@ module TUI
         indicator = (data["success"] == false) ? ERROR_ICON : CHECKMARK
         tool_id = data["tool_use_id"]
         tokens = data["tokens"]
-        style = tui.style(fg: response_color)
+        style = tui.style(fg: effective_response_color)
 
         meta_parts = []
         meta_parts << "[#{tool_id}]" if tool_id
@@ -97,7 +117,7 @@ module TUI
         first_line_spans << tui.span(content: content_lines.first.to_s, style: style)
 
         lines = [tui.line(spans: first_line_spans)]
-        content_lines.drop(1).each { |line| lines << tui.line(spans: [tui.span(content: "    #{line}", style: style)]) }
+        content_lines.drop(1).each { |line| lines << tui.line(spans: [tui.span(content: preserve_indentation("    #{line}"), style: style)]) }
         lines
       end
 
@@ -120,13 +140,34 @@ module TUI
       # visually distinct from conversation messages (user/assistant/thought).
       # @return [String]
       def color
-        "magenta"
+        Settings.theme_color_accent
       end
 
       # Color for tool response content. Subclasses override for tool-specific colors.
       # @return [String]
       def response_color
-        "white"
+        Settings.theme_color_text
+      end
+
+      # @return [Boolean] true when the underlying message is still in the
+      #   pending mailbox (not yet promoted to a {Message}). Drives muted
+      #   styling so in-flight pipeline content reads as distinct from
+      #   committed conversation.
+      def pending?
+        data["status"] == "pending"
+      end
+
+      # Tool-call color, dimmed to the muted theme color while pending so
+      # subclass overrides of {#color} don't have to know about pending state.
+      # @return [String]
+      def effective_color
+        pending? ? Settings.theme_color_muted : color
+      end
+
+      # Tool-response color, dimmed to the muted theme color while pending.
+      # @return [String]
+      def effective_response_color
+        pending? ? Settings.theme_color_muted : response_color
       end
 
       private

data/lib/tui/decorators/bash_decorator.rb

@@ -13,7 +13,7 @@ module TUI
       end
 
       def response_color
-        (data["success"] == false) ? "red" : "green"
+        (data["success"] == false) ? Settings.theme_color_error : Settings.theme_color_success
       end
     end
   end

data/lib/tui/decorators/edit_decorator.rb

@@ -3,9 +3,11 @@
 module TUI
   module Decorators
     # Renders edit_file tool calls and responses.
-    # Calls show the file path with a pencil icon in the unified tool color.
+    # Calls show the file path in the header line for immediate visibility.
     # Responses use the CRUD Update color (light_yellow) to flag modifications.
     class EditDecorator < BaseDecorator
+      include FileCallBehavior
+
       ICON = "\u270F\uFE0F" # pencil
 
       def icon
@@ -13,7 +15,7 @@ module TUI
       end
 
       def response_color
-        "light_yellow"
+        Settings.theme_tool_update_color
       end
     end
   end

data/lib/tui/decorators/read_decorator.rb

@@ -3,9 +3,11 @@
 module TUI
   module Decorators
     # Renders read_file tool calls and responses.
-    # Calls show the file path with a page icon in the unified tool color.
+    # Calls show the file path in the header line for immediate visibility.
     # Responses use the CRUD Read color (light_blue) for informational content.
     class ReadDecorator < BaseDecorator
+      include FileCallBehavior
+
       ICON = "\u{1F4C4}" # page facing up
 
       def icon
@@ -13,7 +15,7 @@ module TUI
       end
 
       def response_color
-        "light_blue"
+        Settings.theme_tool_read_color
       end
     end
   end

data/lib/tui/decorators/think_decorator.rb

@@ -17,7 +17,7 @@ module TUI
       # @param tui [RatatuiRuby] TUI rendering API
       # @return [Array<RatatuiRuby::Widgets::Line>]
       def render_think(tui)
-        style = tui.style(fg: "dark_gray")
+        style = tui.style(fg: Settings.theme_color_muted)
         ts = data["timestamp"]
 
         meta = []
@@ -26,7 +26,7 @@ module TUI
 
         content_lines = data["content"].to_s.split("\n", -1)
         lines = [tui.line(spans: [tui.span(content: "#{header} #{content_lines.first}", style: style)])]
-        content_lines.drop(1).each { |line| lines << tui.line(spans: [tui.span(content: "  #{line}", style: style)]) }
+        content_lines.drop(1).each { |line| lines << tui.line(spans: [tui.span(content: preserve_indentation("  #{line}"), style: style)]) }
         lines
       end
     end

data/lib/tui/decorators/web_get_decorator.rb

@@ -13,7 +13,7 @@ module TUI
       end
 
       def response_color
-        "light_blue"
+        Settings.theme_tool_read_color
       end
     end
   end

data/lib/tui/decorators/write_decorator.rb

@@ -3,9 +3,11 @@
 module TUI
   module Decorators
     # Renders write_file tool calls and responses.
-    # Calls show the file path with a memo icon in the unified tool color.
+    # Calls show the file path in the header line for immediate visibility.
     # Responses use the CRUD Create color (light_green) to signal new content.
     class WriteDecorator < BaseDecorator
+      include FileCallBehavior
+
       ICON = "\u{1F4DD}" # memo
 
       def icon
@@ -13,7 +15,7 @@ module TUI
       end
 
       def response_color
-        "light_green"
+        Settings.theme_tool_create_color
       end
     end
   end

data/lib/tui/flash.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "settings"
+
 module TUI
   # Ephemeral notification system for the TUI, modeled after Rails flash
   # messages. Notifications render as a colored bar at the top of the
@@ -22,18 +24,19 @@ module TUI
   # @example Dismissing
   #   flash.dismiss!
   class Flash
-    AUTO_DISMISS_SECONDS = 20.0
-
-    # Flash area occupies at most 1/3 of the chat pane height.
-    MAX_HEIGHT_FRACTION = 3
-
     Entry = Struct.new(:message, :level, :created_at, keyword_init: true)
 
-    LEVEL_STYLES = {
-      error: {fg: "white", bg: "red", icon: " \u2718 "},
-      warning: {fg: "black", bg: "yellow", icon: " \u26A0 "},
-      info: {fg: "white", bg: "blue", icon: " \u2139 "}
-    }.freeze
+    LEVEL_ICONS = {error: " \u2718 ", warning: " \u26A0 ", info: " \u2139 "}.freeze
+
+    # Builds level styles from current theme settings.
+    # Called per-render so hot-reloaded theme changes take effect immediately.
+    def self.level_styles
+      {
+        error: {fg: Settings.theme_flash_error_fg, bg: Settings.theme_flash_error_bg},
+        warning: {fg: Settings.theme_flash_warning_fg, bg: Settings.theme_flash_warning_bg},
+        info: {fg: Settings.theme_flash_info_fg, bg: Settings.theme_flash_info_bg}
+      }
+    end
 
     def initialize
       @entries = []
@@ -81,7 +84,7 @@ module TUI
       expire!
       return 0 if @entries.empty?
 
-      height = [@entries.size, area.height / MAX_HEIGHT_FRACTION].min
+      height = [@entries.size, area.height / Settings.flash_max_height_fraction].min
 
       flash_area, _ = tui.split(
         area,
@@ -110,7 +113,7 @@ module TUI
 
     def expire!
       now = monotonic_now
-      @entries.reject! { |entry| now - entry.created_at > AUTO_DISMISS_SECONDS }
+      @entries.reject! { |entry| now - entry.created_at > Settings.flash_auto_dismiss_seconds }
     end
 
     def row_rect(area, index, tui)
@@ -120,10 +123,12 @@ module TUI
     end
 
     def render_entry(frame, area, entry, tui)
-      config = LEVEL_STYLES.fetch(entry.level, LEVEL_STYLES[:info])
+      styles = self.class.level_styles
+      config = styles.fetch(entry.level, styles[:info])
+      icon = LEVEL_ICONS.fetch(entry.level, LEVEL_ICONS[:info])
       style = tui.style(fg: config[:fg], bg: config[:bg], modifiers: [:bold])
 
-      text = "#{config[:icon]}#{entry.message} "
+      text = "#{icon}#{entry.message} "
       # Pad to full width so background color fills the entire row
       padded = text.ljust(area.width)
 

data/lib/tui/formatting.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "settings"
+
 module TUI
   # Shared formatting helpers for timestamps and token counts.
   # Used by both the Chat screen and client-side decorators
@@ -21,21 +23,21 @@ module TUI
     # responses jump out immediately in debug mode.
     #
     # Thresholds (empirically tuned from real agent sessions):
-    #   < 1k  → dark_gray  (routine, ignorable)
-    #   < 3k  → white      (normal)
-    #   < 10k → yellow     (notable)
+    #   < 1k  → muted   (routine, ignorable)
+    #   < 3k  → text    (normal)
+    #   < 10k → warning (notable)
     #   < 20k → 208/orange (expensive)
-    #   ≥ 20k → red        (alarm — likely runaway)
+    #   ≥ 20k → error   (alarm — likely runaway)
     #
     # @param tokens [Integer] token count
     # @return [String, Integer] named color or 256-color index
     def token_count_color(tokens)
-      return "dark_gray" if tokens < 1_000
-      return "white" if tokens < 3_000
-      return "yellow" if tokens < 10_000
-      return 208 if tokens < 20_000 # orange (256-color)
+      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
 
-      "red"
+      Settings.theme_color_error
     end
 
     # Converts nanosecond-precision timestamp to human-readable HH:MM:SS.
@@ -46,5 +48,14 @@ module TUI
 
       Time.at(ns / 1_000_000_000.0).strftime("%H:%M:%S")
     end
+
+    # 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.
+    # @param text [String] text that may contain leading spaces
+    # @return [String] text with leading spaces replaced by NBSP
+    def preserve_indentation(text)
+      text.gsub(/^( +)/) { "\u00a0" * _1.length }
+    end
   end
 end

data/lib/tui/input_buffer.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "settings"
+
 module TUI
   # Manages editable text with cursor position tracking.
   # Supports multiline input with newline insertion, cursor navigation
@@ -7,8 +9,6 @@ module TUI
   #
   # Pure logic object with no rendering or framework dependencies.
   class InputBuffer
-    MAX_LENGTH = 10_000
-
     attr_reader :text, :cursor_pos
 
     def initialize
@@ -36,9 +36,9 @@ module TUI
       @text.include?("\n")
     end
 
-    # @return [Boolean] whether the buffer has reached MAX_LENGTH
+    # @return [Boolean] whether the buffer has reached Settings.input_max_length
     def full?
-      @text.length >= MAX_LENGTH
+      @text.length >= Settings.input_max_length
     end
 
     # Ensures cursor stays within valid bounds after external state changes.
@@ -48,9 +48,9 @@ module TUI
     end
 
     # @param char [String] character(s) to insert at cursor
-    # @return [Boolean] true if inserted, false if result would exceed MAX_LENGTH
+    # @return [Boolean] true if inserted, false if result would exceed Settings.input_max_length
     def insert(char)
-      return false if @text.length + char.length > MAX_LENGTH
+      return false if @text.length + char.length > Settings.input_max_length
 
       @text = "#{@text[0...@cursor_pos]}#{char}#{@text[@cursor_pos..]}"
       @cursor_pos += char.length