tuile 0.2.0 → 0.4.0

data/sig/tuile.rbs

@@ -16,6 +16,14 @@ module Tuile
   class Error < StandardError
   end
 
+  # ANSI escape sequence constants. Tuile emits colors and text attributes
+  # via Rainbow, which produces **SGR** sequences ("Select Graphic
+  # Rendition", `ESC [ <params> m` — e.g. `\e[31m` red, `\e[1m` bold,
+  # `\e[0m` reset).
+  module Ansi
+    RESET: String
+  end
+
   # Constants for keys returned by {.getkey} and helpers for reading them from
   # stdin. The constants are the raw escape sequences emitted by the terminal;
   # see https://en.wikipedia.org/wiki/ANSI_escape_code for the encoding.
@@ -37,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.
@@ -208,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.
     # 
@@ -216,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}
@@ -231,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?
 
@@ -322,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`
     # 
@@ -371,46 +486,29 @@ module Tuile
 
     # _@return_ — currently focused component.
     attr_accessor focused: Component?
-  end
 
-  # Truncates a string to a given column width, preserving ANSI escape
-  # sequences and accounting for Unicode display width. Truncated output is
-  # suffixed with an ellipsis (`…`).
-  # 
-  # Extracted from `strings-truncation` 0.1.0 (MIT, Piotr Murach) — only the
-  # default end-position, default-omission, no-separator path Tuile uses.
-  module Truncate
-    ANSI_REGEXP: Regexp
-    RESET: String
-    RESET_REGEXP: Regexp
-    END_REGEXP: Regexp
-    OMISSION: String
-    OMISSION_WIDTH: Integer
+    # 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
 
-    # Truncate `text` to at most `length` display columns. ANSI escape
-    # sequences pass through without consuming budget; when characters are
-    # dropped, an ellipsis (`…`) is appended (and counts toward `length`).
-    # 
-    # _@param_ `text`
-    # 
-    # _@param_ `length` — target column width. A `nil` returns `text` unchanged.
-    def truncate: (String text, length: Integer?) -> String
+      # Returns the value of attribute over_popups
+      attr_reader over_popups: Object
 
-    # Truncate `text` to at most `length` display columns. ANSI escape
-    # sequences pass through without consuming budget; when characters are
-    # dropped, an ellipsis (`…`) is appended (and counts toward `length`).
-    # 
-    # _@param_ `text`
-    # 
-    # _@param_ `length` — target column width. A `nil` returns `text` unchanged.
-    def self.truncate: (String text, length: Integer?) -> String
+      # 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
 
@@ -442,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.
@@ -562,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
@@ -589,24 +695,34 @@ module Tuile
     # no parent.
     attr_accessor parent: Component?
 
-    # A scrollable list of String items with cursor support.
+    # A scrollable list of items with cursor support.
     # 
-    # Items are lines painted directly into the component's {#rect}. Lines are
-    # automatically clipped horizontally. Vertical scrolling is supported via
-    # {#top_line}; the list can also automatically scroll to the bottom if
-    # {#auto_scroll} is enabled.
+    # Items are modeled as {StyledString}s and painted directly into the
+    # component's {#rect}. Lines wider than the viewport are ellipsized via
+    # {StyledString#ellipsize} (span styles are preserved across the cut —
+    # unlike the older ANSI-as-bytes truncation, color does *not* get
+    # dropped on the surviving characters). Vertical scrolling is supported
+    # via {#top_line}; the list can also automatically scroll to the bottom
+    # if {#auto_scroll} is enabled.
     # 
     # Cursor is supported; call {#cursor=} to change cursor behavior. The
-    # cursor responds to arrows, `jk`, Home/End, Ctrl+U/D and scrolls the list
-    # automatically.
+    # cursor responds to arrows, `jk`, Home/End, Ctrl+U/D and scrolls the
+    # list automatically. The cursor highlight overlays a dark background
+    # while preserving each span's foreground color.
     class List < Component
+      CURSOR_BG: Integer
+
       def initialize: () -> void
 
-      # Sets new lines. Each entry is coerced via `#to_s`, split on `\n` into
-      # separate lines, and trailing whitespace stripped — symmetric with
-      # {#add_lines}, so the stored `@lines` is always `Array<String>`.
+      # Sets new lines. Each entry is coerced into a {StyledString} (a
+      # `String` is parsed via {StyledString.parse}, so embedded ANSI is
+      # honored; a {StyledString} is used as-is; anything else is stringified
+      # via `#to_s` first), then split on `\n` into separate lines via
+      # {StyledString#lines}, with trailing empty pieces dropped and trailing
+      # ASCII whitespace stripped — symmetric with {#add_lines}, so the
+      # stored `@lines` is always `Array<StyledString>`.
       # 
