tuile 0.3.0 → 0.4.0

data/sig/tuile.rbs

@@ -45,14 +45,51 @@ module Tuile
     PAGE_DOWN: String
     BACKSPACE: String
     DELETE: String
+    CTRL_A: String
+    CTRL_B: String
+    CTRL_C: String
+    CTRL_D: String
+    CTRL_E: String
+    CTRL_F: String
+    CTRL_G: String
     CTRL_H: String
-    BACKSPACES: ::Array[String]
+    CTRL_I: String
+    CTRL_J: String
+    CTRL_K: String
+    CTRL_L: String
+    CTRL_M: String
+    CTRL_N: String
+    CTRL_O: String
+    CTRL_P: String
+    CTRL_Q: String
+    CTRL_R: String
+    CTRL_S: String
+    CTRL_T: String
     CTRL_U: String
-    CTRL_D: String
+    CTRL_V: String
+    CTRL_W: String
+    CTRL_X: String
+    CTRL_Y: String
+    CTRL_Z: String
+    BACKSPACES: ::Array[String]
     ENTER: String
     TAB: String
     SHIFT_TAB: String
 
+    # True iff `key` is a single printable character — a one-character string
+    # whose codepoint is not in Unicode's C (Other) category. Rejects multi-
+    # character escape sequences ({UP_ARROW}, mouse events, …), control bytes
+    # ({TAB}, {ENTER}, {ESC}, {CTRL_A}..{CTRL_Z}, {BACKSPACE}), and the empty
+    # string; accepts ASCII letters/digits/punctuation/space *and* non-ASCII
+    # printables like "é".
+    # 
+    # Used by {Screen#register_global_shortcut} to reject keys that would
+    # collide with typing, and by {Tuile::Component::TextField} to decide
+    # whether to insert a key at the caret.
+    # 
+    # _@param_ `key`
+    def self.printable?: (String key) -> bool
+
     # Grabs a key from stdin and returns it. Blocks until the key is obtained.
     # Reads a full ESC key sequence; see constants above for some values returned
     # by this function.
@@ -216,6 +253,22 @@ module Tuile
     # _@param_ `component`
     def invalidate: (Component component) -> void
 
+    # Rebuild the status-bar text from the current focus and global-shortcut
+    # registry. Called from {#focused=} and whenever the global registry
+    # changes. Popups own their own "q Close" prefix in `#keyboard_hint`;
+    # for the tiled case Screen tacks on the global "q quit" instead.
+    # Global-shortcut hints get spliced in too — see {#global_shortcut_hints}
+    # for the over_popups filter rule.
+    def refresh_status_bar: () -> void
+
+    # Status-bar hints from currently-registered global shortcuts.
+    # When a popup is open, only `over_popups: true` shortcuts contribute —
+    # the rest don't fire in that context, so showing them would be a lie.
+    # Insertion order is preserved (Hash iteration order).
+    # 
+    # _@param_ `popup_open`
+    def global_shortcut_hints: (popup_open: bool) -> ::Array[String]
+
     # Internal — use {Component::Popup#open} instead. Adds the popup to
     # {#pane}, centers and focuses it.
     # 
@@ -224,7 +277,9 @@ module Tuile
 
     # Runs event loop – waits for keys and sends them to active window. The
     # function exits when the 'ESC' or 'q' key is pressed.
-    def run_event_loop: () -> void
+    # 
+    # _@param_ `capture_mouse` — when true (default), enables xterm mouse tracking so clicks and scroll wheel arrive as {MouseEvent}s and feed {Component#handle_mouse}. When false, no tracking escape sequence is written: the terminal keeps its native click handling, which is what you want if the app benefits more from select-to-copy than from click-to-focus. Components' `handle_mouse` is simply never invoked from the loop in that mode (the terminal stops sending the bytes).
+    def run_event_loop: (?capture_mouse: bool) -> void
 
     # Advances focus to the next {Component#tab_stop?} in tree order, wrapping
     # around. Scope is the topmost popup if one is open, otherwise {#content}
@@ -239,6 +294,51 @@ module Tuile
     # _@return_ — true if focus moved.
     def focus_previous: () -> bool
 
