typr 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5a6c88b12b4be9c1fe406898172147d1d874e0353af72d211d2530ef5a48d82f
-  data.tar.gz: 36dd949f072aa3ab232256d4c7d7c10d6989812c97977f65f72bd25ef7d6124a
+  metadata.gz: cdcaef4b1bc2c40e6fab6bd7d1462ddf19aeca03babcdbb9be74629551230647
+  data.tar.gz: b4e927b5237f27e2366ed15057054b33d9f070ef5a50c234533699182c7228ee
 SHA512:
-  metadata.gz: 87a3993d064a814f0c819a5466c4245029d38aeabd3b6b869a9d5f2f505b60daa45aecea6447dac70cee577605e8ec1d66ee5ce858751d1122614905a9983610
-  data.tar.gz: f29f2787e8cc2b606bfb215adebe21b1384bcc860b986318bfcff334105ebea72f30844124083dc6471c81a215698dbd3aa2fcfca9b63d92594c09ab89373bdf
+  metadata.gz: 889fd403e345e89dc6777c02c6736d0865b7266b16157e13e4cf2469b9a3664d68f4fe672d1f9b5b6d72316d697c2c8e20e1f920853ae495014c9fb049fed6cd
+  data.tar.gz: 662df0d3ef61d964cd8a03a1cd1f7caa7fb14a15d87c22afa3a2cdf9115f4780b944446ebcdc9f538c33ee80753e48c362fea7f716d2ef7fca2070f07fe5483f

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [v1.3.0] — 2026-08-03
+
+### Added
+- Mouse support — `Typr.init`/`Typr.exit` enable/disable mouse reporting (buttons + SGR coordinates, `CSI ? 1000 h/l` + `CSI ? 1006 h/l`); `read_key` decodes SGR and legacy X10 reports into a `Typr::Mouse` struct (`button`, `x`, `y`, `action`, `modifiers`) with `press?`/`release?`/`wheel?`/`left?`/`middle?`/`right?` predicates
+- `Stack#hit` — maps a 1-based terminal row/col to the data row id under the cursor (nil for header/margins/outside)
+- Click-to-act in pickers — a left click on a row in `Stack#pick`/`Browser#pick` acts like pressing its hint digit (selects the row; in `Browser` cd's into directories and returns file paths)
+- Wheel-to-scroll in pickers — mouse wheel up/down scrolls the listing in `Stack#pick`/`Browser#pick`
+
 ## [v1.2.0] — 2026-08-02
 
 ### Added

data/README.md

@@ -1,29 +1,44 @@
 # typr — Terminal UI Toolkit
 
-typr is a Ruby library for building interactive terminal-based user interfaces. It provides data-object based spaces and keyboard-driven interaction.
+typr is a Ruby library for building interactive, keyboard-driven terminal user interfaces. It is built from data-object based components: grids for arrays, a pager for text, a file picker, and lines for user interaction — each of which renders itself, handles its own keymap, and can be combined into full applications.
+
+typr is designed for speed: every interactive choice is one keystroke away. Selectable rows and columns carry number hints, popups open in `/` search mode so long lists can be distilled down and picked from in a couple of keystrokes. It is the toolkit behind the [Filecon](https://codeberg.org/typr/filecon) file manager.
+
+typr's terminal layer is self-contained: it ships a precompiled terminfo key table and a MIME-type database inside the gem, so it has no ncurses dependency and works on any raw, ANSI-capable terminal — including Android/Termux.
 
 ## Features
 
-### Spaces
+### Components
 
-- **Grid** — sortable, filterable table with formatted columns, colors, and row selection
-- **Text** — scrollable text viewer with word/line picking, search, and borders
-- **Browser** — file-system directory browser with MIME type detection
-- **Stack, Space** — layout containers for composing spaces
-- **Line** — interactive prompt/input with colored questions and answers
+- **Grid** — sortable, filterable table with formatted columns, per-cell colors, and row selection. Columns can be `:min`/`:max`/fixed-width, with built-in processors for dates, file sizes, and file trees. `Grid#pick column:` adds live `/` search
+- **Text** — scrollable text viewer with word/row picking, `/` search with `n`/`p` navigation and match highlighting, and borders
+- **Browser** — file-system directory browser with MIME-type detection (bundled database, optional magic detection), per-type coloring, and an interactive picker
+- **Line** — interactive prompt/input with colored questions and answers, configurable bindings, and strict `ask` question types (`Array`, `:key`, `:line`)
 
-### Frontends
+### Keyboard interaction
 
-typr supports two rendering backends, selectable via `require`:
+Navigation uses **hint numbers** displayed next to selectable items — rows in grids, words in text, and other elements. Press the number to select that item directly. When more items are visible than fit in one set of hints (1–9, 0), press **Tab** to cycle through hint groups. Arrow keys, Page Up/Down, Home/End work as expected, and all keys are dispatched through a configurable keymap.
 
-- **Terminal** (`require 'typr'`) — raw terminal IO, no dependencies beyond Ruby stdlib
-- **Graphical** (`require 'typr/graphical'`) — SDL2-based, for desktop GUI windows
+**Live `/` search** is built into listings and pickers: popups open in search mode, so you start typing to distill the list down to the matches, then press a number hint to pick from the few remaining results. `Text` adds less-style search (`/`, `n`, `p`) with smart-case matching and wrap-around.
 
-All spaces work identically across frontends.
+### Mouse support
 
-### Keyboard interaction
+typr reports and decodes mouse input. `Typr.init` enables mouse reporting and `Typr.exit` disables it; `Typr.read_key` decodes SGR and legacy X10 reports into a `Typr::Mouse` struct (`button`, `x`, `y`, `action`, `modifiers`) with `press?`/`release?`/`wheel?`/`left?`/`middle?`/`right?` predicates. Pickers accept the mouse directly: a left click acts like pressing the row's hint digit, and the wheel scrolls the listing.
 
-Navigation uses **hint numbers** displayed next to selectable items — rows in grids, columns, or other elements. Press the number to select that item directly. When more items are visible than fit in one set of hints (1-9, 0), press **Tab** to cycle through hint groups. Arrow keys, Page Up/Down, Home/End work as expected. All keys are dispatched through a configurable keymap.
+### Terminal layer
+
+The default terminal frontend is pure ANSI on raw TTY input — **no ncurses**. Key sequences and keypad escapes are precompiled into a bundled terminfo table (`share/terminfo`), and MIME types come from a bundled database (`share/mimetypes`); both ship with the gem, so typr runs anywhere a raw, ANSI-capable terminal exists. The only runtime dependency is `unicode-display_width`.
+
+### Colors
+
+Named colors (basic, shades, and `dark_*`), grey shades `grey0`–`grey100`, the terminal's 8-bit palette, and RGB triplets for true-color terminals. Every component takes a per-part `colors:` hash (columns, headers, hints, search matches, …).
+
+### Frontends
+
+- **Terminal** (`require 'typr'`) — the default: raw terminal IO, no ncurses, works over SSH and on Termux
+- **Graphical** (`require 'typr/graphical'`) — experimental: SDL2-based windows
+
+All components work identically across frontends.
 
 ## Installation
 
@@ -34,7 +49,7 @@ gem install typr
 Or in your Gemfile:
 
 ```ruby
-gem 'typr', '~> 1.0'
+gem 'typr', '~> 1.2'
 ```
 
 ## Usage
@@ -59,8 +74,8 @@ Typr.init
 
 Typr.clear
 @grid.show
-key = Typr.read(:key)   # reads a single keypress
-@grid.reset               # reset grid to default view
+key = Typr.read_key   # reads a single keypress
+@grid.reset            # reset grid to default view
 Typr.exit
 ```
 
@@ -82,7 +97,7 @@ Typr.init
 Typr.clear
 loop do
   @text.show
-  key = Typr.read(:key)
+  key = Typr.read_key
   case key
   when ?q then break
   else     @text.send(key)  # spacebar scrolls, j/k move up/down, etc.
@@ -104,7 +119,7 @@ Typr.init
   colors: { hints: [:white, :black] }
 )
 
-selected = @browser.pick("/home")   # interactive file picker, returns path
+selected = @browser.pick   # interactive file picker, returns the absolute path
 puts "You selected: #{selected}"
 Typr.exit
 ```
@@ -140,7 +155,7 @@ class MyApp
     loop do
       @grid.show
       @prompt.show
-      key = Typr.read(:key)
+      key = Typr.read_key
       case key
       when ?s then @grid.sort_by(@prompt.ask("sort column": [@grid, :column]))
       when ?f then @grid.add_filter(*@prompt.ask("filter column": [@grid, :column], with: :line))
@@ -163,31 +178,46 @@ end
 ## API Reference
 
 ### `Typr.init` / `Typr.exit`
-Initialize and tear down the terminal UI. Always call these at the start and end of your program.
+Initialize and tear down the terminal UI (hides the cursor, enables key-mode and mouse reporting; restores them on exit). Always call these at the start and end of your program.
 
 ### `Typr.clear([scope])`
 Clears the full screen or a single line (`:line`).
 
-### `Typr.read(type)`
-Reads input from the terminal. Types:
-- `:key` — a single keypress (returns `KEY_ESCAPE`, `?q`, etc.)
-- `:line` — a full line of text input
+### `Typr.read_key`
+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:
+
+```ruby
+Typr.read_line "/" do |key, query, cursor|
+  filter query
+  nil
+end
+```
+
+### `Line#ask`
+Strict question types:
+- `Array` — pick a row from an object/column (hint-driven)
+- `:key` — read a single key
+- `:line` — read a line of text
+
+The question and answer are rendered in `@colors[:question]`/`@colors[:answer]`.
 
-### Layout properties (all spaces)
+### Layout properties (all components)
 - `top`, `bottom`, `left`, `right` — placement. Integers for absolute offsets, floats (0-1) for relative sizing. Negative values position from the opposite edge. (`bottom: -1` = last row)
 
 ### Grid options
 | Option | Description |
 |---|---|
 | `input` | Array of arrays (data rows) |
-| `header` | Column titles array |
+| `header` | Column titles array (symbols define `Typr::NAME`-style constants) |
 | `format` | Per-column format: `:min`, `:max`, or a number for fixed width |
+| `procs` | Per-column processors (built-ins: `:datetime`, `:magnitudes`, `:filetree`, `:convert`) |
 | `colors` | `{ columns: [:yellow, :cyan], header: [:white, :black] }` etc. |
-| `sorted_by` | Column index the grid is sorted by (setter) |
-| `filters` | Active filters array (getter) |
-| `selected` | Selected row indices (getter/setter) |
-| `.sort_by` | Sort the grid on a given column |
-| `.select_rows / select_columns` | Multi-select via index picker |
+| `.sort_by` | Sort the grid on a given column (toggles direction) |
+| `.add_filter` | Add a substring/regex filter on a column (or `:all`) |
+| `.pick :row, column:` | Interactive row picker with live `/` search and number hints |
 
 ### Text options
 | Option | Description |
@@ -195,12 +225,13 @@ Reads input from the terminal. Types:
 | `input` | String or IO-like stream to display |
 | `header` | Header bar text |
 | `border` | Border style: `:round`, `" "`, etc. |
+| `.search` | Search the text (`/`); `.search_next`/`.search_prev` (`n`/`p`) |
 
 ### Browser options
 | Option | Description |
 |---|---|
 | `directory` | Root directory to start browsing |
-| `.pick(start_dir)` | Interactive file picker, returns the selected path |
+| `.pick([type])` | Interactive file picker, returns the absolute path; `type` filters by MIME family (`"image"`, `"audio"`, `"video"`, `"text"`, `"application"`, `"inode"`) |
 
 ## License
 

data/lib/browser.rb

@@ -216,12 +216,7 @@ module Typr
     def help; @user.help end
 
     ##
-    # Recurse through the directory tree, adding subdirectory entries inline
-    # via +cd(path, true)+. Sorts by name with the filetree processor.
-    #
-    #   browser.recurse   # flattens tree into leaf names
-
-    ## Reset display, selection, and position state then re-sort.
+    # Reset display, selection, and position state then re-sort.
     #
     #   browser.reset_view
 
@@ -231,11 +226,13 @@ module Typr
     #
     #   browser.filter_view   # prompts for filter text
 
-    def search; pick :none, 0, column: NAME end
-
     def filter_view; add_filter *@user.ask(
       filter: [ popup( type: :"[f]ilter" ), :row, NAME], with: :line ) end
 
+    ## Open live `/` search filtered on the name column.
+    #
+    #   browser.search   # type to narrow, Escape restores, Enter commits
+
     def search
       @suppress_user = true
       pick :none, column: NAME
@@ -262,12 +259,14 @@ module Typr
 
     ##
     # Interactive file/directory picker. Blocks until a selection or Escape.
-    # Return on a file wraps the path in single quotes. Enter on a directory
-    # triggers cd. +type+ optionally filters by MIME family (audio, video,
-    # image, text, application, inode).
+    # Return on a file yields its raw absolute path; multi-select joins the
+    # chosen paths double-quoted with spaces. Enter on a directory triggers
+    # cd. +type+ optionally filters by MIME family (audio, video, image,
+    # text, application, inode). Mouse: left-click a row to pick it; wheel
+    # up/down scrolls the listing.
     #
-    #   browser.pick              # => '/home/user/file.txt'
-    #   browser.pick 'image'      # => '/path/to/photo.png' (images only)
+    #   browser.pick              # => /home/user/file.txt
+    #   browser.pick 'image'      # => /path/to/photo.png (images only)
     #   browser.pick nil          # => anything, same as 'file'
 
     def pick type='file', **kw
@@ -284,7 +283,15 @@ module Typr
           reset :display
           return
         end
-        next unless choice = send( key )
+        if key.is_a?(Typr::Mouse)
+          if key.wheel? and key.press?
+            send( key.wheel_up? ? @keymap[:up] : @keymap[:down] )
+            next
+          elsif key.press? and key.left? and choice = hit( key.y, key.x )
+          else next end
+        else
+          next unless choice = send( key )
+        end
         case choice
           when Array; choice = choice.map{ |id| @data[id][NAME] }.join('" "')
           when Integer; file = @data[ choice ]
@@ -303,7 +310,7 @@ module Typr
     #   browser.show   # shows browser with info bar
 
     def show; super
-      user = ENV["USER"] || Etc.getlogin
+      user = Etc.getpwuid(Process.euid).name rescue ENV["USER"] || Etc.getlogin
       @head.colors[:columns][0] = user == "root" ? [:red, :black] : [:green, :black]
       @head.reset :format
       @head.show
@@ -440,7 +447,7 @@ module Typr
       @parent = self
       @head ||= Grid.new( parent:self, left: ->{@parent.left}, margin: '',
         right: ->{@parent.width + @parent.left - 1}, top: ->{@parent.top-1},
-        input: [ [->{ENV["USER"] || Etc.getlogin}, ->{@parent.directory},
+        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"}"},

data/lib/space.rb

@@ -29,6 +29,7 @@ include Typr
 STR
 eval( method % ([name]*11) ) }
 
+  # Deep-convert String keys to Symbols so string-keyed config (e.g. YAML) is honored.
   def symbolize obj
     case obj
     when Hash
@@ -40,17 +41,23 @@ eval( method % ([name]*11) ) }
   attr_writer :left, :top, :right, :bottom
   attr_accessor :margin, :colors, :interval, :borders
 
+  # Viewport width in cells (right - left + 1).
   def width; right - left + 1 end
+  # Viewport height in cells (bottom - top + 1).
   def height; bottom - top + 1 end
 
+  # Redraw every +interval+ seconds from a background thread.
   def start; @updater = Thread.new{ loop{show; sleep @interval }} end
+  # Stop the background refresh thread.
   def stop; @updater.terminate end
 
+  # Draw a border char at screen (x, y); skips nil and off-screen positions.
   def draw_border x,y,char
     draw move_code(x, y) + char unless not char or
       x < 0 or x > Typr.width or y < 0 or y > Typr.height
   end
 
+  # Draw the widget's border box (no-op when no borders are set).
   def show
     return if @borders.empty?
     color @colors[:border]
@@ -66,6 +73,8 @@ eval( method % ([name]*11) ) }
     draw_border(right + 1, bottom + 1, @borders[:bottom_right])
   end
 
+  # Set border style: :light/:heavy/:double/:round, a char repeated across
+  # the box, or nil for none.
   def border=(border)
     chars = case border
       when Symbol
@@ -78,6 +87,8 @@ eval( method % ([name]*11) ) }
       bottom_right ].map.with_index{ |part,id| [part.to_sym, chars[id]] }.to_h if chars
   end
 
