anima-core 1.0.2 → 1.1.1

data/lib/tui/screens/chat.rb

@@ -1,10 +1,23 @@
 # frozen_string_literal: true
 
 require_relative "../input_buffer"
+require_relative "../flash"
+require_relative "../performance_logger"
+require_relative "../height_map"
+require_relative "../decorators/base_decorator"
+require_relative "../decorators/bash_decorator"
+require_relative "../decorators/read_decorator"
+require_relative "../decorators/edit_decorator"
+require_relative "../decorators/write_decorator"
+require_relative "../decorators/web_get_decorator"
+require_relative "../decorators/think_decorator"
+require_relative "../formatting"
 
 module TUI
   module Screens
     class Chat
+      include Formatting
+
       MIN_INPUT_HEIGHT = 3
       PRINTABLE_CHAR = /\A[[:print:]]\z/
 
@@ -18,10 +31,11 @@ module TUI
       TOOL_ICON = "\u{1F527}"
       CLOCK_ICON = "\u{1F552}"
       CHECKMARK = "\u2713"
-      RETURN_ARROW = "\u21A9"
-      ERROR_ICON = "\u274C"
 
-      THOUGHT_BUBBLE = "\u{1F4AD}"
+      # Viewport virtualization tuning
+      VIEWPORT_BACK_BUFFER = 3    # entries before scroll target for upward scroll margin
+      VIEWPORT_OVERFLOW_MULTIPLIER = 2 # build this many viewports worth of lines
+      VIEWPORT_BOTTOM_THRESHOLD = 10   # entries from end before we include all trailing
 
       ROLE_COLORS = {"user" => "green", "assistant" => "cyan"}.freeze
 
@@ -32,13 +46,17 @@ module TUI
       attr_reader :message_store, :scroll_offset, :session_info, :view_mode, :sessions_list,
         :authentication_required, :token_save_result, :parent_session_id,
         :chat_focused
+      attr_accessor :hud_hint
 
       # @param cable_client [TUI::CableClient] WebSocket client connected to the brain
       # @param message_store [TUI::MessageStore, nil] injectable for testing
-      def initialize(cable_client:, message_store: nil)
+      # @param perf_logger [TUI::PerformanceLogger, nil] optional performance logger
+      def initialize(cable_client:, message_store: nil, perf_logger: nil)
         @cable_client = cable_client
         @message_store = message_store || MessageStore.new
+        @perf_logger = perf_logger || PerformanceLogger.new(enabled: false)
         @input_buffer = InputBuffer.new
+        @flash = Flash.new
         @loading = false
         @scroll_offset = 0
         @auto_scroll = true
@@ -46,7 +64,7 @@ module TUI
         @max_scroll = 0
         @input_scroll_offset = 0
         @view_mode = "basic"
-        @session_info = {id: cable_client.session_id || 0, message_count: 0, active_skills: [], active_workflow: nil, goals: []}
+        @session_info = {id: cable_client.session_id || 0, message_count: 0, active_skills: [], active_workflow: nil, goals: [], children: []}
         @sessions_list = nil
         @parent_session_id = nil
         @authentication_required = false
@@ -55,6 +73,14 @@ module TUI
         @input_history = []
         @history_index = nil
         @saved_input = nil
+        # Viewport virtualization: only renders messages visible in the scroll
+        # window. Heights are estimated for all entries (cheap string math),
+        # but Line objects are only built for the visible range + buffer.
+        @height_map = HeightMap.new
+        @height_map_version = -1
+        @height_map_width = nil
+        @height_map_loading = nil
+        @viewport = viewport_cache_empty
       end
 
       def messages
@@ -86,6 +112,8 @@ module TUI
         )
 
         render_messages(frame, chat_area, tui)
+        render_flash(frame, chat_area, tui)
+
         render_input(frame, input_area, tui)
       end
 
@@ -101,6 +129,9 @@ module TUI
         return handle_paste_event(event) if event.paste?
         return handle_scroll_key(event) if event.page_up? || event.page_down?
 
+        # Dismiss flash on any keypress (flash auto-expires too)
+        @flash.dismiss! if @flash.any?
+
         return handle_chat_focused_event(event) if @chat_focused
 
         if event.up?
@@ -238,6 +269,8 @@ module TUI
             handle_active_workflow_updated(msg)
           when "goals_updated"
             handle_goals_updated(msg)