+    # Registers an app-level keyboard shortcut. When `key` arrives, the block
+    # is invoked on the event-loop thread (so it may freely mutate UI) before
+    # the key reaches any component. Re-registering the same key replaces the
+    # previous binding; use {#unregister_global_shortcut} to remove one.
+    # 
+    # Only unprintable keys are accepted — control characters (Ctrl+letter,
+    # ESC, BACKSPACE, ENTER, …) and multi-character escape sequences (arrows,
+    # F-keys, …). Printable keys raise {ArgumentError}: they'd hijack typing
+    # into a {Component::TextField} and should be expressed as
+    # {Component#key_shortcut} instead, which the dispatcher suppresses while
+    # a text widget owns the hardware cursor. TAB and SHIFT_TAB are also
+    # rejected because {#handle_key} intercepts them for focus navigation
+    # before the global registry is consulted, so a binding on them would
+    # silently never fire.
+    # 
+    # Pass `hint:` to surface the shortcut in the status bar. It's a
+    # preformatted string the caller fully owns (so colors and the key label
+    # style stay consistent with whatever the host app uses elsewhere). The
+    # framework splices it in like any other status hint: in the tiled case,
+    # right after `q quit` and before the active window's own hint; while a
+    # popup is open, only hints from `over_popups: true` shortcuts are
+    # shown, and they're prepended before the popup's `q Close`.
+    # 
+    # Example — open a log popup with Ctrl+L from anywhere, even while a
+    # popup is already on screen:
+    # 
+    #   screen.register_global_shortcut(Keys::CTRL_L,
+    #                                   over_popups: true,
+    #                                   hint: "^L #{Rainbow("log").cadetblue}") do
+    #     log_popup.open
+    #   end
+    # 
+    # _@param_ `key` — unprintable key (e.g. {Keys::CTRL_L}, {Keys::ESC}, {Keys::PAGE_UP}).
+    # 
+    # _@param_ `over_popups` — when true, fires even while a modal popup is open (pre-empting the popup's own key handling). When false (default), the shortcut is suppressed while any popup is open and the popup gets the key instead.
+    # 
+    # _@param_ `hint` — preformatted status-bar hint (e.g. `"^L #{Rainbow("log").cadetblue}"`). When nil (default) the shortcut is silent in the status bar.
+    def register_global_shortcut: (String key, ?over_popups: bool, ?hint: String?) -> void
+
+    # Removes a shortcut previously installed by {#register_global_shortcut}.
+    # No-op if `key` was not registered.
+    # 
+    # _@param_ `key`
+    def unregister_global_shortcut: (String key) -> void
+
     # _@return_ — current active tiled component.
     def active_window: () -> Component?
 
@@ -330,10 +430,17 @@ module Tuile
     # A key has been pressed on the keyboard. Handle it, or forward to active
     # window.
     # 
-    # Tab / Shift+Tab are reserved navigation keys: intercepted here before
-    # the pane sees them, so a focused {Component::TextField} (which would
-    # otherwise swallow printable keys via the standard cursor-owner
-    # suppression) doesn't trap them.
+    # Dispatch order:
+    #   1. Tab / Shift+Tab — reserved focus navigation, intercepted before
+    #      anything else so a focused {Component::TextField} (which would
+    #      otherwise swallow printable keys via cursor-owner suppression)
+    #      doesn't trap them.
+    #   2. App-level shortcuts from {#register_global_shortcut}. An entry
+    #      registered with `over_popups: true` always fires; one with the
+    #      default `over_popups: false` fires only when no popup is open
+    #      (otherwise the popup receives the key normally).
+    #   3. {ScreenPane#handle_key}, which routes to the topmost popup or
+    #      tiled content.
     # 
     # _@param_ `key`
     # 
@@ -379,13 +486,29 @@ module Tuile
 
     # _@return_ — currently focused component.
     attr_accessor focused: Component?
+
+    # Entry in the global shortcut registry: the block to run, whether it
+    # pre-empts open popups, and an optional preformatted status-bar hint.
+    # @api private
+    class Shortcut < Data
+      # Returns the value of attribute block
+      attr_reader block: Object
+
+      # Returns the value of attribute over_popups
+      attr_reader over_popups: Object
+
+      # Returns the value of attribute hint
+      attr_reader hint: Object
+    end
   end
 
   # A UI component which is positioned on the screen and draws characters into
   # its bounding rectangle (in {#repaint}).
   # 
-  # Component is considered invisible if {#rect} is empty or one of left/top is
-  # negative. The component won't draw when invisible.
+  # Painting is gated by attachment: a detached component (one whose {#root}
+  # isn't {Screen#pane}) is never enqueued for repaint via {#invalidate}, and
+  # any stale invalidation entries are filtered out at drain time. Subclasses
+  # can paint freely in {#repaint} without re-asserting attachment.
   class Component
     def initialize: () -> void
 