+  # Build a widget from boundary (left/top/right/bottom), border, margin,
+  # colors, interval, and keymap.
   def initialize args={}
     @max, @keymap, @colors, @margin = 0, {}, {}, '  '
     @left, @top, @interval, @borders = 0, 0, 1, {}

data/lib/stack.rb

@@ -38,6 +38,20 @@ module Typr
 
     def headspace; @header ? 1 : 0 end
 
+    ##
+    # Map a mouse click at 1-based terminal (row, col) to a data row id on
+    # the current page, or nil when the click lands outside the widget (border,
+    # header, margins). Row ids match what hint presses return from `pick`.
+    #
+    #   stack.hit 3, 5   # => 0  (row 3, col 5 hits data row 0)
+
+    def hit row, col
+      return unless row and col
+      rel = row - 1 - top - headspace
+      return unless rel.between?(0, height - 1) and col.between?(left, right)
+      page.to_a[rel]
+    end
+
     ##
     # The usable height after subtracting any header space.
     #
@@ -193,6 +207,8 @@ module Typr
     #   stack.pick                # single row picker
     #   stack.pick :column, 3     # pick a column in row 3
     #   stack.pick "rows"         # multi-select rows
+    #
+    # Mouse: left-click a row to pick it; wheel up/down scrolls the page.
 
     def pick type = :row, row=0 #, key=nil
       type = type.to_s
