fatty 0.99.0

data/lib/fatty/terminal.rb

@@ -0,0 +1,1067 @@
+# frozen_string_literal: true
+
+require_relative 'terminal/progress'
+require_relative 'terminal/popup_owner'
+
+module Fatty
+  class Terminal
+    SCROLL_RENDER_THROTTLE = 0.05
+    DEFAULT_STATUS_MAX_ROWS = 4
+
+    # Commands are plain Ruby arrays for now.
+    #
+    # Suggested shapes:
+    #
+    # Terminal/runtime commands:
+    #   [:terminal, :quit]
+    #   [:terminal, :push, session]
+    #   [:terminal, :pop]
+    #
+    # Session-targeted commands (no special casing):
+    #   [:send, :alert, :show, { level: :warn, message: "No matches" }]
+    #   [:send, :alert, :clear, {}]
+    #
+    # You can add more later; Terminal only needs a small dispatcher.
+
+    attr_reader :screen, :renderer, :event_source, :status_text, :status_role, :env
+
+    def initialize(prompt: "> ",
+                   on_accept: nil,
+                   completion_proc: nil,
+                   history_path: :default,
+                   history_ctx: nil,
+                   env: nil)
+      @prompt = Prompt.ensure(prompt)
+      @on_accept = on_accept
+      @completion_proc = completion_proc
+      @history_path = history_path
+      @history_ctx = history_ctx
+      @env = env
+
+      @running = false
+      @stack = []
+      @pinned = []
+      @sessions = []
+      @sessions_by_id = {}
+      @modal_stack = []
+      @status_text = nil
+      @status_role = :info
+      @status_transient = false
+    end
+
+    # --- Status line management ------------------------------------------------
+
+    def set_status(text, role: :info, transient: false)
+      old_rows = status_rows
+      str =
+        if text.is_a?(Array)
+          text.map { |part| part.is_a?(Hash) && part.key?(:text) ? part[:text] : part }.join
+        else
+          text.to_s
+        end
+
+      if str.empty?
+        @status_text = nil
+        @status_role = :info
+        @status_transient = false
+      else
+        @status_text = text
+        @status_role = role
+        @status_transient = transient
+      end
+      refresh_layout! if @screen && old_rows != status_rows
+    end
+
+    def clear_status
+      old_rows = status_rows
+      @status_text = nil
+      @status_role = :info
+      @status_transient = false
+      refresh_layout! if @screen && old_rows != status_rows
+    end
+
+    def transient_status?
+      !!@status_transient
+    end
+
+    # Display a message to the user in the status line, colored according to
+    # the Config for "info".
+    def info(text)
+      return $stderr.puts(text) unless @ctx
+
+      set_status(text.to_s, role: :info, transient: true)
+    end
+
+    # Display a message to the user in the status line, colored according to
+    # the Config for "good," i.e., success.
+    def good(text)
+      return $stderr.puts(text) unless @ctx
+
+      set_status(text.to_s, role: :good, transient: true)
+    end
+
+    # Display a message to the user in the status line, colored according to
+    # the Config for "warn," i.e., short of an error but not complete
+    # success either.
+    def warn(text)
+      return $stderr.puts(text) unless @ctx
+
+      set_status(text.to_s, role: :warn, transient: true)
+    end
+
+    # Display a message to the user in the status line, colored according to
+    # the Config for "oops," i.e., a soft failure.
+    def oops(text)
+      return $stderr.puts(text) unless @ctx
+
+      set_status(text.to_s, role: :error, transient: true)
+    end
+
+    # --- Session management ------------------------------------------------
+
+    def push(session)
+      Fatty.debug("Terminal#push(#{session})", tag: :session)
+      @stack << session
+      register(session)
+      commands = session.init(terminal: self)
+      apply_commands(commands)
+      session
+    end
+
+    def pop
+      Fatty.debug("Terminal#pop -> #{@stack.last}", tag: :session)
+      @stack.pop
+    end
+
+    def pin(session)
+      Fatty.debug("Terminal#pin(#{session})", tag: :session)
+      @pinned << session
+      register(session)
+      commands = session.init(terminal: self)
+      apply_commands(commands)
+      session
+    end
+
+    def active_session
+      top = @modal_stack.last
+      return top[:session] if top
+
+      focused_session
+    end
+
+    def focused_session
+      top = @stack.last
+      return top[:session] if top.is_a?(Hash)
+
+      top
+    end
+
+    def register(session)
+      return unless session.respond_to?(:id)
+      return if session.id.nil?
+
+      @sessions_by_id[session.id] = session
+    end
+
+    def find_session(id)
+      @sessions_by_id[id]
+    end
+
+    def push_modal(session, owner:)
+      @modal_stack << { session: session, owner: owner }
+      msg = "Terminal#push_modal: size=#{@modal_stack.length} session=#{session.class} object_id=#{session.object_id}"
+      Fatty.debug(msg, tag: :session)
+      register(session)
+      @renderer.invalidate! if defined?(@renderer) && @renderer
+      commands = session.init(terminal: self)
+      apply_commands(commands)
+    end
+
+    def pop_modal
+      top = @modal_stack.pop
+      msg = "Terminal#pop_modal: size=#{@modal_stack.length} popped=#{top && top[:session].class}"
+      Fatty.debug(msg, tag: :session)
+      session = top && top[:session]
+
+      session.close if session&.respond_to?(:close)
+      @renderer&.invalidate!
+      nil
+    end
+
+    # Return the owner of the top modal session without modifying the stack.
+    def modal_owner
+      top = @modal_stack.last
+      top && top[:owner]
+    end
+
+    # --- Runtime -----------------------------------------------------------
+
+    def go
+      preflight!
+      start_curses!
+      install_default_sessions!
+
+      @running = true
+      last_render = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      pending_scroll_render = false
+      render_frame
+
+      # For performance logging
+      perf_started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      loop_count = 0
+      event_count = 0
+      tick_dirty_count = 0
+      render_count = 0
+      deferred_count = 0
+      frame_ms = 0.0
+
+      while @running
+        loop_count += 1
+
+        dirty = false
+        immediate = false
+
+        msg = event_source.next_event
+        if msg
+          dispatch_message(msg)
+          dirty = true
+          immediate = true
+        end
+
+        s = active_session
+        begin
+          tick_dirty = !!s&.tick
+          tick_dirty_count += 1 if tick_dirty
+          dirty ||= tick_dirty
+        rescue StandardError => e
+          Fatty.error("Terminal#go tick failed: #{e.class}: #{e.message}", tag: :terminal)
+          dirty = true
+          immediate = true
+        end
+
+        if dirty
+          now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+          if immediate || renderer.context.truecolor || !scrolling_output?
+            render_frame
+            last_render = now
+            pending_scroll_render = false
+            render_count += 1
+          elsif now - last_render >= SCROLL_RENDER_THROTTLE
+            render_frame
+            last_render = now
+            pending_scroll_render = false
+            render_count += 1
+          else
+            pending_scroll_render = true
+            deferred_count += 1
+          end
+        elsif pending_scroll_render
+          now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          if now - last_render >= SCROLL_RENDER_THROTTLE
+            render_frame
+            last_render = now
+            pending_scroll_render = false
+            render_count += 1
+          end
+        end
+
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        if now - perf_started_at >= 1.0
+          avg_frame_ms =
+            if render_count.zero?
+              0.0
+            else
+              (frame_ms / render_count).round(2)
+            end
+
+          # Performance logging
+          Fatty.debug(
+            "perf loops=#{loop_count} events=#{event_count} " \
+              "tick_dirty=#{tick_dirty_count} renders=#{render_count} " \
+              "deferred=#{deferred_count} avg_frame_ms=#{avg_frame_ms} " \
+              "scrolling=#{scrolling_output?}",
+            tag: :perf,
+          )
+          perf_started_at = now
+          loop_count = 0
+          event_count = 0
+          tick_dirty_count = 0
+          render_count = 0
+          deferred_count = 0
+          frame_ms = 0.0
+        end
+      end
+    rescue => e
+      Fatty.error("Terminal#go fatal error: #{e.class}: #{e.message}", tag: :terminal)
+      Fatty.error(e.backtrace.join("\n"), tag: :terminal) if e.backtrace
+      raise
+    ensure
+      begin
+        stop_curses!
+      rescue => e
+        Fatty.error("Terminal#go stop_curses! failed: #{e.class}: #{e.message}", tag: :terminal)
+        Fatty.error(e.backtrace.join("\n"), tag: :terminal) if e.backtrace
+      end
+
+      begin
+        persist_sessions!
+      rescue => e
+        Fatty.error("Terminal#go persist_sessions! failed: #{e.class}: #{e.message}", tag: :terminal)
+        Fatty.error(e.backtrace.join("\n"), tag: :terminal) if e.backtrace
+      end
+    end
+
+    # The consumer can call #choose to cause an interactive popup session to
+    # present the user with a series of choices to select from.
+    def choose(prompt, choices:, initial_choice_idx: 0, quit_value: nil)
+      items = normalize_choices(choices)
+      raise ArgumentError, "choices must not be empty" if items.empty?
+
+      labels = items.map(&:first)
+      popup = Fatty::PopUpSession.new(
+        source: labels,
+        kind: :terminal_choose,
+        title: "Choose",
+        message: prompt,
+        prompt: "> ",
+        selection: :top,
+        validate_unique_labels: true,
+      )
+
+      popup.instance_variable_set(:@selected, initial_choice_idx.to_i.clamp(0, labels.length - 1))
+
+      done = false
+      result = nil
+
+      acc_proc = ->(payload) do
+        item = payload[:item]
+        idx = labels.index(item)
+        result = idx ? items[idx][1] : quit_value
+        done = true
+      end
+
+      cancel_proc = -> do
+        result = quit_value
+        done = true
+      end
+
+      owner = PopupOwner.new(on_result: acc_proc, on_cancel: cancel_proc)
+      begin
+        push_modal(popup, owner: owner)
+        render_frame
+
+        while !done && @running
+          dirty = false
+          msg = event_source.next_event
+          if msg
+            dispatch_message(msg)
+            dirty = true
+          end
+
+          s = active_session
+          begin
+            tick_dirty = !!s&.tick
+            dirty ||= tick_dirty
+          rescue StandardError => e
+            Fatty.error("Terminal#choose tick failed: #{e.class}: #{e.message}", tag: :terminal)
+            dirty = true
+          end
+
+          render_frame if dirty
+        end
+      ensure
+        render_frame
+      end
+
+      result
+    end
+
+    # A simple Yes/No chooser.
+    def confirm(prompt, default: true)
+      idx = default ? 0 : 1
+      choose(
+        prompt,
+        choices: [["Yes", true], ["No", false]],
+        initial_choice_idx: idx,
+        quit_value: false,
+      )
+    end
+
+    # The consumer can call #choose_multi to cause an interactive popup session to
+    # present the user with a series of choices to select from.
+    def choose_multi(prompt, choices:, quit_value: nil)
+      items = normalize_choices(choices)
+      raise ArgumentError, "choices must not be empty" if items.empty?
+
+      labels = items.map(&:first)
+      popup = Fatty::PopUpSession.new(
+        source: labels,
+        kind: :terminal_choose_multi,
+        title: "Choose Many",
+        message: prompt,
+        prompt: "> ",
+        selection: :top,
+        selection_mode: :multiple,
+        validate_unique_labels: true,
+      )
+
+      done = false
+      result = nil
+
+      label_to_value = items.to_h
+      acc_proc = ->(payload) do
+        selected = payload[:items] || {}
+
+        result =
+          selected.each_with_object({}) do |(label, _), h|
+            h[label] = label_to_value.fetch(label, quit_value)
+          end
+
+        done = true
+      end
+
+      cancel_proc = -> do
+        result = quit_value
+        done = true
+      end
+
+      owner = PopupOwner.new(on_result: acc_proc, on_cancel: cancel_proc)
+
+      begin
+        push_modal(popup, owner: owner)
+        render_frame
+
+        while !done && @running
+          dirty = false
+          msg = event_source.next_event
+          if msg
+            dispatch_message(msg)
+            dirty = true
+          end
+
+          s = active_session
+          begin
+            tick_dirty = !!s&.tick
+            dirty ||= tick_dirty
+          rescue StandardError => e
+            Fatty.error("Terminal#choose_multi tick failed: #{e.class}: #{e.message}", tag: :terminal)
+            dirty = true
+          end
+
+          render_frame if dirty
+        end
+      ensure
+        render_frame
+      end
+
+      result
+    end
+
+    # Create a popup to ask the user to enter an arbitrary string.  These
+    # prompts will keep their own history based on the history_key, or if not
+    # history_key is given, the prompt text.
+    def prompt(prompt, initial: "", quit_value: nil, history_key: nil)
+      history_ctx = { prompt: (history_key || prompt).to_s }
+
+      popup = Fatty::PromptSession.new(
+        title: "Prompt",
+        message: prompt,
+        prompt: "> ",
+        initial: initial,
+        kind: :terminal_prompt,
+        history_ctx: history_ctx,
+      )
+      done = false
+      result = nil
+
+      acc_proc = ->(payload) do
+        result = payload[:text]
+        done = true
+      end
+
+      cancel_proc = -> do
+        result = quit_value
+        done = true
+      end
+
+      owner = PopupOwner.new(on_result: acc_proc, on_cancel: cancel_proc)
+
+      begin
+        push_modal(popup, owner: owner)
+        render_frame
+
+        while !done && @running
+          dirty = false
+          msg = event_source.next_event
+          if msg
+            dispatch_message(msg)
+            dirty = true
+          end
+
+          s = active_session
+          begin
+            tick_dirty = !!s&.tick
+            dirty ||= tick_dirty
+          rescue StandardError => e
+            Fatty.error("Terminal#prompt tick failed: #{e.class}: #{e.message}", tag: :terminal)
+            dirty = true
+          end
+
+          render_frame if dirty
+        end
+      ensure
+        render_frame
+      end
+
+      result
+    end
+
+    # Create a transient status-line progress indicator.
+    # For style :spinner, total may be omitted for indeterminate progress.
+    def progress(label:, total: nil, style: :percent, role: :info, width: 40)
+      Progress.new(
+        terminal: self,
+        label: label,
+        total: total,
+        style: style,
+        role: role,
+        width: width,
+      )
+    end
+
+    # Present a chooser whose selected value is executed.
+    #
+    # choices may be:
+    #   [["Label", proc { ... }], ...]
+    # or:
+    #   { "Label" => proc { ... } }
+    #
+    # The proc may accept:
+    #   0 args
+    #   terminal:
+    #   terminal:, label:
+    #   terminal:, label:, payload:
+    def menu(prompt, choices:, initial_choice_idx: 0, quit_value: nil)
+      items = normalize_choices(choices)
+      raise ArgumentError, "choices must not be empty" if items.empty?
+
+      labels = items.map(&:first)
+      popup = Fatty::PopUpSession.new(
+        source: labels,
+        kind: :terminal_menu,
+        title: "Menu",
+        message: prompt,
+        prompt: "> ",
+        selection: :top,
+        validate_unique_labels: true,
+      )
+
+      popup.instance_variable_set(:@selected, initial_choice_idx.to_i.clamp(0, labels.length - 1))
+
+      done = false
+      result = nil
+      menu_session = active_session
+      acc_proc = ->(payload) do
+        label = payload[:item]
+        idx = labels.index(label)
+        action = idx ? items[idx][1] : nil
+        result = call_menu_action(
+          action,
+          session: menu_session,
+          label: label,
+          payload: payload,
+        )
+        done = true
+      end
+      cancel_proc = -> do
+        result = quit_value
+        done = true
+      end
+
+      owner = PopupOwner.new(on_result: acc_proc, on_cancel: cancel_proc)
+      begin
+        push_modal(popup, owner: owner)
+        render_frame
+
+        while !done && @running
+          dirty = false
+          msg = event_source.next_event
+
+          if msg
+            dispatch_message(msg)
+            dirty = true
+          end
+
+          s = active_session
+          begin
+            tick_dirty = !!s&.tick
+            dirty ||= tick_dirty
+          rescue StandardError => e
+            Fatty.error("Terminal#menu tick failed: #{e.class}: #{e.message}", tag: :terminal)
+            dirty = true
+          end
+
+          render_frame if dirty
+        end
+      ensure
+        render_frame
+      end
+      result
+    end
+
+    def call_menu_action(action, session:, label:, payload:)
+      if action.respond_to?(:call)
+        env = MenuEnv.new(
+          terminal: self,
+          session: session,
+          label: label,
+          payload: payload,
+        )
+        if action.arity.zero?
+          action.call
+        else
+          action.call(env)
+        end
+      else
+        action
+      end
+    end
+
+    def render_now
+      render_frame
+    end
+
+    def status_visible?
+      @status_text && !@status_text.empty?
+    end
+
+    def status_rows
+      return 0 unless status_visible?
+
+      status_lines.length.clamp(1, status_max_rows)
+    end
+
+    def status_max_rows
+      Fatty::Config.config.dig(:status, :max_rows)&.to_i || DEFAULT_STATUS_MAX_ROWS
+    end
+
+    def status_lines
+      width = screen&.cols || 80
+
+      @status_text.to_s
+        .lines
+        .flat_map { |line| wrap_status_line(line.chomp, width) }
+        .last(status_max_rows)
+    end
+
+    private
+
+    def wrap_status_line(line, width)
+      text = Fatty::Ansi.strip(line.to_s)
+      return [""] if text.empty?
+
+      # Good enough first pass: no soft wrap within words.
+      # Later this should use visible-width-aware wrapping.
+      text.scan(/.{1,#{[width, 1].max}}/)
+    end
+
+    def preflight!
+      Fatty::Config.config
+      Fatty::Logger.configure
+      if Fatty::Logger.logger
+        Fatty.info("Logger configured to log to #{Logger.path}")
+        Fatty.info("Read config from #{Config.user_config_path}", tag: :config)
+        Fatty.info("Config", config: Config.config, tag: :config)
+      end
+      Fatty::Config.keydefs
+      Fatty::Config.keybindings
+      Fatty::Config.install_default_themes!
+      Fatty::Themes::Manager.load!
+      Thread.report_on_exception = true
+    rescue FatConfig::ParseError => ex
+      msg = "Terminal#preflight!: configuration error: #{ex.class}: #{ex.message}"
+      warn msg
+      begin
+        Fatty.error(msg, tag: :config)
+      rescue StandardError
+        nil
+      end
+      exit(1)
+    end
+
+    def start_curses!
+      @ctx = Fatty::Curses::Context.new
+      @ctx.start
+
+      @screen = Fatty::Screen.new(rows: ::Curses.lines, cols: ::Curses.cols, status_rows: status_rows)
+      @ctx.apply_layout(@screen)
+
+      @renderer =
+        if @ctx.truecolor
+          Fatty::Renderer::Truecolor.new(context: @ctx, screen: @screen, palette: @ctx.palette)
+        else
+          Fatty::Renderer::Curses.new(context: @ctx, screen: @screen, palette: @ctx.palette)
+        end
+      @renderer.sync_backgrounds! if @ctx.truecolor
+
+      @env ||= Fatty::Env.detect
+      key_decoder = Fatty::Curses::KeyDecoder.new(env: @env)
+      @event_source =
+        Fatty::Curses::EventSource.new(context: @ctx, key_decoder: key_decoder, poll_ms: 50)
+      self
+    end
+
+    def stop_curses!
+      @ctx&.close
+    ensure
+      begin
+        $stdout.write("\e[0m")  # SGR reset
+        $stdout.write("\e[0 q") # DECSCUSR: restore terminal default cursor
+        $stdout.flush
+      rescue StandardError
+        # best-effort cleanup
+      end
+    end
+
+    def install_default_sessions!
+      pin(Fatty::AlertSession.new)
+      push(Fatty::ShellSession.new(
+        prompt: @prompt,
+        on_accept: @on_accept,
+        completion_proc: @completion_proc,
+        history_path: @history_path,
+        history_ctx: @history_ctx,
+      ))
+    end
+
+    def scrolling_output?
+      session = active_session
+      pager =
+        if session.respond_to?(:pager)
+          session.pager
+        end
+
+      pager && pager.mode == :scrolling
+    end
+
+    def refresh_layout!
+      screen.resize(
+        rows: @ctx.rows,
+        cols: @ctx.cols,
+        status_rows: status_rows,
+      )
+      @ctx.apply_layout(screen)
+      renderer.screen = screen
+      if (session = focused_session)
+        session.resize_output! if session.respond_to?(:resize_output!)
+      end
+      if (top = @modal_stack.last)
+        session = top[:session]
+        apply_commands(session.handle_resize) if session.respond_to?(:handle_resize)
+      end
+      renderer.sync_backgrounds! if renderer.context.truecolor
+      renderer.invalidate!
+    end
+
+    def resize_message?(message)
+      kind, event = message
+      kind == :key && event.respond_to?(:key) && event.key == :resize
+    end
+
+    def handle_resize
+      rows = ::Curses.lines
+      cols = ::Curses.cols
+      size = [rows, cols]
+
+      return [] if size == @last_handled_resize_size
+
+      @last_handled_resize_size = size
+
+      did_resize_term = false
+
+      # ncurses must be told to finalize internal resize state before we
+      # draw ANSI output. Without this, ANSI writes after resize may be
+      # ignored or clipped. Guarded to avoid recursive resize storms.
+      unless @inside_resize_term
+        @inside_resize_term = true
+        did_resize_term = true
+
+        # Use ncurses' high-level resize finalizer. This updates stdscr/curscr
+        # and ncurses bookkeeping before we rebuild Fatty's own layout and draw
+        # the ANSI overlay. resize_term is lower-level and is not equivalent here.
+        ::Curses.resizeterm(rows, cols)
+      end
+
+      renderer.clear_physical_screen! if renderer.context.truecolor
+
+      screen.resize(rows: rows, cols: cols, status_rows: status_rows)
+      renderer.context.apply_layout(screen)
+      renderer.screen = screen
+      renderer.sync_backgrounds! if renderer.context.truecolor
+      renderer.invalidate!
+
+      if (out = focused_session)
+        out.resize_output! if out.respond_to?(:resize_output!)
+      end
+
+      if (top = @modal_stack.last)
+        session = top[:session]
+        cmds = session.handle_resize
+        apply_commands(cmds)
+      end
+      []
+    ensure
+      @inside_resize_term = false if did_resize_term
+    end
+
+    def persist_sessions!
+      sessions = []
+      sessions << @focused_session if @focused_session
+      sessions.concat(@sessions) if defined?(@sessions) && @sessions
+
+      sessions.uniq.each do |s|
+        next unless s.respond_to?(:persist!)
+
+        s.persist!
+      end
+    end
+
+    def quit
+      @running = false
+    end
+
+    # --- Dispatch ----------------------------------------------------------
+
+    def dispatch_message(message)
+      s = active_session
+      return [] unless s
+
+      # Clear transient alerts on the next user keypress.
+      if key_event_message?(message) && !resize_message?(message) && find_session(:alert)
+        apply_command([:send, :alert, :clear, {}])
+      end
+
+      # Clear transient status line on the next user keypress.
+      if key_event_message?(message) && transient_status?
+        clear_status
+      end
+
+      Fatty.debug("Terminal#dispatch_message: #{message.inspect}", tag: :session)
+      commands = s.update(message)
+      Fatty.debug("Terminal#dispatch_message: session=#{s.class} -> cmds=#{commands.inspect}", tag: :session)
+
+      apply_commands(commands)
+    end
+
+    # Return whether message is a key message
+    def key_event_message?(message)
+      message.is_a?(Array) && message[0] == :key
+    end
+
+    def apply_commands(commands)
+      Array(commands).each do |cmd|
+        apply_command(cmd)
+      end
+    end
+
+    # A command is either bound for this Terminal (first element :terminal) or
+    # it's meant to be forwarded to a Session (first element :send).  This
+    # method routes the command to its proper destination.
+    def apply_command(cmd)
+      Fatty.debug("Terminal#apply_command(#{cmd})", tag: :session)
+      return if cmd.nil?
+
+      unless cmd.is_a?(Array) && cmd.first.is_a?(Symbol)
+        raise ArgumentError, "command must be an Array starting with a Symbol, got: #{cmd.inspect}"
+      end
+
+      case cmd[0]
+      when :terminal
+        apply_terminal_command(cmd)
+      when :send
+        apply_send_command(cmd)
+      else
+        raise ArgumentError, "unknown command domain #{cmd[0].inspect} (cmd=#{cmd.inspect})"
+      end
+    end
+
+    # Apply a command meant to be applied by this Terminal
+    def apply_terminal_command(cmd)
+      _, name, *rest = cmd
+      case name
+      when :quit
+        persist_sessions!
+        quit
+      when :push
+        session = rest.fetch(0)
+        push(session)
+      when :pop
+        pop
+      when :push_modal
+        session = rest.fetch(0)
+        Fatty.debug("Terminal#apply_terminal_command(:push_modal) before size=#{@modal_stack.length}", tag: :session)
+        push_modal(session, owner: focused_session)
+        Fatty.debug("Terminal#apply_terminal_command(:push_modal) after size=#{@modal_stack.length}", tag: :session)
+      when :pop_modal
+        Fatty.debug("Terminal#apply_terminal_command(:pop_modal) before size=#{@modal_stack.length}", tag: :session)
+        pop_modal
+        Fatty.debug("Terminal#apply_terminal_command(:pop_modal) aftersize=#{@modal_stack.length}", tag: :session)
+      when :send_modal_owner
+        msg = rest.fetch(0)
+        owner = modal_owner
+        # cmds = owner ? owner.update(msg, terminal: self) : []
+        cmds = owner ? owner.update(msg) : []
+        apply_commands(cmds)
+      when :cycle_theme
+        new_theme = Fatty::Themes::Manager.cycle
+        renderer.apply_theme!(new_theme)
+        apply_command([:send, :alert, :show, { level: :info, message: "Theme: #{new_theme}" }])
+      when :set_theme
+        theme = rest.fetch(0)
+        Fatty::Themes::Manager.set(theme)
+        renderer.apply_theme!(theme)
+        apply_command([:send, :alert, :show, { level: :info, message: "Theme: #{theme}" }])
+      when :handle_resize
+        handle_resize
+      else
+        raise ArgumentError, "unknown terminal command #{name.inspect} (cmd=#{cmd.inspect})"
+      end
+    end
+
+    # Forward a command meant to be applied by a
+    # [:send, recipient, message_name, payload_hash]
+    def apply_send_command(cmd)
+      _, recipient, message_name, payload = cmd
+
+      session = find_session(recipient)
+      raise ArgumentError, "no session registered with id=#{recipient.inspect}" unless session
+
+      payload ||= {}
+      unless payload.is_a?(Hash)
+        raise ArgumentError, "send payload must be a Hash, got: #{payload.inspect}"
+      end
+
+      # Deliver as a uniform "command message" array for now.
+      # Sessions can pattern-match it in #update.
+      message = [:cmd, message_name, payload]
+
+      commands = session.update(message)
+      apply_commands(commands)
+    end
+
+    def prompt_history
+      @prompt_history ||= Fatty::History.new(path: :default)
+    end
+
+    # --- Choose helpers ---------------------------------------------------------
+
+    def normalize_choices(choices)
+      Array(choices).map do |choice|
+        if choice.is_a?(Array) && choice.length == 2
+          [choice[0].to_s, choice[1]]
+        else
+          [choice.to_s, choice]
+        end
+      end
+    end
+
+    # --- Rendering ---------------------------------------------------------
+
+    def render_frame
+      renderer.begin_frame
+      sessions = @pinned + @stack
+      sessions.each do |s|
+        s.view(screen: screen, renderer: renderer)
+      end
+      Fatty::StatusView.new.render(
+        screen: screen,
+        renderer: renderer,
+        terminal: self,
+      )
+      if (top = @modal_stack.last)
+        top[:session].view(screen: screen, renderer: renderer)
+      end
+
+      restore_active_cursor
+      renderer.finish_frame
+    end
+
+    def restore_active_cursor
+      if @modal_stack && !@modal_stack.empty?
+        session = @modal_stack.last[:session]
+
+        if session.respond_to?(:pager_active?) && session.pager_active?
+          ::Curses.curs_set(0)
+          return
+        end
+
+        if session.respond_to?(:win) && session.respond_to?(:field) && session.field
+          win = session.win
+          unless win
+            ::Curses.curs_set(0)
+            return
+          end
+
+          begin
+            maxy = win.maxy
+            maxx = win.maxx
+          rescue RuntimeError
+            ::Curses.curs_set(0)
+            return
+          end
+
+          # If the popup is too small to place a cursor safely, just hide it.
+          if maxy < 3 || maxx < 3
+            ::Curses.curs_set(0)
+            return
+          end
+
+          ::Curses.curs_set(1)
+
+          cursor_x = session.field.cursor_x
+          cursor_x = 0 if cursor_x.nil?
+
+          if session.is_a?(Fatty::PopUpSession)
+            input_row = maxy - 2
+            cursor_x = cursor_x.clamp(0, [maxx - 3, 0].max)
+            begin
+              win.setpos(input_row, 1 + cursor_x)
+            rescue RuntimeError
+              ::Curses.curs_set(0)
+            end
+          elsif session.is_a?(Fatty::PromptSession)
+            message_rows = session.message && !session.message.empty? ? 1 : 0
+            input_row = 1 + message_rows
+            cursor_x = cursor_x.clamp(0, [maxx - 3, 0].max)
+            begin
+              win.setpos(input_row, 1 + cursor_x)
+            rescue RuntimeError
+              ::Curses.curs_set(0)
+            end
+          else
+            ::Curses.curs_set(0)
+          end
+
+          return
+        end
+
+        ::Curses.curs_set(0)
+        return
+      end
+
+      session = active_session
+      return unless session
+
+      if session.respond_to?(:pager_active?) && session.pager_active?
+        ::Curses.curs_set(0)
+        return
+      end
+
+      return unless session.respond_to?(:field) && session.field
+
+      ::Curses.curs_set(1)
+      renderer.restore_cursor(session.field)
+    end
+  end
+end