fatty 0.99.0 → 0.99.3

data/lib/fatty/terminal.rb

@@ -1,738 +1,430 @@
 # frozen_string_literal: true
 
-require_relative 'terminal/progress'
 require_relative 'terminal/popup_owner'
 
 module Fatty
+  # Fatty aims at providing a full-featured, curses-based platform for
+  # REPL-style interaction with
+  #  - command-line editing (by default using Emacs-like keybindings),
+  #  - an output pane for normal output, a status pane for out-of-band
+  #    messages to the user, and an alert pane for library-related error or
+  #    information messages,
+  #  - history traversal and context-aware history,
+  #  - command completions based on input-so-far,
+  #  - popup facilities for things such as prompting the user for a string,
+  #    selecting one or more values from a list, selecting user-defined
+  #    actions from a menu, and more,
+  #  - a variety of progress indicators to keep the user informed about what's
+  #    happening in a long-running process.
+  #  - scrolling and searching long output to the output pane,
+  #  - rendering markdown text in the output pane,
+  #  - a theming system with several pre-defined color themes and facilities
+  #    for the user to add their own,
+  #  - a way to define keys that curses does not recognize and assign actions
+  #    to them, including actions the user defines
+  #  - rendering ANSI colored text to the output pane and the status pane,
+  #  - a way to suspend Fatty and exit to your real terminal and come back to
+  #    where you left off when you exit that terminal session.
+  #
+  # In other words, Fatty does much of the heavy lifting needed for a
+  # comfortable, full-featured interactive application.
+  #
+  # Fatty does not purport to be a "terminal" program but sits on top of them
+  # using curses and truecolor rendering into your normal terminal.
+  #
+  # Terminal is the main entry point. A library user normally creates a
+  # Terminal, configures the prompt, completion, history, and accept callback,
+  # then calls #go.
+  #
+  # Initialization options:
+  #
+  # - prompt :: either a fixed string or a proc that, when called, returns a
+  #   string to be used as the command-line prompt;
+  #
+  # - on_accept :: a proc that takes the edited line and performs some action
+  #   on it; the proc will have available to it a variable, `env`, that
+  #   contains an CallbackEnvironment object containing a reference to the
+  #   ShellSession and Terminal so that it can call actions on them, most
+  #   commonly `env.session.append_output(text)` to write output to the output
+  #   pane;
+  #
+  # - completion_proc :: a proc that returns an Array of strings based on the
+  #   input-so-far to suggest completions that can be inserted at that point;
+  #
+  # - history_path :: a path or sentinel describing input history is loaded
+  #   from and persisted;
+  #
+  # - history_ctx :: a proc that provides a "context" for history so that it
+  #   can be "favored" by history requests in the same context later;
+  #
+  # - env :: an optional Fatty::Env describing the runtime environment; when
+  #   omitted, Fatty will detect it with `Fatty::Env.detect`.
+  #
   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
+    attr_reader :screen, :renderer, :event_source, :env, :ctx
+    attr_reader :shell_session, :status_session, :alert_session, :focused_session
 
     def initialize(prompt: "> ",
                    on_accept: nil,
+                   app_name: nil,
+                   app_config_dir: nil,
                    completion_proc: nil,
                    history_path: :default,
                    history_ctx: nil,
                    env: nil)
       @prompt = Prompt.ensure(prompt)
       @on_accept = on_accept
+      @app_name = app_name
+      @app_config_dir = app_config_dir
       @completion_proc = completion_proc
       @history_path = history_path
       @history_ctx = history_ctx
       @env = env
+      @renderer = nil
 
       @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
+      @status_rows = 0
 
-    def register(session)
-      return unless session.respond_to?(:id)
-      return if session.id.nil?
-
-      @sessions_by_id[session.id] = session
+      @ctx = nil
+      @immediate_render = false
+      @session_dirty = false
+      @render_requested = false
+      @last_render_time = nil
+      @restore_cursor_after_render = true
+      @render_count = 0
+      @deferred_count = 0
     end
 
-    def find_session(id)
-      @sessions_by_id[id]
+    def inspect
+      "Terminal: prompt: #{@prompt}; history: #{@history_path}; sessions size: #{@sessions.size} active: #{active_session.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]
+    def to_s
+      inspect
     end
 
     # --- Runtime -----------------------------------------------------------
