tuile 0.1.0 → 0.3.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.
@@ -26,9 +34,13 @@ module Tuile
     UP_ARROWS: ::Array[String]
     LEFT_ARROW: String
     RIGHT_ARROW: String
+    CTRL_LEFT_ARROW: String
+    CTRL_RIGHT_ARROW: String
     ESC: String
     HOME: String
     END_: String
+    HOMES: ::Array[String]
+    ENDS_: ::Array[String]
     PAGE_UP: String
     PAGE_DOWN: String
     BACKSPACE: String
@@ -38,6 +50,8 @@ module Tuile
     CTRL_U: String
     CTRL_D: String
     ENTER: String
+    TAB: String
+    SHIFT_TAB: String
 
     # 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
@@ -212,6 +226,19 @@ module Tuile
     # function exits when the 'ESC' or 'q' key is pressed.
     def run_event_loop: () -> 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}
+    # — this keeps Tab confined inside a modal popup. No-op (returns false) if
+    # the modal scope has no tab stops or no content at all.
+    # 
+    # _@return_ — true if focus moved.
+    def focus_next: () -> bool
+
+    # Mirror of {#focus_next} that walks backwards through the tab order.
+    # 
+    # _@return_ — true if focus moved.
+    def focus_previous: () -> bool
+
     # _@return_ — current active tiled component.
     def active_window: () -> Component?
 
@@ -240,7 +267,23 @@ module Tuile
 
     def self.close: () -> void
 
-    # Prints given strings.
+    # Prints given strings. While {#repaint} is running, writes are
+    # accumulated into a frame buffer and flushed to the terminal as a
+    # single `$stdout.write` at the end of the cycle. This stops the
+    # emulator from rendering half-finished frames (e.g. a layout's
+    # clear-background pass before its children have re-painted), which
+    # was visible as a brief flicker when the auto-clear path triggers.
+    # 
+    # Outside repaint, writes go straight to stdout. We deliberately
+    # don't raise on a "print outside repaint" — that would be a useful
+    # guardrail against components painting outside the repaint loop,
+    # but it'd force terminal-housekeeping writes (`Screen#clear`,
+    # mouse-tracking start/stop, cursor-show on teardown) to bypass
+    # this method entirely and write directly to `$stdout`. {FakeScreen}
+    # overrides `print` to capture every byte into its `@prints` array,
+    # and tests that exercise `run_event_loop` against a real {Screen}
+    # would otherwise leak escape sequences to the test runner's stdout.
+    # Keeping `print` as the single sink preserves that override seam.
     # 
     # _@param_ `args` — stuff to print.
     def print: (*String args) -> void
@@ -255,6 +298,17 @@ module Tuile
     # but only one focused.
     def cursor_position: () -> Point?
 
+    # Walks the current modal scope in pre-order, collects tab stops, and
+    # advances focus by one (wrapping). When the focused component isn't in
+    # the tab order (e.g. focus is parked on a popup/window chrome with no
+    # interactable widgets), Tab goes to the first stop and Shift+Tab to the
+    # last.
+    # 
+    # _@param_ `forward`
+    # 
+    # _@return_ — true if focus moved.
+    def cycle_focus: (forward: bool) -> bool
+
     # Collects a component and all its descendants in tree order
     # (parent before children).
     # 
@@ -276,6 +330,11 @@ 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.
+    # 
     # _@param_ `key`
     # 
     # _@return_ — true if the key was handled by some window.
@@ -336,12 +395,28 @@ module Tuile
     # Focuses this component. Equivalent to `screen.focused = self`.
     def focus: () -> void
 
-    # Repaints the component. Default implementation does nothing.
+    # Repaints the component.
     # 
-    # The component must fully draw over {#rect}, and must not draw outside of
-    # {#rect}.
+    # The default does the bookkeeping that almost every component would
+    # otherwise have to remember: it clears the background and re-invalidates
+    # any direct children whose rects leave gaps in {#rect}. Concretely:
     # 