-      # _@param_ `lines` — new lines. Entries need only respond to `#to_s`.
+      # _@param_ `lines` — entries are `String`, `StyledString`, or anything that responds to `#to_s`.
       def lines=: (::Array[untyped] lines) -> void
 
       # Without a block, returns the current lines. With a block, fully
@@ -617,19 +733,21 @@ module Tuile
       # end
       # ```
       # 
-      # _@return_ — current lines (when called without a block).
-      def lines: () ?{ (::Array[String] buffer) -> void } -> ::Array[String]
+      # _@return_ — current lines (when called without a
+      # block).
+      def lines: () ?{ (::Array[untyped] buffer) -> void } -> ::Array[StyledString]
 
+      # sord duck - #to_s looks like a duck type with an equivalent RBS interface, replacing with _ToS
       # Adds a line.
       # 
       # _@param_ `line`
-      def add_line: (String line) -> void
+      def add_line: ((String | StyledString | _ToS) line) -> void
 
-      # Appends given lines. Each entry is coerced via `#to_s`, split on `\n`
-      # into separate lines, and trailing whitespace stripped — symmetric with
-      # {#lines=}.
+      # Appends given lines. Each entry is parsed the same way as in
+      # {#lines=}: coerced to a {StyledString}, split on `\n`, with trailing
+      # empty pieces dropped and trailing ASCII whitespace stripped.
       # 
-      # _@param_ `lines` — entries need only respond to `#to_s`.
+      # _@param_ `lines` — entries are `String`, `StyledString`, or anything that responds to `#to_s`.
       def add_lines: (::Array[untyped] lines) -> void
 
       def content_size: () -> Size
@@ -646,6 +764,8 @@ module Tuile
       # Moves the cursor to the next line whose text contains `query`
       # (case-insensitive substring match). Search wraps around the end of the
       # list. Only lines reachable by the current {#cursor} are considered.
+      # Matching uses the line's plain text — span styles do not affect the
+      # match.
       # 
       # _@param_ `query` — substring to match. Empty query never matches.
       # 
@@ -669,11 +789,42 @@ module Tuile
       # Paints the list items into {#rect}.
       # 
       # Skips the {Component#repaint} default's auto-clear: every row of
-      # {#rect} is painted below (with padded content past the last item),
+      # {#rect} is painted below (with blank padding past the last item),
       # so the parent contract — "fully draw over your rect" — is met
       # without an upfront wipe.
       def repaint: () -> void
 
+      # 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. 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
+      # {StyledString} lines. Each entry becomes a {StyledString} (String
+      # via {StyledString.parse}, StyledString passed through, anything else
+      # via `#to_s`), then split on `\n` via {StyledString#lines} — with
+      # trailing empty pieces dropped (matching `String#split("\n")`'s
+      # default behavior, so `add_line ""` is a no-op) — and trailing ASCII
+      # whitespace stripped on each resulting line.
+      # 
+      # _@param_ `entries`
+      def parse_input_lines: (::Array[untyped] entries) -> ::Array[StyledString]
+
+      # _@param_ `entry`
+      def split_to_lines: (Object entry) -> ::Array[StyledString]
+
+      # Returns `line` with trailing ASCII whitespace (space/tab) dropped,
+      # preserving span styles on the surviving prefix. Whitespace chars are
+      # all single-column ASCII, so byte-count delta equals column-count
+      # delta and {StyledString#slice} can do the cut.
+      # 
+      # _@param_ `line`
+      def rstrip_styled: (StyledString line) -> StyledString
+
       # _@return_ — true if the cursor sits on a real content line.
       def cursor_on_item?: () -> bool
 
@@ -681,9 +832,9 @@ module Tuile
       # Caller must ensure {#cursor_on_item?}.
       def fire_item_chosen: () -> void
 
