terminal_rb 0.19.0 → 1.0.3

data/lib/terminal/ansi.rb

@@ -1,97 +1,67 @@
 # frozen_string_literal: true
 
 module Terminal
+  # ANSI escape code generation and BBCode-to-ANSI conversion.
   #
-  # Fast ANSI control code and BBCode processing.
+  # Provides methods for text decoration, color, cursor control, screen
+  # manipulation, hyperlinks, notifications, and progress indicators.
+  # All methods return ANSI escape sequence strings — they do not write
+  # to the terminal directly.
+  #
+  # Colors can be specified as named symbols, 256-color indices, hex
+  # strings, or CSS/X11 color names.
+  #
+  # @example Generate ANSI codes
+  #   Terminal::Ansi[:bold, :red]   # => "\e[1;31m"
+  #   Terminal::Ansi[:on_blue]      # => "\e[44m"
+  #
+  # @example BBCode to ANSI
+  #   Terminal::Ansi.bbcode('[bold]Hello[/bold]') # => "\e[1mHello\e[m"
   #
   module Ansi
     class << self
-      # Supported attribute names.
-      #
-      # @see []
+      # All known text attribute names (bold, italic, underline, etc.).
       #
       # @attribute [r] attributes
-      # @return [Array<Symbol>] all attribute names
+      # @return [Array<Symbol>]
       def attributes = @attributes.dup
 
-      # Supported 3/4-bit color names.
-      #
-      # @see []
+      # All known basic color names.
       #
       # @attribute [r] colors
-      # @return [Array<Symbol>] all color names
+      # @return [Array<Symbol>]
       def colors = @colors.dup
 
-      # Supported basic 24-bit (Kitty compatible) color names.
-      #
-      # @see []
+      # All CSS/X11 named colors.
       #
       # @attribute [r] named_colors
-      # @return [Array<Symbol>] all basic named_colors names
+      # @return [Array<Symbol>]
       def named_colors = NAMED_COLORS.keys.map!(&:to_sym)
 
       #
-      # @!group ANSI control code generator functions
-      #
-
-      # Combine given {attributes}, {colors}, {named_colors} and color codes to
-      # an ANSI control code sequence.
-      #
-      # Colors can specified by their name for ANSI 3-bit and 4-bit colors.
-      # For 8-bit ANSI colors use 2-digit hexadecimal values `00`...`ff`.
-      #
-      # To use RGB ANSI colors (24-bit colors) specify 3-digit or 6-digit
-      # hexadecimal values `000`...`fff` or `000000`...`ffffff`.
-      # This represent the `RRGGBB` values (or `RGB` for short version) like you
-      # may known from CSS color notation.
-      #
-      # To use a color as background color prefix the color attribute with `bg_`
-      # or `on_`.
-      # To use a color as underline color prefix the color attribute with `ul_`.
-      # To clarify that a color attribute have to be used as foreground
-      # color use the prefix `fg_`.
-      #
-      # @example Valid Foreground Color Attributes
-      #   Terminal::Ansi[:yellow]
-      #   Terminal::Ansi[:fg_fab]
-      #   Terminal::Ansi[:fg_00aa00]
-      #   Terminal::Ansi[:af]
-      #   Terminal::Ansi[:fg_af]
-      #   Terminal::Ansi['#fab']
-      #   Terminal::Ansi['#00aa00']
-      #   Terminal::Ansi['lightblue']
-      #
-      # @example Valid Background Color Attributes
-      #   Terminal::Ansi[:bg_yellow]
-      #   Terminal::Ansi[:bg_fab]
-      #   Terminal::Ansi[:bg_00aa00]
-      #   Terminal::Ansi[:bg_af]
-      #   Terminal::Ansi['bg#00aa00']
-      #   Terminal::Ansi['bg_lightblue']
-      #
-      #   Terminal::Ansi[:on_yellow]
-      #   Terminal::Ansi[:on_fab]
-      #   Terminal::Ansi[:on_00aa00]
-      #   Terminal::Ansi[:on_af]
-      #   Terminal::Ansi['on#00aa00']
-      #   Terminal::Ansi['on_lightblue']
-      #
-      # @example Valid Underline Color Attributes
-      #   Terminal::Ansi[:underline, :ul_yellow]
-      #   Terminal::Ansi[:underline, :ul_fab]
-      #   Terminal::Ansi[:underline, :ul_00aa00]
-      #   Terminal::Ansi[:underline, :ul_fa]
-      #   Terminal::Ansi[:underline, :ul_bright_yellow]
-      #   Terminal::Ansi[:underline, 'ul#00aa00']
-      #   Terminal::Ansi['underline', 'ul_lightblue']
-      #
-      # @example Combined attributes:
-      #   Terminal::Ansi[:bold, :italic, :bright_white, :on_0000cc]
-      #
-      # @see valid?
-      #
-      # @param attributes [Array<Symbol, String>] attribute names to be used
-      # @return [String] combined ANSI attributes
+      # @!group ANSI Control Code Generation
+      #
+
+      # Generate an ANSI escape sequence from attribute names or color
+      # indices.
+      #
+      # Accepts symbols (`:bold`, +:red+), strings (`"bold"`, +"#ff0000"+),
+      # or integers for 256-color palette (0-255 foreground, 256-511
+      # background, 512-767 underline color).
+      #
+      # @example Named attributes
+      #   Terminal::Ansi[:bold, :italic, :green] # => "\e[1;3;32m"
+      # @example 256-color palette
+      #   Terminal::Ansi[196]       # foreground color 196
+      #   Terminal::Ansi[256 + 21]  # background color 21
+      # @example Hex colors
+      #   Terminal::Ansi[:ff8800] # => "\e[38;2;255;136;0m"
+      # @example Named CSS colors
+      #   Terminal::Ansi[:coral] # => "\e[38;2;255;127;80m"
+      #
+      # @param attributes [Array<String, Symbol, Integer>] ANSI attributes
+      # @return [String] ANSI escape sequence
+      # @raise [ArgumentError] for unknown attributes
       def [](*attributes)
         return +'' if attributes.empty?
         "\e[#{