-
+    # Run the terminal.
+    #
+    # This method owns Fatty's main lifecycle:
+    #
+    # - load configuration and logging;
+    # - start curses and build the screen, renderer, and event source;
+    # - install the default permanent sessions;
+    # - enter the event loop;
+    # - restore the real terminal and persist session state on exit.
+    #
+    # The event loop has two sources of work. First, it polls the EventSource
+    # for user input, resize events, and other terminal events. Any event is
+    # routed to the active session, whose #update method may mutate session
+    # state and return commands for Terminal to process. Second, the active
+    # session is ticked once per loop so it can animate, poll, or otherwise
+    # mark itself dirty without receiving a key event.
+    #
+    # Whenever an event or tick changes state, Terminal schedules a render. Most
+    # renders happen immediately. The exception is fast scrolling in the normal
+    # curses renderer, where repeated output updates may be throttled to avoid
+    # excessive redraws. Truecolor rendering and direct user input are rendered
+    # immediately.
+    #
+    # Fatal errors are logged and re-raised, but cleanup still runs: curses is
+    # stopped so the real terminal is restored, and persistent sessions are given
+    # a chance to save their state.
     def go
       preflight!
       start_curses!
       install_default_sessions!
+      Fatty.debug("@sessions: #{@sessions.map(&:id).join('==')}")
 
       @running = true
-      last_render = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      pending_scroll_render = false
+      @last_render_time = 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
+        @session_dirty = false
+        @immediate_render = false
+        if (cmd = event_source.next_event)
+          begin
+            apply_command(cmd)
+            @session_dirty = true
+            @immediate_render = true
+          rescue StandardError => e
+            Fatty.error("Terminal#go apply_command failed: #{e.class}: #{e.message}", tag: :terminal)
+            Fatty.error(e.backtrace.join("\n"), tag: :terminal) if e.backtrace
+            @session_dirty = true
+            @immediate_render = true
+            raise
           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
+        @session_dirty ||= active_session&.tick
+        render_frame if render_due?
       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
+      cleanup_after_go
+    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
+    # --- Suspension  ------------------------------------------------
+
+    # Suspend fatty and run the block in the normal terminal, then restore
+    # fatty's terminal on exit.
+    def suspend
+      stop_curses!
+      yield
+    ensure
+      start_curses!
+      refresh_layout!
+      render_frame
     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,
-      )
+    # A command is either bound for this Terminal or it's meant to be
+    # forwarded to a Session.  This method routes the command to its proper
+    # destination.
+    def apply_command(command)
+      command = Fatty::Command.coerce(command)
+      return unless command
 
-      popup.instance_variable_set(:@selected, initial_choice_idx.to_i.clamp(0, labels.length - 1))
+      @apply_command_depth ||= 0
+      outermost = @apply_command_depth.zero?
+      @apply_command_depth += 1
 
-      done = false
-      result = nil
+      Fatty.debug(
+        "Terminal#apply_command: active_session: #{active_session.id}",
+        tag: :session,
+      )
+      Fatty.debug("Terminal#apply_command(#{command.inspect})", tag: :session)
 
-      acc_proc = ->(payload) do
-        item = payload[:item]
-        idx = labels.index(item)
-        result = idx ? items[idx][1] : quit_value
-        done = true
+      if user_interaction_command?(command)
+        apply_command(Command.session(:status, :clear))
+        apply_command(Command.session(:alert, :clear))
       end
 
-      cancel_proc = -> do
-        result = quit_value
-        done = true
+      if command.terminal?
+        apply_terminal_command(command)
+      else
+        apply_session_command(command)
       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
+    ensure
+      if command
+        @apply_command_depth -= 1
+        render_frame if outermost && render_due?
       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,
-      )
+    def interrupt_pending?
+      event_source.interrupt_pending?
     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
+    def modal_active?
+      @modal_stack.any?
     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
+    def running?
+      @running
+    end
 
-      acc_proc = ->(payload) do
-        result = payload[:text]
-        done = true
-      end
+    def tick_active_session
+      active_session&.tick
+    end
 
-      cancel_proc = -> do
-        result = quit_value
-        done = true
+    def render_frame
+      renderer.begin_frame
+      focused_session&.view
+      status_session.view
+      alert_session.view
+      if (top = @modal_stack.last)
+        top[:session].view
       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
+      if @restore_cursor_after_render
+        restore_active_cursor
+      else
+        renderer.hide_cursor
       end
-
-      result
+      renderer.finish_frame
+      @pending_scroll_render = false
+      @render_requested = false
+      @session_dirty = false
+      @last_render_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
     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,
-      )
+    def without_cursor_restore
+      old_restore_cursor = @restore_cursor_after_render
+      @restore_cursor_after_render = false
+      yield
+    ensure
+      @restore_cursor_after_render = old_restore_cursor
     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
