tuile 0.3.0 → 0.5.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.
@@ -151,6 +188,70 @@ module Tuile
     attr_reader height: Integer
   end
 
+  # An immutable terminal color. Accepts the three forms ANSI/SGR understands:
+  # 
+  # - a Symbol from {COLOR_SYMBOLS} — 8 standard + 8 bright named colors
+  #   (SGR 30..37 / 90..97 for fg, 40..47 / 100..107 for bg)
+  # - an Integer 0..255 — the 256-color palette (SGR 38;5;N / 48;5;N)
+  # - an Array of three Integers 0..255 — 24-bit RGB (SGR 38;2;R;G;B / 48;2;R;G;B)
+  # 
+  # A constant per named color is pre-defined (`Color::RED`, `Color::BRIGHT_BLUE`,
+  # …) so callers can reach for `Color::RED` instead of building one each time.
+  # {.coerce} accepts anything {.new} accepts plus `nil` (terminal default) and
+  # an existing {Color} (returned as-is), so APIs that accept colors typically
+  # take `[Color, nil]` and pass through {.coerce}.
+  # 
+  # ```ruby
+  # Color.new(:red)              # named
+  # Color.new(42)                # 256-color palette
+  # Color.new([255, 100, 0])     # RGB
+  # Color::RED                   # constant
+  # Color.coerce(:red)           # accepts raw forms, returns Color
+  # Color.coerce(nil)            # nil → nil
+  # ```
+  # 
+  # {#to_ansi} renders a full SGR escape (`"\e[31m"`); {#sgr_codes} returns the
+  # raw numeric codes so callers (notably {StyledString}) can combine them with
+  # other SGR attributes in a single sequence.
+  class Color
+    COLOR_SYMBOLS: ::Array[Symbol]
+
+    # Coerces the input to a {Color}. `nil` passes through unchanged (callers
+    # use `nil` for the terminal default); an existing {Color} is returned
+    # as-is; otherwise the value is fed to {.new}.
+    # 
+    # _@param_ `value`
+    def self.coerce: ((Color | Symbol | Integer | ::Array[Integer])? value) -> Color?
+
+    # _@param_ `value` — see class-level docs for the three accepted forms.
+    def initialize: ((Symbol | Integer | ::Array[Integer]) value) -> void
+
+    # SGR parameter codes for emitting this color as either a foreground
+    # (`target: :fg`) or background (`target: :bg`). Returned as an array so
+    # callers can splice them into a multi-attribute SGR (e.g. bold + color).
+    # 
+    # _@param_ `target` — `:fg` or `:bg`.
+    def sgr_codes: (?Symbol target) -> ::Array[Integer]
+
+    # Full SGR escape sequence for this color (e.g. `"\e[31m"`). Useful for
+    # `print`-style direct emission; for composing with other attributes use
+    # {#sgr_codes} instead.
+    # 
+    # _@param_ `target` — `:fg` or `:bg`.
+    def to_ansi: (?Symbol target) -> String
+
+    # _@param_ `other`
+    def ==: (Object other) -> bool
+
+    def hash: () -> Integer
+
+    def inspect: () -> String
+
+    # The underlying raw representation — a Symbol, Integer, or frozen
+    # Array<Integer>.
+    attr_reader value: (Symbol | Integer | ::Array[Integer])
+  end
+
   # A point with `x` and `y` integer coordinates, both 0-based.
   # 
   # @!attribute [r] x
@@ -216,6 +317,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 +341,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 +358,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 +494,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 +550,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 +604,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 +726,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 +860,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 +943,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 +1059,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 +1078,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 +1101,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 +1130,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 +1142,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
@@ -951,9 +1173,13 @@ module Tuile
       # Each line is ellipsized to fit, padded with trailing spaces out to
       # the full width, and pre-rendered to ANSI so {#repaint} is just a
       # lookup + screen.print per row. {@blank_line} covers rows past the
-      # last text line.
+      # last text line. When {#bg} is set, every produced line (and the
+      # blank row) has the bg applied uniformly.
       def update_clipped_lines: () -> void
 
+      # _@param_ `line`
+      def apply_bg: (StyledString line) -> StyledString
+
       # _@param_ `line`
       # 
       # _@param_ `width`
