typr 1.7.0 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 75b5f8bf6bcd9c1e957f87f8ef47eaec83784cefcc3903ea9e68b25f0280d7af
-  data.tar.gz: 1e92d998f96105408ac13e6c43f49ae2a44cdf0b2e6e34596f55749228beff29
+  metadata.gz: 74b0a2cd082b9a2ee58f9fb64356a7ed4f5a970c0427768acae334ae3325748a
+  data.tar.gz: af90bbcfff025ba60f1d8de7cae5171152f8939a00a7fac5975cc95785a28547
 SHA512:
-  metadata.gz: 3fb8fb7f24580c81250951138b3600037ce3eef21acc48a17c79db4c3fe5cceddd8037e1cb04548d85d2fde048426fa90c08846b09b9c8b2ad06472106813058
-  data.tar.gz: 83f72c57b64e9515c27ddea087bdce0ad2d935e98b697a7e8b5d0de9885aa9dab18f15143437e4b8f0136899d5a6b08c5b7712dbd8f5b8d2f41ab56cb8c5d598
+  metadata.gz: c29e087834938ef34608086cb90ec221760ca50f0be054e7d9602f46cc6e63c73fbe06a960c8b55e551b17159f404d796f275e3a11cddcb3f70baccefc67636b
+  data.tar.gz: a33662ba4009f34cef2e91b5295a6fc1e3f2b17ebd9edf118052caa016e6dc0d8dd4d6f2c3fb468244f2e488e589c1ec79236f2a7001bc4e6622064fcf9a3365

data/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## [vx.y.z] — __DATE__
 
+## [v1.9.0] — 2026-10-12
+
+### Changed
+- RI documentation pass — every class, method, attribute, and constant now carries a doc comment with behavior, `@param`/`@return` contracts, and runnable examples: RDoc reports 222/222 parts documented (previously 38 undocumented). Grouped comments were split so RDoc attaches them to each sibling attribute/method, and the generated `Space` edge accessors are documented through their `attr_writer` entry
+- `Typr#prepare` slimmed to pad-or-delegate — the 13-line manual width scan duplicated `real_size` and `clip`, so it now clips overflow via `clip` (the single truncation engine) and pads the result to exact width; the uncalled and broken `fade` flag (standalone `fade` is unchanged) is dropped
+- Read-line internals made private — `Typr.slice_width` and `word_prev`/`word_next` serve only `read_line`, so they are `private_class_method` now; their doc blocks stay for RI
+- Live list narrowing is labeled `[/]:narrow`, not `[/]:search` — the bar action shrinks the listing as you type, while `search` keeps meaning only pager find-in-text (`/`, `n`, `p`). The method is renamed `Browser#search` → `#narrow` (`search` stays as an alias, so stale configs wired to `!search` keep working)
+
+### Fixed
+- Overtype guard scoped to `Grid#pick` and fixed for canonical ttys — private `drain_quiet` (called bare by `read_key`) waits out an armed window in raw mode, since canonical-buffered keystrokes are invisible to `select` and the old guard timed out only to deliver them late; each arrival restarts the window; `flush_overtype` and the `quiet_window?` predicate are gone, `drain_input` is back to a plain pending-bytes flush, and `suppress_keys` remains the sole arming seam for `Grid#pick` selections (filecon drops its two `flush_overtype` calls)
+- Doc comments corrected where they disagreed with the code — `Grid#header=` defines `Typr::NAME` holding the column index (not `NAME_0 = "name"`); the mouse header-click sort doc sat on `sort_by` instead of `Grid#send`; `Grid#pick` now documents the single-match auto-return, the 0.5s overtype quiet window, and `:none` disabling both; `Line#ask` documents the `[:line, { initial: }]` inline-editor form; `Line#cli` no longer mentions a removed `completions:` option; `Browser#bottom` reserves only the command-line row (the path bar is `top`)
+
+## [v1.8.0] — 2026-10-11
+
+### Changed
+- Sort indicator uses solid triangles (▲▼) instead of thin arrows, for a heavier mark at the same single-cell width
+
+### Fixed
+- Text paints new spans once at entry and rebuilds only reflow: scheme and content colors survive resizes and appends without stacking or stripping
+- Terminal self-test renders without scrolling and covers all named colors — status line uses raw output on the last row (`p` scrolled with inspect quotes and a newline), rows are capped to the visible area, the 256-ramp starts at a known position, the color list includes all `COLOR_MAP` names plus the full grey ramp, and the fg/bg steppers clamp to valid ids
+- String headers fit inside minimal-width boxes — the box ignored the margin in the header width, so the border overwrote the last header character; single `:max` columns provably span the widget width
+- Word jumps are documented as alt-arrow, not ctrl-arrow — README, the `read_line` doc comment, and the v1.2.0 entry called them ctrl-arrow while the bindings are `KEY_ALT_LEFT`/`KEY_ALT_RIGHT` (SGR modifier 3 = alt); the package's key modifier is alt everywhere
+- Command-line redraw overwrites in place — `read_line` cleared the row on every keypress, flashing on cursor moves; each frame now pads to end-of-line with spaces instead, so shrinking content leaves no ghosts either
+- Cursor stays hidden while the command line redraws — every keypress parked the visible cursor at the prompt between the home move and the edit-position move; each frame now hides it first and shows it at the edit position
+- Mode table corrected to standard SGR order (`dim` restored, so `slow→5` and `invert→7`) with `:steady` at position 25 for blink-off; `mode_code` stays index-by-position
+
 ## [v1.7.0] — 2026-10-02
 
 ### Fixed