+    def history
+      shell_session&.history || Fatty::History.for_path(@history_path)
+    end
 
-        while !done && @running
-          dirty = false
-          msg = event_source.next_event
+    private
 
-          if msg
-            dispatch_message(msg)
-            dirty = true
-          end
+    # simplecov:disable
 
-          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
+    # * Session management
+    #
+    # Terminal coordinates a small set of Session objects. A session is a UI
+    # component with three standard phases:
+    #
+    # - init :: receive the terminal and initialize session state;
+    # - update :: receive events or commands, mutate session state accordingly,
+    #   and, optionally, return commands requesting that Terminal perform
+    #   additional actions or route commands to other sessions;
+    # - view :: render the session's current state.
+    #
+    # Terminal is not itself a Session subclass, but it acts as the coordinator
+    # for all sessions. It routes input events to the active session, routes
+    # explicit commands either to itself or to a named session, and renders the
+    # sessions in a fixed order.
+    #
+    # Terminal keeps sessions in two groups:
+    #
+    # - permanent sessions :: a collection of always-present sessions. One
+    #   permanent session is designated the focused session and receives
+    #   keyboard input whenever no modal session is active. In the standard
+    #   configuration this is a ShellSession. Other permanent sessions, such
+    #   as StatusSession and AlertSession, are output-only sessions that do
+    #   not receive input focus.
+    # - modal sessions :: temporary sessions displayed above the permanent
+    #   sessions, usually as popups. While a modal session is present, it
+    #   becomes the active session and receives input first. The modal stack
+    #   also records an owner so that modal results can be sent back to the
+    #   session or helper that opened the modal.
+    #
+    # Rendering follows the same layering: permanent sessions are rendered
+    # first, followed by the top modal session.
+    #
+    def install_session(session, focus: false)
+      @sessions << session
+      register(session)
+      @focused_session = session if focus
 
-          render_frame if dirty
-        end
-      ensure
-        render_frame
-      end
-      result
+      commands = session.init(terminal: self)
+      apply_commands(commands)
+      session
     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
+    def register(session)
+      @sessions_by_id[session.id] = session
     end
 
-    def render_now
-      render_frame
+    def deregister(session)
+      @sessions_by_id.delete(session.id)
     end
 
-    def status_visible?
-      @status_text && !@status_text.empty?
+    def install_default_sessions!
+      @alert_session = Fatty::AlertSession.new(id: :alert)
+      install_session(@alert_session)
+      @status_session = Fatty::StatusSession.new(id: :status)
+      install_session(@status_session)
+      @shell_session = ShellSession.new(
+          id: :shell,
+          prompt: @prompt,
+          on_accept: @on_accept,
+          completion_proc: @completion_proc,
+          history_path: @history_path,
+          history_ctx: @history_ctx,
+        )
+      install_session(@shell_session, focus: true)
     end
 
-    def status_rows
-      return 0 unless status_visible?
+    def push_modal(session, owner: focused_session)
+      commands = session.init(terminal: self)
+      register(session)
+      @modal_stack << { session: session, owner: owner }
 
-      status_lines.length.clamp(1, status_max_rows)
-    end
+      msg = "Terminal#push_modal: size=#{@modal_stack.length} session=#{session.class} object_id=#{session.object_id}"
+      Fatty.debug(msg, tag: :session)
 
-    def status_max_rows
-      Fatty::Config.config.dig(:status, :max_rows)&.to_i || DEFAULT_STATUS_MAX_ROWS
+      @renderer&.invalidate!
+      apply_commands(commands)
     end
 
-    def status_lines
-      width = screen&.cols || 80
+    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)
 
-      @status_text.to_s
-        .lines
-        .flat_map { |line| wrap_status_line(line.chomp, width) }
-        .last(status_max_rows)
+      session = top && top[:session]
+      if session
+        session.close
+        deregister(session)
+      end
+      @renderer&.invalidate!
+      nil
     end
 
-    private
-
-    def wrap_status_line(line, width)
-      text = Fatty::Ansi.strip(line.to_s)
-      return [""] if text.empty?
+    # If we have modal sessions, the most recent one is active; otherwise, the
+    # focused_session, i.e., the ShellSession.
+    def active_session
+      top = @modal_stack.last
+      top ? top[:session] : focused_session
+    end
 