@@ -116,134 +86,155 @@ module Terminal
         }m"
       end
 
-      # Test if given String contains ANSI control codes.
-      #
-      # @param str [#to_s] object to be tested
-      # @return [true, false] whether if attributes are found
-      def ansi?(str) = @re_test.match?(str.to_s)
-
-      # Decorate given argument with ANSI attributes and colors.
+      # Wrap a string with ANSI escape codes.
       #
       # @example
-      #   Terminal::Ansi.decorate(
-      #     'Hello World!',
-      #     :bold, :italic, :bright_white, :on_00c
-      #   )
-      #   # => "\e[1;3;97;48;2;0;0;204mHello World!\e[m"
-      #
-      # @see []
-      # @see undecorate
-      #
-      # @param str [#to_s] object to be decorated
-      # @param attributes [Array<Symbol, String>] attribute names to be used
-      # @param reset [true, false] whether to include reset code for ANSI attributes
-      # @return [String] `str` converted and decorated with the ANSI `attributes`
+      #   Terminal::Ansi.decorate('Hello', :bold, :red)
+      #   # => "\e[1;31mHello\e[m"
+      # @example Without reset
+      #   Terminal::Ansi.decorate('Hello', :bold, reset: false)
+      #   # => "\e[1mHello"
+      #
+      # @param str [#to_s] the string to decorate
+      # @param attributes [Array<String, Symbol, Integer>] ANSI attributes
+      #   to apply
+      # @param reset [true, false] append a reset code at the end
+      # @return [String] the decorated string
       def decorate(str, *attributes, reset: true)
         attributes = self[*attributes]
         attributes.empty? ? "#{str}" : "#{attributes}#{str}#{"\e[m" if reset}"
       end
 
-      # Remove ANSI functions, attributes and colors from given string.
+      # Remove all ANSI escape codes from a string.
       #
       # @example
-      #   Terminal::Ansi.undecorate("\e[1;3;97;48;2;0;0;204mHello World!\e[m")
-      #   # => "Hello World!"
+      #   Terminal::Ansi.undecorate("\e[1;31mHello\e[m")
+      #   # => "Hello"
       #
-      # @see decorate
-      #
-      # @param str [#to_s] string to be modified
-      # @return [String] string without ANSI attributes
+      # @param str [#to_s] the string to clean
+      # @return [String] a copy with all ANSI codes stripped
       def undecorate(str)
         (str = str.to_s).index("\e") ? str.gsub(@re_test, '') : str.dup
       end
 
-      # Try to combine given ANSI attributes and colors.
-      # The attributes and colors have to be separated by given `separator``.
-      #
-      # @example Valid Attribute String
-      #   Terminal::Ansi.try_convert('bold italic blink red on#00ff00')
-      #   # => "\e[1;3;5;31;48;2;0;255;0m"
-      #
-      # @example Invalid Attribute String
-      #   Terminal::Ansi.try_convert('cool bold on green')
-      #   # => nil
+      # Try to convert a space-separated attribute string to an ANSI
+      # escape sequence.
       #
-      # @see []
+      # @example
+      #   Terminal::Ansi.try_convert('bold red')  # => "\e[1;31m"
+      #   Terminal::Ansi.try_convert('invalid')    # => nil
       #
-      # @param attributes [#to_s] attributes separated by given `separator`
-      # @param separator [String] attribute separator char
-      # @return [String] combined ANSI attributes
-      # @return [nil] when string does not contain valid attributes
+      # @param attributes [#to_s] space-separated attribute names
+      # @param separator [String] delimiter for splitting
+      # @return [String, nil] ANSI escape sequence, or +nil+ if any
+      #   attribute is invalid
       def try_convert(attributes, separator: ' ')
         return unless attributes
         return if (attributes = attributes.to_s.split(separator)).empty?
-        "\e[#{attributes.map! { @attr_map[_1] || return }.join(';')}m"
+        attributes.uniq!
+        "\e[#{attributes.map! { @attr_map[it] || return }.join(';')}m"
       end
 
-      # Test if all given attributes are valid.
+      # Generate rainbow-colored text using true color (24-bit) ANSI
+      # codes.
       #
-      # @see []
+      # @example
+      #   puts Terminal::Ansi.rainbow('Hello, World!')
       #
-      # @param attributes [Array<Symbol, String>] attribute names to be used
-      # @return [true, false] whether if all given attributes are valid
-      def valid?(*attributes)
-        attributes.all? do |arg|
-          case arg
-          when String
-            @attr_map[arg]
-          when Symbol
-            @attrs_map[arg]
-          when (0..767)
-            true
-          end
-        end
+      # @param str [#to_s] text to colorize
+      # @param frequency [Float] color wave frequency
+      # @param spread [Float] color wave spread
+      # @param seed [Float] starting position in the color cycle
+      # @return [String] text with per-character RGB foreground colors
+      def rainbow(str, frequency: 0.3, spread: 0.8, seed: 1.1)
+        pos = -1
+        @pi2_third ||= 2.0 * Math::PI / 3.0
+        @pi4_third ||= 4.0 * Math::PI / 3.0
+        (
+          str.to_s.chars.map! do |char|
+            i = (seed + ((pos += 1) / spread)) * frequency
+            "\e[38;2;#{(Math.sin(i) * 255).round.abs};#{
+              (Math.sin(i + @pi2_third) * 255).round.abs
+            };#{(Math.sin(i + @pi4_third) * 255).round.abs}m#{char}"
+          end << RESET_FG
+        ).join
       end
 
       #
       # @!endgroup
       #
-      # @!group BBcode related functions
+      # @!group BBcode Generation
       #
 
-      # Replace embedded BBCode-like attributes with ANSI control codes.
+      # Convert BBCode markup to ANSI escape codes.
       #
-      # @example
-      #   Terminal::Ansi.bbcode "[b]Bold[/b] Text"
-      #   # => "\e[1mBold\e[22m Text"
+      # Tags like +[bold]+ are converted to their ANSI equivalents;
+      # +[/bold]+ or +[/]+ resets. Unknown tags are left unchanged.
+      # Escape a tag with a backslash: +[\\bold]+ renders as +[bold]+.
       #