@@ -962,6 +1188,11 @@ module Tuile
       # _@return_ — the current text. Defaults to an empty
       # {StyledString}.
       attr_accessor text: (StyledString | String)?
+
+      # _@return_ — background color applied uniformly across every
+      # painted row (including padding past the text). `nil` (default)
+      # leaves whatever bg the text's own styling carries.
+      attr_accessor bg: (Color | Symbol | Integer | ::Array[Integer])?
     end
 
     # A modal overlay that wraps any {Component} as its content. Popup itself
@@ -992,7 +1223,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 +1383,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 +1414,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 +1474,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 +1536,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 +1553,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.
@@ -1373,22 +1586,129 @@ module Tuile
       # honored); a `StyledString` is used as-is; `nil` is coerced to an
       # empty {StyledString}.
       # 
+      # Detaches every existing {Region} (including the original default)
+      # and installs a fresh internal default region that owns all the new
+      # hard lines. Any handle the caller was holding becomes detached and
+      # raises on use — see {Region#attached?}. The no-op short-circuit
+      # (matching value, same {StyledString}) preserves existing regions.
+      # 
       # _@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=}.
+      # Creates a new empty {Region} at the spatial tail of the document
+      # and returns its handle. Subsequent {#append} / {#<<} / {#add_line}
+      # calls route through this new region (since it is now the spatial
+      # tail). Earlier regions keep their content and their handles stay
+      # valid; their {Region#range} shifts as later regions grow.
+      # 
+      # Apps streaming logically-distinct sections (e.g. an LLM's "thinking"
+      # vs. "assistant" output) create one region per section, hold the
+      # handles, and call `region.append` / `region.text=` directly when
+      # they need to grow or rewrite an earlier section.
+      def create_region: () -> Region
+
+      # _@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.
+      # 
+      # For the "add an entry on a new line" pattern use {#add_line}.
       # 
-      # 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.
+      # 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
+
+      # Replaces a contiguous range of hard lines with the parsed content
+      # of `str`. The replacement is parsed exactly like {#text=} and
+      # {#append}: a {String} is run through {StyledString.parse} (so
+      # embedded ANSI is honored), a {StyledString} is used as-is, `nil`
+      # behaves like an empty replacement (the range is deleted). Embedded
+      # `"\n"` in the replacement produces multiple hard lines, so a single
+      # `replace` can grow or shrink the buffer.
+      # 
+      # `range` selects which hard lines to swap out:
+      # 
+      # - an `Integer` `n` is shorthand for `n..n` (replace one existing
+      #   line — `n` must be in `[0, hard-line count)`);
+      # - a non-empty `Range` of hard-line indices replaces those lines;
+      # - an empty `Range` (e.g. `2...2`, or the canonical end-insertion
+      #   `hard_lines.size...hard_lines.size`) is *insertion* at that
+      #   position — no lines are removed. {#insert} is a thin alias for
+      #   this case.
+      # 
+      # Endpoints must be non-negative integers; `begin` may equal
+      # `hard-line count` (insertion at the end), `end` may not exceed
+      # `hard-line count - 1`. `nil` endpoints (beginless / endless ranges)
+      # are not accepted.
+      # 
+      # Cost is roughly `O(from + length + new content)`: the splice
+      # updates only the affected slice of the physical-row buffer, using
+      # the per-hard-line wrap-count cache to locate the starting offset
+      # without re-wrapping preceding lines. Lines outside the splice are
+      # never re-wrapped. {#top_line} is clamped if the new line count
+      # puts it past the end; {#auto_scroll} pins it to the bottom as
+      # usual. The call is a no-op (no invalidation) when the parsed
+      # replacement equals the covered range (vacuously true for an empty
+      # range plus empty replacement, so `replace(n...n, "")` is a cheap
+      # no-op).
+      # 
+      # _@param_ `range` — hard-line indices to replace.
+      # 
+      # _@param_ `str` — replacement content.
+      def replace: ((::Range[untyped] | Integer) range, (String | StyledString)? str) -> void
+
+      # Inserts `str` at hard-line index `at`. Equivalent to
+      # `replace(at...at, str)` — a no-removal splice that grows the buffer
+      # by the parsed line count. `at == hard-line count` is allowed and
+      # appends at the end; for that case {#append} / {#add_line} are
+      # usually more idiomatic.
+      # 
+      # _@param_ `at` — 0-based hard-line index in `[0, hard-line count]`.
+      # 
+      # _@param_ `str` — content to insert.
+      def insert: (Integer at, (String | StyledString)? str) -> void
+
       # Clears the text. Equivalent to `text = ""`.
       def clear: () -> void
 