+          when "children_updated"
+            handle_children_updated(msg)
           when "sessions_list"
             @sessions_list = msg["sessions"]
           when "user_message_recalled"
@@ -246,13 +279,15 @@ module TUI
             @authentication_required = true
           when "token_saved"
             @authentication_required = false
-            @token_save_result = {success: true}
+            @token_save_result = {success: true, warning: msg["warning"]}.compact
           when "token_error"
             @token_save_result = {success: false, message: msg["message"]}
           when "error"
-            # Silently ignored — no user-facing error display yet
+            @flash.error(msg["message"]) if msg["message"]
           else
             case type
+            when "bounce_back"
+              handle_bounce_back(msg)
             when "connection"
               handle_connection_status(msg)
             when "user_message"
@@ -288,6 +323,16 @@ module TUI
         @message_store.remove_by_ids(evicted_ids)
       end
 
+      # Renders flash messages as colored bars inside the chat frame,
+      # just below the top border (respecting rounded corners).
+      def render_flash(frame, chat_area, tui)
+        return unless @flash.any?
+
+        # Inner area: inset by 1 on each side for the chat frame border
+        inner = tui.block(borders: [:all]).inner(chat_area)
+        @flash.render(frame, inner, tui)
+      end
+
       # Reacts to connection lifecycle changes from the WebSocket client.
       # Clears stale state when subscription begins so the store is empty
       # before history arrives. Action Cable sends confirm_subscription
@@ -304,6 +349,25 @@ module TUI
         end
       end
 
+      # Handles a Bounce Back event: the server rolled back the user event
+      # because LLM delivery failed. Removes the phantom message from the
+      # chat, restores the text to the input field, and shows a flash.
+      def handle_bounce_back(msg)
+        event_id = msg["event_id"]
+        content = msg["content"]
+        error = msg["error"]
+
+        @message_store.remove_by_id(event_id) if event_id
+        @loading = false
+
+        if content
+          @input_buffer.clear
+          @input_buffer.insert(content)
+        end
+
+        @flash.error("Message not delivered: #{error}") if error
+      end
+
       def handle_session_changed(msg)
         new_id = msg["session_id"]
         @cable_client.update_session_id(new_id)
@@ -311,7 +375,7 @@ module TUI
         @view_mode = msg["view_mode"] if msg["view_mode"]
         @session_info = {id: new_id, name: msg["name"], message_count: msg["message_count"] || 0,
                          active_skills: msg["active_skills"] || [], active_workflow: msg["active_workflow"],
-                         goals: msg["goals"] || []}
+                         goals: msg["goals"] || [], children: msg["children"] || []}
         @parent_session_id = msg["parent_session_id"]
         @input_buffer.clear
         @loading = false
@@ -354,6 +418,14 @@ module TUI
         @session_info[:goals] = msg["goals"] || []
       end
 
+      # Updates the children list when a sub-agent is spawned or its
+      # processing state changes. Only applies to the current session.
+      def handle_children_updated(msg)
+        return unless msg["session_id"] == @session_info[:id]
+
+        @session_info[:children] = msg["children"] || []
+      end
+
       # Handles server broadcast of view mode change. Clears the message store
       # in preparation for the re-decorated viewport events that follow.
       def handle_view_mode_changed(msg)
@@ -367,45 +439,80 @@ module TUI
         @auto_scroll = true
       end
 
+      # Renders chat messages using viewport virtualization.
+      # Only builds Line objects for entries visible in the scroll window,
+      # keeping render cost constant regardless of conversation length.
+      #
+      # Uses overflow-based viewport building: starts from the estimated
+      # scroll position and builds entries forward until enough lines
+      # accumulate to fill the viewport. Real line counts (not estimates)
+      # determine when to stop, so the buffer naturally adapts to entry
+      # sizes — no fixed entry-count buffer needed.
       def render_messages(frame, area, tui)
-        lines = build_message_lines(tui)
+        inner_width = [area.width - 2, 1].max
+        @visible_height = [area.height - 2, 0].max
+        entries = messages
+        version = @message_store.version
 
-        if @loading
-          lines << tui.line(spans: [
-            tui.span(content: "Thinking...", style: tui.style(fg: "yellow", modifiers: [:bold]))
-          ])
+        if entries.empty?
+          render_empty_or_loading(frame, area, tui)
+          return
         end
 