-      # @see unbbcode
-      # @see []
+      # @see .unbbcode
+      # @see .plain
       #
-      # @param str [#to_s] string to be modified
-      # @return [String] string with ANSI attributes
+      # @example
+      #   Terminal::Ansi.bbcode('[bold red]Hello[/] World')
+      #   # => "\e[1;31mHello\e[m World"
+      # @example Escaped tag
+      #   Terminal::Ansi.bbcode('[\\bold]') # => "[bold]"
+      #
+      # @param str [#to_s] text with BBCode markup
+      # @return [String] text with ANSI escape codes
       def bbcode(str)
-        str = str.to_s
-        return str.dup unless str.index('[')
+        return str.dup unless (str = str.to_s).index('[')
         str.gsub(@re_bbcode) do |match_str|
           match = Regexp.last_match(1) or next match_str
-          next "[#{match[1..]}]" if match[0] == '\\'
-          try_convert(match) || match_str
+          next try_convert(match) || match_str if match[0] != '\\'
+          match[0] = ''
+          "[#{match}]"
         end
       end
 
-      # Remove embedded BBCode-like attributes.
+      # Remove BBCode tags from a string, keeping the enclosed text.
       #
-      # @example
-      #   Terminal::Ansi.unbbcode "[b]Bold[/b] Text"
-      #   # => "Bold Text"
+      # @see .bbcode
       #
-      # @see bbcode
+      # @example
+      #   Terminal::Ansi.unbbcode('[bold]Hello[/bold]') # => "Hello"
       #
-      # @param str [#to_s] string to be modified
-      # @return [String] string without BBCode
+      # @param str [#to_s] text with BBCode markup
+      # @return [String] text with tags removed
       def unbbcode(str)
-        str = str.to_s
-        return str.dup unless str.index('[')
+        return str.dup unless (str = str.to_s).index('[')
         str.gsub(@re_bbcode) do |match_str|
           match = Regexp.last_match(1) or next match_str
-          next "[#{match[1..]}]" if match[0] == '\\'
+          if match[0] == '\\'
+            match[0] = ''
+            next "[#{match}]"
+          end
           next match_str if (match = match.split).empty?
-          next if match.all? { @attr_map[_1] }
+          next if match.all? { @attr_map[it] }
+          match_str
+        end
+      end
+
+      # Escape BBCode tags so they render as literal text after
+      # {.bbcode} processing.
+      #
+      # @see .bbcode
+      #
+      # @example
+      #   Terminal::Ansi.escape_bbcode('[bold]Hi[/bold]')
+      #   # => "[\\bold]Hi[\\/bold]"
+      #
+      # @param str [#to_s] text with BBCode markup
+      # @return [String] text with BBCode tags escaped
+      def escape_bbcode(str)
+        return str.dup unless (str = str.to_s).index('[')
+        str.gsub(@re_bbcode) do |match_str|
+          fc = match_str[1]
+          next match_str if fc == '\\' || fc == ']'
+          match = Regexp.last_match(1) or next match_str
+          next match_str if (parts = match.split).empty?
+          next "[\\#{match}]" if parts.all? { @attr_map[it] }
           match_str
         end
       end
@@ -251,120 +242,124 @@ module Terminal
       #
       # @!endgroup
       #
-      # @!group Other tool functions
+      # @!group Tool Functions
+      #
+
+      # Test whether a string contains ANSI escape codes.
+      #
+      # @example
+      #   Terminal::Ansi.ansi?("\e[1mHi\e[m") # => true
+      #   Terminal::Ansi.ansi?("Hello")       # => false
       #
+      # @param str [#to_s] the string to test
+      # @return [true, false]
+      def ansi?(str) = @re_test.match?(str.to_s)
 
-      # Remove any BBCode-like and/or ANSI attributes.
+      # Check whether all given attributes are valid.
       #
-      # @see undecorate
-      # @see unbbcode
+      # @example
+      #   Terminal::Ansi.valid?(:bold, :red)  # => true
+      #   Terminal::Ansi.valid?(:nope)        # => false
       #
-      # @param str [#to_s] string to be modified
-      # @return [String] string without BBCode and ANSI control codes.
-      def plain(str)
-        unless (str = str.to_s).index('[')
-          return str.index("\e") ? str.gsub(@re_test, '') : str.dup
-        end
-        str =
-          str.gsub(@re_bbcode) do |match_str|
-            match = Regexp.last_match(1) or next match_str
-            next "[#{match[1..]}]" if match[0] == '\\'
-            next match_str if (match = match.split).empty?
-            next if match.all? { @attr_map[_1] }
-            match_str
+      # @param attributes [Array<String, Symbol, Integer>] attributes to
+      #   validate
+      # @return [true, false]
+      def valid?(*attributes)
+        attributes.all? do |arg|
+          case arg
+          when String
+            @attr_map[arg]
+          when Symbol
+            @attrs_map[arg]
+          when (0..767)
+            true
           end
-        str.index("\e") ? str.gsub!(@re_test, '') : str
+        end
       end
 
-      # Create nice colored text.
+      # Remove both BBCode tags and ANSI escape codes, returning plain
+      # text.
       #
-      # @param str [#to_s] string to enrich with color
-      # @param frequency [Float] color change frequency
-      # @param spread [Float] number of chars with same color
-      # @param seed [Float] start index on sinus curve
-      # @return [String] fancy text
-      def rainbow(str, frequency: 0.3, spread: 0.8, seed: 1.1)
-        pos = -1
-        @pi2_third ||= 2.0 * Math::PI / 3.0
-        @pi4_third ||= 4.0 * Math::PI / 3.0
-        (
-          str.to_s.chars.map! do |char|
-            i = (seed + ((pos += 1) / spread)) * frequency
-            "\e[38;2;#{(Math.sin(i) * 255).to_i.abs};" \
-              "#{(Math.sin(i + @pi2_third) * 255).to_i.abs};" \
-              "#{(Math.sin(i + @pi4_third) * 255).to_i.abs}m#{char}"
-          end << RESET
-        ).join
+      # @example
+      #   Terminal::Ansi.plain('[bold]Hello[/bold]')     # => "Hello"
+      #   Terminal::Ansi.plain("\e[1mHello\e[m")         # => "Hello"
+      #
+      # @param str [#to_s] text with BBCode and/or ANSI codes
+      # @return [String] plain text
+      def plain(str)
+        str.gsub!(@re_test, '') if (str = unbbcode(str)).index("\e")
+        str
       end
 
       #
       # @!endgroup
       #