-      # Good enough first pass: no soft wrap within words.
-      # Later this should use visible-width-aware wrapping.
-      text.scan(/.{1,#{[width, 1].max}}/)
+    # Return the owner of the top modal session without modifying the stack.
+    def modal_owner
+      top = @modal_stack.last
+      top && top[:owner]
     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
+    # Return the Session object associated with `id`, which will be a symbol
+    # like :status or :alert.  Special id's :active and :focused resolve to
+    # the focused session (the one currently taking in key events) and the
+    # active session, the top modal session or, if there is none, the focused
+    # session.
+    def find_session(id)
+      case id
+      when :active
+        active_session
+      when :focused
+        focused_session
+      else
+        @sessions_by_id[id]
       end
-      exit(1)
     end
 
-    def start_curses!
-      @ctx = Fatty::Curses::Context.new
-      @ctx.start
+    # --- Rendering ---------------------------------------------------------
 
-      @screen = Fatty::Screen.new(rows: ::Curses.lines, cols: ::Curses.cols, status_rows: status_rows)
-      @ctx.apply_layout(@screen)
+    def render_due?
+      return true if @render_requested
 
-      @renderer =
-        if @ctx.truecolor
-          Fatty::Renderer::Truecolor.new(context: @ctx, screen: @screen, palette: @ctx.palette)
+      result =
+        if @session_dirty
+          immediate_render_due?
+        elsif @pending_scroll_render
+          scroll_render_due?
         else
-          Fatty::Renderer::Curses.new(context: @ctx, screen: @screen, palette: @ctx.palette)
+          false
         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
+      if @session_dirty && !result
+        @pending_scroll_render = true
+      end
+      result
     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
+    def immediate_render_due?
+      @immediate_render ||
+        renderer.context.truecolor ||
+        !scrolling_output? ||
+        scroll_render_due?
     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,
-      ))
+    def scroll_render_due?
+      now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      now - @last_render_time >= SCROLL_RENDER_THROTTLE
     end
 
     def scrolling_output?
