tuile 0.2.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.
@@ -373,39 +381,6 @@ module Tuile
     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
-
-    # 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
-
-    # 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
-  end
-
   # A UI component which is positioned on the screen and draws characters into
   # its bounding rectangle (in {#repaint}).
   # 
@@ -589,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
@@ -617,19 +602,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 +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.
       # 
@@ -669,11 +658,38 @@ 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.
+      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 +697,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.
@@ -734,45 +750,53 @@ 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 `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,
@@ -900,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
@@ -1199,7 +1247,6 @@ module Tuile
     class TextArea < Component
       ACTIVE_BG_SGR: String
       INACTIVE_BG_SGR: String
-      SGR_RESET: String
 
       def initialize: () -> void
 
@@ -1293,6 +1340,169 @@ module Tuile
       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:
     # 
@@ -1338,7 +1548,6 @@ module Tuile
     class TextField < Component
       ACTIVE_BG_SGR: String
       INACTIVE_BG_SGR: String
-      SGR_RESET: String
 
       def initialize: () -> void
 
@@ -1801,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