@@ -1414,30 +1734,164 @@ module Tuile
       # this hook.
       def on_width_changed: () -> void
 
+      # Validates and unpacks a {#replace}-style range argument into
+      # inclusive `[from, to]` line indices. An `Integer` `n` becomes
+      # `[n, n]` (which must point at an existing line — `Integer` is
+      # never insertion sugar). A `Range` is normalized for
+      # `exclude_end?`; `to == from - 1` is a valid empty range
+      # (insertion at `from`), and `from` may equal `size` for
+      # end-insertion. Shared by {#replace} and {Region#replace};
+      # `size` is the buffer or region line count, and `what` is the
+      # entity name woven into error messages.
+      # 
+      # _@param_ `range`
+      # 
+      # _@param_ `size`
+      # 
+      # _@param_ `what`
+      def normalize_replace_range: ((::Range[untyped] | Integer) range, ?Integer size, ?String what) -> [Integer, Integer]
+
+      # Hard-line index where `region` begins in {@hard_lines} — derived
+      # by summing the line counts of all regions that precede it.
+      # 
+      # _@param_ `region`
+      def region_start_index: (Region region) -> Integer
+
+      # Joined {StyledString} of the hard lines that `region` owns. Mirrors
+      # {#text} but scoped to one region.
+      # 
+      # _@param_ `region`
+      def text_for_region: (Region region) -> StyledString
+
+      # Replaces all of `region`'s hard lines with the parsed content of
+      # `value`. Symmetric with {#text=}, scoped to one region. Empty/nil
+      # content empties the region (no visible blank line). Works on
+      # already-empty regions (insertion at the region's position).
+      # 
+      # _@param_ `region`
+      # 
+      # _@param_ `value`
+      def set_region_text: (Region region, (String | StyledString)? value) -> void
+
+      # Region-scoped {#replace}. Validates `range` against
+      # `region.line_count`, translates region-relative indices to
+      # absolute buffer indices, splices, and updates the region's count.
+      # 
+      # _@param_ `region`
+      # 
+      # _@param_ `range`
+      # 
+      # _@param_ `str`
+      def replace_in_region: (Region region, (::Range[untyped] | Integer) range, (String | StyledString)? str) -> void
+
+      # Verbatim append into `region`.
+      # 
+      # _@param_ `region`
+      # 
+      # _@param_ `str`
+      def append_to_region: (Region region, (String | StyledString)? str) -> void
+
+      # Drops the last `n` hard lines from `region`'s tail via
+      # {#splice_hard_lines}. `n` is clamped to the region's current
+      # line count; callers guarantee `n > 0` and the region is
+      # non-empty (the {Region#remove_last_n_lines} guard handles the
+      # no-op cases).
+      # 
+      # _@param_ `region`
+      # 
+      # _@param_ `n`
+      def remove_last_n_from_region: (Region region, Integer n) -> void
+
+      # Drops `region` from {@regions}: its hard lines are removed via
+      # {#splice_hard_lines}, the handle is detached, and the always-one
+      # default is restored if the removal would have left zero regions.
+      # Skips the rewrap / invalidate work when the region was empty
+      # (the buffer didn't change), but always detaches.
+      # 
+      # _@param_ `region`
+      def remove_region: (Region region) -> void
+
+      # Adjusts region line counts after a {@hard_lines} splice that
+      # removed `removed_count` lines at index `from` and inserted
+      # `added_count` in their place. Two passes:
+      # 
+      # 1. Subtract each region's overlap with the removed range (uses
+      #    the original counts to compute positions). Remember the first
+      #    region that lost lines — that's the natural home for the
+      #    replacement content.
+      # 2. Credit `added_count` to that region. For pure insertions (no
+      #    removal), there's no "first overlapping region" to pick from;
+      #    walk regions and credit the latest one starting at `from` (the
+      #    boundary tiebreaker matches the spatial-tail-routing of
+      #    {#append}). Past-the-end inserts fall back to the tail region.
+      # 
+      # _@param_ `from`
+      # 
+      # _@param_ `removed_count`
+      # 
+      # _@param_ `added_count`
+      def update_region_counts: (Integer from, Integer removed_count, Integer added_count) -> void
+
       # _@return_ — number of visible lines.
       def viewport_lines: () -> Integer
 
       # _@return_ — the max value of {#top_line} for scroll-key clamping.
       def top_line_max: () -> Integer
 