-        if lines.empty?
-          lines << tui.line(spans: [
-            tui.span(content: "Type a message to start chatting.", style: tui.style(fg: "dark_gray"))
-          ])
+        # Phase 1: Height estimation — O(n) string math, cached by version+width.
+        # Needed for total_height / scrollbar / scroll-offset-to-entry mapping.
+        @perf_logger.measure(:estimate_heights) { update_height_map(entries, inner_width, version) }
+
+        # Phase 2: Preliminary scroll offset for visible_range lookup.
+        # Don't clamp here — Phase 5.5 sets the authoritative @max_scroll
+        # from actual viewport height. Clamping here would cap scroll_offset
+        # to the (under)estimated total, making the bottom unreachable.
+        if @auto_scroll
+          est_total = @height_map.total_height
+          est_total += 1 if @loading
+          @scroll_offset = [est_total - @visible_height, 0].max
         end
 
-        inner_width = [area.width - 2, 1].max
-        @visible_height = [area.height - 2, 0].max
+        # Phase 3: Find approximate first visible entry
+        first_vis, = @height_map.visible_range(@scroll_offset, @visible_height)
 
-        base_widget = tui.paragraph(text: lines, wrap: true, style: tui.style(fg: "white"))
-        content_height = base_widget.line_count(inner_width)
+        # Phase 4: Build Line objects using overflow — stops when viewport is full
+        lines = @perf_logger.measure(:build_lines) {
+          cached_viewport_lines(tui, entries, version, first_vis)
+        }
+
+        # Phase 5: Paragraph widget + wrapped line count
+        base_widget = @perf_logger.measure(:paragraph) {
+          tui.paragraph(text: lines, wrap: true, style: tui.style(fg: "white"))
+        }
+        wrapped_height = @perf_logger.measure(:line_count) {
+          cached_viewport_line_count(base_widget, inner_width, version)
+        }
+
+        # Phase 5.5: Correct scroll state using actual viewport height.
+        # Replace the estimated viewport portion with the real wrapped_height.
+        vp_first = @viewport[:first]
+        vp_last = @viewport[:last]
+        est_before = @height_map.cumulative_height(vp_first)
+        est_after = @height_map.total_height - @height_map.cumulative_height(vp_last + 1)
+        loading_outside = @loading && vp_last < entries.size - 1
+        corrected_total = est_before + wrapped_height + est_after + (loading_outside ? 1 : 0)
 
-        @max_scroll = [content_height - @visible_height, 0].max
+        @max_scroll = [corrected_total - @visible_height, 0].max
         @scroll_offset = @max_scroll if @auto_scroll
         @scroll_offset = @scroll_offset.clamp(0, @max_scroll)
 
-        chat_block = {
-          title: "Chat",
-          borders: [:all],
-          border_type: :rounded,
-          border_style: @chat_focused ? {fg: "yellow"} : {fg: "cyan"}
-        }
-        if @chat_focused
-          chat_block[:titles] = [
-            {content: "\u2191\u2193 scroll  Esc return", position: :bottom, alignment: :center}
-          ]
-        end
+        # Phase 6: Map global scroll_offset into the viewport paragraph.
+        # est_before cancels between scroll_offset and max_scroll, so
+        # estimation errors don't create a dead zone at the bottom —
+        # they shift to the top (oldest messages) where they're harmless.
+        max_adjusted = [wrapped_height - @visible_height, 0].max
+        adjusted_scroll = (@scroll_offset - est_before).clamp(0, max_adjusted)
 
-        widget = base_widget.with(scroll: [@scroll_offset, 0], block: tui.block(**chat_block))
-        frame.render_widget(widget, area)
+        widget = @perf_logger.measure(:widget_with) {
+          base_widget.with(scroll: [adjusted_scroll, 0], block: tui.block(**chat_block_config))
+        }
+        @perf_logger.measure(:render_widget) { frame.render_widget(widget, area) }
 
         return unless @max_scroll > 0
 
@@ -420,17 +527,206 @@ module TUI
         frame.render_widget(scrollbar, area)
       end
 