@@ -417,6 +540,8 @@ module Tuile
     # responsibility for {#rect}. Everything else should call super.
     # 
     # A component must not draw outside of {#rect}.
+    # 
+    # Only called when the component is attached.
     def repaint: () -> void
 
     # Called when a character is pressed on the keyboard.
@@ -537,6 +662,12 @@ module Tuile
 
     # Invalidates the component: {Screen} records this component as
     # needs-repaint and once all events are processed, will call {#repaint}.
+    # 
+    # No-op when the component is not {#attached?} — a detached component has
+    # no place on the screen to paint to, so {Screen} must never end up
+    # repainting it. Callers don't need to guard their own `invalidate` calls;
+    # mutating a detached component (e.g. setting `lines=` on a {List} sitting
+    # inside a closed {Component::Popup}) is silent.
     def invalidate: () -> void
 
     # Whether direct children fully tile {#rect}. Used by the default
@@ -665,7 +796,11 @@ module Tuile
 
       # Rebuilds pre-padded lines when the wrap width changes. The wrap width
       # depends on {#rect}`.width` and the scrollbar gutter, both of which
-      # trigger this hook.
+      # trigger this hook. Also re-evaluates {#auto_scroll}: if items were
+      # appended while the rect was empty (e.g. a {Popup}-wrapped list got
+      # `add_line` calls before the popup was opened), the auto-scroll update
+      # was skipped because there was no viewport — re-run it now that there
+      # is one, so the list snaps to the bottom on first paint.
       def on_width_changed: () -> void
 
       # Coerces and flattens a list of input entries into trimmed
@@ -744,7 +879,14 @@ module Tuile
       # _@param_ `delta` — negative scrolls up, positive scrolls down.
       def move_top_line_by: (Integer delta) -> void
 
-      # If auto-scrolling, recalculate the top line.
+      # If auto-scrolling, recalculate the top line and snap the cursor to the
+      # last reachable position. Without the cursor snap the viewport gets
+      # yanked back to wherever the cursor sat on the next arrow press,
+      # negating the auto-scroll. Skipped when {#rect} is empty: without a
+      # viewport the "lines minus viewport" formula yields `@lines.size`,
+      # which would leave `top_line` past the last item once a real rect
+      # arrives. {#on_width_changed} re-runs this hook when the rect grows so
+      # the snap-to-bottom intent is preserved.
       def update_top_line_if_auto_scroll: () -> void
 
       # _@return_ — whether the scrollbar should be drawn right now.
@@ -853,6 +995,15 @@ module Tuile
         # _@return_ — true if the position changed.
         def go: (Integer new_position) -> bool
 
+        # Moves the cursor to the last reachable position. For base {Cursor},
+        # the last line; {Limited} clamps to the last allowed position; {None}
+        # is a no-op.
+        # 
+        # _@param_ `line_count` — number of lines in the list.
+        # 
+        # _@return_ — true if the position changed.
+        def go_to_last: (Integer line_count) -> bool
+
         # _@param_ `lines`
         # 
         # _@param_ `line_count`
@@ -863,9 +1014,6 @@ module Tuile
 
         def go_to_first: () -> bool
 
-        # _@param_ `line_count`
-        def go_to_last: (Integer line_count) -> bool
-
         # _@return_ — 0-based line index of the current cursor position.
         attr_reader position: Integer
 
@@ -889,6 +1037,16 @@ module Tuile
 
           # _@param_ `_line_count`
           def candidate_positions: (Integer _line_count) -> ::Array[Integer]
+
+          # Overridden so all movement funnels — base {Cursor#go_to_last},
+          # {Cursor#go_to_first}, etc., which all call {#go} — become safe
+          # no-ops on a disabled cursor. The instance is frozen, so a default
+          # mutating {#go} would raise.
+          # 
+          # _@param_ `_new_position`
+          # 
+          # _@return_ — always false.
+          def go: (Integer _new_position) -> bool
         end
 
         # Cursor which can only land on specific allowed lines.
@@ -908,6 +1066,9 @@ module Tuile
           # _@param_ `line_count`
           def candidate_positions: (Integer line_count) -> ::Array[Integer]
 