@@ -100,7 +126,7 @@
 ## [v1.2.0] — 2026-08-02
 
 ### Added
-- `Typr.read_key` / `Typr.read_line` — the public terminal input API: `read_key` reads a raw key; `read_line` is the shared interactive line editor that renders a prompt + query at any position with arrow keys, ctrl-arrow word jumps, Home/End/Delete/Backspace, Escape aborts (`nil`), Enter confirms, and an optional block runs after each keypress
+- `Typr.read_key` / `Typr.read_line` — the public terminal input API: `read_key` reads a raw key; `read_line` is the shared interactive line editor that renders a prompt + query at any position with arrow keys, alt-arrow word jumps, Home/End/Delete/Backspace, Escape aborts (`nil`), Enter confirms, and an optional block runs after each keypress
 - `Line#ask` strict question types — `Array` (pick from an object/column), `:key`, `:line`; the question and answer are rendered in `@colors[:question]`/`@colors[:answer]`
 - `Line#align` attribute (`:left`/`:right`) for text alignment in draw
 - `dark_*` named colors (`dark_red`, `dark_green`, `dark_yellow`, `dark_blue`, `dark_magenta`, `dark_cyan`) and a `COLOR_MAP` of popular named colors in `color_code`

data/README.md

@@ -185,7 +185,7 @@ Clears the full screen or a single line (`:line`).
 Reads a single keypress in raw mode. Returns the key as a String (`KEY_ESCAPE`, `?q`, arrow escape sequences), a `Typr::Mouse` struct for mouse reports, or `nil` when input is unavailable.
 
 ### `Typr.read_line(prompt, ...)`