-      # Recomputes {@physical_lines} for the current text and wrap width,
-      # pre-padding every line to `wrap_width` so {#paintable_line} is just
-      # a lookup + optional scrollbar-char append at paint time (and the
-      # rendered ANSI is cached on each line via {StyledString#to_ansi}'s
-      # memoization, so re-painting on scroll is near-free). Clamps
-      # {@top_line} if the new line count puts it out of range.
+      # Full rebuild of {@physical_lines} and {@hard_line_wrap_counts}
+      # from {@hard_lines}. Called when wrap width changes (which
+      # invalidates every cached row count) and from {#text=} (which
+      # replaces the whole logical model). Mid-buffer mutators splice
+      # incrementally via {#splice_hard_lines} and do *not* go through
+      # here. Clamps {@top_line} if the new line count puts it out of
+      # range.
       def rewrap: () -> void
 
-      # Wraps `hard_line` at `width` and appends the padded physical lines
-      # to {@physical_lines}. Empty hard lines (e.g. from a `"\n\n"` run)
-      # and degenerate `width <= 0` both emit a single {@blank_line} row,
-      # matching what `@text.wrap(width).map { |l| pad_to(l, width) }`
-      # would have produced for those cases.
+      # Wraps `hard_line` at `width` and returns the padded physical rows
+      # alongside the row count. Empty hard lines (e.g. from a `"\n\n"`
+      # run) and degenerate `width <= 0` both emit a single {@blank_line}
+      # row, matching what `@text.wrap(width).map { |l| pad_to(l, width) }`
+      # would have produced.
       # 
-      # _@param_ `hard_line` — one hard-broken line (no embedded `"\n"`).
+      # _@param_ `hard_line`
       # 
       # _@param_ `width`
-      def append_physical_lines: (StyledString hard_line, Integer width) -> void
+      def wrap_hard_line: (StyledString hard_line, Integer width) -> [::Array[StyledString], Integer]
+
+      # Appends `hard_line` to the tail of {@hard_lines}, updating the
+      # wrap-count cache and {@physical_lines} in lockstep.
+      # 
+      # _@param_ `hard_line`
+      # 
+      # _@param_ `width`
+      def push_hard_line: (StyledString hard_line, Integer width) -> void
+
+      # Pops the last hard line, the corresponding cache entry, and the
+      # physical rows that hard line contributed. Returns the popped
+      # hard line.
+      def pop_hard_line: () -> StyledString
+
+      # Splices `new_hard_lines` into the buffer in place of the `count`
+      # hard lines starting at index `from`. Updates {@hard_lines},
+      # {@hard_line_wrap_counts}, and {@physical_lines} consistently.
+      # The starting physical-row offset is computed in O(`from`) integer
+      # adds via the cache — no wraps of preceding hard lines. Wraps are
+      # done only for the new content, so total cost is
+      # `O(from + count + new_hard_lines.sum(&:display_width))`.
+      # 
+      # _@param_ `from`
+      # 
+      # _@param_ `count` — number of existing hard lines to remove.
+      # 
+      # _@param_ `new_hard_lines`
+      def splice_hard_lines: (Integer from, Integer count, ::Array[StyledString] new_hard_lines) -> void
+
+      # _@param_ `idx`
+      # 
+      # _@return_ — the {@physical_lines} index where the hard line
+      # at {@hard_lines}`[idx]` starts. O(`idx`) integer adds via the
+      # wrap-count cache.
+      def phys_offset_at: (Integer idx) -> Integer
 
       # Rebuilds the joined {StyledString} from {@hard_lines}, inserting a
       # default-styled `"\n"` between hard lines. Called from the {#text}