-      # _@return_ — `[position, line_at_position]`,
-      # with `line` nil when the cursor is off-content.
-      def cursor_state: () -> [[Integer, String, NilClass]]
+      # _@return_ — `[position, line_at_position]`, with `line` nil when the cursor is
+      # off-content.
+      def cursor_state: () -> [[Integer, StyledString, NilClass]]
 
       # Fires {#on_cursor_changed} if {#cursor_state} differs from the last
       # fired state. Idempotent — safe to call after any mutation.
@@ -728,51 +879,66 @@ 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.
       def scrollbar_visible?: () -> bool
 
-      # Trims string exactly to `width` columns.
+      # _@return_ — column width available for line content (rect width
+      # minus the scrollbar gutter, when visible). `0` when {#rect}'s width
+      # is non-positive.
+      def content_width: () -> Integer
+
+      # Recomputes {@padded_lines} for the current rect width and scrollbar
+      # visibility. Each line is ellipsized to fit and pre-padded with
+      # single-space gutters on each side, so {#paintable_line} only has to
+      # apply the cursor highlight (if any) and append the scrollbar glyph.
+      def rebuild_padded_lines: () -> void
+
+      # Pads `line` to one full row of the viewport (scrollbar gutter
+      # excluded). Lines wider than the content area are ellipsized via
+      # {StyledString#ellipsize} (span styles survive the cut); shorter
+      # lines are padded with default-styled spaces.
       # 
-      # _@param_ `str`
+      # _@param_ `line`
       # 
-      # _@param_ `width`
-      def trim_to: (String str, Integer width) -> String
+      # _@return_ — exactly {#content_width} display columns wide
+      # (or {StyledString::EMPTY} when content_width is non-positive).
+      def pad_to_row: (StyledString line) -> StyledString
 
       # _@param_ `index` — 0-based index into {#lines}.
       # 
       # _@param_ `row_in_viewport` — 0-based row within the viewport.
       # 
-      # _@param_ `width` — number of columns the line should occupy.
-      # 
       # _@param_ `scrollbar` — scrollbar instance, or nil if not shown.
       # 
-      # _@return_ — paintable line exactly `width` columns wide;
-      # highlighted if cursor is here.
-      def paintable_line: (
-                            Integer index,
-                            Integer row_in_viewport,
-                            Integer width,
-                            VerticalScrollBar? scrollbar
-                          ) -> String
+      # _@return_ — paintable ANSI-encoded line exactly `rect.width`
+      # columns wide; highlighted if cursor is here.
+      def paintable_line: (Integer index, Integer row_in_viewport, VerticalScrollBar? scrollbar) -> String
 
       # _@return_ — callback fired when an item is chosen — by pressing
       # Enter on the cursor's item, or by left-clicking an item. Called as
-      # `proc.call(index, line)` with the chosen 0-based index and its line.
-      # Never fires when the cursor's position is outside the content (e.g.
-      # {Cursor::None}, or empty content).
+      # `proc.call(index, line)` with the chosen 0-based index and its
+      # {StyledString} line. Never fires when the cursor's position is
+      # outside the content (e.g. {Cursor::None}, or empty content).
       attr_accessor on_item_chosen: Proc?
 
       # _@return_ — callback fired when the `(index, line)` tuple under
       # the cursor changes. Called as `proc.call(index, line)` where `line`
-      # is `nil` when the cursor is off-content ({Cursor::None}, empty list,
-      # or `index` past the last line). Fires on cursor moves (key, mouse,
-      # search), on {#cursor=}, and on {#lines=}/{#add_lines} when the line
-      # at the cursor's index changes (or its in-range/out-of-range status
-      # flips). Useful for keeping a details pane in sync with the
-      # highlighted row.
+      # is the {StyledString} at the cursor, or `nil` when the cursor is
+      # off-content ({Cursor::None}, empty list, or `index` past the last
+      # line). Fires on cursor moves (key, mouse, search), on {#cursor=},
+      # and on {#lines=}/{#add_lines} when the line at the cursor's index
+      # changes (or its in-range/out-of-range status flips). Useful for
+      # keeping a details pane in sync with the highlighted row.
       attr_accessor on_cursor_changed: Proc?
 
       # _@return_ — if true and a line is added or new content is set,
@@ -829,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`
@@ -839,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
 
@@ -865,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.
@@ -884,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`
@@ -893,27 +1078,48 @@ 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
 
