anima-core 1.0.2 → 1.1.1

data/lib/tui/decorators/edit_decorator.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module TUI
+  module Decorators
+    # Renders edit tool calls and responses.
+    # Calls show the file path with a pencil icon.
+    class EditDecorator < BaseDecorator
+      ICON = "\u270F\uFE0F" # pencil
+
+      def icon
+        ICON
+      end
+
+      def color
+        "yellow"
+      end
+    end
+  end
+end

data/lib/tui/decorators/read_decorator.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module TUI
+  module Decorators
+    # Renders read tool calls and responses.
+    # Calls show the file path with a page icon.
+    # Responses show file content in dim text.
+    class ReadDecorator < BaseDecorator
+      ICON = "\u{1F4C4}" # page facing up
+
+      def icon
+        ICON
+      end
+
+      def color
+        "cyan"
+      end
+
+      def response_color
+        "dark_gray"
+      end
+    end
+  end
+end

data/lib/tui/decorators/think_decorator.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module TUI
+  module Decorators
+    # Renders think tool events — the agent's inner reasoning.
+    # "aloud" thoughts use yellow (narration for the user), "inner"
+    # thoughts use dark_gray (dimmed to signal internality).
+    class ThinkDecorator < BaseDecorator
+      THOUGHT_BUBBLE = "\u{1F4AD}" # thought balloon
+
+      def icon
+        THOUGHT_BUBBLE
+      end
+
+      # Think events always dispatch here via BaseDecorator#render.
+      #
+      # @param tui [RatatuiRuby] TUI rendering API
+      # @return [Array<RatatuiRuby::Widgets::Line>]
+      def render_think(tui)
+        aloud = data["visibility"] == "aloud"
+        fg = aloud ? "yellow" : "dark_gray"
+        style = tui.style(fg: fg)
+        ts = data["timestamp"]
+
+        meta = []
+        meta << "[#{format_ns_timestamp(ts)}]" if ts
+        header = meta.empty? ? icon : "#{meta.join(" ")} #{icon}"
+
+        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)]) }
+        lines
+      end
+    end
+  end
+end

data/lib/tui/decorators/web_get_decorator.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module TUI
+  module Decorators
+    # Renders web_get tool calls and responses.
+    # Calls show the URL with a globe icon.
+    class WebGetDecorator < BaseDecorator
+      ICON = "\u{1F310}" # globe with meridians
+
+      def icon
+        ICON
+      end
+
+      def color
+        "blue"
+      end
+    end
+  end
+end

data/lib/tui/decorators/write_decorator.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module TUI
+  module Decorators
+    # Renders write tool calls and responses.
+    # Calls show the file path with a memo icon.
+    class WriteDecorator < BaseDecorator
+      ICON = "\u{1F4DD}" # memo
+
+      def icon
+        ICON
+      end
+
+      def color
+        "yellow"
+      end
+    end
+  end
+end