@@ -1501,6 +1955,136 @@ module Tuile
       # `Size.new(0, 0)`. Maintained incrementally by {#text=} and
       # {#append}, so reads are O(1).
       attr_reader content_size: Size
+
+      # A logical section of a {TextView}'s text — a contiguous run of
+      # hard lines the app wants to address as a unit (e.g. an LLM's
+      # "thinking" output vs. its assistant message). The view always
+      # has at least one region, an internal default that owns whatever
+      # hard lines aren't claimed by an app-created region.
+      # 
+      # Apps don't construct regions directly; call {TextView#create_region}
+      # to get one. The handle stays valid as long as the region is
+      # attached — i.e. until {TextView#text=} (or {TextView#clear}) wipes
+      # the slate and installs a fresh internal default. Detached regions
+      # raise {RuntimeError} on every mutator and reader.
+      # 
+      # A region's position is derived from its sibling order and counts,
+      # so growing or shrinking an earlier region implicitly shifts the
+      # ranges of all later regions. Empty regions occupy zero rows but
+      # still hold a position in the sequence; `region.text = ""` collapses
+      # a region's visible footprint without detaching it. Pre-creating
+      # empty placeholder regions is supported and is the natural pattern
+      # for "I'll fill this in later" layouts.
+      class Region
+        # _@param_ `view` — the owning view (never `nil` at construction).
+        # 
+        # _@param_ `line_count` — number of hard lines this region owns.
+        def initialize: (TextView view, ?Integer line_count) -> void
+
+        # _@return_ — `true` while the region is owned by its
+        # {TextView}. Becomes `false` permanently once detached
+        # (typically by {TextView#text=} / {TextView#clear}).
+        def attached?: () -> bool
+
+        # _@return_ — true iff the region owns zero hard lines.
+        # Empty regions render nothing — they still hold a position in
+        # the sequence, so subsequent mutations route to them as usual.
+        def empty?: () -> bool
+
+        # _@return_ — the joined content of just this region's
+        # hard lines. Empty regions return {StyledString::EMPTY}.
+        def text: () -> StyledString
+
+        # Replaces all of this region's hard lines with the parsed content
+        # of `value`. Accepts the same inputs as {TextView#text=}; empty
+        # or `nil` content collapses the region to zero hard lines.
+        # 
+        # _@param_ `value`
+        def text=: ((String | StyledString)? value) -> void
+
+        # Verbatim append into this region's tail. Same semantics as
+        # {TextView#append} but scoped to the region: embedded `"\n"`
+        # creates new hard lines within the region, no-leading-newline
+        # input extends the region's last hard line. Empty / `nil` input
+        # is a no-op (but still raises when detached). When the region is
+        # the spatial tail of the view, this uses the incremental
+        # {TextView#append} path; mid-document regions splice the affected
+        # slice of the physical-row buffer (lines outside the region are
+        # not re-wrapped).
+        # 
+        # _@param_ `str`
+        def append: ((String | StyledString)? str) -> void
+
+        # _@return_ — the hard-line indices this region currently
+        # occupies — `start...(start + line_count)`. Empty regions
+        # return a degenerate exclusive range at their position (e.g.
+        # `5...5`). The result is computed on each call and so always
+        # reflects sibling mutations.
+        def range: () -> ::Range[untyped]
+
+        # Removes this region from its view. The region's hard lines (if
+        # any) are deleted from the buffer — subsequent regions' ranges
+        # shift up by `line_count` — and the handle detaches permanently.
+        # The view keeps its always-≥1-region invariant: if this was the
+        # only remaining region, a fresh internal default is installed
+        # (the app doesn't get a handle to it; call
+        # {TextView#create_region} again to start tracking).
+        # 
+        # Idempotent: calling `remove` on an already-detached region is a
+        # silent no-op (unlike the other mutators, which raise). This
+        # lets cleanup paths blindly call `remove` without first checking
+        # {#attached?}.
+        def remove: () -> void
+
+        # Appends `str` as a new entry in this region: starts a fresh
+        # hard line first (when the region is non-empty), then appends
+        # `str`. Scoped equivalent of {TextView#add_line}. On an empty
+        # region behaves like {#append}.
+        # 
+        # _@param_ `str`
+        def add_line: ((String | StyledString)? str) -> void
+
+        # Replaces a contiguous range of this region's hard lines with the
+        # parsed content of `str`. Region-scoped counterpart of
+        # {TextView#replace}: indices are 0-based **within the region**
+        # (so `replace(0, "x")` rewrites the region's first line, not
+        # the buffer's). Same range conventions apply — `Integer`,
+        # inclusive/exclusive `Range`, empty range as insertion at
+        # `begin`, and `begin == line_count` for end-insertion.
+        # 
+        # _@param_ `range` — region-relative hard-line indices.
+        # 
+        # _@param_ `str` — replacement content.
+        def replace: ((::Range[untyped] | Integer) range, (String | StyledString)? str) -> void
+
+        # Inserts `str` at region-relative hard-line index `at`.
+        # Equivalent to `replace(at...at, str)`. Region-scoped counterpart
+        # of {TextView#insert}; `at == line_count` is allowed and appends
+        # at the region's tail.
+        # 
+        # _@param_ `at` — region-relative index in `[0, line_count]`.
+        # 
+        # _@param_ `str`
+        def insert: (Integer at, (String | StyledString)? str) -> void
+
+        # Drops the last `n` hard lines from this region's tail.
+        # Subsequent regions' ranges shift up by the number actually
+        # dropped. `n` is clamped to {#line_count}, so passing a large
+        # `n` empties the region — the handle stays attached (use
+        # {#remove} when the goal is to drop the region itself).
+        # `n == 0` and an already-empty region are no-ops.
+        # 
+        # _@param_ `n`
+        def remove_last_n_lines: (Integer n) -> void
+
+        def detach!: () -> void
+
+        def check_attached: () -> void
+
+        # _@return_ — number of hard lines this region owns. Safe to
+        # read on a detached region (no error raised).
+        attr_accessor line_count: (Integer | untyped)
+      end
     end
 
     # Shows a log. Construct your logger pointed at a {LogWindow::IO} to route