+          # _@param_ `_line_count`
+          def go_to_last: (Integer _line_count) -> bool
+
           # _@param_ `lines`
           # 
           # _@param_ `line_count`
@@ -917,9 +1078,6 @@ module Tuile
           def go_up_by: (Integer lines) -> bool
 
           def go_to_first: () -> bool
-
-          # _@param_ `_line_count`
-          def go_to_last: (Integer _line_count) -> bool
         end
       end
     end
@@ -992,7 +1150,9 @@ module Tuile
 
       def focusable?: () -> bool
 
-      # Mounts this popup on the {Screen}.
+      # Mounts this popup on the {Screen}. Recomputes the popup's size from
+      # the current content first, so reopening a popup whose content has
+      # grown or shrunk while closed picks up the new size.
       def open: () -> void
 
       # Constructs and opens a popup in one call.
@@ -1150,8 +1310,9 @@ module Tuile
     # 
     # The window's `content` is unset by default; assign one via {#content=}.
     # 
-    # Window is considered invisible if {#rect} is empty or one of left/top is
-    # negative. The window won't draw when invisible.
+    # Window is considered invisible if {#rect} is empty. The window won't
+    # draw when invisible. (Repaint of detached windows is short-circuited
+    # by {Component#invalidate}; subclasses don't need to re-check.)
     class Window < Component
       include Tuile::Component::HasContent
 
@@ -1180,10 +1341,6 @@ module Tuile
       # window has no content, footer, or caption.
       def content_size: () -> Size
 
-      # _@return_ — true if {#rect} is off screen and the window won't
-      # paint.
-      def visible?: () -> bool
-
       # Fully repaints the window: both frame and contents.
       # 
       # Window deliberately paints over its entire rect (border around the
@@ -1244,26 +1401,26 @@ module Tuile
     # Currently only {#on_change} is wired; Enter inserts a newline as in any
     # plain `<textarea>` or text editor. A future `on_enter`/`on_submit`
     # callback may opt out of that by consuming Enter instead.
-    class TextArea < Component
+    class TextArea < Tuile::Component::TextInput
       ACTIVE_BG_SGR: String
       INACTIVE_BG_SGR: String
 
       def initialize: () -> void
 
-      def focusable?: () -> bool
-
-      def tab_stop?: () -> bool
-
       def cursor_position: () -> Point?
 
-      # _@param_ `key`
-      def handle_key: (String key) -> bool
-
       # _@param_ `event`
       def handle_mouse: (MouseEvent event) -> void
 
       def repaint: () -> void
 
+      def on_text_mutated: () -> void
+
+      def on_caret_mutated: () -> void
+
+      # _@param_ `key`
+      def handle_text_input_key: (String key) -> bool
+
       def on_width_changed: () -> void
 
       # _@return_ — cached wrap of {#text} for the
@@ -1306,38 +1463,11 @@ module Tuile
       # _@return_ — always true.
       def insert_char: (String char) -> bool
 
-      def delete_before_caret: () -> void
-
-      def delete_at_caret: () -> void
-
       # Keeps the caret visible by scrolling vertically.
       def adjust_top_display_row: () -> void
 
-      # _@param_ `key`
-      def printable?: (String key) -> bool
-
-      # Same semantics as {TextField}'s ctrl+left.
-      def word_left: () -> Integer
-
-      # Same semantics as {TextField}'s ctrl+right.
-      def word_right: () -> Integer
-
-      # _@return_ — current text contents (may contain embedded `\n`).
-      attr_accessor text: String
-
-      # _@return_ — caret index in `0..text.length`.
-      attr_accessor caret: Integer
-
       # _@return_ — index of the topmost display row currently visible.
       attr_reader top_display_row: Integer
-
-      # Optional callback fired whenever {#text} changes. Receives the new text
-      # as a single argument. Not fired by {#caret=} (text unchanged), not
-      # fired by a no-op setter, and not fired by a re-wrap caused by a width
-      # change ({#text} itself is unchanged).
-      # 
-      # _@return_ — one-arg callable, or nil.
-      attr_accessor on_change: (Proc | Method)?
     end
 
     # A read-only viewer for prose: chunks of formatted text that scroll
@@ -1350,9 +1480,19 @@ module Tuile
     # ANSI-as-bytes wrapping, color does *not* get dropped on continuation
     # rows). {#text=} accepts a {String} (parsed via {StyledString.parse},
     # so embedded ANSI is honored) or a {StyledString} directly; {#text}