-      # @!group Cursor manipulation
+      # @!group ANSI Control Code Generation
       #
 
-      # Move cursor given lines up.
+      # Move cursor up.
       #
-      # @param lines [Integer] number of lines to move
-      # @return [String] ANSI control code
+      # @param lines [Integer] number of lines
+      # @return (see .[])
       def cursor_up(lines = 1) = "\e[#{lines}A"
 
-      # Move cursor given lines down.
+      # Move cursor down.
       #
-      # @param (see cursor_up)
-      # @return (see cursor_up)
+      # @param (see .cursor_up)
+      # @return (see .[])
       def cursor_down(lines = 1) = "\e[#{lines}B"
 
-      # Move cursor given columns forward.
+      # Move cursor right.
       #
-      # @param columns [Integer] number of columns to move
-      # @return (see cursor_up)
+      # @param columns [Integer] number of columns
+      # @return (see .[])
       def cursor_forward(columns = 1) = "\e[#{columns}C"
 
-      # Move cursor given columns back.
+      # Move cursor left.
       #
-      # @param (see forward)
-      # @return (see cursor_up)
+      # @param (see .cursor_forward)
+      # @return (see .[])
       def cursor_back(columns = 1) = "\e[#{columns}D"
 
-      # Move cursor to the beginning of the given next line.
+      # Move cursor to beginning of line, N lines down.
       #
-      # @param (see up)
-      # @return (see cursor_up)
+      # @param (see .cursor_up)
+      # @return (see .[])
       def cursor_next_line(lines = 1) = "\e[#{lines}E"
 
-      # Move cursor to the beginning of the given previous line.
+      # Move cursor to beginning of line, N lines up.
       #
-      # @param (see up)
-      # @return (see cursor_up)
+      # @param (see .cursor_up)
+      # @return (see .[])
       def cursor_prev_line(lines = 1) = "\e[#{lines}F"
 
-      # Move cursor to given column in the current row.
+      # Move cursor to absolute column.
       #
-      # @param column [Integer] column index
-      # @return (see cursor_up)
+      # @param column [Integer] column number
+      # @return (see .[])
       def cursor_column(column = 1) = "\e[#{column}G"
 
-      # Move cursor to given column in the current row relative to the current
-      # position.
-      # (Skip some columns.)
+      # Move cursor right by relative columns.
       #
-      # @param (see cursor_column)
-      # @return (see cursor_up)
+      # @param column [Integer] number of columns
+      # @return (see .[])
       def cursor_column_rel(column = 1) = "\e[#{column}a"
 
-      # Move cursor to given row relative to the current position.
-      # (Skip some rows.)
+      # Move cursor down by relative rows.
       #
-      # @param row [Integer] row index
-      # @return (see cursor_up)
+      # @param row [Integer] number of rows
+      # @return (see .[])
       def cursor_row_rel(row = 1) = "\e[#{row}e"
 
-      # Move to given row and column.
+      # Move cursor to absolute position.
+      #
+      # @example
+      #   Terminal::Ansi.cursor_pos(1, 1)  # home position
+      #   Terminal::Ansi.cursor_pos(10, 5) # row 10, column 5
       #
-      # @param row [Integer] row index
-      # @param column [Integer] column index
-      # @return (see cursor_up)
+      # @param row [Integer, nil] row number; +nil+ moves to home
+      # @param column [Integer, nil] column number
+      # @return (see .[])
       def cursor_pos(row, column = nil)
         return column ? "\e[;#{column}H" : "\e[H" unless row
         column ? "\e[#{row};#{column}H" : "\e[#{row}H"
@@ -372,142 +367,162 @@ module Terminal
 
       # Show cursor.
       #
-      # @return (see cursor_up)
+      # @return (see .[])
       def cursor_show = +CURSOR_SHOW
 
       # Hide cursor.
       #
-      # @return (see cursor_up)
+      # @return (see .[])
       def cursor_hide = +CURSOR_HIDE
 
       # Save current cursor position.
       #
-      # @return (see cursor_up)
-      def cursor_save_pos = +CURSOR_POS_SAVE
-
-      # Restore saved cursor position.
+      # @see .cursor_restore_pos
       #
-      # @return (see cursor_up)
-      def cursor_restore_pos = +CURSOR_POS_RESTORE
+      # @return (see .[])
+      def cursor_save_pos = +CURSOR_POS_SAVE
 
+      # Restore previously saved cursor position.
       #
-      # @!endgroup
-      #
-      # @!group Screen manipulation
+      # @see .cursor_save_pos
       #
+      # @return (see .[])
+      def cursor_restore_pos = +CURSOR_POS_RESTORE
 
-      # Erase screen part.
+      # Erase part of the screen.
       #
-      # @param part [:below, :above, :all, :scrollback] screen part to erase
-      # @return (see cursor_up)
+      # @param part [Symbol] area to erase:
+      #   +:all+, +:below+, +:above+, or +:scrollback+
+      # @return (see .[])
       def screen_erase(part = :all) = "\e[#{@screen_erase[part]}J"
 
-      # Safe current screen.
+      # Save screen state.
+      #
+      # @see .screen_restore
       #
-      # @return (see cursor_up)
+      # @return (see .[])
       def screen_save = +SCREEN_SAVE
 
-      # Restore current screen.
+      # Restore previously saved screen state.
       #
-      # @return (see cursor_up)
+      # @see .screen_save
+      #
+      # @return (see .[])
       def screen_restore = +SCREEN_RESTORE
 
-      # Use alternative screen buffer.
+      # Switch to the alternate screen buffer.
+      #
+      # @see .screen_alternate_off
       #
-      # @return (see cursor_up)
+      # @return (see .[])
       def screen_alternate = +SCREEN_ALTERNATE
 