-The shared interactive line editor. Renders a prompt and query at any position with arrow keys, ctrl-arrow word jumps, Home/End/Delete/Backspace; Enter confirms, Escape aborts (`nil`). An optional block runs after each keypress and may short-circuit with a result. Pass `completions:` — a callable `->(query, cursor) { candidates }` — and TAB matches the current word against `candidates` in a pick grid: a candidate is either a string or `[text, color-pair]` to tint its pick entry. Pass `regex:` — a Hash of `Regexp => color`, or a scheme name (`:generic`, `:shell`) — and matching regions of the query are colored as they are typed, restoring the prompt's trailing color code. The editor is agnostic to where candidates come from.
+The shared interactive line editor. Renders a prompt and query at any position with arrow keys, alt-arrow word jumps, Home/End/Delete/Backspace; Enter confirms, Escape aborts (`nil`). An optional block runs after each keypress and may short-circuit with a result. Pass `completions:` — a callable `->(query, cursor) { candidates }` — and TAB matches the current word against `candidates` in a pick grid: a candidate is either a string or `[text, color-pair]` to tint its pick entry. Pass `regex:` — a Hash of `Regexp => color`, or a scheme name (`:generic`, `:shell`) — and matching regions of the query are colored as they are typed, restoring the prompt's trailing color code. The editor is agnostic to where candidates come from.
 
 ```ruby
 Typr.read_line "/", completions: ->(query, cursor) {

data/lib/browser.rb

@@ -5,6 +5,7 @@ require_relative 'line.rb'
 
 module Typr
 
+  # Bundled extension => MIME-type database (share/mimetypes).
   MIMETYPES = eval File.read( __dir__ + "/../share/mimetypes" )
 
   # A file-system directory browser built on Grid. Renders entries as rows
@@ -33,14 +34,39 @@ module Typr
   #   Escape          | quit, returns nil
 
   class Browser < Grid
+    ##
+    # Browser state: +directory+ the current path, +user+ the login name
+    # shown in the info bar, +pwd+ alias of +directory+, +view+ the active
+    # column view name.
+    #
+    #   browser.directory   #=> "/tmp/"
+    #   browser.view        #=> :compact
+
     attr_accessor :directory, :user, :pwd, :view
+    ##
+    # +mimetype_db+ toggles the bundled extension database, +mimetype_magic+
+    # the +file --mime-type+ fallback for unknown extensions.
+    #
+    #   browser.mimetype_db = false   # skip extension lookups
+
     attr_accessor :mimetype_db, :mimetype_magic
 
-    ## Height minus 2 rows reserved for path bar and command line.
+    ##
+    # Bottom edge pulled in one row for the command line (the path bar is
+    # reserved by {#top}).
+    #
+    #   browser.bottom   #=> terminal_bottom - 1
+    #
+    # @return [Integer]
 
     def bottom; super - 1 end
 
-    ## Top offset plus one row for the path info bar.
+    ##
+    # Top edge pushed down one row for the path info bar.
+    #
+    #   browser.top   #=> constructor top + 1
+    #
+    # @return [Integer]
 
     def top; super + 1 end
 
@@ -53,6 +79,11 @@ module Typr
     #   browser.cd "~"           # => changes to home
     #   browser.cd ".."          # => parent directory
     #   browser.cd 2             # => jump to history entry 2
+    #
+    # @param dir [String, Integer] target path or history index
+    # @param append [Boolean] scan without clearing (used by history)
+    # @param trim [Integer] path prefix trim for the +path+ column
+    # @return [false, nil] false when the directory cannot be opened
 
     def cd dir, append=false, trim=0
       return unless dir
@@ -176,10 +207,15 @@ module Typr
     end
 
     ##
-    # Resolves hint characters typed on a row. Returns the matching row id
-    # for fast navigation, otherwise falls through to Stack#send.
+    # Resolve hint characters typed on a row to a row id; a click on the
+    # info bar or command line dispatches that binding instead. Falls
+    # through to {Stack#send} for keys and navigation.
+    #
+    #   browser.send "1"    # => row id if hint "1" is visible
+    #   browser.send ?s      # => runs the sort command (a bound key)
     #
-    #   browser.send "1"   # => row id if hint "1" is visible
+    # @param key [Typr::Mouse, String] mouse event, hint char, or key sequence
+    # @return [Integer, String, Symbol, nil] picked row id, bound command result, or super's response
 
     def send key
       if key.is_a?(Typr::Mouse) and key.press? and key.left?
@@ -200,19 +236,28 @@ module Typr
       else super end
     end
 
-    ## Returns the current directory path as the confirm result.
+    ##
+    # Returns the current directory path as the confirm result.
+    #
+    #   browser.confirm   #=> "/tmp/"
+    #
+    # @return [String]
 
     def confirm; return @directory end
 
     ## Prompts to select rows by index. Returns chosen ids or nil.
     #
     #   browser.mark   # => [0, 2, 5] or nil
+    #
+    # @return [Array<Integer>, nil]
 
     def mark; return @user.ask( 'mark files': [self, :rows] ) end
 
     ## Toggles selection for every row within a "from..to" range.
     #
     #   browser.mark_range   # prompts for from/to, toggles selection
+    #
+    # @return [Array<Integer>] the toggled ids
 
     def mark_range; return ids[ ( eval @user.ask(
       'mark from': [self, :relative_row], 'to': [self, :relative_row]
@@ -234,24 +279,32 @@ module Typr
     ## Navigate up one directory.
     #
     #   browser.back   # equivalent to cd ".."
+    #
+    # @return [void]
 
     def back; cd ".." end
 
     ## Navigate to the root directory.
     #
     #   browser.root   # => cd "/"
+    #
+    # @return [void]
 
     def root; cd ?/ end
 
     ## Navigate to the home directory.
     #
     #   browser.home   # => cd "~"
+    #
+    # @return [void]
 
     def home; cd ?~ end
 
     ## Toggle visibility of hidden files (those starting with a dot).
     #
-    #   browser.toggle_hidden
+    #   browser.toggle_hidden   # rescans the directory
+    #
+    # @return [void]
 
     def toggle_hidden
       @show_hidden = !@show_hidden
@@ -259,6 +312,10 @@ module Typr
     end
 
     ## Display a help grid listing all keybindings.
+    #
+    #   browser.help   # => picked binding row id or nil
+    #
+    # @return [Integer, nil]
 
     def help; @user.help end
 
@@ -266,35 +323,46 @@ module Typr
     # Reset display, selection, and position state then re-sort.
     #
     #   browser.reset_view
+    #
+    # @return [void]
 
     def reset_view; reset [:display, :selection]; cd @directory; sort end
 
     ## Open a filter popup on the chosen row/column and apply the input.
     #
     #   browser.filter_view   # prompts for filter text
+    #
+    # @return [void]
 
     def filter_view; add_filter *@user.ask(
       filter: [ popup( type: :"[f]ilter" ), :row, NAME, { column: 0 }], with: :line ) end
 
-    ## Open live `/` search filtered on the name column.
+    ## Open live `/` narrowing filtered on the name column.
     #
-    #   browser.search   # type to narrow, Escape restores, Enter commits
+    #   browser.narrow   # type to narrow, Escape restores, Enter commits
+    #
+    # @return [void]
 
-    def search
+    def narrow
       @suppress_user = true
       pick :none, column: NAME
       @suppress_user = false
     end
+    alias search narrow
 
     ## Open a sort-picker popup to choose a column to sort by.
     #
     #   browser.sort_view   # pick a column header to sort
+    #
+    # @return [void]
 
     def sort_view; sort_by @user.ask( "sort by": [ popup( type: :"[s]ort" ), :row, nil, { column: 0 }] ) end
 
     ## Open a view-picker popup and switch to the selected view.
     #
     #   browser.views   # choose :simple, :compact, :stats, or :full
+    #
+    # @return [void]
 
     def views; change_view( popup( type: :"[v]iews", input: @views.keys ).pick( :row, column: 0 ) )  end
 
@@ -503,7 +571,7 @@ full:    %i[ name size permissions executable printable owner group
         input: [ [->{Etc.getpwuid(Process.euid).name rescue ENV["USER"] || Etc.getlogin}, ->{@parent.directory},
           ->{@parent.filter_display},
           ->{ (s = @parent.sorted_by(true)) &&
-            "#{s} #{@parent.reverse ? "\u2193" : "\u2191"}"},
+            "#{s} #{@parent.reverse ? "\u25BC" : "\u25B2"}"},
           ->{@parent.view} ] ], format: [:min, :max, :min, :min, :min],
         colors: { columns: [@colors[:default], @colors[:default],
           @colors[:actions][:filter], @colors[:actions][:sort],
@@ -549,21 +617,20 @@ full:    %i[ name size permissions executable printable owner group
           wire.(label, cmd)
         end
         @user ||= Line.new( parent:self, left:->{@parent.left}, top:->{@parent.bottom+1},
-          colors: { regex: @colors[:regex] }, bindings: bindings_labels )
+          bindings: bindings_labels )
       else
-        cmds = { "[h]elp" => :help, "[/]:search" => :search,
+        cmds = { "[h]elp" => :help, "[/]:narrow" => :narrow,
           "[f]ilter" => :filter_view, "[s]ort" => :sort_view, "[v]iews" => :views,
           "[r]eset" => :reset_view, "[m]ark" => :mark,
           "[M]ark_range" => :mark_range, "mark_[a]ll" => :mark_all,
           "[i]nvert_mark" => :mark_invert, "[~]:home" => :home,
           "[H]idden_files" => :toggle_hidden }
-        plain = ["[h]elp", "[/]:search"] +
+        plain = ["[h]elp", "[/]:narrow"] +
           @colors[:actions].map { |name, _| "[" + name.to_s[0] + "]" + name.to_s[1..] } +
           %w[ [r]eset [m]ark [M]ark_range mark_[a]ll
           [i]nvert_mark [~]:home [H]idden_files [back]:.. [up] [down] [pageup] [pagedown] [home] [end] [esc]:quit [return]:confirm\  ]
         plain.each { |label| wire.(label, cmds[label]) if cmds[label] }
         @user ||= Line.new( parent:self, left:->{@parent.left}, top:->{@parent.bottom+1},
-          colors: { regex: @colors[:regex] },
           bindings: plain.map { |label|
             name = label.gsub( /[\[\]]/, '' ).downcase.to_sym
             @colors[:actions][name] ?

data/lib/grid.rb

@@ -9,16 +9,37 @@ module Typr
   #     input:  [ ["Alice", 30], ["Bob", 25] ],
   #     header: [:name, :age],
   #     format: [:max, :right]
-#   )
-#   grid.show
-#
+  #   )
+  #   grid.show
+  #
   # Column format tokens: +Integer+ (fixed width), +:min+ (auto), +:max+ (fill remaining).
   #
   # Built-in procs: +:filetree+, +:datetime+, +:magnitudes+, +:convert+.
 
   class Grid < Stack # Table
+    ##
+    # Display and transform state: +format+ per-column width tokens,
+    # +procs+ per-column processors, +filters+ the active [column, query]
+    # pairs, +data+ the rows (Array or Hash), and +map+ the visible row
+    # ids after filtering/sorting.
+    #
+    #   grid.filters  #=> [[0, "Ali"]]
+    #   grid.map      #=> [0, 2]
+
     attr_accessor :format, :procs, :filters, :data, :map
+    ##
+    # +align+ is per-column alignment, +rawsort+/+rawfilter+ flag columns
+    # to bypass their +procs+, and +reverse+ flips the sort direction.
+    #
+    #   grid.reverse = true
+    #   grid.rawsort[0] = true   # sort raw values for column 0
+
     attr_accessor :align, :rawsort, :rawfilter, :reverse
+    ##
+    # Overrides the column render order (see {#sequence}).
+    #
+    #   grid.sequence = [2, 0, 1]
+
     attr_writer :sequence
 
     ##
@@ -52,7 +73,8 @@ module Typr
     ##
     # Column render order. Defaults to 0..n-1; override with +sequence=+.
     #
-    #   grid.sequence  #=> [0, 1, 2]
+    #   grid.sequence      #=> [0, 1, 2]
+    #   grid.sequence = [2, 0, 1]
     #
     # @return [Array<Integer>]
 
@@ -115,12 +137,14 @@ module Typr
     end
 
     ##
-    # Set column headers. Symbols are auto-defined as +UPCASE_I+ constants.
+    # Set column headers. Symbols are auto-defined as +UPCASE+ constants
+    # holding the column index.
     #
-    #   grid.header = [:name, :age]
-    #   # defines NAME_0 = "name", AGE_1 = "age"
+    #   grid.header = ["name", "age"]
+    #   Typr::NAME  #=> 0
+    #   Typr::AGE   #=> 1
     #
-    # @param h [Array<String, Symbol>]
+    # @param h [Array<String, Symbol>] header labels
 
     def header=( h ); super
       h.each_with_index{ |h,i|
@@ -240,18 +264,22 @@ module Typr
     def sorted_by name=false; (name and @sort) ? @header[@sort] : @sort end
 
     ##
-    # Pick a row with live-filtering.
+    # Pick a row with live filtering. When the query narrows the list to a
+    # single row it returns immediately (no Enter needed) and arms a 0.5s
+    # overtype quiet window via +Typr.suppress_keys+, so a trailing Enter
+    # or extra characters cannot re-trigger anything. +:none+ disables the
+    # auto-return (used by {Browser#narrow}, where Escape must restore).
     #
-    # When column is given, `Grid` overrides `Stack#pick` to add interactive
-    # text filtering of rows by the given column. Filter text is shown at the
-    # bottom of the grid. Passes through to `super` for all other types or
-    # when no column is given.
+    # With no +column+, passes through to {Stack#pick}.
     #