@@ -1516,6 +2100,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 +2134,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 +2164,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 +2285,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 +2292,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
@@ -1758,13 +2426,39 @@ module Tuile
     # Awaits until the event queue is empty (all events have been processed).
     def await_empty: () -> void
 
+    # Schedules `block` to fire on the event-loop thread roughly `fps` times
+    # per second, passing a 0-based monotonically increasing tick counter. Use
+    # it for animations (e.g. a `/-\|` spinner in a {Component::Label}) or
+    # periodic UI refresh from a background task.
+    # 
+    # The returned {Ticker} controls the schedule — call {Ticker#cancel} to
+    # stop it.
+    # 
+    # **Errors:** if `block` raises, the {Ticker} cancels itself and the
+    # exception flows through the normal event-loop error path — i.e.
+    # {Screen#on_error} for the default Tuile setup. Auto-cancel prevents a
+    # broken block from spamming `on_error` at the tick rate.
+    # 
+    # Tickers reuse `concurrent-ruby`'s shared timer thread
+    # ({Concurrent}.global_timer_set) — adding more tickers does not add more
+    # threads, just more work on the shared scheduler.
+    # 
+    # _@param_ `fps` — firings per second, must be positive. Fractional values are fine (`fps: 0.5` ⇒ one tick every two seconds).
+    def tick: (Numeric fps) ?{ (Integer tick) -> void } -> Ticker
+
     # Runs the event loop and blocks. Must be run from at most one thread at the
     # same time. Blocks until some thread calls {#stop}. Calls block for all
-    # events submitted via {#post}; the block is always called from the thread
-    # running this function.
+    # events; the block is always called from the thread running this function.
     # 
-    # Any exception raised by block is re-thrown, causing this function to
-    # terminate.
+    # Any exception raised by the block is re-thrown, causing this function to
+    # terminate. Wrap the block body in `rescue` if you want to handle errors
+    # without tearing down the loop — see {Screen#event_loop} for an example.
+    # 
+    # **Procs are yielded too.** A {#submit}ed block arrives as a `Proc` event;
+    # the consumer is responsible for invoking it (typically `event.call`).
+    # Yielding rather than dispatching inline means a raise inside the
+    # submitted block flows through the consumer's `rescue` like any other
+    # event-handler error, instead of bypassing it.
     def run_loop: () ?{ (Object event) -> void } -> void
 
     # _@return_ — true if this thread is running inside an event queue.