-    # A label which shows static text. No word-wrapping; clips long lines.
+    # A label which shows static text. No word-wrapping; long lines are
+    # truncated with an ellipsis. Text is modeled as a {StyledString};
+    # {#text=} accepts a {String} (parsed via {StyledString.parse}, so
+    # embedded ANSI is honored) or a {StyledString} directly. {#text}
+    # always returns the {StyledString}.
     class Label < Component
       def initialize: () -> void
 
-      # _@param_ `text` — draws this text. May contain ANSI formatting. Clipped automatically.
-      def text=: (String? text) -> void
-
+      # _@return_ — longest hard-line's display width × number of hard
+      # lines. Reported on the *unclipped* text — sizing is intrinsic to
+      # the content, not the viewport. Empty text returns `Size.new(0, 0)`.
       def content_size: () -> Size
 
+      # Paints the text into {#rect}.
+      # 
+      # Skips the {Component#repaint} default's auto-clear: every row is
+      # painted explicitly (with pre-padded blanks past the last line), so
+      # the "fully draw over your rect" contract is met without an upfront
+      # wipe.
       def repaint: () -> void
 
       def on_width_changed: () -> void
 
-      def update_clipped_text: () -> void
+      # Recomputes {@clipped_lines} for the current text and rect width.
+      # 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.
+      def update_clipped_lines: () -> void
+
+      # _@param_ `line`
+      # 
+      # _@param_ `width`
+      def pad_to: (StyledString line, Integer width) -> StyledString
+
+      # _@return_ — the current text. Defaults to an empty
+      # {StyledString}.
+      attr_accessor text: (StyledString | String)?
     end
 
     # A modal overlay that wraps any {Component} as its content. Popup itself
@@ -944,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.
@@ -1102,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
 
@@ -1132,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
@@ -1196,27 +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
-      SGR_RESET: 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
@@ -1259,38 +1463,234 @@ 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
 
+      # _@return_ — index of the topmost display row currently visible.
+      attr_reader top_display_row: Integer
+    end
+
+    # A read-only viewer for prose: chunks of formatted text that scroll
+    # vertically. Shape-wise a hybrid between {Label} (string-shaped content
+    # via {#text=}) and {List} (scroll keys, optional scrollbar, auto-scroll).
+    # 
+    # Text is modeled as a {StyledString}: embedded `\n` are hard line breaks,
+    # lines wider than the viewport are word-wrapped via {StyledString#wrap}
+    # (style spans are preserved across wrap boundaries — unlike the older
+    # 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}.
+    # 
+    # 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.
+    class TextView < Component
+      def initialize: () -> void
+
+      # _@return_ — the current text. Defaults to an empty
+      # {StyledString}. Internally the text is stored as an array of hard
+      # lines so {#append} can stay O(appended) instead of re-scanning the
+      # whole buffer; the joined {StyledString} returned here is
+      # reconstructed on first read after a mutation and cached, so
+      # repeated reads are O(1) but the first read after {#append} pays
+      # O(total spans).
+      def text: () -> StyledString
+
+      # Replaces the text. Embedded `\n` characters become hard line breaks.
+      # A `String` is parsed via {StyledString.parse} (so embedded ANSI is
+      # honored); a `StyledString` is used as-is; `nil` is coerced to an
+      # empty {StyledString}.
+      # 
+      # _@param_ `value`
+      def text=: ((String | StyledString)? value) -> void
+
+      # _@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 + 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
+
+      def focusable?: () -> bool
+
+      def tab_stop?: () -> bool
+
       # _@param_ `key`
-      def printable?: (String key) -> bool
+      def handle_key: (String key) -> bool
 
-      # Same semantics as {TextField}'s ctrl+left.
-      def word_left: () -> Integer
+      # _@param_ `event`
+      def handle_mouse: (MouseEvent event) -> void
 
-      # Same semantics as {TextField}'s ctrl+right.
-      def word_right: () -> Integer
+      # Paints the text into {#rect}.
+      # 
+      # Skips the {Component#repaint} default's auto-clear: every row is
+      # painted explicitly (with padded blanks past the last line), so the
+      # "fully draw over your rect" contract is met without an upfront wipe.
+      def repaint: () -> void
 
