fatty 0.99.0 → 0.99.3

data/README.md

@@ -1,31 +1,2220 @@
-- [Introduction](#orga462d10)
-- [Reading Keys](#org64156e4)
-- [Alerts](#org38ad970)
+- [Introduction](#org92a02ab)
+- [Quick Start](#orga9758e6)
+  - [Installing](#org5d48af2)
+  - [Trying it Out with the \`fatty\` Demo](#orga0811d0)
+    - [Builtin commands](#org10b740e)
+    - [Screenshots](#orga21015c)
+      - [Command line editing](#orge811242)
+      - [Searchable Output](#org86db3fd)
+      - [Paging Markdown](#org465e882)
+      - [Popup Selection](#orged601b1)
+- [Usage](#org0fbc008)
+  - [Launching a Fatty Terminal](#orgdd7a899)
+    - [`on_accept`](#orge36ae8e)
+      - [Parameters to `on_accept`](#org74e77b2)
+      - [The `line` parameter to `on_accept`](#org21b8961)
+      - [The callback parameter to `on_accept`](#org3091db0)
+      - [Output ordering](#orgcd415d8)
+      - [Long-running callbacks and interruption](#org0d9a504)
+      - [ANSI colors in output](#org89ae995)
+    - [Other parameters to `Terminal.new`](#orgce83cdf)
+  - [The Callback API](#orgef3914d)
+    - [`append(text, follow: true)`](#org1f2fcbb)
+    - [`append_now(text, follow: true, mode: nil)`](#org3318ee2)
+    - [`markdown(text)`](#org3da5738)
+    - [`status(text, role: :info)`](#org5e0ab5d)
+    - [`good(text, replace: false, render: true)`](#orgd2a8b1b)
+    - [`info(text, replace: false, render: true)`](#org8ec7886)
+    - [`warn(text, replace: false, render: true)`](#org6bb2e02)
+    - [`error(text, replace: false, render: true)`](#org6040c43)
+    - [`oops(text, replace: false, render: true)`](#org3e60ade)
+    - [`alert(text, role: :info)`](#org5e74284)
+    - [`prompt(prompt, initial: "", cancel_value: nil, history_key: nil, save_history: true)`](#org71a56a2)
+    - [`check_interrupt!`](#orgd0da92b)
+    - [`add_progress(label:, total: nil, style: :percent, role: :info, width: 40)`](#orgfbc8aa5)
+      - [Initialization `add_progress(label:, style: :percent, total: nil, role: :info, width: 40)`](#orgd758f7b)
+      - [Update `update(current: nil, indicator: nil, render: false)`](#orgbe50f7a)
+      - [Finish](#org058be1b)
+      - [Clear](#org22e4b8d)
+    - [`choose(prompt, choices:, initial_choice_idx: 0, cancel_value: nil)`](#orgcfb56dd)
+    - [`choose_multi(prompt, choices:, cancel_value: nil)`](#org5b1d7d1)
+    - [`confirm(prompt, yes_label: "Yes", no_label: "No", cancel_value: false)`](#org9b37a8e)
+    - [`menu(prompt, choices:, initial_choice_idx: 0, cancel_value: nil)`](#org8d63dae)
+    - [`environment`](#org1750b9e)
+- [Default Interaction](#org727ceaf)
+  - [Parts of the Screen](#orgd560bdc)
+    - [Input Field](#org6ae09c7)
+    - [Output Pane](#org73b9106)
+    - [Status Area](#orga48a015)
+    - [Alert Area](#org5098d11)
+  - [Command-line Editing](#org2926c89)
+    - [Input Context](#orgbcdaaad)
+      - [Cursor Motion](#org1af96be)
+      - [Clearing](#org32a2afa)
+      - [Undo and Redo](#org72cce5e)
+      - [Deletion and Killing](#org5ac8fea)
+      - [Yanking, Mark, and Region](#org948d8d5)
+      - [Count Prefix](#orgb998032)
+      - [History Navigation](#org30cf355)
+      - [Completion](#org0c995ec)
+      - [Accept or Cancel](#orgf4edfcc)
+    - [Paging Context](#org8d58d09)
+    - [Searching Output](#org89f3027)
+      - [String and Regex Search](#org77137d8)
+      - [Incremental Search](#orgd90c796)
+- [Configuration](#orgc8458e1)
+  - [General Configuration `config.yml`](#org0add8c9)
+    - [`word_char_re`](#org1099eb8)
+    - [`esc_delay`](#orgce3e466)
+    - [`history`](#org95b5e48)
+      - [`file`](#orgdc30f58)
+      - [`max`](#org0941468)
+    - [`theme`](#orgce1b37d)
+    - [`truecolor`](#orgdd529bd)
+    - [`log`](#org2b58449)
+      - [`file`](#org0e3b938)
+      - [`level`](#org9c70445)
+      - [`tags`](#orge47f304)
+  - [Key code definitions `keydefs.yml`](#org220de42)
+  - [Key bindings  `keybindings.yml`](#orgbd79429)
+    - [Key Names](#org698f2a9)
+      - [Printable Keys](#org58581e4)
+      - [Curses and Fatty Named Keys](#org4b0cf5b)
+      - [Possibly Invisible Keys](#orgeab9ebe)
+      - [Unnamed but Recognized Keys](#orgde02d1d)
+    - [Mouse Events](#orge487bc7)
+    - [Modifiers](#orgcf36a39)
+    - [Contexts](#orgc29aad9)
+    - [Actions](#orgdb5aa78)
+      - [Input buffer actions](#orgf51a408)
+      - [Input field actions](#org3f876b8)
+      - [Shell session actions](#orge0c4e6e)
+      - [Pager actions](#org05813c6)
+      - [Pager search actions](#orgea58518)
+      - [Popup actions](#org6ea9ecc)
+      - [Prompt popup actions](#org8f3d6dc)
+      - [Utility Actions](#org4a9e2d4)
+  - [Themes `themes/`](#org7e9ed87)
+    - [Distributed Themes](#orgf951ab7)
+    - [Custom Themes](#orgcf6fbb1)
+      - [Theme Name](#orgb8ead89)
+      - [Inheritance from Another Theme](#orgc49dfe9)
+      - [Inheritance within a Theme](#org371d3bb)
+      - [Theme Roles](#org83d0479)
+      - [Role Colors and Attributes and Frame Style](#orgabf70f2)
 
-#+PROPERTY: header-args:ruby :results value :colnames no :hlines yes :exports both :dir "./"
-#+PROPERTY: header-args:ruby+ :wrap example :session fatty_session :eval yes
-#+PROPERTY: header-args:ruby+ :prologue "$:.unshift('./lib') unless $:.first == './lib'; require 'fatty'"
-#+PROPERTY: header-args:ruby+ :ruby "bundle exec irb"
-#+PROPERTY: header-args:sh :exports code :eval no
-#+PROPERTY: header-args:bash :exports code :eval no
 
-[![CI](https://github.com/ddoherty03/fatty/actions/workflows/main.yml/badge.svg?branch=master)](https://github.com/ddoherty03/fatty/actions/workflows/main.yml)
 
+<a id="org92a02ab"></a>
+
+# Introduction
+
+`Fatty` aims to provide a full-featured command-line environment that provides:
+
+1.  an emacs-like editing command-line input, including undo/redo and kill/yank
+2.  a history facility,
+3.  command completion,
+4.  completion of partially-typed file path names,
+5.  output into a paging environment,
+6.  searching within the paged output,
+7.  issuing messages to a "status" area separate from the output pane,
+8.  binding keys to pre-defined actions,
+9.  defining unrecognized key-codes as named keys,
+10. color themes that can be selected in real time,
+11. a way to define new themes,
+12. processing completed command lines with a callback procedure of your choosing,
+13. several user-interface widgets such as selection popups, text prompts, menus, and progress indicators,
+14. a way to render markdown to the output pane,
+
+In other words, fatty allows you to write a terminal-based REPL of your choosing but takes care of all the difficult parts.
+
+`Fatty` is written entirely in Ruby and was born from my frustrations at the limitations of libraries like `readline` and `reline`. It uses `curses` and `truecolor` sequences for low-level rendering and is surprisingly snappy.
+
+`Fatty` is *not* a terminal emulator but runs on top of one.
+
+
+<a id="orga9758e6"></a>
+
+# Quick Start
+
+
+<a id="org5d48af2"></a>
+
+## Installing
+
+`Fatty` is a ruby gem, so it can be installed with
+
+```sh
+$ gem install fatty
+```
+
+
+<a id="orga0811d0"></a>
+
+## Trying it Out with the \`fatty\` Demo
+
+Once installed, you can try out `fatty` with the included program called `fatty`. It allows you to easily exercise all of the important features of the `fatty` library. At a normal shell prompt simply type `fatty`, and it will launch the `fatty` demo program.
+
+Once inside `fatty` you will be prompted with a prompt that names your current directory. Type `help` to get a summary of the builtin commands available to you. If you type anything other than a builtin command, `fatty` attempts to run it as a shell command and displays the output.
+
+
+<a id="org10b740e"></a>
+
+### Builtin commands
+
+Here are the commands builtin to `fatty`
+
+| Command                     | Description                                                             |
+|--------------------------- |----------------------------------------------------------------------- |
+| help                        | Display this file on the output pane                                    |
+| cd                          | Change the current directory used by the shell                          |
+| choose                      | Present a series of choices in a popup window                           |
+| choosevals                  | Also present choices in a popup window but return an associated value   |
+| choose\_multi               | Present choices with a "checkbox" for selecting multiple values         |
+| choosevals\_multi           | Also present a checkbox but return associated values                    |
+| menu                        | Present a menu of labeled routines to run                               |
+| info                        | Display an "info" message on the status line                            |
+| good                        | Display a "good" message colored to indicate success                    |
+| warn                        | Display a "warn" message colored to indicate caution                    |
+| oops                        | Display an "oops" message colored to indicate failure                   |
+| interrupt                   | Test fatty's interrupt handling                                         |
+| prompt                      | Popup a text box for entering a value in response to a prompt           |
+| progress count <N>          | Display an animated progress indicator counting up to 40 or the given N |
+| progress percent <N>        | Same but also show the percent complete                                 |
+| progress count\_percent <N> | Same but show both count and the percent complete                       |
+| progress trail              | Show progress by displaying an "indicator" character for each step      |
+| progress bar                | Show progress by a filling bar using ASCII characters                   |
+| progress unicode\_bar       | Same, but using unicode characters                                      |
+| progress braille\_bar       | Same, but using braille characters                                      |
+| progress spinner            | Animate a "spinner" showing a busy state                                |
+| markdown <file.md>          | Render the markdown file to the output pane; defaults to a demo file    |
+| keytest                     | Enter key diagnostic mode to report keycodes, key names, and bindings   |
+| colors                      | Display ANSI, 256-color, and X11 color diagnostics                      |
+
+
+<a id="orga21015c"></a>
+
+### Screenshots
+
+
+<a id="orge811242"></a>
+
+#### Command line editing
+
+Here is the command line, mid-edit showing a region selected and, in dim text to the right, a predictive completion based on history.
+
+![img](images/input_editing.png "Input editing showing region and predictive completion.")
+
+
+<a id="org86db3fd"></a>
+
+#### Searchable Output
+
+While paging output, you can search for words, as here the user searches for the word `tty` in the output. The current match is highlighted in yellow with other matches highlighted in gray. The paging status line shows the search term and the direction of search. The user can navigate for other matches in the output using `n` and `N`.
+
+![img](images/search_output.png "Searching for instances of `tty` in the output.")
+
+
+<a id="org465e882"></a>
+
+#### Paging Markdown
+
+The `fatty` demo running the `markdown` command and paging the output. It shows `fatty's` ability to render markdown using ANSI codes, including colorizing code blocks, as well as its paging interface.
+
+![img](images/page_markdown.png "Running the `fatty` demo `markdown` command.")
+
+
+<a id="orged601b1"></a>
+
+#### Popup Selection
+
+One of the many "widgets" available through `fatty` is the ability to present the user with a set of choices to select from. After running the demo's `choose "AAA" "BBB" "CCC" "DDD" "EEE"`
+
+![img](images/choose_popup.png "Running the `fatty` demo `choose` command.")
+
+
+<a id="org0fbc008"></a>
+
+# Usage
+
+
+<a id="orgdd7a899"></a>
+
+## Launching a Fatty Terminal
+
+
+<a id="orge36ae8e"></a>
+
+### `on_accept`
+
+You can launch a `Fatty` terminal session that does arbitrary processing of an edited command line and returns a String to be displayed on the output pane by providing an `on_accept` proc as a parameter as shown in this file that we'll call `loudrev`:
+
+```ruby
+#! /usr/bin/env ruby
+# -*- mode: ruby -*-
+
+require 'fatty'
+
+loud_reversal = lambda do |line|
+  line.upcase.reverse
+end
+
+Fatty::Terminal.new(
+  on_accept: loud_reversal,
+).go
+```
+
+Now you have an interactive application that allows you to type text and see what it looks like when written backwards in uppercase letters. It's as easy as that!
+
+When a `fatty` application runs, `fatty` installs a few files if they do not exist:
+
+-   a history file at `~/.fatty_history`
+-   a config directory at `~/.config/fatty` that contains
+    -   `config.yml`, the main configuration file
+    -   `keydefs.yml`, a file for associating keycodes emitted by the underlying terminal with names when curses does not do so automatically,
+    -   `keybindings.yml`, a file for associating named keys with actions above and beyond the emacs bindings that are used by default, and
+    -   `themes`, a directory of pre-defined theme definitions that you can choose from and add to by adding your own themes.
+
+
+<a id="org74e77b2"></a>
+
+#### Parameters to `on_accept`
+
+The `on_accept` proc passed to an instance of `Fatty::Terminal` can take one or two parameters: (1) `line`, the edited line as it exists when the user types `RETURN` and (2) an optional callback parameter that you can use to access the facilities of `fatty`.
+
+
+<a id="org21b8961"></a>
+
+#### The `line` parameter to `on_accept`
+
+`Fatty` does not parse command lines for your application. When the user accepts a `line`, `Fatty` passes the line to `on_accept` as text. It is up to your callback to decide whether to strip whitespace, split words, interpret quotes, parse options, recognize subcommands, or treat punctuation specially.
+
+This keeps `Fatty` useful for many different kinds of REPLs. Some applications want shell-like parsing. Others want to preserve the user's input exactly.
+
+For shell-like parsing, Ruby's standard `Shellwords` library is often useful:
+
+```ruby
+#! /usr/bin/env ruby
+# -*- mode: ruby -*-
+
+require 'fatty'
+require 'shellwords'
+
+runner = lambda do |line, fatty|
+  words = Shellwords.split(line)
+
+  case words
+  when ["echo", *rest]
+    fatty.append("#{rest.join(" ")}\n")
+  when ["count", *rest]
+    fatty.append("#{rest.length}\n")
+  when []
+    fatty.status("Blank line", role: :info)
+  else
+    fatty.alert("Unknown command: #{words.first}", role: :warn)
+  end
+rescue ArgumentError => e
+  fatty.alert("Could not parse line: #{e.message}", role: :error)
+end
+
+Fatty::Terminal.new(
+  prompt: "shellwords> ",
+  on_accept: runner,
+).go
+```
+
+
+<a id="org3091db0"></a>
+
+#### The callback parameter to `on_accept`
+
+The `on_accept` proc can have a second parameter named whatever you like that serves as a callback into certain facilities provided by `fatty`. In this README we use the name `fatty` for the callback parameter since it provides access to the facilities provided by the `fatty` library. Here is a variation of the prior example that also echoes the original typed string into the so-called status area:
+
+```ruby
+#! /usr/bin/env ruby
+# -*- mode: ruby -*-
+
+require 'fatty'
+
+loud_reversal = lambda do |line, fatty|
+  fatty.good(line)
+  line.upcase.reverse
+end
+
+Fatty::Terminal.new(
+  on_accept: loud_reversal,
+).go
+```
+
+The callback parameter responds to several methods that allow your application to interact with the user. They are documented below.
+
+
+<a id="orgcd415d8"></a>
+
+#### Output ordering
+
+The `on_accept` callback can send text to the output pane in three ways:
+
+1.  by returning a value from the callback;
+2.  by calling `append` or `markdown` on the callback environment; or
+3.  by calling `append_now` on the callback environment.
+
+A returned `String` is the simplest output mechanism. It is displayed after the callback finishes:
+
+```ruby
+Fatty::Terminal.new(
+  on_accept: ->(line) { line.upcase.reverse },
+).go
+```
+
+Calls to `append` and `markdown` also queue output until the callback finishes. If a callback both calls `append` or `markdown` and returns a `String`, the queued output is displayed first and the returned string is displayed after it.
+
+Calls to `append_now` are different. They append text and immediately render a frame, so the user can see output while the callback is still running. Use `append_now` for long-running callbacks that should stream progress to the output pane.
+
+At the end of the callback, `Fatty` finishes the command and updates the pager state. Output produced with `append_now` may therefore appear during the callback, while output from `append`, `markdown`, and the callback's return value appears after the callback returns.
+
+
+<a id="org0d9a504"></a>
+
+#### Long-running callbacks and interruption
+
+The `on_accept` callback runs synchronously. While it is running, control does not return to Fatty's normal event loop. A callback that performs lengthy work should therefore provide explicit safe points at which the user may interrupt it:
+
+```ruby
+runner = lambda do |_line, fatty|
+  records.find_each do |record|
+    process(record)
+    fatty.check_interrupt!
+  end
+  fatty.good("Processing complete.")
+end
+```
+
+The `check_interrupt!` method performs a throttled, nonblocking input check. If the user has typed C-c or C-g, it raises `Fatty::Interrupt`. Fatty catches that exception at the callback boundary, finishes the current command cleanly, and returns to the normal input loop.
+
+Calls to `check_interrupt!` should be placed only at points where it is safe to stop the application work. For example, they can go between records, batches, files, or other complete units of work. Fatty does not interrupt callbacks asynchronously and does not stop threads or raise exceptions at arbitrary instructions.
+
+Fast callbacks do not need to call `check_interrupt!`. Long-running callbacks that already update a shared progress facility can often place the check there so that individual commands do not need separate interruption logic.
+
+Code that needs to report interruption before allowing Fatty to perform its normal cleanup may rescue and re-raise the exception:
+
+```ruby
+begin
+  items.each do |item|
+    process(item)
+    fatty.check_interrupt!
+  end
+rescue Fatty::Interrupt
+  fatty.warn("Processing interrupted.", replace: true)
+  raise
+else
+  fatty.good("Processing complete.", replace: true)
+end
+```
+
+
+<a id="org89ae995"></a>
+
+#### ANSI colors in output
+
+Text passed to `append`, `append_now`, `status`, and `alert` may contain ANSI SGR color/style sequences. Fatty interprets those sequences relative to the current theme role, so an ANSI reset returns to the active Fatty role rather than to the terminal's physical default colors. `fatty` includes the nice [`Rainbow` gem](https://github.com/ku1ik/rainbow) for colorizing text as a convenience.
+
+
+<a id="orgce83cdf"></a>
+
+### Other parameters to `Terminal.new`
+
+When building a REPL with `Terminal.new` you can also supply several other parameters:
+
+-   **`prompt:`:** a `String` or a zero-argument callable such as a `Proc` or `lambda` that returns the prompt used for the input line to be edited. Because it can be a callable, it can change after each run of `on_accept`; if not given, it defaults to '> ';
+-   **`app_name`:** the name for the "app" using the `fatty` library; this allows app-specific configuration under `~/.config/fatty/apps/<app_name>` or a different directory specified by `app_config_dir`;
+-   **`app_config_dir`:** an alternative directory for app-specific configuration instead of the default;
+-   **`completion_proc`:** a callable that takes the current text of the input field's buffer and returns an `Array` of possible completions at that point in the input; by default, there is no completion proc;
+-   **`history_path`:** a `String` for the file path where command history is loaded from and saved. The default, `:default`, uses `history.file` from Fatty's configuration, falling back to `~/.fatty_history` if no history file is configured. Passing `nil` or `false` disables persistent history and keeps history in memory only. Passing a string uses that path directly.
+-   **`history_ctx`:** optional history context used to prefer relevant history entries. It may be a hash or a callable returning a hash. The context is stored in the history file with each accepted line and is used by history navigation and history autosuggestions. Matching context entries are preferred, but history is not strictly partitioned; Fatty can still fall back to other entries. This is useful when the same application wants different history behavior in different directories, ledgers, projects, modes, or accounts.
+
+For example, the `fatty` demo executable uses the current working directory as history context:
+
+```ruby
+Fatty::Terminal.new(
+  history_ctx: -> { { pwd: Dir.pwd } },
+  on_accept: ->(line, env) {
+    # ...
+  },
+).go
+```
+
+With that setup, commands entered in `~/src/byr` are favored when the terminal is again in `~/src/byr`, while commands entered elsewhere remain available as fallback history.
+
+
+<a id="orgef3914d"></a>
+
+## The Callback API
+
+Here are the details on the messages that you can send to the callback parameter to the `on_accept` proc.
+
+
+<a id="org1f2fcbb"></a>
+
+### `append(text, follow: true)`
+
+Add the given text to the output pane. After a full page of output is produced, enter paging mode so the user can view the output at leisure and search the output. If `follow` is true, keep the output pane's viewport covering the last lines of output.
+
+
+<a id="org3318ee2"></a>
+
+### `append_now(text, follow: true, mode: nil)`
+
+Like `append`, but display output as it is produced rather than wait for a full page to be produced.
+
+Setting the mode to `:scrolling` or `:paging` determines whether the output is scrolled continuously or paused on each page of output.
+
+
+<a id="org3da5738"></a>
+
+### `markdown(text)`
+
+Render the given text as markdown source according to the current theme then `append` the result to the output pane.
+
+We will not rehearse here how to compose markdown, but one thing that is a bit special with `fatty` is forcing a line break: you should use `<br>` to force a line break in the middle of a line.
+
+```
+This line has a forced line break <br> and this should appear on the next line.
+```
+
+will render as
+
+```
+This line has a forced line break
+and this should appear on the next line.
+```
+
+
+<a id="org5e0ab5d"></a>
+
+### `status(text, role: :info)`
+
+Display the text in the "status" area, the lines immediately above the input field, using one of the following "roles":
+
+-   **:good:** colored to indicate something affirming according to the theme, usually something greenish;
+-   **:info:** colored something neutral simply for informational purposes;
+-   **:warn:** colored something to suggest caution, usually something in the orange to yellow range;
+-   **:error:** colored something to suggest danger, usually some tone of red.
+
+
+<a id="orgd2a8b1b"></a>
+
+### `good(text, replace: false, render: true)`
+
+Display the text in the status area with the role :good.
+
+
+<a id="org8ec7886"></a>
+
+### `info(text, replace: false, render: true)`
+
+Display the text in the status area with the role :info.
+
+
+<a id="org6bb2e02"></a>
+
+### `warn(text, replace: false, render: true)`
+
+Display the text in the status area with the role :warn.
+
+
+<a id="org6040c43"></a>
+
+### `error(text, replace: false, render: true)`
+
+Display the text in the status area with the role :error.
+
+
+<a id="org3e60ade"></a>
+
+### `oops(text, replace: false, render: true)`
+
+An alias for `error(text)`
+
+
+<a id="org5e74284"></a>
+
+### `alert(text, role: :info)`
+
+Display the text in the one-line alert panel just below the input field. In the alert panel, the role only controls the foreground color, not the background.
+
+
+<a id="org71a56a2"></a>
+
+### `prompt(prompt, initial: "", cancel_value: nil, history_key: nil, save_history: true)`
+
+Display a popup dialog box that allows the user to type in any string and return it. Combine the input line with a prompted-for string and shuffle their letters together:
+
+```ruby
+#! /usr/bin/env -S ruby -Ilib
+# -*- mode: ruby -*-
+
+require 'fatty'
+
+weaver = lambda do |line, fatty|
+  str = fatty.prompt("Secondary string to weave in with '#{line}'")
+  (line + str).downcase.gsub(/[^a-z]/, '').split('').shuffle.join
+end
+
+Fatty::Terminal.new(
+  on_accept: weaver,
+  prompt: "Primary String> "
+).go
+```
+
+You can pre-fill the prompt's input line by passing in an `initial:` parameter.
+
+The `prompt` input has its own history facility separate from the history in the main input command line. You can turn it off by setting `save_history` to `false`.
+
+`prompt` returns whatever the user typed and returns `nil` if the user cancels with C-c or C-g unless you specify an alternative `cancel_value`.
+
+
+<a id="orgd0da92b"></a>
+
+### `check_interrupt!`
+
+Provide a cooperative interruption point during a long-running `on_accept` callback. Fatty periodically performs a nonblocking input check and raises `Fatty::Interrupt` if the user has typed C-c or C-g.
+
+The polling is throttled, so `check_interrupt!` may be called frequently. It should nevertheless be called only at points where the callback can safely stop its work.
+
+Fatty catches `Fatty::Interrupt` at the callback boundary, finishes the current command, restores the terminal state, and resumes the normal input loop.
+
+
+<a id="orgfbc8aa5"></a>
+
+### `add_progress(label:, total: nil, style: :percent, role: :info, width: 40)`
+
+Display a progress widget in the status area to show the user that the system is working, not frozen. The `add_progress` method returns a `Progress` object on which the `#update` method can be called to cause it to animate one step. To the left of the widget the `label:` is displayed, followed by the widget. For processes where the total size is known in advance, the `total:` parameter indicates that size. The `role:` parameter controls the styling of the widget. The `width:` parameter places a limit on the size of the widget. `Fatty` supports several styles of progress widgets:
+
+-   **:spinner:** a simple busy-wait indicator that just animates on every call;
+-   **:count:** count up to `total` on each call of `update(current: <count>)`
+-   **:percent:** count up to percent of `total` on each call of `update(current: <count>)`
+-   **:count\_percent:** count up and show percent of `total` on each call of `update(current: <count>)`
+-   **:bar:** display a filling ASCII progress bar with percent and count
+-   **:unicode\_bar:** display a filling Unicode progress bar with percent and count
+-   **:braille\_bar:** display a filling progress bar with percent and count using braille characters
+-   **:trail:** display an "indicator" on each call of `update(indicator: <string>)`
+
+
+<a id="orgd758f7b"></a>
+
+#### Initialization `add_progress(label:, style: :percent, total: nil, role: :info, width: 40)`
+
+-   **`label:`:** Text displayed before the progress widget, "Progress" by default.
+-   **`style:`:** The style of the progress widget from one of those named above.
+-   **`total:`:** For all styles except :trail and :spinner, the number that represents the size of the task. As the `#update` calls increase the value of `current` towards `total`, the widget indicates increasing completion.
+-   **`role:`:** One of :good, :info, :warn, or :error to color the widget according to the theme's idea of these roles. By default, :info.
+-   **`width`:** The number of characters for the full widget display: it is only relevant for the bar styles and the trail style; otherwise it is ignored.
+
+
+<a id="orgbe50f7a"></a>
+
+#### Update `update(current: nil, indicator: nil, render: false)`
+
+You update the progress widget by calling `#update` on the Progress object, passing as the `current:` parameter a number that indicates progress so far.
+
+```ruby
+#! /usr/bin/env -S ruby -Ilib
+# -*- mode: ruby -*-
+
+require 'fatty'
+require 'prime'
+
+primer = lambda do |input, fatty|
+  if input.match?(/\A[1-9]\d*\z/)
+    k = input.to_i
+    prog = fatty.add_progress(label: "Thinking...", total: k, style: :bar)
+    out_line = +""
+    num_primes = 0
+    Prime.each do |p|
+      num_primes += 1
+      out = "#{p} "
+
+      if out_line.length + out.length > 100
+        fatty.append_now("#{out_line}\n", mode: :scrolling)
+        out_line.clear
+      end
+
+      out_line << out
+      prog.update(current: num_primes)
+      break if num_primes >= k
+    end
+    fatty.append_now("#{out_line}\n", mode: :scrolling) unless out_line.empty?
+    prog.finish("Done")
+  else
+    fatty.alert "Give me a positive integer", role: :error
+  end
+end
+
+Fatty::Terminal.new(
+  on_accept: primer,
+  prompt: 'How many primes? ',
+).go
+```
+
+For the trail-style progress, you can use an arbitrary string to indicate progress by adding an `indicator:` parameter to the `#update` call.
+
+Suppose, for example, you wanted to print a trail in which the last digit of the prime is displayed to indicate progress and colored so it stands out:
+
+```ruby
+#! /usr/bin/env -S ruby -Ilib
+# -*- mode: ruby -*-
+
+require 'fatty'
+require 'prime'
+require "rainbow/refinement"
+
+using Rainbow
+
+primer = lambda do |input, fatty|
+  if input.match?(/\A[1-9]\d*\z/)
+    k = input.to_i
+    prog = fatty.add_progress(label: "Thinking...", total: k, style: :trail, width: 100)
+    out_line = +""
+    num_primes = 0
+    Prime.each do |p|
+      num_primes += 1
+      out = "#{p} "
+
+      if out_line.length + out.length > 100
+        fatty.append_now("#{out_line}\n", mode: :scrolling)
+        out_line.clear
+      end
+
+      out_line << out
+      last_dig = p.to_s.split('').last
+      sig =
+        case last_dig
+        when '1'
+          last_dig.red
+        when '3'
+          last_dig.blue
+        when '7'
+          last_dig.green
+        when '9'
+          last_dig.yellow
+        else
+          '!'
+        end
+      prog.update(current: num_primes, indicator: sig)
+      break if num_primes >= k
+    end
+    fatty.append_now("#{out_line}\n", mode: :scrolling) unless out_line.empty?
+    prog.finish("Done")
+  else
+    fatty.alert "Give me a positive integer", role: :error
+  end
+end
+
+Fatty::Terminal.new(
+  on_accept: primer,
+  prompt: 'How many primes? ',
+).go
+```
+
+
+<a id="org058be1b"></a>
+
+#### Finish
+
+As the prior examples illustrate, you can issue an ending message at the end of the process by calling `#finish` on the Progress object.
+
+
+<a id="org22e4b8d"></a>
+
+#### Clear
+
+And, if you have occasion, you can clear the Progress by calling `#clear` on the Progress object.
+
+
+<a id="orgcfb56dd"></a>
+
+### `choose(prompt, choices:, initial_choice_idx: 0, cancel_value: nil)`
+
+Present a set of `choices:`, which can be either:
+
+-   an `Array` of `String` choices, where the selected string is returned; or
+-   a `Hash` whose keys are converted to `String` labels and whose values are returned.
+
+`choose` returns:
+
+-   the selected `String` when `choices:` is an `Array`;
+-   the associated value when `choices:` is a `Hash`; or
+-   `cancel_value` when the user cancels with C-c or C-g.
+
+The `prompt` String (by default "Choose") can guide the user about the purpose of the choices.
+
+If you want to set one of the choices as the initial choice, set `initial_choice_idx:` to the Integer index of one of the choices.
+
+If you want a value associated with the user's cancellation of the chooser with C-c or C-g, set `cancel_value:` to that value.
+
+With an Array of Strings:
+
+```ruby
+#! /usr/bin/env -S ruby -Ilib
+# -*- mode: ruby -*-
+
+require 'fatty'
+
+rgb = lambda do |_line, fatty|
+  color = fatty.choose(
+    "Choose a color",
+    choices: ["red", "green", "blue"],
+  )
+  fatty.status("If you say so: #{Rainbow(color).send(color.to_sym)} it is!\n")
+end
+
+Fatty::Terminal.new(
+  prompt: "Hit RETURN to choose a color> ",
+  on_accept: rgb,
+).go
+```
+
+Or with a Hash:
+
+```ruby
+#! /usr/bin/env -S ruby -Ilib
+# -*- mode: ruby -*-
+
+require 'fatty'
+
+nums = lambda do |_line, fatty|
+  const = fatty.choose(
+    "Choose a constant",
+    choices: { "Pi" => 3.14159, "Euler" => 2.718281828, "Golden Ratio" => 1.61803398875 }
+  )
+  fatty.status("Somewhere around #{const}\n")
+end
+
+Fatty::Terminal.new(
+  prompt: "Hit RETURN to choose a constant> ",
+  on_accept: nums,
+).go
+```
+
+
+<a id="org5b1d7d1"></a>
+
+### `choose_multi(prompt, choices:, cancel_value: nil)`
+
+Present a set of `choices:`, which can either be
+
+-   an Array whose items are converted to `Strings` and presented as choices
+-   a Hash whose keys converted to `Strings` and presented as choices
+
+`choose_multi` returns
+
+-   a `Hash` whose keys and values are the user's selections if `choices:` was an `Array` of `Strings`,
+-   a `Hash` whose keys and values are those selected from the `choices:` `Hash` if `choices:` was an `Hash`,
+-   or the `cancel_value` if the user canceled the selection with C-c or C-g.
+
+The `prompt` String (by default "Choose Many") can guide the user about the purpose of the choices.
+
+
+<a id="org9b37a8e"></a>
+
+### `confirm(prompt, yes_label: "Yes", no_label: "No", cancel_value: false)`
+
+Present the user with a simple Yes/No choice using your choice of ways to express "Yes" or "No" with `yes_label:` and `no_label:`.
+
+`confirm` returns `true` for "Yes" and `false` for "No."
+
+`confirm` will return `false` on cancellation with C-c or C-g unless you provide an alternative `cancel_value:`, in which case it returns that.
+
+
+<a id="org8d63dae"></a>
+
+### `menu(prompt, choices:, initial_choice_idx: 0, cancel_value: nil)`
+
+Present the user with a set of `choices:` representing actions to execute.
+
+`choices:` is a `Hash` whose keys are labels presented to the user and whose values are procs, lambdas, or other objects that respond to `#call`.
+
+```ruby
+#! /usr/bin/env -S ruby -Ilib
+# -*- mode: ruby -*-
+
+require 'fatty'
+
+asker = lambda do |_line, fatty|
+  result = fatty.menu(
+    "Pick an action",
+    choices: {
+      "Self Echo" => ->(fatty, label) {
+        fatty.append("You chose #{label}\n")
+        :echoed
+      },
+      "Say Hello" => ->(fatty, _label) {
+        name = fatty.prompt("Name?")
+        fatty.append("Hello, #{name}\n")
+        :greeted
+      },
+    },
+  )
+  fatty.good(result)
+end
+
+Fatty::Terminal.new(
+  on_accept: asker,
+  prompt: "Type RETURN for some action> ",
+).go
+```
+
+Each callable has access to the `CallbackEnvironment`, called `fatty` here and the `String` label that the user selected.
+
+Each callable can return a value that the `@on_accept` proc can process as it pleases. In the example, they are printed to the status area.
+
+If you want to set one of the choices as the initial choice, set `initial_choice_idx:` to the Integer index of one of the choices.
+
+If you want a value associated with the user's cancellation of the chooser with C-c or C-g, set `cancel_value:` to that value.
+
+
+<a id="org1750b9e"></a>
+
+### `environment`
+
+This returns a `Hash` of runtime conditions detected by `Fatty`:
+
+| Key                   | Description                                          |
+|--------------------- |---------------------------------------------------- |
+| `:arch`               | System CPU architecture, e.g., `x86_64`              |
+| `:os`                 | Operating system detected                            |
+| `:ruby_platform`      | Ruby platform, e.g., `x86_64-linux`                  |
+| `:screen`             | Whether the terminal is running under `screen`       |
+| `:ssh`                | Whether the terminal is running under SSH            |
+| `:tmux`               | Whether the terminal is running under `tmux`         |
+| `:terminal`           | Detected underlying terminal, e.g., `kitty`          |
+| `:terminal_version`   | Version of the terminal, if known                    |
+| `:term`               | The `TERM` terminal type                             |
+| `:truecolor_detected` | Whether truecolor capability appears to be available |
+| `:truecolor_enabled`  | Whether Fatty is actually using truecolor rendering  |
+| `:curses`             | Runtime curses capabilities and parameters           |
+
+The environment report also includes a nested `:curses` hash:
+
+| Key                 | Description                                          |
+|------------------- |---------------------------------------------------- |
+| `:started`          | Whether curses has been initialized                  |
+| `:truecolor`        | Whether the active curses context is using truecolor |
+| `:key_min`          | Lowest keycode with a curses name                    |
+| `:key_max`          | Highest keycode with a curses name                   |
+| `:lines`            | Number of terminal rows available                    |
+| `:cols`             | Number of terminal columns available                 |
+| `:has_colors`       | Whether curses reports color support                 |
+| `:colors`           | Number of colors available to curses                 |
+| `:color_pairs`      | Number of color pairs available to curses            |
+| `:can_change_color` | Whether curses can redefine color values             |
+
+
+<a id="org727ceaf"></a>
+
+# Default Interaction
+
+
+<a id="orgd560bdc"></a>
+
+## Parts of the Screen
+
+
+<a id="org6ae09c7"></a>
+
+### Input Field
+
+Just above the bottom of the screen where all the action takes place: it is a line for editing the input. It displays a prompt followed by an area in which you build the command line using `fatty's` editing facilities.
+
+
+<a id="org73b9106"></a>
+
+### Output Pane
+
+Most of the top part of the screen is reserved for displaying whatever output is sent to it with the `on_accept` callback to the `Terminal`. It can render colored ANSI-encoded strings and will page long output so you can view it a page at a time and even search the output.
+
+
+<a id="orga48a015"></a>
+
+### Status Area
+
+The one to four lines just above the Input Field that displays output to the user that is out of band for the Output Pane. Brief messages of confirmation, warning, or error can be displayed there so as to get the user's immediate attention. Progress bars also render there where their visibility is made prominent.
+
+
+<a id="org5098d11"></a>
+
+### Alert Area
+
+Alerts are short-lived, non-scrolling messages shown below the input field. They are intended for user-visible conditions that require attention. `Fatty` uses this area to warn the user of unrecognized key codes and of unbound key presses.
+
+
+<a id="org2926c89"></a>
+
+## Command-line Editing
+
+`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&#x2014;at least not yet. Maybe some day.
+
+
+<a id="orgbcdaaad"></a>
+
+### Input Context
+
+When editing the input line or text input for widgets like the \`prompt\`, \`fatty\` provides emacs-like editing keybindings by default. Many of these commands can take a count prefix argument to repeat the command count times. For example, \`M-8 M-0 #\` will insert 80 '#' characters at the cursor.
+
+
+<a id="org1af96be"></a>
+
+#### Cursor Motion
+
+`Fatty` implements all the expected actions for moving the cursor around the input buffer. You can move by characters or words or to the beginning or end of the buffer.
+
+| Key      | Description                       |
+|-------- |--------------------------------- |
+| C-a      | move to the beginning of the line |
+| :home    | move to the beginning of the line |
+| C-e      | move to the end of the line       |
+| :end     | move to the end of the line       |
+| C-f      | move cursor right one character   |
+| :right   | move cursor right one character   |
+| C-b      | move cursor left one character    |
+| :left    | move cursor left one character    |
+| M-f      | move cursor right one word        |
+| M-:right | move cursor right one word        |
+| C-:right | move cursor right one word        |
+| M-b      | move cursor left one word         |
+| M-:left  | move cursor left one word         |
+| C-:left  | move cursor left one word         |
+
+
+<a id="org32a2afa"></a>
+
+#### Clearing
+
+This is one action that does not affect the input buffer but the output pane. It clears it.
+
+| Key | Description           |
+|--- |--------------------- |
+| C-l | clear the output pane |
+
+
+<a id="org72cce5e"></a>
+
+#### Undo and Redo
+
+`Fatty` keeps a stack of buffer-modifying actions, recording the buffer contents before any change is made. The undo-redo facility allows you to traverse that stack, `undo` travels backward to an earlier buffer state, and, once at an earlier state, `redo` travels forward to a more recent buffer state.
+
+| Key   | Description |
+|----- |----------- |
+| C-/   | undo        |
+| C-\_  | undo        |
+| C-M-/ | redo        |
+| M-/   | redo        |
+
+
+<a id="org5ac8fea"></a>
+
+#### Deletion and Killing
+
+`Fatty` implements the emacs-esque notion of "killing" text by deleting it but also adding it to the "kill ring", a circular structure of all prior kills. It is circular in that successive "yanks", or pastes, traverse the kill ring and return to the beginning after reaching the end. By contrast a "deletion" merely removes text from the buffer without adding it to the kill ring.
+
+When the region is active, destructive editing commands kill the region rather than deleting characters or words.
+
+| Key        | Description                    |
+|---------- |------------------------------ |
+| C-d        | delete character at cursor     |
+| :delete    | delete character at cursor     |
+| :backspace | delete character before cursor |
+| M-d        | kill word at cursor            |
+| C-w        | kill word before cursor        |
+| C-k        | kill to end of line            |
+| C-t        | transpose characters           |
+| M-t        | transpose words                |
+
+
+<a id="org948d8d5"></a>
+
+#### Yanking, Mark, and Region
+
+Text that has been killed can be "yanked" into the buffer at the cursor position with the "yank" action. That text can be replaced by successive entries in the kill ring with the yank\_pop action.
+
+In addition, `fatty` allows you to define a "region" by setting a mark and moving the cursor. The text between the mark and the cursor is the region. The region can be killed or copied, that is deleted and added to the kill ring or just added to the kill ring.
+
+Notice that commands that normally delete characters or words, kill the region if the region is active.
+
+| Key        | Description                                       |
+|---------- |------------------------------------------------- |
+| C-y        | yank last kill at the cursor                      |
+| M-y        | replace last yank with next item in the kill ring |
+|            |                                                   |
+| C-d        | when region active, kill the region               |
+| :delete    | when region active, kill the region               |
+| :backspace | when region active, kill the region               |
+| M-d        | when region active, kill the region               |
+| C-w        | when region active, kill the region               |
+|            |                                                   |
+| C-:space   | set the mark at the current cursor position       |
+| C-@        | set the mark at the current cursor position       |
+| C-g        | clear the mark                                    |
+| C-w        | kill the region                                   |
+| M-w        | copy the region                                   |
+
+
+<a id="orgb998032"></a>
+
+#### Count Prefix
+
+By default each action acts on one item, so the default count is 1. But for certain commands that operate on characters or words, you can modify the count by typing `M-<digit>` keys before the command. For example, if you want to insert exactly 80 '#' characters into the buffer, `M-8 M-0 #` will do the trick.
+
+There is one command, however, for which the count is not used as a repeat count: for `page_top` (bound in paging to `g`) the count is used as a line number to navigate to.
+
+Fatty follows the emacs convention of making `C-u` multiply the count prefix by 4 with each press. So you can insert 64 '#' characters with `C-u C-u C-u #`.
+
+| Key       | Description                                        |
+|--------- |-------------------------------------------------- |
+| C-u       | universal count argument (times 4 with each press) |
+| M-<digit> | accumulate a count argument                        |
+
+
+<a id="org30cf355"></a>
+
+#### History Navigation
+
+`Fatty` sports a rather sophisticated history system. It not only records each completed item of input but can also be made to note the kind of items and the "context" in which it was entered.
+
+History is essentially partitioned into separate "kinds" of history so that the command line can occupy one part of history and search strings a different part of history. That way, the history is made relevant to the current input buffer that you are working on.
+
+In addition, each history item can note its "context". This is less strict than "kinds" of history but allows the history mechanism to favor history items from the same "context" as the current context. For example, in the `fatty` demo, any line that is not a builtin command is treated as a shell
+
+if you traverse history items, you will be shown command executed from the directory you are in before other history items. It still will give you items from other contexts, it just pushes items from the current context to the front of the list.
+
+You can navigate history items with the `up` and `down` keys as you would expect. But you can also have the history items presented in a popup that shows all history items then allows you to narrow the items displayed by typing text into its narrowing input field. Bonus: the narrowing input field itself has a history that you can access with `M-p` and `M-n`. History on history.
+
+| Key   | Description                                  |
+|----- |-------------------------------------------- |
+| C-p   | replace the line with the prior history item |
+| :up   | replace the line with the prior history item |
+| C-n   | replace the line with the next history item  |
+| :down | replace the line with the next history item  |
+| C-r   | search the history in a popup                |
+
+
+<a id="org0c995ec"></a>
+
+#### Completion
+
+`Fatty` also provides a completion facility that makes entering input easier.
+
+1.  Input Completion
+
+    As you type a command-line, `fatty` will auto-suggest ways to complete the line with dimmed text to the right of the cursor:
+    
+    ![img](images/auto_suggest.png)
+    
+    After typing 'ec' `fatty` suggests a command-line pulled from history using the dimmed text to the right of the cursor. The suggestion can be accepted by moving the cursor into the suggestion, and any text then to the left of the cursor becomes part of the input buffer.
+    
+    `fatty` may have several completions suggested by the text-so-far and you can cycle through them by hitting the `tab` key. And if you want, you can see all the suggestions in a popup with `M-tab`. That allows narrowing by the text of the completions and the narrowing filter has its own history.
+    
+    ![img](images/completion_popup.png)
+
+2.  Sources for Input Completion
+
+    For input completion, `fatty` uses two sources:
+    
+    1.  The input history.
+    2.  The candidates returned by the `Terminal#completion_proc`.
+    
+    History completion is always available when the terminal has history enabled. It lets the user complete from lines they have previously accepted. This is especially useful for command shells, REPL-style interfaces, and applications where users often repeat or slightly modify earlier input.
+    
+    Application completion is supplied by the optional `completion_proc` passed to `Fatty::Terminal.new`. The proc is called with the input buffer's text-so-far and returns candidate strings. This is where an application can offer completions for commands, file names, account names, option names, object identifiers, or anything else meaningful to the application.
+    
+    The two sources are combined before they are presented to the user. Fatty deduplicates candidates and then offers the result through the normal completion interface. `TAB` cycles through completions inline. `M-TAB` opens a completion popup, where the user can narrow the candidate list by typing in the `Complete:` field.
+    
+    Application candidates are offered first. History candidates fill in behind them. This gives the host application priority for current, domain-specific completions while still letting users recover earlier accepted input.
+    
+    The completion popup is still a popup filter. Its narrowing text has its own history, separate from command input history and from other popup filters. Use `M-p` and `M-n` inside the completion popup to recall previous completion filters.
+
+3.  File Name Completion
+
+    Apart from command-line completion, `fatty` offers completion of file names if the cursor is at the end of a string that looks like a file name: that is, it starts with './', '../', '~/' or '/'.
+    
+    1.  If the string-so-far matches only one directory or file name, it inserts that into the input buffer and continues completion from there.
+    2.  If the string-so-far matches multiple files or directories it auto-suggests the first and `TAB` cycles through each of the candidates which you can accept by moving the cursor past the suggestion. Likewise `S-TAB` cycles backwards through the list of candidates.
+    3.  If the string-so-far matches no files, completion does nothing.
+    
+    Just as with command line completion, you can invoke a popup of completions with `M-TAB` and a popup of possible file names will appear within which you may filter the candidates down by narrowing. Unlike other forms of completion, the file name completion popup allows you to fill out the path by navigating directories within the popup by hitting `TAB` or `right` to descend into a sub-directory or `S-TAB` or `left` to ascend to the parent directory. The popup title shows the path so far.
+
+
+<a id="orgf4edfcc"></a>
+
+#### Accept or Cancel
+
+Finally, when the command-line is to your satisfaction, you can submit the line to the `on_accept` proc which determines how your app responds to it.
+
+You can end a `fatty` session with `C-c` at the command line, or (only if the buffer is empty) with `C-d`.
+
+| Key      | Description                                            |
+|-------- |------------------------------------------------------ |
+| :enter   | feed the line to the on\_accept proc and page output   |
+| M-:enter | feed the line to the on\_accept proc and scroll output |
+| C-c      | quit \`fatty\`                                         |
+| C-d      | quit \`fatty\` only if the input line is empty         |
+
+
+<a id="org8d58d09"></a>
+
+### Paging Context
+
+Once the command-line is accepted, \`fatty\` sends output to the large output pane, and if the output is more than one screen long presents a paging environment for viewing and searching the output. From there, `fatty` offers the expected navigation aids for examining the output:
+
+| Key         | Count? | Description                                         |
+|----------- |------ |--------------------------------------------------- |
+| `up`        | Yes    | move output one line up                             |
+| `k`         | Yes    | move output one line up                             |
+| `down`      | Yes    | move output one line down                           |
+| `j`         | Yes    | move output one line down                           |
+| `page_up`   | Yes    | move back one page                                  |
+| `b`         | Yes    | move back one page                                  |
+| `u`         | Yes    | move back one page                                  |
+| `M-v`       | Yes    | move back one page                                  |
+| `backspace` | Yes    | move back one page                                  |
+| `page_down` | Yes    | move forward one page                               |
+| `f`         | Yes    | move forward one page                               |
+| `d`         | Yes    | move forward one page                               |
+| `space`     | Yes    | move forward one page                               |
+| `C-v`       | Yes    | move forward one page                               |
+| `home`      | No     | move to the top of output                           |
+| `M-<`       | No     | move to the top of output                           |
+| `g`         | Yes    | move to the top, or to the counted original line\*  |
+| `end`       | No     | move to the end of output                           |
+| `M->`       | No     | move to the end of output                           |
+| `G`         | No     | move to the end of output                           |
+| `=`         | No     | toggle the display of line numbers                  |
+| `M-s`       | No     | toggle between paging and scrolling                 |
+| `/`         | No     | initiate a fixed-string search forward              |
+| `?`         | No     | initiate a fixed-string search backward             |
+| `C-s`       | No     | initiate an Isearch session forward                 |
+| `C-r`       | No     | initiate an Isearch session backward                |
+| `C-M-s`     | No     | initiate an Regexp session forward                  |
+| `C-M-r`     | No     | initiate an Regexp session backward                 |
+| `C-/`       | No     | initiate an Regexp session forward                  |
+| `<`         | No     | narrow output to lines containing all entered terms |
+| `>`         | No     | widen output by clearing the narrowing              |
+| `C-c`       | No     | quit paging                                         |
+| `q`         | No     | quit paging                                         |
+| `C-g`       | No     | quit paging                                         |
+| `escape`    | No     | quit paging                                         |
+| `n`         | Yes    | move to the next instance of the current search     |
+| `N`         | Yes    | move to the prior instance of the current search    |
+
+`*` Without a count, `g` moves to the beginning of output. With a numeric prefix, it moves to that original output line; for example, `M-1 M-0 M-0 M-0 g` moves to line 1000. It uses the original line numbers even when output is narrowed.
+
+As you can see, `fatty` tries to accommodate a number of finger habits besides `emacs`, including `vim` and `Emacs Info`, by offering several alternative ways to invoke navigation actions.
+
+One unusual action is invoked by `M-s` which toggles the output between scrolling mode without pause and paging mode. It can be invoked while doing either to enter the other mode.
+
+You can add line numbers to the display while paging by using the `=` key.
+
+You can also "narrow" the output with `<`, which will prompt you for one or more terms to match. The output will then show only lines that match all the terms typed. To return to the full output, "widen" with `>`.
+
+
+<a id="org89f3027"></a>
+
+### Searching Output
+
+While paging, you can initiate a search of the output as indicated in the above key bindings for paging. Once a search session is initiated, `fatty` presents an input line for entering search terms.
+
+After a search session has ended, `fatty` returns to paging but remembers the last search term and allows navigation among them with `n` and `N`: `n` searches in the direction of the last search and `N` searches in the opposite direction. Notice that the current search term and direction are added to the paging bar after the information on your location within the output.
 
-<a id="orga462d10"></a>
 
-# Introduction
+<a id="org77137d8"></a>
+
+#### String and Regex Search
+
+`/` and `?` prompt for a fixed string and search forward or backward. `C-M-s` (or `C-/`) and `C-M-r` (or `C-?`) perform the corresponding regular-expression searches. Accepting the search leaves the selected match active for later navigation with `n` and `N`.
+
+
+<a id="orgd90c796"></a>
+
+#### Incremental Search
+
+`C-s` and `C-r` begin forward or backward incremental search. The output moves to matching text as the search term is edited. Accepting commits the match; canceling restores the output position from before the search began.
+
+
+<a id="orgc8458e1"></a>
+
+# Configuration
+
+When a Fatty application starts, Fatty installs default configuration files under `~/.config/fatty` if they do not already exist. Fatty does not overwrite files that are already there, so you can edit these files directly and keep them under version control.
+
+The config files are:
+
+-   **`config.yml`:** general configuration;
+-   **`keydefs.yml`:** terminal-specific keycode naming;
+-   **`keybindings.yml`:** user-defined keybindings;
+-   **`themes/`:** YAML theme files.
+
+The default user-specific configuration directory follows `XDG_CONFIG_HOME` if it is set. Otherwise it is `~/.config/fatty`.
+
+In addition to the user-specific configuration, fatty will read app-specific configuration files from `~/.config/fatty/apps/<app_name>` if `Terminal` was given an `app_name` parameter. It will use a different directory of your choosing if `Terminal` was given an `app_config_dir` directory name.
+
+
+<a id="org0add8c9"></a>
+
+## General Configuration `config.yml`
+
+`config.yml` controls general behavior such as word movement, ESC handling, logging, history, the initial theme, and truecolor rendering.
+
+A small configuration might look like this:
+
+```yaml
+word_char_re: "[[:alnum:]_.:-]"
+
+esc_delay: 0
+
+history:
+  file: "~/.fatty_history"
+  max: 10000
+
+theme: wordperfect
+
+truecolor: auto
+```
+
+
+<a id="org1099eb8"></a>
+
+### `word_char_re`
+
+This setting is a Ruby regular expression fragment used to decide what counts as a word in the input buffer. It must be a `String` representing a `Regexp` that matches a single character that is meant to be a part of a "word" for purposes of cursor movement. The default setting treats letters, digits, and underscore as word characters:
+
+```yaml
+word_char_re: "[[:alnum:]_]"
+```
+
+For command-line applications, you may want dashes to be part of a word:
+
+```yaml
+word_char_re: "[[:alnum:]_-]"
+```
+
+For Ruby constants, hostnames, or command-like tokens, you may want a broader definition:
+
+```yaml
+word_char_re: "[[:alnum:]_.:-]"
+```
+
+
+<a id="orgce3e466"></a>
+
+### `esc_delay`
+
+`esc_delay` controls how long curses waits after receiving `ESC` before deciding whether another key is part of the same Meta-key sequence. The value is in milliseconds.
+
+```yaml
+esc_delay: 0
+```
+
+
+<a id="org95b5e48"></a>
+
+### `history`
+
+
+<a id="orgdc30f58"></a>
+
+#### `file`
+
+The path to the history file to use, by default `~/.fatty_history`
+
+
+<a id="org0941468"></a>
+
+#### `max`
+
+The maximum number of lines of history retained, by default 10,000.
+
+
+<a id="orgce1b37d"></a>
+
+### `theme`
+
+The `theme` setting names the theme Fatty applies at startup:
+
+```yaml
+theme: nordic
+```
+
+
+<a id="orgdd529bd"></a>
+
+### `truecolor`
+
+The `truecolor` setting controls whether Fatty uses truecolor escape sequences for rendering colors. The usual setting is `auto`, meaning that `truecolor` is enabled if available. It can be set to `true`, `false`, `on`, `off` or `auto`.
+
+```yaml
+truecolor: auto
+```
+
+
+<a id="org2b58449"></a>
+
+### `log`
+
+Logging is configured under `log`:
+
+```yaml
+log:
+file: "~/log/fatty.log"
+level: debug
+tags:
+  - keycode
+  - keyevent
+  - keybinding
+  - action
+  - command
+  - session
+  - render
+  - perf
+```
+
+
+<a id="org0e3b938"></a>
+
+#### `file`
+
+The path to the log file to use.
+
+
+<a id="org9c70445"></a>
+
+#### `level`
+
+Can be one of the following
+
+-   **`info`:** only informational messages
+-   **`warn`:** only non-fatal warning messages and `info` messages
+-   **`error`:** only fatal error messages and `warn` and `info` messages
+-   **`debug`:** detailed messages to assist debugging `fatty` plus all of the above.
+
+
+<a id="orge47f304"></a>
+
+#### `tags`
+
+`log.tags` controls which tagged log messages are written. Tags are ordinary symbolic labels used by Fatty's logging calls; they are not checked against a fixed registry. A tag is useful if Fatty logs messages with that tag.
+
+The special tag `all` enables all tagged log messages except `perf`. Performance logging is intentionally noisy and must be enabled explicitly with `perf`.
+
+```yaml
+log:
+tags:
+- keycode
+- keybinding
+- render
+- perf
+```
+
+
+<a id="org220de42"></a>
+
+## Key code definitions `keydefs.yml`
+
+Most keys are named correctly by curses. Some terminal emulators, multiplexers, or keyboard modes emit numeric keycodes that curses does not name usefully. The `keydefs.yml` file lets you assign names and modifiers to those numeric codes.
+
+When Fatty runs inside `tmux`, key definitions are looked up under `tmux`, not under the outer terminal emulator. `tmux` translates the outer terminal's input before Fatty sees it, so keycodes observed inside `tmux` may differ from keycodes observed directly under GNOME Terminal, Kitty, Alacritty, or another terminal. Use `keytest` in the same environment where the application will normally run. The same comment applies to `screen`.
+
+A key definition is terminal-specific. For example:
+
+```yaml
+tmux:
+  555:
+    key: left
+    meta: true
+  570:
+    key: right
+    meta: true
+  557:
+    key: left
+    ctrl: true
+  572:
+    key: right
+    ctrl: true
+```
+
+This says that, when Fatty detects that the terminal is `tmux`, curses keycode `555` should be treated as `M-left`, keycode `570` as `M-right`, and so on.
+
+The demo executable has a `keytest` command that is useful when building this file. Run `fatty`, use the `keytest` command, press the key you want to identify, and add an entry for the numeric code if Fatty does not already know what to call it.
+
+Here is what I found running `keytest` on a variety of popular terminals to determine how each reported `PageDown`, `C-PageDown`, `M-PageDown`, and `C-M-PageDown`:
+
+| Terminal       | Key Pressed | Ctrl? | Meta? | Code   | Status            |
+|-------------- |----------- |----- |----- |------ |----------------- |
+| gnome-terminal | PageDown    | no    | no    | 338    | Defined and bound |
+| gnome-terminal | PageDown    | yes   | no    | 559    | Undefined         |
+| gnome-terminal | PageDown    | no    | yes   | 557    | Undefined         |
+| gnome-terminal | PageDown    | yes   | yes   | 561    | Undefined         |
+| alacritty      | PageDown    | no    | no    | 338    | Defined and bound |
+| alacritty      | PageDown    | yes   | no    | 559    | Undefined         |
+| alacritty      | PageDown    | no    | yes   | 557    | Undefined         |
+| alacritty      | PageDown    | yes   | yes   | 561    | Undefined         |
+| kitty          | PageDown    | no    | no    | 338    | Defined and bound |
+| kitty          | PageDown    | yes   | no    | 565    | Undefined         |
+| kitty          | PageDown    | no    | yes   | 563    | Undefined         |
+| kitty          | PageDown    | yes   | yes   | 567    | Undefined         |
+| terminator     | PageDown    | no    | no    | 338    | Defined and bound |
+| terminator     | PageDown    | yes   | no    | <none> | Undefinable       |
+| terminator     | PageDown    | no    | yes   | 557    | Undefined         |
+| terminator     | PageDown    | yes   | yes   | 561    | Undefined         |
+| ghostty        | PageDown    | no    | no    | 338    | Defined and bound |
+| ghostty        | PageDown    | yes   | no    | 564    | Undefined         |
+| ghostty        | PageDown    | no    | yes   | 562    | Undefined         |
+| ghostty        | PageDown    | yes   | yes   | 566    | Undefined         |
+| konsole        | PageDown    | no    | no    | 338    | Defined and bound |
+| konsole        | PageDown    | yes   | no    | 559    | Undefined         |
+| konsole        | PageDown    | no    | yes   | 557    | Undefined         |
+| konsole        | PageDown    | yes   | yes   | 561    | Undefined         |
+
+I could turn this into a `keydefs.yml` file that would allow me to define all those keys:
+
+```yaml
+gnome-terminal:
+  559:
+    key: page_down
+    ctrl: true
+  557:
+    key: page_down
+    meta: true
+  561:
+    key: page_down
+    ctrl: true
+    meta: true
+
+alacritty:
+  559:
+    key: page_down
+    ctrl: true
+  557:
+    key: page_down
+    meta: true
+  561:
+    key: page_down
+    ctrl: true
+    meta: true
+
+kitty:
+  565:
+    key: page_down
+    ctrl: true
+  563:
+    key: page_down
+    meta: true
+  567:
+    key: page_down
+    ctrl: true
+    meta: true
+
+terminator:
+  # 559:
+  #   key: page_down
+  #   ctrl: true
+  557:
+    key: page_down
+    meta: true
+  561:
+    key: page_down
+    ctrl: true
+    meta: true
+
+ghostty:
+  564:
+    key: page_down
+    ctrl: true
+  562:
+    key: page_down
+    meta: true
+  566:
+    key: page_down
+    ctrl: true
+    meta: true
+
+konsole:
+  559:
+    key: page_down
+    ctrl: true
+  557:
+    key: page_down
+    meta: true
+  561:
+    key: page_down
+    ctrl: true
+    meta: true
+```
+
+After installing that keydefs, I find that the PageDown variants are all recognized by name and modifiers (except for the strange failure of `terminator` to recognize `C-PageDown`!).
+
+
+<a id="orgbd79429"></a>
+
+## Key bindings  `keybindings.yml`
+
+Fatty has built-in Emacs-style bindings for ordinary input editing, history, completion, popup navigation, and paging. The `keybindings.yml` file lets you add or override bindings without changing Ruby code.
+
+A keybinding names a key chord, the context in which it applies, and the Fatty action to run:
+
+```yaml
+- key: left
+  meta: true
+  action: move_word_left
+
+- key: right
+  meta: true
+  action: move_word_right
+
+- key: space
+  context: paging
+  action: page_down
+
+- key: backspace
+  context: paging
+  action: page_up
+```
+
+
+<a id="org698f2a9"></a>
+
+### Key Names
+
+A keybinding uses the unmodified key name under the `key` field:
+
+```yaml
+- key: f
+  meta: true
+  context: text
+  action: move_word_right
+```
+
+
+<a id="org58581e4"></a>
+
+#### Printable Keys
+
+Most printable keys can be written as the character itself. Quote keys that YAML might otherwise treat specially or make hard to read, such as `":"`, `"#"`, `"["`, `"]"`, `"{"`, `"}"`, `"\""`, and `"\\"`.
+
+```yaml
+- key: a
+- key: /
+- key: .
+- key: =
+- key: "\\"
+- key: "\""
+```
+
+
+<a id="org4b0cf5b"></a>
+
+#### Curses and Fatty Named Keys
+
+`Fatty` translates codes returned by curses for special keys into names:
+
+|                |                |                 |                   |                |
+|-------------- |-------------- |--------------- |----------------- |-------------- |
+| `tab`          | `insert`       | `delete`        | `home`            | `end`          |
+| `left`         | `right`        | `page_up`       | `page_down`       | `up`           |
+| `down`         | `f1`           | `f2`            | `f3`              | `f4`           |
+| `f8`           | `f9`           | `f10`           | `f11`             | `f12`          |
+| `keypad_0`     | `keypad_1`     | `keypad_2`      | `keypad_3`        | `keypad_4`     |
+| `keypad_8`     | `keypad_9`     | `keypad_divide` | `keypad_multiply` | `keypad_minus` |
+| `keypad_enter` | `keypad_comma` |                 |                   |                |
+
+Some terminals can report application-keypad sequences such as `keypad_divide`, `keypad_multiply`, or `keypad_enter`, but numeric keypad digits are often not distinguishable from ordinary digits when NumLock is on, and are often reported as navigation keys such as `end`, `down`, `page_down`, or `left` when NumLock is off. Use `keytest` to see what your terminal actually sends.
+
+`Fatty` also provides convenient names to other common keys:
+
+-   `enter`,
+-   `escape`, and
+-   `space`
+
+
+<a id="orgeab9ebe"></a>
+
+#### Possibly Invisible Keys
+
+Some physical keys may never reach Fatty at all. They may be handled by the keyboard firmware, the kernel, the desktop environment, the window manager, or the terminal emulator before curses can report them. Common examples include `Print Screen`, `Scroll Lock`, `Pause/Break`, `Caps Lock`, `Num Lock`, `Fn`, `Menu/Application`, `Super/Windows`, power/sleep/wake keys, brightness keys, volume/media keys, keyboard-backlight keys, airplane-mode keys, and touchpad toggle keys.
+
+Use `keytest` to check. If Fatty sees a key as a raw numeric code, you can name it in `keydefs.yml` and bind it. If `keytest` shows nothing, the key is being intercepted before Fatty receives it.
+
+
+<a id="orgde02d1d"></a>
+
+#### Unnamed but Recognized Keys
+
+Some terminals report modified special keys as distinct numeric keycodes that `fatty` and `curses` do not name. Use `keytest` to discover those codes, then assign names to them in `keydefs.yml`. The name can be one of Fatty's usual names, or a new name of your own.
+
+For example, if a keyboard has an extra thumb key and `keytest` reports it as an uncoded keycode `601`, you could name it:
+
+```yaml
+gnome-terminal:
+  601:
+    key: thumb_left
+```
+
+Then bind it in `keybindings.yml`:
+
+```yaml
+- key: thumb_left
+  context: text
+  action: move_word_left
+```
+
+Fatty does not require custom key names to come from a fixed registry. A custom name only needs to be used consistently between `keydefs.yml` and `keybindings.yml`.
+
+
+<a id="orge487bc7"></a>
+
+### Mouse Events
+
+Mouse events can also be bound:
+
+```yaml
+- button: left_clicked
+  context: popup
+  action: choose
+```
+
+Recognized mouse button names include:
+
+```org
+left_pressed
+left_released
+left_clicked
+left_double_clicked
+left_triple_clicked
+middle_pressed
+middle_released
+middle_clicked
+middle_double_clicked
+middle_triple_clicked
+right_pressed
+right_released
+right_clicked
+right_double_clicked
+right_triple_clicked
+scroll_up
+scroll_down
+```
+
+
+<a id="orgcf36a39"></a>
+
+### Modifiers
+
+A binding may include these modifiers:
+
+```yaml
+ctrl: true
+meta: true
+shift: true
+```
+
+
+<a id="orgc29aad9"></a>
+
+### Contexts
+
+In `Fatty`, the key map is partitioned by "contexts" and in different environments the contexts are tried in order from highest priority to lowest and the first binding found wins. The following table lists the contexts associated with each interaction environment:
+
+| Environment        | Contexts High to Low                    |
+|------------------ |--------------------------------------- |
+| Input Field        | :input, :text, :terminal                |
+| Output Paging      | :paging, :terminal                      |
+| Output Scrolling   | :terminal                               |
+| String Search      | :search, :text, :terminal               |
+| Incremental Search | :isearch, :text, :terminal              |
+| Prompt Popup       | :prompt, :text, :terminal               |
+| Popup Choose       | :popup, :text, :terminal                |
+| Popup Multi-Choose | :popup\_multi, :popup, :text, :terminal |
+
+The available contexts are:
+
+| Context        | Meaning                                               |
+|-------------- |----------------------------------------------------- |
+| `:terminal`    | global terminal/session commands                      |
+| `:text`        | ordinary text-editing commands shared by input fields |
+| `:input`       | the main command input field                          |
+| `:paging`      | output pager navigation                               |
+| `:search`      | non-incremental search field                          |
+| `:isearch`     | incremental search field                              |
+| `:prompt`      | prompt popup input                                    |
+| `:popup`       | popup selection/navigation                            |
+| `:popup_multi` | multi-select popup behavior                           |
+
+The \`:terminal\` context is the lowest-priority fallback context for terminal-wide commands. It is where Fatty puts bindings that are not specific to text editing, paging, search, or popup selection, such as theme selection, key testing, and quitting. Because \`:terminal\` is searched last, any more specific context can override a terminal-wide binding.
+
+
+<a id="orgdb5aa78"></a>
+
+### Actions
+
+A keybinding connects a key event in a context to an "action." An action is a named Fatty command such as \`move\_left\`, \`delete\_backward\`, \`accept\_line\`, \`page\_down\`, \`choose\_theme\`, or \`quit\`.
+
+A binding entry names the action with the \`action\` field:
+
+```yaml
+- key: left
+  context: text
+  action: move_left
+
+- key: f
+  meta: true
+  context: text
+  action: move_word_right
+
+- key: page_down
+  context: paging
+  action: page_down
+```
+
+Most movement, deletion, history, completion, paging, and popup-navigation actions honor Fatty's numeric count argument. The count is entered before the command, Emacs-style. For example, `M-5 C-f` moves forward five characters if `C-f` is bound to move\_right, and `M-3 C-n` moves down three items if `C-n` is bound to the current environment's `next-item` action.
+
+Use \`keytest\` to check what action is currently bound to a key. If a key is bound, \`keytest\` reports the matching context, action name, arguments, and the object that handles the action.
+
+
+<a id="orgf51a408"></a>
+
+#### Input buffer actions
+
+Input buffer actions edit the contents of a text buffer. These are the ordinary line-editing operations shared by the main input field, search fields, prompt popups, and other text-like interactions. Many of these actions honor the numeric prefix count.
+
+Terminology notes:
+
+-   **kill ring:** like emacs, `fatty` keeps a "clipboard" of items with the newest item in the current position and older items "before" it but in a "ring" that return to the beginning;
+-   **yank:** retrieve the most recent item from the kill ring
+-   **yank pop:** retrieve successively older items from the kill ring
+-   **delete:** removes text without copying it to the kill ring;
+-   **kill:** removes text and copies it to the kill ring for later yank;
+-   **word:** a sequence of contiguous characters that are each matched by the `word_char_re` from the config file or "[[:alnum]\_]" by default;
+
+| Action Name            | Count? | Description                                |
+|---------------------- |------ |------------------------------------------ |
+| bol                    | No     | Move cursor to beginning of buffer         |
+| clear                  | No     | Clear the buffer                           |
+| clear\_mark            | No     | Clear the region mark                      |
+| copy\_region           | No     | Copy the text in the region to kill ring   |
+| delete\_char\_backward | Yes    | Delete char to the left of cursor          |
+| delete\_char\_forward  | Yes    | Delete char to the right of cursor         |
+| delete\_region         | No     | Delete the text in the region              |
+| eol                    | No     | Move cursor to end of buffer               |
+| kill\_region           | No     | Kill the text in the region                |
+| kill\_to\_bol          | No     | Kill the text from cursor to beginning     |
+| kill\_to\_eol          | No     | Kill the text from cursor to end           |
+| kill\_word\_backward   | Yes    | Kill the word to the left of  cursor       |
+| kill\_word\_forward    | Yes    | Kill the word to the right of  cursor      |
+| move\_left             | Yes    | Move cursor one char left                  |
+| move\_right            | Yes    | Move cursor one char right                 |
+| move\_word\_left       | Yes    | Move cursor one word left                  |
+| move\_word\_right      | Yes    | Move cursor one word right                 |
+| redo                   | No     | Redo an undone action                      |
+| set\_mark              | No     | Set the region mark at cursor              |
+| transpose\_chars       | Yes    | Switch position of char with prior char    |
+| transpose\_words       | Yes    | Switch position of word with prior char    |
+| undo                   | No     | Revert last edit action                    |
+| yank                   | No     | Copy kill ring to buffer at cursor         |
+| yank\_pop              | Yes    | Copy next kill ring item and replace prior |
+
+
+<a id="org3f876b8"></a>
+
+#### Input field actions
+
+Input field actions operate on an editable input field. An input field occurs at the main input prompt, but also in things like search-narrowing input, incremental-search, a prompt for text, etc. It is lower level than the shell session input described in the next section. In particular, it can have its own history attached to it depending on its purpose. They handle accepting the current line, moving through history, and receiving pasted text.
+
+| Action Name   | Count? | Description                                               |
+|------------- |------ |--------------------------------------------------------- |
+| accept\_line  | No     | Accept the current text as the input                      |
+| history\_prev | No     | Insert the prior relevant history item in the input field |
+| history\_next | No     | Insert the next relevant history item in the input field  |
+
+
+<a id="orge0c4e6e"></a>
+
+#### Shell session actions
+
+Shell session actions operate at the session level around the main command input and output area. They submit input, interrupt running work, clear output, start completion, open completion/history popups, and manage numeric prefix entry.
+
+| Action Name          | Count? | Description                                                      |
+|-------------------- |------ |---------------------------------------------------------------- |
+| submit\_line         | No     | Pass the current text to the on\_accept proc and page output     |
+| submit\_and\_scroll  | No     | Pass the current text to the on\_accept proc and scroll output   |
+| interrupt            | No     | End the current session                                          |
+| interrupt\_if\_empty | No     | End the current session only if the current text is empty        |
+| clear\_output        | No     | Clear the output pane                                            |
+| complete             | No     | Suggest the next possible completion as an autosuggestion        |
+| complete\_previous   | No     | Suggest the prior possible completion as an autosuggestion       |
+| completion\_popup    | No     | Display all possible completions in a popup for selection        |
+| history\_search      | No     | Display history item starting with the text-so-far for selection |
+| count\_digit         | No     | Add a digit to the numeric prefix                                |
+| universal\_argument  | No     | Set the numeric argument to 4 or multiply the current one by 4   |
+
+
+<a id="org05813c6"></a>
+
+#### Pager actions
+
+Pager actions navigate output when the output area is in paging mode. They move by line, page, top, bottom, or end of output, handle mouse-wheel scrolling, and switch between paging and scrolling behavior. Most movement actions honor the numeric prefix count.
+
+| Action Name           | Count? | Description                                      |
+|--------------------- |------ |------------------------------------------------ |
+| page\_up              | Yes    | Move the output view one page up                 |
+| page\_down            | Yes    | Move the output view one page down               |
+| end\_of\_output       | No     | Move the output to the end of output and scroll  |
+| line\_up              | Yes    | Move the output view one line up                 |
+| line\_down            | Yes    | Move the output view one line down               |
+| scroll\_up            | Yes    | Move the output view six lines up                |
+| scroll\_down          | Yes    | Move the output view six lines down              |
+| page\_top             | Yes    | Move to the beginning, or to the counted line    |
+| page\_bottom          | No     | Move the output to the end of output             |
+| paging\_to\_scrolling | No     | Quit paging and scroll output as it is produced  |
+| toggle\_paging        | No     | Toggle output mode between paging and scrolling  |
+| quit\_paging          | No     | Quit paging and return control to the input line |
+
+
+<a id="orgea58518"></a>
+
+#### Pager search actions
+
+Pager search actions can *initiate* a search session within the pager: a string search, a regular expression search, or an incremental-search. Once a search session is entered, other actions navigate matches in the output. There are also actions to end a search session.
+
+While the search session is active, accepting commits the current match and canceling restores the pager to the position it had when the search began. After the search is accepted, `n` and `N` repeat the committed search in the pager; at that point the search session is no longer active.
+
+| Action Name                    | Count? | Description                                                         |
+|------------------------------ |------ |------------------------------------------------------------------- |
+| pager\_search\_forward         | No     | Initiate a string search forward from current output point          |
+| pager\_search\_backward        | No     | Initiate a string search backward from current output point         |
+| pager\_regex\_search\_forward  | No     | Initiate a regex search forward from current output point           |
+| pager\_regex\_search\_backward | No     | Initiate a regex search backward from current output point          |
+| pager\_isearch\_forward        | No     | Initiate an incremental search forward from current output point    |
+| pager\_isearch\_backward       | No     | Initiate an incremental search backward from current output point   |
+| pager\_search\_next            | No     | Move output to the next search match                                |
+| pager\_search\_prev            | No     | Move output to the prior search match                               |
+| search\_toggle\_regex          | No     | Toggle between regex and string search                              |
+| search\_step\_forward          | No     | Preview the next match using the current search text                |
+| search\_step\_backward         | No     | Preview the prior match using the current search text               |
+| isearch\_next                  | No     | Move output to the next isearch match                               |
+| isearch\_prev                  | No     | Move output to the prior isearch match                              |
+| search\_accept                 | No     | Commit the current search and close the search session              |
+| search\_cancel                 | No     | Cancel the active search session and restore its starting point     |
+| isearch\_accept                | No     | Commit the current incremental search and close the search session  |
+| isearch\_cancel                | No     | Cancel the active incremental search and restore its starting point |
+
+
+<a id="org6ea9ecc"></a>
+
+#### Popup actions
+
+Popup actions control selection and narrowing popups such as choose, menu, completion, and history popups. You can narrow the selections presented by typing in the input field presented. You can move through the list, accept or cancel the selection, page through choices, jump to the top or bottom, recenter the selection, and toggle selection in multi-select popups.
+
+| Action Name             | Count? | Description                                               |
+|----------------------- |------ |--------------------------------------------------------- |
+| popup\_cancel           | No     | Close the popup and return its cancel\_value              |
+| popup\_accept           | No     | Close the popup and return the selection                  |
+| popup\_next             | No     | Move the selection cursor to the next item                |
+| popup\_prev             | No     | Move the selection cursor to the prior item               |
+| popup\_page\_down       | No     | Move the selection list down one page                     |
+| popup\_page\_up         | No     | Move the selection list up one page                       |
+| popup\_top              | No     | Move to the top of the selection list                     |
+| popup\_bottom           | No     | Move to the bottom of the selection list                  |
+| popup\_recenter         | No     | Recenter the selection list on the current item           |
+| popup\_toggle\_selected | No     | In multi-select, toggle the selection of the current item |
+
+
+<a id="org8f3d6dc"></a>
+
+#### Prompt popup actions
+
+Prompt popup actions control prompt dialogs that collect a string from the user. They accept the prompt, cancel it, or cancel only when the prompt is empty.
+
+| Action Name               | Count? | Description                                          |
+|------------------------- |------ |---------------------------------------------------- |
+| prompt\_accept            | No     | Close the prompt popup and return the current string |
+| prompt\_cancel            | No     | Close the prompt popup and return its cancel\_value  |
+| prompt\_cancel\_if\_empty | No     | Cancel only if the input buffer is empty             |
+
+
+<a id="org4a9e2d4"></a>
+
+#### Utility Actions
+
+Some actions exist to support `Fatty`'s own input machinery and are not normally useful as ordinary user bindings. For example, `insert`, `replace`, and `paste` need text supplied by code: `paste` is used for bracketed paste events from the terminal and normalizes pasted text for a one-line input field; `self_insert` is selected automatically for printable characters. They are listed here for completeness.
+
+| Action Name  | Args | Count? | Description                        |
+|------------ |---- |------ |---------------------------------- |
+| insert       | str  | Yes    | Insert the string at point         |
+| self\_insert |      | Yes    | Insert the bound key at point      |
+| replace      | str  | No     | Replace the buffer with the string |
+| set          | str  | No     | Alias for `replace`                |
+| paste        | str  | No     | Insert pasted text at point        |
+
+
+<a id="org7e9ed87"></a>
+
+## Themes `themes/`
+
+
+<a id="orgf951ab7"></a>
+
+### Distributed Themes
+
+As distributed, `fatty` comes with the following themes, most of which are based on popular themes used in many text editors and IDEs.
+
+Within a `fatty` terminal, themes can be changed interactively. The default Emacs-style bindings include:
+
+| Key     | Action                                  |
+|------- |--------------------------------------- |
+| `C-M-t` | cycle to the next loaded theme          |
+| `M-=`   | preview and choose a theme from a popup |
+
+Here are the builtin themes:
+
+| Name              | Description                                        |
+|----------------- |-------------------------------------------------- |
+| capuchin\_monk    | A tribute to St. Francis of Assisi                 |
+| catppuccin\_latte | Pastel theme of the latte flavor                   |
+| catppuccin\_mocha | Pastel theme of the mocha flavor                   |
+| cyberpunk         | Brash colorful theme                               |
+| dracula           | Dark theme inspired by the Count                   |
+| everforest\_dark  | Dark green-esque theme                             |
+| gruvbox\_dark     | Engineered for focus, built for developers         |
+| gruvbox\_light    | Engineered for focus, built for developers         |
+| mono              | Minimal black-and-white theme                      |
+| monokai           | Based on <https://monokai.pro/history>             |
+| nordic            | Shiver me timbers, it's northern                   |
+| onedark           | Shameless imitation of Atom editor theme           |
+| solarized\_dark   | Ethan Schoonover's famous terminal theme           |
+| solarized\_light  | And its light variant                              |
+| terminal          | Use the terminal's color scheme                    |
+| tokyo\_night      | Celebrates the neon lights and dark vibes of Tokyo |
+| wordperfect       | Nostalgic nod to the good old word processor       |
+
+
+<a id="orgcf6fbb1"></a>
+
+### Custom Themes
+
+
+<a id="orgb8ead89"></a>
+
+#### Theme Name
+
+A Fatty theme is a YAML file in the user-specific config directory (normally `~/.config/fatty/themes`) or the app-specific config directory (by default `~/.config/fatty/apps/<app_name>/themes`). The filename does not determine the theme name: the theme file must have a `name` field to set the name:
+
+```yaml
+name: nordic
+```
+
+
+<a id="orgc49dfe9"></a>
+
+#### Inheritance from Another Theme
+
+Themes can inherit from other themes with the `inherit:` tag:
+
+```yaml
+name: my_nordic
+inherit: nordic
+
+output:
+fg: "#eeeeee"
+```
+
+This means that all the theme setting from the `nordic` theme apply except to the extent changed by the rest of the `my_nordic` theme file.
+
+
+<a id="org371d3bb"></a>
+
+#### Inheritance within a Theme
+
+Not only may one theme inherit from another theme, some roles within a theme inherit from other roles. For example, the `input` role inherits from the `output` role.
+
+Thus, a minimal theme can define only `output` and inherit everything else through Fatty's role defaults:
+
+```yaml
+name: simple_dark
+inherit: null
+
+output:
+  fg: white
+  bg: black
+```
+
+This means that the input field will have the same coloring and attributes as the output pane.
+
+
+<a id="org83d0479"></a>
+
+#### Theme Roles
+
+Here is a listing of what roles act as the parent for each of the roles, their purpose, and the role, if any, from which they inherit.
+
+| Role name               | Used for                                  | Parent Role           |
+|----------------------- |----------------------------------------- |--------------------- |
+| `output`                | Main output area text.                    | <none>                |
+| `input`                 | Main command/input field.                 | `output`              |
+| `input_suggestion`      | Autosuggestion or completion suffix text. | `input`               |
+| `cursor`                | Cursor cell styling where applicable.     | `input`               |
+| `region`                | Selected text / active region.            | `output`              |
+| `status`                | Status area base role.                    | `output`              |
+| `info`                  | Informational messages.                   | `output`              |
+| `good`                  | Success messages.                         | `info`                |
+| `warn`                  | Warning messages.                         | `info`                |
+| `error`                 | Error messages.                           | `warn`                |
+| `alert`                 | Alert panel base role.                    | `output`              |
+| `pager_status`          | Pager status / prompt row.                | `status`              |
+| `line_number`           | Line numbers when toggled on              | `output`              |
+| `search_input`          | Search input field.                       | `popup`               |
+| `match_current`         | Current search match.                     | `region`              |
+| `match_other`           | Other search matches.                     | `region`              |
+| `popup`                 | Popup body.                               | `output`              |
+| `popup_frame`           | Popup border/frame.                       | `popup`               |
+| `popup_input`           | Popup filter/input field.                 | `input`               |
+| `popup_selection`       | Selected popup item row.                  | `region`              |
+| `popup_counts`          | Popup counts/status row.                  | `popup`               |
+| `markdown_h1`           | Markdown level-1 headings.                | `output`              |
+| `markdown_h2`           | Markdown level-2 headings.                | `markdown_h1`         |
+| `markdown_h3`           | Markdown level-3 headings.                | `markdown_h2`         |
+| `markdown_code`         | Inline markdown code.                     | `output`              |
+| `markdown_code_block`   | Markdown fenced-code block base role.     | `markdown_code`       |
+| `markdown_code_gutter`  | Code block gutter/prefix.                 | `markdown_code_block` |
+| `markdown_strong`       | Markdown strong/bold text.                | `output`              |
+| `markdown_emphasis`     | Markdown emphasized text.                 | `output`              |
+| `markdown_link`         | Markdown link text.                       | `output`              |
+| `markdown_url`          | Markdown displayed URL text.              | `markdown_link`       |
+| `markdown_quote_gutter` | Markdown block quote gutter.              | `output`              |
+| `markdown_highlight`    | Markdown highlight / marked text.         | `output`              |
+| `markdown_table_header` | Markdown table header cells.              | `markdown_strong`     |
+| `markdown_table_cell`   | Markdown table body cells.                | `output`              |
+| `markdown_underline`    | Markdown underline text.                  | `output`              |
+| `markdown_hrule`        | Markdown horizontal rules.                | `output`              |
+
+
+<a id="orgabf70f2"></a>
+
+#### Role Colors and Attributes and Frame Style
+
+Each role can have assigned to it a foreground color (`fg:`), a background color (`bg:`), and one or more "attributes" (`attrs:`).
 
+1.  Colors
 
-<a id="org64156e4"></a>
+    The colors can be a hex string of the form "#RRGGBB", that is a mixture of red, green, and blue at level given by three valid hexadecimal numbers RR, GG, and BB. For example "#FF0000" is pure red, "#330044" is a middling mixture of red and blue, a shade of purple. In addition, `fatty` recognizes color names defined as 16 ANSI colors, 256 xterm colors, and X11 colors, all of which you can see by invoking `fatty`'s CLI command `colors`.
+    
+    The special color `default` means to inherit colors from the underlying terminal program.
 
-# Reading Keys
+2.  Attributes
 
-Shift/Ctrl/Meta F-keys are normalized when ncurses provides distinct constants.
+    Each role can also have non-color attributes applied by specifying an `attrs` list. Supported attributes are `bold`, `dim`, `italic`, `underline`, and `reverse`. Italic is emitted by the truecolor renderer and by markdown ANSI output, but curses terminals may display it inconsistently or not at all.
 
+3.  Frame Style
 
-<a id="org38ad970"></a>
+    In addition, one role, `popup_frame:`, in addition to these have two attributes for styling the "frame" drawn around popup:
+    
+    | `border:`  | single, double, or ascii |
+    | `corners:` | rounded or square        |
 
-# Alerts
+4.  An Example Theme
 
-Alerts are short-lived, non-scrolling messages shown below the input line. They are intended for user-visible conditions that require attention.
+    ```yaml
+    name: example
+    inherit: null
+    
+    output:
+      fg: "#d8dee9"
+      bg: "#2e3440"
+    
+    input:
+      fg: "#eceff4"
+      bg: "#3b4252"
+      attrs: [bold]
+    
+    input_suggestion:
+      fg: "#81a1c1"
+      bg: "#3b4252"
+    
+    cursor:
+      fg: "#2e3440"
+      bg: "#88c0d0"
+    
+    region:
+      fg: "#2e3440"
+      bg: "#88c0d0"
+    
+    info:
+      fg: "#d8dee9"
+      bg: "#2e3440"
+    
+    good:
+      fg: green
+      bg: "#2e3440"
+    
+    warn:
+      fg: "#2e3440"
+      bg: "#ebcb8b"
+    
+    error:
+      fg: "#eceff4"
+      bg: "#bf616a"
+    
+    pager_status:
+      fg: black
+      bg: lightgreen
+    
+    search_input:
+      fg: black
+      bg: cyan
+    
+    match_current:
+      fg: black
+      bg: yellow
+    
+    match_other:
+      fg: black
+      bg: lightgray
+    
+    popup:
+      fg: "#d8dee9"
+      bg: "#3b4252"
+    
+    popup_input:
+      fg: "#eceff4"
+      bg: "#434c5e"
+    
+    popup_selection:
+      fg: "#2e3440"
+      bg: "#88c0d0"
+    
+    popup_counts:
+      fg: "#2e3440"
+      bg: white
+    
+    popup_frame:
+      fg: "#81a1c1"
+      bg: "#3b4252"
+      border: single
+      corners: rounded
+    ```
+    
+    Or you can group them under `markdown` without the `markdown_` prefix:
+    
+    ```yaml
+    markdown:
+      h1:
+        fg: yellow
+        bg: navy
+        attrs: [bold]
+      code:
+        fg: lightgreen
+        bg: black
+      link:
+        fg: cyan
+        bg: navy
+        attrs: [underline]
+    ```