data/lib/tui/flash.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module TUI
+  # Ephemeral notification system for the TUI, modeled after Rails flash
+  # messages. Notifications render as a colored bar at the top of the
+  # chat pane and auto-dismiss after a configurable timeout or on any
+  # keypress.
+  #
+  # Reusable beyond Bounce Back — useful for connection status changes,
+  # background task notifications, and any transient user feedback that
+  # doesn't belong in the chat stream.
+  #
+  # @example Adding a flash
+  #   flash = TUI::Flash.new
+  #   flash.error("Message not delivered: API token not configured")
+  #   flash.warning("Rate limited, retry in 30s")
+  #   flash.info("Reconnected to server")
+  #
+  # @example Rendering (returns height consumed)
+  #   flash_height = flash.render(frame, area, tui)
+  #
+  # @example Dismissing
+  #   flash.dismiss!
+  class Flash
+    AUTO_DISMISS_SECONDS = 5.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
+
+    def initialize
+      @entries = []
+    end
+
+    # @param message [String]
+    def error(message)
+      push(message, :error)
+    end
+
+    # @param message [String]
+    def warning(message)
+      push(message, :warning)
+    end
+
+    # @param message [String]
+    def info(message)
+      push(message, :info)
+    end
+
+    # Removes expired entries and returns true if any remain.
+    def any?
+      expire!
+      @entries.any?
+    end
+
+    # @return [Boolean]
+    def empty?
+      !any?
+    end
+
+    # Removes all entries immediately (e.g. on keypress).
+    def dismiss!
+      @entries.clear
+    end
+
+    # Renders flash entries as colored bars at the top of the given area.
+    # Returns the height consumed so the caller can adjust layout.
+    #
+    # @param frame [RatatuiRuby::Frame]
+    # @param area [RatatuiRuby::Rect] full chat area (flash renders at top)
+    # @param tui [RatatuiRuby::TUI]
+    # @return [Integer] number of rows consumed
+    def render(frame, area, tui)
+      expire!
+      return 0 if @entries.empty?
+
+      height = [@entries.size, area.height / MAX_HEIGHT_FRACTION].min
+
+      flash_area, _ = tui.split(
+        area,
+        direction: :vertical,
+        constraints: [
+          tui.constraint_length(height),
+          tui.constraint_fill(1)
+        ]
+      )
+
+      @entries.each_with_index do |entry, index|
+        break if index >= height
+
+        row_area = row_rect(flash_area, index, tui)
+        render_entry(frame, row_area, entry, tui)
+      end
+
+      height
+    end
+
+    private
+
+    def push(message, level)
+      @entries << Entry.new(message: message, level: level, created_at: monotonic_now)
+    end
+
+    def expire!
+      now = monotonic_now
+      @entries.reject! { |entry| now - entry.created_at > AUTO_DISMISS_SECONDS }
+    end
+
+    def row_rect(area, index, tui)
+      rows = (0...area.height).map { tui.constraint_length(1) }
+      chunks = tui.split(area, direction: :vertical, constraints: rows)
+      chunks[index]
+    end
+
+    def render_entry(frame, area, entry, tui)
+      config = LEVEL_STYLES.fetch(entry.level, LEVEL_STYLES[:info])
+      style = tui.style(fg: config[:fg], bg: config[:bg], modifiers: [:bold])
+
+      text = "#{config[:icon]}#{entry.message} "
+      # Pad to full width so background color fills the entire row
+      padded = text.ljust(area.width)
+
+      line = tui.line(spans: [tui.span(content: padded, style: style)])
+      widget = tui.paragraph(text: [line])
+      frame.render_widget(widget, area)
+    end
+
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/tui/formatting.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module TUI
+  # Shared formatting helpers for timestamps and token counts.
+  # Used by both the Chat screen and client-side decorators
+  # to avoid duplicating display logic.
+  module Formatting
+    # Formats a token count for display, with tilde prefix for estimates.
+    # @param tokens [Integer, nil] token count
+    # @param estimated [Boolean] whether the count is an estimate
+    # @return [String] formatted label, e.g. "[42 tok]" or "[~28 tok]"
+    def format_token_label(tokens, estimated)
+      return "" unless tokens
+
+      label = estimated ? "~#{tokens}" : tokens.to_s
+      "[#{label} tok]"
+    end
+
+    # Converts nanosecond-precision timestamp to human-readable HH:MM:SS.
+    # @param ns [Integer, nil] nanosecond timestamp
+    # @return [String] formatted time, or "--:--:--" when nil
+    def format_ns_timestamp(ns)
+      return "--:--:--" unless ns
+
+      Time.at(ns / 1_000_000_000.0).strftime("%H:%M:%S")
+    end
+  end
+end

data/lib/tui/height_map.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module TUI
+  # Tracks estimated visual heights for chat entries, enabling
+  # viewport virtualization. Heights are in visual (wrapped) line
+  # units, estimated from content length and terminal width.
+  #
+  # Provides efficient scroll-position-to-entry-index mapping so
+  # the chat screen can render only visible messages instead of
+  # processing the entire conversation history.
+  #
+  # @example
+  #   map = HeightMap.new
+  #   map.update(entries, 80) { |entry, width| estimate(entry, width) }
+  #   first, last = map.visible_range(scroll_offset, viewport_height)
+  #   total = map.total_height
+  class HeightMap
+    # @return [Integer] number of tracked entries
+    attr_reader :size
+
+    def initialize
+      @heights = []
+      @size = 0
+    end
+
+    # Replaces all heights from a fresh estimation pass.
+    # Each entry's height is computed by the caller-supplied block.
+    #
+    # @param entries [Array<Hash>] message store entries
+    # @param width [Integer] terminal width for wrap estimation
+    # @yield [entry, width] block returning estimated visual line count
+    # @return [void]
+    def update(entries, width)
+      @heights = entries.map { |entry| [yield(entry, width), 1].max }
+      @size = @heights.size
+    end
+
+    # @return [Integer] sum of all estimated entry heights
+    def total_height
+      @heights.sum(0)
+    end
+
+    # Cumulative height of entries before the given index.
+    #
+    # @param index [Integer] entry index (0-based)
+    # @return [Integer] total visual lines above this entry
+    def cumulative_height(index)
+      return 0 if index <= 0 || @heights.empty?
+      return @heights.sum(0) if index >= @size
+
+      @heights[0...index].sum(0)
+    end
+
+    # Finds the entry range visible within a scroll window.
+    # An entry is visible if any of its lines fall within
+    # [scroll_offset, scroll_offset + visible_height).
+    #
+    # @param scroll_offset [Integer] top of viewport in visual lines
+    # @param visible_height [Integer] viewport height in visual lines
+    # @return [Array(Integer, Integer)] [first_visible, last_visible]
+    def visible_range(scroll_offset, visible_height)
+      return [0, 0] if @heights.empty?
+
+      first_found = false
+      first = 0
+      last = 0
+      cumulative = 0
+      end_line = scroll_offset + visible_height
+
+      @heights.each_with_index do |entry_height, idx|
+        entry_end = cumulative + entry_height
+        unless first_found
+          if entry_end > scroll_offset
+            first = idx
+            first_found = true
+          end
+        end
+        last = idx if cumulative < end_line
+        cumulative = entry_end
+      end
+
+      first = [@size - 1, 0].max unless first_found
+      [first, [last, first].max]
+    end
+
+    # Clears all tracked heights.
+    # @return [void]
+    def reset
+      @heights.clear
+      @size = 0
+    end
+  end
+end

