anima-core 1.0.1 → 1.1.0

data/lib/tui/decorators/base_decorator.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require_relative "../formatting"
+
+module TUI
+  module Decorators
+    # Client-side decorator layer for per-tool TUI rendering.
+    #
+    # Mirrors the server's Draper architecture but with a different
+    # specialization axis: server decorators are uniform per EVENT TYPE
+    # (tool_call, tool_result, message), while client decorators are
+    # unique per TOOL NAME (bash, read_file, web_get) — determining
+    # how each tool looks on screen.
+    #
+    # The factory dispatches on the +tool+ field in the structured data
+    # hash received from the server. Unknown tools fall back to generic
+    # rendering provided by this base class.
+    #
+    # @example Render a tool call
+    #   decorator = TUI::Decorators::BaseDecorator.for(data)
+    #   lines = decorator.render(tui)
+    class BaseDecorator
+      include Formatting
+
+      ICON = "\u{1F527}"        # wrench
+      CHECKMARK = "\u2713"
+      RETURN_ARROW = "\u21A9"
+      ERROR_ICON = "\u274C"
+
+      attr_reader :data
+
+      def initialize(data)
+        @data = data
+      end
+
+      # Factory returning the per-tool decorator for the given data hash.
+      #
+      # @param data [Hash] structured event data with string keys
+      #   ("role", "tool", "content", etc.)
+      # @return [BaseDecorator] the appropriate per-tool decorator
+      def self.for(data)
+        tool = resolve_tool(data)
+        decorator_for(tool).new(data)
+      end
+
+      # Renders the event, dispatching by role to the appropriate method.
+      #
+      # @param tui [RatatuiRuby] TUI rendering API
+      # @return [Array<RatatuiRuby::Widgets::Line>]
+      def render(tui)
+        case data["role"].to_s
+        when "tool_call" then render_call(tui)
+        when "tool_response" then render_response(tui)
+        when "think" then render_think(tui)
+        end
+      end
+
+      # Generic tool call rendering — icon, tool name, and indented input.
+      # Subclasses override for tool-specific presentation.
+      #
+      # @param tui [RatatuiRuby] TUI rendering API
+      # @return [Array<RatatuiRuby::Widgets::Line>]
+      def render_call(tui)
+        style = tui.style(fg: 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)])
+        end
+        lines
+      end
+
+      # Generic tool response rendering — success/failure indicator and content.
+      # Subclasses override for tool-specific presentation.
+      #
+      # @param tui [RatatuiRuby] TUI rendering API
+      # @return [Array<RatatuiRuby::Widgets::Line>]
+      def render_response(tui)
+        indicator = (data["success"] == false) ? ERROR_ICON : CHECKMARK
+        tool_id = data["tool_use_id"]
+        tokens = data["tokens"]
+
+        meta_parts = []
+        meta_parts << "[#{tool_id}]" if tool_id
+        meta_parts << indicator
+        meta_parts << format_token_label(tokens, data["estimated"]) if tokens
+        prefix = "  #{RETURN_ARROW} #{meta_parts.join(" ")} "
+
+        content_lines = data["content"].to_s.split("\n", -1)
+        style = tui.style(fg: response_color)
+        lines = [tui.line(spans: [tui.span(content: "#{prefix}#{content_lines.first}", style: style)])]
+        content_lines.drop(1).each { |line| lines << tui.line(spans: [tui.span(content: "    #{line}", style: style)]) }
+        lines
+      end
+
+      # Think rendering — delegated to ThinkDecorator, but base provides
+      # a fallback that renders as a generic tool call.
+      #
+      # @param tui [RatatuiRuby] TUI rendering API
+      # @return [Array<RatatuiRuby::Widgets::Line>]
+      def render_think(tui)
+        render_call(tui)
+      end
+
+      # Icon for this tool type. Subclasses override with tool-specific icons.
+      # @return [String]
+      def icon
+        ICON
+      end
+
+      # Color for tool call headers. Subclasses override for tool-specific colors.
+      # @return [String]
+      def color
+        "white"
+      end
+
+      # Color for tool response content. Subclasses override for tool-specific colors.
+      # @return [String]
+      def response_color
+        "white"
+      end
+
+      private
+
+      # Builds the header line for a tool call entry.
+      # @return [String]
+      def build_call_header
+        ts = data["timestamp"]
+        tool_id = data["tool_use_id"]
+
+        meta = []
+        meta << "[#{format_ns_timestamp(ts)}]" if ts
+        prefix = meta.empty? ? icon : "#{meta.join(" ")} #{icon}"
+        header = "#{prefix} #{data["tool"]}"
+        header += " [#{tool_id}]" if tool_id
+        header
+      end
+
+      # Resolves the tool name from the data hash.
+      # Think events have role "think" but no "tool" field.
+      def self.resolve_tool(data)
+        role = data["role"].to_s
+        return "think" if role == "think"
+
+        data["tool"].to_s
+      end
+      private_class_method :resolve_tool
+
+      # Maps tool name to its decorator class.
+      # Unknown tools get the base decorator (generic rendering).
+      def self.decorator_for(tool_name)
+        case tool_name
+        when "bash" then BashDecorator
+        when "think" then ThinkDecorator
+        when "read" then ReadDecorator
+        when "edit" then EditDecorator
+        when "write" then WriteDecorator
+        when "web_get" then WebGetDecorator
+        else self
+        end
+      end
+      private_class_method :decorator_for
+    end
+  end
+end

data/lib/tui/decorators/bash_decorator.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module TUI
+  module Decorators
+    # Renders bash tool calls and responses.
+    # Calls show the shell command with a terminal icon.
+    # Responses use green for success, red for failure.
+    class BashDecorator < BaseDecorator
+      ICON = "\u{1F4BB}" # laptop / terminal
+
+      def icon
+        ICON
+      end
+
+      def response_color
+        (data["success"] == false) ? "red" : "green"
+      end
+    end
+  end
+end

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

@@ -32,6 +32,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 +48,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 +91,7 @@ module TUI
       @mutex.synchronize do
         @entries = []
         @entries_by_id = {}
+        @version += 1
       end
     end
 
@@ -111,6 +126,7 @@ module TUI
         return false unless entry
 
         @entries.delete(entry)
+        @version += 1
         true
       end
     end
@@ -131,6 +147,7 @@ module TUI
           @entries.delete(entry)
           removed += 1
         end
+        @version += 1 if removed > 0
         removed
       end
     end
@@ -151,6 +168,7 @@ module TUI
         return false unless entry
 
         entry[:data] = rendered
+        @version += 1
         true
       end
     end
@@ -170,6 +188,7 @@ module TUI
         entry = {type: :rendered, data: data, event_type: event_type, id: id}
         @entries << entry
         @entries_by_id[id] = entry if id
+        @version += 1
       end
       true
     end
@@ -182,6 +201,7 @@ module TUI
         else
           @entries << {type: :tool_counter, calls: 1, responses: 0}
         end
+        @version += 1
       end
       true
     end
@@ -189,7 +209,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
@@ -204,6 +227,7 @@ module TUI
         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
+        @version += 1
       end
       true
     end