-    # always returns the {StyledString}. Use {#append} for incremental "log
-    # line" style updates; turn on {#auto_scroll} to keep the latest content
-    # in view.
+    # always returns the {StyledString}.
+    # 
+    # For incremental updates pick the right primitive: {#append} (aliased
+    # as `<<`) is verbatim and stream-friendly — chunks are concatenated
+    # straight onto the buffer, with embedded `\n` becoming hard breaks.
+    # {#add_line} is the "log entry" convenience — it starts the content on
+    # a fresh line by inserting a leading `\n` when the buffer is non-empty.
+    # {#remove_last_n_lines} pops hard lines back off the tail — the
+    # inverse of building up a region with {#append} / {#add_line}, so a
+    # caller streaming reformattable content (e.g. partially-rendered
+    # Markdown that may need to retract its last paragraph) can replace
+    # the tail without rewriting the whole text. Turn on {#auto_scroll}
+    # to keep the latest content in view.
     # 
     # TextView is meant to be the content of a {Window} — focus indication and
     # keyboard-hint surfacing rely on the surrounding window chrome.
@@ -1376,19 +1516,58 @@ module Tuile
       # _@param_ `value`
       def text=: ((String | StyledString)? value) -> void
 
-      # Appends `str` as a new physical line. If the current text is empty,
-      # behaves like `text = str`; otherwise prepends a newline so the new
-      # content lands on a fresh line. Accepts the same input forms as
-      # {#text=}.
+      # _@return_ — true iff {#text} is empty (no hard lines).
+      def empty?: () -> bool
+
+      # Appends `str` verbatim. Embedded `\n` characters become hard line
+      # breaks; otherwise the text is concatenated onto the current last
+      # hard line. Designed for streaming use (e.g. an LLM chat window
+      # receiving partial messages — feed each chunk straight in). Accepts
+      # the same input forms as {#text=}; empty/`nil` input is a no-op.
       # 
-      # Cost is O(appended) rather than O(total) — the existing wrapped
-      # buffer is reused, only the new hard line(s) are wrapped and padded,
-      # and `@content_size` is updated incrementally. The cached
-      # {#text} is invalidated and rebuilt on demand.
+      # For the "add an entry on a new line" pattern use {#add_line}.
+      # 
+      # Cost is O(appended + width-of-current-last-hard-line) — the
+      # previously last hard line is re-wrapped (because the extension may
+      # cause it to wrap differently), any additional hard lines created by
+      # embedded `\n` are wrapped fresh. The cached {#text} is invalidated
+      # and rebuilt on demand.
       # 
       # _@param_ `str`
       def append: ((String | StyledString)? str) -> void
 
+      # Verbatim append, returning `self` for chainability (`view << a << b`).
+      # 
+      # _@param_ `str`
+      def <<: ((String | StyledString)? str) -> self
+
+      # Appends `str` as a new entry: starts a fresh hard line first (when
+      # the buffer is non-empty) and then appends `str`. Equivalent to
+      # `append("\n" + str)` on a non-empty buffer, or `append(str)` on an
+      # empty one. `nil` and `""` produce a blank entry on a non-empty
+      # buffer and a no-op on an empty buffer (matches the old `append`
+      # semantics for "log line" callers).
+      # 
+      # _@param_ `str`
+      def add_line: ((String | StyledString)? str) -> void
+
+      # Drops the last `n` hard lines from the buffer. The inverse of
+      # building up a tail region with {#append} / {#add_line}: a caller
+      # streaming partially-rendered content whose tail must occasionally
+      # be retracted (e.g. Markdown-to-ANSI where a new token reformats
+      # the table being built) can call `remove_last_n_lines(k)` followed
+      # by `append(new_tail)` to replace the damaged region in place.
+      # 
+      # `n == 0` and the empty-buffer case are no-ops (no invalidation).
+      # `n >= hard-line count` empties the buffer.
+      # 
+      # Operates on **hard lines** (the `\n`-delimited entries the
+      # buffer stores), not on wrapped physical rows — same granularity
+      # as {#add_line}. Cost is O(rendered-rows of the popped lines).
+      # 
+      # _@param_ `n` — number of hard lines to drop; must be >= 0.
+      def remove_last_n_lines: (Integer n) -> void
+
       # Clears the text. Equivalent to `text = ""`.
       def clear: () -> void
 