-      # Do not longer use alternative screen buffer.
+      # Switch back from the alternate screen buffer.
+      #
+      # @see .screen_alternate
       #
-      # @return (see cursor_up)
+      # @return (see .[])
       def screen_alternate_off = +SCREEN_ALTERNATE_OFF
 
-      # Scroll window given lines up.
+      # Scroll the screen up.
       #
-      # @param lines [Integer] number of lines to scroll
-      # @return (see cursor_up)
+      # @param (see .cursor_up)
+      # @return (see .[])
       def screen_scroll_up(lines = 1) = "\e[#{lines}S"
 
-      # Scroll window given lines down.
+      # Scroll the screen down.
       #
-      # @param (see scroll_up)
-      # @return (see cursor_up)
+      # @param (see .cursor_up)
+      # @return (see .[])
       def screen_scroll_down(lines = 1) = "\e[#{lines}T"
 
+      # Repeat the last printed character.
       #
-      # @!endgroup
+      # @param count [Integer] number of repetitions
+      # @return (see .[])
+      def char_repeat(count = 1) = "\e[#{count}b"
+
+      # Erase part of the current line.
+      #
+      # @param part [Symbol] area to erase:
+      #   +:all+, +:to_end+, or +:to_start+
+      # @return (see .[])
+      def line_erase(part = :all) = "\e[#{@line_erase[part]}K"
+
+      # Set the terminal window title.
+      # @note Supported by Hyper, iTerm2, Kitty, macOS Terminal, Tabby,
+      #   WezTerm.
       #
-      # @!group Other ANSI control functions
+      # @example
+      #   Terminal.raw_write(Terminal::Ansi.title('My App'))
       #
+      # @param title [String] the title text
+      # @return (see .[])
+      def title(title) = "\e]0;#{title}\a"
 
-      # Repeat last char.
+      # Start a hyperlink (OSC 8).
       #
-      # @param count [Integer] repeat count
-      # @return (see cursor_up)
-      def char_repeat(count = 1) = "\e[#{count}b"
+      # @note Supported by Ghostty, iTerm2, Kitty, Rio, Tabby, WezTerm.
+      #
+      # @see .link
+      # @see .link_end
+      #
+      # @param url [#to_s] the link URL
+      # @param params [Hash] optional link parameters (e.g., +id:+)
+      # @return (see .[])
+      def link_start(url, **params)
+        "\e]8;#{params.map { it.join('=') }.join(':')};#{url}\a"
+      end
 
-      # Erase part of line.
+      # End a hyperlink.
       #
-      # @param part [:to_end, :to_start, :all] line part to erase
-      # @return (see cursor_up)
-      def line_erase(part = :all) = "\e[#{@line_erase[part]}K"
+      # @see .link_start
+      #
+      # @return (see .[])
+      def link_end = +LINK_END
 
-      # Set (tab) title.
-      # This is not widely supported; works for
-      # Hyper,
-      # iTerm2,
-      # Kitty,
-      # MacOS Terminal,
-      # Tabby,
-      # WezTerm.
-      #
-      # @param title [#to_s] text
-      # @return (see cursor_up)
-      def title(title) = "\e]0;#{title}\a"
+      # Create a complete hyperlink (OSC 8).
+      #
+      # @see .link_start
+      # @see .link_end
+      #
+      # @example
+      #   Terminal::Ansi.link('https://example.com', 'Example')
+      #
+      # @param (see .link_start)
+      # @param text [String] the visible link text
+      # @return (see .[])
+      def link(url, text, **params)
+        "#{link_start(url, **params)}#{text}#{LINK_END}"
+      end
 
-      # Create a hyperlink.
-      # This is not widely supported; works for
-      # Ghostty,
-      # iTerm2,
-      # Kitty,
-      # Rio,
-      # Tabby,
-      # WezTerm.
-      #
-      # @param url [#to_s] URL to link to
-      # @param text [#to_s] text to display for the link
-      # @return (see cursor_up)
-      def link(url, text) = "\e]8;;#{url}\a#{text}\e]8;;\a"
-
-      # Show a simple notification.
-      # This is not widely supported; works for
-      # Ghostty,
-      # iTerm2,
-      # Kitty,
-      # WezTerm.
-      #
-      # @param text [#to_s] text to display
-      # @return (see cursor_up)
+      # Send a desktop notification via the terminal.
+      # @note Supported by Ghostty, iTerm2, Kitty, WezTerm.
+      #
+      # @example
+      #   Terminal.raw_write(Terminal::Ansi.notify('Build complete!'))
+      #
+      # @param text [to_s] the notification text
+      # @return (see .[])
       def notify(text) = "\e]9;#{text}\a"
 
-      # Set task progress state.
-      # This is not widely supported; works for
-      # Ghostty,
-      # iTerm2,
-      # Kitty.
-      #
-      # @param state [:show, :warning, :error, :indeterminate, :hide]
-      #   - `:show`
-      #     show progress indicator with given percent value in default mode
-      #   - `:warning`
-      #     show progress with given percent value in warning mode
-      #   - `:error`
-      #     show progress with given percent value in error mode
-      #   - `:indeterminate`
-      #     show progress in indeterminate state (percent value is ignored)
-      #   - `:hide`
-      #     hide progress indicator (percent value is ignored)
-      # @return (see cursor_up)
+      # Show or update a progress indicator in the terminal tab/title
+      # bar.
+      #
+      # @note Supported by Ghostty, iTerm2, Kitty.
+      #
+      # @example
+      #   Terminal.raw_write(Terminal::Ansi.progress(50))     # 50%
+      #   Terminal.raw_write(Terminal::Ansi.progress(:error)) # error state
+      #   Terminal.raw_write(Terminal::Ansi.progress(nil))    # hide
+      #
+      # @param state [Symbol, Numeric, Boolean] progress state:
+      #   - +:show+ or +true+ to show, `:err`/`:error`, `:warn`/`:warning`,
+      #   +:indeterminate+, a +Numeric+ (0-100) to set percentage, or
+      #   any other value to hide
+      # @param percent [Integer] progress percentage (0-100, used with
+      #   +:show+ state)
+      # @return (see .[])
       def progress(state, percent = 0)
         case state
         when :show, true