-    # Tip: use {#clear_background} to clear component background before painting.
+    # - Leaf (no children): always clears, so subclasses can paint their
+    #   content directly without an explicit `clear_background` call.
+    # - Container with children that fully tile {#rect}: skipped — the
+    #   children themselves will repaint and cover everything.
+    # - Container with gappy children (e.g. a form layout where widgets
+    #   don't tile): clears, then invalidates the children so they re-paint
+    #   on top of the cleared background. This is what makes mixed
+    #   field/button forms safe without each container learning a custom
+    #   damage-tracking pass.
+    # 
+    # Subclasses that paint their entire rect themselves (e.g. {Window}'s
+    # border draws over the area the default would clear; {Component::List}
+    # explicitly paints every row) may skip super and take full
+    # responsibility for {#rect}. Everything else should call super.
+    # 
+    # A component must not draw outside of {#rect}.
     def repaint: () -> void
 
     # Called when a character is pressed on the keyboard.
@@ -386,9 +461,23 @@ module Tuile
     # only focusable ones can become a focus target that puts themselves and
     # their ancestors on the active chain.
     # 
+    # See also {#tab_stop?}: focusable controls _can_ receive focus (via click
+    # or programmatic assignment), but only tab stops participate in Tab /
+    # Shift+Tab cycling. Containers like {Window} and {Popup} are focusable
+    # (so a click on chrome lands focus) but are not tab stops.
+    # 
     # _@return_ — true if this component can be focused.
     def focusable?: () -> bool
 
+    # Whether this component participates in Tab / Shift+Tab focus cycling.
+    # `false` by default. Only true on components that accept direct user
+    # input (e.g. {TextField}, {List}, {Component::Button}). Implies
+    # {#focusable?} — Screen will skip non-focusable tab stops, but in
+    # practice every override should keep the two consistent.
+    # 
+    # _@return_ — true if Tab / Shift+Tab should land on this component.
+    def tab_stop?: () -> bool
+
     # _@return_ — the distance from the root component; 0 if {#parent}
     # is nil.
     def depth: () -> Integer
@@ -450,6 +539,15 @@ module Tuile
     # needs-repaint and once all events are processed, will call {#repaint}.
     def invalidate: () -> void
 
+    # Whether direct children fully tile {#rect}. Used by the default
+    # {#repaint} to decide whether the framework needs to wipe gaps.
+    # 
+    # Approximated by area: sum of (non-empty) child areas vs the parent's
+    # area. Cheap, and correct as long as siblings don't overlap each other
+    # — which Tuile already requires (no clipping in the tiled tree).
+    # Children with empty rects contribute zero, since they paint nothing.
+    def children_tile_rect?: () -> bool
+
     # Clears the background: prints spaces into all characters occupied by the
     # component's rect.
     def clear_background: () -> void
@@ -466,24 +564,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
@@ -494,25 +602,29 @@ 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
 
       def focusable?: () -> bool
 
+      def tab_stop?: () -> bool
+
       # _@param_ `key` — a key.
       # 
       # _@return_ — true if the key was handled.
@@ -521,6 +633,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.
       # 
@@ -542,8 +656,40 @@ module Tuile
       def handle_mouse: (MouseEvent event) -> void
 
       # Paints the list items into {#rect}.
+      # 
+      # Skips the {Component#repaint} default's auto-clear: every row of
+      # {#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.
+      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
 
@@ -551,6 +697,14 @@ 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, StyledString, NilClass]]
+
+      # Fires {#on_cursor_changed} if {#cursor_state} differs from the last
+      # fired state. Idempotent — safe to call after any mutation.
+      def notify_cursor_changed: () -> void
+
       # _@param_ `query`
       # 
       # _@param_ `include_current`
@@ -596,37 +750,55 @@ module Tuile
       # _@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 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,
       # auto-scrolls to the bottom.
       attr_accessor auto_scroll: bool
@@ -752,20 +924,44 @@ module Tuile
       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
@@ -854,17 +1050,70 @@ module Tuile
       def on_focus: () -> void
     end
 