data/lib/tui/message_store.rb

@@ -14,6 +14,11 @@ module TUI
   # rendered content fall back to existing behavior: tool events aggregate
   # into counters, messages store role and content.
   #
+  # Entries with event IDs are maintained in ID order (ascending)
+  # regardless of arrival order, preventing misordering from race
+  # conditions between live broadcasts and viewport replays.
+  # Duplicate IDs are deduplicated by updating the existing entry.
+  #
   # Tool counters aggregate per agent turn: a new counter starts when a
   # tool_call arrives after a message entry. Consecutive tool events
   # increment the same counter until the next message breaks the chain.
@@ -32,6 +37,15 @@ module TUI
       @entries = []
       @entries_by_id = {}
       @mutex = Mutex.new
+      @version = 0
+    end
+
+    # Monotonically increasing counter that bumps on every mutation.
+    # Consumers compare this to a cached value to detect changes
+    # without copying the full entries array on every frame.
+    # @return [Integer]
+    def version
+      @mutex.synchronize { @version }
     end
 
     # @return [Array<Hash>] thread-safe copy of stored entries
@@ -39,6 +53,11 @@ module TUI
       @mutex.synchronize { @entries.dup }
     end
 
+    # @return [Integer] number of stored entries (no array copy)
+    def size
+      @mutex.synchronize { @entries.size }
+    end
+
     # Processes a raw event payload from the WebSocket channel.
     # Uses structured decorator data when available; falls back to
     # role/content extraction for messages and tool counter aggregation.
@@ -77,6 +96,7 @@ module TUI
       @mutex.synchronize do
         @entries = []
         @entries_by_id = {}
+        @version += 1
       end
     end
 
@@ -111,6 +131,7 @@ module TUI
         return false unless entry
 
         @entries.delete(entry)
+        @version += 1
         true
       end
     end
@@ -131,6 +152,7 @@ module TUI
           @entries.delete(entry)
           removed += 1
         end
+        @version += 1 if removed > 0
         removed
       end
     end
@@ -151,6 +173,7 @@ module TUI
         return false unless entry
 
         entry[:data] = rendered
+        @version += 1
         true
       end
     end
@@ -165,15 +188,79 @@ module TUI
       event_data.dig("rendered")&.values&.compact&.first
     end
 
+    # Inserts a rendered entry at the correct chronological position.
+    # System prompt entries (no ID) are always placed at position 0.
     def record_rendered(data, event_type: nil, id: nil)
       @mutex.synchronize do
         entry = {type: :rendered, data: data, event_type: event_type, id: id}
-        @entries << entry
-        @entries_by_id[id] = entry if id
+        insert_ordered(entry)
+        @version += 1
       end
       true
     end
 
+    # Inserts an entry in event-ID order. Entries without an ID are
+    # appended. If an entry with the same ID already exists, updates
+    # it in-place (deduplication for live/viewport replay races).
+    # System prompt entries are always placed at position 0.
+    #
+    # @param entry [Hash] the entry to insert
+    # @return [void]
+    def insert_ordered(entry)
+      if entry[:event_type] == "system_prompt"
+        @entries.unshift(entry)
+        return
+      end
+
+      id = entry[:id]
+      unless id
+        @entries << entry
+        return
+      end
+
+      existing = @entries_by_id[id]
+      if existing
+        existing[:data] = entry[:data] if entry.key?(:data)
+        existing[:content] = entry[:content] if entry.key?(:content)
+        existing[:event_type] = entry[:event_type] if entry.key?(:event_type)
+        return
+      end
+
+      insert_sorted_by_id(entry)
+      @entries_by_id[id] = entry
+    end
+
+    # Inserts an entry in sorted order by event ID. Optimized for the
+    # common case where events arrive in order (appends without scanning).
+    # Entries without IDs (tool counters, etc.) are skipped during the
+    # sort scan and don't affect insertion position.
+    #
+    # @param entry [Hash] entry with a non-nil +:id+
+    # @return [void]
+    def insert_sorted_by_id(entry)
+      id = entry[:id]
+
+      # Fast path: entry belongs at the end (typical during live streaming)
+      last_id = last_entry_id
+      if last_id.nil? || last_id < id
+        @entries << entry
+        return
+      end
+
+      # Out-of-order arrival: insert before the first entry with a higher ID
+      insert_pos = @entries.index { |e| e[:id] && e[:id] > id } || @entries.size
+      @entries.insert(insert_pos, entry)
+    end
+
+    # Returns the highest event ID in the entries array, scanning from the
+    # end for efficiency (entries with IDs are typically at the tail).
+    #
+    # @return [Integer, nil] the highest event ID, or nil if no entries have IDs
+    def last_entry_id
+      @entries.reverse_each { |e| return e[:id] if e[:id] }
+      nil
+    end
+
     def record_tool_call
       @mutex.synchronize do
         current = current_tool_counter