@@ -1439,6 +1618,17 @@ module Tuile
       # _@param_ `width`
       def append_physical_lines: (StyledString hard_line, Integer width) -> void
 
+      # Pops from {@physical_lines} the rows that `hard_line` previously
+      # contributed (the inverse of {#append_physical_lines} for the same
+      # input). Used by {#append} when extending the last hard line: its
+      # old wrapped rows are dropped, then the extended hard line is
+      # re-wrapped and appended.
+      # 
+      # _@param_ `hard_line`
+      # 
+      # _@param_ `width`
+      def drop_physical_rows_for: (StyledString hard_line, Integer width) -> void
+
       # Rebuilds the joined {StyledString} from {@hard_lines}, inserting a
       # default-styled `"\n"` between hard lines. Called from the {#text}
       # reader when the cache is cold. Cost is O(total spans).
@@ -1516,6 +1706,11 @@ module Tuile
       # _@param_ `caption`
       def initialize: (?String caption) -> void
 
+      # Appends given line to the log. Can be called from any thread. Does nothing if nil is passed in.
+      # 
+      # _@param_ `string` — the line (or multiple lines) to log.
+      def log: (String? string) -> void
+
       # IO-shaped adapter that forwards each log line to the owning {LogWindow}.
       # Implements both {#write} (stdlib `Logger`) and {#puts} (loggers that
       # call `output.puts`, e.g. `TTY::Logger`).
@@ -1545,26 +1740,28 @@ module Tuile
     # The caret is a logical index in `0..text.length`. The hardware cursor is
     # positioned by {Screen} after each repaint cycle when this component is
     # focused; see {Component#cursor_position}.
-    class TextField < Component
+    class TextField < Tuile::Component::TextInput
       ACTIVE_BG_SGR: String
       INACTIVE_BG_SGR: String
 
       def initialize: () -> void
 
-      def focusable?: () -> bool
-
-      def tab_stop?: () -> bool
-
       def cursor_position: () -> Point?
 
-      # _@param_ `key`
-      def handle_key: (String key) -> bool
-
       # _@param_ `event`
       def handle_mouse: (MouseEvent event) -> void
 
       def repaint: () -> void
 
+      # Truncate to fit `rect.width - 1` — single-line fields can't grow past
+      # their width.
+      # 
+      # _@param_ `new_text`
+      def preprocess_text: (String new_text) -> String
+
+      # _@param_ `key`
+      def handle_text_input_key: (String key) -> bool
+
       def on_width_changed: () -> void
 
       # Maximum number of characters {#text} can hold given current width.
@@ -1573,12 +1770,110 @@ module Tuile
       # _@param_ `char`
       def insert: (String char) -> bool
 