@@ -526,32 +541,28 @@ module Terminal
         "\e]9;4;#{state};#{percent.to_i.clamp(0, 100)}\a"
       end
 
-      # Create scaled text.
-      # It uses the
+      # Scale text using the
       # [text sizing protocol](https://sw.kovidgoyal.net/kitty/text-sizing-protocol).
-      # This is not widely supported; works for Kitty.
+      #
+      # @note Only supported by Kitty.
       #
       # @example Double-height Greeting
       #   Terminal::Ansi.scale('Hello Ruby!', scale: 2)
       #
       # @example Half-height Greeting
-      #   Terminal::Ansi.scale('Hello Ruby!', fracn: 1, fracd: 2, vertical: :centered)
-      #
-      # @param text [#to_s]
-      #   text to scale
-      # @param scale [Integer, nil]
-      #   overall scale size, range 1..7
-      # @param width [Integer, nil]
-      #   with in cells, range 0..7
-      # @param fracn [Integer, nil]
-      #   numerator for the fractional scale, range: 0..15
-      # @param fracd [Integer, nil]
-      #   denominator for the fractional scale, range: 0..15, > fracn
-      # @param vertical [:top, :bottom, :centered, nil]
-      #   vertical alignment to use for fractionally scaled text
-      # @param horizontal [:left, :right, :centered, nil]
-      #   horizontal alignment to use for fractionally scaled text
-      # @return (see cursor_up)
+      #   Terminal::Ansi.scale('Hello Ruby!', fracn: 1, fracd: 2, vertical: :middle)
+      #
+      # @param text [#to_s] text to scale
+      # @param scale [Integer, nil] scale multiplier (1-7)
+      # @param width [Integer, nil] width mode (0-7)
+      # @param fracn [Integer, nil] fractional numerator (0-15)
+      # @param fracd [Integer, nil] fractional denominator
+      #   (must be > fracn, max 15)
+      # @param vertical [Symbol, Integer, nil] vertical alignment:
+      #   +:top+, +:bottom+, +:middle+
+      # @param horizontal [Symbol, Integer, nil] horizontal alignment:
+      #   +:left+, +:right+, +:center+
+      # @return (see .[])
       def scale(
         text,
         scale: nil,
@@ -571,7 +582,7 @@ module Terminal
             opts << 'v=0'
           when 1, :bottom
             opts << 'v=1'
-          when 2, :centered
+          when 2, :middle
             opts << 'v=2'
           end
           case horizontal
@@ -579,7 +590,7 @@ module Terminal
             opts << 'h=0'
           when 1, :right
             opts << 'h=1'
-          when 2, :centered
+          when 2, :center
             opts << 'h=2'
           end
         end
@@ -601,10 +612,6 @@ module Terminal
       end
     end
 
-    @cbase = { 'bg' => '48', 'on' => '48', 'ul' => '58' }
-    @cbase.default = '38'
-    @cbase.freeze
-
     @re_test =
       /
       (?:\e\[[\x30-\x3f]*[\x20-\x2f]*[a-zA-Z])
@@ -616,139 +623,128 @@ module Terminal
 
     clr_map = {
       # foreground
-      '30' => 'black',
-      '31' => 'red',
-      '32' => 'green',
-      '33' => 'yellow',
-      '34' => 'blue',
-      '35' => 'magenta',
-      '36' => 'cyan',
-      '37' => 'white',
-      '39' => 'default', # reset
+      'black' => '30',
+      'red' => '31',
+      'green' => '32',
+      'yellow' => '33',
+      'blue' => '34',
+      'magenta' => '35',
+      'cyan' => '36',
+      'white' => '37',
+      'default' => '39',
       # background
-      '40' => 'on_black',
-      '41' => 'on_red',
-      '42' => 'on_green',
-      '43' => 'on_yellow',
-      '44' => 'on_blue',
-      '45' => 'on_magenta',
-      '46' => 'on_cyan',
-      '47' => 'on_white',
-      '49' => 'on_default', # reset
+      'on_black' => '40',
+      'on_red' => '41',
+      'on_green' => '42',
+      'on_yellow' => '43',
+      'on_blue' => '44',
+      'on_magenta' => '45',
+      'on_cyan' => '46',
+      'on_white' => '47',
+      'on_default' => '49',
       # underline
-      '58;2;0;0;0' => 'ul_black',
-      '58;2;0;0;128' => 'ul_blue',
-      '58;2;0;0;255' => 'ul_bright_blue',
-      '58;2;0;128;0' => 'ul_green',
-      '58;2;0;128;128' => 'ul_cyan',
-      '58;2;0;255;0' => 'ul_bright_green',
-      '58;2;0;255;255' => 'ul_bright_cyan',
-      '58;2;128;0;0' => 'ul_red',
-      '58;2;128;0;128' => 'ul_magenta',
-      '58;2;128;128;0' => 'ul_yellow',
-      '58;2;128;128;128' => 'ul_white',
-      '58;2;255;0;0' => 'ul_bright_red',
-      '58;2;255;0;255' => 'ul_bright_magenta',
-      '58;2;255;255;0' => 'ul_bright_yellow',
-      '58;2;255;255;255' => 'ul_bright_white',
-      '58;2;64;64;64' => 'ul_bright_black',
-      '59' => 'ul_default', # reset
+      'ul_black' => '58;2;0;0;0',
+      'ul_blue' => '58;2;0;0;128',
+      'ul_bright_blue' => '58;2;0;0;255',
+      'ul_green' => '58;2;0;128;0',
+      'ul_cyan' => '58;2;0;128;128',
+      'ul_bright_green' => '58;2;0;255;0',
+      'ul_bright_cyan' => '58;2;0;255;255',
+      'ul_red' => '58;2;128;0;0',
+      'ul_magenta' => '58;2;128;0;128',
+      'ul_yellow' => '58;2;128;128;0',
+      'ul_white' => '58;2;128;128;128',
+      'ul_bright_red' => '58;2;255;0;0',
+      'ul_bright_magenta' => '58;2;255;0;255',
+      'ul_bright_yellow' => '58;2;255;255;0',
+      'ul_bright_white' => '58;2;255;255;255',
+      'ul_bright_black' => '58;2;64;64;64',
+      'ul_default' => '59',
       # bright foreground
-      '90' => 'bright_black',
-      '91' => 'bright_red',
-      '92' => 'bright_green',
-      '93' => 'bright_yellow',
-      '94' => 'bright_blue',
-      '95' => 'bright_magenta',
-      '96' => 'bright_cyan',
-      '97' => 'bright_white',
+      'bright_black' => '90',
+      'bright_red' => '91',
+      'bright_green' => '92',
+      'bright_yellow' => '93',
+      'bright_blue' => '94',
+      'bright_magenta' => '95',
+      'bright_cyan' => '96',
+      'bright_white' => '97',
       # bright background
-      '100' => 'on_bright_black',
-      '101' => 'on_bright_red',
-      '102' => 'on_bright_green',
-      '103' => 'on_bright_yellow',
-      '104' => 'on_bright_blue',
-      '105' => 'on_bright_magenta',
-      '106' => 'on_bright_cyan',
-      '107' => 'on_bright_white'
-    }.invert
-    clr_alias = ->(t, s) { clr_map[t] = clr_map[s] }
-
-    %w[black red green yellow blue magenta cyan white].each do |name|
-      clr_alias["fg_#{name}", name]
-      clr_alias["bg_#{name}", "on_#{name}"]
-      clr_alias["fg_bright_#{name}", "bright_#{name}"]
-      clr_alias["bg_bright_#{name}", "on_bright_#{name}"]
-    end
-    clr_alias['fg_default', 'default']
-    clr_alias['bg_default', 'on_default']
+      'on_bright_black' => '100',
+      'on_bright_red' => '101',
+      'on_bright_green' => '102',
+      'on_bright_yellow' => '103',
+      'on_bright_blue' => '104',
+      'on_bright_magenta' => '105',
+      'on_bright_cyan' => '106',
+      'on_bright_white' => '107'
+    }
+
+    @colors = clr_map.keys.map!(&:to_sym).sort!.freeze
 
     attr_map = {
-      '' => 'reset',
-      '1' => 'bold',
-      '2' => 'faint',
-      '3' => 'italic',
-      '4' => 'underline',
-      '5' => 'blink',
-      '6' => 'rapid_blink',
-      '7' => 'invert',
-      '8' => 'hide',
-      '9' => 'strike',
-      '10' => 'primary_font',
-      '11' => 'font1',
-      '12' => 'font2',
-      '13' => 'font3',
-      '14' => 'font4',
-      '15' => 'font5',
-      '16' => 'font6',
-      '17' => 'font7',
-      '18' => 'font8',
-      '19' => 'font9',
-      '20' => 'fraktur',
-      '21' => 'double_underline',
-      '22' => 'bold_off', # faint_off
-      '23' => 'italic_off', # fraktur_off
-      '24' => 'underline_off', # double_underline_off
-      '25' => 'blink_off', # rapid_blink_off
-      '26' => 'proportional',
-      '27' => 'invert_off',
-      '28' => 'hide_off',
-      '29' => 'strike_off',
-      # colors ...
-      '50' => 'proportional_off',
-      '51' => 'framed',
-      '52' => 'encircled',
-      '53' => 'overlined',
-      '54' => 'framed_off', # encircled_off
-      '55' => 'overlined_off',
+      'reset' => '',
+      'bold' => '1',
+      'faint' => '2',
+      'italic' => '3',
+      'underline' => '4',
+      'blink' => '5',
+      'rapid_blink' => '6',
+      'invert' => '7',
+      'hide' => '8',
+      'strike' => '9',
+      'primary_font' => '10',
+      'font1' => '11',
+      'font2' => '12',
+      'font3' => '13',
+      'font4' => '14',
+      'font5' => '15',
+      'font6' => '16',
+      'font7' => '17',
+      'font8' => '18',
+      'font9' => '19',
+      'fraktur' => '20',
+      'double_underline' => '21',
+      'bold_off' => '22',
+      'faint_off' => '22',
+      'italic_off' => '23',
+      'fraktur_off' => '23',
+      'underline_off' => '24',
+      'double_underline_off' => '24',
+      'blink_off' => '25',
+      'rapid_blink_off' => '25',
+      'proportional' => '26',
+      'invert_off' => '27',
+      'hide_off' => '28',
+      'strike_off' => '29',
+      # ...
+      'proportional_off' => '50',
+      'framed' => '51',
+      'encircled' => '52',
+      'overlined' => '53',
+      'framed_off' => '54',
+      'encircled_off' => '54',
+      'overlined_off' => '55',
       # ...
-      '73' => 'superscript',
-      '74' => 'subscript',
-      '75' => 'superscript_off', # subscript_off
+      'superscript' => '73',
+      'subscript' => '74',
+      'superscript_off' => '75',
+      'subscript_off' => '75',
       # special underline
-      '4:3' => 'curly_underline',
-      '4:4' => 'dotted_underline',
-      '4:5' => 'dashed_underline',
-      '4:0' => 'curly_underline_off' # dotted_underline_off, dashed_underline_off
-    }.invert
-    attr_alias = ->(t, s) { attr_map[t] = attr_map[s] }
+      'curly_underline' => '4:3',
+      'dotted_underline' => '4:4',
+      'dashed_underline' => '4:5',
+      'curly_underline_off' => '4:0',
+      'dotted_underline_off' => '4:0',
+      'dashed_underline_off' => '4:0'
+    }
 