-    #   grid.pick :row, 0, column: :name
-    #   grid.pick :row, 0, column: :all   # match any column
+    #   grid.pick :row, 0, column: 0    # type to narrow, auto-returns at 1 match
+    #   grid.pick :row, 0, column: :all # match any column
+    #   grid.pick :none, column: 0      # narrowing only, Enter commits
     #
-    # @param type [Symbol] type is ignored (always :row); passed to super otherwise
-    # @param column [Symbol, String] column name to filter on, or :all (default nil)
+    # @param type [Symbol, String] picker type; +:none+ disables auto-return
+    # @param row [Integer] ignored (always :row); passed to super otherwise
+    # @param column [Integer, Symbol, String] column index/name to filter on, or :all
+    # @return [Integer, nil] picked row id, or nil on abort
 
     def pick type = :row, row=0, column: nil
       return super(type, row) unless column
@@ -308,12 +336,15 @@ module Typr
     end
 
     ##
-    # Sort by column (toggle direction on repeat).
+    # Dispatch a mouse press on the header row to a column sort (clicking
+    # the header cell for a column calls +sort_by+); everything else falls
+    # through to {Stack#send}.
     #
-    #   grid.sort_by :age
-    #   grid.sort_by :age  # reverses
+    #   grid.send Typr::Mouse.new(0, 12, grid.top + 1, :press, 0)  #=> :scroll
+    #   grid.send Typr::KEY_DOWN                                    # scrolls
     #