-      def build_message_lines(tui)
-        messages.flat_map do |entry|
-          case entry[:type]
-          when :rendered
-            build_rendered_lines(tui, entry)
-          when :tool_counter
-            build_tool_counter_lines(tui, entry)
-          when :message
-            build_chat_message_lines(tui, entry)
-          end
+      # Renders the empty or loading state placeholder when no messages exist.
+      # Resets scroll state since there is no scrollable content.
+      #
+      # @param frame [RatatuiRuby::Frame] current render frame
+      # @param area [RatatuiRuby::Rect] available area for the chat pane
+      # @param tui [RatatuiRuby] TUI rendering API
+      # @return [void]
+      def render_empty_or_loading(frame, area, tui)
+        lines = if @loading
+          [tui.line(spans: [
+            tui.span(content: "Thinking...", style: tui.style(fg: "yellow", modifiers: [:bold]))
+          ])]
+        else
+          [tui.line(spans: [
+            tui.span(content: "Type a message to start chatting.", style: tui.style(fg: "dark_gray"))
+          ])]
         end
+
+        widget = tui.paragraph(text: lines, wrap: true, style: tui.style(fg: "white"))
+          .with(scroll: [0, 0], block: tui.block(**chat_block_config))
+        frame.render_widget(widget, area)
+        @max_scroll = 0
+        @scroll_offset = 0
+      end
+
+      # Re-estimates entry heights when content or width changes.
+      # Height estimation is O(n) string-length math — orders of
+      # magnitude cheaper than building Line/Span objects. Skips
+      # re-estimation when version, width, and loading state are unchanged.
+      #
+      # @param entries [Array<Hash>] message store entries
+      # @param width [Integer] available terminal width
+      # @param version [Integer] message store version counter
+      # @return [void]
+      def update_height_map(entries, width, version)
+        return if version == @height_map_version && width == @height_map_width && @loading == @height_map_loading
+
+        @height_map.update(entries, width) { |entry, avail_width| estimate_entry_height(entry, avail_width) }
+        @height_map_version = version
+        @height_map_width = width
+        @height_map_loading = @loading
+      end
+
+      # Returns cached viewport lines, rebuilding only when content
+      # changes or scroll moves outside the cached range. Uses overflow
+      # building: starts from a back-buffer before the visible entry and
+      # builds forward until the pre-wrap line count exceeds 2x the
+      # viewport height. Real line counts determine the buffer size, so
+      # it naturally adapts to entry sizes.
+      def cached_viewport_lines(tui, entries, version, first_visible_est)
+        vp = @viewport
+        vp_first = vp[:first]
+
+        # Cache hit: content unchanged and scroll target within the built range
+        if version == vp[:version] && @loading == vp[:loading] &&
+            vp_first && first_visible_est >= vp_first && first_visible_est <= vp[:last]
+          return vp[:lines]
+        end
+
+        entry_count = entries.size
+
+        # Start a few entries before the scroll target for upward buffer
+        buf_first = [first_visible_est - VIEWPORT_BACK_BUFFER, 0].max
+
+        # Build forward until we've accumulated enough lines to fill the
+        # viewport with margin. Pre-wrap count is a lower bound on visual
+        # height (wrapping only adds lines), so 2x guarantees coverage.
+        target = @visible_height * VIEWPORT_OVERFLOW_MULTIPLIER
+        lines = []
+        pre_wrap_count = 0
+        buf_last = buf_first
+
+        (buf_first...entry_count).each do |idx|
+          entry_lines = build_entry_lines(tui, entries[idx])
+          lines.concat(entry_lines)
+          pre_wrap_count += entry_lines.size
+          buf_last = idx
+          # Stop early only when we have enough lines AND are far from
+          # the bottom. Near the bottom, always include trailing entries
+          # so the viewport covers the actual end of content — otherwise
+          # the last entries become unreachable.
+          break if pre_wrap_count >= target && entry_count - idx > VIEWPORT_BOTTOM_THRESHOLD
+        end
+
+        if @loading && buf_last >= entry_count - 1
+          lines << tui.line(spans: [
+            tui.span(content: "Thinking...", style: tui.style(fg: "yellow", modifiers: [:bold]))
+          ])
+        end
+
+        @perf_logger.info(
+          "viewport MISS range=#{buf_first}..#{buf_last} " \
+          "of=#{entry_count} lines=#{lines.size}"
+        )
+
+        @viewport = {
+          version: version, loading: @loading, width: nil,
+          first: buf_first, last: buf_last,
+          lines: lines, wrapped_height: nil
+        }
+        lines
+      end
+
+      # Returns cached wrapped line count for the viewport paragraph.
+      # Avoids the expensive FFI line_count call when the viewport
+      # content and width haven't changed.
+      def cached_viewport_line_count(widget, width, version)
+        vp = @viewport
+        cached_height = vp[:wrapped_height]
+        if cached_height && version == vp[:version] && @loading == vp[:loading] && width == vp[:width]
+          return cached_height
+        end
+
+        height = widget.line_count(width)
+        @viewport[:width] = width
+        @viewport[:wrapped_height] = height
+        @perf_logger.info("viewport_lc MISS width=#{width} wrapped=#{height}")
+        height
+      end
+
+      # Builds Line objects for a single message store entry.
+      # Dispatches by entry type to the appropriate line builder.
+      #
+      # @param tui [RatatuiRuby] TUI rendering API
+      # @param entry [Hash] message store entry
+      # @return [Array<RatatuiRuby::Widgets::Line>]
+      def build_entry_lines(tui, entry)
+        case entry[:type]
+        when :rendered then build_rendered_lines(tui, entry)
+        when :tool_counter then build_tool_counter_lines(tui, entry)
+        when :message then build_chat_message_lines(tui, entry)
+        else []
+        end
+      end
+
+      # Estimates visual (wrapped) line count for a message store entry.
+      # Used only for scroll mapping (total_height, scrollbar) — the
+      # actual viewport uses real line counts from overflow building.
+      #
+      # @param entry [Hash] message store entry
+      # @param width [Integer] available terminal width
+      # @return [Integer] estimated visual lines (minimum 1)
+      def estimate_entry_height(entry, width)
+        effective_width = [width, 1].max
+
+        case entry[:type]
+        when :tool_counter
+          2 # counter line + blank separator
+        when :rendered
+          data = entry[:data]
+          text = [data["content"], data["input"]].compact.map(&:to_s).reject(&:empty?).join("\n")
+          lines = estimate_text_height(text, effective_width)
+          lines += 1 # header/label line
+          lines += 1 unless entry[:event_type] == "tool_call" # separator
+          lines
+        when :message
+          lines = estimate_text_height(entry[:content].to_s, effective_width)
+          lines + 1 # separator
+        else
+          1
+        end
+      end
+
+      # Estimates visual line count for multi-line text after word-wrapping.
+      #
+      # @param text [String] content text with embedded newlines
+      # @param width [Integer] available width
+      # @return [Integer] estimated visual line count (minimum 1)
+      def estimate_text_height(text, width)
+        return 1 if text.empty?
+
+        text.split("\n", -1).sum { |line|
+          [(line.length.to_f / width).ceil, 1].max
+        }
+      end
+
+      VIEWPORT_CACHE_EMPTY = {
+        version: -1, loading: nil, width: nil,
+        first: nil, last: nil, lines: nil, wrapped_height: nil
+      }.freeze
+
+      def viewport_cache_empty
+        VIEWPORT_CACHE_EMPTY.dup
+      end
+
+      # Builds the shared chat pane block config with focus-aware styling.
+      # @return [Hash] block configuration for tui.block
+      def chat_block_config
+        config = {
+          title: "Chat",
+          borders: [:all],
+          border_type: :rounded,
+          border_style: @chat_focused ? {fg: "yellow"} : {fg: "cyan"}
+        }
+        if @chat_focused
+          config[:titles] = [
+            {content: "\u2191\u2193 scroll  Esc return", position: :bottom, alignment: :center}
+          ]
+        end
+        config
       end
 
       # Renders a tool activity counter (e.g. "🔧 Tools: 2/2 ✓").