@@ -207,7 +223,15 @@ module Typr
           draw_hints type, row unless type['none']
           limit = type['row'] ? height : positions(row).count
           key = Typr.read_key
-          if key.is_a?(String) and value =
+          if key.is_a?(Typr::Mouse)
+            if key.wheel? and key.press?
+              send( key.wheel_up? ? @keymap[:up] : @keymap[:down] )
+              next
+            elsif key.press? and key.left? and type['row'] and
+              value = hit( key.y, key.x )
+              relative = value if type['relative_']
+            end
+          elsif key.is_a?(String) and value =
             @hints[0..limit-@hints_start-1].index(key)
             value += @hints_start
             relative = value + @start if type['relative_']

data/lib/terminal.rb

@@ -10,22 +10,70 @@ module Typr
   # Raw /dev/tty used for key input; falls back to $stdin when unavailable.
   INPUT = (IO.new IO.sysopen("/dev/tty", "r")) rescue $stdin
 
-  # KEY_* escape sequences come from the terminfo database (infocmp -L1).
-  `infocmp -L1`.split.each{ |info| key,value = info[0..-2].split("=")
-    if value
-      value.gsub! '\E', '\e'
-      value += "\\" if value[-1] == "\\"
-      eval "%s=\"%s\"" % [key.upcase,value] if key
-    end }
+  # KEY_* escapes and keypad sequences are precompiled into share/terminfo by
+  # bin/build_terminfo, so the runtime needs no ncurses/infocmp (e.g. Termux).
+  TERMINFO = begin
+    eval File.read(File.expand_path("../share/terminfo", __dir__))
+  rescue StandardError
+    {}
+  end
+  # Known-good fallback so KEY_* are always defined, even for TERM=dumb.
+  DEFAULT_KEYS = { "key_up" => "\eOA", "key_down" => "\eOB", "key_left" => "\eOD",
+    "key_right" => "\eOC", "key_home" => "\eOH", "key_end" => "\eOF",
+    "key_backspace" => "\x7f", "key_dc" => "\e[3~", "key_npage" => "\e[6~",
+    "key_ppage" => "\e[5~", "carriage_return" => "\r",
+    "keypad_xmit" => "\e[?1h\e=", "keypad_local" => "\e[?1l\e>",
+    "cursor_invisible" => "\e[?25l", "cursor_normal" => "\e[?25h",
+    "clear_screen" => "\e[H\e[2J", "user7" => "\e[6n" }
+  term = ENV["TERM"].to_s
+  entry = nil
+  [ term, term.sub(/-.*/, ""), "xterm" ].each do |name|
+    found = TERMINFO[name]
+    if found && found.any? { |cap, _| cap.start_with?("key_") }
+      entry = found
+      break
+    end
+  end
+  entry ||= {}
+  # Fill gaps with safe ANSI defaults, but never fabricate keypad modes:
+  # those must match the terminal exactly or arrows get misread.
+  DEFAULT_KEYS.each do |cap, seq|
+    next if cap.start_with?("keypad_") && !entry[cap]
+    const_set cap.upcase, entry[cap] || seq
+  end
 
   # Common key aliases and the line-erase escape sequence.
   ERASE_LINE = "\e[K"