+      # Optional callback fired when the UP arrow key is pressed. When set, UP
+      # is consumed by the field; when nil, UP falls through to the parent
+      # (default behavior). Only triggered by {Keys::UP_ARROW}, not by `k`,
+      # since `k` is a printable character inserted into {#text}.
+      # 
+      # _@return_ — no-arg callable, or nil.
+      attr_accessor on_key_up: (Proc | Method)?
+
+      # Optional callback fired when the DOWN arrow key is pressed. When set,
+      # DOWN is consumed by the field; when nil, DOWN falls through to the
+      # parent (default behavior). Only triggered by {Keys::DOWN_ARROW}, not by
+      # `j`, since `j` is a printable character inserted into {#text}.
+      # 
+      # _@return_ — no-arg callable, or nil.
+      attr_accessor on_key_down: (Proc | Method)?
+
+      # Optional callback fired when ENTER is pressed. When set, ENTER is
+      # consumed by the field; when nil, ENTER falls through to the parent
+      # (default behavior).
+      # 
+      # _@return_ — no-arg callable, or nil.
+      attr_accessor on_enter: (Proc | Method)?
+    end
+
+    # Abstract base for editable text components ({TextField}, {TextArea}).
+    # 
+    # Holds the shared state — a mutable {#text} buffer, a {#caret} index,
+    # {#on_change} and {#on_escape} callbacks — and the keyboard machinery
+    # that single-line and multi-line inputs both need: ESC handling,
+    # LEFT/RIGHT caret movement, CTRL+LEFT/CTRL+RIGHT word jumps, and the
+    # `focusable?`/`tab_stop?` flags.
+    # 
+    # Subclasses implement the layout-specific pieces ({#cursor_position},
+    # {#repaint}) and add their own keys (HOME/END, ENTER, UP/DOWN,
+    # printable insertion) by overriding the protected
+    # {#handle_text_input_key} hook — `super` falls through to the common
+    # navigation handling.
+    # 
+    # The mutation pipeline is a template method: {#text=} and {#caret=}
+    # detect no-ops, mutate state, fire {#on_change}, and invalidate.
+    # Subclasses inject their own behavior via two protected hooks:
+    # 
+    # - {#preprocess_text} — input filter (e.g. {TextField} truncates to
+    #   fit `rect.width - 1`).
+    # - {#on_text_mutated} / {#on_caret_mutated} — post-mutation side
+    #   effects (e.g. {TextArea} invalidates its wrap cache and scrolls to
+    #   keep the caret visible).
+    class TextInput < Component
+      ACTIVE_BG_SGR: String
+      INACTIVE_BG_SGR: String
+
+      def initialize: () -> void
+
+      # _@return_ — true iff {#text} is the empty string.
+      def empty?: () -> bool
+
+      def focusable?: () -> bool
+
+      def tab_stop?: () -> bool
+
+      # Handles a key. Returns false when the component is inactive. Otherwise
+      # first runs the {Component#handle_key} shortcut search via `super`, then
+      # delegates to {#handle_text_input_key}.
+      # 
+      # _@param_ `key`
+      def handle_key: (String key) -> bool
+
+      # Input filter for {#text=}. Subclasses override to truncate or reject
+      # invalid input. Default coerces to String.
+      # 
+      # _@param_ `new_text`
+      # 
+      # _@return_ — possibly transformed text.
+      def preprocess_text: (String new_text) -> String
+
+      # Hook called after {#text} has been mutated, before invalidation /
+      # {#on_change}. Default no-op. Subclasses use this to invalidate caches
+      # ({TextArea}'s wrap cache) and update derived state.
+      def on_text_mutated: () -> void
+
+      # Hook called after {#caret} has been mutated, before invalidation.
+      # Default no-op. Subclasses use this to keep the caret visible
+      # ({TextArea}'s vertical scroll).
+      def on_caret_mutated: () -> void
+
+      # Dispatch hook for {#handle_key}. Handles ESC and the navigation keys
+      # that have identical semantics in single-line and multi-line inputs:
+      # LEFT/RIGHT arrows, CTRL+LEFT/CTRL+RIGHT for word jumps. Subclasses
+      # override to add their own keys (HOME/END, UP/DOWN, ENTER, BACKSPACE/
+      # DELETE, printable insertion) and call `super` to fall back to the
+      # common navigation handling.
+      # 
+      # _@param_ `key`
+      # 
+      # _@return_ — true if the key was handled.
+      def handle_text_input_key: (String key) -> bool
+
       def delete_before_caret: () -> void
 
       def delete_at_caret: () -> void
 
-      # _@param_ `key`
-      def printable?: (String key) -> bool
+      # Default {#on_escape} action: clear focus. Component deactivates; user
+      # can re-focus by clicking or tabbing back in.
+      def default_on_escape: () -> void
 
       # Caret target for ctrl+left: skip whitespace going left, then a run of
       # non-whitespace. Lands at the beginning of the current word, or the
@@ -1596,13 +1891,6 @@ module Tuile
       # _@return_ — caret index in `0..text.length`.
       attr_accessor caret: Integer
 
-      # Optional callback fired when ESC is pressed. When set, ESC is consumed
-      # by the field; when nil, ESC falls through to the parent (default
-      # behavior).
-      # 
-      # _@return_ — no-arg callable, or nil.
-      attr_accessor on_escape: (Proc | Method)?
-
       # Optional callback fired whenever {#text} changes. Receives the new text
       # as a single argument. Not fired by {#caret=} (text unchanged) and not
       # fired when a setter is a no-op.
@@ -1610,28 +1898,14 @@ module Tuile
       # _@return_ — one-arg callable, or nil.
       attr_accessor on_change: (Proc | Method)?
 