-    attr_alias['faint_off', 'bold_off']
-    attr_alias['fraktur_off', 'italic_off']
-    attr_alias['double_underline_off', 'underline_off']
-    attr_alias['rapid_blink_off', 'blink_off']
-    attr_alias['encircled_off', 'framed_off']
-    attr_alias['subscript_off', 'superscript_off']
-    attr_alias['dotted_underline_off', 'curly_underline_off']
-    attr_alias['dashed_underline_off', 'curly_underline_off']
+    attr_alias = ->(t, s) { attr_map[t] = attr_map[s] }
 
-    # extra aliases:
+    # aliases:
     attr_alias['off', 'reset']
     attr_alias['dim', 'faint']
     attr_alias['dim_off', 'faint_off']
-    attr_alias['conceal', 'hide']
-    attr_alias['conceal_off', 'hide_off']
-    attr_alias['reveal', 'hide_off']
     attr_alias['spacing', 'proportional']
     attr_alias['spacing_off', 'proportional_off']
 
@@ -761,20 +757,26 @@ module Terminal
     attr_alias['h', 'hide']
     attr_alias['s', 'strike']
     attr_alias['uu', 'double_underline']
-    attr_alias['ovr', 'overlined']
-    attr_alias['sup', 'superscript']
-    attr_alias['sub', 'subscript']
     attr_alias['cu', 'curly_underline']
     attr_alias['dau', 'dashed_underline']
     attr_alias['dou', 'dotted_underline']