@@ -1835,6 +2529,36 @@ module Tuile
     class EmptyQueueEvent
       include Singleton
     end
+
+    # Handle returned by {EventQueue#tick}. Cancel a running ticker via
+    # {#cancel}.
+    # 
+    # Internally wraps a `Concurrent::TimerTask` whose firing posts a single
+    # submit-block to the owning {EventQueue}; the user's block therefore
+    # always runs on the event-loop thread and may freely mutate UI. If the
+    # user block raises, the Ticker auto-cancels and the exception is
+    # re-raised so it flows through the loop's normal error handling
+    # ({Screen#on_error} for the default Tuile setup).
+    class Ticker
+      # _@param_ `event_queue` — queue to dispatch tick calls onto.
+      # 
+      # _@param_ `fps` — firings per second (positive).
+      # 
+      # _@param_ `block` — called as `block.call(tick_count)` on each fire.
+      def initialize: (EventQueue event_queue, Numeric fps, Proc block) -> void
+
+      # _@return_ — true once {#cancel} has been called.
+      def cancelled?: () -> bool
+
+      # Stops the ticker. Idempotent and safe to call from any thread,
+      # including from inside the tick block. Any tick already queued on the
+      # event loop at the moment of cancellation is dropped before the user
+      # block runs.
+      def cancel: () -> void
+
+      # Runs on the event-loop thread.
+      def fire: () -> void
+    end
   end
 
   # Testing only — a screen which doesn't paint anything and pretends that the
@@ -1881,7 +2605,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 +2614,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 +2644,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.
@@ -2167,8 +2906,16 @@ module Tuile
     # `underline`). Useful for row-level highlights — the new bg overlays
     # without dropping foreground colors the original styling carried.
     # 