-      # _@return_ — current text contents (may contain embedded `\n`).
-      attr_accessor text: String
+      # Rewraps the text on width changes. Wrap width depends on
+      # {#rect}`.width` and the scrollbar gutter, both of which trigger
+      # this hook.
+      def on_width_changed: () -> void
 
-      # _@return_ — caret index in `0..text.length`.
-      attr_accessor caret: Integer
+      # _@return_ — number of visible lines.
+      def viewport_lines: () -> Integer
 
-      # _@return_ — index of the topmost display row currently visible.
-      attr_reader top_display_row: Integer
+      # _@return_ — the max value of {#top_line} for scroll-key clamping.
+      def top_line_max: () -> 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).
+      # 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.
+      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.
       # 
-      # _@return_ — one-arg callable, or nil.
-      attr_accessor on_change: (Proc | Method)?
+      # _@param_ `hard_line` — one hard-broken line (no embedded `"\n"`).
+      # 
+      # _@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).
+      def build_text: () -> StyledString
+
+      # _@return_ — {#content_size} computed from {@hard_lines}.
+      def compute_content_size: () -> Size
+
+      # _@return_ — column width available for wrapped text — viewport
+      # width minus the scrollbar gutter (when visible). `0` when {#rect}'s
+      # width is non-positive, which yields a degenerate "no wrap" result.
+      def wrap_width: () -> Integer
+
+      # _@param_ `delta` — negative scrolls up, positive scrolls down.
+      def move_top_line_by: (Integer delta) -> void
+
+      # _@param_ `target` — desired top line; clamped to `[0, top_line_max]`.
+      def move_top_line_to: (Integer target) -> void
+
+      def update_top_line_if_auto_scroll: () -> void
+
+      def scrollbar_visible?: () -> bool
+
+      # Pads `line` with trailing default-styled spaces out to `width` display
+      # columns. Callers rely on {StyledString#wrap} having already
+      # constrained the line to `<= width`, so no truncation is performed.
+      # `width <= 0` returns {StyledString::EMPTY} to handle the degenerate
+      # `wrap_width == 0` case (rect.width == 1 with scrollbar).
+      # 
+      # _@param_ `line`
+      # 
+      # _@param_ `width`
+      def pad_to: (StyledString line, Integer width) -> StyledString
+
+      # _@param_ `index` — 0-based index into `@physical_lines`.
+      # 
+      # _@param_ `row_in_viewport` — 0-based row within the viewport.
+      # 
+      # _@param_ `scrollbar`
+      # 
+      # _@return_ — paintable ANSI-encoded line exactly `rect.width`
+      # columns wide. Body lines come pre-padded from {#rewrap}, so this
+      # reduces to a memoized {StyledString#to_ansi} read plus an
+      # ASCII-string concat of the scrollbar glyph when one is present.
+      def paintable_line: (Integer index, Integer row_in_viewport, VerticalScrollBar? scrollbar) -> String
+
+      # _@return_ — index of the first visible physical line.
+      attr_accessor top_line: Integer
+
+      # _@return_ — `:gone` or `:visible`.
+      attr_accessor scrollbar_visibility: Symbol
+
+      # _@return_ — if true, mutating the text scrolls the viewport so
+      # the last line stays in view. Default `false`.
+      attr_accessor auto_scroll: bool
+
+      # _@return_ — longest hard-line's display width × number of hard
+      # lines. Reported on the *unwrapped* text — wrap-aware sizing would
+      # be circular (width depends on width). Empty text returns
+      # `Size.new(0, 0)`. Maintained incrementally by {#text=} and
+      # {#append}, so reads are O(1).
+      attr_reader content_size: Size
     end
 
     # Shows a log. Construct your logger pointed at a {LogWindow::IO} to route