@@ -749,24 +441,23 @@ module Fatty
       screen.resize(
         rows: @ctx.rows,
         cols: @ctx.cols,
-        status_rows: status_rows,
+        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
+      apply_command(Command.session(:status, :resize))
+      apply_command(Command.session(:focused, :resize))
       if (top = @modal_stack.last)
-        session = top[:session]
-        apply_commands(session.handle_resize) if session.respond_to?(:handle_resize)
+        apply_command(Command.session(top[:session].id, :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
+    def resize_command?(command)
+      # kind, event = message
+      # kind == :key && event.respond_to?(:key) && event.key == :resize
+      command.action == :resize
     end
 
     def handle_resize
@@ -777,25 +468,28 @@ module Fatty
       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
+      # renderer.clear_physical_screen! if renderer.context.truecolor
+
+      screen.resize(rows: rows, cols: cols, status_rows: @status_rows)
+      Fatty.info(
+        "handle_resize after=#{screen.rows}x#{screen.cols} " \
+        "output_after=#{screen.output_rect.inspect}",
+        tag: :resize,
+      )
 
-      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
@@ -810,11 +504,102 @@ module Fatty
         cmds = session.handle_resize
         apply_commands(cmds)
       end
+      @render_requested = true
       []
     ensure
       @inside_resize_term = false if did_resize_term
     end
 
+    # --- Initialization ---------------------------------------------------------
+
+    #
+    # These methods get Fatty started by reading the config, preparing
+    # Curses, the Logger, installing key definitions and mappings, and
+    # installing themes.
+    #
+    def preflight!
+      Fatty::Config.configure_app(
+        app_name: @app_name,
+        app_config_dir: @app_config_dir,
+      )
+      Fatty::Config.install_defaults!
+      Fatty::Config.config
+      Fatty::Logger.configure
+      if Fatty::Logger.logger
+        Fatty.info("Fatty #{Fatty::VERSION} loaded from #{__dir__}", tag: :config)
+        Fatty.info("Logger configured to log to #{Logger.path}", tag: :config)
+        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::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: 0)
+      @ctx.apply_layout(@screen)
+
+      @renderer =
+        if @ctx.truecolor_enabled?
+          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.invalidate!
+      @renderer.clear_physical_screen! if @ctx.truecolor_enabled?
+      @renderer.sync_backgrounds! if @ctx.truecolor_enabled?
+
+      @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
+
+    # --- Shutdown ---------------------------------------------------------
+
+    def cleanup_after_go
+      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
+
+    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 persist_sessions!
       sessions = []
       sessions << @focused_session if @focused_session
@@ -833,235 +618,152 @@ module Fatty
 
     # --- 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
+    def user_interaction_command?(command)
+      return false if command.action == :resize
+      return false unless command.target == :active
+      return false unless command.action == :key
 
-      # 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)
+      event = command.payload[:event]
+      event && event.key != :resize
     end
 
-    # Return whether message is a key message
-    def key_event_message?(message)
-      message.is_a?(Array) && message[0] == :key
+    # Return whether command is a key event
+    def key_event_command?(command)
+      command.action == :key
     end
 
     def apply_commands(commands)
+      commands = [commands] if commands.is_a?(Fatty::Command)
       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
+    # Apply a command meant to be applied by this Terminal.
+    def apply_terminal_command(command)
+      case command.action
       when :quit
         persist_sessions!
         quit
-      when :push
-        session = rest.fetch(0)
-        push(session)
-      when :pop
-        pop
+      when :register_session
+        register(command.payload.fetch(:session))
+      when :set_status_rows
+        @status_rows = command.payload.fetch(:rows)
+      when :refresh_layout
+        refresh_layout!
       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)
+        session = command.payload.fetch(:session)
+        push_modal(session, owner: command.payload[:owner] || focused_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)
+        command = command.payload.fetch(:command)
         owner = modal_owner
-        # cmds = owner ? owner.update(msg, terminal: self) : []
-        cmds = owner ? owner.update(msg) : []
-        apply_commands(cmds)
+        commands = owner ? owner.update(command) : []
+        apply_commands(commands)
+      when :choose_theme
+        Fatty.debug("choose_theme: themes=#{Fatty::Themes::Manager.theme_names.inspect}", tag: :theme)
+        choose_theme
       when :cycle_theme
         new_theme = Fatty::Themes::Manager.cycle
+        Fatty.debug("cycle_theme: new_theme=#{new_theme.inspect}", tag: :theme)
         renderer.apply_theme!(new_theme)
-        apply_command([:send, :alert, :show, { level: :info, message: "Theme: #{new_theme}" }])
+        apply_command(
+          Command.session(
+            :alert,
+            :show,
+            role: :info,
+            text: "Theme: #{new_theme}",
+          ))
       when :set_theme
-        theme = rest.fetch(0)
+        theme = command.payload.fetch(:theme)
         Fatty::Themes::Manager.set(theme)
         renderer.apply_theme!(theme)
-        apply_command([:send, :alert, :show, { level: :info, message: "Theme: #{theme}" }])
-      when :handle_resize
+        apply_command(
+          Command.session(
+            :alert,
+            :show,
+            role: :info,
+            text: "Theme: #{theme}",
+          ))
+      when :resize
         handle_resize
       else
-        raise ArgumentError, "unknown terminal command #{name.inspect} (cmd=#{cmd.inspect})"
+        raise ArgumentError, "unknown terminal command #{command.action.inspect} (cmd=#{command.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
+    # Forward a command to the target session.
+    def apply_session_command(command)
+      session = find_session(command.id)
+      raise ArgumentError, "no session registered with id=#{command.id.inspect}" unless session
 
-      payload ||= {}
-      unless payload.is_a?(Hash)
-        raise ArgumentError, "send payload must be a Hash, got: #{payload.inspect}"
+      unless command.payload.is_a?(Hash)
+        raise ArgumentError, "session command payload must be a Hash, got: #{command.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)
+      commands = session.update(command)
+      @session_dirty = true
+      @immediate_render = true if %i[status alert].include?(session.id)
       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
+    def hide_cursor
+      renderer.hide_cursor
     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
+    def show_cursor
+      renderer.show_cursor
     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?(:cursor_visible?) && !session.cursor_visible?
+        renderer.hide_cursor
+        return
+      end
+
       if session.respond_to?(:pager_active?) && session.pager_active?
-        ::Curses.curs_set(0)
+        renderer.hide_cursor
         return
       end
 
       return unless session.respond_to?(:field) && session.field
 
-      ::Curses.curs_set(1)
+      renderer.show_cursor
       renderer.restore_cursor(session.field)
     end
+
+    def choose_theme
+      current = Fatty::Themes::Manager.current
+      names = Fatty::Themes::Manager.theme_names
+      ordered = [current] + (names - [current])
+
+      chooser = PopUpSession.new(
+        source: ordered,
+        kind: :theme_chooser,
+        title: "Themes",
+        prompt: "Theme: ",
+        current: :top,
+      )
+      owner = PopupOwner.new(
+        on_result: ->(payload) do
+          Fatty::Command.terminal(:set_theme, theme: payload[:item])
+        end,
+        on_cancel: -> do
+          Fatty::Command.terminal(:set_theme, theme: current)
+        end,
+        on_change: ->(payload) do
+          Fatty::Command.terminal(:set_theme, theme: payload[:item])
+        end,
+      )
+      push_modal(chooser, owner: owner)
+    end
   end
 end