@@ -450,8 +746,10 @@ module TUI
         ]
       end
 
-      # Renders structured event data from the server. Uses the role field
-      # for styling — no string parsing or regex needed.
+      # Renders structured event data from the server. Tool-related roles
+      # (tool_call, tool_response, think) are dispatched to per-tool
+      # client-side decorators for tool-specific icons, colors, and formatting.
+      # Other roles are rendered inline.
       # @param tui [RatatuiRuby] TUI rendering API
       # @param entry [Hash] entry shaped `{type: :rendered, data: Hash}`
       # @return [Array<RatatuiRuby::Widgets::Line>] rendered lines + blank separator
@@ -462,12 +760,8 @@ module TUI
         lines = case role
         when "user", "assistant"
           render_conversation_entry(tui, data, role)
-        when "tool_call"
-          render_tool_call_entry(tui, data)
-        when "tool_response"
-          render_tool_response_entry(tui, data)
-        when "think"
-          render_think_entry(tui, data)
+        when "tool_call", "tool_response", "think"
+          Decorators::BaseDecorator.for(data).render(tui)
         when "system"
           render_system_entry(tui, data)
         when "system_prompt"
@@ -508,42 +802,6 @@ module TUI
         lines
       end
 
-      # Renders a tool invocation with tool name, optional tool_use_id, and indented input.
-      # @param tui [RatatuiRuby] TUI rendering API
-      # @param data [Hash] structured data with "tool", "input", and optional "tool_use_id"
-      # @return [Array<RatatuiRuby::Widgets::Line>]
-      def render_tool_call_entry(tui, data)
-        style = tui.style(fg: "white")
-        header = "#{TOOL_ICON} #{data["tool"]}"
-        header += " [#{data["tool_use_id"]}]" if data["tool_use_id"]
-
-        lines = [tui.line(spans: [tui.span(content: header, style: style)])]
-        data["input"].to_s.split("\n").each do |line|
-          lines << tui.line(spans: [tui.span(content: "  #{line}", style: style)])
-        end
-        lines
-      end
-
-      # Renders tool output with success/failure indicator, optional tool_use_id and token count.
-      # @param tui [RatatuiRuby] TUI rendering API
-      # @param data [Hash] structured data with "content", "success", and optional
-      #   "tool_use_id", "tokens", "estimated"
-      # @return [Array<RatatuiRuby::Widgets::Line>]
-      def render_tool_response_entry(tui, data)
-        indicator = (data["success"] == false) ? ERROR_ICON : CHECKMARK
-        meta_parts = []
-        meta_parts << "[#{data["tool_use_id"]}]" if data["tool_use_id"]
-        meta_parts << indicator
-        meta_parts << format_token_label(data["tokens"], data["estimated"]) if data["tokens"]
-        prefix = "  #{RETURN_ARROW} #{meta_parts.join(" ")} "
-
-        content_lines = data["content"].to_s.split("\n")
-        style = tui.style(fg: "white")
-        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
-
       # Renders a system message with optional timestamp prefix.
       # @param tui [RatatuiRuby] TUI rendering API
       # @param data [Hash] structured data with "content" and optional "timestamp"