@@ -1306,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`).
@@ -1335,27 +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
-      SGR_RESET: 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.
@@ -1364,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
@@ -1387,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.
@@ -1401,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}.
+      # 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_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)?
+      attr_accessor on_escape: (Proc | Method)?
     end
 
     # A mixin interface for a component with one child tops. The host must
@@ -1672,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
@@ -1681,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
@@ -1696,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.
@@ -1801,6 +2299,360 @@ module Tuile
     attr_reader status_bar: Component::Label
   end
 
+  # An immutable string-with-styling, modeled as a sequence of {Span}s where
+  # each span carries a complete {Style} (`fg`, `bg`, `bold`, `italic`,
+  # `underline`). Spans are non-overlapping and fully tile the string — every
+  # character has exactly one resolved style, no overlay layers to merge.
+  # 
+  # Where this differs from threading SGR escapes through a plain `String`:
+  # slicing, wrapping, and concatenation operate on the structured spans, so
+  # they never have to "figure out what SGR state is active at column N" —
+  # the answer is just the containing span's `style`. The flip side is one
+  # extra type to construct (or parse) before doing styled-text math.
+  # 
+  # ## Constructors
+  # 
+  # ```ruby
+  # StyledString.new                                  # empty
+  # StyledString.plain("hello")                       # default style
+  # StyledString.styled("hello", fg: :red, bold: true)
+  # StyledString.parse("\e[31mhello\e[0m world")      # ANSI → spans
+  # ```
+  # 
+  # ## Algebra
+  # 
+  # All operations return a fresh {StyledString} — the underlying spans are
+  # frozen and shared. `+` coerces a `String` operand via {.parse}.
+  # 
+  # ```ruby
+  # a + b                       # concatenate
+  # ss.slice(2, 5)              # 5 display columns starting at column 2
+  # ss.slice(2..5)              # range (inclusive end)
+  # ss.lines                    # split on "\n" → Array<StyledString>
+  # ss.each_char_with_style { |ch, style| ... }
+  # ```
+  # 
+  # ## Rendering
+  # 
+  # - `#to_s` — plain text, no SGR.
+  # - `#to_ansi` — minimal-diff SGR rendering, ending with `\e[0m` only when
+  #   the last span carried a non-default style. Transitions to the default
+  #   style emit `\e[0m` (shorter than re-emitting every off-code).
+  # 
+  # ## Parser
+  # 
+  # {.parse} is strict by design: it recognizes only the SGR codes
+  # corresponding to {Style}'s supported attributes (fg/bg/bold/italic/
+  # underline). Anything else — unmodeled attributes (dim, blink, reverse,
+  # strike, conceal, double-underline, overline, ...), unknown SGR codes, or
+  # non-SGR escapes (cursor moves, OSC) — raises {ParseError}. This keeps the
+  # round-trip parse(to_ansi(x)) == x contract honest.
+  class StyledString
+    EMPTY: StyledString
+
+    # sord duck - #to_s looks like a duck type with an equivalent RBS interface, replacing with _ToS
+    # _@param_ `text`
+    def self.plain: (_ToS text) -> StyledString
+
+    # sord duck - #to_s looks like a duck type with an equivalent RBS interface, replacing with _ToS
+    # _@param_ `text`
+    # 
+    # _@param_ `style_kwargs` — forwarded to {Style.new}.
+    def self.styled: (_ToS text, **::Hash[Symbol, Object] style_kwargs) -> StyledString
+
+    # Parses an ANSI/SGR-coded string into a {StyledString}. A {StyledString}
+    # input is returned as-is. `nil` and the empty string both fast-path to
+    # {EMPTY}. Strings without any `\e` byte fast-path to a single
+    # default-styled span.
+    # 
+    # _@param_ `input`
+    def self.parse: ((String | StyledString)? input) -> StyledString
+
+    # _@param_ `spans`
+    def initialize: (?::Array[Span] spans) -> void
+
+    # Total display width in terminal columns, accounting for Unicode wide
+    # characters (fullwidth CJK = 2 columns, combining marks = 0, etc.).
+    # Memoized — safe because spans are frozen and immutable.
+    def display_width: () -> Integer
+
+    def empty?: () -> bool
+
+    # Plain text concatenation across all spans — no SGR codes.
+    def to_s: () -> String
+
+    # Rendered ANSI string. Minimal-diff between adjacent spans: only the
+    # attributes that changed are emitted. A transition to the default style
+    # emits `\e[0m` (one code) instead of the longer "turn each attribute
+    # off" form. Always closes with `\e[0m` when the last span carried a
+    # non-default style, so the styled run doesn't bleed into subsequent
+    # output. Memoized — safe because spans are frozen and immutable.
+    def to_ansi: () -> String
+
+    # _@param_ `other`
+    def ==: (Object other) -> bool
+
+    def hash: () -> Integer
+
+    # Concatenation. A `String` operand is parsed via {.parse} before joining
+    # (so embedded ANSI escapes round-trip through spans).
+    # 
+    # _@param_ `other`
+    def +: ((StyledString | String) other) -> StyledString
+
+    # Substring by display columns, preserving spans. Characters whose column
+    # range only partially overlaps the slice (e.g. a 2-column CJK character
+    # straddling the start or end boundary) are dropped — never split.
+    # 
+    # Accepts either `slice(start_col, len_col)` or `slice(range)`. Both
+    # forms support negative indices counting from the end of the string.
+    # 
+    # _@param_ `start_col`
+    # 
+    # _@param_ `len_col`
+    def slice: (Integer start_col, Integer len_col) -> StyledString
+
+    # Truncates to a target column width, appending an ellipsis when
+    # characters were dropped. The ellipsis counts toward the target — the
+    # returned {StyledString}'s `display_width` never exceeds
+    # `display_width`. When `self` already fits, `self` is returned. When
+    # `display_width` is smaller than the ellipsis's own width, the ellipsis
+    # is sliced down to fit and no original content is included.
+    # 
+    # _@param_ `display_width` — target column width.
+    # 
+    # _@param_ `ellipsis` — appended when truncation occurs. Defaults to the Unicode horizontal-ellipsis `…` (one column). A `String` is parsed via {.parse}, so ANSI in it is preserved.
+    def ellipsize: (Integer display_width, ?(String | StyledString) ellipsis) -> StyledString
+
+    # Splits on `"\n"`, preserving spans on each side. A trailing newline
+    # produces a trailing empty {StyledString} (matches `split("\n", -1)`).
+    # An empty {StyledString} returns a single empty entry, like `"".split`.
+    def lines: () -> ::Array[StyledString]
+
+    # Word-wraps to physical lines that each fit within `width` display
+    # columns, preserving spans and styles across breaks. Greedy word-wrap,
+    # hard-break for words wider than `width`, leading whitespace dropped on
+    # wrapped continuations, hard `"\n"` breaks preserved as separate output
+    # lines.
+    # 
+    # Whitespace runs are space or tab; other characters are treated as word
+    # content. When a single character is wider than `width` (e.g. a 2-column
+    # CJK character with `width = 1`), it is still emitted on its own line at
+    # its natural width. The "no line exceeds `width`" guarantee therefore
+    # holds whenever every character is at most `width` columns wide.
+    # 
+    # _@param_ `width` — target column width. `nil` or `<= 0` skips wrapping and returns each hard-line as-is, so callers can pass a stale viewport width without crashing.
+    # 
+    # _@return_ — one entry per physical (output) line.
+    # An empty receiver returns `[]`.
+    def wrap: (Integer? width) -> ::Array[StyledString]
+
+    # Yields each character (per `String#each_char`) along with the {Style}
+    # it carries. Returns an `Enumerator` without a block.
+    def each_char_with_style: () -> (::Enumerator[untyped] | self)
+
+    # Returns a new {StyledString} with `bg` applied to every span, preserving
+    # each span's text and other style attributes (`fg`, `bold`, `italic`,
+    # `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
+
+    # 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
+
+    # _@param_ `spans`
+    def normalize: (::Array[Span] spans) -> ::Array[Span]
+
+    # _@param_ `from`
+    # 
+    # _@param_ `to`
+    def sgr_diff: (Style from, Style to) -> String
+
+    # _@param_ `color`
+    # 
+    # _@param_ `base` — base SGR code — 30 for fg, 40 for 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]
+
+    # _@param_ `start_or_range`
+    # 
+    # _@param_ `len`
+    # 
+    # _@param_ `total` — receiver's full display width.
+    # 
+    # _@return_ — normalized `[start_col, len_col]`.
+    def resolve_slice_bounds: ((Integer | ::Range[untyped]) start_or_range, Integer? len, Integer total) -> [Integer, Integer]
+
+    # _@param_ `start`
+    # 
+    # _@param_ `len`
+    def slice_spans: (Integer start, Integer len) -> StyledString
+
+    # _@param_ `hard_line` — one hard-broken line — no embedded `"\n"`.
+    # 
+    # _@param_ `width`
+    def wrap_one: (StyledString hard_line, Integer width) -> ::Array[StyledString]
+
+    # _@param_ `hard_line`
+    # 
+    # _@return_ — tokens shaped `[type, chars, w]` where `type` is
+    # `:space` or `:word`, `chars` is an `Array<[String, Style, Integer]>`
+    # (char, style, display width), and `w` is the token's total width.
+    def tokenize_for_wrap: (StyledString hard_line) -> ::Array[::Array[untyped]]
+
+    # _@param_ `chars` — `[char, style, width]` triples.
+    # 
+    # _@param_ `width`
+    # 
+    # _@return_ — each inner Array is a `chars`-shaped chunk.
+    def hard_break_chars: (::Array[::Array[untyped]] chars, Integer width) -> ::Array[::Array[::Array[untyped]]]
+
+    # _@param_ `chars` — `[char, style, width]` triples.
+    def chars_to_styled: (::Array[::Array[untyped]] chars) -> StyledString
+
+    # _@param_ `text`
+    # 
+    # _@param_ `start_col`
+    # 
+    # _@param_ `len_col`
+    def slice_text_by_columns: (String text, Integer start_col, Integer len_col) -> String
+
+    # _@return_ — the frozen, normalized span list — no empty-text
+    # entries, no two adjacent entries sharing a style.
+    attr_reader spans: ::Array[Span]
+
+    # Raised by {.parse} on malformed or unsupported escape sequences.
+    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
+    # 
+    # @!attribute [r] fg
+    #   @return [Symbol, Integer, Array<Integer>, nil]
+    # @!attribute [r] bg
+    #   @return [Symbol, Integer, Array<Integer>, nil]
+    # @!attribute [r] bold
+    #   @return [Boolean]
+    # @!attribute [r] italic
+    #   @return [Boolean]
+    # @!attribute [r] underline
+    #   @return [Boolean]
+    class Style
+      COLOR_SYMBOLS: ::Array[Symbol]
+      DEFAULT: Style
+
+      # _@param_ `fg`
+      # 
+      # _@param_ `bg`
+      # 
+      # _@param_ `bold`
+      # 
+      # _@param_ `italic`
+      # 
+      # _@param_ `underline`
+      def self.new: (
+                      ?fg: (Symbol | Integer | ::Array[Integer])?,
+                      ?bg: (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.
+      # 
+      # _@param_ `overrides`
+      def merge: (**::Hash[Symbol, Object] overrides) -> Style
+
+      attr_reader fg: (Symbol | Integer | ::Array[Integer])?
+
+      attr_reader bg: (Symbol | Integer | ::Array[Integer])?
+
+      attr_reader bold: bool
+
+      attr_reader italic: bool
+
+      attr_reader underline: bool
+    end
+
+    # A maximal run of text sharing a single {Style}. `text` is plain — it
+    # never contains ANSI escape sequences. Spans inside a {StyledString} are
+    # normalized: no empty text, no two adjacent spans share a style.
+    # 
+    # @!attribute [r] text
+    #   @return [String] frozen plain text.
+    # @!attribute [r] style
+    #   @return [Style]
+    class Span
+      # _@param_ `text`
+      # 
+      # _@param_ `style`
+      def initialize: (text: String, style: Style) -> void
+
+      # _@return_ — frozen plain text.
+      attr_reader text: String
+
+      attr_reader style: Style
+    end
+
+    # @api private
+    # Hand-rolled SGR parser. State machine over a {StringScanner}: plain
+    # text accumulates into the current span; each `\e[...m` flushes the
+    # current span and updates the running {Style}. Anything outside the
+    # supported SGR alphabet raises {ParseError}.
+    class Parser
+      STANDARD_COLORS: ::Array[Symbol]
+      BRIGHT_COLORS: ::Array[Symbol]
+
+      # _@param_ `input`
+      def initialize: (String input) -> void
+
+      def parse: () -> StyledString
+
+      def consume_text: () -> void
+
+      def consume_escape: () -> void
+
+      # _@param_ `params_str`
+      def apply_sgr: (String params_str) -> void
+
+      # _@param_ `codes`
+      # 
+      # _@param_ `index`
+      # 
+      # _@param_ `target` — either `:fg` or `:bg`.
+      # 
+      # _@return_ — how many SGR codes were consumed (3 for 256-color, 5 for RGB).
+      def consume_extended_color: (::Array[Integer] codes, Integer index, Symbol target) -> Integer
+
+      def flush: () -> void
+    end
+  end
+
   # 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