+    attr_alias['ovr', 'overlined']
+    attr_alias['sup', 'superscript']
+    attr_alias['sub', 'subscript']
 
-    @colors = clr_map.keys.map!(&:to_sym).sort!.freeze
     @attributes = attr_map.keys.map!(&:to_sym).sort!.freeze
 
     # shortcuts disable:
     attr_map.keys.each do |n|
       attr_alias["/#{n.delete_suffix('_off')}", n] if n.end_with?('_off')
     end
+
+    # additional shortcuts disable:
+    attr_alias['/', 'reset']
+    attr_map['/bg'] = clr_map['on_default']
+    attr_map['/fg'] = clr_map['default']
+    attr_map['/ul'] = clr_map['ul_default']
+
     attr_alias['/b', 'bold_off']
     attr_alias['/d', 'dim_off']
     attr_alias['/i', 'italic_off']
@@ -783,26 +785,24 @@ module Terminal
     attr_alias['/h', 'hide_off']
     attr_alias['/s', 'strike_off']
     attr_alias['/uu', 'double_underline_off']
-    attr_alias['/ovr', 'overlined_off']
-    attr_alias['/sup', 'superscript_off']
-    attr_alias['/sub', 'subscript_off']
     attr_alias['/cu', 'curly_underline_off']
     attr_alias['/dau', 'dashed_underline_off']
     attr_alias['/dou', 'dotted_underline_off']
+    attr_alias['/ovr', 'overlined_off']
+    attr_alias['/sup', 'superscript_off']
+    attr_alias['/sub', 'subscript_off']
 
-    # additional shortcuts disable:
-    attr_alias['/', 'reset']
-    attr_map['/fg'] = clr_map['default']
-    attr_map['/bg'] = clr_map['on_default']
-    attr_map['/ul'] = clr_map['ul_default']
+    @cbase = { 'on' => '48', 'ul' => '58' }
+    @cbase.default = '38'
+    @cbase.freeze
 
     @attr_map =
       Hash.new do |_, str|
-        b, v = /\A(fg|bg|on|ul)?_?#?([[:xdigit:]]{1,6})\z/.match(str)&.captures
+        b, v = /\A(on|ul)?_?#?([[:xdigit:]]{1,6})\z/.match(str)&.captures
         unless v
-          b = /\A(fg|bg|on|ul)?_?([a-z]{3,}[0-9]{0,3})\z/.match(str) or next
-          name = NAMED_COLORS[b[2]] or next
-          next "#{@cbase[b[1]]};#{name}"
+          b = /\A(on|ul)?_?([a-z]{3,}[0-9]{0,3})\z/.match(str) or next
+          v = NAMED_COLORS[b[2]] or next
+          next "#{@cbase[b[1]]};#{v}"
         end
         case v.size
         when 1, 2
@@ -813,7 +813,7 @@ module Terminal
           "#{@cbase[b]};2;#{v[0, 2].hex};#{v[2, 2].hex};#{v[4, 2].hex}"
         end
       end
-    attr_map.merge!(clr_map).keys.sort!.each { @attr_map[_1] = attr_map[_1] }
+    attr_map.merge!(clr_map).keys.sort!.each { @attr_map[it] = attr_map[it] }
     @attr_map.freeze
 
     @attrs_map = @attr_map.transform_keys(&:to_sym)
@@ -828,12 +828,15 @@ module Terminal
     @line_erase.default = '2'
     @line_erase.compare_by_identity.freeze
 
-    autoload :NAMED_COLORS, "#{__dir__}/ansi/named_colors.rb"
-    private_constant :NAMED_COLORS
-
     # @private
     RESET = -self[:reset]
 
+    # @private
+    RESET_FG = -self[:default]
+
+    # @private
+    RESET_BG = -self[:on_default]
+
     # @private
     FULL_RESET = "\ec"
 
@@ -843,6 +846,13 @@ module Terminal
     CURSOR_FIRST_ROW = -cursor_pos(1)
     # @private
     CURSOR_FIRST_COLUMN = -cursor_column(1)
+    # @private
+    CURSOR_NEXT_LINE = -cursor_next_line(nil)
+
+    # @private
+    CURSOR_BACK = -cursor_back(nil)
+    # @private
+    CURSOR_FORWARD = -cursor_forward(nil)
 
     # @private
     CURSOR_SHOW = "\e[?25h"
@@ -893,6 +903,9 @@ module Terminal
     # @private
     LINE_ERASE_PREV = -"#{cursor_prev_line(nil)}#{LINE_ERASE}"
 
+    # @private
+    LINK_END = "\e]8;;\a"
+
     # @private
     PROGRESS_HIDE = "\e]9;4;0;0\a"
     # @private
@@ -929,5 +942,10 @@ module Terminal
     #   https://sw.kovidgoyal.net/kitty/color-stack
     #   https://sw.kovidgoyal.net/kitty/deccara
     #   https://sw.kovidgoyal.net/kitty/clipboard
+
+    dir = "#{__dir__}/ansi"
+    autoload :NAMED_COLORS, "#{dir}/named_colors.rb"
+    autoload :ScreenViewer, "#{dir}/screen_viewer.rb"
+    private_constant :NAMED_COLORS
   end
 end