@@ -576,47 +834,6 @@ module TUI
         lines
       end
 
-      # Renders a think event — the agent's inner reasoning between tool calls.
-      # "aloud" thoughts use yellow (narration for the user), "inner" thoughts
-      # use dark_gray (visible only in verbose/debug, dimmed to signal internality).
-      # @param tui [RatatuiRuby] TUI rendering API
-      # @param data [Hash] structured data with "content", "visibility", optional "timestamp", "tool_use_id"
-      # @return [Array<RatatuiRuby::Widgets::Line>]
-      def render_think_entry(tui, data)
-        aloud = data["visibility"] == "aloud"
-        color = aloud ? "yellow" : "dark_gray"
-        style = tui.style(fg: color)
-
-        meta = []
-        meta << "[#{format_ns_timestamp(data["timestamp"])}]" if data["timestamp"]
-        header = meta.empty? ? THOUGHT_BUBBLE : "#{meta.join(" ")} #{THOUGHT_BUBBLE}"
-
-        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
-
-      # 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
-
       def build_chat_message_lines(tui, msg)
         role = msg[:role]
         role_style = (role == ROLE_USER) ? tui.style(fg: "green", modifiers: [:bold]) : tui.style(fg: "cyan", modifiers: [:bold])
@@ -663,9 +880,7 @@ module TUI
           scroll: [input_scroll, 0],
           block: tui.block(
             title: title,
-            titles: disabled ? [] : [
-              {content: "Enter send", position: :bottom, alignment: :center}
-            ],
+            titles: input_bottom_titles(disabled),
             borders: [:all],
             border_type: :rounded,
             border_style: styles[:border]
@@ -704,6 +919,16 @@ module TUI
         end
       end
 
+      def input_bottom_titles(disabled)
+        return [] if disabled
+
+        command_hint = @hud_hint ? "C-a → h HUD" : "C-a command"
+        [
+          {content: command_hint, position: :bottom, alignment: :left},
+          {content: "Enter send", position: :bottom, alignment: :center}
+        ]
+      end
+
       # Builds input text as pre-wrapped Line objects for the Paragraph widget.
       # Lines are word-wrapped here so the Paragraph renders without its own
       # wrapping, keeping cursor positioning in sync with the displayed text.