-    # _@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
+    # _@param_ `bg` — background color, coerced via {Color.coerce}. `nil` clears bg back to the terminal default.
+    def with_bg: ((Color | 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, coerced via {Color.coerce}. `nil` clears fg back to the terminal default.
+    def with_fg: ((Color | Symbol | Integer | ::Array[Integer])? fg) -> StyledString
 
     def inspect: () -> String
 
@@ -2184,10 +2931,11 @@ module Tuile
 
     # _@param_ `color`
     # 
-    # _@param_ `base` — base SGR code — 30 for fg, 40 for bg.
+    # _@param_ `target` — `:fg` or `:bg`.
     # 
-    # _@param_ `ext` — extended-color SGR code — 38 for fg, 48 for bg.
-    def color_codes: ((Symbol | Integer | ::Array[Integer])? color, base: Integer, ext: Integer) -> ::Array[Integer]
+    # _@return_ — SGR codes; `[39]` / `[49]` for the "default" reset
+    # when `color` is `nil`, otherwise delegated to {Color#sgr_codes}.
+    def color_codes: (Color? color, target: Symbol) -> ::Array[Integer]
 
     # _@param_ `start_or_range`
     # 
@@ -2240,18 +2988,16 @@ module Tuile
     class ParseError < Tuile::Error
     end
 
-    # A frozen value type describing the visual style of a {Span}.
-    # 
-    # `fg` and `bg` accept:
-    # - `nil` — the terminal default (SGR 39 / 49)
-    # - a symbol from {COLOR_SYMBOLS} — 8 standard + 8 bright ANSI colors
-    # - an Integer 0..255 — 256-color palette index (SGR 38;5;N / 48;5;N)
-    # - an `[r, g, b]` Array of three 0..255 Integers — 24-bit RGB
+    # A frozen value type describing the visual style of a {Span}. Colors are
+    # stored as {Color} instances (or `nil` for the terminal default); inputs
+    # to {.new} and {#merge} are coerced via {Color.coerce}, so the four
+    # accepted color forms — `nil`, Symbol, Integer 0..255, RGB Array — work
+    # transparently.
     # 
     # @!attribute [r] fg
-    #   @return [Symbol, Integer, Array<Integer>, nil]
+    #   @return [Color, nil]
     # @!attribute [r] bg
-    #   @return [Symbol, Integer, Array<Integer>, nil]
+    #   @return [Color, nil]
     # @!attribute [r] bold
     #   @return [Boolean]
     # @!attribute [r] italic
@@ -2259,12 +3005,11 @@ module Tuile
     # @!attribute [r] underline
     #   @return [Boolean]
     class Style
-      COLOR_SYMBOLS: ::Array[Symbol]
       DEFAULT: Style
 
-      # _@param_ `fg`
+      # _@param_ `fg` — coerced via {Color.coerce}.
       # 
-      # _@param_ `bg`
+      # _@param_ `bg` — coerced via {Color.coerce}.
       # 
       # _@param_ `bold`
       # 
@@ -2272,18 +3017,13 @@ module Tuile
       # 
       # _@param_ `underline`
       def self.new: (
-                      ?fg: (Symbol | Integer | ::Array[Integer])?,
-                      ?bg: (Symbol | Integer | ::Array[Integer])?,
+                      ?fg: (Color | Symbol | Integer | ::Array[Integer])?,
+                      ?bg: (Color | Symbol | Integer | ::Array[Integer])?,
                       ?bold: bool,
                       ?italic: bool,
                       ?underline: bool
                     ) -> Style
 
-      # _@param_ `color`
-      # 
-      # _@param_ `which`
-      def self.validate_color!: (Object color, Symbol which) -> void
-
       def default?: () -> bool
 
       # Returns a new {Style} with the given attributes overridden.
@@ -2291,9 +3031,9 @@ module Tuile
       # _@param_ `overrides`
       def merge: (**::Hash[Symbol, Object] overrides) -> Style
 
-      attr_reader fg: (Symbol | Integer | ::Array[Integer])?
+      attr_reader fg: Color?
 
-      attr_reader bg: (Symbol | Integer | ::Array[Integer])?
+      attr_reader bg: Color?
 
       attr_reader bold: bool
 
@@ -2359,6 +3099,8 @@ module Tuile
   # A "synchronous" event queue – no loop is run, submitted blocks are run right
   # away and submitted events are thrown away. Intended for testing only.
   class FakeEventQueue
+    def initialize: () -> void
+
     def locked?: () -> bool
 
     def stop: () -> void
@@ -2371,6 +3113,42 @@ module Tuile
 
     # _@param_ `event`
     def post: (Object event) -> void
+
+    # Mirrors {EventQueue#tick} but timeless: returns a {FakeTicker} that
+    # only fires when a test calls {#tick_once}. The `fps` argument is
+    # validated the same way the real queue validates it, then discarded —
+    # the fake has no clock, so frame cadence is up to the test.
+    # 
+    # _@param_ `fps` — firings per second, must be positive. Validated for parity with {EventQueue#tick}; otherwise unused.
+    def tick: (Numeric fps) ?{ (Integer tick) -> void } -> FakeTicker
+
+    # Test helper: fires every live ticker's user block once and prunes
+    # cancelled tickers. No-op when no tickers are registered. Pumps once
+    # per call regardless of any ticker's fps — the fake has no clock, so
+    # tests pump N frames by calling this N times.
+    def tick_once: () -> void
+
+    # Handle returned by {FakeEventQueue#tick}. Mirrors the public surface of
+    # {EventQueue::Ticker} (`cancel`, `cancelled?`) but does not auto-fire —
+    # the host {FakeEventQueue} drives firing via {FakeEventQueue#tick_once}.
+    class FakeTicker
+      # _@param_ `block` — called as `block.call(tick_count)` on each {#fire}.
+      def initialize: (Proc block) -> void
+
+      # _@return_ — true once {#cancel} has been called.
+      def cancelled?: () -> bool
+
+      # Marks the ticker cancelled. Idempotent. Subsequent {#fire} calls are
+      # no-ops; {FakeEventQueue#tick_once} also prunes the ticker on its next
+      # pass.
+      def cancel: () -> void
+
+      # Invokes the user block with the current tick counter, then advances.
+      # No-op when {#cancelled?}. Typically driven by
+      # {FakeEventQueue#tick_once}; safe to call directly from a test that
+      # wants to drive a single ticker.
+      def fire: () -> void
+    end
   end
 
   # A vertical scrollbar that computes which character to draw at each row.