fatty 0.99.8.4 → 0.99.8.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b46a42de2b3925689cb1b1383a85b01e143493db9271294b031eb78e3bcceb6b
-  data.tar.gz: 5ace58f489a5a0cfc0dfd623b76d2ff3f0074da7ceb776cbea86b25c42f49eaa
+  metadata.gz: 6d2ce5d4499e640b71d333ef143a02f3590aa44514f6ad64c21017ff4eb829f7
+  data.tar.gz: 5c9ac04a0c7975c71756c3a9364ab0222e43ec5696150cfed3526b589b3cdd48
 SHA512:
-  metadata.gz: 1d01d6ee255dc289fe9828c96a16aaf267abdf4d3a95fb1e9eb26cee0dbdb1cc0523d66dd7f6cfd14a200a0654cb49df4c483e74b56865007e58a2365fb63e4d
-  data.tar.gz: 12aa3e2a67f801583f43a6de8e07dc560fb247c61d90cafe2285c49c4f12502307dde31f5c07942f982f272a3b19933f981527bb378628b4bb5a3343532f699d
+  metadata.gz: a9fab1feaae8bacc7dcda281b9081fed3bab00440445763ab25577399e233321574828b1b014fc3ab9121d35aee69be66dbf2380cc03a16697c4aab4605930cb
+  data.tar.gz: 7c6c437ca0b0b3e5ab28a4488a30a770ef3ab127b2467c83b255e9551db7ce40294e469c2e4817f964171bde56847ef6bdfe99e2a936bbcc17c729bd0c7b6226

data/README.md

@@ -990,6 +990,11 @@ Alerts are short-lived, non-scrolling messages shown below the input field. They
 
 ## Command-line Editing
 
+Press `M-?` (Alt-?, or Escape followed by ?) to browse the current
+keybindings, including user overrides and action descriptions. The help
+uses the usual pager controls, including search. Press `q` to return to
+the previous output, pager position, and unfinished command line.
+
 `fatty` aims to have a full-featured command-line editor for editing a single line of text that is sent to the `on_accept` proc for the `Terminal`. The default keybindings are based on Emacs keybindings, but they are fully customizable. Implementing `vim`-like keybindings is not currently possible because `fatty` has no notion of editing "modes" as would be required for any kind of a modal editor—at least not yet. Maybe some day.
 
 

data/README.org

@@ -855,6 +855,11 @@ uses this area to warn the user of unrecognized key codes and of unbound key
 presses.
 
 ** Command-line Editing
+Press =M-?= (Alt-?, or Escape followed by ?) to browse the current
+keybindings, including user overrides and action descriptions.  The help
+uses the usual pager controls, including search.  Press =q= to return to
+the previous output, pager position, and unfinished command line.
+
 =fatty= aims to have a full-featured command-line editor for editing a single
 line of text that is sent to the =on_accept= proc for the =Terminal=.  The
 default keybindings are based on Emacs keybindings, but they are fully

data/help/help.md

@@ -60,6 +60,11 @@ Here are the commands builtin to `fatty`
 
 ## Keybindings
 