+    # A clickable button. Activated by Enter, Space, or a left mouse click;
+    # fires the {#on_click} callback. Renders as `[ caption ]` on a single
+    # row; the background is highlighted when the button is focused so the
+    # user can see which button is active.
+    # 
+    # Buttons are tab stops — Tab and Shift+Tab will land on them as part of
+    # the standard focus cycle. Click-to-focus also works via the inherited
+    # {Component#handle_mouse}.
+    # 
+    # Assign a {#rect} (typically by the surrounding {Layout}) wide enough to
+    # show `[ caption ]`; {#content_size} reports that natural width.
+    class Button < Component
+      # _@param_ `caption` — the button's label.
+      def initialize: (?String caption) -> void
+
+      def focusable?: () -> bool
+
+      def tab_stop?: () -> bool
+
+      # _@return_ — natural width is `caption.length + 4` to fit
+      # `[ caption ]`; height is 1.
+      def content_size: () -> Size
+
+      # _@param_ `key`
+      def handle_key: (String key) -> bool
+
+      # _@param_ `event`
+      def handle_mouse: (MouseEvent event) -> void
+
+      def repaint: () -> void
+
+      # _@return_ — the button's label.
+      attr_accessor caption: String
+
+      # Callback fired when the button is activated (Enter, Space, or
+      # left-click). The callable receives no arguments.
+      # 
+      # _@return_ — no-arg callable, or nil.
+      attr_accessor on_click: (Proc | Method)?
+    end
+
     # A layout doesn't paint anything by itself: its job is to position child
     # components.
     # 
-    # All children must completely cover the contents of a layout: that way,
-    # the layout itself doesn't have to draw and no clipping algorithm is
-    # necessary.
+    # Children that fully tile the layout's rect repaint themselves and
+    # cover everything; children that leave gaps (e.g. a form with widgets
+    # of varying widths) trigger {Component#repaint}'s default behavior —
+    # the background is cleared and children are re-invalidated so they
+    # paint over a clean surface.
     class Layout < Component
       def initialize: () -> void
 
       def children: () -> ::Array[Component]
 
+      # Layouts are focusable containers — like {Window} and {Popup}, they
+      # don't accept input themselves but they need to participate in the
+      # {HasContent} focus cascade so a Popup wrapping a Layout wrapping a
+      # {TextField} ends up focusing the field rather than parking focus on
+      # the popup. Layouts don't paint any visible chrome of their own
+      # (the auto-cleared background is just blank space), so this has no
+      # mouse-routing consequences — clicks on a gap area land back on the
+      # Layout itself and the on_focus cascade forwards to a tab stop.
+      def focusable?: () -> bool
+
       # Adds a child component to this layout.
       # 
       # _@param_ `child`
@@ -875,8 +1124,6 @@ module Tuile
 
       def content_size: () -> Size
 
-      def repaint: () -> void
-
       # Dispatches the event to the child under the mouse cursor.
       # 
       # _@param_ `event`
@@ -938,6 +1185,15 @@ module Tuile
       def visible?: () -> bool
 
       # Fully repaints the window: both frame and contents.
+      # 
+      # Window deliberately paints over its entire rect (border around the
+      # edge, content/footer over the interior), so we don't need the
+      # {Component#repaint} default's auto-clear — but we do still want its
+      # "re-invalidate children" effect, since the border overpaints
+      # whatever the content/footer drew on the perimeter. Calling super
+      # handles both: the auto-clear is harmless (we re-paint over it), and
+      # the invalidation queues content + footer for repaint in the same
+      # cycle.
       def repaint: () -> void
 
       # _@param_ `key`
@@ -972,6 +1228,281 @@ module Tuile
       attr_accessor caption: String
     end
 