-    # @param column [Integer, Symbol]
+    # @param key [Typr::Mouse, String] mouse event or key sequence
+    # @return [Symbol, Object] +:scroll+ on a header click, super's response otherwise
 
     def send key
       if key.is_a?(Typr::Mouse) and key.press? and key.left? and
@@ -328,6 +359,15 @@ module Typr
       super
     end
 
+    ##
+    # Sort by column (toggle direction on repeat).
+    #
+    #   grid.sort_by :age
+    #   grid.sort_by :age  # reverses
+    #
+    # @param column [Integer, Symbol] column index or header-name symbol
+    # @return [void]
+
     def sort_by column
       column = @header.index( column.to_s ) if column.is_a? Symbol
       if @sort and (column == @sort) then @reverse = !@reverse
@@ -411,7 +451,7 @@ module Typr
       gaps = @margin.size + @separator.size * (columns - 1)
       sum = @widths.sum
       @max = sum + gaps - 1
-      @max = [ @max, @header.length ].max if @header.is_a?(String)
+      @max = [ @max, @header.length + @margin.size ].max if @header.is_a?(String)
       space = width - gaps
       if (extra = sum - space  ) > 0
         extra.times{ |i| @widths[ @widths.index(@widths.max) ] -= 1 }
@@ -434,7 +474,7 @@ module Typr
     def print row=nil
       return super unless row
       header = ( row == :header )