+  # Reset foreground/background to the terminal defaults.
+  ORIG_COLORS = "\e[39;49m"
   KEY_ESCAPE = "\e"
   KEY_RETURN = CARRIAGE_RETURN
   KEY_TAB = "\t"
   KEY_PAGEDOWN = KEY_NPAGE
   KEY_PAGEUP = KEY_PPAGE
 
+  # Enable/disable mouse reporting. Universal private modes, independent of
+  # terminfo: 1000 = button press/release/wheel, 1006 = SGR coordinates.
+  MOUSE_ON = "\e[?1000h\e[?1006h"
+  MOUSE_OFF = "\e[?1000l\e[?1006l"
+
+  # A mouse event decoded from the input stream. +x+ / +y+ are 1-based
+  # terminal coordinates; +button+ is 0=left, 1=middle, 2=right, or 4-7 for
+  # the wheel (up/down/left/right); +modifiers+ holds the SGR shift/alt/ctrl
+  # bits. Non-widget code can test `key.is_a?(Typr::Mouse)`.
+  Mouse = Struct.new(:button, :x, :y, :action, :modifiers) do
+    def press?;   action == :press end
+    def release?; action == :release end
+    def wheel?;   button.between?(4, 7) end
+    def wheel_up?;   button == 4 end
+    def wheel_down?; button == 5 end
+    def left?;   button == 0 end
+    def middle?; button == 1 end
+    def right?;  button == 2 end
+    def to_s; "%s button=%i x=%i y=%i%s" % [ action, button, x, y,
+      ( modifiers > 0 ? " modifiers=#{modifiers}" : "" ) ] end
+  end
+
   # Text attributes (reset, bold, italic, ...) and named 8/256-color tables.
   MODES =  %i[ reset bold italic underline slow fast invert ]
   COLORS = %i[ black red green yellow blue magenta cyan white ]