@@ -182,6 +269,7 @@ module TUI
         else
           @entries << {type: :tool_counter, calls: 1, responses: 0}
         end
+        @version += 1
       end
       true
     end
@@ -189,7 +277,10 @@ module TUI
     def record_tool_response
       @mutex.synchronize do
         current = current_tool_counter
-        current[:responses] += 1 if current
+        return false unless current
+
+        current[:responses] += 1
+        @version += 1
       end
       true
     end
@@ -198,12 +289,10 @@ module TUI
       content = event_data["content"]
       return false if content.nil?
 
-      event_id = event_data["id"]
-
       @mutex.synchronize do
-        entry = {type: :message, role: ROLE_MAP.fetch(event_data["type"]), content: content, id: event_id}
-        @entries << entry
-        @entries_by_id[event_id] = entry if event_id
+        entry = {type: :message, role: ROLE_MAP.fetch(event_data["type"]), content: content, id: event_data["id"]}
+        insert_ordered(entry)
+        @version += 1
       end
       true
     end

data/lib/tui/performance_logger.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module TUI
+  # Frame-level performance logger for TUI render profiling.
+  #
+  # When enabled via `--debug`, logs timing data for each render phase
+  # to `log/tui_performance.log`. Each frame produces one log line with
+  # phase durations in milliseconds, enabling bottleneck identification.
+  #
+  # Uses monotonic clock to avoid wall-clock jitter.
+  #
+  # @example
+  #   logger = PerformanceLogger.new(enabled: true)
+  #   logger.start_frame
+  #   logger.measure(:build_lines) { build_message_lines(tui) }
+  #   logger.measure(:line_count) { widget.line_count(width) }
+  #   logger.end_frame
+  class PerformanceLogger
+    LOG_PATH = "log/tui_performance.log"
+
+    # @param enabled [Boolean] whether to actually log (no-op when false)
+    def initialize(enabled: false)
+      @enabled = enabled
+      @phases = {}
+      @frame_start = nil
+      @frame_count = 0
+      @logger = nil
+
+      return unless @enabled
+
+      @logger = Logger.new(LOG_PATH, 1, 5 * 1024 * 1024) # 5MB rotation
+      @logger.formatter = proc { |_sev, time, _prog, msg| "#{time.strftime("%H:%M:%S.%L")} #{msg}\n" }
+      @logger.info("TUI Performance Logger started — pid=#{Process.pid}")
+    end
+
+    # @return [Boolean] true when logging is active
+    def enabled?
+      @enabled
+    end
+
+    # Marks the beginning of a render frame.
+    def start_frame
+      return unless @enabled
+
+      @frame_start = monotonic_now
+      @phases = {}
+    end
+
+    # Measures a named phase within the current frame.
+    # Returns the block's result so it can be used inline.
+    #
+    # @param name [Symbol] phase name (e.g. :build_lines, :line_count)
+    # @yield the code to measure
+    # @return [Object] the block's return value
+    def measure(name)
+      return yield unless @enabled
+
+      start = monotonic_now
+      result = yield
+      @phases[name] = ((monotonic_now - start) * 1000).round(2)
+      result
+    end
+
+    # Logs the completed frame with all phase timings.
+    def end_frame
+      return unless @enabled
+
+      total = ((monotonic_now - @frame_start) * 1000).round(2)
+      @frame_count += 1
+
+      parts = @phases.map { |name, ms| "#{name}=#{ms}ms" }
+      @logger.info("frame=#{@frame_count} total=#{total}ms #{parts.join(" ")}")
+    end
+
+    # Logs a one-off informational message (e.g. cache hit/miss).
+    #
+    # @param message [String]
+    def info(message)
+      @logger&.info(message)
+    end
+
+    private
+
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end