-      return draw @header[0..width-1].ljust(width) if
+      return draw @header[0...(width - @margin.size)].ljust(width - @margin.size) if
         header and @header.is_a? String
       return unless row_data = header ? @header : @data[row]
       fields = row_data.dup

data/lib/line.rb

@@ -12,6 +12,16 @@ module Typr
 #   line.ask([ ["Name?", :line], ["Age?", :line] ])
 
 class Line < Space
+  ##
+  # Line state: +default+ text restored by {#reset}, +prompt+ character
+  # before answers, +bindings+ the clickable keybinding labels, +data+ the
+  # currently rendered text, +align+ (:left/:right) horizontal alignment,
+  # +trim+ (:left/:right) the side clipped on overflow.
+  #
+  #   line.default = "status: ok"
+  #   line.prompt  = "?"
+  #   line.align   = :left
+
   attr_accessor :default, :prompt, :bindings, :data, :align, :trim
 
   # Render +msg+ (String, Proc, or Space) on this line.
@@ -92,7 +102,10 @@ class Line < Space
   #   Array - interactive pick via <widget>.pick(<type>); an optional third
   #           element renders the chosen row's field into the line, and an
   #           optional fourth element is passed as pick keyword arguments
-  #           (e.g. { column: 0 } to open the pick in / search mode)
+  #           (e.g. { column: 0 } to open the pick in / search mode).
+  #           Special case: [:line, { initial: "text" }] opens the inline
+  #           editor via Typr.read_line prefilled with +initial+ instead
+  #           of a widget pick.
   #   :key  - a single keypress via Typr.read_key
   #   :line - interactive line editor via Typr.read_line at the cursor
   #