@@ -196,11 +244,47 @@ module Typr
   ## Reads a single keypress in raw mode.
   #
   # Returns the key sequence as a String (e.g. "a" or "\e[A" for up-arrow),
-  # or nil when stdin is not a tty or input is unavailable.
+  # or a Typr::Mouse for a mouse report, or nil when stdin is not a tty or
+  # input is unavailable.
 
   def self.read_key
-    return INPUT.raw{ |tty| tty.sysread 6 } rescue nil unless INPUT.tty?
-    INPUT.raw{ |tty| tty.sysread 6 } rescue return
+    read = ->(tty) do
+      str = tty.sysread 6
+      if str.start_with?("\e[<")
+        # SGR mouse reports (CSI < b ; x ; y M/m) can exceed six bytes.
+        str << tty.sysread(1) until str[-1].ord >= 0x40
+      elsif str.start_with?("\e[M") and str.size < 6
+        str << tty.sysread(6 - str.size)
+      end
+      str
+    end
+    raw = (INPUT.raw{ |tty| read.call tty } rescue nil)
+    return unless raw
+    decode_mouse(raw) || raw
+  end
+
+  ## Decode a raw input string into a {Typr::Mouse} event, or nil when +raw+
+  # is not a mouse report. Handles both SGR (CSI < b ; x ; y M/m) and the
+  # legacy X10 (CSI M + three bytes) encodings.
+
+  def self.decode_mouse raw
+    if (m = raw.match(/\A\e\[<(\d+);(\d+);(\d+)([Mm])\z/))
+      code, x, y, final = m[1].to_i, m[2].to_i, m[3].to_i, m[4]
+    elsif raw.start_with?("\e[M")
+      code, x, y = raw.getbyte(3) - 32, raw.getbyte(4) - 32, raw.getbyte(5) - 32
+      final = code == 3 ? ?m : ?M
+    else
+      return nil
+    end
+    modifiers = code & 28
+    base = code & ~28
+    motion = (base & 32) != 0
+    wheel = base >= 64
+    button = wheel ? base - 64 + 4 : base & 3
+    action = if motion then :motion
+      elsif wheel then final == ?m ? :release : :press
+      else ( final == ?m or code == 3 ) ? :release : :press end
+    Mouse.new button, x, y, action, modifiers
   end
 
   ## Interactive line editor used for string prompts (search, %str, ...).
@@ -303,21 +387,25 @@ module Typr
   def self.on_resize &block
     trap(:WINCH, &block)
   end
-  # Enter interactive mode: seed the default colors, hide the cursor and
-  # enable key-mode (application) escapes when stdin is a tty.
+  # Enter interactive mode: seed the default colors, hide the cursor, enable
+  # key-mode (application) escapes and mouse reporting when stdin is a tty.
   def self.init default=[ :white, :black  ]
     $default = default.dup
     $color = $default.dup
     if $stdin.tty?
       print CURSOR_INVISIBLE
-      system "tput smkx"
+      print KEYPAD_XMIT if defined?(KEYPAD_XMIT)
+      print MOUSE_ON
     end
   end
-  # Restore the terminal: show the cursor, reset colors and clear the screen.
+  # Restore the terminal: show the cursor, reset keypad/colors, disable mouse
+  # reporting and clear.
   def self.exit;
   extend self
     if $stdin.tty?
       $>.print CURSOR_NORMAL;
+      $>.print KEYPAD_LOCAL if defined?(KEYPAD_LOCAL)
+      $>.print MOUSE_OFF
       $>.print ORIG_COLORS; color; clear
     end
   end

data/lib/text.rb

@@ -191,6 +191,8 @@ module Typr
       self << @input
     end
 
+    # Reset state: +:search+ clears the pattern and highlights; +:all+ resets
+    # position, selection, and search; else falls through to {Stack#reset}.
     def reset type=:all
       case type
         when :search; highlight_clear
@@ -201,10 +203,13 @@ module Typr
 
     private
 
+    # Re-apply search for a live query (empty clears the highlights).
     def live_search query
       query.empty? ? highlight_clear : search(query)
     end
 
+    # Move to the next/previous match from the current position; returns the
+    # matched line id or nil when there are none.
     def step
       matches = @search[:matches]
       return nil if matches.empty?
@@ -221,6 +226,8 @@ module Typr
       return id
     end
 
+    # Interactive `/` prompt via Typr.read_line; Escape restores the previous
+    # search state, Enter searches (empty restores the last pattern).
     def search_prompt
       query = @search[:pattern].is_a?(String) ? @search[:pattern].dup : ''
       saved = { re: @re, pattern: @search[:pattern],

data/lib/typr.rb

@@ -1,7 +1,7 @@
 # typr is a Ruby library for building interactive terminal-based user interfaces.
 # It provides layout primitives, widgets, and event-driven interaction.
 #
-# == Widgets
+# == Classes
 #
 # * Typr::Grid   - Sortable, filterable table with formatted columns and row selection
 # * Typr::Text   - Scrollable text viewer with word/line picking and search
@@ -12,7 +12,7 @@
 #
 # == Terminal Control
 #
-#   Typr.init               # Initialize terminal (hide cursor, enable key mode)
+#   Typr.init               # Initialize terminal (hide cursor, enable key mode and mouse reporting)
 #   Typr.clear              # Clear entire screen
 #   Typr.clear :line        # Clear current line only
 #   key = Typr.read_key      # Read a single keypress
@@ -21,7 +21,7 @@
 #
 # == Layout Properties
 #
-# All widgets accept +left+, +top+, +right+, +bottom+ as:
+# All classes accept +left+, +top+, +right+, +bottom+ as:
 #   Integer  - absolute position
 #   Float    - fraction of terminal (0.0..1.0)
 #   Proc     - evaluated each layout pass