-      # Optional callback fired when the UP arrow key is pressed. When set, UP
-      # is consumed by the field; when nil, UP falls through to the parent
-      # (default behavior). Only triggered by {Keys::UP_ARROW}, not by `k`,
-      # since `k` is a printable character inserted into {#text}.
-      # 
-      # _@return_ — no-arg callable, or nil.
-      attr_accessor on_key_up: (Proc | Method)?
-
-      # Optional callback fired when the DOWN arrow key is pressed. When set,
-      # DOWN is consumed by the field; when nil, DOWN falls through to the
-      # parent (default behavior). Only triggered by {Keys::DOWN_ARROW}, not by
-      # `j`, since `j` is a printable character inserted into {#text}.
+      # Callback fired when ESC is pressed. Defaults to a closure that clears
+      # focus (`screen.focused = nil`) so ESC visibly cancels text entry instead
+      # of bubbling to the parent — and, in particular, instead of reaching the
+      # screen's default ESC-to-quit handler. Set to nil to let ESC fall through
+      # to the parent again; set to any other callable to replace the default.
       # 
       # _@return_ — no-arg callable, or nil.
-      attr_accessor on_key_down: (Proc | Method)?
-
-      # Optional callback fired when ENTER is pressed. When set, ENTER is
-      # consumed by the field; when nil, ENTER falls through to the parent
-      # (default behavior).
-      # 
-      # _@return_ — no-arg callable, or nil.
-      attr_accessor on_enter: (Proc | Method)?
+      attr_accessor on_escape: (Proc | Method)?
     end
 
     # A mixin interface for a component with one child tops. The host must
@@ -1881,7 +2155,7 @@ module Tuile
   # 
   # @!attribute [r] button
   #   @return [Symbol, nil] one of `:left`, `:middle`, `:right`, `:scroll_up`,
-  #     `:scroll_down`; `nil` if not known.
+  #     `:scroll_down`, `:scroll_left`, `:scroll_right`; `nil` if not known.
   # @!attribute [r] x
   #   @return [Integer] x coordinate, 0-based.
   # @!attribute [r] y
@@ -1890,14 +2164,29 @@ module Tuile
     # _@return_ — the event's position.
     def point: () -> Point
 
-    # Checks whether given key is a mouse event key
+    # Checks whether given key is a mouse event key. Returns true on the X10
+    # `\e[M` prefix regardless of length — {.parse} is the place that
+    # validates the full 6-byte shape and raises on malformed input.
     # 
     # _@param_ `key` — key read via {Keys.getkey}
     # 
     # _@return_ — true if it is a mouse event
     def self.mouse_event?: (String key) -> bool
 
+    # Parses an X10 mouse report (`\e[M` + 3 bytes: button, x, y).
+    # 
+    # Raises {Tuile::Error} when `key` starts with the mouse prefix but is
+    # not exactly 6 bytes long. Both shorter and longer inputs are bugs in
+    # the upstream key-reader: a shorter prefix means the tail was lost on
+    # the way in, and a longer one means we over-consumed into the next
+    # escape sequence. We refuse to silently truncate either case because
+    # the trailing `\e` of an over-read corrupts the *next* getkey, and the
+    # corruption then surfaces as garbled keystrokes in focused inputs
+    # rather than as a parser failure pointing at the actual cause.
+    # 
     # _@param_ `key` — key read via {Keys.getkey}
+    # 
+    # _@return_ — `nil` if `key` is not a mouse event
     def self.parse: (String key) -> MouseEvent?
 
     def self.start_tracking: () -> String
@@ -1905,7 +2194,7 @@ module Tuile
     def self.stop_tracking: () -> String
 
     # _@return_ — one of `:left`, `:middle`, `:right`, `:scroll_up`,
-    # `:scroll_down`; `nil` if not known.
+    # `:scroll_down`, `:scroll_left`, `:scroll_right`; `nil` if not known.
     attr_reader button: Symbol?
 
     # _@return_ — x coordinate, 0-based.
@@ -2170,6 +2459,14 @@ module Tuile
     # _@param_ `bg` — background color, in any of the forms accepted by {Style.new}. `nil` clears bg back to the terminal default.
     def with_bg: ((Symbol | Integer | ::Array[Integer])? bg) -> StyledString
 
+    # Returns a new {StyledString} with `fg` applied to every span, preserving
+    # each span's text and other style attributes (`bg`, `bold`, `italic`,
+    # `underline`). The new fg overlays without dropping background colors or
+    # text attributes the original styling carried.
+    # 
+    # _@param_ `fg` — foreground color, in any of the forms accepted by {Style.new}. `nil` clears fg back to the terminal default.
+    def with_fg: ((Symbol | Integer | ::Array[Integer])? fg) -> StyledString
+
     def inspect: () -> String
 
     def build_ansi: () -> String