+Press `M-?` (Alt-?, or Escape followed by ?) to browse the current
+keybindings, including user overrides and action descriptions. Use the
+usual pager controls to scroll and search; `q` restores the previous output
+and unfinished command line.
+
 The following tables explain the keybindings available in \`fatty\` in different contexts. Named keys are indicated by \`:name\` and key categories, such as \`<digits>\` are indicated with brackets.
 
 

data/lib/fatty/colors/pairs.rb

@@ -37,6 +37,10 @@ module Fatty
       POPUP_FRAME     = 33
       POPUP_COUNTS    = 34
 
+      MARKDOWN_H1 = 35
+      MARKDOWN_H2 = 36
+      MARKDOWN_TABLE_HEADER = 37
+
       # Role -> pair id mapping for iteration.
       ROLE_TO_PAIR = {
         output: OUTPUT,
@@ -69,6 +73,10 @@ module Fatty
         popup_input: POPUP_INPUT,
         popup_frame: POPUP_FRAME,
         popup_counts: POPUP_COUNTS,
+
+        markdown_h1: MARKDOWN_H1,
+        markdown_h2: MARKDOWN_H2,
+        markdown_table_header: MARKDOWN_TABLE_HEADER,
       }.freeze
     end
   end

data/lib/fatty/config_files/themes/cyberpunk.yml

@@ -81,7 +81,7 @@ markdown_h1:
   attrs: [bold]
 
 markdown_h2:
-  fg: "#00d7ff"
+  fg: "#ffff00"
   bg: "#000000"
   attrs: [bold]
 

data/lib/fatty/config_files/themes/nordic.yml

@@ -2,6 +2,10 @@ name: nordic
 inherit: null
 markdown_code_theme: monokai
 
+markdown_h2:
+  fg: "#88c0d0"
+  attrs: [bold]
+
 output:
   fg: "#d8dee9"
   bg: "#2e3440"

data/lib/fatty/config_files/themes/solarized_dark.yml

@@ -2,6 +2,10 @@ name: solarized_dark
 inherit: null
 markdown_code_theme: solarized_dark
 
+markdown_h2:
+  fg: "#b58900"
+  attrs: [bold]
+
 output:
   fg: "#839496"
   bg: "#002b36"

data/lib/fatty/help.rb

@@ -2,6 +2,49 @@
 
 module Fatty
   module Help
+    CONTEXT_DESCRIPTIONS = {
+      text: "The text context supplies the shared editing keys for moving the cursor, " \
+        "deleting text, undoing edits, and copying or pasting. It is active while editing " \
+        "the command line, prompts, search queries, and popup filters. The input context " \
+        "below adds command-line-specific keys; other text fields add their own context. " \
+        "Those more specific bindings take precedence over text bindings.",
+      input: "The input context is active while you compose a command at the main prompt. " \
+        "It adds command history, completion, and submission to the shared text editing " \
+        "keys above. Fatty checks input bindings first, then text, then terminal. " \
+        "These input bindings do not apply to other prompts or search fields, or while paging output.",
+      terminal: "The terminal context supplies shared controls available from command input, " \
+        "the pager, prompts, searches, and popups. It is checked after the other active " \
+        "contexts, so these keys work throughout the normal interface unless a more " \
+        "specific context binds the same key. Special modes such as key testing handle " \
+        "keys separately.",
+      paging: "The paging context is active while you browse output, including this help. " \
+        "Its keys scroll, jump, search, narrow the displayed lines, or leave the pager. " \
+        "Printable keys act as pager commands rather than editing the command line. " \
+        "Terminal bindings remain available when paging does not bind the same key.",
+      popup: "The popup context is active in menus and selection lists. Its keys move " \
+        "among items, accept a choice, or cancel. Text bindings edit the popup's filter, " \
+        "while popup bindings take precedence for navigation and selection. Terminal " \
+        "bindings are checked last.",
+      popup_multi: "The popup_multi context adds selection controls to popups that let " \
+        "you choose multiple items. Its bindings are checked before popup, text, and " \
+        "terminal bindings. By default, Space toggles the current item instead of " \
+        "inserting a space into the filter.",
+      prompt: "The prompt context is active when Fatty asks you to enter an answer in " \
+        "a prompt. It supplies acceptance, cancellation, and prompt-history controls. " \
+        "The shared text bindings edit your answer; terminal bindings are checked last. " \
+        "The main command line uses input instead of this context.",
+      search: "The search context is active while you enter a pager search query. It " \
+        "provides search history, acceptance and cancellation, match navigation, and " \
+        "switching between literal text and regular expressions. Text bindings edit " \
+        "the query, and terminal bindings are checked last. After leaving the search " \
+        "field, paging bindings control the output again.",
+      isearch: "The isearch context is active during incremental pager search, where " \
+        "the match updates as you type. Its keys step through matches, recall search " \
+        "history, accept the search, or cancel and restore the earlier view. Text " \
+        "bindings edit the query, and terminal bindings are checked last.",
+    }.freeze
+    private_constant :CONTEXT_DESCRIPTIONS
+
     def self.path
       File.expand_path("../../help/help.md", __dir__)
     end
@@ -9,5 +52,78 @@ module Fatty
     def self.text
       File.read(path)
     end
+
+    def self.keybindings(keymap, width: 83)
+      lines = ["# Current keybindings", "",
+               "Fatty is the terminal user-interface library used by this application. " \
+                 "It provides command-line editing, output paging and search, and interactive prompts and menus.", "",
+               "Use the pager to browse or search; quit paging to return.", "",
+               "The tables below show the loaded keybindings for each context, including user overrides. " \
+                 "Keys use Emacs-like notation: C- means hold Control, M- means hold Alt (also called Meta), " \
+                 "and C-M- means hold both. Shift may be indicated by the final key name, as in M-R, " \
+                 "or by an explicit S- prefix, as in M-S-r. Both examples mean Alt-Shift-R. " \
+                 "Printable characters insert text in text-entry contexts.", "",
+               "The Action column gives the name of the Fatty action bound to each key. " \
+                 "These names are useful when customizing keybindings or working on Fatty itself."]
+      key_width, action_width, description_width = keybinding_column_widths(width)
+      keymap.bindings.sort_by { |context, _| [[:text, :input].index(context) || 2, context.to_s] }.each do |context, bindings|
+        description = CONTEXT_DESCRIPTIONS.fetch(context) do
+          "This context is supplied by the application or a custom keymap. Its bindings " \
+            "apply when the application activates it; the application determines how " \
+            "it combines with other contexts."
+        end
+        lines << "" << "## In the #{context} context:" << "" << description << ""
+        lines << "| Key | Action | Description |" << "| --- | --- | --- |"
+        entries = bindings.map do |gesture, binding|
+          key = gesture.is_a?(MouseGesture) ? gesture.button : gesture.key
+          label = KeyEvent.key_to_str(key: key, ctrl: gesture.ctrl, meta: gesture.meta, shift: gesture.shift)
+          action, *args = Array(binding)
+          description = Actions.lookup(action)&.fetch(:doc)
+          action_text = ([action] + args.map(&:inspect)).join(" ")
+          [label, action_text, description]
+        end
+        entries.sort_by(&:first).each do |label, action, description|
+          keys = wrap_cell(label, key_width)
+          actions = wrap_cell(action, action_width)
+          descriptions = wrap_cell(description, description_width)
+          [keys.length, actions.length, descriptions.length].max.times do |index|
+            lines << "| #{escape_cell(keys[index])} | #{escape_cell(actions[index])} | #{escape_cell(descriptions[index])} |"
+          end
+        end
+      end
+      lines.join("\n")
+    end
+
+    def self.keybinding_column_widths(width)
+      width = [width, 83].min
+      key_width = [[width / 6, 12].min, 3].max
+      action_width = [[width - 12 - key_width - 11, 27].min, 6].max
+      [key_width, action_width, [width - 12 - key_width - action_width, 11].max]
+    end
+
+    def self.wrap_cell(text, width)
+      lines = []
+      line = +""
+      text.to_s.split.each do |word|
+        if !line.empty? && line.length + word.length + 1 > width
+          lines << line
+          line = +""
+        end
+        while word.length > width
+          lines << word.slice!(0, width)
+        end
+        line << " " unless line.empty?
+        line << word
+      end
+      lines << line unless line.empty?
+      lines
+    end
+    private_class_method :wrap_cell
+
+    def self.escape_cell(text)
+      # Entities keep punctuation keys (especially pipes) inside their cells.
+      text.to_s.each_char.map { |char| char.match?(/[[:alnum:] ]/) ? char : "&##{char.ord};" }.join
+    end
+    private_class_method :escape_cell
   end
 end

data/lib/fatty/keymaps/emacs.rb

@@ -4,6 +4,7 @@ module Fatty
   module Keymaps
     def self.emacs
       map = KeyMap.new
+      map.bind(context: :terminal, key: :'?', meta: true, action: :show_keybindings)
 
       # Motion
       map.bind(key: :f, ctrl: true, action: :move_right)

data/lib/fatty/markdown/ansi_renderer.rb

@@ -7,12 +7,14 @@ module Fatty
   class AnsiRenderer < Redcarpet::Render::Base
     HARD_BREAK = "\uE000"
 
-    def initialize(width: 80, palette: nil, theme: nil, truecolor: false)
+    def initialize(width: 80, palette: nil, theme: nil, truecolor: false, table_widths: nil, table_borders: false)
       super()
       @width = width.to_i
       @palette = palette || {}
       @theme = theme || {}
       @truecolor = truecolor
+      @table_widths = table_widths
+      @table_borders = table_borders
     end
 
     def block_code(code, language)
@@ -37,6 +39,10 @@ module Fatty
       text
     end
 
+    def entity(text)
+      CGI.unescapeHTML(text.to_s)
+    end
+
     def raw_html(html)
       text = CGI.unescapeHTML(html.to_s)
       render_inline_html(text)
@@ -186,6 +192,10 @@ module Fatty
         end
       end
 
+      if @table_borders
+        rendered.unshift(render_table_separator(widths, joints: ["┌", "┬", "┐"]))
+        rendered << render_table_separator(widths, joints: ["└", "┴", "┘"])
+      end
       rendered.join("\n") + "\n\n"
     end
 
@@ -207,7 +217,7 @@ module Fatty
         end
       end
 
-      widths
+      widths.each_with_index.map { |width, index| [width, Array(@table_widths)[index].to_i].max }
     end
 
     def render_table_row_cells(row, widths, header: false)
@@ -220,12 +230,12 @@ module Fatty
       "  │ #{cells.join(' │ ')} │"
     end
 
-    def render_table_separator(widths)
+    def render_table_separator(widths, joints: @table_borders ? ["├", "┼", "┤"] : [TABLE_BAR, TABLE_BAR, TABLE_BAR])
       parts = widths.map do |width|
         TABLE_DASH * (width + 2)
       end
 
-      "  #{TABLE_BAR}#{parts.join(TABLE_BAR)}#{TABLE_BAR}"
+      "  #{joints[0]}#{parts.join(joints[1])}#{joints[2]}"
     end
 
     def pad_visible(text, width)

data/lib/fatty/markdown/render.rb

@@ -2,9 +2,10 @@
 
 module Fatty
   module Markdown
-    def self.render(text, width: 80, palette: nil, theme: nil, truecolor: false) #
+    def self.render(text, width: 80, palette: nil, theme: nil, truecolor: false, table_widths: nil, table_borders: false)
       markdown = Redcarpet::Markdown.new(
-        Fatty::AnsiRenderer.new(width: width, palette: palette, theme: theme, truecolor: truecolor),
+        Fatty::AnsiRenderer.new(width: width, palette: palette, theme: theme, truecolor: truecolor,
+                               table_widths: table_widths, table_borders: table_borders),
         tables: true,
         fenced_code_blocks: true,
         autolink: true,

data/lib/fatty/renderer/curses.rb

@@ -523,27 +523,16 @@ module Fatty
         base_attr = pair_attr(:output, fallback: ::Curses::A_NORMAL)
         win.attrset(base_attr)
         win.scrl(delta)
-        if delta.positive?
-          start_y = height - delta
-          start_y = 0 if start_y < 0
-
-          (start_y...height).each do |y|
-            visible_line = lines[y]
-            draw_output_row(
-              win,
-              line: visible_line.text,
-              fragments: visible_line.fragments,
-              y: y,
-              abs_line: visible_line.number - 1,
-              highlights: highlights,
-            )
+        exposed_rows =
+          if delta.positive?
+            [height - delta, 0].max...height
+          else
+            0...[-delta, height].min
           end
-        else
-          count = -delta
-          count = height if count > height
 
-          (0...count).each do |y|
-            visible_line = lines[y]
+        exposed_rows.each do |y|
+          visible_line = lines[y]
+          if visible_line
             draw_output_row(
               win,
               line: visible_line.text,
@@ -552,6 +541,11 @@ module Fatty
               abs_line: visible_line.number - 1,
               highlights: highlights,
             )
+          else
+            win.setpos(y, 0)
+            win.attrset(base_attr)
+            win.addstr("~")
+            win.clrtoeol
           end
         end
         stage_window(win)
@@ -624,15 +618,16 @@ module Fatty
         win.bkgdset(base_attr) if win.respond_to?(:bkgdset)
         win.erase
 
-        lines.each_with_index do |visible_line, y|
+        viewport.height.times do |y|
+          visible_line = lines[y]
           draw_output_row(
             win,
-            line: visible_line.text,
-            fragments: visible_line.fragments,
+            line: visible_line ? visible_line.text : "~",
+            fragments: visible_line&.fragments,
             y: y,
-            abs_line: visible_line.number - 1,
+            abs_line: visible_line ? visible_line.number - 1 : nil,
             highlights: highlights,
-            line_number: visible_line.number,
+            line_number: visible_line&.number,
             line_number_width: line_number_width,
           )
         end

data/lib/fatty/renderer/truecolor.rb

@@ -510,7 +510,7 @@ module Fatty
 
         rect.rows.times do |y|
           visible_line = lines[y]
-          text = visible_line&.text.to_s
+          text = visible_line ? visible_line.text : (y < viewport.height ? "~" : "")
           abs_line = visible_line ? visible_line.number - 1 : nil
           ranges = highlight_ranges_for_line(highlights, abs_line)
           segments = []

data/lib/fatty/session/keybindings_session.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Fatty
+  class KeybindingsSession < OutputSession
+    def init(terminal:)
+      super
+      width = [screen.output_rect.cols, 83].min
+      text = Markdown.render(
+        Help.keybindings(keymap, width: width),
+        width: [width, 80].min,
+        table_widths: Help.keybinding_column_widths(width),
+        table_borders: true,
+      )
+      # Keep Markdown roles semantic so theme changes recolor existing help.
+      sections = text.lines.chunk { |line| help_role(line.chomp) }
+      [
+        Command.session(id, :resize),
+        *sections.map { |role, lines| Command.session(id, :append, text: lines.join, role: role, follow: false) },
+        Command.session(id, :set_mode, mode: :paging),
+      ]
+    end
+
+    def update(command)
+      return [Command.terminal(:pop_modal)] if command.action == :quit_paging
+
+      super
+    end
+
+    def handle_resize
+      [Command.session(id, :resize)]
+    end
+
+    def show_keybindings
+      []
+    end
+
+    private
+
+    def help_role(line)
+      if line == "Current keybindings"
+        :markdown_h1
+      elsif keymap.contexts.any? { |context| line == "In the #{context} context:" }
+        :markdown_h2
+      elsif line.start_with?("  │ Key ")
+        :markdown_table_header
+      else
+        :output
+      end
+    end
+
+    def keymap_contexts
+      [:paging, :terminal]
+    end
+
+    def apply_action(action, args, event:)
+      return [Command.terminal(:pop_modal)] if action == :quit_paging
+
+      super
+    end
+  end
+end

data/lib/fatty/session.rb

@@ -69,6 +69,11 @@ module Fatty
       Command.terminal(:cycle_theme)
     end
 
+    desc "Display current keybindings in a temporary pager"
+    action :show_keybindings do
+      Command.terminal(:push_modal, session: KeybindingsSession.new(keymap: keymap), owner: self)
+    end
+
     desc "Choose a theme from a popup"
     action :choose_theme do
       Command.terminal(:choose_theme)
@@ -168,6 +173,7 @@ require_relative "session/popup_session"
 require_relative "session/search_session"
 require_relative "session/isearch_session"
 require_relative "session/output_session"
+require_relative "session/keybindings_session"
 require_relative "session/shell_session"
 require_relative 'session/prompt_session'
 require_relative 'session/keytest_session'

data/lib/fatty/terminal.rb

@@ -150,6 +150,8 @@ module Fatty
             text: warning,
           ),
         )
+      elsif (hint = keybinding_help_hint)
+        apply_command(Command.session(:alert, :show, role: :info, text: hint))
       end
 
       Fatty.debug("@sessions: #{@sessions.map(&:id).join('==')}")
@@ -260,8 +262,8 @@ module Fatty
       focused_session&.view
       status_session.view
       alert_session.view
-      if (top = @modal_stack.last)
-        top[:session].view
+      @modal_stack.each do |entry|
+        entry[:session].view
       end
       if @restore_cursor_after_render
         restore_active_cursor
@@ -464,8 +466,8 @@ module Fatty
       renderer.screen = screen
       apply_command(Command.session(:status, :resize))
       apply_command(Command.session(:focused, :resize))
-      if (top = @modal_stack.last)
-        apply_command(Command.session(top[:session].id, :resize))
+      @modal_stack.each do |entry|
+        apply_command(Command.session(entry[:session].id, :resize))
       end
       renderer.sync_backgrounds! if renderer.context.truecolor
       renderer.invalidate!
@@ -516,8 +518,8 @@ module Fatty
         out.resize_output! if out.respond_to?(:resize_output!)
       end
 
-      if (top = @modal_stack.last)
-        session = top[:session]
+      @modal_stack.each do |entry|
+        session = entry[:session]
         cmds = session.handle_resize
         apply_commands(cmds)
       end
@@ -550,6 +552,23 @@ module Fatty
     # Curses, the Logger, installing key definitions and mappings, and
     # installing themes.
     #
+    def keybinding_help_hint
+      map = shell_session&.keymap
+      return unless map
+
+      gesture = map.bindings.values.flat_map(&:keys).uniq.find do |key|
+        next unless key.is_a?(KeyGesture)
+
+        event = KeyEvent.new(key: key.key, ctrl: key.ctrl, meta: key.meta, shift: key.shift)
+        binding = map.resolve(event, contexts: [:input, :text, :terminal])
+        Array(binding).first == :show_keybindings
+      end
+      return unless gesture
+
+      label = KeyEvent.key_to_str(key: gesture.key, ctrl: gesture.ctrl, meta: gesture.meta, shift: gesture.shift)
+      "Press #{label} for keybinding help."
+    end
+
     def preflight!
       Fatty::Config.configure_app(
         app_name: @app_name,

data/lib/fatty/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Fatty
-  VERSION = "0.99.8.4"
+  VERSION = "0.99.8.5"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: fatty
 version: !ruby/object:Gem::Version
-  version: 0.99.8.4
+  version: 0.99.8.5
 platform: ruby
 authors:
 - Daniel E. Doherty
 bindir: exe
 cert_chain: []
-date: 2026-09-18 00:00:00.000000000 Z
+date: 2026-10-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: curses
@@ -224,6 +224,7 @@ files:
 - lib/fatty/session.rb
 - lib/fatty/session/alert_session.rb
 - lib/fatty/session/isearch_session.rb
+- lib/fatty/session/keybindings_session.rb
 - lib/fatty/session/keytest_session.rb
 - lib/fatty/session/modal_session.rb
 - lib/fatty/session/output_session.rb