@@ -102,6 +115,7 @@ class Line < Space
   #   line.ask(name: :line)                  #=> "Alice"
   #   line.ask(keys: :key)                   #=> "a"
   #   line.ask(open: [grid, :row, :name])    #=> 2   (picked row id)
+  #   line.ask(nick: [:line, { initial: "bob" }])  #=> edited string
   #   line.ask([ ["Name?", :line], ["Ok?", :key] ])  #=> ["Alice", "a"]
 
   def ask sentence
@@ -149,23 +163,33 @@ class Line < Space
     return ( answer.one? ? answer.first : answer )
   end
 
-  # Prompt for a single command line at the cursor: +prompt+ rendered in the
-  # line's default color, typed input in the answer color. When +completions+
-  # is truthy, TAB matches the current word against the shell (commands,
-  # options, files) and replaces it through the pick grid. Regions of the
-  # typed input matching @colors[:regex] are colored as they are typed
-  # (with the :shell scheme: the first word red, double-dash options blue).
+  ##
+  # Prompt for a single command line at the cursor: +prompt+ rendered in
+  # the line's default color, typed input in the answer color. TAB
+  # matches the current word against the shell (commands, options, files)
+  # and replaces it through the pick grid. Regions of the typed input
+  # matching @colors[:regex] are colored as they are typed (with the
+  # :shell scheme: the first word red, double-dash options blue).
+  #
+  # +history+ is an Array whose entries Up/Down walk; +prefixes+ lists
+  # command-start characters stripped before completion matching;
+  # +redraw+ repaints the caller's screen after a completion pick;
+  # +regex+ overrides @colors[:regex] for this prompt.
   #
   #   line.cli "> ", initial: "cp %name"
   #   #=> "cp source.txt" (or nil on Escape)
+  #   line.cli "> ", history: @recent, prefixes: "$>"
+  #
+  # @param prompt [String] rendered before the typed input
+  # @return [String, nil] the accepted command, or nil on Escape
 
-  def cli prompt, initial: '', redraw: nil, history: nil, prefixes: nil
+  def cli prompt, initial: '', redraw: nil, history: nil, prefixes: nil, regex: nil
     re = /\A[#{Regexp.escape(prefixes || '|+=!')}]/
     source = ->(query) {
       bash_candidates(query.sub(re, '')).split("\n").reject(&:empty?).uniq }
     colored = color_code(@colors[:default]).to_s + prompt + color_code(@colors[:answer])
     Typr.read_line(colored, left: left, top: top, initial: initial,
-      completions: source, redraw: redraw, regex: @colors[:regex], history: history)
+      completions: source, redraw: redraw, regex: regex || @colors[:regex], history: history)
   end
 
   private
@@ -197,6 +221,16 @@ class Line < Space
 
   public
 
+  ##
+  # Construct a Line. Position via the {Space} boundaries; +default+ sets
+  # the text shown after {#reset}, +bindings+ the keybinding labels.
+  #
+  #   line = Typr::Line.new(top: -1, left: 0,
+  #     default: "(f)ilter, (s)ort, [esc] quit")
+  #
+  # @param args [Hash] boundary and display options (see {Space#initialize})
+  # @return [Line]
+
   def initialize args
     @right= -1
     @align = :left