+    # A multi-line, word-wrapping text input.
+    # 
+    # Sized by the caller — {#rect} is fixed; the area does not grow with
+    # content. Text is wrapped to {Rect#width} columns and any text that
+    # doesn't fit vertically is reached by scrolling: {#top_display_row}
+    # follows the caret so the line being edited stays visible. There is no
+    # horizontal scrolling.
+    # 
+    # The caret is a logical index in `0..text.length`. When the caret falls
+    # inside a whitespace run that was absorbed by a soft wrap, it displays
+    # at the end of the previous row (which is visually identical to the
+    # start of the next row in nearly all cases).
+    # 
+    # 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
+      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_width_changed: () -> void
+
+      # _@return_ — cached wrap of {#text} for the
+      # current {Rect#width}. Each entry is `{start:, length:}`.
+      def display_rows: () -> ::Array[::Hash[Symbol, Integer]]
+
+      # Greedy word-wrap. Whitespace at a soft-wrap break point is absorbed
+      # (not rendered on either row). A token longer than {Rect#width} hard-
+      # wraps inside the token. Newlines force a hard break and the wrap
+      # restarts on the next character.
+      def compute_display_rows: () -> ::Array[::Hash[Symbol, Integer]]
+
+      # Trims trailing space/tab characters off a row's visible length so the
+      # whitespace at a soft-wrap point is absorbed (not rendered) rather than
+      # left at the end of the row. Without this, soft-wrapping `"foo bar"`
+      # to width 4 would yield row 0 length 4 (`"foo "`) and the natural
+      # end-of-row caret position would coincide with row 1's start.
+      # 
+      # _@param_ `row_start`
+      # 
+      # _@param_ `row_chars`
+      # 
+      # _@return_ — new row_chars.
+      def trim_trailing_whitespace: (Integer row_start, Integer row_chars) -> Integer
+
+      # _@param_ `caret`
+      # 
+      # _@return_ — `[row_index, column]` for `caret`.
+      def caret_to_display: (Integer caret) -> [Integer, Integer]
+
+      # _@param_ `delta` — `+1` for down, `-1` for up.
+      def move_caret_vertical: (Integer delta) -> void
+
+      def move_caret_to_row_start: () -> void
+
+      def move_caret_to_row_end: () -> void
+
+      # _@param_ `char`
+      # 
+      # _@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
+    # 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}. Use {#append} for incremental "log
+    # line" style updates; 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
+
+      # 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=}.
+      # 
+      # 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.
+      # 
+      # _@param_ `str`
+      def append: ((String | StyledString)? str) -> void
+
+      # Clears the text. Equivalent to `text = ""`.
+      def clear: () -> void
+
+      def focusable?: () -> bool
+
+      def tab_stop?: () -> bool
+
+      # _@param_ `key`
+      def handle_key: (String key) -> bool
+
+      # _@param_ `event`
+      def handle_mouse: (MouseEvent event) -> void
+
+      # 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
+
+      # 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_ — 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.
+      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.
+      # 
+      # _@param_ `hard_line` — one hard-broken line (no embedded `"\n"`).
+      # 
+      # _@param_ `width`
+      def append_physical_lines: (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
     # log lines into this window:
     # 
@@ -1015,10 +1546,15 @@ module Tuile
     # positioned by {Screen} after each repaint cycle when this component is
     # focused; see {Component#cursor_position}.
     class TextField < Component
+      ACTIVE_BG_SGR: String
+      INACTIVE_BG_SGR: String
+
       def initialize: () -> void
 
       def focusable?: () -> bool
 
+      def tab_stop?: () -> bool
+
       def cursor_position: () -> Point?
 
       # _@param_ `key`
@@ -1044,6 +1580,16 @@ module Tuile
       # _@param_ `key`
       def printable?: (String key) -> bool
 
+      # 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
+      # beginning of the previous word if already there.
+      def word_left: () -> Integer
+
+      # Caret target for ctrl+right: skip non-whitespace going right, then a
+      # run of whitespace. Lands at the beginning of the next word, or at the
+      # end of the text if no further word exists.
+      def word_right: () -> Integer
+
       # _@return_ — current text contents.
       attr_accessor text: String
 
@@ -1433,13 +1979,26 @@ module Tuile
 
     # Focus repair when a child detaches. Default {Component#on_child_removed}
     # would refocus to `self` (the pane), which isn't a useful focus target.
-    # Instead, route focus to the now-topmost popup, then to the prior focus
-    # snapshotted when this popup was opened (if still attached), then to
-    # content, then nil.
+    # Instead, route focus to the first interactable widget in the now-topmost
+    # popup; falling back to the focus snapshotted when this popup was opened
+    # (if still attached and still focusable); then to the first interactable
+    # widget in {#content}; then to {#content} itself; then nil.
+    # 
+    # "First interactable widget" = first {Component#tab_stop?} in pre-order;
+    # if a scope has no tab stops at all (a borderless ESC-to-close popup, or
+    # tiled content made entirely of {Label}s), we focus the scope's root so
+    # `q`/ESC still has somewhere to dispatch from.
     # 
     # _@param_ `child`
     def on_child_removed: (Component child) -> void
 
+    # First {Component#tab_stop?} in `root`'s subtree (pre-order), falling
+    # back to `root` itself when the subtree has no tab stops. Returns `nil`
+    # if `root` is `nil`.
+    # 
+    # _@param_ `root`
+    def first_tab_stop_or_root: (Component? root) -> Component?
+
     # _@return_ — the tiled content component.
     attr_accessor content: Component?
 
@@ -1451,6 +2010,352 @@ 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
+
+    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